Skip to content

About

PDB and mmCIF parsers, and selections from ProDy

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

prodyparsers

prodyparsers contains the PDB and mmCIF parsers and the atomic data structures (atom groups, hierarchical views, and atom selections) of ProDy, stripped down to a small pure Python package. It exists so that Meeko can read PDB and mmCIF files on recent Python versions.

import prodyparsers

atoms = prodyparsers.parsePDB("receptor.pdb", altloc="all")   # or parseMMCIF("receptor.cif")
site = atoms.select("chain A and resname CYS and (name CA or name CB)")
for chain in atoms.getHierView().iterChains():
    for residue in chain.iterResidues():
        print(residue.getChid(), residue.getResname(), residue.getResnum(), residue.getIcode())

The API is ProDy's API. Code written for prody.parsePDB, prody.parseMMCIF, AtomGroup, Selection, HierView, Chain, Residue, Segment, Atom and the selection language works unchanged after you replace prody with prodyparsers. confProDy is not included. To silence the log messages, use prodyparsers.LOGGER.verbosity = 'none'.

Why this package exists

ProDy is a large package for protein dynamics: normal mode analysis, ensembles, trajectories, sequence analysis and more. It ships several C/C++ extensions. Meeko uses only a small part of it: reading PDB and mmCIF files, iterating over chains and residues, and atom selections. As of ProDy 2.6.1 (the current release in October 2026):

  • PyPI has only a CPython 3.12 Linux wheel. Every other Python version and platform must compile ProDy's C extensions from source.
  • ProDy pins pyparsing<=3.1.1. Newer pyparsing releases cannot be used next to it.
  • The selection grammar breaks with pyparsing 3.3.3 (released 2026-09-20). For example, name CA or name CB fails to parse, because pyparsing's infix_notation was reimplemented.
  • Importing ProDy prints SyntaxWarning: invalid escape sequence on recent Python versions. ProDy also reads and writes a pickled settings file, ~/.prodyrc.

prodyparsers keeps only the parsing and selection code. It has no compiled extensions, so a single py3-none-any wheel (and a noarch: python conda package) works on every platform and Python version (3.10 and later). It depends only on numpy and pyparsing>=3.0.9, including the latest pyparsing.

Provenance

prodyparsers was made from the ProDy v2.6.1 release:

  • repository: https://github.com/prody/ProDy
  • tag v2.6.1, commit f83690d5e1b93bce04c04c6561cb55fe1ba26a6c (2025-08-14), which is identical to the prody==2.6.1 package on PyPI and conda-forge

The files kept from ProDy, now under src/prodyparsers/:

