Skip to main content

What is a Session?

A Session is the fundamental data container in tif1, representing a single Formula 1 track session. Each session corresponds to one on-track activity during a Grand Prix weekend. Examples are Practice 1, Qualifying, Sprint, or the Race. The Session object is the primary interface for access to all F1 data associated with that particular session. It provides a unified, high-performance API for data retrieval.
  • Driver information - Complete roster of participating drivers with team affiliations, driver numbers, names, and metadata
  • Lap data - Comprehensive lap-by-lap information for all drivers including lap times, sectors, tire compounds, track status, and more
  • Telemetry data - High-frequency sensor data capturing speed, throttle, brake, RPM, gear, DRS, and 3D position coordinates
  • Weather conditions - Time-series weather data including air temperature, track temperature, humidity, wind, and rainfall
  • Race control messages - Official FIA communications including flags, penalties, safety car periods, and track status changes
  • Session results - Final classification with driver and team details, finish status, and laps completed
  • Circuit information - Track layout data including corner positions, angles, and circuit rotation
The Session object uses lazy loading and intelligent caching for maximum performance. Data is fetched from the CDN only on explicit access. Subsequent accesses are served instantly from cache. This architecture enables efficient work with large datasets and keeps the API simple and intuitive.

Session Data Hierarchy

The Session data hierarchy supports efficient navigation and access to the required information.

Data Organization

The Session object organizes data in a logical hierarchy:
  1. Session Level - Top-level metadata, configuration, and session-wide data (weather, race control messages)
  2. Driver Level - Individual driver information, complete lap history for each driver
  3. Lap Level - Single lap data including lap time, sectors, tire compound, track status
  4. Telemetry Level - Sensor data for a specific lap, sampled several times per second (about 7-8 Hz)

Creating a Session

The primary way to create a Session object is through the get_session() function. This function accepts flexible parameters that identify the exact session for analysis.

Basic Session Creation

tif1 resolves the event name in three steps. First, it tries the exact event name. Next, it tries a table of circuit, city, and country aliases, such as "Spa", "Monza", and "USA". Last, it uses fuzzy matching, so a typo such as "Monacco" resolves to Monaco. A fuzzy match needs a score of at least 70 out of 100. A name below that score raises tif1.EventNotFoundError, a subclass of ValueError. An alias for an event that is not on the calendar of that season raises tif1.EventNotInSeasonError, a subclass of EventNotFoundError.

Performance Optimization with Polars

tif1 supports Polars as an alternative DataFrame backend.
Polars (polars>=2.0.0,<3) is installed with tif1. If Polars is not importable, for example after a manual uninstall, tif1 automatically falls back to pandas with a warning.

Cache Control

By default, tif1 caches all fetched data to disk for instant subsequent access. Control the caching behavior for each session:
Disabling cache is useful when:
  • Data pipeline changes are under test
  • Cached data is possibly stale or corrupted
  • A fresh fetch from the CDN is required
  • Live or recent sessions may have updated data

Global Configuration

Set default values for lib and enable_cache globally with the config system:

Session Properties

Session properties provide read-only access to various data types. All properties use lazy loading. Data is fetched only on first access to the property.

drivers

Returns a list of driver numbers as strings, in classification order (as in FastF1). session.drivers[:10] is the top ten. The 3-letter codes are in session.drivers_df["Driver"], in the same order. For seasons whose upstream driver file is sorted by car number only, tif1 rebuilds the order from the laps. That order can miss a post-race penalty.
Returns: list[str] - List of driver numbers as strings

driver_list

Alias for drivers property. Returns the same list of driver numbers.
Returns: list[str] - List of driver numbers as strings

drivers_df

Returns comprehensive driver information as a DataFrame. This is the most detailed driver data available, including names, teams, colors, and headshot URLs. The rows are in the same classification order as session.drivers.
Returns: pandas.DataFrame - DataFrame with 7 columns (Driver, Team, DriverNumber, FirstName, LastName, TeamColor, HeadshotUrl)

laps

