Sessions

Understanding sessions in tif1 - the core data container for F1 session analysis

Overview

A Session is the primary data container in tif1, representing a single F1 session (Practice, Qualifying, Race, or Sprint). It provides lazy-loaded access to lap times, telemetry, driver information, weather data, and race control messages.

Creating a Session

Basic Session Creation

The simplest way to create a session is using the get_session() function:

import tif1

# Create a session for the 2024 Monaco Grand Prix Race
session = tif1.get_session(2024, "Monaco Grand Prix", "Race")

Session Types

Tif1 supports all standard F1 session types:

• Practice 1, 2, 3: Free practice sessions
• Qualifying: Qualifying session (Q1, Q2, Q3)
• Sprint: Sprint race
• Sprint Qualifying: Sprint qualifying session
• Race: Main race

# Different session types
fp1 = tif1.get_session(2024, "Silverstone Grand Prix", "Practice 1")
quali = tif1.get_session(2024, "Silverstone Grand Prix", "Qualifying")
race = tif1.get_session(2024, "Silverstone Grand Prix", "Race")

Event Identifiers

You can specify events by name or round number:

# By event name
session = tif1.get_session(2024, "Monaco Grand Prix", "Race")

# By round number
session = tif1.get_session(2024, 7, "Race")  # Round 7

Session Attributes

The Session class exposes several key attributes:

Basic Properties

session = tif1.get_session(2024, "Monaco Grand Prix", "Race")

# Session metadata
print(session.year)      # 2024
print(session.name)      # "Race"
print(session.date)      # Session date as pandas Timestamp

Data Properties

All data properties use lazy loading - data is only fetched when you first access the property:

Laps Data

# Access all laps (loads automatically)
laps = session.laps

# Returns a DataFrame with columns:
# - LapNumber, LapTime, Driver, Team
# - Sector1Time, Sector2Time, Sector3Time
# - Compound, TyreLife, Stint, Position
print(laps.head())

The Session Class

Class Definition

From core.py:1354-1430:

class Session:
    """
    Represents an F1 session with lap and telemetry data.

    Args:
        year: Season year (2018-current)
        gp: Grand Prix name or round number
        session: Session name
        enable_cache: Enable caching (default: True)
        lib: Data library ('pandas' or 'polars')

    Attributes:
        year: Season year
        gp: Grand Prix name (URL encoded)
        session: Session name (URL encoded)
        drivers_df: DataFrame with driver information
        laps: DataFrame with all laps
    """

Lazy Loading Mechanism

Tif1 uses lazy loading to optimize performance. Data is only fetched when you access it:

session = tif1.get_session(2024, "Monaco", "Race")
# No data loaded yet - instant creation

laps = session.laps  # Data loaded now - triggers async fetch
# Subsequent accesses use cached data
laps2 = session.laps  # Instant - returns cached data

Lazy loading means:

• Fast session creation - no network requests until needed
• Selective loading - only fetch the data you need
• Automatic caching - data is cached after first load

Loading Data

The load() Method

You can explicitly control what data gets loaded using session.load():

session = tif1.get_session(2024, "Monaco", "Race")

# Load all data (default)
session.load()

# Load only specific data
session.load(
    laps=True,        # Load lap times
    telemetry=True,   # Load all telemetry (requires laps)
    weather=True,     # Load weather data
    messages=True     # Load race control messages
)

# Load laps and telemetry only
session.load(laps=True, telemetry=True, weather=False, messages=False)

When telemetry=True, laps are automatically loaded (telemetry requires lap data).

Async Loading

For maximum performance, use async loading:

import asyncio
import tif1

async def load_session_data():
    session = tif1.get_session(2024, "Monaco", "Race")
    
    # Load laps asynchronously (4-5x faster)
    laps = await session.laps_async()
    
    return laps

# Run async function
laps = asyncio.run(load_session_data())

Working with Sessions

Getting Fastest Laps

session = tif1.get_session(2024, "Monaco", "Race")

# Get overall fastest lap
fastest = session.get_fastest_laps(by_driver=False)
print(fastest[['Driver', 'LapNumber', 'LapTime']])

