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 generic-format contract see specs/generic-format-adapters.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 formats

These four adapters parse a file you supply and emit the canonical feature record (type, start, end, optional description/score). Point a track at a local file whose extension selects the adapter (e.g. data: ./hotspots.csv), or set adapter: explicitly. A machine-readable schema for this record is served at feature-record.schema.json (published at https://ebi-webcomponents.github.io/protvista/schema/v1/feature-record.schema.json).

features-csv — CSV (comma-separated)

A header row plus one feature per line. Point a track at ./x.csv (or set adapter: features-csv).

• File extension: .csv — fetched as: text
• Header row (required columns): type,start,end,description — plus optional score.
• The header must contain type,start,end,description; score is an optional column. A description cell may be empty (the column is required, the value is not).

Field	Type	Required	Notes
type	string	Yes	Feature category label (e.g. DOMAIN, BINDING). Drives filter: and colour grouping.
start	number	Yes	1-based start position (inclusive).
end	number	Yes	1-based end position (inclusive).
description	string	No	Free text shown in the default tooltip. Omitted when empty.
score	number	No	Optional numeric score. Omitted when empty.

features-tsv — TSV (tab-separated)

Identical to features-csv but tab-delimited. Point a track at ./x.tsv.

• File extension: .tsv — fetched as: text
• Header row (required columns): type,start,end,description — plus optional score.
• The header must contain type<TAB>start<TAB>end<TAB>description; score is an optional column.

Field	Type	Required	Notes
type	string	Yes	Feature category label (e.g. DOMAIN, BINDING). Drives filter: and colour grouping.
start	number	Yes	1-based start position (inclusive).
end	number	Yes	1-based end position (inclusive).
description	string	No	Free text shown in the default tooltip. Omitted when empty.
score	number	No	Optional numeric score. Omitted when empty.

features-json — JSON array of feature objects

A JSON array of objects with the same fields as features-csv. Point a track at ./x.json. Extra object keys are ignored.

• File extension: .json — fetched as: json
• start may instead be given as begin (the UniProt convention); start wins when both are present.

Field	Type	Required	Notes
type	string	Yes	Feature category label (e.g. DOMAIN, BINDING). Drives filter: and colour grouping.
start	number	Yes	1-based start position (inclusive). begin is accepted as an alias; start wins when both are present.
end	number	Yes	1-based end position (inclusive).
description	string	No	Free text shown in the default tooltip. Omitted when empty.
score	number	No	Optional numeric score. Omitted when empty.

bed — BED (tab-separated, positional)

Standard BED (BED3–BED6), headerless and positional. Point a track at ./x.bed.

• File extension: .bed — fetched as: text
• BED coordinates are 0-based half-open and converted to 1-based inclusive. track/browser/# header lines are skipped. Output records carry a synthetic type: "BED"; columns 6+ (strand, …) are dropped.

Field	Type	Required	Notes
chrom	string	No	Column 1 — sequence name; informational only for this single-sequence viewer, so it is dropped.
chromStart	number	Yes	Column 2 — 0-based start; mapped to start (start = chromStart + 1).
chromEnd	number	Yes	Column 3 — 0-based half-open end; mapped to 1-based inclusive end.
name	string	No	Column 4 (optional) — mapped to description.
score	number	No	Column 5 (optional) — mapped to score.

Built-in track adapters (provider-supplied)

These adapters back the built-in semantic kinds. Their input is a response from an EBI API (or equivalent provider) — you do not author these payloads; you point a track at the source URL and the adapter transforms the response. The shapes below are informational (useful when swapping an endpoint or writing a custom adapter for a kind), 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.
features-interpro	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.
confidence-score	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.
pathogenicity-score	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.
pathogenicity-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.

Related

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

Licensed under CC BY 4.0.