Genome Analysis Wiki - User contributions [en]

Minimac3

2022-10-18T19:40:35Z

Abought: Add category tag to improve findability

* '''New Version [[Minimac4]] available ! Please Check out !!!'''

* '''Please join our NEW [https://groups.google.com/forum/embed/?place=forum/minimac4-help#!forum/minimac4-help mailing list] to get updates about future releases, bug fixes or post queries.'''

* '''No further development on Minimac3 !!!''' See [[Minimac3 ChangeLog | ChangeLog ]] for details !!!

= Useful Wiki Pages =

There are a few pages in this Wiki that may be useful to for '''Minimac3''' users. Here are links to a few:

* [[Minimac3| Minimac3 Overview Page]]

* [[Minimac3 Usage | Minimac3 Usage and Documentation]]

* [[Minimac3 Imputation Cookbook]] ('''Recommended for New Users!!''')

* [[Minimac3 Cookbook : Chromosome X Imputation| Chromosome X Imputation]]

* [[Minimac3 Examples| Minimac3 Examples]]

* [[Minimac3 Info File| Minimac3 Info File]]

* [[Minimac3 ChangeLog | Minimac3 ChangeLog ]]

* [[M3VCF Files| M3VCF Files]]

= Introduction =

'''Minimac3 ''' is a lower memory and more computationally efficient implementation of the genotype imputation algorithms in [[Minimac|minimac]] and [[Minimac2|minimac2]]. '''Minimac3''' is designed to handle very large reference panels in a more computationally efficient way with no loss of accuracy. It accomplishes this by identifying repeat haplotype patterns and using these to simplify the underlying calculations, with no loss of accuracy.

Minimac3 uses [[M3VCF Files|M3VCF files]] (customized minimac3 VCF files) to store reference panel information in a compact form, thus saving on memory and time required to read large datasets. Users can use Minimac3 to convert standard VCF files to M3VCF files. M3VCF files can also store pre-calculated estimates of recombination fraction and error, which speeds up later rounds of imputation. Minimac3 outputs results in the form of standard VCF files for easy data manipulation in downstream analysis.

= Download =

'''Minimac3 ''' is currently available as a release version. Commonly used reference panels in M3VCF format are available for download in [[#Reference Panels for Download | Reference Panels]].

'''Please join our NEW [https://groups.google.com/forum/embed/?place=forum/minimac4-help#!forum/minimac4-help mailing list] to get updates about future releases or report possible bugs or email them to [mailto:sayantan@umich.edu Sayantan Das].'''

'''VERSION: 2.0.1 !!! (Updated 6.6.2016) !!!'''

'''Github Repo:''' Users can clone from github repository as well : [https://github.com/Santy-8128/Minimac3 Minimac3 Github]

'''Cloning from GitHub is recommened so that updates can be easily pulled back !!!'''

{| class="wikitable" style="text-align:center" border="1" cellpadding="2"
|- bgcolor="lightgray"
! Description
! Download Link
|-
| Source Files
| [ftp://share.sph.umich.edu/minimac3/Minimac3.v2.0.1.tar.gz UNIX Users ]
|-
| Binary Executable †
| [ftp://share.sph.umich.edu/minimac3/Minimac3Executable.tar.gz UNIX Users ]
|}

'''†''' Binary executables are NOT guaranteed to run on every LINUX machine. Please compile from source files if you have trouble with the executable, or else contact the author [mailto:sayantan@umich.edu Sayantan Das]..

= Usage=

Users should follow the following steps to compile '''Minimac3''' (if they downloaded the source files) or should skip them (if they downloaded the binary executable).

## DOWNLOAD, EXTRACT MINIMAC3 AND COMPILE
 
wget ftp://share.sph.umich.edu/minimac3/Minimac3.v2.0.1.tar.gz
tar -xzvf Minimac3.v2.0.1.tar.gz
cd Minimac3/
make

A typical '''Minimac3''' command line for imputation is as follows

../bin/Minimac3 --refHaps refPanel.vcf \
--haps targetStudy.vcf \
--prefix testRun

Here refPanel.vcf is the reference panel used in VCF format (e.g. 1000 Genomes), targetStudy.vcf is the phased GWAS data in VCF format, and testRun is the prefix for the output files. Some commonly used reference panels are available for download in [[Minimac3 Imputation Cookbook#Reference Panels for Download| Reference Panels]]. See wiki page on [[Minimac3 Usage| Detailed Usage]] and [[Minimac3 Imputation Cookbook|Imputation Cookbook]] for further details on using '''Minimac3''' for imputation analysis.

Users can always type the following for further support:

/bin/Minimac3 --help

= Reference Panels for Download =

Some commonly used reference panels are available for download here:

'''Chr X Haplotypes for 1000 Genomes Phase 3 have been updated on Oct 20 to include multi-allelic variants as well (split as bi-allelic variants) !!!'''

{| class="wikitable" style="text-align:center" border="1" cellpadding="2"
|- bgcolor="lightgray"
! width="150px" |Reference Panel
! width="100px" |Number of Samples
! width="100px" |File Format
! width="100px" |Parameter Estimates Available
! width="120px" |Chromosomes
! width="80px" |Link
|-
| rowspan=4 | '''1000 Genomes''' 
'''Phase 3''' 
(version 5)
| rowspan=4 style="text-align:center" | '''2,504'''
| '''VCF'''
| -
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_VCF_Files.tar.gz Download] 
|-
| rowspan=2 style="text-align:center" | '''M3VCF'''
| YES
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_M3VCF_FILES_WITH_ESTIMATES.tar.gz Download] 
|-
|NO
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_M3VCF_FILES_NO_ESTIMATES.tar.gz Download] 
|-
| '''VCF''','''M3VCF'''
| YES
| X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_CHR_X_VCF_M3VCF_FILES.tar.gz Download] 
|-
| rowspan=4 | '''1000 Genomes''' 
'''Phase 1''' 
(version 3)
| rowspan=4 | '''1,092'''
| '''VCF'''
| -
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_VCF_Files.tar.gz Download]
|-
| rowspan=2 style="text-align:center" | '''M3VCF'''
| YES
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_M3VCF_FILES_WITH_ESTIMATES.tar.gz Download]
|-
| NO
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_M3VCF_FILES_NO_ESTIMATES.tar.gz Download]
|-
| '''VCF''','''M3VCF'''
| YES
| X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_CHR_X_VCF_M3VCF_FILES.tar.gz Download] 
|}

= Reference =

If you use [[minimac3]] please cite:

