wells: Listing of well names
In opm: Analysing Phenotype Microarray and Growth Curve Data

Description Usage Arguments Details Value See Also Examples

Get the names of the wells contained in an OPMX object. Optionally the full substrate names can be added in parentheses or brackets or used instead of the coordinate, and trimmed to a given length. The listing methods create a textual listing of the discretised values. (See do_disc for generating discretised data.) This is useful to describe OmniLog(R) phenotype microarray results in a scientific manuscript.

  ## S4 method for signature 'MOPMX'
listing(x, as.groups,
    cutoff = opm_opt("min.mode"), downcase = TRUE, full = TRUE,
    in.parens = FALSE, html = FALSE, sep = " ", ..., exact = TRUE,
    strict = TRUE) 
  ## S4 method for signature 'OPMD'
listing(x, as.groups,
    cutoff = opm_opt("min.mode"), downcase = TRUE, full = TRUE,
    in.parens = FALSE, html = FALSE, sep = " ", ..., exact = TRUE,
    strict = TRUE) 
  ## S4 method for signature 'OPMX'
listing(x, as.groups,
    cutoff = opm_opt("min.mode"), downcase = TRUE, full = TRUE,
    in.parens = FALSE, html = FALSE, sep = " ", ..., exact = TRUE,
    strict = TRUE) 
  ## S4 method for signature 'well_coords_map'
listing(x) 

  ## S4 method for signature 'ANY'
wells(object, full = TRUE, in.parens = FALSE,
    max = opm_opt("max.chars"), brackets = FALSE, clean = TRUE,
    word.wise = FALSE, paren.sep = " ", downcase = FALSE, rm.num = FALSE,
    plate = "PM01", prefix = FALSE, simplify = FALSE) 
  ## S4 method for signature 'MOPMX'
wells(object, ...) 
  ## S4 method for signature 'OPM'
wells(object, full = FALSE, in.parens = TRUE,
    max = opm_opt("max.chars"), brackets = FALSE, clean = TRUE,
    word.wise = FALSE, paren.sep = " ", downcase = FALSE, rm.num = FALSE,
    plate = plate_type(object), prefix = FALSE, simplify = TRUE) 
  ## S4 method for signature 'OPMS'
wells(object, ...) 
  ## S4 method for signature 'missing'
wells(object, ...)

`object`	`OPM` object, `OPMS` or `MOPMX` object or well name or index. If missing, defaults to the selection of all possible wells (for the default plate type, see below).
`full`	Logical scalar. Return the full names of the wells (if available) or just their coordinates on the plate? The following arguments have no effect if `full` is `FALSE`.
`in.parens`	Logical scalar. If `TRUE`, add the full name of the substrate in parentheses (or brackets) after the original name. If `FALSE`, replace by the full substrate name. Note that adding in parentheses (or brackets) is only done if the trimmed substrate names are not empty.
`max`	Numeric scalar. Maximum number of characters allowed in the names. Longer names are truncated and the truncation is indicated by appending a dot.
`brackets`	Logical scalar. Use brackets instead of parentheses?
`clean`	Logical scalar. If `TRUE`, clean trimmed end of full substrate name from non-word characters; use an empty string if only the dot remained.
`word.wise`	Logical scalar. If `TRUE`, abbreviation works by truncating each word separately, and removing vowels first.
`paren.sep`	Character scalar. What to insert before the opening parenthesis (or bracket) if `full` is chosen. Currently only zero to many whitespace characters are allowed. The ability to insert a line break is the main purpose of this argument. Using the ‘at sign’ as value is the only alternative and also special, as it causes the plate name itself to be appended to the well coordinate (after an ‘at sign’, without parentheses or brackets). So mapping is not actually done in that case but the resulting names are understood by certain other opm methods which can conduct the mapping at a later stage.
`downcase`	Logical scalar indicating whether full names should be (carefully) converted to lower case. This uses `substrate_info` in `downcase` mode; see there for details.
`rm.num`	Logical scalar indicating whether numbering (used in the case of replicated substrates per plate) should be stripped from the end of the full well names.
`plate`	Name of the plate type. Several ones can be given unless `object` is of class `OPM` or `OPMS`. Normalisation as in `plate_type` is applied before searching for the substrate names but otherwise the match must be exact.
`prefix`	Logical scalar indicating whether the (short) plate name should be prepended to the well name. Only works in conjunction with `full` and `in.parens`.
`simplify`	Logical scalar indicating whether the result should be simplified to a vector. This will never be done if more than a single column is contained, i.e. if data for more than a single plate type are queried for.
`...`	Optional arguments passed between the methods.
`x`	`OPMD`, `OPMS` or `well_coords_map` object.
`as.groups`	Key suitable for querying the metadata, or `NULL`. If non-empty, passed as eponymous argument to `extract`. Thus `TRUE` and `FALSE` can be used, creating either a single group or one per plate. The extracted metadata define groups for which the discretised data are aggregated. If `x` is an `OPMD` object and `as.groups` is not empty, it is used to create the row name of the single row of the resulting `OPMS_Listing` object. Otherwise an `OPMD_Listing` object is produced.
`cutoff`	Numeric scalar used if ‘as.groups’ is non-empty. If the relative frequency of the most frequent entry within the discretised values to be joined is below that cutoff, `NA` is used. Ignored if `x` is an `OPMD` object but added to the result if `as.groups` is non-empty.
`html`	Logical scalar. Convert to HTML? This involves Greek letters and paragraph (‘div’) tags.
`sep`	Character scalar used for joining the ‘as.groups’ entries (if any).
`exact`	Logical scalar passed to `metadata`.
`strict`	Logical scalar also passed to `metadata`.

