Contributing to EEGPrep#

We welcome contributions from the community! This guide will help you get started with contributing to EEGPrep.

Getting Started#

Fork and Clone#

  1. Fork the repository on GitHub by clicking the “Fork” button

  2. Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/eegprep.git
cd eegprep

  1. Add the upstream repository:

git remote add upstream https://github.com/sccn/eegprep.git

  1. Create a new branch for your feature or bugfix:

git checkout -b feature/your-feature-name

Development Environment#

Virtual Environment Setup#

Create the uv-managed development environment:

uv python install 3.11
uv sync --group dev

Install Dependencies#

If you only need documentation dependencies, sync the docs extra:

uv sync --extra docs --group dev

uv sync installs:

  • The eegprep package in editable mode

  • Repo tooling dependencies

  • GUI and eegprep-console runtime dependencies

  • Documentation dependencies when --extra docs is used

Code Style Guidelines#

PEP 8 Compliance#

We follow PEP 8 style guidelines. Key points:

  • Use 4 spaces for indentation (never tabs)

  • Maximum line length: 100 characters

  • Use descriptive variable and function names

  • Add spaces around operators: x = 1, not x=1

Naming Conventions#

  • Functions and variables: Use lowercase with underscores (snake_case)

  • Classes: Use CapWords (PascalCase)

  • Constants: Use UPPERCASE with underscores (CONSTANT_NAME)

  • Private methods/attributes: Prefix with underscore (_private_method)

Code Formatting#

Use the repository pre-commit entry point:

./pre-commit.py --fix

Testing Requirements#

Running Tests#

Run the full test suite:

uv run pytest tests

Run tests for a specific module:

uv run pytest tests/test_clean_artifacts.py

Run tests with verbose output:

uv run pytest -v tests/test_clean_artifacts.py

Writing Tests#

When adding new features, include tests:

import numpy as np
from eegprep import EEGobj

def test_new_feature():
    """Test description of what this tests."""
    # Setup: EEGobj wraps an EEG dict (or a .set file path).
    eeg_dict = {
        "data": np.zeros((4, 100), dtype=np.float32),
        "nbchan": 4,
        "pnts": 100,
        "trials": 1,
        "srate": 128.0,
        "xmin": 0.0,
        "xmax": 99 / 128.0,
        "chanlocs": [{"labels": f"Ch{i + 1}"} for i in range(4)],
        "event": [],
        "epoch": [],
    }
    eeg = EEGobj(eeg_dict)

    # Execute: EEGobj dispatches pop_* operations, e.g. eeg.pop_reref([]).
    result = eeg.pop_reref([])

    # Assert
    assert result is not None
    assert result["nbchan"] == 4

Documentation Standards#

Docstring Format#

Use Google-style docstrings:

def preprocess_eeg(eeg, filter_type='bandpass', freq_range=(1, 50)):
    """Preprocess EEG data with filtering and artifact removal.

    This function applies a series of preprocessing steps to clean
    EEG data for further analysis.

    Parameters
    ----------
    eeg : EEGobj
        The EEG object to preprocess.
    filter_type : str, optional
        Type of filter to apply. Options: 'bandpass', 'highpass', 'lowpass'.
        Default is 'bandpass'.
    freq_range : tuple, optional
        Frequency range for filtering in Hz. Default is (1, 50).

    Returns
    -------
    dict
        The preprocessed EEG dictionary.

    Raises
    ------
    ValueError
        If filter_type is not recognized.
    TypeError
        If eeg is not an EEG dictionary.

    Examples
    --------
    >>> from eegprep import pop_eegfiltnew, pop_loadset
    >>> EEG = pop_loadset("data.set")
    >>> EEG, com = pop_eegfiltnew(EEG, locutoff=1, hicutoff=50, return_com=True)

    Notes
    -----
    This function returns the updated EEG dictionary.

    See Also
    --------
    clean_artifacts : Remove artifacts from EEG data
    clean_flatlines : Remove flat-line channels
    """
    # Implementation here
    pass

Documentation Examples#

Include practical examples in docstrings:

def load_bids_dataset(bids_root, subject_id):
    """Load a BIDS-formatted EEG dataset.

    Examples
    --------
    >>> import eegprep
    >>> eeg = eegprep.load_bids_dataset('/data/bids_root', 'sub-001')
    >>> print(eeg.nbchan)  # Number of channels
    64
    """
    pass

Pull Request Process#

Before Submitting#

  1. Update your branch with the latest upstream changes:

git fetch upstream
git rebase upstream/develop

  1. Run tests locally:

uv run pytest tests

  1. Check code style:

./pre-commit.py

  1. Build documentation locally:

cd docs
make html

Submitting a Pull Request#

  1. Push your branch to your fork:

git push origin feature/your-feature-name

  1. Go to the GitHub repository and click “New Pull Request”

  2. Fill in the PR template with:

    • Title: Clear, descriptive title

    • Description: What changes are made and why

    • Related Issues: Link to any related issues (e.g., “Fixes #123”)

    • Testing: Describe how you tested the changes

    • Documentation: Note any documentation updates

  3. Ensure all CI checks pass

  4. Wait for review and address feedback

PR Review Process#

  • At least one maintainer review is required

  • All CI checks must pass

  • Code coverage should not decrease

  • Documentation must be updated if needed

  • Commits should be clean and well-organized

Code of Conduct#

Respectful Collaboration#

We are committed to providing a welcoming and inclusive environment. All contributors must:

  • Be respectful and professional in all interactions

  • Welcome diverse perspectives and experiences

  • Provide constructive feedback

  • Report inappropriate behavior to the maintainers

Unacceptable Behavior#

The following behaviors are not tolerated:

  • Harassment, discrimination, or intimidation

  • Offensive comments or language

  • Unwelcome sexual attention or advances

  • Deliberate disruption of discussions

  • Publishing private information without consent

Reporting Issues#

If you experience or witness unacceptable behavior, please report it to the maintainers at:

  • Open an issue on GitHub (private if needed)

  • Contact the project maintainers directly

All reports will be handled confidentially and investigated promptly.

Getting Help#

Thank you for contributing to EEGPrep!