Dynamical Fingerprints of Rare-Event Transitions

Code and simulation inputs accompanying the manuscript “Dynamical Fingerprints of Rare-Event Transitions from Transition Corridors.”

Overview

This repository implements a transition-conditioned workflow for extracting dynamical fingerprints of designated rare-event transitions. The workflow:

1. constructs a free-energy landscape in a global collective-variable (CV) representation;
2. identifies a minimum-barrier path and a finite-width transition corridor;
3. learns corridor-conditioned displacement and slow modes;
4. ranks microscopic players by their transition-local informativeness; and
5. tests transition leverage through REST2 and metadynamics interventions.

The repository is organized around the four computational stages used in the study:

Stage	Directory	Purpose
1	ranking_players/	Corridor construction, PCA/tICA analysis, and atom ranking
2	rest2/	REST2 intervention inputs and launch scripts
3	metadynamics/	Multi-walker metadynamics inputs and launch scripts
4	visualization/	Projection and free-energy-surface visualization

Shared CHARMM22* parameter files are stored in forcefields/charmm22star.ff/. Third-party provenance and citation information is recorded in THIRD_PARTY_NOTICES.md.

Data availability

The long unbiased molecular-dynamics trajectories used to construct the transition corridors are not redistributed in this repository. They were obtained from the Anton simulations reported in:

Lindorff-Larsen K, Piana S, Dror RO, Shaw DE. How Fast-Folding Proteins Fold. Science. 2011;334:517–520. https://doi.org/10.1126/science.1208351

Users must obtain those trajectories independently from the applicable source, subject to its access and reuse terms, or supply their own compatible topology/trajectory data. The repository ignores common trajectory and GROMACS runtime formats to prevent accidental redistribution.

See data/README.md for the required local layout and manifest format.

Software environment

The Python analysis environment is defined in environment.yml. Create it with Conda, Mamba, or Micromamba:

micromamba create --file environment.yml

The tested environment uses Python 3.10 and pinned versions of NumPy, pandas, SciPy, scikit-learn, MDAnalysis, PyEMMA, deeptime, Biopython, Matplotlib, and tqdm.

The intervention inputs were prepared for GROMACS 2019.6 patched with PLUMED 2.7.3. Scheduler directives are templates; users must supply site-specific partitions, accounts, modules, and resource limits.

Minimal analysis workflow

After obtaining compatible data, copy the example manifest and replace its paths:

cp data/trajectory_manifest.example.csv data/trajectory_manifest.csv

Run the corridor-conditioned ranking workflow:

python ranking_players/main.py \
    --manifest data/trajectory_manifest.csv \
    --topology /path/to/compatible-topology.pdb \
    --system_name trpcage \
    --output_dir ranking_players/results_trpcage \
    --input_method tica \
    --lag_time_first_tICA 50 \
    --pca_components 60 \
    --lag_time 50 \
    --top_n 10

Export the first two PCA and tICA modes:

python ranking_players/export_modes_mainstyle.py \
    --manifest data/trajectory_manifest.csv \
    --topology /path/to/compatible-topology.pdb \
    --system-name trpcage \
    --output-dir ranking_players/results_trpcage \
    --lag-ns 50 \
    --selection "name CA"

Paths beginning with /path/to/ are placeholders and must be replaced with real local paths.

Atom selections

Mode construction accepts MDAnalysis selection expressions. Common choices include:

Selection	Meaning
name CA	Cα atoms only
backbone	Protein backbone atoms
protein	All protein atoms
protein and not name H*	Protein heavy atoms
all	Every atom, including solvent and ions

The manuscript workflow uses Cα atoms for the global CV representation. Broader selections increase memory and compute requirements. Selecting all can make solvent motion dominate the representation and should be used only when that behavior is intended.

Reproducibility scope

• Random or independently obtained raw trajectories are not part of the Git history.
• Generated caches, scheduler logs, checkpoints, and large time-series files are excluded.
• Selected compact mode bundles, free-energy grids, and representative figures are retained to document expected output formats.
• The supplied simulation files are research run configurations. Scheduler and environment settings must be adapted to the target HPC system.
• Numerical results can depend on trajectory preprocessing, atom ordering, frame spacing, lag time, basin endpoints, corridor parameters, and software versions. These choices must be recorded when applying the workflow to new systems.

Repository status

This is an anonymized peer-review snapshot. Author and affiliation metadata, personal contact details, and the manuscript PDF are intentionally omitted. Citation metadata and a public archival release will be added after peer review.