Final fit-free calculations =========================== The final scoring boundary permits fixed empirical statistical-potential tables. Their observed contact counts, pseudocounts, weighting and reference convention remain estimated dependencies and must accompany the table identity. No Gaussian, GLM, fitted Potts or fitted transition readout belongs to the final specification. Q/T/S also use estimated reference moments or correlation weights and remain historical. These APIs and their measured results are preserved. Searched annotation references -------------------------------- ARDA 2.36.2 or later validates the source reference and actual MMseqs database payloads by content, preserving legacy indexes as evidence. Source-root discovery recognizes ARDA itself rather than an unrelated enclosing project. ``scoring``, ``features``, ``recognize`` and ``export`` retain ``searched_indexes`` in provenance sidecars: resolved database prefixes and SHA256 identities of the searched sequence, header and index files, including split payloads. These are captured around annotation, not inferred from package versions after scoring. Mid-search changes and mixed generations across input chunks fail explicitly. An empty identity record does not certify annotation provenance. Contact sums and references --------------------------- For a set of observed residue contacts C and a selected pair-potential table V, the contact sum is Phi = sum over (i,j) in C of V(a_i,a_j). The identities a_i and a_j are the observed amino acids. The virtual reference difference is DeltaPhi = Phi(observed) - Phi(reference), with C unchanged. Lower values follow the energy direction. These are dimensionless statistical-potential sums, not a calibrated binding free energy. The manuscript reference uses structural alanine truncation: preserve backbone and C-beta coordinates, remove the remaining side-chain atoms, construct C-beta for glycine using the existing substitution geometry, and rebuild contacts. This differs from the historical virtual reference and can change rankings. ``scoring --delta`` references peptide identities. ``dPhi_peptide_sum`` is the unweighted TCR:peptide plus peptide:MHC reference sum. Historical ``Phi_total`` and ``dPhi_total`` use estimated native-reference scale weights and are excluded from final scoring; they must not substitute for the unweighted sum. ``export`` references receptor identities, or exports existing exact decompositions. No fitted replacement is introduced: .. code-block:: console tcren scoring -s structures/ --delta --reference-mode structural --no-superimpose --tcr-peptide-potential tcren2 -o peptide.csv tcren export -s structures/ --potential tcren2 --quantity receptor-reference --reference-mode structural -o receptor.tsv tcren export -s structures/ --potential tcren2 --quantity position -o positions.tsv tcren export -s structures/ --potential tcren2 --quantity residue -o residues.tsv tcren export -s structures/ --potential tcren2 --quantity contacts -o contacts.tsv tcren export -s structures/ --potential tcren2 --quantity placement -o placement.tsv Use ``--reference-mode structural`` explicitly for the manuscript. The default ``virtual`` mode remains available for exact historical reproduction. Output rows and provenance identify the mode; do not mix modes in a comparison. Structural peptide references require alanine and use the selected cutoff and contact weighting. The peptide reference contact map is built once per structure and reused across both peptide interfaces. Potential sums then operate on the contact tables; SASA and coordinate-based descriptors still require their structural calculations. When running multiple outer workers, set ``POLARS_MAX_THREADS=1`` and the BLAS thread limit before starting Python to avoid nested thread pools. The receptor export substitutes alanine in all, CDR, CDR1/2 or CDR3 receptor positions, separately for TCR:peptide and TCR:MHC and their explicit sum. Position exports use ``position_profile``; residue exports use ``residue_importance``. Leave-one-out ``explain`` is not an equivalent decomposition. Each contact contributes to both residue endpoints, so the sum of endpoint contributions is twice the contact sum. Distances and placement are in angstroms. Identity and accounting ----------------------- Exports retain full source stems, physical chain IDs, sequential residue indices, author residue numbers and insertion codes. CDR regions exclude conserved junction anchors. One batched annotation is used per species plus one MHC annotation batch. Files, directories, glob/manifests and supported structure archives are accepted. Every input receives an accounting row, including parsing, annotation and export errors. Empty/all-failed runs exit nonzero and keep diagnostics. Mixed runs retain all failures for explicit acceptance by their consumer; a benchmark must verify its full key set rather than silently discard failed rows. Sidecars retain residue assignments, chain annotations, installed versions, reference hashes, the exact potential tables and their hashes. A custom potential has no inferred derivation or unit calibration. Source paths and annotations may be private; review them before sharing generated outputs. Historical assessment availability ---------------------------------- ``score_table`` exposes a finite-value ``_available`` flag per readout, ``assessment_available`` for binder-score availability, and a JSON list of ``missing_descriptors``. Absent columns are marginalized; missing values in present required columns remain missing. No imputation or refit is performed. ``inspect-models`` omits fitted assessment unless ``--historical-assessment`` is explicitly requested. Documentation builds require the ``docs`` extra and the external Pandoc executable for nbsphinx. IPython supplies the notebook syntax lexer. Molecular publication consumers ------------------------------- Scene producers read exact ``position``, ``residue``, ``contacts``, ``placement`` and ``pmhc`` exports. They do not substitute leave-one-out ``explain`` for a position decomposition or calculate new contact scores during drawing. Physical chain, author residue number and insertion code identify selections; region membership comes from annotation. Preserve raw-coordinate, searched-reference, potential, camera and scene-geometry identities and check the displayed atom colours against their authoritative rows. Inspect the final PNGs and composed PDF pages. Keep class II, epitopes and template strata separate. Historical images and manifests remain archived when labels or pixels change. Structural class-II registers ----------------------------- Sequence-only ``anchor_indices`` remains a prediction for historical callers. For an experimentally verified core reference, export structural correspondence in the same annotation batch:: tcren export -s native.txt --quantity contacts --potential tcren2 --cutoff 8 -t 2 \ --register-reference-id 1fyt --register-p1 3 -o contacts.tsv The reference must be included in ``native.txt``. ``contacts.tsv.registers.tsv`` contains every forward/reverse nine-residue core, its C-alpha RMSD after aligning both MHC groove chains, physical P1/P4/P6/P9 identities, groove RMSD, the exact rigid transform and the gap between the two lowest core RMSDs (all distances in angstroms). No peptide atoms enter the rigid fit and no sequence motif, trained coefficient or acceptance threshold enters core ranking. A minimum is a correspondence candidate, not a certificate of structural correctness; inspect residuals and the source structure. Incomplete cores fail explicitly, with errors retained in input accounting. Register exports retain known HETATM amino acids as ``X`` with their chemical names and geometry; unsupported modified peptides are not energy-scored. Historical parsing defaults are unchanged. ``--peptide-selection verified.tsv`` supplies source-verified antigen intervals: ``pdb.id``, ``chain.id``, ``first_pdb``, ``last_pdb`` (inclusive author numbering). This handles engineered fused antigens in the presence of auxiliary peptides. Original residue indices and coordinates remain unchanged; insertion-code boundaries and overlap with annotated receptor regions are rejected. The selection and register exports are hashed in provenance. Ordinary exports keep their previous behavior. The Python APIs are ``tcren.refine.structural_register.structural_register`` and ``select_peptide``; they require already annotated structures and perform no search. Local topology and topography of contacts ----------------------------------------- ``export --quantity contact-context --potential tcren2`` retains every original TCR:peptide residue-pair contact, author identities and region markup. It adds endpoint degrees and the number of bipartite four-cycles through each edge, computed as ``(B B^T B)[u,v] - degree(u) - degree(v) + 1`` for an existing edge. Here B is the binary incidence matrix of all TCR:peptide contacts, u is a TCR residue and v a peptide residue. Framework contacts remain identifiable; these are graph cycles, not geometric loops or spatial Betti numbers. The closest peptide atom is projected onto the existing receptor-free pMHC surface grid. Rows retain its height, the projected cell's peptide/MHC ownership, surface height and KD hydropathy, and height minus the existing 90th-percentile helix rim (angstroms). Cell ownership identifies peptide versus MHC, not a particular peptide residue. Missing rims/out-of-window cells remain undefined. ``pair_energy`` is the supplied potential's exact per-pair contribution; missing matrix entries remain NaN and are omitted only when reproducing the established sum. Neither a zero retained sum nor a missing value is a binding probability. This export supports inspection of graph-supported or protrusion-associated contacts without learning thresholds from labels. It does not apply a filter, replace the original score or establish that contacts outside a mask are false. Keep assay targets, classes and template strata separate during evaluation. ``contact-summary -i contacts.tsv -o contacts.summary.tsv`` reduces that exact stamped export and its accounting sidecar, with no parsing, annotation or search. Canonical amino-acid-pair count matrices multiply the fixed potential vector: identical contact compositions remain tied regardless of input row order. It exports counts and sums for all contacts, edges participating in four-cycles, peptide-owned projected cells above the established ridge, and their intersection. These are declared structural selections, not calibrated nonbinding filters. Accounting retains empty models; undefined topography remains NaN for affected surface selections. Missing potential entries are counted and omitted as in the original sum. ``--accounting`` supplies a relocated ledger explicitly. Compare new sums with exact recorded baselines rather than perturbing old score ties. Exact atom observations ----------------------- .. code-block:: console tcren export -s native.txt --quantity contact-atoms --interface all -t 1 -o atoms.parquet This opt-in quantity requires no potential. It selects CDR1/2/3 contacts with peptide or annotated MHC helices and peptide contacts with those helices, counting each physical heavy-atom pair once. Groove-floor and B2M contacts are outside this observation scope. Missing helix annotation fails explicitly. Choose an existing individual interface name instead of ``all`` to restrict the export. The ``.parquet`` suffix selects compressed columnar output for this quantity; other suffixes retain TSV output. Its summary/accounting sidecars remain TSV. The per-residue conformer policy chooses the lexicographically first nonblank alternate label plus blank atoms, preferring the selected label on atom-name ties. This deterministic convention is not occupancy selection or proof of correlated conformer compatibility between residues. Legacy contacts/scoring are unchanged. Glycine contributes observed backbone atoms only; no C-beta is synthesized. Physical sides retain atom/source indices, author residue/insertion, alternate labels, coordinates, chain roles and regions. ``chem.a``/``chem.b`` sort whole amino-acid/atom-name tuples, independently of physical side order. Observed N/CA/CB geometry yields trRosetta omega, endpoint-specific theta/phi in radians and C-beta distance in angstroms. Missing atoms and degenerate vectors yield null, not a favourable geometry value. Existing v2 chemical flags remain distance/type heuristics; stacking uses the existing ring geometry. Hydrogen-bond angles, line-of-sight, plausibility probabilities and penalties are not calculated here. The summary sidecar separates atom-pair and residue-pair frequencies by MHC class, interface and receptor region. Residue rows use the closest retained atom distance and the union of type flags across all atom pairs. Chemical types overlap; their counts need not sum to the total. Summary groups contain observed contacts only; the accounting sidecar separately retains successful zero-contact structures. No count is labelled an independent sample size or a probability of physical validity. Provenance retains the summary hash, conformer policy, annotation and searched-reference identities. See :mod:`tcren.contacts.observations`.