Returns all laps for all drivers in the session. This is one of the most important properties, containing comprehensive lap-by-lap data. Key Features:
  • Includes the weather sample that the source data matched to each lap (WeatherTime, AirTemp, and the other weather columns). The match is misaligned for many laps, so use laps.get_weather_data() for the sample of a lap
  • Contains sector times, lap times, tire compounds, track status
  • Includes position data, pit stop information, and more
  • Returns pandas or Polars DataFrame depending on session configuration
Returns: Laps (a pandas DataFrame subclass) or a Polars DataFrame - All laps, with the weather columns
The laps property triggers a network fetch on first access if data is not cached. For sessions with many laps, such as race sessions, this may take a few seconds.

weather

Returns time-series weather data recorded throughout the session. Weather data is sampled at regular intervals (about once per minute).
Returns: DataFrame (pandas or Polars) - Weather data time series
Each row of session.laps carries a weather sample that the source data matched to the lap, but that match is misaligned for many laps. laps.get_weather_data() picks the sample of each lap from session.weather with the fastf1 rule. Use session.weather for the full weather time series.
Time is timedelta64[ns] on pandas and Duration("ns") on polars. Rainfall is a nullable boolean and WindDirection a nullable integer on both backends. When the weather payload cannot be converted, tif1 logs a warning and returns an empty DataFrame. See Empty weather or race control tables.

weather_data

Alias for the weather property. Provides FastF1 API compatibility.
Returns: DataFrame (pandas or Polars) - Weather data time series

race_control_messages

Returns official FIA race control messages issued during the session. These messages include flags, penalties, investigations, safety car periods, and other official communications.
Returns: DataFrame (pandas or Polars) - Race control messages

results

Returns the final classification with driver information, one row per driver in classification order. This property provides a FastF1-compatible SessionResults object.
Race, Sprint, and Qualifying sessions take Status and the times from the official Ergast classification. In the 2025 Bahrain race, Status is "Retired" for SAI and "Disqualified" for HUL. Races and sprints also take GridPosition and Points from it. In every other session, and with ergast=False, GridPosition and Points are NaN (polars: null). The other sessions are classified from the laps, as fastf1 does:
  • Practice: Position by best lap, Status "Finished" for every driver, Laps, and Time, the best lap that is not deleted. get_driver() returns the same row.
  • Sprint Qualifying and Sprint Shootout: the best accurate lap of each segment fills Q1 to Q3. The order is by Q3, then Q2, then Q1. A driver out in Q1 outside 107% of the best Q1 time has ClassifiedPosition "N". The knockout applies. A driver out in Q1 has no Q2 or Q3 time, and a driver out in Q2 has no Q3 time. The Q1 cut is 15 of 20 cars or 16 of 22. For the 2024 Chinese Sprint Qualifying, the top three are NOR, HAM, and ALO.
  • With ergast=False, qualifying follows the same segment rule, and races and sprints use the lap count for Status: "Finished", "+N Laps", or "Did not start".
Practice and the sprint qualifying formats take DriverId and TeamId from the Ergast race results. results.iloc[i].dnf is True unless the status is "Finished", "Lapped", or "+N Lap(s)". Returns: SessionResults (pandas DataFrame subclass, indexed by driver number). On a polars session it is a PolarsSessionResults, with DriverNumber as a column - Session results

car_data

Returns the telemetry of each driver for the whole session, as fastf1 does. The value is a lazy dict (LazyTelemetryDict) keyed by driver number. Driver abbreviations are accepted as keys too. Nothing is fetched until a key is read. len(), iteration, and in use the driver list only. tif1 resolves the car numbers before it builds the keys. A session whose drivers.json has no numbers (the 2024 Belgian Grand Prix) still has number keys. The later drivers of a shared car have number/Abbreviation keys, as in results. Each frame lists every lap of the driver in session order, with each lap-boundary sample once. Its Time is the session clock, as in fastf1: it equals SessionTime.
Returns: LazyTelemetryDict - One Telemetry (a PolarsTelemetry on a polars session) per driver
Each key holds every lap of one driver (about 44,000 samples for a race). The first read of a key fetches one telemetry file per lap of that driver. Use lap.telemetry or session.get_fastest_lap_tel() when one lap is enough.

pos_data

The same dict as car_data. pos_data[n] and car_data[n] hold the same merged frame, because tif1 telemetry carries the car channels and the position channels together.
Returns: LazyTelemetryDict - The same object as car_data

