Quickdraws GWAS Software Documentation

Quickdraws is a scalable method to perform genome-wide association studies (GWAS) for quantitative and binary traits. To run GWAS using Quickdraws, you will need three main input files: bed (and bgen) files with model-building and testing genetic variants, phenotype files, and covariate files. For certain analyses, you may also need a list of model SNPs and a file describing close genetic relatives.

0. Installation
1. Input Files
   • Required Input Files
   • Optional Input Files
2. Steps to Run Quickdraws
   • Step 0: Convert Bed File to HDF5 (Optional)
   • Quantitative Traits
     • Step 1
     • Step 2 (bed files)
     • Step 2 (bgen files)
   • Binary Traits
     • Step 1
     • Step 2 (bed files)
     • Step 2 (bgen files)
3. List of Options
   • Main Options for Step 1
   • Main Options for Step 2
4. Interpreting the Output
5. FAQs
   • Generating Model SNPs
   • Generating KING Table
   • Concatenating Summary Statistics
   • Using Regenie for Step 2
   • Participation-bias Corrected GWAS
   • Minimal Examples
   • Additional Details on Input/Output File Formats
   • Running on UK Biobank RAP
6. Citation

Installation

It is strongly recommended to either set up a python virtual environment, or a conda environment:

python -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel

conda create -n quickdraws python=3.11 -y
conda activate quickdraws
pip install --upgrade pip setuptools wheel

It is necessary for anything bigger than toy examples to use a cuda-enabled version of pytorch. Use the pytorch configuration helper to find suitable installation instructions for your system. The code snippet below will probably work for most systems:

pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install quickdraws

Input Files

1. Bed file: This contain the genotype data used to build the model (steps 0 and 1). Variants in a bed file can also be tested for association (Step 2).
2. Phenotype file: This files have the phenotype information (see Additional Details on Input/Output File Formats for format details).
3. Covariate file: This files include covariate data (see Additional Details on Input/Output File Formats for format details).
4. Kinship file: Used to calibrate test statistics in the presence of close relatives (for UKB can be found in RAP at Bulk/Genotype Results/Genotype calls/ukb_rel.dat, see Additional Details on Input/Output File Formats for format details).
5. Unrel Sample List file: A list of homogenous unrelated samples in the dataset (for UKB see resource 22021, see Additional Details on Input/Output File Formats for format details).

1. Bgen file: These contain the genotype data to be tested for association (Step 2).
2. Sample file: A .sample file associated with the bgen file recording sample FID and IID.
3. Model SNPs file: A list of SNPs for step 1 (optional, see Generating Model SNPs).
4. Extract SNPs file: A List of SNPs for which test statistics will be computed (one SNP ID per line, same format as Model SNPs file).

Steps to Run Quickdraws

Generate an HDF5 file corresponding to the Bed file for fast sample-wise access. This step is performed once per genetic dataset. This step can be skipped! - you can directly jump to Step 1 which will generate the HDF5 file as a preprocessing step, but it is best practice to generate the HDF5 file for the entire dataset once and reuse it later.

convert-to-hdf5 \
  --out master \
  --bed ${bed} \
  --modelSnps maf001.snps

This will convert the input ${bed} file into the HDF5 file master.hdf5. Only the SNPs listed in maf001.snps will be converted. The maf001.snps file should contain one SNP identifier per line; the identifier corresponds to the 2nd column of the BIM file.

Use spike-and-slab Bayesian linear regression to estimate genetic effects.

quickdraws-step-1 \
    --out ${output_step1} \
    --hdf5 master.hdf5 \
    --bed ${bed} \
    --phenoFile ${pheno} \
    --covarFile ${covar} \
    --modelSnps maf001.snps \
    --kinship kinship.txt

• ${output_step1}: File prefix where the output of Step 1 will be written.
• master.hdf5: Generated in Step 0 (optional).
• ${bed}: Bed file containing the model SNPs.
• ${pheno}: File containing phenotype data. See input/output file formats section for format details.
• ${covar}: File containing covariates. See input/output file formats section for format details.
• maf001.snps: List of SNPs for the regression (optional), described in Step 0.
• kinship.txt: Contains pairwise relatives up to the 3rd degree. This file can be produced using KING as implemented in PLINK (see FAQs for an example).

Generate summary statistics for SNPs in a bed file (e.g., the model SNPs).

quickdraws-step-2 \
   --out ${output_step2} \
   --bed ${bed} \
   --out_step1 ${output_step1} \
   --covarFile ${covar} \
   --unrel_sample_list unrelated_white_British.FID_IID.txt

• ${output_step2}: File prefix where results will be written.
• ${bed}: The Bed file containing the SNPs to be tested.
• ${output_step1}: The output file from Step 1.
• ${covar}: File containing covariates. See input/output file formats section for format details.
• unrelated_white_British.FID_IID.txt: List of unrelated homogeneous samples, or any other list of samples to be included in the calculation of test statistics. See input/output file formats section for format details.

Compute summary statistics for imputed data.

quickdraws-step-2 \
    --out ${output_step2} \
    --bgen ${bgen} \
    --sample ${sample} \
    --out_step1 ${output_step1}  \
    --calibrationFile ${output_step2}.calibration \
    --covarFile ${covar} \
    --extract snp_list.txt

• ${output_step2}: File prefix where results will be written.
• ${bgen}: The Bgen file containing the variants to be tested.
• ${sample}: File containing the list of samples to be included. See input/output file formats section for format details.
• ${output_step1}: The output file from Step 1.
• ${output_step2}.calibration: Calibration coefficients (produced in Step 2).
• ${covar}: File containing covariates. See input/output file formats section for format details.
• snp_list.txt: List of SNPs to test. Should contain one SNP identifier per line; the identifier correponds to the 2nd column of a bim file.

