R: common check... functions

6.2.common.check.functions {pems.utils}

R Documentation

common check... functions

Description

Various pems.utils workhorse functions for input checking and routine data handling.

Usage

checkOption(option=NULL, allowed.options=NULL,
           option.name = "option", allowed.options.name = "allowed.options",
           partial.match=TRUE, fun.name = "checkOption", 
           if.missing = c("stop", "warning", "return"),
           output = c("option", "test.result"), ...)

checkPEMS(data = NULL, fun.name = "checkPEMS",
           if.missing = c("return", "warning", "stop"),
           output = c("pems", "data.frame", "test.result"),
           ...) 

checkUnits(input = NULL, units = NULL, data = NULL, 
           input.name = NULL, fun.name = "checkUnits", 
           if.missing = c("stop", "warning", "return"),
           output = c("special", "units", "input", "test.result"),
           ..., unit.conversions = NULL)

checkOutput(input = NULL, data = NULL,
           input.name = NULL, fun.name = "checkOutput", 
           if.missing = c("stop", "warning", "return"),
           output = c("pems", "data.frame", "input", "test.result"),
           overwrite = FALSE, ...)

checkIfMissing(..., if.missing = c("stop", "warning", "return"), 
           reply = NULL, suggest = NULL, if.warning = NULL, 
           fun.name = NULL)

Arguments

`input`	(vector, object or object element) An input to be tested or recovered for subsequent use by another function, e.g. a speed measurement from a `pems` object.
`data`	(data.frame, pems object) If supplied, the assumed source for an `input`. This can currently be a standard `data.frame` or a `'pems' object`. Note: if an `input` is not found in `data`, the parent environment is then also checked before returning an error message.
`input.name`, `option.name`	(Optional character vectors) If a `check...` function is used as a workhorse by another function, the name it is given in any associated error messaging. See Note below.
`fun.name`	(Optional character vector) If a `check...` function is used as a workhorse routine within another function, the name of that other function to be used in any associated error messaging. See Note below.
`if.missing`	(Optional character vector) How to handle an input, option, etc, if missing, not supplied or `NULL`. Current options include: `"stop"` to stop the `check...` function and any parent function using it with an error message; `"warning"` to warn users that expected information was missing but to continue running the parent code; or `"return"` to continue running the parent code without any warnings.
`output`	(Character vector) Output mode for `check...` function results. Options typically include the `check type` and `"test.results"`. See Value below.
`...`	(Optional) Other arguments, currently ignored by all `check...` functions expect `checkIfMissing`.
`option`, `allowed.options`, `allowed.options.name`	(Character vectors) For `checkOption`, `option` and `allowed.options` are the supplied option, and the allowed options it should be one of, respectively, and `allowed.options.name` if way these allowed options should be identified in any associated error messaging. See Note below.
`partial.match`	(Logical) For `checkOption`, should partial matching be used when comparing `option` and `allowed.options`.
`units`	(Character vector) For `checkUnits`, the units to return `input` in, if requested (`output = "input"`). Note: The default, `output = "special"`, is a special case which allows `checkUnits` to return either the units if they are not set in the call (equivalent to `output = "units"`) or the `input` in the requested units if they are set in the call (equivalent to `output = "input"`).
`unit.conversions`	(List) For `checkUnits`, the conversion method source. See `ref.unit.conversions` and `convertUnits` for further details.
`overwrite`	(Logical) For `checkOutput`, when packing/repacking a `data.frame` or `pems` object, should 'same name' cases be overwritten? If `FALSE` and 'same names' are encountered, e.g. when modifying an existing `data.frame` or `pems` element, a new element if generated with a unique name in the form `[name].[number]`.
`reply`, `suggest`, `if.warning`	(Character vectors) For `checkIfMissing`, when generating error or warning messages, the main reply/problem description, any suggestions what users can try to fix this, and the action taken by the function if just warning (e.g. setting the missing value to `NULL`), respectively. All are options.

Details

The check... functions are intended as a means of future-proofing pems.utils data handling. They provide routine error/warning messaging and consistent 'front-of-house' handling of function arguments regardless of any underlying changes in the structure of the pems objects and/or pems.utils code. This means third-party function developed using these functions should be highly stable.

checkOption checks a supplied option against a set of allowed options, and then if present or matchable returns the assigned option. It is intended as a workhorse for handling optional function arguments.

checkPEMS checks a supplied data source and provides a short-cut for converting this to and from data.frames and pems object classes. It is intended as a 'best-of-both-worlds' mechanism, so users can supply data in various different formats, but function developers only have to work with that data in one (known) format.

checkUnits checks the units of a previously recovered input, and then, depending on the output setting, returns either the units of the input or the input in the required units (assuming the associated conversion is known).

checkOutput packs/repacks a previously recovered input. Depending on the output setting, this can be as the (standalone) input, an element of a data.frame or an element of a pems object.

checkIfMissing if a workhorse function for the if.missing argument. If any of the supplied additional arguments are NULL, it stops, warns and continues or continues a parent function according to the if.missing argument. If supplied, reply, suggest and if.warning arguments are used to generate the associated error or warning message.

Value

All check... functions return a logical if output = "test.result", TRUE if the input, option, etc., is suitable for use in that fashion or FALSE if not.

Otherwise,

checkOption return the option argument if valid (on the basis of if.missing) or an error, warning and/or NULL (on the basis of if.missing) if not. If partial.match = TRUE and partial matching is possible this is in the full form given in allowed.options regardless of the degree of abbreviation used by the user.

checkPEMS returns the data argument if valid or an error, warning and/or NULL (on the basis of if.missing) if not. Depending on output setting, the valid return is either a data.frame or pems object.

checkUnits returns the units of the input argument if no other information is supplied and units have previously been assigned to that input. If units are assigned in the call or output is forced (output = "input"), the input is returned in the requested units. If this action is not possible (e.g. pems.utils does not know the conversion), the function returns an error, a warning and the unchanged input or the unchanged input alone depending on if.missing setting.

Depening on if.missing argument, checkIfMissing either stops all parent functions with an error message, warns of a problem but allows parent functions to continue running, or allows parent functions to continue without informing the user.

Note

The ...name arguments allow the check... functions to be used silently. If a parent function is identified as fun.name and the check case (codeinput, option, etc.) is identified with the associated ...name argument these are used in any associated error messaging.

Author(s)

Karl Ropkins

References

[TO DO]