Compute PRS by trait (give user html_link)
compute_prs_by_traitCalculate polygenic risk scores for a trait using provided VCF genomes, delivering an interactive report with risk percentiles and model quality metrics.
Instructions
Compute the PRS scores associated with a trait for one or more genomes.
REQUIRED REPORT DELIVERY: when html_link is set, your reply MUST include it as a markdown link (for example Open the interactive trait report) and explicitly tell the user to open it. This is the primary user-facing result, not an implementation detail. Do not skip the link, merely say the report was saved, fetch it, or paste the HTML. html_link is an HTTP URL when available and a file:// URI on local stdio.
Pass a raw .vcf/.vcf.gz path directly. Do NOT call normalize_vcf first as a prerequisite: multi-score tools transparently create or reuse a safe normalized cache, and single-score tools read the VCF directly. normalize_vcf is only an optional explicit step for custom filters. If list_genomes already shows a normalized Parquet, it can be passed directly.
trait_id may be an EFO or MONDO identifier. samples is always a
list (one genome is fine): each entry is Label=path or a bare path;
.parquet is a normalized genotype source. Every genome is auto-saved;
the return carries reports, result_paths, and (when models have
percentiles) the primary html_link plus transport-specific
html_url / html_path — the just-prs trait HTML report (same page
as prs plot trait -o *.html).
Pass result_paths to compare_genomes (2+), plot_trait_panel,
or build_prs_prompt.
Profile (curation): profile="all" (default) returns the raw
associated panel. profile="curated" is the interpreted shortlist —
it drops toy scores (<10 variants), scores with no performance evidence,
scores below the C_wt coverage floor, and de-dups score families.
interpret=True (default) attaches percentiles/quality per model.
Set interpret=False for raw scores only — the report then says so.
reference_restoration defaults to "auto". superpopulation
may be a 1000G code or "auto". Set include_prompt=True to also
attach the just-prs LLM prompt covering every genome in this call.
This tool returns a PRSJob immediately. If status is queued or running, call prs_job_status(job_id, wait_seconds=25) until done or failed. Do not start a second identical compute — the server reuses the in-flight job. When done, html_link and result (TraitPRSReports) are on the job. Native multi-score work is isolated in a child process so a DuckDB/Polars crash fails the batch without killing the MCP transport.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| build | No | ||
| limit | No | ||
| panel | No | ||
| top_n | No | ||
| profile | No | all | |
| samples | Yes | ||
| ancestry | No | ||
| trait_id | Yes | ||
| interpret | No | ||
| min_auroc | No | ||
| genome_build | No | ||
| include_prompt | No | ||
| min_match_rate | No | ||
| superpopulation | No | EUR | |
| include_children | No | ||
| genotype_input_mode | No | auto | |
| reference_restoration | No | auto |
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. |