openads 2.0.0__tar.gz

openads-2.0.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [2.0.0] - unreleased
+
+### Changed for the PyPI release (ADR-041)
+- Import package renamed from `ads` to `openads` (`import openads as ads`); a
+  different PyPI distribution also installs a module `ads`. Console scripts:
+  `openads` and `ads`. Plugin entry-point groups: `openads.plugins`, `openads.stages`.
+- `openads assets download [--kind model|atlas|example] [--assets-dir] [--url]`
+  (and `openads.download_assets()`): fetches the assets from `assets/` of
+  farialab/OpenADS on GitHub (pinned commit; `ADS_ASSETS_URL` for another mirror),
+  verifies SHA-256, prints the JHU licence it accepts.
+- `runtime.device` defaults to `auto`: CUDA when visible, else the CPU (logged).
+- The wheel and sdist contain code only; the sdist no longer carries the
+  repository-only regression harness (`tools/`) or verification reports.
+
+A refactor of OpenADS 1.0 (HEAD 6c378d1) into one library with the same output
+tree and the same numerics. Every original function is mapped in
+`docs/refactor/mapping.md`; the decisions are ADRs in
+`docs/refactor/decisions.md`; the regression evidence (stage gates and
+verification reports) stays in the development repository.
+
+### Added
+- Package layout `src/openads` with layers cli -> pipelines -> stages -> steps ->
+  {ops, io, models, core/config/registry/inputs/assets}
+  (`docs/architecture.md`).
+- Python API: `openads.run_dwi`, `openads.run_pwi`, `openads.run_combined`,
+  `openads.run_stage` (run one stage on an existing output folder),
+  `openads.load_config`, `openads.SubjectWorkspace`; `import openads` loads no heavy
+  library.
+- Method registry: `@register(stage, name, params=..., modalities=...)`,
+  modality-aware (`Registry.available(stage, modality)`), built-in methods
+  auto-discovered (`openads.registry.import_submodules`), plugins through the
+  `openads.plugins` entry-point group.
+- Stage registry: `openads.stages.register_stage`, entry-point group `openads.stages`,
+  `Pipeline.with_stages(...)`, `OutputLayout.extended(...)`; cleanup keeps the
+  layout's non-transient artifacts.
+- `openads.steps`: shared file-level building blocks (`write_normalized`,
+  `write_dwi_segmentation`, PWI segmentation helpers, `warp_to_affsyn`).
+- `openads.ops`: the 1.0 numerics as pure, unit-tested functions (ADC, volume
+  order, pseudo-DWI, masks, KDE normaliser, padding, DAGMNet inference
+  helpers, symClassic, post-processing, metrics, TTP, atlas QFV, radiology
+  report, SHAP, figures).
+- Typed configuration with packaged defaults (`openads/config/defaults`), strict
+  keys, `--config` / `--set key=value` layering, `ads config show`.
+- One output-layout table (`openads.core.layout`) for all 156 files of the 1.0
+  tree; data import with input specs, discovery and named derivations
+  (`openads.inputs`).
+- Asset resolution (`ADS_ASSETS_DIR`, repository checkout, user cache) with a
+  SHA-256 manifest: `ads assets where|verify`.
+- CLI: `ads dwi|pwi|combined|stages list|stages run|config show|assets|version`
+  (in-process), `--set`, `--dwi-set`/`--pwi-set`; stage help generated from
+  the stage specs; `ads dwi|pwi --dry-run` and `ads stages list --json` print
+  JSON for other tools.
+- Client helpers: `Pipeline.plan()` / `openads.RunPlan` (stages and output folder
+  without running), `openads.example_subjects()`, `openads.parse_ref` /
+  `openads.stages.resolve_ref` (stage input/output references).
+- User documentation: README, `docs/user_guide.md`, `docs/configuration.md`
+  (generated by `tools/gen_config_doc.py`), `docs/extending.md`,
+  `docs/architecture.md`.
+- Refactor records: `docs/refactor/{mapping,decisions,harness,functions}.md`,
+  verification reports, regression harness in `tools/` (multi-run noise
+  envelope, population noise for motion-correction transforms, strict2
+  reference with the cuDNN autotuner pinned off).
+
+- Thin clients on the public API, outside the wheel: web server `apps/server`
+  (FastAPI, 1.0 endpoints + a job API), Qt GUI launcher `apps/gui`, web pages
+  `apps/web`, Docker images `docker/`, 1.0-compatible `scripts/*.sh` wrappers.
+
+### Changed
+- Faster DWI inference (ADR-039): DAGMNet-DWI's transposed convolutions run on
+  the model device (`stages.inference.params.transpose_backend: torch`; 1.0's
+  CPU NumPy loop is `numpy`): the stage takes ~10 s instead of ~60 s, with
+  identical output files on the example subject. `runtime.cudnn_benchmark`
+  defaults to `false` (1.0: `true`): SynthStrip 2.4 s instead of 5.8 s and no
+  run-to-run mask flips from the cuDNN autotuner.
+- Faster HP_symClassic generation (ADR-040): vectorised supervoxel selection
+  and threaded per-slice SLIC, ~2 s instead of ~17 s, bit-identical masks.
+- Distribution renamed to `openads` (import package and console script stay
+  `ads`).
+- The CLI no longer shells out to `scripts/run_ads_*.py`; the shell wrappers
+  are replaced by `ads dwi|pwi|combined`.
+- Fail fast: no silent CUDA->CPU or `cuda:1`->`cuda:0` fallback (`DeviceError`);
+  places where 1.0 logged an error and continued now raise (listed per stage in
+  the ADRs). Tolerated, configurable exceptions: the motion-correction timeout
+  skip and the argmin TTP for PWI without a JSON sidecar
+  (`no_json_policy: legacy`).
+- Motion correction runs in a `fork`ed child by default (as 1.0); `spawn` is
+  opt-in (`motion_correction.start_method`).
+- Packaging: PEP 639 license metadata (`LicenseRef-JHU-Non-Profit-Research`),
+  `setuptools>=77`, dependency ranges instead of exact pins, `MANIFEST.in`
+  (no assets and no verification reports in the sdist). Every dependency of
+  `ads dwi --all` / `ads pwi --all` is in the default install.
+- Default output root is `output` relative to the working directory.
+- The `report` numerics (`openads.ops.interpret`, `openads.ops.radiology`) import
+  pandas lazily.
+
+### Removed
+- Unused 1.0 modules (dead parallel implementations, unused services, domain
+  dataclasses, legacy loaders); each is listed with its reason in
+  `docs/refactor/mapping.md`.
+- `tqdm` dependency (never imported).
+
+### Known behaviour kept from 1.0
+- Run-to-run differences of the original method: multithreaded ANTs
+  registration, the cuDNN autotuner (1-10 voxels of a network mask), and the
+  bistable KDE ADC normaliser (ADR-020 to ADR-022). A 1-voxel brain-mask
+  difference can change the downstream registration (ADR-026).
+- Numerical quirks of 1.0 are kept verbatim and listed in ADR-034.

