<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{0. AnalysisPageServer}
-->
<link rel="stylesheet" type="text/css" href="AnalysisPageServer.css">


```{r echo = FALSE}
options(markdown.HTML.options = "toc")
```


# AnalysisPageServer

AnalysisPageServer is a framework for sharing interactive data and
plots from R through the web.


------

## Introduction


R is a useful tool for analyzing data and making plots. The web is a
convenient way to share these analyses. AnalysisPageServer is a
modular system that makes it easy to share customizable R analyses via
the web.

The basic object within the AnalysisPageServer system is a plot with
data associated to particular elements (usually points or bars) within
that plot. We use a data.frame to track meta-data associated with
particular elements of the plot. AnalysisPageServer handles all the
details of tagging the elements of the plot and serving to the front
end. The Javascript front end offers a rich experience for the end
user:

* Customizable parameters for the analysis (in dynamic mode)
* Plot and data table display
* Rollover of plot elements to show meta-data
* Filtering of table and plot based on meta-data
* Selecting and tagging of plot elements with filtering based on selection
* Download of (filtered or unfiltered) data in .csv, or plot in .svg or .png.

The server and client are loosely coupled. The server can run without the
front end, just serving raw data such as JSON strings, or plots. The front end
can also run without the server on a single plot and/or dataset. A directory
structure is written to disk with all of the necessary files to open
the front-end on this data set in a browser.
The server can also be deployed within an R process or, more stably, using
[rapache](http://rapache.net) or [FastRWeb](http://rforge.net/FastRWeb) systems.


## Static versus dynamic content

AnalysisPageServer can server either static or dynamic content. [Static
content](StaticContent.html) is generated in any manner, possibly not even by R. Each
dataset is an SVG plot, and/or a data frame (if not generated by R
then this would be a JSON string with a particular format). Such
content can be deployed through the filesystem. This can be thought of
as a system for generating [highly interactive](Interactivity.html) reports.

[Dynamic content](ExampleServers.html) is organized into a registry of `AnalysisPage`s. Each
`AnalysisPage` represents a single handler function, which is specified
when you start the server. Typically the function makes a plot and
returns a data frame. AnalysisPageServer system takes care of all the
details of opening and closing the plotting device, tagging the
elements of the SVG, and formatting the result for the front end. In
dynamic mode, each page also has a set of parameters. Each parameter
corresponds to one argument of the handler function, and is rendered
as a widget for the user. The types of parameters available include
text entry, sliders, dropdown menus, toggle buttons, and
combobox/autocomplete-type widgets, and are described in the [Interactive Apps](InteractiveApps.html)
page.

## Deployment

When serving static content there is no need to run a server. A
directory structure is simply written to disk. It could then be opened
directly in a web browser on your laptop, zipped up and passed to a
collaborator, or served as a static content for example by an Apache
server. Note that Chrome must be run with the `--allow-file-access-from-files`
switch in order to open for example on your local machine, but other browsers tested (Safari and Firefox)
work out of the box. To start Chrome this way on a Mac 
open a Terminal and type `open -a "Google Chrome" --args --allow-file-access-from-files`.
On windows Chrome can be started from the command line  with `"C:\PathTo\Chrome.exe" --allow-file-access-from-files`.
(To find the path to your Chrome executable open the URL `chrome://version` within Chrome.)
If data sets are not rendering in Safari, enable the Developer menu (Preferences -> Advanced -> "Show Develop menu in menu bar"),
then select "Disable local file restrictions" from the Develop menu.

For dynamic content a server is essential since all plots and data are
generated on-the-fly. For development purposes it is possible to
deploy an AnalysisPageServer application using the Rook/Rhttpd
system. This runs a web server within the R process of your local
machine, but it does not perform well due to frequent crashes
caused by parallel requests. A production system can be
deployed using either the [rapache](ApacheDeployment.html) or [FastRWeb](FastRWebDeployment.html) system.

## Running under windows

Creating static reports (described in [Static Content](StaticContent.html), [Embedding](embedding.html)
and [Interactivity](Interactivity.html) vignettes) is fully supported under Windows.

Dynamic applications can be
constructed under windows and deployed using Rook+Rhttpd (described in [Non-interactive Servers and Rook Deployment](ExampleServers.html) and
[Interactive Applications](InteractiveApps.html) vignettes). However, since `fork` is unavailable for
windows, the convenience function `startRookAnalysisPageServer` is unavailable, and deployment has to be
done [within a single R process](ExampleServers.html#toc_4) using the more cumbersome Rook interface.
Furthermore, Rook+Rhttpd deployment is unstable and not recommended for production systems.
To our knowledge there is still no solution for deploying a multi-process R server from windows, and in
particular FastRWeb and RApache are not well supported under windows. Therefore
we do not currently recommend deploying dynamic applications from windows.

## Acknowledgments

This package was developed by Brad Friedman (who wrote the R code) and [Adrian Nowicki](http://www.adrian-nowicki.com/)
(who wrote the javascript/CSS/HTML front end) as part the ExpressionPlot
project in the Genentech Bioinformatics Department. [Hunter Whitney](http://hunterwhitney.com)
was our user experience designer. Matthew Brauer was the senior manager and made the whole project happen.

Some of the error handling code was
adapted from Gregoire Pau's and Jens Reeder's `HTSeqGenie` package.
See the [Licenses page](Licenses.html) for a list of other external dependencies and their licenses.

Thanks to the Bioconductor team, in particular Marc Carlson, for helping us improve the engineering and distribute
this software. Thanks to Jeffrey Horner for `Rook` and `RApache`, to Simon Urbanek for `RServe+FastRWeb`, to
Alex Couture-Beil for `rjson`, and to all three for answering my e-mails.

Thanks also to my colleagues in the Genentech Bioinformatics Department for their suggestions and feedback:
Kiran Mukhyala, Michael Lawrence, Gabriel Becker, Thomas Sandmann, Christiaan Klijn, Jason Hackney,
Christina Chaivorapol, Melanie Huntley, Peter Haverty and Joshua Kaminker.
Thanks to our department directors Gerard Manning, William Young, and Robert Gentleman, for supporting
the project.
Finally, thanks to the many users of ExpressionPlot, the application for which AnalysisPageServer was
initially built,
who provided useful feedback on the user interface:
Jason Dinoso, Pascal Steiner, David Hansen, Bob Yauch, Robert Soriano, Jasmine Chen and Mark Solloway.
A very special thanks to Mark Solloway who first suggested the filtering and tagging interactions.

## Table of Contents

The following is a possible path through this documentation:

1. [Static Content](StaticContent.html). Basic example sharing a scattergram and meta-data.
1. [Embedding](embedding.html). Embedding APS datasets in other documents.
1. [Interactivity](Interactivity.html). Walk through interactive functions on basic example.
1. [Non-interactive Servers and Rook Deployment](ExampleServers.html). Walk through building example non-interactive servers and deployment via Rook.
1. [Interactive Applications](InteractiveApps.html). Building interactive and responsive servers with complete front-end
1. [Rapache](ApacheDeployment.html). Sharing remotely with RApache.
1. [FastRWeb](FastRWebDeployment.html). Sharing remotely with FastRWeb.
