do_disc {opm}R Documentation

Discretise curve parameters

Description

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).

Usage

  ## 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),
    ...)

Arguments

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.

Details

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.

Value

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.

See Also

Other discretization-functions: best_cutoff, discrete

Examples

## OPMA method

# arbitrary threshold, no ambiguity
summary(x <- do_disc(vaas_1, cutoff = 100))

## Class                 OPMD
## From file             ./E. coli DSM
##                       30083T_vim10_7B__1_28_PMX_0_8#30#2010_F_
##                       7B_5.csv
## Hours measured        95.75
## Number of wells       96
## Plate type            Gen III
## Position              7-B
## Setup time            8/30/2010 1:53:08 PM
## Metadata              5
## Aggregated            TRUE
## Discretized           TRUE

stopifnot(has_disc(x), dim(x) == dim(vaas_1), !is.na(discretized(x)))
(y <- disc_settings(x))  # stored discretisation settings

## $method
## [1] "direct"
## 
## $options
## $options$cutoffs
## [1] 100
## 
## $options$datasets
## [1] 1
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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)))

## Class                 OPMD
## From file             ./E. coli DSM
##                       30083T_vim10_7B__1_28_PMX_0_8#30#2010_F_
##                       7B_5.csv
## Hours measured        95.75
## Number of wells       96
## Plate type            Gen III
## Position              7-B
## Setup time            8/30/2010 1:53:08 PM
## Metadata              5
## Aggregated            TRUE
## Discretized           TRUE

# 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

## $method
## [1] "direct"
## 
## $options
## $options$cutoffs
## [1]  75 125
## 
## $options$datasets
## [1] 1
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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))

## Class                 OPMD
## From file             ./E. coli DSM
##                       30083T_vim10_7B__1_28_PMX_0_8#30#2010_F_
##                       7B_5.csv
## Hours measured        95.75
## Number of wells       96
## Plate type            Gen III
## Position              7-B
## Setup time            8/30/2010 1:53:08 PM
## Metadata              5
## Aggregated            TRUE
## Discretized           TRUE

stopifnot(has_disc(x), dim(x) == dim(vaas_1), !is.na(discretized(x)))
(y <- disc_settings(x)) # stored discretisation settings

## $method
## [1] "kmeans"
## 
## $options
## $options$cutoffs
## [1] 196.6758
## 
## $options$datasets
## [1] 1
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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))

## Class                 OPMD
## From file             ./E. coli DSM
##                       30083T_vim10_7B__1_28_PMX_0_8#30#2010_F_
##                       7B_5.csv
## Hours measured        95.75
## Number of wells       96
## Plate type            Gen III
## Position              7-B
## Setup time            8/30/2010 1:53:08 PM
## Metadata              5
## Aggregated            TRUE
## Discretized           TRUE

stopifnot(has_disc(x), dim(x) == dim(vaas_1), any(discretized(x)))
(y <- disc_settings(x)) # stored discretisation settings

## $method
## [1] "kmeans"
## 
## $options
## $options$cutoffs
## [1] 129.0670 241.2105
## 
## $options$datasets
## [1] 1
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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

## $method
## [1] "direct"
## 
## $options
## $options$cutoffs
## [1] 100
## 
## $options$datasets
## [1] 4
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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)

## Warning: discretized data inconsistent with 'A' parameter

## Warning: discretized data inconsistent with 'A' parameter

## Warning: discretized data inconsistent with 'A' parameter

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

## $method
## [1] "direct"
## 
## $options
## $options$cutoffs
## [1] 100
## 
## $options$datasets
## [1] 4
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] 0.5
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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

## $method
## [1] "direct"
## 
## $options
## $options$cutoffs
## [1] 100
## 
## $options$datasets
## [1] 1
## 
## $options$group
## [1] "1"
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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

## $method
## [1] "direct"
## 
## $options
## $options$cutoffs
## [1] 100
## 
## $options$datasets
## [1] 2
## 
## $options$group
## [1] "Escherichia coli"
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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

## $method
## [1] "kmeans"
## 
## $options
## $options$cutoffs
## [1] 172.6614
## 
## $options$datasets
## [1] 2
## 
## $options$group
## [1] "Escherichia coli"
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] -1
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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

## $method
## [1] "kmeans"
## 
## $options
## $options$cutoffs
## [1] 172.6614
## 
## $options$datasets
## [1] 2
## 
## $options$group
## [1] "Escherichia coli"
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] 0.5
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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

## $method
## [1] "best-cutoff"
## 
## $options
## $options$cutoffs
## [1] 239.5111
## 
## $options$datasets
## [1] 2
## 
## $options$score
## [1] 1.62
## 
## $options$group
## [1] "Escherichia coli"
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] 0.5
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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)

## Warning: discretized data inconsistent with 'A' parameter

## Warning: discretized data inconsistent with 'A' parameter

## Warning: discretized data inconsistent with 'A' parameter

## Warning: discretized data inconsistent with 'A' parameter

stopifnot(has_disc(x), dim(x) == dim(vaas_4), anyNA(discretized(x)))
(y <- disc_settings(x)[[1]]) # stored discretisation settings

## $method
## [1] "best-cutoff"
## 
## $options
## $options$cutoffs
## [1] 222.5776
## 
## $options$datasets
## [1] 4
## 
## $options$score
## [1] 1.604167
## 
## $options$parameter
## [1] "A"
## 
## $options$unified
## [1] 0.5
## 
## 
## $software
## [1] "opm"
## 
## $version
## [1] "1.3.63"

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
[Package opm version 1.3.63 Index]