Skip to main content

Overview

The tif1.charts module provides 22 native chart functions for Formula 1 data visualization. Every function loads its own session data, so a single call produces a complete, publication-ready chart:
All functions are available from both tif1.charts and the top-level tif1 namespace (for example tif1.charts.plot_top_speeds and tif1.plot_top_speeds are the same function). They are loaded lazily, so importing tif1 costs nothing extra.

Key features

  • Self-loading: each chart calls tif1.get_session(year, event, session) internally with enable_cache passthrough
  • Return (fig, ax): call plt.show(), save the figure later, or further customize it. Nothing is shown or written unless requested.
  • Optional save_path: pass a path to write the figure with bbox_inches="tight" at the requested dpi. The race-launch chart saves the full canvas instead. Alternatively, enable automatic saving to a year/event/session folder tree with tif1.configure_chart_saving.
  • Shared filter vocabulary: drivers, teams, n_drivers, laptime_cutoff, include_deleted, include_pit_laps, laps work consistently across charts
  • Consistent styling: charts apply the dark theme by default; color_scheme=None leaves matplotlib’s global state untouched
  • Stable bar-chart layout: horizontal bar charts keep tight y-limits at any driver count. The full-canvas race-launch export keeps its bar labels in-canvas (see bar-chart layout guarantees).
  • Both backends: lib="pandas" and lib="polars" draw the identical figure. Chart logic relies on pandas idioms, so the chart always loads the session with the pandas backend. Both backends share the same payloads and payload cache.

Quickstart

Automatic saving

By default, charts write nothing unless save_path is passed. To auto-name and save every chart into a year/event/session folder tree, enable automatic saving once:
Placeholder values are sanitized (lowercase, hyphenated, non-ASCII folded; the chart name keeps its underscores). Known session codes map to their full names (Q → qualifying, R → race, FP1 → practice-1, SQ → sprint-qualifying). The templates support {year}, {event}, {session} and {chart} placeholders. With overwrite=False, repeated saves get _1, _2, … suffixes instead of overwriting files. Every chart also accepts an auto_save keyword that overrides the global setting for one call. auto_save=True forces a save even with the config disabled; auto_save=False suppresses it. Explicit save_path always takes precedence, and its parent directories are created automatically. After any save, the returned figure carries the written path in fig._tif1_save_path. Use it to find where an auto-saved chart was written.

Common signature

Every chart follows the same shape. Only the parameters that apply to a chart are exposed; the output, theme, and session passthrough parameters are identical everywhere:

Output parameters

  • save_path (str | None, default: None) — write the figure to this path with bbox_inches="tight" (plot_race_launch_ratings saves the full canvas). None defers to automatic saving when enabled via tif1.configure_chart_saving (see Automatic saving); otherwise nothing is written.
  • auto_save (bool | None, default: None) — per-call override of the global auto-save setting (True/False force it on/off).
  • dpi (int, default: 150) — resolution used when saving. Each signature below shows the chart’s own default: the track maps (except plot_gear_shifts), plot_telemetry_comparison, plot_gg_diagram, plot_laptime_heatmap, plot_lap_delta, and the performance charts default to 300.
  • figsize (tuple[float, float] | None) — override the chart’s default figure size.
  • facecolor (str | None, default: None) — figure background. None keeps the active theme’s figure background, so the margins match the axes and the text colour. A fixed dark background behind a light theme made the title and tick labels unreadable. Pass a colour to override it for the saved file and the returned figure.

Theme parameters

  • color_scheme (str | None, default: "dark") — theme passed to tif1.plotting.setup_mpl. Supported values are "fastf1", "dark" and "light". "dark" and "light" are the TracingInsights v2 themes, with bundled car/tyre images available via tif1.assets. None skips the theme call entirely and leaves matplotlib.rcParams untouched. Any other string raises ValueError from setup_mpl.
