# 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 }, ... ] ```