% \VignetteIndexEntry{ReportingTools basics}
% \VignetteDepends{}
% \VignetteKeywords{reprise}
% \VignettePackage{ReportingTools}
\documentclass[10pt]{article}

\usepackage{times}
\usepackage{hyperref}
\usepackage{Sweave}

\textwidth=6.5in
\textheight=8.5in
\oddsidemargin=-.1in
\evensidemargin=-.1in
\headheight=-.3in

\title{Basics of ReportingTools}
\author{Jason A. Hackney and Jessica L. Larson}
\date{\today}

\begin{document}

\maketitle
\tableofcontents
\newpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Frequently, when performing an analysis, it is helpful to be able to share these results in several formats at once: as HTML tables, csv files or even as R data packages. \verb@ReportingTools@ attempts to make this as painless as possible. At its heart, \verb@ReportingTools@ is based on a number of pieces of interlocking machinery that transform popular \tt Bioconductor \rm objects into reports.

In this vignette we will highlight the fundamentals of \verb@ReportingTools@.  \verb@ReportingTools@ has several methods for displaying microarray and RNA-seq results and can also be incorporated into \tt shiny \rm applications and \tt knitr \rm reports; for more details, please refer to the corresponding vignettes (knitr.Rmd and shiny.Rnw, respectively) or the \verb@ReportingTools@ \href{http://research-pub.gene.com/ReportingTools}{site}.

For more information on \verb@ReportingTools@, please see Huntley, Larson, {\it et al.} (2013).

\section{Basics of Reporting}

The easiest type of report to generate is a csv file. This is done using the \verb@CSVFile@ class and the publish method. To start we'll create a \verb@data.frame@ that we'll use throughout the vignette.

<<makeBasicDataFrame>>=

my.df <- data.frame(EGID = c("103", "104", "105", "106", "107"),
                    RPKM = c(4, 5, 3, 100, 75),
                    DE = c("Yes", "Yes", "No", "No", "No"))
my.df
@

Next, we'll create the \verb@CSVFile@ object to which we'll publish our results.  We output the results to a new directory called \tt reports\rm.  Note that \tt ReportingTools \rm will create this directory for you if it does not exist already.

<<makeCSVFile, eval=FALSE>>=
library(ReportingTools)

csvFile <- CSVFile(shortName = "my_csv_file", 
    reportDirectory = "./reports")
publish(my.df, csvFile)
@

Obviously, this isn't much less work than just calling \verb@write.csv@ on the \verb@data.frame@ itself, but this is really just a toy example. We can also publish the \tt data.frame \rm as an HTML report.

<<basicHTMLReport, eval=FALSE>>=
htmlRep <- HTMLReport(shortName = "my_html_file",
    reportDirectory = "./reports")
publish(my.df, htmlRep)
finish(htmlRep)
@

\begin{figure}
\centering
\includegraphics[scale = .5]{html1.png}
\caption{Resulting page created by \tt publish \rm for \tt my.df\rm.}
\end{figure}


It's necessary to call \tt finish \rm on the \tt HTMLReport\rm, to allow the contents to be written to the file.   \\

It's also possible to publish the same object in two separate formats at once. 

<<reportingTwoTypes, eval=FALSE>>=
csvFile2 <- CSVFile(shortName = "my_csv_file2", 
    reportDirectory = "./reports")
htmlRep2 <- HTMLReport(shortName = 'my_html_file2',
	title="Publishing a data frame and csv file together",
    reportDirectory = "./reports")
publish(my.df, list(csvFile2, htmlRep2))
finish(htmlRep2)
@

The same few lines of code could be used to publish, for example, the results of a \verb@limma@ differential expression analysis, or the results of a Gene Ontology analysis, all without worrying about coercing the objects to a tabular format ourselves.  For more information, see the microarray and RNA-seq vignettes.


\section{Adding plots or text to a report}

To add links, additional text or plots to a report, simply open the report with \tt HTMLReport\rm, write to it via the \tt publish \rm function  and then call \tt publish \rm on the original data frame and \tt finish \rm the report.  Below we make a simple plot and then add it and some descriptive text to our report.

<<AddImage, eval=FALSE>>=
plot(my.df$EGID, my.df$RPKM, xlab="EGID", 
	ylab="RPKM", main="Scatter plot of RPKMs", col="blue")
scatterPlot <- recordPlot()
library(lattice)
barPlot <- barchart(my.df$RPKM~my.df$EGID)  ##lattice plots behave slightly differently
	
htmlRep3 <- HTMLReport(shortName = "my_html_file3", title="Adding a plot directly to the page",
    reportDirectory = "./reports")
publish(scatterPlot, htmlRep3, name = "scatterPlot")  
publish("This is a bar plot", htmlRep3)
publish(barPlot, htmlRep3, name = "barPlot")
publish(my.df, htmlRep3, name="Table")
finish(htmlRep3)
@

\begin{figure}
\centering
\includegraphics[scale = .5]{html3.png}
\caption{Resulting page created after adding additional figures and text with \tt publish\rm.}
\end{figure}

We can also publish existing images and text directly to sites with \tt hwriter \rm.

<<AddTextPlot, eval=FALSE>>=
png(filename="reports/barplot.png")
barplot(my.df$RPKM, names.arg=my.df$EGID, xlab="EGID", 
	ylab="RPKM", main="Bar plot of RPKMs", col="blue")
dev.off()

library(hwriter)
htmlRep4 <- HTMLReport(shortName = "my_html_file4", title="Adding a link, text and image",
    reportDirectory = "./reports")
publish(hwrite("This is a link to Bioconductor", link = "http://www.bioconductor.org"), htmlRep4) 
publish(hwrite("Bar chart of results", heading=2), htmlRep4)
himg <- hwriteImage("barplot.png", link="barplot.png")
publish(hwrite(himg, br=TRUE), htmlRep4)
publish(hwrite("Results Table", heading=2), htmlRep4)
publish(my.df, htmlRep4)
finish(htmlRep4)
@



\section{Adding plots or links to a report table}
To add additional plots or links to a report table, we can create a new data frame with the path to the plots and our links of interest.  We then \tt publish \rm this data frame.  

Below we make a set of simple plots and then add the images along with new links to the NCBI gene database to our data frame.

<<AddPlotLink, eval=FALSE>>=
imagename <- c()
for (i in 1:nrow(my.df)){
	imagename[i] <- paste0("plot", i, ".png")
	png(filename = paste0("reports/", imagename[i]))
	plot(my.df$RPKM[i], ylab="RPKM", xlab = my.df$EGID[i], main = "RPKM Plot", col = "blue")
	dev.off()
}
my.df$Image <- hwriteImage(imagename, link = imagename, table = FALSE, width=100, height=100)
my.df$Link <- hwrite(as.character(my.df$EGID), link = paste("http://www.ncbi.nlm.nih.gov/gene/",
               as.character(my.df$EGID), sep = ''), table=FALSE)

htmlRep5 <- HTMLReport(shortName = "my_html_file5", 
                       title = "Adding images and links to data frame directly",
                       reportDirectory = "./reports")
publish(my.df, htmlRep5)
finish(htmlRep5)
@


We can also update our data frame by editing, adding and removing columns with functions.  We then include these functions in our publish call as a list with \tt .modifyDF \rm and \tt .toHTML\rm.  \tt .modifyDF \rm uses the basic data frame as its default object and then modifies it with the corresponding function.

<<AddPlotLinkFunctions, eval=FALSE>>=
##this function adds 5 to each value of my.df$RPKMs 
add5 <- function(object,...){
	object$plus5 <- object$RPKM+5
	return(object)
}
##this function replaces the scatter plot images with new plots
makeNewImages<-function(object,...){
	imagename <- c()
	for (i in 1:nrow(object)){
		imagename[i] <- paste0("plotNew", i, ".png")
		png(filename = paste0("reports/", imagename[i]))
		plot(object$RPKM[i], ylab = "RPKM", xlab = object$EGID[i],
                     main = "New RPKM Plot", col = "red", pch = 15, cex=3)
		dev.off()
	}
	object$Image <- hwriteImage(imagename, link = imagename, table = FALSE, height=150, width=150)
	return(object)
}
##This function removes the link column 
removeLink <- function(object, ...){
	object <- subset(object, select = -Link)
	return(object)
}
##This function links the EGID column to the entrez database 
addEGIDLink <- function(object, ...){
	object$EGID <- hwrite(as.character(object$EGID), 
                              link = paste0("http://www.ncbi.nlm.nih.gov/gene/",
                                as.character(object$EGID)), table = FALSE)
	return(object)
}
htmlRep6 <- HTMLReport(shortName = "my_html_file6", 
                       title = "Manipulating the data frame directly",
                       reportDirectory = "./reports")
publish(my.df, htmlRep6, 
        .modifyDF = list(add5, makeNewImages, removeLink, addEGIDLink))
finish(htmlRep6)
@

\begin{figure}
\centering
\includegraphics[scale = .5]{html6.png}
\caption{Resulting page created after adding figures and links to table with \tt .modifyDF\rm.}
\end{figure}

\section{Multiple Tables to the same page}
It is also possible to publish multiple tables to the same html page.  We can change the order of the tables via \tt pos\rm.

<<multipleTables, eval=FALSE>>=
df2 <- data.frame(x = 1:5, y = 11:15)
df3 <- data.frame(x = c("a", "b", "c"), y = 1:3)

htmlRep7 <- HTMLReport(shortName = "my_html_file7", title = "Many tables, one page",
                       reportDirectory = "./reports")
publish(my.df, htmlRep7, 
        .modifyDF = list(add5, makeNewImages, removeLink, addEGIDLink), 
        name = "Df1")
publish(df2, htmlRep7, name = "Df2")
publish(df3, htmlRep7, name = "Df3", pos = 2)
finish(htmlRep7)
@

\section{Publishing other types of data and more advanced features}
To publish data that is not a data frame, there is a need to create and use a \tt .toDF \rm function.  For example, suppose we have a matrix we would like to publish.  \tt ReportingTools \rm will convert the basic matrix to a data.frame and then publish it.  

<<publishMatrix, eval=FALSE>>=
set.seed(123)
my.mat <- matrix(rnorm(20), nrow=5)
makeDF <- function(object, ...){
	df <- as.data.frame(object[-2,])
	names(df) <- paste0("New ", 1:4)
	return(df)
} 
htmlRep8 <- HTMLReport(shortName = 'my_html_file8', 
                       title="Publishing objects that are not data frames",
                       reportDirectory = "./reports")
publish(my.mat, htmlRep8, .toDF = makeDF)
finish(htmlRep8)
@

\begin{figure}
\centering
\includegraphics[scale = .5]{html8.png}
\caption{Resulting page created after transforming a matrix to a data frame with \tt .toDF\rm .}
\end{figure}


For publishing experimental results, including how to publish a \verb@limma@-based linear model and a \verb@edgeR@ objects, please see the relevant vignettes.  There are built-in \tt ReportingTools \rm methods to publish non-data frame objects typically encountered in microarray and RNA-seq analyses.  Example output is shown below.

\begin{figure}
\centering
\includegraphics[scale = .5]{microarray1.png}
\caption{Resulting page created for analysis of a microarray study with \tt limma\rm.}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{References}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Huntley, M.A., Larson, J.L., Chaivorapol, C., Becker, G., Lawrence, M., Hackney, J.A., 
and J.S. Kaminker. (2013).  ReportingTools: an automated results processing and 
presentation toolkit for high throughput genomic analyses. {\it Bioinformatics}. 
{\bf 29}(24): 3220-3221.
 
 
\end{document}
