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
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:- Session Level - Top-level metadata, configuration, and session-wide data (weather, race control messages)
- Driver Level - Individual driver information, complete lap history for each driver
- Lap Level - Single lap data including lap time, sectors, tire compound, track status
- 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 theget_session() function. This function accepts flexible parameters that identify the exact session for analysis.
Basic Session Creation
"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:Global Configuration
Set default values forlib 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.
list[str] - List of driver numbers as strings
driver_list
Alias fordrivers property. Returns the same list of driver numbers.
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 assession.drivers.
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 uselaps.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
Laps (a pandas DataFrame subclass) or a Polars DataFrame - All laps, with the weather columns
weather
Returns time-series weather data recorded throughout the session. Weather data is sampled at regular intervals (about once per minute).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 theweather property. Provides FastF1 API compatibility.
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.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-compatibleSessionResults object.
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:
Positionby best lap,Status"Finished"for every driver,Laps, andTime, 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
Q1toQ3. The order is byQ3, thenQ2, thenQ1. A driver out in Q1 outside 107% of the best Q1 time hasClassifiedPosition"N". The knockout applies. A driver out in Q1 has noQ2orQ3time, and a driver out in Q2 has noQ3time. 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 forStatus:"Finished","+N Laps", or"Did not start".
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.
LazyTelemetryDict - One Telemetry (a PolarsTelemetry on a polars session) per driver
pos_data
The same dict ascar_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.
LazyTelemetryDict - The same object as car_data
session_info
Returns the fastf1session_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).
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 thesession_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).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.
str - Event name or session name
date
Returns the session date as a pandas Timestamp.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.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:laps(bool): If True, fetch laps data. Default: Truetelemetry(bool or"lazy"): If True, fetch telemetry for all laps. Automatically sets laps=True."lazy"does not fetch telemetry now (see below). Default: Trueweather(bool): If True, fetch weather data. Default: Truemessages(bool): If True, fetch race control messages. Default: True
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.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: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 thenumber/Abbreviationlabel of a shared car also work. FastF1-style driver objects with adriverorAbbreviationattribute also work.driver=is the earlier tif1 name of this argument
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:
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:by_driver(bool): If True, return fastest lap per driver. If False, return single overall fastest lap. Default: Truedrivers(list[str] | None): Optional list of driver codes to filter. If None, includes all drivers. Default: None
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:ultra_cold(bool | None): Force the ultra-cold fetch path on or off.Noneuses theultra_cold_startconfig key. Default: None
DataFrame - Telemetry data for the fastest lap
Examples:
get_fastest_laps_tels()
Fetch telemetry for multiple drivers’ fastest laps in parallel. This is significantly faster than fetching telemetry sequentially. Signature:by_driver(bool): If True, fetch telemetry for each driver’s fastest lap. If False, fetch only the overall fastest lap. Default: Truedrivers(list[str] | None): Optional list of driver codes to filter. If None, includes all drivers. Default: None
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. Thesession.laps property runs the same coroutine through asyncio.run(), so use this method inside an async application.
Signature:
Laps (a PolarsLaps on a polars session) - All laps, the same object that session.laps returns.
Examples:
get_circuit_info()
Get circuit layout information including corner positions, angles, and track rotation. Signature:CircuitInfo - Dataclass with circuit information
CircuitInfo Attributes:
corners(DataFrame): Corner data with columns X, Y, Number, Letter, Angle, Distancemarshal_lights(DataFrame): Marshal light positions, with the same columnsmarshal_sectors(DataFrame): Marshal sector positions, with the same columnsrotation(float): Circuit rotation in degrees- tif1 extras:
circuit_key,circuit_name,location,country,country_code,country_key,pit_loss,track,sections,mini_sector_index, andsource
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:
ultra_cold(bool | None): Skip validation and persistent-cache reads for a faster cold start. Fetched payloads are still written to the cache.Noneturns it on when the session has no cached data yet. Default: None
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:
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:- Practice 1 (FP1) - Friday morning, 60 minutes
- Practice 2 (FP2) - Friday afternoon, 60 minutes
- Practice 3 (FP3) - Saturday morning, 60 minutes
- Qualifying (Q) - Saturday afternoon, ~60 minutes (Q1, Q2, Q3)
- Race (R) - Sunday, up to 2 hours
Sprint Weekend
Sprint weekends have a modified format:- Practice 1 (FP1) - Friday, 60 minutes
- Sprint Qualifying (SQ) - Friday, ~45 minutes (SQ1, SQ2, SQ3)
- Sprint (S) - Saturday, ~30 minutes (~100km race)
- Qualifying (Q) - Saturday, ~60 minutes (Q1, Q2, Q3)
- 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.- 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_cacheparameter
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 keyultra_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.
- Real-time applications requiring minimum latency
- One-off queries where caching is not beneficial
- Benchmarking and performance testing
- Skips data validation (assumes CDN data is correct)
- One try per request when
ultra_cold_skip_retriesis 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:- 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, uselaps.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: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;nullon 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 thevalidate_data,validate_lap_times, andvalidate_telemetryconfig keys - Deleted laps - Kept in
lapswithDeleted == True.get_fastest_laps()andpick_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 theload() 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 tosession.laps takes a long time
Solutions:
- Check the internet connection
- Enable logging with
tif1.setup_logging(logging.DEBUG)to see which CDN source fails - Keep ultra-cold start on (the default) for a faster initial fetch
- Use Polars backend for faster parsing
Issue: Cache Not Working
Symptoms: Data is fetched from CDN every time Solutions:- Verify caching is enabled:
session.enable_cache - Check that the platform-specific cache directory exists
- Verify disk space is available
- Clear corrupted cache:
tif1.get_cache().clear()
Issue: Missing Data
Symptoms: Empty DataFrames or missing columns Solutions:- Verify session exists: Check F1 calendar
- Check for typos in event/session names
- Some sessions do not have every data type
- Use
session.driversto verify drivers are present
Issue: Memory Usage
Symptoms: High memory consumption Solutions:- Use the Polars backend
- Load only required data with
session.load() - Access driver-specific data instead of all laps
- Avoid reading every key of
session.car_data(each key holds every lap of one driver) - Process data in chunks
Issue: Telemetry Not Available
Symptoms: Empty telemetry DataFrames Solutions:- Verify telemetry exists for that session/driver
- Some drivers may not have telemetry for all laps
- Check logs for telemetry fetch failures
Related Pages
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.