session_info

Returns the fastf1 session_info dict. tif1 builds it from the schedule row and a packaged circuit table, so reading it sends no request beyond the schedule lookup. Key, Meeting.Key, Path, and ArchiveStatus are always None. EndDate is StartDate plus a nominal duration (two hours for a race).
Returns: dict[str, Any] - Session metadata in the fastf1 layout

track_status and session_status

fastf1 reads these two tables from the live-timing streams, which need an F1 account. tif1 reads the same streams from the session_info.json file of the session (2018 onward). The codes and messages are the fastf1 ones. Without the file, tif1 derives the tables from the race control messages, and the values are an approximation.
Time is the session time: add session.t0_date to get the wall-clock date. Refer to the Core API for the status codes and session_start_time. Returns: DataFrame (pandas or Polars) - Time, Status, and Message (track_status); Time and Status (session_status)

name

Returns the human-readable session name (URL-decoded).
Returns: str - Session name

event_name and session_name

Return the readable event and session names. session.gp and session.session keep the URL-encoded forms, because tif1 builds every CDN path from them.
Returns: str - Event name or session name

date

Returns the session date as a pandas Timestamp.
Returns: pandas.Timestamp or pd.NaT - Session date

event

Returns the Event object for this session’s Grand Prix. The Event object contains schedule information for all sessions in the weekend.
Returns: Event - Event object for the Grand Prix weekend

Session Methods

Session methods provide powerful functionality for data analysis, filtering, and retrieval.

load()

Explicitly load session data with fine-grained control over what gets fetched. This method is useful to pre-fetch data or to control exactly what data is loaded. Signature:
Parameters:
  • laps (bool): If True, fetch laps data. Default: True
  • telemetry (bool or "lazy"): If True, fetch telemetry for all laps. Automatically sets laps=True. "lazy" does not fetch telemetry now (see below). Default: True
  • weather (bool): If True, fetch weather data. Default: True
  • messages (bool): If True, fetch race control messages. Default: True
Returns: Session - Returns self for method chaining Examples:
When telemetry=True is requested but laps=False, the method automatically sets laps=True because telemetry requires lap data to function properly.
Loading telemetry for all laps (telemetry=True) can be time-consuming and memory-intensive for race sessions. Such sessions have 20 drivers and 50+ laps each. Consider loading telemetry selectively using driver-specific or lap-specific methods instead.

Lazy telemetry

session.load(telemetry="lazy") does not fetch telemetry. The first access of a lap of a driver fetches all the laps of that driver in one parallel wave. This includes lap.telemetry, lap.get_car_data(), laps.pick_drivers(...).telemetry and get_fastest_lap_tel(). fetch_all_laps_telemetry() fetches the drivers that are not loaded in one batch. The frames and the cache contents are the same as with telemetry=True. When the code reads the drivers in the order of the laps table, the session fetches the next driver in the background (lazy_telemetry_lookahead). On a cold cache, a loop over every lap of a race is then faster than telemetry=True. A notebook that reads four drivers takes 3 s instead of 10 s.
With "lazy", a network error in a telemetry fetch occurs at the first access of the lap, not in load(). The lap then has an empty telemetry frame, as with any failed lap. load() also does not put telemetry in the cache. Use telemetry=True before work without a network. The config key load_telemetry_lazy (environment variable TIF1_LOAD_TELEMETRY_LAZY) gives telemetry=True the effect of "lazy".

get_driver()

Get a Driver object for a specific driver. The Driver object provides convenient access to that driver’s laps and telemetry. Signature:
Parameters:
  • identifier (Any): 3-letter driver code (for example, ‘VER’, ‘HAM’, ‘LEC’) or the driver number as a string or an int (‘1’ or 1). The full name and the number/Abbreviation label of a shared car also work. FastF1-style driver objects with a driver or Abbreviation attribute also work. driver= is the earlier tif1 name of this argument
Returns: Driver - The results row of the driver, with laps and telemetry access. For a car that two drivers shared (before the 1960s), the car number gives the first driver and the number/Abbreviation label gives the other one. Raises: DriverNotFoundError, also a ValueError as in fastf1, for an unknown identifier. Examples:
The get_driver() method uses prefetching. On the first call, it fetches the driver list and the session lap table in parallel. This reduces the wait for the first driver lookup.

