Models nonlinear interactions between covariates and phenotypes
DeepNull: Modeling non-linear covariate effects improves phenotype prediction and association power
This repository contains code implementing nonlinear covariate modeling to increase power in genome-wide association studies, as described in "DeepNull: Modeling non-linear covariate effects improves phenotype prediction and association power" (Hormozdiari et al 2021). The code is written using Python 3.7 and TensorFlow 2.4.
Installation is not required to run DeepNull end-to-end; you can just
DeepNull_e2e.ipynb in colab
to try it out.
To install DeepNull locally, run
pip install --upgrade pip pip install --upgrade deepnull
on a machine with Python 3.7+. This installs a CPU-only version, as there are typically few enough covariates that using accelerators does not provide meaningful speedups.
Verify that the installation is working properly by executing all tests:
python -m deepnull.config_test python -m deepnull.data_test python -m deepnull.metrics_test python -m deepnull.main_test python -m deepnull.model_test python -m deepnull.train_eval_test
How to run DeepNull
To run locally, there is a single required input file. This file contains the phenotype of interest and covariates used to predict the phenotype, formatted as a tab-separated file suitable for GWAS analysis with PLINK or BOLT-LMM.
Briefly, the file must contain a single header line. The first two columns must
IID, and all
IID values must be unique.
An example command to train DeepNull to predict the phenotype
genotyping_array is the following:
python -m deepnull.main \ --input_tsv=/input/YOUR_PHENOCOVAR_TSV \ --output_tsv=/output/YOUR_OUTPUT_TSV \ --target=pheno \ --covariates="age,sex,genotyping_array"
To see all available flags, run
python -m deepnull.main --help 2> /dev/null
Of particular note is the
--model_config flag. DeepNull uses the
ml_collections library to specify
all parameters related to the model and training regimen. The supported
configuration code is located in
config.py, and parameters can
be modified as described in detail in the
As a brief example, to use the DeepNull architecture with the
and train with batch size 4096, the above example command would be modified as
python -m deepnull.main \ --input_tsv=/input/ORIGINAL_PHENOCOVAR_TSV \ --output_tsv=/output/PHENOCOVAR_WITH_DEEPNULL_PREDICTION_TSV \ --target=pheno \ --covariates="age,sex,genotyping_array" \ --model_config=/path/to/config.py:deepnull \ --model_config.model_config.mlp_activation=elu \ --model_config.training_config.batch_size=4096
/path/to/config.py provides the path to
config.py on your
Incorporating DeepNull into a GWAS analysis
The above section, "How to run DeepNull", shows that the DeepNull software adds
a single column to a phenotype+covariate file of interest that represents a
nonlinear prediction of the target phenotype of interest. To incorporate this
into a GWAS analysis, the single additional covariate should be added as an
additional covariate. A concrete example with
BOLT-LMM, using the same file,
pheno, and covariates
genotyping_array as above, is
Original example GWAS command
# N.B. Data loading flags are omitted for brevity. bolt \ --phenoFile /input/ORIGINAL_PHENOCOVAR_TSV \ --covarFile /input/ORIGINAL_PHENOCOVAR_TSV \ --qCovarCol age \ --qCovarCol sex \ --qCovarCol genotyping_array \ --phenoCol pheno
After running DeepNull on the
/input/ORIGINAL_PHENOCOVAR_TSV to create the new
/output/PHENOCOVAR_WITH_DEEPNULL_PREDICTION_TSV that includes the column
pheno_deepnull, the updated command is given below:
Updated GWAS command to incorporate DeepNull
# N.B. Data loading flags are omitted for brevity. # Note the addition of the single `--qCovarCol pheno_deepnull` line. bolt \ --phenoFile /output/PHENOCOVAR_WITH_DEEPNULL_PREDICTION_TSV \ --covarFile /output/PHENOCOVAR_WITH_DEEPNULL_PREDICTION_TSV \ --qCovarCol age \ --qCovarCol sex \ --qCovarCol genotyping_array \ --qCovarCol pheno_deepnull \ --phenoCol pheno
Datasets used to reproduce the results from the above publication are available to researchers with approved access to the UK Biobank.
NOTE: the content of this research code repository (i) is not intended to be a medical device; and (ii) is not intended for clinical use of any kind, including but not limited to diagnosis or prognosis.
This is not an officially supported Google product.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.