protcross 0.1.3

Domain-adaptive protein point-cloud binding-site prediction.

ProtCross

ProtCross is a domain-adaptive protein point-cloud learning framework for binding-site prediction across experimentally solved PDB structures and predicted AlphaFold2 (AF2) structures. The model accepts structures from AlphaFold and can write per-residue binding probabilities to the B-factor column of a new PDB output file.

Published paper (JCIM): Zhong, S., & Jiang, Y. (2026). ProtCross: Bridging the PDB-AlphaFold Gap for Binding Site Prediction with Protein Point Clouds. Journal of chemical information and modeling, 66(7), 3688-3701. https://doi.org/10.1021/acs.jcim.5c03224

The codebase combines:

• residue-level structural geometry (C-alpha coordinates),
• language-model residue embeddings (ESM-C), and
• confidence-aware domain adaptation (pLDDT-weighted DANN)

to improve robustness when transferring from PDB (source domain) to AF2 (target domain).

---

Quick Start

Use this path when you only want to predict binding sites for one structure.

pip install "protcross[predict]"
protcross predict input.pdb

By default this writes a complete result package next to the input: input.protcross.pdb, input.protcross.scores.tsv, input.protcross.pockets.json, and input.protcross.summary.json. For mmCIF input, the annotated structure output uses .cif.

On the first prediction run, ProtCross automatically installs runtime assets into ~/.cache/protcross/assets/v0.1.2 by default:

protcross-0.1.2-binding-moad-final.ckpt    # recommended release checkpoint
pca_esmc_128_binding_moad_0.1.2.pkl        # matching PCA reducer
esmc_600m_2024_12_v0.pth                   # ESM-C weights from Hugging Face

PyPI packages ship code only. Use protcross setup-assets when you want to pre-download assets, install a specific asset bundle, or provide custom URLs:

protcross setup-assets \
  --checkpoint-url https://example.org/protcross-0.1.2-binding-moad-final.ckpt \
  --pca-url https://example.org/pca_esmc_128_binding_moad_0.1.2.pkl

Use the 0.1.2 release checkpoint for practical binding-site prediction and when reporting ProtCross as a benchmark method. If ProtCross is used as a benchmark, report the probability threshold used for the final predictions.

Training a new release-style model uses the modern protcross train, protcross preprocess, protcross download-af2, and protcross map-labels commands. Paper-reproduction notes are documented in reproduction/legacy/README.md.

If your system already has ESM-C weights, skip that large download and pass the path at prediction time:

protcross setup-assets --skip-esm
protcross predict input.pdb \
  --esm-weights /absolute/path/to/esmc_600m_2024_12_v0.pth \
  --out-dir protcross-results

Table of Contents

• Quick Start
• 1. Project Overview
• 2. Installation
  • 2.1 System Requirements
  • 2.2 Create Environment
  • 2.3 Runtime Assets
  • 2.4 Verify Installation
• 3. Usage
  • 3.1 Apply ProtCross (Inference with Existing Model)
    • 3.1.1 Single-structure Prediction
    • 3.1.2 Batch Prediction (Multiple Structures)
  • 3.2 Retrain Release Workflow
    • 3.2.1 Data Preparation
    • 3.2.2 Preprocess Source (PDB) with PCA Fit
    • 3.2.3 Preprocess Target (AF2) with Shared PCA
    • 3.2.4 Map Labels from PDB to AF2
    • 3.2.5 Train
• 4. Configuration Guide (Hydra)
• 5. Repository Layout
• 6. Troubleshooting
• 7. Changelog
• 8. License

---

1. Project Overview

Core capabilities

• Binding-site segmentation on protein point clouds with PointNet++.
• Domain adaptation (DANN-style) via gradient reversal and domain discriminator.
• AF2 confidence-aware weighting based on pLDDT.
• ESM-C embeddings + PCA reduction for residue features.
• Hydra-driven experiment control with easy command-line overrides.

Primary stack

• PyTorch + PyTorch Lightning
• Torch Geometric
• Hydra
• ESM (EvolutionaryScale)

---

2. Installation

