6.4.analysis.summary.reports {pems.utils}

Generating summary reports

Description

Various functions for generating summary reports for pems objects.

Usage

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

Arguments

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.

Details

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.

Value

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.

Warning

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

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.

Author(s)

Karl Ropkins

References

References in preparation.

See Also

checkUnits and convertUnits for data management.

Examples

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