PheTK - The Phenotype Toolkit

The official repository of PheTK, a fast python library for Phenome Wide Association Studies (PheWAS) utilizing both phecode 1.2 and phecodeX 1.0.

Reference: Tam C Tran, David J Schlueter, Chenjie Zeng, Huan Mo, Robert J Carroll, Joshua C Denny, PheWAS analysis on large-scale biobank data with PheTK, Bioinformatics, Volume 41, Issue 1, January 2025, btae719, https://doi.org/10.1093/bioinformatics/btae719

Contact: PheTK@mail.nih.gov

Releases: check GitHub Releases for the latest versions and changelogs.

CURRENT MAJOR FUNCTIONALITIES (v0.3 — June 2026)

• Variant selection - Retrieve ClinVar variants for a gene symbol or genomic region with ClinVar.search(), filtering by clinical significance, review star rating, variant type, and allele frequency. Output columns feed directly into by_genotype(). Works cross-platform.
• Cohort generation - Build genotype-based cohorts from VCF or Hail data with by_genotype(), add demographic and genetic covariates with add_covariates(). Cohort generation and covariate retrieval require the All of Us Researcher Workbench (CDR v7-v9); custom platforms are supported with user-provided data paths and BigQuery datasets.
• Phecode mapping - Map ICD codes to phecodes (phecode 1.2, phecodeX 1.0) with count_phecode(), and compute age-at-first-event and time-to-event. ICD extraction from OMOP requires All of Us or a compatible BigQuery dataset; phecode mapping and time-to-event computation work cross-platform with local files. The bundled mapping tables are also directly loadable via get_phecode_map().
• PheWAS analysis - Run phenome-wide association studies with logistic, Cox, Firth logistic, and Firth Cox regression. Works cross-platform on any pre-built dataset.
• Visualization - Generate Manhattan, Miami, and forest plots. Works cross-platform.
• CLI support - Full command-line interface for all modules (phetk clinvar, phetk phewas, phetk cohort, phetk phecode)
• Distributed computing - Built-in dsub integration for large-scale analyses on Google Cloud on the All of Us Researcher Workbench.

📋 View full changelog

QUICK LINKS

• Installation
• 1-minute PheWAS demo
• PheTK description
• Usage examples
  • ClinVar module
  • Cohort module
  • Phecode module
  • PheWAS module
  • Plot module
• System requirements & computing resources
• Platform specific tutorial(s):
  • All of Us: Tutorial notebooks - Interactive Jupyter notebooks demonstrating PheTK usage on the All of Us Researcher Workbench with various analysis examples. Please note that all examples require All of Us registered user access.
• Changelogs and releases: from v0.1.45, please use GitHub Releases for the latest versions and changelogs. Legacy changelogs were archived in CHANGELOG.md.
• Resource to learn about PheWAS and phecode: The PheWAS Catalog.

1. INSTALLATION

Using pip

The latest version (v0.3+) of PheTK can be installed using the pip install command in the terminal (note that the lowercase package name "phetk" starts from version 0.2+):

pip install phetk --upgrade

Users can also specify a version, e.g., for the last stable version of version 0.1:

pip install phetk==0.1.47

To check current installed version:

pip show phetk | grep Version

Using Docker

Please refer to https://hub.docker.com/r/phetk/phetk/tags for the latest docker images.

docker pull phetk/phetk:latest

2. 1-MINUTE PHEWAS DEMO

User can run the quick 1-minute PheWAS demo with the following command in a terminal:

phetk demo

Or in Jupyter Notebook:

from phetk import demo

demo.run()

The example files (example_cohort.tsv, example_phecode_counts.tsv, and example_phewas_results.tsv) generated in this Demo should be in users' current working directory. New-to-PheWAS users could explore these files to get a sense of what data are used or generated in PheWAS with PheTK.

3. DESCRIPTIONS

PheTK is a fast python library for Phenome Wide Association Studies (PheWAS) utilizing both phecode 1.2 and phecodeX 1.0.

Standard PheWAS workflow. Green italicized texts are PheTK module names. Black components are supported while gray ones are not supported by PheTK currently.

All of Us: the All of Us Research Program (https://allofus.nih.gov/)

4. USAGE

For detailed usage examples and documentation for each module, please refer to the individual module documentation:

• ClinVar module - Retrieve ClinVar variants by gene or genomic region
• Cohort module - Generate genetic cohorts and add covariates
• Phecode module - Map ICD codes to phecodes and generate counts
• PheWAS module - Run PheWAS analysis with logistic or Cox regression
• Plot module - Generate Manhattan, Miami, and forest plots

5. SYSTEM REQUIREMENTS

PheTK was developed for efficient processing of large data while being resource-friendly. It was tested on different platforms from laptops to different cloud environments.

General Requirements

PheTK's resource requirements vary by usage context. The information in this section is tailored towards cloud computing platforms where large biobanks are often hosted.

• All PheTK functions run on standard machines. The by_genotype() Cohort function supports VCF (default, no Spark needed) and Hail (requires a Spark cluster) data formats.
• Both logistic regression and Cox regression scale with CPU counts for faster processing. See figure S2 below from PheTK publication for more information. In our experience, 4 CPU machines are the most cost-efficient, especially for large-scale analyses.
• For an end-to-end pipeline, the system requirements should be based on the most demanding steps, which is usually phecode mapping. Since v0.2.7, the phecode module uses DuckDB by default, which brought the memory requirement for the full All of Us v8 cohort down substantially: a 4 vCPU / 26GB RAM VM is sufficient for the entire pipeline. If users only need to run PheWAS analysis, it can be run at a much lower configuration as shown in figure S2.

Figure S2: Logistic regression performance benchmarks from PheTK publication showing scalability with different CPU configurations and cohort sizes.

PheWAS Module - Logistic Regression

• Minimal resources required - Can run efficiently on lightweight configurations
• Minimum tested configuration: GCP X-highcpu-4 (4 vCPUs, 8GB RAM, X=GCP machine type, e.g., c2d) or equivalent
• Uses multithreading for parallel processing with lower memory overhead

PheWAS Module - Cox Regression

• Slightly higher resources required - Uses multiprocessing which demands more memory
• Minimum tested configuration: GCP X-standard-4 (4 vCPUs, 16GB RAM, X=GCP machine type, e.g., c2d) or equivalent
• The additional memory accommodates the multiprocessing overhead for survival analysis

Phecode Module (ICD Code Mapping)

• Memory requirements scale with cohort size, but the default engine="duckdb" keeps memory bounded via a streaming, spill-capable pipeline
• Recommended: For All of Us database v8 with over 500k participants, count_phecode() has been tested and runs successfully on a 4 vCPU / 26GB RAM machine with the default DuckDB engine
• engine="polars" runs fully in memory and is somewhat faster, but needs considerably more RAM — roughly 16 vCPU / 104GB RAM for the full v8 cohort
• memory_limit sets the DuckDB memory ceiling explicitly; it defaults to ~90% of currently available RAM. See the phecode module docs