rrs: A single gate for a single condition
In gateR: Flow/Mass Cytometry Gating via Spatial Kernel Density Estimation

View source: R/rrs.R

rrs	R Documentation

A single gate for a single condition

Description

Estimates a relative risk surface and computes the asymptotic p-value surface for a single gate with a single condition, including features for basic visualization. This function is used internally within the gating function to extract the points within the significant areas. This function can also be used as a standalone function.

Usage

rrs(
  dat,
  bandw = NULL,
  alpha = 0.05,
  p_correct = "none",
  nbc = NULL,
  plot_gate = FALSE,
  save_gate = FALSE,
  name_gate = NULL,
  path_gate = NULL,
  rcols = c("#FF0000", "#CCCCCC", "#0000FF"),
  lower_lrr = NULL,
  upper_lrr = NULL,
  c1n = NULL,
  win = NULL,
  ...,
  doplot = lifecycle::deprecated(),
  verbose = lifecycle::deprecated()
)

Arguments

`dat`	Input data frame flow cytometry data with four (4) features (columns): 1) ID, 2) Condition A ID, 3) Marker A as x-coordinate, 4) Marker B as y-coordinate.
`bandw`	Optional, numeric. Fixed bandwidth for the kernel density estimation. Default is based on the internal `[sparr]{OS}` function.
`alpha`	Numeric. The two-tailed alpha level for significance threshold (default is 0.05).
`p_correct`	Optional. Character string specifying whether to apply a correction for multiple comparisons including a False Discovery Rate `p_correct = "FDR"`, a spatially dependent Sidak correction `p_correct = "correlated Sidak"`, a spatially dependent Bonferroni correction `p_correct = "correlated Bonferroni"`, an independent Sidak correction `p_correct = "uncorrelated Sidak"`, an independent Bonferroni correction `p_correct = "uncorrelated Bonferroni"`, and a correction based on Random Field Theory using an equation by Adler and Hasofer `p_correct = "Adler and Hasofer"` or an equation by Friston et al. `p_correct = "Friston"`. If `p_correct = "none"` (the default), then no correction is applied.
`nbc`	Optional. An integer for the number of bins when `p_correct = "correlated"`. Similar to `nbclass` argument in `modified.ttest`. The default is 30.
`plot_gate`	Logical. If `TRUE`, the output includes basic data visualization.
`save_gate`	Logical. If `TRUE`, the output saves the visualization as a separate PNG file.
`name_gate`	Optional, character. The filename of the visualization. The default is "gate".
`path_gate`	Optional, character. The path of the visualization. The default is the current working directory.
`rcols`	Character string of length three (3) specifying the colors for: 1) group A (numerator), 2) neither, and 3) group B (denominator) designations. The defaults are `c("#FF0000", "#cccccc", "#0000FF")` or `c("red", "grey80", "blue")`.
`lower_lrr`	Optional, numeric. Lower cut-off value for the log relative risk value in the color key (typically a negative value). The default is no limit, and the color key will include the minimum value of the log relative risk surface.
`upper_lrr`	Optional, numeric. Upper cut-off value for the log relative risk value in the color key (typically a positive value). The default is no limit, and the color key will include the maximum value of the log relative risk surface.
`c1n`	Optional, character. The name of the level for the numerator of condition A. The default is NULL, and the first level is treated as the numerator.
`win`	Optional. Object of class `owin` for a custom two-dimensional window within which to estimate the surfaces. The default is NULL and calculates a convex hull around the data.
`...`	Arguments passed to `risk` to select resolution.
`doplot`	`doplot` is no longer supported and has been renamed `plot_gate`.
`verbose`	`verbose` is no longer supported; this function will not display verbose output from internal `risk` function.

Details

This function estimates a relative risk surface and computes the asymptotic p-value surface for a single gate and single condition using the risk function. Bandwidth is fixed across both layers (numerator and denominator spatial densities). Basic visualization is available if plot_gate = TRUE.

Provides functionality for a correction for multiple testing. If p_correct = "FDR", calculates a False Discovery Rate by Benjamini and Hochberg. If p_correct = "uncorrelated Sidak", calculates an independent Sidak correction. If p_correct = "uncorrelated Bonferroni", calculates an independent Bonferroni correction. If p_correct = "correlated Sidak" or if p_correct = "correlated Bonferroni", then the corrections take into account the into account the spatial correlation of the surface. (NOTE: If p_correct = "correlated Sidak" or if p_correct = "correlated Bonferroni", it may take a considerable amount of computation resources and time to calculate). If p_correct = "Adler and Hasofer" or if p_correct = "Friston", then calculates a correction based on Random Field Theory. If p_correct = "none" (the default), then the function does not account for multiple testing and uses the uncorrected alpha level. See the internal pval_correct function documentation for more details.

The condition variable (Condition A) within dat must be of class 'factor' with two levels. The first level is considered the numerator (i.e., "case") value, and the second level is considered the denominator (i.e., "control") value. The level can also be specified using the c1n parameter.