# 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 or FastRWeb systems.

## Static versus dynamic content

AnalysisPageServer can server either static or dynamic content. Static content 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 reports.

Dynamic content 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 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 or FastRWeb system.

## Running under windows

Creating static reports (described in Static Content, Embedding and Interactivity 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 and Interactive Applications 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 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 (who wrote the javascript/CSS/HTML front end) as part the ExpressionPlot project in the Genentech Bioinformatics Department. Hunter Whitney 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 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. Basic example sharing a scattergram and meta-data.
2. Embedding. Embedding APS datasets in other documents.
3. Interactivity. Walk through interactive functions on basic example.
4. Non-interactive Servers and Rook Deployment. Walk through building example non-interactive servers and deployment via Rook.
5. Interactive Applications. Building interactive and responsive servers with complete front-end
6. Rapache. Sharing remotely with RApache.
7. FastRWeb. Sharing remotely with FastRWeb.