xnatbidscli 2.0.0__tar.gz → 2.1.0__tar.gz

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xnatbidscli
-Version: 2.0.0
+Version: 2.1.0
 Summary: CLI for logging into XNAT, downloading neuroimaging experiments, and converting them to BIDS.
 Project-URL: Homepage, https://github.com/nimh-dsst/xnat-bids-cli
 Project-URL: Documentation, https://xnatbidscli.readthedocs.io/
@@ -17,19 +17,21 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
 Requires-Python: >=3.11
-Requires-Dist: bioread>=3; python_version < '3.12'
+Requires-Dist: bioread>=3
 Requires-Dist: cubids>=1.2.1
 Requires-Dist: dcm2bids>=3
 Requires-Dist: dcm2niix>=1.0.20260416
-Requires-Dist: nibabel<5.4,>=5.3; python_version < '3.12'
-Requires-Dist: nibabel>=5.4.2; python_version >= '3.12'
-Requires-Dist: numpy<2
+Requires-Dist: nibabel>=5.4.2
 Requires-Dist: pandas<2.4,>=2
-Requires-Dist: phys2bids>=2.10; python_version < '3.12'
+Requires-Dist: phys2bids>=2.11
 Requires-Dist: pydicom>=2.4
+Requires-Dist: pymatreader>=1
 Requires-Dist: pyxnat>=1.6
 Requires-Dist: requests>=2
 Description-Content-Type: text/markdown

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/docs/changelog.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-10-28
+
+`physioconvert` now works on every supported Python version, using the new `phys2bids` 2.11 release. `download` no longer downloads over an experiment that is already on disk, and has a new `--overwrite` flag.
+
+### Added
+
+- `download --overwrite` deletes an experiment's existing directory and downloads it again. With `-a/--archive`, it also replaces an existing archive after a `COMPLETE` download.
+- `download --csv` skips with a `WARNING` every row of an experiment listed more than once (`DUPLICATE`, or `RENAME_CONFLICT` when its `SUBJECT_BIDS_RENAME`/`EXPERIMENT_BIDS_RENAME` values differ), and every experiment that would download into the same directory as another (`COLLISION`).
+- `pymatreader` is now installed with `xnatbidscli`, so `physioconvert` can read MATLAB `.mat` files without an extra install.
+
+### Changed
+
+- `download` skips an experiment whose directory already exists and is not empty, with a `WARNING` and a new `SKIPPED` status, instead of downloading over it. `-a/--archive` and `-d/--delete` are not run for it, with a louder `WARNING`. Skipped experiments do not change the exit code.
+- `physioconvert` works on every supported Python version (3.11 and newer), not just 3.11. `xnatbidscli` now requires `phys2bids` 2.11 or newer, which no longer caps `numpy` below 1.24. `phys2bids` and `bioread` install on every Python version, and the `numpy<2` and `nibabel<5.4` pins are removed.
+
+### Fixed
+
+- The `READER_MISSING` hint for `.mat` files now names `pymatreader`, the package `phys2bids` actually uses, instead of `scipy`.
+
 ## [2.0.0] - 2026-09-28
 
 The project is renamed from `xnatcli` to `xnatbidscli` and is published on PyPI. Downloads are faster and more reliable, and you can now rename subjects and experiments between `query` and `download`.
@@ -58,6 +77,7 @@ First release.
 - `xnatcli` subcommands: `login`, `query`, `download`, `mriconfig`, `mriconvert`, `physioconvert`, `bidsmap` and `cubids`.
 - A documentation site built with Zensical and hosted on Read the Docs.
 
-[Unreleased]: https://github.com/nimh-dsst/xnat-bids-cli/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/nimh-dsst/xnat-bids-cli/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/nimh-dsst/xnat-bids-cli/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/nimh-dsst/xnat-bids-cli/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/nimh-dsst/xnat-bids-cli/releases/tag/v1.0.0

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/docs/cli/download.md

