opmx.function: Convert user-defined objects to OPMX

In opm: Analysing Phenotype Microarray and Growth Curve Data

Description

Convert data frames with user-defined plate types to OPMX or MOPMX objects.

Usage

  ## S4 method for signature 'data.frame'
opmx(object,
    format = c("horizontal", "rectangular", "vertical"), plate.type = NULL,
    position = NULL, well = NULL, prefix = "T_", sep = object[1L, 1L],
    full.name = NULL, setup.time = date(), filename = "", interval = NULL,
    na.strings = "NA", dec = ".") 

Arguments

object	Data frame containing numeric data with growth or respiration measurements and optional or mandatory additional columns, depending on the format argument.
format	Character scalar indicating the data layout within object. See below for examples. In brief, the formats are: horizontal One row per well, with additional columns providing the substrate names, metadata that identify the plate, and optionally other columns to be used as metadata or csv_data entries. The time points must be given in columns that can be identified with a certain prefix. The part after the prefix must be convertible to numeric data (the time points, ideally given in hours). Several plates and even several plate types can be contained within object. rectangular Several rows and columns per time point, yielding a set of (potentially incomplete) rectangles per plate. Empty columns are skipped; empty rows are skipped or act as separator. Only a single plate, and only measurements are contained within object, thus some of the other arguments cannot be empty. See the interval argument for setting time points and see sep for details of the format. vertical One column per well. Only a single plate, and only measurements and time points are contained within object, thus some of the other arguments cannot be empty. The time points are either contained as column or can be read from the row names. Ideally, they are given in hours.If object has no column names, the first column or the row names yield the time points.
position	Character vector. In ‘horizontal’ format, the name of one to several columns to be joined yielding ‘position’ indicators. These will be used to uniquely identify each plate. The columns to be joined will be kept, too; usually they will end up in the metadata. In this case, the resulting ‘position’ indicators are newly generated rather than literally taken from the input, but yield the same grouping. An empty position argument is possible, but then an accordingly named column must already be present, whose content is used literally. The position argument is mandatory for the ‘rectangular’ and ‘vertical’ formats. It should be chosen so as to identify the resulting OPM object again once it is combined with others into an OPMS object. (By default the setup time is additionally considered but the default for the setup.time argument is just the time of the call to opmx.) For plate position values to be used literally, integers between 0 and 99 (inclusively) followed by a single letters are recommended, because this allows opm to normalise this entry. See the eponymous argument of csv_data.
plate.type	Character scalar. In ‘horizontal’ mode, the name of the column containing the plate-type indicators. After normalisation, these will be used for storing the mapping of well coordinates. The argument is ignored if empty. But then an accordingly named column must already be present OR full.name must contain a single named element, whose name is then inserted as plate name. The plate.type argument is mandatory for the ‘rectangular’ and vertical formats. An according plate type must already have been stored using register_plate and contain the well coordinates found in object. Normalisation of the plate-type name is done, however. In ‘horizontal’ mode, the plate type can be registered beforehand, too, which is useful to enforce a certain ordering of wells. But then the registered well-coordinate map must contains all well coordinates found in object.
well	Character scalar. In ‘horizontal’ format, the name of the column containing the well indicators. These should be substrate names; an according mapping from (newly assigned) well coordinates to these substrate names will then be stored using register_plate if it is not yet present. Ignored if empty (but then an accordingly named column must be present).
prefix	Character scalar. In ‘horizontal’ format, used for identifying the measurements columns.
sep	Character vector, numeric scalar, or empty. In ‘rectangular’ format, used for identifying the rows and column with time-points and well coordinates. If empty, object is split at rows containing only NA values or empty strings. If a positive number, object is split into section with that many rows. If a non-empty character vector, rows harbouring values contained in sep are regarded as the first row of each section. Well coordinates can be missing from each rectangle unless sep is a non-empty character vector. If present, they must comprise single letters in one column and values interpretable as integers in the first row, or otherwise around. If missing, in the case of more rows than columns letters are assigned to the columns, numbers to the rows, else otherwise around.
full.name	Named character vector indicating the full plate names. Ignored if empty. Names should be names of the plate types found within object, if any, but normalisation will be done. Values should be the respective full names. Missing ones are silently ignored. If the plate type is not found within object, then it is taken from the name of full.name, assuming a uniform plate type throughout object. In that case, full.name must contain only a single element (and a single name).
setup.time	Character scalar to be inserted if missing in the data. Like the next argument, the value goes into the csv_data.
filename	Character scalar to be inserted if missing in the data.
interval	Numeric vector. If of length one, indicating the time interval between measurements in the ‘rectangular’ format. If the length corresponds to the number of measurements per well in object, it is interpreted directly as the time points. This is useful if the intervals are non-unique. Ignored if empty, causing 0, 1, 2, ... to be used as time points. (This is often acceptable as it only causes a different scaling; it is not acceptable if the time points were not in regular intervals.) In the case of the vertical format, a non-empty interval value causes the time points to not be extracted from object but constructed from interval. Ideally, interval is given in hours (because this corresponds to the default axis labelling of some plotting functions).
na.strings	Character vector passed to type.convert from the utils package. Currently only relevant for the ‘rectangular’ format.
dec	Likewise.

