Screening of Congenital Heart Diseases (CHD) in mice with 3D <img src="https://latex.codecogs.com/svg.latex?\mu" /> CTscans.
***Napari plugin: [MouseCHD Napari plugin](https://github.com/hnguyentt/mousechd-napari)***
## Installation
There are three ways that you can run the package:
### Conda environment
* Create virtual environment: `conda create -n mousechd python=3.9`
* Activate the environment: `conda activate mousechd`
* Install the package: `pip install mousechd`
### Docker
* Pull the docker image: `sudo docker pull hoanguyen93/mousechd`
* Test if docker image pulled successfully: `sudo docker run mousechd mousechd -h`
<details>
<summary>Expected output:</summary>
```
usage: mousechd [-h] [-version] {postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad} ...
optional arguments:
-h, --help show this help message and exit
-version show program's version number and exit
Choose a command:
{postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad}
```
</details>
To assure that you can run the docker with GPUs if available, see [Running docker with GPU](https://github.com/hnguyentt/MouseCHD/tree/master/containers#running-docker-with-gpu) section.
### Apptainer
In case you run the package on HPC on which you don't have superuser permission, you can use Apptainer instead of docker.
* Download container to your computer or HPC:
```bash
wget https://zenodo.org/records/13855119/files/mousechd.sif
```
* On HPC, the internet connection may not be not available on running node, you should download models in advance. See the downloading instruction [Downloading models in advance on HPC](https://github.com/hnguyentt/MouseCHD/tree/master/containers#downloading-models-in-advance-on-hpc)
* Test if container run correctly: `apptainer exec --nv <path/to/mousechd.sif> mousechd -h`
<details>
<summary>Expected output:</summary>
```
usage: mousechd [-h] [-version] {postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad} ...
optional arguments:
-h, --help show this help message and exit
-version show program's version number and exit
Choose a command:
{postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad}
```
</details>
## How to use
It is recommended that your data are structured in the following way:
```
DATABASE # your database name
└── raw # raw folder to store raw data
├── NameOfDataset1 # name of dataset
│ ├── images_20200206 # folder to store images recieved on 20200206 [YYYYMMDD]
│ ├── masks_20210115 # folder to store masks recieved on 20210115 [YYYYMMDD]
│ ├── masks_20210708 # folder to store masks recieved on 20210708 [YYYYMMDD]
│ └── metadata_20210703.csv # metadata file received on 20210703 [YYYYMMDD]
└── NameOfDataset2 # name of another dataset
└── images_20201010
......
```
In case you use container, see [Running `mousechd` with docker](https://github.com/hnguyentt/MouseCHD/tree/master/containers#running-mousechd-with-docker) and [Running `mousechd` with Apptainer](https://github.com/hnguyentt/MouseCHD/tree/master/containers#running-mousechd-with-apptainer) for more details.
### (1) Preprocessing
This step standardizes the data into the same spacing and view.
* Data format supported: "DICOM", "NRRD", "NIFTI"
* Mask data format supported: "TIF2d", "TIF3d", "NIFTI"
```bash
mousechd preprocess \
-database <PATH/TO/DATABASE> \
-imdir <PATH/TO/IMAGE/DIR> \ # relative to databse
-maskdir <PATH/TO/MASK/DIR> \ # relative to database
-masktype NIFTI \
-metafile <PATH/TO/META/FILE> \ # csv file with headers: "heart_name", "Stage", "Normal heart", "CHD1", "CHD2", ...
-outdir "DATA/processed"
```
### (2) Heart segmentation
```bash
mousechd segment -indir "DATA/processed/images" -outdir "OUTPUTS/HeartSeg"
```
If your computer crashes when running this, you can decrease the number of threads for preprocessing (`-num_threads_preprocessing`, default: 6) and saving NIFTI files (`-num_thread_nifti_save`, default: 2)
### (3) CHD detection
```bash
mousechd test_clf \
-imdir "DATA/processed/images" \
-maskdir "OUTPUTS/HeartSeg" \
-stage ["eval"|"test"] \
-label [PATH/TO/CSV/TEST/FILE] \ # <optional> if stage is "eval", -label must be specified
-outdir [PATH/TO/OUTPUT/DIRECTORY]
```
## Retraining
You have the option to retrain the model using your custom dataset. After completing the heart segmentation, resample to augment the data, followed by data splitting and subsequence model retraining.
<details>
<summary>Click here to expand the instruction</summary>
### (1) Resample
```bash
mousechd resample \
-imdir "DATA/processed/images" \
-maskdir "OUTPUTS/HeartSeg" \
-outdir "DATA/resampled" \
-metafile "DATA/processed/metadata.csv" \
-save_images 1
```
### (2) Split data
```bash
mousechd split_data \
-metafile "DATA/processed/metadata.csv" \
-outdir "DATA/label" \
-val_size 0.2
```
### (3) Train
```bash
mousechd train_clf \
-exp_dir "OUTPUTS/Classifier" \
-exp [EXPERIEMENT_NAME] \
-data_dir "DATA/resampled" \
-label_dir "DATA/label/x5_base/1fold" \
-epochs [NUM_EPOCHS]
```
### (4) Evaluate retrained model
```bash
mousechd test_clf \
-model_dir "OUTPUTS/Classifier/<EXPERIMENT_NAME>" \
-imdir "DATA/processed/images" \
-maskdir "OUTPUTS/HeartSeg" \
-stage ["eval"|"test"] \
-label [PATH/TO/CSV/TEST/FILE] \ # <optional> if stage is "eval", -label must be specified
-outdir [PATH/TO/OUTPUT/DIRECTORY]
```
</details>
## GradCAM
```bash
mousechd explain \
-exp_dir "OUTPUTS/Classifier/<EXPERIMENT_NAME>" \
-imdir "DATA/resampled/images" \
-outdir [PATH/TO/OUTPUT/DIRECTORY]
```
## Analysis
A detailed analysis can be found in the folder [analysis](./analysis/).
For some visualization, [Napari](https://napari.org/stable/) is required. To install: `pip install "napari[all]"`.
## Acknowledgements
* INCEPTION funding: [INCEPTION](https://www.inception-program.fr/en)
* GPU server technical support: Quang Tru Huynh
Raw data
{
"_id": null,
"home_page": "https://github.com/hnguyentt/MouseCHD",
"name": "mousechd",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "deep learning, image segmentation, image classification, medical image analysis, mousechd",
"author": "Hoa Nguyen",
"author_email": "ntthoa.uphcm@gmail.com",
"download_url": null,
"platform": null,
"description": "\n\nScreening of Congenital Heart Diseases (CHD) in mice with 3D <img src=\"https://latex.codecogs.com/svg.latex?\\mu\" /> CTscans.\n\n***Napari plugin: [MouseCHD Napari plugin](https://github.com/hnguyentt/mousechd-napari)***\n\n\n## Installation\nThere are three ways that you can run the package:\n\n### Conda environment\n* Create virtual environment: `conda create -n mousechd python=3.9`\n* Activate the environment: `conda activate mousechd`\n* Install the package: `pip install mousechd`\n\n### Docker\n* Pull the docker image: `sudo docker pull hoanguyen93/mousechd`\n* Test if docker image pulled successfully: `sudo docker run mousechd mousechd -h`\n\n<details>\n<summary>Expected output:</summary>\n\n```\nusage: mousechd [-h] [-version] {postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad} ...\n\noptional arguments:\n -h, --help show this help message and exit\n -version show program's version number and exit\n\nChoose a command:\n {postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad}\n```\n\n</details>\n\nTo assure that you can run the docker with GPUs if available, see [Running docker with GPU](https://github.com/hnguyentt/MouseCHD/tree/master/containers#running-docker-with-gpu) section.\n\n### Apptainer\nIn case you run the package on HPC on which you don't have superuser permission, you can use Apptainer instead of docker.\n\n* Download container to your computer or HPC:\n```bash\nwget https://zenodo.org/records/13855119/files/mousechd.sif\n```\n* On HPC, the internet connection may not be not available on running node, you should download models in advance. See the downloading instruction [Downloading models in advance on HPC](https://github.com/hnguyentt/MouseCHD/tree/master/containers#downloading-models-in-advance-on-hpc)\n* Test if container run correctly: `apptainer exec --nv <path/to/mousechd.sif> mousechd -h`\n\n<details>\n<summary>Expected output:</summary>\n\n```\nusage: mousechd [-h] [-version] {postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad} ...\n\noptional arguments:\n -h, --help show this help message and exit\n -version show program's version number and exit\n\nChoose a command:\n {postprocess_nnUNet,prepare_nnUNet_data,preprocess,segment,resample,split_data,viz3d_views,viz3d_stages,viz_stacks,viz_eda,viz3d_seg,create_label_df,test_clf,train_clf,explain,viz_grad}\n```\n\n</details>\n \n## How to use\n\nIt is recommended that your data are structured in the following way:\n```\n DATABASE # your database name\n \u2514\u2500\u2500 raw # raw folder to store raw data\n \u251c\u2500\u2500 NameOfDataset1 # name of dataset\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 images_20200206 # folder to store images recieved on 20200206 [YYYYMMDD]\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 masks_20210115 # folder to store masks recieved on 20210115 [YYYYMMDD]\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 masks_20210708 # folder to store masks recieved on 20210708 [YYYYMMDD]\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 metadata_20210703.csv # metadata file received on 20210703 [YYYYMMDD]\n \u2514\u2500\u2500 NameOfDataset2 # name of another dataset\n \u2514\u2500\u2500 images_20201010\n ......\n```\n\nIn case you use container, see [Running `mousechd` with docker](https://github.com/hnguyentt/MouseCHD/tree/master/containers#running-mousechd-with-docker) and [Running `mousechd` with Apptainer](https://github.com/hnguyentt/MouseCHD/tree/master/containers#running-mousechd-with-apptainer) for more details.\n\n### (1) Preprocessing\n\nThis step standardizes the data into the same spacing and view.\n* Data format supported: \"DICOM\", \"NRRD\", \"NIFTI\"\n* Mask data format supported: \"TIF2d\", \"TIF3d\", \"NIFTI\"\n\n```bash\nmousechd preprocess \\\n -database <PATH/TO/DATABASE> \\\n -imdir <PATH/TO/IMAGE/DIR> \\ # relative to databse\n -maskdir <PATH/TO/MASK/DIR> \\ # relative to database\n -masktype NIFTI \\\n -metafile <PATH/TO/META/FILE> \\ # csv file with headers: \"heart_name\", \"Stage\", \"Normal heart\", \"CHD1\", \"CHD2\", ...\n -outdir \"DATA/processed\"\n```\n\n### (2) Heart segmentation\n\n ```bash\n mousechd segment -indir \"DATA/processed/images\" -outdir \"OUTPUTS/HeartSeg\"\n ```\nIf your computer crashes when running this, you can decrease the number of threads for preprocessing (`-num_threads_preprocessing`, default: 6) and saving NIFTI files (`-num_thread_nifti_save`, default: 2)\n\n### (3) CHD detection\n```bash\nmousechd test_clf \\\n -imdir \"DATA/processed/images\" \\\n -maskdir \"OUTPUTS/HeartSeg\" \\\n -stage [\"eval\"|\"test\"] \\\n -label [PATH/TO/CSV/TEST/FILE] \\ # <optional> if stage is \"eval\", -label must be specified\n -outdir [PATH/TO/OUTPUT/DIRECTORY]\n```\n\n## Retraining\n\nYou have the option to retrain the model using your custom dataset. After completing the heart segmentation, resample to augment the data, followed by data splitting and subsequence model retraining.\n\n<details>\n<summary>Click here to expand the instruction</summary>\n\n### (1) Resample\n```bash\nmousechd resample \\\n -imdir \"DATA/processed/images\" \\\n -maskdir \"OUTPUTS/HeartSeg\" \\\n -outdir \"DATA/resampled\" \\\n -metafile \"DATA/processed/metadata.csv\" \\\n -save_images 1\n```\n\n### (2) Split data\n```bash\nmousechd split_data \\\n -metafile \"DATA/processed/metadata.csv\" \\\n -outdir \"DATA/label\" \\\n -val_size 0.2\n```\n\n### (3) Train\n```bash\nmousechd train_clf \\\n -exp_dir \"OUTPUTS/Classifier\" \\\n -exp [EXPERIEMENT_NAME] \\\n -data_dir \"DATA/resampled\" \\\n -label_dir \"DATA/label/x5_base/1fold\" \\\n -epochs [NUM_EPOCHS]\n```\n\n### (4) Evaluate retrained model\n```bash\nmousechd test_clf \\\n -model_dir \"OUTPUTS/Classifier/<EXPERIMENT_NAME>\" \\\n -imdir \"DATA/processed/images\" \\\n -maskdir \"OUTPUTS/HeartSeg\" \\\n -stage [\"eval\"|\"test\"] \\\n -label [PATH/TO/CSV/TEST/FILE] \\ # <optional> if stage is \"eval\", -label must be specified\n -outdir [PATH/TO/OUTPUT/DIRECTORY]\n```\n\n</details>\n\n## GradCAM\n```bash\nmousechd explain \\\n-exp_dir \"OUTPUTS/Classifier/<EXPERIMENT_NAME>\" \\\n-imdir \"DATA/resampled/images\" \\\n-outdir [PATH/TO/OUTPUT/DIRECTORY]\n```\n\n## Analysis\nA detailed analysis can be found in the folder [analysis](./analysis/).\n\nFor some visualization, [Napari](https://napari.org/stable/) is required. To install: `pip install \"napari[all]\"`.\n\n\n## Acknowledgements\n* INCEPTION funding: [INCEPTION](https://www.inception-program.fr/en) \n* GPU server technical support: Quang Tru Huynh\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Segmenting hearts and screening congenital heart diseases in mice",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/hnguyentt/MouseCHD"
},
"split_keywords": [
"deep learning",
" image segmentation",
" image classification",
" medical image analysis",
" mousechd"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "632abd322148bd043bcf9aa7de78bad4c4c85cf10521e5eb54db68272549c2f8",
"md5": "5c8821984f92a78c90417a1093526ea1",
"sha256": "aa88f0f33cc62054d33d34533c909eabdc38076b292120d17e15a0bd49c28bec"
},
"downloads": -1,
"filename": "mousechd-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c8821984f92a78c90417a1093526ea1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 62108,
"upload_time": "2024-09-29T23:31:48",
"upload_time_iso_8601": "2024-09-29T23:31:48.650112Z",
"url": "https://files.pythonhosted.org/packages/63/2a/bd322148bd043bcf9aa7de78bad4c4c85cf10521e5eb54db68272549c2f8/mousechd-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-29 23:31:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hnguyentt",
"github_project": "MouseCHD",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mousechd"
}
JSON
