Abstract
Selection pressures often act at the level of protein structure, yet most evolutionary analyses remain confined to linear sequences. Early structure-informed approaches improved interpretation by mapping single-site metrics onto protein structures, and later methods introduced 3D sliding windows to capture spatial neighbourhoods missed by linear analyses. These frameworks, however, are restricted to predefined statistics and narrowly defined 3D window types, limiting the scope of questions that can be addressed. We developed an R package, evo3D, a generalised framework for structure-informed evolutionary analysis that supports any downstream statistic and scales from simple to complex structures. evo3D extracts structure-informed multiple sequence alignment subsets (spatial haplotypes), making the structure-informed unit of analysis directly available to users. The framework provides fixed-count and fixed-distance spatial windows, supports residue and codon analysis modes, and extends across multimers, interfaces, and multiple structural models through a single wrapper, run_evo3d(). We demonstrate evo3D's utility by performing an epitope-level diversity scan of Hepatitis C virus E1/E2 complex, identifying conserved spatial neighbourhoods missed by linear sliding windows, and by evaluating evo3D's scalability on the octameric Chikungunya virus E1/E2 assembly. By formalising the core components of structure-informed genetic analysis and removing the technical barriers, evo3D streamlines the evaluation of evolutionary patterns directly within 3D structural contexts and we anticipate its wide application in molecular evolution studies. The package is available at github.com/bbroyle/evo3D.