do_disc: Discretise curve parameters
In opm: Analysing Phenotype Microarray and Growth Curve Data

Description Usage Arguments Details Value See Also Examples

Discretise the aggregated kinetic data, i.e. infer discrete values from the curve parameters stored in an OPMA or OPMS object. Here, only discretisation into positive, negative and ambiguous reactions is supported, and by default based on the ‘maximum height’ curve parameter (which is biologically reasonable though).

  ## S4 method for signature 'MOPMX'
do_disc(object, ...) 
  ## S4 method for signature 'OPMA'
do_disc(object, cutoff, groups = FALSE,
    plain = FALSE, subset = opm_opt("disc.param"), unify = FALSE) 
  ## S4 method for signature 'OPMS'
do_disc(object, cutoff = TRUE, groups = FALSE,
    plain = FALSE, subset = opm_opt("disc.param"), unify = !length(cutoff),
    ...)

`object`	`OPMA`, `OPMS` or `MOPMX` object.
`cutoff`	Determines the discretisation approach. If not `NULL`, passed as `range` argument to `discrete` (with `gap` set to `TRUE`), thus triggering discretisation using either k-means partitioning or one or two predefined thresholds. If `NULL`, a discretisation cutoff is determined using `best_cutoff`, which is only possible for `OPMS` objects.
`groups`	List, `NULL` or character vector passed as ‘as.labels’ argument to `extract`, or logical scalar. In that case, if `TRUE`, groups are automatically created with one plate per group. If `FALSE`, grouping is not used, i.e. there is only a single group containing all plates. Note that if `cutoff` is empty and `groups` is `TRUE`, an error is raised since `best_cutoff` needs groups with more than a single element. The `groups` argument has no effect on `OPMA` objects.
`plain`	Logical scalar indicating whether or not an `OPMD` or `OPMS` object should be created.
`subset`	Character scalar passed to `extract`. It is recommended to use the maximum height (currently called ‘A’).
`unify`	Logical or numeric scalar indicating whether results should be unified per group. This works by choosing the most frequent value (mode) if its frequency is above a given threshold and `NA` otherwise. (The same approach is used by `listing` and `phylo_data`.) If `unify` is a logical scalar, `NA` triggers unification using 1 as threshold, i.e. all ambiguities are codes as `NA`. Using `TRUE` turns on unification with the default threshold given by `opm_opt("min.mode")`, whereas `FALSE` turns unification off. If `unify` is a numeric scalar, values below or equal to zero turn unification off. Values above zero are directly used as unification threshold, thus values above 1 or numeric `NA` make no sense (cause an error). See ‘Details’ below on the potential consequences of unification. In the `disc_settings` entries, an according ‘unified’ entry will report the threshold used, with -1 indicating no unification. The `unify` argument has no effect on `OPMA` objects (because they represent a single group with a single member).
`...`	Optional arguments passed between the methods or to `extract`. The latter is only relevant for certain settings of `groups`, see above.

If unify is set to FALSE, the discretisation results are always consistent (in the sense described for the OPMD class) with the discretised parameter. If unify is set to TRUE this cannot be guaranteed any more. To enforce consistency, use opm_opt(strict.OPMD = TRUE).

The discretised values can be queried for using has_disc and received using discretized.

If plain is FALSE, an OPMD or OPMS object. Otherwise a logical vector whose length corresponds to the number of wells in object with an additional ‘settings’ attribute describing the run. The vector and its attribute would correspond to the discretized and disc_settings entries of a resulting OPMD object, respectively.

Other discretization-functions: best_cutoff, discrete

## OPMA method

# arbitrary threshold, no ambiguity
summary(x <- do_disc(vaas_1, cutoff = 100))
stopifnot(has_disc(x), dim(x) == dim(vaas_1), !is.na(discretized(x)))
(y <- disc_settings(x))  # stored discretisation settings
stopifnot(identical(y$method, "direct"))
stopifnot(is.list(y), is.list(y$options)) # named lists