@@ -4,12 +4,14 @@ Downloads every file belonging to one XNAT experiment (single-experiment mode, `
 
 1. Loads credentials from `~/.xnatbidscli/credentials.cfg`; if the file is missing or incomplete, exits with a message telling you to run `xnatbidscli login`.
 2. Connects to the stored server via PyXNAT.
-3. For each experiment, walks `project → subject → experiment`, then issues zip requests against XNAT's REST API: one bulk request for all scans, and one request per session-level resource (XNAT has no bulk "all resources" export endpoint, unlike scans). With `--accession`, an extra server-wide lookup happens first, in this order: subject ID, experiment ID, study UID (XNAT's stored session `UID`), then subject and experiment labels together. IDs and UIDs are unique across the server. Labels are only unique within their parent, so a label that matches more than one subject or experiment exits with an error listing each match's XNAT ID, project and subject; rerun with one of those IDs. A UID only matches sessions where XNAT stored it.
-4. Each zip is extracted directly into `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT/`, following XNAT's own scan/resource folder naming (not a custom path scheme), then discarded. If a resource resolves to a single file, XNAT sometimes streams that file directly instead of wrapping it in a zip; this is detected and the file is saved as-is rather than failing the experiment. If some resources download successfully and others fail, the successful ones are still kept and the experiment is reported as `FAILURE` with each failing resource named in the error.
+3. In `--csv` mode, every row is screened before anything downloads, and repeated or colliding experiments are skipped (see [Repeated experiments in the CSV](#repeated-experiments-in-the-csv)).
+4. For each experiment, if `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` (using any rename) already exists and is not empty, it counts as already downloaded. A `WARNING` is printed and the experiment is reported `SKIPPED` without contacting XNAT. `-a`/`-d` are not run for it either, and a second, louder `WARNING` says so. Pass `--overwrite` to delete the directory and download it again instead. The directory is deleted only after the experiment is found on XNAT. An empty directory does not count as downloaded. Because `-d` removes the directory, re-running after `-a -d` downloads those experiments again.
+5. For each experiment, walks `project → subject → experiment`, then issues zip requests against XNAT's REST API: one bulk request for all scans, and one request per session-level resource (XNAT has no bulk "all resources" export endpoint, unlike scans). With `--accession`, an extra server-wide lookup happens first, in this order: subject ID, experiment ID, study UID (XNAT's stored session `UID`), then subject and experiment labels together. IDs and UIDs are unique across the server. Labels are only unique within their parent, so a label that matches more than one subject or experiment exits with an error listing each match's XNAT ID, project and subject; rerun with one of those IDs. A UID only matches sessions where XNAT stored it.
+6. Each zip is extracted directly into `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT/`, following XNAT's own scan/resource folder naming (not a custom path scheme), then discarded. If a resource resolves to a single file, XNAT sometimes streams that file directly instead of wrapping it in a zip; this is detected and the file is saved as-is rather than failing the experiment. If some resources download successfully and others fail, the successful ones are still kept and the experiment is reported as `FAILURE` with each failing resource named in the error.
 
     `PROJECT` is the canonical XNAT project ID; `SUBJECT` and `EXPERIMENT` are the user-facing labels emitted by `xnatbidscli query`, unless overridden by that row's `SUBJECT_BIDS_RENAME`/`EXPERIMENT_BIDS_RENAME` values in `--csv` mode, or by `--rename-subject`/`--rename-experiment` in `-1`/`--accession` mode (see [Manual Interventions](../manual.md)) — XNAT is still queried using the original labels either way. In `--accession` mode, the resolved XNAT IDs (not labels) are used both to query XNAT and, absent a rename, as the on-disk `SUBJECT`/`EXPERIMENT` directory names.
 
-5. With `-a/--archive`, after each experiment is downloaded, its `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` directory (using any rename override) is tar+gzipped to `OUTPUT_DIR/archive/PROJECT-<P>_SUBJECT-<S>_EXPERIMENT-<E>.tar.gz`. An existing archive at that path is left untouched and reported as `SKIPPED`. With `-d/--delete` (requires `-a/--archive`), the `EXPERIMENT` directory is removed once its archive is `COMPLETE` or `SKIPPED`; the `SUBJECT` and then `PROJECT` parent directories are also removed if they become empty as a result.
+7. With `-a/--archive`, after each experiment is downloaded, its `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` directory (using any rename override) is tar+gzipped to `OUTPUT_DIR/archive/PROJECT-<P>_SUBJECT-<S>_EXPERIMENT-<E>.tar.gz`. An existing archive at that path is left untouched and reported as `SKIPPED`. With `-d/--delete` (requires `-a/--archive`), the `EXPERIMENT` directory is removed once its archive is `COMPLETE` or `SKIPPED`; the `SUBJECT` and then `PROJECT` parent directories are also removed if they become empty as a result.
 
 ```bash
 # Single experiment
@@ -45,6 +47,7 @@ xnatbidscli download --csv PATH/TO/QUERY.csv -o OUTPUT_DIR -a -d
 | `-l`, `--log` | *Optional.* Write a per-experiment log CSV to `OUTPUT_DIR/log/download_<YYYYMMDD_HHMMSS>_log.csv` (local time, captured at run start). |
 | `-a`, `--archive` | *Optional.* After downloading each experiment, tar+gzip its `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` directory into `OUTPUT_DIR/archive/PROJECT-<P>_SUBJECT-<S>_EXPERIMENT-<E>.tar.gz`. Existing archives are skipped with a warning. |
 | `-d`, `--delete` | *Optional.* Requires `-a/--archive`. After a successful archive, delete the `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` directory. Empty `SUBJECT` and `PROJECT` parent directories are also pruned. |
+| `--overwrite` | *Optional.* Delete a non-empty `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` directory and download it again, instead of skipping it as `SKIPPED`. The directory is deleted only after the experiment is found on XNAT. With `-a/--archive`, an existing archive is also replaced, but only after a `COMPLETE` download; otherwise it is kept, with a `WARNING`. |
 
 ## Per-experiment STATUS (and exit code)
 
@@ -56,17 +59,31 @@ In `--csv` mode, and in `--accession` mode when it resolves to a subject, the ru
 | `FAILURE` | The experiment exists, but a zip request raised an error. If the underlying HTTP connection was dropped mid-download (a transient network/server timeout), the reported error names this cause explicitly rather than a generic message. |
 | `NONEXISTENT` | The experiment lookup did not find anything on the server. |
 | `EMPTY` | The experiment exists but has no scans and no session-level resources. |
+| `SKIPPED` | Its experiment directory already existed and was not empty, so nothing was downloaded, archived or deleted. Use `--overwrite` to download it again. |
+| `DUPLICATE` | `--csv` only. The experiment is listed more than once with the same renames; every instance is skipped. |
+| `RENAME_CONFLICT` | `--csv` only. The experiment is listed more than once with different renames; every instance is skipped. |
+| `COLLISION` | `--csv` only. Different experiments would download into the same directory; all of them are skipped. |
 
-Exit code is `0` if every processed experiment is `COMPLETE` or `EMPTY`, and `1` otherwise; archiving/deletion outcome (see below) does not affect it.
+Exit code is `1` if any processed experiment is `FAILURE` or `NONEXISTENT`, and `0` otherwise, so skipped experiments do not fail a run. The archiving/deletion outcome (see below) does not affect it.
+
+## Repeated experiments in the CSV
+
+An experiment is identified by its `PROJECT`, `SUBJECT_LABEL` and `EXPERIMENT_LABEL`. Before anything downloads, `--csv` mode prints one `WARNING` per problem and skips every affected row:
+
+- **`DUPLICATE`:** the experiment appears on more than one row with the same `SUBJECT_BIDS_RENAME`/`EXPERIMENT_BIDS_RENAME` values (after the `sub-`/`ses-` prefix is added, so `01` and `sub-01` are the same). Delete the extra rows.
+- **`RENAME_CONFLICT`:** the experiment appears on more than one row with different rename values, including blank vs. filled. Keep one row.
+- **`COLLISION`:** different experiments would download into the same `PROJECT/SUBJECT/EXPERIMENT` directory, compared case-insensitively. Give each a unique rename.
+
+Fix the CSV and re-run; experiments that already downloaded are `SKIPPED`.
 
 ## Archiving and deletion (`-a`/`--archive`, `-d`/`--delete`)
 
-With `-a/--archive`, each experiment's directory is tar+gzipped regardless of its download STATUS, and one of these is printed:
+With `-a/--archive`, each downloaded experiment's directory is tar+gzipped regardless of its download STATUS, and one of these is printed. Experiments skipped before downloading (`SKIPPED`, `DUPLICATE`, `RENAME_CONFLICT`, `COLLISION`) are neither archived nor deleted, and the run summary repeats a `WARNING` with the number of `SKIPPED` ones.
 
 | Archive STATUS | Meaning |
 | --- | --- |
-| `COMPLETE` | The tarball was written successfully. |
-| `SKIPPED` | An archive already exists at that path; it is left untouched. |
+| `COMPLETE` | The tarball was written successfully. With `--overwrite`, this includes replacing an existing archive after a `COMPLETE` download. |
+| `SKIPPED` | An archive already exists at that path and was not replaced; it is left untouched. |
 | `FAILURE` | An error occurred while writing the tarball. |
 | `NONEXISTENT` | `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` does not exist (e.g., the download itself failed). |
 
@@ -94,4 +111,4 @@ When `-l/--log` is supplied, a CSV is written at `OUTPUT_DIR/log/download_<YYYYM
 DATESTAMP,USER,PROJECT,SUBJECT,EXPERIMENT,STATUS
 ```
 
-`DATESTAMP` is the per-experiment download attempt begin time, formatted to match Python's `logging` module default `asctime` (`YYYY-MM-DD HH:MM:SS,mmm`, local time). `USER` is the OS-level username running the command (via Python's `getpass.getuser()`). `SUBJECT`/`EXPERIMENT` reflect any rename override (`SUBJECT_BIDS_RENAME`/`EXPERIMENT_BIDS_RENAME` in `--csv` mode, `--rename-subject`/`--rename-experiment` in `-1`/`--accession` mode — see [Manual Interventions](../manual.md)), i.e. the on-disk directory names actually written under `OUTPUT_DIR` (for `--accession` without a rename, this is the resolved XNAT ID, not a label), not necessarily the original XNAT labels. One row is appended per processed experiment; rows are written under a lock so concurrent workers do not interleave.
+`DATESTAMP` is the per-experiment download attempt begin time, formatted to match Python's `logging` module default `asctime` (`YYYY-MM-DD HH:MM:SS,mmm`, local time). `USER` is the OS-level username running the command (via Python's `getpass.getuser()`). `SUBJECT`/`EXPERIMENT` reflect any rename override (`SUBJECT_BIDS_RENAME`/`EXPERIMENT_BIDS_RENAME` in `--csv` mode, `--rename-subject`/`--rename-experiment` in `-1`/`--accession` mode — see [Manual Interventions](../manual.md)), i.e. the on-disk directory names actually written under `OUTPUT_DIR` (for `--accession` without a rename, this is the resolved XNAT ID, not a label), not necessarily the original XNAT labels. One row is appended per processed experiment, including skipped ones (one row per CSV row for `DUPLICATE`, `RENAME_CONFLICT` and `COLLISION`); rows are written under a lock so concurrent workers do not interleave.

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/docs/cli/physioconvert.md

