README FILE

**1.	Obtaining necessary perl scripts and installation.**
Users can download the two perl scripts necessary for visualizing GRAIL functional connections 
from the online GRAIL site at (http://www.broadinstitute.org/mpg/grail/vizgrail.html). Users should 
download both the makeInputFiles_v1.2.pl as well as the graphCluster_v1.8.pl perl scripts. These 
scripts require local installation of Perl 5.8.9, and the modules: LWP::SIMPLE, GD::SIMPLE, 
MATH::TRIG, LIST::UTIL, and POSIX.


**2.	Running a GRAIL query. Users must interface with the GRAIL site**
(http://www.broadinstitute.org/mpg/grail/grail.php) to run a job. The visualization scripts can 
effectively handle up to 100 independent loci derived from a total of 200 genes. More loci or genes 
than that will cause the ultimate graphic to look jumbled and confused. The user must run the GRAIL 
query with the “check here if Query Regions are identical to Seed Regions” option. The user must 
be careful to not include multiple loci that contain the same gene or genes – each locus must have 
a unique and mutually exclusive list of genes. The user may use any of the databases to calculate 
gene similarity, and any of the SNP resources as allowed by the site to define linkage 
disequilibrium blocks. Once the GRAIL results are completed, than the necessary calculations have 
been completed to visualize functional connections across the input loci. The site identifies the 
genes within those loci, identifies the degree functional similarity between genes, and then 
assesses the statistical significance of that degree of similarity for each gene. 

**3.	Making input files.**
The user then uses the makeInputFiles_v1.2.pl script to calculate the 
thickness of functional connections between genes accounting for the number of genes in the loci 
that they are derived from, and the strength of the relationship itself. The makeInputFiles_v1.2.pl 
script downloads the online results from the GRAIL site to create input files that define the 
genetic loci, statistical significance scores, and the pair-wise gene connections. To run the 
program:

bash-3.2$ perl makeInputFiles_v1.2.pl [GRAIL ID] [TRIM PARAM] 

where [GRAIL ID] is the numerical ID generated by the GRAIL site that indicates a specific 
GRAIL job. The [TRIM PARAM] is an optional numerical parameter that is set to zero by default. 
As the value of the parameter set at values increasing from zero, thinner connections are zeroed 
out, and remaining thicker connections are proportionally made thinner linearly to occupy the 0 
to range 3.

**4.	Making the graphic. **
Using the input files generated by makeInputFiles_v1.2.pl the user then 
uses the graphCluster_v1.8.pl script to optimally order regions and genes so that the generated a 
circular graphic displaying connections with a minimal number of intersections.

The input files can of course be modified, changed, or made by users to generate desired graphics. 
To run the program:

bash-3.2$ perl graphCluster_v1.8.pl –data [DATA]  --connect [CONNECT] –clusterRegions [CLUSTER] 
–scoreThresh [SCORE] –clusterGenes [CLSTGENES], and –orient [ORIENT]

Arguments can be entered in any order. 
[DATA] is the name of a tab-delimited file that defines how genes are within loci, and the 
individual statistical significance score for each gene. The first column is a locus or genomic 
region name, the second column is the name of an individual gene, and the third column is a 
statistical score ranging from zero to one. An example file is provided in the supplement.

[CONNECT] is the name of a tab-delimited file that defines the connectivity between the different 
genes. The first field is a gene name, the second field is a gene name, and the final field is a 
value between zero and 3 defining the strength of the connection between the two genes. Every gene 
must be listed in [DATA], and no gene pair can be listed twice. An example file is provided in the 
supplement.

[CLUSTER] is a parameter that defines how the regions/loci should be optimally oriented. An entry 
of zero will result in no arrangement of regions/loci. An entry of an in integer n will instruct 
the program to do at most n iterations in order to find the optimal configuration regions; the 
default parameter seeting is 200. The user can also choose to enter a file name that specifies 
the order that genetic regions should be listed; this file must list each region in [DATA] in an 
individual line, in the order that the user would like loci arranged around the circle. If the user 
opts to optimize the ordering, the ultimate ordering that is derived is written to the 
“clusteredOrder” file. 

[SCORE]. This parameter is a value between zero and one. Only the genes with significance values 
in the [DATA] file less than [SCORE] will have connections displayed. By default [SCORE] is set to 
0.05.

[CLUSTGENES]. This parameter is either 0 or 1. By default it is 1. If set to 1, only then will 
genes within loci be clustered to minimize overlap between connections.

[ORIENT]. This parameter is either 0, 1, or a region/loci name. If set to 0 than the display is not 
oriented. If set to 1, then the region/loci with the most connections will be oriented to the top. 
If set to the name of a specific locus or region, that locus or region will be oriented to the top 
of the figure.