openads-2.0.0/LICENSE

@@ -0,0 +1,24 @@
+JHU Non-Profit Research Software License Agreement  
+
+This license agreement ("License") is effective automatically between you, a non-profit academic or non-profit research institution ("Licensee"), and The Johns Hopkins University (“JHU”) for use of the software with which this License is distributed (“Software”) so long as Licensee complies with the following terms and conditions:
+
+The requirement to acknowledge the copyright of JHU as follows: “© The Johns Hopkins University” and copyrights of any incorporated third-party software as described in the associated documentation.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the source code must retain the above copyright notice and these terms and conditions.
+
+Neither the name of JHU nor its affiliates may be used to endorse or promote products derived from this Software without specific prior written permission from an authorized JHU representative.
+
+THIS SOFTWARE IS PROVIDED BY JHU "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JHU BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. LICENSEE AGREES TO DEFEND, INDEMNIFY AND HOLD HARMLESS JHU FOR ANY CLAIMS ARISING FROM LICENSEE’S USE OF THE SOFTWARE TO THE FULLEST EXTENT PERMITTED BY LAW.
+
+Only a non-exclusive, nontransferable license is granted to Licensee to use the Software for non-commercial, non-profit purposes. Commercial use of the Software, including research use by for-profit entities, requires a separately executed written license agreement.
+
+Licensee agrees that it will use the Software, and any modifications, improvements, or derivatives of the Software that the Licensee may create (collectively, "Improvements") solely for non-commercial, non-profit purposes and shall not distribute or transfer the Software or Improvements to any third-party without requiring that such third-parties adhere to the terms of this License. Licensee agrees that any Improvements made by Licensee shall be subject to the same terms and conditions as the Software.
+
+Licensee acknowledges that JHU holds copyright in the Software or portions of the Software, and that the Software may incorporate third-party software which may be subject to additional terms and conditions. Licensee shall comply with any additional terms and conditions appliable to such third-party software.
+
+Licensee agrees that any publication of results obtained with the Software will acknowledge its use by an appropriate citation.
+
+Licensee’s rights under this License terminate automatically without notice from JHU if Licensee fail to comply with any term(s) of this License.
+
+This License shall be governed by the laws of the State of Maryland, excluding the application of its conflicts of law rules. Licensee agrees that any dispute shall be appropriate only in the state and federal courts located within the State of Maryland.
+

