{"id":22118061,"url":"https://github.com/sanderlab/cellbox","last_synced_at":"2025-07-25T12:31:32.004Z","repository":{"id":38413619,"uuid":"203857779","full_name":"sanderlab/CellBox","owner":"sanderlab","description":"CellBox: Interpretable Machine Learning for Perturbation Biology","archived":false,"fork":false,"pushed_at":"2023-07-27T17:33:41.000Z","size":94240,"stargazers_count":53,"open_issues_count":16,"forks_count":23,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T06:51:18.853Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/sanderlab.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}},"created_at":"2019-08-22T19:14:11.000Z","updated_at":"2025-02-02T09:22:26.000Z","dependencies_parsed_at":"2023-02-18T00:46:07.061Z","dependency_job_id":"dfa647f4-b065-40a0-88e7-7109f766db49","html_url":"https://github.com/sanderlab/CellBox","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/sanderlab/CellBox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanderlab%2FCellBox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanderlab%2FCellBox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanderlab%2FCellBox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanderlab%2FCellBox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sanderlab","download_url":"https://codeload.github.com/sanderlab/CellBox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanderlab%2FCellBox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267007440,"owners_count":24020257,"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","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-12-01T13:43:36.587Z","updated_at":"2025-07-25T12:31:26.948Z","avatar_url":"https://github.com/sanderlab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca target=\"_blank\" href=\"https://colab.research.google.com/github/sanderlab/CellBox/blob/master/notebooks/cellbox_example_tf2.ipynb\"\u003e\n  \u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/\u003e\n\u003c/a\u003e\n\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/sanderlab/CellBox/9d13f3354f8b14bd896de6c8aa5db0b97c65ad12)\n\n# CellBox\n\n## Abstract\nSystematic perturbation of cells followed by comprehensive measurements of molecular and phenotypic responses provides informative data resources for constructing computational models of cell biology. Models that generalize well beyond training data can be used to identify combinatorial perturbations of potential therapeutic interest. Major challenges for machine learning on large biological datasets are to find global optima in a complex multi-dimensional space and mechanistically interpret the solutions. To address these challenges, we introduce a hybrid approach that combines explicit mathematical models of cell dynamics with a machine learning framework, implemented in TensorFlow. We tested the modeling framework on a perturbation-response dataset of a melanoma cell line after drug treatments. The models can be efficiently trained to describe cellular behavior accurately. Even though completely data-driven and independent of prior knowledge, the resulting de novo network models recapitulate some known interactions. The approach is readily applicable to various kinetic models of cell biology. \n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://lh3.googleusercontent.com/d/15Lildcx8sC4shTalODLXqfibJTbnxmun=w600\"\u003e\n\u003c/p\u003e\n\n## Citation and Correspondence\n\nThis is CellBox scripts developed in Sander lab for the paper in _[Cell Systems](https://www.cell.com/cell-systems/pdfExtended/S2405-4712(20)30464-6)_ or [bioRxiv](https://www.biorxiv.org/content/10.1101/746842v3).\n\n\u003eYuan, B.*, Shen, C.*, Luna, A., Korkut, A., Marks, D., Ingraham, J., Sander, C. CellBox: Interpretable Machine Learning for Perturbation Biology with Application to the Design of Cancer Combination Therapy. _Cell Systems_, 2020. \n\nMaintained by Bo Yuan, Judy Shen, and Augustin Luna.\n\nIf you want to discuss the usage or to report a bug, please use the 'Issues' function here on GitHub.\n\nIf you find `CellBox` useful for your research, please consider citing the corresponding publication.\n\nFor more information, please find our contact information [here](https://www.sanderlab.org/#/).\n\n# Quick Start\n\nEasily try `CellBox` online with Binder \n\n1. Go to: https://mybinder.org/v2/gh/sanderlab/CellBox/9d13f3354f8b14bd896de6c8aa5db0b97c65ad12\n2. From the New dropdown, click Terminal \n3. Run the following command for a short example of model training process: \n\n```\npython scripts/main.py -config=configs/Example.random_partition.json\n```\n\nAlternatively, in project folder, do the same command\n\n# Installation\n\n## Install using pip \nBefore installing CellBox, it is good practice to create a Python virtual environment. With conda, `conda create -n “cellbox” python==3.8.0` creates a conda environment with the name `cellbox` and Python 3.8.0. Activate the environment by `conda activate cellbox`. \n\nTo install CellBox to a particular folder, type the following:\n\n```\ngit clone https://github.com/sanderlab/CellBox.git \u003cfolder_name\u003e\ncd /\u003cfolder_name\u003e/cellbox\npip install .\n```\n\nIf you only want to install CellBox from a particular branch, the following command will install cellbox from a particular branch using the '@' notation:\n\n```\npip install git+https://github.com/sanderlab/CellBox.git@cell_systems_final#egg=cellbox\\\u0026subdirectory=cellbox\n```\n\n## Install using setup.py (setup.py install has been deprecated in newer Python versions)\nClone repository and in the `cellbox` folder run:\n\n```\npython3.6 setup.py install\n```\n\nOnly python3.6 supported. Anaconda or pipenv is recommended to create python environment. \n\nNow you can test if the installation is successful\n\n```\nimport cellbox\ncellbox.VERSION\n```\n\n# Project Structure\n\n## Data files: in ./data/ folder in GitHub repo used for example\nThese data files are used for generating the results from the official CellBox paper. Replace these files with your own data.\n* `node_index.csv`: names of each protein/phenotypic node.\n* `expr_index.txt`: information each perturbation condition. This is one of the original data files we downloaded from [paper](https://elifesciences.org/articles/04640) and is only used here as a reference for the condition names. In other words the 2nd and 3rd columns are not being used in CellBox.\n* `loo_label.csv`: A deprecated csv file that stores the actual indexing of perturbation targets, used in the original paper. There are 89 rows corresponding to 89 drug combinations. On each row, two numbers denote the index of one of 12 drugs for that combination. Number 0 denotes no drug, meaning rows with 0 denote single-target drugs.\n* `expr.csv`: Protein expression data from RPPA for the protein nodes and phenotypic node values. Each row is a condition while each column is a node.\n* `pert.csv`: Perturbation strength and target of all perturbation conditions. Used as input for differential equations.\n* `expr_subset.npz` and `pert_subset.npz`: A subset of `expr.csv` and `pert.csv` (clarification needed).\n\n## cellbox package:\n* `CellBox` is defined in `model.py`\n* A `dataset.factory()` function for random parition, leave-one-out, and single-to-combo tasks.\n* A multiple-substage training process for finding the optimal hyperparameters defined in `train.py`.\n\n## One click model construction\n\n### __Step 1: Create experiment json files (some examples can be found under ./configs/)__\n* Make sure to specify the experiment_id and experiment_type\n\t* `experiment_id`: name of the experiments, would be used to generate results folders\n\t* `experiment_type`: currently available tasks are {\"random partition\", \"leave one out (w/o single)\", \"leave one out (w/ single)\", \"full data\", \"single to combo\"}\n* Different training stages can be specified using `stages` and `sub_stages` in config file\n* Other default configurations are defined in `config.py`\n\n### __Step 2: Use main.py to construct models using random partition of dataset__\n\nThe experiment type configuration file is specified by `--experiment_config_path` or `-config`\n\n```\npython scripts/main.py -config=configs/Example.random_partition.json\n```\n\nNote: always run the script in the root folder.\n\n\nA random seed can also be assigned by using argument `--working_index` or `-i`\n\n```\npython scripts/main.py -config=configs/Example.random_partition.json -i=1234\n```\n\n\nWhen training with leave-one-out validation, make sure to specify the drug index `--drug_index` or `-drug` to leave out from training.\n\n\n### __Step 3: Analyze result files__\n* You should see a experiment folder generated under `/results` using the date and `experiment_id`.\n* Under experiment folder, you would see different models run with different random seeds\n* Under each model folder, you would have:\n\t* `record_eval.csv`: log file with loss changes and time used.\n\t* `random_pos.csv`: how the data was split (only for random partitions)\n\t* `best.W`, `best.alpha`, `best.eps`: model parameters snapshot for each training stage\n\t* `best.test_hat`: Prediction on test set, using the best model for each stage\n\t* `.ckpt` files are the final models in tensorflow compatible format.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanderlab%2Fcellbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanderlab%2Fcellbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanderlab%2Fcellbox/lists"}