''Das S, Forer L, Schönherr S, Sidore C, Locke AE'' et al. Next-generation genotype imputation service and methods. Nature Genetics 2016; 48, 1284–1287 (2016) doi:10.1038/ng.3656[http://www.nature.com/ng/journal/v48/n10/full/ng.3656.html]

= Contact =

In case of any queries and bugs please contact [mailto:sayantan@umich.edu Sayantan Das].

[[Category:Software]]

Minimac4

2022-10-18T18:10:54Z

Abought: Add category tag to improve findability

= Introduction =

'''Minimac4 ''' is a latest version in the series of genotype imputation software - preceded by [[Minimac3|Minimac3]] (2015), [[Minimac2|Minimac2]] (2014), [[Minimac|minimac]] (2012) and [[MaCH|MaCH]] (2010). '''Minimac4''' is a lower memory and more computationally efficient implementation of the original algorithms with comparable imputation quality.

The Minimac3 mailing list has been renamed as the Minimac4 mailing list. If you were already a member, no need to re-join. If not, please join our [https://groups.google.com/forum/embed/?place=forum/minimac4-help&umich.edu| mailing list] to get updates about future releases or report possible bugs or email them to [mailto:yukt@umich.edu Ketian Yu] or [mailto:sayantan@umich.edu Sayantan Das].'''

= Installation =

'''Minimac4 (version 1.0.0, released 2.14.2018)''' is currently available on [https://github.com/Santy-8128/Minimac4 Minimac4 Github].

The easiest way to install Minimac4 and its dependencies is to use the install.sh file provided.
git clone <nowiki>https://github.com/statgen/Minimac4.git</nowiki>
cd Minimac4
bash install.sh

Please see [https://github.com/Santy-8128/Minimac4 Minimac4 Github] for the full instructions for installation.

Commonly used reference panels in M3VCF format are available for download in [[#Reference Panels for Download | Reference Panels]].

= What's New =

The input file format, output file formats and typical command lines are the same in Minimac4 (as they were in minimac3). Some of the main new features are summarized below:

* '''Improved Speed - ''' Minimac4 is approximately '''6 times''' faster for 1000 Genomes Phase 1 and Phase 3 and '''2 times''' faster for the HRC reference panels at comparable accuracy (details of accuracy for imputing into 10 European samples are given here). The speed can be further improved by tuning the approximation parameters (see below), but we recommend using the default values.

* '''Automated Chunking - ''' Minimac4 automatically chunks the whole chromosome (into overlapping chunks), analyzes each chunk sequentially and then concatenates the imputed chunks back. This caps the memory usage across different chromosomes (memory requirement is based on chunk size, not chromosome size). The length of the chunk and the overlap can be controlled by the <code>--chunkLengthMb</code> and <code>--chunkLengthOverlapMb</code> options, although we recommend using the default values of 20 and 3, respectively.

* '''Approximations - ''' Minimac4 uses some simple approximations to speed up the imputation analyses. The levels of approximation can be controlled by the parameters <code>--probThreshold</code>, <code>--diffThreshold</code>, and <code>--topThreshold</code> (details given in Minimac4 Usage). Higher levels of approximation will reduce the compute time but marginally reduce the imputation accuracy. We recommend using the default values (0.01).

* '''Improved Chromosome X/Y Support - ''' Minimac4 can handle different ploidys in the same VCF file for imputation of sex chromosomes. For example, for the non-PAR region on chromosome X, males and females can be imputed together, irrespective of whether males are coded as haploids or diploids. However, each sample must have a fixed ploidy. Thus, PAR and non-PAR regions still need to be imputed separately. Please see Chromosome X Imputation for more details.

* '''Other Helpful Features'''
** We introduced a new feature called <code>--memUsage</code> that will estimate and report the memory required by Minimac4. This feature should be useful for users running their jobs on a compute cluster that requires memory specification.
** We introduced some other FORMAT options for the output dosage data, allowing users to retrieve haplotype dosages, genotype probabilities, genotype dosages or any other measure of summary that they want.
** We have fixed the bug related to FILTER=GENOTYPED and FILTER=GENOTYPED_ONLY which was causing a crash in bcftools.

* '''Obsolete Features'''
** In Minimac4, we removed the <code>--doseOutput</code> and <code>--hapOutput</code> options. Please use [[DosageConvertor]] to convert your files to MaCH or PLINK dosage format.
** Currently Minimac4 can ONLY handle M3VCF format files. If your reference panel is in VCF format, please use [[Minimac3]] to convert the VCF file to M3VCF (along with parameter estimation) and then use that M3VCF for imputation using Minimac4. The same holds for the option <code>--processReference</code> as well. Although the handle is made available, we will implement it in a later version.
** Parameters such as <code>--rounds</code>, <code>--states</code>, <code>--rec</code>, <code>--err</code> have been deactivated for now until we implement parameter estimation in minimac4.

= Usage =
A typical Minimac4 command line for imputation is as follows

minimac4 --refHaps refPanel.m3vcf \
--haps targetStudy.vcf \
--prefix testRun

Here refPanel.m3vcf is the reference panel used in M3VCF format (e.g. 1000 Genomes), targetStudy.vcf is the phased GWAS data in VCF format, and testRun is the prefix for the output files.

=== Full List of Options ===
Please see '''[[Minimac4 Documentation]]''' for detailed explanation of all available options.

Also, users can always type the following for the full list of available options:
minimac4 --help

=== Convert VCF to M3VCF ===
If the reference panel is in VCF format, please use [[Minimac3]] to convert it into M3VCF format first.
../bin/Minimac3 --refHaps refPanel.vcf \
--processReference \
--prefix refPanel

=== Multi-Threading ===
The following example shows the same analysis as above, but using 5 threads:

minimac4 --refHaps refPanel.m3vcf \
--haps targetStudy.vcf \
--prefix testRun \
--cpus 5

= Reference Panels for Download =

Some commonly used reference panels are available for download here:

{| class="wikitable" style="text-align:center" border="1" cellpadding="2"
|- bgcolor="lightgray"
! width="150px" |Reference Panel
! width="100px" |Number of Samples
! width="100px" |File Format
! width="100px" |Parameter Estimates Available
! width="120px" |Chromosomes
! width="80px" |Link
|-
| rowspan=4 | '''1000 Genomes''' 
'''Phase 3''' 
(version 5)
| rowspan=4 style="text-align:center" | '''2,504'''
| '''VCF'''
| -
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_VCF_Files.tar.gz Download] 
|-
| rowspan=2 style="text-align:center" | '''M3VCF'''
| YES
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_M3VCF_FILES_WITH_ESTIMATES.tar.gz Download] 
|-
|NO
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_M3VCF_FILES_NO_ESTIMATES.tar.gz Download] 
|-
| '''VCF''','''M3VCF'''
| YES
| X
| [ftp://share.sph.umich.edu/minimac3/G1K_P3_CHR_X_VCF_M3VCF_FILES.tar.gz Download] 
|-
| rowspan=4 | '''1000 Genomes''' 
'''Phase 1''' 
(version 3)
| rowspan=4 | '''1,092'''
| '''VCF'''
| -
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_VCF_Files.tar.gz Download]
|-
| rowspan=2 style="text-align:center" | '''M3VCF'''
| YES
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_M3VCF_FILES_WITH_ESTIMATES.tar.gz Download]
|-
| NO
| 1-22,X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_M3VCF_FILES_NO_ESTIMATES.tar.gz Download]
|-
| '''VCF''','''M3VCF'''
| YES
| X
| [ftp://share.sph.umich.edu/minimac3/G1K_P1_CHR_X_VCF_M3VCF_FILES.tar.gz Download] 
|}

= Useful Wiki Pages =

There are a few pages in this Wiki that may be useful to for '''Minimac4''' users. Here are links to a few:

* [[Minimac4| Minimac4 Overview Page]]

* [[Minimac4 Documentation]]

* [[M3VCF Files| M3VCF Files]]

[[Category:Software]]

LocusZoom Standalone

2021-11-18T22:03:24Z

Abought:

{| align="right"
|-
| __TOC__
|}

 [[Image:LocusZoomSmall.png]]

This page contains information regarding a version of LocusZoom that may be downloaded for personal use. For more information on LocusZoom, see this [[LocusZoom|page]]. '''This page refers to the command line "standalone" version, which is no longer actively maintained. For information about a web-friendly version with support for modern datasets, see [https://github.com/statgen/locuszoom LocusZoom.js] on GitHub, or [https://my.locuszoom.org https://my.locuszoom.org] to plot your own data''' .

To be notified of future changes to LocusZoom, you can join our [http://groups.google.com/group/locuszoom Google Group].

== Quick Start (Requirements) ==

The following software is required:

*[http://www.python.org/download/ Python 2.7+] (do '''not''' download the 3.0 branch!)
*[http://www.r-project.org/ R 3.0+]. Note that if using R 3.1, you must install LocusZoom 1.3 (previous versions will fail.)

The following software is optional but recommended:

*[[New Fugue|new_fugue]], a program for computing LD, written by Goncalo Abecasis.
*[http://pngu.mgh.harvard.edu/~purcell/plink/ PLINK]
*[http://samtools.sourceforge.net/ tabix], downloaded with samtools

The following R packages are optional but recommended:
*[http://cran.r-project.org/web/packages/gridExtra/index.html gridExtra] (used for creating summary tables of GWAS hits / fine-mapping SNPs as additional pages in the PDF)

For the latest stable LocusZoom package, see our [https://github.com/statgen/locuszoom-standalone download] page. The current version is '''1.3''', released on June 20th, 2014.

Currently only '''Unix/Linux''' is supported, though Mac OS X should be supported in a future release. Support for Windows may come at a much later date.

== Synopsis ==

First, change directory into examples/. Then, run the following command:
<pre>./run_example.py</pre>
This script runs the following command for you:
<pre>../bin/locuszoom --metal Kathiresan_2009_HDL.txt --refgene FADS1</pre>
A PDF plot of the FADS1 locus will be created in the directory. It should look roughly like this:

[[Image:FADS1 small.png]]

== Download ==

See our [https://github.com/statgen/locuszoom-standalone download] page for links to the latest as well as previous releases.

== Installation ==

=== Step 1: Install Python ===

You will need to install Python on your system if it is not already. Head over to [http://www.python.org www.python.org] to download it. Note that you will want to make sure to download the latest from the 2.x branch, and '''*not*''' the 3.x one.

=== Step 2: Install R ===

R is also required for generating the plots. You can download R at [http://www.r-project.org/ www.r-project.org]. Version 2.10 or greater is required.

=== Step 3: Install LD calculation software (optional) ===

* If you wish to calculate from hg18 sources (hapmap, earlier releases of 1000G): install '''new_fugue''' (see below.)
* If you wish to calculate from hg19 sources (latest 1000G): install '''PLINK''' (see below.)
* If you plan to supply your own LD files per region, or calculate LD directly from VCF files: install nothing! See options for --ld and --ld-vcf.

==== new_fugue ====

New_fugue is a program that calculates linkage disequilibrium measures from genotype files. While installing new_fugue is optional, we highly recommend it as it makes the process of generating plots much easier. If you opt to skip installing new_fugue, you will need to provide your own computed LD files for each region that you want to plot.

New_fugue can be downloaded from [[New Fugue|here]].

Once downloaded, extract the tar file using:
<pre> tar zxf /path/to/new_fugue.tar.gz</pre>
Change into the generic-new_fugue directory that is created, and run:
<pre> make install </pre>

You may need administrator rights to install this program.

==== PLINK ====

PLINK is now used to calculate LD for all future LD sources / populations that we may add. The program new_fugue (above) is used to calculate LD from older sources (such as hapmap) and older builds (such as hg18) where LD files are sufficiently small.

You can download PLINK and find instructions for installing it [http://pngu.mgh.harvard.edu/~purcell/plink/download.shtml here].

=== Step 5: Install tabix ===

Tabix is used to quickly extract regions from bgzipped and tabix-indexed files. It is used in LocusZoom to extract regions from VCF files when calculating LD, and for extracting from EPACTS result files.

It can be downloaded from the sourceforge site [http://samtools.sourceforge.net/ here] or directly to the download site [http://sourceforge.net/projects/samtools/files/ here].

=== Step 6: Install LocusZoom ===

LocusZoom is provided as a tar archive which contains the following:

*The LocusZoom python application
*The R script used for generating plots
*Human genome '''build hg18 and hg19''' data, including:
**genotype files (used for computing LD) from HapMap and 1000G
**a SQLite database file containing tables describing SNP positions, SNP annotations, gene and exon locations, and recombination rates

Simply unpack the tar to your directory of choice by doing the following:
<pre>cd <directory where you want to place locuszoom>
tar zxf /path/to/locuszoom.tgz
</pre>
The tar archive will extract into the following directory structure:

*locuszoom/
**bin/
***locuszoom (this is the locuszoom "executable")
***locuszoom.R (the R script which is used by locuszoom for creating the plots)
***dbmeister.py (script for creating custom user databases)
***lzupdate.py (script for creating an updated copy of the provided locuszoom database)
**conf/ (configuration file located here)
**data/
***database/ (SQLite file located here)
***hapmap/ (hapmap genotype files)
***1000G/ (1000G genotype files)
**src/ (source code for locuszoom)

It is important that this directory structure remain intact. To make launching locusoom easier, you could create a link to it from /usr/local/bin, for example:
<pre>ln -s bin/locuszoom /usr/local/bin/locuszoom</pre>

== Sources of information ==

LocusZoom uses various sources of information for annotation, positions, and calculating LD.

For computing LD:
*[ftp://ftp.hapmap.org/hapmap/genotypes/2008-10_phaseII/ HapMap genotypes] for populations CEU, YRI, and JPT+CHB.
*[ftp://ftp.1000genomes.ebi.ac.uk/vol1/ftp/pilot_data/release/2010_03/pilot1 1000 Genomes genotypes]

For SNP, gene, and exon positions:
*[http://www.ncbi.nlm.nih.gov/projects/SNP/ dbSNP position] via the [http://genome.ucsc.edu UCSC Genome Browser]
*[http://www.ncbi.nlm.nih.gov/RefSeq/ Gene and exon positions] via the [http://genome.ucsc.edu UCSC Genome Browser]. We filtered SNPs that map to more than one location or where no allele matches the reference sequence.

For annotation:
*We use various sources including RefSeq Genes (refFlat), TFBS Conserved (tfbsConsSites), and Conservation (phaseConsElements44wayPlacental), all available from the [http://genome.usc.edu UCSC Genome Browser].
*[ftp://ftp.hapmap.org/hapmap/recombination/2008-03_rel22_B36/rates/ Recombination rates from HapMap].

For GWAS hits:
*We use the NHGRI GWAS catalog, available at [http://www.genome.gov/gwastudies/ genome.gov]

== Input ==

=== Association results file ===

LocusZoom requires an association results file similar in formatting to what METAL or EPACTS provides.

==== METAL formatted file ====

The file must have 2 columns: markers (SNPs), and p-values. The file should look something like this:

 

{| width="25%" cellspacing="0" cellpadding="1" border="1"
|-
! scope="col" | MarkerName
! scope="col" | P-value
|-
| align="center" | rs1
| align="center" | 0.423
|-
| align="center" | rs2
| align="center" | 1.23e-04
|-
| align="center" | chr4:401141
| align="center" | 9.4e-390
|}

 

Markers can be either rsIDs or chr:pos format (see above).

This file should be passed to locuszoom using the <code>--metal</code> option.

The file should be tab-delimited, though this can be changed using the <code>--delim </code> option.

If your marker and p-value column names are not "MarkerName" and "P-value", you may set them with <code>--markercol</code> and <code>--pvalcol</code> options.

P-values of any magnitude are supported in scientific notation (we use an arbitrary precision library built-in to python, and transform p-values to the log scale.) If you've already transformed your p-values to the log scale, simply use <code>--no-transform</code> and LocusZoom will not transform them.

==== EPACTS formatted file ====

The file can come directly from [[EPACTS]], or simply be formatted similarly to the following:

{|
|-
! scope="col" | #CHROM
! scope="col" | BEGIN
! scope="col" | END
! scope="col" | MARKER_ID
! scope="col" | NS
! scope="col" | AC
! scope="col" | CALLRATE
! scope="col" | MAF
! scope="col" | PVALUE
! scope="col" | SCORE
! scope="col" | N.CASE
! scope="col" | N.CTRL
! scope="col" | AF.CASE
! scope="col" | AF.CTRL
|-
| 1 || 15903 || 15903 || 1:15903_G/GC || 2657 || 3892.2 || 1 || 0.26757 || 0.36771 || 0.90077 || 1326 || 1331 || 1.4688 || 1.4609
|-
| 1 || 19190 || 19191 || 1:19190_GC/G || 2657 || 823.65 || 1 || 0.155 || 0.67173 || 0.42378 || 1326 || 1331 || 0.3115 || 0.30849
|-
| 1 || 20316 || 20317 || 1:20316_GA/G || 2657 || 1005.3 || 1 || 0.18917 || 0.50804 || 0.66189 || 1326 || 1331 || 0.38062 || 0.37607
|-
| 1 || 30967 || 30970 || 1:30967_CCCA/C || 2657 || 435.35 || 1 || 0.081925 || 0.08848 || -1.7035 || 1326 || 1331 || 0.16007 || 0.16762
|-
| 1 || 51972 || 51975 || 1:51972_GGAC/G || 2657 || 207.8 || 1 || 0.039104 || 0.51638 || -0.64893 || 1326 || 1331 || 0.077187 || 0.079226
|-
| 1 || 53138 || 53140 || 1:53138_TAA/T || 2657 || 216.2 || 1 || 0.040685 || 0.55679 || 0.58762 || 1326 || 1331 || 0.083145 || 0.079602
|-
| 1 || 54421 || 54421 || 1:54421_A/G || 2657 || 179.45 || 1 || 0.033769 || 0.73592 || 0.33726 || 1326 || 1331 || 0.068213 || 0.066867
|-
| 1 || 66221 || 66221 || 1:66221_A/AT || 2657 || 664.45 || 1 || 0.12504 || 0.48676 || 0.69547 || 1326 || 1331 || 0.25366 || 0.24651
|-
| 1 || 66222 || 66223 || 1:66222_TA/T || 2657 || 470.3 || 1 || 0.088502 || 0.64258 || 0.4641 || 1326 || 1331 || 0.17941 || 0.17461
|-
|}

The chrom, start, end, marker ID, and p-value columns must all be present. The file must be tab-delimited.

To load this file, use --epacts.

'''Note''': LocusZoom (as of 1.3) will now use the tabix index for the EPACTS file if it exists and if tabix is intalled on your system. This results in much faster loading of EPACTS files and should absolutely be used if possible.

'''Warning''': The "test" version of EPACTS changed the format of the output. To make LZ work, you'll also need to add <code>--epacts-beg-col BEG</code> to your command line.

==== Reading from STDIN ====

If you have a quick way of pulling out regions from your association results to plot (such as with tabix), you can pass the data directly to locuszoom on STDIN by specifying the file as "-". For example:

<pre>
tabix -h my_file.gz 1:1-10000 | locuszoom --metal - --refgene TCF7L2
</pre>

=== Region ===

You can specify the region to plot in any one of the following ways:

*A reference SNP and flanking region
<pre> --refsnp <your snp> --flank 500kb </pre>

*A reference SNP and chromosome/start/stop specification
<pre> --refsnp <your snp> --chr # --start <base position> --end <base position> </pre>

*A reference SNP and gene:
<pre> --refsnp <your snp> --refgene <your gene> </pre>

This will use the reference gene as the plotting boundaries. You can extend the boundaries by also including --flank.

*A gene and flanking region
<pre> --refgene <your gene> --flank 250kb </pre>
The flank is computed as +/- from the transcription start/end of the gene. From this region, LocusZoom will find the SNP with the most significant p-value, and use this as the reference SNP.

*A gene and chromosome/start/stop specification
<pre> --refgene <your gene> --chr # --start <base position> --end <base position> </pre>
This method is similar to the above, except that an exact region is specified. LD with the SNP with the most significant p-value in this region will be used to color data points.

*A chromosome/start/stop specification
<pre> --chr # --start <base position> --end <base position> </pre>
The SNP with the most significant p-value in this region will be used for estimating LD.

=== Specifying LD source/population/build ===

We supply genotype files for computing LD between the reference SNP and all other SNPs within the region you are plotting. The tables below show the supported combinations of LD source, population, and build. Note that you can always provide your own LD files, see [[#User-supplied_LD|User-supplied LD]] for more information.

'''1000G'''

{| width="75%" cellspacing="0" cellpadding="5" border="1"
|-
! align="left" scope="col" | Release
! align="left" scope="col" | Build
! align="left" scope="col" | Population
! align="left" scope="col" | LocusZoom Arguments
|-
| March 2012
| hg19
| ASN
| --pop ASN --build hg19 --source 1000G_March2012
|-
| March 2012
| hg19
| AFR
| --pop AFR--build hg19 --source 1000G_March2012
|-
| March 2012
| hg19
| EUR
| --pop EUR --build hg19 --source 1000G_March2012
|-
| March 2012
| hg19
| AMR
| --pop AMR --build hg19 --source 1000G_March2012
|-
| Nov 2010
| hg19
| ASN
| --pop ASN --build hg19 --source 1000G_Nov2010
|-
| Nov 2010
| hg19
| AFR
| --pop AFR --build hg19 --source 1000G_Nov2010
|-
| Nov 2010
| hg19
| EUR
| --pop EUR --build hg19 --source 1000G_Nov2010
|-
| June 2010
| hg18
| CEU
| --pop CEU --build hg18 --source 1000G_June2010
|-
| June 2010
| hg18
| YRI
| --pop YRI --build hg18 --source 1000G_June2010
|-
| June 2010
| hg18
| JPT+CHB
| --pop JPT+CHB --build hg18 --source 1000G_June2010
|-
| August 2009
| hg18
| CEU
| --pop CEU --build hg18 --source 1000G_Aug2009
|-
| August 2009
| hg18
| YRI
| --pop YRI --build hg18 --source 1000G_Aug2009
|-
| August 2009
| hg18
| JPT+CHB
| --pop JPT+CHB --build hg18 --source 1000G_Aug2009
|}

 '''HapMap Phase II'''

{| width="75%" cellspacing="0" cellpadding="5" border="1"
|-
! align="left" scope="col" | Build
! align="left" scope="col" | Population
! align="left" scope="col" | LocusZoom Arguments
|-
| hg18
| CEU
| --pop CEU --build hg18 --source hapmap
|-
| hg18
| YRI
| --pop YRI--build hg18 --source hapmap
|-
| hg18
| JPT+CHB
| --pop JPT+CHB --build hg18 --source hapmap
|}

=== Batch mode ===

LocusZoom provides a batch mode for generating plots for a large number of regions:

*<code>--hitspec </code>, which reads a batch mode specification file.

For this option, you must provide a text file of the following format:

{| width="75%" cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Column
! scope="col" | Description
|-
| snp
| Can be either a SNP, or gene.
|-
| chr
| Chromosome
|-
| start
| Start position to display on plot.
|-
| end
| End position to display on plot.
|-
| flank
| Flank for region. Can be given instead of chr/start/stop.
|-
| run
| Should this row be read? Should be "yes" or "no".
|-
| m2zargs
| List of arguments for customizing plots. You can find a list of them here: [[LocusZoom#Commonly_Used_LocusZoom_Options|Commonly Used LocusZoom Options]]
|}

 

The file should be delimited by whitespace (tab, space, multiple spaces), and the header must exist, with column names exactly as specified in the table above. As an example, consider the following file:

{| width="75%" cellspacing="0" cellpadding="5" border="1" class="sortable"
|-
! scope="col" | snp
! scope="col" | chr
! scope="col" | start
! scope="col" | stop
! scope="col" | flank
! scope="col" | run
! scope="col" | m2zargs
|-
| rs7983146
| NA
| NA
| NA
| 500kb
| yes
| title="My favorite SNP"
|-
| TCF7L2
| NA
| NA
| NA
| 1.25MB
| yes
| title="TCF7L2 Region" showRecomb=F
|-
| rs7957197
| 12
| 119503590
| 120322280
| NA
| yes
| showAnnot=F
|}

 

The first row would plot rs7983146 as the reference SNP, and a region of 500kb on either side of it. The plot title would read "My favorite SNP."

The second row would plot 1.25 MB on either side of TCF7L2's transcription start and stop. The SNP with the most significant p-value in your <code>--metal</code> file will be used as the reference SNP. The plot title would read "TCF7L2 Region", and the recombination overlay would be disabled using showRecomb=F.

The third row would plot rs7957197 as the reference SNP, but here we've specifically designated the region to plot, which is chr12:119503590-120322280. We've also disabled showing SNP annotations with showAnnot=F.

=== User-supplied LD ===

If new_fugue is installed, LocusZoom will automatically compute LD between the reference SNP and all other SNPs within each region to be plotted. However, you may wish to provide your own file with LD information. This can be done with the <code>--ld</code> option, which requires a file of the following format:

 

{| width="75%" cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Column
! scope="col" | Description
|-
| snp1
| Any SNP in your plotting region.
|-
| snp2
| Should always be the reference SNP in the region.
|-
| dprime
| D' between snp2 (reference SNP) and snp1.
|-
| rsquare
| r2 between snp2 (reference SNP) and snp1.
|}

 

The dprime column can be all missing if it is not known. Rsquare must be present, and must be valid data.

The file should be whitespace delimited, and the header (column names shown above) must exist.

=== Supply VCF files for calculating LD ===

You can give LocusZoom a VCF file directly to use for calculating LD:

<pre>
locuszoom --ld-vcf my_genotypes.vcf.gz ...
</pre>

This option takes the place of having to supply per-region pre-calculated LD (--ld) or having to specify --pop and --source for calculating LD from genotype files supplied by LZ.

'''Warning: ''' The VCF file must also have a [http://samtools.sourceforge.net/tabix.shtml tabix] index located in the same directory. For the above example, the tabix index "my_genotypes.vcf.gz.tbi" must exist.

You can also calculate D' from phased VCF files:

<pre>
locuszoom --ld-vcf my_genotypes.vcf.gz --ld-measure dprime ...
</pre>

The default measure is "rsquared".

In version 1.3, if you have VCF files separated out by chromosome, you can create a JSON file mapping chromosome name --> VCF file, and provide the JSON file to --ld-vcf. For example, the JSON file could look like:

<pre>
{
"X": "/path/to/X.vcf.gz",
"Y": "/path/to/Y.vcf.gz",
"MT": "/path/to/MT.vcf.gz",
}
</pre>

And then pass it directly using <code>locuszoom --ld-vcf my_vcfs.json</code>.

== Optional Input ==

=== Plotting LD with additional reference SNPs ===

LocusZoom can now show LD with multiple SNPs in a region (for example, you might want to show LD with a number of SNPs from a conditional analysis.)

You give LocusZoom the usual reference SNP (used for centering the plot and calculating the region) but an additional set of lead/reference SNPs as well.

For all other SNPs not in the "lead SNP set" of { reference SNP, additional reference SNPs }, LZ will find which of the lead SNPs it is in highest LD with, and color it to match that lead SNP. The extent of LD with the lead SNP is shown by a gradient of color.

As an example:

<syntaxhighlight lang="bash">
locuszoom --metal <DIAGRAM T2D results> --refsnp "rs231362" --add-refsnps "rs163184"
</syntaxhighlight>

Will generate the following plot:

[[File:New lz cond only.png|700px]]

The following options are available for changing the style of these types of plots:

{| width="85%" cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Option (with default value)
! scope="col" | Description
|-
| condLdColors="gray60,#E41A1C,#377EB8,#4DAF4A,#984EA3,#FF7F00,#A65628,#F781BF"
| First color is missing LD color, the rest are used as needed for each additional lead SNP
|-
| drawMarkerNames = T
| Display marker names (or not) above lead SNPs
|-
| condLdLow=NULL
| Used to set all SNPs with LD in the lowest bin to the same color, for example condLdLow="gray70"
|-
| condRefsnpPch=23
| Symbol for each lead SNP, defaults to diamond
|-
| condPch='4,16,17,15,25,8,7,13,12,9,10'
| Plotting symbols for groups of SNPs in LD with additional refsnps, make sure they don't overlap with condRefsnpPch above
|-
| ldCuts = "0,.2,.4,.6,.8,1"
| Bins for LD
|}

=== GWAS catalog variants ===

You can add known GWAS variants to your plots. For example:

<syntaxhighlight lang="bash">
locuszoom ... --gwas-cat whole-cat_significant-only --build hg19
</syntaxhighlight>

[[File:New lz gwas cat.png|900px]]

Currently the only catalog is the NHGRI GWAS catalog from [http://www.genome.gov/gwastudies/ genome.gov].

<pre>
Available GWAS catalogs for build hg19:

+----------------------------+----------------------------------------------------------------+
| Option | Description |
+----------------------------+----------------------------------------------------------------+
| whole-cat_significant-only | The entire GWAS catalog, filtered to SNPs with p-value < 5E-08 |
+----------------------------+----------------------------------------------------------------+
</pre>

If the R package '''gridExtra''' is installed, a summary of each GWAS catalog variant in your region is listed later in the PDF:

[[File:New lz gwas summary.png|500px]]

=== Fine-mapping credible sets ===

LocusZoom can add an additional track to the plot showing results from a fine-mapping analysis. These are typically SNPs within the 95% credible set (see [http://www.nature.com/ng/journal/v44/n12/full/ng.2435.html this paper] for an example of a method generating such a set of SNPs.)

To add this fine-mapping track, you supply (as a plotting option) the fine-mapping set of credible SNPs as a file:

<syntaxhighlight lang="bash">
locuszoom ... fineMap="my_finemapping_results.txt"
</syntaxhighlight>

The fine-mapping results file should be a tab-delimited file with each fine-mapping SNP (for example, all those fine-mapping SNPs in the 95% credible set), a descriptive label (EUR/AMR/AFR/etc.), and a color:

{| class="wikitable sortable"
|-
! scope="col" | snp
! scope="col" | chr
! scope="col" | pos
! scope="col" | pp
! scope="col" | group
! scope="col" | color
|-
| rs1 || 18 || 55931115 || 0.88 || AMR || red
|-
| rs1 || 18 || 55920115 || 0.88 || AMR || red
|-
| rs1 || 18 || 55940115 || 0.88 || AMR || red
|-
| rs1 || 18 || 55930115 || 0.88 || EUR || blue
|-
| rs2 || 18 || 55940115 || 0.02 || EUR || blue
|-
| rs3 || 18 || 56000000 || 0.03 || AFR || green
|-
| rs4 || 18 || 56022000 || 0.03 || AFR || green
|-
| rs3 || 18 || 56100000 || 0.03 || ASN || purple
|-
| rs3 || 18 || 56150000 || 0.03 || ASN || purple
|-
| rs4 || 18 || 56160000 || 0.03 || ASN || purple
|-
| rs4 || 18 || 56180000 || 0.03 || ASN || purple
|-
|}

LocusZoom will extract from the file only those SNPs falling within the region to be plotted, so you can provide all of your fine-mapping results in a single file.

The generated plot will have a track showing the fine-mapping SNPs:

[[File:New lz finemap.png|900px]]

If the R package '''gridExtra''' is installed, the PDF will also have a summary of each fine-mapping SNP:

[[File:New lz finemap summary.png|400px]]

=== Labeling multiple SNPs ===

You can specify a file controlling the labels for either the reference SNP, or any other arbitrary SNP within the region. For example:

[[File:New lz denote markers.png|700px]]

Use the --denote-markers-file <file> argument to do this:

<syntaxhighlight lang="bash">
locuszoom ... --denote-markers-file <your file>
</syntaxhighlight>

The file looks like:

{|
|-
! scope="col" align="left" | snp
! scope="col" align="left" | string
! scope="col" align="left" | color
|-
| rs231362 || GWAS || blue
|-
| rs163184 || Conditional || purple
|-
|}

It must be tab-delimited and the columns must have a header and be named as such.

=== Plotting BED tracks ===

You can supply locuszoom with a BED file, and the tracks within it will be added to the plot. For example:

[[File:Bed_tracks.png]]

Use the --bed-tracks option, for example:

<pre>
locuszoom ... --bed-tracks <your bed file>
</pre>

The BED file should have at least 4 columns: the first 3 for chr/start/end, and the 4th column for the label of the track. It must be '''tab-delimited''', not white-space delimited.

Color can also be specified, but the BED file then needs to follow the full [http://genome.ucsc.edu/FAQ/FAQformat.html#format1 BED format].

=== Specify gene table (refFlat, GENCODE, etc.) ===

You can now specify a different gene information table to use. LocusZoom provides both refFlat and GENCODE. refFlat is the default. For example:

<pre>
locuszoom --gene-table gencode
</pre>

== Output ==

LocusZoom will produce a directory for each plot that contains the plot itself, along with a number of temporary files containing information on your particular region. The plot will be a PDF, named with the chr#:start-stop that was plotted.

If you only want the PDF itself, and don't want the other files, you can use the <code>--plotonly</code> option.

Each directory (or PDF, in the case of <code>--plotonly</code>) will have the date included to avoid collisions with previous plots - this behavior can be disabled using <code>--no-date</code>.

You can further customize the directory/PDF names that are created by using the <code>--prefix <name></code> option. This will append a text string at the beginning of each directory/PDF that is created.

== LocusZoom options ==

LocusZoom has a number of command line options, described in the table below.

{| width="85%" cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Option
! scope="col" | Description
|-
| colspan="2" | Important settings
|-
| --metal
| This is the data file to provide. Files generated by the meta-analysis program METAL are already formatted appropriately. If your data is not from METAL, it is very simple to format it (see [[#Input|Input]].)
|-
| --delim
| Delimiter for the data file. This defaults to tab, but can be anything. For ease of specification, you can use the following shortcuts: --delim tab, --delim space, --delim comma.
|-
| --pvalcol
| Name of p-value column in the --metal file.
|-
| --markercol
| Name of the SNP column in the --metal file.
|-
| --epacts
| Provide a results file generated by [[EPACTS]] instead of a --metal file.
|-
| --refsnp
| Reference SNP to be used in the plot.
|-
| --refgene
| Specify a gene instead of a reference SNP. This will plot a region near a gene, and automatically find the SNP with the most significant p-value to use as the reference SNP.
|-
| --flank
| Specify the region near a reference SNP or gene as a "flank", instead of having to specify chr/start/stop explicitly. This can be specified in bases, kilobases, or megabases. Examples: 500kb, 1MB, 100141
|-
| --chr, --start, --end
| Specify chromosome/start/stop as the exact interval to plot. If no --refsnp is specified, the SNP with the most significant p-value in the region will be used as the reference SNP.
|-
| colspan="2" | Optional settings
|-
| --build
| Human genome build. This defaults to "hg18". You can supply your own build-specific data by modifying the conf file, and creating your own SQLite database (see *LINK HERE*).
|-
| --ld
| Provide a file specifying LD between your reference SNP and all SNPs within the region you wish to plot. You only need to supply this file if you have created LD specifically for your purposes (perhaps a different population or genome build.) Otherwise, LD is computed automatically for you.
|-
| --ld-vcf
| Use a VCF file to calculate LD between SNPs. This can be a VCF file with an entire genome of SNPs and does not have to be subsetted to your region. The VCF file must also have a tabix index file. For calculating D', the VCF must be phased.
|-
| --source
| Source to use for genotypes when using LD. See [[#Specifying_LD_source.2Fpopulation.2Fbuild|Specifying LD source/population/build]] for more info.
|-
| --pop
| Population to use when computing LD. See [[#Specifying_LD_source.2Fpopulation.2Fbuild|Specifying LD source/population/build]] for more info.
|-
| --snpset
| Rug of SNPs to create at the top of the plot. Defaults to the Illumina 1M chip currently. To disable, use --snpset NULL.
|-
| --plotonly
| Create only a PDF of the plot, and remove all temporary files/directories created during plotting.
|-
| --no-transform
| LocusZoom supports arbitrary precision p-values. However, if your p-values have already been transformed to the -log10 scale, you can use this option to stop LocusZoom from automatically transforming them.
|-
| --prefix
| Places a text string at the beginning of each plot or directory created. This is mainly used to denote different batches of plots - for example, you could use --prefix using_ceu to denote these plots are computed using CEU LD information.
|-
| --db
| SQLite database file to use. This is set in the conf file by default, but can be changed on the command line if desired.
|}

 

 

== Plotting options ==

In addition to the options above, there are options that control the plotting engine inside Locuszoom. These are used with a different syntax: arg=value (no spaces allowed).

New/fixed options in 1.3:

{| width="85%" cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Option (with default value)
! scope="col" | Description
|-
| colorCol=NULL
| Specify the name of a column in association results file denoting the color each marker should be. This disables coloring by LD. For the column values, color names should be used, for example "red" "olivedrab" etc.
|-
| signifLine=NULL
| Specify (in -log10 p-value scale) where to place a horizontal significance line. Can have multiple lines, e.g. signifLine="7.3,9"
|-
| signifLineColor=NULL
| Specify color of each significance line, e.g. signifLineColor="red,blue"
|-
| signifLineWidth=NULL
| Specify the line width for each significance line, e.g. signifLineWidth="2,3"
|-
| showIso=F
| Show genes as isoforms, rather than collapsed into one canonical transcript. To enable use showIso=T
|}

 

Other options:
{| width="85%" cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Option (with default value)
! scope="col" | Description
|-
| theme=NULL
| Select a theme. A theme is a collection of other settings. Options include theme=publication and theme=black.
|-
| ymax=10
| the display range for log10(p-value) will be at least ymax (extended as necessary to avoid clipping)
|-
| axisSize=1
| scaling factor for axes
|-
| axisTextSize=1
| sclaing factor for axis labels
|-
| axisTextColor=gray30
| color of axis labels
|-
| refsnpTextColor=black
| color for reference SNP label (use 'transparent' to hide this label)
|-
| refsnpTextSize=1
| scaling factor for reference SNP text size
|-
| refsnpTextAlpha=1
| transparency level for reference SNP label (1=opaque,0=transparent)
|-
| title = ""
| title for plot
|-
| titleColor=black
| color for title
|-
| width=10
| width of pdf (inches)
|-
| height=7
| height of pdf (inches)
|-
| leftMarginLines=5
| margin (in lines) on left
|-
| rightMarginLines=5
| margin (in lines) on right
|-
| unit=1000000
| bp per unit displayed in plot
|-
| showAnnot=TRUE
| show annotation for each snp?
|-
| showGenes=TRUE
| show genes?
|-
| annotCol='annotation'
| column to use for custom annotation, if it exists
|-
| annotPch='24,24,25,22,22,8,7,21'
| plot symbols for annotation
|-
| annotOrder=NULL
| ordering of custom annotation classes (comma-separated list annotation strings in order, alphabetical by default)
|-
| showRefsnpAnnot=TRUE
| show annotation for reference snp too?
|-
| ld=NULL
| file for LD information
|-
| ldCuts="0,.2,.4,.6,.8,1"
| cut points for LD coloring
|-
| ldColors="gray50,navy, lightskyblue,green, orange,red,purple3"
| colors for LD
|-
| ldCol='rsquare'
| name for LD column
|-
| LDTitle=NULL
| title for LD legend
|-
| smallDot=.4
| smallest p-value cex
|-
| largeDot=.8
| largest p-value cex
|-
| refDot=NULL
| largest p-value cex
|-
| rfrows=4
| max number of rows used for displaying genes
|-
| showPartialGenes=TRUE
| should genes that don't fit completely be displayed?
|-
| geneFontSize=.8
| size for gene names
|-
| geneColor="navy"
| color for genes
|-
| snpsetFile=NULL
| use this file for SNPset rug data
|-
| rugColor=gray30
| color for snpset rugs
|-
| rugAlpha=1
| alpha for snpset rugs
|-
| metalRug=NULL
| if not null, use as label for rug of metal positions
|-
| showRecomb=TRUE
| show recombination rate?
|-
| recombColor=blue
| color for recombination rate on plot
|-
| recombAxisColor=NULL
| color for recombination rate axis labeing (default matches recombColor)
|-
| recombAxisAlpha=NULL
| color for recombination rate axis labeing
|-
| recombOver=FALSE
| overlay recombination rate? (else underlay it)
|-
| recombFill=FALSE
| fill recombination rate? (else line only)
|-
| recombFillAlpha=0.2
| recomb fill alpha
|-
| recombLineAlpha=0.8
| recomb line/text alpha
|-
| frameColor=gray30
| frame color for plots
|-
| frameAlpha=1
| frame alpha for plots
|-
| legendSize=.8
| scaling factor of legend
|-
| legendAlpha=1
| transparency of legend background
|-
| legend='auto'
| legend? (auto, left, right, or none)
|-
| hiStart=0
| start of highlighted region
|-
| hiEnd=0
| end of highlighted region
|-
| hiColor=blue
| color used for highlighting
|-
| hiAlpha=0.1
| transparency level for highlighting
|-
| prelude=NULL
| R code to execute after data is read but before plot is made (allows data modification)
|-
| postlude=NULL,
| R code to execute after plot is made
|}

 

 

== Examples ==

=== A quick peek at a particular SNP ===

<code></code>
<pre>--metal your_data --refsnp rs1002227
</pre>
=== A quick peek at a particular gene ===

<code></code>
<pre>--metal your_data --refgene CETP
</pre>
=== Plot 500kb on either side of a SNP ===

<code></code>
<pre>--metal your_data --refsnp rs7983146 --flank 500kb
</pre>
=== Use 1000 genomes, CEU for LD instead of the default (HapMap r22 CEU) ===

<code></code>
<pre>--metal your_data --refsnp rs11899863 --source 1000G
</pre>

=== Use HapMap YRI for LD ===

<code></code>
<pre>--metal your_data --refsnp rs11899863 --pop YRI --build hg18 --source hapmap
</pre>

=== Specify a specific region and reference SNP to plot ===

<code></code>
<pre>--metal your_data --refsnp rs1552224 --chr 11 --start 71810746 --end 72710746
</pre>

=== An example using plotting options ===

Note in this example the plotting options are placed at the '''end''' of the command-line, and are of the format '''arg'''='''value'''. The value should be double-quoted if spaces are included in the value (see title= below.)

<code></code>
<pre>--metal your_data --refsnp rs7903146 title="My region" geneFontSize=1.1 recombColor="gray"
</pre>

== Advanced configuration ==

=== Creating a custom SQLite database ===

As a starting point, we provide SQLite databases based on UCSC human genome '''build hg18 and hg19''', which includes the following tables:

*snp_pos: SNP positions
*refFlat: gene information (exons, transcription start/stops, etc.)
*recomb_rate: recombination rates from hapmap phase 2
*snp_set: maps each SNP to a "set" - for example, all SNPs on the Illumina 1M chip
*refsnp_trans: a table that maps SNPs from previous builds to the current build

To create your own database, we provide a script <code>bin/dbmeister.py</code> that can insert these tables for you. We recommend creating your own database file, rather than inserting tables into the default LocusZoom database. This script is capable of using python's built-in sqlite support, but for faster insertion of tables (about 2x faster), we recommend installing sqlite3 from [http://www.sqlite.org/ www.sqlite.org].

==== Inserting snp_pos ====

First, create a file that looks like the following:

{| width="75%" cellspacing="0" cellpadding="5" border="1" class="sortable"
|-
! scope="col" | snp
! scope="col" | chr
! scope="col" | pos
|-
| rs38343
| 1
| 93919141
|-
| rs918141
| 7
| 763263
|-
| chr4:9181
| 4
| 9181
|}

The file should be: tab-delimited, must have a header, and the columns should be exactly in that order.

Now, you can create your own database, and insert this file by using:
<pre> dbmeister.py --db my_database.db --snp_pos my_snp_pos_file </pre>
This command creates a database called "my_database.db" and inserts the SNP position table into it. If "my_database.db" had existed already, it would drop the snp_pos table in it, and insert yours in its place.

One special note about adding SNP position tables: a refsnp_trans table will automatically be created for you, where each SNP maps to itself. If you have a list of SNPs from previous builds that you would like to map to a SNP in the current build, you can then insert your own refsnp_trans table (see below for more information on this table.)

==== Inserting refsnp_trans ====

The refsnp_trans table looks like the following:

{| width="75%" cellspacing="0" cellpadding="5" border="1" class="sortable"
|-
! scope="col" | rs_orig
! scope="col" | rs_current
|-
| rs840
| rs715
|-
| rs1086
| rs940
|-
| rs1234
| rs1067
|}

The first column contains SNP names from older genome builds, and the rs_current column contains SNP names from the current genome build (i.e., the build your database file is anchored to.)

Inserting this table into your database is simply then:
<pre> dbmeister.py --db my_database.db --trans my_snp_translations_file </pre>
You will want to execute this command AFTER inserting the snp_pos table, since that command drops the existing translation table.

==== Inserting refFlat ====

The refFlat table mirrors what is currently supplied by the refFlat table in the UCSC database. The file should look like:

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | geneName
! scope="col" | name
! scope="col" | chrom
! scope="col" | strand
! scope="col" | txStart
! scope="col" | txEnd
! scope="col" | cdsStart
! scope="col" | cdsEnd
! scope="col" | exonCount
! scope="col" | exonStarts
! scope="col" | exonEnds
|-
| EFCAB1
| NM_024593
| chr8
| -
| 49798505
| 49810423
| 49799853
| 49810263
| 6
| 49798505,
| 49799913,
|-
| HECTD3
| NM_024602
| chr1
| -
| 45240806
| 45249614
| 45241750
| 45249516
| 21
| 45240806,45241927,
| 45241835,45241999,
|-
| PTPN20B
| NM_001042361
| chr10
| -
| 48357047
| 48447587
| 48358657
| 48447532
| 8
| 48357047,48359393,48391320,
| 48358692,48359456,48391411,
|}

You can insert this table into the database using:
<pre> dbmeister.py --db my_database.db --refflat my_refflat_file </pre>
==== Inserting recomb_rate ====

The recomb_rate table mirrors what is available from [ftp://ftp.hapmap.org/hapmap/recombination/2008-03_rel22_B36/rates/ HapMap]. The format is:

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | chr
! scope="col" | pos
! scope="col" | recomb
! scope="col" | cm_pos
|-
| 1
| 72434
| 0.0015
| 0
|-
| 1
| 78032
| 0.0015
| 8.397e-06
|-
| 1
| 554461
| 0.0015
| 0.00072304
|-
| 1
| 554484
| 0.0015
| 0.000723075
|-
| 1
| 555296
| 0.0015
| 0.000724293
|-
| 1
| 558185
| 0.0015
| 0.000728627
|}

The table can be inserted using:
<pre> dbmeister.py --db my_database.db --recomb_rate my_recomb_rate_file </pre>
==== Inserting snp_set ====

The snp_set table simply carries a mapping of SNPs to a particular set they may belong to. The table looks like:

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | snp
! scope="col" | snp_set
|-
| rs1000
| Illu1M
|-
| rs1000
| Illu1M
|-
| rs1000
| Illu1M
|-
| rs1000000
| Illu1M
|-
| rs10000000
| Illu1M
|-
| rs10000009
| Illu1M
|}

The first column is a SNP, and the second is the name of the set it belongs to. If a SNP belongs to multiple sets, you can duplicate that SNP multiple times, one for each set.

Inserting the table into your database can be done using:
<pre> dbmeister.py --db my_database.db --snp_set my_snpset_file </pre>
==== Making LocusZoom aware of your new database ====

Now that you've created your own database file, you need to make LocusZoom aware that it exists. There are two ways to do this:

#Edit conf/m2zfast.conf, and change the <code>SQLITE_DB</code> variable
#Supply the <code>--db</code> command line option when invoking <code>bin/locuszoom</code>

Editing the m2zfast.conf file entails changing the following block of code:

<code></code>
<pre>SQLITE_DB = {
'hg18' : "data/database/locuszoom_hg18.db"
};
</pre>
Here, we've mapped build "hg18" to the default database file that comes with LocusZoom. You can mimic this format and insert your own, for example:

<code></code>
<pre>SQLITE_DB = {
'hg18' : "data/database/locuszoom_hg18.db",
'hg19' : "data/database/my_database.db"
};
</pre>
The location of your database should be either an absolute path to your file, or a path relative to the locuszoom/ root (like those seen above.)

If you wish for your database to become the default, change the <code>LATEST_BUILD</code> variable in the m2zfast.conf file to whatever you have chosen above (in our example, our new database became mapped to 'hg19'.)

=== Updating the existing locuszoom database(s) ===

LocusZoom now comes with a database updating script <code>bin/lzupdate.py</code>. This script can download the necessary data from UCSC, NCBI, NGHRI, and GENCODE to create an up-to-date database file. The script performs the following actions:

# Download latest SNP table from UCSC for the given build
# Reformat SNP table for insertion into sqlite database
# Download latest refFlat from UCSC for the given build
# Reformat refFlat for insertion into sqlite database
# (optional) Download GENCODE annotation file from GENCODE FTP site
# Download RsMergeArch from NCBI
# Write formatted translation table for old rsIDs to latest (from RsMergeArch)
# Create a SNP set file (for indicating rug of markers at top of plot for different genotyping arrays)
# Download the latest NHGRI GWAS catalog
# Format catalog for use with locuszoom
# Call <code>bin/dbmeister.py</code> to insert everything above (except the GWAS catalog file, which remains a separate file)

An example of running the script:

<pre>
bin/lzupdate.py --build hg19 --gencode 19 --gwas-cat
</pre>

The script will NOT overwrite the existing locuszoom database, since you should likely back it up first (under data/database/*.db). After running the script you should have both a new locuszoom.db file, and a gwas catalog file. You can then either overwrite the locuszoom database after backing it up, or you could place them in a different location and modify the conf file accordingly. The script will provide instructions after running for how to do this.

=== Changing m2zfast.conf settings ===

The m2zfast.conf configuration file contains a number of settings that are typically static, but could require user configuration. The table below lists each variable, and its purpose.

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Variable
! scope="col" | Description
|-
| DEFAULT_BUILD
| Default build to use for finding SNP positions, and calculating LD. This is used to index SQLITE_DB, as well as LD_DB.
|-
| DEFAULT_POP
| Default population to use for computing LD.
|-
| DEFAULT_SOURCE
| Default source for computing LD.
|-
| NEWFUGUE_PATH
| Path to the new_fugue binary. Defaults to "new_fugue", which simply means it is searched for on your path. If new_fugue is not on your path, you will need to specify the full path here.
|-
| PLINK_PATH
| Path to the PLINK binary. Defaults to "plink", which searches for PLINK on your path. If it is not on your path, specify the full path here.
|-
| RSCRIPT_PATH
| Path to the Rscript binary. Defaults to "Rscript", which searches for Rscript on your path. If it is not on your path, specify the full path here.
|-
| SQLITE_DB
| See [[LocusZoom Standalone#Making_LocusZoom_aware_of_your_new_database|Making LocusZoom aware of your database]].
|-
| LD_DB
| Contains a "tree" which maps a tuple of (genotype source, genotype population, genome build) to genotype files.
|-
| GWAS_CATS
| Contains a "tree" which maps genome build and the name of a GWAS catalog to the actual file containing the GWAS hits.
|}

=== LD caching ===

LocusZoom attempts to remember LD calculations that were made on previous runs of the program to avoid having to re-calculate the same regional LD for subsequent runs. The process works as follows:

*For a given reference SNP and chr/start/stop:
**If LD has not been previously computed, use new_fugue to compute LD with the reference SNP and all other SNPs in the region, and store this result to the LD cache
**Else, retrieve the previously stored LD results

The cache intelligently stores LD from separate sources (hapmap, 1000G), populations, builds, and even different versions of genotype files separately.

Upon running LocusZoom, a file called "ld_cache.db" will automatically be created in the current directory, and LD computations will be stored there. If you wish to change the location of the LD cache, use <code>--cache <file></code>. If you wish to disable LD caching, you can use <code>--cache None</code>.

''Python note:'' The ld_cache.db is actually a shelve, and you can explore its contents using:

<code></code>
<pre>import shelve
d = shelve.open("ld_cache.db")
</pre>
== License ==

Copyright 2010 Ryan Welch, Randall Pruim

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

[[Category:Software]]

LocusZoom

2020-10-28T17:29:06Z

Abought: Make deprecation warning more visible.

[[Image:LocusZoomSmall.png]]

'''LocusZoom''' is designed to facilitate viewing of local association results together with useful information about a locus, such as the location and orientation of the genes it includes, linkage disequilibrium coefficients and local estimates of recombination rates. It was developed by popular demand, as a result of many questions we have had about "How did you make the figures in your talk?" or "How did you make the figures for your GWAS paper?" (And for better or for worse, we have quite a few GWAS papers!!).

LocusZoom can be used in four ways:

; 1. Plot Summaries of Your Genomewide Scan Interactively
: You can upload summary results of your own genomewide scan or genomewide meta-analysis and request plots of regions of interest using a web-based form.

; 2. Generate Many Plots in Batch Mode
: You can upload summary results for your genomewide scan or genomewide meta-analysis and request several plots in one go by uploading a batch file. You will receive results via e-mail. A snail-mail option is not available.

; 3. Plot Summaries of Publicly Available Datasets
: Currently, this includes the results of [http://www.sph.umich.edu/csg/abecasis/public/lipids2008/ our genome-wide scan] for variants associated with HDL-cholesterol, LDL-cholesterol and triglyceride levels in ~20,000 individuals.

; 4. Download LocusZoom and run on your local unix machine
: [http://genome.sph.umich.edu/wiki/LocusZoom_Standalone Download LocusZoom] and [http://genome.sph.umich.edu/wiki/LocusZoom_Standalone#Sources_of_SQLite_database_tables associated databases]

== Upload your own meta-analysis file and generate single plots using a web-based form ==

=== Uploading Your Association Study Results ===

'''The instructions below refer to a "legacy" service that is not actively maintained. For modern datasets, consider using our new [https://my.locuszoom.org my.locuszoom.org] service for the latest features, including manhattan plots and support for build GRCh38.'''

'''Please note: You CAN plot SNPs without rsid using chr6:20122013 format.'''

Association results can be uploaded to our web server using the [http://locuszoom.org/ plot your data webpage]. Result files are limited to 20Mb in size, which allows for a [[gzip|gzipped]] text table including key columns (marker name, p-value and sample size) for up to ~3 million SNPs. In our tests, a typical GWAS results file is ~17 Mb in size after imputation of HapMap SNPs. Once a file is uploaded, LocusZoom will remember the file for the duration of your web session allowing you to generate multiple plots. If you have a slow connection or would like to save time, you can upload results for a region or chromosome of interest only. Your results are entirely confidential and won't be viewed by us or anyone else (except those with whom you share them!)

To specify the region to be plotted, you will have to specify the name of a key marker in the region (typically, as an rs-number, but can be in chr:pos format), name a gene of interest or provide appropriate genome coordinates. When displaying linkage disequilibrium, plotting will be very fast for small windows when HapMap CEU linkage disequilibrium is requested (because pairwise coefficients have been precomputed) and will be a bit slower for larger windows (because linkage disequilibrium coefficients must be computed on the fly).

If you include a sample size column in the result file, it will be used to control the size of each plotted marker.

=== Custom Annotation ===

You may choose to have SNPs displayed using different plotting symbols to distinguish them from each other. To implement this, in the section "Custom Annotation" in the box "Column Name", you need to provide the name of a column in your meta-analysis file. This column will list a category for each SNP of your own choosing (i.e. "nonsynonymous", "splice","intronic",etc.) or ("Genotyped","Imputed"), however, the category names may not include any spaces. To select the order of the categories to display in the legend and to match the order of pre-selected R plotting symbols (set as pch = 21, 22, 23, 24, 25, 4, 7, 8, 10, 11, 12, 13, 14, 3), you may provide the category names in the specified order in "Category Order" section of "Custom Annotation". Each entry (which may not contain spaces) does not need quotes but each entry should be separated by commas.

Alternatively, we have provided functional annotation of all 1000 Genomes (Aug 2009) and HapMap r22 SNPs according to the following categories; Framestop (24, triangle), Splice (24, triangle), NonSynonymous (25, inverted triangle), Synonymous (22, square), UTR (22, square), TFBScons (8, star), MCS44 Placental (7, square with diagonal lines) and None-of-the-above (21, filled circle). This can be implemented using the section "Show Annotation" and clicking the box beside each annotation category that you would like distinguished. SNPs that are not in any selected category will still be displayed as having no annotation.

=== Plotting of Pairwise Linkage Disequilibrium ===

In the main plot window, data points are colored according to their level of linkage disequilibrium (LD) of the each SNP with the index SNP. If users specify the region to display using an index SNP and flanking region, LD of all data points will be relative to the user-specified index SNP. If users specify the region to display using genome coordinates or a gene name, LocusZoom will automatically select the most significant SNP in the region as the index SNP. For all other SNPs in the plot, the color of the data point will reflect the pairwise LD with this index SNP. The default LD measure is r2 calculated from the HapMap CEU population (release 22), but users have the option to replace this with D’ and of selecting the HapMap YRI, Hapmap CHB+JPT or 1000 Genomes CEU reference panels. To display LD from 1000G CEU, please substitute rsid's for 1000G naming convention (chrxx:xxxx) whenever possible. Because we have pre-computed LD for all SNPs in HapMap CEU, plots will often generate more quickly if using the default LD information. SNPs with missing LD information are shown in grey.

=== Customizing the Display of Your Results ===

All options listed in the Main Table above are available, as well as the options listed below

{| class="wikitable" border="0" cellpadding="3"
|- bgcolor="lightgray"
! Setting
! Default Value
! Details
|-
| Column Delimiter
| none
| Users must specify the type of column delimiter in the results file
|-
| Pvalue Column Name
| none
| Users must specify the name of the column that contains the p-values
|-
| Marker Column Name
| none
| Users must specify the heading of the column that contains marker names
|-
| Human Genome Build
| none
| Plots can be generated based on hg18 (default) or hg17 positions
|-
| HapMap Population for LD
| none
| This option allows the user to specify which HapMap population was used to obtain LD estimates. The default is CEU but users may select YRI or JPT+CHB
|}

== Using Batch Mode ==

To start batch mode, first upload your results file just as you would in interactive mode. The same file size restrictions apply.

=== Generating a Hit Spec File ===

Batch mode allows you to conveniently specify a set of plots to be generated in "Hit Spec" file. This is handy if you need to generate large numbers of plots or if you want to plot the same set of regions after updating a genomewide analysis (for example).

The "Hit Spec" file is a whitespace delimited text file. The file has six mandatory columns which can be followed by a series of optional '''key'''=''value'' pairs to allow for detailed customization of each plot. The first line in the file is assumed to be a header and is ignored. Each subsequent line describes a single plot. There are three ways to select a region to plot:

; Plotting a window flanking an interesting SNP
: This option allows you to plot results for all markers within a specific distance (e.g. 500kb) of an index SNP. To use this option, set column 1 to have the name of the index SNP (e.g. ''rs2'' below) and set column 5 to specify the width of the region of interest (e.g. 500kb below). Here is an example:

<source lang="text">
Feature chr start end flank plot arguments
rs1 na na na 500kb yes rfrows=3 weightCol=”N” snpset=”HapMap” metalRug=”Our SNPs”
</source>

; Plotting a region flanking an interesting SNP
: This option is similar to the previous option, but allows you to specify an assymetric region of interest. For example, perhaps you interested in a plot that extends a bit further to the right of the SNP of interest. In this case, specify the coordinates of the region to be plotted in columns 2, 3, and 4. Here is an example:

<source lang="text">
Feature chr start end flank plot arguments
rs2 1 540000 580000 na yes rfrows=4 legend=”right” showAnnot=T
</source>

; Plotting a region flanking a gene of interest
: This option allows you to focus on a particular gene, rather than a specific SNP. It is similar to the first option. You should set column 1 to be the name of the gene of interest and column 5 to be the desired window width. When you use this option, LocusZoom will automatically select an index SNP for each region; the SNP will be the site with the smallest p-value. Here is an example:

<source lang="text">
Feature chr start end flank plot arguments
CETP na na na 200kb yes rfrows=6 showAnnot=T annotPch=”1,24,24,25,22,21,8,7”
</source>

The sixth column in the "Hit Spec" file can be used to enable (with the value ''yes'') or disable (with the value ''no'') an individual plot. For example, if you run a "Hit Spec" file with 15 plots and 14 of them turn out very nicely, you may wish to re-run the "Hit Spec" file with some tweaks to the problem plot. In this case (if you dislike waiting for your results as much as we do!), you could disable generation of the plots that seem nice by changing the 6th column to “no” and leave the plot that you tweaked as a “yes”.

The 7th and final column contains additional LocusZoom arguments as '''key'''=''value'' pairs. Any number of '''key'''=''value'' pair arguments can be included. For details of available options, see the section entitled LocusZoom options below.

== Generate single plots using our publicly-available lipids GWAS data ==

In addition to plotting your own results, you can plot the results of some publicly available GWAS. Currently, the only publicly available set of results is our GWAS for loci determining blood lipid levels (Kathiresan et al, Nature Genetics 2009). Just like when you are plotting your own data, you can specify 1) an index SNP and a flanking region, 2) the chromosome together with start and stop positions (in basepairs), or 3) gene name and a flanking region.

== Commonly Used LocusZoom Options ==

{| border="1" width="100%" align="center"
|- bgcolor="lightgray"
! Web Form
! "Hit Spec" File Key-Value Pair
! Description
|-
| Title on Plot
| title=”My Favorite Locus”
| Specifies large text displayed above the plot
|-
| Human Genome Build
| n/a
| Plots can be generated based on hg18 (the default) or hg17 positions
|-
| Legend Location
| legend=”left”
| This specifies the location of the legend within the plot, the default is auto. Auto tries to select a location that overlaps a minimal number of datapoints. (auto, left, right, none)
|-
| SNP Position Rug
| snpset=”HapMap” metalRug=”Rug SNPs”
| These options control display of tickmarks indicating SNP positions at the top of the plot. Setting snpset="HapMap", snpset="Illu318" or snpset="Affy500" display a fixed set of SNPs. (You can also try snpset="Affy500,Illu318,HapMap" to see all 3). The metalRug option displays a rug which only includes the SNPs that are actually plotted. To remove the rug in batch mode set snpset=NULL.
|-
| Number of Rows for Gene Names
| rfrows=4
| LocusZoom will automatically tries to determine the number of display rows to use for genes and gene names so they are not overlapping. This can make each plot prettier, but is not ideal when you want to compare many plots side by side. To ensure a fixed amount of space is used for gene names, use this option to set the maximum number of display rows. If LocusZoom runs out of plotting space and some genes are left out, a warning will be added to the plot.
|-
| Point Size
| weightCol=”SampleSize”
| This specifies that the “dot size” of each data points will reflect the square-root of the sample size. The default is to have all dot sizes equal.
|-
| LD Measure
| ldCol=”dprime” (“rsquare”)
| Colors data points according to the selected LD measure. The default is "rsquare".
|-
| Reference Population for LD
| n/a
| This option allows the user to specify which reference panel is used to obtain LD estimates. The default is CEU from HapMap Phase II but users may select YRI or JPT+CHB from HapMap Phase II, or CEU from 1000 Genomes (August 2009 or June 2010 release).
|-
| Highlight Region of Interest
| hiStart=425Mb hiEnd=425.1Mb
| A grey box can be used to highlight important regions of the genome – this can reflect where an association signal peaks or a region selected for sequencing, for example.
|-
| Theme
| theme=”publication”
| We have created a theme that has larger text and is more easily readable for publication.
|-
| Show Annotation
| showAnnot=T showRefsnpAnnot=T annotPch=”21,24,24,25,22,22,8,7”
| SNP annotation is available for all 1000G SNPs (Aug 2009 release) and can be enabled with the showAnnot=T option. The annotPch command allows you to customize the R plotting symbol used for each kind of SNP; it is okay to use the same symbol for more than one category. The annotation categories, together with their default symbol setting are: Framestop (24, triangle), Splice (24, triangle), NonSynonymous (25, inverted triangle), Synonymous (22, square), UTR (22, square), TFBScons (8, star), MCS44 Placental (7, square with diagonal lines) and None-of-the-above (21, filled circle). For more information about these annotation categories used, please see http://research.nhgri.nih.gov/tools/unisnp/?rm=ohelp
|-
| Recombination Rate Overlay
| showRecomb=T
| The estimated recombination rate from HapMap samples can be shown on the plot or left off. The data plotted are from Hapmap; http://hapmap.ncbi.nlm.nih.gov/downloads/recombination/2008-03_rel22_B36/rates/
|}

For a full list of options that can be used in Batch Mode using a hitspec file, please see [http://genome.sph.umich.edu/wiki/LocusZoom_Standalone#Plotting_options this list]

[[Category:Software]]

LocusZoom

2020-10-28T17:23:04Z

Abought: Add deprecation notice and link to new my.locuszoom.org

[[Image:LocusZoomSmall.png]]

'''LocusZoom''' is designed to facilitate viewing of local association results together with useful information about a locus, such as the location and orientation of the genes it includes, linkage disequilibrium coefficients and local estimates of recombination rates. It was developed by popular demand, as a result of many questions we have had about "How did you make the figures in your talk?" or "How did you make the figures for your GWAS paper?" (And for better or for worse, we have quite a few GWAS papers!!).

LocusZoom can be used in four ways:

; 1. Plot Summaries of Your Genomewide Scan Interactively
: You can upload summary results of your own genomewide scan or genomewide meta-analysis and request plots of regions of interest using a web-based form.

; 2. Generate Many Plots in Batch Mode
: You can upload summary results for your genomewide scan or genomewide meta-analysis and request several plots in one go by uploading a batch file. You will receive results via e-mail. A snail-mail option is not available.

; 3. Plot Summaries of Publicly Available Datasets
: Currently, this includes the results of [http://www.sph.umich.edu/csg/abecasis/public/lipids2008/ our genome-wide scan] for variants associated with HDL-cholesterol, LDL-cholesterol and triglyceride levels in ~20,000 individuals.

; 4. Download LocusZoom and run on your local unix machine
: [http://genome.sph.umich.edu/wiki/LocusZoom_Standalone Download LocusZoom] and [http://genome.sph.umich.edu/wiki/LocusZoom_Standalone#Sources_of_SQLite_database_tables associated databases]

== Upload your own meta-analysis file and generate single plots using a web-based form ==

=== Uploading Your Association Study Results ===

'''The instructions below refer to a "legacy" service that is not actively maintained. For modern datasets, consider using our new [https://my.locuszoom.org my.locuszoom.org] service for the latest features, including manhattan plots and support for build GRCh38.'''

'''Please note: You CAN plot SNPs without rsid using chr6:20122013 format.'''

Association results can be uploaded to our web server using the [http://locuszoom.org/ plot your data webpage]. Result files are limited to 20Mb in size, which allows for a [[gzip|gzipped]] text table including key columns (marker name, p-value and sample size) for up to ~3 million SNPs. In our tests, a typical GWAS results file is ~17 Mb in size after imputation of HapMap SNPs. Once a file is uploaded, LocusZoom will remember the file for the duration of your web session allowing you to generate multiple plots. If you have a slow connection or would like to save time, you can upload results for a region or chromosome of interest only. Your results are entirely confidential and won't be viewed by us or anyone else (except those with whom you share them!)

To specify the region to be plotted, you will have to specify the name of a key marker in the region (typically, as an rs-number, but can be in chr:pos format), name a gene of interest or provide appropriate genome coordinates. When displaying linkage disequilibrium, plotting will be very fast for small windows when HapMap CEU linkage disequilibrium is requested (because pairwise coefficients have been precomputed) and will be a bit slower for larger windows (because linkage disequilibrium coefficients must be computed on the fly).

If you include a sample size column in the result file, it will be used to control the size of each plotted marker.

=== Custom Annotation ===

You may choose to have SNPs displayed using different plotting symbols to distinguish them from each other. To implement this, in the section "Custom Annotation" in the box "Column Name", you need to provide the name of a column in your meta-analysis file. This column will list a category for each SNP of your own choosing (i.e. "nonsynonymous", "splice","intronic",etc.) or ("Genotyped","Imputed"), however, the category names may not include any spaces. To select the order of the categories to display in the legend and to match the order of pre-selected R plotting symbols (set as pch = 21, 22, 23, 24, 25, 4, 7, 8, 10, 11, 12, 13, 14, 3), you may provide the category names in the specified order in "Category Order" section of "Custom Annotation". Each entry (which may not contain spaces) does not need quotes but each entry should be separated by commas.

Alternatively, we have provided functional annotation of all 1000 Genomes (Aug 2009) and HapMap r22 SNPs according to the following categories; Framestop (24, triangle), Splice (24, triangle), NonSynonymous (25, inverted triangle), Synonymous (22, square), UTR (22, square), TFBScons (8, star), MCS44 Placental (7, square with diagonal lines) and None-of-the-above (21, filled circle). This can be implemented using the section "Show Annotation" and clicking the box beside each annotation category that you would like distinguished. SNPs that are not in any selected category will still be displayed as having no annotation.

=== Plotting of Pairwise Linkage Disequilibrium ===

In the main plot window, data points are colored according to their level of linkage disequilibrium (LD) of the each SNP with the index SNP. If users specify the region to display using an index SNP and flanking region, LD of all data points will be relative to the user-specified index SNP. If users specify the region to display using genome coordinates or a gene name, LocusZoom will automatically select the most significant SNP in the region as the index SNP. For all other SNPs in the plot, the color of the data point will reflect the pairwise LD with this index SNP. The default LD measure is r2 calculated from the HapMap CEU population (release 22), but users have the option to replace this with D’ and of selecting the HapMap YRI, Hapmap CHB+JPT or 1000 Genomes CEU reference panels. To display LD from 1000G CEU, please substitute rsid's for 1000G naming convention (chrxx:xxxx) whenever possible. Because we have pre-computed LD for all SNPs in HapMap CEU, plots will often generate more quickly if using the default LD information. SNPs with missing LD information are shown in grey.

=== Customizing the Display of Your Results ===

All options listed in the Main Table above are available, as well as the options listed below

{| class="wikitable" border="0" cellpadding="3"
|- bgcolor="lightgray"
! Setting
! Default Value
! Details
|-
| Column Delimiter
| none
| Users must specify the type of column delimiter in the results file
|-
| Pvalue Column Name
| none
| Users must specify the name of the column that contains the p-values
|-
| Marker Column Name
| none
| Users must specify the heading of the column that contains marker names
|-
| Human Genome Build
| none
| Plots can be generated based on hg18 (default) or hg17 positions
|-
| HapMap Population for LD
| none
| This option allows the user to specify which HapMap population was used to obtain LD estimates. The default is CEU but users may select YRI or JPT+CHB
|}

== Using Batch Mode ==

To start batch mode, first upload your results file just as you would in interactive mode. The same file size restrictions apply.

=== Generating a Hit Spec File ===

Batch mode allows you to conveniently specify a set of plots to be generated in "Hit Spec" file. This is handy if you need to generate large numbers of plots or if you want to plot the same set of regions after updating a genomewide analysis (for example).

The "Hit Spec" file is a whitespace delimited text file. The file has six mandatory columns which can be followed by a series of optional '''key'''=''value'' pairs to allow for detailed customization of each plot. The first line in the file is assumed to be a header and is ignored. Each subsequent line describes a single plot. There are three ways to select a region to plot:

; Plotting a window flanking an interesting SNP
: This option allows you to plot results for all markers within a specific distance (e.g. 500kb) of an index SNP. To use this option, set column 1 to have the name of the index SNP (e.g. ''rs2'' below) and set column 5 to specify the width of the region of interest (e.g. 500kb below). Here is an example:

<source lang="text">
Feature chr start end flank plot arguments
rs1 na na na 500kb yes rfrows=3 weightCol=”N” snpset=”HapMap” metalRug=”Our SNPs”
</source>

; Plotting a region flanking an interesting SNP
: This option is similar to the previous option, but allows you to specify an assymetric region of interest. For example, perhaps you interested in a plot that extends a bit further to the right of the SNP of interest. In this case, specify the coordinates of the region to be plotted in columns 2, 3, and 4. Here is an example:

<source lang="text">
Feature chr start end flank plot arguments
rs2 1 540000 580000 na yes rfrows=4 legend=”right” showAnnot=T
</source>

; Plotting a region flanking a gene of interest
: This option allows you to focus on a particular gene, rather than a specific SNP. It is similar to the first option. You should set column 1 to be the name of the gene of interest and column 5 to be the desired window width. When you use this option, LocusZoom will automatically select an index SNP for each region; the SNP will be the site with the smallest p-value. Here is an example:

<source lang="text">
Feature chr start end flank plot arguments
CETP na na na 200kb yes rfrows=6 showAnnot=T annotPch=”1,24,24,25,22,21,8,7”
</source>

The sixth column in the "Hit Spec" file can be used to enable (with the value ''yes'') or disable (with the value ''no'') an individual plot. For example, if you run a "Hit Spec" file with 15 plots and 14 of them turn out very nicely, you may wish to re-run the "Hit Spec" file with some tweaks to the problem plot. In this case (if you dislike waiting for your results as much as we do!), you could disable generation of the plots that seem nice by changing the 6th column to “no” and leave the plot that you tweaked as a “yes”.

The 7th and final column contains additional LocusZoom arguments as '''key'''=''value'' pairs. Any number of '''key'''=''value'' pair arguments can be included. For details of available options, see the section entitled LocusZoom options below.

== Generate single plots using our publicly-available lipids GWAS data ==

In addition to plotting your own results, you can plot the results of some publicly available GWAS. Currently, the only publicly available set of results is our GWAS for loci determining blood lipid levels (Kathiresan et al, Nature Genetics 2009). Just like when you are plotting your own data, you can specify 1) an index SNP and a flanking region, 2) the chromosome together with start and stop positions (in basepairs), or 3) gene name and a flanking region.

== Commonly Used LocusZoom Options ==

{| border="1" width="100%" align="center"
|- bgcolor="lightgray"
! Web Form
! "Hit Spec" File Key-Value Pair
! Description
|-
| Title on Plot
| title=”My Favorite Locus”
| Specifies large text displayed above the plot
|-
| Human Genome Build
| n/a
| Plots can be generated based on hg18 (the default) or hg17 positions
|-
| Legend Location
| legend=”left”
| This specifies the location of the legend within the plot, the default is auto. Auto tries to select a location that overlaps a minimal number of datapoints. (auto, left, right, none)
|-
| SNP Position Rug
| snpset=”HapMap” metalRug=”Rug SNPs”
| These options control display of tickmarks indicating SNP positions at the top of the plot. Setting snpset="HapMap", snpset="Illu318" or snpset="Affy500" display a fixed set of SNPs. (You can also try snpset="Affy500,Illu318,HapMap" to see all 3). The metalRug option displays a rug which only includes the SNPs that are actually plotted. To remove the rug in batch mode set snpset=NULL.
|-
| Number of Rows for Gene Names
| rfrows=4
| LocusZoom will automatically tries to determine the number of display rows to use for genes and gene names so they are not overlapping. This can make each plot prettier, but is not ideal when you want to compare many plots side by side. To ensure a fixed amount of space is used for gene names, use this option to set the maximum number of display rows. If LocusZoom runs out of plotting space and some genes are left out, a warning will be added to the plot.
|-
| Point Size
| weightCol=”SampleSize”
| This specifies that the “dot size” of each data points will reflect the square-root of the sample size. The default is to have all dot sizes equal.
|-
| LD Measure
| ldCol=”dprime” (“rsquare”)
| Colors data points according to the selected LD measure. The default is "rsquare".
|-
| Reference Population for LD
| n/a
| This option allows the user to specify which reference panel is used to obtain LD estimates. The default is CEU from HapMap Phase II but users may select YRI or JPT+CHB from HapMap Phase II, or CEU from 1000 Genomes (August 2009 or June 2010 release).
|-
| Highlight Region of Interest
| hiStart=425Mb hiEnd=425.1Mb
| A grey box can be used to highlight important regions of the genome – this can reflect where an association signal peaks or a region selected for sequencing, for example.
|-
| Theme
| theme=”publication”
| We have created a theme that has larger text and is more easily readable for publication.
|-
| Show Annotation
| showAnnot=T showRefsnpAnnot=T annotPch=”21,24,24,25,22,22,8,7”
| SNP annotation is available for all 1000G SNPs (Aug 2009 release) and can be enabled with the showAnnot=T option. The annotPch command allows you to customize the R plotting symbol used for each kind of SNP; it is okay to use the same symbol for more than one category. The annotation categories, together with their default symbol setting are: Framestop (24, triangle), Splice (24, triangle), NonSynonymous (25, inverted triangle), Synonymous (22, square), UTR (22, square), TFBScons (8, star), MCS44 Placental (7, square with diagonal lines) and None-of-the-above (21, filled circle). For more information about these annotation categories used, please see http://research.nhgri.nih.gov/tools/unisnp/?rm=ohelp
|-
| Recombination Rate Overlay
| showRecomb=T
| The estimated recombination rate from HapMap samples can be shown on the plot or left off. The data plotted are from Hapmap; http://hapmap.ncbi.nlm.nih.gov/downloads/recombination/2008-03_rel22_B36/rates/
|}

For a full list of options that can be used in Batch Mode using a hitspec file, please see [http://genome.sph.umich.edu/wiki/LocusZoom_Standalone#Plotting_options this list]

[[Category:Software]]

Summary Statistics Files Specification for RAREMETAL and rvtests

2019-08-29T15:39:25Z

Abought: Add rmw category tag

[[Category:Software]]
[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
[[Category:rvtests]]
= Summary Files Specification for RAREMETAL =
RAREMETAL use summary statistics files to perform meta-analysis. These includes (1) score statistics file and (2) covariance file.
Both [[RAREMETALWORKER|RAREMETALWORKER]] and [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''] can generate these summary statistics files.

The aim of this wiki page is to explain file formats.

== Input score test statistics file ==

=== Format ===

Header lines begins with '#' or 'CHROM'. After header part, we listed the meaning of each column as following:

# CHROM Chromosome
# POS Position
# REF Reference Allele
# ALT Alternative Allele
# N_INFORMATIVE Count of individuals with genotype and phenotype
# FOUNDER_AF(RAREMETALWORKER only) Allele frequency among founders
# ALL_AF(RAREMETALWORKER only) Allele frequency across entire sample
# AF(rvtests only) Allele frequency (for related samples, this is adjusted allele frequency)
# INFORMATIVE_ALT_AC Copies of the rare allele among samples with genotype and phenotype
# CALL_RATE Fraction of called genotypes
# HWE_PVALUE Exact Hardy-Weinberg equilibrium p-value
# N_REF Count of reference homozygotes
# N_HET Count of heterozygotes
# N_ALT Count of alternative allele homozygotes
# U_STAT Score statistic numerator
# SQRT_V_STAT Score statistic denominator
# ALT_EFF_SIZE Estimated effect size
# PVALUE P-value

=== RAREMETALWORKER Example ===

RAREMETALWORKER generates prefix.traitName.singlevar.score.txt, e.g. prefix.HDL.singlevar.score.txt

##ProgramName=RareMetalWorker
##Version=0.3.4
##Samples=11619
##AnalyzedSamples=5916
##Families=1257
##AnalyzedFamilies=1117
##Founders=3611
##AnalyzedFounders=1023
##Covariates=AGE,AGE2,SEX
##CovariateSummaries min 25th median 75th max mean variance
##AGE 14 29.2 41.9 57 101.3 43.5354 311.366
##AGE2 196 852.64 1755.61 3249 10261.7 2206.65 2.77293e+06
##SEX 1 1 2 2 2 1.5764 0.244204
##InverseNormal=ON
##TraitSummaries min 25th median 75th max mean variance
##TRAIT 27.4 101.822 125.036 149.922 330.482 127.381 1264.63
##AnalyzedTrait -3.7613 -0.674224 0.000211852 0.674756 3.7613 -2.32127e-12 0.999947
##Heritability=33.953%
#CHROM POS REF ALT N_INFORMATIVE FOUNDER_AF ALL_AF INFORMATIVE_ALT_AC CALL_RATE HWE_PVALUE N_REF N_HET N_ALT U_STAT SQRT_V_STAT ALT_EFFSIZE PVALUE SE
1 762320 C T 5916 0.00635386 0.00388776 46 1 1 5870 46 0 3.42523 6.57314 0.0792763 0.602301 0.152149
1 865545 G A 5916 0.000488759 8.45166e-05 1 1 1 5915 1 0 1.32644 1.07745 1.14259 0.21829 0.928141
1 865584 G A 5916 0 0 0 1 1 5916 0 0 NA NA NA NA NA
1 865628 G A 5916 0.00782014 0.00566261 67 1 1 5849 67 0 16.4313 7.82519 0.268338 0.0357464 0.127813

=== Rvtests Example ===
Rvtests generates prefix.MetaScore.assoc, e.g. prefix.MetaScore.assoc

##Samples=2659
##AnalyzedSamples=2659
##Families=2659
##AnalyzedFamilies=2659
##Founders=2659
##AnalyzedFounders=2659
##InverseNormal=ON
##TraitSummary min 25th median 75th max mean variance
##Trait -3.56023 -0.679098 -0.00304512 0.682994 3.56845 0.000710616 1.00065
##AnalyzedTrait -3.55632 -0.674786 0 0.674786 3.55632 -1.10229e-17 0.999884
##Covariates=sex,age,age2,pc1,pc2
##CovariateSummary min 25th median 75th max mean variance
##sex 1 1 1 2 2 1.34524 0.226135
##age 21 55 66 73 91 63.6491 150.565
##age2 441 3025 4356 5329 8281 4201.72 2.25458e+06
##pc1 -0.1946 -0.0041 0.0014 0.0064 0.0246 -0.00027815 0.000184625
##pc2 -0.0957 -0.0067 -0.0005 0.0062 0.0989 0.000239526 0.000188235
CHROM POS REF ALT N_INFORMATIVE AF INFORMATIVE_ALT_AC CALL_RATE HWE_PVALUE N_REF N_HET N_ALT U_STAT SQRT_V_STAT ALT_EFFSIZE PVALUE
1 564766 T C 2659 0.23223 1235 1 0 2041 1 617 20.546 43.5254 0.0108453 0.636894
1 564862 T C 2659 NA NA NA NA NA NA NA NA NA NA NA
1 565111 T C 2659 0.0161715 86 1 4.01334e-96 2616 0 43 0.457052 13.0052 0.00270229 0.971965

== Input covariance test statistic file ==

Covariance test statistics contains the LD matrix among a variant and the adjacent markers within a prefixed-sized window. The default window size is 1MB. It has the following format:

=== Format ===

# CHROM Chromosome
# CURRENT_POS (RAREMETALWORKER only) Position for the first marker in Window
# VAR_POS_IN_WIND (RAREMETALWORKER only) Position for the other markers in window, separated by commas
# COV_MATRICES (RAREMETALWORKER only) Covariance matrix between test statistics
# START_POS (rvtests only) Position for the first marker in sliding window
# END_POS (rvtests only) Position for the last marker in sliding window
# NUM_MARKER (rvtests only) Number of markers in the sliding windows
# MARKER_POS (rvtests only) Number of marker positions in the sliding windows
# COV (rvtests only) Covariance matrix between test statistics

=== RAREMETALWORKER Example ===
RAREMETALWORKER generates prefix.traitName.singlevar.cov.txt, e.g. prefix.HDL.singlevar.cov.txt

CHR POS VAR_POS_IN_WINDOW LD_MATRIX
1 762320 762320,865628,865665,878744,879381,1560000 0.0359084,-0.000242112,-0.00125797,-0.000993422,-0.000344509,-0.00017077,
1 865628 865628,865665,878744,879381,1560000,1864659 0.419804,-0.0103663,-0.00635265,0.0594056,0.0534505,-0.00462183,
1 878744 878744,879381,1560000,1864659,1877659 0.000404537,-0.000235215,-1.4455e-05,-8.69137e-06,-3.1027e-05,

=== Rvtests Example ===
Rvtests generates prefix.MetaCov.assoc.gz, e.g. prefix.HDL.MetaCov.assoc.gz
Later version of rvtests will also generate tabix index file, prefix.MetaCov.assoc.gz

CHR START_POS END_POS NUM_MARKER MARKER_POS COV
1 762320 1560000 6 762320,865628,865665,878744,879381,1560000 0.0359084,-0.000242112,-0.00125797,-0.000993422,-0.000344509,-0.00017077
1 865628 1864659 6 865628,865665,878744,879381,1560000,1864659 0.419804,-0.0103663,-0.00635265,0.0594056,0.0534505,-0.00462183
1 878744 1877659 5 878744,879381,1560000,1864659,1877659 0.000404537,-0.000235215,-1.4455e-05,-8.69137e-06,-3.1027e-05

= Contact =

Please contact Dajiang Liu ([mailto:dajiang@umich.edu]), Xiaowei Zhan ([mailto:zhanxw@umich.edu]), Shuang Feng([mailto:sfengsph@umich.edu]) or Goncalo Abecasis ([mailto:goncalo@umich.edu]).

RAREMETAL METHOD

2019-05-20T17:28:07Z

Abought: Tag category

==INTRODUCTION==
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. Our method has been published in [http://www.ncbi.nlm.nih.gov/pubmed/24336170 '''Liu et. al''']. The main formulae are tabulated in the following:

==KEY FORMULAE==

===NOTATIONS===
We denote the following to describe our methods:

<math>U_{i,k} </math> is the score statistic for the <math>i^{th} </math> variant from the <math> k^{th} </math> study

<math>V_{ij,k} </math> is the covariance of the score statistics between the <math>i^{th} </math> and the <math>j^{th} </math> variant from the <math> k^{th} </math> study

<math>U_{i,k} </math> and <math>V_{ij,k} </math> are described in detail in [[RAREMETALWORKER_method#SINGLE_VARIANT_SCORE_TEST|'''RAREMETALWORKER method''']].

<math>\mathbf{U_k}</math> is the vector of score statistics of rare variants in a gene from the <math> k^{th} </math> study.

<math>\mathbf{V_k}</math> is the variance-covariance matrix of score statistics of rare variants in a gene from the <math> k^{th} </math> study, or <math>\mathbf{V_k} = cov(\mathbf{U_k})</math>

<math> S </math> is the number of studies

<math> f_{i} </math> is the pooled allele frequency of <math>i^{th}</math> variant

<math> f_{i,k} </math> is the allele frequency of <math>i^{th}</math> variant in <math>k^{th}</math> study

<math> {\delta_{k}} </math> is the deviation of trait value of <math>k^{th}</math> study

<math> \mathbf{w^T} = (w_1,w_2,...,w_m)^T</math> is the vector of weights for <math>m</math> rare variants in a gene.

===SINGLE VARIANT META ANALYSIS===
Single variant meta-analysis score statistic can be reconstructed from score statistics and their variances generated by each study, assuming that samples are unrelated across studies. Define meta-analysis score statistics as

<math>U_{meta_i}=\sum_{k=1}^S {U_{i,k}}</math>

and its variance

<math>V_{meta_i}=\sum_{k=1}^S{V_{ii,k}}</math>.

Then the score test statistics for the <math>i^{th}</math> variant <math>T_{meta_i}</math> asymptotically follows standard normal distribution

<math>T_{meta_i}=U_{meta_i}\bigg/\sqrt{V_{meta_i}}=\sum_{k=1}^S {U_{i,k}}\bigg/\sqrt{\sum_{k=1}^S{V_{ii,k}}} \sim\mathbf{N}(0,1)</math>.

'''Optimized method for unbalanced studies (--useExact)''':

<math>U_{meta_i}=\sum_{k=1}^S {U_{i,k}/\hat{\Omega_{k}}}-\sum_{k=1}^S{2n_{k}{\delta_{k}^{2}(f_{i}-f_{i,k})}}</math>

<math>V_{meta_i}={\sigma^{2}}\sum_{k=1}^S{(V_{ii,k}{\Omega_{k}}-4n_{k}(ff'-f_{k}f_{k}'))}</math>

<math>{\sigma^{2}}=\sum_{k=1}^S{((n_{k}-1){\Omega_{k}}+n_{k}{\delta_{k}^{2}})}/(n-1)</math>

===BURDEN META ANALYSIS===

Burden test has been shown to be powerful detecting a group of rare variants that are unidirectional in effects. Once single variant meta analysis statistics are constructed, burden test score statistic for a gene can be easily reconstructed as

<math>T_{meta_{burden}}=\mathbf{w^TU_{meta}}\bigg/\sqrt{\mathbf{w^TV_{meta}w}} \sim\mathbf{N}(0,1)</math>,

where <math>\mathbf{U_{meta}} = (U_{meta_1},U_{meta_2},...,U_{meta_m})^T</math> and <math> \mathbf{V_{meta}}=cov(\mathbf{U_{meta}})</math>, representing a vector of single variant meta-analysis scores of <math>m</math> variants in a gene and the covariance matrix of the scores across <math>m</math> variants.

===VT META ANALYSIS===

Including variants that are not associated to phenotype can hurt power. Variable threshold test is designed to choose the optimal allele frequency threshold amongst rare variants in a gene, to gain power. The test statistic is defined as the maximum burden score statistic calculated using every possible frequency threshold

<math>T_{meta_{VT}}=\max(T_{b\left(f_1\right)},T_{b\left(f_2\right)},\dots,T_{b\left(f_m\right)})</math>,

where <math>T_{b\left(f_i\right)}</math> is the burden test statistic under allele frequency threshold <math>f_i</math>, and can be constructed from single variant meta-analysis statistics using

<math>T_{b\left(f_j\right)}=\boldsymbol{\phi}_{f_j}^\mathbf{T}\mathbf{U_{meta}}\bigg/\sqrt{\boldsymbol{\phi}_{f_j}^\mathbf{T}\mathbf{V_{meta}}\boldsymbol{\phi}_{f_j}} </math>,

where <math>j</math> represents any allele frequency in a group of rare variants, <math>\boldsymbol{\phi}_{f_j}</math> is a vector of 0 and 1, indicating if a variant is included in the analysis using frequency threshold <math>f_i</math>.

As described by [http://www.ncbi.nlm.nih.gov/pubmed/21885029 '''Lin et. al'''], the p-value of this test can be calculated analytically using the fact that the burden test statistics together follow a multivariate normal distribution with mean <math>\mathbf{0}</math> and covariance <math>\boldsymbol{\Omega}</math>, written as

<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) </math>,

where <math>\boldsymbol{\Omega_{ij}}=\frac{\boldsymbol{\phi}_{f_i}^T\mathbf{V_{meta}}\boldsymbol{\phi}_{f_j}}{\sqrt{\boldsymbol{\phi}_{f_i}^T\mathbf{V_{meta}}\boldsymbol{\phi}_{f_i}}\sqrt{\boldsymbol{\phi}_{f_j}^T\mathbf{V_{meta}}\boldsymbol{\phi}_{f_j}}}</math>.

===SKAT META ANALYSIS===

SKAT is most powerful when detecting genes with rare variants having opposite directions in effect sizes. Meta-analysis statistic can also be re-constructed using single variant meta-analysis scores and their covariances

<math>\mathbf{Q}=\mathbf{{U_{meta}}^T}\mathbf{W}\mathbf{U_{meta}}</math>,

where <math>\mathbf{W}</math> is a diagonal matrix of weights of rare variants included in a gene.

As shown in [http://www.ncbi.nlm.nih.gov/pubmed/21737059 '''Wu et. al'''], the null distribution of the <math> \mathbf{Q} </math> statistic follows a mixture chi-sqaured distribution described as

<math>\mathbf{Q}\sim\sum_{i=1}^m{\lambda_i\chi_{1,i}^2}, </math> where <math>\left(\lambda_1,\lambda_2,\dots,\lambda_m\right)</math> are eigen values of <math>\mathbf{V_{meta}^\frac{1}{2}}\mathbf{W}\mathbf{V_{meta}^\frac{1}{2}}</math>.

[[Category:RAREMETAL]]

RAREMETAL Documentation

2019-05-20T17:22:15Z

Abought: Update contact address

[[Category:RAREMETAL]]
== Useful Wiki Pages ==

* Git hub page: https://github.com/statgen/Raremetal

* The [[RAREMETAL_Change_Log | Change Log]]

* The [[RAREMETAL_DOWNLOAD_%26_BUILD | DOWNLOAD page]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Quick Start Tutorial]]
* The [[RAREMETAL METHOD]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETAL Command Reference]]

* The [[RAREMETALWORKER|RAREMETALWORKER documentation]]

The [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''] tool for rare-variant association analysis can also generate output compatible with RAREMETAL.

== Brief Description ==

'''RAREMETAL''' is a computationally efficient tool for meta-analysis of rare variants using sequencing or genotyping array data. 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. 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''' has the following features:
* Performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, and Variable Threshold.
* Performs single variant metal-analysis by default.
* Allows customized groups of variants to be tested.
* Allows conditional analysis to be performed in both gene-level meta-analysis and single variants meta-analysis.
* 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. Our method has been published in [http://www.nature.com/ng/journal/v46/n2/abs/ng.2852.html '''Liu et. al'''] in Nature Genetics. Please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_method '''method'''] for details.

== Download and Installation ==

We have tested compilation using our source code on several platforms including Linux, and Mac OS X.

For source code and executables together with instructions of building from source, please go to [[RAREMETAL_DOWNLOAD_%26_BUILD |'''DOWNLOAD source and executables''']].

For questions about compilation, please go to [[RAREMETAL_FAQ | '''FAQ''']].

== Basic Usage Instructions ==

'''RAREMETAL''' 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====
'''RAREMETAL''' requires the following basic input files: summary statistics and covariance matrices of score statistics generated by '''RAREMETALWORKER''' 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 '''RAREMETALWORKER''' 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
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

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=====
* --summaryFiles 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 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

* When gene-level analysis is requested, --covFiles option should be used to specify the covariance files. An example file is:

/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/HUNT/RareMetalWorker/HUNT_MI_case.TG.singlevar.cov.txt.gz

* 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.

* Please sepcify --dosage option if input files were generated from dosage instead of genotype.

=====Group Rare Variants=====

====== From a Group File ======
* Grouping methods are only necessary when doing gene-based or group-based burden tests in meta-analysis.
* If none of the grouping method is specified, then only single variant meta-analysis will be performed.
* 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:
CHR:POS:REF:ALT
* An example group file is:
PLEKHN1 1:901922:G:A 1:901923:C:A 1:902088:G:A 1:902128:C:T 1:902133:C:G 1:902176:C:T 1:905669:C:G
HES4 1:934735:A:C 1:934770:G:A 1:934801:C:T 1:935085:G:A 1:935089:C:G
ISG15 1:949422:G:A 1:949491:G:A 1:949502:C:T 1:949608:G:A 1:949802:G:A 1:949832:G:A
AGRN 1:970687:C:T 1:976963:A:G 1:977028:G:T 1:977356:C:T 1:977396:G:A 1:978628:C:T 1:978645:G:A
C1orf159 1:1021285:G:T 1:1021302:T:C 1:1021315:A:C 1:1021386:G:A 1:1022534:C:T 1:1025751:C:T 1:1026913:C:T

====== 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 [[Rare-Metal#Example_Command_lines|'''examples''']] of this usage at the bottom of this page.

==== QC Options ====
* '''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''' 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 '''RAREMETAL''', 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, '''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 ==

=== 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 ===
* 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.
* --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
Note: this allows you to group variants that are annotated starting with nonsyn or splicing (not case-sensitive).

* Special format for the annotated VCF file is required: all annotation information should be coded in INFO field in VCF file, starting with the key "ANNO=". An example annotated VCF file is in the following:

#CHROM POS ID REF ALT QUAL FILTER INFO
1 19208194 . G A 100 PASS
AC=3;'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C866T:p.P289L,ALDH4A1:NM_001161504:exon8:c.C686T:p.P229L,ALDH4A1:NM_003748:exon8:c.C866T:p.P289L,;
'''ANNO='''splicing:ALDH4A1
1 19208293 . G C 100 PASS AC=7;STUDIES=5;MAC=7;MAF=0.001;DESIGN=TBD_ASSAY;DSCORE=1.00;
'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C767G:p.P256R,ALDH4A1:NM_001161504:exon8:c.C587G:p.P196R,ALDH4A1:NM_003748:exon8:c.C767G:p.P256R,

* 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.
* Generated group file will be named test.groupfile under your running directory.

===Options for Report Generation===
* --correctGC generates QQ plots and manhattan plots with pvalues corrected using genomic control.
* --prefix allows customized prefix for output files.
* --longOutput allows users to output not only burden test results but also the single variant results (allele frequencies, effect sizes, and p-values) for the variants being grouped together. Please refer to the output files section for detailed explanation and examples.
* --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 [[Rare-Metal#TABULATED_HITS| Tabulated Hits]].

===Miscellaneous Options===
* --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.

== Reports Generated by RAREMETAL ==
=== Single Variant Meta Analysis Output ===

==== TABLES ====

* Single variant meta analysis output has the following components: header, results and footnote.
* Header lines start with "##" shows summary of the meta analysis including method used, number of studies, and total sample size.
* Header line starts with "#" are column headers for results table.
* Footnote also starts with "#", where genomic controls from each study and the overall sample are reported.
* An example single variant meta analysis output is shown below:

##Method=SinglevarScore
##STUDY_NUM=2
##TotalSampleSize=14308
#CHROM POS REF ALT POOLED_ALT_AF EFFECT_SIZE DIRECTION_BY_STUDY PVALUE
1 115658497 G A 0.380906 0.00954332 ++ 0.45828
2 74688884 G A 8.33611e-05 -0.196387 -! 0.845372
3 121414217 C A 0.0747833 0.0216982 -+ 0.34453
6 137245814 G C 0.000803746 0.105693 ++ 0.601805
* 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 --summaryFiles.
"?" 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.

==== PLOTS====

'''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.
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="100" | [[File:QQ.png]]
|-
| align="center" width="200" | [[File:Single_var_manhattan.png]]
|}

=== Gene-level Tests Meta-Analysis Output ===

==== LONG TABLES ====
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.
##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs MAFs SINGLEVAR_EFFECTs SINGLEVAR_PVALUEs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.000166722,0.0242172,0.0109203,0.0355845,0.0333729,0.00700233,0.00200067 -0.183575,-0.00228307,-0.0598337,0.0220595,0.0229464,-0.0302768,-0.0200417 0.790161,0.953446,0.515806,0.503548,0.499251,0.791773,0.926625 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.0148408,0.00108369 -0.0502034,-0.0256403 0.528269,0.934606 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== SHORT TABLES ====
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.

##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== TABULATED HITS ====
* When --tabulateHits is specified, top hits from Burden tests will be generated. Each method will have an individual tabulated file generated. The purpose of this tabulated file is to list burden test results of top hits together with single variant results from variants being grouped in burden tests. The difference between this file and the standard long-format output file from burden test is that each row of the file represents a single variant that is included in the gene for burden test. This format allows each sorting on users end.

* Tabulated top hits are saved in the file:
yourPrefix.meta.tophits.youMethod.tbl (example files names: TG.meta.tophits.burden.tbl, LDL.meta.tophits.SKAT.tbl)

* The following items are tabulated in the output:
GENE: Gene name.
METHOD: Burden test used.
GENE_PVALUE: P-value from gene-based burden tests.
MAF_CUTOFF: MAF cutoff used when doing gene-based tests.
ACTUAL_CUTOFF: Actual MAF cutoff used. (This will be different from MAF_CUTOFF only for Variable Threshold method.
Otherwise, it will be the same as MAF_CUTOFF.)
VAR: Variant name in CHR:POS:REF:ALT format.
MAF: Single variant pooled MAF from all samples.
EFFSIZE: Effect size from single variant meta analysis.
PVALUE: Pvalue from single variant meta analysis.

* An example of tabulated hits from a standard burden test with maf<0.05 as criterion is shown in the following:

GENE METHOD GENE_PVALUE MAF_CUTOFF ACTUAL_CUTOFF VARS MAFS EFFSIZES PVALUES
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55505647:G:T 0.0396631 -0.442192 2.10159e-46
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55518371:G:A 0.0237138 0.0548733 0.430246
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55529187:G:A 0.0433324 0.0946321 0.00129942
APOE BURDEN_0.050 2.83457e-72 0.05 0.05 19:45412079:C:T 0.0413056 -0.554561 2.83457e-72

* According to the example above, PCSK9 had a p-value of 7.54587e-11 from the gene-based burden test, where three variants from this gene were included. Another hit from this meta analysis is APOE, where only one variant was included in the burden test.

==== PLOTS ====
'''RAREMETAL''' generates QQ plots and manhattan plots from single variant and gene-level meta-analysis by default. Example QQ plots and manhattan plots are:
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="200" | [[File:manhattan.png]]
|}

==== LOG ====

* A log file is automatically generated by '''RAREMETAL''' 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 [genes.file]
--annotatedVcf []
--annotation []
--writeVcf [OFF]

QC Options:
============================
--hwe [0]
--callRate [0]

Association Methods:
============================
--burden [true]
--MB [false]
--SKAT [false]
--VT [false]
--condition [condition.file]

Other Options:
============================
--tabix [OFF]
--correctGC [ON]
--prefix [test]
--maf [0.05]
--longOutput [false]
--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 --summaryFiles your.list.of.summary.files --prefix yourPrefix

* When you want to do all burden tests using a group file to specify which variants to group:
./raremetal --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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==
* For a comprehensive tutorial of RAREMETALWORKER and RAREMETAL using example data sets, please go to the following:

[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 Andy Boughton (abought at umich dot edu) for questions.

Also check [[Raremetal Incoming updates | '''Known issues and incoming update in next version''']] to see if your problem has been reported before

RAREMETAL Documentation

2019-03-14T16:53:22Z

Abought: /* Download and Installation */

[[Category:RAREMETAL]]
== Useful Wiki Pages ==

* Git hub page: https://github.com/statgen/Raremetal

* The [[RAREMETAL_Change_Log | Change Log]]

* The [[RAREMETAL_DOWNLOAD_%26_BUILD | DOWNLOAD page]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Quick Start Tutorial]]
* The [[RAREMETAL METHOD]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETAL Command Reference]]

* The [[RAREMETALWORKER|RAREMETALWORKER documentation]]

The [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''] tool for rare-variant association analysis can also generate output compatible with RAREMETAL.

== Brief Description ==

'''RAREMETAL''' is a computationally efficient tool for meta-analysis of rare variants using sequencing or genotyping array data. 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. 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''' has the following features:
* Performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, and Variable Threshold.
* Performs single variant metal-analysis by default.
* Allows customized groups of variants to be tested.
* Allows conditional analysis to be performed in both gene-level meta-analysis and single variants meta-analysis.
* 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. Our method has been published in [http://www.nature.com/ng/journal/v46/n2/abs/ng.2852.html '''Liu et. al'''] in Nature Genetics. Please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_method '''method'''] for details.

== Download and Installation ==

We have tested compilation using our source code on several platforms including Linux, and Mac OS X.

For source code and executables together with instructions of building from source, please go to [[RAREMETAL_DOWNLOAD_%26_BUILD |'''DOWNLOAD source and executables''']].

For questions about compilation, please go to [[RAREMETAL_FAQ | '''FAQ''']].

== Basic Usage Instructions ==

'''RAREMETAL''' 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====
'''RAREMETAL''' requires the following basic input files: summary statistics and covariance matrices of score statistics generated by '''RAREMETALWORKER''' 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 '''RAREMETALWORKER''' 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
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

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=====
* --summaryFiles 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 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

* When gene-level analysis is requested, --covFiles option should be used to specify the covariance files. An example file is:

/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/HUNT/RareMetalWorker/HUNT_MI_case.TG.singlevar.cov.txt.gz

* 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.

* Please sepcify --dosage option if input files were generated from dosage instead of genotype.

=====Group Rare Variants=====

====== From a Group File ======
* Grouping methods are only necessary when doing gene-based or group-based burden tests in meta-analysis.
* If none of the grouping method is specified, then only single variant meta-analysis will be performed.
* 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:
CHR:POS:REF:ALT
* An example group file is:
PLEKHN1 1:901922:G:A 1:901923:C:A 1:902088:G:A 1:902128:C:T 1:902133:C:G 1:902176:C:T 1:905669:C:G
HES4 1:934735:A:C 1:934770:G:A 1:934801:C:T 1:935085:G:A 1:935089:C:G
ISG15 1:949422:G:A 1:949491:G:A 1:949502:C:T 1:949608:G:A 1:949802:G:A 1:949832:G:A
AGRN 1:970687:C:T 1:976963:A:G 1:977028:G:T 1:977356:C:T 1:977396:G:A 1:978628:C:T 1:978645:G:A
C1orf159 1:1021285:G:T 1:1021302:T:C 1:1021315:A:C 1:1021386:G:A 1:1022534:C:T 1:1025751:C:T 1:1026913:C:T

====== 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 [[Rare-Metal#Example_Command_lines|'''examples''']] of this usage at the bottom of this page.

==== QC Options ====
* '''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''' 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 '''RAREMETAL''', 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, '''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 ==

=== 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 ===
* 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.
* --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
Note: this allows you to group variants that are annotated starting with nonsyn or splicing (not case-sensitive).

* Special format for the annotated VCF file is required: all annotation information should be coded in INFO field in VCF file, starting with the key "ANNO=". An example annotated VCF file is in the following:

#CHROM POS ID REF ALT QUAL FILTER INFO
1 19208194 . G A 100 PASS
AC=3;'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C866T:p.P289L,ALDH4A1:NM_001161504:exon8:c.C686T:p.P229L,ALDH4A1:NM_003748:exon8:c.C866T:p.P289L,;
'''ANNO='''splicing:ALDH4A1
1 19208293 . G C 100 PASS AC=7;STUDIES=5;MAC=7;MAF=0.001;DESIGN=TBD_ASSAY;DSCORE=1.00;
'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C767G:p.P256R,ALDH4A1:NM_001161504:exon8:c.C587G:p.P196R,ALDH4A1:NM_003748:exon8:c.C767G:p.P256R,

* 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.
* Generated group file will be named test.groupfile under your running directory.

===Options for Report Generation===
* --correctGC generates QQ plots and manhattan plots with pvalues corrected using genomic control.
* --prefix allows customized prefix for output files.
* --longOutput allows users to output not only burden test results but also the single variant results (allele frequencies, effect sizes, and p-values) for the variants being grouped together. Please refer to the output files section for detailed explanation and examples.
* --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 [[Rare-Metal#TABULATED_HITS| Tabulated Hits]].

===Miscellaneous Options===
* --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.

== Reports Generated by RAREMETAL ==
=== Single Variant Meta Analysis Output ===

==== TABLES ====

* Single variant meta analysis output has the following components: header, results and footnote.
* Header lines start with "##" shows summary of the meta analysis including method used, number of studies, and total sample size.
* Header line starts with "#" are column headers for results table.
* Footnote also starts with "#", where genomic controls from each study and the overall sample are reported.
* An example single variant meta analysis output is shown below:

##Method=SinglevarScore
##STUDY_NUM=2
##TotalSampleSize=14308
#CHROM POS REF ALT POOLED_ALT_AF EFFECT_SIZE DIRECTION_BY_STUDY PVALUE
1 115658497 G A 0.380906 0.00954332 ++ 0.45828
2 74688884 G A 8.33611e-05 -0.196387 -! 0.845372
3 121414217 C A 0.0747833 0.0216982 -+ 0.34453
6 137245814 G C 0.000803746 0.105693 ++ 0.601805
* 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 --summaryFiles.
"?" 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.

==== PLOTS====

'''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.
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="100" | [[File:QQ.png]]
|-
| align="center" width="200" | [[File:Single_var_manhattan.png]]
|}

=== Gene-level Tests Meta-Analysis Output ===

==== LONG TABLES ====
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.
##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs MAFs SINGLEVAR_EFFECTs SINGLEVAR_PVALUEs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.000166722,0.0242172,0.0109203,0.0355845,0.0333729,0.00700233,0.00200067 -0.183575,-0.00228307,-0.0598337,0.0220595,0.0229464,-0.0302768,-0.0200417 0.790161,0.953446,0.515806,0.503548,0.499251,0.791773,0.926625 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.0148408,0.00108369 -0.0502034,-0.0256403 0.528269,0.934606 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== SHORT TABLES ====
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.

##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== TABULATED HITS ====
* When --tabulateHits is specified, top hits from Burden tests will be generated. Each method will have an individual tabulated file generated. The purpose of this tabulated file is to list burden test results of top hits together with single variant results from variants being grouped in burden tests. The difference between this file and the standard long-format output file from burden test is that each row of the file represents a single variant that is included in the gene for burden test. This format allows each sorting on users end.

* Tabulated top hits are saved in the file:
yourPrefix.meta.tophits.youMethod.tbl (example files names: TG.meta.tophits.burden.tbl, LDL.meta.tophits.SKAT.tbl)

* The following items are tabulated in the output:
GENE: Gene name.
METHOD: Burden test used.
GENE_PVALUE: P-value from gene-based burden tests.
MAF_CUTOFF: MAF cutoff used when doing gene-based tests.
ACTUAL_CUTOFF: Actual MAF cutoff used. (This will be different from MAF_CUTOFF only for Variable Threshold method.
Otherwise, it will be the same as MAF_CUTOFF.)
VAR: Variant name in CHR:POS:REF:ALT format.
MAF: Single variant pooled MAF from all samples.
EFFSIZE: Effect size from single variant meta analysis.
PVALUE: Pvalue from single variant meta analysis.

* An example of tabulated hits from a standard burden test with maf<0.05 as criterion is shown in the following:

GENE METHOD GENE_PVALUE MAF_CUTOFF ACTUAL_CUTOFF VARS MAFS EFFSIZES PVALUES
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55505647:G:T 0.0396631 -0.442192 2.10159e-46
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55518371:G:A 0.0237138 0.0548733 0.430246
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55529187:G:A 0.0433324 0.0946321 0.00129942
APOE BURDEN_0.050 2.83457e-72 0.05 0.05 19:45412079:C:T 0.0413056 -0.554561 2.83457e-72

* According to the example above, PCSK9 had a p-value of 7.54587e-11 from the gene-based burden test, where three variants from this gene were included. Another hit from this meta analysis is APOE, where only one variant was included in the burden test.

==== PLOTS ====
'''RAREMETAL''' generates QQ plots and manhattan plots from single variant and gene-level meta-analysis by default. Example QQ plots and manhattan plots are:
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="200" | [[File:manhattan.png]]
|}

==== LOG ====

* A log file is automatically generated by '''RAREMETAL''' 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 [genes.file]
--annotatedVcf []
--annotation []
--writeVcf [OFF]

QC Options:
============================
--hwe [0]
--callRate [0]

Association Methods:
============================
--burden [true]
--MB [false]
--SKAT [false]
--VT [false]
--condition [condition.file]

Other Options:
============================
--tabix [OFF]
--correctGC [ON]
--prefix [test]
--maf [0.05]
--longOutput [false]
--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 --summaryFiles your.list.of.summary.files --prefix yourPrefix

* When you want to do all burden tests using a group file to specify which variants to group:
./raremetal --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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==
* For a comprehensive tutorial of RAREMETALWORKER and RAREMETAL using example data sets, please go to the following:

[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 Sai Chen (saichen at umich dot edu) for questions.

Also check [[Raremetal Incoming updates | '''Known issues and incoming update in next version''']] to see if your problem has been reported before

Raremetal Incoming updates

2019-03-14T16:52:42Z

Abought: Link to issue tracker

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
==Main Wiki Page==

* [[RAREMETAL_Change_Log | RAREMETAL Change log]]

==Reporting a bug==
Please report issues at our GitHub repository [https://github.com/statgen/raremetal/issues issue tracker]. When possible, include your platform (Ubuntu, CentOS, Mac OS, etc), as well as any relevant commands and output that can help us to identify the problem.

==Incoming update==
* Add an option to store group file from vcf
* Take snpeff as annotation input
* When no conditional variant is available, warning is generated but not written to log file.
* enable reading from .gz annotated vcf
* add SKAT-O
* solve the numeric issue of lambda = 0 in SKAT
* In conditional analysis, when cov matrix between the test variant and its conditioned variants is not invertible, MathSVD still tries to invert that matrix and that leads to weird conditional p values.
* '''Optimization for binary traits'''
* '''Memory optimization for gene-based test in large panel'''

RAREMETAL Change Log

2019-03-14T16:50:12Z

Abought: v4.15.0

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
==Main Wiki Page==
* The [[RAREMETAL_Documentation | '''RAREMETAL documentation''']]
* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]

== Change Log ==

* For versions 4.15.0 and later, see the official "releases" page on GitHub: https://github.com/statgen/raremetal/releases
** Note: versions in the 4.14.x series were prone to a bug with that gave incorrect results for SKAT and burden test methods.
** Note: users of a specific long-lived [https://github.com/statgen/raremetal/commit/a1e648edc98a1097e79f18ecf4f2ffd69542ba1b pre-release v4.15.0 candidate] ( April 19, 2018 ) may be affected by an issue with which variants are selected for analysis. If your version incorporates the linked GitHub commit, your results may be affected. Previous release candidates based on that branch should be ok.

* Version 4.14.0 released (11/27/2016)
** '''Optimized method for unbalanced studies with no family structure (--useExact)'''. Check [[RAREMETAL METHOD]]
** bug fixes in conditional analysis
** fixed headers
** more methods in burden test

* Version 4.13.9 released (07/14/2016)
** The source code has been optimized to prepare for incoming new meta-analysis method in next version.
** Reduced running time when reading >10,000s individuals from vcf
** '''Fixed seg fault in raremetalworker for calculating SNP HWE p value when sample size > 40k'''
** A seg fault: sometimes you only have very few variants but raremetal still tries to calculate GC.

* Version 4.13.8 released (12/13/2015)
** when grouping from vcf, raremetal now obtains information only from "ANNOFULL" field.
** fixed seg fault in matching --annotation option to vcf annotation.
** with empty --annotation option, raremetal now groups all non-intergenic variants.
** '''fixed a bug in conditional analysis when there are multiple variants to condition on'''.
** fixed a seg fault in calculating genomic control.
** add --variantList option in RaremetalWorker to only calculate variance-covariance matrix between certain markers.
** add --range option in both Raremetal and RaremetalWorker to focus on given region only.

* Version 4.13.7 released. (9/18/2015).
** group file generated from annotated vcf is now stored in "test.groupfile" under current running directory.
** use -O0 option in compiling. In very rare situations, gcc optimization will affect the results.
** tabix RMW output with --zip toggled.
** In SKAT meta analysis, skip the variant when all its lambdas are zero.
** bug fixes in conditional analysis: in very rare situation raremetal takes rvtest input as raremetalworker input.
** add --altMAF option to exclude studies in which a variant is not present.

* Version 4.13.6 released. (3/8/2015)
** add a new option --mergedVCFID to recognize VCF files with sample IDs in "FAMID_PID" format
** add a new option --flagDosage to flag the field name to label dosage in VCF file.

* Version 4.13.5 released. (9/29/2014)
** a bug fixed in conditional analysis in raremetal.

* Version 4.13.4 released.
** store beta estimates of intercept and fixed effects in rarmetalworker *.singlevar.score.txt header.

* Version 4.13.3 released.
** read rvtest output format correctly in raremetal.

* Version 4.13.2.
** fixed sqrt_V output when analyzing unrelated individuals without kinship and --inverseNormal is not used and trait variance is not one.

* Version 4.13.1.
** fixed a bug affecting output format when ped/dat files are used together with --dominant --recessive options.

* version 4.13
** fixed bug when using --vcX option.
** Fixed bug estimating kinshipX with female samples.
** Added --kinOnly option for generating kinship only without association analysis.
** Added --geneMap option to allow user input for gene-mapping file.

* version 4.12.1
** fixed command interface display issue in raremetalworker.

* version 4.12
** improved make file for better compilation.

* version 4.11
** fixed a bug for inverse-normalizing traits (a bug only in version 4.9 and later).

* version 4.10
** fixed a bug when analyzing multiple traits is requested in raremetalworker (bug only in version 4.9 and later, and doesn't affect results).

===Version 4.8 and before===
* Released version 0.4.7 (4/24/2014).
** optimized code to increase analysis efficiency and reduce memory use.
** added --separateX option to provide another choice of analyzing chromosome X.
** added --kinxFile option to allow kinship X matrix file with different prefix from the autosomal kinship.
** merged raremetal and raremetalworker in one package following version number of raremetalworker.
** completed testing compiling on various platforms.
* Released version 0.4.6 binary. Fixed a bug in recessive and dominant results. (4/1/2014)
* Released version 0.4.5. Fixed a bug when generating plots for recessive results. (3/18/2014)
* Released version 0.4.4. (3/17/2014)
** bug fixed when alleles are flipped in group file.
** fixed hwe=0.0 issue for monomorphic sites.
* Released version 0.4.3. Fixed a few typo in messages. Added --noeof option for VCF files that does not have a BGZF EOF marker.
* Released version 0.4.2. (3/10/2014)
** fixed a bug that could possibly cause compiling error in some Linux system. male heterozygous
** male genotypes on chromosome X are considered missing.
** bug fixed for SKAT when there are two variants in a group
** bug fixed in Makefile for easy compiling.
* Released version 0.4.1. Fixed a bug handling variants in nonPAR region on chromosome X when all samples are male.
* Released version 0.4.0.
** added phone home function. Saved Recessive and dominant results in separate files.
** a few bugs fixed to properly handling missing genotypes.
** Major change in command options.
** allow user to specify list of summary statistics files and covariance files separately using --summaryFiles and --covFiles options.
* Released version 0.3.7. Added dominant and recessive models as options. The default model is additive. (1/7/2014)
* Released version 0.3.6 and fixed a minor bug that caused by code upgrades from version 0.3.5. (12/4/2013)
* Fixed a few bugs handling chromosome X. Generated warning messages when male genotypes are coded wrong in VCF file. (11/25/2013)
* Version 0.3.1 released to fix a bug when one of the alleles coded as missing.
* Version 0.2.9 released after fixing a bug in SKAT and writing PDF when all variants are monomorphic. (10/7/2013)
* Fixed the bug which causes crash when writing PDF when all variants are monomorphic. (10/6/2013)
* Added support for analyzing dosages from VCF in version 2.9. (8/27/2013)
* Version 0.1.2 released after fixing a few bugs, adding conditional analysis and automatic graphing to the tool. (8/5/2013)
* Fixed bug in handling chromosome X. Added sanity checking steps before analysis. Added graphic support by generating QQ and manhattan plots automatically. Upgraded tool to version 2.8. (till 8/12/2013)
* Updated code to report allele frequencies calculated only from selected samples. (3/3/2013)
* Optimized code to speed up the process of calculating empirical kinship. (3/3/2013)
* Fixed a bug when handling chromosome X. Added sex labels option. (3/2/2013)
* Version 0.0.1 released. (2/24/2013)
* Version 0.0.1 released to U of M CSG group. (2/13/2013)
* Fixed a bug when there is missing genotype from VCF file. (2/2013)
* Fixed a bug when reading vcf file with ref or alt allele is missing. (2/5/2013)
* Changed executable name into bin/raremetalworker. Version 0.0.7 released. (12/10/2012)
* Updated output format for monomorphic sites. (12/7/2012)
* Version 0.0.6 released. (12/6/2012)
* Bug fixed for empirical kinship calculation when genotypes are read from VCF file. Version 0.0.5 released. (12/6/2012)
* Version 0.0.4 released. (12/5/2012)
* More messages coded into log file. (12/4/2012)
* Updated output format. Version 0.0.3 released. (12/3/2012)
* Bugs fixed to solve compiling errors on some machines (Thank you Mary Kate!). Version 0.0.2 released. (11/30/2012)
* Added HWE pvalue and call rate in summary statistics output. (11/27/2012)
* Forced sample IDs to be matched when reading in kinship from a file. Perform a sanity check before reading in kinship file. If a sample of interest is not included in kinship file, then fatal error will occur. (11/19/2012)
* Enabled writing log file by defalut. (11/18/2012)
* Uploaded to public wiki. (11/16/2012)
* Modified Rare-Metal-Worker to let it output LD matrix by a sliding window. (11/14/2012)
* Version 0.0.1 was released on 11/13/2012.

RAREMETAL DOWNLOAD & BUILD

2019-03-14T16:44:00Z

Abought: Release 4.15.0; simplify release notes to point to self-contained repository.

RAREMETAL FAQ

2018-03-20T15:46:00Z

Abought:

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
==COMPILE PROBLEMS==
===error: zlib.h: No such file or directory===
Error:

make -C ../../libStatGen --no-print-directory opt
gcc -O4 -pipe -Wall -I../include -I. -D__ZLIB_AVAILABLE__ -D_FILE_OFFSET_BITS=64 -D__STDC_LIMIT_MACROS -o obj/bgzf.o -c bgzf.c
In file included from bgzf.c:37:
bgzf.h:30:18: error: zlib.h: No such file or directory
bgzf.c: In function âopen_writeâ:
bgzf.c:187: error: âZ_DEFAULT_COMPRESSIONâ undeclared (first use in this function)
bgzf.c:187: error: (Each undeclared identifier is reported only once
bgzf.c:187: error: for each function it appears in.)
bgzf.c: In function âdeflate_blockâ:
bgzf.c:298: error: âz_streamâ undeclared (first use in this function)
bgzf.c:298: error: expected â;â before âzsâ
bgzf.c:299: error: âzsâ undeclared (first use in this function)
bgzf.c:306: warning: implicit declaration of function âdeflateInit2â
bgzf.c:306: error: âZ_DEFLATEDâ undeclared (first use in this function)

====SOLUTION====
Based on the compile error, it appears that the development verison of zlib may not be installed. Please go to http://genome.sph.umich.edu/wiki/Zlib for more information.

User can compile the library without ZLIB, but then the code will not be able to read compressed files (typically BAM files are compressed).
If no compressed files is needed, then user can compile using: make ZLIB_AVAIL=0.

===error: undefined reference to `_gfortran_pow_r8_i4'===
Error:

../../libStatGen/libStatGen.a(mvt.o): In function `mvtdns_':
mvt.f:(.text+0x20c9): undefined reference to `_gfortran_pow_r8_i4'
../../libStatGen/libStatGen.a(mvt.o): In function `mvchnv_':
mvt.f:(.text+0x5848): undefined reference to `_gfortran_pow_r8_i4'
collect2: ld returned 1 exit status
make: *** [../bin/raremetal] Error 1

====SOLUTION====

It looks like in some versions of compilers, the Fortran library (required by RareMetal) isn't automatically included.
These Makefile changes fixed it on the machine where I was able to recreate your compile issue:

1) libStatGen/Makefiles/Makefile.src, edit the settings for OPT_BUILD, DEBUG_BUILD, and PROFILE_BUILD to be (the new part is in bold):
OPT_BUILD = $(CXX) $(COMPFLAGS) $(USER_LINK_OPTIONS) -o $(PROG_OPT) $(OBJECTS_OPT) $(USER_LIBS) $(REQ_LIBS_OPT) -lm $(ZLIB_LIB) '''$(OTHER_LIBS)'''
DEBUG_BUILD = $(CXX) $(COMPFLAGS) $(USER_LINK_OPTIONS) -o $(PROG_DEBUG) $(OBJECTS_DEBUG) $(USER_LIBS) $(REQ_LIBS_DEBUG) -lm $(ZLIB_LIB) '''$(OTHER_LIBS)'''
PROFILE_BUILD = $(CXX) $(COMPFLAGS) $(USER_LINK_OPTIONS) -o $(PROG_PROFILE) $(OBJECTS_PROFILE) $(USER_LIBS) $(REQ_LIBS_PROFILE) -lm $(ZLIB_LIB) '''$(OTHER_LIBS)'''

2) raremetal/src/Makefile, add: (I added it on the line right after USER_LIBS is defined.)
OTHER_LIBS = -lgfortran
NOTE: this has been fixed by identifying a bug in makefile. If you still see the same error message, please try the above solutions.

===error while loading shared libraries===
Error:
gcc -O4 -pipe -Wall -I../include -I. -D__ZLIB_AVAILABLE__ -D_FILE_OFFSET_BITS=64 -D__STDC_LIMIT_MACROS -o obj/bgzf.o -c bgzf.c
/broad/software/free/Linux/redhat_5_x86_64/pkgs/gcc_4.4.4/libexec/gcc/x86_64-unknown-linux-gnu/4.4.4/cc1: error while loading shared libraries: libmpfr.so.1: cannot open shared object file: No such file or directory
make[2]: *** [obj/bgzf.o] Error 1
make[1]: *** [samtools] Error 2
make: *** [../../libStatGen/libStatGen. a] Error 2

====SOLUTION====
If you are using version 0.4.4 and under, please go to our wiki page to download the newest version [[RAREMETAL_Documentation#Where_to_Download | '''download RAREMETAL''']]. There was a bug in makefile in older versions of RAREMETAL that could cause this error and it has been fixed. For a quick fix, please go to /raremetal/src and open "Makefile". Then comment out the lines at the bottom of raremetal/src/Makefile that set LD_LIBRARY_PATH. Try compiling and see if it works.

===error: can not find Makefile.base ===

../libStatGen/Makefiles/Makefile.tool:4: Makefile.base: No such file or directory
../libStatGen/Makefiles/Makefile.tool:23: *** first argument to `word' function must be greater than 0. Stop.

====SOLUTION====
This is most likely that you are having an older version of Make. To compile, you have to use Make version 3.80 and older. To get updated version of make, please go to [http://ftp.gnu.org/gnu/make '''make download'''].

==RUNTIME ERRORS==
===error: BGZF EOF marker is missing in xxx.vcf.gz===
Loading input files...
Loading DAT files ... done.
Loading PED files ... done.

BGZF EOF marker is missing in xxx.vcf.gz
Exiting, exception thrown: FAIL_IO: Failed to open xxx.vcf.gz

====SOLUTION====
This problem has been solved. If you are using version 0.4.5 or older, please download the newest version [[RAREMETALWORKER#Where_to_Download |'''download RAREMETALWORKER''']], and then in your command line, add --noeof. If you still see the error message, then you need to check if your bgzip has been updated to current version.

===recommended strategies for debugging===
The ideal would be to send us your data so that we can debug. But if data sharing is not an option, you can use the following strategy to generate a backtrace and send it to us, without sharing the raw data.

How to Generate a backtrace of the error:
This will allow us to see where in the code it hit a segmentation fault. This method isn't perfect and may still leave us with further questions for you before we can come to an answer.
1) Compile for debug: make debug
2) Enable core dumps in the window where he will run: ulimit -c unlimited
3) Run bin/debug/raremetal
(If this does not coredump, then set OPTFLAG_OPT = -g -O4 in src/Makefile and try rerunning the bin/raremetal version - this will run optimized, but with the debug symbols)
4) Run: gdb bin/debug/raremetal core
(specifying the bath to the raremetal executable that was run & the path to the generated core file)
5) In the gdb window, type: bt.
6) Save the backtrace results and send it to us.
That will generate the backtrace which will help us see where the segmentation fault occurred.

==GENERAL QUESTIONS==
===What is RAREMETALWORKER? How is it related to RAREMETAL?===

A: [[Rare-Metal-Worker|'''RAREMETALWORKER''']] is the program that generates summary statistics for individual studies to share. It generates both single variant association results and covariance matrices of score statistics together with QC statistics. It enables analysis of familial data, population data, unrelated individuals and samples with cryptic relatedness and population stratification. [[RareMETAL|'''RAREMETAL''']] takes the summary statistics generated by RAREMETALWORKER to perform both single variant and gene-level association analysis.

Raremetal Incoming updates

2018-03-16T21:55:14Z

Abought:

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
==Main Wiki Page==

* [[RAREMETAL_Change_Log | RAREMETAL Change log]]

==Incoming update==
* Add an option to store group file from vcf
* Take snpeff as annotation input
* When no conditional variant is available, warning is generated but not written to log file.
* enable reading from .gz annotated vcf
* add SKAT-O
* solve the numeric issue of lambda = 0 in SKAT
* In conditional analysis, when cov matrix between the test variant and its conditioned variants is not invertible, MathSVD still tries to invert that matrix and that leads to weird conditional p values.
* '''Optimization for binary traits'''
* '''Memory optimization for gene-based test in large panel'''

RAREMETAL DOWNLOAD & BUILD

2018-03-16T21:54:50Z

Abought:

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
== Useful Wiki Pages ==

* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]
* The [[RAREMETAL_Documentation | '''RAREMETAL documentation''']]
* The [[RAREMETAL FAQ | '''FAQ''']]
* The [[RAREMETAL_Change_Log | '''Change Log''']]

== Where to Download ==

* University of Michigan CSG users can go to the following:
/net/wonderland/home/saichen/Raremetal/

===GIT HUB===

Please clone or download from GitHub:

https://github.com/statgen/Raremetal

There is a known issue with the newest versions (>=4.14.0) of RAREMETAL, which may give incorrect p-values for some burden test calculation methods. We are working on a fix, but for now we recommend using an older version (<= 4.13.9).

Since v4.13.6, MAC and WINDOWS version are no longer updated. Please download old versions from here:

* [[Media:MAC_raremetal.4.13.6.tgz ‎|'''for MAC OS X''']]

* [[Media:CYGWIN64_raremetal.4.13.6.tgz ‎|'''for Windows/CygWin64''']]

* [[Media:MINGW_raremetal.4.13.6.tgz ‎|'''for Windows/MinGW''']]

From version 4.13.6, RAREMETALWORKER and RAREMETAL are distributed within the same package.

===SCRIPTS===

====Calculating Odds Ratio from RAREMETALWORKER output====
*If you want to estimate '''Odds Ratios''' of variants analyzed by RAREMETALWORKER, the script [[Media:CalculateOddsRatio.tgz|'''calculateOddsRatio.pl''']] can help you augment RAREMETALWORKER output with estimated odds ratio to the last column.
*The script can also be found in the RAREMETAL package 4.13.6 and later, under directory '''raremetal/script/calculateOddsRatio.pl'''.

== How to Compile ==

* gfortran is necessary to build RAREMETAL. If your system does not have it yet, please go to [http://gcc.gnu.org/wiki/GFortranBinaries '''GNU gfortran'''] for download.

* If you prefer to build from scratch, then do the following in your Raremetal directory:
prompt> make clean
prompt> make
#This builds RAREMETAL and RAREMETALWORKER under bin/ directory.

* If you prefer to build individual tool:
prompt> cd Raremetal/raremetalworker/
prompt> make
#This will build RAREMETALWORKER under raremetal/bin/ directory.

prompt> cd Raremetal/raremetal/
prompt> make
#This will build RAREMETAL under raremetal/bin/ directory.

* If your compiler is adaptable to openmp (parallel computing), then use the following to build RAREMETALWORKER that allows parallel computing. For more about openmp, please refer to [http://openmp.org/wp/openmp-compilers/ openMP].
prompt> cd raremetalworker/src
prompt> make openmp
#This will build RAREMETALWORKER under raremetal/bin/ directory.

* If you prefer to use the binary file downloaded above, then no compiling is needed, but it is not guaranteed to work due to system and library requirements.

==FAQ==

For compiling questions, please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_FAQ ''' FAQ'''] for more information.

==OLD VERSIONS==
(All linux versions)
* [[Media:Raremetal.4.13.8.tar.gz ‎|'''v4.13.8''']]
* [[Media:Raremetal.4.13.6.tar.gz ‎|'''v4.13.6''']]

RAREMETAL Command Reference

2018-03-16T21:53:46Z

Abought:

[[Category:RAREMETAL]]
==Useful Pages==
* The [[RAREMETAL| Home Page]]

* The [[RAREMETAL_Documentation|RAREMETAL Documentation]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Tutorial]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETALWORKER | RAREMETALWORKER documentation]]

==Command References==
=== Overview of Options ===
Options:
List of Studies : --studyName []
Grouping Methods : --groupFile [], --annotatedVcf [], --annotation [],
--writeVcf
QC Options : --hwe [1.0e-05], --callRate [0.95]
Association Methods : --burden, --MB, --SKAT, --VT, --condition []
Other Options : --labelHits, --correctGC, --prefix [],
--mapFile [../src/refFlat_hg19.txt], --maf [0.05],
--longOutput, --tabulateHits, --hitsCutoff [1.0e-06]
--altMAF

=== Describing Studies ===
--studyName [your.list.of.studies.file]

Additional details on this option is [[Rare-Metal#List_of_Studies_2|available]].

=== Methods to Group Rare Variants ===

--groupFile [your.groups.file]
--annotatedVcf [your.annotated.vcf]
--annotation [nonsyn/stop/splice]
--writeVcf [ON|OFF]

Additional details on [[Rare-Metal#Grouping_from_a_Group_File|groupFile]], [[Rare-Metal#Grouping_from_an_Annotated_VCF_File|annotatedVcf, annotation]] and [[Rare-Metal#Generate_a_VCF_File_to_Annotate_Outside_of_Rare_Metal|writeVcf]] options are available.

=== QC Options ===
--hwe [hwe.pvalue.cutoff] (default = 1e-05)
--callRate [variant.call.rate.cutoff] (default = 0.95)

Additional details on these options are [[Rare-Metal#QC_Options|available]].

=== Association Methods for Meta-analysis ===
--useExact optimized method for unbalanced studies with unrelated samples,
described [[RAREMETAL METHOD#SINGLE_VARIANT_SCORE_TEST]].
--burden burden test with equal weight
--MAB burden test with MAF as weight
--MB burden test with sqrt(maf(1-maf)) as weight
--BBeta beta distribution as weight
--VT variant threshold test
--SKAT standard SKAT test
--condition [your.list.of variants.to.be.conditioned.upon]
Additional details for these options are [[Rare-Metal#Association_Methods|available]].

=== Other Options for Performance and Amenities ===
--labelHits [ON|OFF]
--correctGC [ON|OFF]
--prefix [your.prefix]
--maf [your.maf.threshold.for.gene-level.tests] (default = 0.05)
--longOutput [ON|OFF]
--tabulateHits [ON|OFF]
--hitsCutoff [your.cutoff.for.hits] (default = 1e-06)
--altMAF [if specified, studies that do not contain the variant will be excluded.]

Additional details for these options are [[Rare-Metal#Other_Options|available]].

Summary Statistics Files Specification for RAREMETAL and rvtests

2018-03-16T21:53:24Z

Abought:

[[Category:Software]]
[[Category:RAREMETAL]]
[[Category:rvtests]]
= Summary Files Specification for RAREMETAL =
RAREMETAL use summary statistics files to perform meta-analysis. These includes (1) score statistics file and (2) covariance file.
Both [[RAREMETALWORKER|RAREMETALWORKER]] and [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''] can generate these summary statistics files.

The aim of this wiki page is to explain file formats.

== Input score test statistics file ==

=== Format ===

Header lines begins with '#' or 'CHROM'. After header part, we listed the meaning of each column as following:

# CHROM Chromosome
# POS Position
# REF Reference Allele
# ALT Alternative Allele
# N_INFORMATIVE Count of individuals with genotype and phenotype
# FOUNDER_AF(RAREMETALWORKER only) Allele frequency among founders
# ALL_AF(RAREMETALWORKER only) Allele frequency across entire sample
# AF(rvtests only) Allele frequency (for related samples, this is adjusted allele frequency)
# INFORMATIVE_ALT_AC Copies of the rare allele among samples with genotype and phenotype
# CALL_RATE Fraction of called genotypes
# HWE_PVALUE Exact Hardy-Weinberg equilibrium p-value
# N_REF Count of reference homozygotes
# N_HET Count of heterozygotes
# N_ALT Count of alternative allele homozygotes
# U_STAT Score statistic numerator
# SQRT_V_STAT Score statistic denominator
# ALT_EFF_SIZE Estimated effect size
# PVALUE P-value

=== RAREMETALWORKER Example ===

RAREMETALWORKER generates prefix.traitName.singlevar.score.txt, e.g. prefix.HDL.singlevar.score.txt

##ProgramName=RareMetalWorker
##Version=0.3.4
##Samples=11619
##AnalyzedSamples=5916
##Families=1257
##AnalyzedFamilies=1117
##Founders=3611
##AnalyzedFounders=1023
##Covariates=AGE,AGE2,SEX
##CovariateSummaries min 25th median 75th max mean variance
##AGE 14 29.2 41.9 57 101.3 43.5354 311.366
##AGE2 196 852.64 1755.61 3249 10261.7 2206.65 2.77293e+06
##SEX 1 1 2 2 2 1.5764 0.244204
##InverseNormal=ON
##TraitSummaries min 25th median 75th max mean variance
##TRAIT 27.4 101.822 125.036 149.922 330.482 127.381 1264.63
##AnalyzedTrait -3.7613 -0.674224 0.000211852 0.674756 3.7613 -2.32127e-12 0.999947
##Heritability=33.953%
#CHROM POS REF ALT N_INFORMATIVE FOUNDER_AF ALL_AF INFORMATIVE_ALT_AC CALL_RATE HWE_PVALUE N_REF N_HET N_ALT U_STAT SQRT_V_STAT ALT_EFFSIZE PVALUE SE
1 762320 C T 5916 0.00635386 0.00388776 46 1 1 5870 46 0 3.42523 6.57314 0.0792763 0.602301 0.152149
1 865545 G A 5916 0.000488759 8.45166e-05 1 1 1 5915 1 0 1.32644 1.07745 1.14259 0.21829 0.928141
1 865584 G A 5916 0 0 0 1 1 5916 0 0 NA NA NA NA NA
1 865628 G A 5916 0.00782014 0.00566261 67 1 1 5849 67 0 16.4313 7.82519 0.268338 0.0357464 0.127813

=== Rvtests Example ===
Rvtests generates prefix.MetaScore.assoc, e.g. prefix.MetaScore.assoc

##Samples=2659
##AnalyzedSamples=2659
##Families=2659
##AnalyzedFamilies=2659
##Founders=2659
##AnalyzedFounders=2659
##InverseNormal=ON
##TraitSummary min 25th median 75th max mean variance
##Trait -3.56023 -0.679098 -0.00304512 0.682994 3.56845 0.000710616 1.00065
##AnalyzedTrait -3.55632 -0.674786 0 0.674786 3.55632 -1.10229e-17 0.999884
##Covariates=sex,age,age2,pc1,pc2
##CovariateSummary min 25th median 75th max mean variance
##sex 1 1 1 2 2 1.34524 0.226135
##age 21 55 66 73 91 63.6491 150.565
##age2 441 3025 4356 5329 8281 4201.72 2.25458e+06
##pc1 -0.1946 -0.0041 0.0014 0.0064 0.0246 -0.00027815 0.000184625
##pc2 -0.0957 -0.0067 -0.0005 0.0062 0.0989 0.000239526 0.000188235
CHROM POS REF ALT N_INFORMATIVE AF INFORMATIVE_ALT_AC CALL_RATE HWE_PVALUE N_REF N_HET N_ALT U_STAT SQRT_V_STAT ALT_EFFSIZE PVALUE
1 564766 T C 2659 0.23223 1235 1 0 2041 1 617 20.546 43.5254 0.0108453 0.636894
1 564862 T C 2659 NA NA NA NA NA NA NA NA NA NA NA
1 565111 T C 2659 0.0161715 86 1 4.01334e-96 2616 0 43 0.457052 13.0052 0.00270229 0.971965

== Input covariance test statistic file ==

Covariance test statistics contains the LD matrix among a variant and the adjacent markers within a prefixed-sized window. The default window size is 1MB. It has the following format:

=== Format ===

# CHROM Chromosome
# CURRENT_POS (RAREMETALWORKER only) Position for the first marker in Window
# VAR_POS_IN_WIND (RAREMETALWORKER only) Position for the other markers in window, separated by commas
# COV_MATRICES (RAREMETALWORKER only) Covariance matrix between test statistics
# START_POS (rvtests only) Position for the first marker in sliding window
# END_POS (rvtests only) Position for the last marker in sliding window
# NUM_MARKER (rvtests only) Number of markers in the sliding windows
# MARKER_POS (rvtests only) Number of marker positions in the sliding windows
# COV (rvtests only) Covariance matrix between test statistics

=== RAREMETALWORKER Example ===
RAREMETALWORKER generates prefix.traitName.singlevar.cov.txt, e.g. prefix.HDL.singlevar.cov.txt

CHR POS VAR_POS_IN_WINDOW LD_MATRIX
1 762320 762320,865628,865665,878744,879381,1560000 0.0359084,-0.000242112,-0.00125797,-0.000993422,-0.000344509,-0.00017077,
1 865628 865628,865665,878744,879381,1560000,1864659 0.419804,-0.0103663,-0.00635265,0.0594056,0.0534505,-0.00462183,
1 878744 878744,879381,1560000,1864659,1877659 0.000404537,-0.000235215,-1.4455e-05,-8.69137e-06,-3.1027e-05,

=== Rvtests Example ===
Rvtests generates prefix.MetaCov.assoc.gz, e.g. prefix.HDL.MetaCov.assoc.gz
Later version of rvtests will also generate tabix index file, prefix.MetaCov.assoc.gz

CHR START_POS END_POS NUM_MARKER MARKER_POS COV
1 762320 1560000 6 762320,865628,865665,878744,879381,1560000 0.0359084,-0.000242112,-0.00125797,-0.000993422,-0.000344509,-0.00017077
1 865628 1864659 6 865628,865665,878744,879381,1560000,1864659 0.419804,-0.0103663,-0.00635265,0.0594056,0.0534505,-0.00462183
1 878744 1877659 5 878744,879381,1560000,1864659,1877659 0.000404537,-0.000235215,-1.4455e-05,-8.69137e-06,-3.1027e-05

= Contact =

Please contact Dajiang Liu ([mailto:dajiang@umich.edu]), Xiaowei Zhan ([mailto:zhanxw@umich.edu]), Shuang Feng([mailto:sfengsph@umich.edu]) or Goncalo Abecasis ([mailto:goncalo@umich.edu]).

RAREMETAL

2018-03-16T21:52:43Z

Abought:

[[Category:Software]]
[[Category:RAREMETAL]]
'''RAREMETAL''' is a program that facilitates the meta-analysis of rare variants from genotype arrays or sequencing (manuscript in preparation).
It was developed by [[Shuang_Feng|Shuang Feng]], Dajiang Liu and Gonçalo R. Abecasis. RAREMETAL has been used for the analyses in Exomechip blood lipids consortium and [[EMADS|EMADS]].

If you feel the program is useful, please take one minute to tell us your name and email ([https://docs.google.com/spreadsheet/ccc?key=0AuYjznTeEDYudFpqUk9sQ2pkN3d3endjYldqMEp6ZUE&usp=sharing '''registration''']). Thank you!

For questions please contact Andy Boughton via email: abought at umich dot edu.

== Useful Wiki Pages ==

There are a few pages in this Wiki that may be useful to RAREMETAL users. Here are links to a few:

* The [[RAREMETAL Command Reference]]

* The [[RAREMETAL_Documentation|RAREMETAL Documentation]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Tutorial]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETALWORKER | RAREMETALWORKER documentation]]

== Download and Build==

To download RAREMETAL executable and source code with instruction of build, go to [[Rare-Metal#Download_and_Installation|'''DOWNLOAD and INSTALLATION''']].

== Related Programs ==
[[RAREMETALWORKER]] is a program that does single variant association for sequencing and genotyping array data and generates summary statistics for meta-analysis in RAREMETAL.

[[LocusZoom]] is a program that facilitates display of genomewide association scan results.

[[METAL]] is a program that facilitates meta-analysis of single-variant genomewide scans.

Tutorial: RAREMETAL

2018-03-16T21:51:58Z

Abought:

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
== Useful Wiki Pages ==

There are several pages in this Wiki that may be useful to RAREMETAL users. Here are links to a few:

* The [[RAREMETAL|RAREMETAL Home Page]]

* The [[RAREMETAL Command Reference]]

* The [[RAREMETAL_Documentation|RAREMETAL Documentation]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETALWORKER | RAREMETALWORKER documentation]]

==Introduction==

In this tutorial, we will use [[RAREMETAL|'''RAREMETAL''']] to perform single variant and gene-level meta-analysis using summary statistics of two small studies. We will use [[RAREMETALWORKER|'''RAREMETALWORKER''']] to generate summary statistics for each study.

==STEP 1: Install Software and Download Example Data Sets==

* If RAREMETAL and RAREMETALWORKER have not been installed on your local computer yet, you will first need to install them! You can download the two from here, [[RAREMETALWORKER#Software_Download_and_Installation|'''RAREMETAL installation''']] and [[RAREMETAL#Software_Download_and_Installation|'''RAREMETALWORKER installation''']].

* Then please download the [[Media:Raremetal_tutorial.tar.gz|'''tutorial package''']], including example data sets.

* To unpack the example dataset, use the following two Unix commands:

tar xvzf raremetal_tutorial.tar.gz
cd raremetal_tutorial

==STEP 2: Analyze individual samples using RAREMETALWORKER==

* Our first dataset has 743 unrelated individuals. Their phenotypes and relationships are described in a pair of pedigree and data files; you can get a summary of their contents using pedstats.

* These individuals have been genotyped at ~1000 markers, and these genotypes are stored in a VCF file. The VCF is a text format, so you can try to peek at the contents if you like.

* Although these individuals are "unrelated", there is the possibility that some of them are more closely related than others. In our analysis, we will calculate an empirical (i.e. data-driven) kinship (i.e. relatedness) matrix to describe the similarity between individuals.

* To analyse the first study, we execute the following command:

raremetalworker --ped example1.ped --dat example1.dat --vcf example1.vcf.gz --traitName QT1 \
--inverseNormal --makeResiduals --kinSave --kinGeno --prefix STUDY1

This command transforms phenotypes to normality (--inverseNormal), calculates trait residuals after adjusting for covariates (--makeResiduals), estimates relatedness between individuals and saves this for later use (--kinSave and --kinGeno), and even generates some PDF files summarizing results.

* After RAREMETALWORKER finishes running, you will see several output files:

STUDY1.QT1.singlevar.score.txt ## single variant statistics
STUDY1.QT1.singlevar.cov.txt ## covariance matrices between score statistics
STUDY1.plots.pdf ## QQ plots and Manhattan plots
STUDY1.Empirical.Kinship.gz ## Relatedness matrix
STUDY1.singlevar.log ## Log file

* We next analyse the second study using a similar command:

raremetalworker --ped example2.ped --dat example2.dat --vcf example2.vcf.gz --traitName QT1 \
--inverseNormal --makeResiduals --kinSave --kinGeno --prefix STUDY2

==STEP 3: Run RAREMETAL for Meta-Analysis==

* In this step, we will use RAREMETAL to combine the summary statistics we just generated.

* We will first index the result files generated by RAREMETAL. This step relies on bgzip and tabix, two tools that allow rapid indexing and retrieval of results from compressed text files.

bgzip STUDY1.QT1.singlevar.score.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY1.QT1.singlevar.score.txt.gz
bgzip STUDY1.QT1.singlevar.cov.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY1.QT1.singlevar.cov.txt.gz

* And again for the second study:

bgzip STUDY2.QT1.singlevar.score.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY2.QT1.singlevar.score.txt.gz
bgzip STUDY2.QT1.singlevar.cov.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY2.QT1.singlevar.cov.txt.gz

* We next create two text files that will drive the meta-analysis. The first file lists the input files with summary statistics. Let's call it summaryfiles. In most Linux workstations, you can use the command pico or nano to create this file. These should be the contents of "summaryfiles":

STUDY1.QT1.singlevar.score.txt.gz
STUDY2.QT1.singlevar.score.txt.gz

* The second file lists the input files with variance-covariance information between markers. Let's call it covfiles. These should be its contents:

STUDY1.QT1.singlevar.cov.txt.gz
STUDY2.QT1.singlevar.cov.txt.gz

* Now, we are ready for meta-analysis. To perform single variant and gene-level meta-analyses all at once, use the following command:

raremetal --summaryFiles summaryfiles --covFiles covfiles --groupFile group.file \
--SKAT --burden --MB --VT --longOutput --tabulateHits --hitsCutoff 1e-05 \
--prefix COMBINED.QT1 --hwe 1.0e-05 --callRate 0.95 -

This command filters summary statistics based on HWE p-value and variant call rate, generates single variant meta-analysis results, generates gene-level meta-analysis results using simple burden test, variable threshold test, Madson-Browning weighted burden test, and SKAT, tabulates significant genes with detailed single variant results included, and even generates some PDF files summarizing results.

* The following output will be generated:

COMBINED.QT1.meta.plots.pdf (## QQ plots and manhattan plots)
COMBINED.QT1.meta.singlevar.results
COMBINED.QT1.meta.burden.results
COMBINED.QT1.meta.SKAT.results
COMBINED.QT1.meta.VT.results
COMBINED.QT1.meta.MB.results
COMBINED.QT1.meta.tophits.SKAT.tbl
COMBINED.QT1.meta.tophits.VT.tbl
COMBINED.QT1.meta.tophits.burden.tbl
COMBINED.QT1.meta.tophits.MB.tbl
COMBINED.QT1.raremetal.log

* It is probably a good idea to spend a few minutes reviewing these files - they have the key results for your analysis! A detailed description of output files is available [[RAREMETAL_Documentation#Gene-level_Tests_Meta-Analysis_Output|elsewhere]].

* If you are feeling adventurous and are not yet totally confused, you can continue to explore advanced features of RAREMETAL.

* For example, RAREMETAL can carry out conditional analyses using the summary statistics in summaryfiles and covfiles.

* To carry out a conditional analysis, create a text file that specifies the variant that you want to condition on (lets call it "conditioningfile") and add "--condition conditioningfile" to the command line. The "conditioningfile" might look like this:

9:505484545:C:T

* When you now run RAREMETAL with the extra options --condition conditioningfile, results will be adjusted for the variant 9:505484545:C:T.

* An alternative to generating a group.file is to provide RAREMETAL with an annotated VCF as input. For details, see [[RAREMETAL_Documentation#Group_Rare_Variants_from_Annotated_VCF|documentation]]. This option is especially useful when you first use RAREMETAL's [[RAREMETAL_Documentation#Generate_a_VCF_File_to_Annotate_Outside_of_Rare_Metal|'''--writeVCF''']] option to create a file listing a superset of all available variants.

Tutorial: RAREMETAL

2018-03-16T21:51:50Z

Abought:

[[Category:RAREMETAL]]
[[Category:RAREMETWALWORKER]]
== Useful Wiki Pages ==

There are several pages in this Wiki that may be useful to RAREMETAL users. Here are links to a few:

* The [[RAREMETAL|RAREMETAL Home Page]]

* The [[RAREMETAL Command Reference]]

* The [[RAREMETAL_Documentation|RAREMETAL Documentation]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETALWORKER | RAREMETALWORKER documentation]]

==Introduction==

In this tutorial, we will use [[RAREMETAL|'''RAREMETAL''']] to perform single variant and gene-level meta-analysis using summary statistics of two small studies. We will use [[RAREMETALWORKER|'''RAREMETALWORKER''']] to generate summary statistics for each study.

==STEP 1: Install Software and Download Example Data Sets==

* If RAREMETAL and RAREMETALWORKER have not been installed on your local computer yet, you will first need to install them! You can download the two from here, [[RAREMETALWORKER#Software_Download_and_Installation|'''RAREMETAL installation''']] and [[RAREMETAL#Software_Download_and_Installation|'''RAREMETALWORKER installation''']].

* Then please download the [[Media:Raremetal_tutorial.tar.gz|'''tutorial package''']], including example data sets.

* To unpack the example dataset, use the following two Unix commands:

tar xvzf raremetal_tutorial.tar.gz
cd raremetal_tutorial

==STEP 2: Analyze individual samples using RAREMETALWORKER==

* Our first dataset has 743 unrelated individuals. Their phenotypes and relationships are described in a pair of pedigree and data files; you can get a summary of their contents using pedstats.

* These individuals have been genotyped at ~1000 markers, and these genotypes are stored in a VCF file. The VCF is a text format, so you can try to peek at the contents if you like.

* Although these individuals are "unrelated", there is the possibility that some of them are more closely related than others. In our analysis, we will calculate an empirical (i.e. data-driven) kinship (i.e. relatedness) matrix to describe the similarity between individuals.

* To analyse the first study, we execute the following command:

raremetalworker --ped example1.ped --dat example1.dat --vcf example1.vcf.gz --traitName QT1 \
--inverseNormal --makeResiduals --kinSave --kinGeno --prefix STUDY1

This command transforms phenotypes to normality (--inverseNormal), calculates trait residuals after adjusting for covariates (--makeResiduals), estimates relatedness between individuals and saves this for later use (--kinSave and --kinGeno), and even generates some PDF files summarizing results.

* After RAREMETALWORKER finishes running, you will see several output files:

STUDY1.QT1.singlevar.score.txt ## single variant statistics
STUDY1.QT1.singlevar.cov.txt ## covariance matrices between score statistics
STUDY1.plots.pdf ## QQ plots and Manhattan plots
STUDY1.Empirical.Kinship.gz ## Relatedness matrix
STUDY1.singlevar.log ## Log file

* We next analyse the second study using a similar command:

raremetalworker --ped example2.ped --dat example2.dat --vcf example2.vcf.gz --traitName QT1 \
--inverseNormal --makeResiduals --kinSave --kinGeno --prefix STUDY2

==STEP 3: Run RAREMETAL for Meta-Analysis==

* In this step, we will use RAREMETAL to combine the summary statistics we just generated.

* We will first index the result files generated by RAREMETAL. This step relies on bgzip and tabix, two tools that allow rapid indexing and retrieval of results from compressed text files.

bgzip STUDY1.QT1.singlevar.score.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY1.QT1.singlevar.score.txt.gz
bgzip STUDY1.QT1.singlevar.cov.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY1.QT1.singlevar.cov.txt.gz

* And again for the second study:

bgzip STUDY2.QT1.singlevar.score.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY2.QT1.singlevar.score.txt.gz
bgzip STUDY2.QT1.singlevar.cov.txt
tabix -c "#" -s 1 -b 2 -e 2 STUDY2.QT1.singlevar.cov.txt.gz

* We next create two text files that will drive the meta-analysis. The first file lists the input files with summary statistics. Let's call it summaryfiles. In most Linux workstations, you can use the command pico or nano to create this file. These should be the contents of "summaryfiles":

STUDY1.QT1.singlevar.score.txt.gz
STUDY2.QT1.singlevar.score.txt.gz

* The second file lists the input files with variance-covariance information between markers. Let's call it covfiles. These should be its contents:

STUDY1.QT1.singlevar.cov.txt.gz
STUDY2.QT1.singlevar.cov.txt.gz

* Now, we are ready for meta-analysis. To perform single variant and gene-level meta-analyses all at once, use the following command:

raremetal --summaryFiles summaryfiles --covFiles covfiles --groupFile group.file \
--SKAT --burden --MB --VT --longOutput --tabulateHits --hitsCutoff 1e-05 \
--prefix COMBINED.QT1 --hwe 1.0e-05 --callRate 0.95 -

This command filters summary statistics based on HWE p-value and variant call rate, generates single variant meta-analysis results, generates gene-level meta-analysis results using simple burden test, variable threshold test, Madson-Browning weighted burden test, and SKAT, tabulates significant genes with detailed single variant results included, and even generates some PDF files summarizing results.

* The following output will be generated:

COMBINED.QT1.meta.plots.pdf (## QQ plots and manhattan plots)
COMBINED.QT1.meta.singlevar.results
COMBINED.QT1.meta.burden.results
COMBINED.QT1.meta.SKAT.results
COMBINED.QT1.meta.VT.results
COMBINED.QT1.meta.MB.results
COMBINED.QT1.meta.tophits.SKAT.tbl
COMBINED.QT1.meta.tophits.VT.tbl
COMBINED.QT1.meta.tophits.burden.tbl
COMBINED.QT1.meta.tophits.MB.tbl
COMBINED.QT1.raremetal.log

* It is probably a good idea to spend a few minutes reviewing these files - they have the key results for your analysis! A detailed description of output files is available [[RAREMETAL_Documentation#Gene-level_Tests_Meta-Analysis_Output|elsewhere]].

* If you are feeling adventurous and are not yet totally confused, you can continue to explore advanced features of RAREMETAL.

* For example, RAREMETAL can carry out conditional analyses using the summary statistics in summaryfiles and covfiles.

* To carry out a conditional analysis, create a text file that specifies the variant that you want to condition on (lets call it "conditioningfile") and add "--condition conditioningfile" to the command line. The "conditioningfile" might look like this:

9:505484545:C:T

* When you now run RAREMETAL with the extra options --condition conditioningfile, results will be adjusted for the variant 9:505484545:C:T.

* An alternative to generating a group.file is to provide RAREMETAL with an annotated VCF as input. For details, see [[RAREMETAL_Documentation#Group_Rare_Variants_from_Annotated_VCF|documentation]]. This option is especially useful when you first use RAREMETAL's [[RAREMETAL_Documentation#Generate_a_VCF_File_to_Annotate_Outside_of_Rare_Metal|'''--writeVCF''']] option to create a file listing a superset of all available variants.

RAREMETAL FAQ

2018-03-16T21:50:58Z

Abought:

[[Category:RAREMETAL]]
==COMPILE PROBLEMS==
===error: zlib.h: No such file or directory===
Error:

make -C ../../libStatGen --no-print-directory opt
gcc -O4 -pipe -Wall -I../include -I. -D__ZLIB_AVAILABLE__ -D_FILE_OFFSET_BITS=64 -D__STDC_LIMIT_MACROS -o obj/bgzf.o -c bgzf.c
In file included from bgzf.c:37:
bgzf.h:30:18: error: zlib.h: No such file or directory
bgzf.c: In function âopen_writeâ:
bgzf.c:187: error: âZ_DEFAULT_COMPRESSIONâ undeclared (first use in this function)
bgzf.c:187: error: (Each undeclared identifier is reported only once
bgzf.c:187: error: for each function it appears in.)
bgzf.c: In function âdeflate_blockâ:
bgzf.c:298: error: âz_streamâ undeclared (first use in this function)
bgzf.c:298: error: expected â;â before âzsâ
bgzf.c:299: error: âzsâ undeclared (first use in this function)
bgzf.c:306: warning: implicit declaration of function âdeflateInit2â
bgzf.c:306: error: âZ_DEFLATEDâ undeclared (first use in this function)

====SOLUTION====
Based on the compile error, it appears that the development verison of zlib may not be installed. Please go to http://genome.sph.umich.edu/wiki/Zlib for more information.

User can compile the library without ZLIB, but then the code will not be able to read compressed files (typically BAM files are compressed).
If no compressed files is needed, then user can compile using: make ZLIB_AVAIL=0.

===error: undefined reference to `_gfortran_pow_r8_i4'===
Error:

../../libStatGen/libStatGen.a(mvt.o): In function `mvtdns_':
mvt.f:(.text+0x20c9): undefined reference to `_gfortran_pow_r8_i4'
../../libStatGen/libStatGen.a(mvt.o): In function `mvchnv_':
mvt.f:(.text+0x5848): undefined reference to `_gfortran_pow_r8_i4'
collect2: ld returned 1 exit status
make: *** [../bin/raremetal] Error 1

====SOLUTION====

It looks like in some versions of compilers, the Fortran library (required by RareMetal) isn't automatically included.
These Makefile changes fixed it on the machine where I was able to recreate your compile issue:

1) libStatGen/Makefiles/Makefile.src, edit the settings for OPT_BUILD, DEBUG_BUILD, and PROFILE_BUILD to be (the new part is in bold):
OPT_BUILD = $(CXX) $(COMPFLAGS) $(USER_LINK_OPTIONS) -o $(PROG_OPT) $(OBJECTS_OPT) $(USER_LIBS) $(REQ_LIBS_OPT) -lm $(ZLIB_LIB) '''$(OTHER_LIBS)'''
DEBUG_BUILD = $(CXX) $(COMPFLAGS) $(USER_LINK_OPTIONS) -o $(PROG_DEBUG) $(OBJECTS_DEBUG) $(USER_LIBS) $(REQ_LIBS_DEBUG) -lm $(ZLIB_LIB) '''$(OTHER_LIBS)'''
PROFILE_BUILD = $(CXX) $(COMPFLAGS) $(USER_LINK_OPTIONS) -o $(PROG_PROFILE) $(OBJECTS_PROFILE) $(USER_LIBS) $(REQ_LIBS_PROFILE) -lm $(ZLIB_LIB) '''$(OTHER_LIBS)'''

2) raremetal/src/Makefile, add: (I added it on the line right after USER_LIBS is defined.)
OTHER_LIBS = -lgfortran
NOTE: this has been fixed by identifying a bug in makefile. If you still see the same error message, please try the above solutions.

===error while loading shared libraries===
Error:
gcc -O4 -pipe -Wall -I../include -I. -D__ZLIB_AVAILABLE__ -D_FILE_OFFSET_BITS=64 -D__STDC_LIMIT_MACROS -o obj/bgzf.o -c bgzf.c
/broad/software/free/Linux/redhat_5_x86_64/pkgs/gcc_4.4.4/libexec/gcc/x86_64-unknown-linux-gnu/4.4.4/cc1: error while loading shared libraries: libmpfr.so.1: cannot open shared object file: No such file or directory
make[2]: *** [obj/bgzf.o] Error 1
make[1]: *** [samtools] Error 2
make: *** [../../libStatGen/libStatGen. a] Error 2

====SOLUTION====
If you are using version 0.4.4 and under, please go to our wiki page to download the newest version [[RAREMETAL_Documentation#Where_to_Download | '''download RAREMETAL''']]. There was a bug in makefile in older versions of RAREMETAL that could cause this error and it has been fixed. For a quick fix, please go to /raremetal/src and open "Makefile". Then comment out the lines at the bottom of raremetal/src/Makefile that set LD_LIBRARY_PATH. Try compiling and see if it works.

===error: can not find Makefile.base ===

../libStatGen/Makefiles/Makefile.tool:4: Makefile.base: No such file or directory
../libStatGen/Makefiles/Makefile.tool:23: *** first argument to `word' function must be greater than 0. Stop.

====SOLUTION====
This is most likely that you are having an older version of Make. To compile, you have to use Make version 3.80 and older. To get updated version of make, please go to [http://ftp.gnu.org/gnu/make '''make download'''].

==RUNTIME ERRORS==
===error: BGZF EOF marker is missing in xxx.vcf.gz===
Loading input files...
Loading DAT files ... done.
Loading PED files ... done.

BGZF EOF marker is missing in xxx.vcf.gz
Exiting, exception thrown: FAIL_IO: Failed to open xxx.vcf.gz

====SOLUTION====
This problem has been solved. If you are using version 0.4.5 or older, please download the newest version [[RAREMETALWORKER#Where_to_Download |'''download RAREMETALWORKER''']], and then in your command line, add --noeof. If you still see the error message, then you need to check if your bgzip has been updated to current version.

===recommended strategies for debugging===
The ideal would be to send us your data so that we can debug. But if data sharing is not an option, you can use the following strategy to generate a backtrace and send it to us, without sharing the raw data.

How to Generate a backtrace of the error:
This will allow us to see where in the code it hit a segmentation fault. This method isn't perfect and may still leave us with further questions for you before we can come to an answer.
1) Compile for debug: make debug
2) Enable core dumps in the window where he will run: ulimit -c unlimited
3) Run bin/debug/raremetal
(If this does not coredump, then set OPTFLAG_OPT = -g -O4 in src/Makefile and try rerunning the bin/raremetal version - this will run optimized, but with the debug symbols)
4) Run: gdb bin/debug/raremetal core
(specifying the bath to the raremetal executable that was run & the path to the generated core file)
5) In the gdb window, type: bt.
6) Save the backtrace results and send it to us.
That will generate the backtrace which will help us see where the segmentation fault occurred.

==GENERAL QUESTIONS==
===What is RAREMETALWORKER? How is it related to RAREMETAL?===

A: [[Rare-Metal-Worker|'''RAREMETALWORKER''']] is the program that generates summary statistics for individual studies to share. It generates both single variant association results and covariance matrices of score statistics together with QC statistics. It enables analysis of familial data, population data, unrelated individuals and samples with cryptic relatedness and population stratification. [[RareMETAL|'''RAREMETAL''']] takes the summary statistics generated by RAREMETALWORKER to perform both single variant and gene-level association analysis.

RAREMETALWORKER SPECIAL TOPICS

2018-03-16T21:50:02Z

Abought:

[[Category:RAREMETALWORKER]]
This page describes how [[RAREMETALWORKER]] handles some special cased during analyses.

==Useful Links==

Here are some useful links to key pages:
* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]
* The [[RAREMETALWORKER_METHOD | '''RAREMETALWORKER method''']]
* The [[RAREMETALWORKER_command_reference | '''RAREMETALWORKER command reference''']]
* The [[Tutorial:_RAREMETAL| '''RAREMETALWORKER quick start tutorial''']]
* The [[RAREMETAL_FAQ | '''FAQ''']]

== Unrelated Individuals ==

[[RAREMETALWORKER]] generates single variant association test statistics for a single study prior to meta-analysis. This page provides a brief description of the statistics that
RAREMETALWORKER calculates, together with key formulae.

== Missing Data ==

* Individuals with missing phenotypes will be excluded from analysis.
* If --makeResiduals is used for adjusting covariates, then individuals with missing covariates will also be excluded.
* Individuals that are not genotyped will also be excluded from analyses.
* Missing genotypes are imputed using mean genotype of a variant.

== Analyzing Chromosome X==

* To make sure RAREMETALWORKER analyze chromosome X correctly, '''male must be code as 1 and female must be coded as 2''' in [[RAREMETALWORKER#PED_and_DAT_Files | '''PED''']] file.
* --xStart and --xEnd options described the start and end position of nonPAR region on chromosome X. The default values are 2699520 and 154931044, according to Human Genome build 19.
* When samples are analyzed as unrelated (no any kind of kinship is used for linear mixed model approach), no special actions needed for analyzing markers on chromosome X.
* If you want to use a linear mixed model approach to correct family structure, population structure, or cryptic relatedness, you should issue --vcX option in your command line. This approach will fit a separate linear mixed model using both autosomal kinship matrix and chromosomeX kinship matrix. This approach is believed to have larger power with type I error well controlled.
* On the other hand, if you want a fast association for chromosome X, another valid approach is to issue --vcX --separateX options. This will initiate fitting a separate linear mixed model using chromosomeX kinship only for analyzing markers on chromosomeX. This approach is expected to be faster than the above option, but with less power, although type I error is also expected to be under control.
* Male genotypes for variants in nonPAR region are coded to be 0 or 2.
* If a male is heterozygous in nonPAR region, then the genotype of that male sample is considered missing and will be imputed using mean genotype.
* If a male has genotype coded as ./x in nonPAR region, then the genotype of that male sample is considered missing and will be imputed using mean genotype.
* For details of methods analyzing chromosomeX, please refer to [[RAREMETALWORKER_method | '''method''']].

RAREMETALWORKER METHOD

2018-03-16T21:49:25Z

Abought:

RAREMETALWORKER command reference

2018-03-16T21:47:23Z

Abought:

[[Category:RAREMETALWORKER]]
==Useful Links==

Here are some useful links to key pages:
* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]
* The [[RAREMETALWORKER_METHOD | '''RAREMETALWORKER method''']]
* The [[RAREMETALWORKER_SPECIAL_TOPICS | '''RAREMETALWORKER special topics''']]
* The [[Tutorial:_RAREMETAL | '''RAREMETALWORKER quick start tutorial''']]
* The [[RAREMETAL_FAQ | '''FAQ''']]

Options:
Input Files : --ped [], --dat [], --vcf [], --dosage, --flagDosage [DS],
--noeof
Output Files : --prefix [], --LDwindow [1000000], --zip, --thin,
--labelHits
VC Options : --vcX, --separateX
Trait Options : --makeResiduals, --inverseNormal, --traitName []
Model Options : --recessive, --dominant
Kinship Source : --kinPedigree, --kinGeno, --kinFile [], --kinxFile [],
--kinSave
Kinship Options : --kinMaf [0.05], --kinMiss [0.05]
Chromosome X : --xLabel [X], --xStart [2699520], --xEnd [154931044],
--maleLabel [1], --femaleLabel [2]
others : --cpu [1], --kinOnly,
--geneMap [../data/refFlat_hg19.txt], --mergedVCFID
PhoneHome : --noPhoneHome, --phoneHomeThinning [100]

==Input Files==
===--ped===
*--ped takes a string of your [[RAREMETALWORKER#PED_and_DAT_Files | '''MERLIN format PED''']] file name.
===--dat===
*--ped takes a string of your [[RAREMETALWORKER#PED_and_DAT_Files | '''MERLIN format DAT''']] file name.
===--vcf===
*--vcf takes a string of your [[RAREMETALWORKER#VCF_File | '''VCF''']] file name.
===--dosage===
* When --dosage is issued in command line, RAREMETALWORKER reads dosage from your [[RAREMETALWORKER#VCF_File | '''VCF''']] file.
* --dosage must be used with --vcf option.
* Description of dosage format in a VCF file can be found in [[RAREMETALWORKER#DOSAGE | '''dosage''']].

===--flagDosage===
* This option let user customize the name of field in VCF file that labels dosage data.
* The default is "DS".

===--noeof===
* If you VCF file does not have the BGZF EOF markers, you should use --noeof option to let RAREMETALWORKER skip checking the BGZF EOF markers at the end of the file.
* Please see [[RAREMETAL_FAQ#error:_BGZF_EOF_marker_is_missing_in_xxx.vcf.gz | '''BGZF EOF''']] for more details.

==Output Files==

===--prefix===
* --prefix takes a value of a string as the prefix of your output files.
* For a full list of output files generated by RAREMETALWORKER, please refer to [[RAREMETALWORKER#OUTPUT_FILE_FORMATS | '''output''']].

===--LDwindow===
*--LDwindow takes a integer value as the size of the moving window.
* RAREMETALWORKER generates LD matrices between a current marker that it is working on and all markers within this window.
* The default size is 1 million bases.
* For more information about the LD matrix, please refer to [[RAREMETALWORKER#LD_Matrices | '''LD matrix''']].

===--zip===
* By issuing --zip, RAREMETALWORKER compress the [[ RAREMETALWORKER#Summary_Statistics| '''summary statistics''']] and [[RAREMETALWORKER#LD_Matrices | '''LD matrices''']] generated automatically, using gzip. And the output zip files will be indexed using tabix.

=== --thin ===
* If --thin is issued, then RAREMETALWORKER generates [[RAREMETALWORKER#Plots | '''QQ plots and Manhattan plots''']] with less resolution (points), to make the pdf files smaller in size.

===--labelHits===
* If --thin is issued, then RAREMETALWORKER automatically label the loci that are above a threshold.
* The threshold is calculated using Bonferroni correction (''0.05/N, where N is the total number of polymorphic markers'').

==VC Options==

===--vcX===
* --vcX option has to be used with --kinPedigree (when pedigree kinship is used), or --kinGeno (when genomic relationship matrix is estimated), or --kinFile ( when GRM is read from a file).
* Using --vcX option let RAREMETALWORKER fit a linear mixed model to analyze chromosome X, using both autosomal kinship and chromosome X kinship.

===--separateX===
* --separateX option must be used with --vcX option.
* Using --separateX option requests RAREMETALWORKER to fit a linear mixed model using only chromosome X kinship for analyses of chromosome X markers.

Please refer to [[RAREMETALWORKER_method#ANALYZING_MARKERS_ON_CHROMOSOME_X| '''method''']] and [[RAREMETALWORKER_SPECIAL_TOPICS#Analyzing_Chromosome_X | '''technical details''']] for more explanation.

==Trait Options==
===--makeResiduals===
* If --makeResiduals is used, then covariates are adjusted before fitting linear models using residuals.

===--inverseNormal===
* If --inverseNormal is used, but not with --makeResiduals, then trait values are inverse normalized before fitting linear models.
* If --inverseNormal and --makeResiduals are used together, then covariates are adjusted and inverse normalized residuals are used to fit linear models.

===--traitName===
* --traitName takes a string of the trait name that you want to analyze.
* If this option is not used, then all traits included in [[RAREMETALWORKER#PED_and_DAT_Files | '''PED/DAT''']] files are analyzed.

==Model Options==
===--recessive===
* If --recessive is used, then RAREMETALWORKER generates recessive results in addition to the additive results.
* The set of association results generated by default can be found in [[RAREMETALWORKER#OUTPUT_FILE_NAMES | '''recessive output''']].
* A separate pdf file with QQ and Manhattan plots based on recessive results is generated with name ''yourprefix.traitname.recessive.plots.pdf''.
===--dominant===
* If --dominant is used, then RAREMETALWORKER generates recessive results in addition to the additive results.
* The set of association results generated by default can be found in [[RAREMETALWORKER#OUTPUT_FILE_NAMES | '''dominant output''']].
* A separate pdf file with QQ and Manhattan plots based on recessive results is generated with name ''yourprefix.traitname.dominant.plots.pdf''.

==Kinship Source==
===--kinPedigree===
* If --kinPedigree is used, pedigree structure coded in [[RAREMETALWORKER#PED_and_DAT_Files | '''PED''']] file is used to generate a kinship matrix for later fitting linear mixed model before associations.

===--kinGeno===
* If --kinPedigree is used, then a genomic relationship matrix is estimated from genotype.
* If --vcX option is used, then a separate genomic relationship matrix for chromosome X is also estimated.
* For details about how to estimate GRM, please refer to [[RAREMETALWORKER_method#MODELING_RELATEDNESS | ''methods''']].

===--kinFile===
* --kinFile takes a string of the file name of previously saved GRM with format described in [[RAREMETALWORKER#Genomic_Relationship_Matrix_.28GRM.29 | '''format''']].
* This option reads GRM from the file and then extract the correct GRM based on samples to be analyzed according to your specifications, such as traits to be analyzed, missing covariates and genotypes (please refer to [[RAREMETALWORKER_SPECIAL_TOPICS#Missing_Data | '''missing data''']] for more details).
* --kinFile can not be used together with --kinGeno.

===--kinxFile===
* --kinxFile must be used with --kinFile and --vcX.
* --kinxFile takes a string of file name of the previously saved GRM for chromosome X.
* If --kinxFile is not used, but --kinFile your.autosomal.Empirical.Kinship.gz --vcX are issued in a command line, then RAREMETALWORKER will look for a kinship X file named your.autosomal.Empirical.KinshipX.gz. If this file is still not found, a FATAL ERROR will occur.
===--kinSave===
* This option must be used with --kinGeno.
* Issuing --kinSave will request [[RAREMETALWORKER]] to store the estimated GMR in a file named yourprefix.Empirical.Kinship.gz.
* If --vcX is also issued in the command line, then a separate file named yourprefix.Empirical.KinshipX.gz will be generated where the GRM of chromosome X is saved.
*For formats of the saved genomic relationship matrix, please refer to [[RAREMETALWORKER#Genomic_Relationship_Matrix_.28GRM.29 | '''format''']].

==Kinship Options==
===--kinMaf===
* --kinMaf takes a value that specifies the MAF cutoff for variants to be used to estimate GRMs.
* The default is 0.05, which means variants with MAF<0.05 are not used for estimating GRMs.
===--kinMiss===
* --kinMiss takes a value that specifies the missing genotype cutoff for variants to be used to estimate GRMs.
* The default is 0.05, which means variants with genotype call rate <0.95 are not used for estimating GRMs.

==Chromosome X==
===--xLabel===
* --xLabel takes a string that used as label for chromosome X in your file.
* The default is "X".

===--xStart===
* --xStart takes an integer that described the start position of nonPAR region on chromosome X.
* The default is 2699520 based on Human Genome build 19.

===--xEnd===
* --xStart takes an integer that described the end position of nonPAR region on chromosome X.
* The default is 154931044 based on Human Genome build 19.

==Others==
===--cpu[1]===
*--cpu takes an integer that specifies the number of cpus to use for estimating kinship matrix from genotypes.

===--kinOnly===
*--kinOnly allows users to estimate kinship matrix without any association analysis of any traits included in the data set.
*To also estimate chromosome X kinship, --vcX option should be added in command line.

===--geneMap===
* --geneMap takes a string describing the path to find mapping file for manhattan plot annotation.
* The default is human genome build 19, saved in raremetal/data/refFlat_hg19.txt.

===--mergedVCFID===
* This options allows RAREMETALWORKER to recognize VCF samples IDs in "FAMID_PID" format.
* The default value is OFF, which means VCF sample IDs are consistent with PID field in PED file.

==PhoneHome==
* See [[PhoneHome]] for more information on how PhoneHome works and what it does.
===--noPhoneHome===
* --noPhoneHome disables PhoneHome.
* PhoneHome is enabled by default based on the thinning parameter.
===--phoneHomeThinning===
* --phoneHomeThinning (0-100) adjusts the frequency of PhoneHome.
* The default is 100, running 100% of the time.

RAREMETALWORKER

2018-03-16T21:46:47Z

Abought:

[[Category:RAREMETALWORKER]]

'''RAREMETALWORKER''' is a tool for single variant analysis, generating summary statistics for gene level meta analyses in [http://genome.sph.umich.edu/wiki/RAREMETAL '''RAREMETAL'''].

If you feel this program is useful, please tell us your name and contact in this [https://docs.google.com/spreadsheet/ccc?key=0AuYjznTeEDYudFpqUk9sQ2pkN3d3endjYldqMEp6ZUE&usp=sharing '''registration'''].

If you have any questions, please contact Sai Chen (saichen at umich dot edu) or [[Goncalo_Abecasis | '''Goncalo Abecasis''']] (goncalo at umich dot edu).

== Useful Wiki Pages ==

There are several pages in this Wiki that may be useful to RAREMETALWORKER users. Here are links to key pages:
* The [[RAREMETALWORKER_command_reference | '''RAREMETALWORKER command reference''']]
* The [[RAREMETALWORKER_method | '''RAREMETALWORKER method''']]
* The [[Tutorial:_RAREMETAL| '''RAREMETALWORKER quick start tutorial''']]
* The [[RAREMETALWORKER_SPECIAL_TOPICS | '''RAREMETALWORKER special topics''']]
* The [[RAREMETAL_Documentation | '''RAREMETAL documentation''']]
* The [[RAREMETAL FAQ | '''FAQ''']]
* The [[RAREMETAL_Change_Log | '''Change Log''']]

== Key Features ==
RAREMETALWORKER has the following features:
* Takes genotypes from either PED file or VCF file.
* Generates summary statistics for both related and unrelated individuals.
* Generates linkage disequilibrium matrices summarizing covariance between single marker statistics using an adjustable sliding window.
* Optionally handles related individuals using a kinship matrix derived from either pedigree or genotype data.
* Has the option of fitting shared environment.
* Can handle variants on Chromosome X.
* Calculates QC statistics such as hwe pvalue, call rate and genomic control.
* Automatically generate QQ and manhattan plots.

== Software Download and Installation ==

=== DOWNLOAD ===

We have tested compilation on several platforms including Linux, MAC OS X, and Windows.

For source code and executables together with instructions of building from source, please go to [[RAREMETAL_DOWNLOAD_%26_BUILD |'''DOWNLOAD source and executables''']].

For questions about building and compilation, please go to [[RAREMETAL_FAQ | '''FAQ''']].

=== How to Execute ===

* To execute the program, go to /RareMetalWorker_0.4.8/RareMetalWorker/bin, issue ./raremetalworker.
* For example command lines, please refer to [[RAREMETALWORKER#Example_Command_Lines | '''RAREMETALWORKER EXAMPLES''']].

==Method==

Method description and key formulae can be found in [http://genome.sph.umich.edu/wiki/RAREMETALWORKER_method '''RAREMETALWORKER METHOD'''].

==For Binary Traits==

RAREMETALWORKER currently treat all traits as quantitative. If your trait is binary, the odds ratio can be approximated from effect size estimates generated by RAREMETALWORKER. The installation/source package has a script included to augment the odds ratio estimates to the last column of the RAREMETALWORKER output. For details, please refer to [[RAREMETAL_DOWNLOAD_%26_BUILD#Calculating_Odds_Ratio_from_RAREMETALWORKER_output | '''Calculate Odds Ratio from RAREMETALWORKER output''']].

== Software Specifications ==

===INTERFACE===

RAREMETALWORKER is a command line tool. Once you execute, you will see a full list of options printed on the screen.

For detailed description of command options, please go to [[RAREMETALWORKER_command_reference | '''command reference''']].

Options:
Input Files : --ped [], --dat [], --vcf [], --dosage, --noeof
Output Files : --prefix [], --LDwindow [1000000], --zip, --thin,
--labelHits
VC Options : --vcX, --separateX
Trait Options : --makeResiduals, --inverseNormal, --traitName []
Model Options : --recessive, --dominant
Kinship Source : --kinPedigree, --kinGeno, --kinFile [], --kinxFile [],
--kinSave
Kinship Options : --kinMaf [0.05], --kinMiss [0.05]
Chromosome X : --xLabel [X], --xStart [2699520], --xEnd [154931044],
--maleLabel [1], --femaleLabel [2]
others : --cpu [1], --kinOnly,
--geneMap [../data/refFlat_hg19.txt]
PhoneHome : --noPhoneHome, --phoneHomeThinning [100]

===INPUT FILE FORMAT===

RMW needs the following files as input: PED and DAT file in Merlin format, '''AND/OR''' a VCF file. When genotypes are stored in PED and DAT file, the VCF file is not needed. However, even if genotypes are saved in a VCF file, PED and DAT files are still needed for carrying covariate and trait information.

==== PED and DAT Files ====
* When PED file has genotypes saved, there is no need for a VCF file as input.
* RMW takes PED/DAT file in Merlin format. Please refer to [http://www.sph.umich.edu/csg/abecasis/merlin/tour/input_files.html PED/DAT format description] for details.
* PED file requires "dummy" parents to be included in the pedigree file. To check the integrity of your PED/DAT file, please use [http://www.sph.umich.edu/csg/abecasis/PedStats '''pedstats''']. To add dummy parents into the pedigree, please use the [[Media:Script.tgz | '''perl script''']].
* An example PED file is in the following:
1 1 0 0 1 1.5 1 23 A A A A A A A A A A
2 1 0 0 1 1.0 1 34 A C A C A C A C A C
3 1 0 0 2 0.4 1 43 A A A A A A A A A A
4 1 0 0 2 0.9 1 13 A C A C A C A C A C
* The matching DAT file is in the following:
T YourTraitName
C SEX
C AGE
M 1:123456
M 1:234567
M 2:111111
M 2:222222
M X:12345
* DAT file must have variant names in the following format "M chr:pos".
* Orders of labels in DAT file have to match the order of fields in PED file.
* '''Markers in PED and DAT file must be sorted by chromosome and position.'''

* Covariate and trait values are saved in PED file. Covariate and trait descriptions are saved in DAT file.

==== VCF File ====
=====GENOTYPES=====
* Another option is to use VCF as input. Please refer to the following link for VCF file specification: [http://www.1000genomes.org/wiki/Analysis/Variant%20Call%20Format/vcf-variant-call-format-version-41 1000 genome wiki VCF specs]
* VCF file should be compressed by bgzip and indexed by tabix, using the following command:
bgzip input.vcf ## this command will produce input.vcf.gz
tabix -p vcf -f input.vcf.gz ## this command will produce input.vcf.gz.tbi
* Even with the presence of VCF file, PED/DAT files are still needed for covariates and phenotypes.
* Are you using PLINK file formats? Converting to VCF is easy. Use WDIST (very similar to PLINK) to make the conversion. Visit this page [https://www.cog-genomics.org/wdist/ | WDIST] to find documentation and downloads for WDIST.

* When genotypes are saved in a VCF file, PED and DAT files are used for specifying pedigree structure, covariate and trait information. An example command line might look like this:
--ped input.ped --dat input.dat --vcf input.vcf.gz
* When genotypes are saved in the PED file, the VCF file is not needed. An example command line might look like this:
--ped input.ped --dat input.dat

=====DOSAGE=====
* If you want to analyze dosage data from VCF file, the following option has to be specified: --dosage. A key word "DS" in FORMAT field in VCF file has to included accordingly. An example is in the following:

#CHROM POS ID REF ALT QUAL FILTER INFO FORMAT IDx ID1 ID2 ID3
22 16050408 37239779 T C . PASS AC=2;AN=496 GT:DS:GP ./.:.:0,0,0 ./.:.:0,0,0 ./.:.:0,0,0
22 16050933 37239784 G A . PASS AC=141;AN=904 GT:DS:GP 0/0:0.0:1,0,0 0/0:0.0:1,0,0 0/0:0.0:1,0,0

* --noeof allows using VCF file without BGZF EOF markers. This is a very rare option to use. If your run is terminated with error message: "", then you might want to check out this option.

=== OUTPUT===

====OUTPUT FILE NAMES====

* Three files are generated automatically by default:
prefix.traitName.singlevar.score.txt (single variant summary statistics and QC statistics)
prefix.traitName.singlevar.cov.txt (covariance matrices of single variant score statistics)
prefix.singlevar.log (log file)

* If --zip option is used, then the following will be generated automatically:
prefix.traitName.singlevar.score.txt.gz
prefix.traitName.singlevar.score.txt.gz.tbi
prefix.traitName.singlevar.cov.txt.gz
prefix.traitName.singlevar.cov.txt.gz.tbi
prefix.singlevar.log

* If --recessive and/or --dominant options are used, then the following files are also generated '''in addition''' to the above files
prefix.traitName.recessive.singlevar.score.txt.gz
prefix.traitName.recessive.singlevar.cov.txt.gz
prefix.traitName.dominant.singlevar.score.txt.gz
prefix.traitName.dominant.singlevar.cov.txt.gz

* If --kinGeno --kinSave is used, then the genomic relationship matrix is stored in
prefix.Empirical.Kinship.gz

* If --vcX option is used, then the genomic relationship matrix from chromosome X is stored in
prefix.Empirical.KinshipX.gz

====OUTPUT FILE FORMATS====

=====Summary Statistics=====
* In the file with summary statistics named prefix.traitName.singlevar.score.txt contains summary statistics that are needed by Rare-Metal. An example is shown in below:

LDL mean= -0.00, variance= 1.00, heritability= 34.30
CHR POS REF_ALLELE ALT_ALLELE INFORMATIVE_N FOUNDER_AF ALL_AF INFORMATIVE_AC HWE_PVALUE STAT ALT_ALLELE_EFFSIZE PVALUE
10 45410002 G A 6103 0.034159 0.034159 410 0.165893 126.2050 0.309798 4.030740e-10
19 45412079 G A 6103 0.036812 0.036812 434 0.714645 -265.8400 -0.587356 7.878510e-36
19 45414451 G A 6103 0.444989 0.444989 5312 0.075927 -26.1212 -0.008371 6.400580e-01

* pvalues from the above output are from the family-based single variant score test.

=====LD Matrices=====
* prefix.traitName.singlevar.cov.txt contains the LD matrix among a variant and the adjacent markers within a prefixed-sized window. The default window size is 1MB. It has the following format:

CHR POS VAR_POS_IN_WINDOW LD_MATRIX
1 762320 762320,865628,865665,878744,879381,1560000 0.0359084,-0.000242112,-0.00125797,-0.000993422,-0.000344509,-0.00017077,
1 865628 865628,865665,878744,879381,1560000,1864659 0.419804,-0.0103663,-0.00635265,0.0594056,0.0534505,-0.00462183,
1 878744 878744,879381,1560000,1864659,1877659 0.000404537,-0.000235215,-1.4455e-05,-8.69137e-06,-3.1027e-05,

=====Genomic Relationship Matrix (GRM)=====

* Once --kinGeno --kinSave --prefix options are requested, you would expect to see a GRM generated (compressed by gzip) with name yourprefix.Empirical.Kinship.gz. If --prefix option is not used, then the file name is Empirical.Kinship.gz.
* If --vcX --kinGeno --kinSave --prefix options are requested, besides the autosomal GRM, you would also expect to see a separate GRM for chromosome X saved (compressed by gzip also) under the name yourprefix.Empirical.KinshipX.gz.
* The GRMs are generated based on all genotyped individuals included in the PED file; samples with missing phenotype or missing covariates are not excluded from GRMs. This feature makes GRMs reusable if you have multiple traits to analyze in separate runs. You can simplely use --kinFile option (--kinxFile option if you have X chromosome GRM together with --vcX option issued) to reuse the pre-saved GRMs.
* The format for both autosomal and chromosome X GRMs are the same. The first row has all sample IDs (sample size=N) listed. The rest of the file is a symmetric matrix with dimention ''NxN'', and element ''ij'' of this matrix represents the kinship between the <math>i^{th}</math> and the <math>j^{th}</math> sample whose ID can be found from the first row.
* For details about GRM calculation, please refer to [[RAREMETALWORKER_method | '''method''']].

=====Log File=====
* RMW automatically generates a log file named "yourprefix.singlevar.log".
* The first part of the log file has options used for your analysis saved.

The following parameters are in effect:

Input Files:
============================
--ped [pheno.ped]
--dat [pheno.dat]
--vcf [allvars.vcf.gz]
--dosage [false]
--noeof [false]

Output Files:
============================
--prefix [rmw.test]
--LDwindow [1000000]
--zip [false]
--thin [false]
--labelHits [false]

VC Options:
============================
--vcX [true]
--separateX [true]

Trait Options:
============================
--makeResiduals [false]
--inverseNormal [false]
--traitName []

Model Options:
============================
--recessive [false]
--dominant [false]

Kinship Source:
============================
--kinPedigree [true]
--kinGeno [false]
--kinFile []
--kinxFile []
--kinSave [false]

Kinship Options:
============================
--kinMaf [0.05]
--kinMiss [0.05]

Chromosome X:
============================
xLabel [X]
xStart [2699520]
xEnd [154931044]
maleLabel [1]
femaleLabel [2]

* The second part of the log file has all warnings and running messages saved.

=====Plots=====
* RAREMETALWORKER generates QQ plot and Manhattan plots automatically, unless there are only trivial number of variants analyzed.
* RAREMETALWORKER stores plots of each trait in separate files named ''yourprefix.traitname.plots.pdf''.
* RAREMETALWORKER stores plots for recessive and dominant results separated with files named ''yourprefix.traitname.recessive.plots.pdf'' and ''yourprefix.traitname.dominant.plots.pdf''.
* RAREMETALWORKER automatically generates three stratified QQ plots, one with all variants, one with variants of maf<0.05, and one with variants of maf<0.01.
* Genomic controls are automatically calculated and labeled in QQ plots.
* By using --labelHits option, users can choose to label the hits.
* Here is an example QQ plot and manhattan plot generated by RAREMETALWORKER.

{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="100" | [[File:QQ.png]]
|-
| align="center" width="200" | [[File:Single_var_manhattan.png]]
|}

===SPECIAL TOPICS===
* For special topics such as how RAREMEALWORKER handles missing data, unrelated individuals, markers on chromosomeX, please go to [[RAREMETALWORKER_SPECIAL_TOPICS | '''SPECIAL TOPICS''']].

== Example Command Lines ==

The following list a few popular combinations of options used for analyses. For an itemized description of options, please go to [[RAREMETALWORKER_command_reference | '''COMMAND REFERENCE''']].

===General Usage===

* If your PED file has many traits but you only want one of them to be analyzed, then the following command does the trick:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --traitName BMI --prefix yourFavoritePrefix

* If you want to inverse normalize (quantile normalize) your trait before doing associations, this can be done by adding --inverseNormal to your command line:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --traitName BMI --prefix yourFavoritePrefix --inverseNormal

* The following command will adjust covariates first and then use residuals to proceed association:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --traitName BMI --prefix yourFavoritePrefix --makeResiduals

* The following command will adjust covariates first and then use the inverse normalized residuals to proceed association:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --traitName BMI --prefix yourFavoritePrefix --makeResiduals --inverseNormal

=== Related individuals ===

* When pedigree is known and you want to use it to count for relatedness then the following command can be used:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --kinPedigree --prefix yourFavoritePrefix

* When you want to an estimated genomic relationship matrix to count for relatedness then the following command can be used:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --prefix yourFavoritePrefix --kinGeno --kinSave (this will save the genomic relationship matrix for future use)

* If the genomic relationship matrix has been saved previously, and you want to use it to count for relatedness then the following command can be used:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --prefix yourFavoritePrefix --kinFile yourPreviouslySavedKinship

=== Unrelated individuals ===

* To analyze individuals as unrelated, even if pedigree is known, you just have to use the following command:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --vcf yourInput.vcf.gz --prefix yourFavoritePrefix

===Analyzing Chromosome X===

* To analyze markers on chromosome X, if relatedness is not considered, then no special options needs to be issued.

* When relatedness is modeled using linear mixed model, and pedigree is known, then the following command fits use both autosomal kinship and chromosomeX kinship to fit a variance component model:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --kinPedigree --vcX --vcf yourInput.vcf.gz --prefix yourFavoritePrefix

* Adding --separateX to the above command line will only use chromosome X kinship to fit the variance component model:

prompt> $PATH/bin/raremetalworker --ped yourInput.ped --dat yourInput.dat --kinPedigree --vcX --separateX --vcf yourInput.vcf.gz --prefix yourFavoritePrefix

* Please refer to [[RAREMETALWORKER_method | '''METHODS''']] for methods and [[RAREMETALWORKER_SPECIAL_TOPICS#Analyzing_Chromosome_X | '''SPECIAL TOPICS''']] for technical details.

===Using MERLIN format PED/DAT INPUT FILES===
* When genotypes are stored in MERLIN format PED/DAT files, command should be the same to do the above analysis, except --vcf option should be excluded.
* Please refer to [[RAREMETALWORKER#PED_and_DAT_Files | '''PED/DAT format''']] for format requirements.

== Tutorial ==
* For a comprehensive tutorial of RMW and RAREMETAL using example data sets, please go to the following:

[http://genome.sph.umich.edu/wiki/Tutorial:_RareMETAL '''RAREMETAL and RAREMETALWORKER Tutorial''']

RAREMETAL Change Log

2018-03-15T21:03:55Z

Abought:

[[Category:RAREMETAL]]
[[Category:RAREMETALWORKER]]
==Main Wiki Page==
* The [[RAREMETAL_Documentation | '''RAREMETAL documentation''']]
* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]

== Change Log ==

* [[Raremetal Incoming updates | Known issues and incoming update in next version]]

* Version 4.14.0 released (11/27/2016)
** '''Optimized method for unbalanced studies with no family structure (--useExact)'''. Check [[RAREMETAL METHOD]]
** bug fixes in conditional analysis
** fixed headers
** more methods in burden test

* Version 4.13.9 released (07/14/2016)
** The source code has been optimized to prepare for incoming new meta-analysis method in next version.
** Reduced running time when reading >10,000s individuals from vcf
** '''Fixed seg fault in raremetalworker for calculating SNP HWE p value when sample size > 40k'''
** A seg fault: sometimes you only have very few variants but raremetal still tries to calculate GC.

* Version 4.13.8 released (12/13/2015)
** when grouping from vcf, raremetal now obtains information only from "ANNOFULL" field.
** fixed seg fault in matching --annotation option to vcf annotation.
** with empty --annotation option, raremetal now groups all non-intergenic variants.
** '''fixed a bug in conditional analysis when there are multiple variants to condition on'''.
** fixed a seg fault in calculating genomic control.
** add --variantList option in RaremetalWorker to only calculate variance-covariance matrix between certain markers.
** add --range option in both Raremetal and RaremetalWorker to focus on given region only.

* Version 4.13.7 released. (9/18/2015).
** group file generated from annotated vcf is now stored in "test.groupfile" under current running directory.
** use -O0 option in compiling. In very rare situations, gcc optimization will affect the results.
** tabix RMW output with --zip toggled.
** In SKAT meta analysis, skip the variant when all its lambdas are zero.
** bug fixes in conditional analysis: in very rare situation raremetal takes rvtest input as raremetalworker input.
** add --altMAF option to exclude studies in which a variant is not present.

* Version 4.13.6 released. (3/8/2015)
** add a new option --mergedVCFID to recognize VCF files with sample IDs in "FAMID_PID" format
** add a new option --flagDosage to flag the field name to label dosage in VCF file.

* Version 4.13.5 released. (9/29/2014)
** a bug fixed in conditional analysis in raremetal.

* Version 4.13.4 released.
** store beta estimates of intercept and fixed effects in rarmetalworker *.singlevar.score.txt header.

* Version 4.13.3 released.
** read rvtest output format correctly in raremetal.

* Version 4.13.2.
** fixed sqrt_V output when analyzing unrelated individuals without kinship and --inverseNormal is not used and trait variance is not one.

* Version 4.13.1.
** fixed a bug affecting output format when ped/dat files are used together with --dominant --recessive options.

* version 4.13
** fixed bug when using --vcX option.
** Fixed bug estimating kinshipX with female samples.
** Added --kinOnly option for generating kinship only without association analysis.
** Added --geneMap option to allow user input for gene-mapping file.

* version 4.12.1
** fixed command interface display issue in raremetalworker.

* version 4.12
** improved make file for better compilation.

* version 4.11
** fixed a bug for inverse-normalizing traits (a bug only in version 4.9 and later).

* version 4.10
** fixed a bug when analyzing multiple traits is requested in raremetalworker (bug only in version 4.9 and later, and doesn't affect results).

===Version 4.8 and before===
* Released version 0.4.7 (4/24/2014).
** optimized code to increase analysis efficiency and reduce memory use.
** added --separateX option to provide another choice of analyzing chromosome X.
** added --kinxFile option to allow kinship X matrix file with different prefix from the autosomal kinship.
** merged raremetal and raremetalworker in one package following version number of raremetalworker.
** completed testing compiling on various platforms.
* Released version 0.4.6 binary. Fixed a bug in recessive and dominant results. (4/1/2014)
* Released version 0.4.5. Fixed a bug when generating plots for recessive results. (3/18/2014)
* Released version 0.4.4. (3/17/2014)
** bug fixed when alleles are flipped in group file.
** fixed hwe=0.0 issue for monomorphic sites.
* Released version 0.4.3. Fixed a few typo in messages. Added --noeof option for VCF files that does not have a BGZF EOF marker.
* Released version 0.4.2. (3/10/2014)
** fixed a bug that could possibly cause compiling error in some Linux system. male heterozygous
** male genotypes on chromosome X are considered missing.
** bug fixed for SKAT when there are two variants in a group
** bug fixed in Makefile for easy compiling.
* Released version 0.4.1. Fixed a bug handling variants in nonPAR region on chromosome X when all samples are male.
* Released version 0.4.0.
** added phone home function. Saved Recessive and dominant results in separate files.
** a few bugs fixed to properly handling missing genotypes.
** Major change in command options.
** allow user to specify list of summary statistics files and covariance files separately using --summaryFiles and --covFiles options.
* Released version 0.3.7. Added dominant and recessive models as options. The default model is additive. (1/7/2014)
* Released version 0.3.6 and fixed a minor bug that caused by code upgrades from version 0.3.5. (12/4/2013)
* Fixed a few bugs handling chromosome X. Generated warning messages when male genotypes are coded wrong in VCF file. (11/25/2013)
* Version 0.3.1 released to fix a bug when one of the alleles coded as missing.
* Version 0.2.9 released after fixing a bug in SKAT and writing PDF when all variants are monomorphic. (10/7/2013)
* Fixed the bug which causes crash when writing PDF when all variants are monomorphic. (10/6/2013)
* Added support for analyzing dosages from VCF in version 2.9. (8/27/2013)
* Version 0.1.2 released after fixing a few bugs, adding conditional analysis and automatic graphing to the tool. (8/5/2013)
* Fixed bug in handling chromosome X. Added sanity checking steps before analysis. Added graphic support by generating QQ and manhattan plots automatically. Upgraded tool to version 2.8. (till 8/12/2013)
* Updated code to report allele frequencies calculated only from selected samples. (3/3/2013)
* Optimized code to speed up the process of calculating empirical kinship. (3/3/2013)
* Fixed a bug when handling chromosome X. Added sex labels option. (3/2/2013)
* Version 0.0.1 released. (2/24/2013)
* Version 0.0.1 released to U of M CSG group. (2/13/2013)
* Fixed a bug when there is missing genotype from VCF file. (2/2013)
* Fixed a bug when reading vcf file with ref or alt allele is missing. (2/5/2013)
* Changed executable name into bin/raremetalworker. Version 0.0.7 released. (12/10/2012)
* Updated output format for monomorphic sites. (12/7/2012)
* Version 0.0.6 released. (12/6/2012)
* Bug fixed for empirical kinship calculation when genotypes are read from VCF file. Version 0.0.5 released. (12/6/2012)
* Version 0.0.4 released. (12/5/2012)
* More messages coded into log file. (12/4/2012)
* Updated output format. Version 0.0.3 released. (12/3/2012)
* Bugs fixed to solve compiling errors on some machines (Thank you Mary Kate!). Version 0.0.2 released. (11/30/2012)
* Added HWE pvalue and call rate in summary statistics output. (11/27/2012)
* Forced sample IDs to be matched when reading in kinship from a file. Perform a sanity check before reading in kinship file. If a sample of interest is not included in kinship file, then fatal error will occur. (11/19/2012)
* Enabled writing log file by defalut. (11/18/2012)
* Uploaded to public wiki. (11/16/2012)
* Modified Rare-Metal-Worker to let it output LD matrix by a sliding window. (11/14/2012)
* Version 0.0.1 was released on 11/13/2012.

RAREMETAL Documentation

2018-03-15T21:03:18Z

Abought:

[[Category:RAREMETAL]]
== Useful Wiki Pages ==

* Git hub page: https://github.com/statgen/Raremetal

* The [[RAREMETAL_Change_Log | Change Log]]

* The [[RAREMETAL_DOWNLOAD_%26_BUILD | DOWNLOAD page]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Quick Start Tutorial]]
* The [[RAREMETAL METHOD]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETAL Command Reference]]

* The [[RAREMETALWORKER|RAREMETALWORKER documentation]]

The [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''] tool for rare-variant association analysis can also generate output compatible with RAREMETAL.

== Brief Description ==

'''RAREMETAL''' is a computationally efficient tool for meta-analysis of rare variants using sequencing or genotyping array data. 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. 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''' has the following features:
* Performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, and Variable Threshold.
* Performs single variant metal-analysis by default.
* Allows customized groups of variants to be tested.
* Allows conditional analysis to be performed in both gene-level meta-analysis and single variants meta-analysis.
* 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. Our method has been published in [http://www.nature.com/ng/journal/v46/n2/abs/ng.2852.html '''Liu et. al'''] in Nature Genetics. Please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_method '''method'''] for details.

== Download and Installation ==
* University of Michigan CSG users can go to the following:
/net/wonderland/home/saichen/Raremetal/bin/

=== Where to Download ===

We have tested compilation using our source code on several platforms including Linux, MAC OS X, and Windows.

For source code and executables together with instructions of building from source, please go to [[RAREMETAL_DOWNLOAD_%26_BUILD |'''DOWNLOAD source and executables''']].

For questions about compilation, please go to [[RAREMETAL_FAQ | '''FAQ''']].

== Basic Usage Instructions ==

'''RAREMETAL''' 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====
'''RAREMETAL''' requires the following basic input files: summary statistics and covariance matrices of score statistics generated by '''RAREMETALWORKER''' 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 '''RAREMETALWORKER''' 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
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

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=====
* --summaryFiles 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 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

* When gene-level analysis is requested, --covFiles option should be used to specify the covariance files. An example file is:

/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/HUNT/RareMetalWorker/HUNT_MI_case.TG.singlevar.cov.txt.gz

* 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.

* Please sepcify --dosage option if input files were generated from dosage instead of genotype.

=====Group Rare Variants=====

====== From a Group File ======
* Grouping methods are only necessary when doing gene-based or group-based burden tests in meta-analysis.
* If none of the grouping method is specified, then only single variant meta-analysis will be performed.
* 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:
CHR:POS:REF:ALT
* An example group file is:
PLEKHN1 1:901922:G:A 1:901923:C:A 1:902088:G:A 1:902128:C:T 1:902133:C:G 1:902176:C:T 1:905669:C:G
HES4 1:934735:A:C 1:934770:G:A 1:934801:C:T 1:935085:G:A 1:935089:C:G
ISG15 1:949422:G:A 1:949491:G:A 1:949502:C:T 1:949608:G:A 1:949802:G:A 1:949832:G:A
AGRN 1:970687:C:T 1:976963:A:G 1:977028:G:T 1:977356:C:T 1:977396:G:A 1:978628:C:T 1:978645:G:A
C1orf159 1:1021285:G:T 1:1021302:T:C 1:1021315:A:C 1:1021386:G:A 1:1022534:C:T 1:1025751:C:T 1:1026913:C:T

====== 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 [[Rare-Metal#Example_Command_lines|'''examples''']] of this usage at the bottom of this page.

==== QC Options ====
* '''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''' 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 '''RAREMETAL''', 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, '''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 ==

=== 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 ===
* 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.
* --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
Note: this allows you to group variants that are annotated starting with nonsyn or splicing (not case-sensitive).

* Special format for the annotated VCF file is required: all annotation information should be coded in INFO field in VCF file, starting with the key "ANNO=". An example annotated VCF file is in the following:

#CHROM POS ID REF ALT QUAL FILTER INFO
1 19208194 . G A 100 PASS
AC=3;'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C866T:p.P289L,ALDH4A1:NM_001161504:exon8:c.C686T:p.P229L,ALDH4A1:NM_003748:exon8:c.C866T:p.P289L,;
'''ANNO='''splicing:ALDH4A1
1 19208293 . G C 100 PASS AC=7;STUDIES=5;MAC=7;MAF=0.001;DESIGN=TBD_ASSAY;DSCORE=1.00;
'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C767G:p.P256R,ALDH4A1:NM_001161504:exon8:c.C587G:p.P196R,ALDH4A1:NM_003748:exon8:c.C767G:p.P256R,

* 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.
* Generated group file will be named test.groupfile under your running directory.

===Options for Report Generation===
* --correctGC generates QQ plots and manhattan plots with pvalues corrected using genomic control.
* --prefix allows customized prefix for output files.
* --longOutput allows users to output not only burden test results but also the single variant results (allele frequencies, effect sizes, and p-values) for the variants being grouped together. Please refer to the output files section for detailed explanation and examples.
* --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 [[Rare-Metal#TABULATED_HITS| Tabulated Hits]].

===Miscellaneous Options===
* --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.

== Reports Generated by RAREMETAL ==
=== Single Variant Meta Analysis Output ===

==== TABLES ====

* Single variant meta analysis output has the following components: header, results and footnote.
* Header lines start with "##" shows summary of the meta analysis including method used, number of studies, and total sample size.
* Header line starts with "#" are column headers for results table.
* Footnote also starts with "#", where genomic controls from each study and the overall sample are reported.
* An example single variant meta analysis output is shown below:

##Method=SinglevarScore
##STUDY_NUM=2
##TotalSampleSize=14308
#CHROM POS REF ALT POOLED_ALT_AF EFFECT_SIZE DIRECTION_BY_STUDY PVALUE
1 115658497 G A 0.380906 0.00954332 ++ 0.45828
2 74688884 G A 8.33611e-05 -0.196387 -! 0.845372
3 121414217 C A 0.0747833 0.0216982 -+ 0.34453
6 137245814 G C 0.000803746 0.105693 ++ 0.601805
* 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 --summaryFiles.
"?" 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.

==== PLOTS====

'''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.
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="100" | [[File:QQ.png]]
|-
| align="center" width="200" | [[File:Single_var_manhattan.png]]
|}

=== Gene-level Tests Meta-Analysis Output ===

==== LONG TABLES ====
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.
##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs MAFs SINGLEVAR_EFFECTs SINGLEVAR_PVALUEs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.000166722,0.0242172,0.0109203,0.0355845,0.0333729,0.00700233,0.00200067 -0.183575,-0.00228307,-0.0598337,0.0220595,0.0229464,-0.0302768,-0.0200417 0.790161,0.953446,0.515806,0.503548,0.499251,0.791773,0.926625 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.0148408,0.00108369 -0.0502034,-0.0256403 0.528269,0.934606 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== SHORT TABLES ====
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.

##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== TABULATED HITS ====
* When --tabulateHits is specified, top hits from Burden tests will be generated. Each method will have an individual tabulated file generated. The purpose of this tabulated file is to list burden test results of top hits together with single variant results from variants being grouped in burden tests. The difference between this file and the standard long-format output file from burden test is that each row of the file represents a single variant that is included in the gene for burden test. This format allows each sorting on users end.

* Tabulated top hits are saved in the file:
yourPrefix.meta.tophits.youMethod.tbl (example files names: TG.meta.tophits.burden.tbl, LDL.meta.tophits.SKAT.tbl)

* The following items are tabulated in the output:
GENE: Gene name.
METHOD: Burden test used.
GENE_PVALUE: P-value from gene-based burden tests.
MAF_CUTOFF: MAF cutoff used when doing gene-based tests.
ACTUAL_CUTOFF: Actual MAF cutoff used. (This will be different from MAF_CUTOFF only for Variable Threshold method.
Otherwise, it will be the same as MAF_CUTOFF.)
VAR: Variant name in CHR:POS:REF:ALT format.
MAF: Single variant pooled MAF from all samples.
EFFSIZE: Effect size from single variant meta analysis.
PVALUE: Pvalue from single variant meta analysis.

* An example of tabulated hits from a standard burden test with maf<0.05 as criterion is shown in the following:

GENE METHOD GENE_PVALUE MAF_CUTOFF ACTUAL_CUTOFF VARS MAFS EFFSIZES PVALUES
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55505647:G:T 0.0396631 -0.442192 2.10159e-46
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55518371:G:A 0.0237138 0.0548733 0.430246
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55529187:G:A 0.0433324 0.0946321 0.00129942
APOE BURDEN_0.050 2.83457e-72 0.05 0.05 19:45412079:C:T 0.0413056 -0.554561 2.83457e-72

* According to the example above, PCSK9 had a p-value of 7.54587e-11 from the gene-based burden test, where three variants from this gene were included. Another hit from this meta analysis is APOE, where only one variant was included in the burden test.

==== PLOTS ====
'''RAREMETAL''' generates QQ plots and manhattan plots from single variant and gene-level meta-analysis by default. Example QQ plots and manhattan plots are:
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="200" | [[File:manhattan.png]]
|}

==== LOG ====

* A log file is automatically generated by '''RAREMETAL''' 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 [genes.file]
--annotatedVcf []
--annotation []
--writeVcf [OFF]

QC Options:
============================
--hwe [0]
--callRate [0]

Association Methods:
============================
--burden [true]
--MB [false]
--SKAT [false]
--VT [false]
--condition [condition.file]

Other Options:
============================
--tabix [OFF]
--correctGC [ON]
--prefix [test]
--maf [0.05]
--longOutput [false]
--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 --summaryFiles your.list.of.summary.files --prefix yourPrefix

* When you want to do all burden tests using a group file to specify which variants to group:
./raremetal --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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==
* For a comprehensive tutorial of RAREMETALWORKER and RAREMETAL using example data sets, please go to the following:

[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 Sai Chen (saichen at umich dot edu) for questions.

Also check [[Raremetal Incoming updates | '''Known issues and incoming update in next version''']] to see if your problem has been reported before

RAREMETAL DOWNLOAD & BUILD

2018-01-09T15:58:57Z

Abought: /* Where to Download */ Warn about pvalue errors.

== Useful Wiki Pages ==

* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]
* The [[RAREMETAL_Documentation | '''RAREMETAL documentation''']]
* The [[RAREMETAL FAQ | '''FAQ''']]
* The [[RAREMETAL_Change_Log | '''Change Log''']]

== Where to Download ==

* University of Michigan CSG users can go to the following:
/net/wonderland/home/saichen/Raremetal/

===GIT HUB===

Please clone or download from GitHub:

https://github.com/statgen/Raremetal

There is a known issue with the newest versions (>=4.14.0) of RAREMETAL, which may give incorrect p-values for some burden test calculation methods. We are working on a fix, but for now we recommend using an older version (<= 4.13.9).

Since v4.13.6, MAC and WINDOWS version are no longer updated. Please download old versions from here:

* [[Media:MAC_raremetal.4.13.6.tgz ‎|'''for MAC OS X''']]

* [[Media:CYGWIN64_raremetal.4.13.6.tgz ‎|'''for Windows/CygWin64''']]

* [[Media:MINGW_raremetal.4.13.6.tgz ‎|'''for Windows/MinGW''']]

From version 4.13.6, RAREMETALWORKER and RAREMETAL are distributed within the same package.

===SCRIPTS===

====Calculating Odds Ratio from RAREMETALWORKER output====
*If you want to estimate '''Odds Ratios''' of variants analyzed by RAREMETALWORKER, the script [[Media:CalculateOddsRatio.tgz|'''calculateOddsRatio.pl''']] can help you augment RAREMETALWORKER output with estimated odds ratio to the last column.
*The script can also be found in the RAREMETAL package 4.13.6 and later, under directory '''raremetal/script/calculateOddsRatio.pl'''.

== How to Compile ==

* gfortran is necessary to build RAREMETAL. If your system does not have it yet, please go to [http://gcc.gnu.org/wiki/GFortranBinaries '''GNU gfortran'''] for download.

* If you prefer to build from scratch, then do the following in your Raremetal directory:
prompt> make clean
prompt> make
#This builds RAREMETAL and RAREMETALWORKER under bin/ directory.

* If you prefer to build individual tool:
prompt> cd Raremetal/raremetalworker/
prompt> make
#This will build RAREMETALWORKER under raremetal/bin/ directory.

prompt> cd Raremetal/raremetal/
prompt> make
#This will build RAREMETAL under raremetal/bin/ directory.

* If your compiler is adaptable to openmp (parallel computing), then use the following to build RAREMETALWORKER that allows parallel computing. For more about openmp, please refer to [http://openmp.org/wp/openmp-compilers/ openMP].
prompt> cd raremetalworker/src
prompt> make openmp
#This will build RAREMETALWORKER under raremetal/bin/ directory.

* If you prefer to use the binary file downloaded above, then no compiling is needed, but it is not guaranteed to work due to system and library requirements.

==FAQ==

For compiling questions, please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_FAQ ''' FAQ'''] for more information.

==OLD VERSIONS==
(All linux versions)
* [[Media:Raremetal.4.13.8.tar.gz ‎|'''v4.13.8''']]
* [[Media:Raremetal.4.13.6.tar.gz ‎|'''v4.13.6''']]

Zlib

2017-12-22T20:58:29Z

Abought: Update package names for other platforms

The '''zlib''' library allows applications to conveniently read and write [[gzip]] compatible files. It was developed by Jean-Loupe Gailly and Mark Adler.

== Linux ==

'''zlib''' is included by default in most Linux distributions. If it is not available on your system, you could download and install a copy from http://www.zlib.net or use a package manager like <code>yum</code> or <code>apt</code> to install it on your system. A typical command line request to install zlib might look like one of the following (depending on your operating system or version):

yum install zlib-devel
apt-get install zlib-devel
apt-get install zlib1g-dev (Ubuntu)

== Windows ==

On Windows, '''zlib''' is available through the <code>MinGW</code>, <code>msys</code> and <code>CygWin</code> collections of utilities and libraries, which are designed to facilitate porting of applications from Linux to Windows.

RAREMETAL Documentation

2017-11-15T18:02:33Z

Abought: Point Github link at statgen repo

== Useful Wiki Pages ==

* Git hub page: https://github.com/statgen/Raremetal

* The [[RAREMETAL_Change_Log | Change Log]]

* The [[RAREMETAL_DOWNLOAD_%26_BUILD | DOWNLOAD page]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Quick Start Tutorial]]
* The [[RAREMETAL METHOD]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETAL Command Reference]]

* The [[RAREMETALWORKER|RAREMETALWORKER documentation]]

The [http://genome.sph.umich.edu/wiki/Rvtests '''rvtests'''] tool for rare-variant association analysis can also generate output compatible with RAREMETAL.

== Brief Description ==

'''RAREMETAL''' is a computationally efficient tool for meta-analysis of rare variants using sequencing or genotyping array data. 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. 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''' has the following features:
* Performs gene-based or region-based meta analysis using Burden tests with the following methods: CMC_counts, Madsen-Browning, SKAT, and Variable Threshold.
* Performs single variant metal-analysis by default.
* Allows customized groups of variants to be tested.
* Allows conditional analysis to be performed in both gene-level meta-analysis and single variants meta-analysis.
* 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. Our method has been published in [http://www.nature.com/ng/journal/v46/n2/abs/ng.2852.html '''Liu et. al'''] in Nature Genetics. Please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_method '''method'''] for details.

== Download and Installation ==
* University of Michigan CSG users can go to the following:
/net/wonderland/home/saichen/Raremetal/bin/

=== Where to Download ===

We have tested compilation using our source code on several platforms including Linux, MAC OS X, and Windows.

For source code and executables together with instructions of building from source, please go to [[RAREMETAL_DOWNLOAD_%26_BUILD |'''DOWNLOAD source and executables''']].

For questions about compilation, please go to [[RAREMETAL_FAQ | '''FAQ''']].

== Basic Usage Instructions ==

'''RAREMETAL''' 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====
'''RAREMETAL''' requires the following basic input files: summary statistics and covariance matrices of score statistics generated by '''RAREMETALWORKER''' 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 '''RAREMETALWORKER''' 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
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

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=====
* --summaryFiles 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 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

* When gene-level analysis is requested, --covFiles option should be used to specify the covariance files. An example file is:

/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/HUNT/RareMetalWorker/HUNT_MI_case.TG.singlevar.cov.txt.gz

* 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.

* Please sepcify --dosage option if input files were generated from dosage instead of genotype.

=====Group Rare Variants=====

====== From a Group File ======
* Grouping methods are only necessary when doing gene-based or group-based burden tests in meta-analysis.
* If none of the grouping method is specified, then only single variant meta-analysis will be performed.
* 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:
CHR:POS:REF:ALT
* An example group file is:
PLEKHN1 1:901922:G:A 1:901923:C:A 1:902088:G:A 1:902128:C:T 1:902133:C:G 1:902176:C:T 1:905669:C:G
HES4 1:934735:A:C 1:934770:G:A 1:934801:C:T 1:935085:G:A 1:935089:C:G
ISG15 1:949422:G:A 1:949491:G:A 1:949502:C:T 1:949608:G:A 1:949802:G:A 1:949832:G:A
AGRN 1:970687:C:T 1:976963:A:G 1:977028:G:T 1:977356:C:T 1:977396:G:A 1:978628:C:T 1:978645:G:A
C1orf159 1:1021285:G:T 1:1021302:T:C 1:1021315:A:C 1:1021386:G:A 1:1022534:C:T 1:1025751:C:T 1:1026913:C:T

====== 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 [[Rare-Metal#Example_Command_lines|'''examples''']] of this usage at the bottom of this page.

==== QC Options ====
* '''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''' 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 '''RAREMETAL''', 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, '''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 ==

=== 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 ===
* 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.
* --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
Note: this allows you to group variants that are annotated starting with nonsyn or splicing (not case-sensitive).

* Special format for the annotated VCF file is required: all annotation information should be coded in INFO field in VCF file, starting with the key "ANNO=". An example annotated VCF file is in the following:

#CHROM POS ID REF ALT QUAL FILTER INFO
1 19208194 . G A 100 PASS
AC=3;'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C866T:p.P289L,ALDH4A1:NM_001161504:exon8:c.C686T:p.P229L,ALDH4A1:NM_003748:exon8:c.C866T:p.P289L,;
'''ANNO='''splicing:ALDH4A1
1 19208293 . G C 100 PASS AC=7;STUDIES=5;MAC=7;MAF=0.001;DESIGN=TBD_ASSAY;DSCORE=1.00;
'''ANNO='''nonsynonymous:ALDH4A1:NM_170726:exon8:c.C767G:p.P256R,ALDH4A1:NM_001161504:exon8:c.C587G:p.P196R,ALDH4A1:NM_003748:exon8:c.C767G:p.P256R,

* 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.
* Generated group file will be named test.groupfile under your running directory.

===Options for Report Generation===
* --correctGC generates QQ plots and manhattan plots with pvalues corrected using genomic control.
* --prefix allows customized prefix for output files.
* --longOutput allows users to output not only burden test results but also the single variant results (allele frequencies, effect sizes, and p-values) for the variants being grouped together. Please refer to the output files section for detailed explanation and examples.
* --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 [[Rare-Metal#TABULATED_HITS| Tabulated Hits]].

===Miscellaneous Options===
* --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.

== Reports Generated by RAREMETAL ==
=== Single Variant Meta Analysis Output ===

==== TABLES ====

* Single variant meta analysis output has the following components: header, results and footnote.
* Header lines start with "##" shows summary of the meta analysis including method used, number of studies, and total sample size.
* Header line starts with "#" are column headers for results table.
* Footnote also starts with "#", where genomic controls from each study and the overall sample are reported.
* An example single variant meta analysis output is shown below:

##Method=SinglevarScore
##STUDY_NUM=2
##TotalSampleSize=14308
#CHROM POS REF ALT POOLED_ALT_AF EFFECT_SIZE DIRECTION_BY_STUDY PVALUE
1 115658497 G A 0.380906 0.00954332 ++ 0.45828
2 74688884 G A 8.33611e-05 -0.196387 -! 0.845372
3 121414217 C A 0.0747833 0.0216982 -+ 0.34453
6 137245814 G C 0.000803746 0.105693 ++ 0.601805
* 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 --summaryFiles.
"?" 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.

==== PLOTS====

'''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.
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="100" | [[File:QQ.png]]
|-
| align="center" width="200" | [[File:Single_var_manhattan.png]]
|}

=== Gene-level Tests Meta-Analysis Output ===

==== LONG TABLES ====
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.
##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs MAFs SINGLEVAR_EFFECTs SINGLEVAR_PVALUEs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.000166722,0.0242172,0.0109203,0.0355845,0.0333729,0.00700233,0.00200067 -0.183575,-0.00228307,-0.0598337,0.0220595,0.0229464,-0.0302768,-0.0200417 0.790161,0.953446,0.515806,0.503548,0.499251,0.791773,0.926625 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.0148408,0.00108369 -0.0502034,-0.0256403 0.528269,0.934606 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== SHORT TABLES ====
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.

##Method=Burden
##STUDY_NUM=2
##TotalSampleSize=14308
#GROUPNAME NUM_VAR VARs AVG_AF MIN_AF MAX_AF EFFECT_SIZE PVALUE
NOC2L 7 1:880502:C:T;1:881918:G:A;1:887799:C:T;1:888659:T:C;1:889238:G:A;1:891591:C:T;1:892380:G:A 0.0161807 0.000166722 0.0355845 0.00667875 0.662531
KLHL17 2 1:897285:A:G;1:898869:C:T 0.00796222 0.00108369 0.0148408 -0.0484494 0.528878

==== TABULATED HITS ====
* When --tabulateHits is specified, top hits from Burden tests will be generated. Each method will have an individual tabulated file generated. The purpose of this tabulated file is to list burden test results of top hits together with single variant results from variants being grouped in burden tests. The difference between this file and the standard long-format output file from burden test is that each row of the file represents a single variant that is included in the gene for burden test. This format allows each sorting on users end.

* Tabulated top hits are saved in the file:
yourPrefix.meta.tophits.youMethod.tbl (example files names: TG.meta.tophits.burden.tbl, LDL.meta.tophits.SKAT.tbl)

* The following items are tabulated in the output:
GENE: Gene name.
METHOD: Burden test used.
GENE_PVALUE: P-value from gene-based burden tests.
MAF_CUTOFF: MAF cutoff used when doing gene-based tests.
ACTUAL_CUTOFF: Actual MAF cutoff used. (This will be different from MAF_CUTOFF only for Variable Threshold method.
Otherwise, it will be the same as MAF_CUTOFF.)
VAR: Variant name in CHR:POS:REF:ALT format.
MAF: Single variant pooled MAF from all samples.
EFFSIZE: Effect size from single variant meta analysis.
PVALUE: Pvalue from single variant meta analysis.

* An example of tabulated hits from a standard burden test with maf<0.05 as criterion is shown in the following:

GENE METHOD GENE_PVALUE MAF_CUTOFF ACTUAL_CUTOFF VARS MAFS EFFSIZES PVALUES
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55505647:G:T 0.0396631 -0.442192 2.10159e-46
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55518371:G:A 0.0237138 0.0548733 0.430246
PCSK9 BURDEN_0.050 7.54587e-11 0.05 0.05 1:55529187:G:A 0.0433324 0.0946321 0.00129942
APOE BURDEN_0.050 2.83457e-72 0.05 0.05 19:45412079:C:T 0.0413056 -0.554561 2.83457e-72

* According to the example above, PCSK9 had a p-value of 7.54587e-11 from the gene-based burden test, where three variants from this gene were included. Another hit from this meta analysis is APOE, where only one variant was included in the burden test.

==== PLOTS ====
'''RAREMETAL''' generates QQ plots and manhattan plots from single variant and gene-level meta-analysis by default. Example QQ plots and manhattan plots are:
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="center" width="200" | [[File:manhattan.png]]
|}

==== LOG ====

* A log file is automatically generated by '''RAREMETAL''' 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 [genes.file]
--annotatedVcf []
--annotation []
--writeVcf [OFF]

QC Options:
============================
--hwe [0]
--callRate [0]

Association Methods:
============================
--burden [true]
--MB [false]
--SKAT [false]
--VT [false]
--condition [condition.file]

Other Options:
============================
--tabix [OFF]
--correctGC [ON]
--prefix [test]
--maf [0.05]
--longOutput [false]
--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 --summaryFiles your.list.of.summary.files --prefix yourPrefix

* When you want to do all burden tests using a group file to specify which variants to group:
./raremetal --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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 --summaryFiles your.list.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==
* For a comprehensive tutorial of RAREMETALWORKER and RAREMETAL using example data sets, please go to the following:

[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 Sai Chen (saichen at umich dot edu) for questions.

Also check [[Raremetal Incoming updates | '''Known issues and incoming update in next version''']] to see if your problem has been reported before

RAREMETAL DOWNLOAD & BUILD

2017-11-15T18:02:17Z

Abought: Point Github link at statgen repo

== Useful Wiki Pages ==

* The [[RAREMETALWORKER | '''RAREMETALWORKER documentation''']]
* The [[RAREMETAL_Documentation | '''RAREMETAL documentation''']]
* The [[RAREMETAL FAQ | '''FAQ''']]
* The [[RAREMETAL_Change_Log | '''Change Log''']]

== Where to Download ==

* University of Michigan CSG users can go to the following:
/net/wonderland/home/saichen/Raremetal/

===GIT HUB===

Please clone or download from GitHub:

https://github.com/statgen/Raremetal

Since v4.13.6, MAC and WINDOWS version are no longer updated. Please download old versions from here:

* [[Media:MAC_raremetal.4.13.6.tgz ‎|'''for MAC OS X''']]

* [[Media:CYGWIN64_raremetal.4.13.6.tgz ‎|'''for Windows/CygWin64''']]

* [[Media:MINGW_raremetal.4.13.6.tgz ‎|'''for Windows/MinGW''']]

From version 4.13.6, RAREMETALWORKER and RAREMETAL are distributed within the same package.

===SCRIPTS===

====Calculating Odds Ratio from RAREMETALWORKER output====
*If you want to estimate '''Odds Ratios''' of variants analyzed by RAREMETALWORKER, the script [[Media:CalculateOddsRatio.tgz|'''calculateOddsRatio.pl''']] can help you augment RAREMETALWORKER output with estimated odds ratio to the last column.
*The script can also be found in the RAREMETAL package 4.13.6 and later, under directory '''raremetal/script/calculateOddsRatio.pl'''.

== How to Compile ==

* gfortran is necessary to build RAREMETAL. If your system does not have it yet, please go to [http://gcc.gnu.org/wiki/GFortranBinaries '''GNU gfortran'''] for download.

* If you prefer to build from scratch, then do the following in your Raremetal directory:
prompt> make clean
prompt> make
#This builds RAREMETAL and RAREMETALWORKER under bin/ directory.

* If you prefer to build individual tool:
prompt> cd Raremetal/raremetalworker/
prompt> make
#This will build RAREMETALWORKER under raremetal/bin/ directory.

prompt> cd Raremetal/raremetal/
prompt> make
#This will build RAREMETAL under raremetal/bin/ directory.

* If your compiler is adaptable to openmp (parallel computing), then use the following to build RAREMETALWORKER that allows parallel computing. For more about openmp, please refer to [http://openmp.org/wp/openmp-compilers/ openMP].
prompt> cd raremetalworker/src
prompt> make openmp
#This will build RAREMETALWORKER under raremetal/bin/ directory.

* If you prefer to use the binary file downloaded above, then no compiling is needed, but it is not guaranteed to work due to system and library requirements.

==FAQ==

For compiling questions, please go to [http://genome.sph.umich.edu/wiki/RAREMETAL_FAQ ''' FAQ'''] for more information.

==OLD VERSIONS==
(All linux versions)
* [[Media:Raremetal.4.13.8.tar.gz ‎|'''v4.13.8''']]
* [[Media:Raremetal.4.13.6.tar.gz ‎|'''v4.13.6''']]

RAREMETAL

2017-11-15T17:55:19Z

Abought:

[[Category:Software]]
'''RAREMETAL''' is a program that facilitates the meta-analysis of rare variants from genotype arrays or sequencing (manuscript in preparation).
It was developed by [[Shuang_Feng|Shuang Feng]], Dajiang Liu and Gonçalo R. Abecasis. RAREMETAL has been used for the analyses in Exomechip blood lipids consortium and [[EMADS|EMADS]].

If you feel the program is useful, please take one minute to tell us your name and email ([https://docs.google.com/spreadsheet/ccc?key=0AuYjznTeEDYudFpqUk9sQ2pkN3d3endjYldqMEp6ZUE&usp=sharing '''registration''']). Thank you!

For questions please contact Andy Boughton via email: abought at umich dot edu.

== Useful Wiki Pages ==

There are a few pages in this Wiki that may be useful to RAREMETAL users. Here are links to a few:

* The [[RAREMETAL Command Reference]]

* The [[RAREMETAL_Documentation|RAREMETAL Documentation]]

* The [[Tutorial:_RAREMETAL|RAREMETAL Tutorial]]

* The [[RAREMETAL FAQ]]

* The [[RAREMETALWORKER | RAREMETALWORKER documentation]]

== Download and Build==

To download RAREMETAL executable and source code with instruction of build, go to [[Rare-Metal#Download_and_Installation|'''DOWNLOAD and INSTALLATION''']].

== Related Programs ==
[[RAREMETALWORKER]] is a program that does single variant association for sequencing and genotyping array data and generates summary statistics for meta-analysis in RAREMETAL.

[[LocusZoom]] is a program that facilitates display of genomewide association scan results.

[[METAL]] is a program that facilitates meta-analysis of single-variant genomewide scans.