Plotting - fastf1.plotting#

Helper functions for creating data plots.

fastf1.plotting provides optional functionality with the intention of making it easy to create nice plots.

This module mainly offers:

  • team names and colors

  • driver names and driver abbreviations

  • Matplotlib integration and helper functions

FastF1 focuses on plotting with Matplotlib or related libraries like Seaborn. If you wish to use these libraries, it is highly recommended to enable extend support for these by calling setup_mpl().

Team Colormaps#

Currently, two team colormaps are supported. Each colormap provides one color for each team. Colors are constant over the course of a season. All functions that return colors for teams or drivers accept an optional colormap argument.

The 'default' colormap is FastF1’s default colormap. These colors are teams’ primary colors or accent colors as they are used by the teams on their website or in promotional material. The colors are chosen to maximize readability in plots by creating a stronger contrast while still being associated with the team.

The 'official' colormap contains the colors exactly as they are used by the FOM in official graphics and in the TV graphics. Those colors are often slightly muted. While that makes them more pleasing to look at in some graphics, it also reduces the contrast between colors which is often bad for readability of plots.

See here for a complete list of all colors: Overview over Team Colormaps

Note

Driver Colors

Previously, individual colors for each driver were provided. This is no longer the case. The driver color is now equivalent to the team color, meaning that drivers from the same team have the exact same color. This change was made because different colors for 20 drivers end up looking very similar in many cases anyway, meaning it is not a good solution to use these to distinguish different drivers. Other means of plot styling should be used instead.

Overview#

Configuration and Setup#

Functions:

setup_mpl([mpl_timedelta_support, ...])

Setup matplotlib for use with fastf1.

Get Colors, Names and Abbreviations for Drivers or Teams#

Functions:

get_compound_color(compound, session)

Get the compound color as hexadecimal RGB color code for a given compound.

get_driver_abbreviation(identifier, session)

Get a driver's abbreviation based on a recognizable and identifiable part of the driver's name.

get_driver_abbreviations_by_team(identifier, ...)

Get a list of abbreviations of all drivers that drove for a team in a given session based on a recognizable and identifiable part of the team name.

get_driver_color(identifier, session, *[, ...])

Get the color that is associated with a driver based on the driver's abbreviation or based on a recognizable and identifiable part of the driver's name.

get_driver_name(identifier, session)

Get a full driver name based on the driver's abbreviation or based on a recognizable and identifiable part of the driver's name.

get_driver_names_by_team(identifier, session)

Get a list of full names of all drivers that drove for a team in a given session based on a recognizable and identifiable part of the team name.

get_driver_style(identifier, style, session, *)

Get a plotting style that is unique for a driver based on the driver's abbreviation or based on a recognizable and identifiable part of the driver's name.

get_team_color(identifier, session, *[, ...])

Get a team color based on a recognizable and identifiable part of the team name.

get_team_name(identifier, session, *[, short])

Get a full team name based on a recognizable and identifiable part of the team name.

get_team_name_by_driver(identifier, session, *)

Get a full team name based on a driver's abbreviation or based on a recognizable and identifiable part of a driver's name.

List all Names and Abbreviations for Drivers/Teams in a Session#

Functions:

get_compound_mapping(session)

Returns a dictionary that maps compound names to their associated colors.

get_driver_color_mapping(session, *[, colormap])

Returns a dictionary that maps driver abbreviations to their associated colors.

list_driver_abbreviations(session)

Returns a list of abbreviations of all drivers in the session.

list_driver_names(session)

Returns a list of full names of all drivers in the session.

list_team_names(session)

Returns a list of full team names of all teams in the session.

list_short_team_names(session)

Returns a list of short team names of all teams in the session.

Plot Styling#

Functions:

add_sorted_driver_legend(ax, session)

Adds a legend to the axis where drivers are ordered by team and within a team in the same order that is used for selecting plot styles.

Deprecated Functionality#

The following module-level attributes are deprecated since version 3.4.0 and will be removed in a future release.

Functions:

driver_color(identifier)