get_fastest_laps()

Get the fastest lap(s) from the session. This method can return either the fastest lap per driver or the single overall fastest lap. Signature:
Parameters:
  • by_driver (bool): If True, return fastest lap per driver. If False, return single overall fastest lap. Default: True
  • drivers (list[str] | None): Optional list of driver codes to filter. If None, includes all drivers. Default: None
Returns: Laps (a PolarsLaps on polars) - Fastest lap(s) with all lap data columns, bound to the session whether session.laps was read first or not. A deleted lap is never a fastest lap Examples:
This method skips laps without a LapTime and deleted laps (Deleted == True). A driver whose timed laps were all deleted is not in the result.

get_fastest_lap_tel()

Get telemetry for the overall fastest lap in the session. This is a convenience method that combines finding the fastest lap and fetching its telemetry. Signature:
Parameters:
  • ultra_cold (bool | None): Force the ultra-cold fetch path on or off. None uses the ultra_cold_start config key. Default: None
Returns: DataFrame - Telemetry data for the fastest lap Examples:
On a session without cached data, before any other data access, this method uses the ultra-cold path. It finds the fastest lap in the raw lap payloads and skips cache reads and validation. Then it fetches one telemetry file.

get_fastest_laps_tels()

Fetch telemetry for multiple drivers’ fastest laps in parallel. This is significantly faster than fetching telemetry sequentially. Signature:
Parameters:
  • by_driver (bool): If True, fetch telemetry for each driver’s fastest lap. If False, fetch only the overall fastest lap. Default: True
  • drivers (list[str] | None): Optional list of driver codes to filter. If None, includes all drivers. Default: None
Returns: DataFrame - One telemetry frame for all requested laps, with Driver and LapNumber columns. It is not a dict; group by Driver to get one frame per driver. Examples:
This method uses asynchronous parallel fetching internally, which makes it much faster than calling get_driver(driver).laps.pick_fastest().telemetry for each driver sequentially.

laps_async()

Load all laps from async code. The session.laps property runs the same coroutine through asyncio.run(), so use this method inside an async application. Signature:
Returns: Laps (a PolarsLaps on a polars session) - All laps, the same object that session.laps returns. Examples:
Outside an async context, use the session.laps property instead. It runs the same coroutine.

get_circuit_info()

Get circuit layout information including corner positions, angles, and track rotation. Signature:
Returns: CircuitInfo - Dataclass with circuit information CircuitInfo Attributes:
  • corners (DataFrame): Corner data with columns X, Y, Number, Letter, Angle, Distance
  • marshal_lights (DataFrame): Marshal light positions, with the same columns
  • marshal_sectors (DataFrame): Marshal sector positions, with the same columns
  • rotation (float): Circuit rotation in degrees
  • tif1 extras: circuit_key, circuit_name, location, country, country_code, country_key, pit_loss, track, sections, mini_sector_index, and source
The data comes from the corners.json file of the session. The files of the 2021-2024 seasons have no marshal data. For those seasons, and when the file is missing, the MultiViewer API fills the marshal frames and the corner letters. Seasons before 2018 have no file, so they get the earliest MultiViewer layout of the circuit. A circuit that MultiViewer does not know gets empty frames. source names the origin: "corners.json", "multiviewer", both joined by +, or "" when neither source answered. Examples:
Circuit information is cached after the first call, so subsequent calls are instant.

fetch_all_laps_telemetry()

Fetch telemetry for all laps of all drivers in parallel. session.car_data[driver] loads the same payloads for one driver and joins them into one DataFrame; this method returns one frame per lap. Signature:
Parameters:
  • ultra_cold (bool | None): Skip validation and persistent-cache reads for a faster cold start. Fetched payloads are still written to the cache. None turns it on when the session has no cached data yet. Default: None
Returns: dict[tuple[str, int], DataFrame] - Mapping of (driver_code, lap_number) to that lap’s telemetry. Laps without telemetry are absent from the dict. Examples:
This method fetches telemetry for ALL laps, which can be very slow and memory-intensive. Use sparingly and consider driver-specific or lap-specific methods instead.

