From 3aeb70d42b9620c2fc95c22ac74dd65017207a27 Mon Sep 17 00:00:00 2001 From: Youssef Assis Date: Tue, 29 Sep 2026 20:44:49 +0200 Subject: [PATCH 1/4] [FEAT] Install the pipeline steps as commands The scripts and their configs only worked from a clone. They now live in the package (deepaneseg/cli, deepaneseg/configs) and are installed as commands: deepaneseg-remove-skull, -extract-points, -preprocess, -train, -predict and -evaluate. `pip install git+` is enough to run them from any folder. configs/ is a package so that Hydra finds it once installed. Existing tests now run the modules instead of the script paths; the Docker image and CI use the commands. --- .github/workflows/ci.yml | 2 +- Dockerfile | 2 +- deepaneseg/cli/__init__.py | 0 {scripts => deepaneseg/cli}/evaluate.py | 5 ++--- {scripts => deepaneseg/cli}/extract_points.py | 3 +-- {scripts => deepaneseg/cli}/predict.py | 7 +++---- .../cli/preprocess.py | 5 ++--- {scripts => deepaneseg/cli}/remove_skull.py | 5 ++--- {scripts => deepaneseg/cli}/train.py | 5 ++--- deepaneseg/configs/__init__.py | 1 + .../configs}/augmentation/default.yaml | 0 {configs => deepaneseg/configs}/data/default.yaml | 4 ++-- {configs => deepaneseg/configs}/evaluate.yaml | 4 ++-- .../configs}/extract_points.yaml | 0 {configs => deepaneseg/configs}/model/unet3d.yaml | 0 .../configs}/optimizer/adam.yaml | 0 {configs => deepaneseg/configs}/predict.yaml | 4 ++-- {configs => deepaneseg/configs}/preprocess.yaml | 0 {configs => deepaneseg/configs}/remove_skull.yaml | 0 .../configs}/scheduler/reduce_lr_on_plateau.yaml | 0 {configs => deepaneseg/configs}/train.yaml | 0 pyproject.toml | 11 +++++++++++ tests/test_config.py | 2 +- tests/test_evaluate.py | 7 ++----- tests/test_predict_scans.py | 4 ++-- tests/test_reproducibility.py | 4 +--- tests/test_scripts.py | 15 +++++++-------- 27 files changed, 45 insertions(+), 45 deletions(-) create mode 100644 deepaneseg/cli/__init__.py rename {scripts => deepaneseg/cli}/evaluate.py (94%) rename {scripts => deepaneseg/cli}/extract_points.py (81%) rename {scripts => deepaneseg/cli}/predict.py (91%) rename scripts/preprocess_data.py => deepaneseg/cli/preprocess.py (85%) rename {scripts => deepaneseg/cli}/remove_skull.py (87%) rename {scripts => deepaneseg/cli}/train.py (94%) create mode 100644 deepaneseg/configs/__init__.py rename {configs => deepaneseg/configs}/augmentation/default.yaml (100%) rename {configs => deepaneseg/configs}/data/default.yaml (77%) rename {configs => deepaneseg/configs}/evaluate.yaml (87%) rename {configs => deepaneseg/configs}/extract_points.yaml (100%) rename {configs => deepaneseg/configs}/model/unet3d.yaml (100%) rename {configs => deepaneseg/configs}/optimizer/adam.yaml (100%) rename {configs => deepaneseg/configs}/predict.yaml (87%) rename {configs => deepaneseg/configs}/preprocess.yaml (100%) rename {configs => deepaneseg/configs}/remove_skull.yaml (100%) rename {configs => deepaneseg/configs}/scheduler/reduce_lr_on_plateau.yaml (100%) rename {configs => deepaneseg/configs}/train.yaml (100%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a3ed70e..9e72847 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,4 +35,4 @@ jobs: - name: Smoke test run: | docker run --rm deepaneseg:cpu python -c "import torch, deepaneseg.utils; print(torch.__version__)" - docker run --rm deepaneseg:cpu python scripts/train.py --help + docker run --rm deepaneseg:cpu deepaneseg-train --help diff --git a/Dockerfile b/Dockerfile index 5a05243..427424a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -21,4 +21,4 @@ RUN uv sync --locked --no-install-project --no-dev --extra ${TORCH} && rm -rf /r COPY . . RUN uv sync --locked --no-dev --extra ${TORCH} && rm -rf /root/.cache/uv -CMD ["python", "scripts/train.py", "--help"] +CMD ["deepaneseg-train", "--help"] diff --git a/deepaneseg/cli/__init__.py b/deepaneseg/cli/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/scripts/evaluate.py b/deepaneseg/cli/evaluate.py similarity index 94% rename from scripts/evaluate.py rename to deepaneseg/cli/evaluate.py index 1168e42..d845995 100644 --- a/scripts/evaluate.py +++ b/deepaneseg/cli/evaluate.py @@ -1,7 +1,6 @@ -#!/usr/bin/env python3 -"""Score a training's predictions on its test patients; configuration in configs/evaluate.yaml. +"""Score a training's predictions on its test patients; configuration in deepaneseg/configs/evaluate.yaml. -Example: python scripts/evaluate.py train_dir=/data/0Work/exp1 +Example: deepaneseg-evaluate train_dir=/data/0Work/exp1 A detection (connected component above the threshold) is a true positive when its center lies within an aneurysm's radius (ADAM challenge criteria). Writes per_patient.csv and summary.json to /evaluation. """ diff --git a/scripts/extract_points.py b/deepaneseg/cli/extract_points.py similarity index 81% rename from scripts/extract_points.py rename to deepaneseg/cli/extract_points.py index 571e5ba..b08eef4 100644 --- a/scripts/extract_points.py +++ b/deepaneseg/cli/extract_points.py @@ -1,7 +1,6 @@ -#!/usr/bin/env python3 """Select negative patch centers (on vessels and in the parenchyma) for every patient. -Configuration in configs/extract_points.yaml. Example: python scripts/extract_points.py data_dir=/data +Configuration in deepaneseg/configs/extract_points.yaml. Example: deepaneseg-extract-points data_dir=/data Writes (CSV) and its 3D Slicer .fcsv counterpart in each patient folder. Requires the 'noskull volume' produced by remove_skull.py. """ diff --git a/scripts/predict.py b/deepaneseg/cli/predict.py similarity index 91% rename from scripts/predict.py rename to deepaneseg/cli/predict.py index 30d952f..ed5bf67 100755 --- a/scripts/predict.py +++ b/deepaneseg/cli/predict.py @@ -1,9 +1,8 @@ -#!/usr/bin/env python3 -"""Predict with a trained model; configuration in configs/predict.yaml. +"""Predict with a trained model; configuration in deepaneseg/configs/predict.yaml. Examples: - python scripts/predict.py train_dir=/data/0Work/exp1 # test patients of the split - python scripts/predict.py train_dir=/data/0Work/exp1 input=scan.nii.gz # any scan, or a folder of scans + deepaneseg-predict train_dir=/data/0Work/exp1 # test patients of the split + deepaneseg-predict train_dir=/data/0Work/exp1 input=scan.nii.gz # any scan, or a folder of scans Data and model settings come from the training's resolved configuration (/.hydra/config.yaml). For each case, writes the probability map .nii.gz and the detections _detections.csv (and .fcsv, for 3D Slicer). diff --git a/scripts/preprocess_data.py b/deepaneseg/cli/preprocess.py similarity index 85% rename from scripts/preprocess_data.py rename to deepaneseg/cli/preprocess.py index 42d3347..d4c2a78 100644 --- a/scripts/preprocess_data.py +++ b/deepaneseg/cli/preprocess.py @@ -1,7 +1,6 @@ -#!/usr/bin/env python3 -"""Split the patients into training/validation/testing sets; configuration in configs/preprocess.yaml. +"""Split the patients into training/validation/testing sets; configuration in deepaneseg/configs/preprocess.yaml. -Example: python scripts/preprocess_data.py data_dir=/data split=[0.7,0.2,0.1] +Example: deepaneseg-preprocess data_dir=/data split=[0.7,0.2,0.1] Writes the split to data.split_file (/0Work/split_pats.json by default). """ diff --git a/scripts/remove_skull.py b/deepaneseg/cli/remove_skull.py similarity index 87% rename from scripts/remove_skull.py rename to deepaneseg/cli/remove_skull.py index 2a04a68..8753243 100644 --- a/scripts/remove_skull.py +++ b/deepaneseg/cli/remove_skull.py @@ -1,7 +1,6 @@ -#!/usr/bin/env python3 -"""Skull-strip every patient volume; configuration in configs/remove_skull.yaml. +"""Skull-strip every patient volume; configuration in deepaneseg/configs/remove_skull.yaml. -Example: python scripts/remove_skull.py data_dir=/data +Example: deepaneseg-remove-skull data_dir=/data The result is saved next to each volume and registered as 'noskull volume' in the patient's config.json. """ diff --git a/scripts/train.py b/deepaneseg/cli/train.py similarity index 94% rename from scripts/train.py rename to deepaneseg/cli/train.py index 7c08457..53c5cc1 100755 --- a/scripts/train.py +++ b/deepaneseg/cli/train.py @@ -1,7 +1,6 @@ -#!/usr/bin/env python3 -"""Train a model; configuration in configs/train.yaml. +"""Train a model; configuration in deepaneseg/configs/train.yaml. -Example: python scripts/train.py data_dir=/data name=exp1 batch_size=8 +Example: deepaneseg-train data_dir=/data name=exp1 batch_size=8 Checkpoints, TensorBoard logs and the resolved configuration (.hydra/) are written to /0Work/. Running the same command again resumes from the last checkpoint. """ diff --git a/deepaneseg/configs/__init__.py b/deepaneseg/configs/__init__.py new file mode 100644 index 0000000..bf4c8be --- /dev/null +++ b/deepaneseg/configs/__init__.py @@ -0,0 +1 @@ +"""Hydra configuration of the deepaneseg commands (a package so that installed commands find it).""" diff --git a/configs/augmentation/default.yaml b/deepaneseg/configs/augmentation/default.yaml similarity index 100% rename from configs/augmentation/default.yaml rename to deepaneseg/configs/augmentation/default.yaml diff --git a/configs/data/default.yaml b/deepaneseg/configs/data/default.yaml similarity index 77% rename from configs/data/default.yaml rename to deepaneseg/configs/data/default.yaml index 6dfcec3..5a33f7b 100644 --- a/configs/data/default.yaml +++ b/deepaneseg/configs/data/default.yaml @@ -1,9 +1,9 @@ # Patient data and patch geometry data_dir: ${data_dir} # directory containing the patient folders (P????) work_dir: ${.data_dir}/0Work # split file and trainings are written here -split_file: ${.work_dir}/split_pats.json # written by preprocess_data.py +split_file: ${.work_dir}/split_pats.json # written by deepaneseg-preprocess volume: init volume # key, in each patient's config.json, of the volume to train on normalize: Linear # Linear (rescale to [0, 1]), Normal (zero mean, unit variance) or null -negative_patch_centers: points.csv # written by extract_points.py in each patient folder +negative_patch_centers: points.csv # written by deepaneseg-extract-points in each patient folder patch_shape: [48, 48, 48] # patch dimension, in voxels patch_size: [38, 38, 38] # patch size, in mm (resolution = patch_size / patch_shape) diff --git a/configs/evaluate.yaml b/deepaneseg/configs/evaluate.yaml similarity index 87% rename from configs/evaluate.yaml rename to deepaneseg/configs/evaluate.yaml index 42d6a45..b5b32aa 100644 --- a/configs/evaluate.yaml +++ b/deepaneseg/configs/evaluate.yaml @@ -1,6 +1,6 @@ # Detection metrics (ADAM challenge criteria) of a training's predictions on its test patients -train_dir: ??? # training directory written by train.py -predictions: ${train_dir}/prediction/test # .nii.gz probability maps written by predict.py +train_dir: ??? # training directory written by deepaneseg-train +predictions: ${train_dir}/prediction/test # .nii.gz probability maps written by deepaneseg-predict threshold: 0.5 # probability above which a voxel belongs to a detection min_size: null # detections smaller than this, in voxels, are ignored; null keeps all diff --git a/configs/extract_points.yaml b/deepaneseg/configs/extract_points.yaml similarity index 100% rename from configs/extract_points.yaml rename to deepaneseg/configs/extract_points.yaml diff --git a/configs/model/unet3d.yaml b/deepaneseg/configs/model/unet3d.yaml similarity index 100% rename from configs/model/unet3d.yaml rename to deepaneseg/configs/model/unet3d.yaml diff --git a/configs/optimizer/adam.yaml b/deepaneseg/configs/optimizer/adam.yaml similarity index 100% rename from configs/optimizer/adam.yaml rename to deepaneseg/configs/optimizer/adam.yaml diff --git a/configs/predict.yaml b/deepaneseg/configs/predict.yaml similarity index 87% rename from configs/predict.yaml rename to deepaneseg/configs/predict.yaml index 422bc3a..26f0156 100644 --- a/configs/predict.yaml +++ b/deepaneseg/configs/predict.yaml @@ -1,10 +1,10 @@ # Predicts with a trained model; data and model settings are read from the training's config -train_dir: ??? # training directory written by train.py +train_dir: ??? # training directory written by deepaneseg-train input: null # NIfTI scan or folder of scans; null: the test patients of the training's split output_dir: null # null: /prediction/test, or /prediction/scans for input checkpoint: last_checkpoint.pytorch volume: noskull volume # key, in each patient's config.json, of the volume to predict on -skull_strip: true # skull-strip input scans as remove_skull.py does, to match volume above +skull_strip: true # skull-strip input scans as deepaneseg-remove-skull does, to match volume above threshold: 0.5 # detections: connected components above this probability min_size: null # detections smaller than this, in voxels, are ignored; null keeps all margin: 8 # voxels discarded at each patch border when stitching predictions diff --git a/configs/preprocess.yaml b/deepaneseg/configs/preprocess.yaml similarity index 100% rename from configs/preprocess.yaml rename to deepaneseg/configs/preprocess.yaml diff --git a/configs/remove_skull.yaml b/deepaneseg/configs/remove_skull.yaml similarity index 100% rename from configs/remove_skull.yaml rename to deepaneseg/configs/remove_skull.yaml diff --git a/configs/scheduler/reduce_lr_on_plateau.yaml b/deepaneseg/configs/scheduler/reduce_lr_on_plateau.yaml similarity index 100% rename from configs/scheduler/reduce_lr_on_plateau.yaml rename to deepaneseg/configs/scheduler/reduce_lr_on_plateau.yaml diff --git a/configs/train.yaml b/deepaneseg/configs/train.yaml similarity index 100% rename from configs/train.yaml rename to deepaneseg/configs/train.yaml diff --git a/pyproject.toml b/pyproject.toml index c921302..e480777 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,6 +24,14 @@ dependencies = [ "hydra-core>=1.3", ] +[project.scripts] +deepaneseg-remove-skull = "deepaneseg.cli.remove_skull:main" +deepaneseg-extract-points = "deepaneseg.cli.extract_points:main" +deepaneseg-preprocess = "deepaneseg.cli.preprocess:main" +deepaneseg-train = "deepaneseg.cli.train:main" +deepaneseg-predict = "deepaneseg.cli.predict:main" +deepaneseg-evaluate = "deepaneseg.cli.evaluate:main" + [project.optional-dependencies] # PyTorch build, for uv: `uv sync --extra cpu` or `uv sync --extra cu126` (see [tool.uv.sources]) cpu = ["torch"] @@ -54,6 +62,9 @@ explicit = true [tool.setuptools.packages.find] include = ["deepaneseg*"] +[tool.setuptools.package-data] +deepaneseg = ["configs/*.yaml", "configs/*/*.yaml"] + [tool.pytest.ini_options] testpaths = ["tests"] diff --git a/tests/test_config.py b/tests/test_config.py index 4408ed4..8d44417 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -11,7 +11,7 @@ from deepaneseg.training.trainer import create_trainer from deepaneseg.utils import get_model -CONFIG_DIR = str(Path(__file__).parents[1] / "configs") +CONFIG_DIR = str(Path(__file__).parents[1] / "deepaneseg" / "configs") def compose_config(name, overrides): diff --git a/tests/test_evaluate.py b/tests/test_evaluate.py index 41733f5..85a930e 100644 --- a/tests/test_evaluate.py +++ b/tests/test_evaluate.py @@ -1,7 +1,6 @@ import json import subprocess import sys -from pathlib import Path import nibabel as ni import numpy as np @@ -12,8 +11,6 @@ from deepaneseg.data.io import read_aneurysm_spheres from deepaneseg.inference.evaluation import summarize_detections -SCRIPTS = Path(__file__).parents[1] / "scripts" - def make_patient(data_dir, name, aneurysm_points=None): patient = data_dir / name @@ -66,7 +63,7 @@ def test_evaluate_script_scores_the_test_predictions(tmp_path): ni.save(ni.Nifti1Image(np.full((20, 20, 20), 0.1), np.eye(4)), predictions / "P0002.nii.gz") result = subprocess.run( - [sys.executable, str(SCRIPTS / "evaluate.py"), f"train_dir={train_dir}"], capture_output=True, text=True + [sys.executable, "-m", "deepaneseg.cli.evaluate", f"train_dir={train_dir}"], capture_output=True, text=True ) assert result.returncode == 0, result.stderr[-2000:] @@ -87,7 +84,7 @@ def test_evaluate_script_reports_missing_predictions(tmp_path): ) result = subprocess.run( - [sys.executable, str(SCRIPTS / "evaluate.py"), f"train_dir={train_dir}"], capture_output=True, text=True + [sys.executable, "-m", "deepaneseg.cli.evaluate", f"train_dir={train_dir}"], capture_output=True, text=True ) assert result.returncode != 0 and "P0001" in result.stderr diff --git a/tests/test_predict_scans.py b/tests/test_predict_scans.py index a6e7e5c..59983aa 100644 --- a/tests/test_predict_scans.py +++ b/tests/test_predict_scans.py @@ -47,7 +47,7 @@ def test_save_detections_writes_csv_and_slicer_markups(tmp_path): @pytest.fixture def trained(tmp_path): """A tiny untrained model with its saved training configuration.""" - with initialize_config_dir(config_dir=str(ROOT / "configs"), version_base="1.3"): + with initialize_config_dir(config_dir=str(ROOT / "deepaneseg" / "configs"), version_base="1.3"): cfg = compose( "train", [ @@ -67,7 +67,7 @@ def trained(tmp_path): def predict(*args): return subprocess.run( - [sys.executable, str(ROOT / "scripts" / "predict.py"), *map(str, args)], capture_output=True, text=True + [sys.executable, "-m", "deepaneseg.cli.predict", *map(str, args)], capture_output=True, text=True ) diff --git a/tests/test_reproducibility.py b/tests/test_reproducibility.py index 61e2ebc..06ba285 100644 --- a/tests/test_reproducibility.py +++ b/tests/test_reproducibility.py @@ -14,8 +14,6 @@ from deepaneseg.data.io import fetch_patient_dirs from deepaneseg.utils import run_info, seed_everything -SCRIPTS = Path(__file__).parents[1] / "scripts" - def test_split_depends_only_on_the_seed(): patients = [f"P{i:04d}" for i in range(20)] @@ -89,7 +87,7 @@ def train(name): "data.patch_size=[16,16,16]", "augmentation.positive.duplicates=2", ] - result = subprocess.run([sys.executable, str(SCRIPTS / "train.py"), *args], capture_output=True, text=True) + result = subprocess.run([sys.executable, "-m", "deepaneseg.cli.train", *args], capture_output=True, text=True) assert result.returncode == 0, result.stderr[-2000:] return torch.load(tmp_path / "0Work" / name / "last_checkpoint.pytorch")["model_state_dict"] diff --git a/tests/test_scripts.py b/tests/test_scripts.py index c701ed6..b243e26 100644 --- a/tests/test_scripts.py +++ b/tests/test_scripts.py @@ -1,13 +1,12 @@ import json import subprocess import sys -from pathlib import Path -SCRIPTS = Path(__file__).parents[1] / "scripts" - -def run(script, *args): - return subprocess.run([sys.executable, str(SCRIPTS / script), *map(str, args)], capture_output=True, text=True) +def run(command, *args): + return subprocess.run( + [sys.executable, "-m", f"deepaneseg.cli.{command}", *map(str, args)], capture_output=True, text=True + ) def make_patients(data_dir, n): @@ -19,8 +18,8 @@ def make_patients(data_dir, n): def test_preprocess_data_splits_patients_and_refuses_to_overwrite(tmp_path): make_patients(tmp_path, 10) - first = run("preprocess_data.py", f"data_dir={tmp_path}") - second = run("preprocess_data.py", f"data_dir={tmp_path}") + first = run("preprocess", f"data_dir={tmp_path}") + second = run("preprocess", f"data_dir={tmp_path}") assert first.returncode == 0, first.stderr split = json.loads((tmp_path / "0Work" / "split_pats.json").read_text()) @@ -29,6 +28,6 @@ def test_preprocess_data_splits_patients_and_refuses_to_overwrite(tmp_path): def test_train_requires_data_dir_and_name(): - result = run("train.py") + result = run("train") assert result.returncode != 0 and "Missing mandatory value" in result.stderr From 09f34b208f537b41ae4b5d5b52f86c248aabcb81 Mon Sep 17 00:00:00 2001 From: Youssef Assis Date: Tue, 29 Sep 2026 20:45:19 +0200 Subject: [PATCH 2/4] [TEST] Check the installed commands and their packaged configs --- tests/test_cli.py | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 tests/test_cli.py diff --git a/tests/test_cli.py b/tests/test_cli.py new file mode 100644 index 0000000..62faa05 --- /dev/null +++ b/tests/test_cli.py @@ -0,0 +1,36 @@ +"""The installed commands and the configs they read.""" + +import shutil +import subprocess +from importlib.metadata import entry_points +from importlib.resources import files + +import pytest + +COMMANDS = { + "deepaneseg-remove-skull": "remove_skull", + "deepaneseg-extract-points": "extract_points", + "deepaneseg-preprocess": "preprocess", + "deepaneseg-train": "train", + "deepaneseg-predict": "predict", + "deepaneseg-evaluate": "evaluate", +} + + +def test_every_command_is_installed(): + installed = {ep.name: ep for ep in entry_points(group="console_scripts") if ep.name.startswith("deepaneseg-")} + + assert set(installed) == set(COMMANDS) + assert all(callable(ep.load()) for ep in installed.values()) + + +@pytest.mark.parametrize("config", sorted(set(COMMANDS.values()))) +def test_every_command_has_its_config_in_the_package(config): + assert (files("deepaneseg.configs") / f"{config}.yaml").is_file() + + +@pytest.mark.parametrize("command", ["deepaneseg-train", "deepaneseg-predict"]) +def test_commands_run_from_any_folder(command, tmp_path): + result = subprocess.run([shutil.which(command), "--help"], cwd=tmp_path, capture_output=True, text=True) + + assert result.returncode == 0 and "Configuration groups" in result.stdout From bef15322d99fa893a48a62c07e9eed500993c276 Mon Sep 17 00:00:00 2001 From: Youssef Assis Date: Tue, 29 Sep 2026 20:45:20 +0200 Subject: [PATCH 3/4] [CHORE] Check in CI that the built wheel runs outside the repository --- .github/workflows/ci.yml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e72847..de11514 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,6 +26,24 @@ jobs: - name: Test run: uv run pytest + wheel: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v10.2.0 + - name: Build and install the wheel outside the repository + run: | + uv build --wheel -o /tmp/dist + uv venv /tmp/venv + VIRTUAL_ENV=/tmp/venv uv pip install /tmp/dist/*.whl --extra-index-url https://download.pytorch.org/whl/cpu --index-strategy unsafe-best-match + - name: Run the commands from another folder + working-directory: /tmp + run: | + mkdir -p data/P0001 && echo '{}' > data/P0001/config.json + /tmp/venv/bin/deepaneseg-train --help + /tmp/venv/bin/deepaneseg-preprocess data_dir=data + test -f data/0Work/split_pats.json + docker: runs-on: ubuntu-latest steps: From 72a207ee6565b013bbd6d3a621f78d6934c0d618 Mon Sep 17 00:00:00 2001 From: Youssef Assis Date: Tue, 29 Sep 2026 20:45:40 +0200 Subject: [PATCH 4/4] [DOCS] Use the installed commands in the README --- README.md | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 2e6a625..b7b0fd2 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,9 @@ deepaneseg/ training/ dataset, losses, metrics, trainer inference/ patch-wise prediction and ADAM-style evaluation experimental/ post-paper models (vessel-coupled U-Nets) and their trainer -configs/ Hydra configuration (see Configuration) -scripts/ pipeline steps (see Usage) - experimental/ analysis scripts from the PhD experiments + cli/ pipeline commands (see Usage) + configs/ Hydra configuration (see Configuration) +scripts/experimental/ analysis scripts from the PhD experiments ``` The data is expected in the following layout: @@ -48,56 +48,57 @@ Data_dir/ ``` # Configuration -Settings are [Hydra](https://hydra.cc) configs in `configs/`: one file per script (`train.yaml`, `predict.yaml`, -`preprocess.yaml`, `remove_skull.yaml`, `extract_points.yaml`) composed from groups (`data`, `model`, `optimizer`, +Settings are [Hydra](https://hydra.cc) configs in `deepaneseg/configs/`: one file per command (`train.yaml`, +`predict.yaml`, `evaluate.yaml`, `preprocess.yaml`, `remove_skull.yaml`, `extract_points.yaml`) composed from groups (`data`, `model`, `optimizer`, `scheduler`, `augmentation`). Any value can be overridden on the command line: ``` -uv run python scripts/train.py data_dir=Data_dir name=my_training batch_size=8 optimizer.lr=3e-4 model.f_maps=32 -uv run python scripts/train.py --cfg job --resolve data_dir=Data_dir name=my_training # print the config +uv run deepaneseg-train data_dir=Data_dir name=my_training batch_size=8 optimizer.lr=3e-4 model.f_maps=32 +uv run deepaneseg-train --cfg job --resolve data_dir=Data_dir name=my_training # print the config ``` Runs are reproducible: `seed` (0 by default) fixes the patient split and the training, and each training writes `run_info.json` with the git commit and library versions next to its checkpoints. For identical GPU runs, also set `deterministic=true` (slower). To add an alternative (for example another scheduler), add a file to the group, such as -`configs/scheduler/step.yaml` with a `_target_` class, and select it with `scheduler=step`. +`deepaneseg/configs/scheduler/step.yaml` with a `_target_` class, and select it with `scheduler=step`. # Usage -Run every command from the repository root. +Run the commands with `uv run` from the repository folder, or directly (`deepaneseg-train …`) from any folder once +`.venv` is activated or the package is installed with pip. **1. Data preparation:** skull-strip the volumes, then select the negative patch centers. ``` -uv run python scripts/remove_skull.py data_dir=Data_dir -uv run python scripts/extract_points.py data_dir=Data_dir +uv run deepaneseg-remove-skull data_dir=Data_dir +uv run deepaneseg-extract-points data_dir=Data_dir ``` **2. Split:** assign the patients to training, validation and testing. ``` -uv run python scripts/preprocess_data.py data_dir=Data_dir # split=[0.7,0.2,0.1] overwrite=true +uv run deepaneseg-preprocess data_dir=Data_dir # split=[0.7,0.2,0.1] overwrite=true ``` **3. Training:** outputs go to `Data_dir/0Work/my_training`; running the same command again resumes training. The training and validation volumes are kept in memory as float32, about 4 bytes per voxel (150 MiB for a 512×512×150 scan). ``` -uv run python scripts/train.py data_dir=Data_dir name=my_training +uv run deepaneseg-train data_dir=Data_dir name=my_training ``` **4. Testing:** predictions of the test patients are written to `Data_dir/0Work/my_training/prediction/test`: a probability map per patient, and its detections (center and radius in mm, size, probability) as CSV and as `.fcsv` markups for 3D Slicer. ``` -uv run python scripts/predict.py train_dir=Data_dir/0Work/my_training +uv run deepaneseg-predict train_dir=Data_dir/0Work/my_training ``` Any other scan, or folder of scans, can be predicted the same way (skull-stripped first, like the training data): ``` -uv run python scripts/predict.py train_dir=Data_dir/0Work/my_training input=scan.nii.gz output_dir=results +uv run deepaneseg-predict train_dir=Data_dir/0Work/my_training input=scan.nii.gz output_dir=results ``` **5. Evaluation:** detection metrics of the test predictions (ADAM challenge criteria: sensitivity and false positives per patient), written to `Data_dir/0Work/my_training/evaluation`. ``` -uv run python scripts/evaluate.py train_dir=Data_dir/0Work/my_training # threshold=0.5 min_size=null +uv run deepaneseg-evaluate train_dir=Data_dir/0Work/my_training # threshold=0.5 min_size=null ``` # Differences from the published code @@ -111,7 +112,8 @@ uv sync --extra cu126 # NVIDIA GPU (CUDA 12.6) uv sync --extra cpu # CPU only (also the build used on macOS) ``` This creates `.venv` with the exact versions of `uv.lock`, including pytest and ruff. Commands then run with -`uv run`, e.g. `uv run pytest`. Without uv, `pip install -e .` also works (PyTorch's default PyPI build). +`uv run`, e.g. `uv run pytest`. Without uv, `pip install -e .` also works (PyTorch's default PyPI build), or, to only +use the commands, `pip install git+https://github.com/youssefassis/DeepAneSeg`. # Docker Build the image with the GPU (default) or CPU PyTorch build: @@ -122,9 +124,9 @@ docker build -t deepaneseg:cpu --build-arg TORCH=cpu . Mount the data folder and run any script; outputs are written under `Data_dir/0Work` on the host: ``` docker run --rm --gpus all --shm-size=8g -v /path/to/Data_dir:/data deepaneseg \ - python scripts/train.py data_dir=/data name=my_training + deepaneseg-train data_dir=/data name=my_training docker run --rm --gpus all --shm-size=8g -v /path/to/Data_dir:/data deepaneseg \ - python scripts/predict.py train_dir=/data/0Work/my_training + deepaneseg-predict train_dir=/data/0Work/my_training ``` GPU runs need the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/) on the host. `--shm-size` gives the data-loading workers enough shared memory, and `--user $(id -u):$(id -g)` creates the