Manually Draw Polygon Gate

Produce a simple x~y dotplot on the specified channels that is used with locator to define the gate boundaries, similar to defining a polygon gate in standard FCM GUIs. The resulting data are saved as an R-object under the name specified in pggId. Press 'esc' when done drawing the gate.

Usage

drawGate(
  gs,
  flf = NULL,
  gn = "root",
  pggId = ".",
  channels = ".",
  foN.gateStrat = ".",
  useLoc = TRUE,
  locN = 512,
  bnd = ".",
  showGate = NULL
)

Arguments

gs: A gating set as produced by makeGatingSet or makeAddGatingSet.
flf: Character or numeric length one. The identifier of the flowFrame within the gating set where the gate should be drawn on. Optimally, this is a flowFrame, i.e. sample, with a very good representation of the desired population. Possible input values can be determined via 'show'.
gn: Character length one. The name of a gate further specifying the desired subset of data; defaults to "root".
pggId: Character length one. The name of the resulting file containing the boundaries of the gate. If left at the default '.', the name as defined in the settings file (key: 'fiN_gate') will be used.
channels: Character length two. The channels the gate should be defined in. If left at the default '.', the two channels as defined in the settings file (key: 'dV_channelsForPGG') will be used. Available channels can be viewed via 'show' - see examples.
foN.gateStrat: Character length one. The name of the folder where the file defining the gating strategy and the gate definitions reside. If left at the default '.', the name as defined in the settings file (key: 'foN_gating') will be used.
useLoc: Logical. If, after plotting, the locator should be used. Defaults to TRUE.
locN: Numeric length one. How many points to acquire in the locator. Defaults to 512; use "ESC" to abort the locator action.
bnd: NULL or numeric length four. The boundaries to be marked on the plot, format: (x1, x2, y1, y2). If values are provided, two straight lines on the x-axis and two on the y-axis will be drawn.
showGate: Character length one. The name of an already existing gate residing in the folder specified by 'foN.gateDefs'. If provided, this gate will be additionally drawn on the dotplot. This can be helpful when e.g. on old, sub-optimal gate should be replaced with a new one: In this case the name of the 'old' would be provided at 'showGate' with the same name specified at 'ppgId'. Thus, the old gate will be replaced with the new one.

Value

A list with the locator coordinates. Mainly called for its side effect, i.e. the locator matrix data saved as an R-object in the folder specified at 'foN.gateStrat'.

Details

The generated R-object is saved automatically and can be used as a gate-definition in the gating strategy. For the lines to be drawn while the locator points are clicked, it is recommended to use this function NOT within R-Studio. The sample names within the gating set can be obtained via 'show' - see examples.

Warning

Existing locator matrix files with the same name will be overwritten without asking!

Link

Please refer also to https://bpollner.github.io/flowdex/articles/workflow_1.html for an in-depth description of the workflow how to create the gating strategy.

Examples

td <- tempdir()
data_source <- "https://github.com/bpollner/data/raw/main/flowdex_examples/flowdex_examples.zip"
check_download_data(td, data_source)
exp_home <- paste0(td, "/flowdex_examples")
old_wd <- getwd()
setwd(exp_home)
#
assign("get_settings_from_flowdex_package_root", TRUE, pos=.GlobalEnv)
# only required to make the examples run automatically
# you should not call 'assign' if you run the examples manually
# the effect of setting 'get_settings_from_flowdex_package_root' to TRUE
# is that the file 'flowdex_settings.R' in 'root' of the installed package
# 'flowdex' will be sourced instead of the one in the user-defined location.
#
# only required for the automated tests
# this simulates the manual drawing of a gate:
pathToPgg <- paste0(exp_home, "/gating/BactStainV1")
assign("pathToPgg", pathToPgg, pos=.GlobalEnv) # do NOT call this ('assign')
# when running example manually
#####
#####
gs <- makeGatingSet(patt="GPos_T4")
#> Reading in fcs files... ok. 
#> Producing gating set... Applying fjbiexp transformation... ok. 
drawGate(gs, 1, useLoc = FALSE) # to just check

drawGate(gs, 1, pggId = "new_pgg", showGate = "BactStainV1")

drawGate(gs, 1, pggId = "new_pgg", showGate = "new_pgg") 

#
setwd(old_wd)