{"id":26786839,"url":"https://github.com/marrlab/scemila","last_synced_at":"2025-04-19T19:34:26.396Z","repository":{"id":112117166,"uuid":"388514844","full_name":"marrlab/SCEMILA","owner":"marrlab","description":"Single cell based explainable multiple instance learning algorithm (SCEMILA) for genetic acute myeloid leukemia subtype classification. ","archived":false,"fork":false,"pushed_at":"2023-03-16T21:02:34.000Z","size":78076,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T12:16:57.986Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marrlab.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,"zenodo":null}},"created_at":"2021-07-22T15:42:43.000Z","updated_at":"2025-02-23T15:24:39.000Z","dependencies_parsed_at":"2023-05-05T14:01:28.019Z","dependency_job_id":null,"html_url":"https://github.com/marrlab/SCEMILA","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSCEMILA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSCEMILA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSCEMILA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marrlab%2FSCEMILA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marrlab","download_url":"https://codeload.github.com/marrlab/SCEMILA/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249780486,"owners_count":21324555,"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":"2025-03-29T12:17:01.743Z","updated_at":"2025-04-19T19:34:26.383Z","avatar_url":"https://github.com/marrlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SCEMILA - README\n\nWelcome to the Github repository supplementing the publication \"Explainable AI identifies diagnostic cells of genetic AML subtypes.\" (Hehr M, Sadafi A, Matek C, Lienemann P, Pohlkamp C, et al. (2023) PLOS Digital Health 2(3): e0000187. https://doi.org/10.1371/journal.pdig.0000187). \n\n## Table of contents\n1. Description\n\n2. Getting started\n\n    2.1 Data\n\n    2.2 Dependencies   \n    \n    2.3 Code setup\n    \n    2.4 Execution\n\n    2.5 Analysis\n\n3. Authors\n4. Acknowledgements\n5. License\n\n\n# 1. Description\n## About\nThis Repository contains both the machine learning algorithm and the necessary functions to analyze and plot the figures published in the paper \"Explainable AI identifies diagnostic cells of genetic AML subtypes.\" (Hehr M, Sadafi A, Matek C, Lienemann P, Pohlkamp C, et al. (2023) PLOS Digital Health 2(3): e0000187. https://doi.org/10.1371/journal.pdig.0000187).\n\n## Contact\nFor questions and issues regarding the code, feel free to contact [Matthias Hehr](https://www.linkedin.com/in/matthias-hehr/). Otherwise, please reach out to the corresponding authors.  \n\n# 2. Getting started\n\n## 2.1 Data\nTo reproduce results, download the data and unzip it. The publication of our dataset is currently in progress, the data will be available at [The Cancer Imaging Archive (TCIA):](https://www.cancerimagingarchive.net/) https://doi.org/10.7937/6ppe-4020\n\n\n## 2.2 Dependencies\nThe pipeline and corresponding analysis requires a python environment with various packages. The [requirements file](requirements.txt) will be of help to build a functioning python environment. \n\n## 2.3 Code setup\nOnce the library is built and the dataset is downloaded, adjust the paths for the dataset and output folder in the file [run_pipeline.py](ml_pipeline/run_pipeline.py). \nLocate your dataset and create an output folder to store the results, afterwards change the lines \n\n```python\n# 1: Setup. Source Folder is parent folder for both mll_data_master and the /data folder\nTARGET_FOLDER = 'result_directory'       # results will be stored here\nSOURCE_FOLDER = 'data_directory'         # path to dataset\n```  \nOnce the algorithm has been trained, the paths have to be adjusted similarly in the [analysis notebook](analysis/analysis_notebook.ipynb).\n\n## 2.4 Execution\nTo start the pipeline, navigate to the folder [ml_pipeline](ml_pipeline) and load your environment. Train the algorithm for one fold by executing:\n\n```\npython3 run_pipeline.py --result_folder=result_folder_1\n```\nThis will create a new folder in your directory `TARGET_FOLDER` called `result_folder_1` which will contain all relevant data generated during training, validation and testing. Important: the argument `--result_folder` has to be set, otherwise the script will not run. While the algorithm is configured to run with the same parameters used in the paper, many arguments can be manipulated, altering the training process:\n|Argument|Description|Possible input|Default|\n|---|---|---|---|\n|`--fold`|Change this parameter to rotate through different folds of cross validation.For 5-fold cross validation (default), simply launch the code five times, every time with a different value for `--fold` in range of [0,1,2,3,4]|Integer, suggested: [0,1,2,3,4]|0|\n|`--lr`|Learning rate|Float|0.00005|\n|`--ep`|Maximum epochs to train for, until training stops|Integer|150|\n|`--es`|Early stopping. Amount of epochs to keep training, while no improvement on the validation loss is made. |Integer|20|\n|`--multi_att`|Enable multiple attention values for each image (one value per image, per possible class) as suggested in our paper.|Integer (0=False, 1=True)|1|\n|`--prefix`|The prefix defines the set of features that should be loaded. If an own method for feature extraction is generated and the features are saved in the dataset folder, change this value to make use of the newly generated features.|String|fnl34_|\n|`--filter_diff`|Filter out patients based on the amount of myeloblasts derived from human blood smear differential count (data stored the dataset master csv file). Value represents % of cells, patients with less (\u003c) myeloblasts are filtered out.|Integer|20|\n|`--filter_mediocre_quality`|Filter out patients with borderline acceptable sample quality. This data is derived from cytologist assessment of the digitized samples. |Integer (0=False, 1=True)|0|\n|`--bootstrap_idx`|For further experiments: Integer value, which is responsible for dropping out a specific patient from the dataset. Setting this to -1 deactivates the mechanism. |Integer|-1|\n|`--save_model`|Deactivate model saving to save storage (e.g. if only accuracy is relevant). The model file is required to generate the occlusion maps, so deactivating will prevent generating the data used for the occlusion maps. |Integer (0=False, 1=True)|1|\n\n## 2.5 Analysis\nTo analyze the data generated and take a look at various visualizations, use the [analysis notebook](analysis/analysis_notebook.ipynb) and adjust the corresponding paths as mentioned in 2.3 (Code Setup).\n\nThe notebook is designed to simplify analysis of the results generated with the pipeline, by automated plotting of most of the figures published in the paper. These figures are then exported directly into the [output folder](analysis/output).\nThe last sections of our notebook require large amounts of RAM (we recommend 32GB), otherwise the pythonkernel might crash. \n\n# 3. Authors\nMajor contributions were made by the following people:\n\nMatthias Hehr\u003csup\u003e1,2,3\u003c/sup\u003e, Ario Sadafi\u003csup\u003e1,2,4\u003c/sup\u003e, Christian Matek\u003csup\u003e1,2,3\u003c/sup\u003e, Peter Lienemann\u003csup\u003e1,3\u003c/sup\u003e, Christian Pohlkamp\u003csup\u003e5\u003c/sup\u003e, Torsten Haferlach\u003csup\u003e5\u003c/sup\u003e, Karsten Spiekermann\u003csup\u003e3,6,7\u003c/sup\u003e and Carsten Marr\u003csup\u003e1,2,*\u003c/sup\u003e\n\n\u003csup\u003e1\u003c/sup\u003eInstitute of AI for Health, Helmholtz Zentrum München – German Research Center for Environmental Health, Neuherberg, Germany\n\u003csup\u003e2\u003c/sup\u003eInstitute of Computational Biology, Helmholtz Zentrum München – German Research Center for Environmental Health, Neuherberg, Germany\n\u003csup\u003e3\u003c/sup\u003eLaboratory of Leukemia Diagnostics, Department of Medicine III, University Hospital, LMU Munich, Munich, Germany\n\u003csup\u003e4\u003c/sup\u003eComputer Aided Medical Procedures, Technical University of Munich, Munich, Germany\n\u003csup\u003e5\u003c/sup\u003eMunich Leukemia Laboratory, Munich, Germany\n\u003csup\u003e6\u003c/sup\u003eGerman Cancer Consortium (DKTK), Heidelberg, Germany\n\u003csup\u003e7\u003c/sup\u003eGerman Cancer Research Center (DKFZ), Heidelberg, Germany\n\u003csup\u003e*\u003c/sup\u003eCorresponding author: carsten.marr@helmholtz-muenchen.de\n\n\n\n# 4. Acknowledgements\nM.H. was supported by a José-Carreras-DGHO-Promotionsstipendium. C.M. has received funding from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation program (Grant agreement No. 866411)\n\n# 5. License\n[See the license](LICENSE). If you use this code, please cite our original paper:\n\nHehr M, Sadafi A, Matek C, Lienemann P, Pohlkamp C, et al. (2023) Explainable AI identifies diagnostic cells of genetic AML subtypes. PLOS Digital Health 2(3): e0000187. https://doi.org/10.1371/journal.pdig.0000187\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarrlab%2Fscemila","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarrlab%2Fscemila","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarrlab%2Fscemila/lists"}