> ## Documentation Index
> Fetch the complete documentation index at: https://tif1.tracinginsights.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Charts API

> 22 native chart functions for Formula 1 visualization: track maps, speed traces, telemetry comparisons, lap time analysis, and performance metrics.

## 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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import tif1

tif1.plot_top_speeds(2023, "Italian Grand Prix", "Q", save_path="top_speeds.png")
```

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](/guides/data-visualization#bar-chart-layout-guarantees)).
* **pandas backend by default**: chart logic relies on pandas idioms. Pass `lib="polars"` with caution.

## Quickstart

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import matplotlib.pyplot as plt
import tif1

# Save directly to a file
tif1.plot_track_speed_map(2023, "Monaco", "Q", save_path="speed_map.png", dpi=300)

# Or get the (fig, ax) pair and show it in a notebook
fig, ax = tif1.plot_driver_laptimes(2023, "Azerbaijan Grand Prix", "R", drivers=["ALO"])
plt.show()
```

## 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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import tif1

tif1.configure_chart_saving(
    enabled=True,
    output_dir="tracinginsights",  # default root
    format="png",
    folder_template="{year}/{event}/{session}",
    filename_template="{chart}",
    overwrite=True,
    dpi=300,  # optional dpi override for auto-saved files
)

# writes tracinginsights/2024/italian-grand-prix/qualifying/top_speeds.png
tif1.plot_top_speeds(2024, "Italian Grand Prix", "Q")
```

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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_<name>(
    year: int,
    event: str | int,
    session: str | int,
    *,
    # output
    save_path: str | None = None,
    auto_save: bool | None = None,
    dpi: int = 150,
    figsize: tuple[float, float] | None = None,
    facecolor: str | None = "#1a1a1a",  # None keeps the theme/transparent background
    # theme
    color_scheme: str | None = "fastf1",
    # get_session passthrough
    enable_cache: bool | None = None,
    lib: Literal["pandas", "polars"] = "pandas",
    # shared filters (only those that apply)
    drivers: list[str] | None = None,
    teams: list[str] | None = None,
    n_drivers: int | None = None,
    laps: list[int] | None = None,
    laptime_cutoff: float | None = 1.07,
    include_deleted: bool = False,
    include_pit_laps: bool = False,
) -> tuple[Figure, Axes]:
```

### 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](#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`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_track_speed_map(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    cmap: str = "plasma",
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_track_speed_map(2023, "Monaco", "Q", save_path="speed_map.png")
```

### `plot_track_throttle_map`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_track_throttle_map(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    cmap: str = "RdYlGn",
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_track_throttle_map(2023, "Silverstone", "Q", save_path="throttle_map.png")
```

### `plot_track_brake_zones`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_track_brake_zones(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    cmap: str = "RdYlGn_r",
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_track_brake_zones(2023, "Monza", "Q", save_path="brake_zones.png")
```

### `plot_track_acceleration_map`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_track_acceleration_map(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    cmap: str = "RdBu_r",
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_track_acceleration_map(2023, "Suzuka", "Q", save_path="accel_map.png")
```

### `plot_gear_shifts`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_gear_shifts(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    cmap: str = "Paired",
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_gear_shifts(2021, "Austrian Grand Prix", "Q", save_path="gear_shifts.png")
```

### `plot_multi_driver_speed_comparison`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_multi_driver_speed_comparison(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    cmap: str = "plasma",
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_multi_driver_speed_comparison(
    2023, "Bahrain Grand Prix", "Q",
    drivers=["VER", "PER", "LEC"],
    save_path="multi_driver_speed.png",
)
```

## Telemetry

### `plot_speed_traces`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_speed_traces(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_speed_traces(2023, "Spanish Grand Prix", "Q", drivers=["VER", "HAM"])
```

### `plot_annotated_speed_trace`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_annotated_speed_trace(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_annotated_speed_trace(2021, "Spanish Grand Prix", "Q", save_path="annotated.png")
```

### `plot_telemetry_comparison`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_telemetry_comparison(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    distance_min: float = 1000,
    distance_max: float = 2500,
) -> tuple[Figure, np.ndarray]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
fig, axes = tif1.plot_telemetry_comparison(
    2024, "Monaco Grand Prix", "Q",
    drivers=["VER", "LEC"],
    distance_min=500, distance_max=2000,
)
```

### `plot_gg_diagram`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_gg_diagram(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_gg_diagram(2024, "Monaco Grand Prix", "Q", drivers=["VER", "LEC", "NOR"])
```

## Race launch

### `plot_race_launch_ratings`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_race_launch_ratings(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "default-dark",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    speed_threshold: int = 50,
    speed_range: tuple[int, int] | None = None,
) -> tuple[Figure, Axes]
```

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).

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_race_launch_ratings(2024, "Monaco Grand Prix", "R", speed_threshold=100)
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_race_launch_ratings(
    2024, "Silverstone", "R",
    speed_range=(100, 200),
    save_path="launch_ratings.png",
)
```

