genomatch 0.4.1

A Python toolkit for auditable harmonization, liftover, intersection, and projection of genetic variant tables and payloads.

Variant Table Toolkit

This toolkit harmonizes genetic variant data across common research formats and reference assemblies. It supports GRCh37, GRCh38, and T2T-CHM13v2.0, chromosomes 1-22, X, Y, and MT, common contig naming modes (ncbi, ucsc, plink), and biallelic variants, including SNPs and supported indels.

The common workflow rewrites chr / bp / a1 / a2 / snp fields in BFILE, PFILE, VCF, or summary-statistics inputs into a standardized variant key while adjusting the attached data, such as genotypes or summary-statistic columns, accordingly. Users request the target build, contig naming, and optional filtering or normalization flags; the pipeline handles build guessing in the source data, liftover between builds (if needed), allele swaps, reference-anchored allele ordering, sorting, and duplicate removal. The workflow is split into preparation and projection phases, so users can save and reuse a prepared variant set, or project only a user-defined subset of source variants.

Start here

1. Install the runtime using one of the supported paths in docs/install.md.
2. Download the reference FASTA/chain assets and configure config.yaml as described in docs/downloads.md.
3. Run through the worked example in docs/tutorial-1.md.

Documentation

• Workflow: the common prepare, combine, restrict, and project workflow.
• Summary statistics: metadata, SNP-only imports with --id-lookup, projection, and clean projection.
• Primitive tools and object model reference: lower-level tools plus .vmap, .vtable, payloads, source-row mapping, object metadata, and allele ordering.

Specifications

For exact schema and edge-case rules, see SPEC.md and the detailed specs in spec/. Wrapper behavior for prepare_variants.py, prepare_variants_sharded.py, and project_payload.py is defined in spec/workflow.md. Payload-application semantics are defined in spec/payload-application.md.