6.1.common.calculations: Common calculations
In pems.utils: Portable Emissions (and Other Mobile) Measurement System Utilities

Description Usage Arguments Details Value Note Author(s) References See Also Examples

Various common calculations associated with PEMS data.

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)

`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.

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.

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.

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.

Karl Ropkins

References in preparation.

calcVSP for VSP calculations. calcEm for emissions calculations.

###########
##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