# arbitrary thresholds, allowing intermediate ('weak') reactions
summary(x <- do_disc(vaas_1, cutoff = c(75, 125)))
# the intermediate reactions are coded as NA
stopifnot(has_disc(x), dim(x) == dim(vaas_1), anyNA(discretized(x)))
(y <- disc_settings(x)) # stored discretisation settings
stopifnot(identical(y$method, "direct"))
stopifnot(is.list(y), is.list(y$options)) # named lists

# using k-means, two categories, no intermediate ('weak') reactions
summary(x <- do_disc(vaas_1, cutoff = FALSE))
stopifnot(has_disc(x), dim(x) == dim(vaas_1), !is.na(discretized(x)))
(y <- disc_settings(x)) # stored discretisation settings
stopifnot(identical(y$method, "kmeans"))
stopifnot(is.list(y), is.list(y$options)) # named lists

# using k-means, now allowing intermediate ('weak') reactions
summary(x <- do_disc(vaas_1, cutoff = TRUE))
stopifnot(has_disc(x), dim(x) == dim(vaas_1), any(discretized(x)))
(y <- disc_settings(x)) # stored discretisation settings
stopifnot(identical(y$method, "kmeans"))
stopifnot(is.list(y), is.list(y$options)) # named lists


## OPMS method

# arbitrary threshold, no ambiguity, no groups
x <- do_disc(vaas_4, cutoff = 100)
stopifnot(has_disc(x), dim(x) == dim(vaas_4), !is.na(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "direct"))
stopifnot(is.list(y), is.list(y$options)) # named lists

# arbitrary threshold, no ambiguity, no groups, with unification
x <- do_disc(vaas_4, cutoff = 100, unify = TRUE)
stopifnot(has_disc(x), dim(x) == dim(vaas_4))
stopifnot(anyNA(discretized(x))) # NAs caused by unification
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "direct"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# all plates made uniform (makes not much sense)

# arbitrary threshold, no ambiguity, with groups, 1 plate per group
x <- do_disc(vaas_4, cutoff = 100, groups = TRUE)
stopifnot(has_disc(x), dim(x) == dim(vaas_4), !is.na(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "direct"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# here, the plate numbers yield the group names

# arbitrary threshold, no ambiguity, with specified groups
x <- do_disc(vaas_4, cutoff = 100, groups = "Species")
stopifnot(has_disc(x), dim(x) == dim(vaas_4), !is.na(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "direct"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# now, groups are from the metadata (but played no role)

# using k-means, no ambiguity, with specified groups
x <- do_disc(vaas_4, cutoff = FALSE, groups = "Species")
stopifnot(has_disc(x), dim(x) == dim(vaas_4), !is.na(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "kmeans"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# grouping by species, discretised separately

# same, with unification
x <- do_disc(vaas_4, cutoff = FALSE, groups = "Species", unify = TRUE)
stopifnot(has_disc(x), dim(x) == dim(vaas_4))
stopifnot(anyNA(discretized(x))) # NAs caused by unification
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "kmeans"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# grouping by species, discretised separately, then made uniform

# using best_cutoff(), groups defined by species affiliation (makes not
# much sense and by default yields warnings with these data)
x <- do_disc(vaas_4, cutoff = NULL, groups = "Species")
stopifnot(has_disc(x), dim(x) == dim(vaas_4), anyNA(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "best-cutoff"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# groups as above, 2 strains per species, but some additional entries

# using best_cutoff(), single group for all plates (makes even less sense
# and by default also yields warnings with these data)
x <- do_disc(vaas_4, cutoff = NULL, groups = FALSE)
stopifnot(has_disc(x), dim(x) == dim(vaas_4), anyNA(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings
stopifnot(identical(y$method, "best-cutoff"))
stopifnot(is.list(y), is.list(y$options)) # named lists
# no subgroups, all 4 data sets in one group, and some additional entries