include_metadata: Add or map metadata or edit them by hand

In opm: Analysing Phenotype Microarray and Growth Curve Data

Description

Either include metadata by mapping CSV data and column names in a data frame (optionally read from file), or modify meta-information stored together with the measurements by using a function or other kinds of mappings and return the objects otherwise unchanged, or invoke edit from the utils package for editing the metadata by hand.

Usage

  ## S4 method for signature 'MOPMX'
edit(name, ...) 
  ## S4 method for signature 'WMDX'
edit(name, ...) 

  ## S4 method for signature 'MOPMX'
include_metadata(object, ...) 
  ## S4 method for signature 'OPM'
include_metadata(object, md, keys = opm_opt("csv.keys"), ...)
  ## S4 method for signature 'WMD'
include_metadata(object, md, keys, replace = FALSE,
    skip.failure = FALSE, remove.keys = TRUE, normalize = -1L, ...) 
  ## S4 method for signature 'WMDS'
include_metadata(object, ...) 

  ## S4 method for signature 'MOPMX,ANY'
map_metadata(object, mapping, ...) 
  ## S4 method for signature 'MOPMX,missing'
map_metadata(object, mapping, values = TRUE, classes = "factor")
  ## S4 method for signature 'WMD,FOE'
map_metadata(object, mapping,
    values = parent.frame(), classes = NULL) 
  ## S4 method for signature 'WMD,character'
map_metadata(object, mapping, values = TRUE, classes = "factor")
  ## S4 method for signature 'WMD,function'
map_metadata(object, mapping, values = TRUE, classes = "ANY", ...)
  ## S4 method for signature 'WMD,missing'
map_metadata(object, mapping, values = TRUE, classes = "factor")
  ## S4 method for signature 'WMDS,ANY'
map_metadata(object, mapping, ...) 
  ## S4 method for signature 'WMDS,missing'
map_metadata(object, mapping, values = TRUE, classes = "factor")

  ## S4 method for signature 'list,formula'
map_values(object, mapping, coerce = parent.frame())

Arguments

object	OPM (WMD), OPMS (WMDS) or MOPMX object. For map_values, a list.
name	Like object, but for the edit method.
md	Data frame containing keys as column names, or name of file from which to read the data frame. Handled by to_metadata. In the case of many plates, it is computationally more efficient to provide a data frame instead of a file name.
keys	Character vector. Corresponds to the selection argument of collect_template.
replace	Logical scalar indicating whether the previous metadata, if any, shall be replaced by the novel ones, or whether these shall be appended.
skip.failure	Logical scalar. Do not stop with an error message if (unambiguous) selection is impossible but raise a warning only?
remove.keys	Logical scalar. When including md in the metadata, discard the keys columns?
normalize	Passed to csv_data. The same value must be chosen for subsequent calls of collect_template and include_metadata.
mapping	In most cases passed to map_values. If a function, this is just a wrapper for rapply, with how set to ‘replace’, if values is TRUE. It is applied to all non-list elements of metadata, which is traversed recursively. Alternatively, a character vector. metadata_chars can be used to create a template for such a vector. mapping can also be a formula; in that case, metadata is replaced by the according method of map_values. If the left side of the formula is missing, the entire metadata are replaced by the result, which is an error if the result is not a list. If mapping is missing, the behaviour is special; see the next two arguments. The opm package augments map_values with a method for lists and formulae. For all other methods, see the pkgutils package.
values	Mostly a logical scalar. For the function and character-vector methods, if FALSE, metadata names, not values, are mapped, and classes is ignored (names are always of class ‘character’). For the formula method, values is the enclosing environment used. If mapping is missing, setting values to TRUE causes all non-list entries that only comprise NA values to be removed.
classes	Character vector or (for the character vector-based mapping) TRUE. For the mapping with a function or vector, this specifies the classes in addition to ‘character’ that are mapped (after converting to ‘character’ mode). If classes is TRUE, mapping is treated as a mapping between class names, and the according conversions are applied. See the coerce argument of map_values for details. If mapping is missing, classes specifies classes that are converted to character vectors.
coerce	Character vector or TRUE. See the description of map_values in the pkgutils package for details.
...	Optional arguments passed to mapping if it is a function, and from the WMDS method to the WMD method, or from include_metadata to to_metadata, or as additional arguments to edit from the utils package.

Details

The WMDS method applies the inclusion and mapping routines to all plates in turn and returns an WMDS object with accordingly modified metadata.

Three kinds of errors can occur when attempting to identify a data-frame row using the given combination of keys and values.

• The combination results in more than a single row.

• The combination results in now rows at all.

• The keys are not found at all.

In the first two cases study the error message in detail. It contains the failed values enclosed in single quotes, doubling all contained single quotes, if any. This eases recognising leading and trailing spaces, which used to be a frequent cause of mismatches between data-frame fields and csv_data within WMD objects.

The third kind of error is usually caused by a wrong column separator (sep) argument. This happens particularly if a spreadsheet software saves the file with a separator distinct from the one used in the input. The to_metadata method for file names by default tries several sep values in turn as a remedy.

Leading and trailing spaces can be lost when writing CSV files and inputting them again. By default both collect_template and include_metadata attempt to avoid this by replacing all spaces with underscores. Make sure you use the same normalize argument with both functions. If you use a non-default normalize argument, consider the strip.white argument.

