Getting Started Guide

This guide walks you through everything you need to know to start analyzing Formula 1 data with tif1.

Prerequisites

Before you begin, ensure you have:

Python 3.10 or higher
pip or uv package manager
Basic knowledge of pandas or polars
Internet connection for data fetching

Installation

Install tif1

Install using pip or uv:

pip install tifone

uv pip install tif1

Verify Installation

Check that tif1 is installed correctly:

python -c "import tif1; print(tif1.__version__)"

Your first analysis

Let’s load and analyze data from a recent race.

Step 1: load a session

import tif1

# Load the 2025 monaco grand prix race
session = tif1.get_session(2025, "Monaco Grand Prix", "Race")

print(f"Loaded session: {session.event} {session.session_type}")

The first time you load a session, tif1 fetches data from the CDN. Subsequent loads are instant thanks to caching.

Step 2: explore drivers

# Get list of drivers
drivers = session.drivers_df

print(drivers[["Driver", "Team", "DriverNumber"]])

Output:

  Driver                Team  DriverNumber
0    VER  Red Bull Racing            33
1    HAM         Mercedes            44
2    LEC          Ferrari            16
...

Step 3: analyze lap times

# Get all laps
laps = session.laps

# Show fastest laps
fastest = laps.nsmallest(10, "LapTime")
print(fastest[["Driver", "LapNumber", "LapTime", "Compound"]])

Step 4: compare drivers

# Get specific drivers
ver = session.get_driver("VER")
lec = session.get_driver("LEC")

# Compare fastest laps
ver_fastest = ver.get_fastest_lap()
lec_fastest = lec.get_fastest_lap()

print(f"VER: {ver_fastest['LapTime'].iloc[0]:.3f}s")
print(f"LEC: {lec_fastest['LapTime'].iloc[0]:.3f}s")

Step 5: analyze telemetry

# Get telemetry for fastest lap
ver_lap = ver.get_fastest_lap()
lap_number = ver_lap["LapNumber"].iloc[0]

lap = ver.get_lap(lap_number)
telemetry = lap.telemetry

# Analyze speed
print(f"Top speed: {telemetry['Speed'].max()} km/h")
print(f"Avg speed: {telemetry['Speed'].mean():.1f} km/h")

Common Patterns

Finding available data

Before loading data, check what’s available:

import tif1

# List all events in 2025
events = tif1.get_events(2025)
print(f"Found {len(events)} events")

# List sessions for an event
sessions = tif1.get_sessions(2025, "Monaco Grand Prix")
print(f"Available sessions: {sessions}")

Filtering Laps

Clean and filter lap data for analysis:

laps = session.laps

# Remove deleted laps
clean = laps[~laps["Deleted"]]

# Remove pit laps
clean = clean[clean["PitInTime"].isna()]

# Remove lap 1 (standing start)
clean = clean[clean["LapNumber"] > 1]

# Filter by compound
soft_laps = clean[clean["Compound"] == "SOFT"]

Analyzing tire strategy

# Group by driver and stint
strategy = laps.groupby(["Driver", "Stint"]).agg({
    "Compound": "first",
    "LapNumber": ["min", "max", "count"]
}).reset_index()

print(strategy)

Weather Analysis

# Get weather data
weather = session.weather

# Check for rain
if weather["Rainfall"].any():
    print("Rain detected during session")
    rain_laps = weather[weather["Rainfall"]]["Time"]
    print(f"Rain from {rain_laps.min():.0f}s to {rain_laps.max():.0f}s")

Performance Tips

Use async for cold cache

When loading data for the first time, use async for 4-5x speedup:

import asyncio
import tif1

async def load_data():
    session = tif1.get_session(2025, "Monaco", "Race")
    laps = await session.laps_async()
    return laps

laps = asyncio.run(load_data())

Batch telemetry fetching

Never fetch telemetry in a loop:

# Fetch all telemetry in parallel (28x faster)
tels = session.get_fastest_laps_tels(by_driver=True)

for driver, tel in tels.items():
    print(f"{driver}: {tel['Speed'].max()} km/h")