Session Types and Formats

tif1 supports all official Formula 1 session types across different weekend formats.

Standard Race Weekend

A typical F1 race weekend consists of:
  1. Practice 1 (FP1) - Friday morning, 60 minutes
  2. Practice 2 (FP2) - Friday afternoon, 60 minutes
  3. Practice 3 (FP3) - Saturday morning, 60 minutes
  4. Qualifying (Q) - Saturday afternoon, ~60 minutes (Q1, Q2, Q3)
  5. Race (R) - Sunday, up to 2 hours

Sprint Weekend

Sprint weekends have a modified format:
  1. Practice 1 (FP1) - Friday, 60 minutes
  2. Sprint Qualifying (SQ) - Friday, ~45 minutes (SQ1, SQ2, SQ3)
  3. Sprint (S) - Saturday, ~30 minutes (~100km race)
  4. Qualifying (Q) - Saturday, ~60 minutes (Q1, Q2, Q3)
  5. Race (R) - Sunday, up to 2 hours

Session Name Variations

tif1 accepts multiple variations of session names for convenience: Matching is case-insensitive, so "fp1", "race", and "r" work as well. Other spellings, such as "Free Practice 1" or "Quali", raise ValueError. A session that the event does not have also raises ValueError, for example "Sprint" on a weekend without a sprint.

Data Loading Architecture

Knowledge of the tif1 data loading process helps with performance optimization and troubleshooting.

Lazy Loading

Sessions use lazy loading for optimal performance. When a Session object is created, no data is fetched immediately. Data is retrieved only on explicit access.
Benefits of Lazy Loading:
  • Fast initialization - Session objects are created instantly
  • Efficient memory usage - Only requested data is loaded
  • Flexible workflows - Load only the data that the analysis requires
  • Reduced network traffic - Avoid fetching unused data

Caching Strategy

tif1 implements a multi-tier caching system for maximum performance:

1. Memory Cache (L1)

  • The session memo inside the Session object, plus process-wide LRU caches for lap tables and payloads
  • No disk or network access
  • The session memo is released with the Session object
  • Automatic and transparent

2. Persistent Cache (L2)

  • SQLite-based disk cache in the tif1 OS-dependent cache directory (configurable via TIF1_CACHE_DIR)
  • Survives across Python sessions
  • Shared between all tif1 sessions
  • Configurable via enable_cache parameter

3. CDN (L3)

  • Three-source CDN chain (jsDelivr, Hugging Face buckets, StaticDelivr) serving TracingInsights data repositories
  • Fetched only on cache miss
  • Automatic retry with exponential backoff
  • Multiple CDN sources for redundancy

Session Loading Flow

Ultra-Cold Start Optimization

tif1 has an ultra-cold start mode for the first fetch of a session that is not in the cache yet. It is on by default (config key ultra_cold_start). It skips the persistent-cache reads and the validation on the critical path. Once a session is cached, tif1 reads the cache instead.
When to Use Ultra-Cold Start:
  • Real-time applications requiring minimum latency
  • One-off queries where caching is not beneficial
  • Benchmarking and performance testing
Trade-offs:
  • Skips data validation (assumes CDN data is correct)
  • One try per request when ultra_cold_skip_retries is on (the default)
  • Skips persistent-cache reads. Fetched payloads are still written to the cache, so the next load is warm

Parallel Fetching

tif1 automatically uses parallel fetching for operations that require multiple network requests:
Parallel Fetching Benefits:
  • Concurrent requests instead of one request after another
  • Efficient use of network bandwidth
  • Automatic connection pooling
  • Configurable concurrency limits (max_concurrent_requests)

Prefetching Strategies

tif1 implements intelligent prefetching to reduce latency:

Driver Lookup Prefetching

Background Telemetry Prefetching

Data Enrichment and Transformations

tif1 automatically enriches and transforms raw F1 data to make it more useful for analysis.

Weather Columns on Every Lap

The lap payload carries a weather sample that the source data matched to each lap, so no manual join is necessary. The match is misaligned for many laps. In the 2025 Bahrain race, 435 of the 1,128 laps carry a sample other than the one that the fastf1 rule picks. For the exact sample of each lap, use laps.get_weather_data().

