cytoframe {flowWorkspace} | R Documentation

## `cytoframe`: A reference class for efficiently managing the data representation of a `flowFrame`

### Description

This class serves the same purpose as the `flowFrame` class from the `flowCore` package: to store quantitative data on cell populations from a single FCS run. The primary difference is in the underlying representation of the data. While `flowFrame` objects store the underlying data matrix in the `exprs` slot as an R object, `cytoframe` objects store the matrix (as well as the data from the other slots) in a C data structure that is accessed through an external pointer. This allows for greater optimization of data operations including I/O, parsing, transformation, and gating.

### Details

From the user's standpoint, interacting with a `cytoframe` is very similar to interacting with a `flowframe`, with one important difference. While operations such as subsetting or copying a `flowFrame` using the standard R assignment operator (<-) will perform a deep copy of the data in its slots, the same operations on a `cytoframe` will produce a view to the same underlying data as the original object. This means that changes made to the `cytoframe` resulting from subsetting or copying will affect the original `cytoframe`. If a deep copy of the underyling data is desired, the `realize_view` method will accomplish this.

Because the `cytoframe` class inherits from `flowFrame`, the `flowFrame` slots are present but not utilized. Thus, attempting to access them directly will yield empty data structures. However, the `exprs`, `parameters`, or `description` methods work in a manner similar to a `flowFrame` by accessing the same information from the underlying data structure.

### Methods

Many of the methods here have their own documentation pages or are more extensively explained in the documentation for `flowFrame`, so those documentation pages may be consulted as well for more details.

`[`

  Subsetting. Returns an object of class `cytoframe`. The syntax for subsetting is similar to that of `data.frames`. In addition to the usual index vectors (integer and logical by position, character by parameter names), `cytoframe`s can be subset via `filterResult` and `filter` objects.

  Usage:
  `cytoframe[i,j]`
  `cytoframe[filter,]`
  `cytoframe[filterResult,]`
  Note that the value of argument `drop` is ignored when subsetting `cytoframes`.

$

  Subsetting by channel name. This is similar to subsetting of columns of `data.frames`, i.e., `frame$FSC.H` is equivalent to `frame[, "FSC.H"]`. Note that column names may have to be quoted if they are not valid R symbols (e.g. `frame$"FSC-H"` or `frame$`FSC-H``).

exprs, exprs<-

  `exprs` returns an object of class `matrix` containing the measured intensities. Rows correspond to cells, columns to the different measurement channels. The `colnames` attribute of the matrix should hold the names or identifiers for the channels. The `rownames` attribute would usually not be set.
  `exprs<-` replaces the raw data intensities. The replacement value must be a numeric matrix with `colnames` matching the parameter definitions. Implicit subsetting is allowed (i.e. less columns in the replacement value compared to the original `cytoframe`), but all columns must be defined in the original `cytoframe`.
  Usage:
  `exprs(cytoframe)`
  `exprs(cytoframe) <- value`

head, tail

  Show first/last elements of the raw data matrix
  Usage:
  `head(cytoframe)`
  `tail(cytoframe)`

keyword, keyword<-

  Extract all entries or a single entry from the annotations by keyword or replace the entire list of key/value pairs with a new named list. See `keyword` for details.
  Usage:
  `keyword(cytoframe)`
  `keyword(cytoframe, character)`
  `keyword(cytoframe) <- list(value)`

parameters, parameters<-

  Extract parameters and return an object of class `AnnotatedDataFrame` containing information about each column of the `cytoframe`, or replace such an object.
  This information will generally be filled in by `load_cytoframe_from_fcs` or similar functions using data from the FCS keywords describing the parameters. To access the actual parameter annotation, use `pData(parameters(cytoframe))`.
  Replacement is only valid with `AnnotatedDataFrames` containing all varLabels `name`, `desc`, `range`, `minRange` and `maxRange`, and matching entries in the `name` column to the colnames of the `exprs` matrix. See `parameters` for more details.
  Usage:
  `parameters(cytoframe)`
  `parameters(cytoframe) <- value`

show

  Display details about the `cytoframe` object.

summary

  Return descriptive statistical summary (min, max, mean and quantile) for each channel
  Usage:
  `summary(cytoframe)`

plot

  Basic plots for `cytoframe` objects. If the object has only a single parameter this produces a `histogram`. For exactly two parameters we plot a bivariate density map (see `smoothScatter`) and for more than two parameters we produce a simple `splom` plot. To select specific parameters from a `flowFrame` for plotting, either subset the object or specify the parameters as a character vector in the second argument to `plot`. The smooth parameters lets you toggle between density-type `smoothScatter` plots and regular scatterplots. For far more sophisticated plotting of flow cytometry data, see the `ggcyto` package.
  Usage:
  `plot(cytoframe, ...)`
  `plot(cytoframe, character, ...)`
  `plot(cytoframe, smooth=FALSE, ...)`

