4.2.referencing.pems.data {pems.utils}

Data Referencing Functions.

Description

Various functions for grouping, subsetting, filtering and conditioning datasets.

Usage

refRow(ref = NULL, n = 4, breaks = NULL, 
        data = NULL, ..., labels = NULL,
        fun.name = "refRow")

refX(ref = NULL, n = 4, breaks = NULL, 
        method = "percentile", 
        data = NULL, ..., labels = NULL,
        fun.name = "refX")
        
refEngineOn(rpm = NULL, data = NULL, 
        threshold = 200, ..., labels = NULL, 
        fun.name = "refEngineOn")
        
refDrivingMode(speed = NULL, accel = NULL,
        time = NULL, data = NULL, 
        threshold.speed = 0.1, 
        threshold.accel = 0.1,
        ..., labels = NULL, 
        fun.name = "refDrivingMode")

Arguments

ref

(Data series, typically vector) The reference data-series to consider when making a vector of subset markers/indices. See Details.

n, breaks

(numerics) With refRow and refX, n sets the number of equal intervals to attempt to cut the data into. With refRow, breaks sets the rows at which to cut the data at. With refX, breaks sets the values of ref to cut the data at. In both cases, if both n and breaks are set, breaks is applied.

data

(Optional data.frame or pems object) The data source if ref is supplied in either a data.frame or pems object.

...

(Optional) Other arguments, currently passed on to pems.utils management functions.

labels

(Vector, typically Character) a vector of labels to be assigned to the reference regions.

fun.name

(function managment argument) fun.name is the name of the parent function, to be used in error messaging.

method

(Various) For refX, the method to use when cutting data. If character vector, 'percentile' or 'range'. If function, it should be in form function(ref, n), and return breaks.

rpm

For refEngineOn, the input, assumed to be engine speed and expected to have units of rpm.

threshold

For refEngineOn, the signal threshold above which the vehicle engine is assumed to be on.

speed, accel, time

For refDrivingMode, possible inputs. Strictly, refDrivingMode needs speed and accel but can use speed and time to build accel.

threshold.speed, threshold.accel

For refDrivingMode, the speed and acceleration signal thresholds. Below these thresholds the signals are assumed to be noise and the vehicle is not moving or accelerating, respectively.

Details

ref... functions generate a vector of subset markers or indices based of the referencing method applied and the length of ref. See Value regarding outputs.

refRow assigns reference regions based on row number. Because row depends on the length of the ref element independent of values, this is a unique case where ref can be either a vector or a data set (pems, data.frame). It accepts n to set the number of cases to make or breaks to set break-points at specific rows.

refX assigns reference regions based on the value of a supplied data-series.It accepts n to set the number of cases to make or breaks to set the ref values to make break-points. If using n, method used to assign cut method, e.g. 'percentile' or 'range'.

refEngineOn assigns reference regions based on engine operation status. It uses the input, which it assumes is engine speed, and assumes reported engine speeds larger than the supplied threshold, by default 200 rpm, indicate that the engine is on.

refDrivingMode assigns reference regions based on vehicle driving mode. It uses inputs, assumed to be speed, accel and/or accel, and associated threshold to characterize activity as decel, idle, cruise or accel.

Value

By default results are returned as pems.elements.

The reference vector generated by ref... functions can then be used to group, subset, filter or condition data in pems objects.

refRow assigns reference according to row number, and, by default, reference labels show start row and end row of the referenced case.

refX assigns reference according to value of supplied input, and, by default, reference labels show lower value and higher value of the referenced case.

refEngineOn assigns reference according to engine operation status based on engine speed, and, by default, reference labels are 'on' or 'off'.

refDrivingMode assigns reference according to vehicle driving mode, based on vehicle speed, acceleration and associated thresholds, and, by default, reference labels are decel, idle, cruise and accel.

Note

With refRow, If n is applied and the length of ref is not exactly divisible by n a best attempt is made.

With refX, if breaks are at values that are duplicated, all same values are assigned to the same (lower) value case, so e.g. 'percentile' may vary significantly if break-point values are highly duplicated in ref

Author(s)

Karl Ropkins

References

References in preparation.

See Also

cut, etc. in the main R package.

Examples

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

#basic usage

#working with a temporary pems

temp <- pems.1

#cut into equal subsets

temp$ref <- refRow(velocity, n= 5, data=temp)
pemsPlot(local.time, velocity, cond=ref, data=temp, 
             type="l", layout=c(1,5))

#cut at three points

temp <- pems.1
temp$ref <- refRow(velocity, breaks=c(180,410,700), 
             data=temp)

pemsPlot(local.time, velocity, cond=ref, data=temp, 
             type="l", layout=c(1,5))