xpid 2.1.3

Detector for XH-π interactions in protein structures.

Xpid

Xpid detects XH–π interactions in protein structures from PDB/mmCIF files using Gemmi.

• Source code: https://github.com/SeanWang5868/xpid2
• PyPI: https://pypi.org/project/xpid/

Installation

pip install xpid

For Parquet export:

pip install "xpid[parquet]"

The demo notebook also uses:

pip install "xpid[demo]"

Monomer Library

Hydrogen placement depends on the CCP4 monomer library. Xpid handles this automatically:

1. It first looks for an existing CCP4 monomer library through CLIBD_MON, GEMMI_MON_LIB_PATH, CLIBD, or CCP4.
2. If no local CCP4 library is found, it downloads the CCP4 monomer library from MonomerLibrary/monomers into the user cache.

There is no manual monomer-library setup step for normal use.

Quick Start

Scan one structure:

xpid 1abc.cif --file-type csv

By default, the result is written beside the scanned structure:

/path/to/1abc.cif
/path/to/xpid_results.csv

Scan a directory:

xpid ./structures --file-type json

The merged result is written into ./structures/xpid_results.json.

Use a PDB code list with a local mirror:

xpid --pdb-list codes.txt --pdb-mirror /path/to/pdb/mirror

Prefer PDB-REDO structures when available:

xpid --pdb-list codes.txt --redo-mirror /path/to/pdb-redo/mirror --pdb-mirror /path/to/pdb/mirror

Python API

from xpid import detect

results = detect("structure.cif")
for hit in results:
    print(hit["pdb"], hit["pi_res"], hit["X_res"], hit["dist_X_Pi"])

Output column names currently remain ASCII for compatibility with existing scripts.

Demo Notebook

xpid_demo.ipynb is a complete guided tutorial. It:

1. lists the required Python packages,
2. downloads PDB entry 5FJJ beside the notebook,
3. verifies which CCP4 monomer library Xpid is using,
4. runs detection,
5. summarizes XH–π interactions with tables and plots,
6. demonstrates filtering and command-line usage.

Geometric Criteria

Definitions: Cπ = ring centroid, n = ring normal, X = donor heavy atom, Xp = projection of X onto the π plane, H = hydrogen.

Hudson System

Parameter	Threshold
d(X–Cπ)	≤ 4.5 Å
angle(X–H–n)	≤ 40°
d(Xp–Cπ)	≤ 1.6 Å for 5-membered rings; ≤ 2.0 Å for 6-membered rings

Plevin System

Parameter	Threshold
d(X–Cπ)	≤ donor-element cutoff
angle(X–H–Cπ)	≥ 120°
angle(X–Cπ–n)	< 25°

Command-Line Options

Input

Argument	Description
inputs	PDB/CIF file(s) or directory path(s).
--pdb-list	Text file containing PDB codes, separated by commas or whitespace.
--pdb-mirror	Path to a local PDB mirror.
--redo-mirror	Path to a local PDB-REDO mirror, prioritized over --pdb-mirror.

Output

Argument	Description
--out-dir	Override the output directory.
--output-name	Merged output filename stem. Default: xpid_results.
--separate	Write separate output files per structure.
--file-type	json, csv, or parquet. Default: json.
-v, --verbose	Include detailed geometric columns.
--log	Save a run log.

Processing

Argument	Description
--jobs N	Number of worker processes. Default: 1.
--h-mode N	Gemmi hydrogen mode: 0=NoChange, 1=Shift, 2=Remove, 3=ReAdd, 4=ReAddButWater, 5=ReAddKnown.
--model ID	Model index to analyze, or all.
--cone	Enable implicit cone rescue for rotatable groups.
--sym-contacts	Detect contacts across crystallographic symmetry mates.
--include-water	Include water molecules as potential donors.
--max-b N	Exclude contacts when any π-ring atom or X atom has B-factor above N. 0 disables this filter.

Filters

Argument	Description
--pi-res	Limit π-acceptor residues, for example TRP,TYR.
--donor-res	Limit donor residues, for example LYS,ARG.
--donor-atom	Limit donor element symbols or exact atom names, for example N,O,C or OG,NZ.
--min-occ N	Minimum combined occupancy to report. Default: 0.0.

Output Data

Simple mode includes structure ID, resolution, donor/π-acceptor residue IDs, X atom, H atom, d(X–Cπ), Hudson/Plevin flags, remarks, and symmetry operation index.

Verbose mode adds secondary-structure annotations, π-center and X coordinates, angles, projection distance, sequence separation, and B-factors.

Notes

• Same-residue donor/π-acceptor contacts are excluded.
• The automatic monomer-library download is stored in the user cache, not inside the installed package directory.
• Output column names currently remain ASCII (pi_res, dist_X_Pi) to avoid breaking existing scripts.

Contact

Sean Wang, York Structural Biology Laboratory (YSBL), University of York