Should the metric definition/ID evolve from common to specific based on data type (short/long) and assembly (GRCh37/38)?

[justinjj24]

Do we need to refine the metric definition/ID from a common form to more specific ones depending on data type (short paired-end / long), genome assembly (GRCh37 / 38) and the JSON schema?

Current version support specific to short pair-end data, GRCh38 assembly and only autosomes non gap regions of GRCh38.

Metrics common to both short and long read sequence data are yield BP, percent reads mapped, mean coverage, cross contamiination, count SNV and ti/tv rate..

eg.

GRCh38 assembly refers to 1000genome-dragen-3.7.6 reference

Autosomes non gap regions
Autosomes non gap regions refers to the selection of chromosome 1 to 22, excluding chromosome X, Y, M and alternative contigs. In addition, gap regions as defined by UCSC are excluded. See NPM-sample-qc documentation

[justinjj24]

Guideline for Metric Definition/ID Granularity

1. Base Principle

• Each metric should have a stable base ID (e.g., mean_coverage, variant_count).

• Context-specific information (e.g., data type, reference genome) should be captured as attributes/metadata unless differences fundamentally change the interpretation.

2. When to Keep a Metric Common

Keep a single ID when:

• The definition and calculation method are identical across data types and assemblies.

• Differences are only in values, not in meaning (e.g., coverage depth is calculated the same way for short vs. long reads).

• Comparisons across contexts are valid and interpretable.

Example:

• mean_autosome_coverage → calculation is the same whether GRCh37 or GRCh38; only the chromosome lengths differ.

• Store assembly info in metadata instead of splitting IDs.

3. When to Make a Metric Specific

Create separate IDs or definitions when:

• The metric has different formulas or assumptions across data types.

• The interpretation differs depending on assembly or technology.

• Reuse of a “common” definition would be misleading or non-comparable.

Example:

Mapping quality (MAPQ) has different scales between Illumina short reads and ONT long reads → should not share one metric ID.

4. Metadata Requirements

Every metric entry must include at least:

• data_type: {short-read | long-read }

• assembly: {GRCh37 | GRCh38 } / refget_seq: https://[refget-server-url]/sequences/[sequence-checksum]

• version: to ensure provenance

5. Edge Case Handling

• Novel assemblies (pangenome, custom references): use base metric ID, but explicitly record assembly in metadata.

• Hybrid datasets (short + long): store both metrics separately, or define a combined “hybrid” context.

• Deprecated assemblies (GRCh36): maintain backward compatibility with flagged metadata.

6. Recommended Sources for Definitions

• GA4GH: Data Standards (Phenopackets, Metadata, Refget)

• ISO/TC 215 SC1: Genomics informatics standards in development

• GATK Metrics: authoritative for coverage & variant calling

• HTSlib / Samtools: widely used for basic stats (coverage, quality, etc.)

[justinjj24]

WG consensus:

Extend the metric definition template with attributes:

data_type: {short-read | long-read}
assembly: {GRCh37 | GRCh38 | other}
use GA4GH refget genome sequence collection" instead of assembly to align with other GA4GH standards.
version: {quality-control-wgs-v1.0} GA4GH WGS-QC release to ensure provenance

Schema Flexibility:

• JSON schema will allow for attributes that adapt across different data types {short-read | long-read} and technologies (PacBio/ONT, Illumina/Ultima,MGI) and assemblies
• Version-control -> Standards definition.
  also, version as a child of alignment metric and version as a child of variant metric?
• References and access IDs where applicable
• JSON-LD - link to individual metric definion md file

Common ID + metadata – when the metric meaning is stable
Split into specific IDs – when the metric's definition or interpretation differs across data types or assemblies.

[justinjj24]

Metadata Requirements

• data_type: {short-read | long-read}

• assembly: {GRCh37 | GRCh38 }

• sequencing platform: {PacBio/ONT/Constellation, Illumina/Ultima/MGI}

• associated aligner/variant caller: {BWA-MEM/DRAGEN/Minimap2, GATK/DRAGEN/DeepVaraint}

• version: {quality-control-wgs-v1.0} GA4GH WGS-QC release to ensure provenance