prepData: Data preparation
In CATALYST: Cytometry dATa anALYSis Tools

Description Usage Arguments Details Value Author(s) Examples

Data preparation

prepData(
  x,
  panel = NULL,
  md = NULL,
  features = NULL,
  transform = TRUE,
  cofactor = 5,
  panel_cols = list(channel = "fcs_colname", antigen = "antigen", class =
    "marker_class"),
  md_cols = list(file = "file_name", id = "sample_id", factors = c("condition",
    "patient_id")),
  by_time = TRUE,
  FACS = FALSE
)

`x`	a `flowSet` holding all samples or a path to a set of FCS files.
`panel`	a data.frame containing, for each channel, its column name in the input data, targeted protein marker, and (optionally) class ("type", "state", or "none"). If 'panel' is unspecified, it will be constructed from the first input sample via `guessPanel`.
`md`	a table with column describing the experiment. An exemplary metadata table could look as follows: `file_name`: the FCS file name `sample_id`: a unique sample identifier `patient_id`: the patient ID `condition`: brief sample description (e.g. reference/stimulated, healthy/diseased) If 'md' is unspecified, the `flowFrame/Set` `identifier`(s) will be used as sample IDs with no additional metadata factors.
`features`	a logical vector, numeric vector of column indices, or character vector of channel names. Specified which column to keep from the input data. Defaults to the channels listed in the input panel.
`transform`	logical. Specifies whether an arcsinh-transformation with cofactor cofactor should be performed, in which case expression values (transformed counts) will be stored in assay(x, "exprs").
`cofactor`	numeric cofactor(s) to use for optional arcsinh-transformation when `transform = TRUE`; single value or a vector with channels as names.
`panel_cols`	a names list specifying the `panel` column names that contain channel names, targeted protein markers, and (optionally) marker classes. When only some `panel_cols` deviate from the defaults, specifying only these is sufficient.
`md_cols`	a named list specifying the column names of `md` that contain the FCS file names, sample IDs, and factors of interest (batch, condition, treatment etc.). When only some `md_cols` deviate from the defaults, specifying only these is sufficient.
`by_time`	logical; should samples be ordered by acquisition time? Ignored if `!is.null(md)` in which case samples will be ordered as they are listed in `md[[md_cols$file]]`. (see details)
`FACS`	logical; is this FACS / flow cytometry data? By default, `prepData` moves non-mass channels to the output SCE's `int_colData`; `FACS = TRUE` assures that all channels are kept as `assay` data. If `FALSE`, `prepData` will try and access the input `flowFrame/Set`'s `"$CYT"` descriptor (`keyword(., "$CYT")`) to determine the data type; this may be inaccurate for some cytometer descriptors.

By default, non-mass channels (e.g., time, event lengths) will be removed from the output SCE's assay data and instead stored in the object's internal cell metadata (int_colData) to assure these data are not subject to transformationsor other computations applied to the assay data.

For more than 1 sample, prepData will concatenate cells into a single SingleCellExperiment object. Note that cells will hereby be order by "Time", regardless of whether by_time = TRUE or FALSE. Instead, by_time determines the sample (not cell!) order; i.e., whether samples should be kept in their original order, or should be re-ordered according to their acquision time stored in keyword(flowSet, "$BTIM").

When a metadata table is specified (i.e. !is.null(md)), argument by_time will be ignored and sample ordering is instead determined by md[[md_cols$file]].

a SingleCellExperiment.

Helena L Crowell helena.crowell@uzh.ch

data(PBMC_fs, PBMC_panel, PBMC_md)
prepData(PBMC_fs, PBMC_panel, PBMC_md)

# channel-specific transformation
cf <- sample(seq_len(10)[-1], nrow(PBMC_panel), TRUE)
names(cf) <- PBMC_panel$fcs_colname
sce <- prepData(PBMC_fs, cofactor = cf)
int_metadata(sce)$cofactor

# input has different name for "condition"
md <- PBMC_md
m <- match("condition", names(md))
colnames(md)[m] <- "treatment"

# add additional factor variable batch ID
md$batch_id <- sample(c("A", "B"), nrow(md), TRUE)

# specify 'md_cols' that differ from defaults
factors <- list(factors = c("treatment", "batch_id"))
ei(prepData(PBMC_fs, PBMC_panel, md, md_cols = factors))

# without panel & metadata tables
sce <- prepData(raw_data)

# 'flowFrame' identifiers are used as sample IDs
levels(sce$sample_id)

# panel was guess with 'guessPanel';
# non-mass channels are set to marker class "none"
rowData(sce)