Overview
The fastf1.utils module provides utility functions for common operations in FastF1, including time conversions, delta time calculations, and recursive dictionary access.
Functions
to_timedelta()
fastf1.utils.to_timedelta(x)
x (str | datetime.timedelta): Timestamp string or timedelta object
Returns:
datetime.timedelta | None: Parsed timedelta object or None if parsing fails
Permissible String Formats:
For example: 13:24:46.320215 with:
- Optional hours and minutes
- Optional microseconds and milliseconds with arbitrary precision (1 to 6 digits)
Examples of valid formats:
24.3564 - seconds + milli/microseconds36:54 - minutes + seconds8:45:46 - hours, minutes, seconds
Example:
import fastf1.utils as utils
# Parse a lap time
lap_time = utils.to_timedelta("1:23.456")
print(lap_time) # 0:01:23.456000
# Parse seconds only
sector_time = utils.to_timedelta("28.345")
print(sector_time) # 0:00:28.345000
to_datetime()
fastf1.utils.to_datetime(x)
x (str | datetime.datetime): Timestamp string or datetime object
Returns:
datetime.datetime | None: Parsed datetime object or None if parsing fails
Permissible String Formats:
For example: 2020-12-13T13:27:15.320000Z with:
- Optional milliseconds and microseconds with arbitrary precision (1 to 6 digits)
- Optional trailing letter ‘Z’
Examples of valid formats:
2020-12-13T13:27:15.3200002020-12-13T13:27:15.32Z2020-12-13T13:27:15
Example:
import fastf1.utils as utils
# Parse session timestamp
session_time = utils.to_datetime("2023-03-05T15:30:00Z")
print(session_time) # 2023-03-05 15:30:00
# Parse with microseconds
precise_time = utils.to_datetime("2023-03-05T15:30:00.123456")
print(precise_time) # 2023-03-05 15:30:00.123456
delta_time()
fastf1.utils.delta_time(reference_lap, compare_lap)
This function is deprecated since version 3.0.0 and may be modified or removed in a future release due to accuracy concerns.
This function has a tendency to give inaccurate results. Always verify the result against sector time differences.
reference_lap (fastf1.core.Lap): The lap taken as referencecompare_lap (fastf1.core.Lap): The lap to compare
Returns:
tuple[pd.Series, fastf1.core.Telemetry, fastf1.core.Telemetry]: A tuple containing:
pd.Series of type float64 with the delta in seconds- Telemetry for the reference lap
- Telemetry for the comparison lap
Use the returned telemetry for plotting to ensure you have telemetry data that was created with the same interpolation and resampling options.
import fastf1 as ff1
from fastf1 import plotting, utils
from matplotlib import pyplot as plt
plotting.setup_mpl(color_scheme='fastf1')
session = ff1.get_session(2021, 'Emilia Romagna', 'Q')
session.load()
lec = session.laps.pick_drivers('LEC').pick_fastest()
ham = session.laps.pick_drivers('HAM').pick_fastest()
delta_time, ref_tel, compare_tel = utils.delta_time(ham, lec)
fig, ax = plt.subplots()
ax.plot(ref_tel['Distance'], ref_tel['Speed'],
color=plotting.get_team_color(ham['Team'], session))
ax.plot(compare_tel['Distance'], compare_tel['Speed'],
color=plotting.get_team_color(lec['Team'], session))
twin = ax.twinx()
twin.plot(ref_tel['Distance'], delta_time, '--', color='white')
twin.set_ylabel("<-- Lec ahead | Ham ahead -->")
plt.show()
recursive_dict_get()
fastf1.utils.recursive_dict_get(d, *keys, default_none=False)
d (dict): The dictionary to traverse*keys (str): Variable number of keys to traversedefault_none (bool, optional): If True, return None instead of empty dict when key doesn’t exist. Default is False.
Returns:
- The value at the nested key path, or
{} (or None if default_none=True) if any key doesn’t exist
Example:
from fastf1.utils import recursive_dict_get
data = {
'session': {
'weather': {
'temperature': 25,
'humidity': 60
}
}
}
# Get nested value
temp = recursive_dict_get(data, 'session', 'weather', 'temperature')
print(temp) # 25
# Missing key returns empty dict
missing = recursive_dict_get(data, 'session', 'track', 'length')
print(missing) # {}
# Or return None instead
missing = recursive_dict_get(data, 'session', 'track', 'length', default_none=True)
print(missing) # None
