biobanking 0.0.20

Biobanking data processing, annotation, and association workflows

Biobanking

Systematic collection, processing, storage, and analysis of biological samples and associated health records for medical research.

Supported pipelines

Preprocess

Contains biobank-specific modules for EHR data collection, cleaning, and processing.

QC (Under construction)

Will contain biobank-specific modules for variant quality control and filtering.

Annotation (Under construction)

Will contain biobank-specific modules for variant annotation.

Association

Contains biobank-specific modules for genotype-phenotype association tests.

Plotting

Contains forest plot helpers for burden and interaction association results.

Interaction forest plots can include marginal burden rows for the anchor and target genes by passing the corresponding burden result files to plot_interaction_forest(..., burden_data=[anchor_file, target_file]). These rows appear as Burden :: <gene> before the interaction-model main effect, interaction effect, and joint effect rows.

More plotting examples are in docs/plotting.md.

Supported biobanks

All of Us

The All of Us biobank consists of coupled whole genome sequencing and electronic health record data of more than 400k individuals, with continued expansion.

UK Biobank (Under construction)

The UK Biobank consists of coupled whole genome sequencing and electronic health record data of ~500k participants.

AoU REGENIE workflow

The All of Us association utilities currently support a packaged regenie workflow with four Step 2 categories:

• Burden association testing
• SKAT-O association testing
• Mask-only runs for writing burden-mask PLINK datasets
• Interaction testing using precomputed burden-mask PLINK datasets

The workflow implementation lives in src/biobanking/workflows/regenie.wdl, and the Python utilities live in src/biobanking/association/aou.py.

The Step 2 tracking model separates statistical test, variant-mask family, and concrete run identity:

• step2_category: burden, skato, mask, or interaction
• step2_mode: the variant/mask family, such as plof, missense, or plof_missense
• run_label: the concrete run, such as default, INHBE_vs_LDLR, or INHBE_vs_chr1

This keeps LOCO and prediction reuse aligned with the phenotype definition, lets pLoF and missense mask families share the same workflow machinery, and avoids encoding interaction labels into step2_mode.

Recommended usage pattern

• Run or reuse Step 1 once per phenotype prefix.
• Use burden runs for standard gene-based mask tests.
• Use SKAT-O runs when you want the REGENIE --vc-tests skato gene-based test for the same mask family; these default to --vc-maxAAF 0.001 unless vc_max_aaf is overridden.
• Use mask runs to materialize chromosome-wide burden-mask PLINK files from a universal dummy phenotype stored at data/associations/masks/<burden_type>/dummy.tsv.gz, without phenotype covariates.
• Use interaction runs only after Step 1 exists for the phenotype prefix you are testing.

Burden input files are generated from annotation files at data/exome/annot/chr<chrom>_<burden_type>.tsv.gz. The default pLoF call uses built-in pLoF_strict and pLoF_lenient mask definitions; custom mask families can pass mask_definitions directly to create_regenie_burden_files(...).

More detailed usage examples are in docs/workflows.md.

Validate WDL

Before submitting workflows through Cromwell, validate the WDL locally with womtool. A simple setup is:

java -jar .\data\tools\womtool.jar validate .\src\biobanking\workflows\regenie.wdl

If womtool.jar is not present yet, place it under data/tools/ in the repository and rerun the validation command before submitting updated workflow code.

Internal use

python -m pip install -U pip build
pip install twine
# linux
rm -rf dist build *.egg-info src/*.egg-info
# windows
Remove-Item -Recurse -Force dist, *.egg-info, src\*.egg-info
python -m build
pip install dist/biobanking-0.0.20-py3-none-any.whl
java -jar .\data\tools\womtool.jar validate .\src\biobanking\workflows\regenie.wdl
python -c "from biobanking.association.aou import REGENIE; regenie = REGENIE(); from biobanking.preprocess.aou.measurements import save_measurements_in_wide_format; print('import ok')"
twine upload dist/*