clop-dit 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. clop_dit-1.1.0/LICENSE +21 -0
  2. clop_dit-1.1.0/PKG-INFO +156 -0
  3. clop_dit-1.1.0/README.md +97 -0
  4. clop_dit-1.1.0/clop_dit/__init__.py +22 -0
  5. clop_dit-1.1.0/clop_dit/architecture/__init__.py +5 -0
  6. clop_dit-1.1.0/clop_dit/architecture/cell2cell.py +355 -0
  7. clop_dit-1.1.0/clop_dit/architecture/clop/__init__.py +22 -0
  8. clop_dit-1.1.0/clop_dit/architecture/clop/aligner.py +488 -0
  9. clop_dit-1.1.0/clop_dit/architecture/clop/losses.py +748 -0
  10. clop_dit-1.1.0/clop_dit/architecture/decoder.py +388 -0
  11. clop_dit-1.1.0/clop_dit/architecture/dit.py +672 -0
  12. clop_dit-1.1.0/clop_dit/architecture/scgpt_embed.py +848 -0
  13. clop_dit-1.1.0/clop_dit/cli.py +72 -0
  14. clop_dit-1.1.0/clop_dit/data_pipeline/__init__.py +15 -0
  15. clop_dit-1.1.0/clop_dit/data_pipeline/cache_builder.py +554 -0
  16. clop_dit-1.1.0/clop_dit/data_pipeline/dataset.py +855 -0
  17. clop_dit-1.1.0/clop_dit/data_pipeline/embedding_preprocessor.py +426 -0
  18. clop_dit-1.1.0/clop_dit/data_pipeline/geo_fetcher.py +254 -0
  19. clop_dit-1.1.0/clop_dit/data_pipeline/group_aware_sampler.py +170 -0
  20. clop_dit-1.1.0/clop_dit/data_pipeline/subcluster_annotation.py +1102 -0
  21. clop_dit-1.1.0/clop_dit/data_pipeline/text_cleaner.py +339 -0
  22. clop_dit-1.1.0/clop_dit/evaluation/__init__.py +6 -0
  23. clop_dit-1.1.0/clop_dit/evaluation/baseline_registry.py +245 -0
  24. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/__init__.py +4 -0
  25. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/constants.py +38 -0
  26. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/figures.py +613 -0
  27. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/generation.py +97 -0
  28. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/io.py +120 -0
  29. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/metrics.py +173 -0
  30. clop_dit-1.1.0/clop_dit/evaluation/biological_validation/run.py +219 -0
  31. clop_dit-1.1.0/clop_dit/evaluation/downstream_biology.py +627 -0
  32. clop_dit-1.1.0/clop_dit/evaluation/embedding_quality.py +231 -0
  33. clop_dit-1.1.0/clop_dit/evaluation/generative_metrics.py +426 -0
  34. clop_dit-1.1.0/clop_dit/evaluation/metrics.py +443 -0
  35. clop_dit-1.1.0/clop_dit/evaluation/model_benchmarking.py +525 -0
  36. clop_dit-1.1.0/clop_dit/evaluation/run_metrics.py +328 -0
  37. clop_dit-1.1.0/clop_dit/evaluation/visualizer.py +255 -0
  38. clop_dit-1.1.0/clop_dit/experiments/__init__.py +19 -0
  39. clop_dit-1.1.0/clop_dit/experiments/ood_evaluation.py +715 -0
  40. clop_dit-1.1.0/clop_dit/experiments/rare_cell_augmentation.py +867 -0
  41. clop_dit-1.1.0/clop_dit/training/__init__.py +5 -0
  42. clop_dit-1.1.0/clop_dit/training/reproducibility.py +60 -0
  43. clop_dit-1.1.0/clop_dit/training/schedulers.py +55 -0
  44. clop_dit-1.1.0/clop_dit/training/train_cell2cell.py +552 -0
  45. clop_dit-1.1.0/clop_dit/training/train_clop.py +890 -0
  46. clop_dit-1.1.0/clop_dit/training/train_dit.py +619 -0
  47. clop_dit-1.1.0/clop_dit/utils/__init__.py +34 -0
  48. clop_dit-1.1.0/clop_dit/utils/constants.py +106 -0
  49. clop_dit-1.1.0/clop_dit/utils/experiment_tracker.py +214 -0
  50. clop_dit-1.1.0/clop_dit/utils/helpers.py +58 -0
  51. clop_dit-1.1.0/clop_dit/utils/logging_config.py +39 -0
  52. clop_dit-1.1.0/clop_dit/utils/paths.py +139 -0
  53. clop_dit-1.1.0/clop_dit/visualization/__init__.py +27 -0
  54. clop_dit-1.1.0/clop_dit/visualization/_plot_helpers.py +162 -0
  55. clop_dit-1.1.0/clop_dit/visualization/_utils.py +43 -0
  56. clop_dit-1.1.0/clop_dit/visualization/article_composition.py +162 -0
  57. clop_dit-1.1.0/clop_dit/visualization/article_delivery.py +383 -0
  58. clop_dit-1.1.0/clop_dit/visualization/baseline_panels.py +3 -0
  59. clop_dit-1.1.0/clop_dit/visualization/benchmark_panels.py +3 -0
  60. clop_dit-1.1.0/clop_dit/visualization/direct_layout.py +200 -0
  61. clop_dit-1.1.0/clop_dit/visualization/downstream_panels.py +22 -0
  62. clop_dit-1.1.0/clop_dit/visualization/experimental/__init__.py +10 -0
  63. clop_dit-1.1.0/clop_dit/visualization/experimental/fig19_pseudobulk.py +132 -0
  64. clop_dit-1.1.0/clop_dit/visualization/experimental/fig20_failure_analysis.py +149 -0
  65. clop_dit-1.1.0/clop_dit/visualization/experimental/fig21_ablation_heatmap.py +185 -0
  66. clop_dit-1.1.0/clop_dit/visualization/experimental/fig21_field_ablation.py +135 -0
  67. clop_dit-1.1.0/clop_dit/visualization/experimental/fig22_discriminator.py +151 -0
  68. clop_dit-1.1.0/clop_dit/visualization/experimental/fig22_multi_seed.py +141 -0
  69. clop_dit-1.1.0/clop_dit/visualization/experimental/fig23_ood_showcase.py +154 -0
  70. clop_dit-1.1.0/clop_dit/visualization/experimental/fig24_variance_deepdive.py +194 -0
  71. clop_dit-1.1.0/clop_dit/visualization/experimental/fig25_cross_dataset.py +167 -0
  72. clop_dit-1.1.0/clop_dit/visualization/experimental/fig26_expanded_de.py +231 -0
  73. clop_dit-1.1.0/clop_dit/visualization/experimental/fig27_ood_robustness.py +244 -0
  74. clop_dit-1.1.0/clop_dit/visualization/experimental/fig28_marker_completeness.py +215 -0
  75. clop_dit-1.1.0/clop_dit/visualization/experimental/fig29_embedding_augmentation.py +238 -0
  76. clop_dit-1.1.0/clop_dit/visualization/experimental/fig30_validation_summary.py +396 -0
  77. clop_dit-1.1.0/clop_dit/visualization/experimental/fig31_decoder_ablation.py +174 -0
  78. clop_dit-1.1.0/clop_dit/visualization/explicit_positioning.py +135 -0
  79. clop_dit-1.1.0/clop_dit/visualization/fig03_training.py +567 -0
  80. clop_dit-1.1.0/clop_dit/visualization/fig04_embedding.py +843 -0
  81. clop_dit-1.1.0/clop_dit/visualization/fig05_metrics.py +659 -0
  82. clop_dit-1.1.0/clop_dit/visualization/fig06_fidelity.py +291 -0
  83. clop_dit-1.1.0/clop_dit/visualization/fig07_alignment.py +387 -0
  84. clop_dit-1.1.0/clop_dit/visualization/fig08_markers.py +346 -0
  85. clop_dit-1.1.0/clop_dit/visualization/fig09_expression_corr.py +322 -0
  86. clop_dit-1.1.0/clop_dit/visualization/fig10_expression_analysis.py +301 -0
  87. clop_dit-1.1.0/clop_dit/visualization/fig11_conditioning.py +392 -0
  88. clop_dit-1.1.0/clop_dit/visualization/fig12_diversity.py +237 -0
  89. clop_dit-1.1.0/clop_dit/visualization/fig13_noise_tradeoff.py +154 -0
  90. clop_dit-1.1.0/clop_dit/visualization/fig14_expr_diversity.py +122 -0
  91. clop_dit-1.1.0/clop_dit/visualization/fig15_baselines.py +405 -0
  92. clop_dit-1.1.0/clop_dit/visualization/fig16_benchmark.py +333 -0
  93. clop_dit-1.1.0/clop_dit/visualization/fig17_downstream.py +704 -0
  94. clop_dit-1.1.0/clop_dit/visualization/fig18_de_concordance.py +294 -0
  95. clop_dit-1.1.0/clop_dit/visualization/figS01_supplementary_validation.py +281 -0
  96. clop_dit-1.1.0/clop_dit/visualization/figS02_expression_diagnostics.py +529 -0
  97. clop_dit-1.1.0/clop_dit/visualization/panel_geometry.py +76 -0
  98. clop_dit-1.1.0/clop_dit/visualization/panels_classifier.py +17 -0
  99. clop_dit-1.1.0/clop_dit/visualization/panels_clustering.py +9 -0
  100. clop_dit-1.1.0/clop_dit/visualization/panels_conditioning.py +14 -0
  101. clop_dit-1.1.0/clop_dit/visualization/panels_de_concordance.py +3 -0
  102. clop_dit-1.1.0/clop_dit/visualization/panels_diversity.py +14 -0
  103. clop_dit-1.1.0/clop_dit/visualization/panels_embedding.py +9 -0
  104. clop_dit-1.1.0/clop_dit/visualization/panels_expression.py +29 -0
  105. clop_dit-1.1.0/clop_dit/visualization/panels_heatmaps.py +20 -0
  106. clop_dit-1.1.0/clop_dit/visualization/panels_merged.py +9 -0
  107. clop_dit-1.1.0/clop_dit/visualization/panels_metrics.py +3 -0
  108. clop_dit-1.1.0/clop_dit/visualization/panels_quality.py +17 -0
  109. clop_dit-1.1.0/clop_dit/visualization/panels_training.py +3 -0
  110. clop_dit-1.1.0/clop_dit/visualization/panels_umap_quality.py +9 -0
  111. clop_dit-1.1.0/clop_dit/visualization/report.py +49 -0
  112. clop_dit-1.1.0/clop_dit/visualization/results_visualizer.py +1022 -0
  113. clop_dit-1.1.0/clop_dit/visualization/style.py +977 -0
  114. clop_dit-1.1.0/clop_dit/visualization/supplementary/__init__.py +11 -0
  115. clop_dit-1.1.0/clop_dit/visualization/supplementary/figS1_robustness_ablation.py +465 -0
  116. clop_dit-1.1.0/clop_dit/visualization/supplementary/figS2_downstream_validation.py +611 -0
  117. clop_dit-1.1.0/clop_dit/visualization/supplementary/figS3_expression_decoder.py +356 -0
  118. clop_dit-1.1.0/clop_dit.egg-info/PKG-INFO +156 -0
  119. clop_dit-1.1.0/clop_dit.egg-info/SOURCES.txt +139 -0
  120. clop_dit-1.1.0/clop_dit.egg-info/dependency_links.txt +1 -0
  121. clop_dit-1.1.0/clop_dit.egg-info/entry_points.txt +2 -0
  122. clop_dit-1.1.0/clop_dit.egg-info/requires.txt +22 -0
  123. clop_dit-1.1.0/clop_dit.egg-info/top_level.txt +1 -0
  124. clop_dit-1.1.0/setup.cfg +4 -0
  125. clop_dit-1.1.0/setup.py +71 -0
  126. clop_dit-1.1.0/tests/test_article_delivery.py +294 -0
  127. clop_dit-1.1.0/tests/test_check_lane_c_staffing_gate.py +260 -0
  128. clop_dit-1.1.0/tests/test_check_strict_ood.py +126 -0
  129. clop_dit-1.1.0/tests/test_clop_loss.py +35 -0
  130. clop_dit-1.1.0/tests/test_config_v8_2.py +261 -0
  131. clop_dit-1.1.0/tests/test_configs.py +75 -0
  132. clop_dit-1.1.0/tests/test_dataset_loader_paths.py +256 -0
  133. clop_dit-1.1.0/tests/test_direct_layout.py +53 -0
  134. clop_dit-1.1.0/tests/test_embedding_quality.py +134 -0
  135. clop_dit-1.1.0/tests/test_experiment_article_policy.py +120 -0
  136. clop_dit-1.1.0/tests/test_lane_c_feasibility.py +448 -0
  137. clop_dit-1.1.0/tests/test_panel_label_offsets.py +208 -0
  138. clop_dit-1.1.0/tests/test_strict_ood_candidate_inventory.py +48 -0
  139. clop_dit-1.1.0/tests/test_vcd_checks.py +693 -0
  140. clop_dit-1.1.0/tests/test_visualization.py +236 -0
  141. clop_dit-1.1.0/tests/test_visualization_imports.py +34 -0
