SteeringEntropyModel

class undaqTools.steeringentropy.SteeringEntropyModel(**kwds)

Methods

__init__(**kwds)

Steering Entropy Model as described by Boer, Rakauskas, Ward, and Goodrich (2005).

Model is calibrated to the unique spectral characteristics of the driver. This makes it sensitive to a variety of coping strategies employed by drivers in response to increased workload demands.

A model should be built for each participant. A baseline segment of steering angle data is needed to fit the model via the baseline method. This segment of data should be at least 2 minutes. baseline() will raise an exception if less than 1 minute of data is supplied.

Parameters :

resample_fs : float, optional

Rate in Hz to resample input data. Default is 4. According to Borg et al. this rate is optimizes the senstivity of the entropy estimates.

alpha : float, optional

controls the spacing of the bins used to estimate the prediction errors distribution. Must be between 0-1. The default value is 0.2. According to Borg et al. this rate is optimizes the senstivity of the entropy estimates.

M : int, optional

Controls the number of bins used to estimate the prediction errors distribution. Number of bins is 2*M + 2. Default is 6 (resulting in 14 bins). This is set to avoid having an excess of empty counts when the data set is small.

b_pe : array, optional

AR coefficients (initialized when fit_baseline is called)

pkbas : array, optional

baseline prediction error density coefficients cooresponding to bins (initialized when fit_baseline is called)

bin_edges : array, optional

baseline prediction error density bin edges corresponding to pkbas (initialized when fit_baseline is called)

len(bins) == len(pkbas) + 1

hbas : float, optional

baseline entropy estimate (initialized when fit_baseline is called)

cdf : CDF, optional

Object holding the cumulative density function data of the baseline prediction errors. Used to build bins. (initialized when fit_baseline is called)

Notes

Expecting data to be in degrees. It may not matter but small values will sometimes cause overflow errors in arburg. If you your steering data is in radians it might be better to convert it to degrees.

Loosely based off of Chris’ SteeringEntropy.m script in ndaqTools. Users familiar with ndaqTools should note that the steeringentropy function in ndaqTools (Chris’ matlab) uses the first 60 s to find the AR coeffs and the second 60 s to find baseline prediction error distribution. This module splits the baseline data in half. This class applies a 5th order lowpass to 3/7 the resample_fs as suggested by Boer et al. before resampling. The ndaqTools algorithm just applies an integer factor downsample. Because of these slight differences entropy estimates may differ.

References

Boer, E. R., Rakauskas, M. E., Ward, N. J., and Goodrich. M. A.

(2005). Steering Entropy Revisited. Proceedings of the Third International Driving Symposium on Human Factors in Driver Assessment, Training and Vehicle Design. June 27-30, 2005. Rockport, Maine.

Boer, E. R., Behavioral entropy as an index of workload

Proceedings of the IEA 2000 / HFES 2000 Congress.

Nakayama, O., Futami, T., Nakamura T., and Boer, E. R.,

Development of a steering entropy method for evaluating driver workload. SAE Technical Paper Series #1999-01-0892. Presented at the International Congress and Exposition, Detriot, Michigan. March 1-4, 1999.

fit_baseline(self, x[, fs=60.][, _tsplot=False])

Finds AR coefficients to build prediction errors and estimates baseline prediction errors distribution. Returns the baseline entropy.

Parameters :

x : array_like

Input data. Should specify steering wheel angle over at least 120 s. x[:N/2] is used to find the AR coefficients. x[N/2:] is used to build the baseline prediciton error distribution.

fs : float

sampling rate of x in Hz. Default is 60 Hz. Be sure to specify fs if x was not sampled at 60 Hz.

Returns :

hbas : float

baseline entropy

get_entropy(self, x[, fs=60.][, _pedistplot=False])

Returns steering entropy from given data vector. Specify fs if not collected at 60 Hz.

Parameters :

x : array_like

Input data. Should specify steering wheel angle over at least 60 s

fs : float

sampling rate of x in Hz. Default is 60 Hz. Be sure to specify fs if x was not sampled at 60 Hz.

Returns :

hbas : float

baseline entropy

bode()

returns bode plot of AR coeffs filter

Parameters :None : Returns :fig : matplotlib.figure.Figure

_build_lpfilter(fs)

builds low-pass filter with a cutoff frequency of 3/7th the resample frequency. The filter should be down 40 dB at 1.5 times the cutoff frequency (6/7th) the resample frequency.

Parameters :

fs : the base sampling rate

Returns :

b, a : array_like

Numerator (b) and denominator (a) polynomials of the IIR filter.

_resample(x, fs)

Private method applies 5th low-pass Butterworth filter to x and resamples and returns x at self.resample_fs.

Parameters :

x : array_like

Input data.

fs : float

sampling rate of x in Hz

Returns :

x_resampled : np.ndarray

low-passed and resampled copy of x

_lpfilter_bode()

returns bode plot of the lp filter applied before downsampling

Parameters :None : Returns :fig : matplotlib.figure.Figure

_baseline_tsplot(x, _x, PE, fs)

returns ts plot to fit_baseline so it can be returned indirectly to user

Parameters :

x : array_like

unfiltered data

_x : array_like

lowpassed and downsampled data

PE : array_like

prediction errors

fs : float

base sampling rate

Returns :

fig : matplotlib.figure.Figure

_pedistplot(Pk)

returns plot to get_entropy so it can be returned indirectly to user