2.1 System Requirements

• Linux (recommended) or WSL2
• Python 3.10
• Conda (Miniconda or Anaconda)
• NVIDIA GPU + CUDA 12.1 (recommended for training and ESM-C preprocessing)

CPU-only runs are possible for debugging/small tests but will be significantly slower.

2.2 Create Environment

For development or training:

conda env create -f environment.yml
conda activate protcross
pip install -e ".[test,esm]"

For the lightweight prediction interface from PyPI:

pip install "protcross[predict]"
protcross predict input.pdb --output input.protcross.pdb

The provided environment includes:

• pytorch==2.3.0
• pytorch-cuda==12.1
• Torch Geometric and companion packages
• esm>=3.1.0 for ESM-C APIs

CPU-only notes

If you do not have a CUDA-capable GPU:

1. Remove/replace pytorch-cuda=12.1 in environment.yml.
2. Install CPU-compatible PyTorch/Torch Geometric wheels.
3. Run preprocessing/training with --device cpu or CPU trainer settings.

2.3 Runtime Assets

ProtCross separates code and large runtime assets. PyPI distributions include the Python package and command-line tools, while the pretrained checkpoint, PCA reducer, and ESM-C weights are downloaded after installation.

Recommended setup:

protcross setup-assets

Manual setup is optional for standard prediction because protcross predict automatically downloads missing default assets. By default this downloads:

• ESM-C 600M weights from https://huggingface.co/EvolutionaryScale/esmc-600m-2024-12
• protcross-0.1.2-binding-moad-final.ckpt from the ProtCross v0.1.2 GitHub release
• pca_esmc_128_binding_moad_0.1.2.pkl from the ProtCross v0.1.2 GitHub release

The default asset version is fixed by the installed package for reproducibility. default and latest both mean the current packaged stable bundle, currently 0.1.2; they do not query a floating remote latest release. The concrete bundle version is recorded in protcross-assets.json. The default install location is ~/.cache/protcross/assets/v0.1.2. You can override it with PROTCROSS_ASSETS_DIR or --output-dir:

PROTCROSS_ASSETS_DIR=/data/protcross-assets protcross setup-assets
protcross setup-assets --output-dir /data/protcross-assets

After setup, prediction can discover assets automatically:

protcross predict input.pdb --out-dir protcross-results

To disable automatic asset setup during prediction, pass --no-auto-assets or --offline. To repair a stale cache, pass --refresh-assets.

For source checkouts or custom releases, explicit paths are still supported:

protcross predict input.pdb \
  --checkpoint checkpoints/protcross-0.1.2-binding-moad-final.ckpt \
  --esm-weights /absolute/path/to/esmc_600m_2024_12_v0.pth \
  --pca data/pca_esmc_128_binding_moad_0.1.2.pkl \
  --out-dir protcross-results

What is ESM-C?

ESM-C is EvolutionaryScale's protein language model family for extracting residue-level sequence representations. In ProtCross, ESM-C embeddings are used as per-residue features.

Recommended checkpoint for this project:

• ESM-C 600M (2024-12): https://huggingface.co/EvolutionaryScale/esmc-600m-2024-12

The ESM-C model repository uses a custom non-commercial license. Review the model terms before downloading or redistributing derived assets.

Manual ESM-C download fallback

If the automatic downloader is unavailable in your environment, you can download the model weights from Hugging Face in either of the following ways.

Option A - Git LFS clone

# 1) Install Git LFS once (if needed)
git lfs install

# 2) Clone the model repository
git clone https://huggingface.co/EvolutionaryScale/esmc-600m-2024-12

Option B - Hugging Face CLI

# 1) Install CLI
pip install -U "huggingface_hub[cli]"

# 2) Download repository files to a local directory
huggingface-cli download EvolutionaryScale/esmc-600m-2024-12 \
  --local-dir ./esmc-600m-2024-12

After downloading, locate data/weights/esmc_600m_2024_12_v0.pth and pass its absolute path to --esm-weights.

Example:

