Skip to content

Plotly Util PlotlyTheme

plotly_theme

Plotly theme and color palettes.

PlotlyTheme defines the layout defaults of a figure template and applies it as the default template. colors holds the color palettes.

colors module-attribute

colors = ColorPalette

The color palettes, for example colors.primary.blue. See ColorPalette.

ConstantsIterable

Base class for creating iterable constant collections.

Provides dictionary-like interface methods (items, values, keys) for accessing class attributes as constants.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
class ConstantsIterable:
    """Base class for creating iterable constant collections.

    Provides dictionary-like interface methods (items, values, keys) for
    accessing class attributes as constants.
    """

    @classmethod
    def items(cls) -> Iterator[tuple[str, Any]]:
        """Yield (name, value) pairs for all non-private, non-callable attributes.

        Yields:
            Tuple of (attribute_name, attribute_value) for class constants.
        """
        for attr_name in dir(cls):
            if not attr_name.startswith('__') and not callable(getattr(cls, attr_name)):
                yield attr_name, getattr(cls, attr_name)

    @classmethod
    def values(cls) -> Iterator[Any]:
        """Yield values for all non-private, non-callable attributes.

        Yields:
            Attribute values for class constants.
        """
        for attr_name in dir(cls):
            if not attr_name.startswith('__') and not callable(getattr(cls, attr_name)):
                yield getattr(cls, attr_name)

    @classmethod
    def keys(cls) -> Iterator[str]:
        """Yield names for all non-private, non-callable attributes.

        Yields:
            Attribute names for class constants.
        """
        for attr_name in dir(cls):
            if not attr_name.startswith('__') and not callable(getattr(cls, attr_name)):
                yield attr_name

items classmethod

items() -> Iterator[tuple[str, Any]]

Yield (name, value) pairs for all non-private, non-callable attributes.

Yields:

Type Description
tuple[str, Any]

Tuple of (attribute_name, attribute_value) for class constants.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
21
22
23
24
25
26
27
28
29
30
@classmethod
def items(cls) -> Iterator[tuple[str, Any]]:
    """Yield (name, value) pairs for all non-private, non-callable attributes.

    Yields:
        Tuple of (attribute_name, attribute_value) for class constants.
    """
    for attr_name in dir(cls):
        if not attr_name.startswith('__') and not callable(getattr(cls, attr_name)):
            yield attr_name, getattr(cls, attr_name)

values classmethod

values() -> Iterator[Any]

Yield values for all non-private, non-callable attributes.

Yields:

Type Description
Any

Attribute values for class constants.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
32
33
34
35
36
37
38
39
40
41
@classmethod
def values(cls) -> Iterator[Any]:
    """Yield values for all non-private, non-callable attributes.

    Yields:
        Attribute values for class constants.
    """
    for attr_name in dir(cls):
        if not attr_name.startswith('__') and not callable(getattr(cls, attr_name)):
            yield getattr(cls, attr_name)

keys classmethod

keys() -> Iterator[str]

Yield names for all non-private, non-callable attributes.

Yields:

Type Description
str

Attribute names for class constants.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
43
44
45
46
47
48
49
50
51
52
@classmethod
def keys(cls) -> Iterator[str]:
    """Yield names for all non-private, non-callable attributes.

    Yields:
        Attribute names for class constants.
    """
    for attr_name in dir(cls):
        if not attr_name.startswith('__') and not callable(getattr(cls, attr_name)):
            yield attr_name

PrimaryColors

Bases: ConstantsIterable

Primary color palette with vibrant, distinct colors.

Provides a curated set of primary colors suitable for categorical data visualization and general plotting needs.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class PrimaryColors(ConstantsIterable):
    """Primary color palette with vibrant, distinct colors.

    Provides a curated set of primary colors suitable for categorical data
    visualization and general plotting needs.
    """

    mint = '#00b894'
    cyan = '#00cec9'
    blue = '#0984e3'
    red = '#d63031'
    pink = '#e84393'
    green_light = '#badc58'
    green_bold = '#6ab04c'
    orange_light = '#fdcb6e'
    orange_bold = '#e17055'
    purple_light = '#a29bfe'
    purple_bold = '#6c5ce7'

SequentialColors

Bases: ConstantsIterable

Sequential color palettes for ordered data visualization.

