Generated-model inspection ========================== ``tcren inspect-models`` connects native AF3/TCRmodel2 confidence outputs to the same annotation, geometry, descriptor and residue-contact APIs used on deposited structures. It serves the ipTM/pLDDT diagnostics block. No separate analysis package is required. Prepare a TSV manifest with unique ``complex.id`` and ``structure`` columns. Optional columns are ``generator`` (``af3``, ``tcrmodel2``, ``boltz2``, ``tfold-tcr``, ``af2-multimer``, ``protenix`` or ``rf3``), ``confidence``, ``detail_confidence``, ``producer_structure`` and ``model_key``. Relative paths resolve against the manifest. For AF3, point ``confidence`` at the summary-confidence JSON and ``detail_confidence`` at the full-confidence JSON. For TCRmodel2, point ``confidence`` at ``statistics.json`` and give the literal ``model_key`` (for example ``ranked_0``). Native references omit confidence. Use a unique ID across jobs: two files named ``ranked_0.pdb`` are two different models. .. code-block:: bash tcren inspect-models manifest.tsv analysis/ --threads 2 The output directory contains: * ``models.tsv``: manifest identity, literal generator scalars, interface contact counts, descriptor availability and all four default descriptor families, including docking angles. * ``residues.tsv``: TCR CDR/framework, peptide and MHC residue markup from one batched annotation pass. Residue indexes are zero based within each coordinate chain. * ``chains.tsv``: chain roles, sequences, original author residue IDs and the library's allele/germline annotation. ``cdr3`` is the arda CDR3 region, not anchor-inclusive junction. Allele/germline values are sequence-reference annotations, not experimentally established genotypes; a truncated MHC groove does not necessarily distinguish full-resolution alleles. * ``contacts.tsv``: directed, annotated residue pairs, closest heavy-atom distances, heavy-atom pair counts, and available global/chain-pair/token-pair confidence. * ``assessment.tsv``: historical fitted readouts only with ``--historical-assessment``; disabled by default. Existing frozen tcren readouts on complete alphabeta TCR:pMHC structures; ``confidence_residual`` and ``binder_iptm`` are added where ipTM exists. The frozen model's calibration/hold-out provenance remains the one shipped by tcren; these readouts are not a new validation of transfer to AF3 or of binder discrimination. ``assessment_status`` and ``missing_descriptors`` distinguish unavailable complete-case readouts from numerical values without imputing missing interface evidence. Each emitted readout has a corresponding ``*_available`` boolean, including ``confidence_residual_available`` and ``binder_iptm_available`` where ipTM exists. Without the historical opt-in, the assessment table is empty and complete models report ``assessment_status=historical_not_requested``. * ``angles.tsv``: existing ``docking_angles`` and ``tcr_placement`` API values, including signed crossing and incident angles and CDR height/shift/offset. These readouts retain their existing definitions; this export does not add a new descriptor to the catalogue. Every table has a provenance sidecar. Parsing, annotation, confidence mismatch or featurisation failures raise: an empty or failed batch must not look successful. TCR-only and pMHC-only inputs receive annotation and contacts, with ``descriptor_status=incomplete_construct``; ternary descriptors and assessment stay unavailable. No missing chain is invented. Interpret the evidence separately --------------------------------- Global ipTM is repeated per model/contact for joining; it is not a contact probability. AF3 chain-pair ipTM and minimum PAE retain chain order and direction. Full AF3 confidence JSON supplies separate token-pair PAE and contact probability. Protein token identities are matched by coordinate chain ID and author residue number, never by a guessed sequential index. Multiple tokens per residue (ligands/modifications) are outside this inspection surface. AF3's native token contact probability is the distogram's <8 Å event; it is not the probability of tcren's default inclusive 5 Å minimum-heavy-atom contact. Keep the native probability, computed contact definition and distance cutoff separate. The current TCRmodel2 statistics output supplies scalar confidence only; deleted upstream PAE arrays are not reconstructed. Numeric strings are accepted while original metric names are retained. A fused pMHC may report pTM and interface pLDDT without ipTM: absence stays null. Do not compare these as interchangeable confidence estimates across construct types. Contacts are symmetrised: each residue pair appears in both directions. An interface selection in ``ContactMap`` chooses one biological direction. Empty interfaces remain explicit in ``models.tsv`` even when there are no rows to write in the contact table. The contact export defaults to 5 Å; ``--cutoff`` changes that export and its counts. Descriptor definitions retain their catalogue thresholds (including the standard 5 Å contact definition), regardless of the export cutoff. An angle describes rotation; CDR placement and contact counts expose displacement that an angle alone cannot detect. Library use ----------- .. code-block:: python import polars as pl from tcren.prediction import inspect_predictions tables = inspect_predictions(pl.read_csv("manifest.tsv", separator="\t"), threads=1) models, contacts = tables["models"], tables["contacts"] # Filter contacts by complex.id, chain.type.from/to, region.type.from/to or residue.index. # assessment.tsv joins to models on complex.id; contacts retain the same model key. ``recognition_table(..., annotate=False)`` reuses already annotated ``Structure`` objects for callers that also need contacts/markup. ``tcren.validation.structures`` provides sequence-verified role mapping, coordinate diagnostics and chain-pair contact coverage. These proximity diagnostics are not MolProbity clashscores. ``tcren.validation.md`` reads recorded GROMACS XVG datasets and plots short-run readouts without running MD again. Whole-system potential energies from different solvent boxes are not binding energies; 20 ps execution checks do not establish equilibration. ``compatible_reference_models(models, reference_roles, construct_roles)`` selects queries covering every explicit reference role, including complete-complex queries for a pMHC-only reference. The caller supplies the construct-to-role mapping and uses ``map_sequence_roles`` to verify actual coordinate sequence spans. This selection helper does not run a campaign comparison. In a partial-reference fit, ``all`` must mean all matched components; unmatched receptor coordinates must not be scored against a pMHC-only reference (issue #22). Multiple descriptor workers are supported from notebooks, stdin, the CLI and guarded scripts. Interactive calls send already annotated structures through private temporary transport to an importable entrypoint, which runs the same bounded spawn pool. Annotation remains one complete query batch per reference in the caller; workers do not search. No fork, notebook replay or serial fallback is used. Temporary transport is deleted on success or failure, and worker errors propagate to the caller. Ordinary scripts still need an ``if __name__ == "__main__":`` guard. Import ``tcren`` before initializing Polars; an existing multithreaded Polars pool remains unsupported. Building this documentation locally ----------------------------------- Install the ``docs`` extra and Pandoc (``brew install pandoc`` on macOS). The notebook pages require this external document converter, as does the existing docs CI. Then run ``.venv/bin/sphinx-build -W -b html docs docs/_build/html``. Retaining TCRmodel2 residue confidence -------------------------------------- TCRmodel2 normally removes its raw prediction results during finalisation. For a running local producer, ``tcren.validation.tcrmodel2.export_generated_confidence`` exports its PAE and per-residue pLDDT before that cleanup, retaining checksums of the original result and unrelaxed PDB. This reads trusted locally generated pickles, not arbitrary interchange files. Exported JSON records exact producer-chain sequences and sequential residue positions. Point ``detail_confidence`` at the retained JSON. The inspection API verifies its ranking confidence against the requested rank and remaps tokens by unique exact sequence spans when postprocessing renames chains and applies AHO author numbering. Contacts then carry ``token_pair_pae`` and ``residue_plddt.from/to``. No AF2 chain-pair ipTM or residue-contact probability is invented. ``ranked_detail_file`` selects retained results by unique exact producer ranking confidence, refusing ties instead of guessing. Earlier completed runs whose raw results were removed remain scalar-only. MD and controlled AF3 follow-up ------------------------------- Validation helpers audit literal AF3 chains, MSA query sequences and template index bounds; paired-MSA removal preserves other search outputs as an explicit inference-only experiment. ``tcren.validation.md.component_relative_rmsd`` fits a selected component and measures its partner in that frame, using corresponding backbone coordinates in Å after PBC correction. Atom selections must be one-dimensional integer indices; fractional, boolean and out-of-range indices are rejected before coordinate selection. ``minimum_potential_frame`` requires exact saved-frame/energy timestamps in ps and kJ/mol. It selects whole-system potential, never binding energy. ``close_atom_pairs`` exports atom identities and source ``altloc.from/to`` labels for nonlocal heavy-atom proximity pairs, with ``alternate_location_involved`` and possible-disulfide flags. Bond classification is explicitly unknown; adjacent-residue exclusions are a sequence heuristic, not a bond graph. Different altloc letters across residues do not establish conformer incompatibility. All parsed conformers still contribute to contact geometry; writers retain their existing one-conformer selection and preserve the selected label. This is not a MolProbity clashscore. See issues #25 and #26. Missing original MD settings must remain explicit. The native inspection also exports ``interfaces.tsv``: directional AF3 chain-pair confidence with observed directed-contact counts, including zero-contact pairs. AF2 pair matrices remain unavailable; global/named confidence is retained in models. The library helper ``confidence_chain_pairs`` exposes this table without treating confidence as contact probability. Modern predictor controls ------------------------- ``tcren.validation.prediction_inputs.af3_to_boltz_input`` exports literal protein sequences and retained unpaired MSAs to a Boltz YAML/CSV input. All CSV pairing keys are -1; lowercase insertions are preserved. No templates, paired MSAs, steering or affinity setting is silently transferred. The output directory must be new, and the provenance records source and MSA checksums. This is an inference control, not a fresh database search. Native confidence ingestion for additional providers is tracked in issue #28; unsupported fields must remain unavailable. ``map_sequence_roles(..., allow_extended=True)`` explicitly permits an exact requested domain inside a longer output chain. It returns coordinates only for that span and records both reference/output offsets. The default remains strict. ``geometry_and_contacts`` records the actual ``cutoff_A`` and generic pair counts; legacy ``*_le4_5A`` aliases appear only for a 4.5 Å calculation (issue #27). ``inspect_md_trajectory`` streams a GROMACS multi-model PDB after explicit PBC correction. It requires TITLE timestamps, exact polymer sequences and matching backbone atom identities. Supply named components as chain-ID lists and a two-column potential-energy XVG. It returns partner-relative RMSD rows in Å/ps, minimum saved-frame metadata and that frame's PDB text. The reference structure must be specified explicitly; selection remains whole-system potential energy. Native Boltz-2 confidence ------------------------- Use ``generator=boltz2`` with the writer's ``confidence_MODEL.json`` and an explicit ``producer_structure`` pointing to its processed structure NPZ. ``detail_confidence`` points to ``pae_MODEL.npz``; the corresponding ``plddt_MODEL.npz`` must exist beside it. Only standard all-protein inputs with all chains valid are supported. The adapter validates chain order, unique IDs, residue spans, full coordinate sequences and matrix dimensions. It preserves directional chain-pair ipTM and the original ``confidence_score``; the latter is never renamed ipTM. Boltz's 0–1 token pLDDT is explicitly converted to the 0–100 pLDDT units used in residue-contact exports. No contact probability or AF3-specific minimum-PAE matrix is invented. All evidence files are checksummed. ``compare_same_frame_energy_forces`` compares one identical-coordinate rerun against a numerical reference, requiring equal energy/force timestamps and three force columns per atom. It reports total-potential difference (kJ/mol), vector force RMS/relative error and percentile/max errors (kJ/mol/nm). The caller must verify coordinate/topology identity and System-group atom order. These numerical readouts do not establish affinity or structural quality. For ``generator=tfold-tcr``, retain native scalar scores, ordered token/chain sequences and per-residue pLDDT from the producer in one JSON bundle. The reader requires explicit sequence indexing and ``probability_0_1`` pLDDT units, verifies full coordinate sequences, and exports pLDDT in 0–100 units. Global ipTM remains global; unsupported chain-pair confidence, PAE and contact probability remain unavailable. Producer execution and generation of the retained bundle are separate from library inspection. ``generator=af2-multimer`` accepts the analogous retained native AF2 bundle, requiring ``score_0_100`` pLDDT units and preserving a supplied token PAE matrix. No chain-pair ipTM is imputed. The generic Multimer baseline records the official source and retained-MSA/no-template inputs separately from TCRmodel2. MD preprocessing must make molecules whole, establish a compact first-frame complex image, then unwrap continuously using that coherent first-frame reference. A TPR containing wrapped starting coordinates can anchor ``nojump`` to broken chains. The reader rejects consecutive Cα gaps above 8 Å in this complete-chain canonical MD scope (issue #29). If the first frame contains CRYST1, ``validate_initial_complex_image`` checks that every pair of chain Cα centroids is in a nearest periodic image, using the full triclinic cell. A closer lattice image raises an error before RMSD reporting. The returned ``initial_image_status`` is ``nearest_image_chain_centroids`` on success or ``unavailable_no_unit_cell`` when CRYST1 is absent. This compact-centroid check neither unwraps coordinates nor establishes docking correctness. It is applied only to the first frame, preserving later displacement and unbinding. Independently fitting partners, or clustering every later frame, must not conceal relative motion/unbinding. ``energy_drift`` reports NVE total-energy slope per ns and per atom; it does not treat correlated frames as independent replicates or normalize by a potential zero. ``inspect_md_trajectory(..., contact_cutoff=5.0, docking=True)`` additionally reports zero-inclusive chain-pair contact counts, observed residue-pair occupancy over saved frames and native docking/placement descriptors for each frame. The reader verifies heavy-atom identity before comparing contacts. Docking annotates the reference once and transfers exact-sequence region markup onto each frame's own residues. Occupancy is a fraction of saved frames, not an independently sampled binding probability; never-observed residue pairs are omitted. The caller owns the whole-molecule/compact-first-frame/continuous-unwrapping preprocessing, must retain its commands and source hashes, and must provide the explicit RMSD reference. The reader returns first and final saved coordinates, exact frame times and the minimum-potential frame. Post-MD coordinates have no newly inferred predictor confidence; keep the original prediction confidence separate. ``validation.prediction_comparison.compare_peptide_contact_sets`` compares directed inspection contact tables against an explicit predicted comparator over exact TRA/TRB/peptide sequences. It reports shared, reference-only and candidate-only residue pairs and Jaccard agreement. A contact-free complete matching complex is distinct from a missing or different sequence, which remains unavailable. Both tables must use the same inclusive heavy-atom cutoff. Empty unions remain undefined. Agreement is not native accuracy or binding evidence. AF2 retained confidence tokens may use input chain IDs that differ from the PDB writer output. The contact join maps exact full-chain sequences with a complete one-to-one correspondence; it rejects ambiguous renamed identical chains and sequence differences, including on contact-free structures. PAE direction and token pLDDT are preserved without rewriting the producer bundle. Protenix and RF3 summary confidence ----------------------------------- ``generator=protenix`` and ``generator=rf3`` accept native summary JSON scalar values, retaining producer names such as ``iptm``, ``ptm`` and ``ranking_score``. A ranking score is never substituted for ipTM. Native chain-pair arrays and residue/token confidence remain unavailable until version-pinned producer fixtures verify their correspondence to coordinates. These adapters reject ``detail_confidence`` and ``producer_structure`` instead of assuming AF3 semantics. ``models.tsv`` records ``confidence_token_mapping_status=unavailable_unverified_token_mapping``. The scalar schemas were checked against the official `Protenix confidence producer `_ and `RF3 output writer `_. Synthetic tests verify scalar preservation and rejection of unsupported detail inputs; they do not establish a completed prediction campaign or validated token mapping. Frozen candidate pools and CPUs ------------------------------- ``score -s templates.txt -c candidates.tsv -p karnaukhov2022 -t 0 -o scores.csv`` accepts a candidate manifest with ``complex.id`` and ``peptide`` columns. Annotation runs as a parent batch; coarse contiguous template workers then score the pools and return results in the original template order. Default ``-t 0`` uses all allocated CPUs, ``-t 1`` selects serial execution, and positive N selects a bounded budget. Native kernels stay serial inside workers. A pool failure is propagated. Keep candidate identities and multiplicities fixed for potential comparisons. ``rank`` generates another background and is not a replacement for scoring a frozen legacy pool. Residue-sequence threading does not supply physical mutant sidechain coordinates for an atom-specific correction. Paired CDR3 candidate pools --------------------------- ``score-receptors -s templates.txt -c receptors.tsv -p karnaukhov2022 -t 0 -o scores.csv`` threads paired receptor sequences onto each template's fixed CDR3:peptide contacts by default (``--receptor-region cdr3``). The tab-separated input requires ``complex.id``, ``candidate.id``, ``cdr3a`` and ``cdr3b``. IDs are unique within a template; distinct IDs with identical sequences remain separate rows. Each sequence must contain standard uppercase amino acids and exactly match its template's observed, anchor-excluded CDR3 length. Exactly one physical TRA and TRB CDR3 and one observed standard-amino-acid peptide are required. The contact cutoff must be finite and positive. Missing templates and invalid rows fail. The command builds one fresh contact map per template and reuses ``score_peptides`` with the receptor (``from``) side substituted. ``score.tra`` and ``score.trb`` are separate directed sums; ``score`` is their sum, with the selected potential's units and missing-cell omission policy. In default CDR3 mode, framework and CDR1/2 contacts are excluded. This is fixed-contact sequence threading, with no donor coordinate construction, anchor synthesis, fitting, or peptide-only weighting/reference options. Parent-only batched annotation precedes coarse bounded workers; default ``-t 0`` uses allocated CPUs, with serial native kernels. ``-t 1`` selects serial execution. ``--receptor-region junction`` instead requires ``junctiona`` and ``junctionb`` input columns. A junction includes the actual observed Cys104 and F/W118 anchors. The command recovers them from the last annotated FR3 residue and first annotated FR4 residue, requiring one unambiguous annotation of each flank and immediate adjacency to the contiguous observed CDR3. Missing, gapped or invalid anchors fail; no anchor residues are synthesized. Candidate junctions must start with C, end with F or W, and exactly match the observed template junction length. Physical anchor contacts contribute to each directed chain sum. The contact view is indexed from the observed junction start without modifying the structure or contact map. The default CDR3 mode and its output columns remain unchanged.