Get metadata

Description

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.

Usage

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

Arguments

Details

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.

Value

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.

See Also

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

Examples

# 'WMD' methods

(x <- metadata(vaas_1, "Strain"))

## [1] "DSM30083T"

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

## [1] "DSM30083T"

stopifnot(identical(x, y))

(x <- metadata_chars(vaas_1, values = FALSE))

##     Experiment   Plate number           Slot        Species         Strain 
##   "Experiment" "Plate number"         "Slot"      "Species"       "Strain"

stopifnot(names(x) == x) # mapping metadata keys to themselves
(x <- metadata_chars(vaas_1, values = TRUE))

##                  B          DSM30083T   Escherichia coli 
##                "B"        "DSM30083T" "Escherichia coli" 
##    First replicate 
##  "First replicate"

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

## [1] "DSM18039"  "DSM30083T" "DSM1707"   "429SC1"

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

## [1] "DSM18039"  "DSM30083T" "DSM1707"   "429SC1"

stopifnot(identical(x, y))

(x <- metadata_chars(vaas_4, values = TRUE)) # the values

##                   429SC1                        B                  DSM1707 
##                 "429SC1"                      "B"                "DSM1707" 
##                 DSM18039                DSM30083T         Escherichia coli 
##               "DSM18039"              "DSM30083T"       "Escherichia coli" 
##          First replicate   Pseudomonas aeruginosa 
##        "First replicate" "Pseudomonas aeruginosa"

(y <- metadata_chars(vaas_4, values = FALSE)) # the keys

##     Experiment   Plate number           Slot        Species         Strain 
##   "Experiment" "Plate number"         "Slot"      "Species"       "Strain"

stopifnot(length(x) > length(y))

# detecting misspellings
(x <- metadata_chars(vaas_4, max.dist = 0.1))

## named character(0)

stopifnot(length(x) == 0) # no misspellings
(x <- metadata_chars(vaas_4, max.dist = 0.5)) # wrong result!

##     DSM1707    DSM18039 
## "DSM30083T" "DSM30083T"

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

## named character(0)

stopifnot(length(x) == 0) # strings with numbers excluded