For the complete documentation index, see llms.txt. This page is also available as Markdown.

Annotations JSON File Format

Overview

Conventions

In the Illumina Connected Annotations JSON representation, we try to maximize the amount of useful information that is relayed in the output file. As such, we have several conventions that are useful to know about:

  • With boolean key/value pairs, we only output the keys that have a true value. I.e. there's no reason to display "isStructuralVariant":false a few million times when annotating a small variant VCF.

  • When transferring data from the VCF file to the JSON (e.g. for allele depths (AD)), it is common to use a period (.) as a placeholder for missing data in the VCF file. Illumina Connected Annotations treats periods like empty or null strings and therefore will not output those entries.

JSON Layout

In general, each position corresponds to a row in the original VCF file.

For each gene that was referenced in the transcripts found in the positions section, there will be additional gene-level annotation in the gene section.

Parsing

We've put together a new section that discusses how to parse our JSON files easily using examples in a Python Jupyter notebook and a R version as well. In addition, we have information about how to quickly dump content from our JSON file using a tabix-like utility called JASIX.

Field
Type
Notes

annotator

string

the name of the annotator and the current version

creationTime

string

yyyy-MM-dd hh🇲🇲ss

genomeAssembly

string

schemaVersion

integer

incremented whenever the core structure of the JSON file introduces breaking changes

dataVersion

string

dataSources

object array

samples

string array

the order of these sample names will be used throughout the JSON file when enumerating samples

Data Source

Field
Type
Notes

name

string

version

string

description

string

optional description of the data source

releaseDate

string

yyyy-MM-dd

Genome Assemblies

  • GRCh37

  • GRCh38

  • hg19

  • SARSCoV2

Positions

Field
Type
Variant Type
Notes

chromosome

string

all

exactly as displayed in the vcf

position

integer

all

exactly as displayed in the vcf (1-based notation). Range: 1 - 250 million

id

string

all

provided from ID column in the VCF file, this field will be omitted if empty or has "." value

repeatUnit

string

STR

provided by ExpansionHunter

refRepeatCount

integer

STR

provided by ExpansionHunter

svEnd

integer

SV

refAllele

string

all

exactly as displayed in the vcf

altAllele

string array

all

exactly as displayed in the vcf

quality

float

all

exactly as displayed in the vcf (Normally an integer, but some variant callers using floating point. Has been observed as high as 500k)

filters

string array

all

exactly as displayed in the vcf

ciPos

integer array

SV

ciEnd

integer array

SV

svLength

integer

SV

strandBias

float

small variant

provided by GATK (from SB)

jointSomaticNormalQuality

integer

SV

provided by the Manta variant caller (SOMATICSCORE)

cytogeneticBand

string

all

e.g. 17p13.1

ClinGen

Field
Type
Notes

clingen

object array

chromosome

string

Ensembl-style chromosome names

begin

integer

1-based position

end

integer

1-based position

variantType

string

Any of the sequence alterations defined here.

id

string

Identifier from the data source. Alternatively a VID

clinicalInterpretation

string

see possible values below

observedGains

integer

Range: 0 - (231 - 1). Only used if copy_number_variation, copy_number_loss, or copy_number_gain.

observedLosses

integer

Range: 0 - (231 - 1). Only used if copy_number_variation, copy_number_loss, or copy_number_gain.

validated

boolean

phenotypes

string array

Description of the phenotype.

phenotypeIds

string array

Description of the phenotype IDs.

reciprocalOverlap

floating point

Range: 0 - 1. E.g. 0.57 would indicate a 57% reciprocal overlap. Specified up to 5 decimal places (Not reported for Insertions).

clinicalInterpretation

  • benign

  • curated benign

  • curated pathogenic

  • likely benign

  • likely pathogenic

  • path gain

  • path loss

  • pathogenic

  • uncertain

Field
Type
Notes

clingenDosageSensitivityMap

object array

chromosome

string

Ensembl-style chromosome names

begin

integer

1-based position

end

integer

1-based position

haploinsufficiency

string

see possible values below

triplosensitivity

string

(same as haploinsufficiency)

reciprocalOverlap

floating point