@@ -33,7 +33,7 @@ With `-n/--nphysio` > 1, the `phys2bids` conversions run in parallel across sepa
 | `CONVERTED` | `phys2bids` read the raw file and its `_physio.tsv.gz`/`.json` were written next to the paired `.nii.gz`. |
 | `SKIPPED` | The expected single-frequency `_physio.tsv.gz` already existed at its destination and was a valid, non-corrupt GZIP file; conversion was not attempted. |
 | `NOT_PHYSIO` | The referenced file matched a supported extension but could not be loaded as physiological data. |
-| `READER_MISSING` | The optional reader package `phys2bids` needs for this format is not installed (e.g. `bioread` for `.acq`, `scipy` for `.mat`, `sonpy` for `.smr`). This is an environment problem, not a data problem — install the package and re-run. |
+| `READER_MISSING` | The optional reader package `phys2bids` needs for this format is not installed (e.g. `bioread` for `.acq`, `pymatreader` for `.mat`, `sonpy` for `.smr`). This is an environment problem, not a data problem — install the package and re-run. |
 | `CONVERT_ERROR` | `phys2bids` raised while converting, produced no `.tsv.gz` output, or its destination was already occupied by a different association. |
 | `SOURCE_MISSING` | `PhysioParent` was unset/not a directory, the named basename was not found under it, or the `mriconvert_qc.tsv` row is missing `participant_id`/`datatype`. |
 | `COLLISION` | This `physio` basename is referenced by more than one `mriconvert_qc.tsv` row; none were converted until resolved. |
@@ -46,5 +46,3 @@ Exit code is `1` if any association is `CONVERT_ERROR` or `READER_MISSING`, and
 | `-p`, `--project` | **Required.** Project directory name under `OUTPUT_DIR` identifying the BIDS dataset produced by `xnatbidscli mriconvert`. |
 | `-n`, `--nphysio` | *Optional.* Number of physio conversions to run in parallel, one `phys2bids` conversion per process (default `1`). |
 | `-l`, `--log` | *Optional.* Write a per-association log CSV to `OUTPUT_DIR/log/physioconvert_<YYYYMMDD_HHMMSS>_log.csv` (header `DATESTAMP,USER,STATUS,MRI_FILENAME,PHYSIO_SOURCE,DESTINATION_PATH`). One row per processed association, except a conversion that produced several outputs emits one row per output; associations with no output get a single blank-`DESTINATION_PATH` row. Also mirrors everything printed to stdout/stderr into a companion text log at `OUTPUT_DIR/log/physioconvert_<YYYYMMDD_HHMMSS>_log.txt`, the Python equivalent of piping through `tee`. Off by default. |
