lotrrs {gateR}

A single gate for two conditions

Description

Estimates a ratio of relative risk surfaces and computes the asymptotic p-value surface for a single gate with two conditions. Includes 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

lotrrs(
  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,
  c2n = NULL,
  win = NULL,
  ...,
  doplot = lifecycle::deprecated(),
  verbose = lifecycle::deprecated()
)

Arguments

dat

Input data frame flow cytometry data with five (5) features (columns): 1) ID, 2) Condition A ID, 3) Condition B ID, 4) Marker A as x-coordinate, 5) 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.

c2n

Optional, character. The name of the level for the numerator of condition B. 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 ratio of relative risk surfaces and computes the asymptotic p-value surface for a single gate with two conditions using three successive risk functions. A relative risk surface is estimated for Condition A at each level of Condition B, and then a ratio of the two relative risk surfaces is computed.

RR_{Condition B1} = \frac{Condition A2 of B1}{Condition A1 of B1}

RR_{Condition B2} = \frac{Condition A2 of B2}{Condition A1 of B2}

ln(rRR) = ln\left (\frac{RR_{Condition B2}}{CRR_{Condition B2}}\right )

The p-value surface of the ratio of relative risk surfaces is estimated assuming asymptotic normality of the ratio value at each gridded knot. The bandwidth is fixed across all layers. 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 two condition variables (Condition A and Condition B) within dat must be of class 'factor' with two levels. The first level in each variable is considered the numerator (i.e., "case") value, and the second level is considered the denominator (i.e., "control") value. The levels can also be specified using the c1n and c2n parameters.

Value

An object of class 'list' where each element is a object of class 'rrs' created by the risk function with two additional components:

rr

An object of class 'im' with the relative risk surface.

f

An object of class 'im' with the spatial density of the numerator.

g

An object of class 'im' with the spatial density of the denominator.

P

An object of class 'im' with the asymptotic p-value surface.

lrr

An object of class 'im' with the log relative risk surface.

alpha

A numeric value for the alpha level used within the gate.

Examples

test_lotrrs <- lotrrs(dat = randCyto)