Range: 0 - 1. E.g. 0.57 would indicate a 57% reciprocal overlap. Specified up to 5 decimal places (Not reported for Insertions).

annotationOverlap

floating point

Range: 0 - 1. E.g. 0.57 would indicate a 57% reciprocal overlap. Specified up to 5 decimal places (Not reported for Insertions).

haploinsufficiency and triplosensitivity

  • no evidence to suggest that dosage sensitivity is associated with clinical phenotype

  • little evidence suggesting dosage sensitivity is associated with clinical phenotype

  • emerging evidence suggesting dosage sensitivity is associated with clinical phenotype

  • sufficient evidence suggesting dosage sensitivity is associated with clinical phenotype

  • gene associated with autosomal recessive phenotype

  • dosage sensitivity unlikely

1000 Genomes (SV)

Field
Type
Notes

chromosome

string

begin

integer

end

integer

variantType

string

id

string

allAn

integer

allele number for all populations. Non-zero integer.

allAc

integer

allele count for all populations. Integer.

allAf

floating point

allele frequency for all populations. Range: 0 - 1.0

afrAf

floating point

allele frequency for the African super population. Range: 0 - 1.0

amrAf

floating point

allele frequency for the Ad Mixed American super population. Range: 0 - 1.0

eurAf

floating point

allele frequency for the European super population. Range: 0 - 1.0

easAf

floating point

allele frequency for the East Asian super population. Range: 0 - 1.0

sasAf

floating point

allele frequency for the South Asian super population. Range: 0 - 1.0

reciprocalOverlap

floating point

range: 0 - 1.

gnomAD (SV)

Field
Type
Notes

chromosome

string

chromosome number

begin

integer

position interval start

end

integer

position internal end

variantType

string

structural variant type

variantId

string

gnomAD ID

allAf

floating point

allele frequency for all populations. Range: 0 - 1.0

afrAf

floating point

allele frequency for the African super population. Range: 0 - 1.0

amrAf

floating point

allele frequency for the Ad Mixed American super population. Range: 0 - 1.0

easAf

floating point

allele frequency for the East Asian super population. Range: 0 - 1.0

eurAf

floating point

allele frequency for the European super population. Range: 0 - 1.0

othAf

floating point

allele frequency for all other populations. Range: 0 - 1.0

femaleAf

floating point

allele frequency for female population. Range: 0 - 1.0

maleAf

floating point

allele frequency for male population. Range: 0 - 1.0

allAc

integer

allele count for all populations.

afrAc

integer

allele count for the African super population.

amrAc

integer

allele count for the Ad Mixed American super population.

easAc

integer

allele count for the East Asian super population.

eurAc

integer

allele count for the European super population.

othAc

integer

allele count for all other populations.

maleAc

integer

allele count for male population.

femaleAc

integer

allele count for female population.

allAn

integer

allele number for all populations.

afrAn

integer

allele number for the African super population.

amrAn

integer

allele number for the Ad Mixed American super population.

easAn

integer

allele number for the East Asian super population.

eurAn

integer

allele number for the European super population.

othAn

integer

allele number for all other populations.

femaleAn

integer

allele number for female population.

maleAn

integer

allele number for male population.

allHc

integer

count of homozygous individuals for all populations.

afrHc

integer

count of homozygous individuals for the African / African American population.

amrHc

integer

count of homozygous individuals for the Latino population.

easHc

integer

count of homozygous individuals for the East Asian population.

eurAc

integer

count of homozygous individuals for the European super population.

othHc

integer

count of homozygous individuals for all other populations.

maleHc

integer

count of homozygous individuals for male population.

femaleHc

integer

count of homozygous individuals for female population.

failedFilter

boolean

True if this variant failed any filters (Note: we do not list the failed filters)

reciprocalOverlap

floating point

Reciprocal overlap. Range: 0 - 1.0

annotationOverlap

floating point

Reciprocal overlap. Range: 0 - 1.0

Note: Following fields are not available in GRCh38 because the source file does not contain this information:

Field

femaleAf

maleAf

maleAc

femaleAc

femaleAn

maleAn

allHc

afrHc

amrHc

easHc

eurAc

othHc

maleHc

femaleHc

failedFilter

MITOMAP (SV)

