> For the complete documentation index, see [llms.txt](https://help.dragen.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dragen.illumina.com/dragen-v4.5/product-guides/dragen-v4.5/qc-metrics-reporting/json-metrics-reporting.md). # JSON Metrics Reporting DRAGEN generates an output JSON file, `.metrics.json` that aggregates metadata and module information into a single file that be easily parsed and indexed. The JSON file currently contains the following modules (when enabled): * Mapping and Aligning metrics (analogous to `.mapping_metrics.csv`) * Variant Calling metrics (analogous to `.vc_metrics.csv`) * Coverage region metrics (analogous to `..coverage_metrics.csv`) * FASTQC metrics (analogous to `.fastqc_metrics.csv`) The JSON file also currently contains the following sections: * Metadata ### Format The JSON file is composed of nested dictionary entries containing metadata and metric information. A standard output JSON metrics file is shown below: ``` { "metadata": { "dragenVersion": "x.y.z", "licenseInfo": [ { "license": "Genome", "licenseUsage": 0, "licenseUsageUnits": "bases" } ], "runInfo": { "aligner": [ "map/align" ], "callers": [ "None" ], "features": [ "ORA in", "BAM out", "qc-metrics" ], "mode": [ "WES", "FPGA mode" ], "pipeline": "Germline", "reference": "hg38" }, "runContext": "exampleRun", "timestamp": "2026-02-12T05:22:19Z", }, "modules": { "coverageSummary": { }, "fastQc": { }, "mapAlign": { }, "variantCaller": { }, "qscoreSampleHist": { } } } ``` The metadata section contains information about a DRAGEN run its license consumption. It currently contains the following information: * DRAGEN version - the version of DRAGEN used (string) * License information - an array of JSON objects containing license name (string) and license usage (integer) * Run information - A JSON object containing multiple pieces of high level information to describe the run that took place * Run context - If provided, contains additional context describing the run as provided by the user * Timestamp - A UTC timestamp of when the run completed A typical metric field will have the following format: ``` "metricName": { "description": "Text description", "percentage": "Percentage of total (if applicable, i.e. reads, bases, etc.)", "value": or , "units": "Metric units" } ``` ### Mapping and Aligning Metrics The `mapAlign` module contains two nested dictionaries: one for global metrics applicable to the whole sample (`globalMetrics`) and one for all read group information (`perReadGroupMetrics`). Read group metrics are dictionaries indexed by the read group name and contain per read group level information. This is summarized in the following format: ``` "mapAlign": { "globalMetrics": { "metricName": { }, ... }, "perReadGroupMetrics: { "readGroup1": { "metricName": { }, ... }, "readGroup2": { "metricName": { }, ... } } } ``` The following table shows the mapping between the corresponding JSON field name and the standard output/CSV name: | JSON Metric Name | Standard Output/CSV Name | | ------------------------------ | ----------------------------------------------------------- | | totalInputReads | Total input reads | | duplicateMarkedReads | Number of duplicate marked reads | | duplicatesRemoved | Number of duplicate marked and mate reads removed | | uniqueReads | Number of unique reads | | readsMateSequenced | Reads with mate sequenced | | readsWithoutMateSequenced | Reads without mate sequenced | | qcFailedReads | QC-failed reads | | mappedReads | Mapped reads | | mappedReadsR1 | Mapped reads R1 | | mappedReadsR2 | Mapped reads R2 | | mappedReadsToPopAltInsertions | Mapped reads to pop-alt insertions (PAI) | | mappedReadsToNonRefDecoys | Mapped reads to non-ref decoys (NRD) | | mappedReadsToRefExternalSeq | Mapped reads to ref-external sequences (PAI or NRD) | | mappedReadsToFilterContigs | Mapped reads (RNA) to rRNA and filtered | | mappedReadsToExcludedContigs | Mapped reads (RNA) to chrM and excluded from metrics | | mappedReadsAdj | Mapped reads including ref-external or filtered or excluded | | unmappedReads | Unmapped reads | | unmappedReadsAdjForRefExternal | Unmapped reads minus ref-external mappings | | unmappedReadsAdjForFiltered | Unmapped reads minus filtered mappings | | unmappedReadsAdjForExcluded | Unmapped reads minus excluded mappings | | unmappedReadsAdj | Unmapped reads minus ref-external or filtered or excluded | | singletonReads | Singleton reads | | pairedReads | Paired reads | | properlyPairedReads | Properly paired reads | | discordantReads | Not properly paired reads (discordant) | | pairedReadsDiffChrom | Paired reads mapped to different chromosomes | | pairedReadsDiffChromMapQ10 | Paired reads mapped to different chromosomes (MAPQ >= 10) | | readsMultipleLoc | Reads mapping to multiple locations | | readsMapQ40Inf | Reads with MAPQ \[40:inf) | | readsMapQ3040 | Reads with MAPQ \[30:40) | | readsMapQ2030 | Reads with MAPQ \[20:30) | | readsMapQ1020 | Reads with MAPQ \[10:20) | | readsMapQ010 | Reads with MAPQ \[ 0:10) | | readsMapQNa | Reads with MAPQ NA (Unmapped reads) | | readsWithIndelR1 | Reads with indel R1 | | readsWithIndelR2 | Reads with indel R2 | | readsWithSpliceJunction | Reads with splice junction | | totalBases | Total bases | | totalBasesR1 | Total bases R1 | | totalBasesR2 | Total bases R2 | | mappedBases | Mapped bases | | mappedBasesR1 | Mapped bases R1 | | mappedBasesR2 | Mapped bases R2 | | softClippedBases | Soft-clipped bases | | softClippedBasesR1 | Soft-clipped bases R1 | | softClippedBasesR2 | Soft-clipped bases R2 | | hardClippedBases | Hard-clipped bases | | hardClippedBasesR1 | Hard-clipped bases R1 | | hardClippedBasesR2 | Hard-clipped bases R2 | | mismatchedBasesR1 | Mismatched bases R1 | | mismatchedBasesR2 | Mismatched bases R2 | | mismatchedBasesR1ExIndel | Mismatched bases R1 (excl. indels) | | mismatchedBasesR2ExIndel | Mismatched bases R2 (excl. indels) | | q30Bases | Q30 bases | | q30BasesR1 | Q30 bases R1 | | q30BasesR2 | Q30 bases R2 | | q30BasesNonDupNonClipped | Q30 bases (excl. dups & clipped bases) | | totalAlignments | Total alignments | | secondaryAlignments | Secondary alignments | | supplementaryAlignments | Supplementary (chimeric) alignments | | estimatedReadLength | Estimated read length | | insertLengthMean | Insert length: mean | | insertLengthMedian | Insert length: median | | insertLengthStdDev | Insert length: standard deviation | | inputBasesRefGenomeRatio | Input bases divided by reference genome size | | inputBasesTargetBedRatio | Input bases divided by target bed size | | estimatedSampleContamination | Estimated sample contamination | ### Variant Calling Metrics The `variantCaller` module contains three nested dictionaries: the variant calling summary (`summary`), prefilter metrics (`prefilter`), and postfilter metrics (`postfilter`). The prefilter and postfilter metrics are dictionaries index by the read group name. This summarized in the following format: ``` "variantCaller": { "summary": { "metricName": { }, ... }, "preFilter": { "readGroup1": { "metricName": { }, ... }, ... }, "postFilter": { "readGroup1": { "metricName": { }, ... }, ... }, } ``` The following table shows the mapping between the corresponding JSON field name and the standard output/CSV name: | JSON Metric Name | Standard Output/CSV Name | | ------------------------------ | -------------------------------------------------- | | numberOfSamples | Number of samples | | readsProcessed | Reads Processed | | childSample | Child Sample | | totalVariants | Total | | singleAllelic | Single allelic | | biallelic | Biallelic | | multiallelic | Multiallelic | | snps | SNPs | | insertions | Insertions | | insertionsHap | Insertions (Hap) | | insertionsHom | Insertions (Hom) | | insertionsHet | Insertions (Het) | | deletions | Deletions | | deletionsHap | Deletions (Hap) | | deletionsHom | Deletions (Hom) | | deletionsHet | Deletions (Het) | | indelsHet | Indels (Het) | | denovoAutosomeSnp | DeNovo Autosome SNPs | | denovoAutosomeIndel | De Novo INDELs | | denovoChrXSnp | DeNovo chrX SNPs | | denovoChrXIndel | DeNovo chrX INDELs | | denovoChrYSnp | DeNovo chrY SNPs | | denovoChrYIndel | DeNovo chrY INDELs | | chrXSnp | Chr X number of SNPs over `` | | chrYSnp | Chr Y number of SNPs over `` | | chrXYSnpRatio | (Chr X SNPs)/(chr Y SNPs) ratio over `` | | snpTransitions | SNP Transitions | | snpTransversions | SNP Transversions | | tiTvRatio | Ti/Tv ratio | | snpTransitionsNonCentromeric | SNP Transitions (non-centromeric) | | snpTransversionsNonCentromeric | SNP Transversions (non-centromeric) | | tiTvRatioNonCentromeric | Ti/Tv ratio (non-centromeric) | | numHeterozygous | Heterozygous | | numHomozygous | Homozygous | | snpMosaic | SNP Mosaics | | indelMosaic | Indel Mosaics | | inDbSnp | In dbSNP | | notInDbSnp | Not in dbSNP | | percentCallability | Percent Callability | | percentAutosomeCallability | Percent Autosome Callability | | percentExomeCallability | Percent Autosome Exome Callability | | percentQcRegionCallability | Percent QC Region Callability in Region `` | ### QC Coverage Region Metrics The `coverageSummary` module contains nested dictionaries for each of the QC regions provided as input to DRAGEN. Each dictionary is indexed by the name of the region if provided (e.g `--qc-coverage-tag` is set), or by the default command line name of the region (e.g. `qc-coverage-region-1`). This is summmarized in the following format: ``` "coverageSummary": { "qc-coverage-region-1": { "metricName": { }, ... } "qc-coverage-region-2": { "metricName": { }, ... } "my-custom-region-name": { "metricName": { }, ... }, } ``` The following table shows the mapping between the corresponding JSON field name and the standard output/CSV name: | JSON Metric Name | Standard Output/CSV Name | | ------------------------------ | --------------------------------------------------------- | | alignedBases | Aligned bases | | alignedBasesInRegion | Aligned bases in `` | | avgAlignmentCovOverRegion | Average alignment coverage over `` | | uniformityCov20PerOverRegion | Uniformity of coverage (PCT > 0.2\*mean) | | uniformityCov40PerOverRegion | Uniformity of coverage (PCT > 0.4\*mean) | | pctOfRegionWithCoverageNxtoInf | PCT of `` with coverage Nx to Inf | | medianChrXCovOverRegion | Median chr X coverage (ignore 0x regions) over `` | | medianChrYCovOverRegion | Median chr Y coverage (ignore 0x regions) over `` | | avgMitoCovOverRegion | Average mitochondrial coverage over `` | | avgAutosomalCovOverRegion | Average autosomal coverage over `` | | medianAutosomalCovOverRegion | Median autosomal coverage over `` | | meanMedianCovRatioOverRegion | Mean/Median autosomal coverage ratio over `` | | alignedReads | Aligned reads | | alignedReadsInRegion | Aligned reads in `` | ### FASTQC Metrics The `fastQc` module contains nested dictionaries of metrics for read 1 and read 2 (if applicable). Since these represent sets of histogram data, the format in JSON is different than other modules. This is summmarized in the following format: ``` "fastQc": { "gcContent": { "read1": { }, "read2": { } } "gcContentQual": { ... }, "posQual": { ... }, "positionalBaseContent": { ... }, "positionalBaseQuality": { ... }, "readLengths": { ... }, "readMeanQuality": { ... }, "seqPos": { ... }, } ``` The following table shows the mapping between the corresponding JSON field name and the standard output/CSV name: | JSON Metric Name | Standard Output/CSV Name | | --------------------- | ---------------------------- | | readMeanQuality | Read Mean Quality | | positionalMeanQuality | Positional Base Mean Quality | | positionalBaseContent | Positional Base Content | | readLengths | Read Lengths | | readGcContent | Read GC Content | | readGcContentQuality | Read GC Content Quality | | seqPos | Sequence Positions | | posQuality | Positional Quality | ### Sample Qscore Histogram The `qscoreSampleHist` module contains a list of JSON objects containing an observed qscore value and the ratio in which the score was observed in the sample of 10,000 reads observed. A qscore value is only shown if its ratio was greater then 0.01, or 1%. This is summmarized in the following format: ``` "qscoreSampleHist": [ { "qscore": 40, "sample_ratio": 0.47 }, { "qscore": 39, "sample_ratio": 0.18 }, ... ] ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.dragen.illumina.com/dragen-v4.5/product-guides/dragen-v4.5/qc-metrics-reporting/json-metrics-reporting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.