prs-ui

Reusable Reflex UI components for Polygenic Risk Score (PRS) computation using the PGS Catalog.

Built on top of just-prs for the computation engine and reflex-mui-datagrid for data grid display.

Installation

pip install prs-ui

Running the Standalone App

uv run start

The launcher reads .env, resolves both the Reflex frontend port (PRS_UI_PORT, default 3000) and backend port (PRS_UI_BACKEND_PORT, default 8000), and passes the resolved pair explicitly to Reflex so another running Reflex app cannot shift only one side. Runtime uploads go under PRS_UI_DATA_DIR/input/ (default: ./data/input/ from the directory where the launcher was invoked), which keeps uvx runs from writing into the installed package.

Quick Start

import polars as pl
import reflex as rx
from reflex_mui_datagrid import LazyFrameGridMixin
from prs_ui import PRSComputeStateMixin, prs_section


class MyAppState(rx.State):
    genome_build: str = "GRCh38"
    cache_dir: str = ""
    status_message: str = ""


class PRSState(PRSComputeStateMixin, LazyFrameGridMixin, MyAppState):
    def load_genotypes(self, parquet_path: str) -> None:
        lf = pl.scan_parquet(parquet_path)
        self.set_prs_genotypes_lf(lf)  # preferred: provide a LazyFrame
        self.prs_genotypes_path = parquet_path


def prs_page() -> rx.Component:
    return prs_section(PRSState)

Components

The genotype source is loosely coupled to the PRS logic: a source pushes a normalized genotypes parquet into each consumer via the additive load_genotypes(path) hook, or several at once via load_samples([{"label", "path"}, ...]) for CLI-style multi-sample comparison (per-sample colors, medians, and bell-curve markers). Each uploaded sample gets its genetic ancestry autodetected (1000 Genomes reference panel): the sample row shows the population with the classifier's confidence plus the closest 1000G cohort as a clickable IGSR link with its own confidence — a reference point, not a nationality — and the majority detected population becomes the percentile reference (shown on each sample row; override via the trait dashboard Population dropdown). After computing, the chart panel renders automatically for the first (or currently open) result/trait — no row click needed. Sources may also pass optional per-sample ancestry / ancestry_confidence / fine_population / fine_confidence keys, and optionally set_genome_build(build), so a host app can replace vcf_source_section / GenomicGridState with its own source (public genome, consumer-array file, pre-normalized parquet) without touching PRSComputeStateMixin. VCF normalization (not upload) is the slow step; it is content-aware cached (a fresh normalized parquet is reused) and shown via an indeterminate progress bar.

Curated score directions

Both consumers read the published direction curation through PRSCatalog (pulled from just-dna-seq/pgs-catalog, refreshed after PRS_CURATION_MAX_AGE_HOURS): every result row carries higher_percentile_means, curation_status, concept, axis, valence and polarity; trait summaries put opposite-direction scores on one concept axis and list scores still in curation review without counting them. The Curated tab shows the published tables when the app is not running inside a curation/ checkout.

State Mixin

PRSComputeStateMixin provides all PRS computation logic as a Reflex state mixin. Mix it into your concrete state class alongside LazyFrameGridMixin to get the full PRS workflow.

The preferred input method is a polars LazyFrame via set_prs_genotypes_lf() -- memory-efficient and avoids re-reading VCF files on each computation. A parquet path (prs_genotypes_path) is supported as a fallback.

Documentation

See the just-prs documentation for the full Python API, CLI reference, and integration guide.