getStatistics: Get statistics

In primitybio/cellengine-r-toolkit: 'CellEngine' API Toolkit

Get statistics

Description

Retrieves statistics from FCS files, returning the results as a data frame.

Usage

getStatistics(
  experimentId,
  fcsFileIds = NULL,
  fcsFiles = NULL,
  channels = c(),
  statistics,
  compensationId,
  populationIds = NULL,
  populations = NULL,
  q = 0.5,
  percentOf = NULL,
  includeAnnotations = TRUE,
  layout = "medium"
)

Arguments

experimentId	ID of experiment.
fcsFileIds	IDs of FCS files. If specified, do not specify fcsFiles.
fcsFiles	Names of FCS files. An attempt will be made to find the files by name. If zero or more than one file exists with a given filename, an error will be thrown. If specified, do not specify fcsFileIds.
channels	Names of channels (for statistic types "mean", "median", "quantile", "stddev", "cv" and "mad"). Use channel short names, not reagents.
statistics	Statistics to export. Valid options: "mean", "median", "quantile", "stddev", "cv", "eventcount", "percent", "mad", "geometricmean".
compensationId	Compensation to apply. May be an ID, cellengine::UNCOMPENSATED or cellengine::FILE_INTERNAL.
populationIds	IDs of populations. If specified, do not specify populations.
populations	Names of populations. An attempt will be made to find the population by name. If zero or more than one population exists with the name, an error will be thrown. If specified, do not specify populationIds.
q	Quantile to calculate for "quantile" statistic, in the range 0 to 1.
percentOf	Single population ID or name, or list of population IDs or names. If omitted or the string "PARENT", then the percent of parent will be calculated for each population. If a single ID or name is provided, then the percent of that population will be calculated for each population specified in populations or populationIds (useful for calculating e.g. percent of singlets or leukocytes). If an array of IDs, "PARENT" or names is provided, then the percent of each of those populations will be calculated. In the latter two cases, if a name or list of names instead of IDs are provided, an attempt will be made to find those populations by name. IDs are detected as matching a 24-character string comprised of the characters A-Fa-f0-9.
includeAnnotations	Includes FCS file annotations in the returned data frame.
layout	One of the following: "tall-skinny": One row/object per combination of FCS file, population, statistic and channel. "medium": (default) One row/object per combination of FCS file, population and channel. Separate column/property for each statistic. "short-wide": One row/object per FCS file. One column/property per combination of population, statistic and channel. This format is not readily machine-readable and does not include

Details

The quick syntax accepts FCS files and populations by names. This is often easier to use, but is slower to execute because additional API requests and validation logic must be run. Thus, for performance-critical applications, provide IDs instead of names in the fcsFileIds, populationIds and percentOf parameters. IDs are also guaranteed to reference unique files and populations, while names may be non-unique, in which case an error will be raised.

Specify neither fcsFileIds nor fcsFiles to calculate statistics for all non-control FCS files.

Value

Statistics as a data frame, including file annotations and information about the statistics such as the channel name and population.

Examples

## Not run: 
# Quick syntax, using population names and file names instead of IDs:
fcsFiles <- c("file1.fcs")
channels <- c("SSC-A", "YG780/60-A")
statistics <- c("median", "mean", "quantile", "percent")
populations <- c("Leukocytes")
stats <- getStatistics(experimentId,
  fcsFiles = fcsFiles, channels = channels,
  statistics = statistics, populations = populations, q = 0.95,
  compensationId = cellengine::FILE_INTERNAL
)
# Returns a data.frame of statistics, including the file annotations.
# Because percentOf is not specified, "percent" will be percent of parent.

# Explicit syntax, using IDs instead of population and file names:
fcsFileIds <- c("9ab5c6d7a8cf24a5c4f9a6c2")
statistics <- c("percent")
populationIds <- c("9ab5c6d7a8cf24a5c4f9face")
stats <- getStatistics(experimentId,
  fcsFileIds = fcsFileIds,
  statistics = statistics, populationIds = populationIds,
  compensationId = cellengine::UNCOMPENSATED
)

# Percent of ungated:
getStatistics(experimentId,
  fcsFileIds = fcsFileIds, statistics = statistics,
  populationIds = populationIds, compensationId = cellengine::UNCOMPENSATED,
  percentOf = cellengine::UNGATED
)

## End(Not run)

primitybio/cellengine-r-toolkit documentation built on Oct. 19, 2024, 1:17 a.m.