Computed Columns

tif1 adds computed columns for convenience:

LapTimeSeconds

Numeric representation of lap time for easier calculations:

DriverAhead and DistanceToDriverAhead

Telemetry includes relative position data from the source payload:

Column Renaming and Standardization

tif1 renames columns from the raw CDN format to more intuitive names: The full map is LAP_RENAME_MAP in src/tif1/core_utils/constants.py.

Type Conversions

tif1 automatically converts data types for optimal performance and usability:
See Column types by backend for the full contract.

Data Validation

tif1 validates data integrity and handles edge cases:
  • Missing data - Replaced with the backend’s null values (NaN, NaT, None, <NA> on pandas; null on polars)
  • Sentinel strings - The upstream tokens "None", "null", "nan", and "" become missing values
  • Payload structure - A payload that is not a JSON object raises InvalidDataError. Schema validation with pydantic is off by default; turn it on with the validate_data, validate_lap_times, and validate_telemetry config keys
  • Deleted laps - Kept in laps with Deleted == True. get_fastest_laps() and pick_fastest() skip them
  • Malformed telemetry - Logged and skipped

Performance Optimization Tips

Maximize tif1 performance with these best practices:

1. Use Polars for Large Datasets

Polars is the alternative backend for large datasets:

2. Load Only the Required Data

Use the load() method to control data fetching:

3. Use Driver-Specific Access

get_driver() builds the lap table of one driver only. Both forms below download the same session lap table:

4. Use Parallel Fetching

Use methods that fetch in parallel:

5. Enable Caching

Always use caching unless there is a specific reason not to:

6. Reuse Session Objects

Create session objects once and reuse them:

7. Filter Early

Filter DataFrames as early as possible:

8. Use Ultra-Cold Start for One-Off Queries

Ultra-cold start and single-try fetches are on by default. Keep them on for single-use queries:

9. Avoid Repeated Telemetry Lookups

lap.telemetry fetches the telemetry once and keeps the frame in the session memo. Later reads return the memoized frame without a request. Assign it to a variable to skip the repeated lookups:

10. Monitor Cache Size

Periodically clear cache if disk space is a concern:

Common Patterns and Examples

Pattern: Compare Fastest Laps

Pattern: Analyze Tire Degradation

Pattern: Weather Impact Analysis

Pattern: Sector Analysis

Pattern: Overtaking Analysis

Pattern: Telemetry Heatmap

Troubleshooting

Issue: Slow Data Loading

Symptoms: First access to session.laps takes a long time Solutions:
  1. Check the internet connection
  2. Enable logging with tif1.setup_logging(logging.DEBUG) to see which CDN source fails
  3. Keep ultra-cold start on (the default) for a faster initial fetch
  4. Use Polars backend for faster parsing

Issue: Cache Not Working

Symptoms: Data is fetched from CDN every time Solutions:
  1. Verify caching is enabled: session.enable_cache
  2. Check that the platform-specific cache directory exists
  3. Verify disk space is available
  4. Clear corrupted cache: tif1.get_cache().clear()

Issue: Missing Data

Symptoms: Empty DataFrames or missing columns Solutions:
  1. Verify session exists: Check F1 calendar
  2. Check for typos in event/session names
  3. Some sessions do not have every data type
  4. Use session.drivers to verify drivers are present

Issue: Memory Usage

Symptoms: High memory consumption Solutions:
  1. Use the Polars backend
  2. Load only required data with session.load()
  3. Access driver-specific data instead of all laps
  4. Avoid reading every key of session.car_data (each key holds every lap of one driver)
  5. Process data in chunks

Issue: Telemetry Not Available

Symptoms: Empty telemetry DataFrames Solutions:
  1. Verify telemetry exists for that session/driver
  2. Some drivers may not have telemetry for all laps
  3. Check logs for telemetry fetch failures

Core API

Complete Session class API reference.

Getting Started

Quick start guide and installation.

Data Flow

The tif1 data pipeline.

Caching Strategy

Details of the caching architecture.

Backends

Pandas vs Polars comparison.

Race Analysis Tutorial

Step-by-step race analysis guide.
Last modified on November 3, 2026