cytoframe: 'cytoframe': A reference class for efficiently managing the...

In RGLab/flowWorkspace: Infrastructure for representing and interacting with gated and ungated cytometry data sets.

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), cytoframes 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 forcytoframe 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

RGLab/flowWorkspace documentation built on March 17, 2024, 2:24 p.m.