CONTRIBUTING.md

Contributing to Orthogonal Epistatic Kernels

Thank you for your interest in contributing to this project! This document provides guidelines and information for contributors.

🎯 Code of Conduct

We are committed to providing a welcoming and inclusive experience for everyone. Please be respectful and constructive in all interactions.

🚀 Getting Started

Development Setup

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/Orthogonal-Epistatic-Kernels-Codebase.git
cd Orthogonal-Epistatic-Kernels-Codebase/ogblup_repro

# Install in development mode
pip install -e ".[dev]"

# Verify installation
pytest tests/ -v

Development Workflow

1. Create a branch from main for your feature or fix
2. Write tests first — we maintain 100% coverage
3. Implement your changes with type annotations
4. Run the test suite — all 137+ tests must pass
5. Check coverage — pytest --cov=ogblup_repro --cov-fail-under=100
6. Submit a pull request with a clear description

📋 Contribution Types

Bug Reports

• Use the GitHub Issues template
• Include: Python version, OS, minimal reproduction code, expected vs actual behaviour
• Tag with bug

Feature Requests

• Describe the scientific motivation
• Include references to relevant literature
• Tag with enhancement

Code Contributions

We welcome contributions in the following areas:

Area	Priority	Description
New kernels	High	Additional epistatic kernels (D×D, A×D)
Bayesian methods	Medium	BayesB, BayesCπ implementations
Performance	Medium	GPU acceleration, sparse kernel support
Visualisation	Low	Interactive plotly figures, Jupyter notebooks

🧪 Testing Standards

Requirements

• 100% line coverage — no exceptions
• Edge cases covered — singular matrices, monomorphic loci, empty inputs
• Deterministic tests — use rng fixture from conftest.py
• Fast execution — individual tests should complete in < 2 seconds

Test Structure

class TestMyFeature:
    def test_basic_functionality(self, rng):
        """Test the happy path."""
        result = my_function(valid_input)
        assert result == expected_value

    def test_edge_case(self, rng):
        """Test boundary conditions."""
        result = my_function(edge_input)
        assert result == edge_expected

    def test_invalid_input_raises(self):
        """Test error handling."""
        with pytest.raises(ValueError, match="descriptive message"):
            my_function(invalid_input)

Running Tests

# Full suite
pytest tests/ -v

# Single module
pytest tests/test_reml.py -v

# With coverage
pytest --cov=ogblup_repro --cov-report=term-missing tests/

# Specific test
pytest tests/test_kernels.py::TestAdditiveKernel::test_psd -v

📝 Code Style

Guidelines

• Type annotations on all function signatures
• NumPy-style docstrings with Parameters, Returns, Raises sections
• Descriptive variable names — allele_freqs not af
• Constants in UPPER_CASE — MAX_ITER = 100
• No magic numbers — define named constants

Example

def my_function(
    genotypes: np.ndarray,
    frequencies: np.ndarray,
    *,
    orthogonal: bool = True,
) -> np.ndarray:
    """Compute something important.

    Parameters
    ----------
    genotypes : np.ndarray, shape (N, M)
        Genotype count matrix with values in {0, 1, 2}.
    frequencies : np.ndarray, shape (M,)
        Allele frequencies for each marker.
    orthogonal : bool, optional
        If True, use NOIA orthogonal coding. Default: True.

    Returns
    -------
    np.ndarray, shape (N, M)
        The coded genotype matrix.

    Raises
    ------
    ValueError
        If genotypes contains values outside {0, 1, 2}.
    """
    ...

🔬 Scientific Standards

• All mathematical formulations must reference the manuscript or primary literature
• Numerical implementations must include stability safeguards
• Variance component estimates must be validated against known ground truth
• New kernels must include orthogonality verification tests

---

Thank you for contributing to reproducible genomic prediction research! 🧬