Arpeggia

Arpeggia provides protein contact analysis, surface measurements, structural comparison, sequence alignment and antibody numbering through Rust, Python and a CLI. Contact analysis is based on Arpeggio.

Features

¹ The CLI writes the pair table as part of clustering; Python can calculate it independently.

See antibody numbering, sequence alignment, structure comparison, and scientific conventions for usage and assumptions.

Structure analyses accept PDB and mmCIF files. Tabular Python results are Polars DataFrames; CLI tables support CSV, Parquet and NDJSON. Sequence commands accept unaligned amino-acid strings.

Installation

pip install arpeggia

Published wheels support CPython 3.10–3.14 on x86-64 Linux and Windows, and Arm64 Linux and macOS. Download the CLI from GitHub Releases, or see BUILD.md to build either interface from source.

See the release notes for new features and API changes.

Usage

See Python and CLI examples for chain-group syntax, surface options, table output and reusable RMSD calculations.

Python API

import arpeggia

contacts = arpeggia.contacts("structure.pdb", groups="A/B")
contacts.write_parquet("contacts.parquet")
residue_sasa = arpeggia.sasa("structure.pdb", level="residue")
print(residue_sasa.sort("sasa").head(10))
relative_sasa = arpeggia.relative_sasa("structure.pdb")
sap = arpeggia.sap_score("structure.pdb", level="residue")
print(sap.sort("sap_score", descending=True).head(10))
total, polar, hydrophobic, unknown = arpeggia.dsasa_components(
    "structure.pdb", groups="A/B"
)
sc_score = arpeggia.sc("antibody_antigen.pdb", groups="H,L/A")
print(f"Shape Complementarity: {sc_score:.3f}")

print(arpeggia.align_seqs("ACDEFGHIK", "ACDEYGHIK"))
result = arpeggia.rmsd(
    "reference.cif", "query.cif",
    superpose_residues="A", rmsd_residues="B,C", atoms="ca",
)
print(result.rmsd, result.core_rmsd)

Use help(arpeggia.contacts) for arguments and defaults. The contact-table examples cover hydrogen-bond counts and interface residues; the feature guides above cover alignment and numbering.

Command-Line Interface

arpeggia contacts -i structure.pdb -o results/ -g "A/B" -t parquet
arpeggia sasa -i structure.pdb -o results/ --level residue --chains A,B
arpeggia dsasa -i structure.pdb -g "A/B"
arpeggia seq structure.pdb
arpeggia align-seqs ACDEFGHIK ACDEYGHIK
arpeggia rmsd reference.cif query.cif --atoms backbone
arpeggia cluster-structs -i structures/ -o results/ \
  --num-clusters 5 --pairwise-rmsd --num-threads 8

Run arpeggia --help to list commands, or arpeggia <command> --help for options.

Chain Groups Specification

The groups parameter allows you to specify which chains interact with each other:

• "/" - All chains interact with all chains (including self) for contacts
• "A,B/C,D" - Chains A,B interact with chains C,D
• "A/" - Chain A interacts with all other chains
• "A,B/" - Chains A,B interact with all remaining chains

dSASA and SC require two disjoint, non-empty groups; "/" is therefore invalid for those calculations.

Development

BUILD.md contains locked build, test and native-extension rebuild instructions.

License

GNU General Public License v3.0 - see LICENSE for details.

Bundled germline data are © 1995–2026 IMGT®, the international ImMunoGeneTics information system®, Montpellier, France, licensed separately under CC BY 4.0. Arpeggia filters GENE-DB release 202636-7 and reformats llama protein displays; see the source credits, notices and preparation record.

Credit

• Arpeggio: Original Python library for protein-protein interaction analysis.
• pdbtbx: PDB and mmCIF parsing.
• RustSASA: Library for calculating solvent accessible surface area.
• sc-rs: Library for calculating the Shape Complementarity by Lawrence & Colman (1993).
• Rosetta: SAP reference definition and SASA polarity conventions.