Every chart follows the active theme. Grid lines, zero lines, bar edges, and colorbar ticks take the theme’s text colour, not a fixed white or black. Highlight text uses a green that contrasts with the background: brand lime on dark themes, dark green on light ones. Some data-coloured labels can blend into the background, for example the compound names on the tire degradation chart. These labels get a thin outline. The branded TRACINGINSIGHTS.COM footer follows the polarity of the active background. It is black on light themes and lime on dark ones. Switching between named schemes resets every rcParams key the schemes manage. A dark chart followed by a fastf1 one never inherits hidden spines or the dark legend frame.

Session passthrough

  • enable_cache (bool | None) — forwarded to tif1.get_session.
  • lib ("pandas" | "polars", default: "pandas") — data backend of the caller. Both values draw the identical figure, because the chart loads the session with the pandas backend in both cases. Any other value raises ValueError before the session loads.

Shared filters

Filters apply in a deterministic order. The order is: lap numbers, drivers, teams, top-N by finishing position, deleted laps, pit laps, lap time cutoff.
  • drivers — restrict to these drivers, for example ["VER", "LEC"]. Every chart with this parameter also fuzzy-resolves other identifiers, such as "Verstappen", with a warning on correction. The default depends on the chart. The comparison charts use the top-2 or top-3 finishers. plot_position_changes, plot_downforce_levels, plot_throttle_distance, and plot_race_launch_ratings use every driver. plot_track_temperature uses the driver with the most laps.
  • teams — restrict to these team names (fuzzy-resolved).
  • n_drivers — keep only the top-N drivers by finishing position.
  • laps — restrict to specific lap numbers.
  • laptime_cutoff — drop laps slower than fastest * cutoff. The scope (per-driver vs global) follows the chart’s semantics. Per-driver scope applies to lap deltas, driver lap times, and distributions. Global scope applies to heatmaps and tire degradation.
  • include_deleted — keep deleted laps when True (dropped by default).
  • include_pit_laps — keep pit laps when True (dropped by default).

Track maps

The track maps draw the fastest lap’s telemetry as a colored track line over the circuit layout.

plot_track_speed_map

Colors the track by speed from the session’s fastest lap.

plot_track_throttle_map

Colors the track by throttle position, with a fixed 0-100% color scale.

plot_track_brake_zones

Highlights braking zones (on/off) around the circuit.

plot_track_acceleration_map

Colors the track by longitudinal acceleration in g, computed with np.gradient of speed over time.

plot_gear_shifts

Colors the track by the gear used, with a gear colorbar scaled to the data.

plot_multi_driver_speed_comparison

Overlays the fastest-lap speed traces of several drivers on the track. The plot uses a shared color scale, a driver legend, and a horizontal speed colorbar. Defaults to the top-3 finishers.

Telemetry

plot_speed_traces

Plots each driver’s fastest-lap speed against distance. Defaults to the top-2 finishers.

plot_annotated_speed_trace

Draws the session’s fastest-lap speed trace with vertical markers at each corner (requires session.get_circuit_info()).

plot_telemetry_comparison

Compares two drivers (the first two of drivers, default top-2 finishers) across four synchronized panels: speed, longitudinal acceleration, lateral acceleration, and driver actions. Driver actions cover brake, full throttle, and lift. The returned ax is a numpy array of 4 axes, not a single axes.

plot_gg_diagram

Plots the G-G diagram (lateral vs longitudinal acceleration) per driver with a convex-hull performance envelope. The hull comes from scipy, a tif1 dependency. Defaults to the top-3 finishers.

Race launch

plot_race_launch_ratings

Interpolates each driver’s lap-1 telemetry to find the time to reach the 50/100/150/200 km/h marks. Derives a 0-10 rating for the chosen speed window. The rating is plotted as a horizontal bar chart in the dark style. The style uses a #011627 background, lime text, white labels, Coolvetica/Azonix/GreatVibes fonts, and bundled tyre images. Bundled car images are drawn only on bars that exceed the style’s car_threshold (2.5) and are long enough to hold the image.
Parameters:
  • speed_threshold (int, default: 50) — one of 50, 100, 150, 200; the “lights out to X km/h” rating.
  • speed_range (tuple[int, int] | None) — optional (start, end) speed window for a range rating (for example (50, 100)); takes precedence over speed_threshold.
  • color_scheme (str | None, default: "dark") — the chart’s theme and visual config. Passing "light" switches to the light style (no car threshold, Tenada fonts). Any other scheme ("fastf1", None) picks the style that matches the active matplotlib background. A dark figure background gets the dark style, and a light one gets the light style.