-
-> **Note:** `physioconvert` needs Python 3.11. `phys2bids` 2.10.0, its latest release, caps `numpy` at `<1.24`, and `numpy` 1.23 has no builds for Python 3.12 or newer. So `phys2bids` (and `bioread`) install with `xnatbidscli` only on Python 3.11, where `nibabel` is held below 5.4. On Python 3.12 or newer, every other subcommand works and `physioconvert` exits with a message. This limit goes away once `phys2bids` releases its uncapped `master` branch.

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/docs/faq.md

@@ -25,7 +25,7 @@ Click a question to expand its answer, or use the buttons below to open or close
 
 ??? question "Why does physioconvert say phys2bids is required?"
 
-    `phys2bids` installs with `xnatbidscli` only on Python 3.11. Its latest release (2.10.0) caps `numpy` below 1.24, and that `numpy` has no builds for Python 3.12 or newer. On 3.12 or newer, every other subcommand works, but `physioconvert` exits with this message. To convert physio, install `xnatbidscli` under Python 3.11. This limit goes away once `phys2bids` makes a new release.
+    `phys2bids` could not be imported in your environment. Since `xnatbidscli` 2.1.0, `phys2bids` installs with `xnatbidscli` on every supported Python version. Older releases installed it only on Python 3.11. Upgrade with `pip install --upgrade xnatbidscli`.
 
     **References:**
 
@@ -69,6 +69,14 @@ Click a question to expand its answer, or use the buttons below to open or close
 
     - [`xnatbidscli download`](cli/download.md)
 
