plate_type: Plate type displayed or modified, registered or deleted

In opm: Analysing Phenotype Microarray and Growth Curve Data

Description

Get the type of the OmniLog(R) plate used in the measuring, normalise plate-type names, display known names, or modify the plate type after inputting the plate data. Alternatively, register or remove user-defined plate types.

Usage

  ## S4 method for signature 'MOPMX'
gen_iii(object, ...) 
  ## S4 method for signature 'OPM'
gen_iii(object, to = "gen.iii", force = FALSE) 
  ## S4 method for signature 'OPMS'
gen_iii(object, ...) 

  ## S4 method for signature 'MOPMX'
plate_type(object, ..., normalize = FALSE, subtype = FALSE)
  ## S4 method for signature 'OPM'
plate_type(object, ..., normalize = FALSE, subtype = FALSE)
  ## S4 method for signature 'OPMS'
plate_type(object, ...) 
  ## S4 method for signature 'OPM_DB'
plate_type(object, ..., normalize = FALSE, subtype = FALSE)
  ## S4 method for signature 'character'
plate_type(object, full = FALSE,
    in.parens = TRUE, max = opm_opt("max.chars"), clean = TRUE,
    brackets = FALSE, word.wise = FALSE, paren.sep = " ", downcase = FALSE,
    normalize = TRUE, subtype = FALSE) 
  ## S4 method for signature 'factor'
plate_type(object, ...) 
  ## S4 method for signature 'logical'
plate_type(object, ...) 
  ## S4 method for signature 'missing'
plate_type(object, ...) 

  ## S4 method for signature 'character'
register_plate(object, ...) 
  ## S4 method for signature 'list'
register_plate(object, ...) 
  ## S4 method for signature 'missing'
register_plate(object, ...) 

Arguments

object	OPM, OPMS or MOPMX object, or character vector of original plate name(s), or factor, or logical scalar. If missing, the function displays the plate types opm knows about. If a logical scalar, the behaviour is the same, but optionally restricted to the user-defined or the opm-defined plate types. For register_plate, object is either missing (the easiest way to apply the function), causing the arguments within ... (which should be named) to be used, if any, a named list of NULL values or character vectors, or a character vector whose elements are interpretable as file names. See below for details on the input format.
full	Logical scalar. If TRUE, add (or replace by) the full name of the plate type (if available); otherwise, return it as-is.
in.parens	Logical scalar. This and the five next arguments work like the eponymous ones of wells, but here are applied to the plate name. See there for details.
max	Numeric scalar.
clean	Logical scalar.
brackets	Logical scalar.
word.wise	Logical scalar.
paren.sep	Character scalar.
downcase	Logical scalar.
normalize	Logical scalar. Attempt to normalise the plate-type string before interpreting it?
subtype	Logical scalar. Keep the plate subtype indicator, if any? Only relevant for the character or factor method.
to	Character scalar indicating the plate type. User-defined plate types must be given literally. For generation-III plates, use gen.iii; for the EcoPlate(TM), use eco; the remaining allowed values are only sf.n2, sf.p2, an2, ff and yt, but matching is case-insensitive. A character vector of length greater than one can be passed to the MOPMX method, which recycles its to argument.
force	Logical scalar allowing for changes to essentially all plate types already know to opm, not only the special plate types listed above. Should be used with care, of course.
...	Optional arguments passed between the methods. For register_plate, named arguments to be used if object is missing.

Details

The OPM and OPMS methods of plate_type are convenience methods for one of the more important entries of csv_data with additional options useful for creating plot titles.

The character method normalises the names of OmniLog(R) PM plates to the internally used naming scheme. Unrecognised names are returned unchanged. This needs not normally be called by the opm user but might be of interest.

Factors are treated by passing their levels through the character method.

If a logical scalar is given as object argument, TRUE restricts the output to user-defined plate types (an empty set by default), FALSE to the plate types that ship with opm, and NA shows all plates.

gen_iii change the plate type of an OPM object to ‘Generation III’ or another plate type. This is currently the only function to change plate names. It is intended for Generation-III or other plates that were not devised for the OmniLog instrument but can be run just like PM plates. Usually they will be annotated as some PM plate by the OmniLog(R) system. In contrast, input ID-mode plates are automatically detected (see read_single_opm). For this reason, gen_iii does not enable changes to PM plate types.

