# PXMeter

**Repository Path**: ByteDance/PXMeter

## Basic Information

- **Project Name**: PXMeter
- **Description**: Structural Quality Assessment for Biomolecular Structure Prediction Models
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-16
- **Last Updated**: 2026-02-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PXMeter - Structural Quality Assessment for Biomolecular Structure Prediction Models

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

<div align="left" style="margin: 20px 0;">
<span style="margin: 0 10px;">📄 <a href="https://www.biorxiv.org/content/10.1101/2025.07.17.664878v1">From Dataset Curation to Unified Evaluation: Revisiting
 Structure Prediction Benchmarks with PXMeter</a></span>
</div>

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

```bash
# 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:

```bash
pxm ccd update
```

## 🚀 Quick Start

### Command Line Interface
```bash
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.


```python
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:
```python
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.
```python
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](docs/pxmeter_eval_details.md).

For a comprehensive overview of the runtime configuration options, recommended defaults, and advanced usage examples, see the [PXMeter run configuration guide](docs/run_config_details.md).

### Optional: Stereochemistry checks

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

```bash
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:

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

- The **[Benchmark Documentation](docs/benchmark.md)** explains how to run evaluations on model predictions and how the aggregated metrics are computed.
- The **[Dataset Pipeline Overview](docs/datapipeline.md)** 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](docs/legacy_dataset_reference.md)**, 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](docs/gen_input.md).
 — 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](CONTRIBUTING.md) to get started.

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

```bash
pip install pre-commit
pre-commit install
```


## ✍️ Citing PXMeter
If you use PXMeter in your research, please cite the following:
```bibtex
@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](https://security.bytedance.com/src) or [vulnerability reporting email](sec@bytedance.com).

Please do **not** create a public GitHub issue.

## ⚖️ License
The PXMeter project is made available under the [Apache 2.0 License](./LICENSE), it is free for both academic research and commercial use.