6.4.analysis.summary.reports: Generating summary reports
In pems.utils: Portable Emissions (and Other Mobile) Measurement System Utilities

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

Various functions for generating summary reports for pems objects.

summaryReport(speed = NULL, time = NULL, accel = NULL, 
          distance = NULL, data = NULL, ..., 
          lod.speed = 0.1, lod.accel = 0.1,
          fun.name = "summaryReport")

`speed, accel, time, distance`	(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 if supplied as `data`. See Details below regarding requirements.
`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` which in turn provides access to `pems.utils` management arguments such as `if.missing` and unit handlers such as `unit.conversions`.
`lod.speed, lod.accel`	(numerics) The limits of detection for speed and accel measurements, respectively. [Note: if only one value is given for accel, the accel limits are assumed to be c(-lod.accel, + lod.accel)].
`fun.name`	(Optional character) The name of the parent function, to be used in error messaging.

summaryReport does not strictly require all the arguments speed, accel, time and distance as inputs. It calculates as many of the missing cases as it can using the common.calculations before halting an analysis or warning the user of any problems.

Unit management is by convertUnits. See Note below.

summaryReport returns a one-row data.frame with twelve elements:

distance.travelled.km this total distance travelled (in km)

time.total.s the total time taken (in s)

avg.speed.km.h the mean speed as averaged across the total journey/dataset (in km/h)

avg.running.speed.km.h the mean speed while the vehicle was in motion (in km/h), assuming a 0.01 km/h accuracy for speed measurements.

time.idle.s and time.idle.pc, the time the vehicle was idling (in s and as a percentage, respectively), also assuming a 0.01 km/h cutoff for speed measurements.

avg.accel.m.s.s the mean (positive component of) acceleration (in m/s/s), assuming a 0.1 m/s/s cutoff for accel measurements.

time.accel.s and time.accel.pc, the time the vehicle was accelerating (in s and as a percentage, respectively), also assuming a 0.1 m/s/s cutoff for accel measurements.

avg.decel.m.s.s the mean deceleration (negative component of acceleration in m/s/s), assuming a -0.1 m/s/s cutoff for accel measurements.

time.decel.s and time.decel.pc, the time the vehicle was decelerating (in s and as a percentage, respectively), also assuming a -0.1 m/s/s cutoff for accel measurements.

Currently, summaryReport outputs have units incorporated into their names because the outputs themselves are unitless data.frames.

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.

Karl Ropkins

References in preparation.

checkUnits and convertUnits for data management.

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

#basic usage

summaryReport(velocity, local.time, data=pems.1)

#   distance.travelled.km time.total.s avg.speed.km.h avg.running.speed.km.h
# 1              6.186056         1000        22.2698               28.78538
#   time.idle.s time.idle.pc avg.accel.m.s.s time.accel.s time.accel.pc
# 1          40            4       0.7921279          271          27.1
#   avg.decel.m.s.s time.decel.s time.decel.pc
# 1      -0.9039449          238          23.8

#apply to multiple cases

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

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


#                        [,1]       [,2]      
# distance.travelled.km  6.186056   6.186056  
# time.total.s           1000       1000      
# avg.speed.km.h         22.2698    22.2698   
# avg.running.speed.km.h 28.78538   28.78538  
# time.idle.s            40         40        
# time.idle.pc           4          4         
# avg.accel.m.s.s        0.7921279  0.7921279 
# time.accel.s           271        271       
# time.accel.pc          27.1       27.1      
# avg.decel.m.s.s        -0.9039449 -0.9039449
# time.decel.s           238        238       
# time.decel.pc          23.8       23.8