limno 0.1.0__py3-none-any.whl

limno/__init__.py

@@ -0,0 +1,14 @@
+"""limno: explainable AI for data streams and continual learning."""
+
+from limno import base, importance, imputer, multioutput, storage, tracker
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "base",
+    "importance",
+    "imputer",
+    "multioutput",
+    "storage",
+    "tracker",
+]

limno/base.py

@@ -0,0 +1,305 @@
+"""Base classes and protocols shared across limno.
+
+limno follows River's conventions: features are a dictionary `x`, and everything is processed one
+instance at a time through `*_one` methods.
+
+Explainers only rely on the `Model` and `Metric` protocols, not on a library. River models and
+metrics satisfy them as they are. Models from other libraries can be used through an adapter that
+exposes the same methods.
+
+"""
+
+from __future__ import annotations
+
+import abc
+import collections.abc
+import typing
+from collections.abc import Hashable
+
+__all__ = [
+    "Explainer",
+    "Feature",
+    "ImportanceExplainer",
+    "Imputer",
+    "Metric",
+    "Model",
+    "Storage",
+    "Tracker",
+]
+
+Feature = Hashable
+"""The name of a feature, i.e. a key of `x`."""
+
+
+@typing.runtime_checkable
+class Model(typing.Protocol):
+    """An incremental model.
+
+    Any River model satisfies this protocol, including pipelines. To be scored with a metric that
+    needs probabilities, such as `river.metrics.LogLoss`, a model also needs a
+    `predict_proba_one(x)` method.
+
+    """
+
+    def predict_one(self, x: dict) -> typing.Any: ...
+
+
+@typing.runtime_checkable
+class Metric(typing.Protocol):
+    """A metric that can score one instance at a time.
+
+    Any River metric satisfies this protocol. It tells which way is better with
+    `bigger_is_better`. A metric that has a `requires_labels` attribute set to `False` is given
+    probabilities instead of predicted labels, as in River.
+
+    """
+
+    bigger_is_better: bool
+
+    def update(self, y_true: typing.Any, y_pred: typing.Any) -> typing.Any: ...
+
+    def revert(self, y_true: typing.Any, y_pred: typing.Any) -> typing.Any: ...
+
+    def get(self) -> float: ...
+
+    def clone(self) -> Metric: ...
+
+
+@typing.runtime_checkable
+class Tracker(typing.Protocol):
+    """A running statistic of a series of numbers.
+
+    Statistics from `river.stats` satisfy this protocol.
+
+    """
+
+    def update(self, x: float) -> typing.Any: ...
+
+    def get(self) -> float: ...
+
+
+class Storage(abc.ABC):
+    """Base class for storages, which keep some of the past instances of a stream."""
+
+    def __init__(self) -> None:
+        self.instances: list[dict] = []
+
+    def __len__(self) -> int:
+        return len(self.instances)
+
+    @abc.abstractmethod
+    def update(self, x: dict) -> None:
+        """Offer an instance to the storage, which may keep it.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features.
+
+        """
+
+
+class Imputer(abc.ABC):
+    """Base class for imputers, which replace the values of some features of an instance."""
+
+    @property
+    def ready(self) -> bool:
+        """Whether the imputer can impute."""
+        return True
+
+    @abc.abstractmethod
+    def impute_one(self, x: dict, features: collections.abc.Iterable[Feature]) -> dict:
+        """Replace the values of some features.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features. It is not changed.
+        features
+            The features to replace.
+
+        Returns
+        -------
+        A new dictionary of features.
+
+        """
+
+    def learn_one(self, x: dict) -> None:
+        """Update the imputer with an instance of the stream. By default, it does nothing.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features.
+
+        """
+
+
+def _check_groups(groups: collections.abc.Mapping) -> None:
+    """Check that every group has features, and that no feature is in two groups."""
+    seen = set()
+    for name, features in groups.items():
+        if not features:
+            raise ValueError(f"group {name!r} has no features")
+        for feature in features:
+            if feature in seen:
+                raise ValueError(f"feature {feature!r} is in more than one group")
+            seen.add(feature)
+
+
+def _group(x: dict, groups: collections.abc.Mapping) -> dict[Hashable, list[Feature]]:
+    """The features of `x` by group. A feature that is in no group is a group of its own."""
+    group_of = {feature: name for name, features in groups.items() for feature in features}
+    grouped: dict[Hashable, list[Feature]] = {}
+    for feature in x:
+        if feature not in group_of and feature in groups:
+            raise ValueError(f"{feature!r} is both a feature and the name of a group")
+        grouped.setdefault(group_of.get(feature, feature), []).append(feature)
+    return grouped
+
+
+def _check_model(model: typing.Any) -> None:
+    """Check that `model` can predict."""
+    if not isinstance(model, Model):
+        raise TypeError(f"model must have a predict_one method, got {type(model).__name__}")
+
+
+def _check_river_metric(model: Model, metric: Metric) -> None:
+    """Check that River allows `metric` with `model`, if `model` is from River."""
+    try:
+        from river import base as river_base
+    except ImportError:
+        return
+    works_with = getattr(metric, "works_with", None)
+    if isinstance(model, river_base.Estimator) and works_with and not works_with(model):
+        raise ValueError(f"{type(metric).__name__} does not work with {type(model).__name__}")
+
+
+def _predictor(model: Model, metric: Metric) -> collections.abc.Callable[[dict], typing.Any]:
+    """The method of `model` that gives what `metric` expects, following River's rule."""
+    if not isinstance(metric, Metric):
+        raise TypeError(
+            "metric must have update, revert, get and clone methods and a bigger_is_better "
+            f"attribute, got {type(metric).__name__}"
+        )
+    # An adapter around a River model can have its own check, as River does not know the adapter
+    check_metric = getattr(model, "_check_metric", None)
+    if check_metric is not None:
+        check_metric(metric)
+    else:
+        _check_river_metric(model, metric)
+
+    if getattr(metric, "requires_labels", True):
+        return model.predict_one
+    predict_proba_one = getattr(model, "predict_proba_one", None)
+    if predict_proba_one is None:
+        raise TypeError(
+            f"{type(metric).__name__} needs probabilities, but {type(model).__name__} has no "
+            "predict_proba_one method"
+        )
+    return predict_proba_one
+
+
+class Explainer(abc.ABC):
+    """Base class for local explainers, which explain one prediction.
+
+    A local explainer scores how much each feature of an instance contributes to the prediction of
+    a model. It keeps a reference to the model, so its explanations follow the model as it learns.
+    The explainer never updates the model: that is up to the code that runs the stream.
+
+    Parameters
+    ----------
+    model
+        The model to explain.
+
+    Examples
+    --------
+    >>> class Linear:
+    ...     def predict_one(self, x):
+    ...         return 2 * x.get("a", 0) + x.get("b", 0)
+
+    >>> class DropFeature(Explainer):
+    ...     def explain_one(self, x):
+    ...         y_pred = self.model.predict_one(x)
+    ...         return {
+    ...             f: y_pred - self.model.predict_one({k: v for k, v in x.items() if k != f})
+    ...             for f in x
+    ...         }
+
+    >>> DropFeature(Linear()).explain_one({"a": 1, "b": 3})
+    {'a': 2, 'b': 3}
+
+    """
+
+    def __init__(self, model: Model) -> None:
+        _check_model(model)
+        self.model = model
+
+    @abc.abstractmethod
+    def explain_one(self, x: dict) -> dict[Feature, float]:
+        """Explain the prediction of the model for an instance.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features.
+
+        Returns
+        -------
+        The contribution of each feature to the prediction.
+
+        """
+
+    def learn_one(self, x: dict, y: typing.Any) -> None:
+        """Update the explainer with an instance of the stream.
+
+        By default, it does nothing. Explainers that keep a state, such as a sample of past
+        instances, update it here.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features.
+        y
+            The target of the instance.
+
+        """
+
+
+class ImportanceExplainer(abc.ABC):
+    """Base class for global explainers, which measure how much a model relies on each feature.
+
+    It learns from the stream with `learn_one`, and `importances` gives the current values. It keeps
+    a reference to the model, but never updates it: that is up to the code that runs the stream.
+
+    Parameters
+    ----------
+    model
+        The model to explain.
+
+    """
+
+    def __init__(self, model: Model) -> None:
+        _check_model(model)
+        self.model = model
+
+    @abc.abstractmethod
+    def learn_one(self, x: dict, y: typing.Any) -> None:
+        """Update the importances with an instance of the stream.
+
+        Call this before the model learns from the instance, so that the instance is new to the
+        model.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features.
+        y
+            The target of the instance.
+
+        """
+
+    @property
+    @abc.abstractmethod
+    def importances(self) -> dict[Feature, float]:
+        """The current importance of each feature."""