clop_dit-1.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zeyu Fu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,156 @@
1
+ Metadata-Version: 2.4
2
+ Name: clop-dit
3
+ Version: 1.1.0
4
+ Summary: CLOP-DiT: Text-conditioned single-cell latent generation via contrastive language-omics pretraining and diffusion transformers.
5
+ Home-page: https://github.com/PeterPonyu/CLOP-DiT
6
+ Author: Zeyu Fu
7
+ Author-email: fuzeyu09@gmail.com
8
+ Maintainer: Zeyu Fu
9
+ Maintainer-email: fuzeyu09@gmail.com
10
+ License: MIT
11
+ Project-URL: Source, https://github.com/PeterPonyu/CLOP-DiT
12
+ Project-URL: Issue Tracker, https://github.com/PeterPonyu/CLOP-DiT/issues
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ Requires-Dist: torch>=2.0.0
24
+ Requires-Dist: numpy>=1.24.0
25
+ Requires-Dist: scipy>=1.10.0
26
+ Requires-Dist: scikit-learn>=1.2.0
27
+ Requires-Dist: scanpy>=1.9.0
28
+ Requires-Dist: anndata>=0.9.0
29
+ Requires-Dist: scib>=1.0.0
30
+ Requires-Dist: transformers>=4.35.0
31
+ Requires-Dist: tokenizers>=0.15.0
32
+ Requires-Dist: matplotlib>=3.7.0
33
+ Requires-Dist: seaborn>=0.12.0
34
+ Requires-Dist: umap-learn>=0.5.0
35
+ Requires-Dist: Pillow>=9.0.0
36
+ Requires-Dist: torchdiffeq>=0.2.3
37
+ Requires-Dist: pyyaml>=6.0
38
+ Requires-Dist: tqdm>=4.65.0
39
+ Requires-Dist: GEOparse>=2.0.3
40
+ Requires-Dist: requests>=2.28.0
41
+ Provides-Extra: dev
42
+ Requires-Dist: pytest>=7.0; extra == "dev"
43
+ Requires-Dist: pytest-cov>=4.0; extra == "dev"
44
+ Dynamic: author
45
+ Dynamic: author-email
46
+ Dynamic: classifier
47
+ Dynamic: description
48
+ Dynamic: description-content-type
49
+ Dynamic: home-page
50
+ Dynamic: license
51
+ Dynamic: license-file
52
+ Dynamic: maintainer
53
+ Dynamic: maintainer-email
54
+ Dynamic: project-url
55
+ Dynamic: provides-extra
56
+ Dynamic: requires-dist
57
+ Dynamic: requires-python
58
+ Dynamic: summary
59
+
60
+ # CLOP-DiT
61
+
62
+ > Text-conditioned single-cell latent generation via contrastive language–omics pretraining and diffusion transformers.
63
+
64
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19643738.svg)](https://doi.org/10.5281/zenodo.19643738)
65
+
66
+ CLOP-DiT is a three-stage pipeline that samples single-cell expression embeddings conditioned on a structured five-field text prompt (cell type, tissue, organism, marker genes, disease context). The first stage is a prototype-aware contrastive aligner that maps frozen BiomedBERT text embeddings and frozen scGPT cell embeddings into a shared 512-dimensional latent space. The second stage is a 1-D Diffusion Transformer trained with conditional flow matching and classifier-free guidance, which samples a latent vector from a Gaussian prior toward the conditioned region of that space. The third stage is the frozen scGPT decoder, used to map the generated latent back to per-gene expression for downstream inspection.
67
+
68
+ The training corpus is 220,304 cells from 80 publicly available Gene Expression Omnibus (GEO) datasets, deduplicated to 69 evaluation cell types covering human and mouse tumour-microenvironment and developmental contexts.
69
+
70
+ ## Reported results
71
+
72
+ The headline metrics, evaluated on 69 deduplicated cell types:
73
+
74
+ | Method | KNN-1 | Steering | DivR | LinAcc |
75
+ |---|---|---|---|---|
76
+ | Real data | 0.890 | – | 1.000 | 0.942 |
77
+ | CLOP-DiT, high-fidelity setting (CFG = 2.0) | 0.369 | 0.810 | 0.513 | 0.511 |
78
+ | CLOP-DiT, high-diversity setting (CFG = 1.0) | 0.288 | 0.807 | 0.929 | 0.357 |
79
+ | Embedding-VAE baseline | 0.112 | 0.547 | 0.744 | 0.189 |
80
+ | Gaussian baseline | 0.011 | 0.466 | 2.277 | 0.009 |
81
+
82
+ KNN-1 is reported over the 69-class problem with random chance ≈ 0.0145; CLOP-DiT at CFG = 2.0 is therefore about 25× above random. DivR ideal = 1.0.
83
+
84
+ The reported strength of CLOP-DiT is controllable text-conditioned generation. The reported limitations are that within-type variance and gene–gene correlation are only weakly preserved, and that a Gaussian mean-matching baseline outperforms CLOP-DiT on the nine shared distributional metrics.
85
+
86
+ ## Installation
87
+
88
+ The model code is published on PyPI as `clop-dit`; the import name is `clop_dit`.
89
+
90
+ ```bash
91
+ pip install clop-dit
92
+ ```
93
+
94
+ The training, inference and figure scripts live in this repository. To run them, install from a clone; the code targets Python 3.10 and the full dependency list is in `requirements.txt`.
95
+
96
+ ```bash
97
+ conda create -n clopdit python=3.10
98
+ conda activate clopdit
99
+ pip install -e .
100
+ ```
101
+
102
+ The training and evaluation experiments were carried out with PyTorch 2.1, CUDA 12.0, scGPT v0.2.1, and Hugging Face Transformers 4.36 on a single NVIDIA RTX 5090 Laptop GPU.
103
+
104
+ ## Generating cells from a text prompt
105
+
106
+ Once the trained checkpoints are placed under `models/`, a single text prompt can be sampled and decoded with the inference entry point:
107
+
108
+ ```bash
109
+ python scripts/inference/05_inference.py \
110
+ --prompt "CD8+ cytotoxic T cells from human lung adenocarcinoma" \
111
+ --num_cells 500 --cfg_scale 2.0 --decode_expression \
112
+ --output generated_cells.h5ad
113
+ ```
114
+
115
+ Training the contrastive aligner and the diffusion transformer from cached embeddings:
116
+
117
+ ```bash
118
+ python scripts/training/04a_train_clop.py --config configs/clop.yaml
119
+ python scripts/training/04b_train_dit.py --config configs/dit.yaml
120
+ ```
121
+
122
+ ## Data
123
+
124
+ The training and validation data are derived entirely from public Gene Expression Omnibus (GEO) records. Each accession is resolvable at `https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSExxxxxx`.
125
+
126
+ The deterministic preprocessing pipeline included in this repository (quality control, highly-variable-gene selection, scGPT encoding, study-level stratified split, and deduplication) can rebuild the analysis cache from those GEO records.
127
+
128
+ The trained model checkpoints (the CLOP aligner and the DiT generator) and the preprocessed embedding cache are not redistributed in this repository because of single-cell data licensing and file-size constraints. Both are available from the co-corresponding authors on reasonable request.
129
+
130
+ ## Citation
131
+
132
+ If you use CLOP-DiT, please cite the article:
133
+
134
+ > Fu Z, Liu Y, Wang J, Wang S. CLOP-DiT: Structured-metadata-conditioned single-cell latent generation via contrastive language-omics pretraining and Diffusion Transformers. *Array*. 2026;30:100934. https://doi.org/10.1016/j.array.2026.100934
135
+
136
+ ```bibtex
137
+ @article{fu2026clopdit,
138
+ author = {Fu, Zeyu and Liu, Yiyao and Wang, Junping and Wang, Song},
139
+ title = {CLOP-DiT: Structured-metadata-conditioned single-cell latent generation via contrastive language-omics pretraining and Diffusion Transformers},
140
+ journal = {Array},
141
+ volume = {30},
142
+ pages = {100934},
143
+ year = {2026},
144
+ doi = {10.1016/j.array.2026.100934}
145
+ }
146
+ ```
147
+
148
+ GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
149
+
150
+ ## License
151
+
152
+ Released under the MIT License — see `LICENSE`.
153
+
154
+ ## Contact
155
+
156
+ Zeyu Fu — fuzeyu09@gmail.com
@@ -0,0 +1,97 @@
1
+ # CLOP-DiT
2
+
3
+ > Text-conditioned single-cell latent generation via contrastive language–omics pretraining and diffusion transformers.
4
+
5
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19643738.svg)](https://doi.org/10.5281/zenodo.19643738)
6
+
7
+ CLOP-DiT is a three-stage pipeline that samples single-cell expression embeddings conditioned on a structured five-field text prompt (cell type, tissue, organism, marker genes, disease context). The first stage is a prototype-aware contrastive aligner that maps frozen BiomedBERT text embeddings and frozen scGPT cell embeddings into a shared 512-dimensional latent space. The second stage is a 1-D Diffusion Transformer trained with conditional flow matching and classifier-free guidance, which samples a latent vector from a Gaussian prior toward the conditioned region of that space. The third stage is the frozen scGPT decoder, used to map the generated latent back to per-gene expression for downstream inspection.
8
+
9
+ The training corpus is 220,304 cells from 80 publicly available Gene Expression Omnibus (GEO) datasets, deduplicated to 69 evaluation cell types covering human and mouse tumour-microenvironment and developmental contexts.
10
+
11
+ ## Reported results
12
+
13
+ The headline metrics, evaluated on 69 deduplicated cell types:
14
+
15
+ | Method | KNN-1 | Steering | DivR | LinAcc |
16
+ |---|---|---|---|---|
17
+ | Real data | 0.890 | – | 1.000 | 0.942 |
18
+ | CLOP-DiT, high-fidelity setting (CFG = 2.0) | 0.369 | 0.810 | 0.513 | 0.511 |
19
+ | CLOP-DiT, high-diversity setting (CFG = 1.0) | 0.288 | 0.807 | 0.929 | 0.357 |
20
+ | Embedding-VAE baseline | 0.112 | 0.547 | 0.744 | 0.189 |
21
+ | Gaussian baseline | 0.011 | 0.466 | 2.277 | 0.009 |
22
+
23
+ KNN-1 is reported over the 69-class problem with random chance ≈ 0.0145; CLOP-DiT at CFG = 2.0 is therefore about 25× above random. DivR ideal = 1.0.
24
+
25
+ The reported strength of CLOP-DiT is controllable text-conditioned generation. The reported limitations are that within-type variance and gene–gene correlation are only weakly preserved, and that a Gaussian mean-matching baseline outperforms CLOP-DiT on the nine shared distributional metrics.
26
+
27
+ ## Installation
28
+
29
+ The model code is published on PyPI as `clop-dit`; the import name is `clop_dit`.
30
+
31
+ ```bash
32
+ pip install clop-dit
33
+ ```
34
+
35
+ The training, inference and figure scripts live in this repository. To run them, install from a clone; the code targets Python 3.10 and the full dependency list is in `requirements.txt`.
36
+
37
+ ```bash
38
+ conda create -n clopdit python=3.10
39
+ conda activate clopdit
40
+ pip install -e .
41
+ ```
42
+
43
+ The training and evaluation experiments were carried out with PyTorch 2.1, CUDA 12.0, scGPT v0.2.1, and Hugging Face Transformers 4.36 on a single NVIDIA RTX 5090 Laptop GPU.
44
+
45
+ ## Generating cells from a text prompt
46
+
47
+ Once the trained checkpoints are placed under `models/`, a single text prompt can be sampled and decoded with the inference entry point:
48
+
49
+ ```bash
50
+ python scripts/inference/05_inference.py \
51
+ --prompt "CD8+ cytotoxic T cells from human lung adenocarcinoma" \
52
+ --num_cells 500 --cfg_scale 2.0 --decode_expression \
53
+ --output generated_cells.h5ad
54
+ ```
55
+
56
+ Training the contrastive aligner and the diffusion transformer from cached embeddings:
57
+
58
+ ```bash
59
+ python scripts/training/04a_train_clop.py --config configs/clop.yaml
60
+ python scripts/training/04b_train_dit.py --config configs/dit.yaml
61
+ ```
62
+
63
+ ## Data
64
+
65
+ The training and validation data are derived entirely from public Gene Expression Omnibus (GEO) records. Each accession is resolvable at `https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSExxxxxx`.
66
+
67
+ The deterministic preprocessing pipeline included in this repository (quality control, highly-variable-gene selection, scGPT encoding, study-level stratified split, and deduplication) can rebuild the analysis cache from those GEO records.
68
+
69
+ The trained model checkpoints (the CLOP aligner and the DiT generator) and the preprocessed embedding cache are not redistributed in this repository because of single-cell data licensing and file-size constraints. Both are available from the co-corresponding authors on reasonable request.
70
+
71
+ ## Citation
72
+
73
+ If you use CLOP-DiT, please cite the article:
74
+
75
+ > Fu Z, Liu Y, Wang J, Wang S. CLOP-DiT: Structured-metadata-conditioned single-cell latent generation via contrastive language-omics pretraining and Diffusion Transformers. *Array*. 2026;30:100934. https://doi.org/10.1016/j.array.2026.100934
76
+
77
+ ```bibtex
78
+ @article{fu2026clopdit,
79
+ author = {Fu, Zeyu and Liu, Yiyao and Wang, Junping and Wang, Song},
80
+ title = {CLOP-DiT: Structured-metadata-conditioned single-cell latent generation via contrastive language-omics pretraining and Diffusion Transformers},
81
+ journal = {Array},
82
+ volume = {30},
83
+ pages = {100934},
84
+ year = {2026},
85
+ doi = {10.1016/j.array.2026.100934}
86
+ }
87
+ ```
88
+
89
+ GitHub's "Cite this repository" button reads the same record from `CITATION.cff`.
90
+
91
+ ## License
92
+
93
+ Released under the MIT License — see `LICENSE`.
94
+
95
+ ## Contact
96
+
97
+ Zeyu Fu — fuzeyu09@gmail.com
@@ -0,0 +1,22 @@
1
+ """CLOP-DiT — text-conditioned single-cell latent generation.
2
+
3
+ A three-stage pipeline that generates single-cell expression embeddings from
4
+ a structured five-field text prompt (cell type, tissue, organism, marker
5
+ genes, disease context):
6
+
7
+ 1. Data preparation — curate GEO datasets, build per-type captions,
8
+ and cache frozen scGPT cell embeddings and frozen
9
+ BiomedBERT text embeddings with ZCA whitening.
10
+ 2. CLOP alignment — prototype-aware SigLIP contrastive alignment
11
+ between text and cell embeddings in a shared
12
+ 512-dimensional latent space.
13
+ 3. DiT generation — 1-D Diffusion Transformer trained by conditional
14
+ flow matching with classifier-free guidance;
15
+ decoded to gene expression through the frozen
16
+ scGPT decoder for downstream inspection.
17
+
18
+ See the top-level README for installation, usage, and citation.
19
+ """
20
+
21
+ __version__ = "1.1.0"
22
+ __author__ = "Zeyu Fu, JianXu Zheng, Jiawei Fu"
@@ -0,0 +1,5 @@
1
+ # architecture/__init__.py
2
+ from .dit import DiT1D, DiTBlock, AdaLNZero, TimestepEmbedder
3
+ from .clop import CLOPAligner, ProjectionHead
4
+ from .decoder import ScGPTDecoder
5
+ from .cell2cell import Cell2CellDiT, SourceCellEmbedder, EditStrengthEmbedder
@@ -0,0 +1,355 @@
1
+ # cell2cell.py — Cell→Cell Latent Editing via Conditional Flow Matching (v2: AdaLN injection)
2
+ """
3
+ Cell2Cell: Intra-modal conditional generation in scGPT latent space.
4
+
5
+ Analogy to Stable Diffusion img2img:
6
+ Image img2img: image → VAE encoder → latent → add noise → denoise with prompt → VAE decoder → edited image
7
+ Cell2Cell: cell → scGPT encoder → z_src → add noise → flow match with condition → scGPT decoder → edited cell
8
+
9
+ Architecture (v2 — AdaLN injection, NOT token concatenation):
10
+ v1 used [src_tokens; tgt_tokens] concatenation (32 tokens), causing 4× attention cost.
11
+ v2 injects z_src via AdaLN conditioning: combined_cond = t_emb + c_emb + s_emb + src_emb
12
+ This keeps the token count at 16 (same as DiT1D) and adds <5% compute overhead.
13
+
14
+ Source cell signal flows through the SAME AdaLN modulation pathway as timestep, text condition,
15
+ and edit strength — a single vector that modulates every transformer block.
16
+
17
+ Use cases:
18
+ - Perturbation prediction: control cell → drug-treated cell
19
+ - Batch/domain translation: dataset A → dataset B
20
+ - Trajectory editing: cell at time t₀ → cell at time t₁
21
+ - Cell state transition: naive → activated, healthy → diseased
22
+
23
+ Flow Matching formulation for cell2cell:
24
+ z_t = (1-t) * z_noise + t * z_tgt (t ∈ [0, 1])
25
+ Starting from z_src (noised) instead of pure noise:
26
+ z_start = (1-s) * z_src + s * ε (s = edit_strength ∈ [0, 1])
27
+
28
+ Small s → gentle edit (preserve cell identity)
29
+ Large s → strong edit (more freedom, more drift)
30
+
31
+ References:
32
+ - SDEdit (Meng et al., 2021)
33
+ - Flux img2img (Black Forest Labs, 2024)
34
+ - CellOT (Bunne et al., 2023)
35
+ """
36
+
37
+ import math
38
+ import torch
39
+ import torch.nn as nn
40
+ import torch.nn.functional as F
41
+ from typing import Optional, Tuple, Dict
42
+
43
+ from ..utils.constants import (
44
+ CFG_SCALE,
45
+ COND_DROP_PROB,
46
+ DEFAULT_ATTN_DROP,
47
+ DEFAULT_PROJ_DROP,
48
+ DIT_HIDDEN_DIM,
49
+ DIT_MLP_RATIO,
50
+ DIT_NUM_BLOCKS,
51
+ DIT_NUM_HEADS,
52
+ DIT_NUM_TOKENS,
53
+ LATENT_DIM,
54
+ PROJ_DIM,
55
+ )
56
+ from .dit import (
57
+ TimestepEmbedder,
58
+ ConditionEmbedder,
59
+ AdaLNZero,
60
+ DiTBlock,
61
+ DiTFinalLayer,
62
+ )
63
+
64
+
65
+ # ============================================================================
66
+ # Source Cell Embedder — compresses z_src to a conditioning vector
67
+ # ============================================================================
68
+
69
+ class SourceCellEmbedder(nn.Module):
70
+ """Compresses z_src (512-d) into a conditioning vector (hidden_dim).
71
+
72
+ Unlike v1's SourceCellEncoder which tokenized z_src into 16 tokens
73
+ (doubling the sequence length to 32 and causing 4× attention cost),
74
+ this simply projects z_src into the same hidden_dim space as
75
+ timestep/text embeddings for AdaLN injection.
76
+
77
+ Compute overhead: O(latent_dim × hidden_dim) — negligible.
78
+ """
79
+
80
+ def __init__(self, latent_dim: int = 512, hidden_dim: int = 384):
81
+ super().__init__()
82
+ self.mlp = nn.Sequential(
83
+ nn.Linear(latent_dim, hidden_dim),
84
+ nn.SiLU(),
85
+ nn.Linear(hidden_dim, hidden_dim),
86
+ )
87
+
88
+ def forward(self, z_src: torch.Tensor) -> torch.Tensor:
89
+ """(B, latent_dim) → (B, hidden_dim)"""
90
+ return self.mlp(z_src)
91
+
92
+
93
+ # ============================================================================
94
+ # Edit Strength Embedder
95
+ # ============================================================================
96
+
97
+ class EditStrengthEmbedder(nn.Module):
98
+ """Embeds the edit strength parameter s ∈ [0, 1].
99
+
100
+ Small s → gentle edit; large s → aggressive edit.
101
+ Uses sinusoidal encoding (same as TimestepEmbedder).
102
+ """
103
+
104
+ def __init__(self, hidden_dim: int, frequency_dim: int = 64):
105
+ super().__init__()
106
+ self.mlp = nn.Sequential(
107
+ nn.Linear(frequency_dim, hidden_dim),
108
+ nn.SiLU(),
109
+ nn.Linear(hidden_dim, hidden_dim),
110
+ )
111
+ self.frequency_dim = frequency_dim
112
+
113
+ def forward(self, s: torch.Tensor) -> torch.Tensor:
114
+ s_freq = TimestepEmbedder.sinusoidal_embedding(s, self.frequency_dim)
115
+ return self.mlp(s_freq)
116
+
117
+
118
+ # ============================================================================
119
+ # Cell2Cell DiT — v2: AdaLN Source Injection
120
+ # ============================================================================
121
+
122
+ class Cell2CellDiT(nn.Module):
123
+ """Cell-to-Cell Latent Editing via Conditional Flow Matching.
124
+
125
+ v2: Source cell injected via AdaLN conditioning (NOT token concatenation).
126
+
127
+ combined_cond = t_emb + c_emb + s_emb + src_emb
128
+ ^time ^text ^strength ^source
129
+
130
+ This maintains the SAME 16-token sequence as DiT1D → same attention cost.
131
+ Only overhead vs DiT1D: 3 extra small MLP embedders (~1% compute).
132
+ """
133
+
134
+ def __init__(
135
+ self,
136
+ latent_dim: int = LATENT_DIM,
137
+ hidden_dim: int = DIT_HIDDEN_DIM,
138
+ cond_dim: int = PROJ_DIM,
139
+ num_blocks: int = DIT_NUM_BLOCKS,
140
+ num_heads: int = DIT_NUM_HEADS,
141
+ mlp_ratio: float = DIT_MLP_RATIO,
142
+ num_tokens: int = DIT_NUM_TOKENS,
143
+ cond_drop_prob: float = COND_DROP_PROB,
144
+ src_drop_prob: float = COND_DROP_PROB,
145
+ attn_drop: float = DEFAULT_ATTN_DROP,
146
+ proj_drop: float = DEFAULT_PROJ_DROP,
147
+ ):
148
+ super().__init__()
149
+ assert latent_dim % num_tokens == 0
150
+
151
+ self.latent_dim = latent_dim
152
+ self.hidden_dim = hidden_dim
153
+ self.num_tokens = num_tokens
154
+ self.token_dim = latent_dim // num_tokens
155
+ self.src_drop_prob = src_drop_prob
156
+
157
+ # --- Target input projection (IDENTICAL to DiT1D) ---
158
+ self.input_proj = nn.Linear(self.token_dim, hidden_dim)
159
+ self.pos_embed = nn.Parameter(torch.randn(1, num_tokens, hidden_dim) * 0.02)
160
+
161
+ # --- Source cell embedder (lightweight MLP, NOT tokenizer) ---
162
+ self.src_embedder = SourceCellEmbedder(latent_dim, hidden_dim)
163
+ self.null_source = nn.Parameter(torch.zeros(1, latent_dim))
164
+
165
+ # --- Timestep, condition, and edit strength embedders ---
166
+ self.t_embedder = TimestepEmbedder(hidden_dim)
167
+ self.c_embedder = ConditionEmbedder(cond_dim, hidden_dim, dropout_prob=cond_drop_prob)
168
+ self.s_embedder = EditStrengthEmbedder(hidden_dim)
169
+
170
+ # --- Transformer backbone (SAME blocks as DiT1D, SAME token count) ---
171
+ self.blocks = nn.ModuleList([
172
+ DiTBlock(hidden_dim, num_heads, mlp_ratio, attn_drop, proj_drop)
173
+ for _ in range(num_blocks)
174
+ ])
175
+
176
+ # --- Output projection ---
177
+ self.final_layer = DiTFinalLayer(hidden_dim, self.token_dim)
178
+
179
+ self._init_weights()
180
+
181
+ def _init_weights(self):
182
+ def _init(module):
183
+ if isinstance(module, nn.Linear):
184
+ nn.init.xavier_uniform_(module.weight)
185
+ if module.bias is not None:
186
+ nn.init.zeros_(module.bias)
187
+ self.input_proj.apply(_init)
188
+ nn.init.normal_(self.pos_embed, std=0.02)
189
+
190
+ def forward(
191
+ self,
192
+ z_t: torch.Tensor,
193
+ t: torch.Tensor,
194
+ z_src: torch.Tensor,
195
+ cond: torch.Tensor,
196
+ edit_strength: Optional[torch.Tensor] = None,
197
+ force_drop_cond: bool = False,
198
+ force_drop_src: bool = False,
199
+ ) -> torch.Tensor:
200
+ """
201
+ Parameters
202
+ ----------
203
+ z_t : (B, latent_dim) Noisy target latent.
204
+ t : (B,) Flow matching timestep ∈ [0, 1].
205
+ z_src : (B, latent_dim) Source cell embedding (anchor).
206
+ cond : (B, cond_dim) Edit condition vector.
207
+ edit_strength : (B,) Edit strength ∈ [0, 1]. Default 0.5.
208
+ force_drop_cond : bool Drop condition (for CFG).
209
+ force_drop_src : bool Drop source (for CFG).
210
+
211
+ Returns
212
+ -------
213
+ v_pred : (B, latent_dim) predicted velocity field
214
+ """
215
+ B = z_t.shape[0]
216
+ device = z_t.device
217
+
218
+ # --- Source cell dropout ---
219
+ if force_drop_src:
220
+ z_src_input = self.null_source.expand(B, -1)
221
+ elif self.training and self.src_drop_prob > 0:
222
+ mask = torch.bernoulli(
223
+ torch.ones(B, 1, device=device) * self.src_drop_prob
224
+ )
225
+ z_src_input = z_src * (1 - mask) + self.null_source.expand(B, -1) * mask
226
+ else:
227
+ z_src_input = z_src
228
+
229
+ # --- Tokenize target ONLY (16 tokens, same as DiT1D) ---
230
+ x = z_t.view(B, self.num_tokens, self.token_dim)
231
+ x = self.input_proj(x) + self.pos_embed
232
+ # (B, num_tokens, hidden_dim) ← 16 tokens, NOT 32!
233
+
234
+ # --- Combined AdaLN conditioning (ALL signals as one vector) ---
235
+ t_emb = self.t_embedder(t) # (B, hidden_dim)
236
+ c_emb = self.c_embedder(cond, force_drop=force_drop_cond) # (B, hidden_dim)
237
+ src_emb = self.src_embedder(z_src_input) # (B, hidden_dim)
238
+
239
+ if edit_strength is None:
240
+ edit_strength = torch.full((B,), 0.5, device=device)
241
+ s_emb = self.s_embedder(edit_strength) # (B, hidden_dim)
242
+
243
+ combined_cond = t_emb + c_emb + s_emb + src_emb
244
+ # (B, hidden_dim)
245
+
246
+ # --- Transformer blocks (16 tokens, same cost as DiT1D) ---
247
+ for block in self.blocks:
248
+ x = block(x, combined_cond)
249
+
250
+ # --- Final projection ---
251
+ v_tokens = self.final_layer(x, combined_cond)
252
+ # (B, num_tokens, token_dim)
253
+
254
+ v_pred = v_tokens.reshape(B, self.latent_dim)
255
+ return v_pred
256
+
257
+ def forward_with_cfg(
258
+ self,
259
+ z_t: torch.Tensor,
260
+ t: torch.Tensor,
261
+ z_src: torch.Tensor,
262
+ cond: torch.Tensor,
263
+ edit_strength: Optional[torch.Tensor] = None,
264
+ cfg_scale: float = CFG_SCALE,
265
+ src_cfg_scale: float = 1.5,
266
+ ) -> torch.Tensor:
267
+ """Classifier-Free Guidance with dual conditioning.
268
+
269
+ v_guided = v_uncond
270
+ + cfg_scale * (v_cond_src - v_uncond)
271
+ + src_cfg_scale * (v_cond_src - v_nosrc)
272
+ """
273
+ v_cond_src = self.forward(z_t, t, z_src, cond, edit_strength,
274
+ force_drop_cond=False, force_drop_src=False)
275
+ v_nocond_src = self.forward(z_t, t, z_src, cond, edit_strength,
276
+ force_drop_cond=True, force_drop_src=False)
277
+ v_cond_nosrc = self.forward(z_t, t, z_src, cond, edit_strength,
278
+ force_drop_cond=False, force_drop_src=True)
279
+ v_guided = (v_nocond_src
280
+ + cfg_scale * (v_cond_src - v_nocond_src)
281
+ + src_cfg_scale * (v_cond_src - v_cond_nosrc))
282
+ return v_guided
283
+
284
+ @torch.no_grad()
285
+ def edit(
286
+ self,
287
+ z_src: torch.Tensor,
288
+ cond: torch.Tensor,
289
+ edit_strength: float = 0.5,
290
+ num_steps: int = 4,
291
+ cfg_scale: float = CFG_SCALE,
292
+ src_cfg_scale: float = 1.5,
293
+ ) -> torch.Tensor:
294
+ """Edit cells: source cell + condition → edited cell.
295
+
296
+ 1. Start from noised source: z_start = (1-s)*z_src + s*ε
297
+ 2. Flow towards target condition in remaining steps
298
+ """
299
+ B = z_src.shape[0]
300
+ device = z_src.device
301
+
302
+ noise = torch.randn_like(z_src)
303
+ z = (1 - edit_strength) * z_src + edit_strength * noise
304
+
305
+ t_start = 1.0 - edit_strength
306
+ dt = edit_strength / max(num_steps, 1)
307
+ s_tensor = torch.full((B,), edit_strength, device=device)
308
+
309
+ for i in range(num_steps):
310
+ t_val = t_start + i * dt
311
+ t = torch.full((B,), t_val, device=device)
312
+ v = self.forward_with_cfg(
313
+ z, t, z_src, cond,
314
+ edit_strength=s_tensor,
315
+ cfg_scale=cfg_scale,
316
+ src_cfg_scale=src_cfg_scale,
317
+ )
318
+ z = z + v * dt
319
+ return z
320
+
321
+ @torch.no_grad()
322
+ def sample_text2cell(
323
+ self,
324
+ cond: torch.Tensor,
325
+ num_steps: int = 4,
326
+ cfg_scale: float = CFG_SCALE,
327
+ ) -> torch.Tensor:
328
+ """Fallback: pure text-to-cell generation (no source cell)."""
329
+ B = cond.shape[0]
330
+ device = next(self.parameters()).device
331
+
332
+ z = torch.randn(B, self.latent_dim, device=device)
333
+ null_src = self.null_source.expand(B, -1)
334
+ dt = 1.0 / num_steps
335
+
336
+ for i in range(num_steps):
337
+ t_val = i / num_steps
338
+ t = torch.full((B,), t_val, device=device)
339
+ v_cond = self.forward(z, t, null_src, cond,
340
+ force_drop_cond=False, force_drop_src=True)
341
+ v_uncond = self.forward(z, t, null_src, cond,
342
+ force_drop_cond=True, force_drop_src=True)
343
+ v = v_uncond + cfg_scale * (v_cond - v_uncond)
344
+ z = z + v * dt
345
+ return z
346
+
347
+ def count_parameters(self) -> dict:
348
+ total = sum(p.numel() for p in self.parameters())
349
+ trainable = sum(p.numel() for p in self.parameters() if p.requires_grad)
350
+ return {
351
+ "total": total,
352
+ "trainable": trainable,
353
+ "total_M": f"{total / 1e6:.2f}M",
354
+ "trainable_M": f"{trainable / 1e6:.2f}M",
355
+ }
@@ -0,0 +1,22 @@
1
+ # clop — Contrastive Language-Omics Pre-training (CLOP) Alignment
2
+ """
3
+ CLOP Aligner and loss/transform components.
4
+ Re-export so "from clop_dit.architecture.clop import CLOPAligner" etc. still work.
5
+ """
6
+ from .losses import (
7
+ TextWhiteningTransform,
8
+ ProjectionHead,
9
+ SigLIPLoss,
10
+ PrototypeSigLIPLoss,
11
+ InfoNCELoss,
12
+ )
13
+ from .aligner import CLOPAligner
14
+
15
+ __all__ = [
16
+ "CLOPAligner",
17
+ "TextWhiteningTransform",
18
+ "ProjectionHead",
19
+ "SigLIPLoss",
20
+ "PrototypeSigLIPLoss",
21
+ "InfoNCELoss",
22
+ ]