metadata: Get metadata
In opm: Analysing Phenotype Microarray and Growth Curve Data

Description Usage Arguments Details Value See Also Examples

Get meta-information stored together with the data or collect all ‘character’ entries from the meta-information stored together with the measurements. Optionally coerce data of other types.

  ## S4 method for signature 'MOPMX'
metadata(object, ...) 
  ## S4 method for signature 'WMD'
metadata(object, key = NULL, exact = TRUE, strict = FALSE)
  ## S4 method for signature 'WMDS'
metadata(object, ...) 

  ## S4 method for signature 'MOPMX'
metadata_chars(object, values = TRUE,
    classes = "factor", max.dist = -1, ...) 
  ## S4 method for signature 'WMD'
metadata_chars(object, values = TRUE,
    classes = "factor", max.dist = -1, ...) 
  ## S4 method for signature 'WMDS'
metadata_chars(object, values = TRUE,
    classes = "factor", max.dist = -1, ...)

`object`	`WMD`, `WMDS` or `MOPMX` object.
`key`	`NULL`, vector, factor or formula. If `NULL` or otherwise empty, return all metadata. If a non-empty list, treated as list of keys. Return value would be the list of corresponding metadata values. Here, character vectors of length > 1 can be used to query nested metadata lists. If neither empty nor a list nor a formula (i.e. usually a character or numeric vector), `key` is treated as a single list key. Factors are converted to ‘character’ mode. Formulae can also be used and are converted to a list or character or numeric vector using the rules described under ‘Details’. It is in general not recommended to use numeric vectors as `key` arguments, either directly or within a list or formula.
`exact`	Logical scalar. Use exact or partial matching of keys? Has no effect if `key` is empty.
`strict`	Logical scalar. Is it an error if a `NULL` value results from fetching a metadata key?
`values`	Logical scalar. If `FALSE`, metadata names, not values, are collected, and `classes` is ignored (names are always of class ‘character’ and need not be coerced).
`classes`	Character vector containing the names of classes that should also be collected (and coerced to ‘character’), or `TRUE`. In that case, a mapping template for the classes themselves is returned. See the `coerce` argument of `map_values` for details.
`max.dist`	Numeric scalar. If non-negative, causes the construction of a mapping from potential misspellings to the putative correct spelling, based on string similarity. `max.dist` then gives the maximum string distance allowed for regarding two strings as synonyms. This boundary must not be set too high; otherwise strings with distinct meanings might be regarded as misspellings (see the example below). The resulting vector should always be inspected before passing it to `map_values`. See the `map_values` method for character vectors as `object` and numeric vectors as `mapping` argument in the pkgutils package for further details on such string matching.
`...`	Optional arguments passed between the methods or to `map_values`.

If a named list is used as key argument, its names will be used within the first level of the resulting nested or non-nested list. That is, key can be used to translate names on the fly, and this can be used by all functions that call metadata indirectly, usually via an as.labels or as.groups argument.

Even though it is not technically impossible, it is usually a bad idea to select metadata entries using numeric (positional) or logical keys. The problem is that, in contrast to, e.g., data frames, their is no guarantee that metadata entries with the same name occur in the same position, even if they belong to WMD objects within a single WMDS object.

Note that key = c("a", "b") would search for an element named b within the element named a. To extract two elements at the same (highest) level, key = list("a", "b") should be used. This prevents many ‘subscript out of bounds’ errors.

Formulae passed as key argument are treated by ignoring the left side (if any) and converting the right side to a list or other vector. Code enclosed in I is evaluated with a call to eval. It is up to the user to ensure that this call succeeds and yields a character vector or a list. Operators in all other code within the formula are used just as separators, and all names are converted to character scalars. The $ operator binds tightly, i.e. it separates elements of a character vector (for nested querying) in the output. The same effect have other operators of high precedence such as :: but their use is not recommended. All operators with a lower precedence than $ separate list elements.

Additional options when using formulae are described under extract.

The result of metadata_chars can be used to create a mapping for map_metadata. The WMDS method just applies the WMD method to all contained plates in turn.

metadata generates a list (empty if metadata were not set or if partial selection using key did not result).

Under default settings metadata_chars yields a character vector, sorted and made unique. Original names attributes, if any, are dropped and replaced by the character vector itself. (This might be convenient regarding its use with map_metadata.) If max.distance is non-negative, the result is distinct; see above for details.

Other metadata-functions: edit, include_metadata, map_metadata, map_values, metadata.set,

# 'WMD' methods

(x <- metadata(vaas_1, "Strain"))
stopifnot(x == "DSM30083T")
(y <- metadata(vaas_1, ~ Strain)) # using a formula => same result
stopifnot(identical(x, y))

(x <- metadata_chars(vaas_1, values = FALSE))
stopifnot(names(x) == x) # mapping metadata keys to themselves
(x <- metadata_chars(vaas_1, values = TRUE))
stopifnot(names(x) == x) # mapping metadata values to themselves
# See map_metadata() for a potential usage of the metadata_chars() result

# 'WMDS' methods

(x <- metadata(vaas_4, "Strain"))
stopifnot(x == c("DSM18039", "DSM30083T", "DSM1707", "429SC1"))
(y <- metadata(vaas_4, ~ Strain)) # using a formula => same result
stopifnot(identical(x, y))

(x <- metadata_chars(vaas_4, values = TRUE)) # the values
(y <- metadata_chars(vaas_4, values = FALSE)) # the keys
stopifnot(length(x) > length(y))

# detecting misspellings
(x <- metadata_chars(vaas_4, max.dist = 0.1))
stopifnot(length(x) == 0) # no misspellings
(x <- metadata_chars(vaas_4, max.dist = 0.5)) # wrong result!
# distance too high => non-synonyms thought to be misspellings
stopifnot(length(x) == 2, !is.null(names(x)))
(x <- metadata_chars(vaas_4, max.dist = 0.5, exclude = "\\d"))
stopifnot(length(x) == 0) # strings with numbers excluded