limno/importance/__init__.py

@@ -0,0 +1,9 @@
+"""Global explainers, which measure how much a model relies on each feature over a stream."""
+
+from limno.importance.pfi import PFI
+from limno.importance.sage import SAGE
+
+__all__ = [
+    "PFI",
+    "SAGE",
+]

limno/importance/_base.py

@@ -0,0 +1,98 @@
+"""What the explainers that compare losses have in common."""
+
+from __future__ import annotations
+
+import collections.abc
+import copy
+import random
+import typing
+
+from limno.base import (
+    Feature,
+    ImportanceExplainer,
+    Imputer,
+    Metric,
+    Model,
+    Tracker,
+    _check_groups,
+    _group,
+    _predictor,
+)
+from limno.imputer import Marginal
+from limno.storage import GeometricReservoir
+from limno.tracker import EWMean
+
+Groups = collections.abc.Mapping[typing.Hashable, collections.abc.Collection[Feature]]
+
+
+class _LossImportance(ImportanceExplainer):
+    """What the explainers that compare losses have in common."""
+
+    def __init__(
+        self,
+        model: Model,
+        metric: Metric,
+        imputer: Imputer | None,
+        tracker: Tracker | None,
+        n_samples: int,
+        seed: int | None,
+        max_age: int | None,
+        groups: Groups | None,
+    ) -> None:
+        super().__init__(model)
+        self._predict = _predictor(model, metric)
+        if n_samples < 1:
+            raise ValueError(f"n_samples must be at least 1, got {n_samples}")
+        if max_age is not None and max_age < 1:
+            raise ValueError(f"max_age must be at least 1 or None, got {max_age}")
+        groups = {} if groups is None else groups
+        _check_groups(groups)
+
+        # A clone, as the loss of an instance must not be mixed with what the metric has seen
+        self.metric = metric.clone()
+        self.n_samples = n_samples
+        self.seed = seed
+        self.max_age = max_age
+        self.groups = groups
+        self._rng = random.Random(seed)
+        if imputer is None:
+            storage = GeometricReservoir(seed=self._rng.getrandbits(32))
+            imputer = Marginal(storage, seed=self._rng.getrandbits(32))
+        self.imputer = imputer
+        self.tracker = EWMean() if tracker is None else tracker
+        self._trackers: dict[Feature, Tracker] = {}
+        self._sign = -1.0 if metric.bigger_is_better else 1.0
+        self._n_seen = 0
+        self._last_seen: dict[Feature, int] = {}
+
+    def _see(self, x: dict) -> dict[typing.Hashable, list[Feature]]:
+        """Note which features and groups are in `x`, and give its features by group."""
+        grouped = _group(x, self.groups)
+        self._n_seen += 1
+        for name in grouped:
+            self._last_seen[name] = self._n_seen
+        return grouped
+
+    def _features(self, name: typing.Hashable, grouped: dict) -> collections.abc.Collection:
+        """All the features of a group, so that those missing from `x` are filled in."""
+        return self.groups.get(name, grouped[name])
+
+    def _loss(self, y: typing.Any, y_pred: typing.Any) -> float:
+        self.metric.update(y, y_pred)
+        loss = self.metric.get()
+        self.metric.revert(y, y_pred)
+        return self._sign * loss
+
+    def _update_importance(self, feature: Feature, value: float) -> None:
+        if feature not in self._trackers:
+            self._trackers[feature] = copy.deepcopy(self.tracker)
+        self._trackers[feature].update(value)
+
+    @property
+    def importances(self) -> dict[Feature, float]:
+        """The current importance of each feature or group, without those hidden by `max_age`."""
+        return {
+            feature: tracker.get()
+            for feature, tracker in self._trackers.items()
+            if self.max_age is None or self._n_seen - self._last_seen[feature] < self.max_age
+        }

