include_metadata {opm} | R Documentation |
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.
## 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())
object |
|
name |
Like |
md |
Data frame containing keys as column names, or
name of file from which to read the data frame. Handled
by |
keys |
Character vector. Corresponds to the
|
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
|
normalize |
Passed to |
mapping |
In most cases passed to
The opm
package augments |
values |
Mostly a logical scalar.
|
classes |
Character vector or (for the character
vector-based mapping) If If |
coerce |
Character vector or |
... |
Optional arguments passed to |
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).
Novel WMD
or WMDS
object with
modified metadata.
utils::edit
Other metadata-functions: metadata
,
metadata_chars
## include_metadata()
(x <- collect_template(vaas_1, add.cols = "Location")) # generate data frame
## Setup Time Position
## 1 8/30/2010_1:53:08_PM _7-B
## File Location
## 1 ./E._coli_DSM_30083T_vim10_7B__1_28_PMX_0_8#30#2010_F__7B_5.csv <NA>
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))
## Experiment Plate number Slot Species Strain
## "Experiment" "Plate number" "Slot" "Species" "Strain"
(y <- metadata_chars(copy, values = FALSE))
## Experiment ! Plate number ! Slot ! Species !
## "Experiment !" "Plate number !" "Slot !" "Species !"
## Strain !
## "Strain !"
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)))
## [1] "Escherichia coli DSM30083T"
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)))
## $Experiment
## [1] "First replicate"
##
## $Species
## [1] "Escherichia coli"
##
## $Strain
## [1] "DSM30083T"
##
## $Slot
## [1] "B"
##
## $`Plate number`
## [1] 6
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))
## Experiment Plate number Slot Species Strain
## "Experiment" "Plate number" "Slot" "Species" "Strain"
(y <- metadata_chars(copy, values = FALSE))
## Experiment ! Plate number ! Slot ! Species !
## "Experiment !" "Plate number !" "Slot !" "Species !"
## Strain !
## "Strain !"
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)))
## [1] "Escherichia coli DSM18039" "Escherichia coli DSM30083T"
## [3] "Pseudomonas aeruginosa 429SC1" "Pseudomonas aeruginosa DSM1707"
stopifnot(length(x) == 4) # one entry per plate
# 'mapping' missing
(x <- metadata(map_metadata(vaas_4)))
## [[1]]
## [[1]]$Experiment
## [1] "First replicate"
##
## [[1]]$Species
## [1] "Escherichia coli"
##
## [[1]]$Strain
## [1] "DSM18039"
##
## [[1]]$Slot
## [1] "B"
##
## [[1]]$`Plate number`
## [1] 6
##
##
## [[2]]
## [[2]]$Experiment
## [1] "First replicate"
##
## [[2]]$Species
## [1] "Escherichia coli"
##
## [[2]]$Strain
## [1] "DSM30083T"
##
## [[2]]$Slot
## [1] "B"
##
## [[2]]$`Plate number`
## [1] 6
##
##
## [[3]]
## [[3]]$Experiment
## [1] "First replicate"
##
## [[3]]$Species
## [1] "Pseudomonas aeruginosa"
##
## [[3]]$Strain
## [1] "DSM1707"
##
## [[3]]$Slot
## [1] "B"
##
## [[3]]$`Plate number`
## [1] 6
##
##
## [[4]]
## [[4]]$Experiment
## [1] "First replicate"
##
## [[4]]$Species
## [1] "Pseudomonas aeruginosa"
##
## [[4]]$Strain
## [1] "429SC1"
##
## [[4]]$Slot
## [1] "B"
##
## [[4]]$`Plate number`
## [1] 6
stopifnot(identical(x, metadata(vaas_4))) # nothing to modify in that case
## Not run:
##D ## edit metadata by hand
##D x <- edit(vaas_4) # this would create a new object
##D x <- edit(x) # overwrite x in 2nd editing step
##D ## This will not necessarily work as intended if the metadata are nested!
##D ## 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))
## [1] 10 11 12 13 14 15 16 17
stopifnot(is.numeric(y), y == c(10:17))
(y <- map_values(x, b ~ a + c))
## $a
## [1] 1 2 3 4 5 6 7 8
##
## $c
## [1] 9
##
## $d
## [1] "x"
##
## $b
## [1] 10 11 12 13 14 15 16 17
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))
## a b c
## 1 1 6 7
## 2 2 7 9
## 3 3 8 11
## 4 4 9 13
## 5 5 10 15
stopifnot(is.data.frame(y), dim(y) == c(5, 3))
(z <- map_values(x, ~ a + b))
## [1] 7 9 11 13 15
stopifnot(identical(z, y$c))
# same effect with an expression
(z <- map_values(x, expression(c <- a + b)))
## a b c
## 1 1 6 7
## 2 2 7 9
## 3 3 8 11
## 4 4 9 13
## 5 5 10 15
stopifnot(identical(z, y))