Data Visualization

tif1 provides built-in plotting utilities. It also integrates with matplotlib, plotly, and seaborn.

Built-in Plotting

The plotting module provides quick visualization methods for common F1 analysis tasks.

Speed Comparison

Compare the fastest-lap speed traces of two drivers.

import tif1

# plot_speed_traces loads the session and draws both speed traces
fig, ax = tif1.plot_speed_traces(
    2025,
    "Monaco Grand Prix",
    "Qualifying",
    drivers=["VER", "LEC"],
)

Lap Time Evolution

Track how lap times evolve lap by lap, colored by tire compound.

import tif1

# plot_driver_laptimes draws lap times per lap number for the given drivers
fig, ax = tif1.plot_driver_laptimes(
    2025,
    "Bahrain Grand Prix",
    "Race",
    drivers=["VER", "HAM", "LEC"],
)

Bar-chart layout guarantees

The native bar charts (plot_race_launch_ratings, plot_downforce_levels, plot_throttle_distance, plot_top_speeds, and plot_qualifying_grid) share layout guarantees. The guarantees keep the chart clean at any grid size, from 5 drivers to the full 22-driver grid.

Tight y-limits at any driver count

Each bar chart tightens its y-limits around the bar rows with tif1.charts._common.set_tight_barh_ylim(ax, n_bars). Horizontal bar rows sit at integer positions 0..n_bars-1, and the helper sets the limits to (-0.5, n_bars - 0.5). Without the helper, matplotlib’s default 5% auto-margins leave empty bands above the first and below the last bar. The proportions also shift as the number of drivers changes. With the helper, the same chart is equally compact for a 15-driver grid and the full 22-driver grid. The bars always fill the axes with the same small padding, and no fixed row count is assumed.

Bar labels always fit inside the canvas

Charts that export with bbox_inches="tight" crop the canvas around their content, so bar labels are never clipped in the saved output. plot_race_launch_ratings is the exception: it exports the full canvas (no bbox_inches crop) to mirror the v2 script. Labels placed past the longest bar would be clipped at the right edge. The chart calls tif1.charts._common.fit_labels_inside_xlim(ax, labels), which iterates the x-limit to a fixed point. The iteration stops when the measured extent of every label sits inside the axes. Labels stay fully visible at any bar width. The value-label bar charts (plot_downforce_levels, plot_throttle_distance, plot_top_speeds) apply the same guarantee for inline display, where no crop happens. finalize_figure accepts a label_fit=(ax, labels) pair and runs fit_labels_inside_xlim after tight_layout. Value labels then stay inside the axes box at any grid size and under any theme’s font sizes. Labels fitted before layout can overflow once large fonts resize the axes.

Reuse the helpers in custom charts

Both helpers are part of tif1.charts._common’s public API, so custom bar charts can opt in to the same guarantees:

import matplotlib.pyplot as plt
import tif1.charts._common as common

# Example data for a small custom bar chart
drivers = ["VER", "NOR", "PIA"]
values = [98, 95, 93]
team_colors = ["#3671C6", "#FF8000", "#FF8000"]

fig, ax = plt.subplots(figsize=(12, 8))
hbars = ax.barh(drivers, values, color=team_colors)
labels = ax.bar_label(hbars, padding=8, color="white")

# Bars fill the axes at any grid size
common.set_tight_barh_ylim(ax, len(drivers))
ax.invert_yaxis()

# Labels stay inside the canvas
common.fit_labels_inside_xlim(ax, labels)

For the branded footer, watermark, and footer_y placement used by the race-launch chart, see tif1.charts._common.add_style_branding(fig, style).

Per-driver line chart legends stay beside the plot

The multi-line charts that draw one line per driver (plot_position_changes, plot_track_temperature) anchor their legend outside the axes. The legend sits vertically centred next to the plot and wraps into two columns once the grid exceeds 10 entries. Matplotlib’s default placement drops a 22-entry legend into the middle of the plot and obscures the lines. A top-anchored legend grows downward until it nearly spans the figure. The centred outside anchor keeps the legend balanced and clear of the lines at any grid size. The anchor holds from the 1-driver track-temperature default to the full 22-driver grid.

Matplotlib Integration

For custom visualizations, use matplotlib directly.

Telemetry Overlay

import matplotlib.pyplot as plt
import tif1

session = tif1.get_session(2025, "Silverstone", "Race")
ver = session.get_driver("VER")
lap = ver.get_lap(15)
tel = lap.telemetry

fig, (ax1, ax2, ax3) = plt.subplots(3, 1, figsize=(12, 8), sharex=True)

