PXMeter - Structural Quality Assessment for Biomolecular Structure Prediction Models

📄 From Dataset Curation to Unified Evaluation: Revisiting Structure Prediction Benchmarks with PXMeter

PXMeter is a comprehensive toolkit for evaluating the quality of structures generated by biomolecular structure prediction models, with support for proteins, nucleic acids, and small molecules.

🌟 Features

Full-Atom Matching Between Reference and Model Structures: Automatically matches entities, aligns sequences, and permutes chains and atoms to establish one-to-one correspondence.
Multi-metric Evaluation:
- Local Distance Difference Test (LDDT) - A local superposition-free score for comparing reference and model structures.
- DockQ - Interface interaction quality.
- Pocket-aligned Root Mean Squared Deviation (RMSD) - Ligand pose quality.
- PoseBusters Validity Checks - Plausibility checks for generated molecule poses.
Dual Interfaces: CLI & Python API

🛠️ Installation

# Install from PyPI
pip install pxmeter

# Install from source
git clone https://github.com/bytedance/PXMeter.git
cd PXMeter
pip install -r requirements.txt
pip install -e .

PXMeter directly uses the Chemical Component Dictionary (CCD) bundled with Biotite. To update the CCD files:

pxm ccd update

🚀 Quick Start

Command Line Interface

pxm -r examples/7rss.cif -m examples/7rss_protenix_pred.cif -o pxm_output.json

Key Parameters:

-r or --ref_cif: Path to reference CIF file
-m or --model_cif: Path to model CIF file
-o or --output_json: Path to save evaluation results (default: “pxm_output.json”)
--ref_model: Specify model number of reference CIF (default: 1)
--ref_assembly_id: Specify the assembly ID for the reference CIF (default: None; uses the Asymmetric Unit for evaluation)
--ref_altloc: Specify the alternative location identifier for the reference CIF (default: “first”, uses the first alternative location code for each residue).
--chain_id_to_mol_json: JSON file defining custom ligands, where keys are chain IDs (label_asym_id) and values are the corresponding ligand SMILES strings.
-l or --interested_lig_label_asym_id: Indicate the label_asym_id of ligands for metrics like pocket-aligned RMSD. Multiple ligands should be comma-separated.
-C key.path=value: Override fields in pxmeter.configs.run_config.RUN_CONFIG (repeatable; e.g., -C metric.lddt.eps=1e-4 -C mapping.mapping_ligand=false).

To access the full list of parameters, use the --help option.

Python API

Note: For batch evaluation of multiple structures, the Python API is highly recommended. This approach is more efficient than repeated command line calls because it caches CCD CIF files in memory and thus avoids redundant disk I/O.

from pxmeter.eval import evaluate

ref_cif = "examples/7rss.cif"
model_cif = "examples/7rss_protenix_pred.cif"
metric_result = evaluate(
    ref_cif=ref_cif,
    model_cif=model_cif,
)

json_dict = metric_result.to_json_dict()
print(json_dict)

For detailed descriptions of additional parameters, use the help() function:

help(evaluate)

If you need to modify the runtime settings defined in pxmeter.configs.run_config.RUN_CONFIG (equivalent to using -C on the command line), you may directly update the values in RUN_CONFIG and then pass it into the evaluate() function.

from pxmeter.configs.run_config import RUN_CONFIG

RUN_CONFIG.mapping.res_id_alignments = False
metric_result = evaluate(
    ...,
    run_config=RUN_CONFIG,
)

For a detailed, step-by-step description of the PXMeter runtime evaluation pipeline (mapping, alignment, and metric computation), please refer to the PXMeter evaluation pipeline details.

For a comprehensive overview of the runtime configuration options, recommended defaults, and advanced usage examples, see the PXMeter run configuration guide.

Optional: Stereochemistry checks

Run stereochemistry checks for a single CIF and export a CSV report:

pxm stereocheck -c examples/7rss_protenix_pred.cif -o stereochem_report.csv

pxm stereocheck Parameters:

-c or --cif (required): Path to the CIF file
-o or --output-csv: Path to the output CSV report (default: stereochem_report.csv)

📊 Benchmarking

PXMeter offers a reproducible workflow covering both dataset creation and model evaluation.

Note: The benchmarking workflow (the benchmark/ directory) is only available in the source repository and is not shipped with the PyPI package. To run benchmarking, please clone the repository first:

git clone https://github.com/bytedance/PXMeter.git
cd PXMeter

The Benchmark Documentation explains how to run evaluations on model predictions and how the aggregated metrics are computed. If you want to use the pre-made PXM series datasets, you should also refer to this instruction.
The Dataset Pipeline Overview describes the complete construction of the RecentPDB low-homology dataset, including filtering, homology scans, clustering, and subset labeling. The pipeline also allows users to rebuild the evaluation dataset from scratch using any custom time window. This makes the benchmark fully flexible and adaptable to different release periods or ongoing updates from the PDB.
For details on the dataset used in our paper, please refer to the legacy dataset documentation, which describes the dataset version and evaluation code used at the time of the initial release.

➡️ Preparing input files

When working with structural inputs—e.g., converting mmCIF, AlpahFold3, Protenix, or Boltz formats—you may find the following utility helpful:

pxm gen-input Usage Guide. — a tool for generating and converting model input files via CLI or Python API.

💪 Contributing to PXMeter

We welcome contributions from the community to help improve PXMeter!

Check out the Contributing Guide to get started.

Code Quality: We use pre-commit hooks to maintain consistent programming style and code quality. Please install them before committing.

pip install pre-commit
pre-commit install

✍️ Citing PXMeter

If you use PXMeter in your research, please cite the following:

@article {Ma2025.07.17.664878,
    author = {Ma, Wenzhi and Liu, Zhenyu and Yang, Jincai and Lu, Chan and Zhang, Hanyu and Xiao, Wenzhi},
    title = {From Dataset Curation to Unified Evaluation: Revisiting Structure Prediction Benchmarks with PXMeter},
    year = {2025},
    doi = {10.1101/2025.07.17.664878},
    publisher = {Cold Spring Harbor Laboratory},
    URL = {https://www.biorxiv.org/content/early/2025/07/22/2025.07.17.664878},
    eprint = {https://www.biorxiv.org/content/early/2025/07/22/2025.07.17.664878.full.pdf},
    journal = {bioRxiv}
}

🚧 Limitations

It is recommended to use CIF files from the RCSB PDB as references, as they ensure content accuracy. All development and testing were conducted exclusively on CIF files from this source.

🛡️ Security

If you discover a potential security issue in this project, or think you may have discovered a security issue, we ask that you notify Bytedance Security via our security center or vulnerability reporting email.

Please do not create a public GitHub issue.

⚖️ License

The PXMeter project is made available under the Apache 2.0 License, it is free for both academic research and commercial use.