Field
Type
Notes

chromosome

string

begin

integer

end

integer

variantType

string array

reciprocalOverlap

float

Range: 0 - 1. Specified up to 5 decimal places

annotationOverlap

float

Range: 0 - 1. Specified up to 5 decimal places

Samples

Field
Type
VCF
Notes

genotype

string

GT

variantFrequencies

float array

VF, AD

range: 0 - 1.0. One value per alternate allele

totalDepth

integer

DP

non-negative integer values

genotypeQuality

integer

GQ

non-negative integer values. Typically maxes out at 99

copyNumber

integer

CN

non-negative integer values

minorHaplotypeCopyNumber

integer

MCN

non-negative integer values

repeatUnitCounts

integer array

REPCN

ExpansionHunter-specific

alleleDepths

integer array

AD

non-negative integer values

failedFilter

bool

FT

splitReadCounts

integer array

SR

Manta-specific

pairedEndReadCounts

integer array

PR

Manta-specific

isDeNovo

bool

DN

deNovoQuality

float

DQ

diseaseAffectedStatuses

string array

DST

ExpansionHunter-specific

artifactAdjustedQualityScore

float

AQ

PEPE-specific. Range: 0 - 100.0

likelihoodRatioQualityScore

float

LQ

PEPE-specific. Range: 0 - 100.0

lossOfHeterozygosity

bool

CN, MCN

somaticQuality

float

SQ

heteroplasmyPercentile

float

VF

range: 0 - 100. 2 decimal places. One value per alternate allele

binCount

integer

BC

non-negative integer values

Empty Samples

If a sample does not contain any entries, we will create a sample object that contains the isEmpty key. This ensures that sample ordering is preserved while indicating that a sample is intentionally empty.

Variants

Field
Type
Notes

vid

string

chromosome

string

begin

int

1-based non-negative integer values. Range: 1 - 250 million

end

int

1-based non-negative integer values. Range: 1 - 250 million

isReferenceMinorAllele

bool

true when this is a reference minor allele

isStructuralVariant

bool

true when the variant is a structural variant

inLowComplexityRegion

bool

true when the variant lies in a low complexity region (gnomAD low complexity regions)

refAllele

string

parsimonious representation of the reference allele

altAllele

string

parsimonious representation of the alternate allele.

hgvsg

string

HGVS g. notation

phylopScore

float

phyloP conservation score. Range: -14.08 to 6.424

Reference Minor Alleles

Illumina Connected Annotations supports annotating reference minor alleles. In such a case, refAllele will be replaced by the global major allele and altAllele will be replaced with the original reference allele.

Transcripts

Field
Type
Notes

transcript

string

transcript ID. e.g. ENST00000445503.1

source

string

RefSeq / Ensembl

bioType

string

descriptions of the biotypes from Ensembl

codons

string

aminoAcids

string

cdnaPos

string

Format: start-end/Length

cdsPos

string

Format: start-end/Length

exons

string

exons affected by the variant

introns

string

introns affected by the variant

proteinPos

string

Format: start-end/Length

geneId

string

gene ID. e.g. ENSG00000116062

hgnc

string

gene symbol. e.g. MSH6

consequence

string array

impact

string

See Consequence Impact for details

hgvsc

string

HGVS coding nomenclature

hgvsp

string

HGVS protein nomenclature

geneFusion

object

isCanonical

bool

true when this is a canonical transcript

isManeSelect

bool

true when this is a MANE select transcript

proteinId

string

protein ID. E.g. ENSP00000405294.1

completeOverlap

bool

true when this transcript is completely overlapped by the variant

cancerHotspots

string array

Amino Acid Conservation

Field
Type
Notes

aminoAcidConservation

object

scores

object array of doubles

percent conserved with respect to human amino acid residue. Range: 0.01 - 1.00

Gene Fusions

Field
Type
Notes

exon

int

actual exon where the breakpoint was located

intron

int

actual intron where the breakpoint was located

fusions

object array

Fusion

Field
Type
Notes

exon

int

actual exon where the other breakpoint was located

intron

int

actual intron where the other breakpoint was located

hgvsc

string

HGVS coding nomenclature describing the two genes and the transcripts that are fused along with

