This page explains how to calculate pathway taggings for use with LDAK-PBAT. Please note that this is only necessary when using non-human data, or if you would like to use your own gene pathways or reference panel; otherwise, it generally suffices to use pre-computed pathway taggings.
To construct pathway taggings, you require gene annotations, pathway annotations and a Reference Panel. You can download human gene and pathway annotations from Resources. If you wish to use your own pathway annotations, then these should be saved in a text file with one row for each pathway; each row should start with the pathway name, then provide a list of one or more genes. For example, suppose the pathway annotations file contains the following two rows
CORONEL_RFX7 ABAT DIP2A
FOROUTAN_TGFB ABCA1 ACTN1 JAG1
This file provides details for two pathways; the first is named CORONEL_RFX7, and contains two genes (ABAT & DIP2A); while the second is named FOROUTAN_TGFB and contains three genes (ABCA1, ACTN1 & JAG1). Please note while not identical to, this format is compatible with the gmt format used by MSigDB.
Always read the screen output, which suggests arguments and estimates memory usage.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Map predictors to genes and pathways:
The main argument is --cut-genes <folder>.
This requires the options
--bfile/--gen/--sp/--speed <datastem> or --bgen <datafile> - to specify the genetic data files (see File Formats).
--genefile <genefile> - to specify the gene annotations. The first four columns of <genefile> should specify the name, chromosome, start and end basepairs of each gene. If there is a fifth column, its value should be either + or -, indicating whether the gene is on the forward or backwards strand. Note that the basepairs should provide 0-start, half-open positions (this is the format used by Browser Extensible Data). For example, if Gene ABC is on Chromosome 7 and contains basepairs 1-10, inclusive, the corresponding row of <genefile> would be "ABC 7 0 10" (if providing strand orientation, the row would be either "ABC 7 0 10 +" or "ABC 7 0 10 -").
--pathfile <pathfile> - to specify the pathway annotations. Each row of <pathfile> should contain the name of a pathway, followed by the genes within this pathway (see the top of this page for an example).
By default, LDAK will only consider predictors inside genes. To change this, you can use --gene-buffer <integer>, --up-buffer <integer> or --down-buffer <integer>. For example, if you use --gene-buffer 500, each set will contain predictors inside or within 500bp of a gene. Note that you can only use --up-buffer and --down-buffer if <genefile> provides the orientation of the gene (i.e., has five columns). If you add --overlap NO, LDAK will ensure that each predictor is only allocated to the nearest gene.
The output file <folder>/genes.predictors.used lists which predictors belong to any gene. Meanwhile, the files <folder>/pathway.details and <folder>/pathway.names provide details for the pathways that contained one or more predictors, while the files with prefix <folder>/pathway list the predictors within each pathway (e.g., <folder>/pathway1 and <folder>/pathway2 contain the predictors in the first and second pathways, respectively).
Please note that more details on this command are provided in Gene-Based Analysis.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Calculate pathway taggings:
The main argument is --calc-tagging <outfile>
This requires the options
--bfile/--gen/--sp/--speed <datastem> or --bgen <datafile> - to specify the genetic data files (see File Formats).
--power <float> - to specify how predictors are scaled. In general, we recommend using --power -0.25 (for more details on this parameter, see Technical Details).
--genic-predictors <genpreds> - to specify which predictors belong to any gene (the required file was created above using the command --cut-genes).
--annotation-number <integer> and --annotation-prefix <prefix> - to specify which predictors belong to each pathway (the required files were created above using the command --cut-genes). For example, if there are three pathways, whose predictors are stored in the files path1, path2 and path3, you should use --annotation-number 3 and --annotation-prefix path.
--labels <labfile> - to specify predictor names (the required file was created above using the command --cut-genes).
The pathway taggings are saved in the files <output>.base.tagging, <output>.pathway.tagging and <output>.pathway.sums.
Note that when calculating taggings for very many pathways (e.g., more than 1000), it is advisable to parallelize this process. This can be achieved by using --partition <integer> to calculate taggings separately for subsets of 100 pathways, then combining the subset-specific taggings using the command --merge-tagging <output> with the option --pathlist <pathstems> (see the example below).
Please note that more details on this command are provided in Calculate Taggings.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Example:
Here we use the binary PLINK files human.bed, human.bim and human.fam, and the annotations files anns.txt and pathways.txt from the Test Datasets. The file anns.txt contains (real) details for 927 human genes on Chromosomes 21 & 22, while the file pathways.txt contains details for 245 (fake) gene pathways.
Note that when analysing real data, you should use a much larger reference panel (e.g., imputed or sequence data, retaining all SNPs with MAF>.005 and information score >.8). For more details, see Reference Panel.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
To map predictors to genes and pathways, run the command
./ldak.out --cut-genes map --bfile human --genefile anns.txt --pathfile pathways.txt
The screen output states that 138 of the 927 genes were found, and that 128 of the 245 pathways contain predictors. The key output files are map/gene.predictors.used (this states which predictors are genic), map/pathway.names (this provides the names of the retained pathways) and the files with prefix map/pathway (e.g., map/pathway1, map/pathway2 and map/pathway3 list the predictors belonging to the first three pathways).
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
To construct pathway taggings, run the command
./ldak.out --calc-tagging tags --bfile human --power -.25 --genic-predictors map/genes.predictors.used --annotation-number 128 --annotation-prefix map/pathway --labels map/pathway.names
The pathway taggings are saved in the files tags.base.tagging, tags.pathway.tagging and tags.pathway.sums. These are now ready to be used with LDAK-PBAT.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
When analysing real data, which usually contains very many predictors and pathways, the above command will take a very long time. Therefore, we recommend calculating taggings for subsets of 100 pathways, then merging the taggings across subsets. This is achieved using the commands
for j in {1..2}; do
./ldak.out --calc-tagging tags2 --bfile human --power -.25 --genic-predictors map/genes.predictors.used --annotation-number 128 --annotation-prefix map/pathway --labels map/pathway.names --partition $j
done
./ldak.out --merge-tagging tags2 --pathlist tags2.merge.list
Note that in these scripts, we loop from 1 to 2, because there the 128 pathways are divided into two pathways; for real data, you will likely have many more partitions.
The pathway taggings are saved in the files tags2.base.tagging, tags2.pathway.tagging and tags2.pathway.sums (these files should be identical to those calculated without parallelization).
