Skip to content

MESQUAL Plotly Util PlotlyTheme

plotly_theme

Custom Plotly theme and color palette definitions for consistent visualization styling.

This module provides a comprehensive theming system for Plotly figures, including predefined color palettes, theme configuration, and template application. It enables consistent styling across all visualizations in the MESQUAL framework.

colors module-attribute 

colors = ColorPalette

Global color palette instance for convenient access to all color schemes.

Example:

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

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 submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
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):
        """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):
        """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):
        """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()

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

Yields:

Type Description

Tuple of (attribute_name, attribute_value) for class constants.
Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
21
22
23
24
25
26
27
28
29
30
@classmethod
def items(cls):
    """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()

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

Yields:

Type Description

Attribute values for class constants.
Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
32
33
34
35
36
37
38
39
40
41
@classmethod
def values(cls):
    """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()

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

Yields:

Type Description

Attribute names for class constants.
Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
43
44
45
46
47
48
49
50
51
52
@classmethod
def keys(cls):
    """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 submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
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 submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
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 with meaningful midpoint.

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

Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
class DivergingColors(ConstantsIterable):
    """Diverging color palettes for data with meaningful midpoint.

    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 submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
103
104
105
106
107
108
109
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 submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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.

Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
133
134
135
136
137
138
139
140
141
142
143
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.
    """
    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).

Example:

>>> theme = PlotlyTheme(
...     default_colorway=colors.qualitative.default,
...     watermark_text="MESQUAL"
... )
>>> theme.apply()
Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
158
159
160
161
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
243
244
245
246
247
@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).

    Example:

        >>> theme = PlotlyTheme(
        ...     default_colorway=colors.qualitative.default,
        ...     watermark_text="MESQUAL"
        ... )
        >>> theme.apply()
    """
    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.

        Example:

            >>> theme = PlotlyTheme(watermark_text="My Project")
            >>> theme.apply()
            >>> fig = go.Figure()  # Will use the custom theme
        """
        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.

Example:

>>> theme = PlotlyTheme(watermark_text="My Project")
>>> theme.apply()
>>> fig = go.Figure()  # Will use the custom theme
Source code in submodules/mesqual/mesqual/utils/plotly_utils/plotly_theme.py 
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
243
244
245
246
247
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.

    Example:

        >>> theme = PlotlyTheme(watermark_text="My Project")
        >>> theme.apply()
        >>> fig = go.Figure()  # Will use the custom theme
    """
    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"