Extract publication observations

Read AUTHORITIES.md and the chunk specification. Respect the requested source and technology scope. A reference already present in VDJdb does not establish complete coverage.

For deposited complexes, use structures and the local tcren pipeline. New observations go to the PDB aggregate with their publication reference; inventory reused templates separately. Inspect complete polymer sequences as well as resolved coordinates.

Reconcile the sources

Before extracting a collection or follow-up paper, compare its reported epitope and CDR3 sequences with the last released database and current chunks. Use duplicate review to measure overlap by original publication, then check paired chains, restriction and experiment identifiers. A large overlap can identify an earlier import; a paper filename or reference count alone cannot establish coverage. Attribute reused observations to their original papers. Use the collection paper's reference only for observations first reported in its own experiments.

Inventory the supplied article, supplements and processed assignments. Record which tables contain sequences, pairing, peptides, restrictions and assays. Join on reported clone, donor, well or barcode identifiers and record join cardinality. Do not assert resolved pairing from row order or oligoclonal coexpression. For several reported chains in one source clonotype, prefer the candidate-pair convention: one row per distinct alpha-beta combination, method.pairing=ambiguous, the original meta.clone.id on every row, and an issue comment describing the uncertainty. Retain the same experiment/pMHC metadata and source counts; repeated counts are one clonotype's support.

One row reports one observation or an explicitly marked candidate pair. Verify literal sequences, calls and identifiers against the source. A positive specificity needs at least one reported junction, a literal peptide and supported restriction. A gene or protein label alone is not a peptide assignment. Never derive the tested peptide from a canonical protein sequence.

Separate positive observations, explicit assay negatives, unassigned sequences, reused literature comparisons and unavailable assignments. Give every supplied observation a disposition. Do not turn an assay failure into a negative if a separate binding identification remains supported.

Preserve the submitted biology

The canonical junction starts with C and ends with F or W. Use AIRR junction_aa, which includes both anchors; cdr3_aa excludes them. If only an IMGT core is printed, retain that literal core and inspect the build repair. Preserve terminal flanks and reported V/J values when assembly resolves them. Internal cysteines and noncanonical anchors are review findings, not permission to discard an observation.

Invalid amino-acid symbols, incomplete sequences and chemical modifications require a recorded source disposition outside the positive build. Keep the original source; do not silently delete it or substitute standard residues. Ask only for a curation decision that is still unresolved.

For spreadsheets, inspect repeated headers, formula cells, functionality suffixes and swapped J/D fields. Do not strip allele suffixes merely because a cell also contains a functionality code. For a 10x Genomics dextramer matrix, call the chain co-occurrence caller for the donors in that chunk. process_donor(dcode, donor) and processing/dcode_chain_graph.py --dcode DIR --donors 1 2 3 4 --out DIR rebuild the five tables behind chunks/ISSUE_289.tsv. Deposited ITRAP matrices use processing/itrap_reprocess.py: itrap1_tables then run_frames for chunks/PMID_37133356.tsv, and viral_tables then run_frames for chunks/DOI_10.64898_2025.12.19.695506.tsv. The procedure, the filenames and which committed file is the published table are in Process a 10x dextramer assay. The standalone script reads numeric UMIs, never _binder flags, and writes five sorted tab-separated tables. Fit donors separately: a barcode is unique only within its donor. Validate finite nonnegative integer counts and preserve measured zeros; missing measurements are not zero. Inspect chain posteriors, retained shapes and doublet decisions before exporting calls to the chunk schema. score is a fitted-model posterior, not a p-value or an FDR bound; keep it separate from the VDJdb confidence score. Follow the linked formulas for the negative-binomial background/shared-elevation/single-hot-cell model and its numerical limits. Barcode pairing and clonotype aggregation have different meanings; keep a published assignment when that published table is the chunk.

Record methods and provenance

Use source-supported vocabulary for identification, sequencing, pairing and verification. cultured-T-cells requires culture before receptor sequencing. Later culture of a reconstructed receptor does not establish it. Do not infer tetramers from an unspecified multimer or sorting step. Verification describes the retested receptor, not the initial identification.

Keep clonotype frequency separate from subset frequency. Reported counts, totals, fractions and percentages retain their meanings. Optional donor and method detail stays blank when unknown. Identifiers in metadata must come from the publication, not generated export row labels.

Use a verified PMID, DOI, patent or PDB reference. A submission without a publication uses its VDJdb issue URL. Never guess a PMID. Keep extraction evidence in the local execution record, with source table/row, literal values, joins, exclusions and unresolved questions.

Write the current schema header with UTF-8, tabs, LF endings and empty cells for missing values. Continue with format and proofread.

Reported peptides and predicted cores

Preserve the complete assay peptide and source-supported MHC/provenance. Use standalone vdjdb assess-epitopes during review when predicted presenters, binding registers or TCR-facing representations help resolve a comparison. Follow the assessment guidance. Predictions do not supply a missing experimental epitope or establish equivalent recognition. A predicted core can omit required flanks or insertions and does not replace a structure's full ligand.