picsure

Python client for the PIC-SURE API. Search the data dictionary, build cohort queries with nested AND/OR filters, and export participant-level data — all from a Jupyter notebook.

Installation

pip install picsure

That is everything the library needs, PFB export included: exportAsPFB streams the server's Avro bytes straight to a file and builds nothing locally. Reading the exported file back is a separate job, and a PFB reader such as fastavro or pypfb is what does it.

Quickstart

import picsure
from picsure import PhenotypicFilterType, GroupOperator

# Connect to PIC-SURE
session = picsure.connect(platform=picsure.Platform.BDC_AUTHORIZED, token="your-token")

# Search the data dictionary
results = session.searchDictionary("blood pressure")

# Build a query
sex = picsure.buildClause("\\phs1\\sex\\", type=PhenotypicFilterType.FILTER, categories="Male")
age = picsure.buildClause("\\phs1\\age\\", type=PhenotypicFilterType.FILTER, min=40)
query = picsure.buildClauseGroup([sex, age], operator=GroupOperator.AND)

# Run and export
count_result = session.runQuery(query, type="count")
count = count_result.value  # None if suppressed; check count_result.cap
df = session.runQuery(query, type="participant")
session.exportCSV(df, "cohort.csv")

Genomic Filtering

On genomic-capable platforms (BDC_AUTHORIZED, NHANES_AUTHORIZED), you can filter by gene, consequence, and variant frequency, and discover valid values for any genomic key:

import picsure

gene_filter = picsure.buildGenomicFilter(
    key=picsure.GenomicFilterKey.GENE_WITH_VARIANT, values="BRCA2"
)
freq_filter = picsure.buildGenomicFilter(
    key=picsure.GenomicFilterKey.VARIANT_FREQUENCY_AS_TEXT,
    values=picsure.VariantFrequency.RARE,
)

# Variant severity is a virtual key -> expands to Variant_consequence_calculated
severe_filter = picsure.buildGenomicFilter(
    key=picsure.GenomicFilterKey.VARIANT_SEVERITY,
    values=picsure.VariantSeverity.HIGH,
)

# Genomic-only query
genomic_query = picsure.buildQuery(genomicFilters=[gene_filter, freq_filter])
count_result = session.runQuery(genomic_query, type="count")

# Discover valid values for a genomic key
df = session.searchGenomicValues("Gene_with_variant", query="BRCA")

# Offline list of all variant consequences with severity
consequences = picsure.genomicConsequences()

Documentation

• Getting Started — connect and run your first query
• Search & Facets — search the dictionary with facet filters
• Building Queries - nested AND/OR clause groups, genomic filters
• Running & Exporting — counts, DataFrames, CSV/TSV/PFB
• API Reference — complete function documentation
• Migration Guide — upgrading from PicSureHpdsLib
• Changelog — release history and notable changes

License

Apache 2.0 — see LICENSE for details.