getDynamicRange {cellHTS2} | R Documentation

## Per-plate dynamic range of a cellHTS object

### Description

Calculates per-plate dynamic range of data stored in a `cellHTS` object.

### Usage

    getDynamicRange(x,
    verbose=interactive(),
    definition,
    posControls,
    negControls)

### Arguments

`x` | a configured `cellHTS` object. See details.
`verbose` | a logical, if `TRUE` the function reports some of its intermediate progress. The default is the state of `interactive()`.
`definition` | a character string with possible values "ratio" or "difference". See details.
`posControls` | (optional) a list or vector of regular expressions specifying the name of the positive controls. See details.
`negControls` | (optional) a vector of regular expressions specifying the name of the negative controls. See details.

### Details

`x` should be an already configured `cellHTS` object (`state(x)["configured"]=TRUE`), so that the information about the well annotation of the plates is available.

The per-plate dynamic ranges are calculated for the data stored in slot `assayData` of `x`. This can be raw data, normalized data or scored data.

If `definition="difference"`, the dynamic range is calculated as the absolute difference between the arithmetic average on positive and negative controls.

If `definition="ratio"`, the dynamic range is calculated as the ratio between the geometric mean on positive and negative controls.

NOTE: the argument `definition` should only be set to `"ratio"` if data are in positive scale!

If `definition` is missing it is determined based on the scale of the data. By default, if data are in positive scale, definition is set to `"ratio"`, otherwise, it is set to `"difference`.

`posControls` and `negControls` should be given as a vector of regular expression patterns specifying the name of the positive(s) and negative(s) controls, respectivey, as provided in the plate configuration file (and accessed via `wellAnno(x)`). The length of these vectors should be equal to the current number of channels in `x` (`dim(Data(x))[3]`). By default, if `posControls` is not given, `pos` will be taken as the name for the wells containing positive controls. Similarly, if `negControls` is missing, by default `neg` will be considered as the name used to annotated the negative controls. The content of `posControls` and `negControls` will be passed to `regexpr` for pattern matching within the well annotation given in `wellAnno(x)` (see examples). If no controls are available for a given channel, use `""` or `NA` for that channel. For example, `posControls = c("", "(?i)^diap$")` means that channel 1 has no positive controls, while `diap` is the positive control for channel 2.

The arguments `posControls` and `negControls` are particularly useful in multi-channel data since the controls might be reporter-specific, or after normalizing multi-channel data.

If there are different positive controls, the dynamic range is calculated between each of the positive controls and the negative controls.

In the case of a two-way assay, where two types of "positive" controls are used in the screen ("activators" and "inhibitors"), `posControls` should be defined as a list with two components (called `act` and `inh`), each of which should be vectors of regular expressions of the same length as the current number of reporters (as explained above). The dynamic range is calculated between each type of positive control (`activators` or `inhibitors`) and the negative controls.

### Value

The function generates a list with the per-plate dynamic ranges in each channel and each replicate. The average dynamic range between replicates is also given. Each element of this list is an array of dimensions `nrPlates x (nrReplicates + 1) x nrChannels`, and is named by the positive controls. In the case of a two-way assay, these elements are called `activators` and `inhibitors`, while for a one-way assay, the elements have the same name of the positive controls. See Examples section.

### Author(s)

Ligia P. Bras ligia@ebi.ac.uk

### References

Boutros, M., Bras, L.P. and Huber, W. (2006) Analysis of cell-based RNAi screens, Genome Biology 7, R66.

### See Also

`configure`, `writeReport`

### Examples

        data(KcViabSmall)
        ## pCtrls <- c("pos")
        ## nCtrls <- c("neg")
        ## or for safety reasons (not a problem for the current well annotation, however)
        pCtrls <- c("^pos$")
        nCtrls <- c("^neg$")
        dr <- getDynamicRange(KcViabSmall, definition="ratio", posControls=pCtrls, negControls=nCtrls)
        ## same as:
        ## getDynamicRange(KcViabSmall)

        x <- normalizePlates(KcViabSmall, scale="multiplicative", log=TRUE, method="median", varianceAdjust="none")
        try(drn <- getDynamicRange(x, definition="ratio"))
        drn <- getDynamicRange(x, definition="difference")

[Package cellHTS2 version 2.4.1 Index]