evo3D R package: a spatial haplotype framework for structure-informed analysis of molecular evolution

The paper introduces evo3D, an R package that overcomes the limitations of existing structure-informed evolutionary analysis by providing a flexible framework to extract spatial haplotypes and compute diverse statistics across complex protein structures, thereby enabling more comprehensive identification of evolutionary patterns within 3D contexts.

The Gist

The Big Idea: Why "Flat" Maps Fail

Imagine you are trying to understand a complex machine, like a car engine. If you only looked at a flat list of parts (a spreadsheet), you might see that the spark plug is next to the fuel injector on the list. But in reality, inside the engine, the spark plug is actually touching the piston, which is far away on the list.

For a long time, scientists studying how viruses and proteins evolve have been looking at flat lists (linear DNA sequences). They assume that if two DNA letters are next to each other in the code, they are neighbors.

The Problem: Proteins don't work like flat lists. They fold up into complex 3D shapes (like origami). Two parts of a protein that are far apart in the DNA code might be touching each other in 3D space. If a virus mutates one part, it might break the connection with the part it's touching, even if they are miles apart on the "flat list."

The Solution: The authors built a new tool called evo3D. Think of it as a 3D GPS for evolution. Instead of looking at a flat list, it looks at the protein's 3D shape to find out which parts are actually neighbors.

---

How evo3D Works: The "Neighborhood" Analogy

Imagine a protein is a giant, crowded city.

• The Old Way (Linear Windows): Scientists used to pick a neighborhood by looking at a street address. "Let's study houses 10 through 20." But in a 3D city, house #10 might be on the top floor of a skyscraper, and house #20 might be in the basement. They aren't neighbors at all!
• The evo3D Way (Spatial Haplotypes): evo3D asks, "Who is actually standing next to whom?" It draws a circle around a specific person (a residue) and grabs everyone within arm's reach, regardless of their address on the list. It calls this group a "Spatial Haplotype."

Once it gathers this real-life neighborhood, it checks the DNA of everyone in that group to see how much they are changing (evolving). This tells scientists if that specific 3D cluster is under attack by the immune system or if it's a critical part of the machine that can't afford to change.

Key Features of the Tool

1. It Handles the "Fold":
   Proteins often come in teams (multimers), like a soccer team of 8 players holding hands. evo3D is smart enough to know that if you are looking at Player A, you also need to look at Player B, C, and D who are holding hands with them, even if they are coded by different genes. It can merge these views or keep them separate, depending on what you want to study.

2. It's a "Universal Adapter":
   Before this, scientists had to use different, clunky tools for different jobs. Some tools only worked on Windows, some only worked for cancer, and some only worked for viruses. evo3D is like a universal power strip. It takes your DNA data and your 3D structure file, plugs them in, and runs the analysis with a single button click (run_evo3d()). It's designed to be easy for anyone to use, not just computer experts.

3. It Finds Hidden Secrets:
   The paper tested this on two viruses: Hepatitis C and Chikungunya.

   • The Hepatitis C Discovery: Scientists were looking for a "vaccine target"—a part of the virus that doesn't change much so a vaccine can stick to it. The old flat-list method missed a very stable, unchanging spot on the virus's surface. evo3D found it immediately because it saw that the surrounding 3D neighborhood was locked down tight.
   • The Chikungunya Discovery: They looked at how the virus interacts with human cells. They found that the "lock" (the binding site) is very stable, but the "doorframe" right next to it is chaotic and changing. This helps explain how the virus tricks the immune system: it keeps the important part steady while the surroundings distract the body's defenses.

Why This Matters

This tool removes the "technical barrier." Previously, you needed to be a master coder to combine DNA data with 3D protein shapes. Now, evo3D does the heavy lifting.

The Bottom Line:
Evolution doesn't happen on a piece of paper; it happens in 3D space. evo3D is the first tool that makes it easy to study evolution exactly where it happens: inside the folded, twisting, 3D world of proteins. It helps us find better vaccine targets, understand how viruses hide from our immune systems, and generally see the "big picture" of how life evolves.

Where to find it: The tool is free and open-source on GitHub, ready for any scientist to download and start exploring the 3D world of evolution.

Technical Summary

1. Problem Statement

Current evolutionary analyses of protein-coding regions predominantly rely on linear sequence data (single sites or linear sliding windows). However, selection pressures often act on three-dimensional (3D) structural features (e.g., catalytic domains, ligand-binding sites, protein-protein interfaces) where phenotypes emerge from spatially clustered residues.
Existing structure-informed methods suffer from several limitations:

• Rigidity: They are often restricted to predefined statistics (e.g., only local mutation density) and narrowly defined spatial window types.
• Lack of Generalizability: They do not easily support multimeric assemblies (protein complexes), interfaces, or multiple structural models.
• Technical Barriers: Many tools are OS-specific, have heavy external dependencies, or lack transparency in mapping Multiple Sequence Alignments (MSAs) to Protein Data Bank (PDB) structures, leading to unexamined alignment errors.
• Variable Window Sizes: Most methods use distance cutoffs, resulting in variable residue counts per window, which complicates statistical comparisons across sites.

2. Methodology: The evo3D Framework

The authors developed evo3D, an R package designed as a general-purpose, structure-informed evolutionary analysis framework. It treats the unit of analysis as a "spatial haplotype": a codon sequence formed by the subset of MSA columns corresponding to residues within a defined 3D spatial window.