# Get fastest lap for each driver
fastest_per_driver = session.get_fastest_laps(by_driver=True)
print(fastest_per_driver[['Driver', 'LapNumber', 'LapTime']])

# Get fastest laps for specific drivers
fastest_top3 = session.get_fastest_laps(
    by_driver=True, 
    drivers=['VER', 'HAM', 'LEC']
)

Accessing Circuit Information

session = tif1.get_session(2024, "Monaco", "Race")

# Get circuit info (corners, rotation)
circuit = session.get_circuit_info()

print(circuit.corners)         # DataFrame with corner locations
print(circuit.rotation)        # Circuit rotation angle

# Add distance markers using telemetry
fastest_lap = session.laps.pick_fastest()
circuit.add_marker_distance(fastest_lap)
print(circuit.corners['Distance'])  # Now populated

Session Results

session = tif1.get_session(2024, "Monaco", "Race")

# Get session results
results = session.results

# Access driver results
for idx, driver in results.iterrows():
    print(f"{driver['FullName']}: {driver['TeamName']}")

Configuration Options

Caching

Control caching behavior:

# Enable caching (default)
session = tif1.get_session(2024, "Monaco", "Race", enable_cache=True)

# Disable caching (always fetch from CDN)
session = tif1.get_session(2024, "Monaco", "Race", enable_cache=False)

Backend Selection

Choose between pandas and polars:

# Use pandas (default)
session = tif1.get_session(2024, "Monaco", "Race", lib="pandas")

# Use polars (faster for large datasets)
session = tif1.get_session(2024, "Monaco", "Race", lib="polars")

Polars can be 2x faster for large datasets but requires the polars package:

pip install tif1[polars]

Performance Tips

1. Use Async Loading

# ❌ Slower - synchronous
laps = session.laps

# ✅ Faster - asynchronous (4-5x faster)
laps = await session.laps_async()

2. Enable Caching

# ✅ Cache enabled - subsequent loads are instant
session = tif1.get_session(2024, "Monaco", "Race", enable_cache=True)

3. Load Only What You Need

# ❌ Loads everything
session.load()

# ✅ Load only laps
session.load(laps=True, telemetry=False, weather=False, messages=False)

4. Use Property Access for Lazy Loading

session = tif1.get_session(2024, "Monaco", "Race")

# Only laps are loaded - weather and messages remain unloaded
laps = session.laps

# Now weather is loaded (on demand)
weather = session.weather

Common Patterns

Analyze Race Pace

session = tif1.get_session(2024, "Monaco", "Race")
laps = session.laps

# Filter for specific driver
ver_laps = laps[laps['Driver'] == 'VER']

# Remove pit laps and invalid laps
race_laps = ver_laps.pick_wo_box().pick_accurate()

# Analyze pace by stint
for stint_num in race_laps['Stint'].unique():
    stint_laps = race_laps[race_laps['Stint'] == stint_num]
    avg_time = stint_laps['LapTime'].mean()
    print(f"Stint {stint_num}: {avg_time}")

Compare Qualifying Performance

quali = tif1.get_session(2024, "Monaco", "Qualifying")

# Get fastest laps per driver
fastest = quali.get_fastest_laps(by_driver=True)

# Sort by lap time
fastest_sorted = fastest.sort_values('LapTime')
print(fastest_sorted[['Driver', 'LapTime', 'Compound']])

Track Evolution Analysis

session = tif1.get_session(2024, "Monaco", "Practice 1")
laps = session.laps

# Analyze track evolution over time
import matplotlib.pyplot as plt

for driver in ['VER', 'HAM', 'LEC']:
    driver_laps = laps[laps['Driver'] == driver].pick_wo_box()
    plt.plot(driver_laps['LapNumber'], driver_laps['LapTime'], label=driver)

plt.xlabel('Lap Number')
plt.ylabel('Lap Time (seconds)')
plt.legend()
plt.title('Track Evolution - Monaco FP1')
plt.show()

Related Topics

Laps and Telemetry

Learn about working with lap data and telemetry

Drivers

Working with driver-specific operations

Data Flow

Understand how data flows from CDN to cache to user

API Reference

Complete Session API documentation