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)

• Cohort generation - Build genotype-based cohorts from VCF or Hail data, add demographic and genetic 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), compute counts, 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.
• 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 plots and Forest plots. Works cross-platform.
• CLI support - Full command-line interface for all modules (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
  • 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:

• 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 plots and other visualizations

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. For example, for the All of Us data v8/v9, a VM with 16CPU 104GB RAM should work; 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 - Large cohorts require higher memory configurations
• Recommended: For All of Us database v8 with over 500k participants, phecode mapping could be done with a 16 vCPU 104GB RAM machine.