Changes

From Genome Analysis Wiki
Jump to: navigation, search

RAREMETAL Documentation

807 bytes removed, 13:22, 20 May 2019
Update contact address
[[Category:RAREMETAL]]
== Useful Wiki Pages ==
== Useful Wiki Pages ==* Git hub page: https://github.com/statgen/Raremetal
There are a few pages in this Wiki that may be useful to rareMETAL users. Here are links to key pages:* The [[RAREMETAL_Change_Log | Change Log]]
* The [[RAREMETALRAREMETAL_DOWNLOAD_%26_BUILD |RAREMETAL Home PageDOWNLOAD page]]
* The [[Tutorial:_RAREMETAL|RAREMETAL Quick Start Tutorial]]
* The [[RAREMETAL METHOD]]
* The [[RAREMETAL FAQ]]
* The [[RAREMETALWORKER|RAREMETALWORKER documentation]]
== Key Features =='''RAREMETAL''' has the following featuresThe [http:* '''RAREMETAL''' performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, and Variable Threshold//genome. * '''RAREMETAL''' performs single variant metal-analysis by defaultsph. * '''RAREMETAL''' allows customized groups of variants to be testedumich.* edu/wiki/Rvtests '''RAREMETALrvtests''' allows conditional analysis to be performed in both gene-level meta] tool for rare-variant association analysis and single variants meta-analysis.* '''can also generate output compatible with RAREMETAL''' generate QQ plots and manhattan plots by default.
== Brief Description ==
'''RAREMETAL''' is a computationally efficient tool for meta-analysis of rare variants using sequencing or genotyping array data. '''RAREMETAL''' It takes summary statistics and LD matrices generated by [[Rare-Metal-Worker|'''RAREMETALWORKER''']] or [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''], handles related and unrelated individuals, and supports both single variant and burden meta-analysis. '''RAREMETAL''' generated It generates high quality plots by default and has options that allow users to build reports at different levels. '''RAREMETAL''' is developed by Shuang Feng, Dajiang Liu and Gonçalo Abecasis. A R-package written by Dajiang Liu using the same methodology is [[RareMetals|'''available''']].
== Key Features =='''RAREMETAL''' is developed by Shuang Fenghas the following features:* Performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, Dajiang Liu and Gonçalo AbecasisVariable Threshold. A R* Performs single variant metal-package using the same methodology is [[RareMetals|available]]]analysis by default. * Allows customized groups of variants to be tested. Manuscript for this tool is * Allows conditional analysis to be performed in preparationboth gene-level meta-analysis and single variants meta-analysis. Please contact sfengsph at umich dot edu for questions* Generate QQ plots and manhattan plots by default.
== Approach ==
The key idea behind meta-analysis with RAREMETAL is that various gene-level test statistics can be reconstructed from single variant score statistics and that, when the linkage disequilibrium relationships between variants are known, the distribution of these gene-level statistics can be derived and used to evaluate signifi-cance. Single variant statistics are calculated using the Cochran-Mantel-Haenszel method. The main formulae are tabulated Our method has been published in the following[http{| border="1" cellpadding="5" cellspacing="0" align="center"|+'''Formulae for RAREMETAL'''! scope="col" width="120pt" | Test! scope="col" width="50pt" | Statistics! scope="col" width="225pt" | Null Distribution! scope="col" width="225pt" | Notation|-| Single Variant || <math>T=\sum_{i=1}^n {U_i}\bigg/\sqrt{\sum_{i=1}^n{V_i}}</math> || <math>T\sim\mathbf{N}(0,1)<www.nature.com/math> ||<math> U_i \text{ is the score statistic from study }i;</math><math> V_i \text{ is the variance of } U_i.<ng/math>|-| un-weighted Burden || <math>T_b=\sum_{i=1}^n{\mathbf{U_i}}\Bigjournal/\sqrt{\sum_{i=1}^n{\mathbf{V_i}}}<v46/math> || <math>T_b\sim\mathbf{N}(0,1)<n2/math> ||<math> \mathbf{U_i}\text{ is the vector of score statistics from study }i, or <abs/math> <math> \mathbf{U_i}=\{U_{i1},ng.2852.html '''Liu et.,U_{im}\};</math> <math>\mathbf{V_i} \text{ is the covariance of } \mathbf{U_i}al'''] in Nature Genetics.<Please go to [http:/math>|-| Weighted Burden || <math>T_{wb}=\mathbf{w^T}\sum_{i=1}^n{\mathbf{U_i}}\bigg/\sqrt{\mathbf{w^T}\left(\sum_{i=1}^n{\mathbf{V_i}}\right)\mathbf{w}}</math> || <math>T_{wb}\sim\mathbf{N}(0,1)</math> || <math> \mathbf{w^T}=\{w_1,w_2,genome.sph.umich.,w_m\}^T \text{ is the weight vector.}<edu/math>|-style="height: 50pt;"| VT || <math>T_{VT}=\max(T_{b\left(f_1\right)},T_{b\left(f_2\right)},\dots,T_{b\left(f_m\right)}),\text{ where}<wiki/math><math>T_{b\left(f_j\right)}=\boldsymbol{\phi}_{f_j}^\mathbf{T}\sum_{i=1}^n{\mathbf{U_i}}\bigg/\sqrt{\boldsymbol{\phi}_{f_j}^\mathbf{T}\left(\sum_{i=1}^n{\mathbf{V_i}}\right)\boldsymbol{\phi}_{f_j}} </math> ||<math> \left(T_{b\left(f_1\right)},T_{b\left(f_2\right)},\dots,T_{b\left(f_m\right)}\right)</math><math>\sim\mathbf{MVN}\left(\mathbf{0},\boldsymbol{\Omega}\right)\text{,} </math><math>\text{where }\boldsymbol{\Omega_{ij}}=\frac{\boldsymbol{\phi}_{f_i}^T\left(\sum_{i=1}^n{\mathbf{V_i}}\right)\boldsymbol{\phi}_{f_j}}{\sqrt{\boldsymbol{\phi}_{f_i}^T\left(\sum_{i=1}^n{\mathbf{V_i}}\right)\boldsymbol{\phi}_{f_i}}\sqrt{\boldsymbol{\phi}_{f_j}^T\left(\sum_{i=1}^n{\mathbf{V_i}}\right)\boldsymbol{\phi}_{f_j}}}</math> || <math> \boldsymbol{\phi}_{f_j}\text{ is a vector of } 0 \text{s and } 1\text{s,} </math> <math>\text{indicating the inclusion of a variant using threshold }f_j; </math> |-| SKAT || <math>\mathbf{Q}=\left(\sum_{i=1}^n{\mathbf{U_i^T}}\right) \mathbf{W}\left(\sum_{i=1}^n{\mathbf{U_i}}\right)</math> ||<math>\mathbf{Q}\sim\sum_{i=1}^m{\lambda_i\chi_{1,i}^2},\text{ where}</math> <math>\left(\lambda_1,\lambda_2,\dots,\lambda_m\right)\text{ are eigen values of}</math><math>\left(\sum_{i=1}^n{\mathbf{V_i}}\right)^\frac{1}{2}\mathbf{W}\left(\sum_{i=1}^n{\mathbf{V_i}}\right)^\frac{1}{2}</math> || <math>\mathbf{W}\text{ is a diagonal matrix of weightsRAREMETAL_method '''method'''] for details.}</math>|}
== Download and Installation ==
* University of Michigan CSG users can go to the following:
/net/fantasia/home/sfengsph/code/Rare-Metal/raremetal/bin/raremetal
=== Where to Download ===* The software package for We have tested compilation using our source code on several platforms including Linux , and Mac (source code included) can be downloaded here: [[Media:Raremetal.0.2.9.tarOS X.gz|'''software package download''']]
=== How For source code and executables together with instructions of building from source, please go to Compile ===* Save it to your local path [[RAREMETAL_DOWNLOAD_%26_BUILD |'''DOWNLOAD source and decompress using the following command: tar xvzf raremetal.0.2executables''']].9.tar.gz* Go to raremetal_0.2.9/raremetal/src and type the following command to compile: make
=== How to Execute ===* Go to raremetal_0.2.9/raremetal/bin and use the following: ./raremetal* For example usagequestions about compilation, please refer go to [[http://genome.sph.umich.edu/wiki/Rare-Metal#Example_Usage example command linesRAREMETAL_FAQ | '''FAQ''']].
== Basic Usage Instructions ==
'''raeMETALRAREMETAL''' is a command line tool. It is typically run from a Linux or Unix prompt by invoking the command <code>raremetal</code>. In the following are descriptions of basic usage for meta analysis. A detailed [[Tutorial:_RareMETAL|'''TUTORIAL''']] with toy data are also available.
==== Prepare Input Files====
'''rareMETALRAREMETAL''' requires the following basic input files: summary statistics and covariance matrices of score statistics generated by '''rareMetalWorkerRAREMETALWORKER'''or [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''], a file with list of studies to be included and a group file if gene-level meta-analysis is expected.  
=====Summary Statistics=====
Files containing summary statistics and LD matrices generated by '''rareMetalWorkerRAREMETALWORKER''' should be compressed and [http://samtools.sourceforge.net/tabix.shtml '''tabix'''] indexed using the following commands(Note in RAREMETALWORKER, if --zip is specified, these .gz and .tbi files will be automatically generated):
bgzip study1.singlevar.score.txt
bgzip study1.singlevar.cov.txt
tabix -s 1 -b 2 -e 2 -c "#" study1.singlevar.cov.txt.gz
 
Files containing summary statistics and LD matrices generated by '''rvtests''' should be compressed and [http://samtools.sourceforge.net/tabix.shtml '''tabix'''] indexed using the following commands:
 
bgzip study1.MetaScore.assoc
tabix -s 1 -b 2 -e 2 -S 1 study1.MetaScore.assoc.gz
tabix -s 1 -b 2 -e 2 -S 1 study1.MetaCov.assoc.gz
=====List of Studies=====
* --studyName summaryFiles option is crucial for '''rareMETALRAREMETAL''' to work. Ignoring this option would lead to FATAL ERROR and '''rareMETALRAREMETAL''' would stop.
* The file should contain the path and prefix of the studies you want to include.
* If there is one or more studies that you want to excluded from your list, but want to save some effort of generating a new file, you can put a "#" in front of the line of record. '''rareMETALRAREMETAL''' would automatically exclude that study from meta analysis.* An example list of summary file is in the following:
/net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/TwinsUK/TwinsUK.TG.singlevar.score.txt.gz #/net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/HUNT/RareMetalWorker/HUNT_MI_case.TG.singlevar.score.txt.gz
* The above When gene-level analysis is requested, --covFiles option should be used to specify the covariance files. An example study name file guides '''rareMETAL''' to look for summary statistics from TwinsUK study only, because "HUNT" study is commented out. The following two files are needed for '''rareMETAL''' to perform further analysis together with their tabix index file are needed.:
/net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/TwinsUK/TwinsUK.TG.singlevar.score.txt.gz
/net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/TwinsUK/TwinsUK.TG.singlevar.cov.txt.gz
#/net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/TwinsUKHUNT/RareMetalWorker/TwinsUKHUNT_MI_case.TG.singlevar.scorecov.txt.gz.tbi /net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/TwinsUK/* The above example study name file guides '''RAREMETAL''' to look for summary statistics from TwinsUKstudy only, because "HUNT" study is commented out.TG.singlevarThe following two files are needed for '''RAREMETAL''' to perform further analysis together with their tabix index file are needed.cov.txt.gz * Please sepcify --dosage option if input files were generated from dosage instead of genotype.tbi
=====Group Rare Variants=====
====== From an Annotated VCF File ======
If --groupFile option is '''NOT''' specified, '''rareMETALRAREMETAL''' will look for an annotated vcf file as blue print for variants to group. Users are also allowed to generate a vcf file based on the superset of variants from pooled samples, and annotate outside rareMETALRAREMETAL. Then, annotated vcf file can be used as input for rareMETAL RAREMETAL for gene-level meta-analysis, or group files can be generated based on the annotated vcf file. Detailed description of these options are [[Rare-Metal#Group_Rare_Variants_from_Annotated_VCF|'''available''']]. There are also [[Rare-Metal#Example_Command_lines|'''examples''']] of this usage at the bottom of this page.
==== QC Options ====
* '''rareMETALRAREMETAL''' allows filtering of variants from individual studies by their HWE pvalue and call rate, which are generated as part of the output from '''rareMetalWorkerRAREMETALWORKER'''or [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''].
* To filter by HWE p-values, --hwe option should be used. The default is 0.0, which means not filtering any of the variants.
* To filter by call rate, --callRate option can be specified. The default is 0.0, which allows no filtering utilized.
==== Association Options====
* Currently, CMC type burden test, Madsen-Browning burden test, Variable Threshold burden test and SKAT are provided in '''rareMETALRAREMETAL''', by specifying --burden, --MB, --VT and --SKAT.* --maf specifies the minor allele frequency cutoff when doing gene-based or group-based burden tests. Variants with maf '''above''' this threshold will be ignored. The default is maf<0.05.* In '''a single study''' of sample size N, if a site is monomorphic or not reported in vcf/ped, it is considered that the sample size of this study is not large enough to sample the rare allele. Thus, this study contributes 2*N reference alleles and 0 alternative allele towards meta-analysis. To let such studies contribute no alleles towards pooled allele frequency, specify --altMAF.
==== Conditional Analysis====
* To decide whether a signal is caused by shadowing a significant common variant nearby, '''rareMETALRAREMETAL''' also enables conditional analysis with a list of variants to be conditioned upon provided in a file as input for --condition option. An example input file should be space or tab delimited as in the following. When alleles do not match the ref and alt alleles from samples, the variant will be skipped from conditional analysis.
1:861349:C:T 1:905901:G:A 20:986998:G:C 22:3670691:A:G
== Additional Analysis Options ==
 
=== Generate a VCF File to Annotate Outside RAREMETAL ===
* --writeVCF allows user to write a VCF file including pooled single variants from all studies. Then users can use their favorite annotation tool to annotate the VCF file. After annotating the VCF file, users can use that file as input for '''RAREMETAL''' for further gene-based or region-based meta analysis.
* The output vcf file will be name as: yourPrefix.pooled.variants.vcf. An example output vcf file is in the following:
#CHROM POS ID REF ALT QUAL FILTER INFO
1 115658497 115658497 G A . . ALT_AF=0.380906;
2 74688884 74688884 G A . . ALT_AF=8.33611e-05;
3 121414217 121414217 C A . . ALT_AF=0.0747833;
===Annotation===
* RAREMETAL automatically recognizes the annotation format generated by [[TabAnno | '''ANNO''']] or [[EPACTS#Annotating_VCF_file_using_EPACTS | '''EPACTS''']].
* To annotate a the VCF generated in previous step, you can use the following command:
./anno --in your.in.vcf.gz --out your.out.vcf.gz
=== Group Rare Variants from Annotated VCF ===
* The annotated VCF file should be specified using --annotatedVcf option.
* --annotation should be used with --annotatedVcf together when specific category of functional variants are of interest to be grouped. For example, if grouping nonsynonymous and splicing variants are of interests, the following should be included in command line:
* (! only available after v4.13.8) when --annotation is not specified, raremetal groups all non-intergenic variants.
--annotatedVcf your.annotated.vcf --annotation nonsyn/splicing
* Notice that each variant is allowed to have more than one annotations; but each annotation should start with a new key "ANNO=" followed by annotation:genename:other transcript information.
 === Generate a VCF File to Annotate Outside of Rare Metal ===* --writeVCF allows user to write a VCF file including pooled single variants from all studies. Then users can use their favorite annotation tool to annotate the VCF file. After annotating the VCF file, users can use that file as input for '''RAREMETAL''' for further gene-based or region-based meta analysis.* The output vcf Generated group file will be name as: yourPrefix.pooled.variants.vcf. An example output vcf file is in the following: #CHROM POS ID REF ALT QUAL FILTER INFO 1 115658497 115658497 G A . . ALT_AF=0.380906; 2 74688884 74688884 G A . . ALT_AF=8.33611e-05; 3 121414217 121414217 C A . named test. ALT_AF=0groupfile under your running directory.0747833;
===Options for Report Generation===
EFFECT_SIZE: Alternative Allele Effect Size
DIRECTION_BY_STUDY: Effect size direction of alternative allele from each study.
The order of study is consistent with the order of studies listed in the input file for option --studyNamesummaryFiles.
"?" means the variant is not observed or monomorphic from the study.
"!" means the variant observed from this study has different alleles from those in the first study.
--tabulateHits [false]
--hitsCutoff [1e-06]
--dosage [false]
--altMAF [false]
==Example Command lines==
* Here is an example command line to do single variant meta analysis only:
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --prefix yourPrefix
* When you want to do all burden tests using a group file to specify which variants to group:
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --covFiles your.list.of.cov.files --groupFile your.groupfile --burden --MB --SKAT --VT --maf 0.01 --prefix yourPrefix
(NOTE: this will generate single variant meta analysis result and the short format output for burden test results.)
* Here is how to do all SKAT meta analysis using a group file and request a long format output together with tabulated hits:
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --covFiles your.list.of.cov.files --groupFile your.groupfile --SKAT --longOutput --tabulateHits --hitsCutoff 1.0e-07 --prefix yourPrefix
* Here is an example of adding QC filters to variants when doing meta analysis.
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --covFiles your.list.of.cov.files --groupFile your.groupfile --SKAT --longOutput --tabulateHits --hitsCutoff 1.0e-07 --hwe 1e-06 --callRate 0.98 --prefix yourPrefix
* Here is how to do the same thing but reading grouping information from an annotated VCF file:
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --covFiles your.list.of.cov.files --annotatedVcf your.annotated.vcf --annotation nonsyn/stop/splicing --SKAT --longOutput --tabulateHits --hitsCutoff 1.0e-07 --hwe 1e-06 --callRate 0.98 --prefix yourPrefix
* If you want to write a VCF file of pooled variants from all studies, annotate them using your favorite annotation program, and then come back to '''RAREMETAL''' with the annotate VCF file to do burden tests:
First, use the following command to write the VCF file:
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --writeVcf --prefix yourPrefix
Second, annotate the VCF file using your favorite annotation program. (Annotated VCF file has to follow the format described here: [[Rare-Metal#Group_Rare_Variants_from_Annotated_VCF|annotated VCF format]])
Third, use the following command to do meta analysis:
./raremetal --studyName summaryFiles your.studyNamelist.file of.summary.files --covFiles your.list.of.cov.files --annotatedVcf your.annotated.vcf --annotation nonsyn/splicing/stop --burden --MB --SKAT --VT --maf 0.01 --prefix yourPrefix ==Other Useful Info== * Summary specs can be found [[Summary Files Specification for RAREMETAL]]
==TUTORIAL==
[http://genome.sph.umich.edu/wiki/Tutorial:_RareMETAL '''RAREMETAL Tutorial''']
 
* For a brief tutorial of rvtests, please go to:
 
[http://genome.sph.umich.edu/wiki/Rvtests '''rvtests''']
==CONTACT==
Please email Shuang Feng Andy Boughton (sfengsph abought at umich dot edu) for questions.
== Change Log ==* Version 0.0.1 released to U of M CSG group. (2/13/2013)* Version 0.0.1 released to public. (2/24/2013)* Version 0.1.2 released to public after fixing a few bugs, adding conditional analysis Also check [[Raremetal Incoming updates | '''Known issues and automatic graphing incoming update in next version''']] to the tool. (8/5/2013)see if your problem has been reported before
30
edits

Navigation menu