limno/importance/pfi.py

@@ -0,0 +1,110 @@
+"""Incremental permutation feature importance (iPFI)."""
+
+from __future__ import annotations
+
+import typing
+
+from limno.base import Imputer, Metric, Model, Tracker
+from limno.importance._base import Groups, _LossImportance
+
+
+class PFI(_LossImportance):
+    """Incremental permutation feature importance (iPFI).
+
+    For each instance and feature, the feature is replaced with its value in a past instance. The
+    importance of a feature is how much this increases the loss of the model, as a running mean
+    over the stream. A positive value means that the model does better with the feature, and a
+    value close to zero that it does not rely on it.
+
+    Each instance takes `1 + n_features * n_samples` predictions, or `1 + n_groups * n_samples` with
+    `groups`.
+
+    The method is from Fumagalli et al., "Incremental permutation feature importance (iPFI):
+    towards online explanations on data streams", Machine Learning, 2023,
+    https://doi.org/10.1007/s10994-023-06385-y.
+
+    Parameters
+    ----------
+    model
+        The model to explain. It is not updated, but explanations follow it as it learns.
+    metric
+        The metric that gives the loss, such as `river.metrics.MAE` or `river.metrics.LogLoss`.
+        Whether the model is asked for labels or probabilities depends on the metric, as in River.
+        It is computed on one instance at a time, so metrics that need many instances, such as
+        `river.metrics.ROCAUC` or `river.metrics.F1`, are not useful here.
+    imputer
+        How features are replaced. By default, an `imputer.Marginal` with a
+        `storage.GeometricReservoir` of 100 instances, which follows changes in the stream.
+    tracker
+        The running statistic of each importance, which is copied for each feature. By default, a
+        `tracker.EWMean` with an `alpha` of 0.001. The authors of iPFI found that an `alpha`
+        between 0.001 and 0.01 works well. Use `tracker.Mean` with a
+        `storage.UniformReservoir` if the stream does not change.
+    n_samples
+        The number of past instances to use per feature and instance. More samples give less noise
+        but take more predictions.
+    seed
+        Random seed of the default imputer. To use a seed with your own imputer, give it to the
+        imputer and its storage.
+    max_age
+        Hide a feature from `importances` once it is missing from this many instances in a row, as
+        its value is out of date. It comes back with its old value if it appears again. Raise this
+        for features that are rare, and use `None` to never hide a feature. The default matches the
+        window of the default tracker. A group is seen when any of its features is. This is not
+        part of iPFI, which assumes that the features do not change.
+    groups
+        Features to treat as one, such as `{"location": ["lat", "lon"]}`. A group is replaced as a
+        whole and gets one importance, under its name. With `imputer.Marginal`, its values all come
+        from the same past instance. Features in no group get their own importance. This suits
+        features that only make sense together, such as the columns of a one-hot encoding, or that
+        are correlated. A model can split its weight between correlated features, and then each one
+        alone looks less important than they are together.
+
+
+    Examples
+    --------
+    >>> from river import datasets, linear_model, metrics, preprocessing
+
+    >>> model = preprocessing.StandardScaler() | linear_model.LinearRegression()
+    >>> explainer = PFI(model, metrics.MAE(), seed=42)
+
+    >>> for x, y in datasets.synth.Friedman(seed=42).take(1000):
+    ...     explainer.learn_one(x, y)
+    ...     model.learn_one(x, y)
+
+    In this stream, feature 3 has the largest linear effect on the target.
+
+    >>> max(explainer.importances, key=explainer.importances.get)
+    3
+
+    """
+
+    def __init__(
+        self,
+        model: Model,
+        metric: Metric,
+        imputer: Imputer | None = None,
+        tracker: Tracker | None = None,
+        n_samples: int = 1,
+        seed: int | None = None,
+        max_age: int | None = 2000,
+        groups: Groups | None = None,
+    ) -> None:
+        super().__init__(model, metric, imputer, tracker, n_samples, seed, max_age, groups)
+        if imputer is not None and seed is not None:
+            raise ValueError("seed only applies to the default imputer, give it to your imputer")
+
+    def learn_one(self, x: dict, y: typing.Any) -> None:
+        grouped = self._see(x)
+        if self.imputer.ready:
+            y_pred = self._predict(x)
+            # A River classifier that has not learned yet predicts None or {}
+            if y_pred is not None and y_pred != {}:
+                loss = self._loss(y, y_pred)
+                for name in grouped:
+                    imputed_loss = 0.0
+                    for _ in range(self.n_samples):
+                        imputed = self.imputer.impute_one(x, self._features(name, grouped))
+                        imputed_loss += self._loss(y, self._predict(imputed))
+                    self._update_importance(name, imputed_loss / self.n_samples - loss)
+        self.imputer.learn_one(x)

