HLASCape

HLASCape is a research code suite for analyzing SARS-CoV-2 evolution with two complementary frameworks:

1. HLA_Analyses: population-level HLA clustering and quantification of T cell epitope evasion caused by viral mutations (Panels A-C of Figure 1).
2. Viral_Fitness: ESM-2-based mutation fitness scoring in epistatic sequence contexts across pandemic backgrounds, including targeted hotspot and T cell evasion analyses (panels D-E of Figure 1)

In all folders, the .sh executable file is the practical entry point and documents which Python scripts will be run and in what order.

High-Level Layout

• HLA_Analyses
  • HLA_Clustering
  • Epitope_Loss
• Viral_Fitness
  • interaction maps
  • mutation-vs-background scans
  • NYN/JN.1 T cell evasion-focused analyses
  • ESM-2 domain adaptation workflows

HLA_Analyses (Detailed)

HLA_Clustering

TSNE_Clustering

• Executable script: Network_Only.sh
• Main script: Network_Only_Clean.py (older variant: Network_Only.py)
• Purpose:
  • takes HLA profile tables (e.g., ThouGenomes_Variant_test_HLA_I_profiles.csv)
  • computes pairwise HLA similarity/distance
  • projects individuals in lower-dimensional space (t-SNE-style workflow)
  • generates clustering/network-oriented visual outputs

TSNE_Clustering_RECOVER

• Executable script: Network_Only.sh
• Main script: Network_Only_Clean.py
• Purpose: same computational framework as above, but with RECOVER-specific HLA input data (e.g., RECOVER_Variant_test_HLA_I_profiles.csv).

MDS_Clustering

• Executable script: Network_Only_MDS.sh
• Main script: Network_Only_MDS.py
• Purpose:
  • computes HLA-profile similarities
  • applies MDS projection rather than t-SNE
  • outputs MDS cluster maps used in downstream visualization

KNN_Clustering_Assessment

• Executable script: KNN_Shared_haplotypes_AVERAGE.sh
• Main scripts:
  • KNN_Shared_haplotypes_AVERAGE_cleaned.py (active)
  • KNN_Shared_haplotypes_AVERAGE.py (legacy version)
• Purpose:
  • evaluate cluster coherence/neighbor structure
  • quantify shared haplotype patterns across nearest neighbors
  • support cluster-quality interpretation

SNP_Based_Analysis

Four parallel pipelines are provided:

• HLA_ABC_Analysis
• HLA_ABC_Analysis_Random_SNP_Selection
• FullMHC_Analysis
• FullMHC_Analysis_Random_SNP_Selection

Each has two steps.

Step 1 (Step1_SNP_Extraction_QC/VCF_Plink_filterpipeline_HLA_ABC_JCCoord.sh)

• Converts/filters genotype data with plink2
• Performs QC filters (maf, geno, LD pruning)
• Extracts HLA/MHC region SNP sets (or random controls, depending on folder)
• Generates PCA-ready datasets (--pca 20)
• In selected workflows, calls helper script Select_HLA_MAF_Distribution.py to match SNP frequency distributions

Step 2 (Step2_Data_visualization/Print_PCA.sh)

• Calls one of:
  • Print_PCA_Show_AllPCs_Simplified_CLuster_Colors.py
  • Print_PCA_Show_AllPCs_Simplified_CLuster_Colors_KNN_On_PCA.py
• Produces PCA visualizations and cluster overlays for interpretation/comparison

T_Cell_Evasion_quantitative

• Folders:
  • ONETHOUGP_OldClustering_LatestEpitopeList_QuantitativeData
  • RECOVER_2_OldClustering_LatestEpitopeList_QuantitativeData
• Executable script: VREPRINT_Figures.sh
• Main scripts:
  • VREPRINT_Figures.py
  • VREPRINT_HLA_Distributions_PostCLUSTERING.py
• Purpose:
  • generate quantitative epitope-loss/evasion figures by variant
  • loop through generated recount files and compute post-clustering HLA distribution summaries

Epitope_Loss

Both subfolders use the same core structure and scripts:

• ONEKGP_Epitope_Loss
• RECOVER_Epitope_Loss

Executable script: VREPRINT_Figures.sh

Main scripts:

• VREPRINT_Figures.py
• VREPRINT_HLA_Distributions_PostCLUSTERING.py

Purpose:

• compute and visualize variant-dependent epitope loss
• summarize HLA-level consequences after clustering stratification
• provide figures/tables for OneKGP and RECOVER cohorts separately

Viral_Fitness (Detailed)

Two-mutation_interaction_map

• Executable scripts:
  • GISAID_Variant_Combinations_ESM2_Paralellisation.sh (Runs analysis across all mutations provided in script)
  • The script above relies on GISAID_Variant_Combinations__ESM2.sh
• Main Python scripts:
  • GISAID_Variant_Combinations__Test_epistasis_iterate_through_Muts.py
  • Generate_list_of_Variant_Combinations_Create_combinations.py
  • Combine_Results_and_Plot.py
  • Print_Combined_Results.py
