xpid 2.1.2

Detector for XH-pi interactions in protein structures.

Xpid

Xpid is a Gemmi-based tool for detecting XH–π interactions in protein structures from PDB/mmCIF files.

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

---

Installation

Requires Python 3.9+.

pip install xpid

Configuration

The detection of XH–π interactions depends on the position of H atoms. To add hydrogen atoms before detection, specify the path to a monomer library (e.g. CCP4 monomer library):

xpid --set-mon-lib /path/to/monomers

Quick Start

Scan a directory or a single PDB/mmCIF file:

xpid 1abc.cif --file-type csv

Output: ./xpid_output/xpid_results.json

Use a PDB code list with a local mirror:

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

Use PDB-REDO structures (prioritized over standard PDB):

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

Export results in different formats:

xpid ./data --file-type csv
xpid ./data --file-type parquet

Python API

Xpid can also be used as a library:

from xpid import detect

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

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 Å
∠(X–H–n)	≤ 40°
d(Xp–Cπ)	≤ 1.6 Å (His, Trp-A); ≤ 2.0 Å (Phe, Trp-B, Tyr)

Plevin System

Parameter	Threshold
d(X–Cπ)	≤ 4.5 Å
∠(X–H–Cπ)	≥ 120°
∠(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 (comma or newline separated).
--pdb-mirror	Path to a local PDB mirror (divided layout).
--redo-mirror	Path to a local PDB-REDO mirror (prioritized over --pdb-mirror).

Output

Argument	Description
--out-dir	Custom output directory (default: ./xpid_output).
--output-name	Filename for merged output (default: xpid_results).
--separate	Write separate output files per PDB (default: merged).
--file-type	Output format: json (default), csv, or parquet.
-v, --verbose	Include detailed geometric metrics in output.
--log	Save run log to file.

Processing

Argument	Description
--jobs N	Number of CPU cores (default: 1).
--h-mode N	Hydrogen handling mode: 0=NoChange, 1=Shift, 2=Remove, 3=ReAdd, 4=ReAddButWater (default), 5=ReAddKnown.
--model ID	Model index to analyze (default: 0; use all for NMR ensembles).
--cone	Enable implicit cone logic for rotatable groups.
--sym-contacts	Detect interactions across crystallographic symmetry mates.
--include-water	Include water molecules as potential donors.
--max-b N	Maximum B-factor filter (default: 0 = no filter).

Filters

Argument	Description
--pi-res	Limit acceptor residues (e.g., TRP,TYR).
--donor-res	Limit donor residues (e.g., LYS,ARG).
--donor-atom	Limit donor element types (e.g., N,O,C).
--min-occ N	Minimum combined occupancy to report (default: 0.0).
--mon-lib	Path to a custom monomer library for this run.
--set-mon-lib	Permanently save a default monomer library path.

Output Data

Simple Mode (default)

• PDB ID, Resolution
• Chain, Residue Name, Residue ID for both donor (X) and acceptor (π) residues
• Distance d(X–Cπ)
• Hudson / Plevin classification flags
• Symmetry operation (if applicable)

Verbose Mode (-v)

All simple fields, plus:

• Secondary structure: Type (H/G/I/E/C) and region IDs
• Coordinates: x, y, z for π-center and X-atom
• Geometric parameters: ∠(X–H–n), ∠(X–H–Cπ), ∠(X–Cπ–n), d(Xp–Cπ)
• B-factors: Average B-factor for ring atoms and X-atom

Dependencies

• gemmi — macromolecular crystallography library
• numpy — numerical computing
• pandas + pyarrow — required only for Parquet output

---

Contact

Sean Wang — [e-mail]

York Structural Biology Laboratory (YSBL), University of York