CytobankAPI (version 2.2.0)

statistics: Statistic Endpoints

Description

Interact with statistic endpoints. Gather data about event counts and general channel statistics. Create dataframes of statistics to help with visualization and downstream analysis.

Usage

# S4 method for UserSession
statistics.event_counts(
  UserSession,
  experiment_id,
  gate_version = -1,
  compensation_id,
  fcs_files,
  populations = c(),
  output = "dataframe",
  timeout = UserSession@long_timeout
)
# S4 method for UserSession
statistics.general(
  UserSession,
  experiment_id,
  gate_version = -1,
  compensation_id,
  fcs_files,
  channels,
  populations = c(),
  output = "dataframe_row",
  timeout = UserSession@long_timeout
)

Arguments

UserSession

Cytobank UserSession object

experiment_id

integer representing an experiment ID

gate_version

integer representing an experiment gate version, an integer of -1 corresponds to the state of gates and populations in the gating interface. Faster performance can be achieved by using the maximum gate version from the experiment (learn more about gate versions). Maximum gate version can be seen as the gateVersion attribute returned from a call to the Show Experiment Details endpoint [optional]

compensation_id

integer representing a compensation ID (use -2 for file-internal compensation, -1 for uncompensated)

fcs_files

vector/list of integers representing a list of FCS file IDs

populations

vector/list of integers representing a list of population IDs to calculate statistics for. This is the gateSetId attribute of a population object. Another term for a population is a "gate set". If not specified, all population statistics will be fetched [optional]

output

character representing the output format [optional]
- statistics.event_counts: ("default" [default], "dataframe")
- statistics.general: ("default", "dataframe_col", "dataframe_row")
- dataframe: converts the output to a dataframe for the event count statistics
- dataframe_col: for statistics data on multiple channels, proliferate channel statistics as columns
- dataframe_row: for statistics data on multiple channels, proliferate channel statistics as rows

timeout

integer representing the request timeout time in seconds

channels

vector/list of integers or character representing a list of channel IDs (integers) or long channel names (character)

Details

statistics.event_counts Get event count statistics from an experiment. In the absence of channel information, only event count data are returned. If only event count data are needed, this approach can be faster than retrieving all statistics by avoiding unnecessary computation.
- Optional output parameter, specify one of the following: ("full", "dataframe" [default])
- dataframe: converts the output to a dataframe for the event count statistics

statistics.general Get a batch of common statistics for specific channels on populations from an experiment.
- Optional output parameter, specify one of the following: ("full", "dataframe_col", "dataframe_row" [default])
- dataframe_col: for statistics data on multiple channels, proliferate channel statistics as columns
- dataframe_row: for statistics data on multiple channels, proliferate channel statistics as rows

Examples

if (FALSE) # Authenticate via username/password
cyto_session <- authenticate(site="premium", username="cyril_cytometry", password="cytobank_rocks!")
# Authenticate via auth_token
cyto_session <- authenticate(site="premium", auth_token="my_secret_auth_token")

if (FALSE) statistics.event_counts(cyto_session, 22, compensation_id=-2,
  fcs_files=c(12, 13, 14), channels=c(53, 54, 55), populations=c(32, 33, 34))

if (FALSE) # Full list with all fields present
statistics.general(cyto_session, 22, compensation_id=-2,
  fcs_files=c(12, 13, 14), channels=c(53, 54, 55), populations=c(32, 33, 34))

# Statistics list transformed into a dataframe, proliferating channel statistics by column
statistics.general(cyto_session, 22, compensation_id=-2,
  fcs_files=c(12, 13, 14), channels=c(53, 54, 55), populations=c(32, 33), output="dataframe_col")

# Statistics list transformed into a dataframe, proliferating channel statistics by row
statistics.general(cyto_session, 22, compensation_id=-2,
  fcs_files=c(12, 13, 14), channels=c(53, 54, 55), populations=c(32, 33), output="dataframe_row")

# Statistics list transformed into a dataframe, using helper functions (names_to_ids)
# Get FCS files that match 'pbmc' in their filename
fcs_files <- fcs_files.list(cyto_session, 22)
fcs_files <- fcs_files[,c("id", "filename")]
fcs_files <- unlist(fcs_files$id[grep("pbmc", fcs_files$filename)])

# Get channels that match 'pp' or 'pStat' as their longName
channels <- panels.list(cyto_session, 22)$`Panel 1`$channels
channels <- channels[,c("normalizedShortNameId", "shortName", "longName")]
channels <- channels$normalizedShortNameId[grep("pp.*|pStat.*", channels$longName)]

# Get populations that match 'CD' as their population name
populations <- populations.list(cyto_session, 22)
populations <- populations[,c("gateSetId", "name")]
populations <- populations$id[grep("CD.*", populations$name)]

statistics.general(cyto_session, 22, compensation_id=-2,
  fcs_files=fcs_files, channels=channels, populations=populations, output="dataframe_row")