Links Module¶

External database link generation

Module for adding configurable links to output tables.

This module provides functionality to add new columns containing URL links to each variant line in the final output. The URLs and their substitution logic are defined in the configuration file (config.json) under “links” or “links_by_build”.

For example, if you have a link defined as:

"links": {
    "SpliceAI": "https://spliceailookup.broadinstitute.org/#variant={CHROM}-{POS}-{REF}-{ALT}&hg=38&bc=basic&distance=500&mask=0&ra=0"
}

This will create a new column named “SpliceAI” with a URL where {CHROM}, {POS}, {REF}, {ALT} are replaced by the corresponding values from each row.

variantcentrifuge.links.normalize_reference(reference)[source]¶

Normalize a reference genome identifier to canonical assembly name.

Returns ‘GRCh37’ for hg19/GRCh37 references and ‘GRCh38’ for hg38/GRCh38 references, ignoring version suffixes (e.g., GRCh37.75, GRCh38.99). Returns None for unsupported or non-human assemblies.

Parameters:: reference (str | None)
Return type:: str | None

variantcentrifuge.links.resolve_links(config)[source]¶

Resolve external link configurations based on genome build and explicit configuration.

If ‘links’ is explicitly configured with custom templates (i.e. not matching the bundled defaults), those custom templates are preserved. Otherwise, links are resolved from ‘links_by_build’ based on ‘reference’. If the reference build is unsupported or unknown, bundled links return an empty dict to prevent silently generating hg19 links from GRCh38 or non-human coordinates.

Parameters:: config (dict[str, Any]) – Configuration dictionary containing ‘reference’, optional ‘links’, and optional ‘links_by_build’.
Returns:: The resolved link templates mapping link names to URL templates.
Return type:: dict[str, str]

variantcentrifuge.links.add_links_to_table(lines, link_configs)[source]¶

Add link columns to the table lines based on provided link configurations.

Parameters:

lines (list[str]) – The lines of the final table (including header).
link_configs (dict[str, str]) – A dictionary where keys are link column names and values are URL templates. URL templates contain placeholders like {CHROM}, {POS}, {REF}, {ALT} that are replaced with values from the corresponding columns.

Returns:

The modified lines with new link columns appended.

Return type:

list[str]

Notes

Assumes the first line is a header line.
Each link column is appended to the end of the table.
Placeholders in the link template must match header column names exactly (case-sensitive).
If a placeholder column doesn’t exist in the header, the link will be empty.