---

name: genomics-analysis description: "Use dense Hail MatrixTable workflows for VCF, PLINK, BGEN, variant/sample QC, multiallelic splitting, PCA, LD pruning, association tests, VEP/Nirvana-style annotation, and reference genome or locus/call handling." disable-model-invocation: true metadata: disco-role: operating license: MIT

Hail Genomics Analysis

Use this sub-skill when the task is about dense genotype data represented as a Hail MatrixTable: importing VCF, PLINK, or BGEN; reasoning about row, column, entry, and global axes; annotating samples or variants; filtering calls; running QC; splitting multiallelics; running PCA, LD pruning, relatedness, or association tests; applying VEP/Nirvana-style annotation; or diagnosing reference genome and contig issues.

Start Here

• Read references/matrixtable-workflows.md for import-to-native-cache, annotation, filtering, QC, split, PCA, association, VEP, and export recipes.
• Read references/genomic-methods.md for task-to-method selection across QC, PCA, association, relatedness, VEP/Nirvana boundaries, reference genomes, Locus, Call, and Pedigree.
• Read references/data-formats.md before choosing import/export options or interpreting locus, alleles, s, GT, DP, GQ, PL, info, dosage, and phenotype fields.
• Read references/troubleshooting.md when imports fail, references mismatch, split_multi_hts produces surprising INFO fields, VEP/Nirvana cannot run, association covariates fail, or collect/entries is too expensive.
• Use scripts/matrixtable_recipe_template.py --print-template to generate a safe, editable dense MatrixTable recipe skeleton.

Route Elsewhere

• Use ../variant-datasets/SKILL.md for sparse GVCF, VDS, combiner, hl.vds, local allele fields, or VDS-to-dense conversion work.
• Use ../tables-and-expressions/SKILL.md for generic Table pipelines, one-dimensional annotations, joins, aggregations, or expression-index errors that do not depend on MatrixTable axes.
• Use ../setup-and-backends/SKILL.md for hl.init, Spark/local/Batch backend choice, package installation, Java/JAR/runtime problems, cloud credentials, logs, and storage configuration.
• Use ../batch-and-cli/SKILL.md for hailctl, hailtop.batch, job DAGs, cloud Batch execution, Dataproc/HDInsight command families, or CLI automation.

Core Mental Model

A dense MatrixTable has four axes:

• row: variant/site fields, usually keyed by locus and alleles.
• column: sample fields, usually keyed by s.
• entry: per-row-by-column values such as GT, DP, GQ, AD, PL, GP, or dosage.
• global: metadata shared by the full dataset.

Choose axis-specific methods deliberately: annotate_rows, annotate_cols, annotate_entries, annotate_globals, filter_rows, filter_cols, filter_entries, select_rows, select_cols, select_entries, and select_globals. Avoid converting to entries() unless the task truly needs coordinate-form rows.

Verified API Anchors

The inspected package exposes these dense-genomics entry points: hl.import_vcf, hl.import_plink, hl.import_bgen, hl.export_vcf, hl.variant_qc, hl.sample_qc, hl.split_multi_hts, hl.linear_regression_rows, hl.logistic_regression_rows, hl.pca, hl.ld_prune, and hl.vep. Treat hl.vep and hl.nirvana as external annotation boundaries: Hail joins annotations back to row variants, but executables, configs, caches, schemas, and assembly compatibility are environment responsibilities.

Safe Defaults

• Import external genetics formats with an explicit reference_genome, inspect mt.describe(), then write or checkpoint native .mt before iterative analysis.
• Use hl.variant_qc and hl.sample_qc only when GT is a call entry field and row keys represent variant-like locus/alleles.
• Run hl.split_multi_hts before biallelic-only HWE-sensitive QC, LD pruning, many association workflows, and allele-specific annotations.
• Include an intercept explicitly in association covariates, usually covariates=[1, ...].
• Keep dense workflows separate from VDS workflows; do not force sparse GVCF data into dense MatrixTables unless the task explicitly calls for densification.