Genome Analysis Wiki - User contributions [en]

RAREMETALWORKER

2019-11-20T17:34:13Z

Welchr: /* PED and DAT Files */

[[Category:RAREMETALWORKER]]

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

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

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

== Useful Wiki Pages ==

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

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

== Software Download and Installation ==

=== DOWNLOAD ===

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

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

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

=== How to Execute ===

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

==Method==

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

==For Binary Traits==

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

== Software Specifications ==

===INTERFACE===

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

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

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

===INPUT FILE FORMAT===

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

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

* Covariate and trait values are saved in PED file. Covariate and trait descriptions are saved in DAT file. Note that you must specify <code>--makeResiduals</code> in order to adjust the covariates out of the phenotype. See [[RAREMETALWORKER#Example_Command_Lines | Example Command Lines]] for examples and [[RAREMETALWORKER_command_reference#Trait_Options | Trait Options]] for more information.

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

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

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

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

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

=== OUTPUT===

====OUTPUT FILE NAMES====

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

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

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

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

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

====OUTPUT FILE FORMATS====

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

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

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

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

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

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

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

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

The following parameters are in effect:

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

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

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

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

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

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

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

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

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

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

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

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

== Example Command Lines ==

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

===General Usage===

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

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

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

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

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

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

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

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

=== Related individuals ===

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

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

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

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

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

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

=== Unrelated individuals ===

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

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

===Analyzing Chromosome X===

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

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

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

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

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

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

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

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

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

Talk:METAL Documentation

2019-11-13T20:41:48Z

Welchr:

The website said "The joint meta-analysis method has been implemented though a patch to METAL available from http://www.sph.umich.edu/csg/abecasis/Meta". However, I can not use SCHEME INTERACTION. I used lasted version of METAL. where I can find the patch?

Thanks

---------

Hi Cindy,

It seems as though this patch never made it into the main METAL codebase (https://github.com/statgen/METAL). From what I can gather, it was used in the following paper: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3312394/. Alisa Manning looks to be who posted it on this wiki originally, and she is the first author on the paper. You could try contacting her to see if she still has the code.

Regards,

Ryan Welch

LocusZoom Standalone

2018-05-16T17:00:39Z

Welchr: /* METAL formatted file */

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

 [[Image:LocusZoomSmall.png]]

This page contains information regarding a version of LocusZoom that may be downloaded for personal use. For more information on LocusZoom, see this [[LocusZoom|page]].

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

== Quick Start (Requirements) ==

The following software is required:

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

The following software is optional but recommended:

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

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

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

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

== Synopsis ==

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

[[Image:FADS1 small.png]]

== Download ==

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

== Installation ==

=== Step 1: Install Python ===

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

=== Step 2: Install R ===

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

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

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

==== new_fugue ====

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

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

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

You may need administrator rights to install this program.

==== PLINK ====

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

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

=== Step 5: Install tabix ===

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

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

=== Step 6: Install LocusZoom ===

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

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

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

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

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

== Sources of information ==

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

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

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

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

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

== Input ==

=== Association results file ===

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

==== METAL formatted file ====

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

 

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

 

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

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

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

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

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

==== EPACTS formatted file ====

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

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

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

To load this file, use --epacts.

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

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

==== Reading from STDIN ====

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

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

=== Region ===

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

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

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

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

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

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

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

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

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

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

'''1000G'''

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

 '''HapMap Phase II'''

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

=== Batch mode ===

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

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

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

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

 

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

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

 

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

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

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

=== User-supplied LD ===

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

 

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

 

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

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

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

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

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

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

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

You can also calculate D' from phased VCF files:

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

The default measure is "rsquared".

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

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

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

== Optional Input ==

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

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

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

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

As an example:

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

Will generate the following plot:

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

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

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

=== GWAS catalog variants ===

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

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

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

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

<pre>
Available GWAS catalogs for build hg19:

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

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

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

=== Fine-mapping credible sets ===

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

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

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

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

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

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

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

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

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

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

=== Labeling multiple SNPs ===

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

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

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

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

The file looks like:

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

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

=== Plotting BED tracks ===

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

[[File:Bed_tracks.png]]

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

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

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

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

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

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

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

== Output ==

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

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

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

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

== LocusZoom options ==

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

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

 

 

== Plotting options ==

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

New/fixed options in 1.3:

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

 

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

 

 

== Examples ==

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

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

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

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

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

=== Use HapMap YRI for LD ===

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

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

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

=== An example using plotting options ===

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

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

== Advanced configuration ==

=== Creating a custom SQLite database ===

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

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

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

==== Inserting snp_pos ====

First, create a file that looks like the following:

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

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

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

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

==== Inserting refsnp_trans ====

The refsnp_trans table looks like the following:

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

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

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

==== Inserting refFlat ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

An example of running the script:

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

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

=== Changing m2zfast.conf settings ===

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

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

=== LD caching ===

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

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

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

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

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

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

Copyright 2010 Ryan Welch, Randall Pruim

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

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

[[Category:Software]]

METAL Documentation

2017-12-22T19:52:43Z

Welchr: /* Sample Overlap Correction */

== 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). Most commonly, the weight will be the number of individuals contributing to that particular p-value.

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

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

=== Sample Overlap Correction ===

Correction for sample overlap in sample size weighted meta-analysis (developed by Sebanti Sengupta and implemented by Daniel Taliun).

First, METAL estimates the number of individuals that are common among two or more studies based on Z-statistics from each study. Then, METAL adjusts for sample overlap when calculating overall Z-statistics by correcting the weights with the estimated number of individuals in common.

To enable correction for sample overlap in your sample size weighted meta-analysis, use OVERLAP ON command (valid only with SCHEME SAMPLESIZE). By default, METAL uses Z-statistics <1 for esimating the number of individuals that are common among studies. To change this threshold, use ZCUTOFF [number] command.

More information on the method can be found in:

* [[media:METAL_sample_overlap_2017-11-15.pptx|Method overview and results]]
* [[media:METAL_sample_overlap_method_2017-11-15.pdf|Full method description]] (current draft, manuscript est. 2018)

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

File:METAL sample overlap method 2017-11-15.pdf

2017-12-22T19:48:28Z

Welchr:

METAL Documentation

2017-12-22T19:40:46Z

Welchr: /* Additional Analysis Options */

== 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). Most commonly, the weight will be the number of individuals contributing to that particular p-value.

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

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

=== Sample Overlap Correction ===

Correction for sample overlap in sample size weighted meta-analysis (developed by Sebanti Sengupta and implemented by Daniel Taliun).

First, METAL estimates the number of individuals that are common among two or more studies based on Z-statistics from each study. Then, METAL adjusts for sample overlap when calculating overall Z-statistics by correcting the weights with the estimated number of individuals in common.

To enable correction for sample overlap in your sample size weighted meta-analysis, use OVERLAP ON command (valid only with SCHEME SAMPLESIZE). By default, METAL uses Z-statistics <1 for esimating the number of individuals that are common among studies. To change this threshold, use ZCUTOFF [number] command.

Details on the method can be found in [[media:METAL_sample_overlap_2017-11-15.pptx|these slides]], and eventually as a manuscript (est. 2018).

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

File:METAL sample overlap 2017-11-15.pptx

2017-12-22T19:35:20Z

Welchr:

CSG Tech Talks

2017-07-26T17:14:56Z

Welchr: /* Upcoming Schedule */

The Center for Statistical Genetics (CSG) is hosting a series of talks to help people working in the field of statistical genetics, or applied statistics in general, become more knowledgeable about the technical tools available to them.

We will be hosting meetings during the summer on alternating Wednesdays at 2pm at SPH2 (in room 1152 unless otherwise noted).

To be notified of upcoming presentations, you may add your e-mail address to the csg-tech-talks@umich.edu mailing list on [https://mcommunity.umich.edu MCommunity]

To suggest topic or volunteer to present, please email Matthew at mflick@umich.edu

== Upcoming Schedule ==

* July 26, 2pm - SPH2 M1152 - '''Make and Snakemake''' by Matthew Flickinger, Ryan Welch
** [https://github.com/welchr/csg-snakemake/raw/master/materials/tech_talk_snakemake_20170726.pptx Slides]
** [https://github.com/welchr/csg-snakemake Github]

== Presentation Slides ==

* [[Media:Dplyr_tidyverse.pdf| dplyr and the tidyverse by Matthew Flickinger (July 12, 2017)]] -[https://gist.githubusercontent.com/MrFlick/4297321683f9b3d483a4303e5acd586e/raw/716e2668d483d21e402ddb33dd618168ec697fe0/dplyr_tidyverse.Rmd Markdown Document] - [[Media:Dplyr_tidyverse_md.pdf| Rendered Markdown]]
* [[Media:Cplusplus11-features-and-tricks.pdf| C++11 Features and Tricks by Daniel Taliun (Jul 28, 2016)]]
* [[Media:ReproducibleResearch-TechTalk.pdf| Reproducible Research by Matthew Flickinger (Jul 14, 2016)]]
* [[Media:Julia_presentation.pdf| The Julia Manifesto by Jonathon LeFaive (Jun 30, 2016)]]
* [https://github.com/welchr/csg-jupyter-tutorial Quick introduction to the jupyter notebook by Ryan Welch (Jun 02, 2016)]
* [[Media:TechTalk-RTroubleshooting.pdf| What R You Doing? (Answering Your Own R Questions) by Matthew Flickinger (May 19, 2016)]]
* [[Media:Brooksisms.ppt| Brookisms And Other Nuggets of Programming Wisdom by Chris Clark (May 12, 2016)]]

CSG Tech Talks

2017-07-26T17:12:59Z

Welchr: /* Upcoming Schedule */

The Center for Statistical Genetics (CSG) is hosting a series of talks to help people working in the field of statistical genetics, or applied statistics in general, become more knowledgeable about the technical tools available to them.

We will be hosting meetings during the summer on alternating Wednesdays at 2pm at SPH2 (in room 1152 unless otherwise noted).

To be notified of upcoming presentations, you may add your e-mail address to the csg-tech-talks@umich.edu mailing list on [https://mcommunity.umich.edu MCommunity]

To suggest topic or volunteer to present, please email Matthew at mflick@umich.edu

== Upcoming Schedule ==

* July 26, 2pm - SPH2 M1152 - '''Make and Snakemake''' by Matthew Flickinger, Ryan Welch
** Slides
** Github

== Presentation Slides ==

* [[Media:Dplyr_tidyverse.pdf| dplyr and the tidyverse by Matthew Flickinger (July 12, 2017)]] -[https://gist.githubusercontent.com/MrFlick/4297321683f9b3d483a4303e5acd586e/raw/716e2668d483d21e402ddb33dd618168ec697fe0/dplyr_tidyverse.Rmd Markdown Document] - [[Media:Dplyr_tidyverse_md.pdf| Rendered Markdown]]
* [[Media:Cplusplus11-features-and-tricks.pdf| C++11 Features and Tricks by Daniel Taliun (Jul 28, 2016)]]
* [[Media:ReproducibleResearch-TechTalk.pdf| Reproducible Research by Matthew Flickinger (Jul 14, 2016)]]
* [[Media:Julia_presentation.pdf| The Julia Manifesto by Jonathon LeFaive (Jun 30, 2016)]]
* [https://github.com/welchr/csg-jupyter-tutorial Quick introduction to the jupyter notebook by Ryan Welch (Jun 02, 2016)]
* [[Media:TechTalk-RTroubleshooting.pdf| What R You Doing? (Answering Your Own R Questions) by Matthew Flickinger (May 19, 2016)]]
* [[Media:Brooksisms.ppt| Brookisms And Other Nuggets of Programming Wisdom by Chris Clark (May 12, 2016)]]

LocusZoom Standalone

2017-05-31T18:28:16Z

Welchr:

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

 [[Image:LocusZoomSmall.png]]

This page contains information regarding a version of LocusZoom that may be downloaded for personal use. For more information on LocusZoom, see this [[LocusZoom|page]].

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

== Quick Start (Requirements) ==

The following software is required:

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

The following software is optional but recommended:

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

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

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

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

== Synopsis ==

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

[[Image:FADS1 small.png]]

== Download ==

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

== Installation ==

=== Step 1: Install Python ===

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

=== Step 2: Install R ===

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

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

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

==== new_fugue ====

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

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

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

You may need administrator rights to install this program.

==== PLINK ====

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

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

=== Step 5: Install tabix ===

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

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

=== Step 6: Install LocusZoom ===

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

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

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

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

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

== Sources of information ==

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

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

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

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

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

== Input ==

=== Association results file ===

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

==== METAL formatted file ====

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

 

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

 

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

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

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

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

==== EPACTS formatted file ====

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

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

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

To load this file, use --epacts.

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

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

==== Reading from STDIN ====

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

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

=== Region ===

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

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

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

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

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

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

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

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

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

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

'''1000G'''

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

 '''HapMap Phase II'''

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

=== Batch mode ===

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

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

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

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

 

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

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

 

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

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

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

=== User-supplied LD ===

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

 

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

 

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

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

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

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

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

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

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

You can also calculate D' from phased VCF files:

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

The default measure is "rsquared".

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

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

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

== Optional Input ==

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

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

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

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

As an example:

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

Will generate the following plot:

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

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

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

=== GWAS catalog variants ===

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

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

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

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

<pre>
Available GWAS catalogs for build hg19:

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

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

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

=== Fine-mapping credible sets ===

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

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

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

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

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

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

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

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

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

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

=== Labeling multiple SNPs ===

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

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

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

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

The file looks like:

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

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

=== Plotting BED tracks ===

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

[[File:Bed_tracks.png]]

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

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

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

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

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

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

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

== Output ==

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

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

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

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

== LocusZoom options ==

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

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

 

 

== Plotting options ==

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

New/fixed options in 1.3:

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

 

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

 

 

== Examples ==

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

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

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

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

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

=== Use HapMap YRI for LD ===

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

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

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

=== An example using plotting options ===

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

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

== Advanced configuration ==

=== Creating a custom SQLite database ===

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

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

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

==== Inserting snp_pos ====

First, create a file that looks like the following:

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

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

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

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

==== Inserting refsnp_trans ====

The refsnp_trans table looks like the following:

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

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

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

==== Inserting refFlat ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

An example of running the script:

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

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

=== Changing m2zfast.conf settings ===

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

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

=== LD caching ===

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

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

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

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

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

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

Copyright 2010 Ryan Welch, Randall Pruim

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

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

[[Category:Software]]

CSG Tech Talks

2016-06-02T20:34:40Z

Welchr:

LocusZoom Standalone

2016-05-02T21:04:05Z

Welchr: /* Plotting BED tracks */

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

 [[Image:LocusZoomSmall.png]]

This page contains information regarding a version of LocusZoom that may be downloaded for personal use. For more information on LocusZoom, see this [[LocusZoom|page]].

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

== Quick Start (Requirements) ==

The following software is required:

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

The following software is optional but recommended:

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

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

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

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

== Synopsis ==

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

[[Image:FADS1 small.png]]

== Download ==

See our [https://statgen.sph.umich.edu/locuszoom/download/ download] page for links to the latest as well as previous releases.

== Changes in Version 1.3 ==

New features:

* Database and GWAS catalog files updated for hg19
* [[#Plotting BED tracks| Adding BED tracks]]
* [[#Updating the existing locuszoom database(s)| Update locuszoom's database without waiting for a release]]
* [[#Specify gene table (refFlat, GENCODE, etc.) | Use different gene information tables + GENCODE support]]
* [[#EPACTS formatted file|Support for tabix indexed EPACTS files]]
* [[#Reading from STDIN| Read data from STDIN]]
* [[#Plotting options| New plotting options for color, significance lines]]
* [[#Supply VCF files for calculating LD|Provide multiple chromosome separated VCF files for calculating LD]]

The full changelog is available on the [https://statgen.sph.umich.edu/locuszoom/download/ download] site.

== Changes in Version 1.2 ==

A number of new features have been added for this version. See the following sections for more info:

* [[#EPACTS formatted file|Loading EPACTS results]]
* [[#Plotting LD with additional reference SNPs|Plotting LD with additional reference SNPs]]
* [[#Labeling multiple SNPs|Labeling multiple SNPs]]
* [[#Fine-mapping credible sets|Fine-mapping credible sets]]
* [[#GWAS catalog variants|GWAS catalog variants]]
* [[#Supply VCF files for calculating LD|Supply VCF files for calculating LD]]

The full changelog is available on the [https://statgen.sph.umich.edu/locuszoom/download/ download] site.

== Installation ==

=== Step 1: Install Python ===

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

=== Step 2: Install R ===

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

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

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

==== new_fugue ====

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

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

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

You may need administrator rights to install this program.

==== PLINK ====

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

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

=== Step 5: Install tabix ===

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

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

=== Step 6: Install LocusZoom ===

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

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

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

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

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

== Sources of information ==

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

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

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

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

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

== Input ==

=== Association results file ===

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

==== METAL formatted file ====

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

 

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

 

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

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

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

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

==== EPACTS formatted file ====

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

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

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

To load this file, use --epacts.

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

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

==== Reading from STDIN ====

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

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

=== Region ===

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

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

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

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

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

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

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

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

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

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

'''1000G'''

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

 '''HapMap Phase II'''

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

=== Batch mode ===

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

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

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

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

 

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

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

 

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

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

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

=== User-supplied LD ===

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

 

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

 

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

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

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

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

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

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

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

You can also calculate D' from phased VCF files:

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

The default measure is "rsquared".

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

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

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

== Optional Input ==

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

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

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

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

As an example:

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

Will generate the following plot:

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

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

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

=== GWAS catalog variants ===

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

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

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

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

<pre>
Available GWAS catalogs for build hg19:

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

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

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

=== Fine-mapping credible sets ===

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

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

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

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

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

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

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

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

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

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

=== Labeling multiple SNPs ===

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

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

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

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

The file looks like:

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

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

=== Plotting BED tracks ===

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

[[File:Bed_tracks.png]]

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

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

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

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

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

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

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

== Output ==

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

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

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

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

== LocusZoom options ==

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

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

 

 

== Plotting options ==

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

New/fixed options in 1.3:

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

 

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

 

 

== Examples ==

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

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

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

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

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

=== Use HapMap YRI for LD ===

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

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

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

=== An example using plotting options ===

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

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

== Advanced configuration ==

=== Creating a custom SQLite database ===

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

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

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

==== Inserting snp_pos ====

First, create a file that looks like the following:

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

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

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

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

==== Inserting refsnp_trans ====

The refsnp_trans table looks like the following:

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

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

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

==== Inserting refFlat ====

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

An example of running the script:

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

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

=== Changing m2zfast.conf settings ===

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

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

=== LD caching ===

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

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

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

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

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

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

Copyright 2010 Ryan Welch, Randall Pruim

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

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

[[Category:Software]]

RAREMETALWORKER

2015-05-17T18:28:14Z

Welchr: /* LD Matrices */

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

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

If you have any questions, please contact [[Shuang Feng|'''Shuang Feng''']] sfengsph at umich dot edu or [[Goncalo_Abecasis | '''Goncalo Abecasis''']] goncalo at umich dot edu.

== Useful Wiki Pages ==

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

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

== Software Download and Installation ==

=== DOWNLOAD ===

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

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

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

=== How to Execute ===

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

==Method==

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

==For Binary Traits==

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

== Software Specifications ==

===INTERFACE===

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

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

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

===INPUT FILE FORMAT===

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

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

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

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

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

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

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

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

=== OUTPUT===

====OUTPUT FILE NAMES====

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

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

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

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

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

====OUTPUT FILE FORMATS====

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

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

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

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

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

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

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

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

The following parameters are in effect:

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

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

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

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

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

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

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

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

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

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

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

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

== Example Command Lines ==

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

===General Usage===

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

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

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

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

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

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

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

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

=== Related individuals ===

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

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

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

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

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

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

=== Unrelated individuals ===

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

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

===Analyzing Chromosome X===

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

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

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

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

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

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

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

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

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

Welchr:

A script to ligate together chunks created by minimac:

[http://csg.sph.umich.edu/boehnke/ligate_minimac/ligate_minimac.py ligate_minimac.py]

Usage instructions (can also run the script without arguments, or with -h):

<pre>
Usage: ligate_minimac.py -o output_prefix <info files>

This script assumes the following:

1) You are attempting to merge only minimac chunks from the same chromosome

2) Dosage files and info files end in .dose (or .dose.gz) and .info (or .info.gz)

i.e. chr9.1.10000.info.gz and chr9.1.10000.dose.gz

3) Markers within info files are sorted by genomic position

4) Minimac chunks are disjoint, that is, their markers do not overlap

You must also have the Unix tools join, cut, gzip/gunzip, tail, sort, and cut.
Additionally, the bash shell must be present on your system; you do not need to
be inside a bash shell to run the script, however.

The script will not work under Windows.

Only testing has been done with Python 2.7. Earlier versions of python should
work, but 2.6+ is probably best.

This script makes heavy use of multiple concurrent processes piped together.
Therefore, you should likely only run 1 job at a time on the same machine.

Example:

./ligate_minimac.py -o my_merged_results chr9*info.gz

Options:
-h, --help show this help message and exit
-o OUT, --out=OUT Output file prefix (files OUT.dose.gz and OUT.info.gz
will be created)

</pre>

Contact [mailto:welchr@umich.edu welchr@umich.edu] for questions/issues.

Ligate Minimac

2013-09-10T19:04:57Z

Welchr:

2013-05-09T18:07:19Z

Welchr: /* Labeling multiple SNPs */

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

 [[Image:LocusZoomSmall.png]]

This page contains information regarding a version of LocusZoom that may be downloaded for personal use. For more information on LocusZoom, see this [[LocusZoom|page]].

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

== Quick Start (Requirements) ==

The following software is required:

*[http://www.python.org/download/ Python 2.6] (do '''not''' download the 3.0 branch!)
*[http://www.r-project.org/ R 2.10+]

The following software is optional but recommended:

*[[New Fugue|new_fugue]], a program for computing LD, written by Goncalo Abecasis.
*[http://pngu.mgh.harvard.edu/~purcell/plink/ PLINK], written by Shaun Purcell.

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

For the latest stable LocusZoom package, see our [https://statgen.sph.umich.edu/locuszoom/download/ download] page. The current version is '''1.2''', released on May 10th, 2013.

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

== Synopsis ==

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

[[Image:FADS1 small.png]]

== Download ==

See our [https://statgen.sph.umich.edu/locuszoom/download/ download] page for links to the latest as well as previous releases.

== Installation ==

=== Step 1: Install Python ===

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

=== Step 2: Install R ===

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

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

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

==== new_fugue ====

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

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

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

You may need administrator rights to install this program.

==== PLINK ====

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

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

=== Step 5: Install LocusZoom ===

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

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

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

*locuszoom/
**bin/
***locuszoom (this is the locuszoom "executable")
***locuszoom.R (the R script which is used by locuszoom for creating the plots)
**conf/ (configuration file located here)
**data/
***database/ (SQLite file located here)
***hapmap/ (hapmap genotype files)
***1000G/ (1000G genotype files)
**src/ (source code for locuszoom)

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

== Sources of information ==

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

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

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

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

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

== Input ==

=== Association results file ===

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

==== METAL formatted file ====

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

 

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

 

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

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

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

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

==== EPACTS formatted file ====

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

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

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

To load this file, use --epacts.

=== Region ===

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

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

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

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

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

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

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

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

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

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

'''1000G'''

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

 '''HapMap Phase II'''

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

=== Batch mode ===

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

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

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

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

 

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

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

 

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

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

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

=== User-supplied LD ===

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

 

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

 

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

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

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

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

<syntaxhighlight lang="bash">
locuszoom --ld-vcf my_genotypes.vcf.gz ...
</syntaxhighlight>

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

'''Warning: ''' The VCF file must also have a tabix index located in the same directory. For the above example, the tabix index "my_genotypes.vcf.gz.tbi" must exist.

You can also calculate D' from phased VCF files:

<syntaxhighlight lang="bash">
locuszoom --ld-vcf my_genotypes.vcf.gz --ld-measure dprime ...
</syntaxhighlight>

The default measure is "rsquared".

== Optional Input ==

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

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

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

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

As an example:

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

Will generate the following plot:

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

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

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

=== GWAS catalog variants ===

You can add known GWAS variants to your plots with the following:

<syntaxhighlight lang="bash">
lzdev --gwas-cat whole_cat-significant-only --build hg19 ...
</syntaxhighlight>

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

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

<pre>
Available GWAS catalogs for build hg19:

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

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

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

=== Fine-mapping credible sets ===

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

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

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

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

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

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

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

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

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

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

=== Labeling multiple SNPs ===

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

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

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

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

The file looks like:

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

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

== Output ==

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

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

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

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

== LocusZoom options ==

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

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

 

 

== Plotting options ==

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

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

 

 

== Examples ==

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

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

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

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

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

=== Use HapMap YRI for LD ===

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

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

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

=== An example using plotting options ===

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

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

== Advanced configuration ==

=== Creating a SQLite database ===

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

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

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

==== Inserting snp_pos ====

First, create a file that looks like the following:

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

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

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

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

==== Inserting refsnp_trans ====

The refsnp_trans table looks like the following:

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

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

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

==== Inserting refFlat ====

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

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | geneName
! scope="col" | name
! scope="col" | chrom
! scope="col" | strand
! scope="col" | txStart
! scope="col" | txEnd
! scope="col" | cdsStart
! scope="col" | cdsEnd
! scope="col" | exonCount
! scope="col" | exonStarts
! scope="col" | exonEnds
|-
| EFCAB1
| NM_024593
| chr8
| -
| 49798505
| 49810423
| 49799853
| 49810263
| 6
| 49798505,
| 49799913,
|-
| HECTD3
| NM_024602
| chr1
| -
| 45240806
| 45249614
| 45241750
| 45249516
| 21
| 45240806,45241927,
| 45241835,45241999,
|-
| PTPN20B
| NM_001042361
| chr10
| -
| 48357047
| 48447587
| 48358657
| 48447532
| 8
| 48357047,48359393,48391320,
| 48358692,48359456,48391411,
|}

You can insert this table into the database using:
<pre> dbmeister.py --db my_database.db --refflat my_refflat_file </pre>
==== Inserting recomb_rate ====

The recomb_rate table mirrors what is available from [ftp://ftp.hapmap.org/hapmap/recombination/2008-03_rel22_B36/rates/ HapMap]. The format is:

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | chr
! scope="col" | pos
! scope="col" | recomb
! scope="col" | cm_pos
|-
| 1
| 72434
| 0.0015
| 0
|-
| 1
| 78032
| 0.0015
| 8.397e-06
|-
| 1
| 554461
| 0.0015
| 0.00072304
|-
| 1
| 554484
| 0.0015
| 0.000723075
|-
| 1
| 555296
| 0.0015
| 0.000724293
|-
| 1
| 558185
| 0.0015
| 0.000728627
|}

The table can be inserted using:
<pre> dbmeister.py --db my_database.db --recomb_rate my_recomb_rate_file </pre>
==== Inserting snp_set ====

The snp_set table simply carries a mapping of SNPs to a particular set they may belong to. The table looks like:

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | snp
! scope="col" | snp_set
|-
| rs1000
| Illu1M
|-
| rs1000
| Illu1M
|-
| rs1000
| Illu1M
|-
| rs1000000
| Illu1M
|-
| rs10000000
| Illu1M
|-
| rs10000009
| Illu1M
|}

The first column is a SNP, and the second is the name of the set it belongs to. If a SNP belongs to multiple sets, you can duplicate that SNP multiple times, one for each set.

Inserting the table into your database can be done using:
<pre> dbmeister.py --db my_database.db --snp_set my_snpset_file </pre>
==== Making LocusZoom aware of your new database ====

Now that you've created your own database file, you need to make LocusZoom aware that it exists. There are two ways to do this:

#Edit conf/m2zfast.conf, and change the <code>SQLITE_DB</code> variable
#Supply the <code>--db</code> command line option when invoking <code>bin/locuszoom</code>

Editing the m2zfast.conf file entails changing the following block of code:

<code></code>
<pre>SQLITE_DB = {
'hg18' : "data/database/locuszoom_hg18.db"
};
</pre>
Here, we've mapped build "hg18" to the default database file that comes with LocusZoom. You can mimic this format and insert your own, for example:

<code></code>
<pre>SQLITE_DB = {
'hg18' : "data/database/locuszoom_hg18.db",
'hg19' : "data/database/my_database.db"
};
</pre>
The location of your database should be either an absolute path to your file, or a path relative to the locuszoom/ root (like those seen above.)

If you wish for your database to become the default, change the <code>LATEST_BUILD</code> variable in the m2zfast.conf file to whatever you have chosen above (in our example, our new database became mapped to 'hg19'.)

=== Changing m2zfast.conf settings ===

The m2zfast.conf configuration file contains a number of settings that are typically static, but could require user configuration. The table below lists each variable, and its purpose.

{| cellspacing="0" cellpadding="5" border="1"
|-
! scope="col" | Variable
! scope="col" | Description
|-
| DEFAULT_BUILD
| Default build to use for finding SNP positions, and calculating LD. This is used to index SQLITE_DB, as well as LD_DB.
|-
| DEFAULT_POP
| Default population to use for computing LD.
|-
| DEFAULT_SOURCE
| Default source for computing LD.
|-
| NEWFUGUE_PATH
| Path to the new_fugue binary. Defaults to "new_fugue", which simply means it is searched for on your path. If new_fugue is not on your path, you will need to specify the full path here.
|-
| PLINK_PATH
| Path to the PLINK binary. Defaults to "plink", which searches for PLINK on your path. If it is not on your path, specify the full path here.
|-
| SQLITE_DB
| See [[LocusZoom Standalone#Making_LocusZoom_aware_of_your_new_database|Making LocusZoom aware of your database]].
|-
| LD_DB
| Contains a "tree" which maps a tuple of (genotype source, genotype population, genome build) to genotype files.
|}

=== LD caching ===

LocusZoom attempts to remember LD calculations that were made on previous runs of the program to avoid having to re-calculate the same regional LD for subsequent runs. The process works as follows:

*For a given reference SNP and chr/start/stop:
**If LD has not been previously computed, use new_fugue to compute LD with the reference SNP and all other SNPs in the region, and store this result to the LD cache
**Else, retrieve the previously stored LD results

The cache intelligently stores LD from separate sources (hapmap, 1000G), populations, builds, and even different versions of genotype files separately.

Upon running LocusZoom, a file called "ld_cache.db" will automatically be created in the current directory, and LD computations will be stored there. If you wish to change the location of the LD cache, use <code>--cache <file></code>. If you wish to disable LD caching, you can use <code>--cache None</code>.

''Python note:'' The ld_cache.db is actually a shelve, and you can explore its contents using:

<code></code>
<pre>import shelve
d = shelve.open("ld_cache.db")
</pre>
== License ==

Copyright 2010 Ryan Welch, Randall Pruim

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

[[Category:Software]]