2.1.pems.structure {pems.utils}

'pems' object structure

Description

This pages provides a brief outview description of the 'pems' object structure. It also lists some associated functions

Usage

getPEMSElement(x, pems = NULL, units = NULL, ..., 
            fun.name="getPEMSElement", 
            if.missing = "stop", if.null = if.missing, 
            track.name = TRUE, .x = enquo(x))

getPEMSData(pems=NULL, ..., fun.name = "getPEMSData", 
            if.missing = "stop", .pems = enquo(pems))

getPEMSConstants(pems=NULL, ..., 
            fun.name = "getPEMSConstants", 
            if.missing = "stop", .pems = enquo(pems))

pemsData(pems=NULL, ..., 
          fun.name = "pemsData", if.missing = "stop",
          pems.name = deparse(substitute(pems)))

pemsConstants(pems=NULL, ..., 
          fun.name = "pemsConstants", if.missing = "stop",
          pems.name = deparse(substitute(pems)))

pemsHistory(pems=NULL, ..., 
         fun.name = "pemsHistory", if.missing = "stop",
         pems.name = deparse(substitute(pems)))
         
cpe(...)

Arguments

x

(Required vector, typically pems.element) For getPEMSElement, the required data element.

pems

(pems object) If supplied, the pems object to search for x before checking the parent environments and R workspace.

units

(Optional) The units that x should be supplied in (handled by convertUnits).

...

(Optional) Other Arguments.

fun.name, if.missing, if.null, track.name, pems.name, .x, .pems

(Various) Other options using for pems.utils house-keeping. See check... for definitions, although generally these can be ignored by users. See Note below.

Details

The pems object is a managed data.frame. It has five main components: data, units, constants, history and tags. data is the main data.frame. Each element (named data.frame column) is a data-series of the original PEMS data. units are the associated unit definitions. constants is a list of associated constants that are to be used with the pems object. (The preference order is arguments given in a call then constants declared in the pems object then constant defaults held by the pems.utils package.) history is a log of pems object modifications. tags are any other components that the user wishes to add to a pems object as identifiers.

getPEMSElement gets a requested pem.element from pems if supplied or from the local workspace.

pemsData and getPEMSData get the data component of a supplied pems object.

pemsConstants and getPEMSConstants get all constants locally defined for the supplied pems object.

pemsHistory gets the history of supplied pems object.

cpe combines pems.elements. It is intended as an alternative to c(pems.element, ...) while that generic is in-development.

Value

getPEMSElement returns the requested element of a supplied pems object as a managed vector or pems.element, if available. If missing, error handling is by checkIfMissing. See check... for more details.)

pemsData returns the data component of a supplied pems object as a data.frame.

getPEMSData returns the data component of a supplied pems object as a data.frame.

pemsConstants returns the constants component of a supplied pems object as a list.

getPEMSConstants returns the constants component of a supplied pems object as a list.

pemsHistory returns the history component of a supplied pems object as a list.

cpe turns the concatenated form of supplied input.

Note

pems... functions are in development pems object handlers. They are intended for convenient 'front of house' use. As part of this role, their structure will evolve over time, so arguments and operations may change based on user feedback. Those wishing to develop future-proof third party functions should also consider check... functions when developing their code. See common.calculations for some Examples.

getPEMS... functions are a revision of earlier pems... pems object handlers. They are intended to replace pems... code in future package versions.

rlang and dplyr functions now do the heavy lifting for getPEMSElement.

Author(s)

Karl Ropkins

References

rlang and dplyr package functions now do the heavy lifting for getPEMSElement.

Lionel Henry and Hadley Wickham (2018). rlang: Functions for Base Types and Core R and 'Tidyverse' Features. R package version 0.2.0. https://CRAN.R-project.org/package=rlang

Hadley Wickham, Romain Francois, Lionel Henry and Kirill Muller (2017). dplyr: A Grammar of Data Manipulation. R package version 0.7.4. https://CRAN.R-project.org/package=dplyr

See Also

See Also: check... for check... function equivalents; pems.generics for pems object generic functions.

Examples

###########
##example 1 
###########

#basic usage

#using example data pems.1
#(supplied as part of pems.utils package)

#pems structure
pems.1

# extracting the pems.1 element velocity
getPEMSElement(velocity, pems.1)

## Not run: 
#generic (SE) equivalents
pems.1$velocity
pems.1["velocity"] 

## End(Not run)