{"id":18785300,"url":"https://github.com/andreped/dmdetect","last_synced_at":"2025-08-24T22:34:49.925Z","repository":{"id":109858431,"uuid":"350838738","full_name":"andreped/DMDetect","owner":"andreped","description":"Code relevant for training, evaluating, assessing, and deploying CNNs for image classification and segmentation of Digital Mammography images","archived":false,"fork":false,"pushed_at":"2023-03-31T09:53:20.000Z","size":404,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-23T18:48:28.317Z","etag":null,"topics":["breast-cancer","cnn-classification","deep-learning","digital-mammography","explainable-ai","keras-tensorflow","mammography","tensorflow2","tf-data","tfrecords"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andreped.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-03-23T19:50:24.000Z","updated_at":"2025-04-26T08:11:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"6bea8512-469a-4127-97bf-d856c96d91dc","html_url":"https://github.com/andreped/DMDetect","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/andreped/DMDetect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreped%2FDMDetect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreped%2FDMDetect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreped%2FDMDetect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreped%2FDMDetect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreped","download_url":"https://codeload.github.com/andreped/DMDetect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreped%2FDMDetect/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262543862,"owners_count":23326626,"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":["breast-cancer","cnn-classification","deep-learning","digital-mammography","explainable-ai","keras-tensorflow","mammography","tensorflow2","tf-data","tfrecords"],"created_at":"2024-11-07T20:46:13.935Z","updated_at":"2025-06-29T05:32:48.170Z","avatar_url":"https://github.com/andreped.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DMDetect\n[![license](https://img.shields.io/github/license/DAVFoundation/captain-n3m0.svg?style=flat-square)](https://github.com/DAVFoundation/captain-n3m0/blob/master/LICENSE)\n\nOpen-source project for training, evaluating, assessing and deploying Convolutional Neural Networks (CNNs) for multi-class image classification and segmentation of Digital Mammography (DM) images.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"figures/DM_segmentation_figure.png\" width=\"80%\" height=\"80%\"\u003e\n\u003c/p\u003e\n\nThe project and code is defined such that it should be easy to use out-of-the-box, given that the project structure is defined as [below](https://github.com/andreped/DMDetect/blob/main/README.md#project-structure).\nFor instance, I have tested the project both on a local Win10 machine and using Google Colab without any issues, see notebooks/ for jupyter notebook example(s).\n\nFor this project we have used TensorFlow 2.4 (with CUDA 11). This enabled us to experiment with TFRecords and tf.data.Dataset, which is suitable for efficient batch generation during training, as well as GPU-accelerated data augmentation.\n\n## Preliminary results\n\n#### Segmentation\n\nI've trained a ResU-Net++ model, inputting images of 1024x1024 (preserved aspect ratio, vertical axis as reference). The model is trained to perform multi-class semantic segmentation of cancer, mammary gland, pectoral muscle and nipple:\n\n| metrics | cancer | mammary gland | pectoral muscle | nipple | overall |\n|---------|--------|---------------|-----------------|--------|---------|\n|   DSC   | 0.279  |     0.976     |      0.946      | 0.474  |  0.669  |\n|   IOU   | 0.220  |     0.955     |      0.920      | 0.373  |  0.617  |\n\nDue to the downsampling of images, too much information is lost to produce satisfactory tumour segmentation (in terms on DSC/IOU). Improvements can be made by working patch-wise, working with full or higher resolution, but it might degrade performance on other classes, so it depends on the use case.\n\n\n#### Classification\n\nI've trained a CNN that detects images containing breast cancer tissue. We get quite good results, without really tuning the network or training for long. A summary of the results can be seen below:\n\n|    Classes   |  Precision  |  Recall  |  F1-score  |  Support |   \n| -------------|-------------|----------|------------|----------|\n|            0 |    0.99     |   0.98   |    0.98    |   9755   |\n|            1 |    0.88     |   0.90   |    0.89    |   1445   |\n|              |             |          |            |          |\n|   Accuracy   |             |          |    0.97    |  11200   |\n|  macro avg   |    0.93     |   0.94   |    0.94    |  11200   |\n| weighted avg |    0.97     |   0.97   |    0.97    |  11200   |\n\nReaching a macro-average F1-score of 0.94 is a good start.\n\n## Explainable AI (XAI)\n\nTo further assess the performance of the method, XAI was used (in this case [Grad-CAM](https://arxiv.org/abs/1610.02391), using this [repo](https://github.com/sicara/tf-explain)) to see if the method is doing what it should:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"figures/XAI_example.png\" width=\"70%\" height=\"70%\"\u003e\n\u003c/p\u003e\n\nFrom this figure, it seems like the model is reacting on the correct part of the image. However, overall the network seems biased towards \"always\" using the central part of the image, at least as a default, if nothing else is found. This might be suboptimal.\n\n## Open data sets:\n\n#### Classification\nThe data set used, **DDSM**, can be downloaded from [here](https://www.kaggle.com/skooch/ddsm-mammography/discussion/225969). When downloaded, uncompress and place the folder structure in the data/ folder (see Project structure [below](https://github.com/andreped/DMDetect/blob/main/README.md#project-structure)).\n\n#### Segmentation\nThe data set we used, **CSAW-S**, can be downloaded from [here](https://zenodo.org/record/4030660#.YHGTJOgzaiN). Place the uncompressed data into the data/ folder in the Project structure, such that the raw data is structured as such: data/CSAW-S/CSAW-S/CsawS/anonymized_dataset/.\n\n## How to use?\n\nGiven that you have: \n1. Created a virtual environent (not necessary, but smart to do)\n2. Installed all requirements\n3. Defined the project as [below](https://github.com/andreped/DMDetect/blob/main/README.md#project-structure)\n4. Placed the uncompressed data set in the data/ folder\n\n...you should be all set. If you are using **Google Colab**, see jupyter notebook examples in notebooks/ for more information.\n\n#### Classification\nIn this case, we are using the [DDSM Kaggle data set](https://www.kaggle.com/skooch/ddsm-mammography), which has already been preprocessed in a format which can be processed on-the-fly in the batch generator. Thus, simply train a CNN classifier running the train.py script: \n```\npython train.py\n```\n\nWhen a model is ready (see output/models/), it can be evaluated using the eval.py script, which will return summary performance results, as well as the option to further assess the model using XAI.\n```\npython eval.py\n```\n\n#### Segmentation\nIn this case, we are using the [CSAW-S](https://zenodo.org/record/4030660#.YHGTJOgzaiN) data set. As the data is not preprocessed, it is necessary to do that first:\n```\npython create_data.py\n```\n\nThen simply train a deep segmentation model running:\n```\npython train_seg.py\n```\n\nTo evaluate the model, as well as the option to view results, run:\n```\npython eval_seg.py\n```\n\n## Project structure\n\n```\n+-- {DMDetect}/\n|   +-- python/\n|   |   +-- create_data.py\n|   |   +-- train.py\n|   |   +-- [...]\n|   +-- data/\n|   |   +-- folder_containing_the_unzipped_kaggle_dataset/\n|   |   |   +-- fold_name0/\n|   |   |   +-- fold_name1/\n|   |   |   +-- [...]\n|   |   +-- folder_containing_csaw-s_dataset/\n|   |   |   +-- [...]\n|   +-- output/\n|   |   +-- history/\n|   |   |   +--- history_some_run_name1.txt\n|   |   |   +--- history_some_run_name2.txt\n|   |   |   +--- [...]\n|   |   +-- models/\n|   |   |   +--- model_some_run_name1.h5\n|   |   |   +--- model_some_run_name2.h5\n|   |   |   +--- [...]\n```\n\n## TODOs (most important from top to bottom):\n\n- [x] Setup batch generation through TFRecords for GPU-accelerated generation and data augmentation\n- [x] Introduce smart losses and metrics for handling class-imbalance \n- [x] Make end-to-end pipeline for automatic DM assessment\n- [x] Achieve satisfactory classification performance\n- [x] Introduce XAI-based method to further assess classifier\n- [x] Test MTL design on the multi-classification tasks\n- [x] Made proper support for MIL classifiers, that works both during training and inference \n- [x] Fix data augmentation scheme in the get_dataset method\n- [x] Updated paths to be more generic\n- [x] Added Jupyter Notebook relevant for deployment on Google Colab\n- [x] Get access to semantically annotated data of breast cancer\n- [x] Setup full pipeline for training and evaluating segmentation models\n- [x] Add Jupyter Notebook example for training segmentation models using Google Colab\n- [x] Find the optimal set of augmentation methods for both tasks\n- [ ] Get access to raw DM images, and test the pipeline across the full image (model trained on patches)\n- [ ] Extract the distrbution between the 5 classes (classification task), to be used for balancing classes during training\n- [ ] Introduce ROC-curves and AUC as additional metric for evaluating performance\n- [ ] Make simple script for plotting losses and metrics as a function of epochs, using the CSV history\n- [ ] Add option to set arguments for training/evaluation using [argparse](https://docs.python.org/3/library/argparse.html) or similar\n\n## Tips\n\nMake virtual environment (Not necessary):\\\n`virtualenv -ppython3 venv --clear`\n\nActivating virtual environment:\\\nOn Win10: `.\\venv\\Scripts\\activate.ps1`\\\nOn Linux: `source venv/bin/activate`\n\nDeactivating virtual environment:\\\n`deactivate`\n\nInstall dependencies from requirements file:\\\n`pip install -r requirements.txt`\n\nUpdating requirements.txt file:\\\n`pip freeze \u003e requirements.txt`\n\n------\n\nMade with :heart: and python\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreped%2Fdmdetect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreped%2Fdmdetect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreped%2Fdmdetect/lists"}