## Lap times

### `plot_driver_laptimes`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_driver_laptimes(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    laptime_cutoff: float | None = 1.07,
    include_deleted: bool = False,
) -> tuple[Figure, Axes]
```

Scatter of lap times per lap, colored by tire compound. Defaults to the top-3 finishers; pass `drivers=["ALO"]` for a single-driver view.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_driver_laptimes(2023, "Azerbaijan Grand Prix", "R", drivers=["ALO"])
```

### `plot_laptimes_distribution`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_laptimes_distribution(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    n_drivers: int = 10,
    laptime_cutoff: float | None = 1.10,
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_laptimes_distribution(2023, "Azerbaijan Grand Prix", "R")
```

### `plot_laptime_heatmap`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_laptime_heatmap(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    include_deleted: bool = False,
    include_pit_laps: bool = False,
    laptime_cutoff: float | None = 1.07,
    cmap: str = "RdYlGn_r",
    xticklabels: int | list[int] = 5,
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_laptime_heatmap(2023, "Monaco Grand Prix", "R")
```

### `plot_qualifying_grid`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_qualifying_grid(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    n_drivers: int | None = None,
    include_deleted: bool = False,
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_qualifying_grid(2024, "Abu Dhabi Grand Prix", "Qualifying", n_drivers=10)
```

### `plot_lap_delta`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_lap_delta(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    laps: list[int] | None = None,
    include_pit_laps: bool = False,
    laptime_cutoff: float | None = None,
    ylim: tuple[float, float] | None = None,
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_lap_delta(2024, "Monaco Grand Prix", "R", drivers=["VER", "LEC"])
```

### `plot_position_changes`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_position_changes(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    n_drivers: int | None = None,
) -> tuple[Figure, Axes]
```

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_position_changes(2024, "Abu Dhabi Grand Prix", "Race", n_drivers=10)
```

### `plot_track_temperature`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_track_temperature(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_track_temperature(2024, "Singapore Grand Prix", "Race")
```

## Performance

### `plot_downforce_levels`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_downforce_levels(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_downforce_levels(2023, "Monaco Grand Prix", "Q")
```

### `plot_throttle_distance`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_throttle_distance(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    drivers: list[str] | None = None,
    throttle_threshold: float = 98,
) -> tuple[Figure, Axes]
```

Horizontal bars of the percentage of the fastest lap spent at (near) full throttle per driver.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_throttle_distance(2023, "Bahrain Grand Prix", "Q")
```

### `plot_tire_degradation`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_tire_degradation(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 300,
    figsize: tuple[float, float] | None = None, facecolor: str | None = None,
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    compounds: list[str] | None = None,
    fuel_correction: float = 0.03,
    min_laps: int = 10,
    smoothing_window: int = 5,
    laptime_cutoff: float | None = 1.07,
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_tire_degradation(2024, "Abu Dhabi Grand Prix", "Race")
```

## Top speeds

### `plot_top_speeds`

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def plot_top_speeds(
    year: int, event: str | int, session: str | int, *,
    save_path: str | None = None, dpi: int = 150,
    figsize: tuple[float, float] | None = None, facecolor: str | None = "#1a1a1a",
    color_scheme: str | None = "fastf1",
    enable_cache: bool | None = None, lib: Literal["pandas", "polars"] = "pandas",
    teams: list[str] | None = None,
    speed_trap: str | None = None,
) -> tuple[Figure, Axes]
```

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.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
tif1.plot_top_speeds(2023, "Italian Grand Prix", "Q")
```

## Error handling

Charts propagate the library's own exceptions (`DataNotFoundError`, `NetworkError`, `InvalidDataError`, and subclasses) without swallowing them. Two additional `ValueError`s 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

| Function                             | Category    |
| ------------------------------------ | ----------- |
| `plot_top_speeds`                    | Top speeds  |
| `plot_track_speed_map`               | Track maps  |
| `plot_track_throttle_map`            | Track maps  |
| `plot_track_brake_zones`             | Track maps  |
| `plot_track_acceleration_map`        | Track maps  |
| `plot_gear_shifts`                   | Track maps  |
| `plot_multi_driver_speed_comparison` | Track maps  |
| `plot_speed_traces`                  | Telemetry   |
| `plot_annotated_speed_trace`         | Telemetry   |
| `plot_telemetry_comparison`          | Telemetry   |
| `plot_gg_diagram`                    | Telemetry   |
| `plot_driver_laptimes`               | Lap times   |
| `plot_laptimes_distribution`         | Lap times   |
| `plot_laptime_heatmap`               | Lap times   |
| `plot_qualifying_grid`               | Lap times   |
| `plot_lap_delta`                     | Lap times   |
| `plot_position_changes`              | Lap times   |
| `plot_track_temperature`             | Lap times   |
| `plot_downforce_levels`              | Performance |
| `plot_throttle_distance`             | Performance |
| `plot_tire_degradation`              | Performance |