A further potential cause of mismatches is the reformatting of setup time entries by spreadsheet software. By default both include_metadata and collect_template attempt to avoid this by replacing all spaces with underscores. If this does not help, prevent the reformatting by forcing that software to treat the setup time as character strings.

If md is a file name, the default settings for sep and strip.white try to avoid these errors by trying several values in turn.

Calling edit will only work if to_metadata yields a data frame suitable for the edit method from the utils package. This usually means that the metadata must be rectangular, even though this is not enforced by the implementation of the OPMX classes. Entries missing in some elements of name should not present a problem, however. Values that remained NA would be removed before returning the result. Rows additionally included in the temporary data frame during editing yielded an error. The MOPMX method works by calling each element in turn (allowing for independent editing).

Value

Novel WMD or WMDS object with modified metadata.

See Also

utils::edit

Other metadata-functions: metadata, metadata_chars

Examples

## include_metadata()

(x <- collect_template(vaas_1, add.cols = "Location")) # generate data frame
x[1, "Location"] <- "Braunschweig" # insert additional information
copy <- include_metadata(vaas_1, x) # include the data in new OPM object
stopifnot(is.null(metadata(vaas_1, "Location")))
stopifnot(identical(metadata(copy, "Location"), "Braunschweig"))

## map_metadata()

# WMD methods

# WMD+function method
copy <- map_metadata(vaas_1, identity)
stopifnot(identical(copy, vaas_1))
copy <- map_metadata(vaas_1, identity, values = FALSE)
stopifnot(identical(copy, vaas_1))
copy <- map_metadata(vaas_1, function(x) paste(x, "!"), values = FALSE)
(x <- metadata_chars(vaas_1, values = FALSE))
(y <- metadata_chars(copy, values = FALSE))
stopifnot(identical(as.character(y), paste(x, "!")))

# WMD+character method: mapping a value
map <- metadata_chars(vaas_1)
map["First replicate"] <- "Rep. 1"
copy <- map_metadata(vaas_1, map)
stopifnot(identical(names(metadata(copy)), names(metadata(vaas_1))))
stopifnot(!identical(metadata(copy, "Experiment"),
  metadata(vaas_1, "Experiment")))

# WMD+character method: mapping a name
map <- metadata_chars(vaas_1, values = FALSE)
map["Plate number"] <- "Plate no."
copy <- map_metadata(vaas_1, map, values = FALSE)
stopifnot(!identical(names(metadata(copy)), names(metadata(vaas_1))))

# WMD+formula method
copy <- map_metadata(vaas_1, Organism ~ paste(Species, Strain))
(x <- setdiff(metadata_chars(copy), metadata_chars(vaas_1)))
stopifnot(length(x) == 1, x == "Escherichia coli DSM30083T")
stopifnot(identical(copy, # same result with expression
  map_metadata(vaas_1, expression(Organism <- paste(Species, Strain)))))

# WMD+missing method
(x <- metadata(map_metadata(vaas_1)))
stopifnot(identical(x, metadata(vaas_1))) # nothing to modify in that case

# WMDS method

# using a function
copy <- map_metadata(vaas_4, identity)
stopifnot(identical(copy, vaas_4))
copy <- map_metadata(vaas_4, identity, values = FALSE)
stopifnot(identical(copy, vaas_4))
copy <- map_metadata(vaas_4, function(x) paste(x, "!"), values = FALSE)
(x <- metadata_chars(vaas_4, values = FALSE))
(y <- metadata_chars(copy, values = FALSE))
stopifnot(identical(as.character(y), paste(x, "!")))

# using a character vector
map <- metadata_chars(vaas_4)
map["First replicate"] <- "Rep. 1"
copy <- map_metadata(vaas_4, map)
x <- metadata(vaas_4, "Experiment")
stopifnot(x == "First replicate")
y <- metadata(copy, "Experiment")
stopifnot(y == "Rep. 1")

# using a formula
copy <- map_metadata(vaas_4, Organism ~ paste(Species, Strain))
(x <- setdiff(metadata_chars(copy), metadata_chars(vaas_4)))
stopifnot(length(x) == 4) # one entry per plate

# 'mapping' missing
(x <- metadata(map_metadata(vaas_4)))
stopifnot(identical(x, metadata(vaas_4))) # nothing to modify in that case

## Not run:  ## edit metadata by hand
  x <- edit(vaas_4) # this would create a new object
  x <- edit(x) # overwrite x in 2nd editing step
  ## This will not necessarily work as intended if the metadata are nested!
  ## Moreover, additionally inserted rows would cause an error.

## End(Not run)

## List/formula method of map_values()
x <- list(a = 1:8, c = 9, d = 'x')
(y <- map_values(x, ~ a + c))
stopifnot(is.numeric(y), y == c(10:17))
(y <- map_values(x, b ~ a + c))
stopifnot(is.list(y), y$b == c(10:17))

# ...applied to a data frame
x <- data.frame(a = 1:5, b = 6:10)
(y <- map_values(x, c ~ a + b))
stopifnot(is.data.frame(y), dim(y) == c(5, 3))
(z <- map_values(x, ~ a + b))
stopifnot(identical(z, y$c))
# same effect with an expression
(z <- map_values(x, expression(c <- a + b)))
stopifnot(identical(z, y))

opm documentation built on May 2, 2019, 6:08 p.m.