ncol, nrow, dim

  Extract the dimensions of the data matrix.
  Usage:
  `ncol(cytoframe)`
  `nrow(cytoframe)`
  `dim(cytoframe)`

featureNames, colnames, colnames<-

  `colnames` and `featureNames` are synonyms. They extract parameter names (i.e., the colnames of the data matrix). For `colnames` there is also a replacement method. This will update the `name` column in the `parameters` slot as well.
  Usage:
  `featureNames(cytoframe)`
  `colnames(cytoframe)`
  `colnames(cytoframe) <- value`

markernames, markernames<-

  Access or replace the marker names associated with the channels of the `cytoframe`. For replacement, `value` should be a named list or character vector where the names correspond to the channel names and the values correpond to the marker names.
  Usage:
  `markernames(object)`
  `markernames(object) <- value`

names

  Extract pretty formatted names of the parameters including parameter descriptions.
  Usage:
  `names(cytoframe)`

identifier

  Extract GUID of a `cytoframe`. Returns the file name if no GUID is available. See `identifier` for details.
  Usage:
  `identifier(cytoframe)`

range

  Get instrument or actual data range of the `cytoframe`. Note that instrument dynamic range is not necessarily the same as the range of the actual data values, but the theoretical range of values the measurement instrument was able to capture. The values of the dynamic range will be transformed when using the transformation methods for`cytoframe` objects.
  Parameters:
  x: cytoframe object.
  type: Range type. either "instrument" or "data". Default is "instrument"
  Usage:
  `range(x, type = "data")`

each_row, each_col

  Apply functions over rows or columns of the data matrix. These are convenience methods. See `each_col` for details.
  Usage:
  `each_row(cytoframe, function, ...)`
  `each_col(cytoframe, function, ...)`

transform

  Apply a transformation function on a `cytoframe` object. This uses R's `transform` function by treating the `cytoframe` like a regular `data.frame`. `flowCore` provides an additional inline mechanism for transformations (see `%on%`) which is strictly more limited than the out-of-line transformation described here.
  Usage:
  `transform(cytoframe, translist, ...)`

filter

  Apply a `filter` object on a `cytoframe` object. This returns an object of class `filterResult`, which could then be used for subsetting of the data or to calculate summary statistics. See `filter` for details.
  Usage:
  `filter(cytoframe, filter)`

split

  Split `cytoframe` object according to a `filter`, a `filterResult` or a `factor`. For most types of filters, an optional `flowSet=TRUE` parameter will create a `flowSet` rather than a simple list. See `split` for details.
  Usage:
  `split(cytoframe, filter, flowSet=FALSE, ...)`
  `split(cytoframe, filterResult, flowSet=FALSE, ...)`
  `split(cytoframe, factor, flowSet=FALSE, ...)`

Subset

  Subset a `cytoframe` according to a `filter` or a logical vector. The same can be done using the standard subsetting operator with a `filter`, `filterResult`, or a logical vector as first argument.
  Usage:
  `Subset(cytoframe, filter)`
  `Subset(cytoframe, logical)`

cbind2

  Not yet implemented.
  Expand a `cytoframe` by the data in a `numeric matrix` of the same length. The `matrix` must have column names different from those of the `cytoframe`. The additional method for `numerics` only raises a useful error message.
  Usage:
  `cbind2(cytoframe, matrix)`
  `cbind2(cytoframe, numeric)`

compensate

  Apply a compensation matrix (or a `compensation` object) on a `cytoframe` object. This returns a compensated `cytoframe`.
  Usage:
  `compensate(cytoframe, matrix)`
  `compensate(cytoframe, data.frame)`
  `compensate(cytoframe, compensation)`

decompensate

  Not yet implemented.
  Reverse the application of a compensation matrix (or a `compensation` object) on a `cytoframe` object. This returns a decompensated `cytoframe`.
  Usage:
  `decompensate(cytoframe, matrix)`
  `decompensate(cytoframe, data.frame)`

spillover

  Extract spillover matrix from description slot if present. It is equivalent to `keyword(x, c("spillover", "SPILL"))` Thus will simply return a list of keyword values for "spillover" and "SPILL".
  Usage:
  `spillover(cytoframe)`

realize_view

  Returns a new `cytoframe` with its own copy of the underlying data (a deep copy). The optional `filepath` argument accepts a string to specify a full filename for storing the new copy of the data in h5 format.
  Usage:
  `realize_view(cytoframe, filepath)`

### See Also

`flowSet`, `read.FCS`

[Package flowWorkspace version 4.4.0 Index]