Merge branch 'Project-MONAI:main' into maisi

Author: Can-Zhao

.github/workflows/test-modified.yml

@@ -9,39 +9,40 @@ on:
 
 concurrency:
   # automatically cancel the previously triggered workflows when there's a newer version
-  group: build-gpu-${{ github.event.pull_request.number || github.ref }}
+  group: build-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
 jobs:
   build:
-    if: github.repository == 'Project-MONAI/tutorials'
-    container:
-      image: nvcr.io/nvidia/pytorch:24.02-py3
-      options: --gpus all --ipc host
-    runs-on: [self-hosted, linux, x64]
+    runs-on: ubuntu-latest
     steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.10'
     - name: Install MONAI
       id: monai-install
       run: |
+        find  /opt/hostedtoolcache/* -maxdepth 0 ! -name 'Python' -exec rm -rf {} \;
         which python
-        nvidia-smi
-        rm -rf ../../MONAI/MONAI
-        python -m pip install --upgrade pip wheel
-        pip uninstall -y monai
-        pip uninstall -y monai
-        pip uninstall -y monai-weekly
-        pip uninstall -y monai-weekly # make sure there's no existing installation
-        BUILD_MONAI=0 python -m pip install git+https://github.com/Project-MONAI/MONAI#egg=MONAI
+        python -m pip install -U pip wheel
+        python -m pip install torch torchvision torchaudio
+
         python -m pip install -r https://raw.githubusercontent.com/Project-MONAI/MONAI/dev/requirements-dev.txt
-        python -m pip install -U torch torchvision torchaudio
-    - uses: actions/checkout@v3
+        python -m pip install -r requirements.txt
+
+        BUILD_MONAI=0 python -m pip install git+https://github.com/Project-MONAI/MONAI#egg=MONAI
+        python -m pip list
     - name: Notebook quick check
       shell: bash
       run: |
-        git config --global --add safe.directory /__w/tutorials/tutorials
-        git fetch origin main
-        python -m pip install -r requirements.txt; python -m pip list
         python -c "import monai; monai.config.print_debug_info()"
-        export CUDA_VISIBLE_DEVICES=0
-        git diff --name-only origin/main | while read line; do if [[ $line == *.ipynb ]]; then ./runner.sh -p " -and -wholename './${line}'"; fi; done;
-          # [[ $line == *.ipynb ]] && ./runner.sh --file "$line"
+        git fetch origin main
+        git diff --name-only origin/main | while read line
+        do
+          if [[ $line == *.ipynb ]]
+          then
+            ./runner.sh -p " -and -wholename './${line}'"
+          fi
+        done

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 default_language_version:
-  python: python3.9
+  python: python3
 
 ci:
   autofix_prs: true
@@ -9,7 +9,7 @@ ci:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: end-of-file-fixer
       - id: trailing-whitespace
@@ -22,8 +22,8 @@ repos:
         args: ['--maxkb=1024']
       - id: detect-private-key
 
-  - repo: https://github.com/psf/black
-    rev: "25.1.0"
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: "25.9.0"
     hooks:
       - id: black
       - id: black-jupyter

2d_classification/monai_101.ipynb

@@ -141,15 +141,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "/workspace/data\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "directory = os.environ.get(\"MONAI_DATA_DIRECTORY\")\n",
     "if directory is not None:\n",
@@ -250,11 +242,12 @@
    "outputs": [],
    "source": [
     "max_epochs = 5\n",
-    "model = densenet121(spatial_dims=2, in_channels=1, out_channels=6).to(\"cuda:0\")\n",
+    "device = torch.device(\"cuda:0\" if torch.cuda.device_count() > 0 else \"cpu\")\n",
+    "model = densenet121(spatial_dims=2, in_channels=1, out_channels=6).to(device)\n",
     "\n",
     "logging.basicConfig(stream=sys.stdout, level=logging.INFO)\n",
     "trainer = SupervisedTrainer(\n",
-    "    device=torch.device(\"cuda:0\"),\n",
+    "    device=device,\n",
     "    max_epochs=max_epochs,\n",
     "    train_data_loader=DataLoader(dataset, batch_size=512, shuffle=True, num_workers=4),\n",
     "    network=model,\n",
@@ -320,7 +313,7 @@
     "max_items_to_print = 10\n",
     "with eval_mode(model):\n",
     "    for item in DataLoader(testdata, batch_size=1, num_workers=0):\n",
-    "        prob = np.array(model(item[\"image\"].to(\"cuda:0\")).detach().to(\"cpu\"))[0]\n",
+    "        prob = np.array(model(item[\"image\"].to(device)).detach().to(\"cpu\"))[0]\n",
     "        pred = class_names[prob.argmax()]\n",
     "        gt = item[\"class_name\"][0]\n",
     "        print(f\"Class prediction is {pred}. Ground-truth: {gt}\")\n",

3d_segmentation/spleen_segmentation_3d_visualization_basic.ipynb

@@ -484,7 +484,7 @@
     "# standard PyTorch program style: create UNet, DiceLoss and Adam optimizer\n",
     "device = torch.device(\"cuda:0\")\n",
     "\n",
-    "UNet_meatdata = {\n",
+    "UNet_metadata = {\n",
     "    \"spatial_dims\": 3,\n",
     "    \"in_channels\": 1,\n",
     "    \"out_channels\": 2,\n",
@@ -494,7 +494,7 @@
     "    \"norm\": Norm.BATCH,\n",
     "}\n",
     "\n",
-    "model = UNet(**UNet_meatdata).to(device)\n",
+    "model = UNet(**UNet_metadata).to(device)\n",
     "loss_function = DiceLoss(to_onehot_y=True, softmax=True)\n",
     "loss_type = \"DiceLoss\"\n",
     "optimizer = torch.optim.Adam(model.parameters(), 1e-4)\n",
@@ -539,7 +539,7 @@
     "# initialize a new Aim Run\n",
     "aim_run = aim.Run()\n",
     "# log model metadata\n",
-    "aim_run[\"UNet_meatdata\"] = UNet_meatdata\n",
+    "aim_run[\"UNet_metadata\"] = UNet_metadata\n",
     "# log optimizer metadata\n",
     "aim_run[\"Optimizer_metadata\"] = Optimizer_metadata\n",
     "\n",

README.md

@@ -41,6 +41,50 @@ Running:
 
 in a cell will verify this has worked and show you what kind of hardware you have access to.
 
+#### Google Colab Setup (CUDA 12.x, PyTorch 2.6, MONAI 1.5)
+
+In Google Colab, the default environment may cause version conflicts with MONAI.
+To ensure compatibility, install PyTorch and MONAI explicitly as follows:
+
+# Install PyTorch 2.6.0 with CUDA 12.4
+pip install --index-url https://download.pytorch.org/whl/cu124 \
+  torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0
+
+# Install MONAI and common dependencies
+pip install "monai[all]" nibabel pydicom ipywidgets==8.1.2
+
+
+### Known issues and fixes
+
+- Torchaudio mismatch
+  Colab may come with torchaudio 2.8.0, which is incompatible with torch 2.6.0.
+  Installing the versions above resolves this issue.
+
+- filelock conflicts with nni
+  Some preinstalled packages (such as pytensor with newer filelock) may conflict.
+  Use the following commands to fix:
+
+  pip uninstall -y pytensor
+  pip install -U filelock
+
+- Too many workers warning
+  Colab has limited CPU resources, and high num_workers settings may freeze execution.
+  It is recommended to use --num_workers=2 when running tutorials and adjust the `num_workers` parameters where it is used in notebooks (eg. for data loaders).
+
+
+### Quick smoke test
+
+After installation, verify the environment by running:
+
+git clone https://github.com/Project-MONAI/tutorials.git
+cd tutorials/3d_segmentation/torch
+python -u unet_training_array.py --max_epochs 2 --batch_size 1 --num_workers 2
+
+If the logs show decreasing training loss and a Dice score, the setup is correct.
+
+**Note:** In most cases, users can run MONAI tutorials directly in Colab notebooks without additional installation.
+The steps above are mainly for resolving dependency conflicts when installing extra packages.
+
 #### Data
 
 Some notebooks will require additional data.
@@ -342,3 +386,4 @@ Example shows the use cases of using MONAI to evaluate the performance of a gene
 
 #### [VISTA2D](./vista_2d)
 This tutorial demonstrates how to train a cell segmentation model using the [MONAI](https://monai.io/) framework and the [Segment Anything Model (SAM)](https://github.com/facebookresearch/segment-anything) on the [Cellpose dataset](https://www.cellpose.org/).
+ECHO°¡ ¼³Á¤µÇ¾î ÀÖ½À´Ï´Ù.

auto3dseg/README.md

@@ -56,13 +56,44 @@ We provide [a two-minute example](notebooks/auto3dseg_hello_world.ipynb) for use
 
 To further demonstrate the capabilities of **Auto3DSeg**, [here](./tasks/instance22/README.md) is the detailed performance of the algorithm in **Auto3DSeg**, which won 2nd place in the MICCAI 2022 challenge **[INSTANCE22: The 2022 Intracranial Hemorrhage Segmentation Challenge on Non-Contrast Head CT (NCCT)](https://instance.grand-challenge.org/)**
 
+## Running With Your Own Data
+
+To run Auto3DSeg on your own dataset, you need to build a `datalist.json` file, and pass it to the AutoRunner.
+
+The datalist format is based on the datasets released by the [Medical Segmentation Decathlon](http://medicaldecathlon.com).
+See the function `load_decathlon_datalist` in `monai/data/decathlon_datalist.py` for a description of the format.
+
+For the AutoRunner, we only need the `training` list in the JSON, it does not use any other fields.
+The `fold` key for each image is not required, as the AutoRunner will automatically create cross-validation folds (the number of folds is hard-coded to 5).
+If you do add the cross-validation folds beforehand, the AutoRunner will use these by default.
+You can also choose to include a `validation` list in the JSON file, in which case the AutoRunner will disable cross-validation and use the specified validation set.
+Any other metadata, such as `modality`, `numTraining`, `name`, etc. will not be used by the AutoRunner, but we do recommend using metadata fields to keep track of names and versions of your dataset. If you are using multi-modal scans, it is possible to enter lists of image paths for both the `image` and `label` keys; MONAI will stack them into channels.
+In short, your `datalist.json` file should look like this:
+
+```
+{
+    "name": "Example datalist.json"
+    "training":
+        [
+            {"image": "/path/to/image_1.nii.gz", "label": "/path/to/label_1.nii.gz"},
+            {"image": "/path/to/image_2.nii.gz", "label": "/path/to/label_2.nii.gz"},
+            ...
+        ]
+}
+
+```
+
+The AutoRunner will create a `work_dir` folder in the directory from which it is run, which will contain the resulting models and the copied datalist file _with_ cross-validation folds. This allows you to keep track of which datalist file the models are trained on.
+
+See the description below or the file [run_with_minimal_input.md](docs/run_with_minimal_input.md) to use your datalist with the AutoRunner.
+
 ## Reference Python APIs for Auto3DSeg
 
 **Auto3DSeg** offers users different levels of APIs to run pipelines that suit their needs.
 
 ### 1. Run with Minimal Input using ```AutoRunner```
 
-The user needs to provide a data list (".json" file) for the new task and data root. A typical data list is as this [example](tasks/msd/Task05_Prostate/msd_task05_prostate_folds.json). A sample datalist for an existing MSD formatted dataset can be created using [this notebook](notebooks/msd_datalist_generator.ipynb). After creating the data list, the user can create a simple "task.yaml" file (shown below) as the minimum input for **Auto3DSeg**.
+The user needs to provide a data list (".json" file) for the new task and data root. A typical data list is as this [example](tasks/msd/Task05_Prostate/msd_task05_prostate_folds.json). [This notebook](notebooks/msd_crossval_datalist_generator.ipynb) features an example to create a datalist with cross-validation folds from an existing MSD dataset. After creating the data list, the user can create a simple "task.yaml" file (shown below) as the minimum input for **Auto3DSeg**.
 
 ```
 modality: CT

auto3dseg/docs/run_with_minimal_input.md

@@ -18,55 +18,39 @@ if os.path.exists(root):
     download_and_extract(resource, compressed_file, root)
 ```
 
-**Step 1.** Provide the following data list (a ".json" file) for a new task and the data root. The typical data list is shown as follows.
+**Step 1.** Provide a `datalist.json` file.
+See the documentation under the `load_decathlon_datalist` function in `monai.data.decathlon_datalist` for details on the file format.
 
+For the AutoRunner, you only need the `training` field with its list of training files:
 ```
 {
-    "training": [
-        {
-            "fold": 0,
-            "image": "image_001.nii.gz",
-            "label": "label_001.nii.gz"
-        },
-        {
-            "fold": 0,
-            "image": "image_002.nii.gz",
-            "label": "label_002.nii.gz"
-        },
-        {
-            "fold": 1,
-            "image": "image_003.nii.gz",
-            "label": "label_001.nii.gz"
-        },
-        {
-            "fold": 2,
-            "image": "image_004.nii.gz",
-            "label": "label_002.nii.gz"
-        },
-        {
-            "fold": 3,
-            "image": "image_005.nii.gz",
-            "label": "label_003.nii.gz"
-        },
-        {
-            "fold": 4,
-            "image": "image_006.nii.gz",
-            "label": "label_004.nii.gz"
-        }
-    ],
-    "testing": [
-        {
-            "image": "image_010.nii.gz"
-        }
-    ]
+    "training":
+        [
+            {"image": "/path/to/image_1.nii.gz", "label": "/path/to/label_1.nii.gz"},
+            {"image": "/path/to/image_2.nii.gz", "label": "/path/to/label_2.nii.gz"},
+            ...
+        ],
+    "testing":
+        [
+           "/path/to/test_image_1.nii.gz",
+           "/path/to/test_image_2.nii.gz",
+            ...
+        ]
 }
+
 ```
+In each training item, you can add a `fold` field (with an integer starting at 0) to pre-specify the cross-validation folds, otherwise the AutoRunner will generate its own folds (always 5). All trained algorithms will use the same generated or pre-specified folds, the file can be found in the `work_dir` folder that the AutoRunner generates.
+If you have a validation set, you can include it under a `validation` key with the same format as the `training` list. This will disable cross-validation.
+A "testing" list can also be added, which only requires the image files, not the labels. If it is included, the AutoRunner will output predictions on the testing set after training.
+It is recommended to add a `name` field and any other metadata fields that allow you to track which version of your dataset the models are trained on.
+
+Save the file to `./datalist.json`.
 
 **Step 2.** Prepare "task.yaml" with the necessary information as follows.
 
 ```
-modality: CT
-datalist: "./task.json"
+modality: CT  # or MRI
+datalist: "./datalist.json"
 dataroot: "/workspace/data/task"
 ```
 

auto3dseg/notebooks/auto_runner.ipynb

@@ -273,13 +273,9 @@
     "\n",
     "`set_training_params` in `AutoRunner` provides an interface to change all algorithms' training parameters in one line. \n",
     "\n",
-    "NOTE: \n",
-    "**Auto3DSeg** uses MONAI bundle templates to perform training, validation, and inference.\n",
-    "The number of epochs/iterations of training is specified by the config files in each template.\n",
-    "Users can override these these values in the bundle templates.\n",
-    "But users should consider that some bundle templates may use `num_iterations` and other may use `num_epochs` to iterate.\n",
+    "As an example, see the code block below, which specifies e.g. the number of epochs used for training. Note that some algorithms may treat this as a maximum number of epochs.\n",
     "\n",
-    "For demo purposes, below is a code block to convert num_epoch to iteration style and override all algorithms with the same training parameters.\n",
+    "NOTE: \n",
     "The setup works fine for a machine that has GPUs less than or equal to 8.\n",
     "The datalist in this example is only using a subset of the original dataset.\n",
     "Users need to ensure the number of GPUs is not greater than the number that the training dataset can be partitioned.\n",

…g/notebooks/msd_datalist_generator.ipynb …ks/msd_crossval_datalist_generator.ipynbauto3dseg/notebooks/msd_datalist_generator.ipynb renamed to auto3dseg/notebooks/msd_crossval_datalist_generator.ipynb auto3dseg/notebooks/msd_datalist_generator.ipynb renamed to auto3dseg/notebooks/msd_crossval_datalist_generator.ipynb

@@ -19,7 +19,15 @@
     "See the License for the specific language governing permissions and  \n",
     "limitations under the License. \n",
     "\n",
-    "# Datalist Generator"
+    "# Datalist Cross-Validation Folds Generator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This notebook contains an example to add cross-validation folds to an existing Medical Segmentation Decathlon datalist, in this case the one of Task09_Spleen. \n",
+    "When running repeated experiments, it can be beneficial to create cross-validation folds beforehand."
    ]
   },
   {