ACT Tool

From GersteinInfo

Revision as of 22:55, 22 August 2010

Here is some information on http://act.gersteinlab.org (Aggregation & Correlation Toolbox)

Overview

Getting Started: select from one of the three icons on the ACT website

ACT is a toolbox for harvesting useful results from a vast sea of genomic experimental data. In particular, it is a set of scripts (Aggregation, Correlation, and Saturation) designed to be downloaded and used to analyze signal or hit tracks. These scripts, along with their supporting material (documentation, example files) can be accessed by clicking on their respective icons on the act.gersteinlab.org home page. The downloads are designed primarily with Unix/Linux users in mind. Details of what each script is designed to do, i.e. what files it takes in, what it outputs, and important notes, including dependencies, are discussed below.

There are also several supporting features on the website such as a gallery and example files: these are also discussed below.

In particular, here's a common set of example files that runs on all the tools.

General contact: jjmg [at] gersteinlab.org

Aggregation

The aggregation script takes values from multiple points on a single genomic signal track and creates an average signal profile around a set of anchor points, such as Transcription Start Sites (TSS's).

The main download is written in Python. Each run takes two input files: a signal or hit track (in the form of an sgr file or point file), and an annotations file in bed format. The output is a columnar file with explanatory headers--the files can be plotted in programs like gnuplot, excel, or matlab. The main download package has an R script in the samples folder which shows one way of plotting the output data with error bars.

It should be noted that in computing the "average signal profile" there are a number of computational choices to be made: for example, bin size, whether to use the median or mean of signals within a bin as the bin's value, whether to use the median or mean of signals across all bins as the final value in the signal profile. Since the annotations file requires regions input, there is also a choice to be made as to whether to aggregate around only a single point (the 5' end of the region, such as TSS's) or to include the entire region in the aggregation. Options dealing with all of these choices are available in the main aggregation download. For an idea of how bin scaling over regions works, see the aggregation powerpoint in the gallery.

• Parameters

Annotation file. Tab-delimited file containing several start and end positions, chromosome locations, and strand annotations, such as a bed file. The default structure of these files is like a bed file in which the chromosome is in column 1, 5’ position in column 2, 3’ position in column 3, and strand (“+” or “-“) in column 4. The program will automatically switch orientation based on strand. For this field, you may either upload your own file or use one of the common gene annotations found in the dropdown menu.

Signal file. Tab-delimited file containing signals and positions. Depending on what type of file is specified as well as how probewidth (see below) is defined, these can either represent discrete points with an independent probe width, or they can represent the signal for all locations until the next defined spot. Take, for example, the following excerpt from a signal file:

chr1 10 2.3

chr1 40 5.0

If probewidth is say 5, these two lines are read to mean that locations 10 through 15 on chromosome 1 have a signal of 2.3, and locations 40 through 45 have signal of 5.0. If probewidth is left blank, these two lines are read to mean that locations 10 through 40 have a signal of 2.3. These two options would require one to select the “sgr” format. The “wiggle” format allows one to upload a file containing four columns: one for chromosome, one for start position, one for stop position, and one for intensity, respectively. The “density” option allows one to upload a two column file containing chromosome and location. The program will assume that all points’s have a width of 1 and will calculate the number of probes that fall into the various bins, rather than the average intensity.

nbins upstream and downstream of a site

mbins between start and stop sites

Number of bins (n). Specifies how many bins will be in each flanking region (for a total of 2xn bins). For jobs that do not use scaled bins in the region between start and stop sites, there will be 2xn bins: n bins on each side of the start site.

Number of bins (m). Optional field to be defined if stop and start sites (regions) are to be considered in the aggregation process. Defines the number of bins assigned to the region between start and stop sites (for a total number of m+2n bins).

Length of flanking region. Specifies number of base pairs the program should analyze in both directions from either the start site or the start/stop pair, depending on the option specified.

Probe width. For signal files that present data for probes of a specific width (see Signal file above for use instructions).

Minimum gene length: Tells the program not to consider annotations for start/stop pairs that are shorter than a certain distance.

Include intergenic regions. Tells the program to scale bins inside the start/stop sites, or tells program to analyze in separate directions from the start site if unchecked.

Use mean. The program will automatically ensure that only the median signal of an individual gene (or number of probes, if the density option is selected) contributes to the final “averaging” calculation in each bin to avoid bias against shorter genes. If use mean is selected, the program will take the mean signal across all genes per bin and report the final result. Otherwise, it will use the median signal (of the median signal of each gene).

• Specific use instructions

Accepted file input types: .sgr, .wig (for signal track); abbreviated .bed file (for annotation track)

After unzipping, the main source file (which includes a detailed header with use instructions) is ACT.py. A makefile with example runs can be found in Agg/samples/Makefile

After downloading and unzipping the aggregation package, Agg.tar, the program can be run as follows (data files can be found under "Example Data" in the Aggregation section):

python ACT.py --nbins=50 --mbins=0 --radius=50000 hg17_ensembl.bed baf155.sgr > baf155_ensembl.out

where hg17_ensembl.bed is the annotations file and baf155.sgr is the signal track, placed in the same folder as ACT.py. An alternative run which would include the 3' boundary of each gene region can be performed using the following:

python ACT.py --nbins=50 --mbins=50 --radius=50000 --regions hg17_ensembl.bed baf155.sgr > baf155_ensembl.out

An aggregation run on point tracks (such as SNP lists) to determine average density can be performed as follows:

python ACT.py --nbins=50 --mbins=0 --radius=50000 --signalparser=PointParser gencode.pc.coords.chr1 YRI.snps.parsed.chr1 > YRI_gencode.out

There are additional tags corresponding to different aggregation options which can be viewed in the readme.

Update: no longer requires numpy to run

Correlation

The correlation script takes multiple signal tracks of equal length and divides each one into bins, similarly to the aggregation script, except in this case the bins are not hinged around anchor points and they are generally wider (either hundreds or thousands of bases, depending on which script is chosen). Each bin is assigned a value based on the corresponding signal track values, and then the arrays of bins are correlated with each other in pairwise fashion. Ultimately, a matrix of correlation coefficients corresponding to the correlations between all signal tracks is obtained.

There are options in the correlation script allowing one to control bin (sliding window) size and the overlap of the bins (windows).

There are two versions of the correlation tool. In Kevin Yip's version (Corr/Sat bundle) a final correlation matrix is created based on either the Spearman, Pearson, or normal score correlation between each pair of binned data sets.

In the Cor/Sat bundle, there is a .bat file with an example run. In Correlation P, an example run command is in README.

Correlation parameters summary, from Web ACT

• Parameters

Bootstrap cycle. Number of times to resample and recalculate the correlation coefficient when generating phylogenetic trees. This is done using phylip.

Overlap. The number of base pairs of overlap when the aggregation window “slides.” For example, in Genome Res 17: 787-97 a sliding window size of 3kb was used, with an overlap of 1.5kb.

Window size. Specifies the size of the sliding window in base pairs. For example, in Genome Res 17: 787-97 a sliding window size of 3kb was used, with an overlap of 1.5kb.

Size of heatmap picture. Length of the generated heatmap figure in inches.

• Specific Use Instructions

Input file type: .bed

The tool is run as follows:

java -jar EncodeTfCor2.jar [genome file] [BED file directory] [window size] [overlap size]

A specific example run can be found in EXAMPLE.txt

Saturation

Saturation script allows us to determine the saturation level of a given feature after multiple genomic experiments.

Each input file corresponds to one experimental condition (e.g. one new individual), and each line in a file specifies a genomic location that has the biological phenomenon under study (e.g. tagged SNP's). Our implementation makes use of special data structures to avoid redundant counting. It normally takes less than a minute to generate the plot for up to 30 input files each with a few thousand lines. To handle more files and files with more lines, the tool also provides an option to compute the coverage of a random sample of the input file combinations.

It produces saturation plots from a set of binary data files. Each line of the input flie contians a genomic region in the following format:

<ID><tab><start><tab><end>

where <ID> is the identifier of the region-at-large, such as the chromosome <start> is the starting position of the region <end> is the ending position of the region (this position is inside the region)

The y-axis could be the absolute number of nucleotides, or a fraction of an input total number of nucleotides, such as the total number of nucleotides of the coding transcripts in the example. To use the absolute number, input the total as 0.

An example file demonstrating how to use the saturation component can be found in saturation.bat

Web ACT

Information about input signal tracks can be found here: http://tiling.mbb.yale.edu:8080/aggcorr/documents/sigfile_readme.htm

• Aggregation

Note: based on C++ version of source code found in "Other versions" compendium

Parameters such as mbins and nbins same as described in Aggregation above.

• GSA

In the GSA, input signals are assigned to the nearest anchor in order to reduce the artifacts caused by subsets of anchors clustering together. For aggregation analysis of segment signals, such as sequencing tags, this requires the genomic scope of the experimental setup to be partitioned and accounted for as denominators. The techniques were used and proved effective in the ENCODE pilot and CTCF nucleosome papers.

• Correlation

Information about the correlation web tool can be found here: http://tiling.mbb.yale.edu:8080/aggcorr/documents/corr_readme.htm

Other

• Citation

A paper describing this site and software is currently in preparation . Currently, please just reference act.gersteinlab.org if you use the tool.

• FAQ