new.analysis.page: new.analysis.page

In apomatix/AnalysisPageServer: A framework for sharing interactive data and plots from R through the web

Description

Validate and prepare a handler for installation

Usage

new.analysis.page(handler, param.set = NULL, annotate.plot = TRUE,
  class.name = "plot-point", standard.ids = TRUE, skip.checks = FALSE,
  plot.pars.transformer = NULL, annotate.data.frame = TRUE,
  numeric.sig.digs = 3, no.plot = FALSE, name = NULL, label = name,
  description = label, advanced = 0, thumbnail = NULL, service = FALSE,
  in.menu = !service, paramset.transformer = NULL)

Arguments

handler	A handler function, as described above.
param.set	An AnalysisPageParamSet to use for the function. Or NULL, to call default.param.set. Note that it is not a requirement that all of the function arguments be included in the param set—they just won't be provided.
annotate.plot	Logical. Should plots generated by this handler be automatically annotated? Default: TRUE.
class.name	Character. What class label should be applied to automatically annotated points? Default: "plot-point". (Ignored if annotate.plot is FALSE.)
standard.ids	Logical. By default (TRUE), the rownames of your return value are ignored, and new ones are created like "Reg1","Reg2". The advantage of this is that these IDs are guaranteed to be standard-compliant HTML and SVG id tags. If you want to force using your real rownames as IDs (for example, to help in debugging), then set this to FALSE (FALSE is implemented but not tested). Or you can provide a function with the same signature as AnalysisPageServer:::make.standard.ids that will generate IDs for you (this is also implemented but not tested). When annotate.plot is FALSE (for example, when a PNG is requested) the rownames are always left alone and make.standard.ids is not called.
skip.checks	Logical. By default (FALSE) your handler is run once on its default arguments, and it is checked that it makes an SVG and that the SVG can be annotated (if annotate.plot was set). This is important to get right, but doens't really need to be done during production—it just slows down the server start up.
plot.pars.transformer	A function to transform plot parameters. It should have the signature function(plot=list(), other=list()) and return a list. The first argument is the plot parameters extracted from the user request (these are the parameters like "width" and "height" that are not related to the business of the request but are simply passed through to the device function), and the second is all the other parameters from the user request. The functinon returns a (named) list of further arguments to pass to the device function. The main use for this is to set the image dimensions based on the user request. In that case your function would return a list with "width" and "height" elements. The units would be inches for svg plot. png plot uses pixel units, but if you add the parameter units="in" then you can use inches units. You can do this if "units" %in% names(formals(device)). The default plot.pars.transformer=NULL is to not transform the parameters at all.
annotate.data.frame	Logical, indicating whether your return value should be passed throuhg annotate.data.frame. Default: TRUE. several checks appropriate for the standard case of data associated with plotted regions.
numeric.sig.digs	Number of significant digits to which numeric columns in your data should be rounded. Default: 3. Set to NULL to not round (you could still round within your function if you wanted tighter control). "numeric" here means either that you set the a varMetadata "type" of the column to the string "numeric", or, if that is not available that is(column)[1] is "numeric". This means, in particular that integer columns will not be rounded.
no.plot	This page is meant to return data but no plot. Default: FALSE (it *is* expected to return a plot).
name	A name for the analysis page. Defaults to deparsing the handler argument. This meant to be an internal identifier for the page, only displayed to the user if label and description are unavailable.
label	A display label for the page. This should be 1-3 words, to fit in the navbar. Default: name.
description	A longer description for the page. This should be 1-2 sentences, to appear on rollover or in a summary page. Default: label
advanced	An integer. 0 means not advanced (always display the page). 1, 2, 3 are increasing levels of advanced (only display the page in advanced mode). Default: 0
thumbnail	A URL for a thumbnail to use when listing the page. NULL means to not store any thumbnail.
service	A logical, default FALSE. TRUE means that this page should only be called as a service and should not be rendered as a user page. This also means that the return value will not be processed at all except for JSON-encoding (unless of course you return an AnalysisPageResponse).
in.menu	A logical, default !service. TRUE means that the front-end should display this page in the menu. FALSE means that the front-end should not display the page in the menu, but should still be ready to render it, for example by app state link (contrast with service which the front end can't do anything with except provide a download link or use (as a service) to populate an input widget). The special condition service = FALSE, in.menu = TRUE builds a Page that the front end can use but doesn't show up in the menu. The combination of service = TRUE, in.menu = TRUE, doesn't make any sense and leads to an error.
paramset.transformer	A function which accepts a named list of parameter values as its first argument and possibly the AnalysisPage object as its second argument, and returns a named list of parameter values. This transformation is applied last, after the individual parameters have been transformed, if applicable, but (of course) before the handler is called. Or NULL (default) to not do this transformation. The purpose of this is to be able to encode some reusable logic here for groups of parameters which would often be used together but whose transformation is inter-dependent. If both this argument and plot.pars.transformer are supplied then this transformation is applied first.

Details

An AnalysisPage handler is a function that satistifies the following properties:

1. Can be called with no arguments and return a valid value (to be used for testing in the next steps; although this can be relaxed with skip.checks).

2. It creates a plot but does not open the device (although this can be relaxed with do.plot)

3. It returns a data.frame with x and y fields. Alternatively it may return an AnnotatedDataFrame. (although this can be relaxed with annotate.data.frame)

4. x and y fields are numeric.

5. The points in test plot can be successfully found (based on the x and y coordinates) and labeled.

This function throws an error if the argument does not satistfy one of these. Otherwise it returns void.

The function will be called once at the time of running this function (typically during registration) with all of its defaults to verify the second and third requirements.

The return value is a list of class "AnalysisPage" with the following components:

$handler

The handler function

$params

An AnalysisPageParamSet (see param.set )

$annotate.plot

An logical indicating whether the plots generated by the handler should be automatically annotated

$class.name

A character giving the class to be applied to the annotated SVG elements

A list will be built with the information necessary to render the page. It will contain the handler function in the $function slot, as well as a $params slot listing all of the parameters and their relevant information. The class name of "AnalysisPage" will be slapped on this object for good measure.

Value

See above

Author(s)

Brad Friedman

See Also

register.page, execute.handler, AnnotatedDataFrame

Examples

page <- new.analysis.page(AnalysisPageServer:::sine.handler)
registry <- register.page(new.registry(), "sine", page)
## Note: above is equivalent to the following:
## registry <- register.page(registry, "sine", AnalysisPageServer:::sine.handler)

apomatix/AnalysisPageServer documentation built on May 26, 2019, 11:36 a.m.