Contains multi-hue and single-hue sequential palettes appropriate for displaying ordered data such as numerical ranges or intensity maps.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
class SequentialColors(ConstantsIterable):
    """Sequential color palettes for ordered data visualization.

    Contains multi-hue and single-hue sequential palettes appropriate for
    displaying ordered data such as numerical ranges or intensity maps.
    """

    mint_blue_red = ['#00b894', '#0984e3', '#d63031']
    blue_cyan_pink = ['#0984e3', '#00cec9', '#e84393']
    shades_of_mint = ['#e6fff7', '#55efc4', '#00b894', '#009677', '#006b54']
    shades_of_cyan = ['#e6ffff', '#8ee8e7', '#00cec9', '#00a29a', '#00756e']
    shades_of_blue = ['#e6f4ff', '#74b9ff', '#0984e3', '#0063b1', '#004680']
    shades_of_red = ['#ffe6e6', '#ff7675', '#d63031', '#b02525', '#801b1b']
    shades_of_pink = ['#ffe6f3', '#fd79a8', '#e84393', '#c13584', '#962264']
    default = mint_blue_red

DivergingColors

Bases: ConstantsIterable

Diverging color palettes for data around a central value, such as zero.

Provides color schemes that emphasize deviations from a central value, suitable for correlation matrices, anomaly detection, and comparative analysis.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class DivergingColors(ConstantsIterable):
    """Diverging color palettes for data around a central value, such as zero.

    Provides color schemes that emphasize deviations from a central value,
    suitable for correlation matrices, anomaly detection, and comparative analysis.
    """

    blue_mint = SequentialColors.shades_of_blue[::-1] + SequentialColors.shades_of_mint
    red_mint = SequentialColors.shades_of_red[::-1] + SequentialColors.shades_of_mint
    pink_blue = SequentialColors.shades_of_pink[::-1] + SequentialColors.shades_of_blue
    pink_cyan = SequentialColors.shades_of_pink[::-1] + SequentialColors.shades_of_cyan
    default = blue_mint

CyclicalColors

Bases: ConstantsIterable

Cyclical color palettes for periodic data.

Reserved for future implementation of color schemes appropriate for cyclical data such as seasonal patterns or angular measurements.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
106
107
108
109
110
111
112
113
class CyclicalColors(ConstantsIterable):
    """Cyclical color palettes for periodic data.

    Reserved for future implementation of color schemes appropriate for
    cyclical data such as seasonal patterns or angular measurements.
    """

    default = None

QualitativeColors

Bases: ConstantsIterable

Qualitative color palettes for categorical data.

Provides distinct, visually separable colors for categorical variables without inherent ordering.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
class QualitativeColors(ConstantsIterable):
    """Qualitative color palettes for categorical data.

    Provides distinct, visually separable colors for categorical variables
    without inherent ordering.
    """

    default = [
        PrimaryColors.blue,
        PrimaryColors.mint,
        PrimaryColors.cyan,
        PrimaryColors.red,
        PrimaryColors.pink,
        PrimaryColors.green_light,
        PrimaryColors.green_bold,
        PrimaryColors.orange_light,
        PrimaryColors.orange_bold,
        PrimaryColors.purple_light,
        PrimaryColors.purple_bold,
    ]

ColorPalette

Central access point for all color palette categories.

Organizes color palettes by type (primary, sequential, diverging, etc.) for easy access and consistent usage across the framework.

Examples:

>>> colors.primary.blue
'#0984e3'
>>> colors.sequential.default
['#00b894', '#0984e3', '#d63031']
Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
class ColorPalette:
    """Central access point for all color palette categories.

    Organizes color palettes by type (primary, sequential, diverging, etc.)
    for easy access and consistent usage across the framework.

    Examples:
        >>> colors.primary.blue
        '#0984e3'
        >>> colors.sequential.default
        ['#00b894', '#0984e3', '#d63031']
    """

    primary = PrimaryColors
    sequential = SequentialColors
    diverging = DivergingColors
    cyclical = CyclicalColors
    qualitative = QualitativeColors

PlotlyTheme dataclass

Configurable Plotly theme for consistent figure styling.

This dataclass encapsulates all theme settings and provides methods to apply them to Plotly's global template system. It supports customization of colors, fonts, backgrounds, axis styling, and optional watermarking.

Attributes:

Name Type Description
default_colorway list[str]

Default color sequence for traces.

font dict

Font configuration dictionary.

paper_color str

Background color outside the plot area.

background_color str

Background color of the plot area.

xaxis dict

X-axis styling configuration.

yaxis dict

Y-axis styling configuration.

legend dict

Legend styling configuration.

watermark_text str

Optional watermark text to display.

watermark_position tuple[float, float]

(x, y) position for watermark (paper coordinates).

watermark_opacity float

Opacity level for watermark (0.0 to 1.0).

