Built-in adapter reference

ProtVista configuration (rows, tracks, sources, rendering) is validated by the config JSON Schema; track payloads — the shapes adapters consume — are not. This page fills that gap: the expected input shape for every built-in adapter. For the config-vs-payload boundary see Configuration vs data; for the normative shape-and-format contract see specs/config-approach.md.

This reference is generated from the adapter code and kept in sync by drift tests, so it cannot silently diverge. It is a reference aid, not a normative schema.

Bring your own data

Two independent facts decide how a source is read. Your track’s kind says which records it needs; the file says how they are encoded. You never name an adapter for either: point a track at ./hits.csv and the kind supplies the first half while the extension supplies the second. Use format: only when nothing can infer it — inline text, or a URL with no recognised extension.

A malformed file fails with your own filename, the reading applied to it, and the offending row and column: ./depth.csv (parsed as CSV): row 3, column "value": expected a number, got "abc".

The formats

Format	Extension	Fetched as	Records it can carry
csv	.csv	text	whatever the track’s kind draws
tsv	.tsv	text	whatever the track’s kind draws
json	.json	json	whatever the track’s kind draws
bed	.bed	text	feature records (type, start, end) only

Only BED constrains what it can carry: it encodes feature semantics (0-based half-open, converted on read), so pairing it with a kind that draws anything else is a config error naming both sides.

The record shapes

Three shapes cover every kind that accepts your data. A machine-readable schema for the feature record is served at feature-record.schema.json.

feature records (type, start, end)

Written by: kind: features, kind: interpro-features, kind: peptides, kind: peptides-ptm, kind: structure-coverage.

Readable as: csv, tsv, json, bed — by file extension, or with an explicit format:.

Field	Type	Required	Notes
type	string	Yes	Feature category label (e.g. DOMAIN, BINDING). Drives filter: and colour grouping.
start	integer	Yes	1-based start position (inclusive).
end	integer	Yes	1-based end position (inclusive). Must not be less than start.
description	string	No	Free text shown in the default tooltip. CSV/TSV: the description header column is required (its cells may be empty); optional in JSON, and BED reads it from the name column. Omitted when empty.
score	number	No	Optional numeric score. Omitted when empty.
color	string	No	Per-feature colour (any CSS colour) for the outline, and the fill unless fill is set; wins over the track’s rendering.color. CSV/TSV/JSON only — BED never sets it. Omitted when empty.
shape	string	No	Per-feature glyph (see the type and shape vocabulary); wins over the track’s rendering.shape. CSV/TSV/JSON only. Omitted when empty, and dropped with a warning when it names an Object.prototype property (valueOf, constructor, …).
fill	string	No	Per-feature fill colour; defaults to color. CSV/TSV/JSON only. Omitted when empty.
opacity	number	No	Per-feature opacity, from 0 to 1 (the canvas default is 0.9). CSV/TSV/JSON only. Omitted when empty; any other value is an error.

Any other column of a CSV/TSV file, or key of a JSON record, is kept on the record as written, so a dataTooltip can show it. tooltipContent, locations, residuesToHighlight and names JavaScript reserves (__proto__, toString, …) are dropped with a track-data warning. BED records carry only the fields above that BED can express — never the render fields.

point records (position, value)

Written by: kind: linegraph, kind: rna-editing-counts, kind: variant-counts.

Readable as: csv, tsv, json — by file extension, or with an explicit format:.

Field	Type	Required	Notes
position	integer	Yes	1-based residue position.
value	number	Yes	The number plotted at that position. Any finite value.

variation records (position, variant)

Written by: kind: rna-editing, kind: variants.

Readable as: csv, tsv, json — by file extension, or with an explicit format:.

Field	Type	Required	Notes
position	integer	Yes	1-based position of the changed residue.
variant	string	Yes	The residue it changes to. * for a stop, - for a deletion.
wildType	string	No	The original residue. Shown on hover.
description	string	No	Free text shown on hover/click.
consequence	string	No	Your own consequence label, e.g. missense.

Built-in track adapters (provider-supplied)

These back the kinds named for their provider. Their input is a response from an EBI API (or equivalent) — you do not author these payloads, and no file can stand in for one: each takes two responses plus a further fetch. The shapes below are informational, not a contract you must produce.

