Feat/vs pacs all regions

AGENTS.md

@@ -1,28 +1,38 @@
 # Repository Guidelines
 
-## nbdev workflow
+fastMONAI is an nbdev library: `nbs/` is exported to `fastMONAI/`. `research/` holds
+application projects written as plain Python and notebooks; nbdev does not export them.
 
-- Treat `nbs/*.ipynb` as the source of truth for nbdev-exported package code.
-- Do not edit generated `fastMONAI/*.py` modules directly.
-- After changing library notebooks, run `nbdev_prepare` from the repository root to regenerate modules and run checks.
+## Library (nbdev)
+
+- `nbs/*.ipynb` is the source of truth. Don't edit the generated `fastMONAI/*.py` modules.
+- After changing library notebooks, run `nbdev_prepare` from the repository root.
+- Clean only the notebooks you edited (`nbdev_clean --fname <notebook>`). A repo-wide clean
+  rewrites the tutorials' stored outputs.
+- `README.md` is generated from `nbs/index.ipynb`; edit the notebook, not the README.
+
+## Research projects
+
+- Each project has its own README; see `research/README.md`.
+- CI runs `python -m pytest -q research/vestibular_schwannoma/tests` from the repository root.
+  Without pytest, run the deployment tests from `research/`:
+  `python -m unittest discover -s vestibular_schwannoma/tests/deployment -t .`
+- Container release folders hold only the image archive, a short README and
+  `ror_select_entry.txt`. Don't write `.sha256` files.
+
+## Writing
+
+- Keep READMEs, comments and commit messages short and plain. Don't use em dashes.
+- Comments say what the code does. Which bug a change fixes belongs in the commit message.
 
 ## Commit messages
 
 - Use Conventional Commits: `<type>(<optional scope>): <summary>`, for example
   `fix(vs-pacs): publish pr2mask mask series`.
-- Types:
-  - `feat`: new functionality
-  - `fix`: bug fix
-  - `docs`: documentation only
-  - `test`: tests only
-  - `refactor`: code change without a behaviour change
-  - `perf`: performance improvement
-  - `build`: dependencies, packaging or Docker images
-  - `ci`: CI configuration
-  - `chore`: maintenance that fits none of the above, such as `.gitignore`
-- There is no `bug` or `minor` type: use `fix` for bugs, and `chore`, `docs` or
-  `refactor` for small changes.
+- Types: `feat`, `fix`, `docs`, `test`, `refactor` (no behaviour change), `perf`, `build`
+  (dependencies, packaging, Docker images), `ci` and `chore` (anything else, such as
+  `.gitignore`). There is no `bug` or `minor` type.
 - Mark breaking changes with `!` after the type (`feat!: ...`) and explain them in the body.
-- Write the summary in the imperative, lower case, without a trailing period and
-  under about 72 characters. Use the body to explain why.
+- Write the summary in the imperative, lower case, without a trailing period and under about
+  72 characters. Use the body to explain why.
 - Pull requests to `main` are squash-merged, so give the pull request title the same format.

research/README.md

@@ -1,15 +1,12 @@
-# Research 
+# Research
 
-## Shared deployment guidance
-
-Projects targeting the Research PACS should follow
-[Research PACS deployment with ROR](RESEARCH_PACS_DEPLOYMENT.md).
+Applications built with fastMONAI. Each project has its own README.
 
+| Project | Contents |
+| --- | --- |
+| [spine](spine/README.md) | Spine segmentation from T2w MRI: training, evaluation and inference. |
+| [endometrial_cancer](endometrial_cancer/README.md) | Endometrial cancer segmentation from VIBE, or from T2w, VIBE and ADC together. |
+| [vestibular_schwannoma](vestibular_schwannoma/README.md) | Vestibular schwannoma segmentation from CE-T1w MRI: five-fold cross-validation, inference and a Research PACS container. |
 