Get a driver's color from a driver name or abbreviation.

lapnumber_axis(ax[, axis])

Set axis to integer ticks only.

team_color(identifier)

Get a team's color from a team name or abbreviation.

Data:

COMPOUND_COLORS

Mapping of tyre compound names to compound colors (hex color codes).

DRIVER_COLORS

Mapping of driver names to driver colors (hex color codes).

DRIVER_TRANSLATE

Mapping of driver names to theirs respective abbreviations.

TEAM_COLORS

Mapping of team names to team colors (hex color codes).

TEAM_TRANSLATE

Mapping of team names to theirs respective abbreviations.

COLOR_PALETTE

The default color palette for matplotlib plot lines in fastf1's color scheme.

Plotting API Reference#

fastf1.plotting.add_sorted_driver_legend(ax, session)[source]#

Adds a legend to the axis where drivers are ordered by team and within a team in the same order that is used for selecting plot styles.

This function is a drop in replacement for calling Matplotlib’s ax.legend() method. It can only be used when driver names or driver abbreviations are used as labels for the legend.

There is no particular need to use this function except to make the legend more visually pleasing.

Parameters:

  • ax (Axes) – An instance of a Matplotlib Axes object

  • session (Session) –

    the session for which the data should be obtained

    Returns:

    matplotlib.legend.Legend

Examples using fastf1.plotting.add_sorted_driver_legend#

Driver specific plot styling

Driver specific plot styling
fastf1.plotting.get_compound_color(compound, session)[source]#

Get the compound color as hexadecimal RGB color code for a given compound.

Parameters:

  • compound (str) – The name of the compound

  • session (Session) – the session for which the data should be obtained

Return type:

str

Returns:

A hexadecimal RGB color code

fastf1.plotting.get_compound_mapping(session)[source]#

Returns a dictionary that maps compound names to their associated colors. The colors are given as hexadecimal RGB color codes.

Parameters:

session (Session) – the session for which the data should be obtained

Return type:

Dict[str, str]

Returns:

dictionary mapping compound names to RGB hex colors

fastf1.plotting.get_driver_abbreviation(identifier, session)[source]#

Get a driver’s abbreviation based on a recognizable and identifiable part of the driver’s name.

Note that the driver’s abbreviation, if given exactly, is also a valid identifier. In this case the same value is returned as was given as the identifier.

Parameters:

  • identifier – recognizable part of the driver’s name (or the driver’s abbreviation)

  • session (Session) – the session for which the data should be obtained

Return type:

str

fastf1.plotting.get_driver_abbreviations_by_team(identifier, session)[source]#

Get a list of abbreviations of all drivers that drove for a team in a given session based on a recognizable and identifiable part of the team name.

Parameters:

  • identifier (str) – a recognizable part of the team name

  • session (Session) – the session for which the data should be obtained

Return type:

List[str]

fastf1.plotting.get_driver_color(identifier, session, *, colormap='default')[source]#

Get the color that is associated with a driver based on the driver’s abbreviation or based on a recognizable and identifiable part of the driver’s name.

Note

This will simply return the team color of the team that the driver participated for in this session. Contrary to older versions of FastF1, there are no separate colors for each driver. This was changed, because the small differences in color between drivers of the same team can be barely distinguished in a plot. You should use styling options apart from color if you need to differentiate drivers of the same team. The function get_driver_style() can help you to customize the plot styling for each driver.

Parameters:

  • identifier (str) – driver abbreviation or recognizable part of the driver name

  • session (Session) – the session for which the data should be obtained

  • colormap (str) – one of 'default' or 'official'

Return type:

str

Returns:

A hexadecimal RGB color code

fastf1.plotting.get_driver_color_mapping(session, *, colormap='default')[source]#

Returns a dictionary that maps driver abbreviations to their associated colors. The colors are given as hexadecimal RGB color codes.

Parameters:

  • session (Session) – the session for which the data should be obtained

  • colormap (str) – one of 'default' or 'official'

Return type:

Dict[str, str]

Returns:

