afquery 0.1.4__tar.gz → 0.2.0__tar.gz

afquery-0.2.0/.dockerignore

@@ -0,0 +1,11 @@
+.git
+.github
+docs/
+tests/
+recipes/
+*.md
+*.yml
+__pycache__
+*.pyc
+.venv
+dist/

{afquery-0.1.4 → afquery-0.2.0}/.github/workflows/release.yml

@@ -73,7 +73,61 @@ jobs:
           files: dist/*
           generate_release_notes: true
 
-  # ── 5. Bioconda PR (final releases only — no "rc" in tag) ────────────
+  # ── 5. Docker image → ghcr.io (final releases only) ─────────────────
+  docker:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    if: ${{ !contains(github.ref_name, 'rc') }}   # skip RC tags
+    permissions:
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Wait for PyPI propagation
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          echo "Waiting for afquery==${VERSION} on PyPI..."
+          for i in $(seq 1 12); do
+            STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
+              "https://pypi.org/pypi/afquery/${VERSION}/json")
+            if [ "$STATUS" = "200" ]; then
+              echo "Package available."
+              exit 0
+            fi
+            echo "Attempt ${i}/12: HTTP ${STATUS} — retrying in 30 s..."
+            sleep 30
+          done
+          echo "Not available after 6 min, proceeding anyway."
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          build-args: VERSION=${{ steps.version.outputs.version }}
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}
+            ghcr.io/${{ github.repository }}:latest
+
+  # ── 6. Bioconda PR (final releases only — no "rc" in tag) ────────────
   bioconda-pr:
     needs: publish-pypi
     runs-on: ubuntu-latest

{afquery-0.1.4 → afquery-0.2.0}/.gitignore

@@ -59,3 +59,4 @@ src/afquery/_version.py
 *.duckdb.wal
 *.parquet
 db/*
+site

afquery-0.2.0/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.11-slim
+
+ARG VERSION
+RUN pip install --no-cache-dir afquery==${VERSION}
+
+ENTRYPOINT ["afquery"]

afquery-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: afquery
+Version: 0.2.0
+Summary: Genomic allele frequency query engine with bitmap-encoded genotypes
+License: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: cyvcf2>=0.30
+Requires-Dist: duckdb>=0.10
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pyranges<0.2,>=0.1.2
+Requires-Dist: pyroaring>=0.4.8
+Requires-Dist: tqdm>=4.60
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# AFQuery
+
+[![CI](https://github.com/dlopez-bioinfo/afquery/actions/workflows/ci.yml/badge.svg)](https://github.com/dlopez-bioinfo/afquery/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/dlopez-bioinfo/afquery/graph/badge.svg)](https://codecov.io/gh/dlopez-bioinfo/afquery)
+[![Docs](https://img.shields.io/website?url=https%3A%2F%2Fdlopez-bioinfo.github.io%2Fafquery%2F&label=docs)](https://dlopez-bioinfo.github.io/afquery/)
+<br>
+[![PyPI](https://img.shields.io/pypi/v/afquery.svg?color=blue)](https://pypi.org/project/afquery/)
+[![Bioconda](https://img.shields.io/conda/vn/bioconda/afquery.svg)](https://anaconda.org/bioconda/afquery)
+[![Docker](https://img.shields.io/badge/ghcr.io-afquery-blue?logo=docker)](https://github.com/dlopez-bioinfo/afquery/pkgs/container/afquery)
+[![Python](https://img.shields.io/pypi/pyversions/afquery.svg)](https://pypi.org/project/afquery/)
+[![License: MIT](https://img.shields.io/github/license/dlopez-bioinfo/afquery)](https://github.com/dlopez-bioinfo/afquery/blob/master/LICENSE)
+
+AFQuery enables fast allele frequency queries on user-defined subsets of local genomic cohorts, without rescanning VCFs.
+
+AFQuery is a bitmap-indexed engine that efficiently recomputes AC/AN/AF for dynamically defined subcohorts (e.g., by phenotype, sex, or sequencing technology), a common requirement in ACMG/AMP variant classification. It stores per-variant genotype data as Roaring Bitmaps in Parquet files and resolves sample filters into bitmaps that can be intersected in microseconds, enabling sub-100 ms queries on large cohorts. The system accounts for ploidy in sex chromosomes, adjusts AN based on sequencing technology, supports incremental updates, and runs locally using a file-based setup (Parquet + SQLite) without requiring server or cloud infrastructure.
+
+[Full Documentation→](https://dlopez-bioinfo.github.io/afquery/)
+
+## When to use AFQuery
+
+- You need allele frequencies for phenotype or user-defined subcohorts  
+- You work with mixed sequencing technologies or capture kits versions (WGS, WES, targeted panels)  
+- You require fast, repeated queries without rescanning VCFs  
+- You want a local, reproducible workflow without cloud or cluster dependencies  
+
+## Features
+
+- **Dynamic subcohort queries (<100 ms)** — bitmap intersections at query time; no VCF re-scan required  
+- **Technology-aware** — avoids bias when mixing WGS, WES, and panels using different BED capture indexes  
+- **Ploidy-aware** — correct handling of sex chromosomes (PAR/non-PAR, chrX, chrY)  
+- **ACMG-compatible allele counting** — AC/AN/AF computed per standard definitions  
+- **Flexible metadata filtering** — arbitrary labels (ICD-10, HPO, custom fields) with inclusion/exclusion rules 
+- **Incremental updates** — add or remove samples and update metadata without rebuilding the database
+- **VCF annotation** — annotate variants using subcohort-specific frequencies
+- **FILTER/call quality tracking** — failed calls (FILTER!=PASS) tracked per variant and reported as N_FAIL
+- **Batch and region queries** — query a single locus, a genomic region, or a list of variants from a file
+- **Bulk CSV export** — export all variant frequencies with optional disaggregation by sex, technology, or phenotype
+- **Audit changelog** — all database operations logged with timestamps and operator notes
+- **Database validation** — integrity checks with scripted exit codes
+- **Portable and serverless** — file-based system, no infrastructure required
+
+## Performance
+
+- Query latency: <100 ms (tested up to 50,000 samples)  
+- Storage: ~2 bytes/sample/variant  
+- Scales to millions of variants per chromosome  
+
+## Comparison with Alternative Tools
+
+| | AFQuery | bcftools | GATK GenomicsDB | Hail |
+|---|---|---|---|---|
+| Technology-aware AN | **Yes** | No | No | No |
+| Metadata filtering | **Arbitrary labels** | No | No | Custom code |
+| Ploidy-aware sex chromosomes | **Yes** | Manual | No | Manual |
+| Dynamic subcohort queries | **Yes** | No | Limited | Requires code |
+| FILTER/call quality tracking | **Per variant** | Manual | No | Manual |
+| Incremental updates | **Yes** | No | **Yes** | No |
+| Infrastructure required | **None** | **None** | Java/server | Spark cluster |
+| Query latency (50K samples) | **<100 ms** | ~5 min | <1 min | 1–2 min |
+
+## Algorithm Overview
+
+AFQuery pre-indexes per-variant genotype data as [Roaring Bitmaps](https://roaringbitmap.org/) stored in Parquet files. Each variant row holds three bitmaps: heterozygous carriers, homozygous alt carriers, and samples with FILTER!=PASS. Sample metadata (sex, phenotype, technology) is pre-serialized as bitmaps in SQLite.
+
+At query time, the requested sample filter is resolved to a single candidate bitmap via bitmap intersections and differences — taking microseconds regardless of cohort size. For each variant, the candidate bitmap is intersected with the genotype bitmaps to compute AC/AN/AF. AN accounts for WES capture regions (via BED-indexed interval trees) and for ploidy on sex chromosomes (males are haploid on non-PAR chrX and chrY).
+
+## Input Requirements
+
+- VCF files: normalized and consistent with the selected genome build (GRCh37 or GRCh38)  
+- Sample metadata: must include sex, sequencing technology, and any fields used for filtering (e.g., phenotype)  
+- BED files (optional): define capture regions for each sequencing technology  
+
+## Quick Start
+
+Example workflow from raw VCFs to query, export, and annotation:
+
+```bash
+pip install afquery
+# Docker: see Installation docs for docker pull / run usage
+
+# Build the database
+afquery create-db --manifest samples.tsv --output-dir ./db/ --genome-build GRCh38
+
+# Inspect the database
+afquery info --db ./db/
+
+# Query a single position, filtered to a phenotype
+afquery query --db ./db/ --locus chr1:925952 --phenotype E11.9 --sex female
+
+# Query a genomic region
+afquery query --db ./db/ --region chr1:900000-1000000
+
+# Export BRCA1 variant frequencies to CSV
+afquery dump --db ./db/ --output all_variants.csv --chrom chr17 --start 43044292 --end 43170327
+
+# Annotate a VCF with cohort frequencies
+afquery annotate --db ./db/ --input patient.vcf --output annotated.vcf --threads 12
+
+# Add new samples to an existing database
+afquery update-db --db ./db/ --add-samples new_samples.tsv
+```
+
+## Documentation
+
+- [Full Documentation](https://dlopez-bioinfo.github.io/afquery/)
+- [Getting Started](https://dlopez-bioinfo.github.io/afquery/getting-started/)
+- [Why local allele frequencies?](https://dlopez-bioinfo.github.io/afquery/getting-started/motivation/)
+- [CLI Reference](https://dlopez-bioinfo.github.io/afquery/reference/cli/)
+
+## Citation
+
+If you use AFQuery, please cite:
+
+> AFQuery: fast, metadata-aware allele frequency queries on local genomic cohorts.  
+> *(manuscript in preparation)*

afquery-0.2.0/README.md

@@ -0,0 +1,115 @@
+# AFQuery
+
+[![CI](https://github.com/dlopez-bioinfo/afquery/actions/workflows/ci.yml/badge.svg)](https://github.com/dlopez-bioinfo/afquery/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/dlopez-bioinfo/afquery/graph/badge.svg)](https://codecov.io/gh/dlopez-bioinfo/afquery)
+[![Docs](https://img.shields.io/website?url=https%3A%2F%2Fdlopez-bioinfo.github.io%2Fafquery%2F&label=docs)](https://dlopez-bioinfo.github.io/afquery/)
+<br>
+[![PyPI](https://img.shields.io/pypi/v/afquery.svg?color=blue)](https://pypi.org/project/afquery/)
+[![Bioconda](https://img.shields.io/conda/vn/bioconda/afquery.svg)](https://anaconda.org/bioconda/afquery)
+[![Docker](https://img.shields.io/badge/ghcr.io-afquery-blue?logo=docker)](https://github.com/dlopez-bioinfo/afquery/pkgs/container/afquery)
+[![Python](https://img.shields.io/pypi/pyversions/afquery.svg)](https://pypi.org/project/afquery/)
+[![License: MIT](https://img.shields.io/github/license/dlopez-bioinfo/afquery)](https://github.com/dlopez-bioinfo/afquery/blob/master/LICENSE)
+
+AFQuery enables fast allele frequency queries on user-defined subsets of local genomic cohorts, without rescanning VCFs.
+
+AFQuery is a bitmap-indexed engine that efficiently recomputes AC/AN/AF for dynamically defined subcohorts (e.g., by phenotype, sex, or sequencing technology), a common requirement in ACMG/AMP variant classification. It stores per-variant genotype data as Roaring Bitmaps in Parquet files and resolves sample filters into bitmaps that can be intersected in microseconds, enabling sub-100 ms queries on large cohorts. The system accounts for ploidy in sex chromosomes, adjusts AN based on sequencing technology, supports incremental updates, and runs locally using a file-based setup (Parquet + SQLite) without requiring server or cloud infrastructure.
+
+[Full Documentation→](https://dlopez-bioinfo.github.io/afquery/)
+
+## When to use AFQuery
+
+- You need allele frequencies for phenotype or user-defined subcohorts  
+- You work with mixed sequencing technologies or capture kits versions (WGS, WES, targeted panels)  
+- You require fast, repeated queries without rescanning VCFs  
+- You want a local, reproducible workflow without cloud or cluster dependencies  
+
+## Features
+
+- **Dynamic subcohort queries (<100 ms)** — bitmap intersections at query time; no VCF re-scan required  
+- **Technology-aware** — avoids bias when mixing WGS, WES, and panels using different BED capture indexes  
+- **Ploidy-aware** — correct handling of sex chromosomes (PAR/non-PAR, chrX, chrY)  
+- **ACMG-compatible allele counting** — AC/AN/AF computed per standard definitions  
+- **Flexible metadata filtering** — arbitrary labels (ICD-10, HPO, custom fields) with inclusion/exclusion rules 
+- **Incremental updates** — add or remove samples and update metadata without rebuilding the database
+- **VCF annotation** — annotate variants using subcohort-specific frequencies
+- **FILTER/call quality tracking** — failed calls (FILTER!=PASS) tracked per variant and reported as N_FAIL
+- **Batch and region queries** — query a single locus, a genomic region, or a list of variants from a file
+- **Bulk CSV export** — export all variant frequencies with optional disaggregation by sex, technology, or phenotype
+- **Audit changelog** — all database operations logged with timestamps and operator notes
+- **Database validation** — integrity checks with scripted exit codes
+- **Portable and serverless** — file-based system, no infrastructure required
+
+## Performance
+
+- Query latency: <100 ms (tested up to 50,000 samples)  
+- Storage: ~2 bytes/sample/variant  
+- Scales to millions of variants per chromosome  
+
+## Comparison with Alternative Tools
+
+| | AFQuery | bcftools | GATK GenomicsDB | Hail |
+|---|---|---|---|---|
+| Technology-aware AN | **Yes** | No | No | No |
+| Metadata filtering | **Arbitrary labels** | No | No | Custom code |
+| Ploidy-aware sex chromosomes | **Yes** | Manual | No | Manual |
+| Dynamic subcohort queries | **Yes** | No | Limited | Requires code |
+| FILTER/call quality tracking | **Per variant** | Manual | No | Manual |
+| Incremental updates | **Yes** | No | **Yes** | No |
+| Infrastructure required | **None** | **None** | Java/server | Spark cluster |
+| Query latency (50K samples) | **<100 ms** | ~5 min | <1 min | 1–2 min |
+
+## Algorithm Overview
+
+AFQuery pre-indexes per-variant genotype data as [Roaring Bitmaps](https://roaringbitmap.org/) stored in Parquet files. Each variant row holds three bitmaps: heterozygous carriers, homozygous alt carriers, and samples with FILTER!=PASS. Sample metadata (sex, phenotype, technology) is pre-serialized as bitmaps in SQLite.
+
+At query time, the requested sample filter is resolved to a single candidate bitmap via bitmap intersections and differences — taking microseconds regardless of cohort size. For each variant, the candidate bitmap is intersected with the genotype bitmaps to compute AC/AN/AF. AN accounts for WES capture regions (via BED-indexed interval trees) and for ploidy on sex chromosomes (males are haploid on non-PAR chrX and chrY).
+
+## Input Requirements
+
+- VCF files: normalized and consistent with the selected genome build (GRCh37 or GRCh38)  
+- Sample metadata: must include sex, sequencing technology, and any fields used for filtering (e.g., phenotype)  
+- BED files (optional): define capture regions for each sequencing technology  
+
+## Quick Start
+
+Example workflow from raw VCFs to query, export, and annotation:
+
+```bash
+pip install afquery
+# Docker: see Installation docs for docker pull / run usage
+
+# Build the database
+afquery create-db --manifest samples.tsv --output-dir ./db/ --genome-build GRCh38
+
+# Inspect the database
+afquery info --db ./db/
+
+# Query a single position, filtered to a phenotype
+afquery query --db ./db/ --locus chr1:925952 --phenotype E11.9 --sex female
+
+# Query a genomic region
+afquery query --db ./db/ --region chr1:900000-1000000
+
+# Export BRCA1 variant frequencies to CSV
+afquery dump --db ./db/ --output all_variants.csv --chrom chr17 --start 43044292 --end 43170327
+
+# Annotate a VCF with cohort frequencies
+afquery annotate --db ./db/ --input patient.vcf --output annotated.vcf --threads 12
+
+# Add new samples to an existing database
+afquery update-db --db ./db/ --add-samples new_samples.tsv
+```
+
+## Documentation
+
+- [Full Documentation](https://dlopez-bioinfo.github.io/afquery/)
+- [Getting Started](https://dlopez-bioinfo.github.io/afquery/getting-started/)
+- [Why local allele frequencies?](https://dlopez-bioinfo.github.io/afquery/getting-started/motivation/)
+- [CLI Reference](https://dlopez-bioinfo.github.io/afquery/reference/cli/)
+
+## Citation
+
+If you use AFQuery, please cite:
+
+> AFQuery: fast, metadata-aware allele frequency queries on local genomic cohorts.  
+> *(manuscript in preparation)*

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

@@ -23,14 +23,14 @@ This generates 1,000 synthetic samples and 10,000 variants per chromosome, build
 | `--n-samples` | `1000` | Number of synthetic samples |
 | `--n-variants` | `10000` | Number of variants per chromosome |
 | `--output` | `benchmark_report.json` | Output path for JSON report |
-| `--db-dir` | None | Run against an existing database instead of synthetic data |
+| `--db` | None | Run against an existing database instead of synthetic data |
 
 ---
 
 ## Benchmark Against a Real Database
 
 ```bash
-afquery benchmark --db-dir ./my_db/ --output my_db_benchmark.json
+afquery benchmark --db ./my_db/ --output my_db_benchmark.json
 ```
 
 This uses your actual Parquet files and sample metadata, giving realistic performance numbers for your specific cohort size and variant density.
@@ -90,11 +90,11 @@ Run the benchmark after major updates to detect regressions:
 
 ```bash
 # Before update
-afquery benchmark --db-dir ./db/ --output before.json
+afquery benchmark --db ./db/ --output before.json
 
 # After adding 500 samples
 afquery update-db --db ./db/ --add-samples new_batch.tsv
-afquery benchmark --db-dir ./db/ --output after.json
+afquery benchmark --db ./db/ --output after.json
 
 # Compare
 python3 -c "
@@ -106,3 +106,65 @@ for k in before:
     print(f'{k}: {before[k]:.1f} → {after[k]:.1f} ms  ({delta:+.1f})')
 "
 ```
+
+---
+
+## Comparison with Alternative Approaches
+
+### Feature Comparison
+
+| Feature | AFQuery | bcftools stats | VCFtools --freq | GATK GenomicsDB | Hail |
+|---------|---------|---------------|----------------|----------------|------|
+| **Query latency** | <100 ms | Minutes (VCF scan) | Minutes (VCF scan) | Seconds | Seconds–minutes |
+| **Dynamic subcohort queries** | Yes | No | No | Partial | Yes (programmatic) |
+| **Metadata filtering** | Arbitrary labels | No | No | No | User-defined |
+| **Sex-stratified AF** | Yes (auto ploidy) | Manual | Manual | No | Manual |
+| **Technology-aware AN** | Yes (BED capture) | No | No | No | No |
+| **Incremental updates** | Yes (no rebuild) | N/A | N/A | Yes (import) | Rebuild |
+| **Infrastructure required** | None (file-based) | None | None | Java/server | Spark cluster |
+| **Input format** | Single-sample VCFs | Any VCF | VCF | gVCF | VCF/BGEN |
+| **Output format** | JSON/TSV/VCF annotation | Stats text | Freq file | Merged gVCF | Table/VCF |
+| **Max cohort size (tested)** | 50,000 | 100,000+ | 100,000+ | 100,000+ | 1,000,000+ |
+| **Bitmap compression** | Yes (Roaring) | No | No | Yes (GenomicsDB) | No |
+| **VCF annotation** | Yes | No | No | No | Yes |
+| **Python API** | Yes | No | No | No | Yes |
+
+### Query Latency Summary
+
+Brief summary of query latency comparison:
+
+| Tool | 50K samples, chr1, point query |
+|------|-------------------------------|
+| AFQuery (cold) | <100 ms |
+| AFQuery (warm) | ~10 ms |
+| bcftools stats (VCF scan) | ~5 minutes |
+| VCFtools --freq (VCF scan) | ~5 minutes |
+
+AFQuery achieves this speed advantage because queries access only the bitmaps for a single 1-Mbp bucket (one Parquet file) rather than scanning the entire dataset.
+
+---
+
+## Regression Testing
+
+Run the benchmark after each major update to detect performance regressions:
+
+```bash
+# Save baseline before changes
+afquery benchmark --db ./db/ --output baseline.json
+
+# After update
+afquery benchmark --db ./db/ --output after_update.json
+
+# Compare
+python3 - <<'EOF'
+import json
+b = json.load(open('baseline.json'))['queries']
+a = json.load(open('after_update.json'))['queries']
+for k in b:
+    pct = (a[k] - b[k]) / b[k] * 100
+    flag = " ⚠" if pct > 20 else ""
+    print(f"{k}: {b[k]:.1f} → {a[k]:.1f} ms  ({pct:+.1f}%){flag}")
+EOF
+```
+
+A regression of >20% on `point_query_cold_ms` warrants investigation.

afquery-0.2.0/docs/advanced/debugging-results.md

@@ -0,0 +1,138 @@
+# Debugging Results
+
+When AFQuery returns unexpected results — AN=0, surprising AF values, or missing variants — use this diagnostic checklist to identify the root cause.
+
+---
+
+## Diagnostic Checklist
+
+### 1. Unexpected AN=0
+
+AN=0 means no eligible samples at the queried position. Work through these checks in order:
+
+| Check | Command | What to look for |
+|-------|---------|-----------------|
+| Chromosome normalization | `afquery query --db ./db/ --chrom 1 ...` vs `--chrom chr1` | Database may use `chr1` while you're querying `1` (or vice versa). Check `manifest.json` for `genome_build`. |
+| Position exists in database | `afquery query --db ./db/ --locus chr1:12345678` | If no result at all, the variant was not observed in any sample during ingestion. |
+| BED coverage (WES) | `afquery info --db ./db/` | If all eligible samples are WES and the position is outside capture regions, AN=0 is correct. |
+| Sample filter too restrictive | Remove `--phenotype` and `--sex` filters | Query with no filters first. If AN>0 without filters, the filter is excluding all samples. |
+| Technology filter | Remove `--tech` filter | Check if any samples match the requested technology. |
+
+### 2. Unexpected AF Value
+
+| Symptom | Likely Cause | Resolution |
+|---------|-------------|------------|
+| AF higher than expected | Cohort enriched for disease with this variant | Compare with `--phenotype ^disease_code` to get control AF |
+| AF lower than expected | Many WES samples without coverage at this position → diluted AN | Filter by `--tech wgs` to check WGS-only AF |
+| AF=1.0 | All eligible samples carry the variant | Check if AN is very small (e.g., AN=2 means just 1 sample) |
+| AF differs from gnomAD | Expected — local cohort AF ≠ global population AF | This is by design; see [Why Cohort-Specific AF Matters](../getting-started/concepts.md#why-cohort-specific-af-matters) |
+
+### 3. Missing Variants
+
+A variant you expect to find is not in the database:
+
+| Check | Details |
+|-------|---------|
+| Was it in the source VCFs? | AFQuery only stores variants present in ingested VCFs |
+| Was it FILTER=PASS? | Default ingestion skips non-PASS variants. Check with `afquery info` for `pass_only_filter` |
+| Multiallelic sites | AFQuery stores each ALT separately. Query the specific ALT allele, not just position |
+| Chromosome naming | Ensure consistent `chr` prefix usage |
+
+### 4. Unexpected N_FAIL > 0
+
+`N_FAIL > 0` means some eligible samples had the alt allele called but with `FILTER≠PASS`. These samples are excluded from AC/AN. This is usually benign (1–2 samples), but a high N_FAIL warrants investigation:
+
+| N_FAIL relative to n_eligible | Likely cause |
+|---|---|
+| 1–2 samples | Isolated low-quality calls — not concerning |
+| > 5% of n_eligible | Systematic sequencing artifact at this site |
+| All eligible samples | Site-wide QC failure — AF=0 but variant is present in source VCFs |
+
+To inspect a site with high N_FAIL, query with `--format json` to see all fields:
+
+```bash
+afquery query --db ./db/ --locus chr1:12345678 --format json
+```
+
+If N_FAIL is consistently high across many sites, check the variant calling pipeline and FILTER field settings in your VCFs.
+
+---
+
+## Diagnostic Commands
+
+### Database Info
+
+```bash
+afquery info --db ./db/
+```
+
+Shows: sample count, technology list, schema version, genome build, PASS-only status.
+
+### Check Database Integrity
+
+```bash
+afquery check --db ./db/
+```
+
+Validates: manifest consistency, Parquet file integrity, capture index presence.
+
+### Query with Full Output
+
+```bash
+# Point query with all fields visible
+afquery query --db ./db/ --locus chr1:12345678 --format json
+```
+
+JSON format shows all fields including N_HET, N_HOM_ALT, N_HOM_REF, and N_FAIL — useful for understanding the composition of the result.
+
+
+### Direct Metadata Inspection
+
+```python
+import sqlite3
+
+conn = sqlite3.connect("./db/metadata.sqlite")
+
+# List all phenotype codes and sample counts
+cursor = conn.execute("""
+    SELECT code, COUNT(*) as n_samples
+    FROM sample_phenotypes
+    GROUP BY code
+    ORDER BY n_samples DESC
+""")
+for row in cursor:
+    print(f"{row[0]:30s}  {row[1]} samples")
+
+# List technologies
+cursor = conn.execute("""
+    SELECT technology, COUNT(*) as n_samples
+    FROM samples
+    GROUP BY technology
+""")
+for row in cursor:
+    print(f"{row[0]:20s}  {row[1]} samples")
+
+conn.close()
+```
+
+---
+
+## Common Root Causes
+
+| Symptom | Root Cause | Fix |
+|---------|-----------|-----|
+| AN=0 for all queries | Wrong `--db` path or empty database | Verify path; run `afquery info` |
+| AN=0 for specific region | WES-only cohort, position outside capture | Check BED file coverage |
+| AN much lower than sample count | Mixed WGS/WES, position outside WES capture | Filter by `--tech wgs` to isolate |
+| AF=None in output | AN=0 (division by zero) | See AN=0 diagnosis above |
+| Different AF between `query` and `annotate` | Different default filters or phenotype context | Ensure same `--phenotype`, `--sex`, `--tech` flags |
+| N_FAIL high at a site | Systematic QC failure in source VCFs at this position | Inspect site with `--format json`; check VCF FILTER annotations |
+
+---
+
+## Related Pages
+
+- [Understanding Output](../getting-started/understanding-output.md) — what each field means
+- [FAQ](../faq.md) — common questions and answers
+- [Troubleshooting](../troubleshooting.md) — error messages and solutions
+- [FILTER=PASS Tracking](filter-pass-tracking.md) — how PASS filtering works