How ai4protein/venusrem works
Project type and purpose
• This is a research‐driven bioinformatics pipeline (“VenusREM”) for zero‐shot prediction of protein mutation fitness.
• It orchestrates data retrieval (MSA, structure, substitutions), preprocessing, a learned structural encoder/quantizer, and a fitness‐scoring inference step.
File structure
• Top level:
• compute_fitness.py – main entrypoint for inference
• data/ – raw and processed datasets (ProteinGym, Uniprot, PDB files, substitution CSVs)
• script/ – shell wrappers that invoke the Python modules in a standard sequence
• src/data/ – Python modules for each data‐prep subtask (MSA, structure seq/extract, substitution parsing, plotting)
• src/structure/ – core model code: GVP encoder, quantizer, static assets (joblib, AE.pt)
• environment.yml, requirements.txt – conda environment and pip dependencies
README for additional insights
• Describes multi‐step workflow:
1. Prepare raw data (unpack archives, build local directories)
2. Search homology via JackHMMER + EVcouplings
3. Select/convert MSA files
4. Retrieve or generate structures (AlphaFold, ESMFold) and extract sequences
5. Run compute_fitness.py to produce zero‐shot mutation scores
• External dependencies: HMMER, EVcouplings (plmc), Uniref100 DB, GPU/CPU requirements
a. Main components
• Data Sources:
• ProteinGym archives (aa_seq, substitutions, pdbs, struc_seq)
• Uniprot/UniRef100 database
• Data Prep Layer (src/data + bash scripts)
• get_msa (JackHMMER → EVcouplings)
• select_msa (filter top alignments)
• get_struc_seq (extract sequence from PDB)
• get_struc_aln (structural alignment processing)
• data_format_convert, get_sav, etc.
• Core Model Layer (src/structure)
• Encoder (gvp.py + layer.py → graph/vector‐protein encoder)
• Quantizer (quantizer.py, static assets)
• Pretrained AE (AE.pt) + joblib tables
• Inference Layer
• compute_fitness.py (loads data, calls model, outputs scores)
• External Tools & Services
• HMMER / JackHMMER
• EVcouplings (plmc)
• AlphaFold/ESMFold server or local database
• Outputs
• result/<protein_dir>/fitness_scores.csv
• attention maps / plots (via plot_attention_map.py)
b. Relationships and interactions
• Data Prep sequentially produces MSA files → structure seq → substitution tables.
• Inference script pulls preprocessed data and passes through Model Layer (encoder → quantizer)
• Model outputs per‐mutation fitness, saved to result/; optionally passed to plotting module.
c. Architectural patterns & design principles
• Pipeline (batch processing) architecture: clear stages, each with its own module
• Modular separation: src/data vs. src/structure vs. compute_fitness entrypoint
• Externalization of large static assets (joblib, AE.pt) to avoid recomputation
• Use of configuration (single_config_monomer.txt) to decouple model parameters
d. Key technologies & libraries
• Python 3.x, Conda environment (environment.yml)
• HMMER, EVcouplings (C/Fortran toolchain via plmc)
• PyTorch or similar (for AE.pt)
• joblib for static lookups
• Standard data formats: FASTA, A2M, PDB, CSV