Metric reference¶

For metrics, the Receives field in the function descriptions is used to document what columns are assumed to be in the DriveData objects processed by the metric.

amountOfChange ¶

amountOfChange(drivedata: DriveData, var: str)

Calculates the difference between the first and last value of the specified column

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process.	required

Returns:

Type	Description
	(Last value - first value) of the column

closeFollowing ¶

closeFollowing(drivedata: DriveData, threshold: float = 2, percentage: bool = False, minvelocity: Optional[float] = None) -> Optional[float]

Close following is the amount of time where the headway time was lower than a threshold

Very close following is sometimes called tailgating

Parameters:

Name	Type	Description	Default
`threshold`	`float`	maximum following time to collision, in seconds	`2`
`percentage`	`bool`	flag to output a percentage of total time spent following closely, rather than the number of seconds	`False`
`minvelocity`	`Optional[float]`	minimum velocity to consider rows as part of total time. If None, consider all times	`None`

Requires data columns:

SimTime: Simulation time in seconds
HeadwayTime: Headway time in seconds. This is the headway distance multiplied by the current speed of the vehicle.

Returns:

Type	Description
`Optional[float]`	number of seconds or percentage of close following, under the specified threshold

colCount ¶

colCount(drivedata: DriveData, var: str, floor: Optional[float] = 0)

Calculate the number of rows with values greater than the threshold value in a column.

:param drivedata: The DriveData object containing the data. :param var: The name of the variable. :param floor: The lower threshold value of the column. :return: The number of rows with values greater than the threshold value in a column.

colFirst ¶

colFirst(drivedata: DriveData, var: str) -> Any

Returns the first value of the specified column

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process.	required

Returns:

Type	Description
`Any`	First value of selected column.

colLast ¶

colLast(drivedata: DriveData, var: str) -> Optional[float]

Returns the last value of the specified column

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process	required

Returns:

Type	Description
`Optional[float]`	Last value of selected column.

colMax ¶

colMax(drivedata: DriveData, var: str) -> Optional[float]

Calculates the maximum of the specified column

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process. Must be numeric.	required

Returns:

Type	Description
`Optional[float]`	Maximum value of selected column.

colMean ¶

colMean(drivedata: DriveData, var: str, cutoff: Optional[float] = None) -> Optional[float]

Calculates the mean of the specified column

If cutoff is not None, then all values less than cutoff are ignored. If column is not numeric, None is returned.

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process. Must be numeric.	required
`cutoff`	`Optional[float]`	Lower bound on data processed.	`None`

Returns:

Type	Description
`Optional[float]`	Mean of selected column. If `cutoff` is not `None`, then all values less than `cutoff` are ignored. If column is not numeric, `None` is returned.

colMedian ¶

colMedian(drivedata: DriveData, var: str, cutoff: Optional[float] = None) -> Optional[float]

Calculates the median of the specified column

If cutoff is not None, then all values less than cutoff are ignored. If column is not numeric, None is returned.

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process. Must be numeric.	required
`cutoff`	`Optional[float]`	Lower bound on data processed.	`None`

Returns:

Type	Description
`Optional[float]`	Median of selected column. If `cutoff` is not `None`, then all values less than `cutoff` are ignored. If column is not numeric, `None` is returned.

colMin ¶

colMin(drivedata: DriveData, var: str) -> Optional[float]

Calculates the minimum of the specified column

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process. Must be numeric.	required

Returns:

Type	Description
`Optional[float]`	Minimum value of selected column.

colSD ¶

colSD(drivedata: DriveData, var: str, cutoff: Optional[float] = None) -> Optional[float]

Calculates the standard deviation of the specified column

Uses Bessel's correction (denominator of N-1) for SD calculation.

Parameters:

Name	Type	Description	Default
`var`	`str`	The column name to process. Must be numeric.	required
`cutoff`	`Optional[float]`	Lower bound on data processed.	`None`

Returns:

Type	Description
`Optional[float]`	Standard deviation of selected column. If `cutoff` is not `None`, then all values less than `cutoff` are ignored. If column is not numeric, `None` is returned.

leadVehicleCollision ¶

leadVehicleCollision(drivedata: DriveData, cutoff: float = 2.85) -> Optional[float]

Number of collisions between the ownship and the lead vehicle.

Parameters:

Name	Type	Description	Default
`cutoff`	`float`	number of meters below wich the headway distance is considered "collided". Since headway distance is measured center-to-center of the two vehicles, 2.85m is used as the default value based on the size of sedans in the simulation.	`2.85`

Requires data columns

SimTime: Simulation time in seconds
HeadwayDistance: distance between the ownship and the lead vehicle in meters

Returns:

Type	Description
`Optional[float]`	number of collision events

maxacceleration ¶

maxacceleration(drivedata: DriveData, cutofflimit: int = 1) -> Optional[float]

Returns the maximum acceleration value

Parameters:

