{"id":20881903,"url":"https://github.com/aiff22/deepcmorph","last_synced_at":"2025-04-11T01:02:35.806Z","repository":{"id":244473612,"uuid":"785237052","full_name":"aiff22/DeepCMorph","owner":"aiff22","description":"Histopathological Image Classification with Cell Morphology Aware Deep Neural Networks","archived":false,"fork":false,"pushed_at":"2024-06-17T23:33:31.000Z","size":609,"stargazers_count":16,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T01:02:30.173Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aiff22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-11T13:32:11.000Z","updated_at":"2025-02-28T14:59:33.000Z","dependencies_parsed_at":"2024-06-15T00:26:11.416Z","dependency_job_id":"3f5ffc3b-e40d-4310-91cc-683a2ceee5b6","html_url":"https://github.com/aiff22/DeepCMorph","commit_stats":null,"previous_names":["aiff22/deepcmorph"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiff22%2FDeepCMorph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiff22%2FDeepCMorph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiff22%2FDeepCMorph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aiff22%2FDeepCMorph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aiff22","download_url":"https://codeload.github.com/aiff22/DeepCMorph/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322597,"owners_count":21084336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-18T07:26:56.009Z","updated_at":"2025-04-11T01:02:35.777Z","avatar_url":"https://github.com/aiff22.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Histopathological Image Classification with Cell Morphology Aware Deep Neural Networks\n\n\u003cbr/\u003e\n\n\u003cimg src=\"http://people.ee.ethz.ch/~ihnatova/demo_deepcmorph/architecture.png\"/\u003e\n\n\u003cbr/\u003e\n\n#### 1. Overview [[Paper]](https://openaccess.thecvf.com/content/CVPR2024W/CVMI/papers/Ignatov_Histopathological_Image_Classification_with_Cell_Morphology_Aware_Deep_Neural_Networks_CVPRW_2024_paper.pdf)\n\nThis repository provides the implementation of the foundation **DeepCMorph CNN model** designed for histopathological image classification and analysis. Unlike the existing models, DeepCMorph explicitly **learns cell morphology**: its segmentation module is trained to identify different cell types and nuclei morphological features.\n\nKey DeepCMorph features:\n\n1. Achieves the state-of-the-art results on the **TCGA**, **NCT-CRC-HE** and **Colorectal cancer (CRC)** datasets\n2. Consists of two independent **nuclei segmentation / classification** and **tissue classification** modules\n3. The segmentation module is pre-trained on a combination of **8 segmentation datasets**\n4. The classification module is pre-trained on the **Pan-Cancer TCGA dataset** (8736 diagnostic slides / 7175 patients)\n5. Can be applied to images of **arbitrary resolutions**\n6. Can be trained or fine-tuned on **one GPU**\n\n\u003cbr/\u003e\n\n#### 2. Prerequisites\n\n- Python: numpy and imageio packages\n- [PyTorch + TorchVision](https://pytorch.org/) libraries\n- [Optional] Nvidia GPU\n\n\u003cbr/\u003e\n\n#### 3. Download Pre-Trained Models\n\nThe segmentation module of all pre-trained models is trained on a combination of 8 publicly available nuclei segmentation / classification datasets: **Lizard, CryoNuSeg, MoNuSAC, BNS, TNBC, KUMAR, MICCAI** and **PanNuke** datasets.\n\n| Dataset                     | #Classes | Accuracy | Download Link |\n|-----------------------------|----------|----------|---------------|\n| Combined [[TCGA](https://zenodo.org/records/5889558) + [NCT_CRC_HE](https://zenodo.org/records/1214456)]       | 41       | 81.59%   |  [Link](https://data.vision.ee.ethz.ch/ihnatova/public/DeepCMorph/DeepCMorph_Datasets_Combined_41_classes_acc_8159.pth)             |\n| [TCGA](https://zenodo.org/records/5889558) [Extreme Augmentations] | 32       | 82.00%   |  [Link](https://data.vision.ee.ethz.ch/ihnatova/public/DeepCMorph/DeepCMorph_Pan_Cancer_Regularized_32_classes_acc_8200.pth)             |\n| [TCGA](https://zenodo.org/records/5889558) [Moderate Augmentations] | 32       | 82.73%   |  [Link](https://data.vision.ee.ethz.ch/ihnatova/public/DeepCMorph/DeepCMorph_Pan_Cancer_32_classes_acc_8273.pth)             |\n| [NCT_CRC_HE](https://zenodo.org/records/1214456)                  | 9        | 96.99%   |  [Link](https://data.vision.ee.ethz.ch/ihnatova/public/DeepCMorph/DeepCMorph_NCT_CRC_HE_Dataset_9_classes_acc_9699.pth)             |\n\nDownload the required models and copy them to the ``pretrained_models/`` directory.\n\n\u003cbr/\u003e\n\n#### 4. Pre-Trained Model Usage\n\nIntegrating the DeepCMorph model into your project is extremely simple. The code below shows how to define, initialize and run the model on sample histopathological images: \n\n\n```python\nfrom model import DeepCMorph\n\n# Defining the model and specifying the number of target classes:\n# 41 for combined datasets, 32 for TCGA, 9 for CRC\nmodel = DeepCMorph(num_classes=41)\n\n# Loading model weights corresponding to the network trained on combined datasets\n# Possible 'dataset' values: TCGA, TCGA_REGULARIZED, CRC, COMBINED\nmodel.load_weights(dataset=\"COMBINED\")\n\n# Get the predicted class for a sample input image\npredictions = model(sample_image)\n_, predicted_class = torch.max(predictions.data, 1)\n\n# Get feature vector of size 2560 for a sample input image\nfeatures = model(sample_image, return_features=True)\n\n# Get predicted segmentation and classification maps for a sample input image\nnuclei_segmentation_map, nuclei_classification_maps = model(sample_image, return_segmentation_maps=True)\n```\n\nA detailed model usage example is additionally provided in the script ``run_inference.py``. It applies the pre-trained DeepCMorph model to 32 images from the TCGA dataset to generate 1) sample **classification predictions**, 2) **feature maps of dimension 2560** that can be used for classification with the SVM or other stand-alone model, 3) **nuclei segmentation / classification maps** generation and visualization. \n\n\u003cbr/\u003e\n\n#### 5. Fine-Tuning the Model\n\nThe following codes are needed to initialize the model for further fine-tuning: \n\n```python\nfrom model import DeepCMorph\n\n# Defining the model with frozen segmentation module (typical usage)\n# All weights of the classification module are trainable\nmodel = DeepCMorph(num_classes=...)\n\n# Defining the model with frozen segmentation and classificaton modules\n# Only last fully-connected layer would be trainable\nmodel = DeepCMorph(num_classes=..., freeze_classification_module=True)\n\n# Defining the model with all layers being trainable\nmodel = DeepCMorph(num_classes=..., freeze_segmentation_module=False)\n```\n\n\u003cbr/\u003e\n\n#### 6. Pre-Trained Model Evaluation\n\nFile ``validate_model.py`` contains sample codes needed for model evaluation on the **NCT-CRC-HE-7K** dataset. To check the model accuracy:\n\n1. Download the corresponding model weights\n2. Download the [NCT-CRC-HE-7K](https://zenodo.org/records/1214456) dataset and extract it to the ``data`` directory.\n3. Run the test script: ```python validate_model.py ```\n\nThe provided script can be also easily modified for other datasets.\n\n\u003cbr/\u003e\n\n\n#### 7. Folder structure\n\n\u003e```data/sample_TCGA_images/```        \u0026nbsp; - \u0026nbsp; the folder with sample TCGA images \u003cbr/\u003e\n\u003e```pretrained_models/```   \u0026nbsp; - \u0026nbsp; the folder with the provided pre-trained DeepCMorph models \u003cbr/\u003e\n\u003e```sample_visual_results/``` \u0026nbsp; - \u0026nbsp; visualization of the nuclei segmentation and classification maps\u003cbr/\u003e\n\n\u003e```model.py```           \u0026nbsp; - \u0026nbsp; DeepCMorph implementation [PyTorch] \u003cbr/\u003e\n\u003e```train_model.py```     \u0026nbsp; - \u0026nbsp; the script showing model usage on sample histopathological images \u003cbr/\u003e\n\u003e```validate_model.py```      \u0026nbsp; - \u0026nbsp; the script for model validation on the NCT-CRC-HE-7K dataset \u003cbr/\u003e\n\n\u003cbr/\u003e\n\n#### 8. License\n\nCopyright (C) 2024 Andrey Ignatov. All rights reserved.\n\nLicensed under the [CC BY-NC-SA 4.0 (Attribution-NonCommercial-ShareAlike 4.0 International)](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode).\n\nThe code is released for academic research use only.\n\n\u003cbr/\u003e\n\n#### 9. Citation\n\n```\n@inproceedings{ignatov2024histopathological,\n  title={Histopathological Image Classification with Cell Morphology Aware Deep Neural Networks},\n  author={Ignatov, Andrey and Yates, Josephine and Boeva, Valentina},\n  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition},\n  pages={6913--6925},\n  year={2024}\n}\n```\n\u003cbr/\u003e\n\n#### 10. Any further questions?\n\n```\nPlease contact Andrey Ignatov (andrey@vision.ee.ethz.ch) for more information\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiff22%2Fdeepcmorph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiff22%2Fdeepcmorph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiff22%2Fdeepcmorph/lists"}