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 and lib 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. 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 fastf1 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).
- pandas backend by default: chart logic relies on pandas idioms. Pass
lib="polars" with caution.
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:
Folder and file names are sanitized (lowercase, hyphenated, non-ASCII folded). 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". 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. Track maps, telemetry charts, heatmaps, and performance charts default to 300.
figsize (tuple[float, float] | None) — override the chart’s default figure size.
facecolor (str | None, default varies) — figure background. 8 charts default to "#1a1a1a" (dark), 13 default to None (keep the theme background). Pass None explicitly for a transparent/unchanged background.
Theme parameters
color_scheme (str | None, default: "fastf1") — theme passed to tif1.plotting.setup_mpl. Supported values include "fastf1", "default-light" and "default-dark". These are the TracingInsights v2 Fastest_Lap-style themes, with bundled car/tyre images available via tif1.assets. None skips the theme call entirely and leaves matplotlib.rcParams untouched.
Session passthrough
enable_cache (bool | None) — forwarded to tif1.get_session.
lib ("pandas" | "polars", default: "pandas") — forwarded to tif1.get_session.
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 driver abbreviations (fuzzy-resolved with a warning on correction). Defaults are auto-selected per chart (top-2 or top-3 finishers).
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 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. Requires scipy. 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 default-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 when the rating exceeds the style’s car_threshold (2.5).
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, default: "default-dark") — the chart’s theme and visual config. Passing "default-light" switches to the light style (no car threshold, Tenada fonts); other schemes keep the dark visuals.
Lap times
plot_driver_laptimes
Scatter of lap times per lap, colored by tire compound. 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; requires exactly two drivers.
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. When drivers is None, uses the driver with the most recorded laps; otherwise draws one line per driver. Requires the session’s weather data.
plot_downforce_levels
Horizontal bars of a relative downforce metric (average speed / max speed x 100) per driver’s fastest lap. Raises ValueError if no driver can be processed.
plot_throttle_distance
Horizontal bars of the percentage of the fastest lap spent at (near) full throttle per driver.
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; compounds with fewer than min_laps laps are skipped.
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 trap with the highest readings is used automatically.
Error handling
Charts propagate the library’s own exceptions (DataNotFoundError, NetworkError, InvalidDataError, and subclasses) without swallowing them. Two additional ValueErrors are raised by design:
plot_lap_delta and plot_telemetry_comparison raise when fewer than two drivers can be resolved
plot_downforce_levels, plot_throttle_distance, plot_gg_diagram, and plot_speed_traces raise when no driver could be processed (never a silently empty chart)
Full list
Last modified on September 3, 2026