Cancer Hotspots

Field
Type
Notes

residue

string

numSamples

int

how many samples are associated with a variant at the same amino acid position

numAltAminoAcidSamples

int

how many samples are associated with a variant with the same position and alternate amino acid position

qValue

double

Regulatory Regions

Field
Type
Notes

id

string

type

string

consequence

string array

Regulatory Types

  • CTCF_binding_site

  • enhancer

  • open_chromatin_region

  • promoter

  • promoter_flanking_region

  • TF_binding_site

Regulatory Consequences

  • regulatory_region_variant

  • regulatory_region_ablation

  • regulatory_region_amplification

  • regulatory_region_truncation

ClinVar

small variants:

large variants:

Field
Type
Notes

id

string

ClinVar ID

variationId

string

ClinVar VCV ID

variantType

string

variant type

reviewStatus

string

see possible values below

alleleOrigins

string array

see possible values below

refAllele

string

altAllele

string

phenotypes

string array

medGenIds

string array

MedGen IDs

omimIds

string array

OMIM IDs

orphanetIds

string array

Orphanet IDs

significance

string array

see possible values below

lastUpdatedDate

string

yyyy-MM-dd

pubMedIds

string array

PubMed IDs

isAlleleSpecific

bool

true when the current variant alternate allele matches the ClinVar alternate allele

reviewStatus:

  • no assertion provided

  • no assertion criteria provided

  • criteria provided, single submitter

  • practice guideline

  • classified by multiple submitters

  • criteria provided, conflicting interpretations

  • criteria provided, multiple submitters, no conflicts

  • no interpretation for the single variant

alleleOrigins:

  • unknown

  • other

  • germline

  • somatic

  • inherited

  • paternal

  • maternal

  • de-novo

  • biparental

  • uniparental

  • not-tested

  • tested-inconclusive

significance:

  • uncertain significance

  • not provided

  • benign

  • likely benign

  • likely pathogenic

  • pathogenic

  • drug response

  • histocompatibility

  • association

  • risk factor

  • protective

  • affects

  • conflicting data from submitters

  • other

  • no interpretation for the single variant

  • conflicting interpretations of pathogenicity

1000 Genomes

Field
Type
Notes

allAf

float

allele frequency for all populations. Range: 0 - 1.0

allAc

int

allele count for all populations. Integer.

allAn

int

allele number for all populations. Non-zero integer.

afrAf

float

allele frequency for the African super population. Range: 0 - 1.0

afrAc

int

allele count for the African super population. Integer.

afrAn

int

allele number for the African super population. Non-zero integer.

amrAf

float

allele frequency for the Ad Mixed American super population. Range: 0 - 1.0

amrAc

int

allele count for the Ad Mixed American super population. Integer.

amrAn

int

allele number for the Ad Mixed American super population. Non-zero integer.

easAf

float

allele frequency for the East Asian super population. Range: 0 - 1.0

easAc

int

allele count for the East Asian super population. Integer.

easAn

int

allele number for the East Asian super population. Non-zero integer.

eurAf

float

allele frequency for the European super population. Range: 0 - 1.0

eurAc

int

allele count for the European super population. Integer.

eurAn

int

allele number for the European super population. Non-zero integer.

sasAf

float

allele frequency for the South Asian super population. Range: 0 - 1.0

sasAc

int

allele count for the South Asian super population. Integer.

sasAn

int

allele number for the South Asian super population. Non-zero integer.

DANN

Field
Type
Notes

dannScore

float

Range: 0 - 1.0

dbSNP

Field
Type
Notes

dbsnp

string array

dbSNP rsIDs

DECIPHER

Field
Type
Notes

chromosome

int

Ensembl-style chromosome names

begin

int

1-based position

end

int

1-based position

numDeletions

int

# of observed deletions

deletionFrequency

float

deletion frequency

numDuplications

int

# of observed duplications

duplicationFrequency

float

duplication frequency

sampleSize

int

total # of samples

reciprocalOverlap

float

Range: 0 - 1. E.g. 0.57 would indicate a 57% reciprocal overlap

annotationOverlap

float

Range: 0 - 1. E.g. 0.57 would indicate a 57% annotation overlap

