DOI: 10.5281/zenodo.15105593
title: Application of qualifying variants for genomic analysis: data and code

description: Application of qualifying variants for genomic analysis: data and code.

For manuscript files see github https://github.com/DylanLawless/qvApp2025lawless.

Qualifying Variants (QVs) are defined, versioned criteria that determine which genomic alterations are included in an analysis. Rather than being hidden as code-level filters, QVs are externalised into human- and machine-readable YAML or JSON files that specify the exact rules applied, such as allele frequency thresholds, gene panels, or pathogenicity classifications. This makes analyses transparent, reproducible, and auditable across tools, studies, and institutions. QVs function as a common reference layer that links the technical and interpretive logic of variant analysis, ensuring that every decision in a genomic workflow is explicit, traceable, and aligned with FAIR data principles.



Contents

./README.md./data├── qv_acmg_guru├── qv_exomiser└── qv_gwas./images./qv_builder_public.html./qv_files├── qv_acmg_svnindel_criteria_20250225.yaml├── qv_gwas_common_v1_20250826.yaml├── qv_trio_wgs_qc_demo_v1_20250829.yaml├── qv_trio_wgs_qc_demo_v1_20250829_prompt.txt└── sha256.sh./ref # reference files used in acmguru study./script├── README.md├── benchmark├── qv_acmg_guru├── qv_exomiser├── qv_gwas└── r_qv_reader

67 directories, 242 files

Data release

This repository includes validation datasets from three studies:1. Public HapMap GWAS data2. GIAB WGS trio analysed with Exomiser3. An in-house rare disease cohort (summary statistics only)

To ensure traceability while keeping the repository size minimal, only files smaller than 10 MB are included.All larger files can be fully reproduced using the provided source scripts.

How to build a QV file


We recommend YAML or JSON for portability and adoption. You can build a QV in three ways:



option 1: use the HTML QV builder (Zenodo)




Open the HTML builder from the Zenodo repository.

Enter simple key=value statements in the left pane.

Copy or download the generated YAML.


Example input lines:



meta qv_set_id="qv_gwas_common_v1_20250827"
meta version="1.0.0"
meta title="GWAS common QC"
meta authors=Alice,Bob
meta tags=GWAS,QC,PCA
filter maf_minimum field=MAF operator=">=" value=0.01 desc="Minimum MAF"
filter hwe field=HWE_P operator=">=" value=1e-6 logic=keep_if
filter region_include desc="include panel" field=OVERLAP(targets.exome.bed) operator=">=" value=1 logic=keep_if
criteria disease_panel logic=and desc="HIGH impact within panel"
criteria disease_panel field=IMPACT operator="==" value=HIGH
criteria disease_panel field=OVERLAP(targets.exome.bed) operator=">=" value=1
meta description_patient="There is a strong family history of early heart attacks."
meta description_ppie="The PPIE group reviewed and approved the criteria on 2025-08-15."



option 2: write YAML by hand


Minimal pattern:



meta:
  qv_set_id: qv_disease_panel_v1_20250828
  version: 1.0.0
  title: Disease panel filter
filters:
  region_include:
    description: Restrict to curated disease gene panel
    logic: keep_if
    field: OVERLAP(targets.disease_panel.bed)
    operator: ">="
    value: 1
criteria:
  pathogenic:
    description: Variant classified as pathogenic or likely pathogenic
    logic: and
    conditions:
      - group: any_of:start
      - { field: CLASS, operator: "==", value: P }
      - { field: CLASS, operator: "==", value: LP }
      - group: any_of:end
notes:
  - Gene panel file defines the target regions

 




option 3: write JSON


JSON equivalent of the minimal example:



{
  "meta": {
    "qv_set_id": "qv_disease_panel_v1_20250828",
    "version": "1.0.0",
    "title": "Disease panel filter"
  },
  "filters": {
    "region_include": {
      "description": "Restrict to curated disease gene panel",
      "logic": "keep_if",
      "field": "OVERLAP(targets.disease_panel.bed)",
      "operator": ">=",
      "value": 1
    }
  },
  "criteria": {
    "pathogenic": {
      "description": "Variant classified as pathogenic or likely pathogenic",
      "logic": "and",
      "conditions": [
        { "group": "any_of:start" },
        { "field": "CLASS", "operator": "==", "value": "P" },
        { "field": "CLASS", "operator": "==", "value": "LP" },
        { "group": "any_of:end" }
      ]
    }
  },
  "notes": [
    "Gene panel file defines the target regions"
  ]
}

 




Checksum, and register


Record the checksum:



sha256sum qv/examples/qv_disease_panel_v1_20250828.yaml

 


Register the release:



# qv/registry/releases.csv
qv_disease_panel_v1_20250828,1.0.0,ef6cf810b994dfd4ce5ac275bce1d2dbe2e60332d1c7af304a88c458046d79ce,qv/examples/qv_disease_panel_v1_20250828.yaml,2025-08-28


 


Versioning and IDs:



Use a stable qv_set_id plus semantic version.

Update the version on any change that affects selection or interpretation.

Keep one file per release and never mutate published files.




use in a workflow


Point your pipeline to the QV file:



# workflows/.../config.yaml
qv_file: ".../qv/registry/qv_disease_panel_v1_20250828.yaml"

 It can be read programmatically at runtime, for example using yq in shell-based workflows or yaml::read\_yaml() in R, providing the same parameters that would otherwise be embedded within pipeline configurations.