Metadata-Version: 2.4
Name: nemar-py
Version: 0.2.0
Summary: A Python client for accessing NEMAR datasets.
Author: NEMAR Organization
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/nemarOrg/nemar-py
Project-URL: Repository, https://github.com/nemarOrg/nemar-py
Project-URL: Issues, https://github.com/nemarOrg/nemar-py/issues
Project-URL: Changelog, https://github.com/nemarOrg/nemar-py/releases
Keywords: neuroscience,bids,eeg,meg,ieeg,nemar,dataset,download
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2
Requires-Dist: tqdm
Requires-Dist: typer>=0.12
Requires-Dist: wcmatch>=10.1
Requires-Dist: s3fs>=2024.1
Provides-Extra: datalad
Requires-Dist: datalad>=0.19; extra == "datalad"
Requires-Dist: git-annex>=10; extra == "datalad"
Dynamic: license-file

# nemar-py

Python + CLI client for downloading public **NEMAR** datasets (BIDS / EEG / MEG / iEEG) from `data.nemar.org`.

## Install

```shell
pip install nemar-py            # S3 + HTTPS backends
pip install nemar-py[datalad]   # + the optional DataLad layer
```

The default install uses the direct-S3 and HTTPS backends. The optional
`[datalad]` extra adds the DataLad layer; it bundles the `git-annex` binary
via the `psychoinformatics-de` PyPI wheel (Linux, macOS, Windows), so no
system package step is needed. Without the extra, `--downloader datalad` and
the `auto` chain's DataLad layer fall through to S3 / HTTPS automatically.

## Quick start

```shell
nemar-py download nm000132 -o data/nm000132
```

```python
import nemar
nemar.download(dataset="nm000132", target_dir="data/nm000132")
```

## CLI

| Command                        | Purpose                              |
| ------------------------------ | ------------------------------------ |
| `nemar-py download <DATASET>`  | Download a dataset                   |
| `nemar-py versions <DATASET>`  | List versions advertised by NEMAR    |

### Common flags

| Flag                      | Effect                                              |
| ------------------------- | --------------------------------------------------- |
| `-o, --output DIR`        | Target directory (default `./<DATASET>`)            |
| `-j, --jobs N`            | Parallel downloads (default 16)                     |
| `--tag TAG`               | Pin a version; default `latest`                     |
| `--downloader BACKEND`    | `auto` (default) \| `s3` \| `python` \| `datalad`   |
| `--no-data`               | Sidecars only — skip annexed binaries               |
| `--stimuli`               | Add `stimuli/` scope                                |
| `--derivatives`           | Add `derivatives/` scope                            |
| `--metadata-timeout S`    | Override 30 s metadata timeout                      |
| `--verbose`               | Echo resolved parameters before transfer            |

### BIDS filters (repeatable)

| Flag                                                    | Accepts                                |
| ------------------------------------------------------- | -------------------------------------- |
| `--subject`, `--session`, `--task`, `--run`, `--acq`    | `001` or `sub-001`                     |
| `--datatype`, `--suffix`, `--extension`                 | `eeg`, `T1w`, `.set`, …                |
| `--scope`                                               | `raw`, `derivatives`, `stimuli`, …     |
| `--pipeline`                                            | Subfolder under `derivatives/`         |
| `--entity key=value`                                    | Generic BIDS entity                    |
| `--include PATTERN`, `--exclude PATTERN`                | Path globs                             |

Labels accept either bare (`001`) or BIDS-prefixed (`sub-001`) form.

## Examples

```shell
# One subject, one task, EEG .set + sidecars
nemar-py download nm000132 \
  --subject 001 --task MMN --datatype eeg --suffix eeg --extension .set

# Derivatives from one pipeline
nemar-py download nm000132 --derivatives --pipeline eeglab --subject 001

# Metadata sweep — sidecars only, no big binaries
nemar-py download nm000132 --no-data -o nm000132-metadata
```

```python
import nemar
nemar.download(
    dataset="nm000132",
    subject=["001", "002"],
    task="MMN", datatype="eeg", suffix="eeg", extension=".set",
)
```

## Behaviour

- Catalog (`index`, `version`, `manifest`) is fetched from `https://data.nemar.org/{dataset}/`. No auth.
- File bytes use a layered chain: **S3 → (DataLad) → HTTPS**.
  - **S3** is tried first — anonymous public-read against `nemar.s3.us-east-2.amazonaws.com`, content-addressed at `<dataset>/objects/<git-annex-key>` (`eegdash`-style direct fetch).
  - **DataLad** is an optional middle layer, active only when the `[datalad]` extra is installed *and* the dataset index advertises a `datalad_url`. Absent the extra, this layer is skipped (a missing import is caught and falls through).
  - **HTTPS** through `data.nemar.org` is the always-available fallback, with Range/206 resume.
- BIDS root files (`dataset_description.json`, `participants.tsv`/`json`, `README*`, `CHANGES`, `LICENSE`) are always kept — even with `--include` / `--exclude`.

