6.2.common.check.functions: 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)

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.

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.

Author

Karl Ropkins

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.

References

[TO DO]