Search the PGS Catalog for polygenic scores by free text.

Case-insensitive substring match across PGS ID, score name, reported trait, and EFO trait. Optionally filter to a genome build (GRCh37 / GRCh38, harmonized cross-build scores included). Returns up to limit matches with their key metadata.

Get cleaned metadata for a single PGS score by its ID (e.g. 'PGS000001').

Look up the best evaluation performance for a score (largest sample, EUR-preferred).

Returns parsed effect sizes (OR/HR/Beta) and classification metrics (AUROC/C-index) plus pre-formatted display strings.

Search the PGS Catalog REST API for traits by term.

Upstream matching is exact-substring over labels and synonyms, so this wrapper retries a few punctuation/order variants when the first query is empty. By default, results include counts of directly associated PGS IDs and child-trait PGS IDs; set include_pgs_ids for the full arrays.

Fetch a trait by ontology ID (EFO or MONDO) with its associated PGS IDs.

Normalize a VCF to a quality-filtered genotype Parquet (background task).

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 (pass it as genotypes_path), so a VCF is normalized once and reused across many scores.

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.

Runs as a real MCP background task, though some clients transparently collapse the task/poll handshake and return the final result inline. Normalization is the slow step (seconds to minutes depending on VCF size). The result echoes the effective genome build assumed for downstream PRS scoring; build inference from VCF contigs is deferred to just-prs.

Download a public sample WGS VCF from Zenodo to try PRS without your own data.

Two whole-genome sequencing (WGS) datasets open-sourced by the just-dna-lite project are pre-configured:

• sample="anton" — Anton Kulaga's genome (~482 MB, CC0 public domain, Zenodo record 18370498, file: antonkulaga.vcf).

• sample="livia" — Livia Zaharia's genome (~349 MB, CC-BY-4.0, Zenodo record 19487816, file: SIMHIFQTILQ.hard-filtered.vcf.gz).

Pass record_url (e.g. 'https://zenodo.org/records/18370498') to fetch any other Zenodo record, and filename to pick a specific file when a record has several.

The downloaded VCF lands under <cache_dir>/samples/ (or output_dir) and is a drop-in path for normalize_vcf / compute_prs.

auto_normalize defaults to True: the download is normalized to a reusable Parquet in the same call, so data carries both path (the raw VCF) and normalized_path — a one-call, compute-ready genotype source with no separate normalize_vcf round-trip. (Normalization is idempotent, so a re-download of an already-staged sample is cheap.) Pass auto_normalize=False to fetch the raw VCF only.

Use list_genomes to see which genomes have already been downloaded and/or normalized.

Idempotent: if the target VCF already exists with the size Zenodo reports, the ~hundreds-of-MB download is skipped and the cached file is reused; likewise a present Parquet skips re-normalization. data echoes reused_cache (download skipped) and downloaded_bytes (bytes actually transferred, 0 on a cache hit) so the caller can tell a cache hit from a fresh fetch. Pass force=True to re-download/re-normalize regardless.

Returns an OpResult whose data carries the local path on success. Runs as a background task (files are hundreds of MB).

List genomes available in the server's cache directory.

Scans <cache_dir>/samples/ for downloaded raw VCF files and <cache_dir>/normalized/ for normalized Parquet files. Also lists the pre-configured sample genomes that can be downloaded via download_sample_genome (even if not yet downloaded).

Use this to discover:

• Which genomes have already been downloaded (ready for normalize_vcf).

• Which genomes have already been normalized (ready for compute_prs as genotypes_path).

• Which pre-configured samples are available for download.

No network access required — reads the local filesystem only.

Compute a polygenic risk score for one VCF against one PGS score.

Downloads the harmonized scoring file (cached) and scores the genotypes. Pass genotypes_path to reuse a normalized Parquet from normalize_vcf (avoids re-reading the VCF); otherwise the VCF is read directly. Returns the score, match rate, variant counts, weight-mass coverage (C_wt), trait, and (when data permits) a theoretical percentile.

Set attach_performance=True to embed the score's best published performance (effect sizes, AUROC/C-index, evaluation ancestry) on the result in the same call — no separate best_performance round-trip; it is honored on the genotypes_path reuse branch too (F23). The result also carries detected_genome_build / build_mismatch from the VCF (F4).

