Configuration

.devcontainer/devcontainer.json

@@ -0,0 +1,28 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
+{
+	"name": "Local Development",
+	"build": {
+		// Sets the run context to one level up instead of the .devcontainer folder.
+		"context": "..",
+		// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
+		"dockerfile": "../docker/development.Dockerfile"
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Uncomment the next line to run commands after the container is created.
+	"postCreateCommand": "poetry install",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as an existing user other than the container default. More info: https://aka.ms/dev-containers-non-root.
+	"mounts": [
+		"source=${localWorkspaceFolder},target=/project,type=bind,consistency=cached"
+	]
+}

.github/workflows/CI.yaml

@@ -32,6 +32,25 @@ jobs:
         with:
           pytest-xml-coverage-path: ./coverage.xml
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: cardinalby/export-env-action@v2
+        id: cicd_env
+        with:
+          envFile: 'github.env'
+          expand: 'true'
+      - uses: actions/setup-python@v2
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - uses: abatilo/[email protected]
+        with:
+          poetry-version: ${{ env.POETRY_VERSION }}
+      - run: poetry install --no-interaction
+      - name: Build docs
+        run: poetry run mkdocs build
+
 #  build:
 #    runs-on: ubuntu-latest
 #    steps:

.readthedocs.yaml

@@ -9,6 +9,13 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.8"
+  jobs:
+    post_create_environment:
+      - pip install poetry==1.1.11
+    post_install:
+      # TODO: Change to docs group after poetry upgrade
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install 
+
 
 mkdocs:
   configuration: mkdocs.yml

docker/development.Dockerfile

@@ -0,0 +1,20 @@
+FROM ubuntu:20.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update --yes && \
+    apt-get install -y python3-pip
+
+ENV POETRY_VERSION=1.1.11
+RUN pip3 install --upgrade pip && pip3 install "poetry==$POETRY_VERSION"
+
+
+RUN mkdir /src
+WORKDIR /src
+
+RUN poetry config virtualenvs.create false
+
+# Install dependencies (cached)
+COPY pyproject.toml poetry.lock ./
+RUN poetry install
+
+CMD ["/bin/bash"]

docs/index.md

@@ -2,12 +2,57 @@
 
 PD-DWI is a physiologically-decomposed Diffusion-Weighted MRI machine-learning model for predicting response to neoadjuvant chemotherapy in invasive breast cancer.
 
-PD-DWI was developed by [TCML](https://tcml-bme.github.io/) group as part of [BMMR2 challenge](https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=89096426) using [ACRIN-6698](https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=50135447) dataset.
+PD-DWI was developed by [TCML](https://tcml-bme.github.io/) group. 
+
+<figure markdown="span">
+    ![TCML](assets/tcml_logo.png)
+</figure>
 
 **If you publish any work which uses this package, please cite the following publication:** Gilad, M., Freiman, M. (2022). PD-DWI: Predicting Response to Neoadjuvant Chemotherapy in Invasive Breast Cancer with Physiologically-Decomposed Diffusion-Weighted MRI Machine-Learning Model. In: Wang, L., Dou, Q., Fletcher, P.T., Speidel, S., Li, S. (eds) Medical Image Computing and Computer Assisted Intervention – MICCAI 2022. MICCAI 2022. Lecture Notes in Computer Science, vol 13433. Springer, Cham. https://doi.org/10.1007/978-3-031-16437-8_4
 
 !!! note
     This work was developed as part of the [BMMR2 challenge](https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=89096426) using [ACRIN-6698](https://wiki.cancerimagingarchive.net/pages/viewpage.action?pageId=50135447) dataset.
 
 !!! warning
-    Not intended for clinical use. 
+    Not intended for clinical use. 
+
+## BMMR2 Challenge 
+
+``` plotly
+{
+    "data": [
+        {
+            "x": [
+                "Benchmark",
+                "Team C",
+                "Team B",
+                "Team A",
+                "PD-DWI"
+            ],
+            "y": [
+                0.782,
+                0.803,
+                0.838,
+                0.840,
+                0.885
+            ],
+            "marker": {
+                "color": ["rgba(136,204,238,1)", "rgba(136,204,238,1)", "rgba(136,204,238,1)", "rgba(136,204,238,1)", "rgba(204,102,119,1)"] 
+            },
+            "type": "bar"
+        }
+    ],
+    "layout": {
+        "title": "Model Performance",
+        "xaxis": { "title": "Best Performing Models" },
+        "yaxis": {
+            "title": "AUC Score",
+            "range": [
+                0.75,
+                0.9
+            ]
+        }
+    }
+}
+```
+

docs/installation/install_package.md

@@ -0,0 +1,34 @@
+# Install Package
+
+## Install via pip
+
+PD-DWI package is available on PyPi for installation via pip. Wheels are automatically generated for each release of PD-DWI, allowing you to
+install pd-dwi without having to compile anything. 
+
+!!! note
+    Ensure that you have python 3.8 installed on your machine.
+
+* Install PD-DWI:
+    ```bash
+    python -m pip install pd-dwi
+    ```
+
+## Install from source
+
+PD-DWI can also be installed from source code.
+
+!!! note
+    Ensure the following pre-prerequisites are installed on your machine:
+
+    * git
+    * python 3.8
+    * poetry 1.1.11
+
+1. Clone the repository
+```console
+    git clone https://github.com/TechnionComputationalMRILab/PD-DWI.git
+```
+2. Install the project
+```console
+  cd PD-DWI & poetry install --all-extras
+```

docs/usage.md → docs/usage/index.md

@@ -1,4 +1,4 @@
-# Usage
+# Getting Started
 
 ## Dataset setup
 
@@ -34,43 +34,10 @@ To calculate the ADC and F maps from your DWI data, please use our pre-processin
 
 All clinical data will be stored in a file named _clinical.csv_. 
 Each line will contain the following values, by order of appearance: 
+
 1. Patient ID DICOM - subject identifier, must be identical to subject's folder name
 2. hrher4g - 4 level hormone receptor status
 3. SBRgrade - 3 level tumor grade 
 4. race - subject's race
 5. Ltype - lesion type
-6. pcr - pCR label of subject. If not available, should be defined as an empty string
-
-## Command-line usage 
-
-All options on the command line can be listed by running:
-
-!!! note ""
-    pd-dwi -h
-
-### Train
-To train a pd-dwi model, run: 
-
-!!! note ""
-    pd-dwi train -dataset <path/to/dataset\> -config <path/to/config\> -out <path/to/store/model\>
-
-* The pd-dwi framework expects the dataset to be organized in a specific way, please refer to Dataset setup for additional information.
-* For training configuration structure and options, please refer to training configuration documentation.    
-
-
-### Predict
-To predict model output using a pre-trained pd-dwi model, run
-
-!!! note ""
-    pd-dwi predict -model <path/to/pre-trained/model\> -dataset <path/to/dataset\> [-probability] -out <path/to/store/model/output\>
-
-!!! warning 
-    The pre-trained model must be trained on the same pd-dwi version as the one used for prediction
-
-
-### Score
-To evaluate the performance of the pd-dwi model, run 
-
-!!! note ""
-    pd-dwi score -model <path/to/pre-trained/model\> -dataset <path/to/dataset\> 
-
+6. pcr - pCR label of subject. If not available, should be defined as an empty string

docs/usage/model.md

@@ -0,0 +1,11 @@
+## Model 
+
+
+## Command-line usage
+
+This page provides documentation for command line tools.
+
+::: mkdocs-click
+    :module: pd_dwi.scripts.cli
+    :command: pd_dwi_cli
+    :style: table

docs/usage/pre_processing.md

@@ -0,0 +1,10 @@
+# DWI Pre Processing
+
+## Command-line Usage 
+
+This page provides documentation for pre-processing command line tools.
+
+::: mkdocs-click
+    :module: pd_dwi.scripts.cli
+    :command: preprocessing_cli
+    :style: table

mkdocs.yml

@@ -1,12 +1,60 @@
 site_name: PD-DWI
 
+repo_url: https://github.com/technionComputationalMRILab/PD-DWI/
+
+theme:
+  name: readthedocs
+  highlightjs: true
+  include_homepage_in_sidebar: true
+
 nav:
   - Home: index.md
-  - Installation: installation.md
-  - Usage: usage.md
-  - Training Configuration: training_configuration.md
-  - Dataset Preprocessing: dataset_preprocessing.md
+  - Installation:
+      - Install Package: installation/install_package.md
+  - Usage:
+      - Getting Started: usage/index.md
+      - DWI Pre Processing: usage/pre_processing.md
+      - Model: usage/model.md
+      - Training Configuration: usage/training_configuration.md
+
+plugins:
+  - plotly
+  - search
 
-theme: readthedocs
 markdown_extensions:
+  # Python Markdown
+  - abbr
   - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - toc:
+      permalink: true
+
+  # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+  - mkdocs-click
+  - pymdownx.superfences:
+      custom_fences:
+        - name: plotly
+          class: mkdocs-plotly
+          format: !!python/name:mkdocs_plotly_plugin.fences.fence_plotly
+
+