For binary traits, add the --binary and --h2_grid flags.

quickdraws-step-1 \
    --out ${output_step1} \
    --hdf5 master.hdf5 \
    --bed ${bed} \
    --phenoFile ${pheno} \
    --covarFile ${covar} \
    --modelSnps maf001.snps \
    --kinship kinship.txt \
    --binary \
    --h2_grid

Input/output files are as described for quantitative traits.

Add the --binary and --firth flags for Firth logistic regression.

quickdraws-step-2 \
   --out ${output_step2} \
   --bed ${bed} \
   --out_step1 ${output_step1} \
   --covarFile ${covar} \
   --unrel_sample_list unrelated_white_British.FID_IID.txt \
   --binary \
   --firth

Input/output files are as described for quantitative traits.

Compute summary statistics for imputed data.

quickdraws-step-2 \
    --out ${output_step2} \
    --bgen ${bgen} \
    --sample ${sample} \
    --out_step1 ${output_step1}  \
    --calibrationFile ${output_step2}.calibration \
    --covarFile ${covar} \
    --extract snp_list.txt \
    --binary \
    --firth

Input/output files are as described for quantitative traits.

List of options

You can use --help to get a full list of options for step 1 and step 2 as follows:

quickdraws-step-1 --help
quickdraws-step-2 --help

Interpreting the output

Quickdraws generates the following output files:

FAQs

We only run Step 1 on common genotyped SNPs in the data. One can get the list using PLINK:

plink --bfile genotype --freq --out all_snps
awk '$5 > 0.01' all_snps.frq > maf001.snps

You can use PLINK2 to calculate the KING table for up to 3rd degree relatives as follows:

plink2 --make-king-table --king-table-filter 0.044 --bfile genotype --out king

To combine summary statistics across multiple chromosomes, you can run:

git clone https://github.com/PalamaraLab/quickdraws.git
cd quickdraws
python src/concat_sumstats.py --out ${out}

Quickdraws saves LOCO predictions from Step 1 in the same format as Regenie, so can be easily combined with Regenie. To calculate test statistics through Regenie (tested on Regenie v3.1) For Quantitative traits, run:

regenie \
   --step 2 \
   --pred ${output}_pred.list \
   --bed ${bed} \ 
   --phenoFile ${output}.traits \
   --covarFile ${covarFile} \
   --out ${output}

where ${output}_pred.list is a list of files containing the LOCO predictions, one line per trait, and ${output}.traits is a list of files containing post-processed traits from Quickdraws, in the same order. For Binary traits:

regenie \
   --step 2 \
   --pred ${output}_pred.list \ 
   --bed ${bed} \
   --phenoFile ${output}.traits \
   --covarFile ${covarFile} \
   --out ${output} \
   --bt \
   --firth \ 
   --approx \
   --pThresh 0.05 

NOTE: the summary statistics produced through this approach are not necessarily calibrated, as Regenie does not perform a calibration step.

We perform a weighted linear regression to correct for participation-bias in Step 2 of the algorithm. This is done by specifying a sampling weights file (see Schooleler et al. 2023 for ways to generate this).

quickdraws-step-2 \
   --out ${output} \
   --bed ${bed} \
   --out_step1 ${output} \
   --covarFile ${covar} \
   --unrel_sample_list unrelated_white_British.FID_IID.txt \
   --sampling_weights sampling_weights.txt 

Once you install quickdraws, two executables should be available in your path: quickdraws-step-1 and quickdraws-step-2. Clone the Git repository to access the example data and script demonstrating how these can be used:

git clone https://github.com/PalamaraLab/quickdraws.git
cd quickdraws
bash run_example.sh

The file formats for various input files are as follows:

1. Bed files: Genotypes stored in plink v1 .bed/.fam/.bim files used for model fitting, concatenated across chromosomes.
2. Bgen files: Dosages stored in plink v2 .bgen/.sample files used for test statistics calculation, can be separated across chromosomes.
3. Phenotype files: tab-separated phenotype values for samples, each row corresponds to “FID IID Trait1 Trait2 ..” Example:

FID IID Trait1 Trait2 Trait3
10001 10001 3.121 2.121 nan
10002 10002 1.178 8.21 -1.23
10004 10004 -1.012 -5.12 1.02

4. Covariate files: tab-separated phenotype values for samples, each row corresponds to “FID IID Var1 Var2 ..”, binary or ordinal covariates are to be encoded as numerics. Example:

FID IID Var1 Var2 Var3
10001 10001 1 5.1121 6.12
10002 10002 0 nan 81.23
10004 10004 1 -3.19 4.12

5. Kinship file: Used to calibrate test statistics in the presence of close relatives. The file should be tab-separated and have the following columns “ID1”, “ID2” and “Kinship” which stores the Kinship between ID1 and ID2. Example:

ID1 ID2 Kinship
10001 10002 0.15
10004 10001 0.26
10005 10010 0.07

6. Unrel Sample List file: A list of homogenous unrelated samples in the dataset. The file should be tab-separated and record FID IID pairs of individuals which are unrelated and are homogenous. Example:

10001 10001
10003 10003
10005 10005

6. Model SNPs file: A list of SNP IDs (corresponding to the 2nd column of the .bim file) one per line. Example:

rs123131
rs321219
10_3512121_CT_T

7. Extract SNPs file: Useful to run association step for only a subset of variants, contains a list of SNP IDs one per line similar to model SNPs file.

see UK Biobank RAP Tutorial

If you use this software, please cite:

H. Loya, G. Kalantzis, F. Cooper, P. F. Palamara. A scalable variational inference approach for increased mixed-model association power. bioRxiv, 2024.