LocusZoom Standalone
This page contains information regarding a version of LocusZoom that may be downloaded for personal use. For more information on LocusZoom, see this page.
Quick Start (Requirements)
The following software is required:
- Python 2.6 (do not download the 3.0 branch!)
- R 2.10+
- new_fugue, a program for computing LD, written by Goncalo Abecasis.
Latest stable LocusZoom package (including database tables):
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:
./run_example.py
This script runs the following command for you:
../bin/locuszoom --metal Kathiresan_2009_HDL.txt --refgene FADS1
A PDF plot of the FADS1 locus will be created in the directory. It should look roughly like this:
Voila, your first region plot!
Download
Download mirrors will be available shortly.
Installation
Step 1: Install Python
You will need to install Python on your system if it is not already. Head over to 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.0 one.
Step 2: Install R
R is also required for generating the plots. You can download R at www.r-project.org. Version 2.10 or greater is required.
Step 3: Install 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 here.
Once downloaded, extract the tar file using:
tar zxf /path/to/new_fugue.tar.gz
Change into the generic-new_fugue directory that is created, and run:
make install
You may need administrator rights to install this program.
Step 4: 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 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:
cd <directory where you want to place locuszoom> tar zxf /path/to/locuszoom.tgz
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)
- bin/
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:
ln -s bin/locuszoom /usr/local/bin/locuszoom
Sources of information
LocusZoom uses various sources of information for annotation, positions, and calculating LD.
For computing LD:
- HapMap genotypes for populations CEU, YRI, and JPT+CHB.
- 1000 Genomes genotypes for CEU.
For SNP, gene, and exon positions:
- dbSNP position via the UCSC Genome Browser
- Gene and exon positions via the UCSC Genome Browser. We filtered SNPs that map to more than one location or where no allele matches the reference sequence.
For annotation:
- We used various sources including RefSeq Genes (refFlat), TFBS Conserved (tfbsConsSites), and Conservation (phaseConsElements44wayPlacental), all available from the UCSC Genome Browser.
- Recombination rates from HapMap.
Input
Association results file ("metal" file)
The main input to LocusZoom is a file containing results from an association scan or meta-analysis. The file must have 2 columns: markers (SNPs), and p-values. The file should look something like this:
MarkerName | P-value |
---|---|
rs1 | 0.423 |
rs2 | 1.23e-04 |
rs3 | 9.4e-390 |
The file should be tab-delimited, though this can be changed using the --delim
option.
This file should be passed to locuszoom using the --metal
option.
If your marker and p-value column names are not "MarkerName" and "P-value", you may set them with --markercol
and --pvalcol
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 --no-transform
and LocusZoom will not transform them.
Region
You can specify the region to plot in any one of the following ways:
- A reference SNP and flanking region
--refsnp <your snp> --flank 500kb
- A reference SNP and chromosome/start/stop specification
--refsnp <your snp> --chr # --start <base position> --end <base position>
- A gene and flanking region
--refgene <your gene> --flank 250kb
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
--refgene <your gene> --chr # --start <base position> --end <base position>
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
--chr # --start <base position> --end <base position>
The SNP with the most significant p-value in this region will be used for estimating LD.
Batch mode
LocusZoom provides two fast methods for generating plots for a large number of regions:
--hits
, which parses a file for SNP names (rs#) and creates a plot for each one.--hitspec
, which reads a batch mode specification file.
To use --hits
, you need only provide any text file that has SNP names (of the rs### variety) present in the file. LocusZoom will extract SNPs from this file, regardless of formatting. Note that this file shouldn't be very large, or the parsing procedure could take a long time.
For a more thorough specification of each plot you would like to create, use --hitspec
. For this option, you must provide a text file of the following format:
Column | Description |
---|---|
snp | Can be either a SNP, or gene. |
chr | Chromosome |
start | Start position to plot. |
stop | Stop position. |
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: 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:
snp | chr | start | stop | flank | run | 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 --metal
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 --ld
option, which requires a file of the following format:
Column | 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 file should be whitespace delimited, and the header (column names shown above) must exist.
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 --plotonly
option.
Each directory (or PDF, in the case of --plotonly
) will have the date included to avoid collisions with previous plots - this behavior can be disabled using --no-date
.
You can further customize the directory/PDF names that are created by using the --prefix <name>
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.
Option | Description |
---|---|
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.) |
--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. |
--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, --stop | 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. |
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. Currently, we support "1000G" and "hapmap". |
--pop | Population to use when computing LD. Currently, when we support "CEU" for 1000G, and "CEU", "YRI", and "JPT+CHB" for hapmap. |
--snpset | Rug of SNPs to create at the top of the plot. Defaults to the Illumina 1M chip currently. |
--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).
Option (with default value) | 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
--metal your_data --refsnp rs1002227
A quick peek at a particular gene
--metal your_data --refgene CETP
Plot 500kb on either side of a SNP
--metal your_data --refsnp rs7983146 --flank 500kb
Create a plot for each SNP in a file
--metal your_data --hits file_with_snps
Use 1000 genomes, CEU for LD instead of the default (HapMap r22 CEU)
--metal your_data --refsnp rs11899863 --source 1000G
Use HapMap YRI for LD
--metal your_data --refsnp rs11899863 --pop YRI
Specify a specific region and reference SNP to plot
--metal your_data --refsnp rs1552224 --chr 11 --start 71810746 --stop 72710746
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 bin/dbmeister.py
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 www.sqlite.org.
Inserting snp_pos
First, create a file that looks like the following:
snp | chr | 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:
dbmeister.py --db my_database.db --snp_pos my_snp_pos_file
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:
rs_orig | 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:
dbmeister.py --db my_database.db --trans my_snp_translations_file
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:
geneName | name | chrom | strand | txStart | txEnd | cdsStart | cdsEnd | exonCount | exonStarts | 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:
dbmeister.py --db my_database.db --refflat my_refflat_file
Inserting recomb_rate
The recomb_rate table mirrors what is available from HapMap. The format is:
chr | pos | recomb | 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:
dbmeister.py --db my_database.db --recomb_rate my_recomb_rate_file
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:
snp | 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:
dbmeister.py --db my_database.db --snp_set my_snpset_file
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
SQLITE_DB
variable - Supply the
--db
command line option when invokingbin/locuszoom
Editing the m2zfast.conf file entails changing the following block of code:
SQLITE_DB = { 'hg18' : "data/database/locuszoom_hg18.db" };
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:
SQLITE_DB = { 'hg18' : "data/database/locuszoom_hg18.db", 'hg19' : "data/database/my_database.db" };
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 LATEST_BUILD
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.
Variable | Description |
---|---|
LATEST_BUILD | Latest build (i.e. the default build.) This is used to index SQLITE_DB, as well as LD_DB. |
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. |
OFFLINE | For the standalone version of LocusZoom, this should always be True. |
SQLITE_DB | See 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. |
DEFAULT_SNP_FLANK | If only a --refsnp is given with no --flank, this variable sets the default flank that is used. |
DEFAULT_GENE_FLANK | If only a --refgene is given with no --flank, this variable sets the default flank that is used. |
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 --cache <file>
. If you wish to disable LD caching, you can use --cache None
.
Python note: The ld_cache.db is actually a shelve, and you can explore its contents using:
import shelve d = shelve.open("ld_cache.db")
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.