openads-2.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# sdist contents. The wheel only ships src/openads (+ package data in pyproject.toml).
+include LICENSE README.md CHANGELOG.md pyproject.toml MANIFEST.in
+graft src/openads
+graft tests
+graft docs
+# Models, atlases and examples (~320 MB) are never packaged; see ADS_ASSETS_DIR.
+prune assets
+# Gate reports reference local baseline runs; they stay in the repository only.
+prune docs/refactor/verification
+global-exclude __pycache__ *.py[cod] *.so .DS_Store

openads-2.0.0/PKG-INFO

@@ -0,0 +1,342 @@
+Metadata-Version: 2.4
+Name: openads
+Version: 2.0.0
+Summary: OpenADS: acute stroke detection pipelines for DWI and PWI MRI
+Author: Joshua Shun Liu, Chin-Fu Liu
+Author-email: "Andreia V. Faria" <andreia.faria@gmail.com>
+License-Expression: LicenseRef-JHU-Non-Profit-Research
+Project-URL: Homepage, https://github.com/farialab/OpenADS
+Project-URL: Repository, https://github.com/farialab/OpenADS
+Project-URL: Issues, https://github.com/farialab/OpenADS/issues
+Project-URL: Changelog, https://github.com/farialab/OpenADS/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/farialab/OpenADS/tree/main/docs
+Keywords: stroke,MRI,DWI,PWI,segmentation,neuroimaging
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Operating System :: POSIX :: Linux
+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: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: antspyx<0.7,>=0.5.4
+Requires-Dist: joblib<2,>=1.4
+Requires-Dist: matplotlib<4,>=3.9
+Requires-Dist: nibabel<6,>=5.3
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: pandas<3,>=2.2
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: scikit-image<1,>=0.24
+Requires-Dist: scikit-learn<2,>=1.7
+Requires-Dist: scipy<2,>=1.13
+Requires-Dist: shap<1,>=0.50
+Requires-Dist: surfa<0.7,>=0.6.3
+Requires-Dist: torch<3,>=2.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.13; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "server"
+Requires-Dist: python-multipart; extra == "server"
+Provides-Extra: gui
+Requires-Dist: PyQt5>=5.15; extra == "gui"
+Dynamic: license-file
+
+# OpenADS
+
+OpenADS is an end-to-end pipeline for acute stroke MRI. For one subject folder
+it runs preprocessing, brain masking, MNI registration, lesion segmentation
+(DWI) or hypoperfusion segmentation (PWI), and report generation, and writes
+NIfTI masks, metrics, QFV/lesion-load tables, a text radiological report, SHAP
+interpretation PDFs and PNG figures.
+
+- Distribution name: `openads`. Import package: `openads` (`import openads as ads`).
+  Console scripts: `openads` and `ads` (the same program).
+- Version 2.0 is a refactor of OpenADS 1.0. It writes the same output tree with
+  the same numerics (see [`docs/refactor/`](docs/refactor/)), and adds a
+  Python API, a method and stage plugin system, and typed configuration.
+- Platform: Linux, Python 3.10-3.12. An NVIDIA GPU with CUDA is used when
+  present; without one OpenADS runs on the CPU (slower).
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install openads
+openads assets download          # model weights, atlases, example subjects (~360 MB, once)
+openads version
+```
+
+From a Jupyter notebook, install into the notebook's own environment with `%pip`
+(not `!pip`, which may use another Python):
+
+```ipython
+%pip install openads
+!openads assets download
+```
+
+**CPU or GPU.** `pip install openads` installs torch as well. On Linux, PyPI's
+torch is the CUDA build (large); on Windows and macOS it is the CPU build. To
+choose explicitly, install torch first and then OpenADS, which keeps the torch
+you already have:
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cpu    # CPU only, small
+# or: uv pip install --torch-backend=auto openads                     # uv picks CUDA or CPU for this machine
+pip install openads
+```
+
+In an environment that already has a CUDA build of torch (>= 2.5), `pip install
+openads` uses it. The default `runtime.device: auto` takes the GPU when torch
+sees one and otherwise the CPU, and logs which; `--set runtime.device=cuda`
+insists on the GPU and fails without one.
+
+Every dependency that `ads dwi --all` and `ads pwi --all` need is in the
+default install (torch, antspyx, nibabel, scipy, scikit-image, scikit-learn,
+pandas, matplotlib, shap, surfa, joblib, PyYAML). Optional extras: `dev`
+(pytest, ruff, mypy, build, twine), `server` and `gui` (for the web server and
+GUI launcher, see [GUI / server / Docker](#gui--server--docker)).
+
+For development, from a source checkout: `pip install -e ".[dev]"`.
+
+## Assets (models, atlases, examples)
+
+The model checkpoints, atlases and example subjects are not in the wheel.
+`openads assets download` fetches them from the `assets/` folder of the official
+[farialab/OpenADS](https://github.com/farialab/OpenADS) repository (pinned commit), checks
+every file against the SHA-256 in the packaged manifest, and stores them in
+`~/.cache/openads/assets` (or `ADS_ASSETS_DIR`). It prints the licence first:
+**downloading accepts the JHU Non-Profit Research Software License** (see
+[License](#license)). Re-running it skips files that are already correct.
+
+```bash
+openads assets download                  # everything
+openads assets download --kind atlas     # only atlases (also: model, example)
+openads assets download --assets-dir DIR # somewhere else
+ADS_ASSETS_URL=https://my.mirror/openads-assets openads assets download   # another mirror
+```
+
+OpenADS looks for the asset root in this order and never downloads on its own:
+
+1. an explicit `paths.assets_dir` in the configuration,
+2. the environment variable `ADS_ASSETS_DIR`,
+3. `<repository>/assets` when OpenADS runs from a source checkout,
+4. `~/.cache/openads/assets`.
+
+```bash
+openads assets where                     # show the candidates and the root in use
+openads assets verify                    # check sizes and SHA-256 against the manifest
+openads assets verify --no-hash          # sizes only (fast)
+```
+
+## Command line quick start
+
+Each OpenADS 1.0 command has a 2.0 equivalent:
+
+| OpenADS 1.0 | OpenADS 2.0 |
+|---|---|
+| `./scripts/run_dwi.sh SUBJECT --all --gpu 1` | `ads dwi --subject-path SUBJECT --all --gpu 1` |
+| `./scripts/run_pwi.sh SUBJECT --all --gpu 1` | `ads pwi --subject-path SUBJECT --all --gpu 1` |
+| `./scripts/run_combined.sh --dwi D --pwi P --all --gpu 1` | `ads combined --dwi-subject-path D --pwi-subject-path P --all --gpu 1` |
+| `python scripts/run_ads_dwi.py --subject-path S --config C ...` | `ads dwi --subject-path S --config my.yaml ...` |
+| `python -m openads.cli dwi ...` | `ads dwi ...` or `python -m openads dwi ...` |
+
+```bash
+# Full DWI and PWI pipelines on the example subject (after `openads assets download`;
+# from a source checkout the examples are in assets/examples, else ~/.cache/openads/assets/examples)
+ads dwi --subject-path assets/examples/dwi/sub-02e8eb42 --all --gpu 0 --output-root out
+ads pwi --subject-path assets/examples/pwi/sub-02e8eb42 --all --gpu 0 --output-root out
+
+# Selected stages, a custom output root
+ads dwi --subject-path /data/dwi/sub-0037761d \
+    --stages prepdata,gen_mask,skull_strip,registration,inference,report --gpu 0 --output-root /output
+ads pwi --subject-path /data/pwi/sub-0037761d \
+    --stages prepdata,gen_mask,skull_strip,gen_ttp,registration,ttpadc_coreg,inference,report \
+    --gpu 0 --output-root /output
+
+# Combined: DWI first, then PWI (the DWI brain mask is copied into PWI when missing)
+ads combined --dwi-subject-path assets/examples/dwi/sub-02e8eb42 \
+    --pwi-subject-path assets/examples/pwi/sub-02e8eb42 --all --gpu 0
+ads combined --dwi-subject-path D --pwi-subject-path P \
+    --dwi-stages prepdata,gen_mask,skull_strip,registration,inference,report \
+    --pwi-stages prepdata,gen_mask,skull_strip,gen_ttp,registration,ttpadc_coreg,inference,report \
+    --gpu 0 --output-root /data/openads_output
+
+# One stage on an existing output folder
+ads stages run gen_mask --modality dwi --subject-id sub-02e8eb42 --output-root out --gpu 0
+
+# Inspect
+ads stages list dwi          # stages and the methods available for DWI (--json for tools)
+ads pwi --subject-path DIR --all --dry-run   # print stages and output folder as JSON, run nothing
+ads config show pwi          # the merged configuration (packaged defaults + --config + --set)
+```
+
+Configuration is layered: packaged defaults < `--config my.yaml` <
+`--set key=value` (repeatable, value parsed as YAML), for example
+`--set stages.report.enabled=false` or `--set runtime.device=cuda:1`.
+`--gpu N` sets `CUDA_VISIBLE_DEVICES`; `--gpu cpu` hides all GPUs, and the
+default `runtime.device: auto` then runs on the CPU (it logs the choice; an
+explicit `--set runtime.device=cuda` fails instead). See [`docs/configuration.md`](docs/configuration.md).
+
+Pass one subject folder to `--subject-path`, not a dataset root. The subject
+folder holds files such as `<id>_DWI.nii.gz`, `<id>_b0.nii.gz`, `<id>_ADC.nii.gz`,
+`<id>_stroke.nii.gz` (DWI) and additionally `<id>_PWI.nii.gz`, `<id>_PWI.json`,
+`<id>_HP_manual.nii.gz` (PWI). A missing ADC is computed from DWI and b0; a
+4D DWI is split into b0 and DWI ([`docs/user_guide.md`](docs/user_guide.md)).
+
+## Python API quick start
+
+`import openads` is light (no torch, ANTs or pandas). Heavy libraries load when a
+stage runs. The examples use the full name; `import openads as ads` works the same way.
+
+```python
+import openads
+from openads.models.device import set_visible_gpus
+
+set_visible_gpus("0")  # like --gpu 0; call before anything initialises CUDA
+result = openads.run_dwi("assets/examples/dwi/sub-02e8eb42", all_stages=True, output_root="out")
+print(result.workspace.modality_root)         # out/sub-02e8eb42/DWI
+print(sorted(result.results))                 # stage name -> StageResult
+```
+
+Plan a run without running it, and find the bundled example subjects:
+
+```python
+plan = openads.get_pipeline("dwi").plan("assets/examples/dwi/sub-02e8eb42", output_root="out")
+print(plan.output.subject_root)               # out/sub-02e8eb42 (where run() writes)
+print([p.name for p in openads.example_subjects("dwi")])  # ['sub-02e8eb42']
+```
+
+Configuration objects and overrides:
+
+```python
+cfg = openads.load_config(pipeline="dwi", overrides=["stages.report.enabled=false"])
+print(cfg.stage("gen_mask").method)           # synthstrip
+print(cfg.stage("report").enabled)            # False
+```
+
+Run one stage on an existing output folder (its inputs must already be there):
+
+```python
+res = openads.run_stage("gen_mask", subject_id="sub-02e8eb42", modality="DWI", output_root="out")
+print(res.produced["preprocess.brain_mask"])  # out/sub-02e8eb42/DWI/preprocess/sub-02e8eb42_DWIbrain-mask.nii.gz
+```
+
+The numerics are plain functions on arrays in `openads.ops`:
+
+```python
+import numpy as np
+from openads.ops.adc import compute_adc
+
+dwi = np.full((4, 4, 4), 400.0)
+b0 = np.full((4, 4, 4), 1000.0)
+adc = compute_adc(dwi, b0, bvalue=1000.0)     # float32, -ln(dwi/b0)/b
+print(round(float(adc[0, 0, 0]), 6))           # 0.000916
+```
+
+Add your own method (here a brain-mask method) in one file and select it by
+configuration. See [`docs/extending.md`](docs/extending.md) for plugins and new
+stages.
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+
+from openads.registry import register
+from openads.stages import StageContext
+
+
+@dataclass(frozen=True)
+class ThresholdParams:
+    level: float = 50.0
+
+
+@register("gen_mask", "threshold", params=ThresholdParams)
+def threshold(ctx: StageContext) -> dict[str, Path]:
+    """Toy brain mask: DWI > level."""
+    img = nib.load(ctx.ws.path("preprocess.dwi"))
+    mask = (np.asarray(img.dataobj) > ctx.params.level).astype(np.uint8)
+    out = ctx.ws.path("preprocess.brain_mask")
+    nib.save(nib.Nifti1Image(mask, img.affine), out)
+    return {"preprocess.brain_mask": out}
+
+
+res = openads.run_stage(
+    "gen_mask", subject_id="sub-02e8eb42", modality="DWI", output_root="out",
+    method="threshold", overrides=["stages.gen_mask.params.level=55"],
+)
+print(res.method)                             # threshold
+```
+
+## Output tree
+
+```
+out/sub-02e8eb42
+├── DWI
+│   ├── preprocess     DWI, B0, ADC (+ _brain), DWIbrain-mask, stroke
+│   ├── registration   *_space-MNI152_aff[_desc-norm], *_affsyn, transforms (.mat, warps), manifest
+│   ├── segment        stroke-mask (native), _space-MNI152, _space-MNI152_affsyn, metrics.json
+│   └── reporting      *_QFV.csv, *_lesionload.csv, automatic_radiological_report.txt,
+│                      *_report_interpretation.pdf, DWIstroke*.png
+└── PWI
+    ├── preprocess     PWI, PWI.json, PWI_STC, PWI_average, TTP, masks, *_PWI_moco_aff/*.mat
+    ├── registration   TTP/HP_manual in DWI and MNI space, coregistration transforms
+    ├── segmentation   HP-mask (native), _space-MNI152[_affsyn|_desc-postproc], metrics.json
+    └── reporting      *_HPQFV.csv, *_HPload.csv, automatic_radiological_report.txt, HP*.png
+```
+
+A PWI run after a DWI run of the same subject reuses the DWI registration. The
+file names are defined in one table (`openads.core.layout`); cleanup keeps exactly
+the files of this tree.
+
+## GUI / server / Docker
+
+Thin clients in [`apps/`](apps/) build `ads ...` command lines (stages from
+`openads.get_pipeline(...).stage_names`) and run them as subprocesses. They are not
+in the wheel: run them from a source checkout with the extras installed.
+
+```bash
+pip install -e ".[server,gui]"
+python -m apps.server --host 0.0.0.0 --port 8000   # web pages + API on :8000 (apps/web)
+python -m apps.gui                                 # PyQt5 launcher (1.0 GUI_launcher.py)
+scripts/run_dwi.sh SUBJECT --all --gpu 0 --dry-run # 1.0 wrappers: print or run `ads ...`
+```
+
+The server keeps the 1.0 endpoints (`/api/run` streams the log,
+`/api/outputs`, `/api/download`, `/api/download-all`, `/api/upload-subject`,
+`/api/example-subjects`) and adds `/api/stages` and a job API
+(`/api/jobs`, `/api/jobs/{id}`, `/api/jobs/{id}/log`, `/api/jobs/{id}/stream`).
+Docker images (GPU and CPU) and their entrypoint: [`docker/README.md`](docker/README.md).
+
+## Documentation
+
+- [`docs/user_guide.md`](docs/user_guide.md): inputs, stages, outputs, GPU, troubleshooting.
+- [`docs/configuration.md`](docs/configuration.md): every configuration key and default.
+- [`docs/extending.md`](docs/extending.md): new methods, plugins, new stages, `openads.steps`.
+- [`docs/architecture.md`](docs/architecture.md): layers, the data-import design, design decisions.
+- [`docs/refactor/`](docs/refactor/): the 1.0 -> 2.0 refactor records (mapping,
+  ADRs, regression harness, API catalogue).
+- [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+JHU Non-Profit Research Software License (see [`LICENSE`](LICENSE)): non-profit
+research use only; commercial use needs a separate license from Johns Hopkins
+University.