2.5.analysis.summary.reports: Generating summary reports

In pems: tools for the analysis and visualisation of pems data

Description

Various functions for generating summary reports for pems objects.

Usage

summaryReport(speed = NULL, time = NULL, accel = NULL, 
          distance = NULL, data = NULL, ..., 
          fun.name = "summaryReport", hijack= FALSE)

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.
fun.name	(Optional character) The name of the parent function, to be used in error messaging.
hijack	(Logical) Is this function being locally 'hijacked' by a user/function developer? See Note on hijack below.

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.

hijack is an in-development argument, supplied to allow code developers to run multiple functions in different function environments. When developers 'mix and match' code from several sources it can become unstable, especially if functions are run within functions within functions, etc. hijack = TRUE and associated code makes a function local to 'side-step' this issue. This work by assuming/expecting all inputs to be local, i.e. supplied directly by the code user.

Author(s)

Karl Ropkins

References

References in preparation.

See Also

checkInput, 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  

pems documentation built on May 2, 2019, 5:20 p.m.