Recommended follow-up: after computing the score, call percentile to place it on the population distribution, then call absolute_risk with the z_score from the percentile result to get the concrete disease probability and risk ratio (for disease traits with prevalence data).

Compute PRS for one VCF against many PGS scores (background task).

Memory-safe DuckDB engine with spill-to-disk; reuses the parsed VCF and scoring caches across scores. Returns one result per PGS ID. Set attach_performance=True to embed each score's best published performance on its result in the same pass.

Compute the PRS scores associated with a trait ontology ID.

trait_id may be an EFO or MONDO identifier. Set include_children to also score PGS IDs associated through descendant traits. limit caps how many scores are computed and reports skipped IDs explicitly.

Profile (curation): profile="curated" (default) returns an interpreted shortlist — it applies live criteria (drops toy scores <10 variants, scores with no performance evidence, scores below the C_wt coverage floor, and de-dups score families to one best per publication) and reports what it dropped in filter_summary / n_filtered. Use profile="all" for every associated score (the raw panel).

Filters (apply in both profiles, before top_n): min_match_rate, min_auroc, build (e.g. 'GRCh38'), and ancestry (matched against each score's reference-panel ancestry). These raw knobs are the extended-mode curation surface — using min_match_rate / min_auroc sets needs_extended on the report as a breadcrumb.

top_n then caps how many surviving rows are returned: rows are ranked best-coverage first (scored before failed, reliable percentile before not, higher C_wt then match rate) and the rest trimmed, with n_omitted reporting the count. Trait-level counts and mean_match_rate always reflect every computed score, so both filtering and trimming are explicit, never silent.

Estimate the population percentile (0-100) for a computed PRS value.

Uses the 3-tier fallback: precomputed reference-panel distributions (best), then a theoretical distribution, then an AUROC approximation. superpopulation is a 1000G code (AFR/AMR/EAS/EUR/SAS). Pass weight_mass_coverage (C_wt) from compute_prs so a deflated low-coverage percentile is flagged reliable=False with a caveat instead of presented as authoritative. Also returns the true z-score and reference mean/std used, so absolute risk can be computed without inverting the percentile.

Important next step: for disease traits, feed the returned z_score directly into absolute_risk to get the concrete lifetime probability and risk ratio vs the population average. This is more informative than the percentile alone.

Estimate absolute disease risk from a PRS z-score and population prevalence.

Joins the score's trait to prevalence + effect-size data. z_score is the PRS in standard deviations from the population mean. Raises if the required prevalence / effect-size data is unavailable for this score.

Classify and interpret a PRS result's quality (pure logic — no I/O).

match_rate is the fraction of scoring variants matched (0-1). Returns a quality label/color and a human-readable interpretation combining match rate, AUROC, and (optionally) the result percentile. Pass percentile_method / reliable / caveat from the percentile tool so the summary describes how the percentile was actually derived and echoes any low-coverage caveat.

Compare PRS results across multiple genomes for the same trait(s).

result_paths — list of JSON file paths produced by compute_prs_by_trait (the result_path field in each TraitPRSReport). At least two paths are required. Each file may cover a different genome but they are grouped by trait.

genome_labels — optional override labels (same length as result_paths); if omitted, labels are taken from each saved report's genome_label field or inferred from the filename.

Returns a GenomeComparison with per-trait rankings (sorted high→low percentile — no directionality judgment), percentile spread, model consistency, and a most_divergent_traits list for the LLM to interpret.

Build a Plotly figure spec for a saved by-trait PRS report.

Pass the result_path from a compute_prs_by_trait result (the report is auto-saved as JSON). Returns a Plotly figure ({data, layout}) — NOT a server-rendered image — placing one marker per scored model on a reference normal curve at its percentile: marker shape encodes the model's quality tier and color encodes reliability/outlier status. The client renders it (Plotly.newPlot, plotly.io.from_json, or the optional html page). Set include_html=True to also get a self-contained HTML page (loads plotly.js from CDN) you can save and open in a browser.