protcross preprocess \
  --data-dir data/raw_pdb \
  --output-dir data/processed_pdb \
  --fit-pca \
  --esm-weights /absolute/path/to/esmc_600m_2024_12_v0.pth \
  --pca artifacts/protcross-pca-128.pkl

Important details:

• --esm-weights is treated as a local file path.
• The script truncates sequences to length 1022 for ESM-C context compatibility.

2.4 Verify Installation

python -c "import torch; import torch_geometric; import pytorch_lightning; import hydra; import esm; print('OK')"
pytest -q

---

3. Usage

This section is split into two maintained workflows:

• Apply 0.1.2 release model: use the released checkpoint for inference.
• Retrain release workflow: rebuild datasets/features and train with modern CLI commands.

For most users, the 0.1.2 release checkpoint is the recommended model. It was trained as a release model for external generalization evaluation using Binding MOAD-derived source structures and matched AF2 target structures. If you use ProtCross as a benchmark, use the release checkpoint and report the threshold used for evaluation.

Paper-reproduction notes are kept under reproduction/legacy/.

3.1 Apply ProtCross (Inference with Existing Model)

3.1.1 Single-structure Prediction

You can directly run inference on one PDB/mmCIF structure and write a complete prediction package.

The recommended 0.1.2 path for PyPI users is:

protcross predict examples/6fhu.pdb --out-dir examples/protcross-results

This writes:

• 6fhu.protcross.pdb: annotated structure with scored protein-residue B-factors set to ProtCross probabilities.
• 6fhu.protcross.scores.tsv: residue-level table for downstream scripts.
• 6fhu.protcross.pockets.json: pocket center, residues, scores, residue count, and clustered pockets.
• 6fhu.protcross.summary.json: machine-readable run summary.

Use --summary-only to restore the old behavior and print a summary without creating default output files. Individual paths can still override the defaults:

protcross predict examples/6fhu.pdb \
  --output examples/6fhu.protcross.pdb \
  --scores-tsv examples/6fhu.scores.tsv \
  --pocket-json examples/6fhu.pockets.json \
  --summary-json examples/6fhu.summary.json \
  --threshold 0.5

Prediction output semantics:

• --threshold uses a strict probability > threshold rule for binary calls, TSV is_binding, pocket selection, clustering, and summaries.
• The annotated structure B-factor column always stores continuous ProtCross probabilities in the 0..1 range for scored protein residues. It is not an experimental B-factor. By default, unscored atoms keep their original B-factor; use --unscored-bfactor-policy zero when a viewer or downstream script should treat unscored atoms as zero.
• Pocket coordinates are in the input structure coordinate frame, in Angstrom, using C-alpha atoms.
• summary.top_pocket.center and terminal Pocket center refer to the highest-ranked clustered pocket, not the aggregate of all selected residues. aggregate_pocket.center is reported separately for all selected residues.
• Clustered pockets are connected components from selected residues using the default 8 Angstrom C-alpha cutoff.
• CLI and Python API prediction fail on structures longer than --max-len by default. Pass --allow-truncation or allow_truncation=True to explicitly score only the leading ESM-C context window.

Extended TSV columns:

residue_id, residue_key, residue_id_namespace, model_id, chain_id,
auth_asym_id, label_asym_id, residue_number, auth_seq_id, label_seq_id,
insertion_code, resname, one_letter_code, input_bfactor, probability,
is_binding, x, y, z, cluster_id, is_scored, rank_global, rank_within_chain

Output schema contract:

• scores.tsv: tab-separated UTF-8; probabilities are floats in 0..1; coordinates are Angstrom C-alpha coordinates in input frame; nullable fields are empty strings.
• pockets.json: schema_version is protcross-pocket-v1; includes asset_version, threshold metadata, coordinate units, residue_id_namespaces, aggregate_pocket, and clustered_pockets. If no residue is selected, aggregate_pocket is null and clustered_pockets is empty.
• summary.json: schema_version is protcross-summary-v1; includes input path, device, asset version, threshold, cluster cutoff, scored/original residue counts, truncation flag, unscored_bfactor_policy, top_pocket, aggregate_pocket, top residues, and output paths.
• Empty-pocket example: selected_residue_count: 0, top_pocket: null, aggregate_pocket: null, cluster_count: 0.

