How gevaertlab/sequoia-pub works
Below are the detailed guidelines and a proposed strategy for mapping the project’s architecture:
• Data Ingestion & Pre-Processing:
• Initial stage where WSIs are handled.
• “Patch Extraction” (pre_processing/patch_gen_hdf5.py and scripts/extract_patch.sh) and “Feature Extraction” (compute_features_hdf5.py under pre_processing and scripts/extract_resnet_features.sh).
• That after feature extraction the k-Means clustering is applied (via scripts/extract_kmean_features.sh). Emphasize that these phases transform raw WSIs into feature vectors (stored in HDF5 files).
• Model Training & Fine-tuning:
• Core training module located in the “src” folder. Components include:
o The main training driver (src/main.py).
o The model definitions (src/resnet.py, src/vit.py, src/tformer_lin.py, and src/he2rna.py for the MLP based HE2RNA variant).
o The pre-training script (src/pretrain_gtex.py) and fold definition files (src/folds) for cross-validation splits.
• That training can be run with various model types (vis for the SEQUOIA linearized transformer, vit for standard transformer aggregation, and he2rna for the MLP variant).
• Evaluation & Benchmarking:
• “evaluation” module including evaluation/predict_independent_dataset.py (for scoring an independent dataset) and evaluation/evaluate_model.py (for computing Pearson correlation, RMSE, and filtering significant genes).
• Gene list CSV (evaluation/gene_list.csv) as part of input/output, used to map predicted gene indexes to their names.
• That benchmarking entails comparing model predictions versus ground truth.
• Spatial Visualization:
• Separate the spatial analysis component (spatial_vis folder) that focuses on spatial gene expression mapping.
• Driver/Utility Scripts & Examples:
• “scripts” folder (for bash scripts) and “examples” folder that provides sample reference files.
• These components glue the modular pieces together and allow execution of the full pipeline.
Data Flow & Interactions
• From the initial pre-processing block:
• The output of pre-processing (the feature HDF5 files) is then fed into the Model Training/Fine-tuning block.
• Within Model Training:
• Use of multiple training scripts – one path for pre-training (on GTEx data) and one for fine-tuning on TCGA data.
• Dependency on external pre-trained weights loaded via HuggingFace (as noted in the README).
• Model Evaluation:
• Spatial Visualization:
• That outputs from the trained model also can be fed into the “Spatial Visualization” module to generate spatial gene expression maps.
• Additional computation pipelines like Earth Mover’s Distance (EMD) measurement.
Architectural Patterns and Design Principles
• Modularity: The system is broken into clearly separated folders that encapsulate distinct stages (pre-processing, training, evaluation, and visualization).
• Pipeline Architecture: Data flows sequentially from raw WSIs through pre-processing, feature extraction, model training, evaluation, and finally spatial visualization.
• External Dependencies: Emphasize where external libraries or interfaces come into play (Openslide for WSI processing, HuggingFace for model checkpoints, and dependency management via Conda and requirements.txt).