statworx_theme 2.0.2__py3-none-any.whl

statworx_theme/utils.py

@@ -0,0 +1,407 @@
+"""Utility functions for the statworx theme."""
+
+import os
+import warnings
+from os.path import dirname, join
+
+# get path to config files
+from shutil import copy
+from typing import Any
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+from cycler import Cycler
+from matplotlib.colors import LinearSegmentedColormap, ListedColormap
+from matplotlib.style.core import reload_library
+from seaborn.palettes import MPL_QUAL_PALS
+
+import statworx_theme
+
+
+def register_listed_cmap(colors: list[str], name: str) -> ListedColormap:
+    """Register a listed colormap in matplotlib.
+
+    Args:
+        colors: Color of the colormap
+        name: Name of the colormap
+
+    Returns:
+        Registered Colormap
+    """
+    # register color map
+    cmap = ListedColormap(colors, N=len(colors), name=name)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        mpl.colormaps.register(cmap=cmap, name=name)
+
+    # dark magic shit
+    MPL_QUAL_PALS.update({name: len(colors)})
+    return cmap
+
+
+def register_blended_cmap(colors: list[str], name: str) -> LinearSegmentedColormap:
+    """Register a blended colormap to matplotlib.
+
+    Args:
+        colors: Colors of the colormap
+        name: Name of the colormap
+
+    Returns:
+        Registered Colormap
+    """
+    cmap = LinearSegmentedColormap.from_list(name, colors)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        mpl.colormaps.register(cmap=cmap, name=name)
+    return cmap
+
+
+def _install_styles() -> None:
+    """Install matplotlib style files with suffix `.mplstyle` to the matplotlib config dir."""
+    # list all theme files
+    config_path = join(dirname(statworx_theme.__file__), "styles")
+    theme_files = [join(config_path, f) for f in os.listdir(config_path)]
+
+    # get config directory
+    config_dir = mpl.get_configdir()
+    style_dir = join(config_dir, "stylelib")
+    os.makedirs(style_dir, exist_ok=True)
+
+    # copy theme files into config directory
+    for file in theme_files:
+        copy(file, style_dir)
+
+    # reload matplotlib
+    reload_library()
+
+
+def apply_style() -> None:
+    """Apply the statworx color style."""
+    _install_styles()
+    plt.style.use("statworx")
+
+
+def apply_custom_colors(colors: list[str], cmap_name: str = "stwx:custom", **kwargs: Any) -> None:
+    """Apply custom custom colors to statworx style.
+
+    Args:
+        colors: List of custom colors as hex codes
+        cmap_name: Custom name of new colormap. Defaults to "stwx:custom".
+        **kwargs: Addition parameters that are passed to the style config
+    """
+    # apply statworx style
+    apply_style()
+
+    # add colors as a custom cmap
+    register_listed_cmap(colors, cmap_name)
+
+    # add colors to current style
+    color_list = [{"color": c} for c in colors]
+    mpl.rcParams["axes.prop_cycle"] = Cycler(color_list)
+
+    # apply kwargs
+    mpl.rcParams.update(kwargs)
+
+
+def get_stwx_cmaps(as_hex: bool = True) -> dict[str, Any]:
+    """Gets the registered colormaps as hex or cmap.
+
+    Args:
+        as_hex (bool, optional): Should the cmaps be returned as hexadecimal list or as a cmap.
+                                    Defaults to True.
+
+    Returns:
+        dict[str, Any]: The colormap name as a key and the hex-list or cmap as value.
+    """
+    cmap_names = [cmap for cmap in plt.colormaps() if cmap.startswith("stwx:")]
+    cmaps = [plt.get_cmap(cmap) for cmap in cmap_names]
+    if as_hex:
+        cmap_hex_codes = [[mpl.colors.to_hex(cmap(i)) for i in range(cmap.N)] for cmap in cmaps]
+        return dict(zip(cmap_names, cmap_hex_codes))
+    return dict(zip(cmap_names, cmaps))
+
+
+def apply_style_altair(n_groups_ordinal: int = 10) -> None:
+    """Apply the statworx color style for Altair.
+
+    Args:
+        n_groups_ordinal (int): The number of groups to be plotted for the ordinal
+            color map. Defaults to 10.
+    """
+    import altair as alt  # type: ignore
+
+    apply_style()
+
+    stwx_cmaps = get_stwx_cmaps()
+
+    _create_altair_theme(
+        primary=stwx_cmaps["stwx:alternative"][0],
+        category=stwx_cmaps["stwx:alternative"],
+        diverging=stwx_cmaps["stwx:BlRd_diverging"],
+        heatmap=stwx_cmaps["stwx:BlRd_diverging"],
+        ramp=stwx_cmaps["stwx:Bl_rise"],
+        ordinal=_shrink_cmap(stwx_cmaps["stwx:bad2good"], n_groups=n_groups_ordinal),
+        name="statworx_altair_theme",
+    )
+
+    alt.themes.enable("statworx_altair_theme")
+
+
+def _shrink_cmap(cmap: list[str], n_groups: int) -> list[str]:
+    """Shrinks the cmap for a fixed number of groups.
+
+    Args:
+        cmap (list[str]): The colormap.
+        n_groups (int): The number of groups in the data to plot.
+
+    Returns:
+        list[str]: Shrunken cmap.
+    """
+    nth_element_to_keep = int(len(cmap) / n_groups)
+    return cmap[::nth_element_to_keep]
+
+
+def _create_altair_theme(
+    primary: str,
+    category: list[str],
+    diverging: list[str],
+    heatmap: list[str],
+    ramp: list[str],
+    ordinal: list[str],
+    name: str,
+) -> None:
+    """Creates the altair theme and registers it.
+
+    Args:
+        primary (str): The primary color as hexadecimal string (e.g. "#d9d9d9").
+        category (list[str]): Categorical colors as list of hexadecimal strings.
+        diverging (list[str]): Diverging color palette as list of hexadecimal strings.
+        heatmap (list[str]): Heatmap color palette as list of hexadecimal strings.
+        ramp (list[str]): Ramp color palette as list of hexadecimal strings.
+        ordinal (list[str]): Ordinal color palette as list of hexadecimal strings.
+        name (str): The name of the theme.
+    """
+    import altair as alt
+
+    def statworx_altair_theme() -> dict:
+        """STATWORX altair theme.
+
+        Returns:
+            altair theme
+        """
+        font = "Arial"
+        primary_color = primary
+        font_color = "#000000"
+        grey_color = "#d9d9d9"
+        base_size = 20
+        lg_font = base_size * 1.25
+        sm_font = base_size * 0.8
+        # xl_font = base_size * 1.75
+        config = {
+            "config": {
+                "view": {
+                    "stroke": False,
+                },
+                "background": "white",  # None for transparent
+                "arc": {"fill": primary_color},
+                "area": {"fill": primary_color},
+                "bar": {"fill": primary_color},
+                "boxplot": {"fill": primary_color},
+                "circle": {"fill": primary_color},
+                "line": {"stroke": primary_color},
+                "mark": {"tooltip": True},
+                "path": {"stroke": primary_color},
+                "point": {"stroke": primary_color},
+                "rect": {"fill": primary_color},
+                "rule": {"fill": primary_color},
+                "shape": {"stroke": primary_color},
+                "square": {"stroke": primary_color},
+                "symbol": {"fill": primary_color},
+                "title": {
+                    "font": font,
+                    "color": font_color,
+                    "fontSize": lg_font,
+                    "anchor": "start",
+                    "offset": 10,
+                },
+                "axis": {
+                    "titleFont": font,
+                    "titleColor": font_color,
+                    "titleFontSize": sm_font,
+                    "labelFont": font,
+                    "labelColor": font_color,
+                    "labelFontSize": sm_font,
+                    "gridColor": grey_color,
+                    "domainColor": font_color,
+                    "tickColor": "#fff",
+                    "labelPadding": 10,
+                    "titlePadding": 10,
+                    "ticks": False,
+                    "domain": False,
+                    # "offset": 10
+                },
+                "header": {
+                    "labelFont": font,
+                    "titleFont": font,
+                    "labelFontSize": base_size,
+                    "titleFontSize": base_size,
+                },
+                "legend": {
+                    "titleFont": font,
+                    "titleColor": font_color,
+                    "titleFontSize": sm_font,
+                    "labelFont": font,
+                    "labelColor": font_color,
+                    "labelFontSize": sm_font,
+                },
+                "range": {
+                    "category": category,
+                    "diverging": diverging,
+                    "heatmap": heatmap,
+                    "ramp": ramp,
+                    "ordinal": ordinal,
+                },
+            }
+        }
+        return config
+
+    alt.themes.register(
+        name,
+        statworx_altair_theme,
+    )
+
+
+def apply_custom_colors_altair(
+    primary: str | None = None,
+    category: list[str] | None = None,
+    diverging: list[str] | None = None,
+    heatmap: list[str] | None = None,
+    ramp: list[str] | None = None,
+    ordinal: list[str] | None = None,
+    n_groups_ordinal: int = 10,
+) -> None:
+    """Applies a custom altair theme with custom color palettes to the statworx style.
+
+    Args:
+        primary (str, optional): The primary color as hexadecimal string (e.g. "#d9d9d9").
+            Defaults to None (statworx style is kept).
+        category (list[str], optional): Categorical colors as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        diverging (list[str], optional): Diverging color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        heatmap (list[str], optional): Heatmap color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        ramp (list[str], optional): Ramp color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        ordinal (list[str], optional): Ordinal color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        n_groups_ordinal (int): The number of groups to be plotted using the ordinal color map.
+            Defaults to 10.
+    """
+    import altair as alt  # type: ignore
+
+    stwx_cmaps = get_stwx_cmaps()
+    _create_altair_theme(
+        primary=stwx_cmaps["stwx:alternative"][0] if primary is None else primary,
+        category=stwx_cmaps["stwx:alternative"] if category is None else category,
+        diverging=stwx_cmaps["stwx:BlRd_diverging"] if diverging is None else diverging,
+        heatmap=stwx_cmaps["stwx:BlRd_diverging"] if heatmap is None else heatmap,
+        ramp=stwx_cmaps["stwx:BlRd_diverging"] if ramp is None else ramp,
+        ordinal=(
+            _shrink_cmap(stwx_cmaps["stwx:bad2good"], n_groups=n_groups_ordinal)
+            if ordinal is None
+            else _shrink_cmap(ordinal, n_groups=n_groups_ordinal)
+        ),
+        name="custom_altair_theme",
+    )
+
+    alt.themes.enable("custom_altair_theme")
+
+
+def apply_style_plotly() -> None:
+    """Apply the statworx color style for plotly."""
+    import plotly.io as pio  # type: ignore
+
+    apply_style()
+
+    stwx_cmaps = get_stwx_cmaps()
+    _create_plotly_theme(
+        category=stwx_cmaps["stwx:alternative"],
+        diverging=stwx_cmaps["stwx:BlRd_diverging"],
+        sequential=stwx_cmaps["stwx:bad2good"],
+        sequential_minus=stwx_cmaps["stwx:good2bad"],
+        heatmap=stwx_cmaps["stwx:BlRd_diverging"],
+        name="statworx_plotly_theme",
+    )
+
+    pio.templates.default = "statworx_plotly_theme"
+
+
+def _create_plotly_theme(
+    category: list[str],
+    diverging: list[str],
+    sequential: list[str],
+    sequential_minus: list[str],
+    heatmap: list[str],
+    name: str,
+):
+    """Creates the plotly theme and registers it.
+
+    Args:
+        category (list[str]): Categorical colors as list of hexadecimal strings.
+        diverging (list[str]): Diverging color palette as list of hexadecimal strings.
+        sequential (list[str]): Sequential color palette as list of hexadecimal strings.
+        sequential_minus (list[str]): Downwards sequential color palette as list of hex strings.
+        heatmap (list[str]): Heatmap color palette as list of hexadecimal strings.
+        name (str): The name of the theme.
+    """
+    import plotly.graph_objects as go
+    import plotly.io as pio
+
+    plotly_template = go.layout.Template(pio.templates["plotly_white"])
+
+    plotly_template.layout.colorway = category
+    plotly_template.layout.colorscale.diverging = diverging
+    plotly_template.layout.colorscale.sequential = sequential
+    plotly_template.layout.colorscale.sequentialminus = sequential_minus
+    plotly_template.data.heatmap[0].colorscale = heatmap
+
+    pio.templates[name] = go.layout.Template(plotly_template)
+
+
+def apply_custom_colors_plotly(
+    category: list[str] | None = None,
+    diverging: list[str] | None = None,
+    sequential: list[str] | None = None,
+    sequential_minus: list[str] | None = None,
+    heatmap: list[str] | None = None,
+):
+    """Applies a custom plotly theme with custom color palettes to the statworx style.
+
+    Args:
+        category (list[str]): Categorical colors as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        diverging (list[str]): Diverging color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        sequential (list[str]): Sequential color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+        sequential_minus (list[str]): Downwards sequential color palette as list of hex strings.
+            Defaults to None (statworx style is kept).
+        heatmap (list[str]): Heatmap color palette as list of hexadecimal strings.
+            Defaults to None (statworx style is kept).
+    """
+    import plotly.io as pio
+
+    stwx_cmaps = get_stwx_cmaps()
+    _create_plotly_theme(
+        category=stwx_cmaps["stwx:alternative"] if category is None else category,
+        diverging=stwx_cmaps["stwx:BlRd_diverging"] if diverging is None else category,
+        sequential=stwx_cmaps["stwx:bad2good"] if sequential is None else sequential,
+        sequential_minus=(
+            stwx_cmaps["stwx:good2bad"] if sequential_minus is None else sequential_minus
+        ),
+        heatmap=stwx_cmaps["stwx:BlRd_diverging"] if heatmap is None else heatmap,
+        name="custom_plotly_theme",
+    )
+
+    pio.templates.default = "custom_plotly_theme"

