Skip to content

Plotly Util figure_utils

figure_utils

Utility functions for styling and modifying Plotly figures.

This module provides convenience functions for common figure modifications such as title formatting, annotation styling, axis configuration, and adding interactive controls to Plotly figures.

set_title

set_title(fig: Figure, title: str)

Set a centered, bold title for the figure.

Parameters:

Name Type Description Default
fig Figure

Plotly figure object to modify.

required
title str

Title text to display.

required

Examples:

>>> import plotly.express as px
>>> fig = px.line(x=[0, 1], y=[40.0, 42.0])
>>> set_title(fig, 'Prices')
>>> fig.layout.title.text
'<b>Prices</b>'
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
def set_title(fig: go.Figure, title: str):
    """Set a centered, bold title for the figure.

    Args:
        fig: Plotly figure object to modify.
        title: Title text to display.

    Examples:
        >>> import plotly.express as px
        >>> fig = px.line(x=[0, 1], y=[40.0, 42.0])
        >>> set_title(fig, 'Prices')
        >>> fig.layout.title.text
        '<b>Prices</b>'
    """
    title = f'<b>{title}</b>'
    fig.update_layout(title_text=title, title_x=0.5)

remove_category_in_annotations

remove_category_in_annotations(fig: Figure)

Remove category names from subplot annotations, keeping only values.

Modifies annotation text to show only the part after '=' for cleaner subplot labels (e.g., 'sex=Male' becomes 'Male').

Parameters:

Name Type Description Default
fig Figure

Plotly figure object with annotations to modify.

required

Examples:

>>> import plotly.express as px
>>> prices = pd.DataFrame({'hour': [0, 1, 0, 1], 'price': [40.0, 42.0, 50.0, 55.0], 'country': ['C1', 'C1', 'C2', 'C2']})
>>> fig = px.line(prices, x='hour', y='price', facet_col='country')
>>> remove_category_in_annotations(fig)
>>> [annotation.text for annotation in fig.layout.annotations]
['C1', 'C2']
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def remove_category_in_annotations(fig: go.Figure):
    """Remove category names from subplot annotations, keeping only values.

    Modifies annotation text to show only the part after '=' for cleaner
    subplot labels (e.g., 'sex=Male' becomes 'Male').

    Args:
        fig: Plotly figure object with annotations to modify.

    Examples:
        >>> import plotly.express as px
        >>> prices = pd.DataFrame({'hour': [0, 1, 0, 1], 'price': [40.0, 42.0, 50.0, 55.0], 'country': ['C1', 'C1', 'C2', 'C2']})
        >>> fig = px.line(prices, x='hour', y='price', facet_col='country')
        >>> remove_category_in_annotations(fig)
        >>> [annotation.text for annotation in fig.layout.annotations]
        ['C1', 'C2']
    """
    fig.for_each_annotation(lambda a: a.update(text=a.text.split('=')[-1]))

make_annotations_bold

make_annotations_bold(fig: Figure)

Apply bold formatting to all figure annotations.

Parameters:

Name Type Description Default
fig Figure

Plotly figure object with annotations to modify.

required
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
49
50
51
52
53
54
55
def make_annotations_bold(fig: go.Figure):
    """Apply bold formatting to all figure annotations.

    Args:
        fig: Plotly figure object with annotations to modify.
    """
    fig.for_each_annotation(lambda a: a.update(text='<b>' + a.text + '</b>'))

unmatch_xaxes

unmatch_xaxes(fig: Figure)

Remove x-axis matching across subplots.

Allows each subplot to have independent x-axis ranges and scaling.

Parameters:

Name Type Description Default
fig Figure

Plotly figure object to modify.

required
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
58
59
60
61
62
63
64
65
66
def unmatch_xaxes(fig: go.Figure):
    """Remove x-axis matching across subplots.

    Allows each subplot to have independent x-axis ranges and scaling.

    Args:
        fig: Plotly figure object to modify.
    """
    fig.update_xaxes(matches=None)

unmatch_yaxes

unmatch_yaxes(fig: Figure)

Remove y-axis matching across subplots.

Allows each subplot to have independent y-axis ranges and scaling.

Parameters:

Name Type Description Default
fig Figure

Plotly figure object to modify.

required
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
69
70
71
72
73
74
75
76
77
def unmatch_yaxes(fig: go.Figure):
    """Remove y-axis matching across subplots.

    Allows each subplot to have independent y-axis ranges and scaling.

    Args:
        fig: Plotly figure object to modify.
    """
    fig.update_yaxes(matches=None)

reverse_legend_traceorder

reverse_legend_traceorder(fig: Figure)

Reverse the order of legend entries.

Parameters:

Name Type Description Default
fig Figure

Plotly figure object to modify.

required
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
80
81
82
83
84
85
86
def reverse_legend_traceorder(fig: go.Figure):
    """Reverse the order of legend entries.

    Args:
        fig: Plotly figure object to modify.
    """
    fig.update_layout(legend_traceorder='reversed')

add_datetime_rangeslider

add_datetime_rangeslider(fig: Figure) -> Figure

Add an interactive datetime range slider and selector to the figure.

Adds a range slider below the plot and time period selector buttons for easy navigation of time series data.

Parameters:

Name Type Description Default
fig Figure

Plotly figure object to modify.

required

Returns:

Type Description
Figure

Modified figure object with range controls.

Examples:

>>> import plotly.express as px
>>> fig = add_datetime_rangeslider(px.line(dataset.fetch('Country.Results.price')))
>>> fig.layout.xaxis.rangeslider.visible
True
Source code in src/mesqual/utils/plotly_utils/figure_utils.py
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def add_datetime_rangeslider(fig: go.Figure) -> go.Figure:
    """Add an interactive datetime range slider and selector to the figure.

    Adds a range slider below the plot and time period selector buttons
    for easy navigation of time series data.

    Args:
        fig: Plotly figure object to modify.

    Returns:
        Modified figure object with range controls.

    Examples:
        >>> import plotly.express as px
        >>> fig = add_datetime_rangeslider(px.line(dataset.fetch('Country.Results.price')))
        >>> fig.layout.xaxis.rangeslider.visible
        True
    """
    fig.update_xaxes(
        rangeslider_visible=True,
        rangeselector=dict(
            buttons=list(
                [
                    dict(count=1, label='1d', step='day', stepmode='backward'),
                    dict(count=7, label='1w', step='day', stepmode='backward'),
                    dict(count=1, label='1m', step='month', stepmode='backward'),
                    dict(count=6, label='6m', step='month', stepmode='backward'),
                    dict(count=1, label='YTD', step='year', stepmode='todate'),
                    dict(count=1, label='1y', step='year', stepmode='backward'),
                    dict(step='all'),
                ]
            )
        ),
    )
    fig.update_layout(yaxis_fixedrange=False)
    return fig