What is this? This distribution provides a set of modules, and a single client, gx, to implement GeneXplorer, which is a web interface for browsing hierarchically clustered data. The latest version of this module should always be available from: http://search.cpan.org/dist/Microarray-GeneXplorer/ An example of this software in action is available at: http://microarray-pubs.stanford.edu/cgi-bin/gx?n=prostate1&rx=5 PREREQUISITES GD.pm GeneXplorer relies on the GD module (http://search.cpan.org/dist/GD/) for image creation. If the GD module support png image creation (version > 1.19), then it will create png images, otherwise gif images will be created. INSTALLATION Firstly, read all the installation instructions before you begin! To install this software, you will need some limited Unix experience, and some limited Perl experience. If in doubt, consult your local Perl guru or systems administrator. You also need access to a Unix machine, such as MacOSX, or a Windows machine running Cygwin, a Linux box, a Sun machine etc.. To install the software do the following after downloading the distribution: First decompress the gzipped tarfile, e.g: tar zxvf Microarray-GeneXplorer-0.1.tar.gz or: gunzip Microarray-GeneXplorer-0.1.tar.gz tar xvf Microarray-GeneXplorer-0.1.tar Then change into the created directory: cd Microarray-GeneXplorer-0.1 To install the actual Perl modules themselves, and the executable correlations and makeMicroarrayDataset.pl programs, type the following (note, the 'make install' step requires administrative privileges - see your sysadmin if you don't have them): perl Makefile.PL make make test make install If you don't have administrative privileges, or want to install the modules and excutables (correlations and makeMicroarrayDataset.pl) into a location other than the default location on your machine, then use the following: perl Makefile.PL INSTALLDIRS=site INSTALLSITELIB=/home/your/private/dir/lib INSTALLSCRIPT=/home/your/private/bin make make install Replace /home/your/private/dir/lib with the full path to the directory you want the libraries placed in, and /home/your/private/bin with the full path to the directory that you want the executables placed in. Note that if you install the libraries in a non-standard place, prior to doing the install step you should edit the bin/makeMicroarrayDataset.pl program to include that path (with a 'use lib' statement), so that the installed version can find the library. See the documentation for ExtUtils::MakeMaker for more details about how to modify the behaviour during the make process: http://search.cpan.org/dist/ExtUtils-MakeMaker/ A Note About Directories Programs within the GeneXplorer distribution are picky about directory structures, in that they expect a certain directory structure to exist when a dataset is created (see below), and when the contents of a dataset are subsequently used by the gx application. You will need to have a web accesible directories where images can be read from over http for general images used by GeneXplorer, images used for a particular dataset, and images that are created on a temporary basis. You will also need a cgi-bin directory where the gx application itself will exist, and a directory in which the dataset files can be stored and read by the cgi application. Your set up needs to look something like this: // html/ tmp/ # for temporary images explorer/ # under which images specific for a dataset are created images/ # for general GeneXplorer images cgi-bin/ # gx resides here data/ explorer/ # datafiles for a dataset reside here lib/ in the above example, when creating a dataset, a directory, based on the name of the dataset, would be created under each of : //html/explorer/ //data/explorer/ where files specific to that dataset will be stored. The gx application assumes that there exists a rootpath (server_root above), under which will be an html directory, and underneath that there will be a tmp and an explorer directory. This is somewhat inflexible, and will be made more configurable in a future release. The bottom line is that you MUST create a directory structure that looks like the one above, where the html directory is the DOCUMENT_ROOT. What is a displayConfig file? It is a file that allows you to specify some of the look and feel of gx, and to where certain things should link etc. Some examples are in the data/explorer directory. Using GeneXplorer Once you have installed the Perl modules, and compiled the correlations binary and placed it in an appropriate location, you are almost ready to start using GeneXplorer. There are two stages to using GeneXplorer: 1. Creating a dataset. To create a dataset, you will need a cdt file, whose format is described at: http://genome-www5.stanford.edu/MicroArray/help/formats.shtml#cdt A cdt file is created using a program to hierarchically cluster microarray expression data. Many programs exist to do this hierarchical clustering, e.g.: Cluster: http://rana.lbl.gov/EisenSoftware.html Cluster 3.0 : http://bonsai.ims.u-tokyo.ac.jp/~mdehoon/software/cluster/index.htm XCluster : http://genetics.stanford.edu/~sherlock/cluster.html There are cdt sample files in the data/sample/ directory of this distribution. Once you have a cdtfile, you can now use the makeMicroarrayDataset.pl program to create a dataset from it. Before you run it, you need to make sure of two things: i. The correlations binary that you installed must be in your path. ii. The location where you just installed the perl modules must be in your path, or edit makeMicroarrayDataset.pl to add a 'use lib' statement such that it can find them. There are several command-line options for makeMicroarrayDataset.pl (execute it with no parameters, and it will print out its usage information): makeMicroarrayDataset.pl -file -name \ [-rootpath -contrast -colorscheme -verbose] -file = (required) input file (currently only '.cdt' files supported) -name : (required) dataset name to be created (may be delimited by slashes(/) to imply hierarchy) -rootpath : root directory, under which must exist html and data directories -contrast : (optional) contrast value for the generated images (defaults to 4, As the data are expected to be in log base 2, this corresponds to a 16-fold change as the maximum color in any image) -colorscheme : (optional) color scheme used for generating the images (rg = red/green, yb = yellow/blue ; defaults to yellow/blue) -verbose : (optional) whether show feedback messages during run (no value required - simply provide the parameter) -help : (optional) whether to print usage information (no value required - just provide the parameter) eg: makeMicroarrayDataset.pl -file mydata.cdt -name mydata -rootpath // -imageout -verbose -contrast 2 -colorscheme rg The program will create 7 files in: //data/explorer// with the following suffixes: .expt_info .feature_info, .data_matrix, .binCor, .meta (these files must be readable by a gx application running out of cgi-bin) and two files in: //html/explorer// with the following suffixes: .data_matrix.gif, .expt_info.gif In addition, the dataset creation will expect a tmp directory to exist at: //html/tmp/ Once your dataset has been created, it should be usable by the gx application. 2. Move some files in the distribution into place a) The displayConfig files cp data/explorer/* //data/explorer/ b) Some images cp html/explorer/images/* //html/explorer/images/ 3. Use the gx application You will need to place the gx application in your cgi-bin directory, and make it executable. You will also need to make some modifications to the gx application so that it knows where certain things exist that are within your system: a) Libraries gx has to be able to find the Perl libraries that you installed with the 'make install' command above. If you installed them in a typical system wide fashion, then it is likely that they are in the path of the cgi script. If you installed them in a specific place, then you will need to add a : use lib '/home/your/private/dir/lib'; in gx, before the: use Microarray::CdtDataset; use Microarray::Explorer; use Microarray::Config; lines. If you installed them in a lib directory immediately below the server root, at the same level as your html directory, then simply uncomment the lines in gx that read: #use File::Basename; #use lib dirname($ENV{DOCUMENT_ROOT})."/lib"; which should locate the libraries for you. b) Paths You need to put into the gx file the your rooturl and rootpath so it knows where to find the files and link to. You also need to place the images that are provided in the html/explorer/images directory of this distribution into the /html/explorer/images/ directory on your server. To then actually use gx, you should be able to type in your web browser a url such as: http:///cgi-bin/gx?n= where is the name that you gave your dataset when creating it with makeMicroarrayDataset.pl. For creation of subsequent datasets, as long as you are using the same rootpath directory, then you should be able to not worry about this step 2, and after creating your dataset should be able to simply change the n parameter passed to gx, and it will just work.