Name	Type	Description	Default
`cutofflimit`	`int`	all rows with velocities less than this value will be removed	`1`

Requires data columns

LonAccel: Acceleration value in the direction of travel, in meters per second per second
Velocity: Speed in meters per second

Returns:

Type	Description
`Optional[float]`	maximum acceleration value

maxdeceleration ¶

maxdeceleration(drivedata: DriveData, cutofflimit: float = 1) -> Optional[float]

Returns the maximum deceleration value

Parameters:

Name	Type	Description	Default
`cutofflimit`	`float`	all rows with velocities less than this value will be removed	`1`

Requires data columns

LonAccel: Acceleration value in the direction of travel, in meters per second per second
Velocity: Speed in meters per second

Returns:

Type	Description
`Optional[float]`	maximum negative acceleration value (i.e. minimum acceleration value)

numbrakes ¶

numbrakes(drivedata: DriveData, cutofflimit: float = 1) -> Optional[float]

Returns the number of times the brakes were pressed

Parameters:

Name	Type	Description	Default
`cutofflimit`	`float`	minimum velocity at which braking should be considered	`1`

Requires data columns

BrakeStatus: Column indicating braking. 0: no braking, greater than 0: braking
Velocity: Speed

Returns:

Type	Description
`Optional[float]`	number of separate braking events

steeringReversalRate ¶

steeringReversalRate(drivedata: DriveData) -> Optional[float]

Steering reversal rate

As defined in SAE j2944

Requires data columns

SimTime: simulation time
Steer: orientation of steering wheel in radians

Returns:

Type	Description
`Optional[float]`	reversals per minute

steeringReversals ¶

steeringReversals(drivedata: DriveData) -> Optional[float]

Steering reversals, as a count

Requires data columns

SimTime: simulation time
Steer: orientation of steering wheel in radians

Returns:

Type	Description
`Optional[float]`	total reversals in this ROI

stoppingDist ¶

stoppingDist(drivedata: DriveData, roadtravelposition='XPos') -> Optional[float]

Returns the position of the first complete stop of the vehicle, relative to the center position of the DriveData object, as measured by the roadtravelposition column.

This metric is designed to be used with the position-based ROI to define ROIs that have the stop line for a stop sign or stop light as the middle value in the direction of travel.

Parameters:

Name	Type	Description	Default
`roadtravelposition`		column name of increasing distance of travel, in meters	`'XPos'`

Requires data columns

Velocity: Speed in meters per second

Returns:

Type	Description
`Optional[float]`	Number of meters the detected stop is away from the stop line. If no stops detected, return `10000`

timeAboveSpeed ¶

timeAboveSpeed(drivedata: DriveData, cutoff: float = 0, percentage: bool = False) -> Optional[float]

Returns the amount of seconds travelling above the specified speed

Parameters:

Name	Type	Description	Default
`cutoff`	`float`	Speed threshold value	`0`
`percentage`	`bool`	If true, return the percentage of total time in the DriveData object where the speed was above the cutoff.	`False`

Requires data columns

SimTime: Time in seconds
Velocity: Speed

Returns:

Type	Description
`Optional[float]`	Number of seconds travelling above the specified speed.

timeFirstTrue ¶

timeFirstTrue(drivedata: DriveData, var: str, timecol: str = 'SimTime') -> Optional[float]

Time of the first true (>0) value in the specified variable column

Parameters:

Name	Type	Description	Default
`var`	`str`	column to check for first true value	required
`timecol`	`str`	column to use for for time	`'SimTime'`

Returns:

Type	Description
`Optional[float]`	earliest value of the time column when the var column is true (above 0). None is returned if the var column is never true or if there is a error in processing.

timeToOutsideThreshold ¶

timeToOutsideThreshold(drivedata: DriveData, var: str, threshold_low: float = -100000, threshold_high: float = 100000)

Checks a column "var" values to ensure they are within range [threshold_low: threshold_high]

threshold_low & threshold_high are set to extreme numbers by default to ensure users don't have to define irrelevant bounds. Calculates a reaction time for the first occurrence of a threshold violation.

:arg var: column name to check for reaction :arg threshold_low: the value that defines a reaction for the given column, if lower :arg threshold_high: the value that defines a reaction for the given column, if higher

timeWithinSpeedLimit ¶

timeWithinSpeedLimit(drivedata: DriveData, lowerlimit: float = 0, percentage: bool = False) -> Optional[float]

Returns the amount of seconds travelling below the speed limit

Parameters:

Name	Type	Description	Default
`lowerlimit`	`float`	Filter out all velocities lower than this value.	`0`
`percentage`	`bool`	If true, return the percentage of total time in the DriveData object where the speed was under the limit	`False`

Requires data columns

SimTime: Time in seconds
Velocity: Speed in meters per second
SpeedLimit: Speed limit in miles per hour

Returns:

Type	Description
`Optional[float]`	Number of seconds travelling above the specified speed.