# Speed
ax1.plot(tel["Distance"], tel["Speed"], color="#E10600", linewidth=2)
ax1.set_ylabel("Speed (km/h)")
ax1.grid(True, alpha=0.3)

# Throttle
ax2.plot(tel["Distance"], tel["Throttle"], color="#00D2BE", linewidth=2)
ax2.set_ylabel("Throttle (%)")
ax2.grid(True, alpha=0.3)

# Brake
ax3.plot(tel["Distance"], tel["Brake"].astype(int), color="#FF1E00", linewidth=2)
ax3.set_ylabel("Brake")
ax3.set_xlabel("Distance (m)")
ax3.grid(True, alpha=0.3)

plt.suptitle(f"VER Lap {lap['LapNumber']} Telemetry", fontsize=14, fontweight="bold")
plt.tight_layout()
plt.show()

Tire strategy visualization

import matplotlib.pyplot as plt
import matplotlib.patches as mpatches

session = tif1.get_session(2025, "Monza", "Race")
laps = session.laps

# Season-aware compound colors
compound_colors = tif1.plotting.get_compound_mapping(session)

fig, ax = plt.subplots(figsize=(14, 8))

drivers = laps["Driver"].unique()
for i, driver in enumerate(drivers):
    driver_laps = laps[laps["Driver"] == driver].sort_values("LapNumber")

    for _, lap in driver_laps.iterrows():
        color = compound_colors.get(lap["Compound"], compound_colors["UNKNOWN"])
        ax.barh(i, 1, left=lap["LapNumber"], color=color, edgecolor="black", linewidth=0.5)

ax.set_yticks(range(len(drivers)))
ax.set_yticklabels(drivers)
ax.set_xlabel("Lap Number")
ax.set_title("Tire Strategy - 2025 Monza GP")

# Legend
patches = [mpatches.Patch(color=color, label=compound)
           for compound, color in compound_colors.items()]
ax.legend(handles=patches, loc="upper right")

plt.tight_layout()
plt.show()

Plotly for interactive plots

Plotly enables interactive visualizations in Jupyter notebooks.

This section requires the optional plotting library. Install it with pip install plotly.

Interactive speed trace

import plotly.graph_objects as go
import tif1

session = tif1.get_session(2025, "Spa", "Qualifying")
ver = session.get_driver("VER")
# get_fastest_lap_tel() returns the telemetry of the fastest lap
tel = ver.get_fastest_lap_tel()

fig = go.Figure()

fig.add_trace(go.Scatter(
    x=tel["Distance"],
    y=tel["Speed"],
    mode="lines",
    name="Speed",
    line=dict(color="#E10600", width=2),
    hovertemplate="Distance: %{x:.0f}m<br>Speed: %{y:.0f} km/h<extra></extra>"
))

fig.update_layout(
    title="VER Fastest Lap - Speed Trace",
    xaxis_title="Distance (m)",
    yaxis_title="Speed (km/h)",
    hovermode="x unified",
    template="plotly_dark"
)

fig.show()

3D Track Map

import plotly.graph_objects as go

session = tif1.get_session(2025, "Suzuka", "Race")
ver = session.get_driver("VER")
lap = ver.get_lap(1)
tel = lap.telemetry

fig = go.Figure(data=[go.Scatter3d(
    x=tel["X"],
    y=tel["Y"],
    z=tel["Z"],
    mode="lines",
    line=dict(
        color=tel["Speed"],
        colorscale="Viridis",
        width=4,
        colorbar=dict(title="Speed (km/h)")
    ),
    hovertemplate="X: %{x:.0f}<br>Y: %{y:.0f}<br>Z: %{z:.0f}<br>Speed: %{marker.color:.0f} km/h<extra></extra>"
)])

fig.update_layout(
    title="3D Track Map - Suzuka",
    scene=dict(
        xaxis_title="X (m)",
        yaxis_title="Y (m)",
        zaxis_title="Z (m)",
        aspectmode="data"
    ),
    template="plotly_dark"
)

fig.show()

Seaborn for statistical plots

Seaborn excels at statistical visualizations.

Lap Time Distribution

import seaborn as sns
import matplotlib.pyplot as plt

session = tif1.get_session(2025, "Barcelona", "Race")
laps = session.laps

# Clean data
clean = laps[~laps["Deleted"] & (laps["LapNumber"] > 1)]

plt.figure(figsize=(12, 6))
sns.violinplot(data=clean, x="Driver", y="LapTime", hue="Compound", split=False)
plt.xticks(rotation=45)
plt.title("Lap Time Distribution by Driver and Compound")
plt.ylabel("Lap Time (s)")
plt.tight_layout()
plt.show()

