# 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](https://physionet.org) or [MOABB](https://moabb.neurotechx.com/docs/))
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](https://squidfunk.github.io/mkdocs-material/). 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models).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.

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

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

Replace `your-username` with your GitHub username.

4. Make sure to have anaconda or miniconda correctly installed in your machine, then start installing a new virtual enviroment
```bash
    $ conda create -n myenv python==3.10
```    

5. Now jump into the enviroment and upgrade pip
```bash
    $ conda activate myenv
    $ conda install pip
    $ pip install --upgrade pip
```

6. To install PhysioEx in development mode run:
```bash
    $ pip install -e .
```    

7. Now you need to keep your fork and the original physioex repo in sync creating an upstream:
```bash
    $ git remote add upstream https://github.com/guidogagl/physioex.git
```    

:::{admonition} Check that everything went allright
:class: warning
To check that the upstream is correctly setted up, run:
```bash
    $ git remote -v
```
And check that the output resembles:
```bash
    > 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)
```
:::

:::{admonition} Keep your fork updated
:class: tip
To keep your fork repo updated check the [official doc](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
:::

8. 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)

## 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](architecture/testing/overview.md).

### Running the tests

```bash
# 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:

```bash
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](architecture/library/overview.md) — subsystem map and cross-cutting types
- [Data](architecture/library/data.md) — datasets, pipeline, cache, readers, events
- [Models](architecture/library/models.md) — foundation encoders, classic architectures
- [Train](architecture/library/train.md) — training/eval loop, metrics, logging, CLIs
- [Explain](architecture/library/explain.md) — post-hoc, foundational (CSD), prototypes

**Test suite (Diagram B):**

- [Testing suite architecture](architecture/testing/overview.md) — fixtures, factories, markers, test layout