charite-plot 0.1.0__tar.gz

charite_plot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci 
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache 
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocstrings[python]
+      - run: mkdocs gh-deploy --force

charite_plot-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+examples/**
+!examples/*.py
+site

charite_plot-0.1.0/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright 2026 Pedram Ramezani
+
+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.

charite_plot-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: charite-plot
+Version: 0.1.0
+Summary: Matplotlib and Altair themes for Charité – Universitätsmedizin Berlin
+Project-URL: Homepage, https://github.com/pedramramezani/charite-plot
+Project-URL: Documentation, https://pedramramezani.github.io/charite-plot
+Project-URL: Repository, https://github.com/pedramramezani/charite-plot
+Project-URL: Bug Tracker, https://github.com/pedramramezani/charite-plot/issues
+Author-email: Pedram Ramezani <pedramramezani.pr@gmail.com>
+License: # MIT License
+        
+        Copyright 2026 Pedram Ramezani
+        
+        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.
+License-File: LICENSE.md
+Keywords: altair,charite,matplotlib,theme,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: cycler
+Requires-Dist: matplotlib>=3.5
+Provides-Extra: all
+Requires-Dist: altair>=5.5; extra == 'all'
+Requires-Dist: vega-datasets; extra == 'all'
+Provides-Extra: altair
+Requires-Dist: altair>=5.5; extra == 'altair'
+Requires-Dist: vega-datasets; extra == 'altair'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# charite-plot
+
+A Python package with a Charité-styled Matplotlib theme, [visual identity](https://marke.charite.de/d/Y3FxSwD6Tz3a) colour palettes, and an Altair theme — ported from the [`charite` R package](https://github.com/johannesjuliusm/charite).
+
+## Installation
+
+```bash
+pip install charite-plot                   # Matplotlib only
+pip install "charite-plot[altair]"         # with Altair support
+```
+
+## Examples
+
+Visualize your data with `theme_charite()` to match the Charité corporate style.
+
+<p align="center">
+<img src="docs/assets/theme_example.png" width="80%"/>
+</p>
+
+Preview the available colour palettes.
+
+<p align="center">
+<img src="docs/assets/palette_preview.png" width="80%"/>
+</p>
+
+## Quick start
+
+### Matplotlib
+
+```python
+import matplotlib.pyplot as plt
+from charite_plot.mpl_themes import theme_charite, apply_theme
+
+apply_theme(theme_charite())
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [4, 7, 3])
+ax.set_title("My chart")
+plt.show()
+```
+
+Use as a context manager to scope the theme to a single figure:
+
+```python
+from charite_plot.mpl_themes import theme_charite, using
+
+with using(theme_charite(palette="goldelse")):
+    fig, ax = plt.subplots()
+    ax.bar(["A", "B", "C"], [3, 7, 5])
+```
+
+### Altair
+
+```python
+from charite_plot.altair_themes import enable
+import altair as alt
+
+enable()
+
+chart = alt.Chart(df).mark_bar().encode(...)
+```
+
+Customise with keyword arguments:
+
+```python
+enable(palette="berryseason", font_size=13)
+```
+
+## API overview
+
+| Symbol | Description |
+|--------|-------------|
+| `mpl_themes.theme_charite()` | Returns a matplotlib rcParams dict for the Charité theme |
+| `mpl_themes.apply_theme(params)` | Applies a theme dict permanently to `rcParams` |
+| `mpl_themes.using(params)` | Context manager: applies theme temporarily |
+| `altair_themes.theme_charite()` | Returns a Vega-Lite config dict for the Charité theme |
+| `altair_themes.enable(**kwargs)` | Registers and enables the theme in Altair |
+| `PALETTES` | Dict of 10 named colour palettes |
+| `make_palette(name, n, reverse)` | Subsample or interpolate any palette |
+| `CHARITE_COLORS` | Dict of all 27 hex colour constants |
+
+## Fonts
+
+The fallback chain follows the official Charité brand guidelines:
+
+**Charité Text Office → Charit? Text Office → Calibri → DejaVu Sans**
+
+> **Ersatzschrift „Calibri"** — Falls die Hausschrift aus technischen Gründen nicht verwendet werden kann, ersetzt die Systemschriftart „Calibri" die Hausschrift. Dies ist beispielsweise bei der E-Mail-Korrespondenz der Fall.
+
+`DejaVu Sans` ships with Matplotlib and is always available as the final fallback. To override the preferred font:
+
+```python
+apply_theme(theme_charite(font="Arial"))
+```
+
+## License
+
+MIT © 2026 Pedram Ramezani

charite_plot-0.1.0/README.md

@@ -0,0 +1,98 @@
+# charite-plot
+
+A Python package with a Charité-styled Matplotlib theme, [visual identity](https://marke.charite.de/d/Y3FxSwD6Tz3a) colour palettes, and an Altair theme — ported from the [`charite` R package](https://github.com/johannesjuliusm/charite).
+
+## Installation
+
+```bash
+pip install charite-plot                   # Matplotlib only
+pip install "charite-plot[altair]"         # with Altair support
+```
+
+## Examples
+
+Visualize your data with `theme_charite()` to match the Charité corporate style.
+
+<p align="center">
+<img src="docs/assets/theme_example.png" width="80%"/>
+</p>
+
+Preview the available colour palettes.
+
+<p align="center">
+<img src="docs/assets/palette_preview.png" width="80%"/>
+</p>
+
+## Quick start
+
+### Matplotlib
+
+```python
+import matplotlib.pyplot as plt
+from charite_plot.mpl_themes import theme_charite, apply_theme
+
+apply_theme(theme_charite())
+
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [4, 7, 3])
+ax.set_title("My chart")
+plt.show()
+```
+
+Use as a context manager to scope the theme to a single figure:
+
+```python
+from charite_plot.mpl_themes import theme_charite, using
+
+with using(theme_charite(palette="goldelse")):
+    fig, ax = plt.subplots()
+    ax.bar(["A", "B", "C"], [3, 7, 5])
+```
+
+### Altair
+
+```python
+from charite_plot.altair_themes import enable
+import altair as alt
+
+enable()
+
+chart = alt.Chart(df).mark_bar().encode(...)
+```
+
+Customise with keyword arguments:
+
+```python
+enable(palette="berryseason", font_size=13)
+```
+
+## API overview
+
+| Symbol | Description |
+|--------|-------------|
+| `mpl_themes.theme_charite()` | Returns a matplotlib rcParams dict for the Charité theme |
+| `mpl_themes.apply_theme(params)` | Applies a theme dict permanently to `rcParams` |
+| `mpl_themes.using(params)` | Context manager: applies theme temporarily |
+| `altair_themes.theme_charite()` | Returns a Vega-Lite config dict for the Charité theme |
+| `altair_themes.enable(**kwargs)` | Registers and enables the theme in Altair |
+| `PALETTES` | Dict of 10 named colour palettes |
+| `make_palette(name, n, reverse)` | Subsample or interpolate any palette |
+| `CHARITE_COLORS` | Dict of all 27 hex colour constants |
+
+## Fonts
+
+The fallback chain follows the official Charité brand guidelines:
+
+**Charité Text Office → Charit? Text Office → Calibri → DejaVu Sans**
+
+> **Ersatzschrift „Calibri"** — Falls die Hausschrift aus technischen Gründen nicht verwendet werden kann, ersetzt die Systemschriftart „Calibri" die Hausschrift. Dies ist beispielsweise bei der E-Mail-Korrespondenz der Fall.
+
+`DejaVu Sans` ships with Matplotlib and is always available as the final fallback. To override the preferred font:
+
+```python
+apply_theme(theme_charite(font="Arial"))
+```
+
+## License
+
+MIT © 2026 Pedram Ramezani

charite_plot-0.1.0/charite_plot/__init__.py

@@ -0,0 +1,30 @@
+"""charite_plot — Matplotlib and Altair themes for Charité – Universitätsmedizin Berlin.
+
+Quick start
+-----------
+Matplotlib::
+
+    import matplotlib.pyplot as plt
+    from charite_plot.mpl_themes import theme_charite, apply_theme
+
+    apply_theme(theme_charite())            # permanent
+    # or temporarily:
+    from charite_plot.mpl_themes import using
+    with using(theme_charite(palette="goldelse")):
+        fig, ax = plt.subplots()
+        ax.plot([1, 2, 3])
+
+Altair::
+
+    from charite_plot.altair_themes import enable
+    enable()
+    # charts rendered after this call use the theme automatically
+"""
+
+from .colors import *  # noqa: F401, F403  (all color constants + CHARITE_COLORS)
+from .palettes import PALETTES, make_palette  # noqa: F401
+from . import mpl_themes  # noqa: F401
+from . import altair_themes  # noqa: F401
+
+__version__ = "0.1.0"
+__author__ = "Pedram Ramezani"

charite_plot-0.1.0/charite_plot/altair_themes.py

@@ -0,0 +1,163 @@
+"""Altair / Vega-Lite theme for Charité – Universitätsmedizin Berlin.
+
+Register and enable with::
+
+    from charite_plot.altair_themes import enable
+    enable()                              # default params
+    enable(palette="goldelse")            # custom palette
+    enable(font="Arial", font_size=13)    # font override
+"""
+
+from .colors import (
+    BLACK, WHITE, TEXT_GREY, PRIME_BLUE, PRIME_LGREY,
+    SECOND_DBLUE, KORALL,
+)
+from .palettes import PALETTES
+from .fonts import build_font_stack
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from altair.theme import ThemeConfig
+
+
+def _css_font_stack(preferred: str | None) -> str:
+    """Return a CSS font-family string (comma-separated, quoted if needed)."""
+    def _quote(name: str) -> str:
+        return f'"{name}"' if " " in name else name
+
+    return ", ".join(_quote(f) for f in build_font_stack(preferred=preferred))
+
+
+def theme_charite(
+    font: str | None = None,
+    font_size: int = 12,
+    grid: bool = False,
+    palette: str | list[str] = "primary",
+    background: str = "white",
+) -> "ThemeConfig":
+    """Return an Altair theme config dict for the Charité corporate theme.
+
+    Parameters
+    ----------
+    font:
+        Preferred font. Falls back through Charité Text Office → Charit? Text Office → Calibri → DejaVu Sans.
+    font_size:
+        Base font size in pixels.
+    grid:
+        Show axis grid lines.
+    palette:
+        Built-in palette name or list of hex colors for the categorical range.
+    background:
+        Chart background color.
+    """
+    colors = PALETTES[palette] if isinstance(palette, str) else list(palette)
+    font_str = _css_font_stack(preferred=font)
+    label_size = font_size - 1
+    title_size = round(font_size * 1.2)
+
+    axis = {
+        "labelFont":     font_str,
+        "titleFont":     font_str,
+        "labelFontSize": label_size,
+        "titleFontSize": font_size,
+        "labelColor":    TEXT_GREY,
+        "titleColor":    TEXT_GREY,
+        "titlePadding":  6,
+        "domain":        True,
+        "domainColor":   BLACK,
+        "domainWidth":   0.5,
+        "ticks":         True,
+        "tickColor":     BLACK,
+        "tickWidth":     0.5,
+        "tickSize":      4,
+        "grid":          grid,
+        "gridColor":     PRIME_LGREY,
+        "gridWidth":     0.4,
+        "gridOpacity":   0.8,
+    }
+
+    return {
+        "config": {
+            "background": background,
+            "font":       font_str,
+            "padding":    {"top": 10, "bottom": 10, "left": 10, "right": 10},
+            "view":  {"stroke": None},
+            "axis":  axis,
+            "axisX": axis,
+            "axisY": axis,
+            "legend": {
+                "labelFont":     font_str,
+                "titleFont":     font_str,
+                "labelFontSize": label_size,
+                "titleFontSize": font_size,
+                "labelColor":    TEXT_GREY,
+                "titleColor":    TEXT_GREY,
+                "titlePadding":  6,
+                "padding":       4,
+                "rowPadding":    3,
+                "symbolSize":    100,
+            },
+            "header": {
+                "labelFont":       font_str,
+                "titleFont":       font_str,
+                "labelFontSize":   label_size,
+                "titleFontSize":   font_size,
+                "labelColor":      WHITE,
+                "titleColor":      PRIME_BLUE,
+                "labelBackground": PRIME_BLUE,
+            },
+            "title": {
+                "font":             font_str,
+                "subtitleFont":     font_str,
+                "fontSize":         title_size,
+                "subtitleFontSize": font_size,
+                "color":            PRIME_BLUE,
+                "subtitleColor":    TEXT_GREY,
+                "anchor":           "middle",
+                "offset":           12,
+            },
+            "range": {
+                "category":  colors,
+                "ordinal":   colors,
+                "diverging": [SECOND_DBLUE, "#ffffff", KORALL],
+                "heatmap":   ["#ffffff", PRIME_BLUE],
+                "ramp":      ["#ffffff", PRIME_BLUE],
+            },
+            "bar":      {"color": colors[0], "binSpacing": 1},
+            "line":     {"color": colors[0], "strokeWidth": 2},
+            "point":    {"color": colors[0], "size": 60, "opacity": 0.85, "filled": True},
+            "area":     {"color": colors[0], "opacity": 0.8},
+            "arc":      {"color": colors[0]},
+            "rect":     {"color": colors[0]},
+            "geoshape": {"stroke": WHITE, "strokeWidth": 0.4},
+            "text":     {"font": font_str, "fontSize": label_size, "color": TEXT_GREY},
+        }
+    }
+
+
+def register() -> None:
+    """Register the Charité theme with Altair's theme registry (default params)."""
+    import altair as alt
+    alt.theme.register("charite", enable=False)(theme_charite)
+
+
+def enable(**kwargs) -> None:
+    """Register and enable the Charité theme in Altair.
+
+    Parameters
+    ----------
+    **kwargs:
+        Any parameter accepted by ``theme_charite``
+        (``font``, ``font_size``, ``grid``, ``palette``, ``background``).
+
+    Examples
+    --------
+    ```python
+    from charite_plot.altair_themes import enable
+    enable(palette="goldelse", font_size=13)
+    ```
+    """
+    import altair as alt
+    func = (lambda: theme_charite(**kwargs)) if kwargs else theme_charite
+    alt.theme.register("charite", enable=True)(func)

charite_plot-0.1.0/charite_plot/colors.py

@@ -0,0 +1,77 @@
+"""Charité color definitions — the single source of truth shared by all themes."""
+
+# Primary
+WHITE        = "#ffffff"
+BLACK        = "#000000"
+TEXT_GREY    = "#5e676c"
+PRIME_BLUE   = "#004d9b"
+PRIME_LGREY  = "#cbcfd2"
+PRIME_DGREY  = "#7e898f"
+
+# Secondary
+SECOND_DBLUE = "#002552"
+SECOND_LBLUE = "#007bc3"
+KORALL       = "#ea5451"
+
+# Accents
+BRAUN        = "#89725b"
+MOCCA        = "#c8b8ad"
+GRASGRUEN    = "#a1ba0c"
+LIMETTE      = "#d1d811"
+GRUEN        = "#008939"
+MINT         = "#88c69a"
+MINERAL      = "#009aa9"
+AQUA         = "#61c3d7"
+LILA         = "#564091"
+LAVENDEL     = "#7876b6"
+BROMBEERE    = "#6f186d"
+PFLAUME      = "#944292"
+WEINROT      = "#89014c"
+HIMBEER      = "#d74b7f"
+ROT          = "#e31f2c"
+MANGO        = "#fab600"
+RAPSGELB     = "#ffdf43"
+
+# Special
+EMPLOYER_BRANDING_GREEN = "#ccefcb"
+
+# Lookup dict (lowercase keys)
+CHARITE_COLORS: dict[str, str] = {
+    "white":        WHITE,
+    "black":        BLACK,
+    "text_grey":    TEXT_GREY,
+    "prime_blue":   PRIME_BLUE,
+    "prime_lgrey":  PRIME_LGREY,
+    "prime_dgrey":  PRIME_DGREY,
+    "second_dblue": SECOND_DBLUE,
+    "second_lblue": SECOND_LBLUE,
+    "korall":       KORALL,
+    "braun":        BRAUN,
+    "mocca":        MOCCA,
+    "grasgruen":    GRASGRUEN,
+    "limette":      LIMETTE,
+    "gruen":        GRUEN,
+    "mint":         MINT,
+    "mineral":      MINERAL,
+    "aqua":         AQUA,
+    "lila":         LILA,
+    "lavendel":     LAVENDEL,
+    "brombeere":    BROMBEERE,
+    "pflaume":      PFLAUME,
+    "weinrot":      WEINROT,
+    "himbeer":      HIMBEER,
+    "rot":          ROT,
+    "mango":        MANGO,
+    "rapsgelb":     RAPSGELB,
+    "employer_branding_green": EMPLOYER_BRANDING_GREEN,
+}
+
+__all__ = [
+    "WHITE", "BLACK", "TEXT_GREY", "PRIME_BLUE", "PRIME_LGREY", "PRIME_DGREY",
+    "SECOND_DBLUE", "SECOND_LBLUE", "KORALL",
+    "BRAUN", "MOCCA", "GRASGRUEN", "LIMETTE", "GRUEN", "MINT",
+    "MINERAL", "AQUA", "LILA", "LAVENDEL", "BROMBEERE", "PFLAUME",
+    "WEINROT", "HIMBEER", "ROT", "MANGO", "RAPSGELB",
+    "EMPLOYER_BRANDING_GREEN",
+    "CHARITE_COLORS",
+]

charite_plot-0.1.0/charite_plot/fonts.py

@@ -0,0 +1,37 @@
+"""Font detection and fallback utilities."""
+
+import warnings
+
+FONT_STACK = ["Charité Text Office", "Charit? Text Office", "Calibri", "DejaVu Sans"]
+
+
+def _available_fonts() -> set[str]:
+    try:
+        import matplotlib.font_manager as fm
+        return {f.name for f in fm.fontManager.ttflist}
+    except Exception:
+        return set()
+
+
+def check_font(font: str) -> bool:
+    """Return True if *font* is available on this system, else warn and return False."""
+    if font in _available_fonts():
+        return True
+    warnings.warn(
+        f"Font '{font}' is not installed on this system. "
+        "Using the fallback chain: Charité Text Office → Charit? Text Office → Calibri → DejaVu Sans.",
+        UserWarning,
+        stacklevel=3,
+    )
+    return False
+
+
+def build_font_stack(preferred: str | None) -> list[str]:
+    """Return the font list for matplotlib's ``font.sans-serif`` rcParam."""
+    if preferred is None:
+        return FONT_STACK
+    check_font(preferred)
+    return [preferred, *[f for f in FONT_STACK if f != preferred]]
+
+if __name__ == "__main__":
+    print(sorted(_available_fonts()))