# Slow - fetches one at a time
for driver_code in session.drivers:
    driver = session.get_driver(driver_code)
    fastest = driver.get_fastest_lap()
    # This is very slow!

Use Polars for large datasets

# Use polars lib for 2x faster processing
session = tif1.get_session(
    2025,
    "Monaco",
    "Race",
    lib="polars"
)

laps = session.laps  # Returns polars DataFrame

Visualization

Create quick visualizations:

import matplotlib.pyplot as plt

# Plot lap times
laps = session.laps
ver_laps = laps[laps["Driver"] == "VER"]

plt.figure(figsize=(12, 6))
plt.plot(ver_laps["LapNumber"], ver_laps["LapTime"], marker="o")
plt.xlabel("Lap Number")
plt.ylabel("Lap Time (s)")
plt.title("VER Lap Times - Monaco 2025")
plt.grid(True, alpha=0.3)
plt.show()

Error Handling

Handle errors gracefully:

import tif1

try:
    session = tif1.get_session(2025, "Monaco", "Race")
    laps = session.laps
except tif1.DataNotFoundError:
    print("Session data not available")
except tif1.NetworkError as e:
    print(f"Network error: {e}")
except tif1.TIF1Error as e:
    print(f"Error: {e}")

Configuration

Customize tif1 behavior:

import tif1

# Get configuration
config = tif1.get_config()

# Change cache directory
config.cache_dir = "/custom/cache/path"

# Use polars by default
config.lib = "polars"

# Enable debug logging
config.log_level = "DEBUG"

Next Steps

Now that you understand the basics, explore:

Tutorials

Learn advanced analysis techniques

API Reference

Explore the complete API

Best Practices

Learn recommended patterns

Examples

See more code examples

Common Issues

Cache permission errors

If you get permission errors:

# Check cache directory permissions
ls -la ~/.tif1/cache/

# Fix permissions
chmod -R 755 ~/.tif1/cache/

Network Timeouts

If requests timeout:

import tif1

config = tif1.get_config()
config.request_timeout = 30  # Increase timeout to 30s

Memory Issues

For large datasets:

# Use polars (50% less memory)
session = tif1.get_session(2025, "Monaco", "Race", lib="polars")

# Or process drivers one at a time
for driver_code in session.drivers:
    driver = session.get_driver(driver_code)
    laps = driver.laps
    # Process laps
    del laps  # Free memory

Getting Help

FAQ

Common questions and answers

Troubleshooting

Solve common problems

GitHub Issues

Report bugs or request features

Contributing

Contribute to tif1

Quickstart

Quick 30-second start

Best Practices

Recommended patterns

Examples

Common use cases

Tutorials

Step-by-step guides

​Prerequisites

​Installation

​Your first analysis

​Step 1: load a session

​Step 2: explore drivers

​Step 3: analyze lap times

​Step 4: compare drivers

​Step 5: analyze telemetry

​Common Patterns

​Finding available data

​Filtering Laps

​Analyzing tire strategy

​Weather Analysis

​Performance Tips

​Use async for cold cache

​Batch telemetry fetching

​Use Polars for large datasets

​Visualization

​Error Handling

​Configuration

​Next Steps

Tutorials

API Reference

Best Practices

Examples

​Common Issues

​Cache permission errors

​Network Timeouts

​Memory Issues

​Getting Help

FAQ

Troubleshooting

GitHub Issues

Contributing

​Related Pages

Quickstart

Best Practices

Examples

Tutorials

Prerequisites

Installation

Your first analysis

Step 1: load a session

Step 2: explore drivers

Step 3: analyze lap times

Step 4: compare drivers

Step 5: analyze telemetry

Common Patterns

Finding available data

Filtering Laps

Analyzing tire strategy

Weather Analysis

Performance Tips

Use async for cold cache

Batch telemetry fetching

Use Polars for large datasets

Visualization

Error Handling

Configuration

Next Steps

Common Issues

Cache permission errors

Network Timeouts

Memory Issues

Getting Help

Related Pages