GENESIS / README.md

Card: downloads are gated; request access, then hf auth login

6189cc9 verified 7 days ago

5.54 kB

---
license: other
license_name: cc-by-4.0-and-cc-by-nc-4.0
license_link: LICENSE.md
tags:
- biology
- single-cell
- perturbation
---
# GENESIS

GENESIS (Generative ENErgy-based Single-cell Intervention Simulator) generates the single-cell RNA profiles of a
perturbation in a biological context it was never measured in. These are the trained models behind the paper
*Single-cell perturbation prediction near experimental reproducibility with GENESIS*. The code is at
[github.com/rickconci/GENESIS](https://github.com/rickconci/GENESIS), and the published scores are at
[RConci/GENESIS_results](https://huggingface.co/datasets/RConci/GENESIS_results).

## Start here: two models

| Folder | Data | Predicts |
|---|---|---|
| `tahoe/` | Tahoe-100M: 50 cancer cell lines × drugs | a drug's effect in 5 cell lines held out of training |
| `pbmc/` | Parse PBMC cytokine atlas: 12 donors × 90 cytokines | a cytokine's effect in 4 donors held out of training |

Downloads are gated: request access on this page, then log in once with `hf auth login` (a token from
[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)). Inside a clone of the code
(`uv sync --extra model`), download one model and generate cells for its test conditions:

```bash
uvx --from huggingface_hub hf download RConci/GENESIS --include 'tahoe/*' --exclude '*/split_cache/*' --local-dir models
uv run python scripts/eval/generate.py conditions --run-dir "$PWD/models/tahoe" --out-dir results/generated/tahoe --limit 10
```

Each condition is written as one `.npz` file holding `predictions` (cells x 2,000 genes, log1p), `gene_names` and the
condition's values. This needs a CUDA GPU and no dataset.

## Reproduce the paper's figures: `reproduce/`

The folders are arranged by the figure that first uses them, as in the code's `scripts/figures/figureN/`. Download
everything with `hf download RConci/GENESIS --local-dir models`; each figure's `score.sh` then finds its models by
these names.

| Folder | Figure | Trained on | Seeds |
|---|---|---|---|
| `tahoe/`, `pbmc/` | 2 | all training conditions (5 epochs) | 0 |
| `reproduce/figure2/tahoe_perturbation_split/` | 2 (ED) | Tahoe: a held-out drug is seen in 1-20 other lines; test = 40 drugs × 30 lines × 3 doses | 0 |
| `reproduce/figure2/pbmc_perturbation_split/` | 2 (ED) | PBMC: a held-out cytokine is seen in 1-5 other donors; test = 30 cytokines × 7 donors | 0 |
| `reproduce/figure3/scaling/full_seed{1,2}/` | 3a | as `tahoe/`, with other model seeds; seed 0 of this point is `tahoe/` itself | 1, 2 |
| `reproduce/figure3/scaling/conditions{25,5}_seed{0,1,2}/` | 3a | 25% or 5% of the training conditions (11 or 25 epochs) | 0, 1, 2 |
| `reproduce/figure3/scaling/cells{25,5}_seed{0,1,2}/` | 3a | every condition, 25% or 5% of its perturbed cells, every control (11 or 25 epochs) | 0, 1, 2 |
| `reproduce/figure3/overlap/row{0-4}_seed{0,1,2}/` | 3b | 5 held-out lines, each seeing 0, 15, 30, 80 or 164 drugs in training (one Latin-square row per folder; 15 epochs) | 0, 1, 2 |
| `reproduce/figure4/progeny_5pct_cells/` | 4 | as `cells5`, on 3,072 genes: the 2,000 plus the PROGENy pathway genes, padded with 6 placeholders | 0 |
| `reproduce/figure4/hallmark_15pct_conditions/` | 4 (ED) | 15% of the training conditions, on 5,750 genes: the 2,000 plus the MSigDB Hallmark genes | 0 |

Every Tahoe model above, except the perturbation split, is tested on the same 5 held-out cell lines as `tahoe/`. In
`scaling/`, seed n draws the training subset and initialises the model. In `overlap/`, it draws which drugs each line
sees, and every model starts from the same initialisation.

## What a model folder holds

| File | What it is |
|---|---|
| `checkpoints/last.ckpt` | the PyTorch Lightning checkpoint: weights, optimizer state, the full training config |
| `config_resolved.yaml` | every training setting, as the run used it |
| `encoder_idx_to_name.json` | the cell lines, drugs, doses, plates, donors or cytokines the model can condition on |
| `output_gene_names.txt` | the genes it predicts, in output order |
| `eval/eval_manifest.json`, `eval/condition_summary.parquet` | the test split and the cells measured per condition |
| `split_cache/train_idx.npy` | the dataset rows it trained on (only needed to recount training data) |
| `run.log` | the training log |
| `hbss_meta.json`, `hbss_selected_triplets.parquet` | for subsampled runs: which training conditions were kept |

## Licence

Each model carries the licence of the data it was trained on ([LICENSE.md](LICENSE.md)):

| Folders | Trained on | Licence |
|---|---|---|
| every folder with `pbmc` in its path (`pbmc/`, `reproduce/figure2/pbmc_perturbation_split/`) | the Parse PBMC cytokine atlas, CC BY-NC 4.0 | [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use, with credit |
| every other folder | Tahoe-100M, CC0 1.0 | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): any use, with credit |

Credit means citing the GENESIS paper, plus the dataset a model was trained on. The code is MIT-licensed.

## Data

- Zhang J. *et al.* Tahoe-100M: A Giga-Scale Single-Cell Perturbation Atlas for Context-Dependent Gene Function and
  Cellular Modeling. *bioRxiv* (2025). [doi:10.1101/2025.02.20.639398](https://doi.org/10.1101/2025.02.20.639398)
- Parse Biosciences. 10 Million Human PBMCs in a Single Experiment.
  [parsebiosciences.com/datasets/10-million-human-pbmcs-in-a-single-experiment](https://www.parsebiosciences.com/datasets/10-million-human-pbmcs-in-a-single-experiment/)

	---
	license: other
	license_name: cc-by-4.0-and-cc-by-nc-4.0
	license_link: LICENSE.md
	tags:
	- biology
	- single-cell
	- perturbation
	---

	# GENESIS

	GENESIS (Generative ENErgy-based Single-cell Intervention Simulator) generates the single-cell RNA profiles of a
	perturbation in a biological context it was never measured in. These are the trained models behind the paper
	Single-cell perturbation prediction near experimental reproducibility with GENESIS. The code is at
	[github.com/rickconci/GENESIS](https://github.com/rickconci/GENESIS), and the published scores are at
	[RConci/GENESIS_results](https://huggingface.co/datasets/RConci/GENESIS_results).

	## Start here: two models

	\| Folder \| Data \| Predicts \|
	\|---\|---\|---\|
	\| `tahoe/` \| Tahoe-100M: 50 cancer cell lines × drugs \| a drug's effect in 5 cell lines held out of training \|
	\| `pbmc/` \| Parse PBMC cytokine atlas: 12 donors × 90 cytokines \| a cytokine's effect in 4 donors held out of training \|

	Downloads are gated: request access on this page, then log in once with `hf auth login` (a token from
	[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)). Inside a clone of the code
	(`uv sync --extra model`), download one model and generate cells for its test conditions:

	```bash
	uvx --from huggingface_hub hf download RConci/GENESIS --include 'tahoe/' --exclude '/split_cache/*' --local-dir models
	uv run python scripts/eval/generate.py conditions --run-dir "$PWD/models/tahoe" --out-dir results/generated/tahoe --limit 10
	```

	Each condition is written as one `.npz` file holding `predictions` (cells x 2,000 genes, log1p), `gene_names` and the
	condition's values. This needs a CUDA GPU and no dataset.

	## Reproduce the paper's figures: `reproduce/`

	The folders are arranged by the figure that first uses them, as in the code's `scripts/figures/figureN/`. Download
	everything with `hf download RConci/GENESIS --local-dir models`; each figure's `score.sh` then finds its models by
	these names.

	\| Folder \| Figure \| Trained on \| Seeds \|
	\|---\|---\|---\|---\|
	\| `tahoe/`, `pbmc/` \| 2 \| all training conditions (5 epochs) \| 0 \|
	\| `reproduce/figure2/tahoe_perturbation_split/` \| 2 (ED) \| Tahoe: a held-out drug is seen in 1-20 other lines; test = 40 drugs × 30 lines × 3 doses \| 0 \|
	\| `reproduce/figure2/pbmc_perturbation_split/` \| 2 (ED) \| PBMC: a held-out cytokine is seen in 1-5 other donors; test = 30 cytokines × 7 donors \| 0 \|
	\| `reproduce/figure3/scaling/full_seed{1,2}/` \| 3a \| as `tahoe/`, with other model seeds; seed 0 of this point is `tahoe/` itself \| 1, 2 \|
	\| `reproduce/figure3/scaling/conditions{25,5}_seed{0,1,2}/` \| 3a \| 25% or 5% of the training conditions (11 or 25 epochs) \| 0, 1, 2 \|
	\| `reproduce/figure3/scaling/cells{25,5}_seed{0,1,2}/` \| 3a \| every condition, 25% or 5% of its perturbed cells, every control (11 or 25 epochs) \| 0, 1, 2 \|
	\| `reproduce/figure3/overlap/row{0-4}_seed{0,1,2}/` \| 3b \| 5 held-out lines, each seeing 0, 15, 30, 80 or 164 drugs in training (one Latin-square row per folder; 15 epochs) \| 0, 1, 2 \|
	\| `reproduce/figure4/progeny_5pct_cells/` \| 4 \| as `cells5`, on 3,072 genes: the 2,000 plus the PROGENy pathway genes, padded with 6 placeholders \| 0 \|
	\| `reproduce/figure4/hallmark_15pct_conditions/` \| 4 (ED) \| 15% of the training conditions, on 5,750 genes: the 2,000 plus the MSigDB Hallmark genes \| 0 \|

	Every Tahoe model above, except the perturbation split, is tested on the same 5 held-out cell lines as `tahoe/`. In
	`scaling/`, seed n draws the training subset and initialises the model. In `overlap/`, it draws which drugs each line
	sees, and every model starts from the same initialisation.

	## What a model folder holds

	\| File \| What it is \|
	\|---\|---\|
	\| `checkpoints/last.ckpt` \| the PyTorch Lightning checkpoint: weights, optimizer state, the full training config \|
	\| `config_resolved.yaml` \| every training setting, as the run used it \|
	\| `encoder_idx_to_name.json` \| the cell lines, drugs, doses, plates, donors or cytokines the model can condition on \|
	\| `output_gene_names.txt` \| the genes it predicts, in output order \|
	\| `eval/eval_manifest.json`, `eval/condition_summary.parquet` \| the test split and the cells measured per condition \|
	\| `split_cache/train_idx.npy` \| the dataset rows it trained on (only needed to recount training data) \|
	\| `run.log` \| the training log \|
	\| `hbss_meta.json`, `hbss_selected_triplets.parquet` \| for subsampled runs: which training conditions were kept \|

	## Licence

	Each model carries the licence of the data it was trained on ([LICENSE.md](LICENSE.md)):

	\| Folders \| Trained on \| Licence \|
	\|---\|---\|---\|
	\| every folder with `pbmc` in its path (`pbmc/`, `reproduce/figure2/pbmc_perturbation_split/`) \| the Parse PBMC cytokine atlas, CC BY-NC 4.0 \| [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use, with credit \|
	\| every other folder \| Tahoe-100M, CC0 1.0 \| [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): any use, with credit \|

	Credit means citing the GENESIS paper, plus the dataset a model was trained on. The code is MIT-licensed.

	## Data

	- Zhang J. et al. Tahoe-100M: A Giga-Scale Single-Cell Perturbation Atlas for Context-Dependent Gene Function and
	Cellular Modeling. bioRxiv (2025). [doi:10.1101/2025.02.20.639398](https://doi.org/10.1101/2025.02.20.639398)
	- Parse Biosciences. 10 Million Human PBMCs in a Single Experiment.
	[parsebiosciences.com/datasets/10-million-human-pbmcs-in-a-single-experiment](https://www.parsebiosciences.com/datasets/10-million-human-pbmcs-in-a-single-experiment/)