1. Overview
2. Key Capabilities
3. Target Personas & Discoverability
4. Comparative Matrix vs. Alternatives
5. Governance & Runtime Invariants
6. Pipeline Architecture & Dataflow
7. Multi-Format Ingestion & Build Detection
8. Multi-Source Annotation & INFO Recycling
9. Quality Filtering & Gene Whitelists
10. Desktop GUI & Web Companion PWA
11. Multi-Format Export & Reporting
12. Cython Hotpath Acceleration
13. Installation & Quickstart
14. Test Suite & Verification Gates
15. Third-Party Licenses & Transparency
16. Security & Vulnerability Reporting
17. Research Use Only Boundary & Compliance
18. License & Maintainers

VFDistiller, also known as Variant Fusion Distiller, is a local-first bioinformatics desktop application for research-grade genetic variant files. It converts, filters, annotates, and exports VCF, gVCF, 23andMe raw text, and FASTA data on the user's own machine, with a Windows-first GUI and optional offline resources for allele-frequency lookup and reference-genome validation.

⚠️ Research Use Only / Nicht für klinische Diagnostik / Not for Clinical Use

VFDistiller is a bioinformatics research tool. It is NOT an in-vitro diagnostic medical device (IVDR (EU) 2017/746), NOT CE-marked, NOT reviewed by BfArM or any notified body and NOT intended for clinical diagnosis, prognosis or therapy decisions. ClinSig / variant-impact values shown are third-party research database annotations, not medical assessments. Use for bioinformatics research, teaching and software development only. Free open-source donation; liability limited to intent and gross negligence (§ 521 BGB, AGPL-3.0 §§ 15–17). Use at your own risk.

A bioinformatics desktop tool for processing, converting, and annotating research-grade genetic variant data from any sequencing source. Supports VCF, gVCF, 23andMe raw format, and FASTA without requiring pysam, bcftools, or samtools, making the workflow practical on Windows workstations.

VFDistiller is engineered to solve genomic data filtering and variant annotation challenges for four primary personas:

To facilitate discoverability across scientific repositories, package managers, and search engines:

• local-first VCF variant annotation desktop tool Windows — Local genetic variant filtering and annotation GUI.
• offline gnomAD allele frequency lookup SQLite GUI — Local SQLite-backed allele frequency annotation without web calls.
• 23andMe raw data to annotated VCF converter python — Direct conversion of direct-to-consumer genotyping text files to research VCF.
• gVCF streaming parser without bcftools pysam dependencies — Windows-compatible genomic VCF parser.
• research-grade genetic variant filtering tool CADD ClinVar — Prioritize SNVs and indels by CADD score and ClinSig.
• privacy-preserving clinical genomics analysis desktop app — Zero-egress genomics workstation application.
• VCF format metrics preservation multi-sample export excel pdf — Export filtered variant tables to Excel and PDF with DP/GQ metrics.
• Cython accelerated VCF parser bioinformatics desktop workstation — High-performance compiled C-extensions for variant processing.

The following matrix compares VFDistiller against existing bioinformatics tools and platforms across 10 technical dimensions directly mapped to our governance invariants:

VFDistiller is architected and maintained according to ten foundational governance and runtime invariants:

