Skip to main content

PyLipID - Analysis of Protein–Lipid Interactions from Molecular Dynamics

https://github.com/pstansfeld/PyLipID/actions/workflows/ci.yml/badge.svg https://img.shields.io/pypi/v/PyLipID https://img.shields.io/pypi/pyversions/PyLipID docs/static/pylipid_logo_smallsize.png

PyLipID is a Python package for analysing lipid–protein interactions from Molecular Dynamics (MD) simulations. It supports coarse-grained and all-atom simulations, handles formats supported by MDTraj, and works in scripts or Jupyter notebooks.

Documentation: https://pylipid.readthedocs.io

Features

  • Dual-cutoff contact detection to improve coarse-grained accuracy.

  • Binding site detection using NetworkX Louvain community analysis.

  • Kinetic parameters: koff and residence times per residue and site.

  • Interaction metrics including occupancy, count, duration.

  • Representative bound pose extraction and clustering.

  • Binding site surface area (SASA) calculations.

  • Publication-ready plots and PyMOL scripts.

Installation

From PyPI:

pip install pylipid

From source:

git clone https://github.com/pstansfeld/PyLipID
cd PyLipID
pip install .

Editable/development install:

pip install -e .

Requires Python >= 3.11 (tested on 3.11–3.14).

Quick Start

from pylipid.api import LipidInteraction

trajfile_list = ["run1/protein_lipids.xtc", "run2/protein_lipids.xtc"]
topfile_list  = ["run1/protein_lipids.gro", "run2/protein_lipids.gro"]

li = LipidInteraction(
    trajfile_list,
    topfile_list=topfile_list,
    cutoffs=[0.55, 0.8],
    lipid="CHOL",
    nprot=1,
)

li.collect_residue_contacts()
li.compute_residue_duration()
li.compute_residue_koff()
li.compute_binding_nodes(threshold=4)
li.compute_site_koff()

li.plot("Residence Time")
li.save_data("Dataset")
li.save_pymol_script(pdb_file="receptor.pdb")

PyLipID runs its calculations in parallel worker processes. When running it as a script, put the code under if __name__ == "__main__": (required on macOS and Windows, where the script would otherwise fail or hang); Jupyter notebooks need no change.

What’s New in v1.6.1

Documentation and packaging only; results are unchanged from v1.6.0. The README and docs cite the published JCTC paper, documentation links point at this repository, and the package lists its current maintainer.

What’s New in v1.6.0

Changes to Results

  • Binding site surface areas (compute_surface_area) now use the MARTINI bead radii PyLipID has always documented (BB 0.26 nm, SC1-SC4 0.23 nm) and any radii given. Before, mdtraj matched these against element symbols, so they were ignored and the radii of boron and sulfur (0.19/0.18 nm) were used. Each frame is also calculated separately, working around an mdtraj issue that adds part of the previous frame’s area to each frame in a multi-frame call. Site surface areas are typically 5-20% smaller than in earlier versions.

  • With np.random.seed() set in the calling script, bootstrapped koffs and the poses chosen to represent pose clusters are now reproducible (worker processes previously ignored the seed). Note that with scipy 1.17 (the last release for Python 3.11) curve_fit does not always return the same fit for the same data, so koff values can still vary slightly between runs there; scipy >= 1.18 (Python >= 3.12) is repeatable.

Bug Fixes

  • analyze_bound_poses no longer fails when many bound poses are identical (DBSCAN eps of 0), and a min_samples passed to it is now used instead of being overwritten.

  • Corrected binding-site detection off-by-one error.

  • Fixed calculate_scores returning None.

  • Fixed sparse_corrcoef matrix type issues.

  • Fixed DataFrame column/index mismatches in analyze_bound_poses.

  • Fixed missing return in compute_residue_lipidcount.

  • Fixed a crash when analyze_bound_poses was run more than once with pandas 3.

  • cluster_KMeans now always returns labels (it returned a tuple when there were fewer poses than clusters).

  • plot, plot_logo, save_coordinate and write_site_info calculate missing residue data on demand instead of raising KeyError.

  • Fixed write_PDB errors for .gro files lacking chain IDs.

  • Fixed figure overwriting in plot_koff.

  • Updated deprecated Matplotlib calls.

  • Fixed LogNorm crash on zero-containing matrices.

  • Replaced np.float128 with np.longdouble.

  • Corrected output directory typo.

Performance

  • collect_residue_contacts computes distances in large batches instead of once per lipid, and shares the batches between worker processes that read the coordinates from shared memory (num_cpus; based on Alex Moger’s parallel contacts in PR #1). Results are identical to the serial calculation; on a 2 x 2,000-frame system contacts take 8 s instead of 40 s.

  • Bound-pose scoring evaluates the kernel density estimate in numpy (~20x faster; same scores to within floating-point rounding).

  • Surface areas are shared between worker processes by chunks of frames rather than by trajectory.

  • Progress bars for parallel steps now follow the calculation.

  • Survival-function calculation for koff is vectorised (identical results, ~20% faster koff).

  • Nested progress bars implemented.

Dependencies

  • Removed python-louvain; using NetworkX built-in Louvain.

  • Removed statsmodels and p_tqdm (no longer used).

  • Minimum versions added.

  • Dropped Python < 3.11; supports Python 3.11–3.14, numpy 2, pandas 3 and current mdtraj.

Packaging & CI

  • Migrated to pyproject.toml.

  • CI moved from Travis CI to GitHub Actions.

Citation

https://img.shields.io/badge/DOI-10.1021/acs.jctc.1c00708-blue
@article{song_pylipid_2022,
    author  = {Song, Wanling and Corey, Robin A. and Ansell, T. Bertie and
               Cassidy, C. Keith and Horrell, Michael R. and Duncan, Anna L.
               and Stansfeld, Phillip J. and Sansom, Mark S.P.},
    title   = {PyLipID: A Python Package for Analysis of Protein-Lipid
               Interactions from Molecular Dynamics Simulations},
    journal = {J. Chem. Theory Comput.},
    volume  = {18},
    number  = {2},
    pages   = {1188--1201},
    year    = {2022},
    doi     = {10.1021/acs.jctc.1c00708},
    url     = {https://doi.org/10.1021/acs.jctc.1c00708},
}

License

MIT License. See LICENSE.txt.

Metadata

Release files for pylipid 1.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pylipid 1.6.1
File Size Uploaded Provenance Actions
pylipid-1.6.1.tar.gz 64.2 kB Without provenance Details for pylipid-1.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pylipid 1.6.1
File Interpreter ABI Platform Actions
pylipid-1.6.1-py3-none-any.whl Python 3 none any Details for pylipid-1.6.1-py3-none-any.whl

Total release size: 137.8 kB

Release files / pylipid-1.6.1.tar.gz

Download URL pylipid-1.6.1.tar.gz
Size 64.2 kB
Tags Source
SHA-256 checksum
How to use checksums
01578958657c0f1d4cc5437855db7bae9c19708cc40ad3e99ef93edb9dc71641
BLAKE2b-256 checksum
How to use checksums
6c622f0d5ff7181f362a925ced73d84b981073131c13eae458ed1c28ad474637
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.12

Release files / pylipid-1.6.1-py3-none-any.whl

Download URL pylipid-1.6.1-py3-none-any.whl
Size 73.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1cded0e6d64e333a55872cac2cfbb8a76f308bd8087c4250dfe204cab1da3ae
BLAKE2b-256 checksum
How to use checksums
956a9041428ef45357b90cf263f438e65c628e1e4d1b57a7d8e356dc96295462
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.12

Security for pylipid 1.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.6.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page