arviz 0.23.3__py3-none-any.whl → 1.0.0rc0__py3-none-any.whl

arviz/rcparams.py

@@ -1,606 +0,0 @@
-"""ArviZ rcparams. Based on matplotlib's implementation."""
-
-import locale
-import logging
-import os
-import pprint
-import re
-import sys
-import warnings
-from collections.abc import MutableMapping
-from pathlib import Path
-from typing import Any, Dict
-from typing_extensions import Literal
-
-NO_GET_ARGS: bool = False  # pylint: disable=invalid-name
-try:
-    from typing_extensions import get_args
-except ImportError:
-    NO_GET_ARGS = True  # pylint: disable=invalid-name
-
-
-import numpy as np
-
-_log = logging.getLogger(__name__)
-
-ScaleKeyword = Literal["log", "negative_log", "deviance"]
-ICKeyword = Literal["loo", "waic"]
-
-_identity = lambda x: x
-
-
-def _make_validate_choice(accepted_values, allow_none=False, typeof=str):
-    """Validate value is in accepted_values.
-
-    Parameters
-    ----------
-    accepted_values : iterable
-        Iterable containing all accepted_values.
-    allow_none: boolean, optional
-        Whether to accept ``None`` in addition to the values in ``accepted_values``.
-    typeof: type, optional
-        Type the values should be converted to.
-    """
-    # no blank lines allowed after function docstring by pydocstyle,
-    # but black requires white line before function
-
-    def validate_choice(value):
-        if allow_none and (value is None or isinstance(value, str) and value.lower() == "none"):
-            return None
-        try:
-            value = typeof(value)
-        except (ValueError, TypeError) as err:
-            raise ValueError(f"Could not convert to {typeof.__name__}") from err
-        if isinstance(value, str):
-            value = value.lower()
-
-        if value in accepted_values:
-            # Convert value to python boolean if string matches
-            value = {"true": True, "false": False}.get(value, value)
-            return value
-        raise ValueError(
-            f'{value} is not one of {accepted_values}{" nor None" if allow_none else ""}'
-        )
-
-    return validate_choice
-
-
-def _make_validate_choice_regex(accepted_values, accepted_values_regex, allow_none=False):
-    """Validate value is in accepted_values with regex.
-
-    Parameters
-    ----------
-    accepted_values : iterable
-        Iterable containing all accepted_values.
-    accepted_values_regex : iterable
-        Iterable containing all accepted_values with regex string.
-    allow_none: boolean, optional
-        Whether to accept ``None`` in addition to the values in ``accepted_values``.
-    typeof: type, optional
-        Type the values should be converted to.
-    """
-    # no blank lines allowed after function docstring by pydocstyle,
-    # but black requires white line before function
-
-    def validate_choice_regex(value):
-        if allow_none and (value is None or isinstance(value, str) and value.lower() == "none"):
-            return None
-        value = str(value)
-        if isinstance(value, str):
-            value = value.lower()
-
-        if value in accepted_values:
-            # Convert value to python boolean if string matches
-            value = {"true": True, "false": False}.get(value, value)
-            return value
-        elif any(re.match(pattern, value) for pattern in accepted_values_regex):
-            return value
-        raise ValueError(
-            f"{value} is not one of {accepted_values} "
-            f'or in regex {accepted_values_regex}{" nor None" if allow_none else ""}'
-        )
-
-    return validate_choice_regex
-
-
-def _validate_positive_int(value):
-    """Validate value is a natural number."""
-    try:
-        value = int(value)
-    except ValueError as err:
-        raise ValueError("Could not convert to int") from err
-    if value > 0:
-        return value
-    else:
-        raise ValueError("Only positive values are valid")
-
-
-def _validate_float(value):
-    """Validate value is a float."""
-    try:
-        value = float(value)
-    except ValueError as err:
-        raise ValueError("Could not convert to float") from err
-    return value
-
-
-def _validate_probability(value):
-    """Validate a probability: a float between 0 and 1."""
-    value = _validate_float(value)
-    if (value < 0) or (value > 1):
-        raise ValueError("Only values between 0 and 1 are valid.")
-    return value
-
-
-def _validate_boolean(value):
-    """Validate value is a float."""
-    if isinstance(value, str):
-        value = value.lower()
-    if value not in {True, False, "true", "false"}:
-        raise ValueError("Only boolean values are valid.")
-    return value is True or value == "true"
-
-
-def _add_none_to_validator(base_validator):
-    """Create a validator function that catches none and then calls base_fun."""
-    # no blank lines allowed after function docstring by pydocstyle,
-    # but black requires white line before function
-
-    def validate_with_none(value):
-        if value is None or isinstance(value, str) and value.lower() == "none":
-            return None
-        return base_validator(value)
-
-    return validate_with_none
-
-
-def _validate_bokeh_marker(value):
-    """Validate the markers."""
-    try:
-        from bokeh.core.enums import MarkerType
-    except ImportError:
-        MarkerType = [
-            "asterisk",
-            "circle",
-            "circle_cross",
-            "circle_dot",
-            "circle_x",
-            "circle_y",
-            "cross",
-            "dash",
-            "diamond",
-            "diamond_cross",
-            "diamond_dot",
-            "dot",
-            "hex",
-            "hex_dot",
-            "inverted_triangle",
-            "plus",
-            "square",
-            "square_cross",
-            "square_dot",
-            "square_pin",
-            "square_x",
-            "star",
-            "star_dot",
-            "triangle",
-            "triangle_dot",
-            "triangle_pin",
-            "x",
-            "y",
-        ]
-    all_markers = list(MarkerType)
-    if value not in all_markers:
-        raise ValueError(f"{value} is not one of {all_markers}")
-    return value
-
-
-def _validate_dict_of_lists(values):
-    if isinstance(values, dict):
-        return {key: tuple(item) for key, item in values.items()}
-    validated_dict = {}
-    for value in values:
-        tup = value.split(":", 1)
-        if len(tup) != 2:
-            raise ValueError(f"Could not interpret '{value}' as key: list or str")
-        key, vals = tup
-        key = key.strip(' "')
-        vals = [val.strip(' "') for val in vals.strip(" [],").split(",")]
-        if key in validated_dict:
-            warnings.warn(f"Repeated key {key} when validating dict of lists")
-        validated_dict[key] = tuple(vals)
-    return validated_dict
-
-
-def make_iterable_validator(scalar_validator, length=None, allow_none=False, allow_auto=False):
-    """Validate value is an iterable datatype."""
-    # based on matplotlib's _listify_validator function
-
-    def validate_iterable(value):
-        if allow_none and (value is None or isinstance(value, str) and value.lower() == "none"):
-            return None
-        if isinstance(value, str):
-            if allow_auto and value.lower() == "auto":
-                return "auto"
-            value = tuple(v.strip("([ ])") for v in value.split(",") if v.strip())
-        if np.iterable(value) and not isinstance(value, (set, frozenset)):
-            val = tuple(scalar_validator(v) for v in value)
-            if length is not None and len(val) != length:
-                raise ValueError(f"Iterable must be of length: {length}")
-            return val
-        raise ValueError("Only ordered iterable values are valid")
-
-    return validate_iterable
-
-
-_validate_float_or_none = _add_none_to_validator(_validate_float)
-_validate_positive_int_or_none = _add_none_to_validator(_validate_positive_int)
-_validate_bokeh_bounds = make_iterable_validator(  # pylint: disable=invalid-name
-    _validate_float_or_none, length=2, allow_none=True, allow_auto=True
-)
-
-METAGROUPS = {
-    "posterior_groups": ["posterior", "posterior_predictive", "sample_stats", "log_likelihood"],
-    "prior_groups": ["prior", "prior_predictive", "sample_stats_prior"],
-    "posterior_groups_warmup": [
-        "_warmup_posterior",
-        "_warmup_posterior_predictive",
-        "_warmup_sample_stats",
-    ],
-    "latent_vars": ["posterior", "prior"],
-    "observed_vars": ["posterior_predictive", "observed_data", "prior_predictive"],
-}
-
-defaultParams = {  # pylint: disable=invalid-name
-    "data.http_protocol": ("https", _make_validate_choice({"https", "http"})),
-    "data.load": ("lazy", _make_validate_choice({"lazy", "eager"})),
-    "data.metagroups": (METAGROUPS, _validate_dict_of_lists),
-    "data.index_origin": (0, _make_validate_choice({0, 1}, typeof=int)),
-    "data.log_likelihood": (True, _validate_boolean),
-    "data.save_warmup": (False, _validate_boolean),
-    "plot.backend": ("matplotlib", _make_validate_choice({"matplotlib", "bokeh"})),
-    "plot.density_kind": ("kde", _make_validate_choice({"kde", "hist"})),
-    "plot.max_subplots": (40, _validate_positive_int_or_none),
-    "plot.point_estimate": (
-        "mean",
-        _make_validate_choice({"mean", "median", "mode"}, allow_none=True),
-    ),
-    "plot.bokeh.bounds_x_range": ("auto", _validate_bokeh_bounds),
-    "plot.bokeh.bounds_y_range": ("auto", _validate_bokeh_bounds),
-    "plot.bokeh.figure.dpi": (60, _validate_positive_int),
-    "plot.bokeh.figure.height": (500, _validate_positive_int),
-    "plot.bokeh.figure.width": (500, _validate_positive_int),
-    "plot.bokeh.layout.order": (
-        "default",
-        _make_validate_choice_regex(
-            {"default", r"column", r"row", "square", "square_trimmed"}, {r"\d*column", r"\d*row"}
-        ),
-    ),
-    "plot.bokeh.layout.sizing_mode": (
-        "fixed",
-        _make_validate_choice(
-            {
-                "fixed",
-                "stretch_width",
-                "stretch_height",
-                "stretch_both",
-                "scale_width",
-                "scale_height",
-                "scale_both",
-            }
-        ),
-    ),
-    "plot.bokeh.layout.toolbar_location": (
-        "above",
-        _make_validate_choice({"above", "below", "left", "right"}, allow_none=True),
-    ),
-    "plot.bokeh.marker": ("cross", _validate_bokeh_marker),
-    "plot.bokeh.output_backend": ("webgl", _make_validate_choice({"canvas", "svg", "webgl"})),
-    "plot.bokeh.show": (True, _validate_boolean),
-    "plot.bokeh.tools": (
-        "reset,pan,box_zoom,wheel_zoom,lasso_select,undo,save,hover",
-        lambda x: x,
-    ),
-    "plot.matplotlib.show": (False, _validate_boolean),
-    "stats.ci_prob": (0.94, _validate_probability),
-    "stats.information_criterion": (
-        "loo",
-        _make_validate_choice({"loo", "waic"} if NO_GET_ARGS else set(get_args(ICKeyword))),
-    ),
-    "stats.ic_pointwise": (True, _validate_boolean),
-    "stats.ic_scale": (
-        "log",
-        _make_validate_choice(
-            {"log", "negative_log", "deviance"} if NO_GET_ARGS else set(get_args(ScaleKeyword))
-        ),
-    ),
-    "stats.ic_compare_method": (
-        "stacking",
-        _make_validate_choice({"stacking", "bb-pseudo-bma", "pseudo-bma"}),
-    ),
-}
-
-# map from deprecated params to (version, new_param, fold2new, fnew2old)
-deprecated_map = {"stats.hdi_prob": ("0.18.0", "stats.ci_prob", _identity, _identity)}
-
-
-class RcParams(MutableMapping):
-    """Class to contain ArviZ default parameters.
-
-    It is implemented as a dict with validation when setting items.
-    """
-
-    validate = {key: validate_fun for key, (_, validate_fun) in defaultParams.items()}
-
-    # validate values on the way in
-    def __init__(self, *args, **kwargs):
-        self._underlying_storage: Dict[str, Any] = {}
-        super().__init__()
-        self.update(*args, **kwargs)
-
-    def __setitem__(self, key, val):
-        """Add validation to __setitem__ function."""
-        if key in deprecated_map:
-            version, key_new, fold2new, _ = deprecated_map[key]
-            warnings.warn(
-                f"{key} is deprecated since {version}, use {key_new} instead",
-                FutureWarning,
-            )
-            key = key_new
-            val = fold2new(val)
-
-        try:
-            try:
-                cval = self.validate[key](val)
-            except ValueError as verr:
-                raise ValueError(f"Key {key}: {str(verr)}") from verr
-            self._underlying_storage[key] = cval
-        except KeyError as err:
-            raise KeyError(
-                f"{key} is not a valid rc parameter "
-                f"(see rcParams.keys() for a list of valid parameters)"
-            ) from err
-
-    def __getitem__(self, key):
-        """Use underlying dict's getitem method."""
-        if key in deprecated_map:
-            version, key_new, _, fnew2old = deprecated_map[key]
-            warnings.warn(
-                f"{key} is deprecated since {version}, use {key_new} instead",
-                FutureWarning,
-            )
-            if key not in self._underlying_storage:
-                key = key_new
-        else:
-            fnew2old = _identity
-
-        return fnew2old(self._underlying_storage[key])
-
-    def __delitem__(self, key):
-        """Raise TypeError if someone ever tries to delete a key from RcParams."""
-        raise TypeError("RcParams keys cannot be deleted")
-
-    def clear(self):
-        """Raise TypeError if someone ever tries to delete all keys from RcParams."""
-        raise TypeError("RcParams keys cannot be deleted")
-
-    def pop(self, key, default=None):
-        """Raise TypeError if someone ever tries to delete a key from RcParams."""
-        raise TypeError(
-            "RcParams keys cannot be deleted. Use .get(key) of RcParams[key] to check values"
-        )
-
-    def popitem(self):
-        """Raise TypeError if someone ever tries to delete a key from RcParams."""
-        raise TypeError(
-            "RcParams keys cannot be deleted. Use .get(key) of RcParams[key] to check values"
-        )
-
-    def setdefault(self, key, default=None):
-        """Raise error when using setdefault, defaults are handled on initialization."""
-        raise TypeError(
-            "Defaults in RcParams are handled on object initialization during library"
-            "import. Use arvizrc file instead."
-            ""
-        )
-
-    def __repr__(self):
-        """Customize repr of RcParams objects."""
-        class_name = self.__class__.__name__
-        indent = len(class_name) + 1
-        repr_split = pprint.pformat(
-            self._underlying_storage,
-            indent=1,
-            width=80 - indent,
-        ).split("\n")
-        repr_indented = ("\n" + " " * indent).join(repr_split)
-        return f"{class_name}({repr_indented})"
-
-    def __str__(self):
-        """Customize str/print of RcParams objects."""
-        return "\n".join(map("{0[0]:<22}: {0[1]}".format, sorted(self._underlying_storage.items())))
-
-    def __iter__(self):
-        """Yield sorted list of keys."""
-        yield from sorted(self._underlying_storage.keys())
-
-    def __len__(self):
-        """Use underlying dict's len method."""
-        return len(self._underlying_storage)
-
-    def find_all(self, pattern):
-        """
-        Find keys that match a regex pattern.
-
-        Return the subset of this RcParams dictionary whose keys match,
-        using :func:`re.search`, the given ``pattern``.
-
-        Notes
-        -----
-            Changes to the returned dictionary are *not* propagated to
-            the parent RcParams dictionary.
-        """
-        pattern_re = re.compile(pattern)
-        return RcParams((key, value) for key, value in self.items() if pattern_re.search(key))
-
-    def copy(self):
-        """Get a copy of the RcParams object."""
-        return dict(self._underlying_storage)
-
-
-def get_arviz_rcfile():
-    """Get arvizrc file.
-
-    The file location is determined in the following order:
-
-    - ``$PWD/arvizrc``
-    - ``$ARVIZ_DATA/arvizrc``
-    - On Linux,
-        - ``$XDG_CONFIG_HOME/arviz/arvizrc`` (if ``$XDG_CONFIG_HOME``
-          is defined)
-        - or ``$HOME/.config/arviz/arvizrc`` (if ``$XDG_CONFIG_HOME``
-          is not defined)
-    - On other platforms,
-        - ``$HOME/.arviz/arvizrc`` if ``$HOME`` is defined
-
-    Otherwise, the default defined in ``rcparams.py`` file will be used.
-    """
-    # no blank lines allowed after function docstring by pydocstyle,
-    # but black requires white line before function
-
-    def gen_candidates():
-        yield os.path.join(os.getcwd(), "arvizrc")
-        arviz_data_dir = os.environ.get("ARVIZ_DATA")
-        if arviz_data_dir:
-            yield os.path.join(arviz_data_dir, "arvizrc")
-        xdg_base = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
-        if sys.platform.startswith(("linux", "freebsd")):
-            configdir = str(Path(xdg_base, "arviz"))
-        else:
-            configdir = str(Path.home() / ".arviz")
-        yield os.path.join(configdir, "arvizrc")
-
-    for fname in gen_candidates():
-        if os.path.exists(fname) and not os.path.isdir(fname):
-            return fname
-
-    return None
-
-
-def read_rcfile(fname):
-    """Return :class:`arviz.RcParams` from the contents of the given file.
-
-    Unlike `rc_params_from_file`, the configuration class only contains the
-    parameters specified in the file (i.e. default values are not filled in).
-    """
-    _error_details_fmt = 'line #%d\n\t"%s"\n\tin file "%s"'
-
-    config = RcParams()
-    with open(fname, "r", encoding="utf8") as rcfile:
-        try:
-            multiline = False
-            for line_no, line in enumerate(rcfile, 1):
-                strippedline = line.split("#", 1)[0].strip()
-                if not strippedline:
-                    continue
-                if multiline:
-                    if strippedline == "}":
-                        multiline = False
-                        val = aux_val
-                    else:
-                        aux_val.append(strippedline)
-                        continue
-                else:
-                    tup = strippedline.split(":", 1)
-                    if len(tup) != 2:
-                        error_details = _error_details_fmt % (line_no, line, fname)
-                        _log.warning("Illegal %s", error_details)
-                        continue
-                    key, val = tup
-                    key = key.strip()
-                    val = val.strip()
-                    if key in config:
-                        _log.warning("Duplicate key in file %r line #%d.", fname, line_no)
-                    if key in {"data.metagroups"}:
-                        aux_val = []
-                        multiline = True
-                        continue
-                try:
-                    config[key] = val
-                except ValueError as verr:
-                    error_details = _error_details_fmt % (line_no, line, fname)
-                    raise ValueError(f"Bad val {val} on {error_details}\n\t{str(verr)}") from verr
-
-        except UnicodeDecodeError:
-            _log.warning(
-                "Cannot decode configuration file %s with encoding "
-                "%s, check LANG and LC_* variables.",
-                fname,
-                locale.getpreferredencoding(do_setlocale=False) or "utf-8 (default)",
-            )
-            raise
-
-        return config
-
-
-def rc_params(ignore_files=False):
-    """Read and validate arvizrc file."""
-    fname = None if ignore_files else get_arviz_rcfile()
-    defaults = RcParams([(key, default) for key, (default, _) in defaultParams.items()])
-    if fname is not None:
-        file_defaults = read_rcfile(fname)
-        defaults.update(file_defaults)
-    return defaults
-
-
-rcParams = rc_params()  # pylint: disable=invalid-name
-
-
-class rc_context:  # pylint: disable=invalid-name
-    """
-    Return a context manager for managing rc settings.
-
-    Parameters
-    ----------
-    rc : dict, optional
-        Mapping containing the rcParams to modify temporally.
-    fname : str, optional
-        Filename of the file containing the rcParams to use inside the rc_context.
-
-    Examples
-    --------
-    This allows one to do::
-
-        with az.rc_context(fname='pystan.rc'):
-            idata = az.load_arviz_data("radon")
-            az.plot_posterior(idata, var_names=["gamma"])
-
-    The plot would have settings from 'screen.rc'
-
-    A dictionary can also be passed to the context manager::
-
-        with az.rc_context(rc={'plot.max_subplots': None}, fname='pystan.rc'):
-            idata = az.load_arviz_data("radon")
-            az.plot_posterior(idata, var_names=["gamma"])
-
-    The 'rc' dictionary takes precedence over the settings loaded from
-    'fname'. Passing a dictionary only is also valid.
-    """
-
-    # Based on mpl.rc_context
-
-    def __init__(self, rc=None, fname=None):
-        self._orig = rcParams.copy()
-        if fname:
-            file_rcparams = read_rcfile(fname)
-            rcParams.update(file_rcparams)
-        if rc:
-            rcParams.update(rc)
-
-    def __enter__(self):
-        """Define enter method of context manager."""
-        return self
-
-    def __exit__(self, exc_type, exc_value, exc_tb):
-        """Define exit method of context manager."""
-        rcParams.update(self._orig)