Source code for dit.pid.measures.isx

"""
I^sx, Shared Exclusion Partial Information Decomposition by
Makkeh, A. & Gutknecht, A. & Wibral, M. (2021). Introducing a differentiable measure of pointwise shared information.
Phys. Rev. E 103, 032149
"""

import numpy as np

from ..pid import BasePointwisePID

__all__ = ("PID_SX",)


def _prob_union(outcomes, linear_pmf, outcome, var_sets):
    """
    Probability of the union of events where at least one var_set matches outcome.

    Parameters
    ----------
    outcomes : np.ndarray
        Object array of shape (n_outcomes, n_variables).
    linear_pmf : np.ndarray
        Linear probabilities aligned with `outcomes`.
    outcome : tuple
        The outcome whose events are matched.
    var_sets : iterable of iterables
        Variable index sets; each defines the event ``X_vs = outcome[vs]``.
    """
    mask = np.zeros(len(outcomes), dtype=bool)
    for var_set in var_sets:
        var_set = list(var_set)
        values = np.empty(len(var_set), dtype=object)
        values[:] = [outcome[i] for i in var_set]
        mask |= (outcomes[:, var_set] == values).all(axis=1)
    return linear_pmf[mask].sum()


def _pointwise_parts(dist, sources, target):
    """
    ``(plus, minus)`` dicts of i^sx+(s) = -log2 P(union of source events) and
    i^sx-(s, t) = -log2 P(union of (source, target) events) / P(t).
    """
    dist = dist.copy(base="linear") if dist.is_log() else dist
    outcomes = np.empty((len(dist.outcomes), dist.outcome_length()), dtype=object)
    outcomes[:] = [list(o) for o in dist.outcomes]
    lin_joint = np.asarray(dist.pmf, dtype=float)
    dist_target = dist.marginal(target)
    joint_sets = tuple(tuple(s) + tuple(target) for s in sources)

    plus, minus = {}, {}
    for outcome in dist.outcomes:
        p_t = dist_target[tuple(outcome[t] for t in target)]
        with np.errstate(divide="ignore", invalid="ignore"):
            plus[outcome] = -np.log2(_prob_union(outcomes, lin_joint, outcome, sources))
            minus[outcome] = -np.log2(_prob_union(outcomes, lin_joint, outcome, joint_sets) / p_t)
    return plus, minus


[docs] class PID_SX(BasePointwisePID): """ Shared Exclusion Partial Information Decomposition (I^sx) as described in: Makkeh, A. & Gutknecht, A. & Wibral, M. (2021). Introducing a differentiable measure of pointwise shared information. Phys. Rev. E 103, 032149 When constructed with ``pointwise=True``, also computes the per-outcome pointwise PID (PPID) and the informative / misinformative decomposition (i^sx+ and i^sx-). """ _name = "I_sx" @staticmethod def _pointwise_measure(dist, sources, target): """ Per joint-outcome pointwise shared information: i^sx(t : sources) = i^sx+(s) - i^sx-(s, t) Returns ------- pw : dict ``{outcome: float}`` for every joint outcome in *dist*. """ plus, minus = _pointwise_parts(dist, sources, target) return {outcome: plus[outcome] - minus[outcome] for outcome in plus} @staticmethod def _pointwise_measure_parts(dist, sources, target): """ Informative (+) and misinformative (-) components of the pointwise shared information: * i^sx+(s) = -log2 P(union of source events) * i^sx-(s,t) = -log2 P(union of (source,target) events) / P(t) Returns ------- plus_dict, minus_dict : dict, dict """ return _pointwise_parts(dist, sources, target)