Genome Analysis Wiki - User contributions [en]

GREGOR

2014-09-24T13:54:44Z

Cristen: /* Configuration File */

==GREGOR==

'''GREGOR''' ('''G'''enomic '''R'''egulatory '''E'''lements and '''G'''was '''O'''verlap algo'''R'''ithm) is a tool built to evaluate global enrichment of trait-associated variants in experimentally annotated epigenomic regulatory features.

Because all reference data are version hg19, please make sure that your index SNP list and BED files are also version hg19.

== Get GREGOR Source Codes ==

=== Download from webpage ===
Through this link [http://www.sph.umich.edu/csg/jich/FallInBed/ GREGOR Download], you can download a copy of GREGOR.

=== Download from GitHub with Git ===
You can create your own git clone(copy) using:

git clone https://github.com/jinchen-umich/GREGOR.git
or
git clone git://github.com/jinchen-umich/GREGOR.git

Either of these two commands creates a directory called GREGOR in the current directory.

=== Update your copy ===
If you have already downloaded your copy, use the following commands to update:
1. cd pathToYourCopy/GREGOR
2. git pull

=== Download From GitHub without Git ===
If there is no git in your system, you can still download from GitHub:
# Latest Code (master branch)
#: via Website
#:# Go to : https://github.com/jinchen-umich/GREGOR
#:# Click on the <code>Download ZIP</code> button on the right side panel.
#: via Command Line
#:: <code>wget https://github.com/jinchen-umich/GREGOR/archive/master.zip</code>

After downloading the file, uncompress (unzip/untar) it. The directory created will be named <code>GREGOR</code>.

== Build GREGOR ==

To build GREGOR, copy the GREGOR package to the directory you want, and then run the following command:

tar xzvf GREGOR.tar.gz

After you unzip, you can find 3 directories in "GREGOR" (./example ./lib ./script).

== Download reference files ==

Download the reference files from this link [http://www.sph.umich.edu/csg/jich/FallInBed/ GREGOR Download], then un-package the file

tar xzvf GREGOR.ref.tar.gz

After unzip, you will get 47 reference files in the directory "~/ref"

== Basic Usage Example ==

When you run

perl GREGOR.pl

you will get some information about GREGOR

----------------------------------------------------------------------------------
GREGOR.pl : Functional annotation of trait-associated variants
----------------------------------------------------------------------------------
This program tests for enrichment of an input list of trait-associated index
SNPs ([chr:pos] format or rsID, hg19) in experimentally annotated regulatory
domains (BED files).

Note: the index SNPs should be hg19 version. All maf and LD data are from 1000G
EUR samples! (Release date : May 21, 2011)

Version : 1.1.0

Report Bug(s) : jich[at]umich[dot]edu
----------------------------------------------------------------------------------
Usage : perl GREGOR.pl --conf [conf.file]
----------------------------------------------------------------------------------

The following command is a typical command line:

perl GREGOR.pl --conf [conf.file]

Example configuration file can be found in example directory. Users have to modify the configurations before running.

== Configuration File ==
The example configuration file below illustrate how to configure the GREGOR configuration file.

###############################################################################
# CHIPSEQ ENRICHMENT CONFIGURATION FILE
# This configuration file contains run-time configuration of
# CHIP_SEQ ENRICHMENT
###############################################################################
## KEY ELEMENTS TO CONFIGURE : NEED TO MODIFY
###############################################################################
INDEX_SNP_FILE = /workingdirectory/example/example.index.snps.rsid.list.txt ## e.g. /workingdirectory/example/example.index.snps.rsid.list.txt
BED_FILE_INDEX = /workingdirectory/example/example.bed.file.index ## e.g. /workingdirectory/example/example.bed.file.index
REF_DIR = /workingdirectory/ref/ ## reference directory
R2THRESHOLD = 0.7
LDWINDOWSIZE = 1000000
OUT_DIR = /workingdirectory/example/example.rsid.20130808/ ## e.g. /workingdirectory/example/example.rsid.20130808/
MIN_NEIGHBOR_NUM = 500
BEDFILE_IS_SORTED = True
MOSRUN = mosbatch -E/tmp -i -m2000 -j20,43,122,135,137,138,149,151,153,154,155,156,162,163 sh -c

In the config file, there are several parameters to adjust:

INDEX_SNP_FILE: This file contains a single column of trait-associated input SNPs, without a header. Variants can be listed in rsid or hg19 chr:pos format.

BED_FILE_INDEX: This file lists the datasets (e.g. BED files) to be used for enrichment analysis. Use complete paths to file locations and make sure positions are in hg19 format.

REF_DIR: Define reference file directory which you download at here.

R2THRESHOLD and LDWINDOWSIZE: These two parameters define the index SNP (and control SNP) LD proxies by r2 threshold and LD window size.

OUT_DIR: All result files are saved to this folder, where the script will create multiple sub-directories. Index SNPs are in the folder "index_SNP"; Random SNPs are in the folder "random_SNP".

MIN_NEIGHBOR_NUM: Define the minimum number of control SNPs for each index SNP. Script will find no less than this number around every index SNP. If you make this number of control SNPs very large, the control SNPs will be less closely matched on the three matching properties (distance to nearest gene, frequency and number of SNPs in LD).

BEDFILE_IS_SORTED: True or false, depending on whether the BED files listed in the index file are sorted.

== Results Output ==
The file StatisticSummaryFile.txt in the output directory contains enrichment results with the following information:

Bed_File: The individual datasets used in the enrichment analysis

InBed_Index_SNP: Number of index SNPs or their LD proxies that overlaps regulatory regions in each dataset

Pvalue: P-value calculated assuming a sum of binomial distributions to represent the number of index SNPs (or LD proxies) that overlap a dataset compared to the expectation observed in the matched control sets

*Note: SNPs that cannot be converted from rsID to chr:pos format are listed in the output file rsid.index.snp.txt. SNPs for which there are no LD proxies or no MAF data available are listed in the output file nonannoted.index.snp.txt.

== Testing GREGOR ==
There is an example directory in ~/GREGOR. You can find index SNP file, 3 bed files, bed file index and example config file.
After change your config file, you can run a test.

perl ~/GREGOR/script/GREGOR.pl --conf ~/GREGOR/example/example.conf

After running 2 minutes +/- 1 minutes. You will get result file "StatisticSummaryFile.txt" in your defined output directory.

== Acknowledgements ==
GREGOR is the result of collaborative efforts by Cristen Willer, Jin Chen, Wei Zhou, Ellen Schmidt, He Zhang, and Goncalo Abecasis. Please email Cristen Willer [cristen@umich.edu] with any questions.

LocusZoom

2013-04-23T15:34:10Z

Cristen: /* Uploading Your Association Study Results */

[[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 ===

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

Association results can be uploaded to our web server using the [http://csg.sph.umich.edu/locuszoom/ 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

2012-12-11T15:57:55Z

Cristen: /* Uploading Your Association Study Results */

[[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 ===

Association results can be uploaded to our web server using the [http://csg.sph.umich.edu/locuszoom/ 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]]

METAL Documentation

2011-05-25T15:16:00Z

Cristen: /* Specifying Weights in P-value Based Analysis */

== Useful Wiki Pages ==

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

* The [[METAL Program|METAL Home Page]]

* The [[METAL Quick Start|METAL Quick Start Tutorial]]

* The [[METAL FAQ]]

* The [[METAL Command Reference]]

== History ==

METAL was developed by Goncalo Abecasis, Yun Li and Cristen Willer ([http://www.sph.umich.edu/csg/abecasis/publications/pdf/Bioinformatics.vol.26-pp.2190.pdf manuscript available here]). The first version was developed in 2007 and was used for the analyses presented in [http://www.sph.umich.edu/csg/abecasis/publications/18193045.html Sanna et al (2008)] and [http://www.sph.umich.edu/csg/abecasis/publications/18193043.html Willer et al (2008)]. Since then, it has become quite a popular tool for the analysis of genomewide association scans.

== Brief Description ==

METAL is a tool for meta-analysis genomewide association scans. METAL can combine either (a) test statistics and standard errors or (b) p-values across studies (taking sample size and direction of effect into account). METAL analysis is a convenient alternative to a direct analysis of merged data from multiple studies. It is especially appropriate when data from the individual studies cannot be analyzed together because of differences in ethnicity, phenotype distribution, gender or constraints in sharing of individual level data imposed. Meta-analysis results in little or no loss of efficiency compared to analysis of a combined dataset including data from all individual studies.

== Approach ==

One of the most common questions we receive is about the approach used by METAL to carry out a meta-analysis using p-values as input. The process is actually quite simple! First, for each marker, a reference allele is selected and a z-statistic characterizing the evidence for association is calculated. The z-statistic summarizes the magnitude and the direction of effect relative to the reference allele and all studies are aligned to the same reference allele. Next, an overall z-statistic and p-value are then calculated from a weighted sum of the individual statistics. Weights are proportional to the square-root of the number of individuals examined in each sample and selected such that the squared weights sum to 1.0. For samples that contain related individuals, a smaller ‘effective’ sample size may be used, but simulations suggest that modest changes in the effective sample size have very little impact on the final p-value.

== Basic Usage Instructions ==

METAL is a command line tool. It is typically run from a Linux, Unix or DOS prompt by invoking the command <code>metal</code>. Analyses can be run interactively or a simple script can be provided as input. Interactive analyses are usually convenient when learning how to use METAL, whereas the scripting approach is preferred for production use (as it allows analyses to be conveniently repeated). An example METAL script is included at the bottom of this page.

METAL has lots of options and here we have listed some common ones that, hopefully, will help you get started.

=== Help! ===

Issuing the <code>HELP</code> command lists all available commands and the current settings for each option. The list of all available commands is also available in the [[METAL Command Reference]].

=== Input File Separators ===

METAL expects that each set of results will be summarized in a table. This table must be stored in a text file but otherwise METAL is quite flexible about details such as column separators, column headers and the like. This does mean that an essential bit of information needed before any meta-analysis is a description of each input file.

The first thing you should specify is the column separator. By default, METAL assumes columns are separated by whitespace (which consists of any combination of space and tab characters). You can also specify:

SEPARATOR WHITESPACE - the default
SEPARATOR COMMA - for comma delimited files that are popular in some platforms
SEPARATOR TAB - columns separated by a single tab, so that consecutive tabs indicate an empty column

=== Input File Columns ===

Each input file should include the following information:

* A column with marker name, which should be consistent across studies
* A column indicating the tested allele
* A column indicating the other allele

If you are carrying out a sample size weighted analysis (based on p-values), you will also need:

* A column indicating the direction of effect for the tested allele
* A column indicating the corresponding p-value
* An optional column indicating the sample size (if the sample size varies by marker)

If you are carrying out a meta-analysis based on standard errors, you will need:

* A column indicating the estimated effect size for each marker
* A column indicating the standard error of this effect size estimate

The header for each of these columns must be specified so that METAL knows how to interpret the data. As noted below, additional columns including allele frequency information, strand information, and others can also be present.

Here is a typical set of commands that would describe a table where the headers SNP, RefAllele, NonRefAllele, Pvalue and Beta correspond to the MARKER, ALLELE 1 and 2, PVALUE and EFFECT columns:

MARKERLABEL SNP
ALLELELABELS RefAllele NonRefAllele
PVALUELABEL P-value
EFFECTLABEL Effect

These can be abbreviated as:

MARKER SNP
ALLELE RefAllele NonRefAllele
PVALUE P-value
EFFECT Effect

=== Specifying Weights in P-value Based Analysis ===

The weight for each MARKER can be stored in a column in the table (specified with the <code>WEIGHTLABEL</code> or <code>WEIGHT</code> commands).

WEIGHT N

Alternatively, the same weight can be used for all markers for that inputfile (in which case the fixed weight can be set with the <code>DEFAULTWEIGHT</code> command). The WEIGHTLABEL command takes precedence over the DEFAULTWEIGHT command, so the WEIGHT column label in use must not match any columns in the inputfile.

WEIGHT DONTUSECOLUMN
DEFAULTWEIGHT 1000

=== Reading Each Input File ===

Once all appropriate headers have been specified, issuing the <code>PROCESS</code> command will read an input file and update summary statistics to take the results it contains into account. Thus:

PROCESS study1-results.tbl

=== Performing the Final Analysis ===

Once all input files have been processed, simply issue the <code>ANALYZE</code> command to execute a meta-analysis. If you'd like to execute interim analysis that include only a subset of the studies, issue the ANALYZE command after the corresponding input files have been processed.

ANALYZE

To allow for heterogeneity, use the <code>ANALYZE HETEROGENEITY</code> command. This command will take a little longer to run, because it requires each input file to be examined twice. The METAL heterogeneity analysis requires a second pass of analysis to decide whether observed effect sizes (or test statistics) are homogeneous across samples. The resulting heterogeneity statistic has n-1 degrees of freedom for n samples.

ANALYZE HETEROGENEITY

METAL does not require that all input files report a result for every marker. Any available data is used. To restrict the output to only markers that have at least a specific number of individuals analysed (or weight), use a command like the following:

MINWEIGHT 10000

For example to restrict the output to show only Markers with a total sample size of at least 10,000 individuals.

== Additional Analysis Options ==

=== Selecting an Analysis Scheme ===

SCHEME SAMPLESIZE - default approach, uses p-value and direction of effect, weighted according to sample size
SCHEME STDERR - classical approach, uses effect size estimates and standard errors
STDERR SE - specify the label for the standard error column.

By default, METAL combines p-values across studies taking into account a study specific weight (typically, the sample size) and direction of effect. This behavior can be requested explicitly with the <code>SCHEME SAMPLESIZE</code> command. An alternative can be requested with the <code>SCHEME STDERR</code> command and weights effect size estimates using the inverse of the corresponding standard errors. To enable this option, you will also need to specify which of your input columns contains standard error information using the <code>STDERRLABEL</code> command (or <code>STDERR</code> for short). While standard error based weights are more common in the biostatistical literature, if you decide to use this approach, it is very important to ensure that effect size estimates (''beta'' coefficients) and standard errors use the same units in all studies (i.e. make sure that the exact same trait was examined in each study and that the same transformations were applied). Inconsistent use of measurement units across studies is the most common cause of discrepancies between these two analysis strategies.

=== Genomic Control Correction ===

GENOMICCONTROL OFF - the default, no adjustment to test statistics
GENOMICCONTROL ON - automatically correct test statistics to account for small amounts of population stratification or unaccounted for relatedness
GENOMICCONTROL [value] - correct test statistics using the specified inflation factor

METAL has the ability to apply a genomic control correction to all input files. METAL will estimate the inflation of the test statistic by comparing the median test statistic to that expected by chance, and then apply the genomic control correction to the p-values (for SAMPLESIZE weighted meta-analysis) or the standard error (for STDERR weighted meta-analysis). This should only be applied to files with whole genome data (i.e. should not be used for settings where results are only available for a candidate locus or a small number of SNPs selected for follow-up of [[GWAS]] results). Genomic control settings can be customized for each input file. We recommend applying genomic control correction to all input files that include genomewide data and, in addition, to the meta-analysis results. To apply genomic control to the meta-analysis results, just perform an initial meta-analysis and then load the initial set of results into METAL to get final, genomic control adjusted results.

=== Strand Information ===

USESTRAND ON
STRANDLABEL StrandColumnHeading

Input files can contain a column that indicates which strand the alleles are coded on (given as +/-). If this column is present, you should issue the <code>USESTRAND ON</code> command and specify an appropriate header with the <code>STRANDLABEL</code> command. If USESTRAND is off, the strand is assumed to be “+” for all SNPs, although obvious strand problems are identified by METAL and appropriately handled (for example, when one study provides A/G alleles and a different study provides C/T alleles).

=== Filtering ===

Custom filters can be used to select SNPs for inclusion in the meta-analysis. This can be used, for example, to select SNPs within a specified minor-allele frequency range for analysis.

Here are some possible filters:

ADDFILTER N > 1000
ADDFILTER MAF > 0.01

Together, these two filters would only consider entries where the value in the N column is greater than 1000 and the value in the MAF column is also greater than 0.01.

Filters can be defined using the <, >, <=, >=, =, != and IN operators. The IS operator tests membership in a set. For example to restrict analysis to three interesting SNPs, use (''note absence of spaces in list of SNPs''):

ADDFILTER MARKER_ID IN (rs1234,rs123456,rs123)

To remove all previously defined filters, use the command:

REMOVEFILTERS

=== Verbose Mode ===

VERBOSE ON

METAL allows for complete output of individual summary statistics for all SNPs in all input files. This can create a very large file and should be used with caution. Typically, one should create custom filters to restrict analyses to interesting SNPs of interest before using this option. This option can be useful for comparing direction of effect across many studies since METAL takes care of all the strand flipping and provides the direction of effect relative to the same allele. This is also a way to double-check that the expected data are being used appropriately by METAL.

=== Lenient Mode ===

COLUMNCOUNTING STRICT - requires expected number of columns in every row
COLUMNCOUNTING LENIENT - tries to interpret rows with fewer columns than expected

By default, METAL will skip lines in each input file that don't have the expected number of columns. This is usually a good idea because it avoids producing incorrect results when a column is missing. Sometimes (for example, when there are optional extra columns at the end of each line), the <code>COLUMNCOUNTING LENIENT</code> option can be useful.

=== Tracking Allele Frequencies ===

AVERAGEFREQ ON
MINMAXFREQ ON

METAL can optionally track the effect allele frequency across all files and report the mean, minimum and maximum effect allele frequency. These can be quite useful to check that allele frequencies are similar across different cohorts after METAL performs all strand alignment. Large differences in allele frequencies across studies can suggest inconsistent naming of reference alleles across studies. METAL requires all input files to have an allele frequency column when this feature is turned on. To specify the column header for allele frequency information, use the <code>FREQLABEL</code> command.

=== Custom Variables ===

We allow users to keep cumulative counts of custom variables across input files. An example of this might be to keep track of the sample size when performing standard-error weighted meta-analysis. The name of the custom variable should be defined once, before input files are loaded. The corresponding column label in each input file can be specified using the <code>LABEL</code> command. For example, to create a custom variable labeled TotalSampleSize that tallies the total of the N column across files, one could issue the commands:

CUSTOMVARIABLE TotalSampleSize
LABEL TotalSampleSize as N

If needed, the <code>LABEL</code> command can be used multiple times to customize column headers for each input file.

=== Input File Recommendations ===

We strongly recommend that both allele labels, corresponding to the the effect allele and non-effect allele, should be provided for all SNPs. As long as both allele columns are given for each input file, METAL appropriately accounts for situations when different input files use different reference alleles. Alleles can be coded numerically (A=1,C=2,G=3,T=4) or alphabetically (A,C,G,T,a,c,g,t) and can be on either strand if not an A/T or C/G SNP. For A/T or C/G SNPs, METAL requires SNPs to be on a consistent strand in different input files for the results to be interpretable. For other SNPs, METAL can automatically identify and resolve strand inconsistencies.

P-values that are < 0.0, > 1.0 or non-numeric will be treated as missing and generate a warning.

The EFFECT column can have positive and negative values (beta values from regression, for example), or simply directions of effect relative to the reference allele, listed as “+” and “-“. An EFFECT of “+” (or any positive number) with respect to the reference allele A (or effect allele A), for example, represents a case where increasing number of copies of allele A are correlated with increasing trait values. For discrete traits, it is common to report odds ratios, which are always positive. In this case, to calculate the direction of effect, one should look at the log of the odds ratio. METAL can compute the odds ratio for you if you specify <code>EFFECT log(ODDS_RATIO_COLUMN)</code>

To perform odds-ratio based meta-analysis, select SCHEME STDERR at the beginning of the script. Then, for each file, provide the natural log of the odds ratio as the EFFECT column or another appropriate statistic (such as the corresponding regression coefficient from a logistic regression analysis).

== Example: A METAL Meta-Analysis Script ==

<pre>
#THIS SCRIPT EXECUTES AN ANALYSIS OF EIGHT STUDIES
#THE RESULTS FOR EACH STUDY ARE STORED IN FILES Inputfile1.txt THROUGH Inputfile8.txt

#LOAD THE FIRST EIGHT INPUT FILES

# UNCOMMENT THE NEXT LINE TO ENABLE GenomicControl CORRECTION
# GENOMICCONTROL ON

# === DESCRIBE AND PROCESS THE FIRST INPUT FILE ===
MARKER SNP
ALLELE REF_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE PVALUE
WEIGHT N
PROCESS inputfile1.txt

# === THE SECOND INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile2.txt

# === DESCRIBE AND PROCESS THE THIRD INPUT FILE ===
MARKER SNP
ALLELE A_REF OTHER_ALLELE
EFFECT BETA
PVALUE pvalue
WEIGHT N
PROCESS inputfile3.txt

# === DESCRIBE AND PROCESS THE FOURTH INPUT FILE ===
MARKER MARKERNAME
ALLELE EFFECTALLELE NON_EFFECT_ALLELE
EFFECT EFFECT1
PVALUE PVALUE
WEIGHT NONMISS
PROCESS inputfile4.txt

# === CARRY OUT AN INTERIM ANALYSIS OF THE FIRST FOUR FILES ===
OUTFILE METAANALYSIS_inputfile1to4_ .tbl
ANALYZE

# LOAD THE NEXT FOUR INPUT FILES

# === DESCRIBE AND PROCESS THE FIFTH INPUT FILE ===
MARKER rsid
ALLELE EFFECT_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE Add_p
WEIGHT total_N
SEPARATOR COMMAS
PROCESS inputfile5.txt

# === THE SIXTH INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile6.txt

# === DESCRIBE AND PROCESS THE SEVENTH INPUT FILE ===
ALLELE ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE PVALUE
WEIGHT N
SEPARATOR WHITESPACE
PROCESS inputfile7.txt

# === DESCRIBE AND PROCESS THE EIGHTH INPUT FILE ===
ALLELE BETA_ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE P_VAL
WEIGHT N
PROCESS inputfile8.txt

#for the final meta-analysis of all 8 samples only output results if the
#combined weight is greater than 10000 people

OUTFILE METAANALYSIS_inputfile1-8_ .tbl
MINWEIGHT 10000
ANALYZE

QUIT
</pre>

2011-02-05T01:27:24Z

Cristen: /* Summary of rare variant tests for sequence data */

Rare variant tests

2011-02-05T01:25:24Z

Cristen: /* Summary of rare variant tests for sequence data */

2010-03-29T02:05:26Z

Cristen: /* Specifying Weights in P-value Based Analysis */

== History ==

METAL was developed by Goncalo Abecasis, Yun Li and Cristen Willer. The first version was developed in 2007 and was used for the analyses presented in [http://www.sph.umich.edu/csg/abecasis/publications/18193045.html Sanna et al (2008)] and [http://www.sph.umich.edu/csg/abecasis/publications/18193043.html Willer et al (2008)]. Since then, it has become quite a popular tool for the analysis of genomewide association scans.

== Brief Description ==

METAL is a tool for meta-analysis genomewide association scans. METAL can combine either (a) test statistics and standard errors or (b) p-values across studies (taking sample size and direction of effect into account). METAL analysis is a convenient alternative to a direct analysis of merged data from multiple studies. It is especially appropriate when data from the individual studies cannot be analyzed together because of differences in ethnicity, phenotype distribution, gender or constraints in sharing of individual level data imposed. Meta-analysis results in little or no loss of efficiency compared to analysis of a combined dataset including data from all individual studies.

== Approach ==

One of the most common questions we receive is about the approach used by METAL to carry out a meta-analysis using p-values as input. The process is actually quite simple! First, for each marker, a reference allele is selected and a z-statistic characterizing the evidence for association is calculated. The z-statistic summarizes the magnitude and the direction of effect relative to the reference allele and all studies are aligned to the same reference allele. Next, an overall z-statistic and p-value are then calculated from a weighted sum of the individual statistics. Weights are proportional to the square-root of the number of individuals examined in each sample and selected such that the squared weights sum to 1.0. For samples that contain related individuals, a smaller ‘effective’ sample size may be used, but simulations suggest that modest changes in the effective sample size have very little impact on the final p-value.

== Basic Usage Instructions ==

METAL is a command line tool. It is typically run from a Linux, Unix or DOS prompt by invoking the command <code>metal</code>. Analyses can be run interactively or a simple script can be provided as input. Interactive analyses are usually convenient when learning how to use METAL, whereas the scripting approach is preferred for production use (as it allows analyses to be conveniently repeated). An example METAL script is included at the bottom of this page.

METAL has lots of options and here we have listed some common ones that, hopefully, will help you get started.

=== Help! ===

Issuing the <code>HELP</code> command lists all available commands and the current settings for each option. The list of all available commands is also available in the [[METAL Command Reference]].

=== Input File Separators ===

METAL expects that each set of results will be summarized in a table. This table must be stored in a text file but otherwise METAL is quite flexible about details such as column separators, column headers and the like. This does mean that an essential bit of information needed before any meta-analysis is a description of each input file.

The first thing you should specify is the column separator. By default, METAL assumes columns are separated by whitespace (which consists of any combination of space and tab characters). You can also specify:

SEPARATOR WHITESPACE - the default
SEPARATOR COMMA - for comma delimited files that are popular in some platforms
SEPARATOR TAB - columns separated by a single tab, so that consecutive tabs indicate an empty column

=== Input File Columns ===

Each input file should include the following information:

* A column with marker name, which should be consistent across studies
* A column indicating the tested allele
* A column indicating the other allele

If you are carrying out a sample size weighted analysis (based on p-values), you will also need:

* A column indicating the direction of effect for the tested allele
* A column indicating the corresponding p-value
* An optional column indicating the sample size (if the sample size varies by marker)

If you are carrying out a meta-analysis based on standard errors, you will need:

* A column indicating the estimated effect size for each marker
* A column indicating the standard error of this effect size estimate

The header for each of these columns must be specified so that METAL knows how to interpret the data. As noted below, additional columns including allele frequency information, strand information, and others can also be present.

Here is a typical set of commands that would describe a table where the headers SNP, RefAllele, NonRefAllele, Pvalue and Beta correspond to the MARKER, ALLELE 1 and 2, PVALUE and EFFECT columns:

MARKERLABEL SNP
ALLELELABELS RefAllele NonRefAllele
PVALUELABEL P-value
EFFECTLABEL Effect

These can be abbreviated as:

MARKER SNP
ALLELE RefAllele NonRefAllele
PVALUE P-value
EFFECT Effect

=== Specifying Weights in P-value Based Analysis ===

The weight for each MARKER can be stored in a column in the table (specified with the <code>WEIGHTLABEL</code> or <code>WEIGHT</code> commands) or the same weight can be used for all markers for that inputfile (in which case the fixed weight can be set with the <code>DEFAULTWEIGHT</code> command).

=== Reading Each Input File ===

Once all appropriate headers have been specified, issuing the <code>PROCESS</code> command will read an input file and update summary statistics to take the results it contains into account. Thus:

PROCESS study1-results.tbl

=== Performing the Final Analysis ===

Once all input files have been processed, simply issue the <code>ANALYZE</code> command to execute a meta-analysis. If you'd like to execute interim analysis that include only a subset of the studies, issue the ANALYZE command after the corresponding input files have been processed.

To allow for heterogeneity, use the <code>ANALYZE HETEROGENEITY</code> command. This command will take a little longer to run, because it requires each input file to be examined twice. The METAL heterogeneity analysis requires a second pass of analysis to decide whether observed effect sizes (or test statistics) are homogeneous across samples. The resulting heterogeneity statistic has n-1 degrees of freedom for n samples.

METAL does not require that all input files report a result for every marker. Any available data is used. To restrict the output to only markers that have at least a specific number of individuals analysed (or weight), use a command like the following:

MINWEIGHT 10000

For example to restrict the output to show only Markers with at least 10,000 individuals.

== Additional Analysis Options ==

=== Selecting an Analysis Scheme ===

SCHEME SAMPLESIZE - default approach, uses p-value and direction of effect, weighted according to sample size
SCHEME STDERR - classical approach, uses effect size estimates and standard errors

By default, METAL combines p-values across studies taking into account a study specific weight (typically, the sample size) and direction of effect. This behavior can be requested explicitly with the <code>SCHEME SAMPLESIZE</code> command. An alternative can be requested with the <code>SCHEME STDERR</code> command and weights effect size estimates using the inverse of the corresponding standard errors. While standard error based weights are more common in the biostatistical literature, if you decide to use this approach, it is very important to ensure that effect size estimates (''beta'' coefficients) and standard errors use the same units in all studies (i.e. make sure that the exact same trait was examined in each study and that the same transformations were applied). Inconsistent use of measurement units across studies is the most common cause of discrepancies between these two analysis strategies.

=== Genomic Control Correction ===

GENOMICCONTROL OFF - the default, no adjustment to test statistics
GENOMICCONTROL ON - automatically correct test statistics to account for small amounts of population stratification or unaccounted for relatedness
GENOMICCONTROL [value] - correct test statistics using the specified inflation factor

METAL has the ability to apply a genomic control correction to all input files. METAL will estimate the inflation of the test statistic by comparing the median test statistic to that expected by chance, and then apply the genomic control correction to the p-values (for SAMPLESIZE weighted meta-analysis) or the standard error (for STDERR weighted meta-analysis). This should only be applied to files with whole genome data (i.e. should not be used for settings where results are only available for a candidate locus or a small number of SNPs selected for follow-up of GWAS results). Genomic control settings can be customized for each input file. We recommend applying genomic control correction to all input files that include genomewide data and, in addition, to the meta-analysis results. To apply genomic control to the meta-analysis results, just perform an initial meta-analysis and then load the initial set of results into METAL to get final, genomic control adjusted results.

=== Strand Information ===

USESTRAND ON
STRANDLABEL StrandColumnHeading

Input files can contain a column that indicates which strand the alleles are coded on (given as +/-). If this column is present, you should issue the <code>USESTRAND ON</code> command and specify an appropriate header with the <code>STRANDLABEL</code> command. If USESTRAND is off, the strand is assumed to be “+” for all SNPs, although obvious strand problems are identified by METAL and appropriately handled (for example, when one study provides A/G alleles and a different study provides C/T alleles).

=== Filtering ===

Custom filters can be used to select SNPs for inclusion in the meta-analysis. This can be used, for example, to select SNPs within a specified minor-allele frequency range for analysis.

Here are some possible filters:

ADDFILTER N > 1000
ADDFILTER MAF > 0.01

Together, these two filters would only consider entries where the value in the N column is greater than 1000 and the value in the MAF column is also greater than 0.01.

Filters can be defined using the <, >, <=, >=, =, != and IN operators. The IS operator tests membership in a set. For example to restrict analysis to three interesting SNPs, use:

ADDFILTER MARKER_ID IN (rs1234,rs123456,rs123)

To remove all previously defined filters, use the command:

REMOVEFILTERS

=== Verbose Mode ===

VERBOSE ON

METAL allows for complete output of individual summary statistics for all SNPs in all input files. This can create a very large file and should be used with caution. Typically, one should create custom filters to restrict analyses to interesting SNPs of interest before using this option. This option can be useful for comparing direction of effect across many studies since METAL takes care of all the strand flipping and provides the direction of effect relative to the same allele. This is also a way to double-check that the expected data are being used appropriately by METAL.

=== Lenient Mode ===

COLUMNCOUNTING STRICT - requires expected number of columns in every row
COLUMNCOUNTING LENIENT - tries to interpret rows with fewer columns than expected

By default, METAL will skip lines in each input file that don't have the expected number of columns. This is usually a good idea because it avoids producing incorrect results when a column is missing. Sometimes (for example, when there are optional extra columns at the end of each line), the <code>COLUMNCOUNTING LENIENT</code> option can be useful.

=== Tracking Allele Frequencies ===

AVERAGEFREQ ON
MINMAXFREQ ON

METAL can optionally track the effect allele frequency across all files and report its mean, minimum and maximum. These can be quite useful to check that allele frequencies are similar across different cohorts after METAL performs all strand alignment. Large differences in allele frequencies across studies can suggest inconsistent naming of alleles across studies. METAL requires all input files to have an allele frequency column when this feature is turned on. To specify the column header for allele frequency information, use the <code>FREQLABEL</code> command.

=== Custom Variables ===

We allow users to keep cumulative counts of custom variables across input files. An example of this might be to keep track of the sample size when performing standard-error weighted meta-analysis. The name of the custom variable should be defined once, before input files are loaded. The corresponding column label in each input file can be specified using the <code>LABEL</code> command. For example, to create a custom variable labeled TotalSampleSize that tallies the total of the N column across files, one could issue the commands:

CUSTOMVARIABLE TotalSampleSize
LABEL TotalSampleSize as N

If needed, the <code>LABEL</code> command can be used multiple times to customize column headers for each input file.

=== Input File Recommendations ===

We strongly recommend that both allele labels, corresponding to the the effect allele and non-effect allele, should be provided for all SNPs. As long as both allele columns are given for each input file, METAL appropriately accounts for situations when different input files use different reference alleles. Alleles can be coded numerically (A=1,C=2,G=3,T=4) or alphabetically (A,C,G,T,a,c,g,t) and can be on either strand if not an A/T or C/G SNP. For A/T or C/G SNPs, METAL requires SNPs to be on a consistent strand in different input files for the results to be interpretable. For other SNPs, METAL can automatically identify and resolve strand inconsistencies.

P-values that are < 0.0, > 1.0 or non-numeric will be treated as missing and generate a warning.

The EFFECT column can have positive and negative values (beta values from regression, for example), or simply directions of effect relative to the reference allele, listed as “+” and “-“. An EFFECT of “+” (or any positive number) with respect to the reference allele A (or effect allele A), for example, represents a case where increasing number of copies of allele A are correlated with increasing trait values. For discrete traits, it is common to report odds ratios, which are always positive. In this case, to calculate the direction of effect, one should look at the log of the odds ratio. METAL can compute the odds ratio for you if you specify <code>EFFECT log(ODDS_RATIO_COLUMN)</code>

To perform odds-ratio based meta-analysis, select SCHEME STDERR at the beginning of the script. Then, for each file, provide the natural log of the odds ratio as the EFFECT column or another appropriate statistic (such as the corresponding regression coefficient from a logistic regression analysis).

== Example: A METAL Meta-Analysis Script ==

<pre>
#THIS SCRIPT EXECUTES AN ANALYSIS OF EIGHT STUDIES
#THE RESULTS FOR EACH STUDY ARE STORED IN FILES Inputfile1.txt THROUGH Inputfile8.txt

#LOAD THE FIRST EIGHT INPUT FILES

# UNCOMMENT THE NEXT LINE TO ENABLE GenomicControl CORRECTION
# GENOMICCONTROL ON

# === DESCRIBE AND PROCESS THE FIRST INPUT FILE ===
MARKER SNP
ALLELE REF_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE PVALUE
WEIGHT N
PROCESS inputfile1.txt

# === THE SECOND INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile2.txt

# === DESCRIBE AND PROCESS THE THIRD INPUT FILE ===
MARKER SNP
ALLELE A_REF OTHER_ALLELE
EFFECT BETA
PVALUE pvalue
WEIGHT N
PROCESS inputfile3.txt

# === DESCRIBE AND PROCESS THE FOURTH INPUT FILE ===
MARKER MARKERNAME
ALLELE EFFECTALLELE NON_EFFECT_ALLELE
EFFECT EFFECT1
PVALUE PVALUE
WEIGHT NONMISS
PROCESS inputfile4.txt

# === CARRY OUT AN INTERIM ANALYSIS OF THE FIRST FOUR FILES ===
OUTFILE METAANALYSIS_inputfile1to4_ .tbl
ANALYZE

# LOAD THE NEXT FOUR INPUT FILES

# === DESCRIBE AND PROCESS THE FIFTH INPUT FILE ===
MARKER rsid
ALLELE EFFECT_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE Add_p
WEIGHT total_N
SEPARATOR COMMAS
PROCESS inputfile5.txt

# === THE SIXTH INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile6.txt

# === DESCRIBE AND PROCESS THE SEVENTH INPUT FILE ===
ALLELE ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE PVALUE
WEIGHT N
SEPARATOR WHITESPACE
PROCESS inputfile7.txt

# === DESCRIBE AND PROCESS THE NINTH INPUT FILE ===
ALLELE BETA_ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE P_VAL
WEIGHT N
PROCESS inputfile8.txt

#for the final meta-analysis of all 8 samples only output results if the
#combined weight is greater than 10000 people

OUTFILE METAANALYSIS_inputfile1-8_ .tbl
MINWEIGHT 10000
ANALYZE

QUIT
</pre>

METAL Documentation

2010-03-29T02:03:01Z

Cristen: /* Input File Separators */

== History ==

METAL was developed by Goncalo Abecasis, Yun Li and Cristen Willer. The first version was developed in 2007 and was used for the analyses presented in [http://www.sph.umich.edu/csg/abecasis/publications/18193045.html Sanna et al (2008)] and [http://www.sph.umich.edu/csg/abecasis/publications/18193043.html Willer et al (2008)]. Since then, it has become quite a popular tool for the analysis of genomewide association scans.

== Brief Description ==

METAL is a tool for meta-analysis genomewide association scans. METAL can combine either (a) test statistics and standard errors or (b) p-values across studies (taking sample size and direction of effect into account). METAL analysis is a convenient alternative to a direct analysis of merged data from multiple studies. It is especially appropriate when data from the individual studies cannot be analyzed together because of differences in ethnicity, phenotype distribution, gender or constraints in sharing of individual level data imposed. Meta-analysis results in little or no loss of efficiency compared to analysis of a combined dataset including data from all individual studies.

== Approach ==

One of the most common questions we receive is about the approach used by METAL to carry out a meta-analysis using p-values as input. The process is actually quite simple! First, for each marker, a reference allele is selected and a z-statistic characterizing the evidence for association is calculated. The z-statistic summarizes the magnitude and the direction of effect relative to the reference allele and all studies are aligned to the same reference allele. Next, an overall z-statistic and p-value are then calculated from a weighted sum of the individual statistics. Weights are proportional to the square-root of the number of individuals examined in each sample and selected such that the squared weights sum to 1.0. For samples that contain related individuals, a smaller ‘effective’ sample size may be used, but simulations suggest that modest changes in the effective sample size have very little impact on the final p-value.

== Basic Usage Instructions ==

METAL is a command line tool. It is typically run from a Linux, Unix or DOS prompt by invoking the command <code>metal</code>. Analyses can be run interactively or a simple script can be provided as input. Interactive analyses are usually convenient when learning how to use METAL, whereas the scripting approach is preferred for production use (as it allows analyses to be conveniently repeated). An example METAL script is included at the bottom of this page.

METAL has lots of options and here we have listed some common ones that, hopefully, will help you get started.

=== Help! ===

Issuing the <code>HELP</code> command lists all available commands and the current settings for each option. The list of all available commands is also available in the [[METAL Command Reference]].

=== Input File Separators ===

METAL expects that each set of results will be summarized in a table. This table must be stored in a text file but otherwise METAL is quite flexible about details such as column separators, column headers and the like. This does mean that an essential bit of information needed before any meta-analysis is a description of each input file.

The first thing you should specify is the column separator. By default, METAL assumes columns are separated by whitespace (which consists of any combination of space and tab characters). You can also specify:

SEPARATOR WHITESPACE - the default
SEPARATOR COMMA - for comma delimited files that are popular in some platforms
SEPARATOR TAB - columns separated by a single tab, so that consecutive tabs indicate an empty column

=== Input File Columns ===

Each input file should include the following information:

* A column with marker name, which should be consistent across studies
* A column indicating the tested allele
* A column indicating the other allele

If you are carrying out a sample size weighted analysis (based on p-values), you will also need:

* A column indicating the direction of effect for the tested allele
* A column indicating the corresponding p-value
* An optional column indicating the sample size (if the sample size varies by marker)

If you are carrying out a meta-analysis based on standard errors, you will need:

* A column indicating the estimated effect size for each marker
* A column indicating the standard error of this effect size estimate

The header for each of these columns must be specified so that METAL knows how to interpret the data. As noted below, additional columns including allele frequency information, strand information, and others can also be present.

Here is a typical set of commands that would describe a table where the headers SNP, RefAllele, NonRefAllele, Pvalue and Beta correspond to the MARKER, ALLELE 1 and 2, PVALUE and EFFECT columns:

MARKERLABEL SNP
ALLELELABELS RefAllele NonRefAllele
PVALUELABEL P-value
EFFECTLABEL Effect

These can be abbreviated as:

MARKER SNP
ALLELE RefAllele NonRefAllele
PVALUE P-value
EFFECT Effect

=== Specifying Weights in P-value Based Analysis ===

The weight for each MARKER can be stored in a column in the table (specified with the <code>WEIGHTLABEL</code> or <code>WEIGHT</code> commands) or can be fixed for each file (in which case the fixed weight can be set with the <code>DEFAULTWEIGHT</code> command).

=== Reading Each Input File ===

Once all appropriate headers have been specified, issuing the <code>PROCESS</code> command will read an input file and update summary statistics to take the results it contains into account. Thus:

PROCESS study1-results.tbl

=== Performing the Final Analysis ===

Once all input files have been processed, simply issue the <code>ANALYZE</code> command to execute a meta-analysis. If you'd like to execute interim analysis that include only a subset of the studies, issue the ANALYZE command after the corresponding input files have been processed.

To allow for heterogeneity, use the <code>ANALYZE HETEROGENEITY</code> command. This command will take a little longer to run, because it requires each input file to be examined twice. The METAL heterogeneity analysis requires a second pass of analysis to decide whether observed effect sizes (or test statistics) are homogeneous across samples. The resulting heterogeneity statistic has n-1 degrees of freedom for n samples.

METAL does not require that all input files report a result for every marker. Any available data is used. To restrict the output to only markers that have at least a specific number of individuals analysed (or weight), use a command like the following:

MINWEIGHT 10000

For example to restrict the output to show only Markers with at least 10,000 individuals.

== Additional Analysis Options ==

=== Selecting an Analysis Scheme ===

SCHEME SAMPLESIZE - default approach, uses p-value and direction of effect, weighted according to sample size
SCHEME STDERR - classical approach, uses effect size estimates and standard errors

By default, METAL combines p-values across studies taking into account a study specific weight (typically, the sample size) and direction of effect. This behavior can be requested explicitly with the <code>SCHEME SAMPLESIZE</code> command. An alternative can be requested with the <code>SCHEME STDERR</code> command and weights effect size estimates using the inverse of the corresponding standard errors. While standard error based weights are more common in the biostatistical literature, if you decide to use this approach, it is very important to ensure that effect size estimates (''beta'' coefficients) and standard errors use the same units in all studies (i.e. make sure that the exact same trait was examined in each study and that the same transformations were applied). Inconsistent use of measurement units across studies is the most common cause of discrepancies between these two analysis strategies.

=== Genomic Control Correction ===

GENOMICCONTROL OFF - the default, no adjustment to test statistics
GENOMICCONTROL ON - automatically correct test statistics to account for small amounts of population stratification or unaccounted for relatedness
GENOMICCONTROL [value] - correct test statistics using the specified inflation factor

METAL has the ability to apply a genomic control correction to all input files. METAL will estimate the inflation of the test statistic by comparing the median test statistic to that expected by chance, and then apply the genomic control correction to the p-values (for SAMPLESIZE weighted meta-analysis) or the standard error (for STDERR weighted meta-analysis). This should only be applied to files with whole genome data (i.e. should not be used for settings where results are only available for a candidate locus or a small number of SNPs selected for follow-up of GWAS results). Genomic control settings can be customized for each input file. We recommend applying genomic control correction to all input files that include genomewide data and, in addition, to the meta-analysis results. To apply genomic control to the meta-analysis results, just perform an initial meta-analysis and then load the initial set of results into METAL to get final, genomic control adjusted results.

=== Strand Information ===

USESTRAND ON
STRANDLABEL StrandColumnHeading

Input files can contain a column that indicates which strand the alleles are coded on (given as +/-). If this column is present, you should issue the <code>USESTRAND ON</code> command and specify an appropriate header with the <code>STRANDLABEL</code> command. If USESTRAND is off, the strand is assumed to be “+” for all SNPs, although obvious strand problems are identified by METAL and appropriately handled (for example, when one study provides A/G alleles and a different study provides C/T alleles).

=== Filtering ===

Custom filters can be used to select SNPs for inclusion in the meta-analysis. This can be used, for example, to select SNPs within a specified minor-allele frequency range for analysis.

Here are some possible filters:

ADDFILTER N > 1000
ADDFILTER MAF > 0.01

Together, these two filters would only consider entries where the value in the N column is greater than 1000 and the value in the MAF column is also greater than 0.01.

Filters can be defined using the <, >, <=, >=, =, != and IN operators. The IS operator tests membership in a set. For example to restrict analysis to three interesting SNPs, use:

ADDFILTER MARKER_ID IN (rs1234,rs123456,rs123)

To remove all previously defined filters, use the command:

REMOVEFILTERS

=== Verbose Mode ===

VERBOSE ON

METAL allows for complete output of individual summary statistics for all SNPs in all input files. This can create a very large file and should be used with caution. Typically, one should create custom filters to restrict analyses to interesting SNPs of interest before using this option. This option can be useful for comparing direction of effect across many studies since METAL takes care of all the strand flipping and provides the direction of effect relative to the same allele. This is also a way to double-check that the expected data are being used appropriately by METAL.

=== Lenient Mode ===

COLUMNCOUNTING STRICT - requires expected number of columns in every row
COLUMNCOUNTING LENIENT - tries to interpret rows with fewer columns than expected

By default, METAL will skip lines in each input file that don't have the expected number of columns. This is usually a good idea because it avoids producing incorrect results when a column is missing. Sometimes (for example, when there are optional extra columns at the end of each line), the <code>COLUMNCOUNTING LENIENT</code> option can be useful.

=== Tracking Allele Frequencies ===

AVERAGEFREQ ON
MINMAXFREQ ON

METAL can optionally track the effect allele frequency across all files and report its mean, minimum and maximum. These can be quite useful to check that allele frequencies are similar across different cohorts after METAL performs all strand alignment. Large differences in allele frequencies across studies can suggest inconsistent naming of alleles across studies. METAL requires all input files to have an allele frequency column when this feature is turned on. To specify the column header for allele frequency information, use the <code>FREQLABEL</code> command.

=== Custom Variables ===

We allow users to keep cumulative counts of custom variables across input files. An example of this might be to keep track of the sample size when performing standard-error weighted meta-analysis. The name of the custom variable should be defined once, before input files are loaded. The corresponding column label in each input file can be specified using the <code>LABEL</code> command. For example, to create a custom variable labeled TotalSampleSize that tallies the total of the N column across files, one could issue the commands:

CUSTOMVARIABLE TotalSampleSize
LABEL TotalSampleSize as N

If needed, the <code>LABEL</code> command can be used multiple times to customize column headers for each input file.

=== Input File Recommendations ===

We strongly recommend that both allele labels, corresponding to the the effect allele and non-effect allele, should be provided for all SNPs. As long as both allele columns are given for each input file, METAL appropriately accounts for situations when different input files use different reference alleles. Alleles can be coded numerically (A=1,C=2,G=3,T=4) or alphabetically (A,C,G,T,a,c,g,t) and can be on either strand if not an A/T or C/G SNP. For A/T or C/G SNPs, METAL requires SNPs to be on a consistent strand in different input files for the results to be interpretable. For other SNPs, METAL can automatically identify and resolve strand inconsistencies.

P-values that are < 0.0, > 1.0 or non-numeric will be treated as missing and generate a warning.

The EFFECT column can have positive and negative values (beta values from regression, for example), or simply directions of effect relative to the reference allele, listed as “+” and “-“. An EFFECT of “+” (or any positive number) with respect to the reference allele A (or effect allele A), for example, represents a case where increasing number of copies of allele A are correlated with increasing trait values. For discrete traits, it is common to report odds ratios, which are always positive. In this case, to calculate the direction of effect, one should look at the log of the odds ratio. METAL can compute the odds ratio for you if you specify <code>EFFECT log(ODDS_RATIO_COLUMN)</code>

To perform odds-ratio based meta-analysis, select SCHEME STDERR at the beginning of the script. Then, for each file, provide the natural log of the odds ratio as the EFFECT column or another appropriate statistic (such as the corresponding regression coefficient from a logistic regression analysis).

== Example: A METAL Meta-Analysis Script ==

<pre>
#THIS SCRIPT EXECUTES AN ANALYSIS OF EIGHT STUDIES
#THE RESULTS FOR EACH STUDY ARE STORED IN FILES Inputfile1.txt THROUGH Inputfile8.txt

#LOAD THE FIRST EIGHT INPUT FILES

# UNCOMMENT THE NEXT LINE TO ENABLE GenomicControl CORRECTION
# GENOMICCONTROL ON

# === DESCRIBE AND PROCESS THE FIRST INPUT FILE ===
MARKER SNP
ALLELE REF_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE PVALUE
WEIGHT N
PROCESS inputfile1.txt

# === THE SECOND INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile2.txt

# === DESCRIBE AND PROCESS THE THIRD INPUT FILE ===
MARKER SNP
ALLELE A_REF OTHER_ALLELE
EFFECT BETA
PVALUE pvalue
WEIGHT N
PROCESS inputfile3.txt

# === DESCRIBE AND PROCESS THE FOURTH INPUT FILE ===
MARKER MARKERNAME
ALLELE EFFECTALLELE NON_EFFECT_ALLELE
EFFECT EFFECT1
PVALUE PVALUE
WEIGHT NONMISS
PROCESS inputfile4.txt

# === CARRY OUT AN INTERIM ANALYSIS OF THE FIRST FOUR FILES ===
OUTFILE METAANALYSIS_inputfile1to4_ .tbl
ANALYZE

# LOAD THE NEXT FOUR INPUT FILES

# === DESCRIBE AND PROCESS THE FIFTH INPUT FILE ===
MARKER rsid
ALLELE EFFECT_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE Add_p
WEIGHT total_N
SEPARATOR COMMAS
PROCESS inputfile5.txt

# === THE SIXTH INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile6.txt

# === DESCRIBE AND PROCESS THE SEVENTH INPUT FILE ===
ALLELE ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE PVALUE
WEIGHT N
SEPARATOR WHITESPACE
PROCESS inputfile7.txt

# === DESCRIBE AND PROCESS THE NINTH INPUT FILE ===
ALLELE BETA_ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE P_VAL
WEIGHT N
PROCESS inputfile8.txt

#for the final meta-analysis of all 8 samples only output results if the
#combined weight is greater than 10000 people

OUTFILE METAANALYSIS_inputfile1-8_ .tbl
MINWEIGHT 10000
ANALYZE

QUIT
</pre>

METAL Documentation

2010-03-29T02:02:18Z

Cristen: /* Approach */

== History ==

METAL was developed by Goncalo Abecasis, Yun Li and Cristen Willer. The first version was developed in 2007 and was used for the analyses presented in [http://www.sph.umich.edu/csg/abecasis/publications/18193045.html Sanna et al (2008)] and [http://www.sph.umich.edu/csg/abecasis/publications/18193043.html Willer et al (2008)]. Since then, it has become quite a popular tool for the analysis of genomewide association scans.

== Brief Description ==

METAL is a tool for meta-analysis genomewide association scans. METAL can combine either (a) test statistics and standard errors or (b) p-values across studies (taking sample size and direction of effect into account). METAL analysis is a convenient alternative to a direct analysis of merged data from multiple studies. It is especially appropriate when data from the individual studies cannot be analyzed together because of differences in ethnicity, phenotype distribution, gender or constraints in sharing of individual level data imposed. Meta-analysis results in little or no loss of efficiency compared to analysis of a combined dataset including data from all individual studies.

== Approach ==

One of the most common questions we receive is about the approach used by METAL to carry out a meta-analysis using p-values as input. The process is actually quite simple! First, for each marker, a reference allele is selected and a z-statistic characterizing the evidence for association is calculated. The z-statistic summarizes the magnitude and the direction of effect relative to the reference allele and all studies are aligned to the same reference allele. Next, an overall z-statistic and p-value are then calculated from a weighted sum of the individual statistics. Weights are proportional to the square-root of the number of individuals examined in each sample and selected such that the squared weights sum to 1.0. For samples that contain related individuals, a smaller ‘effective’ sample size may be used, but simulations suggest that modest changes in the effective sample size have very little impact on the final p-value.

== Basic Usage Instructions ==

METAL is a command line tool. It is typically run from a Linux, Unix or DOS prompt by invoking the command <code>metal</code>. Analyses can be run interactively or a simple script can be provided as input. Interactive analyses are usually convenient when learning how to use METAL, whereas the scripting approach is preferred for production use (as it allows analyses to be conveniently repeated). An example METAL script is included at the bottom of this page.

METAL has lots of options and here we have listed some common ones that, hopefully, will help you get started.

=== Help! ===

Issuing the <code>HELP</code> command lists all available commands and the current settings for each option. The list of all available commands is also available in the [[METAL Command Reference]].

=== Input File Separators ===

METAL expects that each set of results will be summarized in a table. This table must be stored in a text file but otherwise METAL is quite flexible about details such as column separators, column headers and the like. This does mean that an essential bit of information needed before any meta-analysis is a description of each input file.

The first thing you should specify is the column separator. By default, METAL assumes columns are separated by each other by whitespace (which consists of any combination of space and tab characters). You can also specify:

SEPARATOR WHITESPACE - the default
SEPARATOR COMMA - for comma delimited files that are popular in some platforms
SEPARATOR TAB - columns separated by a single tab, so that consecutive tabs indicate an empty column

=== Input File Columns ===

Each input file should include the following information:

* A column with marker name, which should be consistent across studies
* A column indicating the tested allele
* A column indicating the other allele

If you are carrying out a sample size weighted analysis (based on p-values), you will also need:

* A column indicating the direction of effect for the tested allele
* A column indicating the corresponding p-value
* An optional column indicating the sample size (if the sample size varies by marker)

If you are carrying out a meta-analysis based on standard errors, you will need:

* A column indicating the estimated effect size for each marker
* A column indicating the standard error of this effect size estimate

The header for each of these columns must be specified so that METAL knows how to interpret the data. As noted below, additional columns including allele frequency information, strand information, and others can also be present.

Here is a typical set of commands that would describe a table where the headers SNP, RefAllele, NonRefAllele, Pvalue and Beta correspond to the MARKER, ALLELE 1 and 2, PVALUE and EFFECT columns:

MARKERLABEL SNP
ALLELELABELS RefAllele NonRefAllele
PVALUELABEL P-value
EFFECTLABEL Effect

These can be abbreviated as:

MARKER SNP
ALLELE RefAllele NonRefAllele
PVALUE P-value
EFFECT Effect

=== Specifying Weights in P-value Based Analysis ===

The weight for each MARKER can be stored in a column in the table (specified with the <code>WEIGHTLABEL</code> or <code>WEIGHT</code> commands) or can be fixed for each file (in which case the fixed weight can be set with the <code>DEFAULTWEIGHT</code> command).

=== Reading Each Input File ===

Once all appropriate headers have been specified, issuing the <code>PROCESS</code> command will read an input file and update summary statistics to take the results it contains into account. Thus:

PROCESS study1-results.tbl

=== Performing the Final Analysis ===

Once all input files have been processed, simply issue the <code>ANALYZE</code> command to execute a meta-analysis. If you'd like to execute interim analysis that include only a subset of the studies, issue the ANALYZE command after the corresponding input files have been processed.

To allow for heterogeneity, use the <code>ANALYZE HETEROGENEITY</code> command. This command will take a little longer to run, because it requires each input file to be examined twice. The METAL heterogeneity analysis requires a second pass of analysis to decide whether observed effect sizes (or test statistics) are homogeneous across samples. The resulting heterogeneity statistic has n-1 degrees of freedom for n samples.

METAL does not require that all input files report a result for every marker. Any available data is used. To restrict the output to only markers that have at least a specific number of individuals analysed (or weight), use a command like the following:

MINWEIGHT 10000

For example to restrict the output to show only Markers with at least 10,000 individuals.

== Additional Analysis Options ==

=== Selecting an Analysis Scheme ===

SCHEME SAMPLESIZE - default approach, uses p-value and direction of effect, weighted according to sample size
SCHEME STDERR - classical approach, uses effect size estimates and standard errors

By default, METAL combines p-values across studies taking into account a study specific weight (typically, the sample size) and direction of effect. This behavior can be requested explicitly with the <code>SCHEME SAMPLESIZE</code> command. An alternative can be requested with the <code>SCHEME STDERR</code> command and weights effect size estimates using the inverse of the corresponding standard errors. While standard error based weights are more common in the biostatistical literature, if you decide to use this approach, it is very important to ensure that effect size estimates (''beta'' coefficients) and standard errors use the same units in all studies (i.e. make sure that the exact same trait was examined in each study and that the same transformations were applied). Inconsistent use of measurement units across studies is the most common cause of discrepancies between these two analysis strategies.

=== Genomic Control Correction ===

GENOMICCONTROL OFF - the default, no adjustment to test statistics
GENOMICCONTROL ON - automatically correct test statistics to account for small amounts of population stratification or unaccounted for relatedness
GENOMICCONTROL [value] - correct test statistics using the specified inflation factor

METAL has the ability to apply a genomic control correction to all input files. METAL will estimate the inflation of the test statistic by comparing the median test statistic to that expected by chance, and then apply the genomic control correction to the p-values (for SAMPLESIZE weighted meta-analysis) or the standard error (for STDERR weighted meta-analysis). This should only be applied to files with whole genome data (i.e. should not be used for settings where results are only available for a candidate locus or a small number of SNPs selected for follow-up of GWAS results). Genomic control settings can be customized for each input file. We recommend applying genomic control correction to all input files that include genomewide data and, in addition, to the meta-analysis results. To apply genomic control to the meta-analysis results, just perform an initial meta-analysis and then load the initial set of results into METAL to get final, genomic control adjusted results.

=== Strand Information ===

USESTRAND ON
STRANDLABEL StrandColumnHeading

Input files can contain a column that indicates which strand the alleles are coded on (given as +/-). If this column is present, you should issue the <code>USESTRAND ON</code> command and specify an appropriate header with the <code>STRANDLABEL</code> command. If USESTRAND is off, the strand is assumed to be “+” for all SNPs, although obvious strand problems are identified by METAL and appropriately handled (for example, when one study provides A/G alleles and a different study provides C/T alleles).

=== Filtering ===

Custom filters can be used to select SNPs for inclusion in the meta-analysis. This can be used, for example, to select SNPs within a specified minor-allele frequency range for analysis.

Here are some possible filters:

ADDFILTER N > 1000
ADDFILTER MAF > 0.01

Together, these two filters would only consider entries where the value in the N column is greater than 1000 and the value in the MAF column is also greater than 0.01.

Filters can be defined using the <, >, <=, >=, =, != and IN operators. The IS operator tests membership in a set. For example to restrict analysis to three interesting SNPs, use:

ADDFILTER MARKER_ID IN (rs1234,rs123456,rs123)

To remove all previously defined filters, use the command:

REMOVEFILTERS

=== Verbose Mode ===

VERBOSE ON

METAL allows for complete output of individual summary statistics for all SNPs in all input files. This can create a very large file and should be used with caution. Typically, one should create custom filters to restrict analyses to interesting SNPs of interest before using this option. This option can be useful for comparing direction of effect across many studies since METAL takes care of all the strand flipping and provides the direction of effect relative to the same allele. This is also a way to double-check that the expected data are being used appropriately by METAL.

=== Lenient Mode ===

COLUMNCOUNTING STRICT - requires expected number of columns in every row
COLUMNCOUNTING LENIENT - tries to interpret rows with fewer columns than expected

By default, METAL will skip lines in each input file that don't have the expected number of columns. This is usually a good idea because it avoids producing incorrect results when a column is missing. Sometimes (for example, when there are optional extra columns at the end of each line), the <code>COLUMNCOUNTING LENIENT</code> option can be useful.

=== Tracking Allele Frequencies ===

AVERAGEFREQ ON
MINMAXFREQ ON

METAL can optionally track the effect allele frequency across all files and report its mean, minimum and maximum. These can be quite useful to check that allele frequencies are similar across different cohorts after METAL performs all strand alignment. Large differences in allele frequencies across studies can suggest inconsistent naming of alleles across studies. METAL requires all input files to have an allele frequency column when this feature is turned on. To specify the column header for allele frequency information, use the <code>FREQLABEL</code> command.

=== Custom Variables ===

We allow users to keep cumulative counts of custom variables across input files. An example of this might be to keep track of the sample size when performing standard-error weighted meta-analysis. The name of the custom variable should be defined once, before input files are loaded. The corresponding column label in each input file can be specified using the <code>LABEL</code> command. For example, to create a custom variable labeled TotalSampleSize that tallies the total of the N column across files, one could issue the commands:

CUSTOMVARIABLE TotalSampleSize
LABEL TotalSampleSize as N

If needed, the <code>LABEL</code> command can be used multiple times to customize column headers for each input file.

=== Input File Recommendations ===

We strongly recommend that both allele labels, corresponding to the the effect allele and non-effect allele, should be provided for all SNPs. As long as both allele columns are given for each input file, METAL appropriately accounts for situations when different input files use different reference alleles. Alleles can be coded numerically (A=1,C=2,G=3,T=4) or alphabetically (A,C,G,T,a,c,g,t) and can be on either strand if not an A/T or C/G SNP. For A/T or C/G SNPs, METAL requires SNPs to be on a consistent strand in different input files for the results to be interpretable. For other SNPs, METAL can automatically identify and resolve strand inconsistencies.

P-values that are < 0.0, > 1.0 or non-numeric will be treated as missing and generate a warning.

The EFFECT column can have positive and negative values (beta values from regression, for example), or simply directions of effect relative to the reference allele, listed as “+” and “-“. An EFFECT of “+” (or any positive number) with respect to the reference allele A (or effect allele A), for example, represents a case where increasing number of copies of allele A are correlated with increasing trait values. For discrete traits, it is common to report odds ratios, which are always positive. In this case, to calculate the direction of effect, one should look at the log of the odds ratio. METAL can compute the odds ratio for you if you specify <code>EFFECT log(ODDS_RATIO_COLUMN)</code>

To perform odds-ratio based meta-analysis, select SCHEME STDERR at the beginning of the script. Then, for each file, provide the natural log of the odds ratio as the EFFECT column or another appropriate statistic (such as the corresponding regression coefficient from a logistic regression analysis).

== Example: A METAL Meta-Analysis Script ==

<pre>
#THIS SCRIPT EXECUTES AN ANALYSIS OF EIGHT STUDIES
#THE RESULTS FOR EACH STUDY ARE STORED IN FILES Inputfile1.txt THROUGH Inputfile8.txt

#LOAD THE FIRST EIGHT INPUT FILES

# UNCOMMENT THE NEXT LINE TO ENABLE GenomicControl CORRECTION
# GENOMICCONTROL ON

# === DESCRIBE AND PROCESS THE FIRST INPUT FILE ===
MARKER SNP
ALLELE REF_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE PVALUE
WEIGHT N
PROCESS inputfile1.txt

# === THE SECOND INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile2.txt

# === DESCRIBE AND PROCESS THE THIRD INPUT FILE ===
MARKER SNP
ALLELE A_REF OTHER_ALLELE
EFFECT BETA
PVALUE pvalue
WEIGHT N
PROCESS inputfile3.txt

# === DESCRIBE AND PROCESS THE FOURTH INPUT FILE ===
MARKER MARKERNAME
ALLELE EFFECTALLELE NON_EFFECT_ALLELE
EFFECT EFFECT1
PVALUE PVALUE
WEIGHT NONMISS
PROCESS inputfile4.txt

# === CARRY OUT AN INTERIM ANALYSIS OF THE FIRST FOUR FILES ===
OUTFILE METAANALYSIS_inputfile1to4_ .tbl
ANALYZE

# LOAD THE NEXT FOUR INPUT FILES

# === DESCRIBE AND PROCESS THE FIFTH INPUT FILE ===
MARKER rsid
ALLELE EFFECT_ALLELE OTHER_ALLELE
EFFECT BETA
PVALUE Add_p
WEIGHT total_N
SEPARATOR COMMAS
PROCESS inputfile5.txt

# === THE SIXTH INPUT FILE HAS THE SAME FORMAT AND CAN BE PROCESSED IMMEDIATELY ===
PROCESS inputfile6.txt

# === DESCRIBE AND PROCESS THE SEVENTH INPUT FILE ===
ALLELE ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE PVALUE
WEIGHT N
SEPARATOR WHITESPACE
PROCESS inputfile7.txt

# === DESCRIBE AND PROCESS THE NINTH INPUT FILE ===
ALLELE BETA_ALLELE OTHER_ALLELE
MARKER SNP
EFFECT BETA
PVALUE P_VAL
WEIGHT N
PROCESS inputfile8.txt

#for the final meta-analysis of all 8 samples only output results if the
#combined weight is greater than 10000 people

OUTFILE METAANALYSIS_inputfile1-8_ .tbl
MINWEIGHT 10000
ANALYZE

QUIT
</pre>