zPicture :: Visualization Tool for Analyzing Conservation Profiles

1. Requirements
	1.1. zPicture should be run on blastz alignments. Therefore blastz
program that is freely available at http://bio.cse.psu.edu/dist is required.
	1.2. zPicture also uses 'gd' version 2.x graphical library that could be freely
obtained from http://www.boutell.com/gd/
	1.3. Three TTF font files are needed for zPicture - timesb.ttf, comic.ttf, and comicbd.ttf
You should modify zPicture.h file and indicate their location in case it differs from
/usr/X11R6/lib/X11/fonts/webfonts

2. Source files
	zPicture tool consists of two programs - blastz2zbn and zPicture. blastz2zbn is used
to compress blastz alignments into the 'zbn' format utilized by zPicture program. zPicture
creates conservation profile images in the graphical PNG format.  

3. Installation
	2.1. Unpack the source files
		gzip -c zpicture.tar.gz | tar xvf -
	2.2. Compile blastz2bin and zPicture 
	     (Note: if you are using not a g++ compiler please make required changes to the
	     first line of 'Makefile' files)
		cd blastz2zbn
		make
		cd zPicture
		make

4. Test blastz2zbn installation
	cd blastz2zbn/test
	../blastz2zbn human_mouse.blastz > test.zbn
	diff test.zbn human_mouse.zbn (files should be the same)

5. Test zPicture installation
	cd zPicture/test
	../zPicture human_mouse.zbn human mouse human.exons human.reps > picture.png
	display picture.png (or use any other picture visualization utility)

6. Add zPicture and blastz2bin locations to your PATH environment variable

7. How to use zPicture
	zPicture could be utilized to visualize compressed blastz alignments. First you would
need to have two sequences in FASTA format. For example, called 'human' and 'mouse'. Then
you need to run blastz to get a blastz alignment:
		blastz human mouse > human_mouse.blastz

Next step is to compress the blastz alignment into the zbn binary format
		blastz2zbn human_mouse.blastz > human_mouse.zbn

If you would like to have repetitive elements visualized you would need to have a RepeatMasker
(http://repeatmasker.genome.washington.edu/cgi-bin/RepeatMasker) output file (human.reps, for example).
If you don't have one or you don't want to visualize repeats, you would need to have an empty
file instead of the RepeatMasker output. You can create an empty file by 'touch'ing it:
		touch human.reps

Also, zPicture allows for a visualization of gene features and uses gene annotation to differentially
color the conservation profile (you can read the details at http://zpicture.dcode.org/zpInstructions.html).
This is an example of the file that we will save as human.exons for this example case:
		< 3186 5447 GENE
		3186 3499 UTR
		3500 3916 exon
		4994 5447 exon
As in case of repetitive elements you can avoid using the gene annotation file by creating an empty
gene annotation file

Now, when the input files are ready, zPicture can be executed:
		zPicture human_mouse.zbn human mouse human.exons human.reps > picture.png

8. Different zPicture options
	-justPrintEcrs : image will not be generated, instead all the ECRs (Evolutionary Conserved Regions) will be described in the print out
	-ecrWin and -ecrId : parameters that define an ECR; minimal length and minimal percent identity
	-smooth : smooth-plot will be generated instead of a pip-plot
	-numSeq N : if there are multiple alignments, all of them could be visualized, one on top of another.
		for example, if you have human_mouse and human_rat alignments you can visualize them simultaneously
		by running: zPicture -numSeq 3 human_mouse.zbn human_rat.zbn human mouse human.exons human.reps > picture.png
	other options are listed if zPicture is run without parameters

9. Questions? Please forward them to dcode@ncbi.nlm.nih.gov