From 37a7a89b4dbc0bae7408f4269840c619189e8e22 Mon Sep 17 00:00:00 2001 From: mikejiang Date: Sat, 25 Nov 2023 16:59:44 -0800 Subject: [PATCH] document --- NAMESPACE | 19 +++ R/tautString.R | 4 - ...typlot-GatingHierarchy-character-method.Rd | 1 - man/gate_tail.Rd | 158 ++++++++++++++++++ man/gate_tautstring.Rd | 41 +++++ ...atingSetList-method.Rd => gslist_clone.Rd} | 11 +- ... => keyword-GatingSet-character-method.Rd} | 9 +- man/sce_to_gs.Rd | 29 ++++ 8 files changed, 256 insertions(+), 16 deletions(-) create mode 100644 man/gate_tail.Rd create mode 100644 man/gate_tautstring.Rd rename man/{clone-GatingSetList-method.Rd => gslist_clone.Rd} (62%) rename man/{getKeywords-GatingSet-character-method.Rd => keyword-GatingSet-character-method.Rd} (73%) create mode 100644 man/sce_to_gs.Rd diff --git a/NAMESPACE b/NAMESPACE index d1e4584..6f4ffe7 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,24 @@ # Generated by roxygen2: do not edit by hand +export(cytoexperiment) +export(gate_tail) +export(gate_tautstring) +export(gs_to_sce) +export(gsexperiment) +export(gslist_clone) +export(gstreeexperiment) +export(print.logicle) +export(readFCSPar) +export(sce_to_gs) +export(tailgate) +export(tautString) +export(tautStringGate) +export(tautstring) +export(tmix2DGate) +exportClasses(cytoexperiment) +exportClasses(gsexperiment) +exportMethods(densityplot) +exportMethods(keyword) import(data.table) import(flowCore) import(flowWorkspace) diff --git a/R/tautString.R b/R/tautString.R index b9b2548..d191769 100644 --- a/R/tautString.R +++ b/R/tautString.R @@ -78,10 +78,6 @@ gate_tautstring <- function(fr, channel, gate_range = NULL, min = NULL, max = NU } return(filters) } -#' @templateVar old tautStringGate -#' @templateVar new gate_tautstring -#' @template template-depr_pkg -NULL #'@export tautStringGate <- function(fr, channel, gate_range = NULL, min = NULL, max = NULL, filterId = ""){ diff --git a/man/densityplot-GatingHierarchy-character-method.Rd b/man/densityplot-GatingHierarchy-character-method.Rd index 78cadb4..74e1400 100644 --- a/man/densityplot-GatingHierarchy-character-method.Rd +++ b/man/densityplot-GatingHierarchy-character-method.Rd @@ -1,6 +1,5 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/densityplot.R -\docType{methods} \name{densityplot,GatingHierarchy,character-method} \alias{densityplot,GatingHierarchy,character-method} \title{plot the population as densityplot for the channels associated with the gate} diff --git a/man/gate_tail.Rd b/man/gate_tail.Rd new file mode 100644 index 0000000..bd17980 --- /dev/null +++ b/man/gate_tail.Rd @@ -0,0 +1,158 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/tailgate.R +\name{gate_tail} +\alias{gate_tail} +\alias{tailgate} +\alias{cytokine} +\alias{.cytokine_cutpoint} +\title{Gates the tail of a density using the derivative of a kernel density estimate} +\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{ +\item{fr}{a \code{flowFrame} object} + +\item{channel}{the channel from which the cytokine gate is constructed} + +\item{filterId}{the name of the filter} + +\item{num_peaks}{the number of peaks expected to see. This effectively removes +any peaks that are artifacts of smoothing} + +\item{ref_peak}{After \code{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.} + +\item{strict}{\code{logical} when the actual number of peaks detected is less than \code{ref_peak}. +an error is reported by default. But if \code{strict} is set to FALSE, then the reference peak will be reset to the peak of the far right.} + +\item{tol}{the tolerance value} + +\item{side}{On which side of the density do we want to gate the tail. Valid options are "left" or "right".} + +\item{min}{a numeric value that sets the lower boundary for data filtering} + +\item{max}{a numeric value that sets the upper boundary for data filtering} + +\item{bias}{a numeric value that adds a constant to the calculated cutpoint(threshold). Default is 0.} + +\item{positive}{If FALSE, after finding the cutpoint, the \code{rectangleGate} returned will have bounds \code{(-Inf, a]} as opposed to \code{[a, Inf)}. +This argument will be ignored if \code{gate_tail} is used in a \code{\link{gatingTemplate}} with \code{\link{gt_gating}} or via \code{\link{gs_add_gating_method}}. +In those cases, pop = "-" should be used instead.} + +\item{...}{additional arguments passed to \code{.deriv_density}} + +\item{x}{a \code{numeric} vector used as input data} + +\item{method}{the method used to select the cutpoint. See details.} + +\item{adjust}{the scaling adjustment applied to the bandwidth used in the +first derivative of the kernel density estimate} + +\item{plot}{logical specifying whether to plot the peaks found +\code{'right'} (default) or \code{'left'}?} + +\item{auto_tol}{when TRUE, it tries to set the tolerance automatically.} +} +\value{ +a \code{filterList} containing the gates (cutpoints) for each sample with +the corresponding \code{\linkS4class{rectangleGate}} objects defining the tail as the positive population. + +the cutpoint along the x-axis +} +\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 \code{\linkS4class{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 \code{x}. +} +\details{ +The default behavior of the first approach, specified by \code{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 \code{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 \code{num_peaks} argument specifes how many peaks should be found +in the smoothened KDE and \code{ref_peak} specifies around which peak the gate's +cutpoint should be placed (starting from the leftmost peak). Setting the \code{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 \code{max} and \code{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 \code{adjust} (e.g. \code{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 \code{tol}, \code{auto_tol}, and \code{bias} arguments allow for adjustments +to be made to the cutpoint that would otherwise be returned. \code{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 \code{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 \code{side = "left"}) with corresponding +derivative within \code{tol}. Thus in practice, a smaller value for \code{tol} effectively pushes the cutpoint +further down the shoulder of the peak towards the flat tail. \code{tol} is set to 0.01 by default +but setting \code{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. \code{tol} and +\code{auto_tol} are only used for \code{method = "first_deriv"}. Additionally, the \code{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 \code{num_points}. The default +bandwidth can also be directly adjusted with \code{bandwidth}, where the final value used +will be given by \code{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 \code{tol} in magnitude and is also greater +than the lowest valley. + +Alternatively, if the \code{method} is selected as \code{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. +} +\examples{ +\dontrun{ + gate <- gate_tail(fr, Channel = "APC-A") # fr is a flowFrame +} +} diff --git a/man/gate_tautstring.Rd b/man/gate_tautstring.Rd new file mode 100644 index 0000000..17491b5 --- /dev/null +++ b/man/gate_tautstring.Rd @@ -0,0 +1,41 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/tautString.R +\name{tautstring} +\alias{tautstring} +\alias{tautString} +\alias{gate_tautstring} +\alias{tautStringGate} +\title{Taut String Density Estimator Gating} +\usage{ +tautstring(sorted_vector, modeprior = 0) + +gate_tautstring( + fr, + channel, + gate_range = NULL, + min = NULL, + max = NULL, + filterId = "" +) +} +\arguments{ +\item{sorted_vector}{\code{numeric} vector of single cell expresion from a single cytometric channel.} + +\item{modeprior}{\code{numeric} scalar specifying the expected number of modes. Default 0 (autodetect). Rarely should this be +set by the user.} + +\item{fr}{a flowFrame object} + +\item{channel}{The channel to gate.} + +\item{gate_range}{The range to look for a gate, no truncation occurs.} + +\item{min}{The min range of the data to truncate the flowFrame} + +\item{max}{The max range of the data to truncate the flowFrame} + +\item{filterId}{The id / name of the gate.} +} +\description{ +The taut string density estimator gating returns 0, 1, or more gates, depending on how many modes it identifies in the data. +} diff --git a/man/clone-GatingSetList-method.Rd b/man/gslist_clone.Rd similarity index 62% rename from man/clone-GatingSetList-method.Rd rename to man/gslist_clone.Rd index b05f28f..51d0935 100644 --- a/man/clone-GatingSetList-method.Rd +++ b/man/gslist_clone.Rd @@ -1,16 +1,15 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/clone.GatingSetList.R -\docType{methods} -\name{clone,GatingSetList-method} -\alias{clone,GatingSetList-method} +\name{gslist_clone} +\alias{gslist_clone} \title{clone a GatingSetList} \usage{ -\S4method{clone}{GatingSetList}(x, ...) +gslist_clone(x, ...) } \arguments{ \item{x}{A \code{GatingSetList}} -\item{...}{see \code{\link{clone,GatingSet-method}}} +\item{...}{see \code{\link{gs_clone}}} } \value{ A copy of a given \code{GatingSetList}. @@ -20,7 +19,7 @@ A wrapper that invokes clone method for each underlying GatingSet. } \examples{ \dontrun{ - gslist1<-clone(gslist) + gslist1<-gslist_clone(gslist) } } diff --git a/man/getKeywords-GatingSet-character-method.Rd b/man/keyword-GatingSet-character-method.Rd similarity index 73% rename from man/getKeywords-GatingSet-character-method.Rd rename to man/keyword-GatingSet-character-method.Rd index 6a97fad..51f9288 100644 --- a/man/getKeywords-GatingSet-character-method.Rd +++ b/man/keyword-GatingSet-character-method.Rd @@ -1,11 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/getKeywords.R -\docType{methods} -\name{getKeywords,GatingSet,character-method} -\alias{getKeywords,GatingSet,character-method} +\name{keyword,GatingSet,character-method} +\alias{keyword,GatingSet,character-method} \title{Fetch a list of keywords from a GatingSet} \usage{ -\S4method{getKeywords}{GatingSet,character}(obj, y) +\S4method{keyword}{GatingSet,character}(object, keyword) } \arguments{ \item{obj}{GatingSet} @@ -21,5 +20,5 @@ No error checking at the moment. library(flowWorkspace) dataDir <- system.file("extdata",package="flowWorkspaceData") suppressMessages(gs <- load_gs(list.files(dataDir, pattern = "gs_manual",full = TRUE))) -getKeywords(gs, c("TUBE NAME", "EXPERIMENT NAME")) +keyword(gs, c("TUBE NAME", "EXPERIMENT NAME")) } diff --git a/man/sce_to_gs.Rd b/man/sce_to_gs.Rd new file mode 100644 index 0000000..383803b --- /dev/null +++ b/man/sce_to_gs.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/gsexperiment.R +\name{sce_to_gs} +\alias{sce_to_gs} +\title{convert SingleCellExperiment to a GatingSet} +\usage{ +sce_to_gs( + sce, + assay_type = "intensity", + sample = "sample", + channel = NA, + marker = NA, + ... +) +} +\arguments{ +\item{sce}{SingleCellExperiment object} + +\item{assay_type}{select assay to use} + +\item{sample}{select the column from colData to represent sample ID} + +\item{channel}{select the column from rowData to represent channels} + +\item{marker}{select the column from rowData to represent markers} +} +\description{ +note that only selected assay and rowData columns will be extracted into the GatingSet +}