dictionary mapping driver abbreviations to RGB hex colors

fastf1.plotting.get_driver_name(identifier, session)[source]#

Get a full driver name based on the driver’s abbreviation or based on a recognizable and identifiable part of the driver’s name.

Parameters:

  • identifier (str) – driver abbreviation or recognizable part of the driver name

  • session (Session) – the session for which the data should be obtained

Return type:

str

fastf1.plotting.get_driver_names_by_team(identifier, session)[source]#

Get a list of full names of all drivers that drove for a team in a given session based on a recognizable and identifiable part of the team name.

Parameters:

  • identifier (str) – a recognizable part of the team name

  • session (Session) – the session for which the data should be obtained

Return type:

List[str]

fastf1.plotting.get_driver_style(identifier, style, session, *, colormap='default', additional_color_kws=())[source]#

Get a plotting style that is unique for a driver based on the driver’s abbreviation or based on a recognizable and identifiable part of the driver’s name.

This function simplifies the task of generating unique and easily distinguishable visual styles for multiple drivers in a plot. Primarily, the focus is on plotting with Matplotlib, but it is possible to customize the behaviour for compatibility with other plotting libraries.

The general idea for creating visual styles is as follows:

  1. Set the primary color of the style to the color of the team for which a driver is driving. This may be the line color in a line plot, the marker color in a scatter plot, and so on.

  2. Use one or multiple other styling options (line style, markers, …) to differentiate drivers in the same team.

Note

It cannot be guaranteed that the styles are consistent throughout a full season, especially in case of driver changes within a team.

Option 1: Rely on built-in styling options

By default, this function supports the following Matplotlib plot arguments: linestyle, marker, color, facecolor, edgecolor as well as almost all other color-related arguments.

The styling options include one color for each team and up to four different line styles and marker styles within a team. That means that no more than four different drivers are supported for a team in a single session. This should be sufficent in almost all scenarios.

The following example obtains the driver style for Alonso and Stroll in a race in the 2023 season. The drivers should be represented using the color and marker arguments, as may be useful in a scatter plot. Both drivers were driving for the Aston Martin team, therefore, both automatically get assigned the same color, which is the Aston Martin team color. But both drivers get assigned a different marker style, so they can be uniquely identified in the plot.

Example::
>>> from fastf1 import get_session
>>> from fastf1.plotting import get_driver_style
>>> session = get_session(2023, 10, 'R')
>>> get_driver_style('ALO', ['color', 'marker'], session)
{'color': '#00665e', 'marker': 'x'}
>>> get_driver_style('STR', ['color', 'marker'], session)
{'color': '#00665e', 'marker': 'o'}

Option 2: Provide a custom list of styling variants

To allow for almost unlimited styling options, it is possible to specify custom styling variants. These are not tied to any specific plotting library.

In the following example, a list with two custom stlyes is defined that are then used to generate driver specific styles. Each style is represented by a dictionary of keywords and values.

The first driver in a team gets assigned the first style, the second driver the second style and so on (if there are more than two drivers). It is necessary to define at least as many styles as there are drivers in a team.

The following things need to be noted:

1. The notion of first or second driver does not refer to any particular reference and no specific order for drivers within a team is intended or guranteed.

2. Any color-related key can make use of the “magic” 'auto' value as shown with Alonso in this example. When the color value is set to 'auto' it will automatically be replaced with the team color for this driver. All color keywords that are used in Matplotlib should be recognized automatically. You can define custom arguments as color arguments through the additional_color_kws argument.

3. Each style dictionary can contain arbitrary keys and value. Therefore, you are not limited to any particular plotting library.