prodyparsers ProDy v2.6.1 changes
atomic/*.py prody/atomic/*.py imports only, plus the select.py fixes listed below
proteins/pdbfile.py prody/proteins/pdbfile.py parsing only (writers, PQR and fetching removed)
proteins/ciffile.py prody/proteins/ciffile.py parsing only (writer and fetching removed), plus the mmCIF fix below
proteins/starfile.py prody/proteins/starfile.py only parseSTARLines and parseSTARSection
kdtree/kdtree.py prody/kdtree/kdtree.py uses the pure Python backend below
utilities/*.py prody/utilities/*.py only the helpers the code above uses
utilities/datafiles/mod_res_map.dat same none
tests/test_select.py prody/tests/atomic/test_select.py ported to pytest
tests/data/*.gz prody/tests/datafiles/ a subset, gzipped; icode_altloc.pdb.gz is made from pdb1ubi.pdb, *_gemmi*.cif.gz were converted with gemmi from pdb1ubi.pdb and pdb2k39_truncated.pdb (some with wrapped records), and pdb3mht_secstrs.txt.gz was written with ProDy

The atomic data structures are kept as is, so this package can follow future ProDy releases with little effort.

What was changed

  • Package name. prody is renamed to prodyparsers, so both packages can be installed side by side. The logger is named .prodyparsers.
  • pyparsing. atomic/select.py uses pyparsing's PEP 8 API (set_parse_action, infix_notation, parse_all, …), which has been available since pyparsing 3.0, instead of the camelCase names deprecated in pyparsing 3.3. The optional and between selection terms used to be written Optional(AND). It is now AND | Empty().leave_whitespace(), which parses the same way with every pyparsing version from 3.0.9 to 3.3.3. With pyparsing 3.3.3, Optional(AND) made selections with or fail.
  • mmCIF atom block. ProDy 2.6.1 ends the _atom_site block at the first line that does not start with ATOM/HETATM. As a result it drops the last atom when the file ends with an atom record, which makes altloc='all' fail with an IndexError. Every atom after the first record that is wrapped over two lines is also lost silently. For example, only 1312 of the 7333 atoms of ProDy's own test file NRAS_BRAF_GDP_model_0.cif are read. mmCIF files written by gemmi, which meeko uses, can hit both problems. ProDy's development branch changed this in PR #1922 (merge commit 0b7cfc3), and that change is backported here with two corrections:
    • ProDy's version ends the block only at a # line, so it fails on files without # separators, as gemmi writes them. Here the block also ends at a blank line, a tag, loop_, data_, save_ or the end of the file.
    • ProDy's version reads the wrong line when joining a wrapped record. It gives correct results only when the wrapped field is the unused model number.
  • Backports from ProDy's development branch. Commit 13dde87 ("fix invalid escape sequences") fixes three escape sequences in atomic/flags.py and atomic/select.py, and also renames the selection function tahn to tanh.
  • KDTree. ProDy's compiled _CKDTree (from Biopython) is replaced with kdtree/_ckdtree.py, a small shim over scipy.spatial.cKDTree. It uses the same single precision and the same inclusive radius. SciPy is imported only when a distance-based selection (within, exwithin) is evaluated, so it is an optional dependency (pip install prodyparsers[kdtree]). Compared with ProDy, point searches, periodic-cell searches, AtomGroup.inferBonds() and distance-based selections give the same results. Pair searches with KDTree.search(radius) find the same pairs and distances, but list them in a different order, and always with the lower index first.
  • Biopython. ProDy imports Biopython only to look up atomic masses. The same table (Bio.Data.IUPACData.atom_weights) is now included in utilities/misctools.py, under the Biopython license (see LICENSE).
  • Settings. Settings are kept in memory only. Nothing is read from or written to ~/.prodyrc. User-defined selection macros and flag definitions last until the session ends.

What was removed

Everything else in ProDy: dynamics, ensembles, trajectories, sequence and MSA tools, measurement and alignment functions, databases, the prody command line tool, and the C/C++ extensions. On the parser side:

  • fetching files from the PDB (fetchPDB, PDB IDs passed to parsePDB or parseMMCIF). Pass a file name instead.
  • header parsing. The keyword arguments header=True, biomol=True and secondary=True raise NotImplementedError.
  • writers (writePDB, writePQR, writeMMCIF), parsePQR, parseChainsList, and EMD/MMTF/STAR file support

If you need any of these, use ProDy.

How sameness with ProDy is checked

  • tests/reference.json holds fingerprints (hashes of every per-atom array, coordinate set, hierarchical view and 30 selections) for 26 parser calls on 16 structures. It was generated by running tests/make_reference.py with ProDy 2.6.1 on Python 3.12. tests/test_reference.py checks that prodyparsers reproduces each of them exactly.
  • mmCIF files that ProDy 2.6.1 reads incorrectly (see above) are checked against gemmi instead: tests/gemmi_reference.json has the serial numbers and coordinates of all models, as read by gemmi (tests/make_gemmi_reference.py), and tests/test_gemmi_reference.py checks them.
  • tests/test_select.py is ProDy's selection test suite. It runs 257 selections with expected atom counts, each on an AtomGroup and on a Selection.
  • The test suite passes with Python 3.10 and numpy 1.22 with pyparsing 3.0.9, and with Python 3.14 and numpy 2.5 with pyparsing 3.0.9, 3.1.1, 3.2.3 and 3.3.3. Every warning is treated as an error.

To update the reference, run python tests/make_reference.py in an environment that has ProDy installed.

Installation

pip install prodyparsers
# or
conda install -c conda-forge prodyparsers

License and citation

prodyparsers is distributed under the MIT License, like ProDy. The ProDy copyright notice (Copyright (C) 2010-2014 University of Pittsburgh) is kept in LICENSE, together with the Biopython license for the atomic-weight table.

All of the code here was written by the ProDy developers. If you use it in published work, please cite ProDy:

  • Zhang S, Krieger JM, Zhang Y, Kaya C, Kaynak B, Mikulska-Ruminska K, Doruker P, Li H, Bahar I. ProDy 2.0: Increased Scale and Scope after 10 Years of Protein Dynamics Modelling with Python. Bioinformatics 2021 37(20):3657-3659.
  • Bakan A, Meireles LM, Bahar I. ProDy: Protein Dynamics Inferred from Theory and Experiments. Bioinformatics 2011 27(11):1575-1577.

About

PDB and mmCIF parsers, and selections from ProDy

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages