Chemur

PyPI Python License: MIT

Find the non-covalent interactions in a PDB or mmCIF structure — between proteins, nucleic acids, ligands, metals and solvent, in any combination.

pip install chemur
chemur analyze structure.cif --out interactions.json
  • 22 interaction types, each with defined geometry
  • Any pair of components. Protein–ligand, protein–protein, protein–DNA/RNA, nucleic acid–ligand, ligand–ligand. Nothing is hard-coded to expect a receptor and a small molecule.
  • Chemistry from templates, geometry from coordinates. Ligands are typed from SMILES, an SDF, or an automatic Chemical Component Dictionary lookup.
  • MD trajectories — per-frame analysis with occupancy and time series.

A ChimeraX plugin builds on this library for interactive 3D visualisation.

Install

pip install chemur

Wheels are published for CPython 3.10–3.13 on Linux x86_64, macOS (a single universal2 build covering Intel and Apple Silicon) and Windows x86_64. Other platforms build from the source distribution and need a C++17 compiler and CMake ≥ 3.18.

Extra Installs Enables
trajectory MDAnalysis reading trajectory files
dataframe pandas AnalysisResult.to_dataframe()
all both 
pip install "chemur[all]"

pH-range ligand protonation (--protonate) needs no extra — dimorphite_dl is a hard dependency. It requires rdkit<2026, so a Chemur install is capped there too.

MDAnalysis is LGPL-3.0-or-later (it relicensed from GPL at 2.8.0; the >=2.4 floor still permits older GPL-licensed releases if you pin one). Chemur itself is MIT and neither bundles nor links it, but installing the trajectory extra adds copyleft-licensed code to your environment.

To confirm you got the compiled core rather than the fallback:

python -c "from chemur.core import USING_CPP_CORE; print('C++ core:', USING_CPP_CORE)"

True is expected. False means the pure-Python fallback loaded — correct results, 10–100× slower. From a wheel that should never happen; from a source build it means CMake or the compiler failed. Set CHEMUR_FORCE_PYTHON_CORE=1 to select it deliberately.

Quick start

import chemur

result = chemur.analyze("structure.cif")

for interaction in result.interactions:
    print(interaction.interaction_type, interaction.component_ids)

result.to_json("interactions.json")

chemur analyze structure.cif --out interactions.json --csv interactions.csv

Any biomolecule, not just protein–ligand

analyze returns every interaction it finds in the structure. There is no receptor or ligand role — you pick out the ones you want by component.

import chemur
from collections import Counter

result = chemur.analyze("complex.cif")

# What was found, and between what?
print(Counter(i.interaction_type for i in result.interactions))

A protein–DNA interface, a protein–protein interface and a ligand binding site are all the same query — filter on the components involved:

def between(result, a, b):
    """Interactions with one atom in component `a` and the other in `b`."""
    return [
        i for i in result.interactions
        if {a, b} <= set(i.component_ids)
    ]

interface = between(result, "A:ARG:145", "B:DG:12")   # protein side chain to a base

Components are identified by component_id; result.components lists them all with their names, so you can select a chain, a residue range, or a single ligand. Nucleic acid phosphate backbones are perceived as anions, protein Arg/Lys as cations and Asp/Glu as carboxylate anions, so salt bridges and cation–π across a protein–nucleic acid interface are detected the same way as in a binding site.

What it detects

Family Types
Hydrogen bonding hbond, weak_hbond, hbond_pi, solvent_bridge, amide_bridge
Electrostatic salt_bridge, metal_coordination, cation_pi, anion_pi, anion_aromatic_edge
Stacking pipi_stack, aliphatic_pi_stack, aliphatic_stack, amide_pi, ch_pi
σ-hole halogen_bond, chalcogen_bond, tetrel_bond, halogen_pi, chalcogen_pi
Other n_pi_star, hydrophobic

aliphatic_stack (saturated–saturated ring stacking) ships disabled; enable it in the profile. The σ-hole, stacking and n→π* geometries follow Adhav & Saikrishnan, ACS Omega 2023, 8, 22268.

Each type has its own geometric criteria, all adjustable — see docs/cli.md for overriding cutoffs and docs/chemistry.md for the chemical gates (such as why an ordinary Met sulfur cannot donate a chalcogen bond).

Ligand chemistry

Ligands need a chemical template so protonation, charge, aromaticity and donor/acceptor status are correct. Chemur takes one from, in order of precedence:

chemur analyze structure.cif --ligand-smiles LIG='CC(=O)N'   # explicit SMILES
chemur analyze receptor.pdb --ligand-sdf docked.sdf          # an SDF (coordinates too)
chemur analyze structure.cif                                 # automatic CCD lookup