statworx_theme-2.0.2.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 statworx GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

statworx_theme-2.0.2.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.1
+Name: statworx_theme
+Version: 2.0.2
+Summary: A color theme for matplotlib using the offical statworx design
+Home-page: https://statworx-theme.readthedocs.io/en/latest
+License: MIT
+Keywords: theme,matplotlib,plotting,statworx
+Author: statworx Team
+Author-email: accounts@statworx.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: altair
+Provides-Extra: plotly
+Requires-Dist: altair (>=5.2.0) ; extra == "altair"
+Requires-Dist: nbformat (>=5.4.0) ; extra == "plotly"
+Requires-Dist: plotly (>=5.10.0) ; extra == "plotly"
+Requires-Dist: seaborn (>=0.11.2)
+Requires-Dist: statsmodels (>=0.13.0) ; extra == "plotly"
+Requires-Dist: vega-datasets (>=0.9.0) ; extra == "altair"
+Project-URL: Repository, https://github.com/STATWORX/statworx-theme
+Description-Content-Type: text/markdown
+
+# Statworx Theme
+
+[![PyPI version](https://badge.fury.io/py/statworx-theme.svg)](https://badge.fury.io/py/statworx-theme)
+[![Documentation Status](https://readthedocs.org/projects/statworx-theme/badge/?version=latest)](https://statworx-theme.readthedocs.io/en/latest/?badge=latest)
+[![Release](https://github.com/STATWORX/statworx-theme/actions/workflows/release.yml/badge.svg)](https://github.com/STATWORX/statworx-theme/actions/workflows/release.yml)
+[![Code Quality](https://github.com/STATWORX/statworx-theme/actions/workflows/conde_quality.yml/badge.svg)](https://github.com/STATWORX/statworx-theme/actions/workflows/conde_quality.yml)
+[![Python version](https://img.shields.io/badge/python-3.8-blue.svg)](https://pypi.org/project/kedro/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/STATWORX/statworx-theme/blob/master/LICENSE)
+![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)
+
+A color theme plugin for the [matplotlib](https://matplotlib.org/) library and all its derivatives, as well as an optional adaption of this theme for [altair](https://altair-viz.github.io/) and [plotly](https://plotly.com/python/), which automatically applies the official statworx color theme.
+This package also registers commonly used [qualitative color maps](https://matplotlib.org/stable/tutorials/colors/colormaps.html) (such as a fade from good to bad) for use in presentations.
+
+![Sample](./docs/assets/sample.svg)
+
+## Quick Start
+
+Simply install a module with `pip` by using the following command.
+
+```console
+pip install statworx-theme
+```
+
+For usage of altair and plotly extra dependencies need to be installed using pip.
+
+```console
+pip install "statworx-theme[altair]"
+pip install "statworx-theme[plotly]"
+```
+
+For using the styles inside a poetry managed project use `poetry add` with extras.
+```console
+#only matplotlib
+poetry add statworx-theme
+
+# altair theme
+poetry add statworx-theme -E "altair"
+
+# plotly theme
+poetry add statworx-theme -E "plotly"
+
+# Whole package
+poetry add statworx-theme -E "altair plotly"
+```
+
+
+To apply the matplotlib style, you must call the `apply_style` function by typing:
+
+```python
+from statworx_theme import apply_style
+apply_style()
+```
+
+For applying the plotly or altair style the respective `apply_style_<library>` function is used:
+```python
+from statworx_theme import apply_style_altair, apply_style_plotly
+apply_style_altair()
+apply_style_plotly()
+```
+
+
+## Gallery
+
+#### Matplotlib
+There is an extensive gallery of figures that use the Statworx theme that you can draw inspiration from. You can find it [here](https://statworx-theme.readthedocs.io/en/latest/gallery.html).
+For a figure gallery using the altair and plotly theme see the respective notebooks inside the [repository](https://github.com/STATWORX/statworx-theme/tree/master/notebooks).
+
+![Sample](./docs/assets/gallery.png)
+
+## Custom Colors
+
+You can also use a custom list of color for the color scheme beside the official statworx colors.
+There is a convenience function for that which is described below.
+This simply changes the colors.
+
+##### Matplotlib
+In case you want to change the entire style you should implement your own `.mplstyle` file (see [this](https://matplotlib.org/stable/tutorials/introductory/customizing.html)).
+
+```python
+from statworx_theme import apply_custom_colors
+
+custom_colors = [
+    DARK_BLUE := "#0A526B",
+    DARK_RED := "#6B0020",
+    GREY := "#808285",
+]
+apply_custom_colors(custom_colors)
+```
+
+#### Altair
+
+```python
+from statworx_theme import apply_custom_colors_altair
+
+custom_colors = [
+    DARK_BLUE := "#0A526B",
+    DARK_RED := "#6B0020",
+    GREY := "#808285",
+]
+apply_custom_colors_altair(category=custom_colors)
+```
+
+#### Plotly
+
+```python
+from statworx_theme import apply_custom_colors_plotly
+custom_colors = [
+    DARK_BLUE := "#0A526B",
+    DARK_RED := "#6B0020",
+    GREY := "#808285",
+]
+apply_custom_colors_plotly(category=custom_colors)
+```
+

statworx_theme-2.0.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+statworx_theme/__init__.py,sha256=BOwY6YtHaSMy91G5OgIuotAv65LMcARwQ3uIo1fgA2A,342
+statworx_theme/colormaps.py,sha256=deY57Qfe-P0nsrFC_EpVKEiYEsOOkB2L8DeC3vj8w5E,2566
+statworx_theme/colors.py,sha256=QkmM3a55eeIdxDuhGQXlaSZppNkolYxRQ2m_wJoUhxA,909
+statworx_theme/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statworx_theme/styles/statworx.mplstyle,sha256=-QSZEsqWx8gFo0zJJYUfcqz4f4uKp44qIbcp1UXdKV4,44890
+statworx_theme/utils.py,sha256=AV3ilyZW_IKKOKQRtj8k34bhlbq32UjRWwx384UDxa4,14376
+statworx_theme-2.0.2.dist-info/LICENSE,sha256=W8Xr7I6xo1I_aW4-QR722mxOGyng9n4HOnRmogx87GE,1070
+statworx_theme-2.0.2.dist-info/METADATA,sha256=hKB6Qp9mXRkYq3LdDLOdImdFl7hCDdViOJKDTtyMQrc,5099
+statworx_theme-2.0.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+statworx_theme-2.0.2.dist-info/RECORD,,

statworx_theme-2.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any