ppi-fingerprints

Consensus-based visualisation of protein-protein interactions from MD trajectories.

A Python pipeline that transforms molecular dynamics (MD) trajectories into clear, interactive visualisations. By wrapping the ProLIF library, this tool extracts per-frame interaction fingerprints (hydrophobic, hydrogen bonds, pi-stacking, etc.), calculates a "consensus" by keeping only consistent interactions across replicate simulations, and outputs a high-quality heatmap and an interactive residue network.

Designed primarily for protein-protein interfaces (e.g., receptor/peptide), but easily configurable for protein-ligand or antibody-antigen systems via a simple config file.

How it works

1. Fingerprint – ProLIF detects interactions per frame for each replicate; occupancy = % of frames a contact is present.
2. Consensus – keeps interactions present in ≥ MIN_REPLICATES (default 2) and with a mean occupancy ≥ MIN_OCCUPANCY% (default 10%), filtering out one-off contacts.
3. Visualise – renders the heatmap + interactive network. Interaction types: hydrophobic, hydrogen bond, pi-stacking, salt bridge, cation-pi.

Tested with pytest; CI runs the suite and re-renders the example on every push.

Peptide residues (y axis), receptor residues (x axis), coloured by mean occupancy (% of frames the contact is present). Generated from the included example data.

Live interactive network – hover edges for occupancy %, drag nodes to explore (or open examples/example_network.html locally).

Quickstart

Runs the demo on the included example data — no trajectory needed:

pip install -r requirements.txt
python visualize.py        # writes examples/example_heatmap.png + example_network.html

Or in Docker:

docker build -t ppi-fingerprints .
docker run --rm -v "$(pwd)/examples:/app/examples" ppi-fingerprints

Your own data

Fingerprinting a real trajectory needs the heavier MD stack (MDAnalysis + ProLIF):

pip install -r requirements.txt -r requirements-fingerprint.txt
# edit config.py (trajectory files, selections, thresholds), then:
python fingerprint.py                                            # trajectory -> <PREFIX>_Consensus_Interactions.csv
python visualize.py --input <PREFIX>_Consensus_Interactions.csv  # -> heatmap + network

fingerprint.py writes <PREFIX>_Consensus_Interactions.csv to the repo root; pass it to visualize.py with --input. Without --input, visualize.py falls back to config.INPUT_CSV (the example data).

Citation & license

Please cite via CITATION.cff (GitHub's "Cite this repository" button). Released under the MIT License © 2026 Daniil A. Baranov.

References

This pipeline builds on two open-source tools — please cite them if you use it in your work:

ProLIF:
Bouysset, C., Fiorucci, S. ProLIF: a library to encode molecular interactions as fingerprints. J Cheminform 13, 72 (2021). https://doi.org/10.1186/s13321-021-00548-6

MDAnalysis:
R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler, D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein. MDAnalysis: A Python package for the rapid analysis of molecular dynamics simulations. In S. Benthall and S. Rostrup, editors, Proceedings of the 15th Python in Science Conference, pages 98-105, Austin, TX, 2016. SciPy. https://doi.org/10.25080/majora-629e541a-00e

N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein. MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations. J. Comput. Chem. 32 (2011), 2319-2327. https://doi.org/10.1002/jcc.21787. PMCID:PMC3144279