• INV-LOCAL-01 (100% Local-First & Zero Egress): All genomic sequencing files, converted VCFs, genome references, SQLite databases, and local settings reside solely on the local workstation. Zero telemetry, zero analytics, zero automated cloud egress.
• INV-PRIVACY-02 (Automated Locus & rsID Log Redaction): Sensitive genomic coordinates and rsIDs are automatically stripped from persistent logs via redact_for_logfile, strictly protecting genetic privacy according to GDPR/DSGVO Art. 9 and GenDG.
• INV-INSPECT-03 (Accessible Desktop GUI & Transparent Filtering): Full visual inspection of variant records via ttkbootstrap desktop GUI and Web Companion PWA; filter criteria (AF thresholds, CADD score, ClinSig, read depth) are completely auditable and user-configurable.
• INV-CONVERT-04 (Multi-Format Ingestion & Standards Parity): Seamless conversion and ingestion of VCF v4.2, gVCF, 23andMe raw text, and FASTA files without requiring Unix-only toolchains (bcftools, samtools, pysam).
• INV-OFFLINE-05 (Offline Allele Frequency & Annotation Capability): Fast local annotation using offline SQLite LightDB (gnomAD) without mandatory internet connectivity, supplemented by optional async REST endpoints (VEP, MyVariant.info).
• INV-ACCEL-06 (Optional Cython Hotpath with Graceful Fallback): Optional compiled Cython extensions provide up to 5x end-to-end acceleration for VCF parsing and AF validation, falling back gracefully to pure Python when no C compiler is available.
• INV-EXPORT-07 (Format Preservation & Multi-Report Generation): VCF exports preserve original sample FORMAT metrics (DP, GQ, AD, PL) and multi-sample integrity, with flexible export to CSV, Excel (.xlsx), and PDF reports.
• INV-UNPRIV-08 (Unprivileged User-Mode Operation — RunAsInvoker): The application runs entirely within unprivileged user space, requiring zero administrative elevation, root rights, or UAC elevation.
• INV-COMPLY-09 (Strict Research Use Only Boundary — RUO): Clear and explicit legal boundaries affirming the application is a research and bioinformatics tool, NOT an in-vitro diagnostic medical device under IVDR (EU) 2017/746 and NOT certified for clinical diagnosis.
• INV-SLA-10 (Open-Source Governance, 48h Security SLA & Test Coverage): Free open-source distribution under AGPL-3.0-or-later, comprehensive third-party license audit, committed 48-hour security response SLA, and automated regression test suites.

flowchart TD
    classDef input fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0c4a6e;
    classDef process fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px,color:#0f172a;
    classDef anno fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f;
    classDef filter fill:#fce7f3,stroke:#db2777,stroke-width:1.5px,color:#831843;
    classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d;

    subgraph Inputs ["1. Multi-Format Input (Local-First)"]
        VCF["VCF / VCF.GZ (v4.2)"]:::input
        GVCF["gVCF (Genomic VCF)"]:::input
        RAW["23andMe Raw Data (.txt)"]:::input
        FASTA["FASTA Reference (.fa)"]:::input
    end

    subgraph Core ["2. Ingestion & Build Detection"]
        PARSER["Streaming Parser / Cython Hotpath"]:::process
        BUILD["Build Detection<br/>GRCh37 (hg19) / GRCh38 (hg38)"]:::process
        PARSER --> BUILD
    end

    subgraph Annotation ["3. Multi-Source Annotation Layer"]
        GNOMAD["gnomAD LightDB (Offline SQLite)"]:::anno
        MYVAR["MyVariant.info (REST)"]:::anno
        VEP["Ensembl VEP (Async aiohttp)"]:::anno
        ALFA["ALFA / TOPMed"]:::anno
        AG["AlphaGenome API (Optional)"]:::anno
    end

    subgraph QualityGate ["4. Quality & Clinical Filtering"]
        AF_FILT["AF Threshold (e.g. &lt; 0.007)"]:::filter
        CADD_FILT["CADD Highlight Score"]:::filter
        CLIN_FILT["ClinVar / ClinSig & Variant Impact"]:::filter
        GENE_FILT["Gene Whitelist / FILTER=PASS"]:::filter
    end

    subgraph Outputs ["5. Interactive UI & Multi-Format Export"]
        GUI["ttkbootstrap Interactive Table"]:::output
        EXP_VCF["Annotated VCF Export"]:::output
        EXP_DOC["CSV / Excel (.xlsx) / PDF Report"]:::output
    end

    Inputs --> PARSER
    BUILD --> Annotation
    Annotation --> QualityGate
    QualityGate --> Outputs

Main Workspace	Filter & Export Workspace

VFDistiller ingests genetic variant files from diverse sequencing pipelines and direct-to-consumer services without intermediate format converters:

