6.1.common.calculations {pems.utils}

Common calculations

Description

Various common calculations associated with PEMS data.

Usage

calcDistance(speed = NULL, time = NULL, data = NULL, 
          ..., fun.name = "calcDistance")

calcSpeed(distance = NULL, time = NULL, data = NULL, 
          ..., fun.name = "calcSpeed")

calcAccel(speed = NULL, time = NULL, data = NULL, 
          ..., method = 2, fun.name = "calcAccel")

calcAcceleration(speed = NULL, time = NULL, data = NULL, 
          ..., method = 2, fun.name = "calcAccel")

calcJerk(accel = NULL, time = NULL, data = NULL, 
          ..., fun.name = "calcJerk")

#associated

calcChecks(fun.name = "calcChecks", ..., data = NULL,
          if.missing = c("stop", "warning", "return"), 
          output = c("input", "data.frame", "pems", "special"),
          unit.conversions = NULL, overwrite = FALSE)

calcPack(output = NULL, data = NULL, settings = NULL, 
          fun.name = "calcPack", this.call = NULL)

Arguments

speed, time, distance, accel

(Required data series typically vectors) The inputs to use when doing a calculation. These can typically be vectors or elements in either a data.frame or pems object.

data

(Optional data.frame or pems object) The data source if either a data.frame or pems object is being used.

...

(Optional) Other arguments, currently passed on to calcChecks.

fun.name

(Optional character) The name of the parent function, to be used in error messaging.

if.missing, output, unit.conversions, overwrite, settings, this.call

(Various) Along with data and fun.name, arguments used by calcCheck and calcPack to manage error and unit handling and workhorse calc... operations. These are typically passed to the appropriate check... or ...Units function for evaluation. See Details, Note and Examples below.

method

(Character) Currently for calcAccel only. The method to use if options exist.

Details

With the exception of calcChecks and calcPack, calc... functions are common calculations.

calcDistance calculates distance (in m) using speed and time.

calcSpeed calculates speed (in m/s) using distance and time.

calcAccel calculates acceleration (in m/s/s) using speed and time.

calcJerk calculates jerk (rate of change of acceleration in m/s/s/s) using acceleration and time.

By default results are returned as pems.elements. Other options include returning as the supplied data plus the results as either a data.frame or a pems object. See Note below.

Unit management is by convertUnits. See Note below.

The extra functions calcChecks and calcPack are add-ins that anyone can use to develop other similiar functions. They are added at the start and end of standard calc... functions to provide an option to use with third-party code. See Note.

Value

With the exception of calcChecks and calcPack, all calc... functions return either a pems.element vector, data.frame or pems object, depending on output setting and data supplied.

Note

Unit handling in pems.utils is via checkUnits, getUnits, setUnits and convertUnits. Allowed unit conversion methods have to be defined in ref.unit.conversions or a locally defined alternative supplied by the user. See convertUnits for an example of how to locally work with unit conversions.

calc.dist and calc.accel are alternatives to calcDistance and calcAccel.

The functions calcChecks and calcPack are currently under revision and likely to be replaced in future versions of pems.utils.

Author(s)

Karl Ropkins

References

References in preparation.

See Also

calcVSP for VSP calculations. calcEm for emissions calculations.

Examples

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

#basic usage

#calculated accel as pems.element

calcAccel(velocity, local.time, pems.1)

#answer returned as suppied pems + calculated accel

calcAccel(velocity, local.time, pems.1, output = "pems")

#or, if you would rather... 
## Not run: 
pems.1$accel <- calcAccel(velocity, local.time, pems.1)

## End(Not run)

###########
#example 2
###########

#making wrappers for routine data processing 

my.pems <- list(pems.1, pems.1)

sapply(my.pems, function(x) 
                  calcAccel(velocity, local.time, data=x))

#ans = accel data series for each pems in my.pems list

#             [,1]        [,2]
# [1,]          NA          NA
# [2,]  0.00000000  0.00000000
# [3,]  0.05555556  0.05555556
# [4,]  0.00000000  0.00000000
# [5,] -0.02777778 -0.02777778
# [6,]  0.05555556  0.05555556
#       ....

#note:
#sapply if you can/want to simiplify outputs
#lapply if you want to keep output as a list of answers