Add reference evidence

Choose the source interface based on the shape of the scientific information.

Per-variant annotations

Use AnnotationSource when each query variant receives zero or one logical annotation record. A record may contain scalar, repeated, or structured fields.

annotations = await source.annotate(variant_ids)

Sources omit variants for which they have no record. Altar's merge preserves those variants with an empty annotation rather than manufacturing values.

An annotation source may declare a prioritization predicate. Passive sources return no predicate and only add evidence.

A source that implements a published AnnotationContract returns its AnnotationSourceIdentity from identity(): the contract, the data release, and the genome build. A host can implement a contract over its own tables; see Use your own annotation tables.

Variant–gene relations

Use VariantGeneLinkSource when a locus can connect to several genes or regulatory elements, or when each link needs its own biosample, distance, score, and provenance.

page = await source.query_links(query)
for link in page.links:
    use(link)

The relation contract is paginated and genome-build-aware. Released datasets can normalize into VariantGeneEvidenceRecord and use VariantGeneLinkStore; source-specific parsing then composes with generic in-memory, SQLite, PostgreSQL, Parquet, BigQuery, or service stores. The store indexes a stable evidence interval, while the source attaches the caller's query locus only when returning a VariantGeneLink.

Lookup versus inference

If published scores already exist before the Altar analysis starts, represent access to those scores as a source. Use a model binding only when the analysis actually executes inference or calls a model API. The integration catalog shows how current components are classified.