Key Technical Components:

• Input/Output: Accepts nucleotide/amino acid MSAs and PDB/mmCIF structures. Returns a structured S3 list containing the core results dataframe, spatial haplotypes, alignment information, and parameter records.
• Workflow (run_evo3d()): A single wrapper function orchestrates the analysis:
  1. MSA Processing: Validates input, detects sequence type, and generates a peptide reference sequence.
  2. Chain Mapping: Automatically maps MSA sequences to PDB chains using fast k-mer similarity (user-overridable).
  3. Spatial Window Generation (pdb_to_patch): Defines 3D neighborhoods around residues using either fixed-distance (cutoff) or fixed-count (e.g., 15 nearest neighbors) rules. It includes a custom C++ implementation of DSSP-style solvent accessibility (SASA) calculations.
  4. Alignment & Mapping (aln_msa_to_pdb): Aligns the reference peptide to the structural chain, maps codons to residues, and handles gap-induced inconsistencies. Crucially, it exposes internal alignments for user inspection and correction.
  5. Multimer Handling:
     • Window Modes: Distinguishes between "residue" mode (retains duplicated codons from different chains) and "codon" mode (deduplicates to unique codons).
     • Analysis Modes: "Residue" mode assigns windows per structural residue (allowing comparison of conformational states); "Codon" mode collapses these into a single codon-level window.
  6. Haplotype Extraction: Extracts discontinuous but structurally coherent MSA subsets (spatial haplotypes) for downstream statistics.
  7. Statistical Calculation: Computes built-in statistics (Shannon entropy, block entropy, nucleotide diversity, Tajima's D) or allows users to apply custom statistics to the extracted haplotypes.

Innovations over Previous Tools:

• Fixed-Count Windows: Ensures consistent window sizes for statistical comparability.
• Interface Extraction: Can isolate protein-protein interfaces as independent spatial haplotypes.
• Transparency: Returns internal MSA-PDB mappings, allowing users to identify and correct alignment errors before final analysis.
• Scalability: Handles monomers, multimers, and multiple structural models within a unified framework.

3. Key Contributions

1. Formalization of Spatial Haplotypes: Defined the spatial haplotype as the fundamental unit for structure-informed analysis, making the extracted MSA subsets directly available for any downstream genetic statistic.
2. Multimeric Framework: Formalized the handling of duplicated codons in multimeric complexes through distinct window and analysis modes, addressing a gap in existing literature.
3. General-Purpose Architecture: Unlike tools limited to specific statistics (e.g., HotMAPS, CONSTRUCT), evo3D returns the raw spatial data, enabling flexible application of diverse evolutionary metrics.
4. Accessibility: Implemented in R with minimal dependencies, cross-platform compatibility, and a single entry point (run_evo3d()), lowering the barrier to entry for structural evolutionary biology.

4. Results and Applications

The authors validated evo3D using two viral protein complexes:

A. Hepatitis C Virus (HCV) E1/E2 Complex

• Goal: Identify conserved epitopes for vaccine design.
• Findings:
  • Spatial analysis identified highly conserved neighborhoods (e.g., E2 residues 606 and 561) on the immune-exposed face that were missed by linear sliding window analysis.
  • Linear windows detected only 2 significant regions, whereas spatial windows detected 5 (4 conserved, 1 diverse).
  • The conserved region around E2 606 (a potential broad-coverage vaccine target) was significant only in the spatial analysis, demonstrating that linear approaches fail to capture 3D functional constraints.
  • Correlation between spatial and linear block entropy was moderate ($r=0.66$), but individual windows showed substantial divergence (differences ranging from -5.8 to +3.9 bits).

B. Chikungunya Virus (ChikV) E1/E2 Octameric Complex

• Goal: Demonstrate scalability and multimer handling.
• Findings:
  • Successfully analyzed an octameric assembly (4 heterodimers) with ~15x larger structural size than HCV.
  • Chain-Specific Variation: In "residue" mode, the analysis revealed that the same codon could have different solvent exposure contexts across the four chains. Collapsing to "codon" mode merged these contexts effectively.
  • Interface Analysis: The MXRA8 receptor-binding interface was analyzed as a separate spatial haplotype. Results showed the binding interface itself is highly conserved, while diversity is elevated in the adjacent regions, a pattern consistent with immune pressure acting on surrounding residues while functional constraints maintain the core interface.
  • Performance: The analysis of the large octamer completed in ~20 seconds on a standard laptop, demonstrating computational efficiency.

5. Significance

• Paradigm Shift: evo3D moves evolutionary analysis from linear sequence contexts to explicit 3D structural contexts, acknowledging that protein function and selection are inherently spatial.
• Vaccine and Drug Discovery: By identifying conserved 3D epitopes and interfaces that linear methods miss, evo3D provides a powerful tool for rational vaccine design (e.g., targeting conserved HCV regions) and understanding drug resistance.
• Reproducibility and Transparency: By exposing the MSA-PDB mapping and allowing user correction, the framework mitigates the "black box" nature of previous structural analysis tools.
• Broad Applicability: While demonstrated on viral proteins, the framework is applicable to any comparative evolutionary question where structural context is relevant, including enzyme evolution, protein-protein interactions, and deep-learning structure predictions (e.g., AlphaFold models).

In conclusion, evo3D bridges the gap between structural biology and evolutionary genetics, providing a robust, transparent, and scalable framework to uncover selection pressures acting on the 3D architecture of proteins.