GERP

Field
Type
Notes

gerpScore

float

Range: -∞ to +∞

GME Variome

Field
Type
Notes

allAc

int

GME allele count

allAn

int

GME allele number

allAf

float

GME allele frequency

failedFilter

bool

True if this variant failed any filters

gnomAD

Field
Type
Notes

coverage

int

average coverage (non-negative integer values)

allAf

float

allele frequency for all populations. Range: 0 - 1.0

maleAf

float

allele frequency for male population. Range: 0 - 1.0

femaleAf

float

allele frequency for female population. Range: 0 - 1.0

controlsAllAf

float

allele frequency for the controls subset. Range: 0 - 1.0

allAc

int

allele count for all populations. Integer.

maleAc

int

allele count for male population. Integer.

femaleAc

int

allele count for female population. Integer.

controlsAllAc

int

allele count for the controls subset. Integer.

allAn

int

allele number for all populations. Non-zero integer.

maleAn

int

allele number for male population. Non-zero integer.

femaleAn

int

allele number for female population. Non-zero integer.

controlsAllAn

int

allele number for the controls subset. Non-zero integer.

allHc

int

count of homozygous individuals for all populations. Non-negative integer.

maleHc

int

count of homozygous individuals for male population. Non-negative integer.

femaleHc

int

count of homozygous individuals for female population. Non-negative integer.

afrAf

float

allele frequency for the African / African American population. Range: 0 - 1.0

afrAc

int

allele count for the African / African American population. Integer.

afrAn

int

allele number for the African / African American population. Non-zero integer.

afrHc

int

count of homozygous individuals for African / African American population. Non-negative integer.

amrAf

float

allele frequency for the Latino population. Range: 0 - 1.0

amrAc

int

allele count for the Latino population. Integer.

amrAn

int

allele number for the Latino population. Non-zero integer.

amrHc

int

count of homozygous individuals for Latino population. Non-negative integer.

easAf

float

allele frequency for the East Asian population. Range: 0 - 1.0

easAc

int

allele count for the East Asian population. Integer.

easAn

int

allele number for the East Asian population. Non-zero integer.

easHc

int

count of homozygous individuals for East Asian population. Non-negative integer.

finAf

float

allele frequency for the Finnish population. Range: 0 - 1.0

finAc

int

allele count for the Finnish population. Integer.

finAn

int

allele number for the Finnish population. Non-zero integer.

finHc

int

count of homozygous individuals for Finnish population. Non-negative integer

nfeAf

float

allele frequency for the Non-Finnish European population. Range: 0 - 1.0

nfeAc

int

allele count for the Non-Finnish European population. Integer.

nfeAn

int

allele number for the Non-Finnish European population. Non-zero integer.

nfeHc

int

count of homozygous individuals for Non-Finnish European population. Non-negative integer

othAf

float

allele frequency for the Other population. Range: 0 - 1.0

othAc

int

allele count for the Other population. Integer.

othAn

int

allele number for the Other population. Non-zero integer.

othHc

int

count of homozygous individuals for Other population. Non-negative integer

asjAf

float

allele frequency for the Ashkenazi Jewish population. Range: 0 - 1.0

asjAc

int

allele count for the Ashkenazi Jewish population Integer.

asjAn

int

allele number for the Ashkenazi Jewish population. Non-zero integer.

asjHc

int

count of homozygous individuals for the Ashkenazi Jewish population. Non-negative integer

sasAf

float

allele frequency for the South Asian population. Range: 0 - 1.0

sasAc

int

allele count for the South Asian population Integer.

sasAn

int

allele number for the South Asian population. Non-zero integer.

sasHc

int

count of homozygous individuals for the South Asian population. Non-negative integer.

failedFilter

bool

True if this variant failed any filters (Note: we do not list the failed filters)

lowComplexityRegion

bool

True if this variant is located in a low complexity region.

MITOMAP

Field
Type
Notes

refAllele

string

altAllele

string

diseases

string array

associated diseases

hasHomoplasmy

boolean

hasHeteroplasmy

boolean

status

string

record status

clinicalSignificance

string

predicted pathogenicity

scorePercentile

float

MitoTIP score

numGenBankFullLengthSeqs

