R: Input metadata

collect_template {opm}

R Documentation

Input metadata

Description

Either collect a metadata template from OmniLog(R) CSV comments assisting in later on adding metadata using include_metadata, or create a data frame containing potential OPM or OPMS object metadata.

Usage

  ## S4 method for signature 'MOPMX'
collect_template(object,
    outfile = NULL, sep = "\t", previous = outfile, md.args = list(),
    selection = opm_opt("csv.selection"), add.cols = NULL,
    normalize = -1L, instrument = NULL, ..., demo = FALSE) 
  ## S4 method for signature 'OPM'
collect_template(object, outfile = NULL,
    sep = "\t", previous = outfile, md.args = list(),
    selection = opm_opt("csv.selection"), add.cols = NULL, normalize = -1L,
    instrument = NULL, ..., demo = FALSE) 
  ## S4 method for signature 'OPMS'
collect_template(object, outfile = NULL,
    sep = "\t", previous = outfile, md.args = list(),
    selection = opm_opt("csv.selection"), add.cols = NULL, normalize = -1L,
    instrument = NULL, ..., demo = FALSE) 
  ## S4 method for signature 'character'
collect_template(object, outfile = NULL,
    sep = "\t", previous = outfile, md.args = list(),
    selection = opm_opt("csv.selection"), add.cols = NULL, normalize = -1L,
    instrument = NULL, include = list(), ..., demo = FALSE) 

  ## S4 method for signature 'ANY'
to_metadata(object, stringsAsFactors = FALSE,
    optional = TRUE, sep = "\t", strip.white = FALSE, ...) 
  ## S4 method for signature 'MOPMX'
to_metadata(object, stringsAsFactors = FALSE,
    optional = TRUE, sep = "\t", strip.white = FALSE, ...) 
  ## S4 method for signature 'WMD'
to_metadata(object, stringsAsFactors = FALSE,
    optional = TRUE, sep = "\t", strip.white = FALSE, ...) 
  ## S4 method for signature 'WMDS'
to_metadata(object, stringsAsFactors = FALSE,
    optional = TRUE, sep = "\t", strip.white = FALSE, ...) 
  ## S4 method for signature 'character'
to_metadata(object, stringsAsFactors = FALSE,
    optional = TRUE, sep = c("\t", ",", ";"), strip.white = NA, ...)

Arguments

`object`	Character vector or `OPM`, `OPMS` or `MOPMX` object. If a character vector is provided to `collect_template`, it acts like the `names` argument of `read_opm`. That is, if it is a directory name, this is automatically scanned for all CSV and YAML files it contains (unless restrictions with patterns are made). One can also provide file names, or a mixture of file and directory names. Regarding the supported input file formats, see `read_single_opm`. The `OPM`, `OPMS` and `MOPMX` methods collect a data frame from their input object. `to_metadata` needs the name of an input file (unnamed character scalar), or any object convertible to a data frame. Might also be `WMD` or `OPMS` object. If a named character vector with more than a single element, it is used as the first row of the resulting data frame. This behaviour is mainly intended for using this function after a call to the `OPM` method of `csv_data`.
`outfile`	Character scalar. Ignored if `NULL`, empty or empty string. Otherwise, interpreted as the name of a CSV output file. If metadata have already been collected in an older file with the same name, old metadata will be kept, identifiers for novel files will be included, their so far empty entries set to `NA`. Users who wish to keep the old version can use two distinct names for novel and old files; see `previous`.
`sep`	Character scalar used for output (CSV field separator for `outfile`). For the input file of `to_metadata` (which ignores the argument unless `object` is interpreted as input file) a non-empty character vector. Each element is used as CSV field separator in turn, and the first one yielding more than as single column succeeds.
`previous`	Ignored if empty. Otherwise passed to `to_metadata`. If it is a file name different from `outfile`, it is an error if the file does not exist.
`md.args`	List of other arguments passed to the ‘to_metadata’ methods.
`add.cols`	Optional character vector with the names of columns to be added to the result, or `NULL`. If not empty, names of columns to be added, initially containing `NA`.
`selection`	Elements to be extracted from the CSV comments contained in each file. Character vector passed to `csv_data`.
`normalize`	Logical scalar also passed to `csv_data`. The same value must be chosen for subsequent calls of `collect_template` and `include_metadata`.
`instrument`	Logical scalar or scalar convertible to integer, or empty. Ignored if empty. If logical and `TRUE`, `opm_opt("machine.id")` is inserted as additional column. Otherwise, `instrument` is used directly.
`include`	File inclusion pattern (or generator for a pattern). Passed to `batch_collect`.
`...`	Other arguments passed to `batch_collect`, or to `read.delim` or `as.data.frame`.
`demo`	Logical scalar. Run in ‘demo’ mode? Also passed to `batch_collect`. If `TRUE`, file input and output would be omitted and only the respective file names shown.
`stringsAsFactors`	Logical scalar passed to `as.data.frame`.
`optional`	Logical scalar passed to `as.data.frame` or used after negation as ‘check.names’ argument of `read.delim`.
`strip.white`	Logical scalar. For the file-name method, passed to `read.delim` (and set to `TRUE` if it is `NA`). It is often advisable to set this to `FALSE` if CSV input is done for a later call to `collect_template`. For a character vector not interpreted as file name, set to `FALSE` if `NA`.

