#This tutorial illustrates how to produce a shivplot, starting
#from data stored in flat files.  You can work through it by 
#pasting the provided commands at the command prompt of an instance of R or S-PLUS.

#Additional provided files:
#example.txt -                small dataset example used in this
#(1751-0473-1-6-S3.txt)       tutorial.  It is a tab-delimited
#                             data file with row (1 to 100) and
#                             column (replicate<Y>) names.
#                             These headings are optional when
#                             importing data.

#Alternative.txt -            A second small dataset representing an
#(1751-0473-1-6-S4.txt)       "alternate normalization" of the first.

#shivcode.txt -               The script for constructing shivplots.
#(1751-0473-1-6-S1.txt)

#tutorial.txt -               This file.
#(1751-0473-1-6-S2.txt)


#Reading files into your R/S-PLUS session:
#(Let's assume the shivplot supplementary files (S1-S4) are located in "D://MyData//")

###Step 1:  Reading shivplot script code into R
#First, copy the shivcode.txt(1751-0473-1-6-S1.txt) file to some working directory (D://MyData)
#Then, at the command prompt inside an instance of R/S-PLUS, type
source ("D://MyData//1751-0473-1-6-S1.txt")

#Step 2:  Read data into session.  "\t" represents the
#tab character for the sep(arator)
#Note: 1751-0473-1-6-S3.txt is just a randomly generated data set.  Referred to as "example.txt" in the manuscript.
example <- read.table("D://MyData//1751-0473-1-6-S3.txt", sep="\t")

#For convenience, we use a less complex data structure to store the information
#in place of the default data.frame  (don't worry if this sounds like nonsense)
example<-as.matrix(example)

#Step 3:  construct basic shivplot:
shivplot(data = example)

#Alternatively, we can toggle some of the defaults on the shivplot.
#To do this, append the name of an argument and its new value after
#the data argument, separated by a comma as illustrated below:
shivplot(data = example, outlierCharacter= "x")
#This will replace the default outlier character (a dot) with an x.

#Let's suppose we had data from a second, alternative preparation of the
#data (or perhaps a new data set entirely).  To construct a
#comparative shivplot (see manuscript), try the following:

#Note: 1751-0473-1-6-S3.txt is just a randomly generated data set.  Referred to as "alternative.txt" in the manuscript.
alternative<-read.table("D://mydata//1751-0473-1-6-S4.txt")
alternative<-as.matrix(alternative)

#The following line attaches the two data sets in a single data structure
#called a 'list'.  The shivplot code reacts differently to list input,
#and constructs one plot per list element.  Here, we are creating a list
#with two elements, one for each data preparation.
compareData<-list(original = example, alt = alternative)

#Now we can construct a comparative shivplot using this list as input
shivplot(data = compareData)
#Plots are ordered in the same order as the elements in the list used
#to generate the plot.  We can attach more meaningful names to the plots
#as follows:
shivplot(data = compareData, plotNames = c("Original", "Alternative"))

#We can also remove these labels entirely:
shivplot(data = compareData, plotNames = c( "", "" ))

#To instead plot shivplots adjacent to one another without enforcing a uniform scale,
#some variant of the following can be used:



par(mfrow=c(1,2))#Prepare a plotting surface to display two adjacent plots
shivplot(data = example, plotNames = "Original")
shivplot(data = alternative, plotNames = "Alternative")
par(mfrow=c(1,1))

#Lastly, we can also create a multi-sample shivplot using the "multishivplot" plotting function.

multishivplot(data = compareData, plotNames = c("Original", "Alternative"), plotColors = c(2,3), titles="Example")