Example::
>>> from fastf1 import get_session
>>> from fastf1.plotting import get_driver_style
>>> session = get_session(2023, 10, 'R')
>>> my_styles = [                 {'linestyle': 'solid', 'color': 'auto', 'custom_arg': True},                 {'linestyle': 'dotted', 'color': '#FF0060', 'other_arg': 10}             ]
>>> get_driver_style('ALO', my_styles, session)
{'linestyle': 'solid', 'color': '#00665e', 'custom_arg': True}
>>> get_driver_style('STR', my_styles, session)
{'linestyle': 'dotted', 'color': '#FF0060', 'other_arg': 10}
Parameters:

  • identifier (str) – driver abbreviation or recognizable part of the driver name

  • style (Union[str, Sequence[str], Sequence[dict]]) – list of matplotlib plot arguments that should be used for styling or a list of custom style dictionaries

  • session (Session) – the session for which the data should be obtained

  • colormap (str) – one of 'default' or 'official'

  • additional_color_kws (Union[list, tuple]) – A list of keys that should additionally be treated as colors. This is most usefull for making the magic 'auto' color work with custom styling options.

Return type:

Dict[str, Any]

Returns: a dictionary of plot style arguments that can be directly passed

to a matplotlib plot function using the ** expansion operator

Examples using fastf1.plotting.get_driver_style#

Position changes during a race

Position changes during a race

Driver specific plot styling

Driver specific plot styling
fastf1.plotting.get_team_color(identifier, session, *, colormap='default')[source]#

Get a team color based on a recognizable and identifiable part of the team name.

The team color is returned as a hexadecimal RGB color code.

Parameters:

  • identifier (str) – a recognizable part of the team name

  • session (Session) – the session for which the data should be obtained

  • colormap (str) – one of 'default' or 'official'

Return type:

str

Returns:

A hexadecimal RGB color code

fastf1.plotting.get_team_name(identifier, session, *, short=False)[source]#

Get a full team name based on a recognizable and identifiable part of the team name.

Alternatively, a shortened version of the team name can be returned. The short version is intended for saving space when annotating plots and may skip parts of the official team name, for example “Scuderia Ferrari” becomes just “Ferrari”.

Parameters:

  • identifier (str) – a recognizable part of the team name

  • session (Session) – the session for which the data should be obtained

  • short (bool) – if True, a shortened version of the team name will be returned

Return type:

str

fastf1.plotting.get_team_name_by_driver(identifier, session, *, short=False)[source]#

Get a full team name based on a driver’s abbreviation or based on a recognizable and identifiable part of a driver’s name.

Alternatively, a shortened version of the team name can be returned. The short version is intended for saving as much space as possible when annotating plots and may skip parts of the official team name.

Parameters:

  • identifier (str) – driver abbreviation or recognizable part of the driver name

  • session (Session) – the session for which the data should be obtained

  • short (bool) – if True, a shortened version of the team name will be returned

Return type:

str

fastf1.plotting.list_compounds(session)[source]#

Returns a list of all compound names for this season (not session).

Return type:

List[str]

fastf1.plotting.list_driver_abbreviations(session)[source]#

Returns a list of abbreviations of all drivers in the session.

Return type:

List[str]

fastf1.plotting.list_driver_names(session)[source]#

Returns a list of full names of all drivers in the session.

Return type:

List[str]

fastf1.plotting.list_team_names(session)[source]#

Returns a list of full team names of all teams in the session.

Return type:

List[str]

fastf1.plotting.list_short_team_names(session)[source]#

Returns a list of short team names of all teams in the session.

Return type:

List[str]

fastf1.plotting.setup_mpl(mpl_timedelta_support=True, color_scheme='fastf1', misc_mpl_mods=True)[source]#

Setup matplotlib for use with fastf1.

This is optional but, at least partly, highly recommended.

Deprecated since version 3.4.0: The optional argument misc_mpls_mods is deprecated.

Deprecated since version 3.4.0: The default value for color_scheme will change from 'fastf1' to None. You should explicitly set the desired value when calling this function.

Parameters:

  • mpl_timedelta_support (bool) –

    Matplotlib itself offers very limited functionality for plotting timedelta values. (Lap times, sector times and other kinds of time spans are represented as timedelta.)

    Enabling this option will patch some internal matplotlib functions and register converters, formatters and locators for tick formatting. The heavy lifting for this is done by an external package called ‘Timple’. See https://github.com/theOehrly/Timple if you wish to customize the tick formatting for timedelta.

  • color_scheme (str, None) – This enables the Fast-F1 color scheme that you can see in all example images. Valid color scheme names are: [‘fastf1’, None]

  • misc_mpl_mods (bool) – This argument is deprecated since v3.4.0 and should no longer be used.

