API reference

lapbox.data

Time conversion, laps, weather, pit stops, stints and gaps.

Every function takes FastF1’s own frames (session.laps, session.weather_data) and returns new ones; nothing is downloaded here and nothing is modified in place.

Summary

normalize_laps: A copy of the laps with float-seconds columns added beside FastF1’s timedeltas.
normalize_weather: A copy of the weather frame with a numeric TimeSeconds column.
derive_pit_stops: One row per pit stop: each in-lap paired with the driver’s next out-lap.
derive_tyre_stints: One row per driver and stint.
gaps_to_car_ahead: Seconds to the car ahead at the line, for every driver and lap.
timedelta_to_seconds: A duration as float seconds.
seconds_to_timedelta: Float seconds as a pd.Timedelta.
format_laptime: A lap or sector time as F1 writes it, M:SS.mmm.

Laps

normalize_lapsfunction

from lapbox.data import normalize_laps

normalize_laps(laps)

A copy of the laps with float-seconds columns added beside FastF1’s timedeltas.

Parameters

laps: pd.DataFrame: FastF1’s laps (session.laps).

Returns

pd.DataFrame: the laps plus LapTimeSeconds, Sector1TimeSeconds, Sector2TimeSeconds, Sector3TimeSeconds, PitInTimeSeconds and PitOutTimeSeconds, for whichever of the source columns exist. Missing times stay missing.

normalize_weatherfunction

from lapbox.data import normalize_weather

normalize_weather(weather)

A copy of the weather frame with a numeric TimeSeconds column.

Parameters

weather: pd.DataFrame: FastF1’s session.weather_data.

Returns

pd.DataFrame

derive_pit_stopsfunction

from lapbox.data import derive_pit_stops

derive_pit_stops(laps)

One row per pit stop: each in-lap paired with the driver’s next out-lap.

Parameters

laps: pd.DataFrame: FastF1’s laps (session.laps).

Returns

pd.DataFrame; empty (with these columns) when Driver, LapNumber or PitInTime is missing.

Columns

Driver: str: The driver.
LapNumber: float: The in-lap.
Stint: float: The stint the in-lap ended.
Compound: str: The tyre the car came in on.
PitInTimeSeconds: float: Session time at pit entry (s).
PitOutTimeSeconds: float: Session time at pit exit, from the next lap (s).
PitStopDurationSeconds: float: Exit minus entry: the time in the pit lane, stop included. NaN when the next lap has no pit-out time.

derive_tyre_stintsfunction

from lapbox.data import derive_tyre_stints

derive_tyre_stints(laps)

One row per driver and stint.

Parameters

laps: pd.DataFrame: FastF1’s laps (session.laps).

Returns

pd.DataFrame sorted by driver and first lap; empty when Driver, Stint, Compound or LapNumber is missing.

Columns

Driver: str: The driver.
Stint: float: FastF1’s stint number.
Compound: str: The tyre.
StintStartLap: float: First lap of the stint.
StintEndLap: float: Last lap of the stint.
StintLength: int: Laps in the stint.
StartTyreLife: float: Tyre age at the start, in laps (with TyreLife). A used set starts above 1.
EndTyreLife: float: Tyre age at the end (with TyreLife).

gaps_to_car_aheadfunction

from lapbox.data import gaps_to_car_ahead

gaps_to_car_ahead(laps)

Seconds to the car ahead at the line, for every driver and lap.

Parameters

laps: pd.DataFrame: FastF1’s laps (session.laps).

Returns

dict[tuple[str, int], float] keyed by (driver, lap), rounded to the millisecond. The leader of a lap has no car ahead and is absent. Empty without Time and LapNumber.

FastF1’s Time is the session time as a driver crosses the line, so sorting one lap number by it gives the running order and the differences are the real gaps. Lapped cars sit on another lap number, so a lapped car physically in front is not counted as the car ahead.

Time

One conversion boundary, safe with None and NaT.

timedelta_to_secondsfunction

from lapbox.data import timedelta_to_seconds

timedelta_to_seconds(value)

A duration as float seconds.

Parameters

value: timedelta | pd.Timedelta | None: A duration, or None / NaT.

Returns

float | None: None when the input is missing.

seconds_to_timedeltafunction

from lapbox.data import seconds_to_timedelta

seconds_to_timedelta(seconds)

Float seconds as a pd.Timedelta.

Parameters

seconds: float | int | None: Seconds, or None / NaN.

Returns

pd.Timedelta | None

format_laptimefunction

from lapbox.data import format_laptime

format_laptime(value)

A lap or sector time as F1 writes it, M:SS.mmm.

Parameters

value: timedelta | pd.Timedelta | float | None: A duration or a number of seconds.

Returns

str: format_laptime(83.245) gives '1:23.245'; a missing value gives '-', so it is safe to drop into a table.

These docs describe lapbox 0.1.0. Something wrong or missing? Open an issue.