Details

The collect_template character method batch-collects templates for meta-information from files and optionally adds these data as novel rows to previously collected data. It writes the collected template to a file for use with an external editor, and/or creates a data frame for editing the data directly in R with the edit function.

The to_metadata character method reads metadata from an input file and is only a thin wrapper for read.delim but contains some useful adaptations (such as not converting strings to factors, and not modifying column names). The default method reads metadata from an object convertible to a data frame and is only a thin wrapper of as.data.frame but contains the same useful adaptations as the file-name method.

The WMD and OPMS methods create a data frame from the contained metadata, where necessary converting nested metadata entries to data-frame columns of mode ‘list’. The number of rows of the resulting data frame corresponds to the length of object, the number of columns to the size of the set created from all valid names at the top level of the metadata entries.

Value

to_metadata yields a data frame. The output of collect_template, in the case of the character method, is a data frame, returned invisibly if outfile is given; if demo is TRUE, a character vector of file names instead, returned invisibly. The OPM method returns a data frame with one row and the number of columns equal to the sum of the lengths of selection and add.cols. The OPM method returns such a data frame with one row per contained plate.

References

http://www.biolog.com/

Examples

## collect_template()

# Character method
test.files <- opm_files("omnilog")
if (length(test.files) > 0) { # if the files are found

  # Without writing to a file
  (x <- collect_template(test.files))
  stopifnot(is.data.frame(x), identical(x[, "File"], test.files))
  # now proceed with e.g.
  # x <- edit(x)

  # Write to file
  outfile <- tempfile()
  stopifnot(!file.exists(outfile))
  # This results in a CSV outfile which could be used as a starting point
  # for including the metadata of interest together with the plate
  # identifiers in a single file. include_metadata() can then be used to
  # integrate the metadata in OPMX objects.
  x <- collect_template(test.files, outfile = outfile)
  stopifnot(file.exists(outfile))
  unlink(outfile)
} else {
  warning("test files not found")
}

## Warning in .local(object, ...): possible artefact(s): constant data in
## column(s) C01

## Warning in .local(object, ...): possible artefact(s): constant data in
## column(s) B07, C07, C09, D05, D07, E05, E07, F05

## Warning in .local(object, ...): possible artefact(s): constant data in
## column(s) C01

## Warning in .local(object, ...): possible artefact(s): constant data in
## column(s) B07, C07, C09, D05, D07, E05, E07, F05

# OPM method
(x <- collect_template(vaas_1)) # => data frame, one row per plate

##             Setup Time Position
## 1 8/30/2010_1:53:08_PM     _7-B
##                                                              File
## 1 ./E._coli_DSM_30083T_vim10_7B__1_28_PMX_0_8#30#2010_F__7B_5.csv

stopifnot(dim(x) == c(1, 3))
(x <- collect_template(vaas_1, instrument = TRUE))

##             Setup Time Position
## 1 8/30/2010_1:53:08_PM     _7-B
##                                                              File
## 1 ./E._coli_DSM_30083T_vim10_7B__1_28_PMX_0_8#30#2010_F__7B_5.csv
##   Instrument
## 1          1

stopifnot(dim(x) == c(1, 4))
(x <- collect_template(vaas_1, add.cols = c("A", "B")))

##             Setup Time Position
## 1 8/30/2010_1:53:08_PM     _7-B
##                                                              File    A
## 1 ./E._coli_DSM_30083T_vim10_7B__1_28_PMX_0_8#30#2010_F__7B_5.csv <NA>
##      B
## 1 <NA>

stopifnot(dim(x) == c(1, 5)) # => data frame with more columns
# see include_metadata() for how to use this to add metadata information

# OPMS method
(x <- collect_template(vaas_4)) # => data frame, one row per plate

##              Setup Time Position
## 1  8/30/2010_1:19:11_PM     12-B
## 2  8/30/2010_1:53:08_PM     _7-B
## 3 8/30/2010_12:31:46_PM     17-B
## 4 8/30/2010_11:28:54_AM     22-B
##                                                                   File
## 1      ./E._coli_DSM_18039_vim10_12B__1_28_PMX_0_8#30#2010_E_12B_5.csv
## 2      ./E._coli_DSM_30083T_vim10_7B__1_28_PMX_0_8#30#2010_F__7B_5.csv
## 3 ./P._aeruginosa_DSM_1707_vim10_17B__1_28_PMX_0_8#30#2010_D_17B_5.csv
## 4  ./P._aeruginosa_St._429_vim10_22B__1_28_PMX_0_8#30#2010_C_22B_5.csv

stopifnot(identical(dim(x), c(4L, 3L)))
(x <- collect_template(vaas_4, add.cols = c("A", "B")))

##              Setup Time Position
## 1  8/30/2010_1:19:11_PM     12-B
## 2  8/30/2010_1:53:08_PM     _7-B
## 3 8/30/2010_12:31:46_PM     17-B
## 4 8/30/2010_11:28:54_AM     22-B
##                                                                   File
## 1      ./E._coli_DSM_18039_vim10_12B__1_28_PMX_0_8#30#2010_E_12B_5.csv
## 2      ./E._coli_DSM_30083T_vim10_7B__1_28_PMX_0_8#30#2010_F__7B_5.csv
## 3 ./P._aeruginosa_DSM_1707_vim10_17B__1_28_PMX_0_8#30#2010_D_17B_5.csv
## 4  ./P._aeruginosa_St._429_vim10_22B__1_28_PMX_0_8#30#2010_C_22B_5.csv
##      A    B
## 1 <NA> <NA>
## 2 <NA> <NA>
## 3 <NA> <NA>
## 4 <NA> <NA>

stopifnot(identical(dim(x), c(4L, 5L))) # => data frame with more columns
# again see include_metadata() for how to use this to add metadata
# information

## to_metadata()

# Character method
(x <- to_metadata(list(a = 7:8, `b c` = letters[1:2])))

##   a b c
## 1 7   a
## 2 8   b

tmpfile <- tempfile()
write.table(x, tmpfile, row.names = FALSE, sep = "\t")
(x1 <- read.delim(tmpfile)) # comparison with base R function

##   a b.c
## 1 7   a
## 2 8   b

(x2 <- to_metadata(tmpfile))

##   a b c
## 1 7   a
## 2 8   b

stopifnot(identical(names(x2), names(x)), !identical(names(x1), names(x)))

# Default method
x <- list(a = 7:8, `b c` = letters[1:2])
(x1 <- as.data.frame(x))

##   a b.c
## 1 7   a
## 2 8   b

(x2 <- to_metadata(x))

##   a b c
## 1 7   a
## 2 8   b

stopifnot(!identical(names(x), names(x1)), identical(names(x), names(x2)))

# WMD method
(x <- to_metadata(vaas_1)) # one row per OPM object

##        Experiment          Species    Strain Slot Plate number
## 1 First replicate Escherichia coli DSM30083T    B            6

stopifnot(is.data.frame(x), nrow(x) == length(vaas_1), ncol(x) > 0)

# OPMS method
(x <- to_metadata(vaas_4)) # one row per OPM object

##        Experiment                Species    Strain Slot Plate number
## 1 First replicate       Escherichia coli  DSM18039    B            6
## 2 First replicate       Escherichia coli DSM30083T    B            6
## 3 First replicate Pseudomonas aeruginosa   DSM1707    B            6
## 4 First replicate Pseudomonas aeruginosa    429SC1    B            6

stopifnot(is.data.frame(x), nrow(x) == length(vaas_4), ncol(x) > 0)
copy <- vaas_4
metadata(copy) <- x
stopifnot(identical(copy, vaas_4))
# ... this works only in the special case of non-nested metadata that
# have the same set of entries in all OPMS elements

[Package opm version 1.3.63 Index]