Package: deepnull
DeepNull: Modeling non-linear covariate effects improves phenotype prediction and association powerThis 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.InstallationInstallation is not required to run DeepNull end-to-end; you can justopenDeepNull_e2e.ipynbin colabto try it out.To install DeepNull locally, runpipinstall--upgradepip
pipinstall--upgradedeepnullon 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-mdeepnull.config_test
python-mdeepnull.data_test
python-mdeepnull.metrics_test
python-mdeepnull.main_test
python-mdeepnull.model_test
python-mdeepnull.train_eval_testHow to run DeepNullTo 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
atab-separatedfile suitable for GWAS analysis withPLINKorBOLT-LMM.Briefly, the file must contain a single header line. The first two columns must
beFIDandIID, and allIIDvalues must be unique.An example command to train DeepNull to predict the phenotypephenofrom
covariatesage,sex, andgenotyping_arrayis the following:python-mdeepnull.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, runpython-mdeepnull.main--help2>/dev/nullOf particular note is the--model_configflag. DeepNull uses theml_collectionslibrary to specify
all parameters related to the model and training regimen. The supported
configuration code is located inconfig.py, and parameters can
be modified as described in detail in theml_collections README.
As a brief example, to use the DeepNull architecture with theeluactivation
and train with batch size 4096, the above example command would be modified as
follows:python-mdeepnull.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=4096where/path/to/config.pyprovides the path toconfig.pyon your
machine.Incorporating DeepNull into a GWAS analysisThe 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 beaddedas an
additional covariate. A concrete example withBOLT-LMM, using the same file,
phenotypepheno, and covariatesage,sex,genotyping_arrayas above, is
shown below:Original example GWAS command# N.B. Data loading flags are omitted for brevity.bolt\--phenoFile/input/ORIGINAL_PHENOCOVAR_TSV\--covarFile/input/ORIGINAL_PHENOCOVAR_TSV\--qCovarColage\--qCovarColsex\--qCovarColgenotyping_array\--phenoColphenoAfter running DeepNull on the/input/ORIGINAL_PHENOCOVAR_TSVto create the new
TSV/output/PHENOCOVAR_WITH_DEEPNULL_PREDICTION_TSVthat includes the columnpheno_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\--qCovarColage\--qCovarColsex\--qCovarColgenotyping_array\--qCovarColpheno_deepnull\--phenoColphenoDataDatasets used to reproduce the results from the above publication are available
to researchers with approved access to theUK 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.