fastf1.plotting.driver_color(identifier)[source]#

Get a driver’s color from a driver name or abbreviation.

Deprecated since version 3.4.0: This function is deprecated and will be removed in a future version. Use get_driver_color() instead.

This function will try to find a matching driver for any identifier string that is passed to it. This involves case-insensitive matching and partial string matching.

Example:

>>> driver_color('charles leclerc')  
'#dc0000'
>>> driver_color('max verstappen')  
'#fcd700'
>>> driver_color('ver')  
'#fcd700'
>>> driver_color('lec')  
'#dc0000'

shortened driver names and typos can be dealt with
too (within reason)

>>> driver_color('Max Verst')  
'#fcd700'
>>> driver_color('Charles')  
'#dc0000'
Parameters:

identifier (str) – Abbreviation or uniquely identifying name of the driver.

Returns:

hex color code

Return type:

str

fastf1.plotting.lapnumber_axis(ax, axis='xaxis')[source]#

Set axis to integer ticks only.

Deprecated since version 3.4.0: The function lapnumber_axis is deprecated and will ber removed in a future version without replacement.

Parameters:

  • ax – matplotlib axis

  • axis – can be ‘xaxis’ or ‘yaxis’

Returns:

the modified axis instance

fastf1.plotting.team_color(identifier)[source]#

Get a team’s color from a team name or abbreviation.

Deprecated since version 3.4.0: This function is deprecated and will be removed in a future version. Use get_team_color() instead.

This function will try to find a matching team for any identifier string that is passed to it. This involves case-insensitive matching and partial string matching.

Example:

>>> team_color('Red Bull')  
'#fcd700'
>>> team_color('redbull')  
'#fcd700'
>>> team_color('Red')  
'#fcd700'
>>> team_color('RBR')  
'#fcd700'

# shortened team names, included sponsors and typos can be dealt with
# too (within reason)

>>> team_color('Mercedes')  
'#00d2be'
>>> team_color('Merc')  
'#00d2be'
>>> team_color('Merecds')  
'#00d2be'
>>> team_color('Mercedes-AMG Petronas F1 Team')  
'#00d2be'
Parameters:

identifier (str) – Abbreviation or uniquely identifying name of the team.

Returns:

hex color code

Return type:

str

fastf1.plotting.COMPOUND_COLORS: Dict[str, str] = {'HARD': '#f0f0ec', 'INTERMEDIATE': '#43b02a', 'MEDIUM': '#ffd12e', 'SOFT': '#da291c', 'TEST-UNKNOWN': '#434649', 'UNKNOWN': '#00ffff', 'WET': '#0067ad'}#

Mapping of tyre compound names to compound colors (hex color codes). (current season only)

Deprecated since version 3.4.0: The COMPOUND_COLORS dictionary is deprecated and will be removed in a future version. Use get_compound_color() or get_compound_mapping() instead.

fastf1.plotting.DRIVER_COLORS: Dict[str, str] = {'alexander albon': '#005aff', 'ayumu iwasa': '#1e6176', 'carlos sainz': '#ff8181', 'charles leclerc': '#dc0000', 'daniel ricciardo': '#2b4562', 'esteban ocon': '#ff117c', 'felipe drugovich': '#2f9b90', 'fernando alonso': '#006f62', 'frederik vesti': '#00a6ff', 'george russell': '#24ffff', 'isack hadjar': '#1e6176', 'jack doohan': '#894667', 'jake dennis': '#907400', 'kevin magnussen': '#ffffff', 'lance stroll': '#00413b', 'lando norris': '#eeb370', 'lewis hamilton': '#00d2be', 'liam lawson': '#2b4562', 'logan sargeant': '#012564', 'max verstappen': '#fcd700', 'nico hulkenberg': '#cacaca', 'nyck de vries': '#1e3d61', 'oliver bearman': '#c40000', 'oscar piastri': '#ff8700', 'pato oward': '#ee6d3a', 'pierre gasly': '#fe86bc', 'robert shwartzman': '#9c0000', 'sergio perez': '#ffec7b', 'theo pourchaire': '#004601', 'valtteri bottas': '#00e701', 'yuki tsunoda': '#356cac', 'zak osullivan': '#1b3d97', 'zhou guanyu': '#008d01'}#