• Standard VCF 4.2 (.vcf, .vcf.gz): Streaming decompression and line-by-line parsing of single- and multi-sample variant calls.
• Genomic VCF (gVCF): Non-variant block compression and genotype confidence filtering.
• 23andMe Raw Data (.txt): Direct translation of 4-column tab-delimited genotyping files (rsid, chromosome, position, genotype) into valid VCF records with reference allele lookup against local FASTA.
• FASTA Reference Validation (.fa, .fasta): Fast index-based (.fai) nucleotide sequence extraction to verify reference alleles against Human Genome assemblies.
• Automatic Build Detection: Inspects VCF contig headers, chromosome names, and coordinate mappings to determine whether data matches GRCh37 (hg19) or GRCh38 (hg38), with manual override available in the GUI.

VFDistiller bridges offline reference datasets and online scientific APIs:

1. gnomAD LightDB (Offline SQLite): Compressed local database containing exome and genome population allele frequencies across major global ancestries. Lookups execute in sub-millisecond time.
2. INFO Field Recycling: Automatically recognizes and preserves existing annotations already present in input VCF INFO tags (e.g. SnpEff annotations, ANNOVAR tags, CADD scores).
3. Async Ensembl VEP: Asynchronous REST batch queries via aiohttp to retrieve transcript consequences, HGVS notations, and protein alterations without blocking the user interface.
4. MyVariant.info & NCBI ClinVar: Enriches variants with clinical significance classifications (ClinSig), review status, and disease phenotype associations.
5. AlphaGenome API (Optional): Optional connector to Google DeepMind's genomic AI predictions using user-supplied API keys.

Easily narrow millions of raw sequencing variants down to a manageable cohort of candidates:

• Allele Frequency Thresholding: Filter out common polymorphisms (e.g., AF < 0.007 or custom thresholds) across global or ancestry-specific populations.
• Read Depth & Genotype Quality: Sample-level filtering on minimum read coverage (DP >= 20) and genotype quality (GQ >= 30).
• Pathogenicity Highlighting: Instant visual highlighting of variants exceeding CADD thresholds (e.g. CADD > 22.0) or annotated as Pathogenic / Likely Pathogenic in ClinVar.
• Gene Whitelists & Disease Panels: Load custom gene symbol lists (e.g. ACMG Secondary Findings v3.2, cardiomyopathy panel) to restrict the view to genes of interest.
• Filter Status Gate: Toggle between viewing all variants or only those marked as FILTER=PASS.

• Modern ttkbootstrap Interface: Dark and light theme support, responsive tabular view with sortable columns, and real-time progress indicators.
• System Tray Integration: Built via pystray with graceful degradation; allows long-running variant annotation batches to run quietly in the background.
• Web Companion PWA (web_companion/): Lightweight Progressive Web App interface with web manifest and vector assets, enabling local network browser previews.
• Bilingual Support: Complete German and English localization loaded seamlessly from locales/translations.json.

Export your filtered variant sets in the exact format required for your downstream workflows:

• Annotated VCF 4.2: Outputs standardized VCF files containing added annotations in the INFO column, with full preservation of sample-level FORMAT fields (DP, GQ, AD, PL).
• Excel Spreadsheet (.xlsx): Formatted multi-tab workbook with auto-fitted column widths, conditional formatting, and clickable hyperlinks to NCBI, ClinVar, and Ensembl.
• Standard CSV / TSV: Clean, delimited text files ready for R, pandas, or custom bioinformatics pipelines.
• PDF Research Summary: Formatted printable summary report via ReportLab, detailing pipeline parameters, quality metrics, and candidate variant tables.

For high-throughput variant processing, optional C-compiled Cython modules deliver up to 5x overall pipeline speedup (e.g., 50,000 variants processed in 3 minutes instead of 15 minutes):

If Cython or a C compiler is unavailable, VFDistiller automatically and transparently falls back to optimized pure-Python implementations with 100% functional equivalence.

• Python 3.10+
• Supported OS: Windows 10/11 (primary target), Linux and macOS (experimental / source)

VFDistiller is distributed exclusively via GitHub under AGPL-3.0-or-later.

