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.

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

colFirst

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

Returns the first value 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]	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. Must be numeric.	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) -> 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
float	reversals per minute

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

throttleReactionTime

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

Calculates the time it takes to accelerate once follow car brakes (r2d)

Requires data columns

• SimTime: Simulation time in secondsSimTime: simulation time
• FollowCarBraking Status: Whether the follow car is braking
• LonAccel: Longitude acceleration
• Brake: Whether the ownship is braking

Returns:

Type	Description
Optional[float]	Time in seconds from when the follow car braked to when the ownship started accelerating forward.

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.

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.