rangeGate2: Improved search for separation between positive and negative...
In ornelles/flowExtra: Helper Functions for flowCore

Description Usage Arguments Details Value See Also Examples

View source: R/rangeGate2.R

This function replaces flowStats::rangeGate() which never seemed to work for me. It does not perform all the functions of the original but will return a mores sensible rectangleGate object more often than flowStats::rangeGate().

rangeGate2(
  fs,
  stain,
  from = NULL,
  to = NULL,
  cutoff = 0.05,
  adjust = 1,
  half.range = TRUE,
  sd = 2.5,
  positive = TRUE,
  method = c("minimum", "left"),
  plot = FALSE,
  legend = TRUE,
  filterId = "defaultRectangleGate",
  ...
)

`fs`	A `flowCore::flowset` or `flowCore::flowFrame` object
`stain`	A `character` scalar (also known as `chan`) of the flow parameter to analyze
`from, to`	Starting and ending values to search for the break
`cutoff`	Peaks and valleys smaller than this fraction of the range will be ignored, default value of 0.05
`adjust`	Adjustment to bandwidth used by `stats::density()`
`half.range`	If `TRUE` and a single population is found, the normal distribution will be fit using the left half of the population
`sd`	In the case of a single population, this is the multiplier for the standard deviation to estimate the upper edge of the negative population, default value of 2.5
`positive`	If `TRUE`, gate the positive population
`method`	Either `"minimum"` or `"left"` to choose the break as the minimum between two peaks or to treat the left-most population as a Gaussian population of the negative population
`plot`	If `TRUE`, show a plot of the data and breakpoint
`legend`	If `TRUE`, include a legend in the plot (if `plot == TRUE`)
`filterId`	The name assigned to the filter (`character` value)
`...`	Other arguments to the original function are accepted such as `borderQuant`, `absolute`, and `refLine` but are discarded

This is a replacement function for flowStats::rangeGate that may be more robust than the original function.

This function seeks the most likely breakpoint between two populations to differentiate between the positive and negative population. The "negative" population is assumed to have a lower values and would be located on the left of a histogram.

The default method (method = "minimum") attempts to identify the lowest minimum between the regions of greatest density or peaks on a densityplot. The search can be limited to values between from and to. If more than four high density regions exist or if only a single high density region is detected, the breakpoint will be determined from the properties of the leftmost population where this population is assumed to follow a normal distribution. This approach also can be specified directly by method = "left" as described below.

With method = "left", the maximum of the left most (minimum) population is determined from a kernel density estimate. If half.range = TRUE, the left half of the population will be used to determine the Gaussian distribution in order to estimate the standard deviation of the population. With method = "left", the value returned is the position of the peak + sd times the standard deviation of the distribution.

A diagnostic plot will be generated with base graphics if plot = TRUE. In this case, the default argument legend = TRUE will add an informative legend to the plot showing the data and breakpoint. The plotting option can be useful to iteratively adjust the search parameters such as adjust, from, to and sd.

An object of class flowCore::rectangleGate

flowStats::rangeGate()

# Read and clean up synchronized cell data
  fs <- readSet(system.file("extdata", "synch", package = "flowExtra"))
  fs <- Subset(fs, linearGate(fs, "FL2.A", "FL2.H"))
# breakpoint by default (method = "minimum")
  rangeGate2(fs[[8]], "FL2.A", plot = TRUE)
# breakpoint by left population (method = "left")
  rangeGate2(fs[[8]], "FL2.A", method = "left", plot = TRUE)
# puzzling choice with original rangeGate() function
  flowStats::rangeGate(fs[[8]], "FL2.A", plot = TRUE)
# example of multiple possible breakpoints
  rangeGate2(fs[[2]], "FL2.A", plot = TRUE)
# adjust by limiting search range with 'to'
  rangeGate2(fs[[2]], "FL2.A", plot = TRUE, to = 275)