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.

Header

Field	Type	Notes
annotator	string	the name of the annotator and the current version
creationTime	string	yyyy-MM-dd hh🇲🇲ss
genomeAssembly	string	see possible values below
schemaVersion	integer	incremented whenever the core structure of the JSON file introduces breaking changes
dataVersion	string
dataSources	object array	see Data Source entry below
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	see Variant Identifiers
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.
variantType	string	uses Sequence Ontology sequence alterations
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	Sequence Ontology Consequences
impact	string	See Consequence Impact for details
hgvsc	string	HGVS coding nomenclature
hgvsp	string	HGVS protein nomenclature
geneFusion	object	see Gene Fusions entry below
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	see Cancer Hotspots entry below

MANE Select

MANE select tags are only available for RefSeq transcripts on GRCh38.

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	see Fusion entry below

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	see possible values below
consequence	string array	see possible values below

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