HOMER

The basic strategy HOMER uses is to create a bedGraph formatted file that can then be uploaded as a custom track to the genome browser.  This is accomplished using the makeUCSCfile program.  To make a ucsc visualization file, type the following:

makeUCSCfile <tag directory> -o auto

i.e. makeUCSCfile PU.1-ChIP-Seq/ -o auto
(output file will be in the PU.1-ChIP-Seq/ folder named PU.1-ChIP-Seq.ucsc.bedGraph.gz)

The "-o auto" with make the program automatically generate an output file name (i.e. TagDirectory.ucsc.bedGraph.gz) and place it in the tag directory which helps with the organization of all these files.  The output file can be named differently by specifying "-o outputfilename" or by simply omitting "-o", which will send the output of the program to stdout (i.e. add " > outputfile" to capture it in the file outputfile).  It is recommended that you zip the file using gzip and directly upload the zipped file when loading custom tracks at UCSC.


To visualize the experiment in the UCSC Genome Browser, go to Genome Browser page and select the appropriate genome (i.e. the genome that the sequencing tags were mapped to).  Then click on the "add custom tracks" button (this will read "manage custom tracks" once at least one custom track is loaded).  Enter the file created earlier in the "Paste URLs or data" section and click "Submit".

The most common problem encountered while loading UCSC files is to see "position exceeds chromosome length" or something to that effect.  This is usually caused by one of two problems:

The program works by approximating the ChIP-fragment density at each position in the genome.  This is done by starting with each tag and extending it by the estimated fragment length (determined by autocorrelation, or it can be manually specified using "-fragLength <#>").  The ChIP-fragment density is then defined as the total number of overlapping fragments at each position in the genome.  Below is a diagram that depicts how this works:

As great as the UCSC Genome Browser is, the large size of recent ChIP-Seq experiments results in custom track files that are very large.  In addition to taking a long time to upload, the genome browser has trouble loading excessively large files.  To help cope with this, the makeUCSCfile program works by specifying a target file size when zipped (default 50MB).  In order to meet the specified target file size, makeUCSCfile merges adjacent regions of tag density levels by their weighted average to reduce the total number lines in the final bedGraph file.  If you have trouble loading getting your file to load, try reducing the size of the file using the "-fsize <#>" option (i.e. "-fsize 2e7").  To force the creation of larger files, use a very large file size (i.e. "-fsize 1e50") - this will create a file that does not merge any regions and displays a "native" view of the data.

Tags can be visualized separately for each strand using the "-strand separate" option.

By default, makeUCSCfile uses the "-fsize <#>" option to determine how man reads to essentially "skip" when making the output file.  You can also manually set the resolution.

In an effort to reduce the size of large UCSC files, one attractive option is to reduce the overall resolution of the file.  By default, makeUCSCfile will make full resolution (i.e.  1 bp) files, but this can be changed by specifying the "-res <#>" option.  For example, "-res 10" will cause changes in ChIP-fragment density to be reported only every 10 bp.

In order to easily compare ChIP-fragment densities between different experiments, makeUCSCfile will normalize density profiles based on the total number of mapped tags for each experiment.  As with other programs apart of HOMER, the total number of tags is normalized to 10 million.  This means that tags from an experiment with only 5 million mapped tags will count for 2 tags apiece.  The total of tags to normalize to can be changed using the "-norm <#>" option.

Normalizing files to Input

The paragraph above specifies how to normalize read densities based on the total number of reads.  For some applications, particularly if studying organisms with small genomes, it is better to visualize the read density as a ratio relative to Input or IgG.  Normally I would NOT recommend visualizing reads this way if the Input/IgG read coverage is sparse as this will cause trouble when calculating ratios.  To normalize the experiment to a second tag directory, use the "-i <input tag directory>" option:

makeUCSCfile ExpTagDirectory/ -i InputTagDirectory  -o auto

Additional parameters to control the normalized output:

-pseudo <#> : To avoid fluctuations in the ratio due to low coverage input, a pseudo count is added to the numerator and denominator when calculating the ratio (default: 5)
-log : report as a log ratio (default is a simple ratio)
-inputtbp <#> : set the maximum tags per bp considered in the input experiment

You can specify that HOMER separate the data based on the strand by using the "-strand <...>" option.  This is useful when looking at strand-specific RNA-Seq/GRO-Seq experiments.  The following options are available:

Some data sets of very large, but you still want to see all of the details from your sequencing in the UCSC Genome Browser.  HOMER can produce bigWig files by running the conversion program for you (bedGraphToBigWig).  The only catch is that you must have access to a webserver where you can post the resulting bigWig file - this is because instead of uploading the whole file to UCSC, the browser actually looks for the data file on YOUR webserver and grabs only the parts it needs.  Slick, eh.  Chuck uses this all the time for big experiments.

Before even trying to make bigWigs, you must download the bedGraphToBigWig program from UCSC and place it somewhere in your executable path (i.e. the /path-to-homer/bin/ folder).  This called directly by HOMER to create the BigWig files. 

Using the makeBigWig.pl Script

Making bigWigs from scratch

1. Copy the *.bigWig file to your webserver location and make sure it is viewable over the internet.
2. Need to edit the "trackfileoutput.txt" file and enter the URL of your bigWig file (...  bigDataUrl=http://server/path/bigWigFilename ...)
3. Upload the "trackfileoutput.txt" file to UCSC as a custom track to view your data.
   

UCSC has recently added the option to create overlay tracks, where several bigWig files can be viewed in the same space with the help of transparent colors.  The first example of this was the Encode Regulation Track, which showed H3K4me1/3 data from several cell types at the same time.  This is very useful for large-scale data sets will many different experiments.  In these cases it is just about impossible to get them on the screen together.

To make a "multi-wig hub", as we will refer to them, you need to make sure you have the bedGraphToBigWig program from UCSC, and a working webserver to host your files.  If you can handle bigWigs in the section above, you can make multi-wig hubs.

The HOMER program to handle multi-wig hubs is called makeMultiWigHub.pl.  It works essentially the same way as the makeBigWig.pl script, however, the syntax is a little different.  The basic usage is:


NOTE: make sure you use the UCSC genome (e.g. mm9) and not the masked, bastardized HOMER version (mm9r).

The above example will produce a hub called "ES-Factors", composed of configuration files and bigWig files, and place it on your server in the directory specified by "-webDir <directory>".  It will also provide you with a URL to the hub (dependent on the value of -url <base url>").  To load the Hub, click on "Track Hubs" on the UCSC browser (next to custom tracks button), and paste the URL in to the dialog box.  The example above will look something like this:



To figure out which factors correspond to which colors, click on the Blue Heading for the Hub in the settings area below the UCSC picture.  Something like this should pop up:



Unfortunately, as of now editing hub information can only be done by directly modifying the hub files on the server.  For example, to edit to colors, you must edit the "/webserver/directory/hubName/genome/trackDB.txt" file.


Because Hubs are so cool, HOMER will also do +/- strand RNA data right.  Unfortunately, for now you can't mix stranded and non-stranded data in the same hub with the makeMultiWigHub.pl program.  To visualize stranded information, add "-strand".  Below is an example:

The following shows what the same data set looks like changing options for file size (-fsize) and resolution (-res).  Usually it's best to use one or the other.

1. -fsize 5e7 -res 1
2. -fsize 1e7 -res 1
3. -fsize 5e7 -res 10
4. -fsize 1e7 -res 10