Pandora defines several terms of its own on top of raw mmCIF vocabulary. Each entry below links to where the concept actually lives in code, and to a usage guide or recipe that puts it to work — follow those if you want to see the term in action rather than just read about it.
For the underlying pydantic models, see Schemas; for every callable, see Functions.
Pandora's central typed model of one parsed mmCIF entry: atoms, entities, assemblies, plus the raw passthrough for everything else. Never mutated in place — every function returns a new Structure via .model_copy(update=...). See Ingestion & parsing.
Entry
One PDB/PDBe deposition, identified by its 4-character entry_id (e.g. 104M). One entry's mmCIF file maps to one Structure.
Entity
An mmCIF entity — one distinct polymer or non-polymer chemical component in the structure (e.g. "the protein", "a bound heme", "water") — as opposed to a chain, which is one physical copy of an entity in the asymmetric unit.
Chain
One physical copy of an entity in the asymmetric unit, identified by its label_asym_id. Two chains can share the same entity (e.g. a homodimer's two copies of the same protein) — canonicalisation can remap chain IDs; see identifier_rules in Policies.
Raw category / raw passthrough
Any mmCIF category mmcif_to_structure() doesn't promote to a typed field, kept verbatim in Structure.raw, readable via raw_rows()/first_row(). Values here are the literal CIF token as gemmi returns it — quoted strings keep their '...' delimiters.
Policy-driven normalization of a parsed Structure: remapping chain IDs, resolving altlocs, handling missing atoms/residues, filtering ligands, and validating the result. The single entry point is canonicalise_structure(); see Canonicalisation.
Canonicalisation policy
The typed, versioned policy object (canonicalisationPolicy) that controls every canonicalisation rule group (identifier_rules, missing_data_rules, altloc_rules, assembly_rules, entity_rules, ligand_rules, validation_rules, provenance_rules). Fully documented field-by-field in Policies.
CanonicalMappings
The record of every id/coordinate change canonicalisation made (chain remaps, dropped atoms, altloc selections, ...), returned alongside the transformed Structure so the change is auditable rather than silent.
Diagnostic / DiagnosticBundle
A structured warning or error (Diagnostic) raised during canonicalisation or validation, collected into a DiagnosticBundle. Only aggregate warning/error counts surface in provenance today, gated behind provenance_rules.emit_canonicalisation_report.
Validation
The final canonicalisation step: computing a "success"/"warning"/"failed" status from the diagnostics collected during the run, per validation_rules.strictness. A "failed" status raises ValueError when fail_on_unresolved_issues=True.
A derived, per-entry or pairwise value computed from an already-canonicalisedStructure — e.g. atom/chain counts, chain-chain interfaces, ligand contacts, or pairwise sequence identity. Produced by the annotate_*() functions in pandora.annotations and recorded as an AnnotationLayer.
Policy-driven filtering of a dataset — dropping structures that fail quality/size/resolution rules — via curate_structure(). See Curate one structure.
Deduplication
Removing structures that share the same entry_id from a batch, via deduplicate_structures(). Distinct from clustering, which groups by similarity rather than identical id.
Similarity hit / edge
A hit is one row of an MMseqs2 or Foldseek all-vs-all search, kept on disk in the hit file a SimilaritySearch points to (compute_sequence_similarity() / compute_structure_similarity()). An edge is a pair of items with at least one hit that passes a HitFilter; edges are what clustering connects. See Filtering hits.
Cluster / clustering
Grouping items (entries, chains, ...) that similarity edges connect into connected components, so that near-duplicates land in the same dataset split. Done by cluster_similar_items(); see Clustering.
Partition / split
Assigning clustered items to train/val/test sets such that no cluster straddles a split boundary ("leakage-safe"), via partition_dataset(). See Leakage-safe partitioning and the worked example in the PPI recipe.
The per-structure provenance report (ProvenanceBundle) assembled by build_provenance_bundle(), aggregating whatever ingestion/canonicalisation/metadata/annotation provenance the caller already has for one structure. The building block a dataset manifest is made of.
Dataset manifest
The dataset-level provenance report (DatasetManifest) produced by build_dataset_manifest(): the curation and canonicalisation policies (stored by value), exclusion records, dedup/clustering/partition provenance, the split assignment, and every retained structure's provenance bundle, all in one JSON-serializable object. See Assemble a dataset manifest.
Pandora's convention for making every stage's rules explicit and inspectable: a typed, versioned pydantic settings object (canonicalisationPolicy, DatasetCurationPolicy, ...) passed into the stage's function rather than hard-coded. Provenance records reference the policy that was applied via the compact AppliedPolicyRef (id, name, version).
Recipe
A narrated, end-to-end walkthrough doc under docs/recipes/ (e.g. the PPI interface dataset recipe) that combines several components into one realistic workflow, as opposed to the single-stage guides under docs/usage/.