Mapping of driver names to driver colors (hex color codes).

Warning

This dictionary will no longer be updated to include new drivers. Use the new API instead.

Deprecated since version 3.4.0: The DRIVER_COLORS dictionary is deprecated and will ber removed in a future version. Use get_driver_color() or get_driver_color_mapping() instead.

fastf1.plotting.DRIVER_TRANSLATE: Dict[str, str] = {'ALB': 'alexander albon', 'ALO': 'fernando alonso', 'BEA': 'oliver bearman', 'BOT': 'valtteri bottas', 'DEN': 'jake dennis', 'DEV': 'nyck de vries', 'DOO': 'jack doohan', 'DRU': 'felipe drugovich', 'GAS': 'pierre gasly', 'HAD': 'isack hadjar', 'HAM': 'lewis hamilton', 'HUL': 'nico hulkenberg', 'IWA': 'ayumu iwasa', 'LAW': 'liam lawson', 'LEC': 'charles leclerc', 'MAG': 'kevin magnussen', 'NOR': 'lando norris', 'OCO': 'esteban ocon', 'OSU': 'zak osullivan', 'OWA': 'pato oward', 'PER': 'sergio perez', 'PIA': 'oscar piastri', 'POU': 'theo pourchaire', 'RIC': 'daniel ricciardo', 'RUS': 'george russell', 'SAI': 'carlos sainz', 'SAR': 'logan sargeant', 'SHW': 'robert shwartzman', 'STR': 'lance stroll', 'TSU': 'yuki tsunoda', 'VER': 'max verstappen', 'VES': 'frederik vesti', 'ZHO': 'zhou guanyu'}#

Mapping of driver names to theirs respective abbreviations.

Warning

This dictionary will no longer be updated to include new drivers. Use the new API instead.

Deprecated since version 3.4.0: The DRIVER_TRANSLATE dictionary is deprecated and will be removed in a future version. Use get_driver_name() instead.

fastf1.plotting.TEAM_COLORS: Dict[str, str] = {'alpine': '#ff87bc', 'aston martin': '#00665f', 'ferrari': '#e8002d', 'haas': '#b6babd', 'mclaren': '#ff8000', 'mercedes': '#27f4d2', 'rb': '#364aa9', 'red bull': '#0600ef', 'sauber': '#00e700', 'williams': '#00a0dd'}#

Mapping of team names to team colors (hex color codes). (current season only)

Deprecated since version 3.4.0: The TEAM_COLORS dictionary is deprecated and will be removed in a future version. Use get_team_color() instead.

fastf1.plotting.TEAM_TRANSLATE: Dict[str, str] = {'AMR': 'aston martin', 'APN': 'alpine', 'FER': 'ferrari', 'HAA': 'haas', 'MCL': 'mclaren', 'MER': 'mercedes', 'RB': 'rb', 'RBR': 'red bull', 'SAU': 'sauber', 'WIL': 'williams'}#

Mapping of team names to theirs respective abbreviations.

Deprecated since version 3.4.0: The TEAM_TRANSLATE dictionary is deprecated and will be removed in a future version. Use get_team_name() instead.

fastf1.plotting.COLOR_PALETTE: List[str] = ['#FF79C6', '#50FA7B', '#8BE9FD', '#BD93F9', '#FFB86C', '#FF5555', '#F1FA8C']#

The default color palette for matplotlib plot lines in fastf1’s color scheme.

Deprecated since version 3.4.0: The COLOR_PALETTE list is deprecated and will be removed in a future version with no replacement.