{"id":28901144,"url":"https://github.com/yuhui-zh15/cellflux","last_synced_at":"2025-07-22T11:05:03.823Z","repository":{"id":278821511,"uuid":"936882835","full_name":"yuhui-zh15/CellFlux","owner":"yuhui-zh15","description":"Official implementation of \"CellFlux: Simulating Cellular Morphology Changes via Flow Matching\" (ICML 2025)","archived":false,"fork":false,"pushed_at":"2025-07-08T22:52:20.000Z","size":20592,"stargazers_count":5,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-08T23:33:15.482Z","etag":null,"topics":["ai-for-science","cell-imaging","computer-vision","generative-models","machine-learning"],"latest_commit_sha":null,"homepage":"https://yuhui-zh15.github.io/CellFlux/","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/yuhui-zh15.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":"2025-02-21T21:23:51.000Z","updated_at":"2025-07-08T22:52:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"b19bca04-8727-4f52-b6d9-c2894f8546c6","html_url":"https://github.com/yuhui-zh15/CellFlux","commit_stats":null,"previous_names":["yuhui-zh15/cellflow","yuhui-zh15/cellflux"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yuhui-zh15/CellFlux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuhui-zh15%2FCellFlux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuhui-zh15%2FCellFlux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuhui-zh15%2FCellFlux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuhui-zh15%2FCellFlux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuhui-zh15","download_url":"https://codeload.github.com/yuhui-zh15/CellFlux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuhui-zh15%2FCellFlux/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266481732,"owners_count":23935938,"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-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"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":["ai-for-science","cell-imaging","computer-vision","generative-models","machine-learning"],"created_at":"2025-06-21T10:03:33.685Z","updated_at":"2025-07-22T11:05:03.817Z","avatar_url":"https://github.com/yuhui-zh15.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CellFlux: Simulating Cellular Morphology Changes via Flow Matching\n\n\u003c!-- ⚠️⚠️⚠️**Repo Under Construction**⚠️⚠️⚠️ --\u003e\n\n[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)\n[![Python](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-311/)\n[![Pytorch](https://img.shields.io/badge/Pytorch-2.5-red.svg)](https://pytorch.org/get-started/previous-versions/#v25)\n[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\nThis repo provides the PyTorch source code of our paper: [CellFlux: Simulating Cellular Morphology Changes via Flow Matching](https://arxiv.org/pdf/2502.09775) (ICML 2025). Check out project page [here](https://yuhui-zh15.github.io/CellFlux/)!\n\n## 🔮 Abstract\n\nBuilding a virtual cell capable of accurately simulating cellular behaviors in silico has long been a dream in computational biology. We introduce CellFlux, an image-generative model that simulates cellular morphology changes induced by chemical and genetic perturbations using flow matching. Unlike prior methods, CellFlux models distribution-wise transformations from unperturbed to perturbed cell states, effectively distinguishing actual perturbation effects from experimental artifacts such as batch effects—a major challenge in biological data. Evaluated on chemical (BBBC021), genetic (RxRx1), and combined perturbation (JUMP) datasets, CellFlux generates biologically meaningful cell images that faithfully capture perturbation-specific morphological changes, achieving a 35% improvement in FID scores and a 12% increase in mode-of-action prediction accuracy over existing methods. Additionally, CellFlux enables continuous interpolation between cellular states, providing a potential tool for studying perturbation dynamics. These capabilities mark a significant step toward realizing virtual cell modeling for biomedical research.\n\n\u003cimg src=\"data/teaser.png\"\u003e\u003c/img\u003e\n**Overview of CellFlux.**\n(a) Objective. CellFlux aims to predict changes in cell morphology induced by chemical or gene perturbations in silico. In this example, the perturbation effect reduces the nuclear size. \n(b) Data. The dataset includes images from high-content screening experiments, where chemical or genetic perturbations are applied to target wells, alongside control wells without perturbations. Control wells provide prior information to contrast with target images, enabling the identification of true perturbation effects (e.g., reduced nucleus size) while calibrating non-perturbation artifacts such as batch effects—systematic biases unrelated to the perturbation (e.g., variations in color intensity). \n(c) Problem formulation. We formulate the task as a distribution-to-distribution problem (many-to-many mapping), where the source distribution consists of control images, and the target distribution contains perturbed images within the same batch. \n(d) Flow matching. CellFlux employs flow matching, a state-of-the-art generative approach for distribution-to-distribution problems. It learns a neural network to approximate a velocity field, continuously transforming the source distribution into the target by solving an ordinary differential equation (ODE). \n(e) Results. CellFlux significantly outperforms baselines in image generation quality, achieving lower Fr´echet Inception Distance (FID) and higher classification accuracy for mode-of-action (MoA) predictions.\n\n\n## 🛠️ CellFlux Methods\n\nUse ```bash example.sh``` to try our CellFlux methods!\n\n## 💎 Capabilities\n\nCellFlux enables accurate prediction of perturbation response, achieving tate-of-the-art performance on various datasets.\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"data/main_comparison.png\" width=\"80%\"\u003e\n\u003c/div\u003e\n\nCellFlux unlocks new capa-bilities such as handling batch effects or visualizing cellular state transitions, significantly advancing the field towards a virtual cell for drug discovery and personalized therapy.\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"data/interpolation.png\" width=\"80%\"\u003e\n\u003c/div\u003e\n\n## 🚀 Usage\n\n### Environment\n\nCreate and activate the conda environment using the provided environment file:\n\n```bash\nconda env create -f environment.yml\nconda activate cellflux\n```\n\n### Data\n\nThree datasets (BBBC021, RxRx1, and JUMP/CPG0000) used in this project are same as [IMPA](https://github.com/theislab/IMPA). Pre-processed data are made available [here](https://zenodo.org/record/8307629).\n\nAdditionally, for RxRx1 and CPG0000, evaluation is performed on 100 random selected perturbations. The data index CSV files for evaluation can be downloaded from [Huggingface](https://huggingface.co/suyc21/CellFlux). \n\nIn our implementation, we combined all the perturbation embeddings in CPG0000. The `combined_embeddings.csv` also needs to be downloaded [here](https://huggingface.co/suyc21/CellFlux). \n\n\n### Running CellFlux\n\n#### 1. Configuration Setup\n\nBefore running CellFlux, update the configuration files in the `configs/` directory with your local paths:\n\nFor each dataset configuration file (`bbbc021_all.yaml`, `rxrx1.yaml`, `cpg0000.yaml`), update the following paths:\n\n```yaml\n# DIRECTORIES FOR DATA\nimage_path: /path/to/your/datasets/[dataset_name]\ndata_index_path: /path/to/your/datasets/[dataset_name]/metadata/[metadata_file].csv\nembedding_path: /path/to/your/datasets/embeddings/[embedding_file].csv\n```\n\n#### 2. Training\n\n**Quick Start with Example Script:**\n```bash\nbash scripts/example.sh\n```\n\n**Using Slurm for Distributed Training:**\n```bash\n# For BBBC021 dataset\nbash scripts/slurm_bbbc021.sh\n\n# For RxRx1 dataset  \nbash scripts/slurm_rxrx1.sh\n\n# For CPG0000 dataset\nbash scripts/slurm_cpg0000.sh\n```\n\n\n#### 3. Evaluation with Pre-trained Checkpoints\n\nPretrained model checkpoints are provided at [Huggingface](https://huggingface.co/suyc21/CellFlux).\n\nTo quickly evaluate with specific checkpoints and generate images:\n\n```bash\n# Evaluate BBBC021\nbash scripts/slurm_eval_bbbc021.sh\n\n# Evaluate RxRx1\nbash scripts/slurm_eval_rxrx1.sh\n\n# Evaluate CPG0000\nbash scripts/slurm_eval_cpg0000.sh\n```\n\nThese scripts will:\n- Load the specified checkpoint\n- Generate sample images\n- Calculate overall FID scores\n- Save results to the given directory\n\n#### 4. Detailed FID and KID Evaluation\nFor comprehensive evaluation metrics including detailed FID and KID results:\n\n```bash\nbash scripts/eval_fid.sh\n```\n\nThis script will compute:\n- Fréchet Inception Distance (FID)\n- Kernel Inception Distance (KID)\n- Detailed per-class metrics\n\n\n## 🎯 Citation\n\nIf you use this repo in your research, please cite it as follows:\n```\n@inproceedings{CellFlux,\n  title={CellFlux: Simulating Cellular Morphology Changes via Flow Matching},\n  author={Zhang, Yuhui and Su, Yuchang and Wang, Chenyu and Li, Tianhong and Wefers, Zoe and Nirschl, Jeffrey and Burgess, James and Ding, Daisy and Lozano, Alejandro and Lundberg, Emma and Yeung-Levy, Serena},\n  booktitle={International Conference on Machine Learning (ICML)},\n  year={2025}\n}\n```\n\n## Acknowledgements\n\nThis repository is built upon the [Flow Matching](https://github.com/facebookresearch/flow_matching) framework. We gratefully acknowledge their foundational work that made this project possible.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuhui-zh15%2Fcellflux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuhui-zh15%2Fcellflux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuhui-zh15%2Fcellflux/lists"}