Documentation Index
Fetch the complete documentation index at: https://mintlify.com/TracingInsights/tif1/llms.txt
Use this file to discover all available pages before exploring further.
The tif1.types module provides comprehensive type definitions for all data structures used in the library, including TypedDicts for DataFrame schemas and Literal types for enumerations.
DataFrame Union Type
DataFrame
DataFrame = Union[pd.DataFrame, pl.DataFrame]
pd.DataFrame if polars is not installed.
TypedDict Definitions
LapDataDict
class LapDataDict(TypedDict):
"""Type definition for lap data dictionary."""
Session.laps and related methods.
Required Fields
| Field | Type | Description |
|---|
Driver | str | Driver identifier (3-letter code) |
DriverNumber | str | Driver racing number |
Team | str | Team name |
Time | datetime.timedelta | Session time from session start |
Optional Fields - Lap Timing
| Field | Type | Description |
|---|
LapTime | timedelta | None | Total lap time |
LapNumber | float | None | Lap number |
Stint | float | None | Stint number |
PitOutTime | timedelta | None | Time when driver exited pit |
PitInTime | timedelta | None | Time when driver entered pit |
Sector1Time | timedelta | None | Sector 1 time |
Sector2Time | timedelta | None | Sector 2 time |
Sector3Time | timedelta | None | Sector 3 time |
Sector1SessionTime | timedelta | None | Session time at sector 1 |
Sector2SessionTime | timedelta | None | Session time at sector 2 |
Sector3SessionTime | timedelta | None | Session time at sector 3 |
LapStartTime | timedelta | None | Lap start time (from session start) |
LapStartDate | datetime | None | Absolute lap start datetime |
LapTimeSeconds | float | None | Lap time in seconds (derived) |
Optional Fields - Speed Traps
| Field | Type | Description |
|---|
SpeedI1 | float | None | Speed at intermediate 1 (km/h) |
SpeedI2 | float | None | Speed at intermediate 2 (km/h) |
SpeedFL | float | None | Speed at finish line (km/h) |
SpeedST | float | None | Speed at speed trap (km/h) |
| Field | Type | Description |
|---|
Compound | str | None | Tyre compound name |
TyreLife | float | None | Laps on current tyres |
FreshTyre | bool | Whether tyres are fresh |
| Field | Type | Description |
|---|
TrackStatus | str | None | Track status code |
Position | float | None | Position in race/session |
IsPersonalBest | bool | Whether lap is driver’s personal best |
Deleted | bool | None | Whether lap was deleted |
DeletedReason | str | None | Reason for lap deletion |
FastF1Generated | bool | Whether lap is generated by FastF1 |
IsAccurate | bool | Whether lap data is accurate |
Optional Fields - Weather Data
| Field | Type | Description |
|---|
WeatherTime | timedelta | None | Weather data timestamp |
AirTemp | float | None | Air temperature (°C) |
Humidity | float | None | Humidity (%) |
Pressure | float | None | Air pressure (mbar) |
Rainfall | bool | Whether it’s raining |
TrackTemp | float | None | Track temperature (°C) |
WindDirection | int | None | Wind direction (degrees) |
WindSpeed | float | None | Wind speed (km/h) |
TelemetryDataDict
class TelemetryDataDict(TypedDict):
"""Type definition for telemetry data dictionary."""
Lap.telemetry and Driver.telemetry.
Required Fields
| Field | Type | Description |
|---|
Time | float | Timestamp in seconds |
Optional Fields
| Field | Type | Description |
|---|
RPM | int | None | Engine RPM |
Speed | float | None | Speed (km/h) |
nGear | int | None | Gear number |
Throttle | float | None | Throttle position (0-100) |
Brake | int | None | Brake status (0 or 1) |
DRS | int | None | DRS status (0-14) |
Distance | float | None | Distance travelled (meters) |
RelativeDistance | float | None | Relative distance on track |
DriverAhead | str | None | Driver ahead identifier |
DistanceToDriverAhead | float | None | Distance to driver ahead (meters) |
X | float | None | X coordinate position |
Y | float | None | Y coordinate position |
Z | float | None | Z coordinate position |
AccelerationX | float | None | X-axis acceleration (g) |
AccelerationY | float | None | Y-axis acceleration (g) |
AccelerationZ | float | None | Z-axis acceleration (g) |
DataKey | str | None | Data source key |
DriverInfoDict
class DriverInfoDict(TypedDict):
"""Type definition for driver info dictionary."""
| Field | Type | Description |
|---|
driver | str | Driver identifier (3-letter code) |
team | str | Team name |
dn | str | Driver number |
fn | str | First name |
ln | str | Last name |
tc | str | Team color code |
url | str | Driver profile URL |
RaceControlDataDict
class RaceControlDataDict(TypedDict):
"""Type definition for race control data dictionary."""
Required Fields
| Field | Type | Description |
|---|
Time | float | Message timestamp in seconds |
Optional Fields
| Field | Type | Description |
|---|
Category | str | None | Message category |
Message | str | None | Message text |
Status | str | None | Session status |
Flag | str | None | Flag type |
Scope | str | None | Message scope |
Sector | int | str | None | Affected sector |
RacingNumber | str | None | Affected driver number |
Lap | int | None | Lap number |
WeatherDataDict
class WeatherDataDict(TypedDict):
"""Type definition for weather data dictionary."""
Session.weather.
Required Fields
| Field | Type | Description |
|---|
Time | timedelta | Timestamp from session start |
Optional Fields
| Field | Type | Description |
|---|
AirTemp | float | None | Air temperature (°C) |
Humidity | float | None | Humidity (%) |
Pressure | float | None | Air pressure (mbar) |
Rainfall | bool | None | Whether it’s raining |
TrackTemp | float | None | Track temperature (°C) |
WindDirection | int | None | Wind direction (degrees) |
WindSpeed | float | None | Wind speed (km/h) |
Literal Types
SessionType
SessionType = Literal[
"Practice 1",
"Practice 2",
"Practice 3",
"Qualifying",
"Sprint",
"Sprint Qualifying",
"Sprint Shootout",
"Race",
]
"Practice 1" - First practice session"Practice 2" - Second practice session"Practice 3" - Third practice session"Qualifying" - Qualifying session"Sprint" - Sprint race"Sprint Qualifying" - Sprint qualifying session"Sprint Shootout" - Sprint shootout session"Race" - Main race
BackendType
BackendType = Literal["pandas", "polars"]
"pandas" - Use pandas DataFrames (default)"polars" - Use polars DataFrames (requires polars installation)
CompoundType
CompoundType = Literal[
"SOFT",
"MEDIUM",
"HARD",
"INTERMEDIATE",
"WET",
"UNKNOWN",
"TEST_UNKNOWN",
]
"SOFT" - Soft compound (red)"MEDIUM" - Medium compound (yellow)"HARD" - Hard compound (white)"INTERMEDIATE" - Intermediate wet weather tyre (green)"WET" - Full wet weather tyre (blue)"UNKNOWN" - Unknown compound"TEST_UNKNOWN" - Unknown test compound
TrackStatusType
TrackStatusType = Literal["1", "2", "4", "5", "6", "7"]
"1" - Track clear (green flag)"2" - Yellow flag"4" - Safety car"5" - Red flag"6" - Virtual safety car"7" - VSC ending
Protocol Types
DataFrameProtocol
class DataFrameProtocol(Protocol):
"""Protocol for DataFrame-like objects."""
shape: tuple[int, int] - DataFrame dimensions (rows, columns)columns: list[str] - Column names
Required Methods:
head(n: int = 5) - Return first n rows__len__() - Return number of rows__getitem__(key) - Support indexing and slicing
Usage Examples
Type Hints with LapDataDict
from tif1.types import LapDataDict
import tif1
session = tif1.get_session(2024, "Monaco", "Race")
session.load()
# Access lap data with proper type hints
lap: LapDataDict = session.laps.iloc[0].to_dict() # type: ignore
print(f"Driver: {lap['Driver']}")
print(f"Lap Time: {lap.get('LapTime')}")
Backend Type Selection
from tif1.types import BackendType
import tif1
backend: BackendType = "polars"
tif1.set_backend(backend)
Session Type Validation
from tif1.types import SessionType
def get_qualifying_data(year: int, event: str) -> None:
session_type: SessionType = "Qualifying"
session = tif1.get_session(year, event, session_type)
session.load()
