Unify BioMod names, flatten weight paths, and remove duplicate source directories

Rename project-owned entrypoints, resource directories, classes and helpers to BioMod/biomod, and update imports, notebooks, documentation and command examples. Preserve old CLI flags as aliases and keep serialized state/configuration keys, raw gene-set IDs, result schemas and third-party interfaces compatible. Move the existing checkpoint/configuration pair to weight/BioMod.pth and weight/BioMod.pkl using their unchanged objects. Remove only the eight approved duplicate files from the source module-data directory and nested attention package; retain the shared copies. Raw datasets, legacy reference data copies and all weight contents remain unchanged. Validation: 90 Python 3 files, 65 notebook cells, 12 utility tests, 7 synthetic backbone comparisons and 10 classifier comparisons passed. No real model weights or datasets were deserialized, and no real-data training was run.

.gitignore

@@ -31,12 +31,8 @@ __pycache__/
 .env
 *.local
 
-# Dated release checkpoints are intentionally versioned on Hugging Face.
+# BioMod model weights and their matching configuration are versioned on Hugging Face.
 !weight/
 weight/*
-!weight/0629model/
-!weight/0629model/*.pkl
-!weight/0629model/*.pth
-!weight/0810model/
-!weight/0810model/*.pkl
-!weight/0810model/*.pth
+!weight/BioMod.pkl
+!weight/BioMod.pth

BioMod/README.md

@@ -1,7 +1,7 @@
-# BioMod / PerformerModule
+# BioMod
 
 Source code and tutorial notebooks for BioMod single-cell pretraining and
-downstream experiments using PerformerModule representations.
+downstream experiments using BioMod representations.
 
 This source directory contains the pretraining entry point and shared training
 utilities, alongside downstream task runners, tutorial notebooks, environment
@@ -29,67 +29,63 @@ from these repository trees.
 ```text
 BioMod/                                                   # Task code: training, evaluation, interpretability and tutorials
 ├── cell_annotation/                                      # Cell-type annotation and model fine-tuning
-│   ├── module_data/                                      # Hallmark and Reactome modules with loading utilities
-│   │   ├── load_module.py
-│   │   ├── module1_hallmarks.json
-│   │   └── module2_reactome_2022_filtered.json
+│   ├── biomod_data/                                      # Hallmark and Reactome modules with loading utilities
+│   │   ├── load_biomod.py
+│   │   ├── biomod1_hallmarks.json
+│   │   └── biomod2_reactome_2022_filtered.json
 │   ├── cmd_finetune.md
-│   └── performer_module_finetune.py
+│   └── biomod_finetune.py
 ├── drug_combination/                                     # Drug-combination synergy prediction
 │   ├── README.md
-│   └── train_drug_combination_performer_module.py
+│   └── train_drug_combination_biomod.py
 ├── drug_response/                                        # Single-drug response prediction and training
 │   ├── cmd.txt
-│   └── train_drug_performer_module.py
+│   └── train_drug_biomod.py
 ├── gene_perturbation/                                    # Perturbation response prediction: processing, training and inference
 │   ├── data_utils_local.py
 │   ├── gears_reduce_local.py
 │   ├── inference_local.py
-│   ├── model_module.py
+│   ├── model_biomod.py
 │   ├── pertdata_local.py
 │   ├── README.md
 │   ├── scfm_utils_local.py
-│   ├── train_module.py
+│   ├── train_biomod.py
 │   └── utils.py
 ├── interpretability/                                     # Module representations and biological interpretability
 │   ├── attention/                                        # Module crosstalk and within-module gene attention
 │   │   ├── __init__.py
-│   │   ├── module_crosstalk.py
-│   │   ├── module_gene_attention.py
+│   │   ├── biomod_crosstalk.py
+│   │   ├── biomod_gene_attention.py
 │   │   ├── README.md
 │   │   └── README_gene_attention.md
-│   ├── module_importance/                                # Module importance, ablation studies and marker-gene validation
+│   ├── biomod_importance/                                # Module importance, ablation studies and marker-gene validation
 │   │   ├── __init__.py
 │   │   ├── cross_class_similarity.py
 │   │   ├── family_ablation.py
 │   │   ├── family_importance_analysis.py
 │   │   ├── marker_gene_verification.py
 │   │   ├── masking_ablation.py
-│   │   ├── module_importance.py
-│   │   ├── module_importance_publication.py
+│   │   ├── biomod_importance.py
+│   │   ├── biomod_importance_publication.py
 │   │   ├── pub_utils.py
 │   │   ├── random_baseline.py
 │   │   ├── README.md
 │   │   ├── RESULTS.md
 │   │   ├── tcell_reactome_analysis.py
 │   │   └── TODO.md
-│   ├── module_text_alignment/                            # Semantic alignment of module representations and pathway text
+│   ├── biomod_text_alignment/                            # Semantic alignment of module representations and pathway text
 │   │   ├── __init__.py
 │   │   ├── DESIGN.md
 │   │   ├── fetch_reactome_descriptions.py
 │   │   ├── MANUSCRIPT_SECTION.md
-│   │   ├── module_text_alignment.py
-│   │   ├── module_text_alignment_extended.py
-│   │   ├── module_text_alignment_publication.py
+│   │   ├── biomod_text_alignment.py
+│   │   ├── biomod_text_alignment_extended.py
+│   │   ├── biomod_text_alignment_publication.py
 │   │   └── reactome_descriptions.json
 │   ├── __init__.py
-│   ├── module_geometry.py
+│   ├── biomod_geometry.py
 │   ├── README.md
 │   └── utils.py
-├── module_data_all/                                      # Module definitions, merging and uncovered-gene tools
-│   ├── create_uncovered_modules.py
-│   ├── merge_modules.py
-│   └── merged_modules.json
 ├── tests/                                                # CPU tests for shared training utilities
 │   └── test_training_utils.py
 ├── toturials/                                            # Jupyter tutorials for five downstream tasks
@@ -103,7 +99,7 @@ BioMod/                                                   # Task code: training,
 │   │   ├── cmd.txt
 │   │   ├── make_low_depth_h5ad.py
 │   │   └── run_zero_shot_low_depth.py
-│   ├── performer_module_zero_shot.py
+│   ├── biomod_zero_shot.py
 │   ├── README.md
 │   └── visualize_results.py
 ├── .env.example
@@ -111,9 +107,9 @@ BioMod/                                                   # Task code: training,
 ├── .gitignore
 ├── command.txt
 ├── environment.yml
-├── models_performer_module.py
-├── module_dataset.py
-├── performer_module.py
+├── models_biomod.py
+├── biomod_dataset.py
+├── biomod.py
 ├── README.md
 ├── requirements.txt
 └── training_utils.py
@@ -130,7 +126,7 @@ environment:
 ```bash
 cd BioMod
 conda env create -f environment.yml
-conda activate performer_module
+conda activate biomod
 ```
 
 Or install Python packages into an existing CUDA/PyTorch environment:
@@ -143,7 +139,7 @@ From this source directory, activate the supplied environment and start Jupyter
 with the tutorial directory as its working directory:
 
 ```bash
-conda activate performer_module
+conda activate biomod
 cd toturials
 jupyter lab
 ```
@@ -161,26 +157,26 @@ imports after installing the dependencies:
 
 ```bash
 python -B -m unittest discover -s tests -p test_training_utils.py -v
-python -B performer_module.py --help
+python -B biomod.py --help
 ```
 
 The utility tests use synthetic tensors and temporary checkpoints; they do not
 load the supplied pretrained weights. Passing these checks does not validate a
 full training run. The pretraining entry point requires CUDA and an NCCL
 process group. Supply `--data_path` explicitly: the pretraining corpus is not
-bundled. Configure module inputs with `--module_data_dir` or `--module_data_path`.
+bundled. Configure module inputs with `--biomod_data_dir` or `--biomod_data_path`.
 Generated checkpoints default to `tutorial_runs/pretraining/` under the outer
 repository root, with periodic latest checkpoints under its `latest/` subdirectory.
 
 ## Shared Assets
 
 The BioMod model weights and matching configuration are stored in
-the outer repository's `weight/0810model/`. Use the supplied `.pth` and `.pkl`
+the outer repository's `weight/`. Use the supplied `.pth` and `.pkl`
 together.
 
-Tutorials expect a pretrained BioMod/PerformerModule checkpoint and shared
+Tutorials expect a pretrained BioMod checkpoint and shared
 gene assets. For the shell examples below, set `BIOMOD_ROOT` to the directory containing
-`weight/0810model/` and `model_dependencies/` (the outer `BioMod/` project directory).
+`weight/` and `model_dependencies/` (the outer `BioMod/` project directory).
 
 ```bash
 # Run this from the inner BioMod/ source directory.
@@ -190,45 +186,33 @@ export BIOMOD_ROOT="$(cd .. && pwd)"
 Current local asset files:
 
 ```text
-$BIOMOD_ROOT/weight/0810model/                # BioMod model weights and matching configuration
-├── mae_tost_70M_75mask_ec2.pkl
-└── mae_tost_70M_75mask_ec2_epoch0.pth
+$BIOMOD_ROOT/weight/                # BioMod model weights and matching configuration
+├── BioMod.pkl
+└── BioMod.pth
 
 $BIOMOD_ROOT/model_dependencies/              # Shared gene mappings, gene lists, embeddings and model components
-├── module_data_all/                                     # Shared module definitions and construction tools
-│   ├── create_uncovered_modules.py
-│   ├── merge_modules.py
-│   └── merged_modules.json
-├── performer_pytorch_cont/                              # Performer attention and model components
-│   ├── performer_pytorch_cont/                          # Nested package containing copies of the model component source files
-│   │   ├── __init__.py
-│   │   ├── ding_models.py
-│   │   ├── performer_pytorch.py
-│   │   ├── performer_pytorch_old.py
-│   │   └── reversible.py
+├── biomod_data_all/                                     # Shared module definitions and construction tools
+│   ├── create_uncovered_biomods.py
+│   ├── merge_biomods.py
+│   └── merged_biomods.json
+├── pytorch_cont/                              # Attention and model components
 │   ├── __init__.py
 │   ├── ding_models.py
-│   ├── performer_pytorch.py
-│   ├── performer_pytorch_old.py
+│   ├── pytorch.py
+│   ├── pytorch_old.py
 │   └── reversible.py
 ├── gene2ens.csv
 ├── selected_gene2vec_27k.npy
 └── selected_genes_27k.txt
 ```
 
-Project-local module definitions are kept in:
-
-```text
-BioMod/module_data_all/                                  # Module definitions, merging and uncovered-gene tools
-├── create_uncovered_modules.py
-├── merge_modules.py
-└── merged_modules.json
-```
+Module definitions and construction tools are shared through
+`$BIOMOD_ROOT/model_dependencies/biomod_data_all/`.
 
 ## BioMod model weights
 
-Use `mae_tost_70M_75mask_ec2_epoch0.pth` with
-`mae_tost_70M_75mask_ec2.pkl` from the shared-assets directory above. The supplied
+Use `BioMod.pth` with
+`BioMod.pkl` from the shared-assets directory above. The supplied
 configuration specifies a 2-layer encoder, a 27,874-gene axis, and 660 module
 definitions. Keep this configuration paired with the weights so that task
 runners can restore the corresponding architecture settings.
@@ -240,8 +224,8 @@ runners can restore the corresponding architecture settings.
 | Cell-type annotation | `toturials/cell_annotation.ipynb` | task script under `cell_annotation/` | metrics, classification report, confusion matrix |
 | Zero-shot batch integration | `toturials/zero_shot_batch_integration.ipynb` | `zero_shot_batch/` runner | UMAP PDF/PNG, avgBatch, avgBio |
 | Gene perturbation | `toturials/gene_perturbation.ipynb` | `gene_perturbation/` runner | selected model, configuration, parameters, and training log |
-| Drug response prediction | `toturials/drug_response_prediction.ipynb` | `drug_response/train_drug_performer_module.py` | scatter, residuals, ROC, per-drug and per-cancer tables |
-| Drug-combination synergy | `toturials/drug_combination.ipynb` | `drug_combination/train_drug_combination_performer_module.py` | label balance, loss, validation metrics, and ROC curves |
+| Drug response prediction | `toturials/drug_response_prediction.ipynb` | `drug_response/train_drug_biomod.py` | scatter, residuals, ROC, per-drug and per-cancer tables |
+| Drug-combination synergy | `toturials/drug_combination.ipynb` | `drug_combination/train_drug_combination_biomod.py` | label balance, loss, validation metrics, and ROC curves |
 
 Each notebook derives paths from `PROJECT_ROOT = Path('../..').resolve()` when
 Jupyter runs from `BioMod/toturials/`. From the repository root, change this to
@@ -296,12 +280,12 @@ Run these commands from the inner `BioMod/` source directory after setting
 `BIOMOD_ROOT` as shown above. Drug response prediction with the BioMod model weights:
 
 ```bash
-python drug_response/train_drug_performer_module.py \
+python drug_response/train_drug_biomod.py \
   --gpu_id 0 \
   --data_path "$BIOMOD_ROOT/data/downstream/final_data/single_drug_response/data" \
-  --checkpoint_path "$BIOMOD_ROOT/weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth" \
-  --hyper_params_path "$BIOMOD_ROOT/weight/0810model/mae_tost_70M_75mask_ec2.pkl" \
-  --module_data_dir "$BIOMOD_ROOT/model_dependencies/module_data_all" \
+  --checkpoint_path "$BIOMOD_ROOT/weight/BioMod.pth" \
+  --hyper_params_path "$BIOMOD_ROOT/weight/BioMod.pkl" \
+  --biomod_data_dir "$BIOMOD_ROOT/model_dependencies/biomod_data_all" \
   --gene_list_path "$BIOMOD_ROOT/model_dependencies/selected_genes_27k.txt" \
   --gene_mapping_path "$BIOMOD_ROOT/model_dependencies/gene2ens.csv" \
   --gene2vec_path "$BIOMOD_ROOT/model_dependencies/selected_gene2vec_27k.npy" \
@@ -315,10 +299,10 @@ python drug_response/train_drug_performer_module.py \
 Drug-combination synergy prediction:
 
 ```bash
-python drug_combination/train_drug_combination_performer_module.py \
-  --checkpoint_path "$BIOMOD_ROOT/weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth" \
-  --hyper_params_path "$BIOMOD_ROOT/weight/0810model/mae_tost_70M_75mask_ec2.pkl" \
-  --module_data_dir "$BIOMOD_ROOT/model_dependencies/module_data_all" \
+python drug_combination/train_drug_combination_biomod.py \
+  --checkpoint_path "$BIOMOD_ROOT/weight/BioMod.pth" \
+  --hyper_params_path "$BIOMOD_ROOT/weight/BioMod.pkl" \
+  --biomod_data_dir "$BIOMOD_ROOT/model_dependencies/biomod_data_all" \
   --gene_list_path "$BIOMOD_ROOT/model_dependencies/selected_genes_27k.txt" \
   --gene_mapping_path "$BIOMOD_ROOT/model_dependencies/gene2ens.csv" \
   --gene2vec_path "$BIOMOD_ROOT/model_dependencies/selected_gene2vec_27k.npy" \
@@ -376,7 +360,7 @@ files and shows which entries are missing.
 
 Check `BIOMOD_ROOT` for shell commands or `PROJECT_ROOT` in a notebook, and verify that the BioMod model weights, matching
 `.pkl` configuration, gene2vec file, gene list, gene mapping, and
-`performer_pytorch_cont/` directory exist at the paths listed under Shared Assets.
+`pytorch_cont/` directory exist at the paths listed under Shared Assets.
 
 ### No space left on device
 

BioMod/{performer_module.py → biomod.py}

@@ -2,14 +2,14 @@
 
 """
 ================================================================================
-Pre-training script for Encoder-only Performer model
+Pre-training script for encoder-only BioMod model
 ================================================================================
-Refer to MAE's data input and masking methods, but use Performer as the encoder
+Refer to MAE's data input and masking methods, but use the BioMod attention encoder
 Main features:
 1. Use module data input (refer to MAE)
 2. Mask the module (refer to MAE’s random_masking)
 3. Use a configurable reconstruction decoder or direct prediction heads
-4. Use Performer as encoder (instead of standard Transformer Block)
+4. Use the BioMod attention encoder
 
 ================================================================================
 [Data flow example - taking default parameters as an example]
@@ -25,11 +25,11 @@
         - 3 = batch_size
         - 27874 = num_genes (gene expression value)
 
-Step 3: Model forward propagation (see models_performer_module.py for details)
+Step 3: Model forward propagation (see models_biomod.py for details)
     ├─> 3.1 Flat to Module: (3, 27874) → (3, num_modules, module_avg_size)
     ├─> 3.2 Module Embedding: → (3, num_modules, 1024)
     ├─> 3.3 Random Masking: mask out 75% of modules and keep 25%
-    ├─> 3.4 Performer Encoder: Process visible modules
+    ├─> 3.4 BioMod encoder: Process visible modules
     ├─> 3.5 Reconstruction: Predict the expression value of the masked module
     └─> 3.6 Calculate Loss: Calculate MSE only on the masked module
 
@@ -63,11 +63,11 @@
 ASSET_ROOT = PROJECT_ROOT / 'model_dependencies'
 if str(SOURCE_DIR) not in sys.path:
     sys.path.insert(0, str(SOURCE_DIR))
-from models_performer_module import (
-    PerformerEncoderOnly_Module,
-    sanitize_performer_module_config,
+from models_biomod import (
+    BioMod,
+    sanitize_biomod_config,
 )
-from module_dataset import ModuleSCDataset, load_module_data
+from biomod_dataset import BioModSCDataset, load_biomod_data
 from training_utils import (
     CosineAnnealingWarmupRestarts,
     SequentialDistributedSampler,
@@ -125,7 +125,7 @@
 parser.add_argument("--dec_heads", type=int, default=8, help='Number of decoder attention heads (valid when performer/cross_attn)')
 parser.add_argument("--dec_dim_head", type=int, default=64, help='Performer decoder dim per head (ignored when cross_attn)')
 parser.add_argument("--ckpt_dir", type=str, default=str(PROJECT_ROOT / 'tutorial_runs' / 'pretraining'), help='Directory for generated checkpoints; user relative paths use the current working directory.')
-parser.add_argument("--model_name", type=str, default='performer_module_27k', help='Pretrained model name.')
+parser.add_argument("--model_name", type=str, default='biomod_27k', help='Pretrained model name.')
 parser.add_argument("--data_path", type=str, required=True,
                     help='Pretraining input: a directory for npz/txt or a file for h5/h5ad. Supply your own pretraining data; it is not bundled.')
 parser.add_argument("--data_format", type=str, default="npz", choices=["npz", "h5", "h5ad", "txt"],
@@ -133,8 +133,8 @@
 parser.add_argument("--h5_dataset_key", type=str, default="expression",
                     help='The data set key name of the expression matrix in h5 format. The default is to read h5[\"expression\"]')
 # Module related parameters
-parser.add_argument("--module_data_path", type=str, default=None, help='Path to module JSON file (single file).')
-parser.add_argument("--module_data_dir", type=str, default=None, help='Path to directory containing module JSON files.')
+parser.add_argument("--biomod_data_path", "--module_data_path", type=str, default=None, help='Path to module JSON file (single file).', dest='module_data_path')
+parser.add_argument("--biomod_data_dir", "--module_data_dir", type=str, default=None, help='Path to directory containing module JSON files.', dest='module_data_dir')
 parser.add_argument("--gene_mapping_path", type=str, default=str(ASSET_ROOT / 'gene2ens.csv'), help='Path to gene symbol to Ensembl ID mapping CSV.')
 parser.add_argument("--gene2vec_data_path", type=str, default=str(ASSET_ROOT / 'selected_gene2vec_27k.npy'))
 parser.add_argument("--fusion_method", type=str, default="multiply",
@@ -167,8 +167,8 @@
 parser.add_argument("--load_opt_and_sched", action='store_true')
 parser.add_argument("--lr_step_within_epoch", action='store_true',
                     help='Update the learning rate according to the optimizer update step; the cycle length is updates_per_epoch (gradually decreasing in each epoch)')
-parser.add_argument("--shuffle_module_genes", action='store_true',
-                    help='Whether to disrupt the gene allocation within the module (used for comparative experiments to verify the effectiveness of module division)')
+parser.add_argument("--shuffle_biomod_genes", "--shuffle_module_genes", action='store_true',
+                    help='Whether to disrupt the gene allocation within the module (used for comparative experiments to verify the effectiveness of module division)', dest='shuffle_module_genes')
 parser.add_argument("--shuffle_seed", type=int, default=2021,
                     help='Random seed used when scrambling module genes (downstream tasks need to use the same value)')
 # Gene2vec ablation experiment parameters
@@ -278,7 +278,7 @@ def restore_model_args_from_config(args, config):
             args.model_config_path,
         )
         with open(resolved_model_config_path, "rb") as handle:
-            resume_model_config = sanitize_performer_module_config(
+            resume_model_config = sanitize_biomod_config(
                 pickle.load(handle),
                 source=resolved_model_config_path,
                 log_fn=print,
@@ -325,11 +325,11 @@ def restore_model_args_from_config(args, config):
 
         # WandB resume logic
         wandb_init_kwargs = {
-            "project": "pretrain_performer_module",
+            "project": "pretrain_biomod",
             "name": args.model_name,
             "entity": "icml_2023_mlb",
             "config": {
-                "architecture": "performer_module",
+                "architecture": "biomod",
                 "gene_num": args.gene_num,
                 "cell_num": args.cell_num,
                 "load model": args.model_path,
@@ -490,7 +490,7 @@ def resolve_total_cells_for_split():
         if is_master:
             print(f"Using {len(module_sets)} modules restored from model config PKL")
     else:
-        module_sets = load_module_data(
+        module_sets = load_biomod_data(
             module_data_path=args.module_data_path,
             module_data_dir=args.module_data_dir,
             gene_list_path=args.gene_list_path,
@@ -616,14 +616,14 @@ def resolve_total_cells_for_split():
         )
 
     # Step 3.3: Instantiate the model
-    # PerformerEncoderOnly_Module model process:
+    # BioMod model process:
     # Input: (batch_size, num_genes) = (3, 27874)
     # ├─> Module division: (batch_size, num_modules, module_avg_size) ≈ (3, 500, 55)
     #   ├─> Module Embedding: (batch_size, num_modules, base_dim) = (3, 500, 1024)
     # ├─> Random Masking (75%): Keep about 125 visible modules
-    # ├─> Performer Encoder: Process visible modules
+    # ├─> BioMod encoder: Process visible modules
     # └─> Reconstruction prediction: Output the reconstruction value of the masked module
-    model = PerformerEncoderOnly_Module(**model_params)
+    model = BioMod(**model_params)
 
     def configure_trainable_modules(model_obj):
         for param in model_obj.parameters():
@@ -721,8 +721,8 @@ def save_initialized_checkpoint_and_exit(model_obj):
     # Step 2.1/2.2 has been completed previously
 
     # Step 2.3: Create training and validation datasets
-    # ModuleSCDataset directly returns the gene expression value, and the module conversion is completed inside the model.
-    train_dataset = ModuleSCDataset(
+    # BioModSCDataset directly returns the gene expression value, and the module conversion is completed inside the model.
+    train_dataset = BioModSCDataset(
         data_path=args.data_path,
         module_sets=module_sets,  # Pass module_sets to maintain compatibility, but no longer used in __getitem__
         data=None,
@@ -735,7 +735,7 @@ def save_initialized_checkpoint_and_exit(model_obj):
         cell_num=None,
         verbose=is_master
     )
-    val_dataset = ModuleSCDataset(
+    val_dataset = BioModSCDataset(
         data_path=args.data_path,
         module_sets=module_sets,
         data=None,
@@ -880,7 +880,7 @@ def any_rank_true(local_flag: bool) -> bool:
                         # 1. Flat to Module: (3, 27874) -> (3, num_modules, module_avg_size)
                         #   2. Module Embedding: -> (3, num_modules, 1024)
                         # 3. Random Masking: mask out 75% of modules
-                        # 4. Performer Encoder: Process visible modules
+                        # 4. BioMod encoder: Process visible modules
                         # 5. Reconstruction: Predict the masked module
                         # Output: loss=MSE on masked module, preds=reconstructed value, mask=mask mark
                         loss, preds, mask = model(data)

BioMod/{module_dataset.py → biomod_dataset.py}

@@ -25,7 +25,7 @@
     h5py = None
 
 
-def load_module_data(
+def load_biomod_data(
     module_data_path: Optional[str] = None,
     module_data_dir: Optional[str] = None,
     gene_list_path: Optional[str] = None,
@@ -219,7 +219,7 @@ def _convert_genes_to_indices(genes: list) -> list[int]:
         elif isinstance(data, list):
             modules = data
         else:
-            raise ValueError("module_data format is incorrect")
+            raise ValueError("biomod_data format is incorrect")
         
         module_sets = []
         for p in modules:
@@ -246,13 +246,13 @@ def _convert_genes_to_indices(genes: list) -> list[int]:
         raise ValueError("module_data_path or module_data_dir must be provided")
 
 
-class ModuleSCDataset(Dataset):
+class BioModSCDataset(Dataset):
     """
     single cell data set
     Supports .npz (sparse CSR), .h5ad and .txt formats
 
     Note: This class no longer performs module conversion (redundant _flat_to_modules removed)
-    Module conversion is completed by the ModuleEmbedding layer inside the model to avoid repeated calculations
+    Module conversion is completed by the BioModEmbedding layer inside the model to avoid repeated calculations
     """
 
     def __init__(

BioMod/cell_annotation/{module_data/load_module.py → biomod_data/load_biomod.py}

@@ -29,8 +29,8 @@ def load_json_files(file1_path, file2_path):
 
 
 # hallmark_data, reactome_data = load_json_files(
-#     'module1_hallmarks.json', 
-#     'module2_reactome_2022_filtered.json'
+#     'biomod1_hallmarks.json', 
+#     'biomod2_reactome_2022_filtered.json'
 # )
 # len(hallmark_data.keys())
 # len(reactome_data.keys())

BioMod/cell_annotation/{performer_module_finetune.py → biomod_finetune.py}

@@ -2,12 +2,12 @@
 # -*- coding: utf-8 -*-
 
 """
-End-to-end cell annotation fine-tuning for Performer Module.
+End-to-end cell annotation fine-tuning for BioMod.
 
 This script is intentionally independent from the legacy two-stage pipeline:
 1. No feature extraction to .npy files.
-2. No imports from other scripts in performer_module/cell_annotation.
-3. Reuses the pretrained Performer Module backbone directly.
+2. No imports from other scripts in biomod/cell_annotation.
+3. Reuses the pretrained BioMod backbone directly.
 
 Supported cell embedding heads:
 - module_mean: mean over restored module tokens
@@ -48,26 +48,26 @@
 from torch.utils.data.distributed import DistributedSampler
 
 SCRIPT_DIR = Path(__file__).resolve().parent
-PERFORMER_MODULE_ROOT = SCRIPT_DIR.parent
-SCLONG_ROOT = PERFORMER_MODULE_ROOT.parent
+BIOMOD_ROOT = SCRIPT_DIR.parent
+SCLONG_ROOT = BIOMOD_ROOT.parent
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 ASSET_DIR = REPO_ROOT / "model_dependencies"
 DOWNSTREAM_DATA_DIR = REPO_ROOT / "data" / "downstream" / "final_data"
-WEIGHTS_DIR = REPO_ROOT / "weight" / "0810model"
+WEIGHTS_DIR = REPO_ROOT / "weight"
 
-if str(PERFORMER_MODULE_ROOT) not in sys.path:
-    sys.path.insert(0, str(PERFORMER_MODULE_ROOT))
+if str(BIOMOD_ROOT) not in sys.path:
+    sys.path.insert(0, str(BIOMOD_ROOT))
 if str(SCLONG_ROOT) not in sys.path:
     sys.path.insert(0, str(SCLONG_ROOT))
 
-from models_performer_module import (
-    migrate_legacy_module_config,
-    migrate_legacy_module_state_dict,
+from models_biomod import (
+    migrate_legacy_biomod_config,
+    migrate_legacy_biomod_state_dict,
 )
 
 if TYPE_CHECKING:
-    from models_performer_module import PerformerEncoderOnly_Module
+    from models_biomod import BioMod
 
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
@@ -373,7 +373,7 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
         return self.out_layer(x)
 
 
-class ModuleSelector(nn.Module):
+class BioModSelector(nn.Module):
     """Per-module scorer: soft weighting during training, hard threshold during inference."""
 
     def __init__(self, embed_dim: int):
@@ -395,10 +395,10 @@ def forward(
         return x, scores
 
 
-class PerformerModuleCellClassifier(nn.Module):
+class BioModCellClassifier(nn.Module):
     def __init__(
         self,
-        backbone: "PerformerEncoderOnly_Module",
+        backbone: "BioMod",
         module_sets: List[List[int]],
         num_classes: int,
         head_type: str,
@@ -430,13 +430,13 @@ def __init__(
         self.use_module_selector = use_module_selector
         self.selector_tau = 0.5
         if use_module_selector:
-            self.module_selector = ModuleSelector(self.embed_dim)
+            self.module_selector = BioModSelector(self.embed_dim)
         else:
             self.module_selector = None
         self._selector_scores = None
 
         if self.head_type == "gene_mean":
-            module_idx, gene_idx, gene_counts = self._build_module_gene_index()
+            module_idx, gene_idx, gene_counts = self._build_biomod_gene_index()
             self.register_buffer("agg_module_idx", module_idx)
             self.register_buffer("agg_gene_idx", gene_idx)
             self.register_buffer("agg_gene_counts", gene_counts)
@@ -454,12 +454,12 @@ def __init__(
     def load_state_dict(self, state_dict, strict: bool = True, assign: bool = False):
         """Accept current module names and older serialized backbone names."""
         return super().load_state_dict(
-            migrate_legacy_module_state_dict(state_dict),
+            migrate_legacy_biomod_state_dict(state_dict),
             strict=strict,
             assign=assign,
         )
 
-    def _build_module_gene_index(self) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    def _build_biomod_gene_index(self) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
         module_indices = []
         gene_indices = []
         gene_counts = torch.zeros(self.num_genes, dtype=torch.long)
@@ -475,7 +475,7 @@ def _build_module_gene_index(self) -> Tuple[torch.Tensor, torch.Tensor, torch.Te
             gene_counts,
         )
 
-    def _restore_module_order(self, latent: torch.Tensor, ids_restore: torch.Tensor) -> torch.Tensor:
+    def _restore_biomod_order(self, latent: torch.Tensor, ids_restore: torch.Tensor) -> torch.Tensor:
         if self.use_cls:
             module_tokens = latent[:, 1:, :]
         else:
@@ -483,7 +483,7 @@ def _restore_module_order(self, latent: torch.Tensor, ids_restore: torch.Tensor)
         gather_index = ids_restore.unsqueeze(-1).expand(-1, -1, module_tokens.shape[-1])
         return torch.gather(module_tokens, dim=1, index=gather_index)
 
-    def _module_to_gene(self, module_tokens: torch.Tensor) -> torch.Tensor:
+    def _biomod_to_gene(self, module_tokens: torch.Tensor) -> torch.Tensor:
         batch_size, _, dim = module_tokens.shape
         gene_feats = torch.zeros(
             batch_size,
@@ -519,7 +519,7 @@ def forward(self, x_model: torch.Tensor) -> torch.Tensor:
         if self.head_type == "cls":
             cell_emb = latent[:, 0, :]
         else:
-            module_tokens = self._restore_module_order(latent, ids_restore)
+            module_tokens = self._restore_biomod_order(latent, ids_restore)
             if self.module_selector is not None:
                 module_tokens, self._selector_scores = self.module_selector(
                     module_tokens, tau=self.selector_tau, hard=not self.training,
@@ -531,7 +531,7 @@ def forward(self, x_model: torch.Tensor) -> torch.Tensor:
             elif self.head_type == "attn_pool":
                 cell_emb, _ = self.pooler(module_tokens)
             elif self.head_type == "gene_mean":
-                gene_tokens = self._module_to_gene(module_tokens)
+                gene_tokens = self._biomod_to_gene(module_tokens)
                 cell_emb = gene_tokens.mean(dim=1)
             else:
                 raise ValueError(f"Unsupported head_type: {self.head_type}")
@@ -540,13 +540,13 @@ def forward(self, x_model: torch.Tensor) -> torch.Tensor:
         return self.classifier(cell_emb)
 
 
-def get_encoder_blocks(backbone: "PerformerEncoderOnly_Module") -> List[nn.Module]:
+def get_encoder_blocks(backbone: "BioMod") -> List[nn.Module]:
     net = backbone.encoder.net
     if hasattr(net, "layers"):
         return list(net.layers)
     if hasattr(net, "blocks"):
         return list(net.blocks)
-    raise AttributeError("Cannot find encoder blocks on Performer backbone")
+    raise AttributeError("Cannot find encoder blocks on BioMod backbone")
 
 
 def set_requires_grad(module: nn.Module, flag: bool) -> None:
@@ -555,7 +555,7 @@ def set_requires_grad(module: nn.Module, flag: bool) -> None:
 
 
 def configure_backbone_trainability(
-    backbone: "PerformerEncoderOnly_Module",
+    backbone: "BioMod",
     finetune_mode: str,
     unfreeze_last_n: int,
     train_pos_emb: bool,
@@ -604,7 +604,7 @@ def configure_backbone_trainability(
 
 
 def build_optimizer(
-    model: PerformerModuleCellClassifier,
+    model: BioModCellClassifier,
     lr_head: float,
     lr_backbone: float,
     weight_decay: float,
@@ -669,20 +669,20 @@ def resolve_batch_sizes(args, world_size: int) -> Tuple[int, int, int]:
     return train_batch_size, eval_batch_size, effective_global_batch
 
 
-def infer_model_config(args, checkpoint: dict, pkl_config: Optional[dict], module_data: List[List[int]]) -> dict:
-    from models_performer_module import sanitize_performer_module_config
+def infer_model_config(args, checkpoint: dict, pkl_config: Optional[dict], biomod_data: List[List[int]]) -> dict:
+    from models_biomod import sanitize_biomod_config
 
     if pkl_config is not None and isinstance(pkl_config, dict):
-        config = sanitize_performer_module_config(
+        config = sanitize_biomod_config(
             pkl_config,
             source=str(args.config_pkl),
             log_fn=logger.info,
         )
         logger.info("Using config from PKL: %s", args.config_pkl)
         if "module_sets" in config:
-            module_data = config["module_sets"]
+            biomod_data = config["module_sets"]
     elif isinstance(checkpoint, dict) and "config" in checkpoint:
-        config = sanitize_performer_module_config(
+        config = sanitize_biomod_config(
             checkpoint["config"],
             source=str(resolve_path(args.performer_checkpoint)),
             log_fn=logger.info,
@@ -695,7 +695,7 @@ def infer_model_config(args, checkpoint: dict, pkl_config: Optional[dict], modul
         )
 
     return {
-        "module_sets": module_data,
+        "module_sets": biomod_data,
         "num_genes": config["num_genes"],
         "base_dim": config["base_dim"],
         "enc_depth": config["enc_depth"],
@@ -722,9 +722,9 @@ def infer_model_config(args, checkpoint: dict, pkl_config: Optional[dict], modul
     }
 
 
-def compute_module_family_ids(module_data_dir: str) -> List[int]:
-    """Read merged_modules.json, return family ID (0-3) for each module."""
-    merged_path = Path(module_data_dir) / "merged_modules.json"
+def compute_biomod_family_ids(module_data_dir: str) -> List[int]:
+    """Read merged_biomods.json, return family ID (0-3) for each module."""
+    merged_path = Path(module_data_dir) / "merged_biomods.json"
     with open(merged_path) as f:
         modules = json.load(f)
     PREFIXES = [
@@ -744,32 +744,32 @@ def compute_module_family_ids(module_data_dir: str) -> List[int]:
     return family_ids
 
 
-def load_backbone(args, device: torch.device) -> Tuple["PerformerEncoderOnly_Module", List[List[int]], dict]:
-    from models_performer_module import PerformerEncoderOnly_Module
-    from module_dataset import load_module_data
+def load_backbone(args, device: torch.device) -> Tuple["BioMod", List[List[int]], dict]:
+    from models_biomod import BioMod
+    from biomod_dataset import load_biomod_data
 
     config_pkl = None
     config_path = resolve_path(args.config_pkl)
     if config_path.exists():
         with open(config_path, "rb") as handle:
-            config_pkl = migrate_legacy_module_config(pickle.load(handle))
+            config_pkl = migrate_legacy_biomod_config(pickle.load(handle))
     else:
         logger.warning("Config PKL not found at %s; fallback to checkpoint config", config_path)
 
     ckpt_path = resolve_path(args.performer_checkpoint)
     checkpoint = torch.load(ckpt_path, map_location=device)
 
-    module_data = None
+    biomod_data = None
     if isinstance(config_pkl, dict) and "module_sets" in config_pkl:
-        module_data = config_pkl["module_sets"]
-        logger.info("Using module_sets from PKL (%d modules)", len(module_data))
+        biomod_data = config_pkl["module_sets"]
+        logger.info("Using module_sets from PKL (%d modules)", len(biomod_data))
     elif isinstance(checkpoint, dict) and isinstance(checkpoint.get("config"), dict) and "module_sets" in checkpoint["config"]:
-        module_data = checkpoint["config"]["module_sets"]
-        logger.info("Using module_sets from checkpoint config (%d modules)", len(module_data))
+        biomod_data = checkpoint["config"]["module_sets"]
+        logger.info("Using module_sets from checkpoint config (%d modules)", len(biomod_data))
     else:
         if not args.module_data_dir:
             raise ValueError("module_data_dir is required when module_sets are not stored in the PKL/checkpoint config")
-        module_data = load_module_data(
+        biomod_data = load_biomod_data(
             module_data_dir=str(resolve_path(args.module_data_dir)),
             gene_list_path=str(resolve_path(args.gene_list_path)),
             gene_mapping_path=str(resolve_path(args.gene_mapping_path)),
@@ -779,18 +779,18 @@ def load_backbone(args, device: torch.device) -> Tuple["PerformerEncoderOnly_Mod
     if args.shuffle_module_genes:
         logger.info("Shuffling genes across modules with seed=%d", args.shuffle_seed)
         rng = random.Random(args.shuffle_seed)
-        module_sizes = [len(module) for module in module_data]
-        all_genes = [gene for module in module_data for gene in module]
+        module_sizes = [len(module) for module in biomod_data]
+        all_genes = [gene for module in biomod_data for gene in module]
         rng.shuffle(all_genes)
         shuffled = []
         start = 0
         for size in module_sizes:
             shuffled.append(all_genes[start:start + size])
             start += size
-        module_data = shuffled
+        biomod_data = shuffled
 
-    model_config = infer_model_config(args, checkpoint, config_pkl, module_data)
-    module_data = model_config["module_sets"]
+    model_config = infer_model_config(args, checkpoint, config_pkl, biomod_data)
+    biomod_data = model_config["module_sets"]
 
     if "model_state_dict" in checkpoint:
         state_dict = checkpoint["model_state_dict"]
@@ -807,7 +807,7 @@ def load_backbone(args, device: torch.device) -> Tuple["PerformerEncoderOnly_Mod
         model_config["base_dim"],
         model_config["enc_depth"],
         model_config["enc_heads"],
-        len(module_data),
+        len(biomod_data),
         use_cls_token,
     )
 
@@ -815,13 +815,13 @@ def load_backbone(args, device: torch.device) -> Tuple["PerformerEncoderOnly_Mod
     if getattr(args, "use_family_emb", False):
         pdd = getattr(args, "module_data_dir", None)
         if pdd:
-            module_family_ids = compute_module_family_ids(str(resolve_path(pdd)))
+            module_family_ids = compute_biomod_family_ids(str(resolve_path(pdd)))
             logger.info("Family embedding enabled: %d module family IDs computed", len(module_family_ids))
 
-    backbone = PerformerEncoderOnly_Module(
-        module_sets=module_data,
+    backbone = BioMod(
+        module_sets=biomod_data,
         num_genes=model_config["num_genes"],
-        max_seq_len=len(module_data),
+        max_seq_len=len(biomod_data),
         base_dim=model_config["base_dim"],
         enc_depth=model_config["enc_depth"],
         enc_heads=model_config["enc_heads"],
@@ -866,7 +866,7 @@ def load_backbone(args, device: torch.device) -> Tuple["PerformerEncoderOnly_Mod
         logger.warning("Unexpected keys: %s", unexpected_keys[:10])
 
     backbone.to(device)
-    return backbone, module_data, model_config
+    return backbone, biomod_data, model_config
 
 
 def stratified_split(
@@ -908,7 +908,7 @@ def stratified_train_val_split(
 
 @torch.no_grad()
 def evaluate(
-    model: PerformerModuleCellClassifier,
+    model: BioModCellClassifier,
     data_loader: DataLoader,
     preprocessor: DataPreprocessor,
     reindex_state: dict,
@@ -948,7 +948,7 @@ def evaluate(
 
 
 def train_one_epoch(
-    model: PerformerModuleCellClassifier,
+    model: BioModCellClassifier,
     data_loader: DataLoader,
     preprocessor: DataPreprocessor,
     reindex_state: dict,
@@ -1075,7 +1075,7 @@ def apply_dataset_preset(args) -> None:
 
 
 def parse_args():
-    parser = argparse.ArgumentParser(description="End-to-end fine-tuning for Performer Module cell annotation")
+    parser = argparse.ArgumentParser(description="End-to-end fine-tuning for BioMod cell annotation")
 
     parser.add_argument("--seed", type=int, default=2021)
     parser.add_argument("--device", type=str, default="cuda")
@@ -1117,13 +1117,13 @@ def parse_args():
     )
     parser.add_argument("--unfreeze_last_n", type=int, default=1)
     parser.add_argument("--train_pos_emb", action="store_true")
-    parser.add_argument("--train_module_embed", action="store_true")
+    parser.add_argument("--train_biomod_embed", "--train_module_embed", action="store_true", dest='train_module_embed')
     parser.add_argument("--use_family_emb", action="store_true",
                         help="Add family-type embedding (Hallmarks/Reactome/Hotspot/WGCNA)")
-    parser.add_argument("--use_module_gate", action="store_true",
-                        help="Add learnable sparse gate per module")
-    parser.add_argument("--use_module_selector", action="store_true",
-                        help="Dynamic module selector with sparsity loss (soft train, hard inference)")
+    parser.add_argument("--use_biomod_gate", "--use_module_gate", action="store_true",
+                        help="Add learnable sparse gate per module", dest='use_module_gate')
+    parser.add_argument("--use_biomod_selector", "--use_module_selector", action="store_true",
+                        help="Dynamic module selector with sparsity loss (soft train, hard inference)", dest='use_module_selector')
     parser.add_argument("--selector_sparsity_weight", type=float, default=0.1,
                         help="Lambda for sparsity loss on module selector scores")
     parser.add_argument("--selector_tau", type=float, default=0.5,
@@ -1152,32 +1152,33 @@ def parse_args():
     parser.add_argument("--min_cells", type=int, default=10)
     parser.add_argument("--max_cells", type=int, default=None)
 
-    parser.add_argument("--config_pkl", type=str, default=str(WEIGHTS_DIR / "mae_tost_70M_75mask_ec2.pkl"))
+    parser.add_argument("--config_pkl", type=str, default=str(WEIGHTS_DIR / "BioMod.pkl"))
     parser.add_argument(
-        "--performer_checkpoint",
+        "--biomod_checkpoint", "--performer_checkpoint",
         type=str,
-        default=str(WEIGHTS_DIR / "mae_tost_70M_75mask_ec2_epoch0.pth"),
+        default=str(WEIGHTS_DIR / "BioMod.pth"),
+        dest='performer_checkpoint',
     )
-    parser.add_argument("--module_data_dir", type=str, default=str(ASSET_DIR / "module_data_all"))
+    parser.add_argument("--biomod_data_dir", "--module_data_dir", type=str, default=str(ASSET_DIR / "biomod_data_all"), dest='module_data_dir')
     parser.add_argument("--gene_list_path", type=str, default=str(ASSET_DIR / "selected_genes_27k.txt"))
     parser.add_argument("--gene_mapping_path", type=str, default=str(ASSET_DIR / "gene2ens.csv"))
     parser.add_argument("--gene2vec_data_path", type=str, default=str(ASSET_DIR / "selected_gene2vec_27k.npy"))
     parser.add_argument("--gene2ens_file", type=str, default=str(ASSET_DIR / "gene2ens.csv"))
     parser.add_argument("--gene2ens_column", type=str, default="Ensembl gene ID")
     parser.add_argument(
-        "--shuffle_module_genes",
+        "--shuffle_biomod_genes", "--shuffle_module_genes",
         action="store_true",
         help="Apply an extra downstream reshuffle on top of module_sets restored from PKL. "
              "Do not pass this when reproducing the pretrained backbone as-is.",
-    )
+        dest='shuffle_module_genes')
     parser.add_argument(
         "--shuffle_seed",
         type=int,
         default=2021,
-        help="Random seed for the downstream extra reshuffle when --shuffle_module_genes is enabled.",
+        help="Random seed for the downstream extra reshuffle when --shuffle_biomod_genes is enabled.",
     )
 
-    parser.add_argument("--output_dir", type=str, default="./ckpts_performer_module_finetune")
+    parser.add_argument("--output_dir", type=str, default="./ckpts_biomod_finetune")
     parser.add_argument("--run_name", type=str, default="")
     parser.add_argument(
         "--save_test_artifacts",
@@ -1384,7 +1385,7 @@ def main():
         train_module_embed=args.train_module_embed,
     )
 
-    model = PerformerModuleCellClassifier(
+    model = BioModCellClassifier(
         backbone=backbone,
         module_sets=module_sets,
         num_classes=num_classes,

BioMod/cell_annotation/cmd_finetune.md

@@ -3,9 +3,9 @@
 Run this command from the repository root in a CUDA/NCCL environment. Resource defaults resolve from the script location; explicit relative paths resolve from the working directory.
 
 ```bash
-torchrun --nproc_per_node=4 BioMod/cell_annotation/performer_module_finetune.py \
---config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
---performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
+torchrun --nproc_per_node=4 BioMod/cell_annotation/biomod_finetune.py \
+--config_pkl weight/BioMod.pkl \
+--biomod_checkpoint weight/BioMod.pth \
 --data_path data/downstream/final_data/Zheng68K.h5ad \
 --label_column celltype \
 --head_type attn_pool \
@@ -16,6 +16,6 @@ torchrun --nproc_per_node=4 BioMod/cell_annotation/performer_module_finetune.py
 --lr_backbone 1e-5 \
 --batch_size 256 \
 --epochs 300 \
---module_data_dir model_dependencies/module_data_all \
+--biomod_data_dir model_dependencies/biomod_data_all \
 --output_dir tutorial_runs/cell_annotation_zheng68k
 ```

BioMod/command.txt

@@ -1,10 +1,10 @@
 # Run from the outer repository root in a Linux CUDA/NCCL environment.
 # Set BIOMOD_PRETRAIN_DATA to your preprocessed per-cell NPZ directory.
 # The pretraining corpus is not included in this repository.
-conda activate performer_module
+conda activate biomod
 : "${BIOMOD_PRETRAIN_DATA:?Set BIOMOD_PRETRAIN_DATA to the pretraining NPZ directory}"
 torchrun --standalone --nproc_per_node="${NPROC_PER_NODE:-1}" \
-    BioMod/performer_module.py \
+    BioMod/biomod.py \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --cell_num 4000000 \
     --epoch 15 \
@@ -15,11 +15,11 @@ torchrun --standalone --nproc_per_node="${NPROC_PER_NODE:-1}" \
     --log_every 100 \
     --mask_ratio 0.75 \
     --data_path "$BIOMOD_PRETRAIN_DATA" \
-    --module_data_dir model_dependencies/module_data_all \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
     --ckpt_dir tutorial_runs/pretraining \
-    --model_name performer_module_pretraining \
+    --model_name biomod_pretraining \
     --fusion_method multiply \
     --loss_mode gene_mean \
     --decoder_type simple \

BioMod/drug_combination/README.md

@@ -1,19 +1,19 @@
 # Drug Combination Synergy Prediction with BioMod
 
 This task predicts drug-combination synergy using BioMod cell embeddings from
-the PerformerModule encoder and GCN-based drug molecular graph encoders. Use the
+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
-PerformerModule.
+BioMod.
 
 ## 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 PerformerModule encoder, module mean pooling, and an MLP to 128 dimensions |
+| Cell branch | Pretrained BioMod encoder, module mean 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.
@@ -55,20 +55,20 @@ pip install RDKit -i https://pypi.tuna.tsinghua.edu.cn/simple
 ### Basic Run (Domain Generalization Mode, Default)
 
 ```bash
-python BioMod/drug_combination/train_drug_combination_performer_module.py \
-    --checkpoint_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/drug_combination/train_drug_combination_biomod.py \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --data_dir data/downstream/final_data/drug_combination_synergy/data_summary
 ```
 
 ### Custom Paths
 
 ```bash
-python BioMod/drug_combination/train_drug_combination_performer_module.py \
-    --checkpoint_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/drug_combination/train_drug_combination_biomod.py \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt\
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_path model_dependencies/selected_gene2vec_27k.npy \
@@ -87,20 +87,20 @@ Reference note: `1e-4 500 0.6824301861702127`.
 ### Five-Fold Cross-Validation (Disable Domain Generalization)
 
 ```bash
-python BioMod/drug_combination/train_drug_combination_performer_module.py \
-    --checkpoint_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/drug_combination/train_drug_combination_biomod.py \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --no_domain_gen
 ```
 
 ### Force Reprocessing After Changing the Model or Data
 
 ```bash
-python BioMod/drug_combination/train_drug_combination_performer_module.py \
-    --checkpoint_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/drug_combination/train_drug_combination_biomod.py \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --force_preprocess
 ```
 
@@ -109,8 +109,8 @@ python BioMod/drug_combination/train_drug_combination_performer_module.py \
 | Argument | Default | Description |
 | --- | --- | --- |
 | `--checkpoint_path` | Required | Path to the BioMod model weights |
-| `--hyper_params_path` | Required | Path to the PerformerModule hyper-parameter pkl file |
-| `--module_data_dir` | None | Directory containing module data files |
+| `--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` |
@@ -120,7 +120,7 @@ python BioMod/drug_combination/train_drug_combination_performer_module.py \
 | `--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 | PerformerModule pooling method (`mean`, `max`, or `concat`) |
+| `--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 |
 
@@ -130,7 +130,7 @@ Results are saved under `--output_dir` (default: `BioMod/drug_combination/result
 
 - `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 PerformerModule cell embeddings
+- `cell_emb_cache_{pool_method}.npy` - cached BioMod cell embeddings
 
 ## Evaluation Metrics
 

BioMod/drug_combination/{train_drug_combination_performer_module.py → train_drug_combination_biomod.py}

@@ -1,18 +1,18 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """
-Drug Combination Synergy Prediction with PerformerModule cell embeddings.
+Drug Combination Synergy Prediction with BioMod cell embeddings.
 
 Aligned with scLong/drug_combination (DeepDDs) architecture:
   - Drug branch: PyG GCNConv + global_max_pool (shared weights for drug1 & drug2)
-  - Cell branch: PerformerModule pretrained encoder -> MLP
+  - Cell branch: BioMod pretrained encoder -> MLP
   - Fusion: concat(drug1, drug2, cell) -> MLP -> 2-class classification
 
 Usage:
     # Run from the repository root.
-    python BioMod/drug_combination/train_drug_combination_performer_module.py \
+    python BioMod/drug_combination/train_drug_combination_biomod.py \
         --checkpoint_path <ckpt> --hyper_params_path <pkl> \
-        --module_data_dir model_dependencies/module_data_all \
+        --biomod_data_dir model_dependencies/biomod_data_all \
         --data_dir data/downstream/final_data/drug_combination_synergy/data_summary
 """
 
@@ -54,35 +54,35 @@
 
 # ===================== Path setup =====================
 SCRIPT_DIR = Path(__file__).resolve().parent
-PERFORMER_MODULE_ROOT = SCRIPT_DIR.parent
-SCLONG_ROOT = PERFORMER_MODULE_ROOT.parent
+BIOMOD_ROOT = SCRIPT_DIR.parent
+SCLONG_ROOT = BIOMOD_ROOT.parent
 
 REPO_ROOT = Path(__file__).resolve().parents[2]
 ASSET_DIR = REPO_ROOT / "model_dependencies"
 DOWNSTREAM_DATA_DIR = REPO_ROOT / "data" / "downstream" / "final_data"
-WEIGHTS_DIR = REPO_ROOT / "weight" / "0810model"
+WEIGHTS_DIR = REPO_ROOT / "weight"
 
-if str(PERFORMER_MODULE_ROOT) not in sys.path:
-    sys.path.insert(0, str(PERFORMER_MODULE_ROOT))
+if str(BIOMOD_ROOT) not in sys.path:
+    sys.path.insert(0, str(BIOMOD_ROOT))
 if str(SCLONG_ROOT) not in sys.path:
     sys.path.insert(0, str(SCLONG_ROOT))
 
 import importlib.util
 
-# Import PerformerModule model
-_models_path = os.path.join(PERFORMER_MODULE_ROOT, 'models_performer_module.py')
-_spec = importlib.util.spec_from_file_location("models_performer_module", _models_path)
+# Import BioMod model
+_models_path = os.path.join(BIOMOD_ROOT, 'models_biomod.py')
+_spec = importlib.util.spec_from_file_location("models_biomod", _models_path)
 _models_mod = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(_models_mod)
-PerformerEncoderOnly_Module = _models_mod.PerformerEncoderOnly_Module
-sanitize_performer_module_config = _models_mod.sanitize_performer_module_config
+BioMod = _models_mod.BioMod
+sanitize_biomod_config = _models_mod.sanitize_biomod_config
 
-# Import module_dataset
-_dataset_path = os.path.join(PERFORMER_MODULE_ROOT, 'module_dataset.py')
-_spec2 = importlib.util.spec_from_file_location("module_dataset", _dataset_path)
+# Import biomod_dataset
+_dataset_path = os.path.join(BIOMOD_ROOT, 'biomod_dataset.py')
+_spec2 = importlib.util.spec_from_file_location("biomod_dataset", _dataset_path)
 _module_mod = importlib.util.module_from_spec(_spec2)
 _spec2.loader.exec_module(_module_mod)
-load_module_data = _module_mod.load_module_data
+load_biomod_data = _module_mod.load_biomod_data
 
 
 # ===================== Utilities =====================
@@ -111,19 +111,19 @@ def reindex_tensor_universal(tensor, index_positions, dim, filler="0", device="c
     return reindexed
 
 
-# ===================== PerformerModule Loading =====================
+# ===================== BioMod Loading =====================
 
-def load_performer_module_model(
+def load_biomod_model(
     checkpoint_path, hyper_params_path, module_data_dir, module_data_path,
     gene_list_path, gene_mapping_path, gene2vec_path, device,
     shuffle_module_genes=False, shuffle_seed=2021,
 ):
-    print_sys(f"Loading PerformerModule model from: {checkpoint_path}")
+    print_sys(f"Loading BioMod model from: {checkpoint_path}")
 
     with open(hyper_params_path, 'rb') as f:
         model_params = pickle.load(f)
     model_params.pop('module_embed_chunk_padded_gene_budget', None)
-    model_params = sanitize_performer_module_config(
+    model_params = sanitize_biomod_config(
         model_params, source=hyper_params_path, log_fn=print_sys,
     )
 
@@ -133,7 +133,7 @@ def load_performer_module_model(
 
     if 'module_sets' not in model_params or model_params.get('module_sets') is None:
         if module_data_dir or module_data_path:
-            module_sets = load_module_data(
+            module_sets = load_biomod_data(
                 module_data_path=module_data_path,
                 module_data_dir=module_data_dir,
                 gene_list_path=gene_list_path,
@@ -143,8 +143,8 @@ def load_performer_module_model(
             model_params['module_sets'] = module_sets
         else:
             raise ValueError(
-                "Model needs module_sets but neither --module_data_dir "
-                "nor --module_data_path provided"
+                "Model needs module_sets but neither --biomod_data_dir "
+                "nor --biomod_data_path provided"
             )
 
     if shuffle_module_genes:
@@ -164,7 +164,7 @@ def load_performer_module_model(
         model_params['module_sets'] = shuffled_module_sets
         print_sys(f"Shuffled {len(all_gene_indices)} genes across {len(shuffled_module_sets)} modules")
 
-    model = PerformerEncoderOnly_Module(**model_params).to(device)
+    model = BioMod(**model_params).to(device)
 
     checkpoint = torch.load(checkpoint_path, map_location=device, weights_only=False)
     state_dict = checkpoint.get('model_state_dict', checkpoint)
@@ -173,7 +173,7 @@ def load_performer_module_model(
         if 'go_conv' not in k and 'G_go' not in k.lower()
     }
     model.load_state_dict(filtered, strict=True)
-    print_sys("Loaded pretrained PerformerModule weights.")
+    print_sys("Loaded pretrained BioMod weights.")
 
     model.eval()
     for p in model.parameters():
@@ -182,7 +182,7 @@ def load_performer_module_model(
     return model, len(model_params['module_sets']), model_params.get('base_dim', 1024)
 
 
-def build_performer_module_gene_mapping(symbol2ens_path, gene_list_path, expr_genes):
+def build_biomod_gene_mapping(symbol2ens_path, gene_list_path, expr_genes):
     gene2ens = pd.read_csv(symbol2ens_path, index_col=0)
     symbol2ens = gene2ens["Ensembl gene ID"].to_dict()
 
@@ -191,15 +191,15 @@ def build_performer_module_gene_mapping(symbol2ens_path, gene_list_path, expr_ge
     input_mapping = {gid: i for i, gid in enumerate(input_genes)}
 
     with open(gene_list_path, "r") as f:
-        performer_genes = [line.rstrip("\n") for line in f.readlines()]
-    performer_genes_pad = performer_genes + ["PAD"]
+        biomod_genes = [line.rstrip("\n") for line in f.readlines()]
+    biomod_genes_pad = biomod_genes + ["PAD"]
 
-    performer_index_positions = [
-        input_mapping.get(gid, input_gene_num) for gid in performer_genes_pad
+    biomod_index_positions = [
+        input_mapping.get(gid, input_gene_num) for gid in biomod_genes_pad
     ]
-    intersect = np.intersect1d(input_genes, performer_genes)
-    print_sys(f"Target and PerformerModule genes intersect: {len(intersect)}")
-    return input_mapping, performer_index_positions
+    intersect = np.intersect1d(input_genes, biomod_genes)
+    print_sys(f"Target and BioMod genes intersect: {len(intersect)}")
+    return input_mapping, biomod_index_positions
 
 
 def build_cell_embeddings(
@@ -208,14 +208,14 @@ def build_cell_embeddings(
     module_data_path, device, pool_method="mean",
     shuffle_module_genes=False, shuffle_seed=2021,
 ):
-    model, num_modules, encoder_embed_dim = load_performer_module_model(
+    model, num_modules, encoder_embed_dim = load_biomod_model(
         checkpoint_path, hyper_params_path, module_data_dir, module_data_path,
         gene_list_path, gene_mapping_path, gene2vec_path, device,
         shuffle_module_genes=shuffle_module_genes, shuffle_seed=shuffle_seed,
     )
 
     gene_columns = list(cell_features_df.columns)
-    _, performer_index_positions = build_performer_module_gene_mapping(
+    _, biomod_index_positions = build_biomod_gene_mapping(
         symbol2ens_path, gene_list_path, gene_columns,
     )
 
@@ -225,10 +225,10 @@ def build_cell_embeddings(
     with torch.no_grad():
         for cell_line_id, row in cell_features_df.iterrows():
             x = torch.tensor(row.values[None, :], dtype=torch.float32, device=device)
-            x_performer = reindex_tensor_universal(
-                x, performer_index_positions, dim=1, filler="0", device=device,
+            x_biomod = reindex_tensor_universal(
+                x, biomod_index_positions, dim=1, filler="0", device=device,
             )
-            out = model(x_performer, mask_ratio=0.0, return_encodings=True)
+            out = model(x_biomod, mask_ratio=0.0, return_encodings=True)
 
             if 'module_encodings' in out:
                 module_enc = out['module_encodings']
@@ -251,7 +251,7 @@ def build_cell_embeddings(
                 first_emb_dim = cell_emb_np.shape[0]
 
     print_sys(
-        f"Built PerformerModule embeddings for {len(cell_emb_dict)} cell lines, "
+        f"Built BioMod embeddings for {len(cell_emb_dict)} cell lines, "
         f"dim={first_emb_dim}, pool_method={pool_method}"
     )
     return cell_emb_dict, first_emb_dim
@@ -319,7 +319,7 @@ class TestbedDataset(InMemoryDataset):
     """
     PyG InMemoryDataset for drug combination prediction.
     Same pattern as scLong/drug_combination/utils_test.py::TestbedDataset,
-    but uses PerformerModule cell embeddings instead of scfm/geneformer.
+    but uses BioMod cell embeddings instead of scfm/geneformer.
     """
 
     def __init__(
@@ -412,7 +412,7 @@ class GCNNet(torch.nn.Module):
 
     Drug branch: 3-layer GCNConv (78->78->156->312) + global_max_pool + 2 FC layers
     Drug1 and drug2 share weights (drug2 uses drug1_conv* layers, same as scLong).
-    Cell branch: PerformerModule embedding -> MLP -> output_dim
+    Cell branch: BioMod embedding -> MLP -> output_dim
     Fusion: concat(drug1, drug2, cell) -> fc1(256) -> fc2(128) -> out(2)
     """
 
@@ -432,7 +432,7 @@ def __init__(
         self.drug1_fc_g1 = nn.Linear(num_features_xd * 4, num_features_xd * 2)
         self.drug1_fc_g2 = nn.Linear(num_features_xd * 2, output_dim)
 
-        # Cell branch (PerformerModule embedding -> MLP)
+        # Cell branch (BioMod embedding -> MLP)
         self.reduction = nn.Sequential(
             nn.Linear(cell_emb_dim, 512),
             nn.ReLU(),
@@ -584,18 +584,18 @@ def load_cell_features(cell_file):
 
 def main():
     parser = argparse.ArgumentParser(
-        description='Drug Combination Synergy Prediction with PerformerModule'
+        description='Drug Combination Synergy Prediction with BioMod'
     )
 
-    # PerformerModule model args
+    # BioMod model args
     parser.add_argument('--checkpoint_path', type=str, required=True,
-                        help='Path to PerformerModule pretrained checkpoint')
+                        help='Path to BioMod pretrained checkpoint')
     parser.add_argument('--hyper_params_path', type=str, required=True,
-                        help='Path to PerformerModule hyper parameters pkl')
-    parser.add_argument('--module_data_dir', type=str, default=None,
-                        help='Directory containing module data files')
-    parser.add_argument('--module_data_path', type=str, default=None,
-                        help='Path to single module data file')
+                        help='Path to BioMod hyper parameters pkl')
+    parser.add_argument('--biomod_data_dir', '--module_data_dir', type=str, default=None,
+                        help='Directory containing module data files', dest='module_data_dir')
+    parser.add_argument('--biomod_data_path', '--module_data_path', type=str, default=None,
+                        help='Path to single module data file', dest='module_data_path')
     parser.add_argument('--gene_list_path', type=str,
                         default=str(ASSET_DIR / 'selected_genes_27k.txt'))
     parser.add_argument('--gene_mapping_path', type=str,
@@ -606,8 +606,8 @@ def main():
                         default=str(ASSET_DIR / 'gene2ens.csv'))
     parser.add_argument('--pool_method', type=str, default='mean',
                         choices=['mean', 'max', 'concat'])
-    parser.add_argument('--shuffle_module_genes', action='store_true',
-                        help='Disrupt the gene allocation within the module (used for comparative experiments to verify the effectiveness of module division)')
+    parser.add_argument('--shuffle_biomod_genes', '--shuffle_module_genes', action='store_true',
+                        help='Disrupt the gene allocation within the module (used for comparative experiments to verify the effectiveness of module division)', dest='shuffle_module_genes')
     parser.add_argument('--shuffle_seed', type=int, default=2021,
                         help='The random seed used when scrambling the module gene (needs to be consistent with the value used during pre-training)')
 
@@ -638,7 +638,7 @@ def main():
                         default=os.path.join(SCRIPT_DIR, 'results'))
     parser.add_argument('--seed', type=int, default=42)
     parser.add_argument('--cache_emb', action='store_true', default=True,
-                        help='Cache PerformerModule cell embeddings to .npy')
+                        help='Cache BioMod cell embeddings to .npy')
     parser.add_argument('--no_cache_emb', dest='cache_emb', action='store_false')
     parser.add_argument('--force_preprocess', action='store_true', default=False,
                         help='Force re-creation of PyG .pt datasets')
@@ -656,7 +656,7 @@ def main():
 
     os.makedirs(args.output_dir, exist_ok=True)
 
-    # -------- Step 1: Build PerformerModule cell embeddings --------
+    # -------- Step 1: Build BioMod cell embeddings --------
     train_cell_file = os.path.join(args.data_dir, args.cell_file)
     train_cell_df = load_cell_features(train_cell_file)
     print_sys(f'Loaded train cell features: {train_cell_df.shape}')
@@ -737,12 +737,12 @@ def main():
     labels_train = train_labels['label'].tolist()
 
     train_d1_dataset = TestbedDataset(
-        root=args.data_dir, dataset='train_drug1_performer_module',
+        root=args.data_dir, dataset='train_drug1_biomod',
         xd=drug1_train, xt=cells_train, y=labels_train,
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )
     train_d2_dataset = TestbedDataset(
-        root=args.data_dir, dataset='train_drug2_performer_module',
+        root=args.data_dir, dataset='train_drug2_biomod',
         xd=drug2_train, xt=cells_train, y=labels_train,
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )
@@ -755,12 +755,12 @@ def main():
     labels_validation = validation_labels['label'].tolist()
 
     validation_d1_dataset = TestbedDataset(
-        root=args.data_dir, dataset='test_drug1_performer_module',
+        root=args.data_dir, dataset='test_drug1_biomod',
         xd=drug1_validation, xt=cells_validation, y=labels_validation,
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )
     validation_d2_dataset = TestbedDataset(
-        root=args.data_dir, dataset='test_drug2_performer_module',
+        root=args.data_dir, dataset='test_drug2_biomod',
         xd=drug2_validation, xt=cells_validation, y=labels_validation,
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )

BioMod/drug_response/cmd.txt

@@ -1,10 +1,10 @@
 # Run from the repository root.
-python BioMod/drug_response/train_drug_performer_module.py \
+python BioMod/drug_response/train_drug_biomod.py \
     --gpu_id 0 \
     --data_path data/downstream/final_data/single_drug_response/data \
-    --checkpoint_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl \
+    --checkpoint_path weight/BioMod.pth \
+    --hyper_params_path weight/BioMod.pkl \
     --epochs 300 \
-    --module_data_dir model_dependencies/module_data_all \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --save_dir tutorial_runs/drug_response \
     --pool_method max

BioMod/drug_response/{train_drug_performer_module.py → train_drug_biomod.py}

@@ -1,20 +1,20 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 """
-Drug response prediction: using drug molecular structure + PerformerModule cell embedding
+Drug response prediction: using drug molecular structure + BioMod cell embedding
 
 Architecture:
 - Drug branch: 3-layer GCN + residual connection + double pooling
-- Cell branch: extract module-level features from pre-trained PerformerModule
+- Cell branch: extract module-level features from pre-trained BioMod
 - Fusion layer: attention mechanism + deep MLP
 - Optimization strategy: AdamW + cosine annealing + early stopping
 
 How to use:
     # Run from the repository root; see drug_response/cmd.txt for a full example.
-    python BioMod/drug_response/train_drug_performer_module.py \
+    python BioMod/drug_response/train_drug_biomod.py \
         --gpu_id 0 --epochs 300 \
-        --checkpoint_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-        --hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl
+        --checkpoint_path weight/BioMod.pth \
+        --hyper_params_path weight/BioMod.pkl
 """
 
 import argparse
@@ -27,7 +27,7 @@
 REPO_ROOT = Path(__file__).resolve().parents[2]
 ASSET_DIR = REPO_ROOT / "model_dependencies"
 DOWNSTREAM_DATA_DIR = REPO_ROOT / "data" / "downstream" / "final_data"
-WEIGHTS_DIR = REPO_ROOT / "weight" / "0810model"
+WEIGHTS_DIR = REPO_ROOT / "weight"
 from typing import Dict, List, Tuple, Union, Optional
 
 import hickle as hkl
@@ -39,7 +39,7 @@
 from scipy.stats import pearsonr
 from torch.utils.data import DataLoader, Dataset
 
-# Import PerformerModule model
+# Import BioMod model
 project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if project_root not in sys.path:
     sys.path.insert(0, project_root)
@@ -47,26 +47,26 @@
 
 # Use direct path import to avoid conflicts with files with the same name
 import importlib.util
-performer_module_dir = project_root
+biomod_dir = project_root
 
-# import models_performer_module
-models_path = os.path.join(performer_module_dir, 'models_performer_module.py')
+# import models_biomod
+models_path = os.path.join(biomod_dir, 'models_biomod.py')
 if not os.path.exists(models_path):
     raise FileNotFoundError(f"Model file not found: {models_path}")
-spec = importlib.util.spec_from_file_location("models_performer_module", models_path)
-models_performer_module = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(models_performer_module)
-PerformerEncoderOnly_Module = models_performer_module.PerformerEncoderOnly_Module
-sanitize_performer_module_config = models_performer_module.sanitize_performer_module_config
-
-# Import module_dataset
-dataset_path = os.path.join(performer_module_dir, 'module_dataset.py')
+spec = importlib.util.spec_from_file_location("models_biomod", models_path)
+models_biomod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(models_biomod)
+BioMod = models_biomod.BioMod
+sanitize_biomod_config = models_biomod.sanitize_biomod_config
+
+# Import biomod_dataset
+dataset_path = os.path.join(biomod_dir, 'biomod_dataset.py')
 if not os.path.exists(dataset_path):
     raise FileNotFoundError(f"Dataset file not found: {dataset_path}")
-spec = importlib.util.spec_from_file_location("module_dataset", dataset_path)
-module_dataset_module = importlib.util.module_from_spec(spec)
-spec.loader.exec_module(module_dataset_module)
-load_module_data = module_dataset_module.load_module_data
+spec = importlib.util.spec_from_file_location("biomod_dataset", dataset_path)
+biomod_dataset_module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(biomod_dataset_module)
+load_biomod_data = biomod_dataset_module.load_biomod_data
 
 
 # ===================== Utility functions =====================
@@ -105,9 +105,9 @@ def reindex_tensor_universal(
     return reindexed
 
 
-# ===================== PerformerModule related =====================
+# ===================== BioMod related =====================
 
-def load_performer_module_model(
+def load_biomod_model(
     checkpoint_path: str,
     hyper_params_path: str,
     module_data_dir: Optional[str],
@@ -118,16 +118,16 @@ def load_performer_module_model(
     device: torch.device,
     shuffle_module_genes: bool = False,
     seed: int = 0,
-) -> PerformerEncoderOnly_Module:
-    """Load a pretrained PerformerModule model"""
-    print_sys(f"Loading PerformerModule model from: {checkpoint_path}")
+) -> BioMod:
+    """Load a pretrained BioMod model"""
+    print_sys(f"Loading BioMod model from: {checkpoint_path}")
 
     # Load model hyperparameters
     print_sys(f"Loading hyper parameters from: {hyper_params_path}")
     with open(hyper_params_path, 'rb') as f:
         model_params = pickle.load(f)
     model_params.pop('module_embed_chunk_padded_gene_budget', None)
-    model_params = sanitize_performer_module_config(
+    model_params = sanitize_biomod_config(
         model_params,
         source=hyper_params_path,
         log_fn=print_sys,
@@ -150,7 +150,7 @@ def load_performer_module_model(
     if 'module_sets' not in model_params or model_params.get('module_sets') is None:
         if module_data_dir or module_data_path:
             print_sys("Loading module data...")
-            module_sets = load_module_data(
+            module_sets = load_biomod_data(
                 module_data_path=module_data_path,
                 module_data_dir=module_data_dir,
                 gene_list_path=gene_list_path,
@@ -159,7 +159,7 @@ def load_performer_module_model(
             )
             model_params['module_sets'] = module_sets
         else:
-            raise ValueError("Model requires module_sets, but --module_data_dir or --module_data_path was not provided")
+            raise ValueError("Model requires module_sets, but --biomod_data_dir or --biomod_data_path was not provided")
     else:
         module_sets = model_params['module_sets']
         print_sys(f"Using module_sets from hyper parameters ({len(module_sets)} modules)")
@@ -191,11 +191,11 @@ def load_performer_module_model(
         model_params['module_sets'] = module_sets
         print_sys(f"Shuffled {len(all_gene_indices)} genes across {len(module_sets)} modules")
 
-    print_sys(f"PerformerModule config: base_dim={model_params.get('base_dim', 'N/A')}, "
+    print_sys(f"BioMod config: base_dim={model_params.get('base_dim', 'N/A')}, "
               f"num_modules={len(module_sets)}")
     
     # Build model
-    model = PerformerEncoderOnly_Module(**model_params).to(device)
+    model = BioMod(**model_params).to(device)
     
     # Load weights
     print_sys(f"Loading checkpoint from: {checkpoint_path}")
@@ -216,7 +216,7 @@ def load_performer_module_model(
     # Use strict=True to ensure the weights match exactly (except for filtered GO parameters)
     model.load_state_dict(filtered_state_dict, strict=True)
     
-    print_sys("Loaded pretrained PerformerModule weights.")
+    print_sys("Loaded pretrained BioMod weights.")
     
     # freeze model
     model.eval()
@@ -226,7 +226,7 @@ def load_performer_module_model(
     return model, len(module_sets), model_params.get('base_dim', 1024)
 
 
-def build_performer_module_gene_mapping(
+def build_biomod_gene_mapping(
     symbol2ens_path: str,
     gene_list_path: str,
     expr_genes: List[str],
@@ -240,18 +240,18 @@ def build_performer_module_gene_mapping(
     input_mapping = {gid: i for i, gid in enumerate(input_genes)}
 
     with open(gene_list_path, "r") as f:
-        performer_genes = [line.rstrip("\n") for line in f.readlines()]
-    performer_genes_pad = performer_genes + ["PAD"]
+        biomod_genes = [line.rstrip("\n") for line in f.readlines()]
+    biomod_genes_pad = biomod_genes + ["PAD"]
 
-    performer_index_positions = [
-        input_mapping.get(gid, input_gene_num) for gid in performer_genes_pad
+    biomod_index_positions = [
+        input_mapping.get(gid, input_gene_num) for gid in biomod_genes_pad
     ]
-    intersect = np.intersect1d(input_genes, performer_genes)
-    print_sys(f"Target and PerformerModule genes intersect: {len(intersect)}")
-    return input_mapping, performer_index_positions
+    intersect = np.intersect1d(input_genes, biomod_genes)
+    print_sys(f"Target and BioMod genes intersect: {len(intersect)}")
+    return input_mapping, biomod_index_positions
 
 
-def build_cell_embeddings_with_performer_module(
+def build_cell_embeddings_with_biomod(
     gexpr_feature: pd.DataFrame,
     symbol2ens_path: str,
     gene_list_path: str,
@@ -267,7 +267,7 @@ def build_cell_embeddings_with_performer_module(
     seed: int = 0,
 ) -> Tuple[Dict[str, np.ndarray], int]:
     """
-    Use PerformerModule to construct embedding for each cell line
+    Use BioMod to construct embedding for each cell line
 
     Args:
         pool_method: pooling method, 'mean', 'max', 'cls', or 'concat'
@@ -277,7 +277,7 @@ def build_cell_embeddings_with_performer_module(
             - 'concat': concatenate all modules (the dimension will be very large)
         use_gene2vec: automatically restored by pre-trained PKL, no longer covered downstream
     """
-    model, num_modules, encoder_embed_dim = load_performer_module_model(
+    model, num_modules, encoder_embed_dim = load_biomod_model(
         checkpoint_path=checkpoint_path,
         hyper_params_path=hyper_params_path,
         module_data_dir=module_data_dir,
@@ -290,7 +290,7 @@ def build_cell_embeddings_with_performer_module(
         seed=seed,
     )
 
-    _, performer_index_positions = build_performer_module_gene_mapping(
+    _, biomod_index_positions = build_biomod_gene_mapping(
         symbol2ens_path=symbol2ens_path,
         gene_list_path=gene_list_path,
         expr_genes=list(gexpr_feature.columns),
@@ -302,12 +302,12 @@ def build_cell_embeddings_with_performer_module(
     with torch.no_grad():
         for cell_line_id, row in gexpr_feature.iterrows():
             x = torch.tensor(row.values[None, :], dtype=torch.float32, device=device)
-            x_performer = reindex_tensor_universal(
-                x, performer_index_positions, dim=1, filler="0", device=device
+            x_biomod = reindex_tensor_universal(
+                x, biomod_index_positions, dim=1, filler="0", device=device
             )
 
             # Extract features through encoder (without masking, mask_ratio=0.0)
-            out = model(x_performer, mask_ratio=0.0, return_encodings=True)
+            out = model(x_biomod, mask_ratio=0.0, return_encodings=True)
             
             # Extract module encodings
             if 'module_encodings' in out:
@@ -318,7 +318,7 @@ def build_cell_embeddings_with_performer_module(
                     if model.use_cls:
                         # Use CLS token (in latent, but module_encodings does not contain CLS)
                         # Need to get the complete latent from forward_encoder
-                        enc_out = model.forward_encoder(x_performer, mask_ratio=0.0)
+                        enc_out = model.forward_encoder(x_biomod, mask_ratio=0.0)
                         latent = enc_out[0]
                         if model.use_cls:
                             cell_emb = latent[:, 0, :]  # (1, encoder_embed_dim)
@@ -345,7 +345,7 @@ def build_cell_embeddings_with_performer_module(
                 first_emb_dim = cell_emb_np.shape[0]
 
     print_sys(
-        f"Built PerformerModule embeddings for {len(cell_emb_dict)} cell lines, "
+        f"Built BioMod embeddings for {len(cell_emb_dict)} cell lines, "
         f"dim={first_emb_dim}, pool_method={pool_method}"
     )
     return cell_emb_dict, first_emb_dim
@@ -525,8 +525,8 @@ def feature_extract(
 
 # ===================== Dataset =====================
 
-class DrugPerformerModuleDataset(Dataset):
-    """Drug + PerformerModule Dataset"""
+class DrugBioModDataset(Dataset):
+    """Drug + BioMod Dataset"""
 
     def __init__(
         self,
@@ -550,7 +550,7 @@ def __getitem__(self, idx: int):
         drug_feat = torch.from_numpy(feat).float()
         drug_adj = torch.from_numpy(adj).float()
 
-        # PerformerModule cell embedding
+        # BioMod cell embedding
         cell_line_id = self.index_list[idx][0]
         cell_emb_np = self.cell_emb_dict[cell_line_id]
         cell_emb = torch.from_numpy(cell_emb_np).float()
@@ -595,13 +595,13 @@ def forward(self, x: torch.Tensor, adj: torch.Tensor) -> torch.Tensor:
         return out
 
 
-class DrugPerformerModuleModel(nn.Module):
+class DrugBioModModel(nn.Module):
     """
-    Drugs + PerformerModule Predictive Model
+    Drugs + BioMod Predictive Model
     
     Architecture:
     - Drug branch: 3-layer GraphConv + residual connection + double pooling
-    - Cell branch: 2-layer MLP (processing PerformerModule module embeddings)
+    - Cell branch: 2-layer MLP (processing BioMod module embeddings)
     - Fusion layer: 4-layer MLP + attention mechanism
     """
 
@@ -624,7 +624,7 @@ def __init__(
         self.drug_bn2 = nn.BatchNorm1d(256)
         self.drug_bn3 = nn.BatchNorm1d(128)
 
-        # Cell branch: 2-layer MLP (processing PerformerModule embeddings)
+        # Cell branch: 2-layer MLP (processing BioMod embeddings)
         self.cell_fc1 = nn.Linear(cell_emb_dim, 256)
         self.cell_bn1 = nn.BatchNorm1d(256)
         self.cell_fc2 = nn.Linear(256, 128)
@@ -689,7 +689,7 @@ def forward(
         x_drug_mean = x_drug.mean(dim=1)   # (B, 128)
         x_drug = x_drug_max + x_drug_mean  # Fusion
 
-        # Cell branching (handling PerformerModule embeddings)
+        # Cell branching (handling BioMod embeddings)
         x_cell = self.cell_fc1(cell_emb)  # (B, 256)
         x_cell = self.cell_bn1(x_cell)
         x_cell = self.relu(x_cell)
@@ -783,7 +783,7 @@ def eval_epoch(model, loader, device):
 
 def main():
     parser = argparse.ArgumentParser(
-        description="Drug response prediction using Drug + PerformerModule"
+        description="Drug response prediction using Drug + BioMod"
     )
     parser.add_argument("--gpu_id", type=str, default="0")
     parser.add_argument("--data_path", type=str, default=str(DOWNSTREAM_DATA_DIR / "single_drug_response" / "data"))
@@ -795,31 +795,31 @@ def main():
     parser.add_argument("--dropout", type=float, default=0.1)
     parser.add_argument("--patience", type=int, default=30)
 
-    # PerformerModule related paths
+    # BioMod related paths
     parser.add_argument(
         "--checkpoint_path",
         type=str,
         required=True,
-        help="Path to pre-trained PerformerModule checkpoint"
+        help="Path to pre-trained BioMod checkpoint"
     )
     parser.add_argument(
         "--hyper_params_path",
         type=str,
         required=True,
-        help="Path to PerformerModule model hyper parameters pkl file"
+        help="Path to BioMod model hyper parameters pkl file"
     )
     parser.add_argument(
-        "--module_data_dir",
+        "--biomod_data_dir", "--module_data_dir",
         type=str,
         default=None,
         help="Directory containing module JSON files"
-    )
+    , dest='module_data_dir')
     parser.add_argument(
-        "--module_data_path",
+        "--biomod_data_path", "--module_data_path",
         type=str,
         default=None,
         help="Path to module JSON file (single file)"
-    )
+    , dest='module_data_path')
     parser.add_argument(
         "--gene_list_path",
         type=str,
@@ -849,25 +849,25 @@ def main():
         type=str,
         default="mean",
         choices=["mean", "max", "cls", "concat"],
-        help="Pooling method for PerformerModule module embeddings"
+        help="Pooling method for BioMod module embeddings"
     )
     parser.add_argument(
-        "--shuffle_module_genes",
+        "--shuffle_biomod_genes", "--shuffle_module_genes",
         action="store_true",
         help="Optional downstream-only extra reshuffle on top of module_sets restored from PKL. "
              "Do not pass this when reproducing the pretrained backbone as-is."
-    )
+    , dest='shuffle_module_genes')
     parser.add_argument(
         "--shuffle_seed",
         type=int,
         default=2021,
-        help="Random seed for the downstream extra reshuffle when --shuffle_module_genes is enabled."
+        help="Random seed for the downstream extra reshuffle when --shuffle_biomod_genes is enabled."
     )
     # Output path
     parser.add_argument(
         "--save_dir",
         type=str,
-        default="./models_drug_performer_module",
+        default="./models_drug_biomod",
         help="Directory to save the model"
     )
 
@@ -877,7 +877,7 @@ def main():
     device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 
     print_sys("=" * 70)
-    print_sys("Drug Response Prediction: Drug + PerformerModule")
+    print_sys("Drug Response Prediction: Drug + BioMod")
     print_sys("=" * 70)
     print_sys(f"Device: {device}")
     print_sys(f"Epochs: {args.epochs}")
@@ -916,9 +916,9 @@ def main():
         gene_expression_file,
     )
 
-    # 2) Build PerformerModule embeddings
-    print_sys("\n[Step 2/6] Building PerformerModule embeddings...")
-    cell_emb_dict, cell_emb_dim = build_cell_embeddings_with_performer_module( # cell_emb_dict │ Dict[str, np.ndarray] │ {cell_line_id: embedding} mapping dictionary
+    # 2) Build BioMod embeddings
+    print_sys("\n[Step 2/6] Building BioMod embeddings...")
+    cell_emb_dict, cell_emb_dim = build_cell_embeddings_with_biomod( # cell_emb_dict │ Dict[str, np.ndarray] │ {cell_line_id: embedding} mapping dictionary
         gexpr_feature=gexpr_feature,
         symbol2ens_path=args.symbol2ens_path,
         gene_list_path=args.gene_list_path,
@@ -950,10 +950,10 @@ def main():
 
     # 5) Build a data set
     print_sys("\n[Step 5/6] Creating datasets...")
-    train_ds = DrugPerformerModuleDataset(
+    train_ds = DrugBioModDataset(
         X_drug_train, Y_train, train_index_list, cell_emb_dict
     )
-    validation_ds = DrugPerformerModuleDataset(
+    validation_ds = DrugBioModDataset(
         X_drug_validation, Y_validation, validation_index_list, cell_emb_dict
     )
 
@@ -977,7 +977,7 @@ def main():
 
     # 6) Build the model
     print_sys("\n[Step 6/6] Building model...")
-    model = DrugPerformerModuleModel(
+    model = DrugBioModModel(
         drug_feat_dim=drug_dim,
         cell_emb_dim=cell_emb_dim,
         hidden_dim=args.hidden_dim,

BioMod/environment.yml

@@ -1,4 +1,4 @@
-name: performer_module
+name: biomod
 channels:
   - pytorch
   - nvidia
@@ -45,7 +45,7 @@ dependencies:
   - rdkit
 
   - pip:
-      # PerformerModule model utilities
+      # BioMod model utilities
       - einops==0.8.1
       - local-attention==1.11.2
       - hickle>=5.0.0

BioMod/gene_perturbation/README.md

@@ -1,14 +1,14 @@
 # Gene Perturbation Prediction with BioMod
 
 This document describes the BioMod gene perturbation workflow (GEARS), using
-the `PerformerEncoderOnly_Module` encoder. The
+the `BioMod` encoder. The
 [BioMod model weights and matching configuration](../../README.md#biomod-model-weights)
 are shared with the other downstream tasks.
 
 ## Overview
 
 This adaptation replaces the original GEARS gene perturbation model based on
-`DualEncoderSCFM` with `PerformerEncoderOnly_Module`. The main adaptation points
+`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.
@@ -17,12 +17,12 @@ are:
 
 ## Main Adaptations
 
-### 1. `SCFM_Module` (`model_module.py`)
+### 1. `SCFM_BioMod` (`model_biomod.py`)
 
-`SCFM_Module` wraps `PerformerEncoderOnly_Module` and provides these functions:
+`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 `PerformerEncoderOnly_Module`.
+- **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.
@@ -42,22 +42,22 @@ for gene_idx in range(len(self.scfm_index_positions) - 1):
         gene_emb = module_encodings.mean(dim=1)  # B, D (global average)
 ```
 
-### 2. `GEARS_Model_Module` (`model_module.py`)
+### 2. `GEARS_Model_BioMod` (`model_biomod.py`)
 
-`GEARS_Model_Module` inherits the original GEARS architecture. Main changes:
+`GEARS_Model_BioMod` inherits the original GEARS architecture. Main changes:
 
-- **Use `SCFM_Module`** instead of the original `SCFM_different_genes`.
+- **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_module.py`)
+### 3. Training Script (`train_biomod.py`)
 
 The training script is based on `GEARS/train_dual_ddp_reduce_dec.py`. Main changes:
 
-- **Model class**: use `GEARS_Model_Module` instead of `GEARS_Model_Acc`.
+- **Model class**: use `GEARS_Model_BioMod` instead of `GEARS_Model_Acc`.
 - **New arguments**:
-  - `--module_data_path`: path to one module JSON file.
-  - `--module_data_dir`: directory containing module JSON files.
+  - `--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
@@ -78,12 +78,12 @@ Run from the repository root in a Linux CUDA/NCCL environment. Built-in asset de
 ```bash
 # DDP training on multiple GPUs.
 python -m torch.distributed.run --standalone --nproc_per_node=4 \
-    BioMod/gene_perturbation/train_module.py \
+    BioMod/gene_perturbation/train_biomod.py \
     --data_dir data/downstream/final_data \
     --data_name norman \
-    --scfm_hyper_params_path weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --scfm_ckpt_path weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --module_data_dir model_dependencies/module_data_all \
+    --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 \
@@ -100,7 +100,7 @@ python -m torch.distributed.run --standalone --nproc_per_node=4 \
 
 - `--scfm_hyper_params_path`: path to the BioMod model configuration file.
 - `--scfm_ckpt_path`: path to the BioMod model weights.
-- `--module_data_path` or `--module_data_dir`: required only when the model configuration does not already contain module definitions.
+- `--biomod_data_path` or `--biomod_data_dir`: required only when the model configuration does not already contain module definitions.
 
 **Recommended arguments**:
 
@@ -110,7 +110,7 @@ python -m torch.distributed.run --standalone --nproc_per_node=4 \
 
 **Optional arguments**:
 
-- `--use_module_level`: use module-level features. This is experimental and is not fully supported at the moment.
+- `--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
@@ -119,7 +119,7 @@ python -m torch.distributed.run --standalone --nproc_per_node=4 \
 
 1. **Model architecture**:
    - **Original sclong**: uses `DualEncoderSCFM` and directly processes gene sequences.
-   - **Module version**: uses `PerformerEncoderOnly_Module` and processes module-based data.
+   - **Module version**: uses `BioMod` and processes module-based data.
 
 2. **Data representation**:
    - **Original sclong**: gene-level embeddings come directly from encoder outputs.
@@ -144,7 +144,7 @@ To compare model performance:
 
    ```bash
    # Run from the BioMod repository root.
-   python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_perturbation/train_module.py [arguments...]
+   python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_perturbation/train_biomod.py [arguments...]
    ```
 
 3. **Compare metrics**:
@@ -161,7 +161,7 @@ module version.
 
 ### Module-to-Gene Mapping
 
-In `SCFM_Module`, `gene_to_modules` records which modules contain each gene:
+In `SCFM_BioMod`, `gene_to_modules` records which modules contain each gene:
 
 ```python
 self.gene_to_modules = {}  # {gene_idx: [module_idx1, module_idx2, ...]}
@@ -193,11 +193,11 @@ BioMod/gene_perturbation/                                # Perturbation response
 ├── data_utils_local.py
 ├── gears_reduce_local.py
 ├── inference_local.py
-├── model_module.py
+├── model_biomod.py
 ├── pertdata_local.py
 ├── README.md
 ├── scfm_utils_local.py
-├── train_module.py
+├── train_biomod.py
 └── utils.py
 ```
 
@@ -212,7 +212,7 @@ BioMod/gene_perturbation/                                # Perturbation response
 
 ### Issue 1: Module Data Not Found
 
-- Check whether `--module_data_path` or `--module_data_dir` is correct.
+- 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
@@ -228,13 +228,13 @@ BioMod/gene_perturbation/                                # Perturbation response
 ## Gene-Based vs Module-Based Methods
 
 This implementation supports two feature extraction modes controlled by
-`--use_module_level`.
+`--use_biomod_level`.
 
 ### Method 1: Gene-Based (Default, Recommended)
 
 ```bash
-# Default mode; do not pass --use_module_level or set it to False.
-python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_perturbation/train_module.py [other arguments...]
+# Default mode; do not pass --use_biomod_level or set it to False.
+python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_perturbation/train_biomod.py [other arguments...]
 ```
 
 **Characteristics**:
@@ -248,7 +248,7 @@ python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_pert
 
 ```bash
 # Enable module-level mode.
-python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_perturbation/train_module.py --use_module_level [other arguments...]
+python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_perturbation/train_biomod.py --use_biomod_level [other arguments...]
 ```
 
 **Characteristics**:
@@ -262,8 +262,8 @@ python -m torch.distributed.run --standalone --nproc_per_node=1 BioMod/gene_pert
 ## References
 
 - Original GEARS code is an external reference and is not included in this source directory.
-- PerformerEncoderOnly_Module model: `BioMod/models_performer_module.py`
-- Module data processing: `BioMod/module_dataset.py`
+- BioMod model: `BioMod/models_biomod.py`
+- Module data processing: `BioMod/biomod_dataset.py`
 
 ## Optional external annotation resources
 

BioMod/gene_perturbation/gears_reduce_local.py

@@ -46,7 +46,7 @@
 # ============================================================
 # Use native modules (optimized versions)
 # ============================================================
-from model_module import GEARS_Model_Module
+from model_biomod import GEARS_Model_BioMod
 from inference_local import evaluate, compute_metrics, deeper_analysis, \
                   non_dropout_analysis, compute_synergy_loss
 from utils import loss_fct, uncertainty_loss_fct, parse_any_pert, \
@@ -74,7 +74,7 @@ class GEARS:
     [Usage process]
     ```python
     gears = GEARS(pert_data, local_rank, is_master, world_size, ...)
-    gears.model_initialize(hidden_size=64, model_class=GEARS_Model_Module, ...)
+    gears.model_initialize(hidden_size=64, model_class=GEARS_Model_BioMod, ...)
     gears.train(epochs=20, result_dir='./results', lr=1e-3)
     ```
     """

BioMod/gene_perturbation/{model_module.py → model_biomod.py}

@@ -1,24 +1,24 @@
 """
 ================================================================================
-Genetic perturbation task model definition (model_module.py)
+Genetic perturbation task model definition (model_biomod.py)
 ================================================================================
 
 [Model Architecture Overview]
 This document implements a deep learning model for genetic perturbation prediction. The core components include:
 
-1. ModuleEmbedding: Convert gene-level expression values into module-level tokens
+1. BioModEmbedding: Convert gene-level expression values into module-level tokens
    - Supports multiple integration methods (multiply/add/gated_residual)
    - Use attention pooling to aggregate genetic information within the module
 
-2. PerformerEncoderOnly_Module: Encoder-only Transformer model
+2. BioMod: Encoder-only Transformer model
    - Use Performer (Linear Complexity Attention) to process large numbers of module tokens
    - Support Masked Autoencoder (MAE) pre-training paradigm
 
-3. SCFM_Module: wrapper for pre-trained models
+3. SCFM_BioMod: wrapper for pre-trained models
    - Process the mapping of input genes to pre-trained model genes
    - Recover gene-level embeddings from module encoding
 
-4. GEARS_Model_Module: Genetic perturbation prediction model
+4. GEARS_Model_BioMod: Genetic perturbation prediction model
    - Integrate pre-trained encoder + GNN + decoder
    - Predict expression changes after gene perturbation
 
@@ -49,19 +49,19 @@
 # Performer is a linear complexity Transformer variant suitable for processing long sequences
 # ============================================================
 try:
-    from BioMod.models_performer_module import (
-        ModuleEmbedding,
-        PerformerEncoderOnly_Module,
-        sanitize_performer_module_config,
+    from BioMod.models_biomod import (
+        BioModEmbedding,
+        BioMod,
+        sanitize_biomod_config,
     )
 except ModuleNotFoundError:
     project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
     if project_root not in sys.path:
         sys.path.insert(0, project_root)
-    from BioMod.models_performer_module import (
-        ModuleEmbedding,
-        PerformerEncoderOnly_Module,
-        sanitize_performer_module_config,
+    from BioMod.models_biomod import (
+        BioModEmbedding,
+        BioMod,
+        sanitize_biomod_config,
     )
 
 # ============================================================
@@ -114,13 +114,13 @@ def reindex_tensor_universal(tensor, index_positions, dim, filler='0', device='c
     return reindexed
 
 
-class SCFM_Module(torch.nn.Module):
+class SCFM_BioMod(torch.nn.Module):
     """
     ================================================================================
-    SCFM_Module: wrapper for pre-trained single cell base models
+    SCFM_BioMod: wrapper for pre-trained single cell base models
 
     [Core functions]
-    Adapt the PerformerEncoderOnly_Module model to the genetic perturbation task to address the following key issues:
+    Adapt the BioMod model to the genetic perturbation task to address the following key issues:
 
     1. Gene mapping: The gene order of the input data may be different from that of the pre-trained model, and re-indexing is required.
     2. Module-to-gene recovery: Recovering gene-level embeddings from module encodings
@@ -150,7 +150,7 @@ def __init__(self, input_genes, scfm_genes,
                  device='cpu',
                  output_dim=200,
                  use_module_level=False):
-        super(SCFM_Module, self).__init__()
+        super(SCFM_BioMod, self).__init__()
         self.device = device
         self.use_module_level = use_module_level
 
@@ -242,12 +242,12 @@ def __init__(self, input_genes, scfm_genes,
         self.register_buffer('scatter_module_idx', torch.tensor(module_indices, dtype=torch.long))
         self.register_buffer('scatter_gene_idx', torch.tensor(gene_indices, dtype=torch.long))
 
-        # Create PerformerEncoderOnly_Module model
+        # Create BioMod model
         scfm_hyper_params['module_sets'] = module_sets
         scfm_hyper_params['num_genes'] = len(scfm_genes)
         scfm_hyper_params['max_seq_len'] = len(module_sets)
 
-        self.scfm = PerformerEncoderOnly_Module(**scfm_hyper_params)
+        self.scfm = BioMod(**scfm_hyper_params)
 
         # ============================================================
         # [Key] Load pre-trained weights
@@ -298,7 +298,7 @@ def forward(self, x):
 
         [Processing Process]
         1. Re-index the input gene expression into the gene order of the pre-trained model
-        2. Get the module encoding through PerformerEncoderOnly_Module
+        2. Get the module encoding through BioMod
         3. Restore gene-level embedding from module encoding (or return module encoding directly)
         4. Reindex gene embeddings back to input gene order
 
@@ -395,17 +395,17 @@ def forward(self, x):
         return output_reindex
 
 
-class GEARS_Model_Module(torch.nn.Module):
+class GEARS_Model_BioMod(torch.nn.Module):
     """
     ================================================================================
-    GEARS_Model_Module: Genetic perturbation prediction model
+    GEARS_Model_BioMod: Genetic perturbation prediction model
 
     [Core functions]
     Predicting transcriptomic changes in cells following genetic perturbation. Enter a perturbation combination (such as knockout gene A),
     Output the expression value prediction of each gene after perturbation.
 
     [Model Architecture]
-    1. Pretrained encoder (SCFM_Module): Encode gene expression into embedding vectors
+    1. Pretrained encoder (SCFM_BioMod): Encode gene expression into embedding vectors
     2. Perturbation embedding layer: generate perturbation features for perturbed genes
     3. GO graph neural network (GNN): using gene ontology knowledge to enhance perturbation representation
     4. Decoder: predict gene expression values after perturbation
@@ -424,7 +424,7 @@ class GEARS_Model_Module(torch.nn.Module):
     ================================================================================
     """
     def __init__(self, args):
-        super(GEARS_Model_Module, self).__init__()
+        super(GEARS_Model_BioMod, self).__init__()
         self.args = args
 
         # Forecast record related settings
@@ -462,7 +462,7 @@ def __init__(self, args):
             with open(args["scfm_hyper_params_path"], 'rb') as handle:
                 self.scfm_hyper_params = pickle5.load(handle)
         self.scfm_hyper_params.pop('module_embed_chunk_padded_gene_budget', None)
-        self.scfm_hyper_params = sanitize_performer_module_config(
+        self.scfm_hyper_params = sanitize_biomod_config(
             self.scfm_hyper_params,
             source=args["scfm_hyper_params_path"],
             log_fn=print,
@@ -480,8 +480,8 @@ def __init__(self, args):
         if 'module_sets' in self.scfm_hyper_params and self.scfm_hyper_params['module_sets'] is not None:
             module_sets = self.scfm_hyper_params['module_sets']
         elif args.get('module_data_path') or args.get('module_data_dir'):
-            from BioMod.module_dataset import load_module_data
-            module_sets = load_module_data(
+            from BioMod.biomod_dataset import load_biomod_data
+            module_sets = load_biomod_data(
                 module_data_path=args.get('module_data_path'),
                 module_data_dir=args.get('module_data_dir'),
                 gene_list_path=args.get('scfm_genes_list_path'),
@@ -499,7 +499,7 @@ def __init__(self, args):
         if args.get('shuffle_module_genes', False):
             shuffle_seed = args.get('shuffle_seed', 2021)
             print(
-                f"[GEARS_Model_Module] Applying downstream-only extra module reshuffle "
+                f"[GEARS_Model_BioMod] Applying downstream-only extra module reshuffle "
                 f"(seed={shuffle_seed}). Pretraining-time module_sets from PKL will be reshuffled again."
             )
             all_gene_indices = []
@@ -518,7 +518,7 @@ def __init__(self, args):
                 shuffled_module_sets.append(all_gene_indices[start_idx:start_idx + size])
                 start_idx += size
             module_sets = shuffled_module_sets
-            print(f"[GEARS_Model_Module] Shuffled {len(all_gene_indices)} genes across {len(module_sets)} modules")
+            print(f"[GEARS_Model_BioMod] Shuffled {len(all_gene_indices)} genes across {len(module_sets)} modules")
 
         # ============================================================
         # [Perturbation Embedding Layer]
@@ -585,13 +585,13 @@ def __init__(self, args):
             self.uncertainty_w = MLP([hidden_size, hidden_size*2, hidden_size, 1], last_layer_act='linear')
 
         # ============================================================
-        # [Core] Initialize pre-trained encoder (SCFM_Module)
+        # [Core] Initialize pre-trained encoder (SCFM_BioMod)
         # requires_grad: whether to fine-tune pre-training parameters
         # - finetune_method='frozen': freeze pre-training parameters
         # - Others: Full parameter fine-tuning
         # ============================================================
         self.use_module_level = args.get('use_module_level', False)
-        self.singlecell_model = SCFM_Module(
+        self.singlecell_model = SCFM_BioMod(
             self.input_genes_list,
             self.scfm_genes_list,
             self.scfm_hyper_params,

BioMod/gene_perturbation/{train_module.py → train_biomod.py}

@@ -1,6 +1,6 @@
 """
 ================================================================================
-Genetic perturbation task training script (train_module.py)
+Genetic perturbation task training script (train_biomod.py)
 ================================================================================
 
 [Task Overview]
@@ -10,7 +10,7 @@
 
 [Core process]
 1. Load perturbation data sets (such as Norman, Adamson and other public data sets)
-2. Initialize the pre-trained single-cell basic model (PerformerEncoderOnly_Module)
+2. Initialize the pre-trained single-cell basic model (BioMod)
 3. Fine-tune the model on perturbed data and learn to predict the effect of perturbation
 4. Evaluate model performance (MSE, Pearson correlation coefficient and other indicators)
 
@@ -47,7 +47,7 @@
 REPO_ROOT = Path(__file__).resolve().parents[2]
 ASSET_DIR = REPO_ROOT / "model_dependencies"
 DOWNSTREAM_DATA_DIR = REPO_ROOT / "data" / "downstream" / "final_data"
-WEIGHTS_DIR = REPO_ROOT / "weight" / "0810model"
+WEIGHTS_DIR = REPO_ROOT / "weight"
 
 # ============================================================
 # [Key] Correctly set the order of sys.path
@@ -58,7 +58,7 @@
 current_dir = os.path.dirname(os.path.abspath(__file__))
 project_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 
-# First add the project root directory (for performer_pytorch_cont)
+# First add the project root directory (for pytorch_cont)
 if project_root not in sys.path:
     sys.path.append(project_root)
 
@@ -87,7 +87,7 @@
 from pertdata_local import PertData  # Local version, does not rely on external gears_reduce
 
 # Import module model
-from model_module import GEARS_Model_Module
+from model_biomod import GEARS_Model_BioMod
 
 def main(parser):
     """
@@ -105,7 +105,7 @@ def main(parser):
 
     args = parser.parse_args()
     if args.module_data_path is None and args.module_data_dir is None:
-        args.module_data_dir = str(ASSET_DIR / 'module_data_all')
+        args.module_data_dir = str(ASSET_DIR / 'biomod_data_all')
 
     # ============================================================
     # [Distributed training initialization]
@@ -190,7 +190,7 @@ def main(parser):
 
     # ============================================================
     # [Model parameter configuration]
-    # Use GEARS_Model_Module instead of GEARS_Model_Acc
+    # Use GEARS_Model_BioMod instead of GEARS_Model_Acc
     # Key parameter description:
     # - hidden_size: hidden layer dimension, affecting model capacity
     # - finetune_method: fine-tuning method ('frozen' freezes pre-training parameters, None means fine-tuning all parameters)
@@ -212,7 +212,7 @@ def main(parser):
         key_enc=None,
         scfm_gene2vec_file=args.scfm_gene2vec_file,
         record_pred=args.record_pred,
-        model_class=GEARS_Model_Module,  # Use module model class
+        model_class=GEARS_Model_BioMod,  # Use module model class
         # ============================================================
         # [Module related parameters] The following parameters affect how the model processes module-based data
         # module_data_path/module_data_dir: module divides the data path
@@ -243,7 +243,7 @@ def main(parser):
         param_pd.to_csv(f'{args.result_dir}/params.csv')
 
 if __name__ == '__main__':
-    parser = argparse.ArgumentParser(description='GEARS with PerformerEncoderOnly_Module')
+    parser = argparse.ArgumentParser(description='GEARS with BioMod')
 
     # ============================================================
     # [Distributed training parameters]
@@ -297,9 +297,9 @@ def main(parser):
     parser.add_argument('--scfm_genes_list_path', type=str,
                         default=str(ASSET_DIR / "selected_genes_27k.txt"))
     parser.add_argument('--scfm_hyper_params_path', type=str,
-                        default=str(WEIGHTS_DIR / "mae_tost_70M_75mask_ec2.pkl"))
+                        default=str(WEIGHTS_DIR / "BioMod.pkl"))
     parser.add_argument('--scfm_ckpt_path', type=str,
-                        default=str(WEIGHTS_DIR / "mae_tost_70M_75mask_ec2_epoch0.pth"))
+                        default=str(WEIGHTS_DIR / "BioMod.pth"))
     parser.add_argument('--run_name', type=str,
                         default="default_run_module")
     parser.add_argument('--scfm_gene2vec_file', type=str,
@@ -314,20 +314,20 @@ def main(parser):
     # fusion_method: Read from pkl to ensure consistency with pre-training
     # shuffle_module_genes: [Ablation experiment] Disrupt the genes in the module to verify the importance of the module structure
     # ============================================================
-    parser.add_argument('--module_data_path', type=str, default=None,
-                        help='Path to module JSON file (single file)')
-    parser.add_argument('--module_data_dir', type=str, default=None,
-                        help='Module JSON directory; defaults to bundled module_data_all only when no module file or directory is supplied')
+    parser.add_argument('--biomod_data_path', '--module_data_path', type=str, default=None,
+                        help='Path to module JSON file (single file)', dest='module_data_path')
+    parser.add_argument('--biomod_data_dir', '--module_data_dir', type=str, default=None,
+                        help='Module JSON directory; defaults to bundled biomod_data_all only when no module file or directory is supplied', dest='module_data_dir')
     parser.add_argument('--gene_mapping_path', type=str, default=str(ASSET_DIR / 'gene2ens.csv'),
                         help='Path to gene symbol to Ensembl ID mapping CSV')
-    parser.add_argument('--use_module_level', action='store_true',
+    parser.add_argument('--use_biomod_level', '--use_module_level', action='store_true',
                         help='Use module-level features directly instead of recovering to gene level. '
-                             'Note: This requires compatible downstream architecture (not fully implemented).')
-    parser.add_argument('--shuffle_module_genes', action='store_true',
+                             'Note: This requires compatible downstream architecture (not fully implemented).', dest='use_module_level')
+    parser.add_argument('--shuffle_biomod_genes', '--shuffle_module_genes', action='store_true',
                         help='[Ablation experiment] Additionally shuffle module_sets after restoring them from the pretrained PKL. '
-                             'Do not pass this parameter when reproducing the experiment normally.')
+                             'Do not pass this parameter when reproducing the experiment normally.', dest='shuffle_module_genes')
     parser.add_argument('--shuffle_seed', type=int, default=2021,
-                        help='Only takes effect when --shuffle_module_genes is turned on and is used for additional downstream shuffling.')
+                        help='Only takes effect when --shuffle_biomod_genes is turned on and is used for additional downstream shuffling.')
     parser.add_argument('--lr', type=float, default=1e-3)
 
     main(parser)

BioMod/interpretability/README.md

@@ -11,11 +11,11 @@ when loading the pretrained backbone.
 
 | # | Script | Core question | Status |
 | --- | --- | --- | --- |
-| 1 | `module_geometry.py` | Does the module latent space self-organize by pathway family,  | Completed |
-| 2 | `module_text_alignment/module_text_alignment.py` | Do module embeddings align with natural-language pathway descriptions,  | Implemented |
-| 3 | `module_importance/module_importance.py` | Does task-driven module importance match known pathway-cell-type or pathway-disease associations,  | Implemented |
+| 1 | `biomod_geometry.py` | Does the module latent space self-organize by pathway family,  | Completed |
+| 2 | `biomod_text_alignment/biomod_text_alignment.py` | Do module embeddings align with natural-language pathway descriptions,  | Implemented |
+| 3 | `biomod_importance/biomod_importance.py` | Does task-driven module importance match known pathway-cell-type or pathway-disease associations,  | Implemented |
 | 4 | `module_vs_gene.py` | Is BioMod better than GenePT/scGPT for pathway-level interpretability,  | TODO |
-| 6 | `attention/module_crosstalk.py` | Do module interactions match Reactome/KEGG pathway relationships,  | Implemented |
+| 6 | `attention/biomod_crosstalk.py` | Do module interactions match Reactome/KEGG pathway relationships,  | Implemented |
 
 Experiments 1 and 2 are the core differentiators because gene-level baselines
 cannot structurally reproduce them. Experiment 3 provides task-level functional
@@ -24,7 +24,7 @@ experiments, such as module crosstalk vs Reactome, module dynamics along
 developmental trajectories, and retraining-based module-granularity ablation, can
 be pursued after the core experiments are complete.
 
-## Experiment 1: Intrinsic Geometry of Module Embeddings (`module_geometry.py`)
+## Experiment 1: Intrinsic Geometry of Module Embeddings (`biomod_geometry.py`)
 
 **Hypothesis:** the BioMod encoder is trained with a masked-module
 reconstruction task, but it should still encode semantically related modules,
@@ -36,7 +36,7 @@ never seen during training.
 
 1. Load the pretrained backbone and run inference with `mask_ratio=0.0` and `return_encodings=True` to obtain module encodings shaped `[B, num_modules, base_dim]`.
 2. Average over the cell population to obtain `[num_modules, base_dim]`, using streaming accumulation rather than storing the full table in memory.
-3. Parse family assignments from the keys in `merged_modules.json`: `Hallmarks` (50), `Reactome` (491), `Hotspot` (73), and `Processed` (46). Hallmark modules are also annotated with one of eight MSigDB biological-process categories: immune, metabolic, signaling, proliferation, development, dna_damage, pathway, and cellular_component.
+3. Parse family assignments from the keys in `merged_biomods.json`: `Hallmarks` (50), `Reactome` (491), `Hotspot` (73), and `Processed` (46). Hallmark modules are also annotated with one of eight MSigDB biological-process categories: immune, metabolic, signaling, proliferation, development, dna_damage, pathway, and cellular_component.
 4. Quantify family separation:
    - silhouette coefficient, using both cosine and Euclidean metrics.
    - kNN purity at `k=10`, using both cosine and Euclidean metrics.
@@ -56,36 +56,36 @@ aggregation end to end during pretraining.
 BioMod/interpretability/                                 # Module representations and biological interpretability
 ├── attention/                                           # Module crosstalk and within-module gene attention
 │   ├── __init__.py
-│   ├── module_crosstalk.py
-│   ├── module_gene_attention.py
+│   ├── biomod_crosstalk.py
+│   ├── biomod_gene_attention.py
 │   ├── README.md
 │   └── README_gene_attention.md
-├── module_importance/                                   # Module importance, ablation studies and marker-gene validation
+├── biomod_importance/                                   # Module importance, ablation studies and marker-gene validation
 │   ├── __init__.py
 │   ├── cross_class_similarity.py
 │   ├── family_ablation.py
 │   ├── family_importance_analysis.py
 │   ├── marker_gene_verification.py
 │   ├── masking_ablation.py
-│   ├── module_importance.py
-│   ├── module_importance_publication.py
+│   ├── biomod_importance.py
+│   ├── biomod_importance_publication.py
 │   ├── pub_utils.py
 │   ├── random_baseline.py
 │   ├── README.md
 │   ├── RESULTS.md
 │   ├── tcell_reactome_analysis.py
 │   └── TODO.md
-├── module_text_alignment/                               # Semantic alignment of module representations and pathway text
+├── biomod_text_alignment/                               # Semantic alignment of module representations and pathway text
 │   ├── __init__.py
 │   ├── DESIGN.md
 │   ├── fetch_reactome_descriptions.py
 │   ├── MANUSCRIPT_SECTION.md
-│   ├��─ module_text_alignment.py
-│   ├── module_text_alignment_extended.py
-│   ├── module_text_alignment_publication.py
+│   ├── biomod_text_alignment.py
+│   ├── biomod_text_alignment_extended.py
+│   ├── biomod_text_alignment_publication.py
 │   └── reactome_descriptions.json
 ├── __init__.py
-├── module_geometry.py
+├── biomod_geometry.py
 ├── README.md
 └── utils.py
 ```
@@ -104,10 +104,10 @@ bundled; run the corresponding upstream analysis before using those paths.
 
 ```bash
 # General h5ad input: cell annotation, zero-shot, or any annotated dataset.
-python BioMod/interpretability/module_geometry.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl           weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir       model_dependencies/module_data_all \
+python BioMod/interpretability/biomod_geometry.py \
+    --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 \
     --gene_mapping_path    model_dependencies/gene2ens.csv \
     --gene2vec_data_path   model_dependencies/selected_gene2vec_27k.npy \
@@ -123,10 +123,10 @@ For pretraining data, where each cell is an `.npz` file already in the 27,874
 model-gene space:
 
 ```bash
-python BioMod/interpretability/module_geometry.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl           weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir       model_dependencies/module_data_all \
+python BioMod/interpretability/biomod_geometry.py \
+    --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 \
     --gene_mapping_path    model_dependencies/gene2ens.csv \
     --gene2vec_data_path   model_dependencies/selected_gene2vec_27k.npy \
@@ -144,10 +144,10 @@ processes a subset of cells, embeddings are aggregated with `all_reduce`, and
 rank 0 computes metrics and figures. Single-GPU and CPU behavior is unchanged.
 
 ```bash
-torchrun --nproc_per_node=2 BioMod/interpretability/module_geometry.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl           weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir       model_dependencies/module_data_all \
+torchrun --nproc_per_node=2 BioMod/interpretability/biomod_geometry.py \
+    --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 \
     --gene_mapping_path    model_dependencies/gene2ens.csv \
     --gene2vec_data_path   model_dependencies/selected_gene2vec_27k.npy \
@@ -167,7 +167,7 @@ torchrun --nproc_per_node=2 BioMod/interpretability/module_geometry.py \
 | `--knn_k` | 10 | `k` for kNN purity. |
 | `--null_permutations` | 200 | Number of label permutations for the empirical null distribution. |
 | `--include_other_in_metrics` | Off | By default, modules from the `Other` family are excluded. |
-| `--shuffle_module_genes` | Off | Randomly shuffle gene-to-module assignments as a negative control or ablation. Uses the same flag as pretraining and downstream finetuning. |
+| `--shuffle_biomod_genes` | Off | Randomly shuffle gene-to-module assignments as a negative control or ablation. Uses the same flag as pretraining and downstream finetuning. |
 | `--umap_n_neighbors` | 15 | UMAP graph-construction parameter. |
 | `--umap_min_dist` | 0.3 | UMAP layout parameter. |
 
@@ -190,9 +190,9 @@ Files are written to `<output_dir>/`:
 
 Two control experiments make Experiment 1 more rigorous:
 
-1. **Random module assignment**: rerun with `--shuffle_module_genes`. This flag preserves module sizes but randomly assigns genes to modules, matching the same ablation flag used for pretraining and finetuning. If geometry is pathway-driven rather than a generic property of the encoder, family separation should drop close to the null distribution.
+1. **Random module assignment**: rerun with `--shuffle_biomod_genes`. This flag preserves module sizes but randomly assigns genes to modules, matching the same ablation flag used for pretraining and finetuning. If geometry is pathway-driven rather than a generic property of the encoder, family separation should drop close to the null distribution.
 
-2. **Untrained backbone**: set `--performer_checkpoint` to the `*_init.pth` checkpoint generated during pretraining with `--save_init_ckpt_and_exit`. Family separation should be close to the null distribution. The gap between trained and untrained models quantifies the contribution of pretraining.
+2. **Untrained backbone**: set `--biomod_checkpoint` to the `*_init.pth` checkpoint generated during pretraining with `--save_init_ckpt_and_exit`. Family separation should be close to the null distribution. The gap between trained and untrained models quantifies the contribution of pretraining.
 
 Together, these controls support the claim that the family structure of the module
 latent space is produced by pathway-based module design plus pretraining, rather
@@ -200,16 +200,16 @@ than by module design alone or by a generic encoder architecture.
 
 ### Control 1: Random Module Assignment (`shuffle_module_genes`)
 
-Add `--shuffle_module_genes` to the original command and write to a control output
+Add `--shuffle_biomod_genes` to the original command and write to a control output
 directory.
 
 For h5ad data, using `pancreas_scib` as an example:
 
 ```bash
-python BioMod/interpretability/module_geometry.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl           weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir       model_dependencies/module_data_all \
+python BioMod/interpretability/biomod_geometry.py \
+    --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 \
     --gene_mapping_path    model_dependencies/gene2ens.csv \
     --gene2vec_data_path   model_dependencies/selected_gene2vec_27k.npy \
@@ -218,17 +218,17 @@ python BioMod/interpretability/module_geometry.py \
     --data_mode            h5ad \
     --gene_name_column     auto \
     --batch_size           640 \
-    --shuffle_module_genes \
+    --shuffle_biomod_genes \
     --output_dir           outputs/interpretability/geometry/pancreas_scib_shuffle
 ```
 
 For pretraining npz data:
 
 ```bash
-python BioMod/interpretability/module_geometry.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl           weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir       model_dependencies/module_data_all \
+python BioMod/interpretability/biomod_geometry.py \
+    --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 \
     --gene_mapping_path    model_dependencies/gene2ens.csv \
     --gene2vec_data_path   model_dependencies/selected_gene2vec_27k.npy \
@@ -237,11 +237,11 @@ python BioMod/interpretability/module_geometry.py \
     --data_mode            pretrain_npz \
     --max_cells            50000 \
     --batch_size           640 \
-    --shuffle_module_genes \
+    --shuffle_biomod_genes \
     --output_dir           outputs/interpretability/geometry/pretrain_subset_shuffle
 ```
 
-How `--shuffle_module_genes` works: inside `load_backbone()`, module sizes are
+How `--shuffle_biomod_genes` works: inside `load_backbone()`, module sizes are
 kept unchanged, all genes are collected into one list, the list is randomly
 shuffled, and genes are reassigned to modules. The seed is controlled by
 `--shuffle_seed`, defaulting to 2021. Model weights are unchanged; only the
@@ -253,7 +253,7 @@ records `"shuffle_module_genes": true`.
 
 ### Control 2: Untrained Backbone with Random Initialization
 
-First generate a randomly initialized checkpoint, then run `module_geometry.py`
+First generate a randomly initialized checkpoint, then run `biomod_geometry.py`
 with it.
 
 A matching randomly initialized checkpoint and configuration are not bundled.
@@ -263,8 +263,8 @@ Keep the generated control files in a separate output directory. Then pass their
 paths explicitly; do not use the pretrained BioMod weights for this control.
 
 ```bash
-python BioMod/interpretability/module_geometry.py \
-    --performer_checkpoint /absolute/path/to/random_init.pth \
+python BioMod/interpretability/biomod_geometry.py \
+    --biomod_checkpoint /absolute/path/to/random_init.pth \
     --config_pkl /absolute/path/to/random_init.pkl \
     --data_path data/downstream/final_data/human_pancreas_norm_complexBatch_with_gene_name.h5ad \
     --data_mode h5ad \
@@ -292,7 +292,7 @@ The three experiments jointly show that the family structure of the module laten
 space is generated by both pathway-based module design and pretraining; both are
 necessary.
 
-## Experiment 2: Module Embedding to Pathway Text Alignment (`module_text_alignment/`)
+## Experiment 2: Module Embedding to Pathway Text Alignment (`biomod_text_alignment/`)
 
 **Hypothesis:** the structure of the BioMod module embedding space significantly
 aligns with natural-language pathway semantics. Semantically similar pathways
@@ -301,7 +301,7 @@ experiment because individual gene names do not carry phrase-level semantics.
 
 **Method:**
 
-1. Parse 541 semantically named modules from `merged_modules.json`: 50 Hallmark and 491 Reactome.
+1. Parse 541 semantically named modules from `merged_biomods.json`: 50 Hallmark and 491 Reactome.
 2. Encode pathway names with S-PubMedBert-MS-MARCO, a sentence-level fine-tuned PubMedBERT model.
 3. Load `module_embeddings.npy` from Experiment 1, containing cell-averaged module embeddings.
 4. Measure alignment:
@@ -322,19 +322,19 @@ raw expression data are not required.
 # Network access or an existing local model cache is required.
 
 # Main experiment: RSA + CKA + LOO retrieval.
-python BioMod/interpretability/module_text_alignment/module_text_alignment.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
     --n_permutations 1000 \
     --output_dir outputs/interpretability/text_alignment/pretrain_subset_v2
 
 # Extended analysis: broad Reactome categories and Hallmark deep dive.
-python BioMod/interpretability/module_text_alignment/module_text_alignment_extended.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment_extended.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
-    --descriptions_file BioMod/interpretability/module_text_alignment/reactome_descriptions.json \
+    --descriptions_file BioMod/interpretability/biomod_text_alignment/reactome_descriptions.json \
     --n_permutations 1000 \
     --output_dir outputs/interpretability/text_alignment/pretrain_subset_v2_extended
 ```

BioMod/interpretability/__init__.py

@@ -1,8 +1,8 @@
-"""Module interpretability experiments for scLong (performer_module).
+"""Module interpretability experiments for scLong (biomod).
 
 Roadmap (priority order):
-    1. module_geometry.py — intrinsic module-embedding geometry (current).
-    2. module_text_alignment.py — module ↔ pathway natural-language alignment.
-    3. module_importance.py — task-driven ablation + literature enrichment.
+    1. biomod_geometry.py — intrinsic module-embedding geometry (current).
+    2. biomod_text_alignment.py — module ↔ pathway natural-language alignment.
+    3. biomod_importance.py — task-driven ablation + literature enrichment.
     4. module_vs_gene.py — comparison with gene-level baselines (GenePT, scGPT, ...).
 """

BioMod/interpretability/attention/README.md

@@ -30,10 +30,10 @@ included; replace `/absolute/path/to/pretraining_cell_npz` with your own directo
 # Run from the BioMod repository root.
 
 # Full run, methods A + C.
-python BioMod/interpretability/attention/module_crosstalk.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/interpretability/attention/biomod_crosstalk.py \
+    --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 \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -46,10 +46,10 @@ python BioMod/interpretability/attention/module_crosstalk.py \
     --pool_mode max
 
 # Method A only, for quick validation.
-python BioMod/interpretability/attention/module_crosstalk.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/interpretability/attention/biomod_crosstalk.py \
+    --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 \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -61,10 +61,10 @@ python BioMod/interpretability/attention/module_crosstalk.py \
     --output_dir outputs/interpretability/crosstalk/pancreas_cosine_only
 
 # Pretraining npz data.
-python BioMod/interpretability/attention/module_crosstalk.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/interpretability/attention/biomod_crosstalk.py \
+    --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 \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \

BioMod/interpretability/attention/README_gene_attention.md

@@ -1,7 +1,7 @@
-# Gene Attention Interpretability: ModuleEmbedding
+# Gene Attention Interpretability: BioModEmbedding
 
 Analyze gene contributions within modules using the content-based attention
-pooling in ModuleEmbedding.
+pooling in BioModEmbedding.
 
 ## Analyses
 
@@ -32,10 +32,10 @@ the column name has not been assumed for the bundled pancreas file.
 ```bash
 # Run from the BioMod repository root.
 
-python BioMod/interpretability/attention/module_gene_attention.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/interpretability/attention/biomod_gene_attention.py \
+    --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 \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -50,10 +50,10 @@ python BioMod/interpretability/attention/module_gene_attention.py \
 ### With DEG Comparison
 
 ```bash
-python BioMod/interpretability/attention/module_gene_attention.py \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/interpretability/attention/biomod_gene_attention.py \
+    --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 \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -89,7 +89,7 @@ Add `--max_cells 5000` to the complete basic command above and change
 | `--marker_db` | None | Custom marker CSV; built-in pancreas markers are used when omitted |
 | `--deg_csv` | None | DEG result CSV; DEG correlation analysis is skipped when omitted |
 | `--celltype_column` | celltype | Cell-type column name in h5ad |
-| `--shuffle_module_genes` | off | Randomly shuffle gene-to-module assignment as a negative control |
+| `--shuffle_biomod_genes` | off | Randomly shuffle gene-to-module assignment as a negative control |
 
 ## Output Files
 

BioMod/interpretability/attention/{module_crosstalk.py → biomod_crosstalk.py}

@@ -19,10 +19,10 @@
   - Permutation null p-values for all metrics
 
 Usage (run from the BioMod repository root):
-  python BioMod/interpretability/attention/module_crosstalk.py \
-      --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-      --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-      --module_data_dir model_dependencies/module_data_all \
+  python BioMod/interpretability/attention/biomod_crosstalk.py \
+      --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 \
       --gene_mapping_path model_dependencies/gene2ens.csv \
       --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -53,14 +53,14 @@
 from sklearn.metrics import roc_auc_score
 
 HERE = Path(__file__).resolve()
-PERFORMER_MODULE = HERE.parents[2]
+BIOMOD_SOURCE = HERE.parents[2]
 REPO_ROOT = HERE.parents[3]
 ASSET_ROOT = REPO_ROOT / "model_dependencies"
-for p in (str(PERFORMER_MODULE), str(REPO_ROOT)):
+for p in (str(BIOMOD_SOURCE), str(REPO_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from cell_annotation.performer_module_finetune import (
+from cell_annotation.biomod_finetune import (
     DataPreprocessor,
     load_backbone,
     seed_all,
@@ -69,9 +69,9 @@
 from interpretability.utils import (
     MatrixRowDataset,
     NpzCellDataset,
-    build_module_metadata,
+    build_biomod_metadata,
     ensure_dir,
-    load_module_names,
+    load_biomod_names,
 )
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
@@ -84,16 +84,16 @@
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
 
-    p.add_argument("--performer_checkpoint", type=str, required=True)
+    p.add_argument("--biomod_checkpoint", "--performer_checkpoint", type=str, required=True, dest='performer_checkpoint')
     p.add_argument("--config_pkl", type=str, required=True)
-    p.add_argument("--module_data_dir", type=str, default=str(ASSET_ROOT / "module_data_all"))
-    p.add_argument("--module_json", type=str, default=None)
+    p.add_argument("--biomod_data_dir", "--module_data_dir", type=str, default=str(ASSET_ROOT / "biomod_data_all"), dest='module_data_dir')
+    p.add_argument("--biomod_json", "--module_json", type=str, default=None, dest='module_json')
     p.add_argument("--gene_list_path", type=str, default=str(ASSET_ROOT / "selected_genes_27k.txt"))
     p.add_argument("--gene_mapping_path", type=str, default=str(ASSET_ROOT / "gene2ens.csv"))
     p.add_argument("--gene2vec_data_path", type=str, default=str(ASSET_ROOT / "selected_gene2vec_27k.npy"))
     p.add_argument("--gene2ens_file", type=str, default=str(ASSET_ROOT / "gene2ens.csv"))
     p.add_argument("--gene2ens_column", type=str, default="Ensembl gene ID")
-    p.add_argument("--shuffle_module_genes", action="store_true")
+    p.add_argument("--shuffle_biomod_genes", "--shuffle_module_genes", action="store_true", dest='shuffle_module_genes')
     p.add_argument("--shuffle_seed", type=int, default=2021)
 
     p.add_argument("--data_path", type=str, required=True)
@@ -129,7 +129,7 @@ def parse_args() -> argparse.Namespace:
 
 
 # ---------------------------------------------------------------------------
-# Data loading (reuses patterns from module_geometry.py)
+# Data loading (reuses patterns from biomod_geometry.py)
 # ---------------------------------------------------------------------------
 
 def build_dataset(args, preprocessor):
@@ -273,9 +273,9 @@ def _compute_single_cell_jacobian(backbone, cell, num_modules, base_dim, device)
 
     with torch.enable_grad():
         if backbone.mask_style == "replace":
-            x = backbone._add_module_position_embedding(x_modules)
+            x = backbone._add_biomod_position_embedding(x_modules)
         else:
-            x = backbone._add_module_position_embedding(x_modules)
+            x = backbone._add_biomod_position_embedding(x_modules)
 
         if backbone.use_cls and backbone.cls_token is not None:
             cls_token = backbone.cls_token + backbone.pos_emb[:, :1, :]
@@ -477,16 +477,16 @@ def main():
             setattr(args, attr, str(Path(val).resolve()))
 
     logger.info("Loading backbone...")
-    backbone, module_data, model_config = load_backbone(args, device)
+    backbone, biomod_data, model_config = load_backbone(args, device)
     backbone.eval()
 
-    num_modules = len(module_data)
+    num_modules = len(biomod_data)
     base_dim = int(model_config["base_dim"])
     expected_genes = int(model_config.get("num_genes", 27874))
     logger.info("Model: %d modules, dim=%d, genes=%d", num_modules, base_dim, expected_genes)
 
-    module_json_path = args.module_json or str(Path(args.module_data_dir) / "merged_modules.json")
-    module_names = load_module_names(module_json_path)
+    module_json_path = args.module_json or str(Path(args.module_data_dir) / "merged_biomods.json")
+    module_names = load_biomod_names(module_json_path)
     with open(module_json_path, "r", encoding="utf-8") as f:
         module_gene_dict = json.load(f)
 
@@ -571,7 +571,7 @@ def main():
         json.dump(results, f, indent=2, ensure_ascii=False)
 
     # --- Plots ---
-    meta = build_module_metadata(module_names)
+    meta = build_biomod_metadata(module_names)
     families = [row["family"] for row in meta]
 
     plot_interaction_matrix(cos_matrix, "Method A: Cosine Similarity",

BioMod/interpretability/attention/{module_gene_attention.py → biomod_gene_attention.py}

@@ -1,6 +1,6 @@
-"""ModuleEmbedding Attention-based Gene Interpretability Analysis (Streaming).
+"""BioModEmbedding Attention-based Gene Interpretability Analysis (Streaming).
 
-Interpretability analysis using single-head content-based attention pooling in ModuleEmbedding.
+Interpretability analysis using single-head content-based attention pooling in BioModEmbedding.
 Streaming computing mode: memory usage O(n_celltypes × n_genes).
 
 Analysis content:
@@ -14,10 +14,10 @@
   8. DEG comparison
 
 Usage (run from the BioMod repository root):
-  python BioMod/interpretability/attention/module_gene_attention.py \
-      --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-      --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-      --module_data_dir model_dependencies/module_data_all \
+  python BioMod/interpretability/attention/biomod_gene_attention.py \
+      --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 \
       --gene_mapping_path model_dependencies/gene2ens.csv \
       --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -51,30 +51,30 @@
 from scipy.stats import spearmanr, t as t_dist
 
 HERE = Path(__file__).resolve()
-PERFORMER_MODULE = HERE.parents[2]
+BIOMOD_SOURCE = HERE.parents[2]
 REPO_ROOT = HERE.parents[3]
 ASSET_ROOT = REPO_ROOT / "model_dependencies"
-for p in (str(PERFORMER_MODULE), str(REPO_ROOT)):
+for p in (str(BIOMOD_SOURCE), str(REPO_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
 # Publication utilities
-MODULE_IMPORTANCE_DIR = PERFORMER_MODULE / "interpretability" / "module_importance"
-if str(MODULE_IMPORTANCE_DIR) not in sys.path:
-    sys.path.insert(0, str(MODULE_IMPORTANCE_DIR))
+BIOMOD_IMPORTANCE_DIR = BIOMOD_SOURCE / "interpretability" / "biomod_importance"
+if str(BIOMOD_IMPORTANCE_DIR) not in sys.path:
+    sys.path.insert(0, str(BIOMOD_IMPORTANCE_DIR))
 
 from pub_utils import setup_publication_style, savefig as pub_savefig
 
-from cell_annotation.performer_module_finetune import (
+from cell_annotation.biomod_finetune import (
     DataPreprocessor,
     load_backbone,
     seed_all,
 )
 from interpretability.utils import (
     MatrixRowDataset,
-    build_module_metadata,
+    build_biomod_metadata,
     ensure_dir,
-    load_module_names,
+    load_biomod_names,
 )
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
@@ -88,16 +88,16 @@
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
 
-    p.add_argument("--performer_checkpoint", type=str, required=True)
+    p.add_argument("--biomod_checkpoint", "--performer_checkpoint", type=str, required=True, dest='performer_checkpoint')
     p.add_argument("--config_pkl", type=str, required=True)
-    p.add_argument("--module_data_dir", type=str, default=str(ASSET_ROOT / "module_data_all"))
-    p.add_argument("--module_json", type=str, default=None)
+    p.add_argument("--biomod_data_dir", "--module_data_dir", type=str, default=str(ASSET_ROOT / "biomod_data_all"), dest='module_data_dir')
+    p.add_argument("--biomod_json", "--module_json", type=str, default=None, dest='module_json')
     p.add_argument("--gene_list_path", type=str, default=str(ASSET_ROOT / "selected_genes_27k.txt"))
     p.add_argument("--gene_mapping_path", type=str, default=str(ASSET_ROOT / "gene2ens.csv"))
     p.add_argument("--gene2vec_data_path", type=str, default=str(ASSET_ROOT / "selected_gene2vec_27k.npy"))
     p.add_argument("--gene2ens_file", type=str, default=str(ASSET_ROOT / "gene2ens.csv"))
     p.add_argument("--gene2ens_column", type=str, default="Ensembl gene ID")
-    p.add_argument("--shuffle_module_genes", action="store_true")
+    p.add_argument("--shuffle_biomod_genes", "--shuffle_module_genes", action="store_true", dest='shuffle_module_genes')
     p.add_argument("--shuffle_seed", type=int, default=2021)
 
     p.add_argument("--data_path", type=str, required=True)
@@ -915,7 +915,7 @@ def main():
 
     # --- Load model ---
     logger.info("Loading backbone from %s", args.performer_checkpoint)
-    backbone, module_data, model_config = load_backbone(args, device)
+    backbone, biomod_data, model_config = load_backbone(args, device)
     backbone.eval()
 
     # --- Build module gene name mapping ---

BioMod/interpretability/{module_geometry.py → biomod_geometry.py}

@@ -12,7 +12,7 @@
 1. Load pretrained backbone (forward with mask_ratio=0).
 2. Iterate over a population of cells, accumulate the per-module encoder output
    in a streaming average -> [num_modules, base_dim].
-3. Parse each module's family from merged_modules.json keys
+3. Parse each module's family from merged_biomods.json keys
    (Hallmarks / Reactome / Hotspot / Processed) and, where applicable, the
    MSigDB hallmark process subcategory (immune / metabolic / signaling / ...).
 4. Quantify family separation:
@@ -44,8 +44,8 @@
 
 CLI
 ---
-python -m performer_module.interpretability.module_geometry \\
-    --performer_checkpoint <ckpt.pth> \\
+python BioMod/interpretability/biomod_geometry.py \\
+    --biomod_checkpoint <ckpt.pth> \\
     --config_pkl <config.pkl> \\
     --data_path <path.h5ad> \\
     --data_mode h5ad \\
@@ -79,14 +79,14 @@
 
 # Make sibling modules importable when launched as a script
 HERE = Path(__file__).resolve()
-PERFORMER_MODULE = HERE.parents[1]
+BIOMOD_SOURCE = HERE.parents[1]
 REPO_ROOT = HERE.parents[2]
 ASSET_ROOT = REPO_ROOT / "model_dependencies"
-for p in (str(PERFORMER_MODULE), str(REPO_ROOT)):
+for p in (str(BIOMOD_SOURCE), str(REPO_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from cell_annotation.performer_module_finetune import (  # noqa: E402
+from cell_annotation.biomod_finetune import (  # noqa: E402
     DataPreprocessor,
     get_rank,
     get_world_size,
@@ -102,9 +102,9 @@
 from interpretability.utils import (  # noqa: E402
     MatrixRowDataset,
     NpzCellDataset,
-    build_module_metadata,
+    build_biomod_metadata,
     ensure_dir,
-    load_module_names,
+    load_biomod_names,
 )
 
 logger = logging.getLogger(__name__)
@@ -115,19 +115,19 @@
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
 
-    # Pretrained backbone (mirrors cell_annotation.performer_module_finetune)
-    parser.add_argument("--performer_checkpoint", type=str, required=True)
+    # Pretrained backbone (mirrors cell_annotation.biomod_finetune)
+    parser.add_argument("--biomod_checkpoint", "--performer_checkpoint", type=str, required=True, dest='performer_checkpoint')
     parser.add_argument("--config_pkl", type=str, required=True)
-    parser.add_argument("--module_data_dir", type=str, default=str(ASSET_ROOT / "module_data_all"))
-    parser.add_argument("--module_json", type=str, default=None,
-                        help="Path to merged_modules.json. Defaults to <module_data_dir>/merged_modules.json.")
+    parser.add_argument("--biomod_data_dir", "--module_data_dir", type=str, default=str(ASSET_ROOT / "biomod_data_all"), dest='module_data_dir')
+    parser.add_argument("--biomod_json", "--module_json", type=str, default=None,
+                        help="Path to merged_biomods.json. Defaults to <module_data_dir>/merged_biomods.json.", dest='module_json')
     parser.add_argument("--gene_list_path", type=str, default=str(ASSET_ROOT / "selected_genes_27k.txt"))
     parser.add_argument("--gene_mapping_path", type=str, default=str(ASSET_ROOT / "gene2ens.csv"))
     parser.add_argument("--gene2vec_data_path", type=str, default=str(ASSET_ROOT / "selected_gene2vec_27k.npy"))
     parser.add_argument("--gene2ens_file", type=str, default=str(ASSET_ROOT / "gene2ens.csv"))
     parser.add_argument("--gene2ens_column", type=str, default="Ensembl gene ID")
-    parser.add_argument("--shuffle_module_genes", action="store_true",
-                        help="Randomly reshuffle gene-to-module assignment (control / ablation).")
+    parser.add_argument("--shuffle_biomod_genes", "--shuffle_module_genes", action="store_true",
+                        help="Randomly reshuffle gene-to-module assignment (control / ablation).", dest='shuffle_module_genes')
     parser.add_argument("--shuffle_seed", type=int, default=2021)
 
     # Data
@@ -245,7 +245,7 @@ def build_inference_loader(
 # ---------- inference: cell-averaged module embeddings ----------
 
 @torch.no_grad()
-def extract_cell_averaged_module_embeddings(
+def extract_cell_averaged_biomod_embeddings(
     backbone,
     loader: DataLoader,
     preprocessor: Optional[DataPreprocessor],
@@ -285,7 +285,7 @@ def extract_cell_averaged_module_embeddings(
             raise RuntimeError(
                 f"Encoder output shape mismatch: got {tuple(enc.shape)}, "
                 f"expected (*, {num_modules}, {base_dim}). "
-                "Module order between merged_modules.json and the loaded backbone may have drifted."
+                "Module order between merged_biomods.json and the loaded backbone may have drifted."
             )
         sum_emb += enc.to(torch.float64).sum(dim=0)
         n_cells += enc.shape[0]
@@ -497,13 +497,13 @@ def setup_logging(output_dir: Path) -> None:
     )
 
 
-def resolve_module_json(args: argparse.Namespace) -> str:
-    """Resolve relative paths against performer_module/cell_annotation/ to stay
+def resolve_biomod_json(args: argparse.Namespace) -> str:
+    """Resolve relative paths against biomod/cell_annotation/ to stay
     consistent with how `load_backbone` reads `module_data_dir`.
     """
     if args.module_json is not None:
         return str(ca_resolve_path(args.module_json))
-    return str(ca_resolve_path(args.module_data_dir) / "merged_modules.json")
+    return str(ca_resolve_path(args.module_data_dir) / "merged_biomods.json")
 
 
 def main() -> None:
@@ -526,15 +526,15 @@ def main() -> None:
     logger.info("DDP: use_ddp=%s, rank=%d/%d, device=%s", use_ddp, rank, world_size, device)
 
     # 1. Load backbone
-    backbone, module_data, model_config = load_backbone(args, device)
+    backbone, biomod_data, model_config = load_backbone(args, device)
     backbone.eval()
     base_dim = int(model_config["base_dim"])
-    num_modules = len(module_data)
+    num_modules = len(biomod_data)
     logger.info("Loaded backbone: num_modules=%d, base_dim=%d", num_modules, base_dim)
 
-    # 2. Load module names (must align with module_data order)
-    module_json_path = resolve_module_json(args)
-    module_names = load_module_names(module_json_path)
+    # 2. Load module names (must align with biomod_data order)
+    module_json_path = resolve_biomod_json(args)
+    module_names = load_biomod_names(module_json_path)
     if len(module_names) != num_modules:
         raise RuntimeError(
             f"Module name count ({len(module_names)} from {module_json_path}) does not match "
@@ -542,7 +542,7 @@ def main() -> None:
             "model and the one given here must be identical, with no modules dropped during "
             "gene-symbol resolution."
         )
-    metadata = build_module_metadata(module_names)
+    metadata = build_biomod_metadata(module_names)
     metadata_df = pd.DataFrame(metadata)
     if is_main_process():
         logger.info("Family distribution:\n%s", metadata_df["family"].value_counts().to_string())
@@ -569,7 +569,7 @@ def main() -> None:
 
     # 4. Inference
     logger.info("Extracting cell-averaged module embeddings over %d cells...", n_cells)
-    mean_emb, processed = extract_cell_averaged_module_embeddings(
+    mean_emb, processed = extract_cell_averaged_biomod_embeddings(
         backbone, loader, preprocessor, reindex_state, device,
         num_modules=num_modules, base_dim=base_dim,
         expected_input_genes=expected_input_genes,

BioMod/interpretability/{module_importance → biomod_importance}/README.md

@@ -33,10 +33,10 @@ preceding steps; they are not bundled inputs.
 
 ```bash
 # Run from the BioMod repository root.
-python BioMod/interpretability/module_importance/module_importance.py \
+python BioMod/interpretability/biomod_importance/biomod_importance.py \
     --finetune_checkpoint tutorial_runs/cell_annotation_zheng68k_biomod/best_model.pt \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -52,10 +52,10 @@ python BioMod/interpretability/module_importance/module_importance.py \
 Pre-encoder mode, more accurate but slower:
 
 ```bash
-python BioMod/interpretability/module_importance/module_importance.py \
+python BioMod/interpretability/biomod_importance/biomod_importance.py \
     --finetune_checkpoint tutorial_runs/cell_annotation_zheng68k_biomod/best_model.pt \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -72,10 +72,10 @@ python BioMod/interpretability/module_importance/module_importance.py \
 Pre-encoder mode on all cells with DDP multi-GPU acceleration:
 
 ```bash
-torchrun --nproc_per_node=4 BioMod/interpretability/module_importance/module_importance.py \
+torchrun --nproc_per_node=4 BioMod/interpretability/biomod_importance/biomod_importance.py \
     --finetune_checkpoint tutorial_runs/cell_annotation_zheng68k_biomod/best_model.pt \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -132,10 +132,10 @@ If the model learns meaningful module importance:
 Progressively mask top, bottom, or random modules and measure the accuracy drop.
 
 ```bash
-python BioMod/interpretability/module_importance/masking_ablation.py \
+python BioMod/interpretability/biomod_importance/masking_ablation.py \
     --finetune_checkpoint tutorial_runs/cell_annotation_zheng68k_biomod/best_model.pt \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -154,11 +154,11 @@ python BioMod/interpretability/module_importance/masking_ablation.py \
 
 ```bash
 # Mode A: shuffle modules, GPU and slow.
-python BioMod/interpretability/module_importance/random_baseline.py \
+python BioMod/interpretability/biomod_importance/random_baseline.py \
     --mode shuffle_modules \
     --finetune_checkpoint tutorial_runs/cell_annotation_zheng68k_biomod/best_model.pt \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -170,7 +170,7 @@ python BioMod/interpretability/module_importance/random_baseline.py \
     --output_dir outputs/interpretability/importance/permutation/
 
 # Mode B: shuffle labels, CPU and fast, requires per_cell_deltas from ablation.
-python BioMod/interpretability/module_importance/random_baseline.py \
+python BioMod/interpretability/biomod_importance/random_baseline.py \
     --mode shuffle_labels \
     --importance_matrix outputs/interpretability/importance/zheng68k_pre_13690/importance_matrix.npy \
     --per_cell_deltas outputs/interpretability/importance/ablation/per_cell_deltas.npy \
@@ -182,21 +182,21 @@ python BioMod/interpretability/module_importance/random_baseline.py \
 ### 3-C: Marker Gene Verification, CPU Only
 
 ```bash
-python BioMod/interpretability/module_importance/marker_gene_verification.py \
+python BioMod/interpretability/biomod_importance/marker_gene_verification.py \
     --importance_matrix outputs/interpretability/importance/zheng68k_pre_13690/importance_matrix.npy \
     --importance_csv <importance_matrix.csv> \
-    --module_data_dir model_dependencies/module_data_all \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --output_dir outputs/interpretability/importance/marker_verification/
 ```
 
 ### Publication Figures
 
 ```bash
-python BioMod/interpretability/module_importance/module_importance_publication.py \
+python BioMod/interpretability/biomod_importance/biomod_importance_publication.py \
     --results_dir outputs/interpretability/importance/zheng68k_pre_13690/ \
     --ablation_dir outputs/interpretability/importance/ablation \
     --permutation_dir outputs/interpretability/importance/permutation/ \
-    --module_data_dir model_dependencies/module_data_all \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --output_dir outputs/interpretability/importance/publication_figures/
 ```
 
@@ -206,7 +206,7 @@ Analyze importance distributions, contribution fractions, and enrichment tests b
 module source family: Hallmarks, Reactome, Hotspot, and WGCNA.
 
 ```bash
-python BioMod/interpretability/module_importance/family_importance_analysis.py \
+python BioMod/interpretability/biomod_importance/family_importance_analysis.py \
     --results_dir outputs/interpretability/importance/zheng68k_pre \
     --output_dir outputs/interpretability/importance/family_analysis \
     --top_k 10 20 50 \
@@ -231,10 +231,10 @@ Ablate whole families by removing or keeping one module family and measuring
 classification-accuracy changes.
 
 ```bash
-python BioMod/interpretability/module_importance/family_ablation.py \
+python BioMod/interpretability/biomod_importance/family_ablation.py \
     --finetune_checkpoint tutorial_runs/cell_annotation_zheng68k_biomod/best_model.pt \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --module_data_dir model_dependencies/module_data_all \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -257,7 +257,7 @@ Analyze correlations and similarity between important modules across the 11 cell
 classes.
 
 ```bash
-python BioMod/interpretability/module_importance/cross_class_similarity.py \
+python BioMod/interpretability/biomod_importance/cross_class_similarity.py \
     --results_dir outputs/interpretability/importance/zheng68k_pre \
     --output_dir outputs/interpretability/importance/publication_figures \
     --top_k 50
@@ -275,10 +275,10 @@ parameters are trained from zero initialization.
 
 ```bash
 # Baseline, no new modules.
-python BioMod/cell_annotation/performer_module_finetune.py \
-    --config_pkl weight/0810model/mae_tost_70M_75mask_ec2.pkl \
-    --performer_checkpoint weight/0810model/mae_tost_70M_75mask_ec2_epoch0.pth \
-    --module_data_dir model_dependencies/module_data_all \
+python BioMod/cell_annotation/biomod_finetune.py \
+    --config_pkl weight/BioMod.pkl \
+    --biomod_checkpoint weight/BioMod.pth \
+    --biomod_data_dir model_dependencies/biomod_data_all \
     --gene_list_path model_dependencies/selected_genes_27k.txt \
     --gene_mapping_path model_dependencies/gene2ens.csv \
     --gene2vec_data_path model_dependencies/selected_gene2vec_27k.npy \
@@ -296,7 +296,7 @@ python BioMod/cell_annotation/performer_module_finetune.py \
 The same command can be extended with:
 
 - `--use_family_emb` to enable family-type embedding, adding `4 x 200 = 800` parameters.
-- `--use_module_gate` to enable sparse module gating, adding LayerNorm + Linear, 601 parameters.
+- `--use_biomod_gate` to enable sparse module gating, adding LayerNorm + Linear, 601 parameters.
 - Both flags can be used together.
 
 The new module parameters use `lr_head`, a higher learning rate, and are
@@ -306,11 +306,11 @@ independent of frozen backbone parameters.
 
 | File | Description |
 | --- | --- |
-| `module_importance.py` | Core importance computation with DDP support |
+| `biomod_importance.py` | Core importance computation with DDP support |
 | `masking_ablation.py` | Ablation-curve experiment, GPU |
 | `random_baseline.py` | Permutation tests, GPU/CPU |
 | `marker_gene_verification.py` | Marker verification, CPU |
-| `module_importance_publication.py` | Publication figures |
+| `biomod_importance_publication.py` | Publication figures |
 | `family_importance_analysis.py` | Family-level importance analysis, CPU |
 | `family_ablation.py` | Family-level ablation, GPU |
 | `cross_class_similarity.py` | Cross-class similarity analysis, CPU |

BioMod/interpretability/{module_importance → biomod_importance}/RESULTS.md

@@ -5,7 +5,7 @@
 ## Dataset
 
 - **Zheng68K**: 11 cell types, 68,450 cells, with 13,690 test cells.
-- Model: PerformerModuleCellClassifier with attention-pooling head and 48M backbone.
+- Model: BioModCellClassifier with attention-pooling head and 48M backbone.
 - Baseline test accuracy: **83.1%**.
 
 ## Data Sources
@@ -13,9 +13,9 @@
 These are historical experiment results. The analysis output files below are not
 included in the repository; recreate them using the commands in `README.md` or
 point the analysis scripts to the original run directory. The shared module JSON
-is bundled under `model_dependencies/module_data_all/` at the repository root.
+is bundled under `model_dependencies/biomod_data_all/` at the repository root.
 
-All analyses are based on the following core files, generated by `module_importance.py`
+All analyses are based on the following core files, generated by `biomod_importance.py`
 with `pre_encoder` over all 13,690 test cells:
 
 | File | Path | Description |
@@ -24,10 +24,10 @@ with `pre_encoder` over all 13,690 test cells:
 | `importance_matrix.csv` | `outputs/interpretability/importance/zheng68k_pre_13690/importance_matrix.csv` | Same matrix with row and column labels |
 | `enrichment_results.csv` | `outputs/interpretability/importance/zheng68k_pre_13690/enrichment_results.csv` | Enrichment-test results |
 | `top_modules_per_celltype.json` | `outputs/interpretability/importance/zheng68k_pre_13690/top_modules_per_celltype.json` | Top-module details |
-| `merged_modules.json` | `model_dependencies/module_data_all/merged_modules.json` | Gene composition of 660 modules |
+| `merged_biomods.json` | `model_dependencies/biomod_data_all/merged_biomods.json` | Gene composition of 660 modules |
 
 Marker verification uses `importance_matrix.npy`, `importance_matrix.csv`, and
-`merged_modules.json`.
+`merged_biomods.json`.
 
 Publication figures use all files above plus ablation and permutation results.
 

BioMod/interpretability/{module_importance → biomod_importance}/TODO.md

@@ -14,7 +14,7 @@
 - [x] `marker_gene_verification.py`: canonical marker verification.
   - Result: 80% of markers are in the top 5%, median percentile = 0.9%.
   - Figures: `fig_marker_ranks.pdf`, `fig_marker_summary_bar.pdf`.
-- [x] `module_importance_publication.py`: publication-figure generator.
+- [x] `biomod_importance_publication.py`: publication-figure generator.
 - [x] `RESULTS.md`: result documentation.
 - [x] `TODO.md`: this file.
 

BioMod/interpretability/{module_importance/module_importance.py → biomod_importance/biomod_importance.py}

@@ -33,10 +33,10 @@
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 INTERP_DIR = SCRIPT_DIR.parent
-PERFORMER_MODULE_ROOT = INTERP_DIR.parent
-SCLONG_ROOT = PERFORMER_MODULE_ROOT.parent
+BIOMOD_ROOT = INTERP_DIR.parent
+SCLONG_ROOT = BIOMOD_ROOT.parent
 
-for p in (str(PERFORMER_MODULE_ROOT), str(SCLONG_ROOT)):
+for p in (str(BIOMOD_ROOT), str(SCLONG_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
@@ -89,8 +89,8 @@ def __getitem__(self, idx):
 
 def load_finetuned_model(args, device: torch.device):
     """Load the full finetuned classifier (backbone + pooler + head)."""
-    from models_performer_module import PerformerEncoderOnly_Module
-    from module_dataset import load_module_data
+    from models_biomod import BioMod
+    from biomod_dataset import load_biomod_data
 
     ckpt_path = Path(args.finetune_checkpoint)
     checkpoint = torch.load(ckpt_path, map_location=device)
@@ -106,13 +106,13 @@ def load_finetuned_model(args, device: torch.device):
         with open(config_pkl_path, "rb") as f:
             config_pkl = pickle.load(f)
 
-    module_data = None
+    biomod_data = None
     if isinstance(config_pkl, dict) and "module_sets" in config_pkl:
-        module_data = config_pkl["module_sets"]
+        biomod_data = config_pkl["module_sets"]
     elif "module_sets" in backbone_config:
-        module_data = backbone_config["module_sets"]
+        biomod_data = backbone_config["module_sets"]
     else:
-        module_data = load_module_data(
+        biomod_data = load_biomod_data(
             module_data_dir=args.module_data_dir,
             gene_list_path=args.gene_list_path,
             gene_mapping_path=args.gene_mapping_path,
@@ -141,10 +141,10 @@ def load_finetuned_model(args, device: torch.device):
     dec_heads = backbone_config.get("dec_heads", 8)
     dec_dim_head = backbone_config.get("dec_dim_head", 64)
 
-    backbone = PerformerEncoderOnly_Module(
-        module_sets=module_data,
+    backbone = BioMod(
+        module_sets=biomod_data,
         num_genes=num_genes,
-        max_seq_len=len(module_data),
+        max_seq_len=len(biomod_data),
         base_dim=base_dim,
         enc_depth=enc_depth,
         enc_heads=enc_heads,
@@ -171,10 +171,10 @@ def load_finetuned_model(args, device: torch.device):
         dec_dim_head=dec_dim_head,
     )
 
-    sys.path.insert(0, str(PERFORMER_MODULE_ROOT / "cell_annotation"))
-    from performer_module_finetune import (
+    sys.path.insert(0, str(BIOMOD_ROOT / "cell_annotation"))
+    from biomod_finetune import (
         GatedAttentionPool,
-        PerformerModuleCellClassifier,
+        BioModCellClassifier,
         ScGPTClsDecoder,
     )
 
@@ -183,9 +183,9 @@ def load_finetuned_model(args, device: torch.device):
     pool_hidden_dim = saved_args.get("pool_hidden_dim", 0)
     cls_decoder_layers = saved_args.get("cls_decoder_layers", 3)
 
-    model = PerformerModuleCellClassifier(
+    model = BioModCellClassifier(
         backbone=backbone,
-        module_sets=module_data,
+        module_sets=biomod_data,
         num_classes=num_classes,
         head_type=head_type,
         pool_hidden_dim=pool_hidden_dim,
@@ -199,9 +199,9 @@ def load_finetuned_model(args, device: torch.device):
 
     logger.info(
         "Loaded finetuned model: head=%s, classes=%d, modules=%d",
-        head_type, num_classes, len(module_data),
+        head_type, num_classes, len(biomod_data),
     )
-    return model, module_data, label_classes, head_type
+    return model, biomod_data, label_classes, head_type
 
 
 # ─── Data Loading ───────────────────────────────────────────────────────────
@@ -210,8 +210,8 @@ def load_test_data(args, label_classes: List[str], device: torch.device):
     """Load Zheng68K and reproduce the test split."""
     import anndata as ad
 
-    sys.path.insert(0, str(PERFORMER_MODULE_ROOT / "cell_annotation"))
-    from performer_module_finetune import DataPreprocessor
+    sys.path.insert(0, str(BIOMOD_ROOT / "cell_annotation"))
+    from biomod_finetune import DataPreprocessor
 
     preprocessor = DataPreprocessor(
         gene2ens_file=args.gene2ens_file,
@@ -276,7 +276,7 @@ def compute_importance_post_encoder(
         if model.head_type == "cls":
             module_tokens = latent[:, 1:, :]
         else:
-            module_tokens = model._restore_module_order(latent, ids_restore)
+            module_tokens = model._restore_biomod_order(latent, ids_restore)
 
         baseline_logits = _classify_from_tokens(model, module_tokens)
         y_tensor = torch.from_numpy(y_batch).to(device)
@@ -340,7 +340,7 @@ def _classify_from_tokens(model: nn.Module, module_tokens: torch.Tensor) -> torc
     elif model.head_type == "attn_pool":
         cell_emb, _ = model.pooler(module_tokens)
     elif model.head_type == "gene_mean":
-        gene_tokens = model._module_to_gene(module_tokens)
+        gene_tokens = model._biomod_to_gene(module_tokens)
         cell_emb = gene_tokens.mean(dim=1)
     else:
         raise ValueError(f"Unsupported head_type: {model.head_type}")
@@ -533,12 +533,12 @@ def run_enrichment(
 
 # ─── Module Gene Mapping ─────────────────────────────────────────────────────
 
-def build_module_gene_mapping(
+def build_biomod_gene_mapping(
     module_data_dir: str,
     gene_list_path: str,
 ) -> Tuple[List[str], Dict[str, List[str]]]:
     """Return (module_names, {module_name: [gene_symbols]})."""
-    merged_path = Path(module_data_dir) / "merged_modules.json"
+    merged_path = Path(module_data_dir) / "merged_biomods.json"
     with open(merged_path, "r") as f:
         merged = json.load(f)
 
@@ -582,7 +582,7 @@ def plot_importance_heatmap(
     logger.info("Saved heatmap: %s", output_path)
 
 
-def plot_top_modules_bar(
+def plot_top_biomods_bar(
     importance: np.ndarray,
     label_classes: List[str],
     module_names: List[str],
@@ -628,8 +628,8 @@ def parse_args():
                    help="Path to best_model.pt from cell annotation finetuning")
     p.add_argument("--config_pkl", required=True,
                    help="Path to pretrained model .pkl config")
-    p.add_argument("--module_data_dir", required=True,
-                   help="Directory containing merged_modules.json")
+    p.add_argument("--biomod_data_dir", "--module_data_dir", required=True,
+                   help="Directory containing merged_biomods.json", dest='module_data_dir')
     p.add_argument("--gene_list_path", required=True,
                    help="Path to selected_genes_27k.txt")
     p.add_argument("--gene_mapping_path", required=True)
@@ -677,8 +677,8 @@ def main():
             setattr(args, attr, str(Path(val).resolve()))
 
     logger.info("Loading finetuned model...")
-    model, module_data, label_classes, head_type = load_finetuned_model(args, device)
-    num_modules = len(module_data)
+    model, biomod_data, label_classes, head_type = load_finetuned_model(args, device)
+    num_modules = len(biomod_data)
     num_classes = len(label_classes)
 
     logger.info("Loading test data...")
@@ -752,7 +752,7 @@ def main():
     # Only rank 0 does enrichment, plotting, saving
     if rank == 0:
         logger.info("Building module-gene mapping...")
-        module_names, module_gene_symbols = build_module_gene_mapping(
+        module_names, module_gene_symbols = build_biomod_gene_mapping(
             args.module_data_dir, args.gene_list_path
         )
 
@@ -810,7 +810,7 @@ def main():
         plot_importance_heatmap(
             importance, label_classes, output_dir / "heatmap_importance.png"
         )
-        plot_top_modules_bar(
+        plot_top_biomods_bar(
             importance, label_classes, module_names, output_dir
         )
 

BioMod/interpretability/{module_importance/module_importance_publication.py → biomod_importance/biomod_importance_publication.py}

@@ -31,9 +31,9 @@
 from pub_utils import (
     CELL_TYPE_COLORS,
     MODULE_FAMILY_COLORS,
-    get_module_families,
+    get_biomod_families,
     load_importance_results,
-    load_module_gene_mapping,
+    load_biomod_gene_mapping,
     savefig,
     setup_publication_style,
 )
@@ -204,7 +204,7 @@ def plot_importance_heatmap_clustered(results_dir, module_data_dir, output_dir):
     label_classes = data["label_classes"]
     module_names = data["module_names"]
 
-    families = get_module_families(module_names)
+    families = get_biomod_families(module_names)
     family_colors = [MODULE_FAMILY_COLORS.get(f, "#CCCCCC") for f in families]
 
     # Cluster modules
@@ -329,8 +329,8 @@ def parse_args():
                    help="Ablation results directory")
     p.add_argument("--permutation_dir",
                    help="Permutation results directory")
-    p.add_argument("--module_data_dir", required=True,
-                   help="Module data directory (merged_modules.json)")
+    p.add_argument("--biomod_data_dir", "--module_data_dir", required=True,
+                   help="Module data directory (merged_biomods.json)", dest='module_data_dir')
     p.add_argument("--output_dir", required=True)
     return p.parse_args()
 

BioMod/interpretability/{module_importance → biomod_importance}/family_ablation.py

@@ -29,10 +29,10 @@
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 INTERP_DIR = SCRIPT_DIR.parent
-PERFORMER_MODULE_ROOT = INTERP_DIR.parent
-SCLONG_ROOT = PERFORMER_MODULE_ROOT.parent
+BIOMOD_ROOT = INTERP_DIR.parent
+SCLONG_ROOT = BIOMOD_ROOT.parent
 
-for p in (str(SCRIPT_DIR), str(PERFORMER_MODULE_ROOT), str(SCLONG_ROOT)):
+for p in (str(SCRIPT_DIR), str(BIOMOD_ROOT), str(SCLONG_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
@@ -40,10 +40,10 @@
     compute_masked_accuracy_post_encoder,
     encode_all_cells,
 )
-from module_importance import (
+from biomod_importance import (
     CellDataset,
     _classify_from_tokens,
-    build_module_gene_mapping,
+    build_biomod_gene_mapping,
     load_finetuned_model,
     load_test_data,
 )
@@ -296,7 +296,7 @@ def parse_args():
     p = argparse.ArgumentParser(description="Family-level ablation experiment")
     p.add_argument("--finetune_checkpoint", required=True)
     p.add_argument("--config_pkl", required=True)
-    p.add_argument("--module_data_dir", required=True)
+    p.add_argument("--biomod_data_dir", "--module_data_dir", required=True, dest='module_data_dir')
     p.add_argument("--gene_list_path", required=True)
     p.add_argument("--gene_mapping_path", required=True)
     p.add_argument("--gene2vec_data_path", required=True)
@@ -329,8 +329,8 @@ def main():
             setattr(args, attr, str(Path(val).resolve()))
 
     logger.info("Loading model...")
-    model, module_data, label_classes, head_type = load_finetuned_model(args, device)
-    module_names, _ = build_module_gene_mapping(args.module_data_dir, args.gene_list_path)
+    model, biomod_data, label_classes, head_type = load_finetuned_model(args, device)
+    module_names, _ = build_biomod_gene_mapping(args.module_data_dir, args.gene_list_path)
     family_indices = get_family_indices(module_names)
     for fam in FAMILY_ORDER:
         logger.info("  %s: %d modules", fam, len(family_indices[fam]))

BioMod/interpretability/{module_importance → biomod_importance}/marker_gene_verification.py

@@ -28,11 +28,11 @@
 from pub_utils import (
     CANONICAL_MARKERS,
     CELL_TYPE_COLORS,
-    find_gene_modules,
-    get_module_family,
+    find_gene_biomods,
+    get_biomod_family,
     importance_rank_percentile,
     load_importance_results,
-    load_module_gene_mapping,
+    load_biomod_gene_mapping,
     savefig,
     setup_publication_style,
 )
@@ -55,7 +55,7 @@ def compute_marker_ranks(
         ranked_indices = np.argsort(-imp_row)
 
         for marker in markers:
-            containing_modules = find_gene_modules(marker, module_gene_symbols)
+            containing_modules = find_gene_biomods(marker, module_gene_symbols)
             if not containing_modules:
                 rows.append({
                     "cell_type": cls_name,
@@ -89,7 +89,7 @@ def compute_marker_ranks(
                 "found_in_modules": True,
                 "num_modules_containing": len(containing_modules),
                 "best_module": module_names[best_pi],
-                "best_module_family": get_module_family(module_names[best_pi]),
+                "best_module_family": get_biomod_family(module_names[best_pi]),
                 "best_rank": best_rank + 1,
                 "rank_percentile": 100.0 * best_rank / num_modules,
                 "best_importance": float(imp_row[best_pi]),
@@ -252,8 +252,8 @@ def parse_args():
                    help="Path to importance_matrix.npy")
     p.add_argument("--importance_csv", required=True,
                    help="Path to importance_matrix.csv (for labels)")
-    p.add_argument("--module_data_dir", required=True,
-                   help="Directory containing merged_modules.json")
+    p.add_argument("--biomod_data_dir", "--module_data_dir", required=True,
+                   help="Directory containing merged_biomods.json", dest='module_data_dir')
     p.add_argument("--output_dir", required=True)
     return p.parse_args()
 
@@ -268,7 +268,7 @@ def main():
     label_classes = list(imp_csv.index)
     module_names = list(imp_csv.columns)
 
-    _, module_gene_symbols = load_module_gene_mapping(args.module_data_dir)
+    _, module_gene_symbols = load_biomod_gene_mapping(args.module_data_dir)
 
     print(f"Importance matrix: {importance.shape}")
     print(f"Cell types: {len(label_classes)}")

BioMod/interpretability/{module_importance → biomod_importance}/masking_ablation.py

@@ -29,14 +29,14 @@
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 INTERP_DIR = SCRIPT_DIR.parent
-PERFORMER_MODULE_ROOT = INTERP_DIR.parent
-SCLONG_ROOT = PERFORMER_MODULE_ROOT.parent
+BIOMOD_ROOT = INTERP_DIR.parent
+SCLONG_ROOT = BIOMOD_ROOT.parent
 
-for p in (str(SCRIPT_DIR), str(PERFORMER_MODULE_ROOT), str(SCLONG_ROOT)):
+for p in (str(SCRIPT_DIR), str(BIOMOD_ROOT), str(SCLONG_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from module_importance import (
+from biomod_importance import (
     CellDataset,
     _classify_from_tokens,
     load_finetuned_model,
@@ -63,7 +63,7 @@ def encode_all_cells(model, dataloader, preprocessor, reindex_state, device):
         if model.head_type == "cls":
             module_tokens = latent[:, 1:, :]
         else:
-            module_tokens = model._restore_module_order(latent, ids_restore)
+            module_tokens = model._restore_biomod_order(latent, ids_restore)
         all_tokens.append(module_tokens.cpu())
         all_labels.append(y_batch.numpy())
 
@@ -248,7 +248,7 @@ def parse_args():
     p = argparse.ArgumentParser(description="Masking ablation curves")
     p.add_argument("--finetune_checkpoint", required=True)
     p.add_argument("--config_pkl", required=True)
-    p.add_argument("--module_data_dir", required=True)
+    p.add_argument("--biomod_data_dir", "--module_data_dir", required=True, dest='module_data_dir')
     p.add_argument("--gene_list_path", required=True)
     p.add_argument("--gene_mapping_path", required=True)
     p.add_argument("--gene2vec_data_path", required=True)
@@ -290,8 +290,8 @@ def main():
             setattr(args, attr, str(Path(val).resolve()))
 
     logger.info("Loading model...")
-    model, module_data, label_classes, head_type = load_finetuned_model(args, device)
-    num_modules = len(module_data)
+    model, biomod_data, label_classes, head_type = load_finetuned_model(args, device)
+    num_modules = len(biomod_data)
 
     logger.info("Loading test data...")
     X_test, y_test, le, preprocessor, reindex_state = load_test_data(

BioMod/interpretability/{module_importance → biomod_importance}/pub_utils.py

@@ -140,15 +140,15 @@ def load_importance_results(results_dir) -> dict:
     return data
 
 
-def load_module_gene_mapping(module_data_dir) -> Tuple[List[str], Dict[str, List[str]]]:
-    """Load merged_modules.json and return (module_names, module_gene_symbols).
+def load_biomod_gene_mapping(module_data_dir) -> Tuple[List[str], Dict[str, List[str]]]:
+    """Load merged_biomods.json and return (module_names, module_gene_symbols).
 
     Returns:
         module_names: ordered list of module names
         module_gene_symbols: dict mapping module_name -> list of gene symbols
     """
     module_data_dir = Path(module_data_dir)
-    with open(module_data_dir / "merged_modules.json") as f:
+    with open(module_data_dir / "merged_biomods.json") as f:
         modules = json.load(f)
     module_names = list(modules.keys())
     module_gene_symbols = {}
@@ -160,7 +160,7 @@ def load_module_gene_mapping(module_data_dir) -> Tuple[List[str], Dict[str, List
     return module_names, module_gene_symbols
 
 
-def get_module_family(module_name: str) -> str:
+def get_biomod_family(module_name: str) -> str:
     """Determine which family a module belongs to based on its name prefix."""
     if module_name.startswith("module1_hallmarks"):
         return "Hallmarks"
@@ -173,14 +173,14 @@ def get_module_family(module_name: str) -> str:
     return "Unknown"
 
 
-def get_module_families(module_names: List[str]) -> List[str]:
+def get_biomod_families(module_names: List[str]) -> List[str]:
     """Get family labels for a list of module names."""
-    return [get_module_family(p) for p in module_names]
+    return [get_biomod_family(p) for p in module_names]
 
 
 # ─── Analysis Helpers ────────────────────────────────────────────────────────
 
-def find_gene_modules(
+def find_gene_biomods(
     gene_symbol: str, module_gene_symbols: Dict[str, List[str]]
 ) -> List[str]:
     """Find all modules containing a given gene symbol."""

BioMod/interpretability/{module_importance → biomod_importance}/random_baseline.py

@@ -27,14 +27,14 @@
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 INTERP_DIR = SCRIPT_DIR.parent
-PERFORMER_MODULE_ROOT = INTERP_DIR.parent
-SCLONG_ROOT = PERFORMER_MODULE_ROOT.parent
+BIOMOD_ROOT = INTERP_DIR.parent
+SCLONG_ROOT = BIOMOD_ROOT.parent
 
-for p in (str(SCRIPT_DIR), str(PERFORMER_MODULE_ROOT), str(SCLONG_ROOT)):
+for p in (str(SCRIPT_DIR), str(BIOMOD_ROOT), str(SCLONG_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from module_importance import (
+from biomod_importance import (
     CellDataset,
     _classify_from_tokens,
     load_finetuned_model,
@@ -48,7 +48,7 @@
 # ─── Mode A: Shuffle Modules (GPU) ──────────────────────────────────────────
 
 @torch.no_grad()
-def compute_importance_shuffled_modules(
+def compute_importance_shuffled_biomods(
     model, dataloader, preprocessor, reindex_state,
     num_modules, num_classes, device, seed,
 ):
@@ -77,7 +77,7 @@ def compute_importance_shuffled_modules(
         if model.head_type == "cls":
             module_tokens = latent[:, 1:, :]
         else:
-            module_tokens = model._restore_module_order(latent, ids_restore)
+            module_tokens = model._restore_biomod_order(latent, ids_restore)
 
         # Permute module token order (breaks module identity)
         module_tokens_shuffled = module_tokens[:, perm, :]
@@ -206,7 +206,7 @@ def parse_args():
     # Model args (for shuffle_modules mode)
     p.add_argument("--finetune_checkpoint")
     p.add_argument("--config_pkl")
-    p.add_argument("--module_data_dir")
+    p.add_argument("--biomod_data_dir", "--module_data_dir", dest='module_data_dir')
     p.add_argument("--gene_list_path")
     p.add_argument("--gene_mapping_path")
     p.add_argument("--gene2vec_data_path")
@@ -256,7 +256,7 @@ def main():
                 setattr(args, attr, str(Path(val).resolve()))
 
         logger.info("Loading model for shuffle_modules mode...")
-        model, module_data, label_classes, _ = load_finetuned_model(args, device)
+        model, biomod_data, label_classes, _ = load_finetuned_model(args, device)
 
         logger.info("Loading test data...")
         X_test, y_test, le, preprocessor, reindex_state = load_test_data(
@@ -273,7 +273,7 @@ def main():
         )
         for pi in range(n_perms_a):
             logger.info("  Permutation %d/%d...", pi + 1, n_perms_a)
-            null_module_shuffle[pi] = compute_importance_shuffled_modules(
+            null_module_shuffle[pi] = compute_importance_shuffled_biomods(
                 model, dataloader, preprocessor, reindex_state,
                 num_modules, num_classes, device,
                 seed=args.seed + pi + 1000,

BioMod/interpretability/{module_text_alignment → biomod_text_alignment}/DESIGN.md

@@ -11,15 +11,15 @@ gene names do not carry phrase-level semantics.
 
 | Script | Function |
 | --- | --- |
-| `module_text_alignment.py` | Main script: RSA/Mantel test, CKA, and leave-one-out Ridge retrieval |
-| `module_text_alignment_extended.py` | Extended analysis: Reactome broad-category RSA, Reactome description-based RSA, and Hallmark deep dive |
-| `module_text_alignment_publication.py` | Publication-level analysis: six main figures, bootstrap CIs, multi-model comparison, cross-dataset validation, and deep analysis |
+| `biomod_text_alignment.py` | Main script: RSA/Mantel test, CKA, and leave-one-out Ridge retrieval |
+| `biomod_text_alignment_extended.py` | Extended analysis: Reactome broad-category RSA, Reactome description-based RSA, and Hallmark deep dive |
+| `biomod_text_alignment_publication.py` | Publication-level analysis: six main figures, bootstrap CIs, multi-model comparison, cross-dataset validation, and deep analysis |
 | `fetch_reactome_descriptions.py` | Fetch `summaryText` for 491 pathways from the Reactome API |
 
 ## Commands
 
 Run from the BioMod repository root. Generate each `module_embeddings.npy` with
-`BioMod/interpretability/module_geometry.py` before using it here. The historical
+`BioMod/interpretability/biomod_geometry.py` before using it here. The historical
 `pretrain_subset` output requires a separately supplied pretraining dataset;
 the `pancreas_scib` example uses the bundled pancreas h5ad file. Existing result
 tables below describe historical runs; their raw output directories are not
@@ -41,24 +41,24 @@ pip install sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple
 
 ```bash
 # pretrain_subset is recommended because averaging over 50k cells is more stable.
-python BioMod/interpretability/module_text_alignment/module_text_alignment.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
     --n_permutations 1000 \
     --output_dir outputs/interpretability/text_alignment/pretrain_subset_v2
 
 # pancreas_scib validates cross-dataset consistency.
-python BioMod/interpretability/module_text_alignment/module_text_alignment.py \
-    --module_embedding_path outputs/interpretability/geometry/pancreas_scib/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pancreas_scib/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
     --n_permutations 1000 \
     --output_dir outputs/interpretability/text_alignment/pancreas_scib_v2
 
 # Quick mode: skip LOO retrieval and run only RSA + CKA.
-python BioMod/interpretability/module_text_alignment/module_text_alignment.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
     --skip_loo \
     --output_dir outputs/interpretability/text_alignment/pretrain_subset_quick
@@ -68,24 +68,24 @@ python BioMod/interpretability/module_text_alignment/module_text_alignment.py \
 
 ```bash
 # Re-fetch if needed. Requires network access to reactome.org and takes about 2 minutes.
-python BioMod/interpretability/module_text_alignment/fetch_reactome_descriptions.py \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/fetch_reactome_descriptions.py \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --output reactome_descriptions.json --delay 0.05
 ```
 
 The command writes refreshed descriptions to `reactome_descriptions.json` in the
 repository root. The analysis examples below use the bundled
-`BioMod/interpretability/module_text_alignment/reactome_descriptions.json` instead;
+`BioMod/interpretability/biomod_text_alignment/reactome_descriptions.json` instead;
 set `--descriptions_file reactome_descriptions.json` to use the refreshed output.
 
 ### 4. Extended Analysis: Reactome Categories, Description-Based RSA, Hallmark Deep Dive
 
 ```bash
-python BioMod/interpretability/module_text_alignment/module_text_alignment_extended.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment_extended.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
-    --descriptions_file BioMod/interpretability/module_text_alignment/reactome_descriptions.json \
+    --descriptions_file BioMod/interpretability/biomod_text_alignment/reactome_descriptions.json \
     --n_permutations 1000 \
     --output_dir outputs/interpretability/text_alignment/pretrain_subset_v2_extended
 ```
@@ -94,23 +94,23 @@ python BioMod/interpretability/module_text_alignment/module_text_alignment_exten
 
 ```bash
 # Basic run: one dataset and one model.
-python BioMod/interpretability/module_text_alignment/module_text_alignment_publication.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment_publication.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
-    --descriptions_file BioMod/interpretability/module_text_alignment/reactome_descriptions.json \
+    --descriptions_file BioMod/interpretability/biomod_text_alignment/reactome_descriptions.json \
     --n_permutations 1000 \
     --n_bootstrap 2000 \
     --output_dir outputs/interpretability/text_alignment/publication
 
 # Full run: cross-dataset validation and multi-model comparison.
-python BioMod/interpretability/module_text_alignment/module_text_alignment_publication.py \
-    --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-    --module_embedding_path2 outputs/interpretability/geometry/pancreas_scib/module_embeddings.npy \
-    --module_json model_dependencies/module_data_all/merged_modules.json \
+python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment_publication.py \
+    --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+    --biomod_embedding_path2 outputs/interpretability/geometry/pancreas_scib/module_embeddings.npy \
+    --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
     --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
     --sentence_models_compare "sentence-transformers/all-mpnet-base-v2,sentence-transformers/all-MiniLM-L6-v2" \
-    --descriptions_file BioMod/interpretability/module_text_alignment/reactome_descriptions.json \
+    --descriptions_file BioMod/interpretability/biomod_text_alignment/reactome_descriptions.json \
     --n_permutations 1000 \
     --n_bootstrap 2000 \
     --output_dir outputs/interpretability/text_alignment/publication_full
@@ -120,8 +120,8 @@ python BioMod/interpretability/module_text_alignment/module_text_alignment_publi
 
 | Argument | Description |
 | --- | --- |
-| `--module_embedding_path` | `module_embeddings.npy` for the main dataset, from Experiment 1 |
-| `--module_embedding_path2` | Optional second dataset for cross-dataset validation |
+| `--biomod_embedding_path` | `module_embeddings.npy` for the main dataset, from Experiment 1 |
+| `--biomod_embedding_path2` | Optional second dataset for cross-dataset validation |
 | `--sentence_models_compare` | Comma-separated model names for comparison, downloaded automatically from HuggingFace |
 | `--n_permutations` | Mantel-test permutations; 1000 is standard and 10000 gives more precise p-values |
 | `--n_bootstrap` | Bootstrap resampling iterations; 2000 is standard for 95% CIs |
@@ -135,7 +135,7 @@ pip install sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple
 
 ## Output Files
 
-### Main Experiment Outputs (`module_text_alignment.py`)
+### Main Experiment Outputs (`biomod_text_alignment.py`)
 
 | File | Content |
 | --- | --- |
@@ -149,7 +149,7 @@ pip install sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple
 | `retrieval_examples.csv` | Top-5 retrieval results for representative pathways |
 | `run.log` | Full log |
 
-### Extended Analysis Outputs (`module_text_alignment_extended.py`)
+### Extended Analysis Outputs (`biomod_text_alignment_extended.py`)
 
 | File | Content |
 | --- | --- |
@@ -159,7 +159,7 @@ pip install sentence-transformers -i https://pypi.tuna.tsinghua.edu.cn/simple
 | `hallmarks_per_module_alignment.csv` | Per-module alignment ranking for 50 Hallmarks |
 | `run_extended.log` | Extended-analysis log |
 
-### Publication-Level Outputs (`module_text_alignment_publication.py`)
+### Publication-Level Outputs (`biomod_text_alignment_publication.py`)
 
 | File | Content |
 | --- | --- |

BioMod/interpretability/{module_text_alignment/module_text_alignment.py → biomod_text_alignment/biomod_text_alignment.py}

@@ -10,7 +10,7 @@
 
 Pipeline
 --------
-1. Parse pathway names from merged_modules.json keys for Hallmarks (50) and
+1. Parse pathway names from merged_biomods.json keys for Hallmarks (50) and
    Reactome (491) modules. Hotspot/Processed are excluded (no semantic names).
 2. Encode pathway names with a biomedical sentence encoder.
 3. Load cell-averaged module embeddings from experiment 1 output.
@@ -58,16 +58,16 @@
 
 HERE = Path(__file__).resolve().parent
 INTERP_DIR = HERE.parent
-PERFORMER_MODULE = INTERP_DIR.parent
-REPO_ROOT = PERFORMER_MODULE.parent
-for p in (str(INTERP_DIR), str(PERFORMER_MODULE), str(REPO_ROOT)):
+BIOMOD_SOURCE = INTERP_DIR.parent
+REPO_ROOT = BIOMOD_SOURCE.parent
+for p in (str(INTERP_DIR), str(BIOMOD_SOURCE), str(REPO_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
 from interpretability.utils import (
     MODULE_FAMILY_MAP,
-    load_module_names,
-    parse_module_family,
+    load_biomod_names,
+    parse_biomod_family,
 )
 
 logger = logging.getLogger(__name__)
@@ -79,7 +79,7 @@
 
 def parse_pathway_text(module_name: str) -> Optional[str]:
     """Extract a human-readable pathway name from a module key."""
-    family = parse_module_family(module_name)
+    family = parse_biomod_family(module_name)
     if family == "Hallmarks":
         raw = module_name.split("__", 1)[1]
         raw = raw.replace("HALLMARK_", "", 1)
@@ -218,7 +218,7 @@ def compute_rsa_by_family(
 ) -> Dict[str, Dict[str, float]]:
     """RSA computed separately for each module family (Hallmarks vs Reactome)."""
     results = {}
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     for fam in ["Hallmarks", "Reactome"]:
         mask = np.array([f == fam for f in families])
         if mask.sum() < 10:
@@ -447,11 +447,11 @@ def parse_args() -> argparse.Namespace:
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument("--module_embedding_path", type=str, required=True,
-                        help="Path to module_embeddings.npy from experiment 1.")
-    parser.add_argument("--module_json", type=str,
-                        default=str(REPO_ROOT / "model_dependencies" / "module_data_all" / "merged_modules.json"),
-                        help="Path to merged_modules.json.")
+    parser.add_argument("--biomod_embedding_path", "--module_embedding_path", type=str, required=True,
+                        help="Path to module_embeddings.npy from experiment 1.", dest='module_embedding_path')
+    parser.add_argument("--biomod_json", "--module_json", type=str,
+                        default=str(REPO_ROOT / "model_dependencies" / "biomod_data_all" / "merged_biomods.json"),
+                        help="Path to merged_biomods.json.", dest='module_json')
     parser.add_argument("--descriptions_file", type=str, default=None,
                         help="Optional JSON with extended pathway descriptions.")
     parser.add_argument("--sentence_model", type=str,
@@ -487,7 +487,7 @@ def main():
 
     # --- Load module names and embeddings ---
     logger.info("Loading module names from %s", args.module_json)
-    module_names = load_module_names(args.module_json)
+    module_names = load_biomod_names(args.module_json)
     logger.info("Total modules: %d", len(module_names))
 
     logger.info("Loading module embeddings from %s", args.module_embedding_path)

BioMod/interpretability/{module_text_alignment/module_text_alignment_extended.py → biomod_text_alignment/biomod_text_alignment_extended.py}

@@ -6,9 +6,9 @@
 3. Hallmarks deep dive (per-module alignment scores, heatmap)
 
 Usage (run from the BioMod repository root):
-    python BioMod/interpretability/module_text_alignment/module_text_alignment_extended.py \
-        --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-        --module_json model_dependencies/module_data_all/merged_modules.json \
+    python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment_extended.py \
+        --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+        --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
         --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
         --output_dir outputs/interpretability/text_alignment/pretrain_subset_v2_extended
 """
@@ -36,14 +36,14 @@
 
 HERE = Path(__file__).resolve().parent
 INTERP_DIR = HERE.parent
-PERFORMER_MODULE = INTERP_DIR.parent
-REPO_ROOT = PERFORMER_MODULE.parent
-for p in (str(INTERP_DIR), str(PERFORMER_MODULE), str(REPO_ROOT)):
+BIOMOD_SOURCE = INTERP_DIR.parent
+REPO_ROOT = BIOMOD_SOURCE.parent
+for p in (str(INTERP_DIR), str(BIOMOD_SOURCE), str(REPO_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from interpretability.utils import load_module_names, parse_module_family
-from module_text_alignment.module_text_alignment import (
+from interpretability.utils import load_biomod_names, parse_biomod_family
+from biomod_text_alignment.biomod_text_alignment import (
     build_text_descriptions,
     compute_cka,
     compute_rsa,
@@ -150,7 +150,7 @@ def reactome_category_rsa(
     logger.info("Analysis 1: Reactome category-level RSA")
     logger.info("=" * 50)
 
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     reactome_mask = np.array([f == "Reactome" for f in families])
     reactome_idx = np.where(reactome_mask)[0]
 
@@ -259,7 +259,7 @@ def reactome_with_descriptions(
     with open(descriptions_file, "r", encoding="utf-8") as f:
         descriptions = json.load(f)
 
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     reactome_mask = np.array([f == "Reactome" for f in families])
     reactome_idx = np.where(reactome_mask)[0]
 
@@ -317,7 +317,7 @@ def hallmarks_deep_dive(
     logger.info("Analysis 3: Hallmarks deep dive")
     logger.info("=" * 50)
 
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -445,9 +445,9 @@ def hallmarks_deep_dive(
 def parse_args():
     parser = argparse.ArgumentParser(description=__doc__,
                                      formatter_class=argparse.RawDescriptionHelpFormatter)
-    parser.add_argument("--module_embedding_path", type=str, required=True)
-    parser.add_argument("--module_json", type=str,
-                        default=str(REPO_ROOT / "model_dependencies" / "module_data_all" / "merged_modules.json"))
+    parser.add_argument("--biomod_embedding_path", "--module_embedding_path", type=str, required=True, dest='module_embedding_path')
+    parser.add_argument("--biomod_json", "--module_json", type=str,
+                        default=str(REPO_ROOT / "model_dependencies" / "biomod_data_all" / "merged_biomods.json"), dest='module_json')
     parser.add_argument("--descriptions_file", type=str, default=None,
                         help="JSON with Reactome summaryText descriptions.")
     parser.add_argument("--sentence_model", type=str,
@@ -474,7 +474,7 @@ def main():
     )
 
     # Load data
-    module_names = load_module_names(args.module_json)
+    module_names = load_biomod_names(args.module_json)
     all_embeddings = np.load(args.module_embedding_path)
     indices, names, texts = build_text_descriptions(module_names)
     module_emb = all_embeddings[indices]

BioMod/interpretability/{module_text_alignment/module_text_alignment_publication.py → biomod_text_alignment/biomod_text_alignment_publication.py}

@@ -4,13 +4,13 @@
 Supports multi-model comparison and cross-dataset validation.
 
 Usage (run from the BioMod repository root):
-    python BioMod/interpretability/module_text_alignment/module_text_alignment_publication.py \
-        --module_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
-        --module_embedding_path2 outputs/interpretability/geometry/pancreas_scib/module_embeddings.npy \
-        --module_json model_dependencies/module_data_all/merged_modules.json \
+    python BioMod/interpretability/biomod_text_alignment/biomod_text_alignment_publication.py \
+        --biomod_embedding_path outputs/interpretability/geometry/pretrain_subset/module_embeddings.npy \
+        --biomod_embedding_path2 outputs/interpretability/geometry/pancreas_scib/module_embeddings.npy \
+        --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
         --sentence_model pritamdeka/S-PubMedBert-MS-MARCO \
         --sentence_models_compare "sentence-transformers/all-mpnet-base-v2" \
-        --descriptions_file BioMod/interpretability/module_text_alignment/reactome_descriptions.json \
+        --descriptions_file BioMod/interpretability/biomod_text_alignment/reactome_descriptions.json \
         --n_permutations 1000 \
         --n_bootstrap 2000 \
         --output_dir outputs/interpretability/text_alignment/publication
@@ -40,19 +40,19 @@
 
 HERE = Path(__file__).resolve().parent
 INTERP_DIR = HERE.parent
-PERFORMER_MODULE = INTERP_DIR.parent
-REPO_ROOT = PERFORMER_MODULE.parent
-for p in (str(HERE), str(INTERP_DIR), str(PERFORMER_MODULE), str(REPO_ROOT)):
+BIOMOD_SOURCE = INTERP_DIR.parent
+REPO_ROOT = BIOMOD_SOURCE.parent
+for p in (str(HERE), str(INTERP_DIR), str(BIOMOD_SOURCE), str(REPO_ROOT)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
 from interpretability.utils import (
     HALLMARK_PROCESS,
-    load_module_names,
+    load_biomod_names,
     parse_hallmark_process,
-    parse_module_family,
+    parse_biomod_family,
 )
-from module_text_alignment.module_text_alignment import (
+from biomod_text_alignment.biomod_text_alignment import (
     build_text_descriptions,
     compute_cka,
     compute_rsa,
@@ -60,7 +60,7 @@
     mantel_test,
     permutation_test_cka,
 )
-from module_text_alignment.module_text_alignment_extended import (
+from biomod_text_alignment.biomod_text_alignment_extended import (
     REACTOME_CATEGORIES,
     categorize_reactome,
 )
@@ -166,8 +166,8 @@ def bootstrap_rsa(
            float(np.percentile(boot_rs, 97.5))
 
 
-def get_module_sizes(module_json: str) -> Dict[str, int]:
-    """Get number of genes per module from merged_modules.json."""
+def get_biomod_sizes(module_json: str) -> Dict[str, int]:
+    """Get number of genes per module from merged_biomods.json."""
     with open(module_json, "r", encoding="utf-8") as f:
         modules = json.load(f)
     return {name: len(genes) for name, genes in modules.items()}
@@ -182,12 +182,12 @@ def parse_args() -> argparse.Namespace:
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument("--module_embedding_path", type=str, required=True,
-                        help="Primary module_embeddings.npy (e.g. pretrain_subset)")
-    parser.add_argument("--module_embedding_path2", type=str, default=None,
-                        help="Second dataset module_embeddings.npy for cross-dataset comparison")
-    parser.add_argument("--module_json", type=str,
-                        default=str(REPO_ROOT / "model_dependencies" / "module_data_all" / "merged_modules.json"))
+    parser.add_argument("--biomod_embedding_path", "--module_embedding_path", type=str, required=True,
+                        help="Primary module_embeddings.npy (e.g. pretrain_subset)", dest='module_embedding_path')
+    parser.add_argument("--biomod_embedding_path2", "--module_embedding_path2", type=str, default=None,
+                        help="Second dataset module_embeddings.npy for cross-dataset comparison", dest='module_embedding_path2')
+    parser.add_argument("--biomod_json", "--module_json", type=str,
+                        default=str(REPO_ROOT / "model_dependencies" / "biomod_data_all" / "merged_biomods.json"), dest='module_json')
     parser.add_argument("--descriptions_file", type=str, default=None)
     parser.add_argument("--sentence_model", type=str,
                         default="pritamdeka/S-PubMedBert-MS-MARCO")
@@ -314,7 +314,7 @@ def fig2_hallmarks_heatmaps(
     output_dir: Path,
 ) -> Dict:
     """Hallmarks 50x50 similarity matrices with rank-transform and clustering."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -433,7 +433,7 @@ def fig3_per_hallmark_alignment(
     seed: int = 42,
 ) -> Dict:
     """Lollipop chart of per-hallmark alignment scores, colored by process."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -531,7 +531,7 @@ def fig4_category_alignment(
     output_dir: Path,
 ) -> Dict:
     """Violin/box plot of alignment scores grouped by MSigDB process category."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -634,7 +634,7 @@ def fig5_granularity_effect(
     output_dir: Path = None,
 ) -> Dict:
     """RSA at multiple granularity levels: fine → category → super-category."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     reactome_mask = np.array([f == "Reactome" for f in families])
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     reactome_idx = np.where(reactome_mask)[0]
@@ -761,7 +761,7 @@ def fig6_model_comparison(
     output_dir: Path = None,
 ) -> Dict:
     """Grouped bar chart comparing RSA across models and datasets."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -861,7 +861,7 @@ def fig6_model_comparison(
 # Deep Analysis: Alignment vs Module Size
 # ============================================================
 
-def analysis_alignment_vs_module_size(
+def analysis_alignment_vs_biomod_size(
     module_emb: np.ndarray,
     text_emb: np.ndarray,
     names: List[str],
@@ -870,7 +870,7 @@ def analysis_alignment_vs_module_size(
     output_dir: Path,
 ) -> Dict:
     """Scatter: n_genes vs alignment score. Tests if larger modules align better."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -891,7 +891,7 @@ def analysis_alignment_vs_module_size(
         per_module_corr[i] = r
 
     # Module sizes
-    module_sizes = get_module_sizes(module_json)
+    module_sizes = get_biomod_sizes(module_json)
     h_sizes = np.array([module_sizes.get(n, 0) for n in h_names])
 
     # Correlation
@@ -945,7 +945,7 @@ def analysis_negative_results(
     n_show: int = 5,
 ) -> Dict:
     """For poorly-aligned modules, show neighbor divergence."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -1022,7 +1022,7 @@ def analysis_knn_overlap(
     output_dir: Path = None,
 ) -> Dict:
     """kNN overlap with bootstrap CI and per-category breakdown."""
-    families = [parse_module_family(n) for n in names]
+    families = [parse_biomod_family(n) for n in names]
     hallmark_mask = np.array([f == "Hallmarks" for f in families])
     hallmark_idx = np.where(hallmark_mask)[0]
 
@@ -1103,13 +1103,13 @@ def main():
     logger.info("Args: %s", vars(args))
 
     # ---- Load data ----
-    module_names = load_module_names(args.module_json)
+    module_names = load_biomod_names(args.module_json)
     all_module_emb = np.load(args.module_embedding_path)
     logger.info("Loaded module embeddings: %s from %s",
                 all_module_emb.shape, args.module_embedding_path)
 
     # Filter to semantic modules (Hallmarks + Reactome)
-    families = [parse_module_family(n) for n in module_names]
+    families = [parse_biomod_family(n) for n in module_names]
     semantic_mask = np.array([f in ("Hallmarks", "Reactome") for f in families])
     semantic_idx = np.where(semantic_mask)[0]
     module_emb = all_module_emb[semantic_idx]
@@ -1205,7 +1205,7 @@ def main():
 
     # ---- Deep Analysis ----
     logger.info("Running deep analysis: alignment vs module size...")
-    metrics_size = analysis_alignment_vs_module_size(
+    metrics_size = analysis_alignment_vs_biomod_size(
         module_emb, text_emb, names, texts, args.module_json, output_dir,
     )
 

BioMod/interpretability/{module_text_alignment → biomod_text_alignment}/fetch_reactome_descriptions.py

@@ -1,11 +1,11 @@
 """Fetch Reactome pathway descriptions via the Content Service REST API.
 
 Produces a JSON file mapping module_name -> summaryText that can be passed
-to module_text_alignment_extended.py via --descriptions_file.
+to biomod_text_alignment_extended.py via --descriptions_file.
 
 Usage (run from the BioMod repository root):
-    python BioMod/interpretability/module_text_alignment/fetch_reactome_descriptions.py \
-        --module_json model_dependencies/module_data_all/merged_modules.json \
+    python BioMod/interpretability/biomod_text_alignment/fetch_reactome_descriptions.py \
+        --biomod_json model_dependencies/biomod_data_all/merged_biomods.json \
         --output reactome_descriptions.json
 
 Requires internet access to https://reactome.org/ContentService/
@@ -24,12 +24,12 @@
 
 HERE = Path(__file__).resolve().parent
 INTERP_DIR = HERE.parent
-PERFORMER_MODULE = INTERP_DIR.parent
-for p in (str(INTERP_DIR), str(PERFORMER_MODULE)):
+BIOMOD_SOURCE = INTERP_DIR.parent
+for p in (str(INTERP_DIR), str(BIOMOD_SOURCE)):
     if p not in sys.path:
         sys.path.insert(0, p)
 
-from interpretability.utils import load_module_names, parse_module_family
+from interpretability.utils import load_biomod_names, parse_biomod_family
 
 REACTOME_API = "https://reactome.org/ContentService/data/query"
 
@@ -56,14 +56,14 @@ def fetch_summary(rhs_id: str, retries: int = 3) -> str:
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--module_json", type=str, required=True)
+    parser.add_argument("--biomod_json", "--module_json", type=str, required=True, dest='module_json')
     parser.add_argument("--output", type=str, default="reactome_descriptions.json")
     parser.add_argument("--delay", type=float, default=0.1,
                         help="Delay between API calls (seconds)")
     args = parser.parse_args()
 
-    module_names = load_module_names(args.module_json)
-    reactome_modules = [n for n in module_names if parse_module_family(n) == "Reactome"]
+    module_names = load_biomod_names(args.module_json)
+    reactome_modules = [n for n in module_names if parse_biomod_family(n) == "Reactome"]
     print(f"Reactome modules to fetch: {len(reactome_modules)}")
 
     descriptions = {}

BioMod/interpretability/utils.py

@@ -1,7 +1,7 @@
 """Shared helpers for module interpretability experiments.
 
 Provides:
-    * module family / hallmark-process parsing from merged_modules.json keys
+    * module family / hallmark-process parsing from merged_biomods.json keys
     * a generic in-memory dataset that yields raw [G_input] expression rows,
       compatible with DataPreprocessor.reindex_tensor_to_model_space
 """
@@ -86,7 +86,7 @@
 }
 
 
-def parse_module_family(module_name: str) -> str:
+def parse_biomod_family(module_name: str) -> str:
     head = module_name.split("__", 1)[0]
     return MODULE_FAMILY_MAP.get(head, "Other")
 
@@ -98,18 +98,18 @@ def parse_hallmark_process(module_name: str) -> Optional[str]:
     return HALLMARK_PROCESS.get(short)
 
 
-def build_module_metadata(module_names: Sequence[str]):
+def build_biomod_metadata(module_names: Sequence[str]):
     rows = []
     for name in module_names:
         rows.append({
             "module_name": name,
-            "family": parse_module_family(name),
+            "family": parse_biomod_family(name),
             "hallmark_process": parse_hallmark_process(name),
         })
     return rows
 
 
-def load_module_names(module_json_path: str) -> List[str]:
+def load_biomod_names(module_json_path: str) -> List[str]:
     with open(module_json_path, "r", encoding="utf-8") as handle:
         return list(json.load(handle).keys())
 

BioMod/{models_performer_module.py → models_biomod.py}

@@ -1,4 +1,4 @@
-"""Module-based Performer encoder with MAE-style masking and configurable
+"""BioMod encoder for gene groups with MAE-style masking and configurable
 reconstruction decoders or direct prediction heads."""
 
 import sys
@@ -16,21 +16,21 @@
     sys.path.insert(0, model_dependencies_dir)
 
 try:
-    from performer_pytorch_cont.ding_models import (
-        Performer,
+    from pytorch_cont.ding_models import (
+        Performer as BioModEncoder,
         Always,
         cast_tuple,
     )
 except ImportError:
     try:
-        from performer_pytorch_cont.performer_pytorch import (
-            Performer,
+        from pytorch_cont.pytorch import (
+            Performer as BioModEncoder,
             Always,
             cast_tuple,
         )
     except ImportError:
         from performer_pytorch.performer_pytorch import (
-            Performer,
+            Performer as BioModEncoder,
             Always,
             cast_tuple,
         )
@@ -41,7 +41,7 @@
 import numpy as np
 
 
-def _migrate_legacy_module_name(value: str) -> str:
+def _migrate_legacy_biomod_name(value: str) -> str:
     """Translate serialized pre-rename names without changing their semantics."""
     replacements = (
         ("PATHCH", "MODULE"),
@@ -59,13 +59,13 @@ def _migrate_legacy_module_name(value: str) -> str:
     return value
 
 
-def migrate_legacy_module_config(config: Dict[str, object]) -> Dict[str, object]:
+def migrate_legacy_biomod_config(config: Dict[str, object]) -> Dict[str, object]:
     """Return a module-named copy of an older serialized configuration."""
     def translate(value):
         if isinstance(value, dict):
             migrated = {}
             for key, item in value.items():
-                new_key = _migrate_legacy_module_name(key) if isinstance(key, str) else key
+                new_key = _migrate_legacy_biomod_name(key) if isinstance(key, str) else key
                 if new_key in migrated:
                     raise ValueError(
                         f"Legacy configuration migration would duplicate key {new_key!r}"
@@ -77,13 +77,13 @@ def translate(value):
         if isinstance(value, tuple):
             return tuple(translate(item) for item in value)
         if isinstance(value, str):
-            return _migrate_legacy_module_name(value)
+            return _migrate_legacy_biomod_name(value)
         return value
 
     return translate(dict(config))
 
 
-def migrate_legacy_module_state_dict(state_dict):
+def migrate_legacy_biomod_state_dict(state_dict):
     """Translate old state-dict key names before PyTorch performs strict loading."""
     try:
         migrated = state_dict.__class__()
@@ -91,7 +91,7 @@ def migrate_legacy_module_state_dict(state_dict):
         migrated = {}
 
     for key, value in state_dict.items():
-        new_key = _migrate_legacy_module_name(key) if isinstance(key, str) else key
+        new_key = _migrate_legacy_biomod_name(key) if isinstance(key, str) else key
         if new_key in migrated:
             # If both spellings are supplied, prefer the explicit new spelling.
             if key == new_key:
@@ -101,7 +101,7 @@ def migrate_legacy_module_state_dict(state_dict):
 
     if hasattr(state_dict, "_metadata"):
         migrated._metadata = {
-            _migrate_legacy_module_name(key): value
+            _migrate_legacy_biomod_name(key): value
             for key, value in state_dict._metadata.items()
         }
     return migrated
@@ -135,13 +135,13 @@ def normalize_fusion_method(fusion_method: str) -> str:
 )
 
 
-def sanitize_performer_module_config(
+def sanitize_biomod_config(
     config: Dict[str, object],
     *,
     source: str = "config",
     log_fn: Optional[Callable[[str], None]] = None,
 ) -> Dict[str, object]:
-    cleaned = migrate_legacy_module_config(config)
+    cleaned = migrate_legacy_biomod_config(config)
     legacy_mode = str(cleaned.get("extra_gene_mode", "none")).lower()
     legacy_num = int(cleaned.get("extra_gene_num", 0) or 0)
     if legacy_mode != "none" or legacy_num > 0:
@@ -160,7 +160,7 @@ def sanitize_performer_module_config(
 
     return cleaned
 
-# ModuleEmbedding is implemented here to support three expression-fusion methods.
+# BioModEmbedding is implemented here to support three expression-fusion methods.
 # from sclong_module.models_module import ModuleToGeneDecoder
 
 
@@ -220,7 +220,7 @@ def forward(self, query: torch.Tensor, memory: torch.Tensor) -> torch.Tensor:
         return query
 
 
-class ModuleEmbedding(nn.Module):
+class BioModEmbedding(nn.Module):
     """Gene embedding, MLP, and attention pooling produce a module token.
 
     Expression fusion supports three methods:
@@ -823,8 +823,8 @@ def forward(
         return self._forward_bucketed(expr, return_module_targets)
 
 
-class PerformerEncoderOnly_Module(nn.Module):
-    """Performer encoder for module inputs with configurable masking and decoding.
+class BioMod(nn.Module):
+    """BioMod encoder for gene-group inputs with configurable masking and decoding.
 
     use_gene2vec=True initializes from supplied pretrained gene embeddings;
     False uses random gene embeddings for ablation experiments."""
@@ -996,7 +996,7 @@ def __init__(
             print(f"[INFO] use_gene2vec=False: Using randomly initialized gene embeddings (dim={gene_embed_dim})")
 
         # Module embedding layer.
-        self.module_embed = ModuleEmbedding(
+        self.module_embed = BioModEmbedding(
             module_sets=module_sets,
             num_genes=num_genes,
             gene_embed_dim=gene_embed_dim,
@@ -1054,7 +1054,7 @@ def __init__(
         self.dropout = nn.Dropout(emb_dropout)
 
         # Performer encoder.
-        self.encoder = Performer(
+        self.encoder = BioModEncoder(
             base_dim, enc_depth, enc_heads, enc_dim_head,
             local_attn_heads, local_window_size, causal, ff_mult, nb_features,
             feature_redraw_interval, reversible, ff_chunks, generalized_attention,
@@ -1090,7 +1090,7 @@ def __init__(
         if self.decoder_type == "performer":
             self.decoder_pos_emb = nn.Parameter(torch.zeros(1, pos_tokens, self.dec_embed_dim))
             self.decoder_dropout = nn.Dropout(emb_dropout)
-            self.decoder = Performer(
+            self.decoder = BioModEncoder(
                 self.dec_embed_dim, dec_depth, dec_heads, dec_dim_head,
                 local_attn_heads=cast_tuple(0), local_window_size=256, causal=False, ff_mult=dec_ff_mult,
                 nb_features=None, feature_redraw_interval=feature_redraw_interval,
@@ -1203,7 +1203,7 @@ def _init_weights(self) -> None:
                 nn.init.constant_(m.bias, 0)
                 nn.init.constant_(m.weight, 1.0)
 
-    def _sample_module_mask(
+    def _sample_biomod_mask(
         self,
         batch_size: int,
         seq_len: int,
@@ -1237,7 +1237,7 @@ def random_masking(self, x: torch.Tensor, mask_ratio: float) -> Tuple[torch.Tens
         ids_restore = [3, 9, 1, 7, 2, 8, 4, 6, 5, 0] is the inverse permutation.
         For example, original module 0 occupies position 3 after shuffling."""
         b, l, d = x.shape
-        mask, ids_shuffle, ids_restore = self._sample_module_mask(
+        mask, ids_shuffle, ids_restore = self._sample_biomod_mask(
             batch_size=b,
             seq_len=l,
             device=x.device,
@@ -1260,7 +1260,7 @@ def replace_masking(
             raise RuntimeError("replace_masking requires encoder_mask_token to be initialized.")
 
         b, l, _ = x.shape
-        mask, _, _ = self._sample_module_mask(
+        mask, _, _ = self._sample_biomod_mask(
             batch_size=b,
             seq_len=l,
             device=x.device,
@@ -1271,7 +1271,7 @@ def replace_masking(
         x_masked = torch.where(mask.bool().unsqueeze(-1), mask_tokens, x)
         return x_masked, mask, ids_restore
 
-    def _add_module_position_embedding(self, x: torch.Tensor) -> torch.Tensor:
+    def _add_biomod_position_embedding(self, x: torch.Tensor) -> torch.Tensor:
         pos = self.pos_emb[:, 1:, :] if self.use_cls else self.pos_emb
         if pos.shape[1] != x.shape[1]:
             raise RuntimeError(
@@ -1306,10 +1306,10 @@ def forward_encoder(
         if self.mask_style == "replace":
             # Replace token contents, then add module-ID embeddings while retaining all positions.
             x, mask, ids_restore = self.replace_masking(x, mask_ratio)
-            x = self._add_module_position_embedding(x)
+            x = self._add_biomod_position_embedding(x)
         else:
             # MAE path: add module-ID embeddings, then drop masked modules.
-            x = self._add_module_position_embedding(x)
+            x = self._add_biomod_position_embedding(x)
             x, mask, ids_restore = self.random_masking(x, mask_ratio)
 
         # Sparse module gating (1B): suppress unimportant modules
@@ -1361,7 +1361,7 @@ def _build_full_tokens(self, x: torch.Tensor, ids_restore: torch.Tensor) -> torc
             return torch.cat([cls_token, x_], dim=1)
         return x_
 
-    def _aggregate_module_to_gene(
+    def _aggregate_biomod_to_gene(
         self,
         module_feats: torch.Tensor,
     ) -> torch.Tensor:
@@ -1383,13 +1383,13 @@ def _aggregate_module_to_gene(
         gene_counts = gene_counts.clamp(min=1.0).unsqueeze(-1)  # (B, G, 1)
         return gene_feats / gene_counts
 
-    def _predict_from_module_features(
+    def _predict_from_biomod_features(
         self,
         module_feats: torch.Tensor,
     ) -> Union[List[torch.Tensor], torch.Tensor]:
         """module_feats: (B, L, D)"""
         if self.recon_target_level == "gene" and self.decoder_gene_agg:
-            gene_feats = self._aggregate_module_to_gene(module_feats)  # (B, G, D)
+            gene_feats = self._aggregate_biomod_to_gene(module_feats)  # (B, G, D)
             assert self.gene_w is not None and self.gene_b is not None
             # Apply a separate linear projection to each gene.
             preds = torch.einsum("bgd,gdk->bgk", gene_feats, self.gene_w).squeeze(-1)
@@ -1445,9 +1445,9 @@ def forward_decoder_simple(
         Returns per-module predictions, or a (B, G) tensor for decoder_gene_agg."""
         x_full = self._build_full_tokens(x, ids_restore)
         module_feats = x_full[:, 1:, :] if self.use_cls else x_full
-        return self._predict_from_module_features(module_feats)
+        return self._predict_from_biomod_features(module_feats)
 
-    def forward_decoder_performer(
+    def forward_decoder_biomod(
         self,
         x: torch.Tensor,
         ids_restore: torch.Tensor,
@@ -1459,7 +1459,7 @@ def forward_decoder_performer(
         x_full = self.decoder(x_full, pos_emb=self.layer_pos_emb(x_full))
         x_full = self.decoder_norm(x_full)
         module_feats = x_full[:, 1:, :] if self.use_cls else x_full
-        return self._predict_from_module_features(module_feats)
+        return self._predict_from_biomod_features(module_feats)
 
     def forward_decoder_cross_attn(
         self,
@@ -1508,14 +1508,14 @@ def forward_decoder_cross_attn(
             masked_queries = self.decoder_norm(masked_queries).to(dtype=module_feats.dtype)
             module_feats[mask_bool] = masked_queries.reshape(-1, dim)
 
-        return self._predict_from_module_features(module_feats)
+        return self._predict_from_biomod_features(module_feats)
 
     def forward_predictor_from_encoder(
         self,
         x: torch.Tensor,
     ) -> Union[List[torch.Tensor], torch.Tensor]:
         module_feats = x[:, 1:, :] if self.use_cls else x
-        return self._predict_from_module_features(module_feats)
+        return self._predict_from_biomod_features(module_feats)
 
     def compute_loss(
         self,
@@ -1618,7 +1618,7 @@ def forward(
             return out
 
         if self.decoder_type == "performer":
-            preds = self.forward_decoder_performer(latent, ids_restore)
+            preds = self.forward_decoder_biomod(latent, ids_restore)
         elif self.decoder_type == "cross_attn":
             preds = self.forward_decoder_cross_attn(latent, mask, ids_restore)
         elif self.decoder_type == "simple":
@@ -1643,7 +1643,7 @@ def get_last_loss_breakdown(self) -> dict:
     def load_state_dict(self, state_dict, strict: bool = True, assign: bool = False):
         """Load current or pre-rename weights under the module-named interface."""
         return super().load_state_dict(
-            migrate_legacy_module_state_dict(state_dict),
+            migrate_legacy_biomod_state_dict(state_dict),
             strict=strict,
             assign=assign,
         )