-## Table of contents
-| Notebook                                                                                                                                                                                                                               | 1-Click Notebook                                                                                                                                                                                   |
-|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [00-spine-segmentation-training-evaluation](https://nbviewer.org/github/MMIV-ML/fastMONAI/blob/main/research/spine/00-spine-segmentation-training-evaluation.ipynb) <br> Notebook to reproduce our test results and facilitate training on your own data. | [![Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MMIV-ML/fastMONAI/blob/main/research/spine/00-spine-segmentation-training-evaluation.ipynb)          |
-| [01-spine-segmentation-inference](https://nbviewer.org/github/MMIV-ML/fastMONAI/blob/main/research/spine/01-spine-segmentation-inference.ipynb) <br> Notebook that shows how to run inference on your own data with our trained models. | [![Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MMIV-ML/fastMONAI/blob/main/research/spine/01-spine-segmentation-inference.ipynb)          |
-| [02_ec_inference](https://nbviewer.org/github/MMIV-ML/fastMONAI/blob/main/research/endometrial_cancer/nbs/02_ec_inference.ipynb) <br> Notebook that shows how to run inference on your own data with our trained model. | [![Google Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MMIV-ML/fastMONAI/blob/main/research/endometrial_cancer/nbs/02_ec_inference.ipynb)          |
-| [vestibular_schwannoma](vestibular_schwannoma/README.md) <br> Five-fold cross-validation, inference and Research PACS deployment for vestibular schwannoma segmentation. | Local setup, see the project README |
+Projects that run in the Research PACS follow
+[Research PACS deployment with ROR](RESEARCH_PACS_DEPLOYMENT.md).

research/RESEARCH_PACS_DEPLOYMENT.md

@@ -204,13 +204,10 @@ docker tag "<CONTAINER_NAME>:$BUILD_VERSION" "<CONTAINER_NAME>:latest"
 
 ARCHIVE="<CONTAINER_NAME>-$BUILD_VERSION.tar.gz"
 docker save "<CONTAINER_NAME>:$BUILD_VERSION" "<CONTAINER_NAME>:latest" | gzip > "$ARCHIVE"
-
-sha256sum "$ARCHIVE" > "$ARCHIVE.sha256"
-sha256sum -c "$ARCHIVE.sha256"
 ```
 
-The SHA-256 detects archive corruption during transfer; it does not test the image. After
-`docker load`, either tag can be called. The dated tag is the stable release and rollback
+Don't write a `.sha256` file into the release folder. After `docker load`, the image ID
+confirms the right image arrived, and either tag can be called. The dated tag is the stable release and rollback
 identity; `latest` follows whichever archive was loaded or tagged last.
 
 ## 9. Research PACS Deployment
@@ -219,7 +216,7 @@ Register the qualified image and its DICOM selection criteria with the Research
 
 Provide the Research PACS administrator with:
 
-- the dated tag, `latest` alias, image ID or registry digest, and archive checksum;
+- the dated tag, `latest` alias, and image ID or registry digest;
 - the Git commit, ROR executable identity, and Fiona base image ID or digest;
 - the model-bundle names and hashes;
 - the bundle's DICOM schema;

research/endometrial_cancer/README.md

@@ -1,60 +1,35 @@
 # Endometrial cancer segmentation
-The primary objective of this repository is to reproduce the results reported in [Automated segmentation of endometrial cancer on MR images using deep learning](https://link.springer.com/content/pdf/10.1038/s41598-020-80068-9.pdf) and to integrate this model into research PACS (see [Results for VIBE](#results-for-vibe) section). 
-In addition, we have looked at improving the segmentation performance using multi-sequence MR images (T2w, VIBE, and ADC) (see [Results for multi-sequence (T2, VIBE, and ADC)](#results-for-multi-sequence-t2-vibe-and-adc) section).
-
-The trained weights and exported learner are available on [Hugging Face](https://huggingface.co/skaliy/endometrial_cancer_segmentation). 
-A Gradio app for VIBE is included in `src/app.py`. To run it on your local system, follow the instructions in the [Getting started](#getting-started) section.
-
-## Structure overview
-```
-├── figs
-│
-├── nbs            # Jupyter notebooks for training and inference
-│   ├── 01_ec_training.ipynb
-│   ├── 02_ec_inference.ipynb
-│   ├── 03_ec_training_multi.ipynb
-│   ├── 04_ec_inference_multi.ipynb
-│
-├── src                  
-│   ├── app.py               # Gradio app
-│   ├── inference_script.py     # Inference script for single-sequence 
-│   └── inference_script_multi.py  # Inference for multi-sequence 
-│
-└── README.md
-```        
-
-## Getting started
-1. Clone this repository:
-```bash
-git clone https://github.com/MMIV-ML/fastMONAI
-```
-2. Install fastMONAI by following the instructions provided [here](https://github.com/MMIV-ML/fastMONAI).
-3. (<b>Optional</b>) Run the `01_ec_training.ipynb` `03_ec_training_multi.ipynb` notebook to train your own model.
-4. Run the `02_ec_inference.ipynb`, `inference_script.py` or `app.py` to perform inference with the trained model for VIBE images.
-5. Run the `04_ec_inference_multi.ipynb` or `inference_script_multi.py` to perform inference with the trained model for T2w, VIBE, and ADC images.
-
-If you choose to use `inference_script.py` or `inference_script_multi.py`, please follow these steps:
-
-- Make the script executable using the following command in the terminal:
-```bash
-chmod +x inference_script.py
-```
-- Run the script by executing the following command in the terminal:
-```bash
-python inference_script.py IMG_PATH
-```
-
-If you choose to use `app.py`, install `gradio` and `opencv-python` (they are not fastMONAI dependencies) and execute the following command in the terminal:
-```bash
-gradio app.py
-```
-The predicted mask will be stored in folder `ec_pred` in the `src` folder. 
-
-## Results for VIBE
-Note that our results are not directly comparable with the results reported in [study](https://link.springer.com/content/pdf/10.1038/s41598-020-80068-9.pdf), as we opted to use the test set for validation to allocate more data to training. Unlike the approach detailed in the study, we refrained from post-processing steps, such as retaining only the largest object. Predictions from new test cases indicate that this method could occasionally eliminate the tumor. Below is the box plot showcasing predictions on the validation set:
+
+Reproduces [Automated segmentation of endometrial cancer on MR images using deep learning](https://link.springer.com/content/pdf/10.1038/s41598-020-80068-9.pdf)
+on VIBE images, and tests whether T2w, VIBE and ADC together improve the segmentation. The
+VIBE model runs in the research PACS. Trained weights and the exported learner are on
+[Hugging Face](https://huggingface.co/skaliy/endometrial_cancer_segmentation).
+
+## Contents
+
+- `nbs/01_ec_training.ipynb`, `nbs/03_ec_training_multi.ipynb`: train the VIBE and the
+  multi-sequence model.
+- `nbs/02_ec_inference.ipynb` ([Colab](https://colab.research.google.com/github/MMIV-ML/fastMONAI/blob/main/research/endometrial_cancer/nbs/02_ec_inference.ipynb)),
+  `nbs/04_ec_inference_multi.ipynb`: run the trained models on your own data.
+- `src/inference_script.py IMG_PATH`, `src/inference_script_multi.py`: command-line inference.
+- `src/app.py`: Gradio app for VIBE. Install `gradio` and `opencv-python` (not fastMONAI
+  dependencies) and run `gradio app.py`; predictions are written to `src/ec_pred`.
+
+Install fastMONAI as described in the [main README](../../README.md).
+
+## Results
+
+The test set was used for validation to leave more data for training, so the results are not
+directly comparable with the study. No post-processing is applied: keeping only the largest
+object sometimes removed the tumour in new cases. DSC columns: inter-rater, model vs rater 1,
+model vs rater 2.
+
+**VIBE**, median DSC 0.8946, 0.8212, 0.779:
+
 ![](figs/vibe_boxplot.png)
 
-The results from the validation set are also presented in the table below:
+<details>
+<summary>Per-case results (VIBE)</summary>
 
 |    |   subject_id |   tumor_vol |   inter_rater |    r1_ml |      r2_ml |   n_components |
 |---:|-------------:|------------:|--------------:|---------:|-----------:|---------------:|
@@ -90,16 +65,18 @@ The results from the validation set are also presented in the table below:
 | 29 |          531 |       22.08 |     0.89225   | 0.555066 | 0.505109   |              1 |
 | 30 |          540 |        8.35 |     0.923702  | 0.855009 | 0.840958   |              1 |
 
-<b>Median DSC</b>: 0.8946, 0.8212, 0.779
+</details>
+
+Prediction on a new subject in the research PACS:
 
-Prediction on a new subject in the research PACS: 
 ![](figs/research_pacs_predicition.png)
 
-## Results for multi-sequence (T2, VIBE, and ADC)
-The box plot of the predictions on the validation set: 
+**T2w, VIBE and ADC**, median DSC 0.8946, 0.8521, 0.8137:
+
 ![](figs/t2_vibe_adc_boxplot.png)
 
-The results from the validation set are also presented in the table below:
+<details>
+<summary>Per-case results (T2w, VIBE and ADC)</summary>
 
 |    |   subject_id |   tumor_vol |   inter_rater |    r1_ml |     r2_ml |   n_components |
 |---:|-------------:|------------:|--------------:|---------:|----------:|---------------:|
@@ -135,7 +112,9 @@ The results from the validation set are also presented in the table below:
 | 29 |          531 |       22.08 |     0.89225   | 0.349648 | 0.319533  |              1 |
 | 30 |          540 |        8.35 |     0.923702  | 0.890343 | 0.88052   |              1 |
 
-<b>Median DSC</b>: 0.8946, 0.8521, 0.8137
+</details>
+
+## Support
 
-## Support and Contribution
-For any issues related to the model or the source code, please open an issue in the corresponding GitHub repository. Contributions to the code or the model are welcome and should be proposed through a pull request.
+Open an issue for problems with the model or the code. Contributions are welcome as pull
+requests.

research/spine/README.md

@@ -1,30 +1,24 @@
-# Multi-Center CNN-based spine segmentation from T2w MRI using small amounts of data
-The source code, designed to reproduce our test results and facilitate training and running inference on your own data. 
-The trained weights and exported learners are available on [Hugging Face](https://huggingface.co/skaliy/spine-segmentation).
+# Multi-center CNN-based spine segmentation from T2w MRI using small amounts of data
 
-## Getting started
-### Quick Start
-You can run the notebooks directly in Google Colab.
+Code to reproduce our test results, train on your own data and run inference. Trained
+weights and exported learners are on [Hugging Face](https://huggingface.co/skaliy/spine-segmentation).
 
-### Local Setup (Optional)
-1. Clone this repository:
-```bash
-git clone https://github.com/MMIV-ML/fastMONAI
-```
-2. Install fastMONAI by following the instructions provided [here](https://github.com/MMIV-ML/fastMONAI/tree/main).
-3. (<b>Optional</b>) Run the `00-spine-segmentation-training-evaluation.ipynb` notebook to train your own model or to reproduce the test results reported in our paper.
-4. Run the `01-spine-segmentation-inference.ipynb` or `inference_script.py` to perform inference with the trained model on own data
+| Notebook | Colab |
+| --- | --- |
+| [00-spine-segmentation-training-evaluation](https://nbviewer.org/github/MMIV-ML/fastMONAI/blob/main/research/spine/00-spine-segmentation-training-evaluation.ipynb): reproduce the test results or train your own model | [Open](https://colab.research.google.com/github/MMIV-ML/fastMONAI/blob/main/research/spine/00-spine-segmentation-training-evaluation.ipynb) |
+| [01-spine-segmentation-inference](https://nbviewer.org/github/MMIV-ML/fastMONAI/blob/main/research/spine/01-spine-segmentation-inference.ipynb): run the trained model on your own data | [Open](https://colab.research.google.com/github/MMIV-ML/fastMONAI/blob/main/research/spine/01-spine-segmentation-inference.ipynb) |
+
+## Local setup
+
+Clone this repository and [install fastMONAI](../../README.md). Then run the notebooks, or
+run inference from the command line:
 
-If you choose to use `inference_script.py`
-- Make the script executable using the following command in the terminal:
-```bash
-chmod +x inference_script.py
-```
-- Run the script by executing the following command in the terminal:
 ```bash
 python inference_script.py IMG_PATH
 ```
 
-## Research PACS 
-Our spine segmentation application deployed in the research PACS system at our hospital: 
+## Research PACS
+
+The model runs in the research PACS at our hospital:
+
 ![](figs/research_pacs.png)