Lap times

plot_driver_laptimes

Scatter of lap times per lap, colored by tire compound. The lap time axis is inverted, so the fastest laps sit at the top. Defaults to the top-3 finishers; pass drivers=["ALO"] for a single-driver view.

plot_laptimes_distribution

Violin + swarm plot of lap time distributions for the point finishers (top 10 by default). Deleted and pit laps are always excluded.

plot_laptime_heatmap

Driver-by-lap heatmap of lap times. The color scale is fixed from the fastest lap to fastest * cutoff so slow laps stand out.

plot_qualifying_grid

Horizontal bars of each driver’s gap to pole. Deleted laps are excluded by default (a deleted lap can never win the pole).

plot_lap_delta

Bars of the lap-by-lap time delta between two drivers. Negative bars mean the first driver was faster; bars are colored with the faster driver’s team color. Defaults to the top-2 finishers; uses the first two drivers of drivers and raises ValueError when fewer than two are available.

plot_position_changes

Line chart of each driver’s race position per lap. Axis limits derive from the data, so it works for any grid size.

plot_track_temperature

Plots the track temperature across the race from the per-lap TrackTemp column of the lap data. When drivers is None, uses the driver with the most recorded laps. One driver gets a single #ff4444 line. Several drivers get one line each in the driver’s team color.

Performance

plot_downforce_levels

Horizontal bars of a relative downforce metric (average speed / max speed x 100) per driver’s fastest lap. The title names the loaded session. Raises ValueError if no driver can be processed.

plot_throttle_distance

Horizontal bars of the percentage of each driver’s fastest-lap distance at or above throttle_threshold (default 98%) throttle. The title names the loaded session.

plot_tire_degradation

Scatter of fuel-corrected lap times against tire life per compound, with rolling-median degradation lines. Lap 1 and slow laps are excluded; a compound with min_laps laps or fewer is skipped. compounds defaults to ["SOFT", "MEDIUM", "HARD"], and laptime_cutoff=None falls back to 1.07.

Top speeds

plot_top_speeds

Horizontal bars of each team’s maximum speed, measured as the gap from the slowest team. speed_trap is one of "SpeedI1", "SpeedI2", "SpeedST", "SpeedFL"; when None, the chart uses the trap that records the highest speed on most laps.

Error handling

Charts propagate the library’s own exceptions (DataNotFoundError, NetworkError, InvalidDataError, and subclasses) from session loading. plot_speed_traces, plot_gg_diagram, plot_multi_driver_speed_comparison, plot_downforce_levels, and plot_throttle_distance skip a driver whose data fails to load. An event name that resembles no event raises EventNotFoundError, a ValueError subclass. Every chart raises ValueError for a lib value other than "pandas" or "polars". The charts also raise ValueError by design, so a chart is never silently empty:
  • plot_lap_delta and plot_telemetry_comparison raise when fewer than two drivers are available (only the first two of a longer list are used). plot_lap_delta also raises when the two drivers have no common laps.
  • plot_speed_traces, plot_gg_diagram, plot_multi_driver_speed_comparison, plot_qualifying_grid, plot_downforce_levels, plot_throttle_distance, and plot_race_launch_ratings raise when no driver could be processed.
  • plot_laptime_heatmap raises when no lap is left after filtering. plot_track_temperature raises when drivers is None and the session has no lap data.
  • plot_top_speeds raises for an unknown speed_trap. plot_race_launch_ratings raises for a speed_threshold or speed_range outside 50, 100, 150, and 200 km/h.
  • tif1.configure_chart_saving raises for an unknown option, a non-bool enabled or overwrite, or an empty format or template.
  • An automatic save raises when a template uses an unknown placeholder.

Full list

Last modified on October 28, 2026