NiChart_DLMUSE
==============
.. image:: https://codecov.io/gh/CBICA/NiChart_DLMUSE/graph/badge.svg?token=i5Vyjayoct
:target: https://codecov.io/gh/CBICA/NiChart_DLMUSE
:alt: Code Coverage
.. image:: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/macos_build.yml/badge.svg
:target: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/macos_build.yml
:alt: macOS Build
.. image:: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/ubuntu_build.yml/badge.svg
:target: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/ubuntu_build.yml
:alt: Ubuntu Build
.. image:: https://img.shields.io/pypi/v/NiChart_DLMUSE
:target: https://pypi.org/project/NiChart_DLMUSE/
:alt: PyPI Stable
Overview
--------
**NiChart_DLMUSE** is a package that allows the users to process their brain imaging (sMRI) data easily and efficiently.
NiChart_DLMUSE offers easy ICV (Intra-Cranial Volume) mask extraction, and brain segmentation into ROIs. This is achieved through the `DLICV <https://github.com/CBICA/DLICV>`_ and `DLMUSE <https://github.com/CBICA/DLMUSE>`_ methods. Intermediate step results are saved for easy access to the user.
Given an input (sMRI) scan, NiChart_DLMUSE extracts the following:
1. ICV mask
2. Brain MUSE ROI segmentation
3. ROI volumes in a .csv format
4. Individual ROI mask (optionally).
This package uses `nnU-Net v2 <https://github.com/MIC-DKFZ/nnUNet>`_ as a basis model architecture for the deep learning parts, and various other `libraries <requirements.txt>`_.
Installation
------------
******************************
As a locally installed package
******************************
You can install NiChart DLMUSE from source: ::
$ git clone https://github.com/CBICA/NiChart_DLMUSE.git
cd NiChart_DLMUSE
python3 -m pip install -e .
Or from out latest stable PyPI wheel: ::
$ pip install NiChart_DLMUSE
(If needed for your system) Install PyTorch with compatible CUDA.
You only need to run this step if you experience errors with CUDA while running NiChart_DLMUSE.
Run "pip uninstall torch torchaudio torchvision".
Then follow the `PyTorch installation instructions <https://pytorch.org/get-started/locally/>`_ for your CUDA version.
Note that we highly recommend matching the torch version you install to the version used by NiChart_DLMUSE. For example, after installing NiChart_DLMUSE: ::
$ pip uninstall torch torchvision torchaudio
pip install torch==2.2.1 --index-url https://download.pytorch.org/whl/cu121
******************
Run NiChart_DLMUSE
******************
Example usage below: ::
$ NiChart_DLMUSE -i /path/to/input \
-o /path/to/output \
-d cpu/cuda/mps
Docker/Singularity/Apptainer-based build and installation
---------------------------------------------------------
************
Docker build
************
The package comes already pre-built as a `docker container <https://hub.docker.com/repository/docker/cbica/nichart_dlmuse/general>`_, for convenience. Please see `Usage <#usage>`_ for more information on how to use it. Alternatively, you can build the docker image
locally, like so: ::
$ docker build -t cbica/nichart_dlmuse .
**************************************
(OUTDATED) Singularity/Apptainer build
**************************************
Singularity and Apptainer images can be built for NiChart_DLMUSE, allowing for frozen versions of the pipeline and easier installation for end-users.
Note that the Singularity project recently underwent a rename to "Apptainer", with a commercial fork still existing under the name "Singularity" (confusing!).
Please note that while for now these two versions are largely identical, future versions may diverge. It is recommended to use the AppTainer distribution. For now, these instructions apply to either.
First install `the container engine <https://apptainer.org/admin-docs/3.8/installation.html>`_.
Then, from the cloned project repository, run: ::
$ singularity build nichart_dlmuse.sif singularity.def
This will take some time, but will build a containerized version of your current repo. Be aware that this includes any local changes!
The nichart_dlmuse.sif file can be distributed via direct download, or pushed to a container registry that accepts SIF images.
*****
Usage
*****
Pre-trained nnUNet models for the skull-stripping can be found in `HuggingFace nichart/DLICV <https://huggingface.co/nichart/DLICV/tree/main>`_ and segmentation tasks
can be found in `HuggingFace nichart/DLMUSE <https://huggingface.co/nichart/DLMUSE/tree/main>`_. Feel free to use it under the package's `license <LICENSE>`_.
******************************
As a locally installed package
******************************
A complete command would be (run from the directory of the package): ::
$ NiChart_DLMUSE -i /path/to/input \
-o /path/to/output \
-d cpu/cuda/mps
For further explanation please refer to the complete documentation: ::
$ NiChart_DLMUSE -h
Troubleshooting model download failures
---------------------------------------
Our model download process creates several deep directory structures. If you are running on Windows and your model download process fails, it may be due to Windows file path limitations.
To enable long path support in Windows 10, version 1607, and later, the registry key `HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\FileSystem LongPathsEnabled (Type: REG_DWORD)` must exist and be set to 1.
If this affects you, we recommend re-running NiChart_DLMUSE with the `--clear_cache` flag set on the first run.
Using the docker container
--------------------------
Using the file structure explained above, an example command using the `docker container <https://hub.docker.com/repository/docker/cbica/nichart_dlmuse/general>`_ is the following: ::
# Pull the image for your CUDA version (as needed)
$ CUDA_VERSION=11.8 docker pull cbica/nichart_dlmuse:1.0.1-cuda${CUDA_VERSION}
# or, for CPU:
$ docker pull cbica/nichart_dlmuse:1.0.1
# Run the container with proper mounts, GPU enabled
# Place input in /path/to/input/on/host.
# Replace "-d cuda" with "-d mps" or "-d cpu" as needed...
# or don't pass at all to automatically use CPU.
# Each "/path/to/.../on/host" is a placeholder, use your actual paths!
$ docker run -it --name DLMUSE_inference --rm
--mount type=bind,source=/path/to/input/on/host,target=/input,readonly
--mount type=bind,source=/path/to/output/on/host,target=/output
--gpus all cbica/nichart_dlmuse -d cuda
(OUTDATED) singularity container
------------------------------------------
To use the singularity container, you can just do: ::
$ singularity run --nv --containall --bind /path/to/.\:/workspace/ nichart_dlmuse.simg NiChart_DLMUSE -i /workspace/temp/nnUNet_raw_data_base/nnUNet_raw_data/ -o /workspace/temp/nnUNet_out -p structural --derived_ROI_mappings_file /NiChart_DLMUSE/shared/dicts/MUSE_mapping_derived_rois.csv --MUSE_ROI_mappings_file /NiChart_DLMUSE/shared/dicts/MUSE_mapping_consecutive_indices.csv --nnUNet_raw_data_base /workspace/temp/nnUNet_raw_data_base/ --nnUNet_preprocessed /workspace/temp/nnUNet_preprocessed/ --model_folder /workspace/temp/nnUNet_model/ --all_in_gpu True --mode fastest --disable_tta
Raw data
{
"_id": null,
"home_page": "https://github.com/CBICA/NiChart_DLMUSE",
"name": "NiChart-DLMUSE",
"maintainer": "Guray Erus, Kyunglok Baik, Spiros Maggioros, Alexander Getka",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "deep learning, image segmentation, semantic segmentation, medical image analysis, medical image segmentation, nnU-Net, nnunet",
"author": "Guray Erus, Wu Di, Kyunglok Baik, George Aidinis",
"author_email": "software@cbica.upenn.edu",
"download_url": "https://files.pythonhosted.org/packages/19/66/9400fe0bc256d6540fcca3d0fb5c40fcd92e3af66128beff927547d6ac58/nichart_dlmuse-1.0.9.tar.gz",
"platform": null,
"description": "NiChart_DLMUSE\n==============\n\n.. image:: https://codecov.io/gh/CBICA/NiChart_DLMUSE/graph/badge.svg?token=i5Vyjayoct\n :target: https://codecov.io/gh/CBICA/NiChart_DLMUSE\n :alt: Code Coverage\n\n.. image:: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/macos_build.yml/badge.svg\n :target: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/macos_build.yml\n :alt: macOS Build\n\n.. image:: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/ubuntu_build.yml/badge.svg\n :target: https://github.com/CBICA/NiChart_DLMUSE/actions/workflows/ubuntu_build.yml\n :alt: Ubuntu Build\n\n.. image:: https://img.shields.io/pypi/v/NiChart_DLMUSE\n :target: https://pypi.org/project/NiChart_DLMUSE/\n :alt: PyPI Stable\n\nOverview\n--------\n\n**NiChart_DLMUSE** is a package that allows the users to process their brain imaging (sMRI) data easily and efficiently.\n\nNiChart_DLMUSE offers easy ICV (Intra-Cranial Volume) mask extraction, and brain segmentation into ROIs. This is achieved through the `DLICV <https://github.com/CBICA/DLICV>`_ and `DLMUSE <https://github.com/CBICA/DLMUSE>`_ methods. Intermediate step results are saved for easy access to the user.\n\nGiven an input (sMRI) scan, NiChart_DLMUSE extracts the following:\n\n 1. ICV mask\n 2. Brain MUSE ROI segmentation\n 3. ROI volumes in a .csv format\n 4. Individual ROI mask (optionally).\n\nThis package uses `nnU-Net v2 <https://github.com/MIC-DKFZ/nnUNet>`_ as a basis model architecture for the deep learning parts, and various other `libraries <requirements.txt>`_.\n\nInstallation\n------------\n\n******************************\nAs a locally installed package\n******************************\n\nYou can install NiChart DLMUSE from source: ::\n\n $ git clone https://github.com/CBICA/NiChart_DLMUSE.git\n cd NiChart_DLMUSE\n python3 -m pip install -e .\n\nOr from out latest stable PyPI wheel: ::\n\n $ pip install NiChart_DLMUSE\n\n(If needed for your system) Install PyTorch with compatible CUDA.\nYou only need to run this step if you experience errors with CUDA while running NiChart_DLMUSE.\nRun \"pip uninstall torch torchaudio torchvision\".\nThen follow the `PyTorch installation instructions <https://pytorch.org/get-started/locally/>`_ for your CUDA version.\nNote that we highly recommend matching the torch version you install to the version used by NiChart_DLMUSE. For example, after installing NiChart_DLMUSE: ::\n\n $ pip uninstall torch torchvision torchaudio\n pip install torch==2.2.1 --index-url https://download.pytorch.org/whl/cu121\n\n******************\nRun NiChart_DLMUSE\n******************\n\nExample usage below: ::\n\n $ NiChart_DLMUSE -i /path/to/input \\\n -o /path/to/output \\\n -d cpu/cuda/mps\n\nDocker/Singularity/Apptainer-based build and installation\n---------------------------------------------------------\n\n************\nDocker build\n************\n\nThe package comes already pre-built as a `docker container <https://hub.docker.com/repository/docker/cbica/nichart_dlmuse/general>`_, for convenience. Please see `Usage <#usage>`_ for more information on how to use it. Alternatively, you can build the docker image\nlocally, like so: ::\n\n $ docker build -t cbica/nichart_dlmuse .\n\n**************************************\n(OUTDATED) Singularity/Apptainer build\n**************************************\n\nSingularity and Apptainer images can be built for NiChart_DLMUSE, allowing for frozen versions of the pipeline and easier installation for end-users.\nNote that the Singularity project recently underwent a rename to \"Apptainer\", with a commercial fork still existing under the name \"Singularity\" (confusing!).\nPlease note that while for now these two versions are largely identical, future versions may diverge. It is recommended to use the AppTainer distribution. For now, these instructions apply to either.\n\nFirst install `the container engine <https://apptainer.org/admin-docs/3.8/installation.html>`_.\nThen, from the cloned project repository, run: ::\n\n $ singularity build nichart_dlmuse.sif singularity.def\n\nThis will take some time, but will build a containerized version of your current repo. Be aware that this includes any local changes!\nThe nichart_dlmuse.sif file can be distributed via direct download, or pushed to a container registry that accepts SIF images.\n\n*****\nUsage\n*****\n\nPre-trained nnUNet models for the skull-stripping can be found in `HuggingFace nichart/DLICV <https://huggingface.co/nichart/DLICV/tree/main>`_ and segmentation tasks\ncan be found in `HuggingFace nichart/DLMUSE <https://huggingface.co/nichart/DLMUSE/tree/main>`_. Feel free to use it under the package's `license <LICENSE>`_.\n\n******************************\nAs a locally installed package\n******************************\n\nA complete command would be (run from the directory of the package): ::\n\n $ NiChart_DLMUSE -i /path/to/input \\\n -o /path/to/output \\\n -d cpu/cuda/mps\n\nFor further explanation please refer to the complete documentation: ::\n\n $ NiChart_DLMUSE -h\n\nTroubleshooting model download failures\n---------------------------------------\n\nOur model download process creates several deep directory structures. If you are running on Windows and your model download process fails, it may be due to Windows file path limitations.\n\nTo enable long path support in Windows 10, version 1607, and later, the registry key `HKEY_LOCAL_MACHINE\\\\SYSTEM\\\\CurrentControlSet\\\\Control\\\\FileSystem LongPathsEnabled (Type: REG_DWORD)` must exist and be set to 1.\n\nIf this affects you, we recommend re-running NiChart_DLMUSE with the `--clear_cache` flag set on the first run.\n\nUsing the docker container\n--------------------------\n\nUsing the file structure explained above, an example command using the `docker container <https://hub.docker.com/repository/docker/cbica/nichart_dlmuse/general>`_ is the following: ::\n\n # Pull the image for your CUDA version (as needed)\n $ CUDA_VERSION=11.8 docker pull cbica/nichart_dlmuse:1.0.1-cuda${CUDA_VERSION}\n # or, for CPU:\n $ docker pull cbica/nichart_dlmuse:1.0.1\n\n # Run the container with proper mounts, GPU enabled\n # Place input in /path/to/input/on/host.\n # Replace \"-d cuda\" with \"-d mps\" or \"-d cpu\" as needed...\n # or don't pass at all to automatically use CPU.\n # Each \"/path/to/.../on/host\" is a placeholder, use your actual paths!\n $ docker run -it --name DLMUSE_inference --rm\n --mount type=bind,source=/path/to/input/on/host,target=/input,readonly\n --mount type=bind,source=/path/to/output/on/host,target=/output\n --gpus all cbica/nichart_dlmuse -d cuda\n\n\n(OUTDATED) singularity container\n------------------------------------------\n\nTo use the singularity container, you can just do: ::\n\n $ singularity run --nv --containall --bind /path/to/.\\:/workspace/ nichart_dlmuse.simg NiChart_DLMUSE -i /workspace/temp/nnUNet_raw_data_base/nnUNet_raw_data/ -o /workspace/temp/nnUNet_out -p structural --derived_ROI_mappings_file /NiChart_DLMUSE/shared/dicts/MUSE_mapping_derived_rois.csv --MUSE_ROI_mappings_file /NiChart_DLMUSE/shared/dicts/MUSE_mapping_consecutive_indices.csv --nnUNet_raw_data_base /workspace/temp/nnUNet_raw_data_base/ --nnUNet_preprocessed /workspace/temp/nnUNet_preprocessed/ --model_folder /workspace/temp/nnUNet_model/ --all_in_gpu True --mode fastest --disable_tta\n",
"bugtrack_url": null,
"license": "By installing/using DLMUSE, the user agrees to the following license: See https://www.med.upenn.edu/cbica/software-agreement-non-commercial.html",
"summary": "Run NiChart_DLMUSE on your data (currently only structural pipeline is supported).",
"version": "1.0.9",
"project_urls": {
"Homepage": "https://github.com/CBICA/NiChart_DLMUSE"
},
"split_keywords": [
"deep learning",
" image segmentation",
" semantic segmentation",
" medical image analysis",
" medical image segmentation",
" nnu-net",
" nnunet"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ef3021adc554747d0e2ede44f70c210dd289431c644dfaff466aff447e664a7",
"md5": "bce63b037aeb504ede03e13f61e7f2f9",
"sha256": "b8b8c0b06bc674097314ce69f9c59e93107fc7c693b176e2919d5f5923285bd9"
},
"downloads": -1,
"filename": "NiChart_DLMUSE-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bce63b037aeb504ede03e13f61e7f2f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 38678,
"upload_time": "2024-12-06T19:39:42",
"upload_time_iso_8601": "2024-12-06T19:39:42.088337Z",
"url": "https://files.pythonhosted.org/packages/4e/f3/021adc554747d0e2ede44f70c210dd289431c644dfaff466aff447e664a7/NiChart_DLMUSE-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "19669400fe0bc256d6540fcca3d0fb5c40fcd92e3af66128beff927547d6ac58",
"md5": "88ebac3b12026df5b848ca6d79a3e0fc",
"sha256": "3373c87830759ec9beff32a1bba73721e7b1765cd00a6fd92403fc9eca1be047"
},
"downloads": -1,
"filename": "nichart_dlmuse-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "88ebac3b12026df5b848ca6d79a3e0fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 33908,
"upload_time": "2024-12-06T19:39:43",
"upload_time_iso_8601": "2024-12-06T19:39:43.763717Z",
"url": "https://files.pythonhosted.org/packages/19/66/9400fe0bc256d6540fcca3d0fb5c40fcd92e3af66128beff927547d6ac58/nichart_dlmuse-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-06 19:39:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CBICA",
"github_project": "NiChart_DLMUSE",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "torch",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "DLICV",
"specs": []
},
{
"name": "DLMUSE",
"specs": []
},
{
"name": "nibabel",
"specs": [
[
">=",
"5.2"
]
]
},
{
"name": "scipy",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "huggingface_hub",
"specs": []
},
{
"name": "argparse",
"specs": []
},
{
"name": "pathlib",
"specs": []
},
{
"name": "pre-commit",
"specs": []
}
],
"lcname": "nichart-dlmuse"
}
JSON