limno/importance/sage.py

@@ -0,0 +1,194 @@
+"""Incremental Shapley additive global importance (iSAGE)."""
+
+from __future__ import annotations
+
+import copy
+import numbers
+import typing
+
+from limno.base import Imputer, Metric, Model, Tracker
+from limno.importance._base import Groups, _LossImportance
+
+
+def _number(y_pred: typing.Any) -> float:
+    """Check that a prediction can be averaged."""
+    if isinstance(y_pred, bool) or not isinstance(y_pred, numbers.Real):
+        raise TypeError(
+            "SAGE averages predictions, so they must be numbers or probabilities, got "
+            f"{type(y_pred).__name__}"
+        )
+    return float(y_pred)
+
+
+def _average(y_preds: list) -> typing.Any:
+    """The mean of predictions, in which a key that is missing from a dictionary counts as 0."""
+    if isinstance(y_preds[0], dict):
+        keys = dict.fromkeys(key for y_pred in y_preds for key in y_pred)
+        return {
+            key: sum(_number(y_pred.get(key, 0.0)) for y_pred in y_preds) / len(y_preds)
+            for key in keys
+        }
+    return sum(_number(y_pred) for y_pred in y_preds) / len(y_preds)
+
+
+def _check_no_labels(metric: Metric) -> None:
+    """Check that `metric` is not a River metric for labels, as labels cannot be averaged."""
+    try:
+        from river import linear_model
+    except ImportError:
+        return
+    works_with = getattr(metric, "works_with", None)
+    if (
+        getattr(metric, "requires_labels", False)
+        and works_with
+        and works_with(linear_model.LogisticRegression())
+    ):
+        raise ValueError(
+            f"{type(metric).__name__} needs labels, but SAGE averages predictions. Use a metric "
+            "for probabilities, such as LogLoss"
+        )
+
+
+class SAGE(_LossImportance):
+    """Incremental Shapley additive global importance (iSAGE).
+
+    SAGE shares out the drop in loss between predicting the mean and using the model, based on
+    Shapley values. For each instance, it reveals the features in a random order. Features that are
+    not revealed yet take their values from past instances, and the importance of a feature is how
+    much revealing it lowers the loss, as a running mean over the stream.
+
+    A positive value means that the model does better with the feature. Unlike `PFI`, the values
+    add up to the drop in loss, as long as the features of the stream do not change. This also
+    accounts for features that interact, as each feature is seen with different others.
+
+    Each instance takes `1 + (n_features - 1) * n_samples` predictions, or
+    `1 + (n_groups - 1) * n_samples` with `groups`.
+
+    Features are replaced from the marginal distribution, the interventional approach of the paper.
+    So correlated features can make unrealistic instances. The observational approach of the paper
+    is not implemented.
+
+    The method is from Muschalik et al., "iSAGE: An Incremental Version of SAGE for Online
+    Explanation on Data Streams", ECML PKDD, 2023, https://doi.org/10.1007/978-3-031-43418-1_26.
+
+    Parameters
+    ----------
+    model
+        The model to explain. It is not updated, but explanations follow it as it learns.
+    metric
+        The metric that gives the loss, such as `river.metrics.MAE` or `river.metrics.LogLoss`.
+        Predictions are averaged, so it must take numbers or probabilities. Metrics that need
+        labels, such as `river.metrics.Accuracy`, are rejected. A metric of your own for labels
+        that are numbers cannot be detected, so do not use one.
+    imputer
+        How features are replaced. By default, an `imputer.Marginal` with a
+        `storage.GeometricReservoir` of 100 instances, which follows changes in the stream.
+    tracker
+        The running statistic of each importance and of the mean prediction, which is copied for
+        each of them. By default, a `tracker.EWMean` with an `alpha` of 0.001. Use `tracker.Mean`
+        with a `storage.UniformReservoir` if the stream does not change.
+    n_samples
+        The number of past instances to average over at each step. The paper only proves that the
+        values reach the true ones as this grows. With few samples, importance moves from unused
+        features to used ones, so that unused features are below zero, even though the sum stays
+        right. Lower this only if predictions are slow, and raise it if the exact values matter.
+    seed
+        Random seed of the order of the features and of the default imputer. To also use a seed
+        with your own imputer, give it to the imputer and its storage.
+    max_age
+        Hide a feature from `importances` once it is missing from this many instances in a row, as
+        its value is out of date. It comes back with its old value if it appears again. Raise this
+        for features that are rare, and use `None` to never hide a feature. The default matches the
+        window of the default tracker. A group is seen when any of its features is. This is not
+        part of iSAGE, which assumes that the features do not change.
+    groups
+        Features to treat as one, such as `{"location": ["lat", "lon"]}`. A group is revealed as a
+        whole and gets one importance, under its name. With `imputer.Marginal`, its values all come
+        from the same past instance. Features in no group get their own importance. This suits
+        features that only make sense together, such as the columns of a one-hot encoding, or that
+        are correlated. A model can split its weight between correlated features, and then each one
+        alone looks less important than they are together.
+
+
+    Examples
+    --------
+    >>> from river import datasets, linear_model, metrics, preprocessing
+
+    >>> model = preprocessing.StandardScaler() | linear_model.LinearRegression()
+    >>> explainer = SAGE(model, metrics.MAE(), seed=42)
+
+    >>> for x, y in datasets.synth.Friedman(seed=42).take(1000):
+    ...     explainer.learn_one(x, y)
+    ...     model.learn_one(x, y)
+
+    In this stream, feature 3 has the largest linear effect on the target.
+
+    >>> max(explainer.importances, key=explainer.importances.get)
+    3
+
+    """
+
+    def __init__(
+        self,
+        model: Model,
+        metric: Metric,
+        imputer: Imputer | None = None,
+        tracker: Tracker | None = None,
+        n_samples: int = 5,
+        seed: int | None = None,
+        max_age: int | None = 2000,
+        groups: Groups | None = None,
+    ) -> None:
+        super().__init__(model, metric, imputer, tracker, n_samples, seed, max_age, groups)
+        _check_no_labels(metric)
+        self._means: dict[typing.Any, Tracker] = {}
+        self._n_means = 0
+
+    def _mean_prediction(self, y_pred: typing.Any) -> typing.Any:
+        """Update the running mean of the predictions, and give its current value."""
+        is_dict = isinstance(y_pred, dict)
+        values = y_pred if is_dict else {None: y_pred}
+        for key in {**self._means, **values}:
+            if key not in self._means:
+                self._means[key] = copy.deepcopy(self.tracker)
+                # A new class had a probability of 0 until now, and all must still add up to 1
+                for _ in range(self._n_means):
+                    self._means[key].update(0.0)
+            self._means[key].update(_number(values.get(key, 0.0)))
+        self._n_means += 1
+        if is_dict:
+            return {key: mean.get() for key, mean in self._means.items()}
+        return self._means[None].get()
+
+    def _explain(self, x: dict, y: typing.Any, y_pred: typing.Any, grouped: dict) -> None:
+        """Reveal the features or groups of an instance in a random order."""
+        previous_loss = self._loss(y, self._mean_prediction(y_pred))
+        order = list(grouped)
+        self._rng.shuffle(order)
+        contributions = {}
+        for i, name in enumerate(order, start=1):
+            hidden = [feature for later in order[i:] for feature in self._features(later, grouped)]
+            # With no feature left to hide, every sample would give `y_pred`
+            y_mean = y_pred
+            if hidden:
+                y_mean = _average(
+                    [
+                        self._predict(self.imputer.impute_one(x, hidden))
+                        for _ in range(self.n_samples)
+                    ]
+                )
+            loss = self._loss(y, y_mean)
+            contributions[name] = previous_loss - loss
+            previous_loss = loss
+        # In the order of `x`, so that the order of `importances` is not random
+        for name in grouped:
+            self._update_importance(name, contributions[name])
+
+    def learn_one(self, x: dict, y: typing.Any) -> None:
+        grouped = self._see(x)
+        if self.imputer.ready:
+            y_pred = self._predict(x)
+            # A River classifier that has not learned yet predicts None or {}
+            if y_pred is not None and y_pred != {}:
+                self._explain(x, y, y_pred, grouped)
+        self.imputer.learn_one(x)

