Overview
Thetif1.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:
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 withenable_cachepassthrough - Return
(fig, ax): callplt.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 withbbox_inches="tight"at the requesteddpi. The race-launch chart saves the full canvas instead. Alternatively, enable automatic saving to ayear/event/sessionfolder tree withtif1.configure_chart_saving. - Shared filter vocabulary:
drivers,teams,n_drivers,laptime_cutoff,include_deleted,include_pit_laps,lapswork consistently across charts - Consistent styling: charts apply the
darktheme by default;color_scheme=Noneleaves 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"andlib="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 unlesssave_path is passed. To auto-name and save every chart into a year/event/session folder tree, enable automatic saving once:
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 withbbox_inches="tight"(plot_race_launch_ratingssaves the full canvas).Nonedefers to automatic saving when enabled viatif1.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/Falseforce it on/off).dpi(int, default:150) — resolution used when saving. Each signature below shows the chart’s own default: the track maps (exceptplot_gear_shifts),plot_telemetry_comparison,plot_gg_diagram,plot_laptime_heatmap,plot_lap_delta, and the performance charts default to300.figsize(tuple[float, float] | None) — override the chart’s default figure size.facecolor(str | None, default:None) — figure background.Nonekeeps 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 totif1.plotting.setup_mpl. Supported values are"fastf1","dark"and"light"."dark"and"light"are the TracingInsights v2 themes, with bundled car/tyre images available viatif1.assets.Noneskips the theme call entirely and leavesmatplotlib.rcParamsuntouched. Any other string raisesValueErrorfromsetup_mpl.
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 totif1.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 raisesValueErrorbefore 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, andplot_race_launch_ratingsuse every driver.plot_track_temperatureuses 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 thanfastest * 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 whenTrue(dropped by default).include_pit_laps— keep pit laps whenTrue(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
plot_track_throttle_map
plot_track_brake_zones
plot_track_acceleration_map
np.gradient of speed over time.
plot_gear_shifts
plot_multi_driver_speed_comparison
Telemetry
plot_speed_traces
plot_annotated_speed_trace
session.get_circuit_info()).
plot_telemetry_comparison
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
scipy, a tif1 dependency. Defaults to the top-3 finishers.
Race launch
plot_race_launch_ratings
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.
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 overspeed_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
drivers=["ALO"] for a single-driver view.
plot_laptimes_distribution
plot_laptime_heatmap
fastest * cutoff so slow laps stand out.
plot_qualifying_grid
plot_lap_delta
drivers and raises ValueError when fewer than two are available.
plot_position_changes
plot_track_temperature
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
ValueError if no driver can be processed.
plot_throttle_distance
throttle_threshold (default 98%) throttle. The title names the loaded session.
plot_tire_degradation
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
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_deltaandplot_telemetry_comparisonraise when fewer than two drivers are available (only the first two of a longer list are used).plot_lap_deltaalso 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, andplot_race_launch_ratingsraise when no driver could be processed.plot_laptime_heatmapraises when no lap is left after filtering.plot_track_temperatureraises whendriversisNoneand the session has no lap data.plot_top_speedsraises for an unknownspeed_trap.plot_race_launch_ratingsraises for aspeed_thresholdorspeed_rangeoutside 50, 100, 150, and 200 km/h.tif1.configure_chart_savingraises for an unknown option, a non-boolenabledoroverwrite, or an emptyformator template.- An automatic save raises when a template uses an unknown placeholder.