Do not confuse wells this with well. The purpose of the OPM and OPMS methods for wells should be obvious. The default method is intended for providing a quick overview of the substrates contained in one to several plates if full is TRUE. If full is FALSE, it can be used to study the effect of the well-index translation and well-name normalisation approaches as used by opm, particularly by the sub-creation methods (see [).

The wells methods return a named character vector or a named matrix of the S3 class well_coords_map, depending on simplify and plate.

The return value of the listing methods for OPMX objects is a character vector or matrix with additional class attribute OPMD_Listing or OPMS_Listing.

The well_coords_map method creates a nested list of the class well_coords_listing which can be used in conjunction with to_yaml or saveRDS for externally storing well maps. See the examples for details.

base::strtrim base::abbreviate

Other naming-functions: find_positions, find_substrate, gen_iii, opm_files, plate_type, register_plate, select_colors, substrate_info

## wells() 'OPM' method
(x <- wells(vaas_1, full = FALSE))[1:10]
(y <- wells(vaas_1, full = TRUE))[1:10]
(z <- wells(vaas_1, full = TRUE, in.parens = FALSE))[1:10]
# string lengths differ depending on selection
stopifnot(nchar(x) < nchar(y), nchar(z) < nchar(y))

## wells() 'OPM' method
(xx <- wells(vaas_4, full = FALSE))[1:10]
# wells are guaranteed to be uniform within OPMS objects
stopifnot(identical(x, xx))

## wells() default method
x <- c("A01", "B10")
(y <- wells(x, plate = "PM1"))
stopifnot(nchar(y) > nchar(x))
(z <- wells(x, plate = "PM1", in.parens = TRUE))
stopifnot(nchar(z) > nchar(y))
# formula yields same result
stopifnot(y == wells(~ c(A01, B10), plate = "PM1"))
# querying for several plate types at once
(y <- wells(~ c(A01, B10), plate = c("PM2", "PM3", "PM10")))
stopifnot(dim(y) == c(2, 3))
(z <- listing(y)) # create a printable nested list
stopifnot(is.list(z), sapply(z, is.list), names(z) == colnames(y))
# using a sequence of well coordinates
stopifnot(nrow(wells(~ C02:C06)) == 5) # well sequence
stopifnot(nrow(wells(plate = "PM1")) == 96) # all wells by default

## listing() 'OPMD' method

# this yields one sentence for each kind of reaction:
(x <- listing(vaas_1, NULL))
stopifnot(inherits(x, "OPMD_Listing"), is.character(x), length(x) == 3,
  !is.null(names(x)))

# create an 'OPMS_Listing' object
(y <- listing(vaas_1, ~ Species + Strain))
stopifnot(inherits(y, "OPMS_Listing"), is.matrix(y), dim(y) == c(1, 3),
  y == x, colnames(y) == names(x), !is.null(rownames(y)))

# including HTML tags
(y <- listing(vaas_1, NULL, html = TRUE))
stopifnot(inherits(y, "OPMD_Listing"), is.character(x), nchar(y) > nchar(x),
  !is.null(names(x)))

## listing() 'OPMS' method

# no grouping, no names (numbering used instead for row names)
(x <- listing(vaas_4[1:2], as.groups = NULL))
stopifnot(inherits(x, "OPMS_Listing"), is.matrix(x), dim(x) == c(2, 3))
stopifnot(!is.null(rownames(x)), !is.null(colnames(x)))
(y <- listing(vaas_4[1:2], as.groups = FALSE)) # alternative
stopifnot(identical(x, y))

# in effect no grouping, but names
(x <- listing(vaas_4[1:2], as.groups = list("Species", "Strain")))
stopifnot(inherits(x, "OPMS_Listing"), is.matrix(x), dim(x) == c(2, 3))
stopifnot(!is.null(rownames(x)), !is.null(colnames(x)))

# only single group for all plates
(y <- listing(vaas_4[1:2], as.groups = TRUE))
stopifnot(inherits(y, "OPMS_Listing"), is.matrix(y), dim(y) == c(1, 3))
stopifnot(!is.null(rownames(x)), !is.null(colnames(x)))

# two groups
(x <- listing(vaas_4, as.groups = list("Species")))
stopifnot(inherits(x, "OPMS_Listing"), is.matrix(x), dim(x) == c(2, 3))
stopifnot(!is.null(rownames(x)), !is.null(colnames(x)))