Normalize VCF
normalize_vcfNormalize raw VCF files into reusable, quality-filtered genotype Parquet for efficient polygenic risk score analysis. Apply optional filters (depth, quality, FILTER) and reuse cached output across multiple scoring runs.
Instructions
Normalize a VCF to a quality-filtered genotype Parquet.
This tool is optional preprocessing, not a prerequisite for scoring:
compute_prs, compute_prs_batch, and compute_prs_by_trait accept
raw VCF paths directly. Use normalization when you intentionally want a
reusable Parquet for many later analyses or custom quality filters. Before
normalizing, list_genomes can show whether a cached Parquet already exists.
Strips the chr prefix, renames id→rsid, computes genotype from GT, applies
optional quality filters (FILTER allow-list, min DP, min QUAL), and writes
zstd-compressed Parquet. The output is a drop-in genotype source for
compute_prs / compute_prs_batch (genotypes_path) and for
compute_prs_by_trait (a samples entry ending in .parquet), so
each VCF is normalized once and reused. Normalize every genome you plan
to compare; scoring still happens per genome.
Idempotent: if the target Parquet already exists it is reused and the
(slow) normalization is skipped — reused_cache=True flags the hit.
Custom filters (pass_filters / min_depth / min_qual / sex)
always re-run, since the cached Parquet may not reflect them. Pass
force=True to re-normalize unconditionally.
Normalization is the slow step (seconds to minutes depending on VCF size).
Returns a PRSJob immediately; poll prs_job_status when status is
running. When done, result is a NormalizeResult.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | ||
| force | No | ||
| min_qual | No | ||
| vcf_path | Yes | ||
| min_depth | No | ||
| output_path | No | ||
| genome_build | No | ||
| pass_filters | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | Tool that created the job. | |
| error | No | Failure message when status is failed. | |
| job_id | Yes | Pass this to prs_job_status until status is done or failed. | |
| result | No | When status is done: the original tool payload (TraitPRSReports, NormalizeResult, OpResult, or a list of PRSResult). Read html_link / result_paths from this object. | |
| status | Yes | queued/running: call prs_job_status. done: read result and html_link. failed: read error. Do not start a second identical compute while queued/running. | |
| message | Yes | Latest progress line. | |
| progress | No | Completed work units, when known. | |
| html_link | No | PRIMARY REPORT DELIVERY TARGET. When set, put this exact value in the user reply as a markdown link and explicitly tell the user to open the interactive report. It is an HTTP URL when available and a file:// URI for local stdio. Never omit, fetch, or paste the HTML. | |
| poll_with | No | Poll this tool with job_id. Optional wait_seconds keeps one poll under typical client timeouts (try 25). | prs_job_status |
| created_at | Yes | UTC timestamp when the job was created. | |
| html_error | No | Optional HTML-generation error. Scores remain valid when this is set. | |
| progress_total | No | Total work units, when known. |