Better documentation for preprocessing methods

[wjs20]

Hi openCyto team!

Really enjoying the package. I'm a bit confused about how to fill in the pre-processing column in my gating template csv for a tailgate. In your vignette you add the standardize_flowset argument, but I cannot find any explanation in the vignette or documentation about what it is used for or how it works. It would be helpful if you could provide some explanations of how this and other preprocessing methods work somewhere in your documentation.

Thankyou

[mikejiang]

let's use standardize_flowset as the example, and heere is the formal of the preprocessing function,

.standardize_flowset <- function(fs, gs, gm, channels, groupBy, isCollapse, ...)

• fs argument is a flowSet( or cytoset), representing the data retrieved from that parent population (specified from parent column)

  • If groupBy column is not specified in the template, then the preprocessing function receive the fs for ALL samples,
  • if groupBy is specified (e.g. patient ID), then only a sub-group of samples (e.g. with the same patient ID) are passed to preprocessing function as fs

• gs argument is the GatingSet object, which is a sort of a hack or backdoor, providing the preprocessing function the access to the entire gating data structure (you don't need to use it unless you need)

The return value of preprocessing can be anything, it is passed on to the gating function as pp_res argument, e.g.

.gate_tail <- function(fr, pp_res = NULL, channels, ...) 

as shown, gating function receives the data from fr argument , which is a flowFrame (or cytoframe) and it typically represents the parent data from a single sample. unless both groupBy and collapseDataForGating columns are set, e.g. collapseDataForGating = TRUE and groupBy = 'patient ID', then the parent data from a sub-group of samples(from the same patent ID) is collapsed(or merged) into a cytoframe and passed to the gating function.

Again, optional pp_res argument can take the preprcoessing result to guide the gating process.

Coming back to standardize_flowset this specific function, it basically takes the parent data from all samples or a sub-group of samples, and standardizes/rescale the given channel of each sample using the mode of the kernel density estimate and the Huber estimator of the standard deviation. And the standardized data is returned and will be passed as pp_res to gating function, which will be using pp_res instead of fr argument for the actual gating

Here is one example of using preprocessing mechanism to achieve the negative control based gating https://rpubs.com/wjiang2/473129