The automatic lookup resolves each ligand by its component name against the RCSB Chemical Component Dictionary. Add --protonate to set the protonation state for a pH range with Dimorphite-DL, and --debug to print the SMILES actually used.

Full detail in docs/cli.md.

Multiple ligands and docking output

Pass several ligands at once, or point at a directory of sdf files.

chemur analyze receptor.pdb --ligand-sdf a.sdf --ligand-sdf b.sdf   # repeatable
chemur analyze receptor.pdb --ligand-sdf-dir poses/                 # a whole directory

By default all supplied ligands are added to the structure and analysed together, as one system — right for a cofactor plus a substrate, or two ligands sharing a pocket.

Docked poses are the opposite case: each is an alternative for the same site, so analysing them together would stack overlapping copies into one pocket. Use --batch to analyse each ligand independently against the same receptor:

chemur analyze receptor.pdb --ligand-sdf-dir poses/ --batch --out all_poses.json

Either way you also get one filtered file per ligand under ligand_outputs/ — in batch mode under a subdirectory per pose — while --out / --csv write the aggregate.

SDF coordinates are used directly, and ligand residues already present in the structure are skipped so the SDF stays authoritative.

Trajectories

pip install "chemur[trajectory]"
chemur trajectory topology.pdb trajectory.xtc --out frames.json

Analyses each frame and reports per-interaction occupancy and time series.

Documentation

Development

git clone https://github.com/SweeneyAaron/chemur
cd chemur

conda create -n chemur-dev -c conda-forge \
  python=3.11 rdkit gemmi numpy pyyaml pandas pytest \
  cmake ninja pybind11 scikit-build-core cxx-compiler
conda activate chemur-dev

pip install -e ".[test,all]" -v
pytest

On macOS you need the Apple command line tools (xcode-select --install). If the build fails with 'cstddef' file not found they are incomplete — repair with sudo rm -rf /Library/Developer/CommandLineTools && xcode-select --install.

This project uses a src/ layout and has no conftest.py on purpose, so pytest always exercises the installed package rather than the source tree. That is what makes the wheel-level checks in CI meaningful.

License

MIT — see LICENSE.

Citation

A manuscript is in preparation. Until then, please cite the repository:

Sweeney, A, Genz, L, Topf, M. Chemur: biomolecular interaction detection.
https://github.com/SweeneyAaron/chemur

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for SweeneyAaron from gravatar.com SweeneyAaron

Credits

Author/Maintainer: Aaron Sweeney

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

protonation trajectory dataframe all test

Tags

structural-biology molecular-interactions protein-ligand protein-protein nucleic-acids hydrogen-bond cheminformatics mmcif

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

