Put dataset launch commands first in each downstream task README

Update the five task READMEs to put complete per-dataset launch commands at the beginning. Add dataset command indexes to both project READMEs. All 15 existing command blocks remain unchanged. No source code, weights, configuration, raw data, or other repository files are modified.

Files changed (7) hide show

BioMod/README.md +30 -0
BioMod/cell_annotation/README.md +292 -282
BioMod/drug_combination/README.md +172 -170
BioMod/drug_response/README.md +73 -70
BioMod/gene_perturbation/README.md +333 -333
BioMod/zero_shot_batch/README.md +187 -187
README.md +30 -0

BioMod/README.md CHANGED Viewed

@@ -212,6 +212,36 @@ default with `RUN_TRAINING = False`; zero-shot inference uses
 path checks before enabling execution. The shell variable `BIOMOD_ROOT` is for
 the command examples only and does not override notebook configuration cells.
 ## Data Layout
 The Hugging Face repository includes datasets under the project-root `data/`

 path checks before enabling execution. The shell variable `BIOMOD_ROOT` is for
 the command examples only and does not override notebook configuration cells.
+## Commands by dataset
+Each row below links to a separate, complete launch command for that task and
+dataset or condition. Commands specify the input paths and output directory;
+you do not need to adapt a command from another dataset. Run them in Bash from
+the outer repository root after activating the environment. Read any
+dataset-specific input caveats before launching.
+| Task | Dataset or condition | Launch command |
+| --- | --- | --- |
+| Cell annotation | Kim Lung | [Complete command](cell_annotation/README.md#1-kim-lung) |
+| Cell annotation | Immune | [Complete command](cell_annotation/README.md#2-immune) |
+| Cell annotation | Liver | [Complete command](cell_annotation/README.md#3-liver) |
+| Cell annotation | MS (paired train/test files) | [Complete command](cell_annotation/README.md#4-ms) |
+| Cell annotation | hPancreas (hp14 paired files) | [Complete command](cell_annotation/README.md#5-hpancreas) |
+| Cell annotation | Zheng68K | [Complete command](cell_annotation/README.md#6-zheng68k) |
+| Cell annotation | Myeloid (reference/query files) | [Complete command](cell_annotation/README.md#7-myeloid) |
+| Zero-shot evaluation | hPNC | [Complete command](zero_shot_batch/README.md#1-hpnc) |
+| Zero-shot evaluation | BMMC | [Complete command](zero_shot_batch/README.md#2-bmmc) |
+| Zero-shot evaluation | Kim Lung: malignant cells retained | [Complete command](zero_shot_batch/README.md#3-kim-lung-malignant-cells-retained) |
+| Zero-shot evaluation | Kim Lung: malignant cells removed | [Complete command](zero_shot_batch/README.md#4-kim-lung-malignant-cells-removed) |
+| Single-drug response | GDSC-CCLE joint inputs | [Complete command](drug_response/README.md#run-the-bundled-gdsc-ccle-collection) |
+| Drug-combination synergy | Bundled training and validation collection | [Complete command](drug_combination/README.md#run-the-bundled-training-and-validation-collection) |
+| Gene perturbation | Norman | [Complete command](gene_perturbation/README.md#2-run-the-bundled-norman-simulation-split) |
+Paired training/test files and complementary drug/cell inputs belong to one
+run configuration. Historical reference copies do not add datasets. The
+[optional drug-combination cross-validation command](drug_combination/README.md#optional-five-fold-cross-validation-on-the-same-collection)
+uses the same collection under a different validation protocol.
 ## Data Layout
 The Hugging Face repository includes datasets under the project-root `data/`

BioMod/cell_annotation/README.md CHANGED Viewed

@@ -1,282 +1,292 @@
-# Cell Annotation with BioMod
-Fine-tune BioMod to predict cell-type labels from single-cell gene expression.
-The training script supports frozen, partially unfrozen, and fully trainable
-backbones with several cell-embedding heads.
-## Notebook
-See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
-## Files
-| File or directory | Purpose |
-| --- | --- |
-| [README.md](README.md) | File guide and command-line training example. |
-| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
-| [train.py](train.py) | Train and evaluate the cell-type classifier with the BioMod backbone. |
-## Optional Module Sources
-The optional [Hallmark and Reactome source definitions](../../model_dependencies/biomod_data_sources/)
-are stored separately from this task. They include
-[Hallmark modules](../../model_dependencies/biomod_data_sources/biomod1_hallmarks.json),
-[filtered Reactome modules](../../model_dependencies/biomod_data_sources/biomod2_reactome_2022_filtered.json),
-and a [JSON loading helper](../../model_dependencies/biomod_data_sources/load_biomod.py).
-These source resources are not the default runtime module definitions for the
-supplied checkpoint. The training example below continues to use
-`model_dependencies/biomod_data_all/` with the matching BioMod weights and configuration.
-## Dataset Commands
-The manuscript's annotation task covers seven benchmarks. The commands below
-map those benchmarks to the files currently bundled in this repository; paired
-files are one benchmark, not two separate datasets. Kim Lung has an unresolved
-missing-label policy documented in its section.
-Run from the outer repository root after installing the environment. Explicit
-relative paths resolve from the working directory. Each command writes to its
-own `tutorial_runs/` directory. Ordinary `python` supports one GPU; CUDA DDP with
-multiple processes additionally requires a working NCCL environment.
-The command blocks use Bash line continuations (`\`). Run them in Bash, such as
-Linux, WSL or Git Bash. In PowerShell, join each command into a single line
-instead of copying the Bash continuation characters.
-### Training Protocol and Limits
-The settings shared by these examples follow the available options for the
-annotation method described in manuscript Section 4.5 (PDF pages 24–25): attention
-pooling, a three-layer classifier, dropout 0.2, full encoder-path fine-tuning,
-AdamW, backbone and head learning rates of `1e-4`, and weight decay `0.01`.
-The script applies cosine annealing internally. `--label_smoothing 0` selects
-the plain cross-entropy loss shown in the manuscript instead of the script's
-default label smoothing of 0.1.
-The manuscript does not specify the annotation batch size, epoch limit, patience,
-or complete seed list in this section. The examples explicitly use batch size
-32, 50 epochs, patience 10 and seed 0 as launch settings; these values are not
-claimed to reproduce the reported five-run results. Reduce the batch size to
-fit available GPU memory and retain the actual experiment settings for reporting.
-The best checkpoint is selected by validation macro-F1, then evaluated on the
-test set.
-The classification report and confusion matrix include every declared class,
-including rows with zero test support. The report's macro average covers this
-full class list. Training and evaluation `macro_f1` values use the classes
-present in the true or predicted labels, so the two averages can differ when
-some declared classes are absent from both. Checkpoint selection keeps the
-existing validation metric.
-For single files, the entry point creates a stratified 70% / 10% / 20% split.
-For paired files, it splits the supplied training file 90% / 10% and uses the
-entire supplied test file for final evaluation. Stored split columns in `obs`
-are not used. The manuscript does not list these exact filenames, so the
-reference/query mapping is based on the bundled file organization and metadata.
-Both expression filtering thresholds are explicitly zero to preserve the supplied
-cells and genes. The entry point reads `adata.X` as supplied: it does not select
-`layers["counts"]` or `.raw`, normalize counts, or apply `log1p`. Metadata checks
-do not establish that each expression matrix has the intended preprocessing.
-Model training and manuscript-result reproduction have not been validated by
-these command examples.
-### 1. Kim Lung
-**Conditional configuration: missing-label handling must be resolved before
-benchmarking.** The file contains 32,493 cells, including 2,021 cells with missing
-`cell_type`. The current classifier converts labels to strings, so the command
-below would treat missing values as an extra class instead of excluding them.
-The manuscript does not specify the annotation policy for these cells. This
-block records the intended file and fields; it is not a verified reproduction
-command. Do not silently relabel or remove cells from the original file.
-```bash
-python BioMod/cell_annotation/train.py \
-    --data_path data/downstream/final_data/Kim2020_Lung.h5ad \
-    --label_column cell_type --gene_name_column gene_name \
-    --val_ratio 0.1 --test_ratio 0.2 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_kim_lung --run_name seed0
-```
-### 2. Immune
-Use the 33,506-cell matrix and its 16 `final_annotation` classes. Gene symbols
-are stored in `var.index`. A new stratified 70% / 10% / 20% split is created.
-```bash
-python BioMod/cell_annotation/train.py \
-    --data_path data/downstream/final_data/Immune_ALL_human.h5ad \
-    --label_column final_annotation --gene_name_column index \
-    --val_ratio 0.1 --test_ratio 0.2 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_immune --run_name seed0
-```
-### 3. Liver
-Use the 8,444-cell matrix and its 20 `cell_type` classes. Gene symbols are stored
-in `var.index`. A new stratified 70% / 10% / 20% split is created.
-```bash
-python BioMod/cell_annotation/train.py \
-    --data_path data/downstream/final_data/liver.h5ad \
-    --label_column cell_type --gene_name_column index \
-    --val_ratio 0.1 --test_ratio 0.2 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_liver --run_name seed0
-```
-### 4. MS
-Keep the 13,468-cell external test file separate. The 7,844-cell training file
-is split 90% / 10% for training and validation. All 18 test labels occur in the
-training file. Some training classes contain only three or four cells, so a
-small validation split may not contain every rare class.
-Use `index_column`, which contains Ensembl IDs in both files. The training file
-has an index *named* `gene_name`, but no `var["gene_name"]` column. Consequently,
-the unmodified `--dataset_preset ms` gene-column default is incompatible with
-that file. The explicit configuration below avoids that default.
-```bash
-python BioMod/cell_annotation/train.py \
-    --train_data_path data/downstream/final_data/MS/c_data.h5ad \
-    --test_data_path data/downstream/final_data/MS/filtered_ms_adata.h5ad \
-    --label_column celltype --test_label_column celltype --gene_name_column index_column \
-    --val_ratio 0.1 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_ms --run_name seed0
-```
-### 5. hPancreas
-The 10,600-cell training file declares 14 categorical labels and contains cells
-from 13 of them. `MHC class II` is already declared in its `Celltype` categories
-with a training count of **0**; the 4,218-cell test file contains **5** such cells.
-The entry point preserves the predefined training categories when constructing
-the classifier and label encoder, including categories with zero training cells.
-It does not create cells, add test cells to training, or infer the class list from
-the test labels. Stratification still operates only on the observed training
-cells. Keeping the output category does not supply positive training examples
-for it.
-Both files use `Celltype` and gene symbols in `var.index`. This annotation
-benchmark is distinct from the 16,382-cell hPNC integration dataset.
-```bash
-python BioMod/cell_annotation/train.py \
-    --train_data_path data/downstream/final_data/hp14/demo_train_with_MHC_class_II.h5ad \
-    --test_data_path data/downstream/final_data/hp14/demo_test.h5ad \
-    --label_column Celltype --test_label_column Celltype --gene_name_column index \
-    --val_ratio 0.1 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_hpancreas --run_name seed0
-```
-### 6. Zheng68K
-Use the 68,450-cell matrix and its 11 `celltype` classes. Gene symbols are stored
-in `var.index`. The 20% test split contains 13,690 cells, matching the test-set
-size reported in the manuscript; exact cell identities still depend on the seed
-and input ordering.
-```bash
-python BioMod/cell_annotation/train.py \
-    --data_path data/downstream/final_data/Zheng68K.h5ad \
-    --label_column celltype --gene_name_column index \
-    --val_ratio 0.1 --test_ratio 0.2 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_zheng68k --run_name seed0
-```
-### 7. Myeloid
-Use the 9,748-cell reference file for training/validation and retain the
-3,430-cell query file as the external test set. The reference contains 21
-observed labels and the query contains 11; every query label occurs in the
-reference. Both files use `cell_type` and gene symbols in `var.index`.
-```bash
-python BioMod/cell_annotation/train.py \
-    --train_data_path data/downstream/final_data/Myeloid/reference_adata.h5ad \
-    --test_data_path data/downstream/final_data/Myeloid/query_adata.h5ad \
-    --label_column cell_type --test_label_column cell_type --gene_name_column index \
-    --val_ratio 0.1 \
-    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_list_path model_dependencies/selected_genes_27k.txt \
-    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
-    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
-    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
-    --dropout 0.2 --label_smoothing 0 \
-    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
-    --min_genes 0 --min_cells 0 \
-    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
-    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_myeloid --run_name seed0
-```
-## Related Datasets
-`BMMC_processed.h5ad`, `human_pancreas_norm_complexBatch_with_gene_name.h5ad`,
-and the lung file without malignant cells belong to the documented
-[zero-shot integration conditions](../zero_shot_batch/README.md#dataset-commands).
-`norman/perturb_processed.h5ad` belongs to
-[gene perturbation prediction](../gene_perturbation/README.md).
-Their presence in the data directory does not add annotation benchmarks to the
-seven listed above.

+# Cell Annotation with BioMod
+Fine-tune BioMod to predict cell-type labels from single-cell gene expression.
+The training script supports frozen, partially unfrozen, and fully trainable
+backbones with several cell-embedding heads.
+## Dataset Commands
+| Dataset | Complete launch command |
+| --- | --- |
+| Kim Lung | [Command](#1-kim-lung) |
+| Immune | [Command](#2-immune) |
+| Liver | [Command](#3-liver) |
+| MS (paired train/test files) | [Command](#4-ms) |
+| hPancreas (hp14 paired files) | [Command](#5-hpancreas) |
+| Zheng68K | [Command](#6-zheng68k) |
+| Myeloid (reference/query files) | [Command](#7-myeloid) |
+The manuscript's annotation task covers seven benchmarks. The commands below
+map those benchmarks to the files currently bundled in this repository; paired
+files are one benchmark, not two separate datasets. Kim Lung has an unresolved
+missing-label policy documented in its section.
+Run from the outer repository root after installing the environment. Explicit
+relative paths resolve from the working directory. Each command writes to its
+own `tutorial_runs/` directory. Ordinary `python` supports one GPU; CUDA DDP with
+multiple processes additionally requires a working NCCL environment.
+The command blocks use Bash line continuations (`\`). Run them in Bash, such as
+Linux, WSL or Git Bash. In PowerShell, join each command into a single line
+instead of copying the Bash continuation characters.
+### Training Protocol and Limits
+The settings shared by these examples follow the available options for the
+annotation method described in manuscript Section 4.5 (PDF pages 24–25): attention
+pooling, a three-layer classifier, dropout 0.2, full encoder-path fine-tuning,
+AdamW, backbone and head learning rates of `1e-4`, and weight decay `0.01`.
+The script applies cosine annealing internally. `--label_smoothing 0` selects
+the plain cross-entropy loss shown in the manuscript instead of the script's
+default label smoothing of 0.1.
+The manuscript does not specify the annotation batch size, epoch limit, patience,
+or complete seed list in this section. The examples explicitly use batch size
+32, 50 epochs, patience 10 and seed 0 as launch settings; these values are not
+claimed to reproduce the reported five-run results. Reduce the batch size to
+fit available GPU memory and retain the actual experiment settings for reporting.
+The best checkpoint is selected by validation macro-F1, then evaluated on the
+test set.
+The classification report and confusion matrix include every declared class,
+including rows with zero test support. The report's macro average covers this
+full class list. Training and evaluation `macro_f1` values use the classes
+present in the true or predicted labels, so the two averages can differ when
+some declared classes are absent from both. Checkpoint selection keeps the
+existing validation metric.
+For single files, the entry point creates a stratified 70% / 10% / 20% split.
+For paired files, it splits the supplied training file 90% / 10% and uses the
+entire supplied test file for final evaluation. Stored split columns in `obs`
+are not used. The manuscript does not list these exact filenames, so the
+reference/query mapping is based on the bundled file organization and metadata.
+Both expression filtering thresholds are explicitly zero to preserve the supplied
+cells and genes. The entry point reads `adata.X` as supplied: it does not select
+`layers["counts"]` or `.raw`, normalize counts, or apply `log1p`. Metadata checks
+do not establish that each expression matrix has the intended preprocessing.
+Model training and manuscript-result reproduction have not been validated by
+these command examples.
+### 1. Kim Lung
+**Conditional configuration: missing-label handling must be resolved before
+benchmarking.** The file contains 32,493 cells, including 2,021 cells with missing
+`cell_type`. The current classifier converts labels to strings, so the command
+below would treat missing values as an extra class instead of excluding them.
+The manuscript does not specify the annotation policy for these cells. This
+block records the intended file and fields; it is not a verified reproduction
+command. Do not silently relabel or remove cells from the original file.
+```bash
+python BioMod/cell_annotation/train.py \
+    --data_path data/downstream/final_data/Kim2020_Lung.h5ad \
+    --label_column cell_type --gene_name_column gene_name \
+    --val_ratio 0.1 --test_ratio 0.2 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_kim_lung --run_name seed0
+```
+### 2. Immune
+Use the 33,506-cell matrix and its 16 `final_annotation` classes. Gene symbols
+are stored in `var.index`. A new stratified 70% / 10% / 20% split is created.
+```bash
+python BioMod/cell_annotation/train.py \
+    --data_path data/downstream/final_data/Immune_ALL_human.h5ad \
+    --label_column final_annotation --gene_name_column index \
+    --val_ratio 0.1 --test_ratio 0.2 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_immune --run_name seed0
+```
+### 3. Liver
+Use the 8,444-cell matrix and its 20 `cell_type` classes. Gene symbols are stored
+in `var.index`. A new stratified 70% / 10% / 20% split is created.
+```bash
+python BioMod/cell_annotation/train.py \
+    --data_path data/downstream/final_data/liver.h5ad \
+    --label_column cell_type --gene_name_column index \
+    --val_ratio 0.1 --test_ratio 0.2 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_liver --run_name seed0
+```
+### 4. MS
+Keep the 13,468-cell external test file separate. The 7,844-cell training file
+is split 90% / 10% for training and validation. All 18 test labels occur in the
+training file. Some training classes contain only three or four cells, so a
+small validation split may not contain every rare class.
+Use `index_column`, which contains Ensembl IDs in both files. The training file
+has an index *named* `gene_name`, but no `var["gene_name"]` column. Consequently,
+the unmodified `--dataset_preset ms` gene-column default is incompatible with
+that file. The explicit configuration below avoids that default.
+```bash
+python BioMod/cell_annotation/train.py \
+    --train_data_path data/downstream/final_data/MS/c_data.h5ad \
+    --test_data_path data/downstream/final_data/MS/filtered_ms_adata.h5ad \
+    --label_column celltype --test_label_column celltype --gene_name_column index_column \
+    --val_ratio 0.1 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_ms --run_name seed0
+```
+### 5. hPancreas
+The 10,600-cell training file declares 14 categorical labels and contains cells
+from 13 of them. `MHC class II` is already declared in its `Celltype` categories
+with a training count of **0**; the 4,218-cell test file contains **5** such cells.
+The entry point preserves the predefined training categories when constructing
+the classifier and label encoder, including categories with zero training cells.
+It does not create cells, add test cells to training, or infer the class list from
+the test labels. Stratification still operates only on the observed training
+cells. Keeping the output category does not supply positive training examples
+for it.
+Both files use `Celltype` and gene symbols in `var.index`. This annotation
+benchmark is distinct from the 16,382-cell hPNC integration dataset.
+```bash
+python BioMod/cell_annotation/train.py \
+    --train_data_path data/downstream/final_data/hp14/demo_train_with_MHC_class_II.h5ad \
+    --test_data_path data/downstream/final_data/hp14/demo_test.h5ad \
+    --label_column Celltype --test_label_column Celltype --gene_name_column index \
+    --val_ratio 0.1 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_hpancreas --run_name seed0
+```
+### 6. Zheng68K
+Use the 68,450-cell matrix and its 11 `celltype` classes. Gene symbols are stored
+in `var.index`. The 20% test split contains 13,690 cells, matching the test-set
+size reported in the manuscript; exact cell identities still depend on the seed
+and input ordering.
+```bash
+python BioMod/cell_annotation/train.py \
+    --data_path data/downstream/final_data/Zheng68K.h5ad \
+    --label_column celltype --gene_name_column index \
+    --val_ratio 0.1 --test_ratio 0.2 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_zheng68k --run_name seed0
+```
+### 7. Myeloid
+Use the 9,748-cell reference file for training/validation and retain the
+3,430-cell query file as the external test set. The reference contains 21
+observed labels and the query contains 11; every query label occurs in the
+reference. Both files use `cell_type` and gene symbols in `var.index`.
+```bash
+python BioMod/cell_annotation/train.py \
+    --train_data_path data/downstream/final_data/Myeloid/reference_adata.h5ad \
+    --test_data_path data/downstream/final_data/Myeloid/query_adata.h5ad \
+    --label_column cell_type --test_label_column cell_type --gene_name_column index \
+    --val_ratio 0.1 \
+    --biomod_checkpoint weight/BioMod.pth --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_list_path model_dependencies/selected_genes_27k.txt \
+    --gene2ens_file model_dependencies/gene2ens.csv --gene_mapping_path model_dependencies/gene2ens.csv \
+    --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
+    --head_type attn_pool --finetune_mode full --cls_decoder_layers 3 \
+    --dropout 0.2 --label_smoothing 0 \
+    --lr_head 1e-4 --lr_backbone 1e-4 --weight_decay 0.01 \
+    --min_genes 0 --min_cells 0 \
+    --batch_size 32 --epochs 50 --patience 10 --seed 0 \
+    --save_test_artifacts --output_dir tutorial_runs/cell_annotation_myeloid --run_name seed0
+```
+## Notebook
+See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
+## Files
+| File or directory | Purpose |
+| --- | --- |
+| [README.md](README.md) | File guide and command-line training example. |
+| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
+| [train.py](train.py) | Train and evaluate the cell-type classifier with the BioMod backbone. |
+## Optional Module Sources
+The optional [Hallmark and Reactome source definitions](../../model_dependencies/biomod_data_sources/)
+are stored separately from this task. They include
+[Hallmark modules](../../model_dependencies/biomod_data_sources/biomod1_hallmarks.json),
+[filtered Reactome modules](../../model_dependencies/biomod_data_sources/biomod2_reactome_2022_filtered.json),
+and a [JSON loading helper](../../model_dependencies/biomod_data_sources/load_biomod.py).
+These source resources are not the default runtime module definitions for the
+supplied checkpoint. The dataset commands use
+`model_dependencies/biomod_data_all/` with the matching BioMod weights and configuration.
+## Related Datasets
+`BMMC_processed.h5ad`, `human_pancreas_norm_complexBatch_with_gene_name.h5ad`,
+and the lung file without malignant cells belong to the documented
+[zero-shot integration conditions](../zero_shot_batch/README.md#dataset-commands).
+`norman/perturb_processed.h5ad` belongs to
+[gene perturbation prediction](../gene_perturbation/README.md).
+Their presence in the data directory does not add annotation benchmarks to the
+seven listed above.

BioMod/drug_combination/README.md CHANGED Viewed

@@ -1,170 +1,172 @@
-# Drug Combination Synergy Prediction with BioMod
-This task predicts drug-combination synergy using BioMod cell embeddings from
-the BioMod encoder and GCN-based drug molecular graph encoders. Use the
-[BioMod model weights and matching configuration](../../README.md#biomod-model-weights).
-It is adapted from scLong's drug-combination implementation
-(DeepDDs), replacing the scfm/geneformer cell-line representation with
-BioMod.
-## Notebook
-See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
-## Files
-| File or directory | Purpose |
-| --- | --- |
-| [README.md](README.md) | File guide, model and data descriptions, training commands, and evaluation details. |
-| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
-| [train.py](train.py) | Train and validate drug-combination synergy prediction with drug graph encoders and BioMod cell embeddings. |
-## Model Architecture
-| Component | Description |
-| --- | --- |
-| Drug branch | Three PyG GCNConv layers (78 -> 78 -> 156 -> 312), `global_max_pool`, and two fully connected layers to 128 dimensions |
-| Cell branch | Pretrained BioMod encoder, configurable pooling, and an MLP to 128 dimensions |
-| Fusion layer | `concat(drug1, drug2, cell) = 384 -> MLP -> 2-class prediction` |
-The drug1 and drug2 branches share weights, matching scLong.
-## Bundled dataset
-The current entry point uses one collection with separate training and validation
-inputs under `data/downstream/final_data/drug_combination_synergy/data_summary/`.
-| Input below `data_summary/` | Purpose |
-| --- | --- |
-| `new_labels_0_10.csv` | 12,415 training records with `drug1`, `drug2`, `cell`, and `label` columns. |
-| `new_cell_features_954.csv` | Training expression; the loader removes the transcript-ID row and obtains 31 cell rows by 954 genes. |
-| `test_data/independent_input.csv` | 668 validation records used for checkpoint selection. |
-| `test_data/independent_cell_features_954.csv` | Validation expression; the loader removes the transcript-ID row and obtains 1,019 cell rows by 954 genes. |
-The directory name `test_data/` is retained for compatibility. The current script
-uses these files as validation inputs. Drug molecular graphs are constructed from
-the SMILES strings already stored in the label tables' `drug1` and `drug2` columns.
-`smiles_0_10.csv` and the other source tables are retained for reference and are not
-additional required inputs to this entry point.
-The older `data/downstream/final_data/drug_response_pytorch/drug_combination/`
-package is a reference copy, not another dataset for this task.
-## Dependencies
-- PyTorch
-- PyTorch Geometric (`torch_geometric`)
-- RDKit
-- networkx
-- scikit-learn
-- pandas, numpy
-## Run the bundled training and validation collection
-Activate the environment described in the [project README](../../README.md), then
-run these commands in Bash from the outer repository root containing `BioMod/`,
-`data/`, `model_dependencies/`, and `weight/`. The backslashes continue commands
-across lines in Bash; they are not PowerShell continuation characters. Use a
-Linux or WSL Bash shell with the required environment. Built-in resource defaults
-resolve from the script location; explicit relative paths resolve from the
-working directory.
-```bash
-python BioMod/drug_combination/train.py \
-    --data_dir data/downstream/final_data/drug_combination_synergy/data_summary \
-    --label_file new_labels_0_10.csv \
-    --cell_file new_cell_features_954.csv \
-    --validation_label_file test_data/independent_input.csv \
-    --validation_cell_file test_data/independent_cell_features_954.csv \
-    --checkpoint_path weight/BioMod.pth \
-    --hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --n_folds 1 \
-    --epochs 500 \
-    --batch_size 256 \
-    --pool_method max \
-    --output_dir tutorial_runs/drug_combination_synergy
-```
-These are example settings for the bundled inputs, not a verified reproduction
-of manuscript results. The default domain-generalization mode trains on the full
-training collection and selects a checkpoint using the separate validation
-collection. `--n_folds 1` requests one run; leaving its default of 5 in this mode
-repeats full-training/full-validation runs rather than performing five-fold
-cross-validation.
-The manuscript describes the 668-sample collection as an independent test set.
-The current code uses it for checkpoint selection, so its reported AUROC is a
-validation result and must not be presented as an independent final test estimate.
-### Optional five-fold cross-validation on the same collection
-This is an alternative validation protocol, not a second dataset. The current
-implementation still reads all four input tables before selecting the held-out
-folds from the training collection.
-```bash
-python BioMod/drug_combination/train.py \
-    --data_dir data/downstream/final_data/drug_combination_synergy/data_summary \
-    --checkpoint_path weight/BioMod.pth \
-    --hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --no_domain_gen \
-    --n_folds 5 \
-    --epochs 500 \
-    --batch_size 256 \
-    --pool_method max \
-    --output_dir tutorial_runs/drug_combination_synergy_cv
-```
-### Input and cache changes
-Use `--gene_list_path`, `--gene_mapping_path`, `--gene2vec_path`, and
-`--symbol2ens_path` only when replacing the bundled shared assets. After changing
-model weights, pooling, or input tables, append `--force_preprocess` to regenerate
-the embedding cache and the PyG datasets under `data_summary/processed/`; an
-existing cache is not automatically keyed by all model and input settings.
-The input files and command arguments have been checked. This documentation update
-did not execute training or verify checkpoint performance.
-## Main Arguments
-| Argument | Default | Description |
-| --- | --- | --- |
-| `--checkpoint_path` | Required | Path to the BioMod model weights |
-| `--hyper_params_path` | Required | Path to the BioMod hyper-parameter pkl file |
-| `--biomod_data_dir` | None | Directory containing module data files |
-| `--data_dir` | `data/downstream/final_data/drug_combination_synergy/data_summary` | Data directory |
-| `--validation_label_file` | `test_data/independent_input.csv` | Validation labels for checkpoint selection; legacy alias: `--test_label_file` |
-| `--validation_cell_file` | `test_data/independent_cell_features_954.csv` | Validation cell features; legacy alias: `--test_cell_file` |
-| `--batch_size` | 256 | Training batch size |
-| `--lr` | 1e-4 | Learning rate |
-| `--epochs` | 100 | Number of training epochs |
-| `--n_folds` | 5 | Number of folds |
-| `--domain_gen` | True | Domain generalization mode: train on the full training set and select checkpoints using a separate validation set |
-| `--eval_interval` | 5 | Evaluate every N epochs |
-| `--pool_method` | mean | BioMod pooling method (`mean`, `max`, or `concat`) |
-| `--cache_emb` | True | Cache cell embeddings to a `.npy` file |
-| `--force_preprocess` | False | Force regeneration of the PyG dataset |
-## Outputs
-Results are saved under `--output_dir` (default: `BioMod/drug_combination/results/` relative to the repository root):
-- `best_model_fold{i}.pt` - model weights selected by the highest validation AUC for each fold
-- `fpr_tpr_fold{i}.pkl` - validation FPR/TPR curve data for drawing ROC curves
-- `cell_emb_cache_{pool_method}.npy` - cached BioMod cell embeddings
-## Evaluation Metrics
-Every `--eval_interval` epochs, the script evaluates AUC, PR_AUC, ACC, BACC,
-PREC, TPR, and KAPPA on the validation set, matching scLong's metric definitions.
-The checkpoint with the highest validation AUC is saved for each fold. In
-`--no_domain_gen` mode, each held-out fold serves as the validation set.
-This naming update preserves the data, splits, checkpoint-selection behavior,
-output filenames, metric column names, and legacy dataset cache IDs. It does not
-create or evaluate an independent final test set; the reported values are
-validation results used during model selection, not final test estimates.

+# Drug Combination Synergy Prediction with BioMod
+This task predicts drug-combination synergy using BioMod cell embeddings from
+the BioMod encoder and GCN-based drug molecular graph encoders. Use the
+[BioMod model weights and matching configuration](../../README.md#biomod-model-weights).
+It is adapted from scLong's drug-combination implementation
+(DeepDDs), replacing the scfm/geneformer cell-line representation with
+BioMod.
+## Dataset Commands
+### Bundled dataset
+The current entry point uses one collection with separate training and validation
+inputs under `data/downstream/final_data/drug_combination_synergy/data_summary/`.
+| Input below `data_summary/` | Purpose |
+| --- | --- |
+| `new_labels_0_10.csv` | 12,415 training records with `drug1`, `drug2`, `cell`, and `label` columns. |
+| `new_cell_features_954.csv` | Training expression; the loader removes the transcript-ID row and obtains 31 cell rows by 954 genes. |
+| `test_data/independent_input.csv` | 668 validation records used for checkpoint selection. |
+| `test_data/independent_cell_features_954.csv` | Validation expression; the loader removes the transcript-ID row and obtains 1,019 cell rows by 954 genes. |
+The directory name `test_data/` is retained for compatibility. The current script
+uses these files as validation inputs. Drug molecular graphs are constructed from
+the SMILES strings already stored in the label tables' `drug1` and `drug2` columns.
+`smiles_0_10.csv` and the other source tables are retained for reference and are not
+additional required inputs to this entry point.
+The older `data/downstream/final_data/drug_response_pytorch/drug_combination/`
+package is a reference copy, not another dataset for this task.
+### Dependencies
+- PyTorch
+- PyTorch Geometric (`torch_geometric`)
+- RDKit
+- networkx
+- scikit-learn
+- pandas, numpy
+### Run the bundled training and validation collection
+Activate the environment described in the [project README](../../README.md), then
+run these commands in Bash from the outer repository root containing `BioMod/`,
+`data/`, `model_dependencies/`, and `weight/`. The backslashes continue commands
+across lines in Bash; they are not PowerShell continuation characters. Use a
+Linux or WSL Bash shell with the required environment. Built-in resource defaults
+resolve from the script location; explicit relative paths resolve from the
+working directory.
+```bash
+python BioMod/drug_combination/train.py \
+    --data_dir data/downstream/final_data/drug_combination_synergy/data_summary \
+    --label_file new_labels_0_10.csv \
+    --cell_file new_cell_features_954.csv \
+    --validation_label_file test_data/independent_input.csv \
+    --validation_cell_file test_data/independent_cell_features_954.csv \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --n_folds 1 \
+    --epochs 500 \
+    --batch_size 256 \
+    --pool_method max \
+    --output_dir tutorial_runs/drug_combination_synergy
+```
+These are example settings for the bundled inputs, not a verified reproduction
+of manuscript results. The default domain-generalization mode trains on the full
+training collection and selects a checkpoint using the separate validation
+collection. `--n_folds 1` requests one run; leaving its default of 5 in this mode
+repeats full-training/full-validation runs rather than performing five-fold
+cross-validation.
+The manuscript describes the 668-sample collection as an independent test set.
+The current code uses it for checkpoint selection, so its reported AUROC is a
+validation result and must not be presented as an independent final test estimate.
+#### Optional five-fold cross-validation on the same collection
+This is an alternative validation protocol, not a second dataset. The current
+implementation still reads all four input tables before selecting the held-out
+folds from the training collection.
+```bash
+python BioMod/drug_combination/train.py \
+    --data_dir data/downstream/final_data/drug_combination_synergy/data_summary \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --no_domain_gen \
+    --n_folds 5 \
+    --epochs 500 \
+    --batch_size 256 \
+    --pool_method max \
+    --output_dir tutorial_runs/drug_combination_synergy_cv
+```
+#### Input and cache changes
+Use `--gene_list_path`, `--gene_mapping_path`, `--gene2vec_path`, and
+`--symbol2ens_path` only when replacing the bundled shared assets. After changing
+model weights, pooling, or input tables, append `--force_preprocess` to regenerate
+the embedding cache and the PyG datasets under `data_summary/processed/`; an
+existing cache is not automatically keyed by all model and input settings.
+The input files and command arguments have been checked. This documentation update
+did not execute training or verify checkpoint performance.
+## Notebook
+See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
+## Files
+| File or directory | Purpose |
+| --- | --- |
+| [README.md](README.md) | File guide, model and data descriptions, training commands, and evaluation details. |
+| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
+| [train.py](train.py) | Train and validate drug-combination synergy prediction with drug graph encoders and BioMod cell embeddings. |
+## Model Architecture
+| Component | Description |
+| --- | --- |
+| Drug branch | Three PyG GCNConv layers (78 -> 78 -> 156 -> 312), `global_max_pool`, and two fully connected layers to 128 dimensions |
+| Cell branch | Pretrained BioMod encoder, configurable pooling, and an MLP to 128 dimensions |
+| Fusion layer | `concat(drug1, drug2, cell) = 384 -> MLP -> 2-class prediction` |
+The drug1 and drug2 branches share weights, matching scLong.
+## Main Arguments
+| Argument | Default | Description |
+| --- | --- | --- |
+| `--checkpoint_path` | Required | Path to the BioMod model weights |
+| `--hyper_params_path` | Required | Path to the BioMod hyper-parameter pkl file |
+| `--biomod_data_dir` | None | Directory containing module data files |
+| `--data_dir` | `data/downstream/final_data/drug_combination_synergy/data_summary` | Data directory |
+| `--validation_label_file` | `test_data/independent_input.csv` | Validation labels for checkpoint selection; legacy alias: `--test_label_file` |
+| `--validation_cell_file` | `test_data/independent_cell_features_954.csv` | Validation cell features; legacy alias: `--test_cell_file` |
+| `--batch_size` | 256 | Training batch size |
+| `--lr` | 1e-4 | Learning rate |
+| `--epochs` | 100 | Number of training epochs |
+| `--n_folds` | 5 | Number of folds |
+| `--domain_gen` | True | Domain generalization mode: train on the full training set and select checkpoints using a separate validation set |
+| `--eval_interval` | 5 | Evaluate every N epochs |
+| `--pool_method` | mean | BioMod pooling method (`mean`, `max`, or `concat`) |
+| `--cache_emb` | True | Cache cell embeddings to a `.npy` file |
+| `--force_preprocess` | False | Force regeneration of the PyG dataset |
+## Outputs
+Results are saved under `--output_dir` (default: `BioMod/drug_combination/results/` relative to the repository root):
+- `best_model_fold{i}.pt` - model weights selected by the highest validation AUC for each fold
+- `fpr_tpr_fold{i}.pkl` - validation FPR/TPR curve data for drawing ROC curves
+- `cell_emb_cache_{pool_method}.npy` - cached BioMod cell embeddings
+## Evaluation Metrics
+Every `--eval_interval` epochs, the script evaluates AUC, PR_AUC, ACC, BACC,
+PREC, TPR, and KAPPA on the validation set, matching scLong's metric definitions.
+The checkpoint with the highest validation AUC is saved for each fold. In
+`--no_domain_gen` mode, each held-out fold serves as the validation set.
+This naming update preserves the data, splits, checkpoint-selection behavior,
+output filenames, metric column names, and legacy dataset cache IDs. It does not
+create or evaluate an independent final test set; the reported values are
+validation results used during model selection, not final test estimates.

BioMod/drug_response/README.md CHANGED Viewed

@@ -1,70 +1,73 @@
-# Drug Response Prediction with BioMod
-Predict drug response from drug molecular graphs and BioMod cell embeddings.
-The training script combines a graph-based drug encoder with the pretrained
-BioMod backbone.
-## Notebook
-See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
-## Files
-| File or directory | Purpose |
-| --- | --- |
-| [README.md](README.md) | File guide and command-line training example. |
-| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
-| [train.py](train.py) | Load drug-response data, build the model, train, and evaluate validation metrics. |
-## Bundled dataset
-The current entry point uses one joint GDSC-CCLE collection. GDSC supplies drug
-information and responses; CCLE supplies cell-line annotations and expression.
-They are complementary inputs to one run, rather than separate training datasets.
-Use the cleaned collection under
-`data/downstream/final_data/single_drug_response/data/`.
-| Input below the data directory | Purpose |
-| --- | --- |
-| `GDSC/1.Drug_listMon Jun 24 09_00_55 2019.csv` | Map drug IDs to PubChem IDs. |
-| `GDSC/drug_graph_feat/*.hkl` | Precomputed molecular graphs; 223 files are bundled. |
-| `CCLE/Cell_lines_annotations_20181226.txt` | Map cell-line IDs to cancer types. |
-| `CCLE/genomic_expression_561celllines_697genes_demap_features.csv` | Expression for 561 cell lines and 697 genes. |
-| `CCLE/GDSC_IC50.csv` | Drug-response matrix used to construct matched response records. |
-The older `data/downstream/final_data/drug_response_pytorch/` package is retained
-for reference. It is not an additional dataset for this task. Files under
-`single_drug_response/optional_reference/` are not consumed by this entry point.
-## Run the bundled GDSC-CCLE collection
-Activate the environment described in the [project README](../../README.md), then
-run these commands in Bash from the outer repository root containing `BioMod/`,
-`data/`, `model_dependencies/`, and `weight/`. The backslashes continue commands
-across lines in Bash; they are not PowerShell continuation characters. Use a
-Linux or WSL Bash shell with the required environment. Built-in resource defaults
-resolve from the script location; explicit relative paths resolve from the
-working directory.
-```bash
-python BioMod/drug_response/train.py \
-    --gpu_id 0 \
-    --data_path data/downstream/final_data/single_drug_response/data \
-    --checkpoint_path weight/BioMod.pth \
-    --hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --epochs 300 \
-    --batch_size 32 \
-    --pool_method max \
-    --save_dir tutorial_runs/drug_response_gdsc_ccle
-```
-This is a command for the bundled inputs, with example training settings. It has
-not been validated as a reproduction of the manuscript results. The current code
-uses a fixed seed of 0 and splits matched records by cancer type into approximately
-95% training and 5% validation. Validation Pearson correlation determines the best
-checkpoint. It does not create a separate final test set, and it does not implement
-the manuscript's 70%/10%/20% train/validation/test protocol.
-The data and asset paths have been checked for existence. A complete training run
-and checkpoint performance have not been verified by this documentation update.

+# Drug Response Prediction with BioMod
+Predict drug response from drug molecular graphs and BioMod cell embeddings.
+The training script combines a graph-based drug encoder with the pretrained
+BioMod backbone.
+## Dataset Commands
+### Bundled dataset
+The current entry point uses one joint GDSC-CCLE collection. GDSC supplies drug
+information and responses; CCLE supplies cell-line annotations and expression.
+They are complementary inputs to one run, rather than separate training datasets.
+Use the cleaned collection under
+`data/downstream/final_data/single_drug_response/data/`.
+| Input below the data directory | Purpose |
+| --- | --- |
+| `GDSC/1.Drug_listMon Jun 24 09_00_55 2019.csv` | Map drug IDs to PubChem IDs. |
+| `GDSC/drug_graph_feat/*.hkl` | Precomputed molecular graphs; 223 files are bundled. |
+| `CCLE/Cell_lines_annotations_20181226.txt` | Map cell-line IDs to cancer types. |
+| `CCLE/genomic_expression_561celllines_697genes_demap_features.csv` | Expression for 561 cell lines and 697 genes. |
+| `CCLE/GDSC_IC50.csv` | Drug-response matrix used to construct matched response records. |
+The older `data/downstream/final_data/drug_response_pytorch/` package is retained
+for reference. It is not an additional dataset for this task. Files under
+`single_drug_response/optional_reference/` are not consumed by this entry point.
+### Run the bundled GDSC-CCLE collection
+Activate the environment described in the [project README](../../README.md), then
+run these commands in Bash from the outer repository root containing `BioMod/`,
+`data/`, `model_dependencies/`, and `weight/`. The backslashes continue commands
+across lines in Bash; they are not PowerShell continuation characters. Use a
+Linux or WSL Bash shell with the required environment. Built-in resource defaults
+resolve from the script location; explicit relative paths resolve from the
+working directory.
+```bash
+python BioMod/drug_response/train.py \
+    --gpu_id 0 \
+    --data_path data/downstream/final_data/single_drug_response/data \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --epochs 300 \
+    --batch_size 32 \
+    --pool_method max \
+    --save_dir tutorial_runs/drug_response_gdsc_ccle
+```
+This is a command for the bundled inputs, with example training settings. It has
+not been validated as a reproduction of the manuscript results. The current code
+uses a fixed seed of 0 and splits matched records by cancer type into approximately
+95% training and 5% validation. Validation Pearson correlation determines the best
+checkpoint. It does not create a separate final test set, and it does not implement
+the manuscript's 70%/10%/20% train/validation/test protocol.
+The data and asset paths have been checked for existence. A complete training run
+and checkpoint performance have not been verified by this documentation update.
+## Notebook
+See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
+## Files
+| File or directory | Purpose |
+| --- | --- |
+| [README.md](README.md) | File guide and command-line training example. |
+| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
+| [train.py](train.py) | Load drug-response data, build the model, train, and evaluate validation metrics. |

BioMod/gene_perturbation/README.md CHANGED Viewed

@@ -1,333 +1,333 @@
-# Gene Perturbation Prediction with BioMod
-This document describes the BioMod gene perturbation workflow (GEARS), using
-the `BioMod` encoder. The
-[BioMod model weights and matching configuration](../../README.md#biomod-model-weights)
-are shared with the other downstream tasks.
-## Notebook
-See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
-## Files
-| File or directory | Purpose |
-| --- | --- |
-| [README.md](README.md) | File guide, model details, training commands, and troubleshooting notes. |
-| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
-| [train.py](train.py) | Configure and launch distributed gene perturbation training. |
-| [components/](components/) | Model, data-processing, training, and evaluation helpers. |
-| [components/model.py](components/model.py) | Define the BioMod-backed GEARS model and recover gene-level features. |
-| [components/trainer.py](components/trainer.py) | Manage model training, checkpointing, and evaluation. |
-| [components/dataset.py](components/dataset.py) | Prepare perturbation datasets, splits, and graph data loaders. |
-| [components/data_utils.py](components/data_utils.py) | Compute differential-expression annotations and construct data splits. |
-| [components/inference.py](components/inference.py) | Run inference and compute perturbation prediction metrics. |
-| [components/training_utils.py](components/training_utils.py) | Provide distributed training, checkpoint, logging, and optimization helpers. |
-| [components/utils.py](components/utils.py) | Provide perturbation parsing, gene-network, loss, and prediction utilities. |
-| [components/__init__.py](components/__init__.py) | Mark the helper directory as a Python package. |
-## Overview
-This adaptation replaces the original GEARS gene perturbation model based on
-`DualEncoderSCFM` with `BioMod`. The main adaptation points
-are:
-1. **Model architecture adaptation**: replace the original dual-encoder model with a module-based encoder-only model.
-2. **Data format adaptation**: handle module-based input data.
-3. **Embedding extraction adaptation**: recover gene-level embeddings from module encodings.
-## Main Adaptations
-### 1. `SCFM_BioMod` (`components/model.py`)
-`SCFM_BioMod` wraps `BioMod` and provides these functions:
-- **Input handling**: reindex input gene expression values to the BioMod gene order.
-- **Module encoding**: obtain module-level encodings from `BioMod`.
-- **Gene embedding recovery**: recover gene-level embeddings from module encodings.
-  - For each gene, find all modules that contain it.
-  - Average the encodings of those modules to obtain the gene embedding.
-  - If a gene is not included in any module, use the global average as a fallback.
-- **Output reindexing**: reindex gene embeddings back to the input gene order.
-**Key adaptation**:
-```python
-# Recover gene-level embeddings from module encodings.
-for gene_idx in range(len(self.scfm_index_positions) - 1):
-    if gene_idx in self.gene_to_modules:
-        module_indices = self.gene_to_modules[gene_idx]
-        module_embs = module_encodings[:, module_indices, :]  # B, num_modules_for_gene, D
-        gene_emb = module_embs.mean(dim=1)  # B, D
-    else:
-        gene_emb = module_encodings.mean(dim=1)  # B, D (global average)
-```
-### 2. `GEARS_Model_BioMod` (`components/model.py`)
-`GEARS_Model_BioMod` inherits the original GEARS architecture. Main changes:
-- **Use `SCFM_BioMod`** instead of the original `SCFM_different_genes`.
-- **Module data loading** supports loading module data from hyper-parameters or file paths.
-- **Other components remain unchanged**, including the GNN layers and decoder.
-### 3. Training Script (`train.py`)
-The training script is based on `GEARS/train_dual_ddp_reduce_dec.py`. Main changes:
-- **Model class**: use `GEARS_Model_BioMod` instead of `GEARS_Model_Acc`.
-- **New arguments**:
-  - `--biomod_data_path`: path to one module JSON file.
-  - `--biomod_data_dir`: directory containing module JSON files.
-  - `--gene_mapping_path`: CSV file mapping gene symbols to Ensembl IDs.
-## Usage
-### 1. Bundled dataset: Norman
-Norman is the only perturbation dataset currently bundled with this repository.
-The following files are present under `data/downstream/final_data/norman/`:
-| Input | Purpose |
-| --- | --- |
-| `perturb_processed.h5ad` | Processed expression and perturbation annotations. |
-| `data_pyg/cell_graphs.pkl` | Prepared per-cell PyG graph cache. |
-| `splits/norman_simulation_1_0.75.pkl` | Existing simulation split for seed 1 and training-gene fraction 0.75. |
-| `splits/norman_simulation_1_0.75_subgroup.pkl` | Test-condition categories for that simulation split. |
-| `go.csv` | Gene Ontology similarity graph. |
-| `simulation_1_0.75_0.4_20_co_expression_network.csv` | Coexpression graph for the same split and default graph settings. |
-These files were checked for existence without deserializing the graph cache,
-split files, or model weights. The shared BioMod weights, configuration, module
-JSON, gene list, gene2vec array, and gene-mapping CSV are also present at the paths
-used below.
-The loader also contains support for other public perturbation datasets, including
-Adamson and Dixit, but their data are not bundled. They require separate data
-preparation or downloading and are not additional ready-to-run local collections.
-### 2. Run the bundled Norman simulation split
-Activate the environment described in the [project README](../../README.md), then
-run this command in Bash from the outer repository root containing `BioMod/`,
-`data/`, `model_dependencies/`, and `weight/`. A Linux CUDA/NCCL environment is
-required, including when using Linux through WSL. The backslashes continue the
-command across lines in Bash; they are not PowerShell continuation characters.
-One GPU still requires the distributed launcher. Built-in asset defaults resolve
-from the script location; explicit relative paths resolve from the working
-directory.
-```bash
-python -m torch.distributed.run --standalone --nproc_per_node=1 \
-    BioMod/gene_perturbation/train.py \
-    --data_dir data/downstream/final_data \
-    --data_name norman \
-    --split simulation \
-    --seed 1 \
-    --train_gene_set_size 0.75 \
-    --scfm_hyper_params_path weight/BioMod.pkl \
-    --scfm_ckpt_path weight/BioMod.pth \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene_mapping_path model_dependencies/gene2ens.csv \
-    --scfm_genes_list_path model_dependencies/selected_genes_27k.txt \
-    --scfm_gene2vec_file model_dependencies/selected_gene2vec_27k.npy \
-    --finetune_method frozen \
-    --result_dir tutorial_runs/gene_perturbation_norman \
-    --run_name norman_biomod \
-    --epochs 20 \
-    --batch_size 32 \
-    --lr 1e-3
-```
-The split arguments select the bundled split and graph caches. The explicit
-`--finetune_method frozen` setting selects the frozen pretrained branch described
-in the manuscript; omitting it uses the script's current full-fine-tuning default.
-To use several GPUs, change `--nproc_per_node` to the number of available GPUs.
-This is a single bundled-data run with example training settings, not a verified
-reproduction of the manuscript's repeated-seed results. The training code selects
-the checkpoint with the lowest validation MSE on the top 20 differentially
-expressed genes and then evaluates that checkpoint on the test split. The stored
-split contents, reported cell counts, and model performance were not revalidated
-by this documentation update.
-Norman already includes `go.csv`, so no external GO annotation file is required
-for this command. If regenerating a missing GO graph for prepared data, supply a
-compatible `gene2go_all.pkl` through `BIOMOD_GENE2GO_PATH`; that optional annotation
-resource is not bundled. Different seeds or split settings require new split and
-coexpression caches and do not reuse the files listed above.
-### 3. Arguments
-**Model arguments** (defaults point to the bundled BioMod assets):
-- `--scfm_hyper_params_path`: path to the BioMod model configuration file.
-- `--scfm_ckpt_path`: path to the BioMod model weights.
-- `--biomod_data_path` or `--biomod_data_dir`: required only when the model configuration does not already contain module definitions.
-**Recommended arguments**:
-- `--gene_mapping_path`: gene mapping file, especially when module data use gene symbols.
-- `--scfm_genes_list_path`: BioMod gene list file.
-- `--scfm_gene2vec_file`: path to the gene2vec file.
-**Optional arguments**:
-- `--use_biomod_level`: use module-level features. This is experimental and is not fully supported at the moment.
-  - Default: False, meaning gene-level features are used and recommended.
-## Comparison with Original sclong
-### Main Differences
-1. **Model architecture**:
-   - **Original sclong**: uses `DualEncoderSCFM` and directly processes gene sequences.
-   - **Module version**: uses `BioMod` and processes module-based data.
-2. **Data representation**:
-   - **Original sclong**: gene-level embeddings come directly from encoder outputs.
-   - **Module version**: gene-level embeddings are recovered from module encodings by mean pooling.
-3. **Input format**:
-   - **Original sclong**: directly inputs gene expression vectors.
-   - **Module version**: keeps the same external input format but internally processes data with module embeddings.
-### Performance Comparison
-To compare model performance:
-1. **Run original scLong** using its own documentation and a separate checkout
-   of the upstream GEARS code. That external workflow is not bundled here.
-2. **Run BioMod** using the complete
-   [Norman simulation command](#2-run-the-bundled-norman-simulation-split) above.
-3. **Compare metrics**:
-   - MSE (Mean Squared Error)
-   - Pearson correlation
-   - MSE and Pearson correlation for the top 20 DE genes
-   - Direction accuracy and related metrics
-Results are saved under each `result_dir`. Compare these metrics to evaluate the
-module version.
-## Technical Details
-### Module-to-Gene Mapping
-In `SCFM_BioMod`, `gene_to_modules` records which modules contain each gene:
-```python
-self.gene_to_modules = {}  # {gene_idx: [module_idx1, module_idx2, ...]}
-for module_idx, module_genes in enumerate(module_sets):
-    for gene_idx in module_genes:
-        if gene_idx < len(scfm_genes):
-            if gene_idx not in self.gene_to_modules:
-                self.gene_to_modules[gene_idx] = []
-            self.gene_to_modules[gene_idx].append(module_idx)
-```
-### Gene Embedding Recovery Strategy
-For each gene:
-1. If the gene appears in some modules, average the encodings of those modules.
-2. If the gene does not appear in any module, use the global average of all modules as a fallback.
-This strategy:
-- Makes full use of module information.
-- Provides a reasonable embedding for genes absent from all modules.
-- Keeps embedding dimensionality similar to the original model.
-## File Structure
-```text
-BioMod/gene_perturbation/                   # Perturbation response prediction
-├── components/                            # Model, data, training, and evaluation helpers
-│   ├── __init__.py
-│   ├── data_utils.py
-│   ├── dataset.py
-│   ├── inference.py
-│   ├── model.py
-│   ├── trainer.py
-│   ├── training_utils.py
-│   └── utils.py
-├── README.md
-├── train.py
-└── tutorial.ipynb
-```
-## Notes
-1. **Module data format**: make sure the gene indices or names in the module data match the BioMod gene list.
-2. **Gene mapping**: provide `gene_mapping_path` if the module data use gene symbols.
-3. **Memory usage**: the module version may require more memory because it maintains the module-to-gene mapping.
-4. **Training stability**: use the same learning rate and training strategy as original sclong when possible.
-## Troubleshooting
-### Issue 1: Module Data Not Found
-- Check whether `--biomod_data_path` or `--biomod_data_dir` is correct.
-- Make sure the module data file exists and has the expected format.
-### Issue 2: Gene Mapping Failed
-- Check whether `--gene_mapping_path` is correct.
-- Make sure the gene mapping file is a CSV containing `Approved symbol` and `Ensembl gene ID` columns.
-### Issue 3: Model Loading Failed
-- Check whether the checkpoint path is correct.
-- Make sure `hyper_params` contains the required module information.
-## Gene-Based vs Module-Based Methods
-This implementation supports two feature extraction modes controlled by
-`--use_biomod_level`.
-### Method 1: Gene-Based (Default, Recommended)
-Use the complete [Norman simulation command](#2-run-the-bundled-norman-simulation-split)
-above. It uses gene-level recovery by omitting `--use_biomod_level`; this is a
-boolean switch, so do not append a value such as `False`.
-**Characteristics**:
-- Recovers gene-level embeddings from module encodings.
-- Fully compatible with the original GEARS architecture.
-- Downstream tasks operate at gene level, including the GNN and decoder.
-- Outputs gene-level predictions.
-### Method 2: Module-Based (Experimental, Not Fully Implemented)
-The `--use_biomod_level` switch selects an experimental mode whose downstream
-architecture is incomplete. It is not included in the runnable
-[Norman simulation command](#2-run-the-bundled-norman-simulation-split). Use the
-default gene-level workflow for the bundled dataset.
-**Characteristics**:
-- Directly uses module-level encodings.
-- Preserves the full module-level information.
-- **Note**: module-level downstream tasks are not fully implemented in the current version.
-- Requires redesigning the downstream architecture, including the GNN and decoder.
-## References
-- Original GEARS code is an external reference and is not included in this source directory.
-- BioMod model: `BioMod/models_biomod.py`
-- Module data processing: `BioMod/biomod_dataset.py`
-## Optional external annotation resources
-The bundled Norman data include `go.csv`. If that network must be regenerated,
-provide `gene2go_path` to `get_go_auto` or set `BIOMOD_GENE2GO_PATH` to the
-appropriate `gene2go_all.pkl` file. This annotation file is not bundled.
-The optional `get_high_umi_idx` helper requires `high_umi_path` or
-`BIOMOD_HIGH_UMI_PATH` pointing to `genes_with_hi_mean.npy`; that resource is also
-not bundled. Neither helper silently searches an old workstation path.

+# Gene Perturbation Prediction with BioMod
+This document describes the BioMod gene perturbation workflow (GEARS), using
+the `BioMod` encoder. The
+[BioMod model weights and matching configuration](../../README.md#biomod-model-weights)
+are shared with the other downstream tasks.
+## Dataset Commands
+### 1. Bundled dataset: Norman
+Norman is the only perturbation dataset currently bundled with this repository.
+The following files are present under `data/downstream/final_data/norman/`:
+| Input | Purpose |
+| --- | --- |
+| `perturb_processed.h5ad` | Processed expression and perturbation annotations. |
+| `data_pyg/cell_graphs.pkl` | Prepared per-cell PyG graph cache. |
+| `splits/norman_simulation_1_0.75.pkl` | Existing simulation split for seed 1 and training-gene fraction 0.75. |
+| `splits/norman_simulation_1_0.75_subgroup.pkl` | Test-condition categories for that simulation split. |
+| `go.csv` | Gene Ontology similarity graph. |
+| `simulation_1_0.75_0.4_20_co_expression_network.csv` | Coexpression graph for the same split and default graph settings. |
+These files were checked for existence without deserializing the graph cache,
+split files, or model weights. The shared BioMod weights, configuration, module
+JSON, gene list, gene2vec array, and gene-mapping CSV are also present at the paths
+used below.
+The loader also contains support for other public perturbation datasets, including
+Adamson and Dixit, but their data are not bundled. They require separate data
+preparation or downloading and are not additional ready-to-run local collections.
+### 2. Run the bundled Norman simulation split
+Activate the environment described in the [project README](../../README.md), then
+run this command in Bash from the outer repository root containing `BioMod/`,
+`data/`, `model_dependencies/`, and `weight/`. A Linux CUDA/NCCL environment is
+required, including when using Linux through WSL. The backslashes continue the
+command across lines in Bash; they are not PowerShell continuation characters.
+One GPU still requires the distributed launcher. Built-in asset defaults resolve
+from the script location; explicit relative paths resolve from the working
+directory.
+```bash
+python -m torch.distributed.run --standalone --nproc_per_node=1 \
+    BioMod/gene_perturbation/train.py \
+    --data_dir data/downstream/final_data \
+    --data_name norman \
+    --split simulation \
+    --seed 1 \
+    --train_gene_set_size 0.75 \
+    --scfm_hyper_params_path weight/BioMod.pkl \
+    --scfm_ckpt_path weight/BioMod.pth \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene_mapping_path model_dependencies/gene2ens.csv \
+    --scfm_genes_list_path model_dependencies/selected_genes_27k.txt \
+    --scfm_gene2vec_file model_dependencies/selected_gene2vec_27k.npy \
+    --finetune_method frozen \
+    --result_dir tutorial_runs/gene_perturbation_norman \
+    --run_name norman_biomod \
+    --epochs 20 \
+    --batch_size 32 \
+    --lr 1e-3
+```
+The split arguments select the bundled split and graph caches. The explicit
+`--finetune_method frozen` setting selects the frozen pretrained branch described
+in the manuscript; omitting it uses the script's current full-fine-tuning default.
+To use several GPUs, change `--nproc_per_node` to the number of available GPUs.
+This is a single bundled-data run with example training settings, not a verified
+reproduction of the manuscript's repeated-seed results. The training code selects
+the checkpoint with the lowest validation MSE on the top 20 differentially
+expressed genes and then evaluates that checkpoint on the test split. The stored
+split contents, reported cell counts, and model performance were not revalidated
+by this documentation update.
+Norman already includes `go.csv`, so no external GO annotation file is required
+for this command. If regenerating a missing GO graph for prepared data, supply a
+compatible `gene2go_all.pkl` through `BIOMOD_GENE2GO_PATH`; that optional annotation
+resource is not bundled. Different seeds or split settings require new split and
+coexpression caches and do not reuse the files listed above.
+### 3. Arguments
+**Model arguments** (defaults point to the bundled BioMod assets):
+- `--scfm_hyper_params_path`: path to the BioMod model configuration file.
+- `--scfm_ckpt_path`: path to the BioMod model weights.
+- `--biomod_data_path` or `--biomod_data_dir`: required only when the model configuration does not already contain module definitions.
+**Recommended arguments**:
+- `--gene_mapping_path`: gene mapping file, especially when module data use gene symbols.
+- `--scfm_genes_list_path`: BioMod gene list file.
+- `--scfm_gene2vec_file`: path to the gene2vec file.
+**Optional arguments**:
+- `--use_biomod_level`: use module-level features. This is experimental and is not fully supported at the moment.
+  - Default: False, meaning gene-level features are used and recommended.
+## Notebook
+See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
+## Files
+| File or directory | Purpose |
+| --- | --- |
+| [README.md](README.md) | File guide, model details, training commands, and troubleshooting notes. |
+| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
+| [train.py](train.py) | Configure and launch distributed gene perturbation training. |
+| [components/](components/) | Model, data-processing, training, and evaluation helpers. |
+| [components/model.py](components/model.py) | Define the BioMod-backed GEARS model and recover gene-level features. |
+| [components/trainer.py](components/trainer.py) | Manage model training, checkpointing, and evaluation. |
+| [components/dataset.py](components/dataset.py) | Prepare perturbation datasets, splits, and graph data loaders. |
+| [components/data_utils.py](components/data_utils.py) | Compute differential-expression annotations and construct data splits. |
+| [components/inference.py](components/inference.py) | Run inference and compute perturbation prediction metrics. |
+| [components/training_utils.py](components/training_utils.py) | Provide distributed training, checkpoint, logging, and optimization helpers. |
+| [components/utils.py](components/utils.py) | Provide perturbation parsing, gene-network, loss, and prediction utilities. |
+| [components/__init__.py](components/__init__.py) | Mark the helper directory as a Python package. |
+## Overview
+This adaptation replaces the original GEARS gene perturbation model based on
+`DualEncoderSCFM` with `BioMod`. The main adaptation points
+are:
+1. **Model architecture adaptation**: replace the original dual-encoder model with a module-based encoder-only model.
+2. **Data format adaptation**: handle module-based input data.
+3. **Embedding extraction adaptation**: recover gene-level embeddings from module encodings.
+## Main Adaptations
+### 1. `SCFM_BioMod` (`components/model.py`)
+`SCFM_BioMod` wraps `BioMod` and provides these functions:
+- **Input handling**: reindex input gene expression values to the BioMod gene order.
+- **Module encoding**: obtain module-level encodings from `BioMod`.
+- **Gene embedding recovery**: recover gene-level embeddings from module encodings.
+  - For each gene, find all modules that contain it.
+  - Average the encodings of those modules to obtain the gene embedding.
+  - If a gene is not included in any module, use the global average as a fallback.
+- **Output reindexing**: reindex gene embeddings back to the input gene order.
+**Key adaptation**:
+```python
+# Recover gene-level embeddings from module encodings.
+for gene_idx in range(len(self.scfm_index_positions) - 1):
+    if gene_idx in self.gene_to_modules:
+        module_indices = self.gene_to_modules[gene_idx]
+        module_embs = module_encodings[:, module_indices, :]  # B, num_modules_for_gene, D
+        gene_emb = module_embs.mean(dim=1)  # B, D
+    else:
+        gene_emb = module_encodings.mean(dim=1)  # B, D (global average)
+```
+### 2. `GEARS_Model_BioMod` (`components/model.py`)
+`GEARS_Model_BioMod` inherits the original GEARS architecture. Main changes:
+- **Use `SCFM_BioMod`** instead of the original `SCFM_different_genes`.
+- **Module data loading** supports loading module data from hyper-parameters or file paths.
+- **Other components remain unchanged**, including the GNN layers and decoder.
+### 3. Training Script (`train.py`)
+The training script is based on `GEARS/train_dual_ddp_reduce_dec.py`. Main changes:
+- **Model class**: use `GEARS_Model_BioMod` instead of `GEARS_Model_Acc`.
+- **New arguments**:
+  - `--biomod_data_path`: path to one module JSON file.
+  - `--biomod_data_dir`: directory containing module JSON files.
+  - `--gene_mapping_path`: CSV file mapping gene symbols to Ensembl IDs.
+## Comparison with Original sclong
+### Main Differences
+1. **Model architecture**:
+   - **Original sclong**: uses `DualEncoderSCFM` and directly processes gene sequences.
+   - **Module version**: uses `BioMod` and processes module-based data.
+2. **Data representation**:
+   - **Original sclong**: gene-level embeddings come directly from encoder outputs.
+   - **Module version**: gene-level embeddings are recovered from module encodings by mean pooling.
+3. **Input format**:
+   - **Original sclong**: directly inputs gene expression vectors.
+   - **Module version**: keeps the same external input format but internally processes data with module embeddings.
+### Performance Comparison
+To compare model performance:
+1. **Run original scLong** using its own documentation and a separate checkout
+   of the upstream GEARS code. That external workflow is not bundled here.
+2. **Run BioMod** using the complete
+   [Norman simulation command](#2-run-the-bundled-norman-simulation-split) above.
+3. **Compare metrics**:
+   - MSE (Mean Squared Error)
+   - Pearson correlation
+   - MSE and Pearson correlation for the top 20 DE genes
+   - Direction accuracy and related metrics
+Results are saved under each `result_dir`. Compare these metrics to evaluate the
+module version.
+## Technical Details
+### Module-to-Gene Mapping
+In `SCFM_BioMod`, `gene_to_modules` records which modules contain each gene:
+```python
+self.gene_to_modules = {}  # {gene_idx: [module_idx1, module_idx2, ...]}
+for module_idx, module_genes in enumerate(module_sets):
+    for gene_idx in module_genes:
+        if gene_idx < len(scfm_genes):
+            if gene_idx not in self.gene_to_modules:
+                self.gene_to_modules[gene_idx] = []
+            self.gene_to_modules[gene_idx].append(module_idx)
+```
+### Gene Embedding Recovery Strategy
+For each gene:
+1. If the gene appears in some modules, average the encodings of those modules.
+2. If the gene does not appear in any module, use the global average of all modules as a fallback.
+This strategy:
+- Makes full use of module information.
+- Provides a reasonable embedding for genes absent from all modules.
+- Keeps embedding dimensionality similar to the original model.
+## File Structure
+```text
+BioMod/gene_perturbation/                   # Perturbation response prediction
+├── components/                            # Model, data, training, and evaluation helpers
+│   ├── __init__.py
+│   ├── data_utils.py
+│   ├── dataset.py
+│   ├── inference.py
+│   ├── model.py
+│   ├── trainer.py
+│   ├── training_utils.py
+│   └── utils.py
+├── README.md
+├── train.py
+└── tutorial.ipynb
+```
+## Notes
+1. **Module data format**: make sure the gene indices or names in the module data match the BioMod gene list.
+2. **Gene mapping**: provide `gene_mapping_path` if the module data use gene symbols.
+3. **Memory usage**: the module version may require more memory because it maintains the module-to-gene mapping.
+4. **Training stability**: use the same learning rate and training strategy as original sclong when possible.
+## Troubleshooting
+### Issue 1: Module Data Not Found
+- Check whether `--biomod_data_path` or `--biomod_data_dir` is correct.
+- Make sure the module data file exists and has the expected format.
+### Issue 2: Gene Mapping Failed
+- Check whether `--gene_mapping_path` is correct.
+- Make sure the gene mapping file is a CSV containing `Approved symbol` and `Ensembl gene ID` columns.
+### Issue 3: Model Loading Failed
+- Check whether the checkpoint path is correct.
+- Make sure `hyper_params` contains the required module information.
+## Gene-Based vs Module-Based Methods
+This implementation supports two feature extraction modes controlled by
+`--use_biomod_level`.
+### Method 1: Gene-Based (Default, Recommended)
+Use the complete [Norman simulation command](#2-run-the-bundled-norman-simulation-split)
+above. It uses gene-level recovery by omitting `--use_biomod_level`; this is a
+boolean switch, so do not append a value such as `False`.
+**Characteristics**:
+- Recovers gene-level embeddings from module encodings.
+- Fully compatible with the original GEARS architecture.
+- Downstream tasks operate at gene level, including the GNN and decoder.
+- Outputs gene-level predictions.
+### Method 2: Module-Based (Experimental, Not Fully Implemented)
+The `--use_biomod_level` switch selects an experimental mode whose downstream
+architecture is incomplete. It is not included in the runnable
+[Norman simulation command](#2-run-the-bundled-norman-simulation-split). Use the
+default gene-level workflow for the bundled dataset.
+**Characteristics**:
+- Directly uses module-level encodings.
+- Preserves the full module-level information.
+- **Note**: module-level downstream tasks are not fully implemented in the current version.
+- Requires redesigning the downstream architecture, including the GNN and decoder.
+## References
+- Original GEARS code is an external reference and is not included in this source directory.
+- BioMod model: `BioMod/models_biomod.py`
+- Module data processing: `BioMod/biomod_dataset.py`
+## Optional external annotation resources
+The bundled Norman data include `go.csv`. If that network must be regenerated,
+provide `gene2go_path` to `get_go_auto` or set `BIOMOD_GENE2GO_PATH` to the
+appropriate `gene2go_all.pkl` file. This annotation file is not bundled.
+The optional `get_high_umi_idx` helper requires `high_umi_path` or
+`BIOMOD_HIGH_UMI_PATH` pointing to `genes_with_hi_mean.npy`; that resource is also
+not bundled. Neither helper silently searches an old workstation path.

BioMod/zero_shot_batch/README.md CHANGED Viewed

@@ -1,187 +1,187 @@
-# BioMod Zero-Shot Embeddings and Batch-Effect Evaluation
-This directory contains code for extracting BioMod cell embeddings and
-evaluating batch effects without fine-tuning. Use the
-[BioMod model weights and matching configuration](../../README.md#biomod-model-weights).
-## Notebook
-See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
-## Files
-| File or directory | Purpose |
-| --- | --- |
-| [README.md](README.md) | File guide, evaluation commands, arguments, and output descriptions. |
-| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
-| [evaluate.py](evaluate.py) | Extract BioMod cell embeddings and evaluate cell-type and batch-effect metrics. |
-| [tools/](tools/) | Optional visualization and sequencing-depth analysis helpers. |
-| [tools/visualize_results.py](tools/visualize_results.py) | Plot saved embeddings and compare batch ASW metrics. |
-| [tools/sequencing_depth/](tools/sequencing_depth/) | Generate reduced-depth inputs and compare zero-shot evaluation results. |
-| [tools/sequencing_depth/make_low_depth_h5ad.py](tools/sequencing_depth/make_low_depth_h5ad.py) | Create reduced-depth h5ad datasets by thinning raw integer counts. |
-| [tools/sequencing_depth/run_zero_shot_low_depth.py](tools/sequencing_depth/run_zero_shot_low_depth.py) | Run evaluation over multiple input datasets and summarize the results. |
-| [tools/sequencing_depth/README.md](tools/sequencing_depth/README.md) | Commands for the sequencing-depth evaluation workflow. |
-## Dataset Commands
-The manuscript evaluates three atlases under four conditions: hPNC, BMMC, and
-Kim Lung with and without malignant cells. Each command below evaluates one
-complete bundled file with `--n_cells all`, max pooling and the scIB metric
-bundle selected by `--metrics_mode scgpt`. These choices follow manuscript
-Section 4.6 (PDF page 25). No additional gene or cell filtering is enabled.
-Run from the outer repository root after installing the environment. Each
-condition has a separate output directory. A batch size of 1 limits the per-step
-inference memory requirement; all cells are still processed. This is a launch
-setting, not a batch size reported in the manuscript. The complete expression
-matrix and metric calculations can still require substantial host memory.
-The command blocks use Bash line continuations (`\`). Run them in Bash, such as
-Linux, WSL or Git Bash. In PowerShell, join each command into a single line
-instead of copying the Bash continuation characters.
-The encoder receives only expression values, not batch or cell-type labels.
-The batch and label fields below are used for evaluation after embedding
-extraction. The entry point reads `adata.X` without additional normalization or
-`log1p`; it does not select counts layers or `.raw`. The commands establish
-file/field wiring, not preprocessing correctness or reproduced performance.
-| Condition | Cells embedded | Genes in file | Label field | Batch field | Observed batches |
-| --- | ---: | ---: | --- | --- | ---: |
-| hPNC | 16,382 | 19,093 | `celltype` | `tech` | 9 |
-| BMMC | 90,261 | 14,087 | `cell_type` | `batch` | 12 |
-| Kim Lung, malignant cells retained | 32,493 | 20,793 | `cell_type` | `sample` | 14 |
-| Kim Lung, malignant cells removed | 21,955 | 20,793 | `cell_type` | `sample` | 14 |
-### 1. hPNC
-Use the 16,382-cell pancreas atlas, not the paired `hp14/` files used for
-annotation. Its `tech` field contains nine observed values: `celseq`, `celseq2`,
-`fluidigmc1`, `inDrop1`–`inDrop4`, `smarter` and `smartseq2`. The manuscript states
-six batches. No six-batch harmonization is defined in the current entry point;
-this command evaluates the nine values stored in the file and must not be
-presented as a verified six-batch reproduction.
-```bash
-python BioMod/zero_shot_batch/evaluate.py \
-    --data_path data/downstream/final_data/human_pancreas_norm_complexBatch_with_gene_name.h5ad \
-    --dataset_preset auto --gene_col gene_name --batch_key tech --label_key celltype \
-    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
-    --gene_mapping_path model_dependencies/gene2ens.csv \
-    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
-    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
-    --min_genes_per_cell 0 --min_cells_per_gene 0 \
-    --output_dir tutorial_runs/zero_shot_hPNC
-```
-### 2. BMMC
-Use the stored `gene_id` column, which decodes to Ensembl identifiers, and the
-45 observed `cell_type` classes. The gene column has 98 missing entries and 36
-duplicate nonmissing identifiers. The current mapping leaves missing IDs
-unmapped and uses the last input column for duplicate IDs; it does not aggregate
-duplicates. These existing input semantics have not been changed.
-```bash
-python BioMod/zero_shot_batch/evaluate.py \
-    --data_path data/downstream/final_data/BMMC_processed.h5ad \
-    --dataset_preset auto --gene_col gene_id --batch_key batch --label_key cell_type \
-    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
-    --gene_mapping_path model_dependencies/gene2ens.csv \
-    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
-    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
-    --min_genes_per_cell 0 --min_cells_per_gene 0 \
-    --output_dir tutorial_runs/zero_shot_bmmc
-```
-### 3. Kim Lung: Malignant Cells Retained
-All 32,493 cells receive embeddings. The file has 10 observed cell-type labels
-and 2,021 unlabeled cells. The evaluator excludes cells with missing labels from
-metrics, so 30,472 cells remain for labeled evaluation. This metadata exclusion
-does not remove rows from the input file or the saved embedding array.
-```bash
-python BioMod/zero_shot_batch/evaluate.py \
-    --data_path data/downstream/final_data/Kim2020_Lung.h5ad \
-    --dataset_preset auto --gene_col gene_name --batch_key sample --label_key cell_type \
-    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
-    --gene_mapping_path model_dependencies/gene2ens.csv \
-    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
-    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
-    --min_genes_per_cell 0 --min_cells_per_gene 0 \
-    --output_dir tutorial_runs/zero_shot_kim_lung
-```
-### 4. Kim Lung: Malignant Cells Removed
-Use the existing 21,955-cell file with malignant cells already excluded. It
-retains nine observed cell-type labels and the same 2,021 unlabeled cells, giving
-19,934 cells for labeled evaluation. The command does not modify or regenerate
-either lung file.
-```bash
-python BioMod/zero_shot_batch/evaluate.py \
-    --data_path data/downstream/final_data/Kim2020_Lung_noMalignant.h5ad \
-    --dataset_preset auto --gene_col gene_name --batch_key sample --label_key cell_type \
-    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
-    --biomod_data_dir model_dependencies/biomod_data_all \
-    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
-    --gene_mapping_path model_dependencies/gene2ens.csv \
-    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
-    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
-    --min_genes_per_cell 0 --min_cells_per_gene 0 \
-    --output_dir tutorial_runs/zero_shot_kim_lung_no_malignant
-```
-## Outputs and Metric Definitions
-Each output directory contains:
-- `sclong_module_batch_cell_emb_mode.csv`: metrics with `metric`, `label` and
-  `value` columns.
-- `sclong_module_batch_cell_emb_mode_ce.npy`: one embedding row per processed
-  input cell, before the metric-only removal of missing batch/label values.
-With `--metrics_mode scgpt`, the script reports individual scIB metrics plus:
-- `avg_bio = (NMI_cluster/label + ARI_cluster/label + ASW_label) / 3`.
-- `avg_batch = (graph_conn + ASW_label/batch) / 2`.
-The manuscript defines `avg_score = 0.6 * avg_bio + 0.4 * avg_batch`, but the
-current entry point does not write an `avg_score` row. Compute that aggregate
-from the two reported values when needed; do not mistake `ASW_label/batch`
-alone for the overall score. `--metrics_mode simple` computes only the batch
-silhouette metric and is not the manuscript's complete metric bundle.
-The manuscript reports five runs with seeds 0–4. This entry point has no general
-`--seed` argument or five-run driver. The existing `--shuffle_seed` controls an
-optional gene-to-module reshuffling experiment; it is not an evaluation seed
-and must not be used as a substitute. Reproducing the reported run-to-run
-variation requires the original randomization protocol.
-## Gene Alignment and Optional Workflows
-The gene column is mapped to the model vocabulary, with unavailable model genes
-filled with zero. `--gene_col` takes an actual `adata.var` column name; to use
-`var.index`, omit this argument with `--dataset_preset auto`. The optional
-`lung` preset supplies `gene_name`, `sample` and `cell_type`, while the examples
-above make every field explicit.
-Keep saved embedding rows aligned with the original input when plotting.
-The [task notebook](tutorial.ipynb) provides result-review cells, and
-[tools/](tools/) contains standalone plotting and sequencing-depth workflows.
-Reduced-depth evaluation is an additional analysis, not a fifth integration
-condition in the manuscript. The supplied counts layers and any source file
-must remain unchanged unless a separate preprocessing task is explicitly chosen.
-The remaining bundled H5AD files serve the documented
-[annotation benchmarks](../cell_annotation/README.md#dataset-commands) and
-[gene perturbation task](../gene_perturbation/README.md); their presence does not
-establish additional manuscript integration benchmarks.

+# BioMod Zero-Shot Embeddings and Batch-Effect Evaluation
+This directory contains code for extracting BioMod cell embeddings and
+evaluating batch effects without fine-tuning. Use the
+[BioMod model weights and matching configuration](../../README.md#biomod-model-weights).
+## Dataset Commands
+The manuscript evaluates three atlases under four conditions: hPNC, BMMC, and
+Kim Lung with and without malignant cells. Each command below evaluates one
+complete bundled file with `--n_cells all`, max pooling and the scIB metric
+bundle selected by `--metrics_mode scgpt`. These choices follow manuscript
+Section 4.6 (PDF page 25). No additional gene or cell filtering is enabled.
+Run from the outer repository root after installing the environment. Each
+condition has a separate output directory. A batch size of 1 limits the per-step
+inference memory requirement; all cells are still processed. This is a launch
+setting, not a batch size reported in the manuscript. The complete expression
+matrix and metric calculations can still require substantial host memory.
+The command blocks use Bash line continuations (`\`). Run them in Bash, such as
+Linux, WSL or Git Bash. In PowerShell, join each command into a single line
+instead of copying the Bash continuation characters.
+The encoder receives only expression values, not batch or cell-type labels.
+The batch and label fields below are used for evaluation after embedding
+extraction. The entry point reads `adata.X` without additional normalization or
+`log1p`; it does not select counts layers or `.raw`. The commands establish
+file/field wiring, not preprocessing correctness or reproduced performance.
+| Condition | Cells embedded | Genes in file | Label field | Batch field | Observed batches |
+| --- | ---: | ---: | --- | --- | ---: |
+| [hPNC](#1-hpnc) | 16,382 | 19,093 | `celltype` | `tech` | 9 |
+| [BMMC](#2-bmmc) | 90,261 | 14,087 | `cell_type` | `batch` | 12 |
+| [Kim Lung, malignant cells retained](#3-kim-lung-malignant-cells-retained) | 32,493 | 20,793 | `cell_type` | `sample` | 14 |
+| [Kim Lung, malignant cells removed](#4-kim-lung-malignant-cells-removed) | 21,955 | 20,793 | `cell_type` | `sample` | 14 |
+### 1. hPNC
+Use the 16,382-cell pancreas atlas, not the paired `hp14/` files used for
+annotation. Its `tech` field contains nine observed values: `celseq`, `celseq2`,
+`fluidigmc1`, `inDrop1`–`inDrop4`, `smarter` and `smartseq2`. The manuscript states
+six batches. No six-batch harmonization is defined in the current entry point;
+this command evaluates the nine values stored in the file and must not be
+presented as a verified six-batch reproduction.
+```bash
+python BioMod/zero_shot_batch/evaluate.py \
+    --data_path data/downstream/final_data/human_pancreas_norm_complexBatch_with_gene_name.h5ad \
+    --dataset_preset auto --gene_col gene_name --batch_key tech --label_key celltype \
+    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
+    --gene_mapping_path model_dependencies/gene2ens.csv \
+    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
+    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
+    --min_genes_per_cell 0 --min_cells_per_gene 0 \
+    --output_dir tutorial_runs/zero_shot_hPNC
+```
+### 2. BMMC
+Use the stored `gene_id` column, which decodes to Ensembl identifiers, and the
+45 observed `cell_type` classes. The gene column has 98 missing entries and 36
+duplicate nonmissing identifiers. The current mapping leaves missing IDs
+unmapped and uses the last input column for duplicate IDs; it does not aggregate
+duplicates. These existing input semantics have not been changed.
+```bash
+python BioMod/zero_shot_batch/evaluate.py \
+    --data_path data/downstream/final_data/BMMC_processed.h5ad \
+    --dataset_preset auto --gene_col gene_id --batch_key batch --label_key cell_type \
+    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
+    --gene_mapping_path model_dependencies/gene2ens.csv \
+    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
+    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
+    --min_genes_per_cell 0 --min_cells_per_gene 0 \
+    --output_dir tutorial_runs/zero_shot_bmmc
+```
+### 3. Kim Lung: Malignant Cells Retained
+All 32,493 cells receive embeddings. The file has 10 observed cell-type labels
+and 2,021 unlabeled cells. The evaluator excludes cells with missing labels from
+metrics, so 30,472 cells remain for labeled evaluation. This metadata exclusion
+does not remove rows from the input file or the saved embedding array.
+```bash
+python BioMod/zero_shot_batch/evaluate.py \
+    --data_path data/downstream/final_data/Kim2020_Lung.h5ad \
+    --dataset_preset auto --gene_col gene_name --batch_key sample --label_key cell_type \
+    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
+    --gene_mapping_path model_dependencies/gene2ens.csv \
+    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
+    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
+    --min_genes_per_cell 0 --min_cells_per_gene 0 \
+    --output_dir tutorial_runs/zero_shot_kim_lung
+```
+### 4. Kim Lung: Malignant Cells Removed
+Use the existing 21,955-cell file with malignant cells already excluded. It
+retains nine observed cell-type labels and the same 2,021 unlabeled cells, giving
+19,934 cells for labeled evaluation. The command does not modify or regenerate
+either lung file.
+```bash
+python BioMod/zero_shot_batch/evaluate.py \
+    --data_path data/downstream/final_data/Kim2020_Lung_noMalignant.h5ad \
+    --dataset_preset auto --gene_col gene_name --batch_key sample --label_key cell_type \
+    --scfm_ckpt_path weight/BioMod.pth --scfm_hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
+    --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
+    --gene_mapping_path model_dependencies/gene2ens.csv \
+    --scfm_genes_file model_dependencies/selected_genes_27k.txt \
+    --n_cells all --batch_size 1 --pool_method max --metrics_mode scgpt \
+    --min_genes_per_cell 0 --min_cells_per_gene 0 \
+    --output_dir tutorial_runs/zero_shot_kim_lung_no_malignant
+```
+## Notebook
+See the [task notebook](tutorial.ipynb) for a step-by-step workflow.
+## Files
+| File or directory | Purpose |
+| --- | --- |
+| [README.md](README.md) | File guide, evaluation commands, arguments, and output descriptions. |
+| [tutorial.ipynb](tutorial.ipynb) | Task configuration, execution, and result review in a Jupyter notebook. |
+| [evaluate.py](evaluate.py) | Extract BioMod cell embeddings and evaluate cell-type and batch-effect metrics. |
+| [tools/](tools/) | Optional visualization and sequencing-depth analysis helpers. |
+| [tools/visualize_results.py](tools/visualize_results.py) | Plot saved embeddings and compare batch ASW metrics. |
+| [tools/sequencing_depth/](tools/sequencing_depth/) | Generate reduced-depth inputs and compare zero-shot evaluation results. |
+| [tools/sequencing_depth/make_low_depth_h5ad.py](tools/sequencing_depth/make_low_depth_h5ad.py) | Create reduced-depth h5ad datasets by thinning raw integer counts. |
+| [tools/sequencing_depth/run_zero_shot_low_depth.py](tools/sequencing_depth/run_zero_shot_low_depth.py) | Run evaluation over multiple input datasets and summarize the results. |
+| [tools/sequencing_depth/README.md](tools/sequencing_depth/README.md) | Commands for the sequencing-depth evaluation workflow. |
+## Outputs and Metric Definitions
+Each output directory contains:
+- `sclong_module_batch_cell_emb_mode.csv`: metrics with `metric`, `label` and
+  `value` columns.
+- `sclong_module_batch_cell_emb_mode_ce.npy`: one embedding row per processed
+  input cell, before the metric-only removal of missing batch/label values.
+With `--metrics_mode scgpt`, the script reports individual scIB metrics plus:
+- `avg_bio = (NMI_cluster/label + ARI_cluster/label + ASW_label) / 3`.
+- `avg_batch = (graph_conn + ASW_label/batch) / 2`.
+The manuscript defines `avg_score = 0.6 * avg_bio + 0.4 * avg_batch`, but the
+current entry point does not write an `avg_score` row. Compute that aggregate
+from the two reported values when needed; do not mistake `ASW_label/batch`
+alone for the overall score. `--metrics_mode simple` computes only the batch
+silhouette metric and is not the manuscript's complete metric bundle.
+The manuscript reports five runs with seeds 0–4. This entry point has no general
+`--seed` argument or five-run driver. The existing `--shuffle_seed` controls an
+optional gene-to-module reshuffling experiment; it is not an evaluation seed
+and must not be used as a substitute. Reproducing the reported run-to-run
+variation requires the original randomization protocol.
+## Gene Alignment and Optional Workflows
+The gene column is mapped to the model vocabulary, with unavailable model genes
+filled with zero. `--gene_col` takes an actual `adata.var` column name; to use
+`var.index`, omit this argument with `--dataset_preset auto`. The optional
+`lung` preset supplies `gene_name`, `sample` and `cell_type`, while the examples
+above make every field explicit.
+Keep saved embedding rows aligned with the original input when plotting.
+The [task notebook](tutorial.ipynb) provides result-review cells, and
+[tools/](tools/) contains standalone plotting and sequencing-depth workflows.
+Reduced-depth evaluation is an additional analysis, not a fifth integration
+condition in the manuscript. The supplied counts layers and any source file
+must remain unchanged unless a separate preprocessing task is explicitly chosen.
+The remaining bundled H5AD files serve the documented
+[annotation benchmarks](../cell_annotation/README.md#dataset-commands) and
+[gene perturbation task](../gene_perturbation/README.md); their presence does not
+establish additional manuscript integration benchmarks.

README.md CHANGED Viewed

@@ -101,6 +101,36 @@ to end with the bundled checkpoint.
 | Drug-pair synergy classification | [Training script](BioMod/drug_combination/train.py) | [Notebook](BioMod/drug_combination/tutorial.ipynb) |
 | Gene perturbation response prediction | [Training script](BioMod/gene_perturbation/train.py) | [Notebook](BioMod/gene_perturbation/tutorial.ipynb) |
 ### Pretraining
 The repository also supports pretraining and continued pretraining.

 | Drug-pair synergy classification | [Training script](BioMod/drug_combination/train.py) | [Notebook](BioMod/drug_combination/tutorial.ipynb) |
 | Gene perturbation response prediction | [Training script](BioMod/gene_perturbation/train.py) | [Notebook](BioMod/gene_perturbation/tutorial.ipynb) |
+### Commands by dataset
+Each row below links to a separate, complete launch command for that task and
+dataset or condition. Commands specify the input paths and output directory;
+you do not need to adapt a command from another dataset. Run them in Bash from
+the outer repository root after activating the environment. Read any
+dataset-specific input caveats before launching.
+| Task | Dataset or condition | Launch command |
+| --- | --- | --- |
+| Cell annotation | Kim Lung | [Complete command](BioMod/cell_annotation/README.md#1-kim-lung) |
+| Cell annotation | Immune | [Complete command](BioMod/cell_annotation/README.md#2-immune) |
+| Cell annotation | Liver | [Complete command](BioMod/cell_annotation/README.md#3-liver) |
+| Cell annotation | MS (paired train/test files) | [Complete command](BioMod/cell_annotation/README.md#4-ms) |
+| Cell annotation | hPancreas (hp14 paired files) | [Complete command](BioMod/cell_annotation/README.md#5-hpancreas) |
+| Cell annotation | Zheng68K | [Complete command](BioMod/cell_annotation/README.md#6-zheng68k) |
+| Cell annotation | Myeloid (reference/query files) | [Complete command](BioMod/cell_annotation/README.md#7-myeloid) |
+| Zero-shot evaluation | hPNC | [Complete command](BioMod/zero_shot_batch/README.md#1-hpnc) |
+| Zero-shot evaluation | BMMC | [Complete command](BioMod/zero_shot_batch/README.md#2-bmmc) |
+| Zero-shot evaluation | Kim Lung: malignant cells retained | [Complete command](BioMod/zero_shot_batch/README.md#3-kim-lung-malignant-cells-retained) |
+| Zero-shot evaluation | Kim Lung: malignant cells removed | [Complete command](BioMod/zero_shot_batch/README.md#4-kim-lung-malignant-cells-removed) |
+| Single-drug response | GDSC-CCLE joint inputs | [Complete command](BioMod/drug_response/README.md#run-the-bundled-gdsc-ccle-collection) |
+| Drug-combination synergy | Bundled training and validation collection | [Complete command](BioMod/drug_combination/README.md#run-the-bundled-training-and-validation-collection) |
+| Gene perturbation | Norman | [Complete command](BioMod/gene_perturbation/README.md#2-run-the-bundled-norman-simulation-split) |
+Paired training/test files and complementary drug/cell inputs belong to one
+run configuration. Historical reference copies do not add datasets. The
+[optional drug-combination cross-validation command](BioMod/drug_combination/README.md#optional-five-fold-cross-validation-on-the-same-collection)
+uses the same collection under a different validation protocol.
 ### Pretraining
 The repository also supports pretraining and continued pretraining.