You can also keep model assets in an explicit directory:

protcross predict examples/6fhu.pdb \
  --assets-dir /path/to/protcross-assets \
  --out-dir examples/protcross-results

The asset directory should contain protcross-assets.json plus protcross-0.1.2-binding-moad-final.ckpt, esmc_600m_2024_12_v0.pth, and pca_esmc_128_binding_moad_0.1.2.pkl. Alternatively, set PROTCROSS_CHECKPOINT, PROTCROSS_ESM_WEIGHTS, and PROTCROSS_PCA.

Python API:

from protcross.inference import ProtCrossPredictor, predict_pdb

# Missing default runtime assets are installed automatically unless
# auto_setup_assets=False is passed.
result = predict_pdb(
    "examples/6fhu.pdb",
    output_pdb="examples/6fhu.protcross.pdb",
    scores_tsv="examples/6fhu.protcross.scores.tsv",
    pocket_json="examples/6fhu.protcross.pockets.json",
    summary_json="examples/6fhu.protcross.summary.json",
)
print(result.format_summary())

predictor = ProtCrossPredictor.from_default_assets(embedding_cache_dir=".protcross-feature-cache")
result = predictor.predict("examples/6fhu.pdb", pocket_json="examples/6fhu.protcross.pockets.json")

result = predict_pdb(
    "examples/6fhu.pdb",
    ckpt_path="checkpoints/protcross-0.1.2-binding-moad-final.ckpt",
    esm_weights="/absolute/path/to/esmc_600m_2024_12_v0.pth",
    pca_path="data/pca_esmc_128_binding_moad_0.1.2.pkl",
    output_pdb="examples/6fhu.protcross.pdb",
)
print(result.format_summary())

3.1.2 Batch Prediction (Multiple Structures)

protcross predict predicts one structure each run. For a few files, iterate in a shell loop and optionally reuse a feature cache across invocations:

