afquery 0.2.0__tar.gz → 0.2.2__tar.gz

afquery-0.2.2/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim AS builder
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends build-essential && \
+    rm -rf /var/lib/apt/lists/*
+
+ARG VERSION
+RUN pip install --no-cache-dir afquery==${VERSION}
+
+
+FROM python:3.11-slim
+
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin/afquery /usr/local/bin/afquery
+
+ENTRYPOINT ["afquery"]

{afquery-0.2.0 → afquery-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: afquery
-Version: 0.2.0
+Version: 0.2.2
 Summary: Genomic allele frequency query engine with bitmap-encoded genotypes
 License: MIT
 License-File: LICENSE
@@ -20,7 +20,10 @@ Provides-Extra: dev
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: matplotlib>=3.8; extra == 'docs'
+Requires-Dist: mike>=2.0; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs-print-site-plugin>=2.6.1; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
 Description-Content-Type: text/markdown

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/benchmarking.md

@@ -76,6 +76,7 @@ If `point_query_cold_ms` exceeds 500 ms, check disk I/O performance. If `point_q
 ## Synthetic Data Generation
 
 The benchmark generates:
+
 - `N` samples with random sex (50/50) and random technology assignment
 - `M` variants per chromosome with uniformly random positions
 - Random genotypes with configurable carrier rates
@@ -168,3 +169,10 @@ EOF
 ```
 
 A regression of >20% on `point_query_cold_ms` warrants investigation.
+
+---
+
+## Next Steps
+
+- [Performance Tuning](performance.md) — tune threads and memory to improve build and query speed
+- [Debugging Results](debugging-results.md) — diagnose unexpected AN=0 or surprising AF values

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/debugging-results.md

@@ -54,6 +54,9 @@ To inspect a site with high N_FAIL, query with `--format json` to see all fields
 afquery query --db ./db/ --locus chr1:12345678 --format json
 ```
 
+!!! tip "Identify failing samples"
+    Use `afquery variant-info --db ./db/ --locus chr1:12345678` to see exactly which samples have FAIL status and their metadata (technology, phenotype codes). This helps determine if failures cluster in a specific technology or sample subset. See [Variant Info](../guides/variant-info.md).
+
 If N_FAIL is consistently high across many sites, check the variant calling pipeline and FILTER field settings in your VCFs.
 
 ---
@@ -130,7 +133,7 @@ conn.close()
 
 ---
 
-## Related Pages
+## Next Steps
 
 - [Understanding Output](../getting-started/understanding-output.md) — what each field means
 - [FAQ](../faq.md) — common questions and answers

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/filter-pass-tracking.md

@@ -7,10 +7,12 @@ AFQuery tracks variants that are called but fail quality filters (`FILTER≠PASS
 ## Background: VCF FILTER Field
 
 In VCF format, the FILTER column indicates whether a variant call passed quality filters:
+
 - `PASS` or `.` (missing) — the variant passed all filters
 - Any other value (e.g., `LowQual`, `VQSRTrancheSNP99.90to100.00`) — the variant failed one or more filters
 
 AFQuery default behavior:
+
 - **PASS-only**: only `FILTER=PASS` variants are counted in AC/AN. This is always enforced.
 
 ---
@@ -22,6 +24,7 @@ AFQuery stores a third bitmap per variant alongside `het_bitmap` and `hom_bitmap
 - **`fail_bitmap`** — bit set for each sample that has a non-ref genotype (AC>0) AND `FILTER≠PASS`
 
 This means:
+
 - A sample in `fail_bitmap` was genotyped with the alt allele but the call failed QC
 - Such samples are **not** counted in AC/AN (they don't affect AF)
 - Their count is exposed as `N_FAIL`
@@ -66,6 +69,16 @@ for r in results:
 
 `N_FAIL` is always an `int` (default `0`).
 
+### Identifying specific FAIL samples
+
+To see which individual samples have FAIL status at a position, use `variant-info`:
+
+```bash
+afquery variant-info --db ./db/ --locus chr1:925952
+```
+
+Each carrier row shows its `filter` column as `PASS` or `FAIL`, along with sample metadata (technology, phenotype codes). This helps pinpoint whether failures cluster in a specific technology or sample group. See [Variant Info](../guides/variant-info.md) for full options.
+
 ---
 
 ## VCF Annotation
@@ -82,19 +95,14 @@ afquery annotate --db ./db/ --input variants.vcf --output annotated.vcf
 
 ---
 
-## Schema Version Compatibility
-
-The `fail_bitmap` and `N_FAIL` tracking requires schema version 2.0 or later. Databases created with older versions of AFQuery do not contain `fail_bitmap` data.
-
-| Database schema | N_FAIL behavior |
-|----------------|-----------------|
-| ≥ 2.0 | `N_FAIL` is always an integer (0 or more) |
-| < 2.0 (legacy) | `N_FAIL` is `None` in Python API results |
+## PASS-Only Enforcement
 
-To upgrade a legacy database, rebuild it with `afquery create-db`. There is no in-place migration.
+AF reflects the quality-filtered allele frequency — the frequency of the alt allele among high-quality calls. This is appropriate for most clinical and research use cases. PASS-only ingestion is always enforced.
 
 ---
 
-## PASS-Only Enforcement
+## Next Steps
 
-AF reflects the quality-filtered allele frequency — the frequency of the alt allele among high-quality calls. This is appropriate for most clinical and research use cases. PASS-only ingestion is always enforced.
+- [Understanding Output](../getting-started/understanding-output.md) — interpreting N_FAIL in query and annotate results
+- [ACMG Criteria](../use-cases/acmg-use-cases.md) — using N_FAIL to assess site quality before applying BA1/PM2
+- [Debugging Results](debugging-results.md) — diagnosing unexpectedly high N_FAIL values

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/multi-cohort-strategies.md

@@ -152,7 +152,7 @@ afquery annotate --db /databases/institutional/cardiology/ \
 
 ---
 
-## Related Pages
+## Next Steps
 
 - [Create a Database](../guides/create-database.md) — database creation options
 - [Update a Database](../guides/update-database.md) — adding samples to an existing database

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/performance.md

@@ -107,7 +107,7 @@ graph TD
 
 ### Sub-100 ms Point Queries
 
-Query performance for a typical 50K-sample cohort:
+Query performance for a typical 50K-sample cohort (see [Benchmarking](benchmarking.md) to measure these on your own database):
 
 | Query type | Cold (first call) | Warm (cached) |
 |------------|-------------------|---------------|
@@ -168,6 +168,7 @@ Actual disk usage depends on variant density and carrier rates. Rare variants (l
 ## Memory at Query Time
 
 Query memory is very low:
+
 - **Bitmap operations**: only the relevant bitmaps are loaded from Parquet (~64 KB per variant at 50K samples)
 - **No full chromosome load**: DuckDB reads only the specific rows matching the query position
 - **Capture index**: one small interval tree per WES technology loaded at `Database.__init__`
@@ -182,4 +183,12 @@ Enable verbose output to see per-step timings (available on `annotate`, `dump`,
 
 ```bash
 afquery annotate --db ./db/ --input variants.vcf --output annotated.vcf --verbose
-```
+```
+
+---
+
+## Next Steps
+
+- [Benchmarking](benchmarking.md) — measure and track query performance on your database
+- [Create a Database](../guides/create-database.md) — build options including `--build-threads` and `--build-memory`
+- [Pipeline Integration](pipeline-integration.md) — thread configuration in Nextflow and Snakemake workflows

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/pipeline-integration.md

@@ -177,7 +177,7 @@ afquery_db: /shared/databases/afquery/cohort_v2
 
 ---
 
-## Related Pages
+## Next Steps
 
 - [Annotate a VCF](../guides/annotate-vcf.md) — full annotation CLI reference
 - [Performance Tuning](performance.md) — thread and memory optimization

{afquery-0.2.0 → afquery-0.2.2}/docs/advanced/ploidy-and-sex-chroms.md

@@ -107,6 +107,9 @@ For every query result, the following identity holds:
 
 This can be used to validate results. N_HOM_REF is the number of eligible samples that are homozygous reference (i.e., do not carry the alt allele and passed quality filters).
 
+!!! note "Mutual exclusivity"
+    N_HET, N_HOM_ALT, N_HOM_REF, and N_FAIL are mutually exclusive. A sample with a non-ref allele but FILTER≠PASS is counted in N_FAIL only — it does not appear in N_HET or N_HOM_ALT. Likewise, N_HOM_REF counts only PASS-filtered samples.
+
 ### chrX non-PAR
 
 - A male with GT=`1` contributes AC=1, AN=1
@@ -114,6 +117,7 @@ This can be used to validate results. N_HOM_REF is the number of eligible sample
 - A female with GT=`1/1` contributes AC=2, AN=2
 
 N_HET and N_HOM_ALT are counted per sample (not per allele):
+
 - Males at chrX non-PAR (haploid positions) are counted in **N_HOM_ALT** when GT=1, because all alleles at that position are alternate. N_HET is reserved for diploid positions where both reference and alternate alleles are present.
 - Females at chrX with GT=`0/1` are counted in N_HET; with GT=`1/1` in N_HOM_ALT.
 
@@ -139,11 +143,21 @@ chrM is haploid for all samples (both sexes contribute AN=1):
 ## Sex Filter Interaction
 
 When `--sex female` is used on chrX (non-PAR), AN is purely diploid:
+
 - Each eligible female contributes AN=2
 - AF is computed over a fully diploid denominator
 
 When `--sex male` is used on chrX (non-PAR), AN is purely haploid:
+
 - Each eligible male contributes AN=1
 - AF reflects the observed allele frequency in haploid male calls
 
 This makes it straightforward to compare X-linked variant frequencies between sexes without manual ploidy adjustment.
+
+---
+
+## Next Steps
+
+- [Sex-Specific AF](../use-cases/sex-specific-af.md) — X-linked variant analysis using sex-stratified queries
+- [Key Concepts](../getting-started/concepts.md) — AC/AN/AF overview and the ploidy table
+- [Sample Filtering](../guides/sample-filtering.md) — `--sex` filter syntax

{afquery-0.2.0 → afquery-0.2.2}/docs/faq.md

@@ -88,7 +88,7 @@ See [Updating sample metadata](guides/update-database.md#update-sample-metadata)
 
 AFQuery has been tested with up to 50,000 samples. Bitmap operations remain fast at this scale because Roaring Bitmaps are highly compressed for sparse data. At 50K samples, a typical variant bitmap is ~64 KB.
 
-For cohorts larger than 50K, performance should remain sub-second for point queries, but build-phase memory requirements scale with cohort size. See [Performance Tuning](advanced/performance.md).
+For cohorts larger than 50K, performance should remain sub-second for point queries, but build-phase memory requirements scale with cohort size. See [Performance Tuning](advanced/performance.md) and [Benchmarking](advanced/benchmarking.md) to measure latency on your own database.
 
 ---
 
@@ -135,6 +135,7 @@ print(db.get_all_phenotypes())
 ## Does filtering by technology affect WGS samples?
 
 WGS samples are always covered at every position (no BED file). Technology filters work by sample membership, not coverage:
+
 - `--tech wgs` restricts to samples with `tech=wgs` in the manifest
 - WES samples at positions outside their capture BED are excluded by coverage, not by the tech filter
 
@@ -177,16 +178,15 @@ Use `afquery info --db ./db/` to list all registered codes before running querie
 
 ### What if AN is very low?
 
-Low AN means the allele frequency estimate is unreliable. For example: AC=1, AN=4, AF=0.25 — this is not a robust 25% frequency estimate.
+Low AN means the allele frequency estimate is unreliable.
 
 **Rules of thumb:**
+
 - **AN ≥ 100**: bare minimum for any interpretation
 - **AN ≥ 500**: necessary for rare variant filtering
 - **AN ≥ 1000**: required for clinical variant interpretation
 
-For detailed per-criterion AN thresholds, see [ACMG Criteria — AN Threshold Guidance](use-cases/acmg-use-cases.md#an-threshold-guidance).
-
-Always check `AFQUERY_AN` alongside `AFQUERY_AF` in downstream analyses. A variant with high AF but very low AN should be treated with skepticism.
+For per-criterion thresholds see [ACMG Criteria — AN Threshold Guidance](use-cases/acmg-use-cases.md#an-threshold-guidance). If AN=0 unexpectedly, see [Debugging Results](advanced/debugging-results.md#1-unexpected-an0) for a step-by-step diagnostic checklist.
 
 ---
 
@@ -195,6 +195,7 @@ Always check `AFQUERY_AN` alongside `AFQUERY_AF` in downstream analyses. A varia
 If your cohort is a mix of ancestries, the AF reflects a weighted average across all ancestries. A variant at AF=0.001 globally may be at AF=0.01 in a subpopulation.
 
 **Mitigation:**
+
 - Tag samples by ancestry or population in `phenotype_codes`
 - Use stratified queries: `afquery query --phenotype AFR` for African samples, `--phenotype EUR` for European samples, etc.
 - Compare AF across subgroups to detect ancestry-specific signals
@@ -208,7 +209,7 @@ Without stratification, rare variant interpretation in mixed cohorts can be misl
 AFQuery is purpose-built for fast subcohort AF computation and is not a general-purpose genomic database:
 
 - **Not a joint genotyper**: AFQuery does not perform joint genotyping. Input VCFs should be individually called before ingestion.
-- **Not a variant database**: AFQuery stores only genotype-level summaries (bitmaps). Individual sample genotypes cannot be retrieved from the database.
+- **Not a genotype store**: AFQuery stores genotype summaries as bitmaps, not raw FORMAT fields. Use `variant-info` to list carriers and their genotype class (het/hom) at a specific position; for full per-sample VCF fields (GQ, DP, AD, etc.), consult the source VCFs.
 - **No statistical genetics**: AFQuery does not compute Hardy-Weinberg equilibrium, population stratification, or other statistical genetics metrics.
 - **Batch queries**: The `--from-file` batch mode supports variants across multiple chromosomes in a single call. Point queries (`--locus`) and region queries (`--region`) target a single position or range; for multi-position multi-chromosome lookups, use `--from-file`.
 - **Cohort size limit**: Performance at >100K samples has not been validated. Memory requirements for the build phase scale with cohort size.
@@ -231,3 +232,4 @@ ManifestError: BED file not found for technology '<tech>': '<path>'
   passed to `--bed-dir`.
 - If the samples are genuinely whole-genome (no capture), change `tech_name` to `WGS`
   in the manifest (no BED file required for WGS).
+

{afquery-0.2.0 → afquery-0.2.2}/docs/getting-started/concepts.md

@@ -167,6 +167,7 @@ WGS samples are always eligible (no BED file needed).
 ## The Manifest
 
 The manifest is a TSV file that drives database creation. It maps each sample to its:
+
 - VCF file path
 - Sex (`male` / `female`)
 - Sequencing technology
@@ -206,6 +207,7 @@ AN is computed only over eligible samples, so AF naturally reflects the chosen s
 Multiple labels per sample are supported. There is no validation or controlled vocabulary — you define the ontology for your cohort.
 
 When planning phenotype codes, consider:
+
 - Codes can be updated after ingestion using `afquery update-db --update-sample` (see [Updating sample metadata](../guides/update-database.md#update-sample-metadata))
 - Codes are case-sensitive: `E11.9` ≠ `e11.9`
 - Trailing or leading spaces cause silent mismatch (always use `E11.9,I10`, never `E11.9, I10`)
@@ -213,3 +215,11 @@ When planning phenotype codes, consider:
 ---
 
 PASS-only ingestion is always enforced. See [FILTER=PASS Tracking](../advanced/filter-pass-tracking.md) for details.
+
+---
+
+## Next Steps
+
+- [5-Min Quickstart](quickstart.md) — build your first database and run queries
+- [Sample Filtering](../guides/sample-filtering.md) — phenotype, sex, and technology filter syntax
+- [Ploidy & Special Chromosomes](../advanced/ploidy-and-sex-chroms.md) — PAR regions and ploidy rules in detail

{afquery-0.2.0 → afquery-0.2.2}/docs/getting-started/installation.md

@@ -82,3 +82,11 @@ If you want to build or serve the documentation locally:
 pip install -e ".[docs]"
 mkdocs serve
 ```
+
+---
+
+## Next Steps
+
+- [VCF Preprocessing](preprocessing.md) — normalize and prepare VCFs before ingestion
+- [5-Min Quickstart](quickstart.md) — build your first database and run queries
+- [Key Concepts](concepts.md) — understand the bitmap index, manifest, and metadata model

afquery-0.2.2/docs/getting-started/motivation.md

@@ -0,0 +1,108 @@
+# Why Local Allele Frequencies Matter
+
+## Clinical Decisions Depend on Accurate AF
+
+Allele frequency (AF) is one of the strongest lines of evidence in clinical variant classification. Under the [ACMG/AMP framework](../use-cases/acmg-use-cases.md), AF thresholds directly determine whether a variant is classified as benign (BA1: AF > 5%), supporting-pathogenic (PM2: absent or extremely rare), or strongly pathogenic through case enrichment (PS4). A misestimated AF can flip a classification — and with it, a clinical decision.
+
+Yet AF is not an intrinsic property of a variant — it depends on the population in which it is measured. The same variant can be common in one cohort and absent in another. When the reference population does not match the patient's background, variant classification becomes unreliable.
+
+This page describes four methodological gaps in current allele frequency workflows that AFQuery was designed to address.
+
+---
+
+## Gap 1 — Global Databases Miss Population-Specific Signals
+
+Population databases like gnomAD are invaluable for identifying common variants, but they aggregate data from broad, predominantly European-ancestry populations. When the patient's ancestry differs from the reference, AF estimates diverge — sometimes dramatically.
+
+!!! warning "Real-world impact"
+    Turkish breast cancer variants showed up to **354-fold higher** allele frequencies in a local variome compared to gnomAD, leading to **6.7% of VUS being reclassified** to likely benign when population-matched data were used [(Agaoglu et al., 2024)](https://pubmed.ncbi.nlm.nih.gov/38308423/). In Taiwanese inherited retinal degeneration, using a local biobank as ancestry-matched controls for PS4 evidence **upgraded 2 variants from LP to P and 6 from VUS to LP** [(Huang et al., 2026)](https://pubmed.ncbi.nlm.nih.gov/41692763/).
+
+The problem extends beyond rare ancestries. In a UK arrhythmia clinic, **32.2% of VUS were reclassified** upon re-evaluation with updated frequency data [(Young et al., 2024)](https://pubmed.ncbi.nlm.nih.gov/38218330/). Analysis of 469,803 UK Biobank exomes found that **12.4% of rare LDLR VUS met criteria for reclassification** to likely pathogenic when biobank-derived odds ratios were calibrated to ACMG PS4 strength levels [(Bhat et al., 2025)](https://pubmed.ncbi.nlm.nih.gov/40639380/).
+
+These are not edge cases. Every cohort with a population composition that differs from gnomAD — geographically, clinically, or by ascertainment — may produce misleading AF when compared only against global references.
+
+| Study | Population | Key Finding |
+|-------|-----------|-------------|
+| [Agaoglu et al. 2024](https://pubmed.ncbi.nlm.nih.gov/38308423/) | Turkish breast cancer | Up to 354× AF difference vs gnomAD; 6.7% VUS reclassified |
+| [Huang et al. 2026](https://pubmed.ncbi.nlm.nih.gov/41692763/) | Taiwanese IRD | 8 variants reclassified using local biobank PS4 evidence |
+| [Young et al. 2024](https://pubmed.ncbi.nlm.nih.gov/38218330/) | UK arrhythmia clinic | 32.2% of VUS reclassified on re-evaluation |
+| [Bhat et al. 2025](https://pubmed.ncbi.nlm.nih.gov/40639380/) | UK Biobank (470K) | 12.4% rare LDLR VUS reclassifiable via biobank OR |
+| [Kotan 2022](https://pubmed.ncbi.nlm.nih.gov/35438269/) | Turkish endocrinology | Population-matched variomes correlate best geographically |
+| [Soussi 2022](https://pubmed.ncbi.nlm.nih.gov/35802772/) | Multi-ethnic (TP53) | 21 benign TP53 SNPs missed in European-biased databases |
+| [Dawood et al. 2024](https://pubmed.ncbi.nlm.nih.gov/39627863/) | Multi-ethnic (MAVE) | AF evidence codes have inequitable impact on non-Europeans (p = 7.47×10⁻⁶) |
+
+---
+
+## Gap 2 — Mixed Sequencing Technologies Inflate the Denominator
+
+Modern cohorts routinely combine samples sequenced with different technologies — WGS, multiple WES capture kits, and targeted gene panels. Even different versions of the same WES kit can differ by hundreds of base pairs at capture boundaries.
+
+This matters because **allele number (AN) must be computed per position, not per cohort**. A sample whose capture kit does not cover the queried position has no genotype there: it contributes nothing to AN. If it is naively counted, the denominator is inflated and the resulting AF is artificially deflated.
+
+The figure below illustrates the problem with a minimal example: two versions of the same WES capture kit (V1, n = 120 and V2, n = 80) sequencing a schematic gene with eight exons.
+
+![Mixed sequencing technologies: coverage at different query positions](../assets/img/gap2_mixed_technologies.png)
+
+**Position A** (Exon 5) falls within the capture region of both kit versions. All 200 samples have a genotype at this position, so AN = 200 × 2 = **400**. Both kits contribute to the count, and the resulting AF is correct.
+
+**Position B** (Exon 7) is covered only by WES_KIT_V2. The 120 samples sequenced with V1 have no data at this position. The correct AN is 80 × 2 = **160** — but a naïve calculation that ignores capture boundaries would use 200 × 2 = 400, **underestimating AF by more than half**. A variant with AC = 5 would appear to have AF = 1.25% (5/400) instead of the true 3.13% (5/160) — enough to cross PM2 filtering thresholds and mislead clinical interpretation.
+
+This is not hypothetical. In the Alzheimer's Disease Sequencing Project, hidden variant-level batch effects between two exome capture kits **significantly impacted disease-associated variant identification**, with a subset of top risk variants originating exclusively from one kit [(Wickland et al., 2021)](https://pubmed.ncbi.nlm.nih.gov/33861770/). A population-based WES study found that separating samples by capture protocol yielded **40.9% more high-quality variants** than pooling them [(Carson et al., 2014)](https://pubmed.ncbi.nlm.nih.gov/24884706/).
+
+No general-purpose VCF tool automates per-position, per-technology AN computation across dozens of BED files.
+
+---
+
+## Gap 3 — Static Tools Require Reprocessing
+
+Standard VCF tools — bcftools, VCFtools, GATK — operate on static VCF files. Computing AF over a different sample subset requires:
+
+1. Selecting samples by external metadata
+2. Subsetting the VCF
+3. Running AF computation
+4. Repeating for each new subset
+
+This is adequate for one-time analyses but prohibitive for interactive clinical variant interpretation, where a geneticist may need AF across dozens of subsets in a single session: by sex, by phenotype, by technology, by combinations thereof.
+
+For a cohort of 10,000 samples with 5 million variants, reprocessing takes minutes per subset. At 20 subsets per clinical session, the wall time is measured in hours — turning what should be an interactive workflow into a batch job.
+
+---
+
+## Gap 4 — No Metadata-Aware Filtering
+
+Computing AF over "female WGS samples tagged with phenotype E11.9, excluding those also tagged I42" requires orchestrating multiple tools: extract sample IDs from a metadata database, subset the VCF, compute statistics. This multi-step process is error-prone (sample ID mismatches, off-by-one in subsetting) and precludes real-time exploratory analysis.
+
+The lack of integrated metadata filtering is particularly problematic for:
+
+- **Pseudo-control analysis** — computing AF in all samples *except* those with a specific disease to assess case enrichment (ACMG PS4)
+- **Sex-stratified AF** — essential for X-linked variant interpretation, where males and females have different ploidy
+- **Technology-stratified QC** — identifying variants that appear only in one sequencing technology, suggesting artifacts rather than true variation
+
+---
+
+## How AFQuery Addresses These Gaps
+
+AFQuery introduces a pre-indexed database architecture that separates the slow step (building the genotype index from VCFs) from the fast step (querying AF on arbitrary subgroups).
+
+The key data structure is the [Roaring Bitmap](https://roaringbitmap.org/) — a compressed bitset that records, for each variant, which samples carry the alternate allele. At query time, computing AC/AN/AF requires only:
+
+1. Loading the variant's carrier bitmap from Parquet storage
+2. Intersecting with the bitmap of eligible samples (determined by sex, phenotype, and capture filters)
+3. Counting set bits (popcount)
+
+This reduces each query to microsecond-scale bitmap operations, achieving sub-100 ms end-to-end latency including Parquet I/O — regardless of cohort size.
+
+| Gap | Existing tools | AFQuery |
+|-----|---------------|---------|
+| Population-specific AF | Compare against gnomAD; build separate databases per population | Compute AF on any phenotype-defined subgroup at query time |
+| Mixed technologies | Manual BED intersection or ignore the problem | Automatic per-position, per-technology AN via capture index |
+| Reprocessing | Re-scan VCF per subset (minutes) | Bitmap intersection (milliseconds) |
+| Metadata filtering | Multi-step: extract IDs → subset VCF → compute | Single query with `--phenotype`, `--sex`, `--tech` flags |
+
+---
+
+## Next Steps
+
+- [Installation](installation.md) — get started
+- [Key Concepts](concepts.md) — how bitmaps, Parquet, and metadata filtering work together
+- [ACMG Criteria](../use-cases/acmg-use-cases.md) — applying local AF to BA1, PM2, and PS4

{afquery-0.2.0 → afquery-0.2.2}/docs/getting-started/preprocessing.md

@@ -33,3 +33,11 @@ Male samples should have haploid genotype calls at chrX non-PAR regions (GT=`1`,
 - **Non-PASS genotypes**: Masking them as missing ensures that low-quality calls do not inflate AC. AFQuery tracks these as N_FAIL.
 - **Homozygous reference calls**: Removing ref/ref genotypes reduces file size and speeds ingestion; they contribute AC=0 and are not needed
 - **INFO fields**: Stripping INFO reduces file size and speeds ingestion. Additionally, malformed or non-standard INFO fields produced by some variant callers can break downstream parsing; stripping them pre-emptively prevents these errors.
+
+---
+
+## Next Steps
+
+- [Manifest Format](../guides/manifest-format.md) — describe your cohort samples for ingestion
+- [Create a Database](../guides/create-database.md) — build the AFQuery database from normalized VCFs
+- [5-Min Quickstart](quickstart.md) — end-to-end tutorial from manifest to first query

{afquery-0.2.0 → afquery-0.2.2}/docs/getting-started/quickstart.md

@@ -2,6 +2,9 @@
 
 This tutorial walks through building a small AFQuery database and running your first queries. It takes about 5 minutes.
 
+!!! tip "New to AFQuery?"
+    If you want to understand how bitmaps, Parquet storage, and metadata filtering work together before diving in, read [Key Concepts](concepts.md) first. Otherwise, follow along — you can always come back to the theory later.
+
 !!! tip "Normalize your VCFs first"
     AFQuery works best with normalized, left-aligned VCFs with ploidy-corrected sex chromosome calls. See [VCF Preprocessing](preprocessing.md) for a reference normalization pipeline using bcftools.
 
@@ -19,6 +22,7 @@ SAMPLE_003	/data/vcfs/sample003.vcf.gz	female	wes_v1	I10
 ```
 
 Fields:
+
 - `sample_name`: unique identifier
 - `vcf_path`: path to single-sample VCF (plain or `.gz`)
 - `sex`: `male` or `female`
@@ -79,12 +83,26 @@ afquery query \
   --phenotype E11.9
 ```
 
+See [Sample Filtering](../guides/sample-filtering.md) for the full include/exclude syntax.
+
 !!! note "Warnings for missing data"
     If a phenotype code, technology name, or chromosome is not found in the database, afquery prints a warning to stderr and returns empty results. Use `--no-warn` to suppress these warnings.
 
 ---
 
-## 5. Query a Region
+## 5. Inspect Carriers (optional)
+
+See which samples carry the variant you just queried:
+
+```bash
+afquery variant-info --db ./my_db/ --locus chr1:925952
+```
+
+This lists each carrier with their sex, technology, phenotype codes, genotype (het/hom), and FILTER status. See [Variant Info](../guides/variant-info.md) for details.
+
+---
+
+## 6. Query a Region
 
 ```bash
 afquery query \
@@ -94,7 +112,7 @@ afquery query \
 
 ---
 
-## 6. Annotate a VCF
+## 7. Annotate a VCF
 
 Given a VCF with variants you want to annotate:
 
@@ -106,7 +124,7 @@ afquery annotate \
   --threads 12
 ```
 
-The output VCF gains INFO fields:
+The output VCF gains INFO fields (see [Annotate a VCF](../guides/annotate-vcf.md) for parallelism options and downstream usage):
 
 | Field | Number | Description |
 |-------|--------|-------------|
@@ -118,4 +136,12 @@ The output VCF gains INFO fields:
 | `AFQUERY_N_HOM_REF` | A (per ALT) | Homozygous ref sample count |
 | `AFQUERY_N_FAIL` | 1 (per site) | Samples with FILTER≠PASS |
 
+---
+
+## Next Steps
 
+- [Key Concepts](concepts.md) — understand how bitmaps, Parquet, and metadata filtering work together
+- [Sample Filtering](../guides/sample-filtering.md) — full syntax for phenotype, sex, and technology filters
+- [Variant Info](../guides/variant-info.md) — list carriers of any variant with metadata
+- [Annotate a VCF](../guides/annotate-vcf.md) — annotation options, parallelism, and downstream usage
+- [ACMG Criteria](../use-cases/acmg-use-cases.md) — applying local AF to BA1, PM2, and PS4