ENH add config and move plot_backend to config system (#141)

* ENH add config and move plot_backend to config system

* DOC mention plot backend more prominently

* TST set_config raises if plotly not installed

* DOC fix docstring for rendering with mkdocs

README.md

@@ -19,6 +19,7 @@ Highlights:
 - Assess the predictive performance of models
     - strictly consistent, homogeneous [scoring functions](https://lorentzenchr.github.io/model-diagnostics/reference/model_diagnostics/scoring/scoring/)
     - [score decomposition](https://lorentzenchr.github.io/model-diagnostics/reference/model_diagnostics/scoring/scoring/#model_diagnostics.scoring.scoring.decompose) into miscalibration, discrimination and uncertainty
+- Choose your plot backend, either [matplotlib](https://matplotlib.org) or [plotly](https://plotly.com/python/), e.g., via [set_config](https://lorentzenchr.github.io/model-diagnostics/reference/model_diagnostics/#model_diagnostics.set_config).
 
 :rocket: To our knowledge, this is the first python package to offer reliability diagrams for quantiles and expectiles and a score decomposition, both made available by an internal implementation of isotonic quantile/expectile regression. :rocket:
 

docs/gen_ref_pages.py

@@ -11,6 +11,7 @@
     - set(Path("src").rglob("*tests/*.py"))
     - set(Path("src").rglob("_*/*.py"))
     - set(Path("src/").rglob("__about__.py"))
+    - set(Path("src").rglob("*_config.py"))
 ):
     module_path = path.relative_to("src").with_suffix("")
     doc_path = path.relative_to("src").with_suffix(".md")

docs/index.md

@@ -19,6 +19,7 @@ Highlights:
 - Assess the predictive performance of models
     - strictly consistent, homogeneous [scoring functions][model_diagnostics.scoring.scoring]
     - [score decomposition][model_diagnostics.scoring.decompose] into miscalibration, discrimination and uncertainty
+- Choose your plot backend, either [matplotlib](https://matplotlib.org) or [plotly](https://plotly.com/python/), e.g., via [set_config][model_diagnostics.set_config].
 
 :rocket: To our knowledge, this is the first python package to offer reliability diagrams for quantiles and expectiles and a score decomposition, both made available by an internal implementation of isotonic quantile/expectile regression. :rocket:
 

src/model_diagnostics/__init__.py

@@ -2,4 +2,12 @@
 
 from packaging.version import parse
 
+from ._config import config_context, get_config, set_config
+
 polars_version = parse(version("polars"))
+
+__all__ = [
+    "get_config",
+    "set_config",
+    "config_context",
+]

src/model_diagnostics/_config.py

@@ -0,0 +1,119 @@
+"""
+Global configuration state and functions for management
+To a large part taken from scikit-learn.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib.util import find_spec
+from typing import Optional
+
+_global_config = {
+    "plot_backend": "matplotlib",
+}
+
+
+def get_config() -> dict:
+    """Retrieve current values for configuration set by :func:`set_config`.
+
+    Returns
+    -------
+    config : dict
+        A copy of the configuration dictionary. Keys are parameter names that can be
+        passed to :func:`set_config`.
+
+    See Also
+    --------
+    config_context : Context manager for global model-diagnostics configuration.
+    set_config : Set global model-diagnostics configuration.
+
+    Examples
+    --------
+    >>> import model_diagnostics
+    >>> config = model_diagnostics.get_config()
+    >>> config.keys()
+    dict_keys([...])
+    """
+    # Return a copy of the global config so that users will
+    # not be able to modify the configuration with the returned dict.
+    return _global_config.copy()
+
+
+def set_config(
+    plot_backend: Optional[str] = None,
+) -> None:
+    """Set global model-diagnostics configuration.
+
+    Parameters
+    ----------
+    plot_backend : bool, default=None
+        The library used for plotting. Can be "matplotlib" or "plotly".
+        If None, the existing value won't change. Global default: "matplotlib".
+
+    See Also
+    --------
+    config_context : Context manager for global scikit-learn configuration.
+    get_config : Retrieve current values of the global configuration.
+
+    Examples
+    --------
+    >>> from model_diagnostics import set_config
+    >>> set_config(plot_backend="plotly")  # doctest: +SKIP
+    """
+    if plot_backend not in (None, "matplotlib", "plotly"):
+        msg = f"The plot_backend must be matplotlib or plotly, got {plot_backend}."
+        raise ValueError(msg)
+    if plot_backend == "plotly" and not find_spec("plotly"):
+        msg = (
+            "In order to set the plot backend to plotly, plotly must be installed, "
+            "i.e. via `pip install plotly`."
+        )
+        raise ModuleNotFoundError(msg)
+
+    if plot_backend is not None:
+        _global_config["plot_backend"] = plot_backend
+
+
+@contextmanager
+def config_context(
+    *,
+    plot_backend: Optional[str] = None,
+) -> Iterator[None]:
+    """Context manager for global model-diagnostics configuration.
+
+    Parameters
+    ----------
+    plot_backend : bool, default=None
+        The library used for plotting. Can be "matplotlib" or "plotly".
+        If None, the existing value won't change. Global default: "matplotlib".
+
+    Yields
+    ------
+    None.
+
+    See Also
+    --------
+    set_config : Set global model-diagnostics configuration.
+    get_config : Retrieve current values of the global configuration.
+
+    Notes
+    -----
+    All settings, not just those presently modified, will be returned to
+    their previous values when the context manager is exited.
+
+    Examples
+    --------
+    >>> import model_diagnostics
+    >>> from model_diagnostics.calibration import plot_reliability_diagram
+    >>> with model_diagnostics.config_context(plot_backend="plotly"):  # doctest: +SKIP
+    ...    plot_reliability_diagram(y_obs=[0, 1], y_pred=[0.3, 0.7])
+    """
+    old_config = get_config()
+    set_config(
+        plot_backend=plot_backend,
+    )
+
+    try:
+        yield
+    finally:
+        set_config(**old_config)

src/model_diagnostics/_utils/plot_helper.py

@@ -4,17 +4,13 @@
 
 
 def get_plotly_color(i):
-    try:
-        sys.modules["plotly"]
-        # Sometimes, those turn out to be the same as matplotlib default.
-        # colors = plotly.colors.DEFAULT_PLOTLY_COLORS
-        # Those are the plotly color default color palette in hex.
-        import plotly.express as px
-
-        colors = px.colors.qualitative.Plotly
-        return colors[i % len(colors)]
-    except KeyError:
-        return False
+    # Sometimes, those turn out to be the same as matplotlib default.
+    # colors = plotly.colors.DEFAULT_PLOTLY_COLORS
+    # Those are the plotly color default color palette in hex.
+    import plotly.express as px
+
+    colors = px.colors.qualitative.Plotly
+    return colors[i % len(colors)]
 
 
 def get_xlabel(ax):

src/model_diagnostics/calibration/identification.py

@@ -45,7 +45,6 @@ def identification_function(
         - `"median"`. Argument `level` is neglected.
         - `"expectile"`
         - `"quantile"`
-
     level : float
         The level of the expectile of quantile. (Often called \(\alpha\).)
         It must be `0 < level < 1`.
@@ -162,7 +161,6 @@ def compute_bias(
         - `"median"`. Argument `level` is neglected.
         - `"expectile"`
         - `"quantile"`
-
     level : float
         The level of the expectile of quantile. (Often called \(\alpha\).)
         It must be `0 < level < 1`.

src/model_diagnostics/calibration/plots.py

@@ -12,7 +12,7 @@
 from scipy.stats import bootstrap
 from sklearn.isotonic import IsotonicRegression as IsotonicRegression_skl
 
-from model_diagnostics import polars_version
+from model_diagnostics import get_config, polars_version
 from model_diagnostics._utils._array import (
     array_name,
     get_array_min_max,
@@ -37,7 +37,6 @@ def plot_reliability_diagram(
     confidence_level: float = 0.9,
     diagram_type: str = "reliability",
     ax: Optional[mpl.axes.Axes] = None,
-    plot_backend: str = "matplotlib",
 ):
     r"""Plot a reliability diagram.
 
@@ -64,7 +63,6 @@ def plot_reliability_diagram(
         - `"median"`. Argument `level` is neglected.
         - `"expectile"`
         - `"quantile"`
-
     level : float
         The level of the expectile or quantile. (Often called \(\alpha\).)
         It must be `0 <= level <= 1`.
@@ -79,19 +77,16 @@ def plot_reliability_diagram(
         - `"reliability"`: Plot a reliability diagram.
         - `"bias"`: Plot roughly a 45 degree rotated reliability diagram. The resulting
           plot is similar to `plot_bias`, i.e. `y_pred - E(y_obs|y_pred)` vs `y_pred`.
-
     ax : matplotlib.axes.Axes or plotly Figure
         Axes object to draw the plot onto, otherwise uses the current Axes.
-    plot_backend: str
-        The plotting backend to use when `ax = None`. Options are:
-
-        - "matplotlib"
-        - "plotly"
 
     Returns
     -------
     ax :
-        Either the matplotlib axes or the plotly figure.
+        Either the matplotlib axes or the plotly figure. This is configurable by
+        setting the `plot_backend` via
+        [`model_diagnostics.set_config`][model_diagnostics.set_config] or
+        [`model_diagnostics.config_context`][model_diagnostics.config_context].
 
     Notes
     -----
@@ -115,11 +110,8 @@ def plot_reliability_diagram(
         In: Proceedings of the National Academy of Sciences 118.8 (2021), e2016191118.
         [doi:10.1073/pnas.2016191118](https://doi.org/10.1073/pnas.2016191118).
     """
-    if plot_backend not in ("matplotlib", "plotly"):
-        msg = f"The plot_backend must be matplotlib or plotly, got {plot_backend}."
-        raise ValueError(msg)
-
     if ax is None:
+        plot_backend = get_config()["plot_backend"]
         if plot_backend == "matplotlib":
             ax = plt.gca()
         else:
@@ -359,7 +351,6 @@ def plot_bias(
         - `"median"`. Argument `level` is neglected.
         - `"expectile"`
         - `"quantile"`
-
     level : float
         The level of the expectile or quantile. (Often called \(\alpha\).)
         It must be `0 <= level <= 1`.
@@ -374,15 +365,14 @@ def plot_bias(
         fulfil `0 <= confidence_level < 1`.
     ax : matplotlib.axes.Axes or plotly Figure
         Axes object to draw the plot onto, otherwise uses the current Axes.
-    plot_backend: str
-        The plotting backend to use when `ax = None`. Options are:
-
-        - "matplotlib"
-        - "plotly"
 
     Returns
     -------
-    ax
+    ax :
+        Either the matplotlib axes or the plotly figure. This is configurable by
+        setting the `plot_backend` via
+        [`model_diagnostics.set_config`][model_diagnostics.set_config] or
+        [`model_diagnostics.config_context`][model_diagnostics.config_context].
 
     Notes
     -----
@@ -406,10 +396,8 @@ def plot_bias(
         raise ValueError(msg)
     with_errorbars = confidence_level > 0
 
-    if plot_backend not in ("matplotlib", "plotly"):
-        msg = f"The plot_backend must be matplotlib or plotly, got {plot_backend}."
-        raise ValueError(msg)
     if ax is None:
+        plot_backend = get_config()["plot_backend"]
         if plot_backend == "matplotlib":
             ax = plt.gca()
         else: