read_opm: Read multiple PM files at once or read single PM file

Description Usage Arguments Details Value References See Also Examples

Description

Read OmniLog(R) or opm data file(s) in one of four possible formats: either new- or old-style OmniLog(R) CSV, OmniLog(R) LIMS format or opm YAML (including JSON) format. MicroStation(TM) CSV is also understood, as well as files compressed using gzip, bzip2, lzma or xz. (Files can be specifically excluded using include and/or exclude).

Usage

1
2
3
4
5
6
  read_opm(names = getwd(),
    convert = c("grp", "try", "no", "yes", "sep"),
    gen.iii = opm_opt("gen.iii"), include = list(), ...,
    force = FALSE, demo = FALSE)

  read_single_opm(filename)

Arguments

names

Character vector with names of files in one of the formats accepted by read_single_opm, or names of directories containing such files, or both; or convertible to such a vector. See the include argument of read_opm and explode_dir for how to select subsets from the input files or directories.

filename

Character scalar, or convertible to such, with the obvious meaning.

convert

Character scalar with one of the following values:

no

Always return a list of OPM objects. (This list is rather a MOPMX object than a plain list.)

yes

Convert to NULL, OPM object, or OPMS object, depending on the number of files read (0, 1, or more).

try

Behave like ‘yes’ but do not result in an error message if conversion to OPMS is impossible; return a list (MOPMX object) in that case.

sep

Return a nested list, each partial list (MOPMX object) containing OPM objects of the same plate type.

grp

Also split into such contained lists but convert them to OPMS objects if more than one plate is encountered. An error is raised if this is impossible (in contrast to ‘try’). Return a list (MOPMX object).

gen.iii

Logical or character scalar. If TRUE, invoke gen_iii on each plate. This is automatically done with CSV input if the plate type is given as OTH (which is usually the case for plates run in ID mode). If a character scalar, it is used as the to argument of gen_iii to set other plate types unless it is empty.

include

Pattern for selecting from the input files. The default value results in the output of file_pattern, which should be sufficient in most cases. See explode_dir for details on other possibilities.

...

Optional further arguments passed to explode_dir.

force

Logical scalar passed to gen_iii (if that function is called, see the gen.iii argument).

demo

Logical scalar. Do not read files, but print a vector with the names of the files that would be (attempted to) read, and return them invisibly?

Details

The expected CSV format is what is output by an OmniLog(R) instrument, one plate per file. The data import section of the opm tutorial provides a detailed description of how to generate such files.

The output of a MicroStation(TM) instrument, with one to many plates per file, can also be read. The same holds for the OmniLog(R) LIMS format, which was introduced in 2014 and uses the file extension EXL.

Other formats, or OmniLog(R) files re-saved with distinct CSV settings, are not understood. For this reason, if any editing of the files was necessary at all, it is advisable to do this in an editor for plain text, not in a spreadsheet program.

Plates run in ID mode are automatically detected as such (their plate type is changed from OTH to the internally used spelling of ‘Generation III’). A generation-III or other plate type can also be forced later on by using gen_iii.

It is possible, but not recommended, to read CSV files that contain more than one plate. The data import section of the opm tutorial provides a detailed description of how to batch-generate many files with one plate per file. In contrast, input YAML files can always contain data from more than one plate. The format (which includes JSON) is described in detail under batch_opm.

For splitting lists of OPM objects according to the plate type, see plate_type, and consider the plate-type selection options of opms.

The order in which it is tried to read distinct formats of CSV files can be modified using the ‘input.try.order’ key of opm_opt. The value is an integer vector whose elements have the following meaning:

  1. New-style OmniLog(R) CSV.

  2. Old-style OmniLog(R) CSV.

  3. MicroStation(TM) CSV.

For instance, opm_opt(input.try.order = 2:1 would change the order in which OmniLog(R) formats are tried and deselect MicroStation(TM) files entirely. Negative indexes can be used, but non-negative values not within the range listed above will result in an error. If it known in advance which formats are (not) to be expected, subset creation or just changing the order can be used to accelerate data input.

Value

read_opm returns an OPM object (maybe derived classes such as OPMA in case of YAML input), or list (MOPMX object) of such objects, or a single OPMS object. If demo is TRUE, a character vector instead.

read_single_opm also returns anOPM object. In the case of YAML and multiple-plate CSV input, the result might instead be a list of such objects, but not an OPMS object. Use opm_opt(warn.mult = TRUE) if you want to be warned in such cases.

References

http://www.yaml.org/

http://www.json.org/

http://www.biolog.com/

See Also

utils::read.csv yaml::yaml.load_file

Other io-functions: batch_collect, batch_opm, batch_process, collect_template, explode_dir, file_pattern, glob_to_regex, split_files, to_metadata

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
test.files <- opm_files("omnilog")
if (length(test.files) > 0) { # if the folder is found
  # check first what you *would* get
  x <- read_opm(names = test.files, demo = TRUE)
  stopifnot(identical(test.files, x))
  # these two have the same plate type
  x <- read_opm(names = test.files[1:2], convert = "try")
  class(x)
  dim(x)
  summary(x)
  stopifnot(is(x, "OPMS"), identical(dim(x), c(2L, 384L, 96L)))
} else {
  warning("test files not found")
}
# This can be repeated for the other input test files. Instead of a several
# file names one can also provide a single one, one to several directory
# names, or mixture of file and directory names.

## Not run: 

# Reading all files from the current working directory is also easy:
x <- read_opm(getwd())
# or
x <- read_opm(".")
# or just
x <- read_opm()

## End(Not run)

# read_single_opm()
test.files <- opm_files("omnilog")
if (length(test.files) > 0) { # if the folder is found
  (x <- read_single_opm(test.files[1])) # => 'OPM' object
  class(x)
  dim(x)
  stopifnot(is(x, "OPM"), identical(dim(x), c(384L, 96L)))
} else {
  warning("test-file folder not found")
}
test.files <- opm_files("multiple")
if (length(test.files) > 0) { # if the folder is found
  (x <- read_single_opm(test.files[1])) # => list
  class(x)
  stopifnot(is.list(x), length(x) > 1, sapply(x, is, "OPM"))
} else {
  warning("test-file folder not found")
}

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