# 1. Clone the repository
git clone https://github.com/biotec-line/VFDistiller.git
cd VFDistiller

# 2. Install dependencies
pip install -r requirements.txt

# 3. Optional: Compile Cython acceleration (requires MSVC on Windows or gcc/clang)
cd cython_hotpath
python setup.py build_ext --inplace
cd ..

# 4. Launch the application
python Variant_Fusion_pro_V17.py

On Windows workstations, you can simply run START.bat or build the standalone executable via build_exe.bat.

• Settings: On first launch, variant_fusion_settings.json is generated from variant_fusion_settings.json.example.
• gnomAD LightDB: To populate the local offline allele frequency database, launch the interactive setup in the GUI or run:

  python "Get gnomAD DB light.py"

• FASTA References: Reference genomes (GRCh37 / GRCh38) can be placed in the root directory; on first run, .fai index files are generated automatically.

The repository enforces deterministic quality gates across all releases:

# Run complete test suite (216 passed, 10 subtests)
python -m pytest

# Run fast quiet regression suite
python -m pytest -q

# Run platform smoke test
python tests/source_platform_smoke.py

# Run bytecode compilation verification
python -m compileall -q .

# Run linter checks
ruff check .

VFDistiller is committed to complete open-source transparency. All runtime and development dependencies are audited and documented in THIRD_PARTY_LICENSES.md and THIRD_PARTY_LICENSES.txt:

• Zero-Copyleft on Genomic Datasets: User sequencing files, converted VCFs, and generated reports remain 100% the intellectual property of the operator and are exempt from copyleft claims.
• pystray (LGPL-3.0-or-later): The system tray integration links dynamically to unmodified upstream wheels in compliance with LGPLv3 Section 4. Users have the right to inspect, modify, and replace this module.
• Unprivileged Runtime (RunAsInvoker): The application runs entirely within user space without administrative elevation.

Security and genetic privacy are fundamental to VFDistiller's architecture:

• Local-First & Zero-Egress: Sensitive patient and variant files never leave your device.
• Automated Log Redaction: Persistent logs generated by MultiSinkLogger automatically scrub chromosome positions, rsIDs, and patient filepaths via redact_for_logfile.
• 48-Hour Security Response SLA: All reported security vulnerabilities receive an initial response within 48 hours and a triage assessment within 5 business days.
• Private Reporting: Report vulnerabilities via GitHub Security Advisories or email security@biotec-line.org / security@open-bricks.org. For full details, see SECURITY.md.

Distribution Change & Regulatory Boundary: VFDistiller was withdrawn from the Microsoft Store on 2026-04-12 and is distributed exclusively via GitHub as an open-source research and educational tool under AGPL-3.0-or-later.

Why: Under the European In-Vitro Diagnostic Medical Device Regulation (IVDR (EU) 2017/746), distribution via a consumer marketplace combined with genomics tooling risked inadvertent classification as in-vitro diagnostic medical device software (IVD-MDSW). The project lead chose to withdraw the Store listing entirely to maintain a clean Research Use Only (RUO) boundary.

• NOT an IVD Medical Device: The software is not approved by the BfArM or any notified body and is not CE-marked.
• NOT for Clinical Diagnoses: Must not be used to make diagnostic, prognostic, or therapeutic decisions.
• Educational and Research Scope: Intended solely for bioinformatics research, laboratory workflow benchmarking, and academic teaching.

AGPL-3.0-or-later (GNU Affero General Public License, version 3 or any later version). Free of charge. Forever.

• Copyright (C) 2026 Lukas Geiger (c/o Um:bruch Think Tank)
• Maintained under the biotec-line bioinformatics organization within the open-bricks ecosystem.
• Full license terms: LICENSE • Legal disclaimer: NOTICE • Level 1 SBOM: THIRD_PARTY_LICENSES.md
• Unpaid open-source donation (§§ 516 ff. BGB). Statutory liability is limited to intent and gross negligence in accordance with § 521 BGB and §§ 15–17 AGPL-3.0. Binding 48h Security Response SLA under INV-SLA-10. Use at own risk.