• Purpose:
  • generate candidate mutation combinations
  • score combinations with ESM-2 in epistatic settings
  • merge results and produce interaction heatmaps/summary plots

Three_mutation_interaction_map

• Executable scripts:
  • GISAID_Variant_Combinations_ESM2_Paralellisation.sh (Runs analysis across all mutations provided in script)
  • The script above relies on GISAID_Variant_Combinations__ESM2.sh
• Main Python scripts:
  • GISAID_Variant_Combinations__Test_epistasis_iterate_through_Muts.py
  • Combine_Results_and_Plot.py
• Purpose: analogous to two-mutation map, extended to triple-mutation interactions.

Mutations_Against_Real_Backgrounds_BA2, Mutations_Against_Real_Backgrounds_Delta and Mutations_Against_Real_Backgrounds_JN1

• Executable scripts:
  • GISAID_Combined_alignment_ESM2_Paralellisation.sh (Runs analysis across all mutations provided in script)
  • Summarize_across_Mutations_NoStats.sh
• Main scripts:
  • Generate_list_of_Pandemicwide_Spike_Sequences_Select_Mutation_Of_Interest_Iterate_through_Muts.py
  • GISAID_CrossPandemicModel_iterate_through_Muts.py
  • Summarize_across_Mutations.py
• Purpose:
  • build mutation-specific background sequence sets
  • score mutation fitness over relevant pandemic backgrounds
  • aggregate across mutations and generate trend/statistical plots

Detrimental_Mutations_Against_Real_Backgrounds

• Executable scripts:
  • GISAID_Combined_alignment_ESM2.sh
  • GISAID_Combined_alignment_ESM2_Paralellisation.sh
  • Summarize_across_Mutations.sh
• Main scripts:
  • Generate_list_of_Pandemicwide_Spike_Sequences_Select_Mutation_Of_Interest_Iterate_through_Muts_parasail.py
  • GISAID_CrossPandemicModel_iterate_through_Muts_parasail.py
  • Summarize_across_Mutations.py
• Purpose: identify and summarize mutations with reproducible deleterious fitness signatures across background contexts.

T_cell_evasion_JN1

• Executable script: Reprint_With_Tcellevasion_REUSE_OLD_FIGS.sh
• Main script: Reprint_With_Tcellevasion_REUSE_OLD_FIGS.py
• Purpose:
  • batch-process RESULTS_GISAID_* folders
  • replot previously generated fitness outputs with T cell evasion annotations
  • produce publication-ready JN.1-oriented summary figures

NYN_T_Cell_Evasion_hotspot_analysis

• Executable scripts:
  • GISAID_Variant_Combinations__ESM2.sh
  • GISAID_Variant_Combinations_ESM2_Paralellisation.sh
• Main scripts:
  • GISAID_Variant_Combinations__Test_epistasis_iterate_through_Muts_Hotspots_TestAll_AA.py
• Purpose:
  • targeted scan of NYN-associated hotspot mutations/deletions
  • evaluate hotspot behavior in multi-mutation epistatic contexts
  • support hypothesis testing on T cell evasion hotspot dynamics

INTER_INTRA_TRANSFORMER_V9_CoVFIT_DomainAdaptation_NOSARS-CoV-2_CONFIRMED_30epoch

• Executable scripts:
  • RUN_MODEL.sh
• Main scripts:
  • Domain_Adaptation.py
• Purpose:
  • train/evaluate domain-adapted ESM-2 modeling workflow
  • run with accelerate (multi-GPU configuration in accel_Config_2GPUS.yaml)
  • provide model-level framework supporting downstream mutation scoring analyses

Reproducibility Workflow

For most folders:

1. Start from the folder-level .sh script.
2. Confirm/modify environment variables (e.g., MUTATIONS, optional deletion lists).
3. Run generation/scoring Python scripts.
4. Run summarization and plotting scripts.

For SNP pipelines:

1. Run Step1_SNP_Extraction_QC (PLINK filtering + PCA inputs).
2. Run Step2_Data_visualization (PCA plots and clustering overlays).

Dependencies

Python libraries imported in this repository

• numpy
• pandas
• matplotlib
• seaborn
• scipy
• scikit-learn
• torch
• transformers
• datasets
• biopython (imported as Bio)
• parasail
• phate
• kneed

External tools / runtime dependencies

• SLURM (sbatch) for HPC scheduling.
• PLINK/PLINK2 for genotype QC, LD pruning, and PCA.
• parasail (module/library) for alignment-aware sequence processing.
• Hugging Face Accelerate for distributed/multi-GPU model runs.
• HPC module environment support (module load ...) in several workflows.

Practical Notes

• File paths and environment/module commands in .sh scripts are configured for an HPC context and may require adaptation for local systems.
• Some folders contain both active and legacy script variants (e.g., *_cleaned.py, *_saved_copy.py); in general, follow the script explicitly called by the current .sh launcher.