Semantic kind	Adapter	Renders with	Inputs	Input shape
features	uniprot-features-json	nightingale-track-canvas	1	UniProt Proteins API features response — { features: [...] }, each feature carrying type, begin, end, and evidence.
interpro-features	interpro-entries-json	nightingale-track-canvas	1	InterPro protein-entries response — { results: [{ metadata, proteins: [{ entry_protein_locations }] }] }. Representative-domain fragments are flattened into features.
variants	uniprot-variation-json	nightingale-variation-canvas	1	UniProt Proteins API variation response — { sequence, features: [...] } with per-variant genomic location, alternative sequence and predictions.
variant-counts	uniprot-variation-counts-json	nightingale-linegraph-track	1	Same variation response as uniprot-variation-json; aggregated into per-position total and disease-causing variant counts for the line graph.
rna-editing	uniprot-rna-editing-json	nightingale-variation-canvas	1	UniProt Proteins API RNA-editing response — { sequence, features: [{ locationType, variantType }] }.
rna-editing-counts	uniprot-rna-editing-counts-json	nightingale-linegraph-track	1	Same RNA-editing response as uniprot-rna-editing-json; aggregated into per-position missense counts for the line graph.
peptides	uniprot-proteomics-json	nightingale-track-canvas	1	UniProt Proteomics API response — { features: [{ unique, ptms }] }; PTMs are lifted onto each peptide as residues to highlight.
peptides-ptm	uniprot-proteomics-ptm-json	nightingale-track-canvas	1	PTMeXchange proteomics-PTM response — { features: [{ begin, peptide, ptms: [{ name, position, dbReferences }] }] }; emitted as per-residue MOD_RES markers coloured by confidence.
structure-coverage	uniprot-proteins-pdb-json	nightingale-track-canvas	1	UniProt Proteins API entry — { dbReferences: [{ type: "PDB", properties: { chains } }] }; PDB chain ranges are parsed and overlapping intervals merged.
alphafold-confidence	alphafold-prediction-json	nightingale-colored-sequence	2 (+ fetches a further URL)	AlphaFold prediction list (matched to the protein sequence) plus the UniProt entry. The adapter then fetches the per-residue confidence JSON and returns pLDDT categories.
alphamissense-pathogenicity	alphamissense-average-csv	nightingale-colored-sequence	2 (+ fetches a further URL)	AlphaFold prediction list (with an AlphaMissense annotations URL) plus the UniProt entry. The adapter fetches the annotations CSV and returns per-position average pathogenicity codes.
alphamissense-heatmap	alphamissense-full-csv	nightingale-sequence-heatmap	2 (+ fetches a further URL)	Same AlphaMissense annotations as alphamissense-average-csv, but returns the full per-mutation { xValue, yValue, score } matrix for the heatmap.

uniprot-proteomics-json output

Each item is the API’s peptide feature with every field passed through under its own name and value (begin, end, peptide, unique, ptms, evidences, xrefs, …), plus the fields below. Only type is overwritten; its API value is kept as sourceType.

Field	Notes
type	'unique' or 'non_unique' (from the API’s unique flag), so filter: can split the two tracks.
sourceType	The API feature’s own type (PROTEOMICS or PROTEOMICS_PTM), which type replaces.
ptms	The API feature’s ptms, unchanged. Each position is relative to the peptide (1 = its first residue).
taxid	The response’s top-level taxid, copied onto each feature.
start	The API begin, which is also kept.
residuesToHighlight	The peptide’s ptms as { name, position, sources, dbReferences }, for highlighting.
category	Always PROTEOMICS.

uniprot-proteomics-ptm-json output

Each item is a marker the adapter builds, one per modification per residue (start = end = the absolute position). The API’s own ptms entries behind it pass through unchanged. The modified residue is not repeated on the marker; read it from the entry sequence at start.

Field	Notes
type	Always MOD_RES_LS.
ptms	The API’s ptms entries for this modification at this residue, unchanged, across every peptide that reports it. Each position is relative to its own peptide.
confidenceScore	The value the marker’s color is computed from: the Confidence score property shared by every entry’s dbReferences (Gold, Silver or Bronze). null when the entries report no score, or a mixture of scores (a mixture also logs a warning).
color	The colour for confidenceScore, or black when it is null.

Related

• Configuration vs data — what config controls vs what providers supply.
• specs/config-approach.md — normative Intent/Representation split.
• specs/config-approach.md — Shape and format — normative shape-and-format contract.
• examples/ — runnable, CI-validated config + data pairs.

Licensed under CC BY 4.0.