integer

# of GenBank full-length sequences

pubMedIds

string array

isAlleleSpecific

boolean

true when the current variant alternate allele matches the MITOMAP alternate allele

Primate AI

Field
Type
Notes

aminoAcidPosition

int

Amino Acid Position (1-based)

refAminoAcid

string

Reference Amino Acid

altAminoAcid

string

Alternate Amino Acid

ensemblTranscriptId

string

Transcript ID (Ensembl)

refSeqTranscriptId

string

Transcript ID (RefSeq)

scorePercentile

float

range: 0 - 1.0

genePercentile

float

range: 0 - 1.0

score

float

range: 0 - 1.0

classification

string

pathogenic or benign classification

geneSymbol

string

HGNC gene symbol

REVEL

Field
Type
Notes

score

float

Range: 0 - 1.0

Splice AI

Field
Type
Notes

hgnc

string

HGNC gene symbol

acceptorGainDistance

int

± bp from current position

acceptorGainScore

float

range: 0 - 1.0. 1 decimal place

acceptorLossDistance

int

± bp from current position

acceptorLossScore

float

range: 0 - 1.0. 1 decimal place

donorGainDistance

int

± bp from current position

donorGainScore

float

range: 0 - 1.0. 1 decimal place

donorLossDistance

int

± bp from current position

donorLossScore

float

range: 0 - 1.0. 1 decimal place

TOPMed

Field
Type
Notes

allAc

int

TOPMed allele count

allAn

int

TOPMed allele number. Non-zero integer.

allAf

float

TOPMed allele frequency (computed by Illumina Connected Annotations)

allHc

int

TOPMed homozygous count

failedFilter

bool

True if this variant failed any filters

Genes

Illumina Connected Annotations reports gene annotations for all genes that have an overlapping variant with the exception of flanking variants (i.e. variants that only cause upstream_gene_variant or downstream_gene_variant).

Field
Type
Notes

name

string

HGNC gene symbol

hgncId

int

HGNC ID

summary

string

short description of the gene from OMIM

OMIM

Field
Type
Notes

mimNumber

int

OMIM ID for gene

geneName

string

gene name

description

string

phenotypes

object array

Phenotype

Field
Type
Notes

mimNumber

int

phenotype

string

description

string

mapping

string

inheritance

string array

comments

string array

Mapping

  1. disorder was positioned by mapping of the wild type gene

  2. disease phenotype itself was mapped

  3. molecular basis of the disorder is known

  4. disorder is a chromosome deletion or duplication syndrome

Inheritance

  • autosomal recessive

  • autosomal dominant

Comments

  • contributes to the susceptibility to multifactorial disorders

  • variations that lead to apparently abnormal laboratory test values

  • unconfirmed mapping

gnomAD LoF Gene Metrics

Field
Type
Notes

pLi

float

probability of being intolerant of a single loss-of-function variant (like haploinsufficient genes, observed ~ 0.1*expected)

pNull

float

probability of being completely tolerant of loss of function variation (observed = expected)

pRec

float

probability of being intolerant of two loss of function variants (like recessive genes, observed ~ 0.5*expected)

synZ

float

corrected synonymous Z score

misZ

float

corrected missense Z score

loeuf

float

loss of function observed/expected upper bound fraction (LOEUF)

ClinGen Disease Validity

Field
Type
Notes

clingenGeneValidity

object

diseaseId

string

Monarch Disease Ontology ID (MONDO)

disease

string

disease label

classification

string

see below for possible values

classificationDate

string

yyyy-MM-dd

classification

  • no reported evidence

  • disputed

  • limited

  • moderate

  • definitive

  • strong

  • refuted

  • no known disease relationship

COSMIC Cancer Gene Census

Field
Type
Notes

roleInCancer

string array

Possible roles in caner

tier

number

Cosmic tiers [1, 2]

Samples

ISCN

ISCN-like Simple Nomenclature for CNV and Ploidy VCFs by encoding chromosomal variations using cytogenetic banding patterns, are provided at the sample level.

Field
Type
Notes

id

string

Unique identifier for the sample

simpleNomenclature

string

ISCN-like representation of the karyotype

Last updated

Was this helpful?