Details

The main purpose of this function is to convert objects that hold non-PM data to OPMX objects that can be analysed with opm. The mechanism for dealing with user-defined plate types is implemented in register_plate, whereas opmx also takes care of the necessary changes in format and naming for converting a data frame to a MOPMX object.

In contrast to functions for reading PM data, opmx allows for input NA values by removing, within each resulting pseudo-plate (OPM object) individually, all time points that contain at least one NA value. This might lose information, of course, but not between plates, even though it might yield OPMX objects with non-uniform measurement times. A warning is issued in the case of removal.

Value

OPMX or MOPMX object or NULL, depending on how many distinct plate types are encountered within object.

See Also

Other conversion-functions: as.data.frame, extract, extract_columns, flatten, merge, oapply, plates, rep, rev, sort, split, to_yaml, unique

Examples

## 'horizontal' input format

# fake data frame containing growth or respiration measurements
x <- data.frame(
  Treatment = c(rep("Control", 4), rep("Heat stress", 4)),
  Strain = paste0("X", c(1, 2, 2, 1, 2, 1, 1, 2)),
  Substrate = c(rep("Glucose", 2), rep("Galactose", 4), rep("Glucose", 2)),
  T_0 = c(12, 5, 8, 6, 8, 9, 7, 10),
  T_5 = c(23, 7, 7, 18, 30, 10, 8, 9),
  T_10 = c(79, 9, 10, 64, 67, 8, 6, 11),
  T_15 = c(103, 8, 46, 99, 101, 17, 9, 8),
  T_20 = c(105, 9, 77, 112, 103, 44, 8, 12)
)

# The plate type is not contained and thus taken from 'full.name', but
# the wells are obviously within 'Substrate', and each combination of
# 'Treatment' and 'Strain' is apparently one group of measurements
# (interpreted as 'plate').
y <- opmx(x, well = "Substrate", position = c("Treatment", "Strain"),
  full.name = c(sugars = "Fake sugar test plate"))

# This yields a single OPMX object as there is only one plate type.
stopifnot(is(y, "OPMX"), dim(y) == c(4, 5, 2))
print(xy_plot(y, include = list("Strain", "Treatment"),
  theor.max = FALSE, main = list(in.parens = FALSE), ylab = "Hours"))

## 'rectangular' input format

# Get the input file. The rectangular format is hardly suitable for R
# but produced by plate readers such as those distributed by the TECAN
# company.
growth.data.file <- grep("tecan", opm_files("growth"), ignore.case = TRUE,
  value = TRUE)

if (length(growth.data.file)) { # if the file was found

  x <- read.table(growth.data.file)
  head(x)

  # Creating a fake well map. For really making sense of these data, one
  # would need to know the real substrate names.
  well.map <- rbind(1:6, 1:6, 1:6, 1:6)
  well.map[] <- paste0("Substrate ", LETTERS[1:4], well.map)

  # Registering the plate type beforehand is mandatory here because the
  # file does not contain the real substrate names.
  register_plate(XYZ = well.map)
  (y <- opmx(x, "rectangular", plate.type = "XYZ", position = 1,
    interval = 0.25))
  plate_type(y) # => a custom (user-defined) plate
  stopifnot(setequal(wells(y, full = TRUE, in.parens = FALSE), well.map))

  register_plate(XYZ = NULL) # tidying up

} else {
  warning("file with growth data not found")
}

## 'vertical' input format

# Fake data frame. It is safer to set all column names explicitly.
# If none are there, the first column yields the time points unless
# there are explicitly set row names.
x <- data.frame(
  c(0, 5, 10, 15, 20),
  c(12, 23, 79, 103, 105),
  c(5, 7, 9, 8, 9),
  c(8, 7, 10, 46, 77),
  c(6, 18, 64, 99, 112),
  c(8, 30, 67, 101, 103),
  c(9, 10, 8, 17, 44),
  c(7, 8, 6, 9, 8),
  c(10, 9, 11, 8, 12)
)
colnames(x) <- NULL # necessary for this example

# Creating a fake well map for the fake data frame.
well.map <- paste("Substrate", 1:8)
names(well.map) <- paste0("A", 1:8)

# Registering the plate type beforehand is mandatory here because the
# input data frame does not contain the real substrate names.
register_plate(XYZ = well.map)
wells(plate = "CUSTOM:XYZ")[1:10]

(y <- opmx(x, "vertical", plate.type = "XYZ", position = 1))

plate_type(y) # => a custom (user-defined) plate
stopifnot(setequal(wells(y, full = TRUE, in.parens = FALSE), well.map))

register_plate(XYZ = NULL) # tidying up

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