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

# Plotting API

> Visualization utilities and color schemes for F1 data

The `tif1.plotting` module provides utilities for creating F1-themed visualizations with team and driver colors, compound colors, and matplotlib styling.

## Setup

### `setup_mpl`

Configure matplotlib with F1-themed styling.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def setup_mpl(
    color_scheme="fastf1",
    misc_mpl_mods=True,
    mpl_timedelta_support=False,
    **kwargs
) -> None
```

**Parameters:**

* `color_scheme`: Color scheme to use (currently only "fastf1" is supported)
* `misc_mpl_mods`: Apply miscellaneous matplotlib modifications
* `mpl_timedelta_support`: Enable timedelta support (compatibility parameter)

**Example:**

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

# Apply F1 dark theme
tif1.plotting.setup_mpl(color_scheme="fastf1")

# Now all plots will use the dark F1 theme
session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
session.load()
laps = session.laps
plt.plot(laps["LapNumber"], laps["LapTime"])
plt.show()
```

***

## Color Functions

### `get_team_color`

Get the official color for a team.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_team_color(team: str, session=None) -> str
```

**Parameters:**

* `team`: Team name (e.g., "Red Bull Racing", "Ferrari")
* `session`: Optional session object (for future compatibility)

**Returns:**

* Hex color code (e.g., "#dc0000" for Ferrari)

**Example:**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from tif1.plotting import get_team_color

ferrari_color = get_team_color("Ferrari")
# Returns: "#dc0000"
```

### `get_driver_color`

Get the color for a specific driver.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_driver_color(driver: str, session=None) -> str
```

**Parameters:**

* `driver`: 3-letter driver code (e.g., "VER", "HAM")
* `session`: Optional session object

**Returns:**

* Hex color code

**Example:**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from tif1.plotting import get_driver_color

ver_color = get_driver_color("VER")
# Returns: "#0600ef" (Red Bull blue)
```

### `get_driver_color_mapping`

Get a complete mapping of driver codes to colors.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_driver_color_mapping(session=None) -> dict[str, str]
```

**Parameters:**

* `session`: Optional session object to extract team colors for all drivers

**Returns:**

* Dictionary mapping driver codes to hex colors

**Example:**

````python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from tif1.plotting import get_driver_color_mapping

session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
session.load()
colors = get_driver_color_mapping(session)

# Plot each driver with their team color
for driver in session.drivers:
    driver_laps = session.get_driver(driver).laps
    plt.plot(
        driver_laps["LapNumber"],
        driver_laps["LapTime"],
        color=colors.get(driver, "#ffffff"),
        label=driver
    )
``` ### `get_compound_color`

Get the color for a tire compound.

```python
def get_compound_color(compound: str, session=None) -> str
````

**Parameters:**

* `compound`: Compound name (e.g., "SOFT", "MEDIUM", "HARD")
* `session`: Optional session object

**Returns:**

* Hex color code

**Example:**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from tif1.plotting import get_compound_color

soft_color = get_compound_color("SOFT")
# Returns: "#da291c" (red)
```

### `get_compound_mapping`

Get a complete mapping of compounds to colors.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_compound_mapping(session=None) -> dict[str, str]
```

**Returns:**

* Dictionary mapping compound names to hex colors

***

## Styling Functions

### `get_driver_style`

Build a driver style dictionary for plotting.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_driver_style(
    identifier: str,
    style=None,
    session=None
) -> dict[str, Any]
```

**Parameters:**

* `identifier`: Driver code
* `style`: Optional style specification (list of keys or dict)
* `session`: Optional session object

**Returns:**

* Dictionary with color and linestyle

**Example:**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from tif1.plotting import get_driver_style

style = get_driver_style("VER")
# Returns: {"color": "#0600ef", "linestyle": "-"}

plt.plot(data, **style)
```

### `add_sorted_driver_legend`

Add a legend with driver labels sorted alphabetically.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def add_sorted_driver_legend(ax, session=None)
```

**Parameters:**

* `ax`: Matplotlib axes object
* `session`: Optional session object

**Returns:**

* Legend object

**Example:**

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

fig, ax = plt.subplots()
# ... plot driver data ...
add_sorted_driver_legend(ax)
plt.show()
```

***

## Color Constants

### Team Colors

````python theme={"theme":{"light":"github-light","dark":"github-dark"}}
TEAM_COLORS = {
    "Mercedes": "#00d2be",
    "Red Bull Racing": "#0600ef",
    "Red Bull": "#0600ef",
    "Ferrari": "#dc0000",
    "McLaren": "#ff8700",
    "Alpine": "#0090ff",
    "Aston Martin": "#006f62",
    "RB": "#6692ff",
    "Haas": "#ffffff",
    "Sauber": "#52e252",
    "Williams": "#005aff",
}
``` ### Driver Colors

```python
DRIVER_COLORS = {
    "VER": "#0600ef",
    "HAM": "#00d2be",
    "LEC": "#dc0000",
    "NOR": "#ff8700",
    "ALO": "#006f62",
}
````

### Compound Colors

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
COMPOUND_COLORS = {
    "SOFT": "#da291c",
    "MEDIUM": "#ffd12e",
    "HARD": "#f0f0ec",
    "INTERMEDIATE": "#43b02a",
    "WET": "#0067ad",
    "UNKNOWN": "#8a8a8a",
}
```

***

## Complete Example

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

# Setup F1 theme
setup_mpl(color_scheme="fastf1")

# Load session
session = tif1.get_session(2021, "Belgian Grand Prix", "Race")
session.load()
laps = session.laps

# Get driver colors
colors = get_driver_color_mapping(session)

# Plot fastest laps for top 3 drivers
fig, ax = plt.subplots(figsize=(12, 6))

for driver in ["VER", "HAM", "BOT"]:
    driver_laps = laps[laps["Driver"] == driver]
    ax.plot(
        driver_laps["LapNumber"],
        driver_laps["LapTime"],
        color=colors.get(driver, "#ffffff"),
        label=driver,
        linewidth=2
    )

ax.set_xlabel("Lap Number")
ax.set_ylabel("Lap Time (s)")
ax.set_title("2021 Belgian Grand Prix - Lap Times")
ax.legend()
ax.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()
```