limno/imputer.py

@@ -0,0 +1,62 @@
+"""Imputers, which replace the values of some features of an instance."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Iterable
+
+from limno.base import Feature, Imputer, Storage
+from limno.storage import GeometricReservoir
+
+__all__ = [
+    "Marginal",
+]
+
+
+class Marginal(Imputer):
+    """Replace features with their values in a random past instance.
+
+    The replaced features of an instance are always taken from the same past instance. If that
+    instance does not have a feature, the feature is removed, as River models accept instances
+    with missing features.
+
+    Parameters
+    ----------
+    storage
+        Where the past instances are kept. By default, a `storage.GeometricReservoir`.
+    seed
+        Random seed for picking past instances.
+
+    Examples
+    --------
+    >>> imputer = Marginal(seed=42)
+    >>> imputer.learn_one({"a": 1, "b": 2})
+    >>> imputer.impute_one({"a": 5, "b": 6}, ["b"])
+    {'a': 5, 'b': 2}
+
+    """
+
+    def __init__(self, storage: Storage | None = None, seed: int | None = None) -> None:
+        self.storage = GeometricReservoir() if storage is None else storage
+        self.seed = seed
+        self._rng = random.Random(seed)
+
+    @property
+    def ready(self) -> bool:
+        """Whether there is a past instance to take values from."""
+        return len(self.storage) > 0
+
+    def impute_one(self, x: dict, features: Iterable[Feature]) -> dict:
+        if not self.ready:
+            raise ValueError("the storage is empty, call learn_one first")
+        past = self._rng.choice(self.storage.instances)
+        imputed = dict(x)
+        for feature in features:
+            if feature in past:
+                imputed[feature] = past[feature]
+            else:
+                imputed.pop(feature, None)
+        return imputed
+
+    def learn_one(self, x: dict) -> None:
+        self.storage.update(x)

limno/multioutput.py

@@ -0,0 +1,150 @@
+"""Wrappers that explain each output of a multi-output model on its own."""
+
+from __future__ import annotations
+
+import collections.abc
+import typing
+from collections.abc import Hashable
+
+from limno.base import Feature, ImportanceExplainer, Metric, Model, _check_model
+
+__all__ = [
+    "PerOutput",
+]
+
+
+def _stand_in(model: typing.Any) -> typing.Any:
+    """A River model with one output of the same kind as `model`, or `None` if it is not from River.
+
+    River's `works_with` rejects a metric for one output when given a multi-output model, so it is
+    given this model instead.
+
+    """
+    try:
+        from river import base as river_base
+        from river import linear_model
+    except ImportError:
+        return None
+    if isinstance(model, river_base.MultiTargetRegressor):
+        return linear_model.LinearRegression()
+    if isinstance(model, river_base.MultiLabelClassifier):
+        return linear_model.LogisticRegression()
+    if isinstance(model, river_base.Estimator):
+        raise TypeError(f"model must have many outputs, got {type(model).__name__}")
+    return None
+
+
+class _Output:
+    """One output of a multi-output model, shown as a model with one output."""
+
+    def __init__(self, model: typing.Any, output: Hashable, stand_in: typing.Any) -> None:
+        self.model = model
+        self.output = output
+        self._stand_in = stand_in
+
+    def predict_one(self, x: dict) -> typing.Any:
+        return self.model.predict_one(x).get(self.output)
+
+    @property
+    def predict_proba_one(self) -> collections.abc.Callable[[dict], typing.Any]:
+        # A property, so that this is missing if the model does not have the method
+        predict_proba_one = self.model.predict_proba_one
+        return lambda x: predict_proba_one(x).get(self.output)
+
+    def _check_metric(self, metric: Metric) -> None:
+        works_with = getattr(metric, "works_with", None)
+        if self._stand_in is not None and works_with and not works_with(self._stand_in):
+            raise ValueError(
+                f"{type(metric).__name__} does not work with one output of "
+                f"{type(self.model).__name__}"
+            )
+
+
+class PerOutput:
+    """Measure how much each output of a multi-output model relies on each feature.
+
+    There is one explainer per output, which is created when the output first appears in `y`. For
+    one value per feature over all the outputs, use a global explainer with a metric from
+    `river.metrics.multioutput` instead.
+
+    Each output costs as much as a model with one output, so `PFI` takes
+    `n_outputs * (1 + n_features * n_samples)` predictions per instance. Each output also keeps its
+    own explainer state, such as past instances.
+
+    In a chain, a later output uses the predictions of earlier ones. So the importance of a feature
+    for an output includes its effect through earlier outputs.
+
+    This is not part of iPFI, whose paper has examples with one output.
+
+    Parameters
+    ----------
+    model
+        The model to explain, whose `predict_one` gives a dictionary with one value per output. It
+        is not updated, but explanations follow it as it learns.
+    make_explainer
+        Creates the explainer of an output. It is given a model with that one output. Use a metric
+        for one output here, such as `river.metrics.MAE`.
+
+    Examples
+    --------
+    >>> import random
+
+    >>> from river import linear_model, metrics, multioutput
+
+    >>> from limno.importance import PFI
+
+    >>> model = multioutput.RegressorChain(linear_model.LinearRegression(), order=["y1", "y2"])
+    >>> explainer = PerOutput(model, lambda output: PFI(output, metrics.MAE(), seed=42))
+
+    >>> rng = random.Random(42)
+    >>> for _ in range(2000):
+    ...     x = {"a": rng.random(), "b": rng.random()}
+    ...     y = {"y1": 3 * x["a"], "y2": 3 * x["b"]}
+    ...     explainer.learn_one(x, y)
+    ...     model.learn_one(x, y)
+
+    >>> {output: max(values, key=values.get) for output, values in explainer.importances.items()}
+    {'y1': 'a', 'y2': 'b'}
+
+    """
+
+    def __init__(
+        self,
+        model: Model,
+        make_explainer: collections.abc.Callable[[Model], ImportanceExplainer],
+    ) -> None:
+        _check_model(model)
+        self.model = model
+        self.make_explainer = make_explainer
+        self.explainers: dict[Hashable, ImportanceExplainer] = {}
+        self._stand_in = _stand_in(model)
+
+    def learn_one(self, x: dict, y: dict) -> None:
+        """Update the explainers with an instance of the stream.
+
+        Call this before the model learns from the instance, so that the instance is new to the
+        model. Only the outputs in `y` are updated.
+
+        Parameters
+        ----------
+        x
+            A dictionary of features.
+        y
+            A dictionary with the target of each output.
+
+        """
+        for output, y_output in y.items():
+            if output not in self.explainers:
+                explainer = self.make_explainer(_Output(self.model, output, self._stand_in))
+                if not isinstance(explainer, ImportanceExplainer):
+                    raise TypeError(
+                        "make_explainer must give an ImportanceExplainer, got "
+                        f"{type(explainer).__name__}"
+                    )
+                self.explainers[output] = explainer
+            self.explainers[output].learn_one(x, y_output)
+
+    @property
+    def importances(self) -> dict[Hashable, dict[Feature, float]]:
+        """The current importance of each feature, for each output seen so far."""
+        return {output: explainer.importances for output, explainer in self.explainers.items()}

limno/storage.py

@@ -0,0 +1,88 @@
+"""Storages, which keep some of the past instances of a stream using a fixed amount of memory."""
+
+from __future__ import annotations
+
+import random
+
+from limno.base import Storage
+
+__all__ = [
+    "GeometricReservoir",
+    "UniformReservoir",
+]
+
+
+class _Reservoir(Storage):
+    def __init__(self, size: int = 100, seed: int | None = None) -> None:
+        if size < 1:
+            raise ValueError(f"size must be at least 1, got {size}")
+        super().__init__()
+        self.size = size
+        self.seed = seed
+        self._rng = random.Random(seed)
+
+
+class UniformReservoir(_Reservoir):
+    """Keep a sample in which every past instance is equally likely to be found.
+
+    This suits a stream that does not change, since old and recent instances count the same.
+
+    Parameters
+    ----------
+    size
+        The number of instances to keep.
+    seed
+        Random seed.
+
+    Examples
+    --------
+    >>> storage = UniformReservoir(size=3, seed=42)
+    >>> for i in range(100):
+    ...     storage.update({"a": i})
+    >>> len(storage)
+    3
+
+    """
+
+    def __init__(self, size: int = 100, seed: int | None = None) -> None:
+        super().__init__(size, seed)
+        self._n_seen = 0
+
+    def update(self, x: dict) -> None:
+        self._n_seen += 1
+        if len(self.instances) < self.size:
+            self.instances.append(dict(x))
+            return
+        i = self._rng.randrange(self._n_seen)
+        if i < self.size:
+            self.instances[i] = dict(x)
+
+
+class GeometricReservoir(_Reservoir):
+    """Keep a sample that favours recent instances, which suits a stream that changes.
+
+    Once full, each new instance replaces a random one. So an instance is kept for about `size`
+    steps, and the chance that it is still kept falls by `1 - 1 / size` at each step.
+
+    Parameters
+    ----------
+    size
+        The number of instances to keep.
+    seed
+        Random seed.
+
+    Examples
+    --------
+    >>> storage = GeometricReservoir(size=3, seed=42)
+    >>> for i in range(100):
+    ...     storage.update({"a": i})
+    >>> len(storage)
+    3
+
+    """
+
+    def update(self, x: dict) -> None:
+        if len(self.instances) < self.size:
+            self.instances.append(dict(x))
+        else:
+            self.instances[self._rng.randrange(self.size)] = dict(x)

limno/tracker.py

@@ -0,0 +1,77 @@
+"""Trackers, which keep a running statistic of a series of numbers.
+
+Statistics from `river.stats` can be used as trackers too.
+
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "EWMean",
+    "Mean",
+]
+
+
+class Mean:
+    """The mean of all the values so far, which suits a stream that does not change.
+
+    Examples
+    --------
+    >>> tracker = Mean()
+    >>> for value in [1.0, 2.0, 6.0]:
+    ...     tracker.update(value)
+    >>> tracker.get()
+    3.0
+
+    """
+
+    def __init__(self) -> None:
+        self._mean = 0.0
+        self._n = 0
+
+    def update(self, x: float) -> None:
+        self._n += 1
+        self._mean += (x - self._mean) / self._n
+
+    def get(self) -> float:
+        return self._mean
+
+
+class EWMean:
+    """An exponentially weighted mean, which favours recent values and so follows changes.
+
+    The weights are normalized. So it does not start from zero or from the first value: at the
+    start it is close to a plain mean, and over time it becomes the usual
+    `(1 - alpha) * mean + alpha * x`.
+
+    Parameters
+    ----------
+    alpha
+        The weight of a new value, between 0 and 1. Larger values follow changes faster, but are
+        noisier. It covers about the last `2 / alpha` values.
+
+    Examples
+    --------
+    >>> tracker = EWMean(alpha=0.5)
+    >>> tracker.update(3.0)
+    >>> tracker.get()
+    3.0
+    >>> tracker.update(6.0)
+    >>> tracker.get()
+    5.0
+
+    """
+
+    def __init__(self, alpha: float = 0.001) -> None:
+        if not 0 < alpha <= 1:
+            raise ValueError(f"alpha must be above 0 and at most 1, got {alpha}")
+        self.alpha = alpha
+        self._sum = 0.0
+        self._weight = 0.0
+
+    def update(self, x: float) -> None:
+        self._sum = (1 - self.alpha) * self._sum + self.alpha * x
+        self._weight = (1 - self.alpha) * self._weight + self.alpha
+
+    def get(self) -> float:
+        return self._sum / self._weight if self._weight else 0.0

