ASSIMILATOR Files

Release notes for ASSIMILATOR 1.31
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Author:  Paul Martin
Email:   Paul.Martin-2@manchester.ac.uk
Date:    March 2011
Website: http://www.medicine.manchester.ac.uk/musculoskeletal/research/arc/genetics/bioinformatics/assimilator/

Version History
~~~~~~~~~~~~~~~
1.0 (May 2010)     - Initial release
1.02 (June 2010)   - Updated tableInfoDb.xml
                   - Added methods to cleanup, check and rebuild tableInfoDb.xml
                   - Added track error capture and reporting.
1.03 (June 2010)   - Connected and initialised TrackDb at start of worker sub to
                     save connecting for each query location.
1.20 (August 2010) - Fixed minor bugs. Added eQTLs, PolyPhen2 and relative SNP 
                     locations.
1.31 (March 2011)  - Fixed bugs relating to UCSC changes in hg19.
                   - Updated visual style and implemented jQuery UI
                   - Updated tableInfoDb.xml

Help
~~~~
Should you have difficulties setting up or running ASSIMILATOR please contact 
the author Paul.Martin-2@manchester.ac.uk providing any error messages.

About
~~~~~
Written in Perl, ASSIMILATOR retrieves, queries and processes information for 
the desired SNPs from the UCSC Genome Browser's (Kent et al. 2002) public MySQL 
database and displays this in a simplified, user friendly manner. All available 
ENCODE (Birney et al. 2007; ENCODE Project Consortium 2004) tracks are queried 
in addition to predefined tracks, such as mRNAs, ESTs and CpG islands. In 
addition, eQTL data hosted by the Pritchard laboratories 
(http:// eqtl.uchicago.edu), PolyPhen2 functional annotation 
(Adzhubei et al. 2010) and SNP location relative to the gene are displayed. 
Multiple systems have been designed to improve the efficiency of data retrieval 
such as an XML based track database, which minimises the number of database 
queries and multi-threading support to query multiple SNPs simultaneously, 
reducing processing time with minimal reduction in individual performance.
The output can be viewed in a standard web browser and allows the user to 
quickly identify SNPs which could be functionally important. To add extra 
functionality, the ability to view selected SNPs in NCBIs dbSNP 
(Sherry et al. 2001) and in the UCSC Genome Browser has been incorporated into 
the output. To efficiently display features for a SNP in the UCSC Genome 
Browser, only tracks which contain features in the SNP region are displayed. 
The user interface has been designed to allow further mining of the output to 
display information from the multiple cell types and links to external data. 
ASSIMILATOR automatically queries any new tracks appearing from the ENCODE 
project on UCSC and includes these in the analysis.

Prerequisites
~~~~~~~~~~~~~
ASSIMILATOR is ditributed with the required libraries used to access and 
process the information obtained from the UCSC Genome Browser. However, to 
run ASSIMILATOR perl must be compiled with thread support enabled. Additionally, 
to access the database and carry out some additional tasks the script requires 
some additional Perl modules. Where a version number is indicated the script 
has been succesfully tested with this version but earlier versions may be 
compatible. Additionally, later versions should be compatible. All required 
libraries known to work are available as a separate download from the 
ASSIMILATOR sourceforge website (http://sourceforge.net/projects/assimilatoruom/files/).
Please see below for installation instructions. An asterisk(*) indicates the 
version is a known minimum requirement due to available methods and 
incompatability issues with multi-threading.
threads 1.76*
threads::shared 1.33*
Thread::Queue 2.11
Sys::CPU 0.51
XML::LibXML 1.70*
XML::SAX 0.14
CGI 3.15
DBI 1.609
DBD::MySQL 3.0007
Getopt::Long 2.38
Getargs::Mixed 1.03
Module::Util 1.07
File::Temp 0.16
To view progress information:-
Term::Report 1.18
Term::StatusBar 1.18

Installation
~~~~~~~~~~~~
ASSIMILATOR comes as a either gzipped tarball (suitable for LINUX/MAC OS) or 
as a zipped archive (suitable for Windows). Please unpack the distribution 
using an appropriate method. For example under LINUX type:-
tar -xvzf assimilator-X.tar.gz
where X indicates version number.
Windows has built in archive support and double clicking the file should 
display it's contents where they can be extracted.

Library Installation
~~~~~~~~~~~~~~~~~~~~
These instructions are given as a guide only. Please refer to indvidual 
module documentation on CPAN (http://www.cpan.org/) for detailed installation 
and usage. It is recommended to install modules via the cpan shells install 
option. This will ensure all modules are installed into correct locations and 
any prerequisites are fullfilled.

The libraries are supplied as a gzipped tarball. Unpack the distribution using:-
tar -xvzf libs.tar.gz
This will create a new directory called libs containing all required modules, 
also as gzipped tarballs.
Unpack and make each module using the following commands, where MODULE is 
replaced with the module name:-
tar -xvzf MODULE.tar.gz
cd MODULE
perl Makefile.PL
make
make test
make install

Usage & Options
~~~~~~~~~~~~~~~~~
Usage:
    perl assimilator.pl ARGS
Required Arguments:-
    snps - comma separated list of SNPs to query
    regions - comma separated list of regions to query (region = chrN:start-end)
    input_file - file containing SNPs or regions to query
    output - file to save output to (adds .html extension)
    One, two or all of -snps, -regions or -input_file can be supplied
Optional Arguments:-
    html_root - root URI for stylesheet, javascript, images etc.
    ucsc_root - root URI for UCSC
    overwrite - overwrites output if it already exists.
    title - html output title (simple html formatting allowed e.g. italics)
    ucsclink - adds links to UCSC (default: 0), requires showUCSC.php
    stylesheet_srcs - relative path to stylesheet
    jscript_src - relative path to javascript
    noprogress - disables progress information
    nomulti - disables multi-threading
    max_slots - sets maximum number of query threads
    noshow_snp_build - supresses dbSNP build in output
    update_xml - updates the track info XML
    rebuild_xml - rebuilds the track info XML in case of corruption
    ucsc_version - specifies the UCSC database version to connect to (default: hg18)
    latest_ucsc - connect to the latest UCSC database which includes ENCODE tracks
    include - comma separated list of additional tracks to query. Either the tracks 
              table name, short or long label can be supplied. Short or 
              long label with spaces must be surrounded by single quotes 
              (eg. 'Vista Enhancers').
    exclude - comma separated list of standard tracks to ignore. For example, 
              the conservation tracks could be excluded if required. This option 
              takes the same format as the include option.

Example Usage
~~~~~~~~~~~~~
Basic usage is as follows
perl assimilator.pl -title Title -output example

To query ASSIMILATOR any or all of three methods are available:-
1) The -snps command switch (see above) can be used to specify one or more SNPs 
where the rs number is known. When specifying more than one SNP, SNP rs numbers 
are separated by commas (no spaces) e.g. add -snps rs1234,rs12345,rs67890 to 
query the three SNPs shown.
2) The -regions command switch (see above) can be used to specify genomic 
co-ordinates of a novel variation without an rs number. This is useful when 
querying novel in-house SNPs, SNPs from the 1000 genomes project 
(http://www.1000genomes.org) or where the SNP is unrecognised by the current 
UCSC database version in use (e.g. dbSNP >131). The format is chrX:start-end 
where X is the chromsome name, start is the start co-ordinate and end is the 
end co-ordinate. For example, chr5:1234-1236 would represent a feature spanning 
three base pairs (1234, 12345 and 12346), chr10:5678-5678 would represent a 
single base change at position 5678. Single base regions may alternatively be 
supplied as chrX:start. In this case the end is automatically assumed to be 
the same as the start (i.e. one bp in length). For example, chr10:5678-5678 
could also be supplied as chr10:5678. As with the -snps argument, multiple 
regions may be supplied separated by commas e.g. add 
-regions chr5:1234-1236,chr10:5678 to query the two regions described 
previously.
3)  The third option, -input_file, allows the user to supply the full 
filename of a file containing multiple SNPs and/or regions (one per line) 
where the format is otherwise the same as described for the -snps and -regions 
arguments. This option is useful when querying many SNPs or regions or when 
quering a mixture of the two. Additionally this format allows an optional 
second column (separated by a TAB character) adding more information for that 
SNP or region such as LD information, p-value or gene information e.g.
rs1678899	rsq=0.82 with rs12345
rs674565	pTREND=5e-5
rs838560	GENE1
chr10:12345	GENE2

IMPORTANT: when supplying a SNP to query by chromosomal position, co-ordinates 
must match the genome build UCSC is querying e.g. hg18 = NCBI36.

When using this option with the additional information it may be helpful to use 
the -noshow_snp_build command switch. This will omit the dbSNP build from the 
results table allowing the user to clearly see the additional information 
supplied. If the -noshow_snp_build command switch is not used a new line 
followed by the dbSNP build is shown. For example, without the argument, 
rs1678899 would produce a table cell as follows:-
rsq=0.82 with rs12345
snp130
and with the argument, just rsq=0.82 with rs12345 would be displayed.

Supplied Files
~~~~~~~~~~~~~~
ASSIMILATOR-1.30/
|-- README
|-- assimilator.pl
|-- example_input.txt
|-- Assimilator
|   |-- PolyPhen2Adaptor.pm
|   |-- PolyPhen2Prediction.pm - Data accessor to PolyPhen2
|   |-- Safe
|   |   `-- StatusBar.pm - threads::shared safe Term::StatusBar subclass
|   |-- UCSC - modules for accessing UCSC
|   |   |-- Group.pm - Representation of a Track Group
|   |   |-- TableInfo
|   |   |   `-- TableColumn.pm - Table column object to map name to column index
|   |   |-- TableInfo.pm - Stores infoformation about the table and columns
|   |   |-- TableInfoDb.pm - Database to hold TableInfo objects
|   |   |-- Track
|   |   |   `-- Feature - Objects representing various features used in UCSC
|   |   |       |-- BasicFeature.pm
|   |   |       |-- Bed.pm
|   |   |       |-- BedGraph.pm
|   |   |       |-- BroadPeak.pm
|   |   |       |-- ClonePos.pm
|   |   |       |-- GenePred.pm
|   |   |       |-- Ld2.pm
|   |   |       |-- NarrowPeak.pm
|   |   |       |-- Psl.pm
|   |   |       |-- WigMaf.pm
|   |   |       `-- Wiggle.pm
|   |   |-- Track.pm - Representaion of a Track
|   |   |-- TrackDb.pm - Database of available tracks and entry point into the
|   |   |                UCSC database
|   |   |-- Utils.pm - Util methods eg SQL argument construction
|   |   `-- tableInfoDb.xml - XML file with stored table information
|   |-- eQTL.pm - Representation of an eQTL feature
|   `-- eQTLAdaptor.pm - Data accessor to the eQTL database
`-- WWW - web related files to display results
    |-- images
    |   |-- cancel.png
    |   `-- subheadimg.png
    |-- javascript
    |   `-- assimilator.js
    |-- showUCSC.php
    `-- stylesheet
        `-- assimilator.css

References
~~~~~~~~~~
Adzhubei, I. A. et al. (2010) A method and server for predicting damaging 
missense mutations. Nat.Methods, 7, 248-249.
Birney, E. et al. (2007) Identification and analysis of functional elements 
in 1% of the human genome by the ENCODE pilot project. Nature, 447, 799-816.
ENCODE Project Consortium (2004) The ENCODE (ENCyclopedia Of DNA Elements) 
Project. Science, 306, 636-640.
Kent, W. J. et al. (2002) The human genome browser at UCSC. Genome Res., 12, 
996-1006.
Sherry, S. T. et al. (2001) dbSNP: the NCBI database of genetic variation. 
Nucleic Acids Res., 29, 308-311.