Difference between revisions of "RAREMETAL Documentation"
(→From an Annotated VCF File)
(→From an Annotated VCF File)
|Line 117:||Line 117:|
====== From an Annotated VCF File ======
====== From an Annotated VCF File ======
If --groupFile option is '''NOT''' specified, '''rareMETAL''' 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 rareMETAL. Then, annotated vcf file can be used as input for 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 examples of this usage at the bottom of this page.
If --groupFile option is '''NOT''' specified, '''rareMETAL''' 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 rareMETAL. Then, annotated vcf file can be used as input for 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 examplesof this usage at the bottom of this page.
==== QC Options ====
==== QC Options ====
Revision as of 22:32, 7 August 2013
rareMETAL is a tool for gene-based meta-analysis, based upon summary statistics generated from individual data using Rare Metal Worker. Another implementation of the same methods in R-package can be found RareMetals.
If you have any questions, please contact: sfengsph at umich dot edu
- 1 Useful Wiki Pages
- 2 Key Features
- 3 Brief Description
- 4 Approach
- 5 Download and Installation
- 6 Basic Usage Instructions
- 7 Additional Analysis Options
- 8 Results Reported by rareMETAL
- 9 Example Command lines
- 10 TUTORIAL
- 11 Change Log
Useful Wiki Pages
There are a few pages in this Wiki that may be useful to rareMETAL users. Here are links to key pages:
- The rareMETAL FAQ
rareMETAL has the following features:
- rareMETAL performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, and Variable Threshold.
- rareMETAL performs single variant metal-analysis by default.
- rareMETAL allows customized groups of variants to be tested.
- rareMETAL allows conditional analysis to be performed in both gene-level meta-analysis and single variants meta-analysis.
- rareMETAL generated QQ plots and manhattan plots by default.
rareMETAL is a tool for meta-analysis rare variants from genotype arrays and sequencing. rareMETAL can combine summary statistics of individual studies generated by rareMetalWorker. It provides a convenient approach for both single variant and gene-level meta-analysis of rare variants from various studies, when joint-analysis of raw data from these studies are restricted.
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 in the following:
Download and Installation
- University of Michigan CSG users can go to the following:
Where to Download
- The software package for Linux and Mac (source code included) can be downloaded here: software package download
How to Compile
- Save it to your local path and decompress using the following command:
tar xvzf raremetal.0.1.5.tgz
- Go to raremetal_0.1.5/raremetal/src and type the following command to compile:
How to Execute
- Go to raremetal_0.1.5/raremetal/bin and use the following:
- For example usage, please refer to [example command lines]
Basic Usage Instructions
raeMETAL is a command line tool. It is typically run from a Linux or Unix prompt by invoking the command
raremetal. In the following are descriptions of basic usage for meta analysis. A detailed TUTORIAL with toy data are also available.
Prepare Input Files
rareMETAL requires the following basic input files: summary statistics and covariance matrices of score statistics generated by rareMetalWorker, a file with list of studies to be included and a group file if gene-level meta-analysis is expected.
Files containing summary statistics and LD matrices generated by rareMetalWorker should be compressed and tabix indexed using the following commands:
bgzip study1.singlevar.score.txt tabix -s 1 -b 2 -e 2 -c "#" study1.singlevar.score.txt.gz
bgzip study1.singlevar.cov.txt tabix -s 1 -b 2 -e 2 -c "#" study1.singlevar.cov.txt.gz
List of Studies
- --studyName option is crucial for rareMETAL to work. Ignoring this option would lead to FATAL ERROR and rareMETAL 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. rareMETAL would automatically exclude that study from meta analysis.
- An example file is in the following:
- The above 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/TwinsUK/TwinsUK.TG.singlevar.score.txt.gz.tbi /net/fantasia/home/sfengsph/prj/raremetal/raremetal/bin/META/TwinsUK/TwinsUK.TG.singlevar.cov.txt.gz.tbi
Group Rare Variants
From a Group File
- With --groupFile option, you can specify particular set of variants to be grouped for burden tests.
- The group file must be a tab or space delimited file in the following format:
GROUP_ID MARKER1_ID MARKER2_ID MARKER3_ID ...
- MARKER_ID must be in the following format:
- An example group file is:
From an Annotated VCF File
If --groupFile option is NOT specified, rareMETAL 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 rareMETAL. Then, annotated vcf file can be used as input for rareMETAL for gene-level meta-analysis, or group files can be generated based on the annotated vcf file. Detailed description of these options are available. There are also examples of this usage at the bottom of this page.
- rareMETAL allows filtering of variants from individual studies by their HWE pvalue and call rate, which are generated as part of the output from rareMetalWorker.
- Currently, CMC type burden test, Madsen-Browning burden test, Variable Threshold burden test and SKAT are provided in rareMETAL, by specifying --burden, --MB, --VT and --SKAT.
- --maf specifies the minor allele frequency cutoff when doing gene-based or group-based burden tests. The default is maf<0.05.
Conditional Analysis Options
- To decide whether a signal is caused by shadowing a significant common variant nearby, rareMETAL 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
Group Rare Variants from Annotated VCF
- If --groupFile option is NOT specified, rareMETAL will look for an annotated vcf file as blue print for variants to group.
- The annotated VCF file should be specified using --annotatedVcf option.
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.
Options for Report Generation
- --prefix allows customized prefix for output files.
- --tabulateHits works with --hitsCutoff together to generate reports for genes that have p-value less than specified cutoff from burden tests or SKAT. The default cutoff of p-value for genes to be reported is 1.0e-06, which can be specified by --hitsCutoff option. For more explanations and examples, please go to [Tabulated Top Hits].
- --tabix allows rapid analysis when number of groups/genes of interests are small. Currently, when number of groups is less than 100, --tabix option is automatically turned on.
Results Reported by rareMETAL
Single Variant Meta Analysis Output
- Single variant meta analysis output has the following components: header and results.
- Header line starts with "#" are column headers for results table.
- An example single variant meta analysis output is shown below:
- A detailed explanation of each column is in the following:
CHROM: Chromosome Name POS: Variant Position REF: Reference Allele Label ALT: Alternative Allele Label POOLED_ALT_AF: Pooled Alternative Allele Frequency 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 --studyName. "?" 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.
rareMETAL generates QQ plots and manhattan plots from single variant meta-analysis by default. Three QQ plots are generated, one with all variants included, one of variants with maf<0.05 and one of variants with maf<0.01. All plots are saved in a pdf file named yourPrefix.meta.plots.pdf. Genomic controls are also reported in the title of plots. When --correctGC option is specified, GC corrected plots are also generated.
Burden Tests Meta Analysis Output
When --longOutput is used, output includes both burden test results of genes and single variant results of the variants included in burden tests. Here is an example of output file from SKAT when --longOutput is specified.
Otherwise, single variant results of variants included in burden tests will not be included in the output. Here is an example of output file from SKAT when --longOutput is not specified.
- Tabulated top hits are saved in the file:
- The following items are tabulated in the output:
rareMETAL generates QQ plots and manhattan plots from single variant and gene-level meta-analysis by default. Example QQ plots and manhattan plots are:
- A log file is automatically generated by Rare Metal to save the parameters in effect. An example is in the following:
The following parameters are in effect: List of Studies: ============================ --studyName [studyName.SardiNia] Grouping Methods: ============================ --groupFile  --annotatedVcf [../../groupvcf/bin/debug/nonsynonymous.vcf] --annotation  --writeVcf [OFF] QC Options: ============================ --hwe  --callRate  Association Methods: ============================ --burden [true] --MB [false] --SKAT [false] --VT [false] Other Options: ============================ --prefix [test] --maf [0.05] --longOutput [false] --tabulateHits [false] --hitsCutoff [1e-06]
Example Command lines
- Here is an example command line to do single variant meta analysis only:
./raremetal --studyName your.studyName.file --prefix yourPrefix
- When you want to do all burden tests using a group file to specify which variants to group:
./raremetal --studyName your.studyName.file --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.)
./raremetal --studyName your.studyName.file --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 your.studyName.file --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 your.studyName.file --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 Rare Metal with the annotate VCF file to do burden tests:
First, use the following command to write the VCF file: ./raremetal --studyName your.studyName.file --writeVcf --prefix yourPrefix Second, annotate the VCF file using your favorite annotation program. (Annotated VCF file has to follow the format described here: [annotated VCF format]) Third, use the following command to do meta analysis: ./raremetal --studyName your.studyName.file --annotatedVcf your.annotated.vcf --annotation nonsyn/splicing/stop --burden --MB --SKAT --VT --maf 0.01 --prefix yourPrefix
- For a comprehensive tutorial of RareMetalWorker and RareMETAL using example data sets, please go to the following:
- 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.0 released to public after fixing a few bugs, adding conditional analysis and automatic graphing to the tool. (8/5/2013)