chemur-0.1.0.tar.gz (120.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

chemur-0.1.0-cp313-cp313-win_amd64.whl (191.7 kB view details)

Uploaded CPython 3.13Windows x86-64

chemur-0.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (187.7 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chemur-0.1.0-cp313-cp313-macosx_11_0_universal2.whl (239.9 kB view details)

Uploaded CPython 3.13macOS 11.0+ universal2 (ARM64, x86-64)

chemur-0.1.0-cp312-cp312-win_amd64.whl (191.7 kB view details)

Uploaded CPython 3.12Windows x86-64

chemur-0.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (187.7 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chemur-0.1.0-cp312-cp312-macosx_11_0_universal2.whl (239.8 kB view details)

Uploaded CPython 3.12macOS 11.0+ universal2 (ARM64, x86-64)

chemur-0.1.0-cp311-cp311-win_amd64.whl (190.1 kB view details)

Uploaded CPython 3.11Windows x86-64

chemur-0.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (187.6 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chemur-0.1.0-cp311-cp311-macosx_11_0_universal2.whl (238.6 kB view details)

Uploaded CPython 3.11macOS 11.0+ universal2 (ARM64, x86-64)

chemur-0.1.0-cp310-cp310-win_amd64.whl (189.4 kB view details)

Uploaded CPython 3.10Windows x86-64

chemur-0.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (186.1 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

chemur-0.1.0-cp310-cp310-macosx_11_0_universal2.whl (235.7 kB view details)

Uploaded CPython 3.10macOS 11.0+ universal2 (ARM64, x86-64)

File details

Details for the file chemur-0.1.0.tar.gz.

File metadata

  • Download URL: chemur-0.1.0.tar.gz
  • Upload date:
  • Size: 120.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chemur-0.1.0.tar.gz
Algorithm Hash digest
SHA256 b0e7ed73ca3f3543b54b5e3ad081f98f2db083bea55d3cc7ebd79c38c7aa8c35
MD5 28d69b21feae40a6c56f65da2354c55c
BLAKE2b-256 ccea3a4f6afde3e34b73ddf41a5ab60954ef284a6654c0dc1c835c1f9e40882c

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0.tar.gz:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: chemur-0.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 191.7 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chemur-0.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 a5189a8600a4c0dc81092626744ebbbd8ab76a86f562197db161e4894d3f54b8
MD5 72ff27103a07c31d7ed231254973eadf
BLAKE2b-256 11233ae89658bffd8847b147376b140b3ea1e615fe1022312f33643ce972ea36

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 85e156f0ae429a3061e631f92ae380561cb47b7192fbb137f530ad774de4fcf3
MD5 2e5df0b85623c8bceb835c57c5ae77d2
BLAKE2b-256 f761bbd5017f1ffb1026522d00e49c22c28c8fc94edf44b85d230833863868c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp313-cp313-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp313-cp313-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 0c25bbcd79f3f712f95bcf08d21b5f749d0e51db33872114334e12bbd3c9907e
MD5 623b237c59771db360be9d66176bc1d3
BLAKE2b-256 ae2a4342bc562181f3ac776c218edc3f469800c592d08f284f9709811ad46fc6

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp313-cp313-macosx_11_0_universal2.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: chemur-0.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 191.7 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chemur-0.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 8d419aad4585cca72b6d472017598e42f16333b8c8867df8cc33aa2f8a502846
MD5 a2df881dd542378e4665a64b8651740f
BLAKE2b-256 ce7c485d4ab0051d21be9531badc2d632e1e07b588275c7039995d7a35fc1733

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 760c7a4317c981b5c741bece53101468adf6ed985b7d6793c39f5d53e480da5a
MD5 39f343245672162f2a68541a8901e5fa
BLAKE2b-256 72db0d557911ebb393052f8de034081c9e4cea7aedc8629783ec9ec657481cf0

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp312-cp312-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp312-cp312-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 075ef0f4ccc261724700bc75b7e8205eed7c2868d9d8f76f0819be5c88ca7fe3
MD5 06e4223503b929d33e1b70003c4c8f22
BLAKE2b-256 976370fc70bb53f63dc99099777acf9b3cead103d16e4b6d80095e6acf667754

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp312-cp312-macosx_11_0_universal2.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: chemur-0.1.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 190.1 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chemur-0.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 e438e582f0da09b7137b7734edd53bad9945d3de11769a56a2f2d2a032ef403d
MD5 81690862811bf795f617c2c93897968b
BLAKE2b-256 b38eb0244e7c8826e34c58e52cae554bd88e71e9828bcfd6196d9b6c5a7b6abe

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9fa1d5e0a7052fc392127e0cf7a33eb87032739a069ab8b137e0b2f10e0ed3f8
MD5 8821201e6c6ef7af28dc19d468df9cc9
BLAKE2b-256 00fb8c1ab29ff1bf0b1b14515cd7582db41cae1b23dc47cad419281bc503a890

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp311-cp311-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp311-cp311-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 be8cd0221403d25624eab71fcd0aab193d4d153dbd4d5b5f63832d3d6d6d843c
MD5 81c6dd7e55bd39a2c877144ef69b9312
BLAKE2b-256 e9c648b681c6fa8b9b0da98583c4dd0e368f2fcd7d90946081a52b686f4e4325

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp311-cp311-macosx_11_0_universal2.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: chemur-0.1.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 189.4 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for chemur-0.1.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 8064e6881768c628a1a6951d3c90ff2f15432e11127976ffbf737e34529d2fd5
MD5 a3925299698e4104ae7e84d56298991e
BLAKE2b-256 f5a9eed3a397d9814242c72f2ae6d64765ba23d98a1474d92f94c4691992428a

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp310-cp310-win_amd64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 152c84b567ba41a8bd8c2ed187e81da68b6f04378fcb71992e1e60c1fb959cff
MD5 9ea2fa7189f7099f806ba635c64997e0
BLAKE2b-256 6deb34f5bb24fd061e1b599b451ad21457ab29f9e9c1c5fe8ac0b6b1dce6680f

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file chemur-0.1.0-cp310-cp310-macosx_11_0_universal2.whl.

File metadata

File hashes

Hashes for chemur-0.1.0-cp310-cp310-macosx_11_0_universal2.whl
Algorithm Hash digest
SHA256 9db96c2a71efee080cb8119860e25cc769ed7cd0b2615a99e38893761cbc65a0
MD5 2305b771b62c2b590f0ea55346ae7a80
BLAKE2b-256 1f93b8e7ac5301ebf03c3871373f08cb9c15cd07779be1db7cd28247bf077c57

See more details on using hashes here.

Provenance

The following attestation bundles were made for chemur-0.1.0-cp310-cp310-macosx_11_0_universal2.whl:

Publisher: release.yml on SweeneyAaron/chemur

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page