+??? question "What happens if I re-run download on experiments I already downloaded?"
+
+    An experiment whose `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` directory exists and is not empty is skipped with a `WARNING` and reported `SKIPPED`. It is not downloaded, archived or deleted. To download it again, pass `--overwrite`, which deletes the directory first and, with `-a`, replaces its archive once the download is `COMPLETE`. Because `-a -d` removes the directory, a re-run after it downloads again. In `--csv` mode, an experiment listed on more than one row, or two experiments renamed into the same directory, are skipped with a `WARNING` too (`DUPLICATE`, `RENAME_CONFLICT`, `COLLISION`). None of these skips change the exit code.
+
+    **References:**
+
+    - [`xnatbidscli download` — repeated experiments](cli/download.md#repeated-experiments-in-the-csv)
+
 ??? question "How do I archive downloaded data?"
 
     Pass `-a`/`--archive` to `download` (or `mriconvert`) to tar+gzip each experiment's directory into `OUTPUT_DIR/archive/PROJECT-<P>_SUBJECT-<S>_EXPERIMENT-<E>.tar.gz` once it's processed; add `-d`/`--delete` to remove the original directory after the archive is confirmed written.

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/docs/installation.md

@@ -8,9 +8,7 @@ pip install xnatbidscli
 
 This puts the `xnatbidscli` command on your `PATH`.
 
-> **Note:** [`physioconvert`](cli/physioconvert.md) needs Python 3.11 for now, because the latest `phys2bids` release does not support newer `numpy`. On Python 3.12 or newer, every other subcommand works.
-
-Runtime dependencies (installed automatically): `pyxnat`, `dcm2bids`, `dcm2niix` (the [`dcm2niix`](https://pypi.org/project/dcm2niix/) PyPI package vendors the binary onto your `PATH`), `pydicom`, `cubids`, `nibabel` (used to read NIfTI shapes for the `mriconvert` `scans.tsv`), `pandas` (used by `bidsmap`), and `phys2bids` (used by `physioconvert` to read physiological recordings and write BIDS physio files; Python 3.11 only, see the note under [`xnatbidscli physioconvert`](cli/physioconvert.md)). `bioread` is also pulled in on Python 3.11 for `phys2bids` to read BIOPAC `.acq` files (phys2bids imports it lazily but does not depend on it directly).
+Runtime dependencies (installed automatically): `pyxnat`, `dcm2bids`, `dcm2niix` (the [`dcm2niix`](https://pypi.org/project/dcm2niix/) PyPI package vendors the binary onto your `PATH`), `pydicom`, `cubids`, `nibabel` (used to read NIfTI shapes for the `mriconvert` `scans.tsv`), `pandas` (used by `bidsmap`), and `phys2bids` (used by `physioconvert` to read physiological recordings and write BIDS physio files). `bioread` and `pymatreader` are also pulled in for `phys2bids` to read BIOPAC `.acq` and MATLAB `.mat` files (phys2bids imports them lazily but does not depend on them directly).
 
 ## Latest unreleased features
 

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/docs/manual.md

@@ -44,6 +44,7 @@ After an optional `sub-`/`ses-` prefix is stripped, the remaining value must be
 
 - In `--csv` mode, `download` validates every row of the input CSV before downloading anything; if any `SUBJECT_BIDS_RENAME` or `EXPERIMENT_BIDS_RENAME` value fails this check, the entire run exits with an error and nothing is downloaded. Fix the offending cell(s) in the CSV and re-run `download`.
 - In `-1`/`--accession` mode, an invalid `--rename-subject`/`--rename-experiment` value exits with an error before downloading.
+- In `--csv` mode, an experiment listed on more than one row, with the same or different renames, or two experiments renamed into the same directory, are skipped with a `WARNING` rather than downloaded. See [Repeated experiments in the CSV](cli/download.md#repeated-experiments-in-the-csv).
 
 `--rename-subject`/`--rename-experiment` only apply to `-1`/`--accession` mode; supplying either alongside `--csv` is an error. `--rename-experiment` is additionally rejected when `--accession` resolves to a subject rather than an experiment.
 

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/pyproject.toml

@@ -19,24 +19,24 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Topic :: Scientific/Engineering :: Medical Science Apps.",
 ]
-# phys2bids 2.10.0 (latest release) caps numpy at <1.24, and numpy 1.23 has no
-# wheels past Python 3.11, so phys2bids (and its bioread reader) install only on
-# Python 3.11, where nibabel is held below 5.4 (5.4 needs numpy>=1.25). Drop
-# these markers once phys2bids releases its uncapped master.
+# bioread and pymatreader are the readers phys2bids imports lazily for .acq and
+# .mat files; it does not depend on them directly.
 dependencies = [
-    "bioread>=3; python_version < '3.12'",
+    "bioread>=3",
     "cubids>=1.2.1",
     "dcm2bids>=3",
     "dcm2niix>=1.0.20260416",
-    "nibabel>=5.3,<5.4; python_version < '3.12'",
-    "nibabel>=5.4.2; python_version >= '3.12'",
-    "numpy<2",
+    "nibabel>=5.4.2",
     "pandas>=2,<2.4",
-    "phys2bids>=2.10; python_version < '3.12'",
+    "phys2bids>=2.11",
     "pydicom>=2.4",
+    "pymatreader>=1",
     "pyxnat>=1.6",
     "requests>=2",
 ]

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/src/xnatbidscli/archive.py

@@ -21,20 +21,26 @@ def archive_path(
 
 
 def archive_experiment(
-    data_root: Path, project: str, subject: str, experiment: str
+    data_root: Path,
+    project: str,
+    subject: str,
+    experiment: str,
+    overwrite: bool = False,
 ) -> tuple[str, str | None]:
     """Tar+gzip data_root/PROJECT/SUBJECT/EXPERIMENT into data_root/archive/.
 
     Returns (status, detail). Existing archives are left untouched and reported
-    as SKIPPED; the tarball is written to a .tmp sibling and renamed into place
-    only on success so an interrupted run never leaves a partial file behind.
+    as SKIPPED unless `overwrite` is set; the tarball is written to a .tmp
+    sibling and renamed into place only on success so an interrupted run never
+    leaves a partial file behind (or loses the archive it was replacing).
     """
     src = data_root / project / subject / experiment
     if not src.is_dir():
         return STATUS_NONEXISTENT, f"source directory not found: {src}"
 
     dest = archive_path(data_root, project, subject, experiment)
-    if dest.exists():
+    replacing = dest.exists()
+    if replacing and not overwrite:
         return STATUS_SKIPPED, f"archive already exists: {dest}"
 
     dest.parent.mkdir(parents=True, exist_ok=True)
@@ -50,6 +56,8 @@ def archive_experiment(
             except Exception:
                 pass
         return STATUS_FAILURE, f"error creating archive: {e}"
+    if replacing:
+        return STATUS_COMPLETE, f"replaced existing archive: {dest}"
     return STATUS_COMPLETE, None
 
 

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/src/xnatbidscli/cli.py

@@ -197,6 +197,17 @@ def build_parser() -> argparse.ArgumentParser:
         "OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT directory. The SUBJECT and "
         "PROJECT parent directories are also removed if they become empty.",
     )
+    download_parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Delete a non-empty OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT "
+        "directory and download it again. Without this flag, such an "
+        "experiment is skipped with a warning (STATUS SKIPPED), along with "
+        "-a/--archive and -d/--delete for it. The directory is deleted only "
+        "after the experiment is found on XNAT. With -a/--archive, an "
+        "existing archive is also replaced, but only after a COMPLETE "
+        "download.",
+    )
     download_parser.set_defaults(func=download_cmd)
 
     mriconfig_parser = subparsers.add_parser(

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/src/xnatbidscli/download.py

@@ -20,6 +20,7 @@ from pyxnat.core import uriutil
 from .archive import (
     OK_STATUSES as ARCHIVE_OK_STATUSES,
     archive_experiment,
+    archive_path,
     delete_experiment_dir,
 )
 from .login import load_credentials
@@ -29,8 +30,32 @@ STATUS_COMPLETE = "COMPLETE"
 STATUS_FAILURE = "FAILURE"
 STATUS_NONEXISTENT = "NONEXISTENT"
 STATUS_EMPTY = "EMPTY"
+STATUS_SKIPPED = "SKIPPED"
+STATUS_DUPLICATE = "DUPLICATE"
+STATUS_RENAME_CONFLICT = "RENAME_CONFLICT"
+STATUS_COLLISION = "COLLISION"
+
+_OK_STATUSES = {
+    STATUS_COMPLETE,
+    STATUS_EMPTY,
+    STATUS_SKIPPED,
+    STATUS_DUPLICATE,
+    STATUS_RENAME_CONFLICT,
+    STATUS_COLLISION,
+}
+_SUMMARY_STATUSES = (
+    STATUS_COMPLETE,
+    STATUS_FAILURE,
+    STATUS_NONEXISTENT,
+    STATUS_EMPTY,
+    STATUS_SKIPPED,
+    STATUS_DUPLICATE,
+    STATUS_RENAME_CONFLICT,
+    STATUS_COLLISION,
+)
 
-_OK_STATUSES = {STATUS_COMPLETE, STATUS_EMPTY}
+# (PROJECT, SUBJECT_LABEL, EXPERIMENT_LABEL, SUBJECT_BIDS_RENAME, EXPERIMENT_BIDS_RENAME)
+CsvRow = tuple[str, str, str, str | None, str | None]
 
 _thread_iface = threading.local()
 
@@ -418,6 +443,40 @@ def _extract_zip_flattened_or_rescue(
         zip_path.replace(dest_dir / filename)
 
 
+def _has_contents(path: Path) -> bool:
+    """Return True if `path` is a directory with at least one entry in it."""
+    try:
+        return path.is_dir() and any(path.iterdir())
+    except OSError:
+        return False
+
+
+def _skip_existing(
+    label: str, experiment_root: Path, do_archive: bool, do_delete: bool
+) -> bool:
+    """Warn and return True if `experiment_root` was already downloaded.
+
+    A non-empty experiment directory counts as already downloaded. This is a
+    local check only, made before contacting XNAT. Archiving/deletion are
+    skipped along with the download, so the warning is loud when they were
+    requested.
+    """
+    if not _has_contents(experiment_root):
+        return False
+    _safe_print(
+        f"WARNING: {label}: {experiment_root} already exists and is not "
+        "empty; skipping download. Pass --overwrite to delete it and "
+        "download again."
+    )
+    if do_archive:
+        steps = "ARCHIVE (-a) AND DELETE (-d)" if do_delete else "ARCHIVE (-a)"
+        _safe_print(
+            f"WARNING: {steps} NOT RUN for {label}: its download was skipped, "
+            f"so {experiment_root} and any existing archive were left untouched."
+        )
+    return True
+
+
 def _process_experiment(
     interface: Interface,
     project: str,
@@ -428,6 +487,7 @@ def _process_experiment(
     progress: _ExperimentProgress | None = None,
     local_subject: str | None = None,
     local_experiment: str | None = None,
+    overwrite: bool = False,
 ) -> str:
     """Download one experiment as whole-experiment zip archives.
 
@@ -444,6 +504,10 @@ def _process_experiment(
     `EXPERIMENT_BIDS_RENAME`) name the on-disk directory when they differ
     from `subject`/`experiment`, which are always used to look up the
     experiment on the XNAT server itself.
+
+    With `overwrite`, a non-empty existing experiment directory is deleted
+    before downloading, but only once the experiment is confirmed to exist
+    on XNAT, so a lookup failure never costs the local copy.
     """
     label = f"{project}/{subject}/{experiment}"
     try:
@@ -461,6 +525,13 @@ def _process_experiment(
     experiment_root = (
         output_dir / project / (local_subject or subject) / (local_experiment or experiment)
     )
+    if overwrite and _has_contents(experiment_root):
+        report(f"WARNING: {label}: deleting existing {experiment_root} before re-downloading (--overwrite).")
+        try:
+            shutil.rmtree(experiment_root)
+        except OSError as e:
+            report(f"  Error deleting {experiment_root}: {e}")
+            return STATUS_FAILURE
     experiment_root.mkdir(parents=True, exist_ok=True)
 
     got_scans = False
@@ -507,12 +578,10 @@ def _format_bids_rename(value: str, prefix: str) -> str | None:
     return value if value.startswith(prefix) else prefix + value
 
 
-def _read_csv_rows(
-    path: Path,
-) -> list[tuple[str, str, str, str | None, str | None]]:
+def _read_csv_rows(path: Path) -> list[CsvRow]:
     if not path.exists():
         sys.exit(f"Error: input CSV not found: {path}")
-    rows: list[tuple[str, str, str, str | None, str | None]] = []
+    rows: list[CsvRow] = []
     with path.open(newline="") as f:
         reader = csv.DictReader(f)
         required = {"PROJECT", "SUBJECT_LABEL", "EXPERIMENT_LABEL"}
@@ -557,6 +626,76 @@ def _read_csv_rows(
     return rows
 
 
+def _screen_csv_rows(
+    rows: list[CsvRow],
+) -> tuple[list[CsvRow], list[tuple[CsvRow, str]]]:
+    """Split CSV rows into ones to download and ones skipped with a WARNING.
+
+    An experiment is identified by (PROJECT, SUBJECT_LABEL, EXPERIMENT_LABEL).
+    Every row of an experiment listed more than once is skipped: DUPLICATE
+    if all its rows have the same (normalized) renames, RENAME_CONFLICT if
+    not. Every remaining row whose on-disk directory is shared with a
+    different experiment is skipped as COLLISION.
+
+    Returns
+    -------
+    tuple[list[CsvRow], list[tuple[CsvRow, str]]]
+        Rows to download, and skipped rows paired with their STATUS.
+    """
+    by_experiment: dict[tuple[str, str, str], list[CsvRow]] = {}
+    for row in rows:
+        by_experiment.setdefault(row[:3], []).append(row)
+
+    flagged: dict[tuple[str, str, str], str] = {}
+    for key, group in by_experiment.items():
+        if len(group) < 2:
+            continue
+        label = "/".join(key)
+        if len({row[3:] for row in group}) == 1:
+            flagged[key] = STATUS_DUPLICATE
+            print(
+                f"WARNING: {label} is listed {len(group)} times in the input "
+                "CSV; skipping every instance. Remove the extra row(s) to "
+                "download it."
+            )
+        else:
+            flagged[key] = STATUS_RENAME_CONFLICT
+            renames = "; ".join(
+                f"SUBJECT_BIDS_RENAME={sr or '(blank)'}, "
+                f"EXPERIMENT_BIDS_RENAME={er or '(blank)'}"
+                for _, _, _, sr, er in group
+            )
+            print(
+                f"WARNING: {label} is listed {len(group)} times in the input "
+                "CSV with different SUBJECT_BIDS_RENAME/EXPERIMENT_BIDS_RENAME "
+                f"values ({renames}); skipping every instance. Keep only one "
+                "row to download it."
+            )
+
+    # Compared case-insensitively, since Windows and macOS filesystems would
+    # merge directories that differ only in case.
+    by_local_dir: dict[tuple[str, ...], dict[tuple[str, str, str], str]] = {}
+    for p, s, e, sr, er in rows:
+        local = f"{p}/{sr or s}/{er or e}"
+        key = tuple(part.casefold() for part in (p, sr or s, er or e))
+        by_local_dir.setdefault(key, {})[(p, s, e)] = local
+    for experiments in by_local_dir.values():
+        if len(experiments) < 2:
+            continue
+        labels = ", ".join("/".join(k) for k in experiments)
+        print(
+            f"WARNING: {labels} would all download into "
+            f"{next(iter(experiments.values()))}; skipping all of them. Give "
+            "each a unique SUBJECT_BIDS_RENAME/EXPERIMENT_BIDS_RENAME."
+        )
+        for key in experiments:
+            flagged.setdefault(key, STATUS_COLLISION)
+
+    to_download = [row for row in rows if row[:3] not in flagged]
+    skipped = [(row, flagged[row[:3]]) for row in rows if row[:3] in flagged]
+    return to_download, skipped
+
+
 def _archive_and_maybe_delete(
     output_dir: Path,
     project: str,
@@ -565,12 +704,30 @@ def _archive_and_maybe_delete(
     do_archive: bool,
     do_delete: bool,
     report: Callable[[str], None],
+    overwrite: bool = False,
+    download_status: str = STATUS_COMPLETE,
 ) -> None:
+    """Archive (and with `do_delete`, then delete) one experiment directory.
+
+    With `overwrite`, an existing archive is replaced, but only after a
+    COMPLETE download, so a failed or partial re-download never replaces a
+    good archive.
+    """
     if not do_archive:
         return
     label = f"{project}/{subject}/{experiment}"
+    replace = overwrite and download_status == STATUS_COMPLETE
+    if (
+        overwrite
+        and not replace
+        and archive_path(output_dir, project, subject, experiment).exists()
+    ):
+        report(
+            f"WARNING: not replacing the existing archive for {label} "
+            f"(--overwrite), since its download was {download_status}."
+        )
     a_status, a_detail = archive_experiment(
-        output_dir, project, subject, experiment
+        output_dir, project, subject, experiment, overwrite=replace
     )
     line = f"  archive {label}: {a_status}"
     if a_detail:
@@ -593,15 +750,23 @@ def _run_single(
     do_delete: bool,
     local_subject: str | None = None,
     local_experiment: str | None = None,
+    overwrite: bool = False,
 ) -> str:
     local_s = local_subject or subject
     local_e = local_experiment or experiment
+    label = f"{project}/{subject}/{experiment}"
+    if not overwrite and _skip_existing(
+        label, output_dir / project / local_s / local_e, do_archive, do_delete
+    ):
+        log_writer.write(_logging_now(), project, local_s, local_e, STATUS_SKIPPED)
+        return STATUS_SKIPPED
     iface = Interface(server=server, user=user, password=password)
     try:
         start = _logging_now()
         status = _process_experiment(
             iface, project, subject, experiment, output_dir, _safe_print,
             local_subject=local_s, local_experiment=local_e,
+            overwrite=overwrite,
         )
     finally:
         try:
@@ -617,6 +782,8 @@ def _run_single(
         do_archive,
         do_delete,
         _safe_print,
+        overwrite,
+        status,
     )
     return status
 
@@ -625,27 +792,28 @@ def _run_csv(
     server: str,
     user: str,
     password: str,
-    rows: list[tuple[str, str, str, str | None, str | None]],
+    rows: list[CsvRow],
     output_dir: Path,
     n_parallel_experiments: int,
     log_writer: _LogWriter,
     do_archive: bool,
     do_delete: bool,
+    overwrite: bool = False,
 ) -> dict[str, int]:
-    counts = {
-        STATUS_COMPLETE: 0,
-        STATUS_FAILURE: 0,
-        STATUS_NONEXISTENT: 0,
-        STATUS_EMPTY: 0,
-    }
-
-    def _worker(row: tuple[str, str, str, str | None, str | None]) -> str:
+    counts = dict.fromkeys(_SUMMARY_STATUSES, 0)
+
+    def _worker(row: CsvRow) -> str:
         p, s, e, subject_rename, experiment_rename = row
         local_s = subject_rename or s
         local_e = experiment_rename or e
-        iface = _get_thread_interface(server, user, password)
         label = f"{p}/{s}/{e}"
         experiment_root = output_dir / p / local_s / local_e
+        if not overwrite and _skip_existing(
+            label, experiment_root, do_archive, do_delete
+        ):
+            log_writer.write(_logging_now(), p, local_s, local_e, STATUS_SKIPPED)
+            return STATUS_SKIPPED
+        iface = _get_thread_interface(server, user, password)
         progress = _ExperimentProgress()
         stop_event = threading.Event()
         monitor = threading.Thread(
@@ -658,14 +826,15 @@ def _run_csv(
             start = _logging_now()
             status = _process_experiment(
                 iface, p, s, e, output_dir, _safe_print, progress,
-                local_s, local_e,
+                local_s, local_e, overwrite,
             )
         finally:
             stop_event.set()
             monitor.join()
         log_writer.write(start, p, local_s, local_e, status)
         _archive_and_maybe_delete(
-            output_dir, p, local_s, local_e, do_archive, do_delete, _safe_print
+            output_dir, p, local_s, local_e, do_archive, do_delete, _safe_print,
+            overwrite, status,
         )
         return status
 
@@ -714,6 +883,33 @@ def _run_csv(
     return counts
 
 
+def _print_summary(
+    heading: str,
+    counts: dict[str, int],
+    log_path: Path | None,
+    do_archive: bool,
+    do_delete: bool,
+) -> int:
+    """Print a batch run's per-STATUS counts and return its exit code.
+
+    Repeats the not-archived warning for SKIPPED experiments at the end,
+    since the per-experiment warnings may have scrolled away.
+    """
+    print(f"\n{heading}")
+    for status in _SUMMARY_STATUSES:
+        print(f"  {status}: {counts[status]}")
+    if do_archive and counts[STATUS_SKIPPED]:
+        steps = "ARCHIVED OR DELETED" if do_delete else "ARCHIVED"
+        print(
+            f"WARNING: {counts[STATUS_SKIPPED]} SKIPPED experiment(s) were NOT "
+            f"{steps}, since their existing directories were left untouched."
+        )
+    if log_path is not None:
+        print(f"Log written to {log_path}")
+    bad = counts[STATUS_FAILURE] + counts[STATUS_NONEXISTENT]
+    return 0 if bad == 0 else 1
+
+
 def _resolve_accession(
     interface: Interface, accession: str
 ) -> tuple[str, str, str, str | None]:
@@ -810,6 +1006,7 @@ def _download_accession(
     local_subject: str | None,
     local_experiment: str | None,
     log_path: Path | None,
+    overwrite: bool = False,
 ) -> int:
     """Handle `download --accession`: resolve it, then delegate like -1/--csv.
 
@@ -860,26 +1057,18 @@ def _download_accession(
         ]
         counts = _run_csv(
             server, user, password, rows, output_dir, n_parallel_experiments,
-            log_writer, do_archive, do_delete,
+            log_writer, do_archive, do_delete, overwrite,
+        )
+        return _print_summary(
+            f"Processed {sum(counts.values())} experiment(s) for subject "
+            f"accession {accession}:",
+            counts, log_path, do_archive, do_delete,
         )
-        total = sum(counts.values())
-        print(f"\nProcessed {total} experiment(s) for subject accession {accession}:")
-        for status in (
-            STATUS_COMPLETE,
-            STATUS_FAILURE,
-            STATUS_NONEXISTENT,
-            STATUS_EMPTY,
-        ):
-            print(f"  {status}: {counts[status]}")
-        if log_path is not None:
-            print(f"Log written to {log_path}")
-        bad = counts[STATUS_FAILURE] + counts[STATUS_NONEXISTENT]
-        return 0 if bad == 0 else 1
 
     status = _run_single(
         server, user, password, project, subject_id, experiment_id,
         output_dir, log_writer, do_archive, do_delete,
-        local_subject, local_experiment,
+        local_subject, local_experiment, overwrite,
     )
     print(
         f"Status for accession {accession} "
@@ -958,6 +1147,7 @@ def download_cmd(args: argparse.Namespace) -> int:
             args.delete,
             local_subject,
             local_experiment,
+            args.overwrite,
         )
         print(
             f"Status for {project}/{subject}/{experiment}: {status}"
@@ -980,9 +1170,10 @@ def download_cmd(args: argparse.Namespace) -> int:
             local_subject,
             local_experiment,
             log_path,
+            args.overwrite,
         )
 
-    rows = _read_csv_rows(Path(args.input))
+    rows, screened = _screen_csv_rows(_read_csv_rows(Path(args.input)))
     counts = _run_csv(
         server,
         user,
@@ -993,17 +1184,12 @@ def download_cmd(args: argparse.Namespace) -> int:
         log_writer,
         args.archive,
         args.delete,
+        args.overwrite,
+    )
+    for (p, s, e, sr, er), status in screened:
+        log_writer.write(_logging_now(), p, sr or s, er or e, status)
+        counts[status] += 1
+    return _print_summary(
+        f"Processed {sum(counts.values())} experiment(s):",
+        counts, log_path, args.archive, args.delete,
     )
-    total = sum(counts.values())
-    print(f"\nProcessed {total} experiment(s):")
-    for status in (
-        STATUS_COMPLETE,
-        STATUS_FAILURE,
-        STATUS_NONEXISTENT,
-        STATUS_EMPTY,
-    ):
-        print(f"  {status}: {counts[status]}")
-    if log_path is not None:
-        print(f"Log written to {log_path}")
-    bad = counts[STATUS_FAILURE] + counts[STATUS_NONEXISTENT]
-    return 0 if bad == 0 else 1

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/src/xnatbidscli/physioconvert.py

@@ -54,7 +54,7 @@ STATUS_SKIPPED = "SKIPPED"
 # is an environment problem, not a sign the file is not physiological data.
 _READER_PACKAGES = {
     ".acq": "bioread",
-    ".mat": "scipy",
+    ".mat": "pymatreader",
     ".smr": "sonpy",
 }
 
@@ -607,9 +607,8 @@ def physioconvert_cmd(args: argparse.Namespace) -> int:
         from phys2bids.phys2bids import phys2bids as _p2b  # noqa: F401
     except ImportError:
         sys.exit(
-            "Error: phys2bids is required for physioconvert. It installs with "
-            "xnatbidscli on Python 3.11 only until phys2bids releases support for "
-            "newer numpy; reinstall xnatbidscli under Python 3.11."
+            "Error: phys2bids is required for physioconvert. "
+            "Reinstall xnatbidscli with 'pip install --upgrade xnatbidscli'."
         )
 
     # physioconvert only reads mriconvert_qc.tsv -- it never writes it back.

{xnatbidscli-2.0.0 → xnatbidscli-2.1.0}/test_plan.md

@@ -75,6 +75,13 @@ This is a manual test plan for exercising every `xnatbidscli` subcommand and its
 - [ ] `-1` single-experiment mode ignores `SUBJECT_BIDS_RENAME`/`EXPERIMENT_BIDS_RENAME` entirely (no CSV involved)
 - [ ] `-a/--archive` produces `OUTPUT_DIR/archive/PROJECT-<P>_SUBJECT-<S>_EXPERIMENT-<E>.tar.gz` after each experiment downloads
 - [ ] Re-running with `-a/--archive` against an experiment whose archive already exists skips archiving with a warning (does not overwrite)
+- [ ] Re-running against an experiment whose directory exists and is not empty prints a `WARNING`, reports `SKIPPED`, does not contact XNAT for it, and exits `0`; an empty directory still downloads
+- [ ] With `-a` (and `-d`), a `SKIPPED` experiment prints a louder `WARNING` that archive/delete were not run, leaves its directory and archive untouched, and the summary repeats the count
+- [ ] `--overwrite` deletes a non-empty experiment directory and downloads it fresh; a `NONEXISTENT` experiment's local directory is not deleted
+- [ ] `--overwrite -a` replaces an existing archive after a `COMPLETE` download (archive `COMPLETE — replaced existing archive`); after a `FAILURE`/`EMPTY` download it keeps the old archive with a `WARNING`
+- [ ] A CSV listing the same experiment twice with the same renames (`01` vs `sub-01` counts as the same) prints one `WARNING` and reports both rows `DUPLICATE`, downloading neither
+- [ ] A CSV listing the same experiment twice with different renames (including blank vs. filled) prints one `WARNING` and reports both rows `RENAME_CONFLICT`, downloading neither
+- [ ] Two different experiments renamed into the same directory (also when differing only in case) print one `WARNING` and are both reported `COLLISION`, downloading neither
 - [ ] `-d/--delete` without `-a/--archive` fails immediately with "requires -a/--archive"
 - [ ] `-a -d` together delete `OUTPUT_DIR/PROJECT/SUBJECT/EXPERIMENT` only after a successful archive
 - [ ] `-a -d` also removes the `SUBJECT` and then `PROJECT` parent directories if they become empty