gate_tail: Gates the tail of a density using the derivative of a kernel...

In openCyto: Hierarchical Gating Pipeline for flow cytometry data

Description

These methods aim to set a one-dimensional gate (cutpoint) near the edge of a peak in the density specified by a channel of a flowFrame to isolate the tail population. They allow two approaches to do this, both beginning by obtaining a smoothened kernel density estimate (KDE) of the original density and then utilizing either its first or second derivative.

We determine a gating cutpoint using either the first or second derivative of the kernel density estimate (KDE) of the x.

Usage

gate_tail(
  fr,
  channel,
  filterId = "",
  num_peaks = 1,
  ref_peak = 1,
  strict = TRUE,
  tol = 0.01,
  side = "right",
  min = NULL,
  max = NULL,
  bias = 0,
  positive = TRUE,
  ...
)

.cytokine_cutpoint(
  x,
  num_peaks = 1,
  ref_peak = 1,
  method = c("first_deriv", "second_deriv"),
  tol = 0.01,
  adjust = 1,
  side = "right",
  strict = TRUE,
  plot = FALSE,
  auto_tol = FALSE,
  ...
)

Arguments

fr	a flowFrame object
channel	the channel from which the cytokine gate is constructed
filterId	the name of the filter
num_peaks	the number of peaks expected to see. This effectively removes any peaks that are artifacts of smoothing
ref_peak	After num_peaks are found, this argument provides the index of the reference population from which a gate will be obtained. By default, the peak farthest to the left is used.
strict	logical when the actual number of peaks detected is less than ref_peak. an error is reported by default. But if strict is set to FALSE, then the reference peak will be reset to the peak of the far right.
tol	the tolerance value
side	On which side of the density do we want to gate the tail. Valid options are "left" or "right".
min	a numeric value that sets the lower boundary for data filtering
max	a numeric value that sets the upper boundary for data filtering
bias	a numeric value that adds a constant to the calculated cutpoint(threshold). Default is 0.
positive	If FALSE, after finding the cutpoint, the rectangleGate returned will have bounds (-Inf, a] as opposed to [a, Inf). This argument will be ignored if gate_tail is used in a gatingTemplate with gt_gating or via gs_add_gating_method. In those cases, pop = "-" should be used instead.
...	additional arguments passed to .deriv_density
x	a numeric vector used as input data
method	the method used to select the cutpoint. See details.
adjust	the scaling adjustment applied to the bandwidth used in the first derivative of the kernel density estimate
plot	logical specifying whether to plot the peaks found 'right' (default) or 'left'?
auto_tol	when TRUE, it tries to set the tolerance automatically.

Details

The default behavior of the first approach, specified by method = "first_deriv", finds valleys in the first derivative of the KDE and uses the lowest such valley to place the cutpoint on the steep right shoulder of the largest peak in the original density.

The default behavior of the second approach, specified by method = "second_deriv", is to find peaks in the second derivative of the KDE and use the largest such peak to place the cutpoint at the point on the right shoulder of the largest peak in the original density where it is most rapidly flattening (the first derivative is rapidly growing less negative).

Both approaches can be significantly modified from defaults with a number of optional arguments. The num_peaks argument specifes how many peaks should be found in the smoothened KDE and ref_peak specifies around which peak the gate's cutpoint should be placed (starting from the leftmost peak). Setting the side argument to "left" modifies the procedure to put the cutpoint on the left side of the reference peak to isolate a left tail. The max and min arguments allow for pre-filtering extreme values in the channel of interest (keeping only observations with channel values less than max and/or more than min). The bandwidth used for kernel density estimation can be proportionally scaled using adjust (e.g. adjust = 0.5 will use a bandwidth that is half of the default). This allows for tuning the level of smoothing applied in the estimation.

Lastly, the tol, auto_tol, and bias arguments allow for adjustments to be made to the cutpoint that would otherwise be returned. tol provides a tolerance value that the absolute value of the KDE derivative at the cutpoint must be under. If the derivative at the original cutpoint is greater than tol in magnitude, the returned cutpoint will be the first point to the right of the original cutpoint (or to the left in the case of side = "left") with corresponding derivative within tol. Thus in practice, a smaller value for tol effectively pushes the cutpoint further down the shoulder of the peak towards the flat tail. tol is set to 0.01 by default but setting auto_tol = TRUE will set the tolerance to a reasonable estimate of 1% of the maximum absolute value of the first derivative of the KDE. tol and auto_tol are only used for method = "first_deriv". Additionally, the bias argument allows for directly shifting the returned cutpoint left or right.

It is also possible to pass additional arguments to control the calculation of the derivative, which will have some effect on the resulting cutpoint determination, but this should usually not be needed. By default the number of grid points for the derivative calculation will be 10,000, but this can be changed with num_points. The default bandwidth can also be directly adjusted with bandwidth, where the final value used will be given by adjust*bandwidth

By default, we compute the first derivative of the kernel density estimate. Next, we determine the lowest valley from the derivative, which corresponds to the density's mode for cytokines. We then contruct a gating cutpoint as the value less than the tolerance value tol in magnitude and is also greater than the lowest valley.

Alternatively, if the method is selected as second_deriv, we select a cutpoint from the second derivative of the KDE. Specifically, we choose the cutpoint as the largest peak of the second derivative of the KDE density which is greater than the reference peak.

Value

a filterList containing the gates (cutpoints) for each sample with the corresponding rectangleGate objects defining the tail as the positive population.

the cutpoint along the x-axis

Examples

## Not run: 
 gate <- gate_tail(fr, Channel = "APC-A") # fr is a flowFrame

## End(Not run)

openCyto documentation built on Nov. 8, 2020, 5:40 p.m.