Correlation Heatmap

import seaborn as sns
import matplotlib.pyplot as plt

session = tif1.get_session(2025, "Singapore", "Race")
laps = session.laps

# Select numeric columns
numeric_cols = ["LapTime", "Sector1Time", "Sector2Time", "Sector3Time",
                "SpeedI1", "SpeedI2", "SpeedFL", "SpeedST",
                "AirTemp", "TrackTemp", "TyreLife"]

correlation = laps[numeric_cols].corr()

plt.figure(figsize=(10, 8))
sns.heatmap(correlation, annot=True, fmt=".2f", cmap="coolwarm", center=0)
plt.title("Lap Data Correlation Matrix")
plt.tight_layout()
plt.show()

Best Practices

Use Team Colors

Make plots more recognizable by using official team colors.

session = tif1.get_session(2025, "Monaco", "Race")
drivers_df = session.drivers_df

# Create color map
color_map = dict(zip(drivers_df["Driver"], drivers_df["TeamColor"]))

# Use in plots
for driver in ["VER", "HAM", "LEC"]:
    driver_laps = laps[laps["Driver"] == driver]
    plt.plot(driver_laps["LapNumber"], driver_laps["LapTime"],
             color=f"#{color_map[driver]}", label=driver)

Handle missing data

Always filter out invalid laps before plotting.

def clean_for_plotting(laps):
    """Prepare laps for visualization."""
    clean = laps.copy()

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

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

    # Remove outliers
    fastest = clean["LapTime"].min()
    clean = clean[clean["LapTime"] < fastest * 1.10]

    return clean

laps = session.laps
plot_data = clean_for_plotting(laps)

Optimize for Performance

For large datasets, downsample telemetry before plotting.

# Downsample telemetry to every 10th point
tel_downsampled = tel[::10]

plt.plot(tel_downsampled["Distance"], tel_downsampled["Speed"])

Export for external tools

Save data for use in other visualization tools.

import pandas as pd

# Export to CSV
laps.to_csv("race_laps.csv", index=False)

# Export to Parquet (smaller, faster)
laps.to_parquet("race_laps.parquet")

# Export to Excel
with pd.ExcelWriter("race_analysis.xlsx") as writer:
    laps.to_excel(writer, sheet_name="Laps", index=False)
    session.weather.to_excel(writer, sheet_name="Weather", index=False)

Plotting API

Plotting reference.

Examples

Visualization examples.

Telemetry Tutorial

Telemetry visualizations.

Get Started

Guides

Concepts

Reference

Data Visualization

Built-in Plotting

Speed Comparison

Lap Time Evolution

Bar-chart layout guarantees

Tight y-limits at any driver count

Bar labels always fit inside the canvas

Reuse the helpers in custom charts

Per-driver line chart legends stay beside the plot

Matplotlib Integration

Telemetry Overlay

Tire strategy visualization

Plotly for interactive plots

Interactive speed trace

3D Track Map

Seaborn for statistical plots

Lap Time Distribution

Correlation Heatmap

Best Practices

Use Team Colors

Handle missing data

Optimize for Performance

Export for external tools

Plotting API

Examples

Telemetry Tutorial

​Built-in Plotting

​Speed Comparison

​Lap Time Evolution

​Bar-chart layout guarantees

​Tight y-limits at any driver count

​Bar labels always fit inside the canvas

​Reuse the helpers in custom charts

​Per-driver line chart legends stay beside the plot

​Matplotlib Integration

​Telemetry Overlay

​Tire strategy visualization

​Plotly for interactive plots

​Interactive speed trace

​3D Track Map

​Seaborn for statistical plots

​Lap Time Distribution

​Correlation Heatmap

​Best Practices

​Use Team Colors

​Handle missing data

​Optimize for Performance

​Export for external tools

​Related Pages

Plotting API

Examples

Telemetry Tutorial

Built-in Plotting

Speed Comparison

Lap Time Evolution

Bar-chart layout guarantees

Tight y-limits at any driver count

Bar labels always fit inside the canvas

Reuse the helpers in custom charts

Per-driver line chart legends stay beside the plot

Matplotlib Integration

Telemetry Overlay

Tire strategy visualization

Plotly for interactive plots

Interactive speed trace

3D Track Map

Seaborn for statistical plots

Lap Time Distribution

Correlation Heatmap

Best Practices

Use Team Colors

Handle missing data

Optimize for Performance

Export for external tools

Related Pages