limno-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: limno
+Version: 0.1.0
+Summary: Explainable AI for data streams and continual learning.
+Project-URL: Homepage, https://github.com/vitor-costa-garcia/limno
+Project-URL: Issues, https://github.com/vitor-costa-garcia/limno/issues
+Author-email: Vitor da Costa Garcia <vitorcostagarcia2006@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: continual-learning,data-streams,explainable-ai,incremental-learning,online-learning,river,xai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: river>=0.21; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Provides-Extra: river
+Requires-Dist: river>=0.21; extra == 'river'
+Description-Content-Type: text/markdown
+
+# limno
+
+[![CI](https://github.com/vitor-costa-garcia/limno/actions/workflows/ci.yml/badge.svg)](https://github.com/vitor-costa-garcia/limno/actions/workflows/ci.yml)
+
+**Explainable AI for data streams and continual learning.**
+
+> limno is in early development: the API may change.
+
+## What is this?
+
+A model that learns from a stream keeps changing, and so do the reasons behind its predictions.
+Most explanation tools assume a fixed model and a fixed dataset, so they do not fit this setting.
+limno provides explanations that are computed one instance at a time and that follow the model as
+it learns. Limnology is the study of inland waters, and limno looks at what goes on inside a
+stream.
+
+limno follows [River](https://riverml.xyz)'s conventions and works with River's models, pipelines,
+metrics and statistics as they are. It complements River rather than replacing it. Other libraries,
+such as [CapyMOA](https://capymoa.org), are not supported yet, but explainers do not depend on
+River, so an adapter can add them later.
+
+## Features
+
+- **Incremental permutation feature importance** (`lm.importance.PFI`), from
+  [Fumagalli et al. (2023)](https://doi.org/10.1007/s10994-023-06385-y). It shows how much a model
+  relies on each feature, as the stream goes on.
+- **Incremental SAGE** (`lm.importance.SAGE`), from
+  [Muschalik et al. (2023)](https://doi.org/10.1007/978-3-031-43418-1_26). Its values add up to the
+  drop in loss between predicting the mean and using the model.
+- **Groups of features** (`groups=`), to measure features that only make sense together as one.
+- **Models with many outputs** (`lm.multioutput.PerOutput`), to see which features each output
+  relies on.
+- **River metrics as the loss.** Whether the model is asked for labels or probabilities depends on
+  the metric, as in River.
+- **Separate pieces** that can be swapped:
+  - Storages (`lm.storage`) keep past instances: `UniformReservoir` and `GeometricReservoir`.
+  - Imputers (`lm.imputer`) replace feature values: `Marginal`.
+  - Trackers (`lm.tracker`) keep running values: `Mean`, `EWMean`, or any of `river.stats`.
+- **Features can appear and disappear** along the stream, with no list of names to give upfront. A
+  feature that stops appearing is hidden after `max_age` instances.
+- **Reproducible runs** with a `seed`.
+- **A base class for your own explainers** (`lm.base.Explainer` and
+  `lm.base.ImportanceExplainer`).
+
+## Installation
+
+```bash
+pip install "limno[river]"
+```
+
+The `river` extra installs River. limno itself has no required dependencies, so
+`pip install limno` is enough for models and metrics from elsewhere.
+
+## Quickstart
+
+```python
+from river import datasets, linear_model, metrics, preprocessing
+
+import limno as lm
+
+model = preprocessing.StandardScaler() | linear_model.LogisticRegression()
+explainer = lm.importance.PFI(model, metrics.LogLoss(), seed=42)
+
+for x, y in datasets.Phishing():
+    explainer.learn_one(x, y)  # before the model learns, so the instance is new to it
+    model.learn_one(x, y)
+
+explainer.importances
+```
+
+```
+{'empty_server_form_handler': 0.177, 'popup_window': 0.11, 'https': 0.106, ...}
+```
+
+A positive value means that the model does better with the feature, and a value close to zero that
+it does not rely on it. The explainer never updates the model.
+
+## Notebooks
+
+The [notebooks](https://github.com/vitor-costa-garcia/limno/tree/main/notebooks) show limno in use
+with River. [How incremental PFI works](https://github.com/vitor-costa-garcia/limno/blob/main/notebooks/01_how_pfi_works.ipynb)
+and [How incremental SAGE works](https://github.com/vitor-costa-garcia/limno/blob/main/notebooks/02_how_sage_works.ipynb)
+explain the methods step by step.
+
+## Contributing and feedback
+
+Ideas, use cases and criticism are welcome through
+[GitHub issues](https://github.com/vitor-costa-garcia/limno/issues).
+
+## License
+
+BSD 3-Clause. See [LICENSE](https://github.com/vitor-costa-garcia/limno/blob/main/LICENSE).

limno-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+limno/__init__.py,sha256=hOVjc-yqO6uJgTMKFaCwbP108YZ-bsp4o0yuwRePrp0,277
+limno/base.py,sha256=v-HP7ERQ4spv5nYCc-vQ2FR3EN2c-lnuQs5z_28jhYs,9062
+limno/imputer.py,sha256=m6oFBljRPGA65FRyCJFAiBzbhK0X4Jb4MbY4Fs7Zmd4,1887
+limno/multioutput.py,sha256=E6kF9gQUHPSVekuIo9P83gL6fnaQZG2XWPvfi9uliRo,5643
+limno/storage.py,sha256=2bWO1cDDFzqkAE1gnOw2579E-XYSckHbyUzuiyy5Hrw,2296
+limno/tracker.py,sha256=a3GzgpRqR6PV6DeJyDo_SgAzqo4FQdXrRG0al2oNUF4,1934
+limno/importance/__init__.py,sha256=mRwr3pP6wYITPuuEvoNWofv0RZOczzm6aZ21zWOyCgY,209
+limno/importance/_base.py,sha256=a6IGmtYQAzH5W4kxKwsDtzP95W_aDCSwn7P-1UAx1IM,3431
+limno/importance/pfi.py,sha256=pokDiW9iI7R5GP9zTybpLH8RZ0vFRycOHE0tcDcIAcg,5174
+limno/importance/sage.py,sha256=SONA59tNYgvYdfpwJsii1bTGTwYTNctDtgI_MG6m__Y,8916
+limno-0.1.0.dist-info/METADATA,sha256=71br83xVAQ2oPH2TRtaOZ0uY0-ap7nBtvh76mlDiR64,5137
+limno-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+limno-0.1.0.dist-info/licenses/LICENSE,sha256=HDjsC4F6fmIndiseOUHa1geZao3FtHRItTdztrHTpHI,1492
+limno-0.1.0.dist-info/RECORD,,

limno-0.1.0.dist-info/WHEEL

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

limno-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Vitor
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.