Contributing to PhysioEx#

Welcome to the PhysioEx project! We appreciate your interest in contributing.

Ways to contribute#

Numerous avenues exist for contributing to the PhysioEx project, with the most prevalent being the provision of code or enhancements to the documentation. The refinement of the documentation is equally as vital as the augmentation of the library itself.

Should you discover an error in the documentation, or have implemented improvements, we encourage you to post a new message on the GitHub discussion board or, ideally, submit a GitHub pull request.

An additional method of contribution involves reporting any issues you encounter, and endorsing issues reported by others that are pertinent to you by giving them a “thumbs up”. Your support in promoting the project is also beneficial: mention the project in your blog posts and articles, provide a link to it from your website, or simply give it a star to indicate your usage of it.

Adviced contributing fields#

  1. Adding support for a new physiological signal dataset (e.g. checking PhysioNet or MOABB)

  2. Adding support for a new deep learning architecture for physiological signal analysis.

  3. Proposing a novel Explainable AI algorithm.

Consider also this other very important fields of contribution:

  • Documentation improving, note: check the official MkDocs Material doc. as reference.

  • Code improving and issues solving.

How to Contribute#

We welcome contributions from everyone. PhysioEx is a GitHub hosted libray, to know more about GitHub collaborative devolpment check their ufficial doc.To get started, follow these steps:

  1. Fork the Repository

Fork this repository to your GitHub account by clicking on the ‘Fork’ button on the top right of the page. This creates a copy of the repository in your account.

  1. Clone your fork of the physioex repo from your GitHub account to your local disk:

    $ git clone git@github.com:your-username/physioex.git 
    $ cd physioex

Replace your-username with your GitHub username.

  1. Make sure to have anaconda or miniconda correctly installed in your machine, then start installing a new virtual enviroment

    $ conda create -n myenv python==3.10

  1. Now jump into the enviroment and upgrade pip

    $ conda activate myenv
    $ conda install pip
    $ pip install --upgrade pip

  1. To install PhysioEx in development mode run:

    $ pip install -e .

  1. Now you need to keep your fork and the original physioex repo in sync creating an upstream:

    $ git remote add upstream https://github.com/guidogagl/physioex.git

Check that everything went allright

To check that the upstream is correctly setted up, run:

    $ git remote -v

And check that the output resembles:

    > origin    https://github.com/your-username/physioex.git (fetch)

    > origin    https://github.com/your-username/physioex.git (push)

    > upstream  https://github.com/guidogagl/physioex.git (fetch)
    > upstream  https://github.com/guidogagl/physioex.git (push)

Keep your fork updated

To keep your fork repo updated check the official doc

  1. Write your code & documentation and when it’s ready submit a Pull Request! For a step-by-step guide on how to submit a PR check the GitHub official documentation

Testing#

PhysioEx uses pytest. Install the dev extra (pip install -e .[dev]) to get pytest and pytest-cov. The suite mirrors the library layout under tests/ (tests/data, tests/models, tests/train, tests/explain), with shared fixtures in tests/conftest.py and synthetic-data generators in tests/factories/. The test architecture is documented in the testing class diagram.

Running the tests#

# Fast unit/integration suite — exactly what CI runs (no data, network, or GPU):
pytest -m "not real_data and not gpu and not hf"

# With the coverage gate (CI fails below the threshold):
pytest -m "not real_data and not gpu and not hf" --cov=physioex --cov-report=term-missing

# A single subpackage or file:
pytest tests/data
pytest tests/models/test_foundation_preproc.py -q

Markers#

Heavy tests are gated behind markers and auto-skip / deselect unless their environment is present, so the default run stays hermetic:

Marker

Runs only when…

What it covers

real_data

PHYSIOEX_TEST_REAL_DATA=1

real PSG datasets on disk (e.g. MASS SS02)

hf

PHYSIOEX_TEST_HF=1

building foundation encoders from HuggingFace weights

gpu

torch.cuda.is_available()

CUDA-specific code paths

slow

always (opt-out with -m "not slow")

long-running builds

unit, integration

always

plain classification of scope

Enable a gated tier explicitly, e.g. on a GPU box with data mounted:

PHYSIOEX_TEST_REAL_DATA=1 pytest -m real_data
PHYSIOEX_TEST_HF=1        pytest -m hf

Conventions#

  • Assert with native assert (a thin 2-line report(name, ok, detail) shim wrapping assert is retained in the large dataset files).

  • Reuse the synthetic-data factories in tests/factories/; don’t re-implement EDF/annotation writers per test.

  • New public API must be reachable from tests/test_api_surface.py (its __all__ export) and covered by a behavioural test in the matching subpackage.

  • CI (.github/workflows/test.yml) runs the fast suite on Python 3.11 and 3.12 and enforces a coverage gate; the target is being raised progressively.

Architecture (internals)#

Living class diagrams, extracted directly from the source and kept in sync with the code — a map for contributors of how the library and its test suite are structured. These are internal references, not needed to use PhysioEx.

Library (Diagram A):

  • Overview — subsystem map and cross-cutting types

  • Data — datasets, pipeline, cache, readers, events

  • Models — foundation encoders, classic architectures

  • Train — training/eval loop, metrics, logging, CLIs

  • Explain — post-hoc, foundational (CSD), prototypes

Test suite (Diagram B):