protcross setup-assets
mkdir -p batch_outputs
for pdb in /path/to/pdb_dir/*.pdb; do
  base="$(basename "${pdb}" .pdb)"
  protcross predict "${pdb}" \
    --out-dir batch_outputs \
    --embedding-cache-dir .protcross-feature-cache \
    --threshold 0.5
done

For larger batches, prefer the Python API so ESM, PCA, and the segmentation model are loaded once:

from pathlib import Path
from protcross.inference import ProtCrossPredictor

predictor = ProtCrossPredictor.from_default_assets(
    device="auto",
    embedding_cache_dir=".protcross-feature-cache",
)
results = predictor.predict_many(
    sorted(Path("/path/to/pdb_dir").glob("*.pdb")),
    threshold=0.5,
    allow_truncation=False,
)

3.2 Retrain Release Workflow

3.2.1 Data Preparation

Expected layout:

data/
|--- raw_pdb/          # input PDB/CIF structures (source)
|--- raw_af2/          # input AF2 PDB structures (target)
|--- processed_pdb/    # generated .pt files for source
`--- processed_af2/    # generated .pt files for target

Optional AF2 retrieval helper:

protcross download-af2 \
  --raw-pdb-dir data/raw_pdb \
  --output-dir data/raw_af2 \
  --mapping-file artifacts/pdb_uniprot_mapping.json

3.2.2 Preprocess Source (PDB) with PCA Fit

protcross preprocess \
  --data-dir data/raw_pdb \
  --output-dir data/processed_pdb \
  --fit-pca \
  --esm-weights ~/.cache/protcross/assets/v0.1.2/esmc_600m_2024_12_v0.pth \
  --pca artifacts/protcross-pca-128.pkl \
  --pca-dim 128

3.2.3 Preprocess Target (AF2) with Shared PCA

protcross preprocess \
  --data-dir data/raw_af2 \
  --output-dir data/processed_af2 \
  --esm-weights ~/.cache/protcross/assets/v0.1.2/esmc_600m_2024_12_v0.pth \
  --pca artifacts/protcross-pca-128.pkl \
  --is-af2

3.2.4 Map Labels from PDB to AF2

protcross map-labels \
  --processed-pdb-dir data/processed_pdb \
  --processed-af2-dir data/processed_af2 \
  --raw-pdb-dir data/raw_pdb \
  --raw-af2-dir data/raw_af2 \
  --mapping-file artifacts/pdb_uniprot_mapping.json

3.2.5 Train

Default training:

protcross train

Common Hydra overrides:

# Disable domain adaptation
protcross train model.use_da=False

# Disable ESM features
protcross train model.use_esm=False

# Short debugging run
protcross train trainer.max_epochs=5

# Custom data directories
protcross train \
  data.data_dir_pdb=/abs/path/to/processed_pdb \
  data.data_dir_af2=/abs/path/to/processed_af2

Evaluation helpers, multi-seed benchmark scripts, and paper-reproduction notes are documented in reproduction/legacy/README.md.

---

4. Configuration Guide (Hydra)

Main configuration files:

• configs/train.yaml: global defaults and run-level settings.
• configs/data/protein_seg.yaml: data module paths and loading parameters.
• configs/model/da_module.yaml: architecture and adaptation hyperparameters.
• configs/trainer/default.yaml: PyTorch Lightning trainer options.

Hydra override syntax:

protcross train key1=value1 key2=value2

Tip: keep all experiment commands in shell scripts to ensure reproducibility.

---

5. Repository Layout

ProtCross/
|--- configs/
|   |--- data/protein_seg.yaml
|   |--- model/da_module.yaml
|   |--- trainer/default.yaml
|   `--- train.yaml
|--- data/
|   |--- raw_pdb/
|   |--- raw_af2/
|   |--- processed_pdb/
|   `--- processed_af2/
|--- reproduction/
|   `--- legacy/                # historical reproduction scripts and notes
|--- src/protcross/
|   |--- cli/                   # installed command entry points
|   |--- data/
|   |--- experiments/           # reproduction benchmark workflows
|   |--- evaluation/
|   |--- inference/             # lightweight predictor API
|   `--- models/
`--- environment.yml

---

6. Troubleshooting

• FileNotFoundError for ESM-C weights
  • Run protcross setup-assets, or ensure --esm-weights points to an existing local .pth checkpoint file.
• protcross setup-assets cannot find GitHub release assets
  • Attach protcross-0.1.2-binding-moad-final.ckpt and pca_esmc_128_binding_moad_0.1.2.pkl to the v0.1.2 GitHub release, or pass --checkpoint-url and --pca-url.
• Torch Geometric install issues
  • Verify that your torch version and wheel index URL match the environment (torch 2.3.0 + cu121).
• OOM during preprocessing/training
  • Reduce batch size, use shorter runs, or switch to a smaller subset first.

---

7. Changelog

0.1.3

Preparation release for user-facing prediction outputs and package cleanup.

• Makes protcross predict write a default result package with annotated structure, extended scores TSV, pocket JSON, and summary JSON.
• Reports clustered pocket centers, residue lists, probabilities, residue counts, truncation metadata, asset version, and output files for docking/MD downstream workflows.
• Renames the canonical source package to protcross while keeping a deprecated import alias for 0.1.x compatibility.
• Moves historical paper-reproduction scripts and notes under reproduction/legacy/.
• Keeps the default runtime asset bundle fixed at the stable 0.1.2 checkpoint/PCA unless the user explicitly selects another asset version.

0.1.2

Release checkpoint update for external prediction and benchmark use.

• Adds the 0.1.2 Binding MOAD-trained release checkpoint and matching PCA reducer as the default runtime assets. This release checkpoint was trained on Binding MOAD-derived labels from 41,409 PDB source structures spanning 20,387 unique ligand IDs, with 8,953 matched AF2 target structures.
• Filters common crystallization additives, salts, ions, and caps from default ligand-adjacent residue labeling.

Earlier release notes and archived command references are maintained in reproduction/legacy/README.md.

---

8. License

This project is licensed under the MIT License. See LICENSE for details.