User-defined plate types are allowed but need the according prefix (which must currently case-insensitively match ‘Custom:’), even though additional normalisation is done. It is an error to set a user-defined plate type that has not beforehand been registered with register_plate.

The actual spelling of the plate type used might (in theory) differ between distinct versions of opm but is internally consistent. It is an error to set one of the PM plate types or to assign an unknown plate type.

Two kinds of information can be registered for user-defined plates: the full name of the plate and/or the full names of the substrates for all well coordinates. Both kinds of information can be deleted again. In any case, the name of the argument within ... or within object given as list must indicate the plate type. Normalisation is done, as well as adding the usual prefix for user-defined plates.

For registering a full plate name, an unnamed character scalar must be provided. For registering the mapping from well coordinates to substrate names, a named character vector must be provided with the names indicating the well coordinates and the elements indicating the according substrate names. Alternatively, a matrix or data frame can be provided that imitates that physical structure of the plate. That is, the rows are the plate rows (A, B, C, ...) and the columns are the plate columns (1, 2, 3, ...). If row or column names are used, they are honoured.

For deleting a user-defined plate, an empty value (such as NULL or an empty vector) must be provided. Deletion is done for both full plate names and mappings from well coordinates to substrate names. It is ignored whether or not this information had been registered beforehand.

Value

Character scalar in the case of the OPM and OPMS methods of plate_type, otherwise a character vector with the same length than object, or a corresponding factor. If object is not given, a character vector of normalised plate-type names.

gen_iii returns a novel OPMX object.

register_plate returns a logical vector whose values indicate whether information was registered or deleted and whose names are the normalised plate-type names.

See Also

base::strtrim base::abbreviate base::gsub

Other naming-functions: find_positions, find_substrate, listing, opm_files, select_colors, substrate_info, wells

Examples

## 'OPM' method
(x <- plate_type(vaas_1, full = FALSE))
(y <- plate_type(vaas_1, full = TRUE))
(z <- plate_type(vaas_1, full = TRUE, in.parens = FALSE))
# strings lengths differ depending on the selection
stopifnot(nchar(x) < nchar(y), nchar(z) < nchar(y))

## Not run: 

# Splitting a list of 'OPM' objects according to the plate type is easy:
x <- split(x), sapply(x, plate_type))
# but see also opms() and read_opm(), which can do this internally

## End(Not run)

## 'OPMS' method
(xx <- plate_type(vaas_4, full = FALSE))
# plate type is guaranteed to be uniform within an OPMS object
stopifnot(identical(x, xx))

## character and factor methods

# Entirely unrecognized strings are returned as-is
(x <- plate_type(letters))
stopifnot(identical(x, letters))

# Something more realistic
(x <- plate_type(y <- c("PM1", "PM-11C", "PMM04-a"), subtype = TRUE))
stopifnot(x != y)

# Factors
(z <- plate_type(as.factor(y), subtype = TRUE))
stopifnot(is.factor(z), z == x) # same result after conversion

## 'missing' method
(x <- plate_type())
stopifnot(is.character(x), plate_type(vaas_1) %in% x)

## changing the plate type

# 'OPM' method
plate_type(copy <- gen_iii(vaas_1))
stopifnot(identical(vaas_1, copy)) # the data set already had that plate type
plate_type(copy <- gen_iii(vaas_1, "eco")) # which is wrong, actually
stopifnot(!identical(vaas_1, copy))

# 'OPMS' method
plate_type(copy <- gen_iii(vaas_4))
stopifnot(identical(vaas_4, copy)) # as above
plate_type(copy <- gen_iii(vaas_4, "eco"))
stopifnot(!identical(vaas_4, copy)) # as above

## registering plate types

# well map and full name of a plate can be simultaneously registered
register_plate(myplate = c(A01 = "Glucose", A02 = "Fructose"),
  myplate = "Simple fake test plate")
# note standardization of name
stopifnot("CUSTOM:MYPLATE" %in% plate_type(TRUE))
# queries can be done ignoring case differences
listing(wells(plate = "custom:myplate"))

# input/output of plate types
plate.file <- tempfile()
write(to_yaml(listing(wells(plate = "custom:myplate"))), plate.file)
register_plate(plate.file)
unlink(plate.file) # tidying up

# erasing this plate type again; this will delete well map and full name
register_plate(myplate = NULL)
stopifnot(!"CUSTOM:MYPLATE" %in% plate_type(TRUE))

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