new.analysis.page {AnalysisPageServer} | R Documentation

## new.analysis.page

### 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)

[Package AnalysisPageServer version 1.20.0 Index]