Examples:

theme = PlotlyTheme(default_colorway=colors.qualitative.default, watermark_text='My Study')
theme.apply()  # the default template of all new figures
Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
@dataclass
class PlotlyTheme:
    """Configurable Plotly theme for consistent figure styling.

    This dataclass encapsulates all theme settings and provides methods to
    apply them to Plotly's global template system. It supports customization
    of colors, fonts, backgrounds, axis styling, and optional watermarking.

    Attributes:
        default_colorway: Default color sequence for traces.
        font: Font configuration dictionary.
        paper_color: Background color outside the plot area.
        background_color: Background color of the plot area.
        xaxis: X-axis styling configuration.
        yaxis: Y-axis styling configuration.
        legend: Legend styling configuration.
        watermark_text: Optional watermark text to display.
        watermark_position: (x, y) position for watermark (paper coordinates).
        watermark_opacity: Opacity level for watermark (0.0 to 1.0).

    Examples:
        ```python
        theme = PlotlyTheme(default_colorway=colors.qualitative.default, watermark_text='My Study')
        theme.apply()  # the default template of all new figures
        ```
    """

    default_colorway: list[str] = field(default_factory=list)
    font: dict = field(default_factory=dict)
    paper_color: str = '#ffffff'
    background_color: str = '#F2F2F2'
    xaxis: dict = field(default_factory=dict)
    yaxis: dict = field(default_factory=dict)
    legend: dict = field(default_factory=dict)
    watermark_text: str = None
    watermark_position: tuple[float, float] = (0.99, 0.01)
    watermark_opacity: float = 0.1

    def apply(self) -> None:
        """Apply the theme settings to Plotly's global template system.

        Creates a custom template with all specified settings and sets it as
        the default template for all subsequent figure creation. The template
        includes styling for layout, axes, legends, and optionally watermarks.

        Note:
            This method modifies Plotly's global state and affects all figures
            created after calling this method.
        """
        template = go.layout.Template()

        template.layout.colorway = self.default_colorway
        template.layout.font = self.font
        template.layout.paper_bgcolor = self.paper_color
        template.layout.plot_bgcolor = self.background_color
        template.layout.xaxis.update(self.xaxis)
        template.layout.yaxis.update(self.yaxis)
        template.layout.legend.update(self.legend)

        template.layout.title = dict(x=0.5)

        template.data.bar = [go.Bar(marker=dict(line=dict(width=0)))]

        if self.watermark_text:
            template.layout.annotations = [
                dict(
                    name='watermark',
                    text=self.watermark_text,
                    xref='paper',
                    yref='paper',
                    x=self.watermark_position[0],
                    y=self.watermark_position[1],
                    showarrow=False,
                    font=dict(size=50, color='black'),
                    opacity=self.watermark_opacity,
                    textangle=0,
                )
            ]

        pio.templates['custom'] = template
        pio.templates.default = 'plotly+custom'

apply

apply() -> None

Apply the theme settings to Plotly's global template system.

Creates a custom template with all specified settings and sets it as the default template for all subsequent figure creation. The template includes styling for layout, axes, legends, and optionally watermarks.

Note

This method modifies Plotly's global state and affects all figures created after calling this method.

Source code in src/mesqual/utils/plotly_utils/plotly_theme.py
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
def apply(self) -> None:
    """Apply the theme settings to Plotly's global template system.

    Creates a custom template with all specified settings and sets it as
    the default template for all subsequent figure creation. The template
    includes styling for layout, axes, legends, and optionally watermarks.

    Note:
        This method modifies Plotly's global state and affects all figures
        created after calling this method.
    """
    template = go.layout.Template()

    template.layout.colorway = self.default_colorway
    template.layout.font = self.font
    template.layout.paper_bgcolor = self.paper_color
    template.layout.plot_bgcolor = self.background_color
    template.layout.xaxis.update(self.xaxis)
    template.layout.yaxis.update(self.yaxis)
    template.layout.legend.update(self.legend)

    template.layout.title = dict(x=0.5)

    template.data.bar = [go.Bar(marker=dict(line=dict(width=0)))]

    if self.watermark_text:
        template.layout.annotations = [
            dict(
                name='watermark',
                text=self.watermark_text,
                xref='paper',
                yref='paper',
                x=self.watermark_position[0],
                y=self.watermark_position[1],
                showarrow=False,
                font=dict(size=50, color='black'),
                opacity=self.watermark_opacity,
                textangle=0,
            )
        ]

    pio.templates['custom'] = template
    pio.templates.default = 'plotly+custom'