pydvl.valuation.games

This module provides several predefined games and, depending on the game, the corresponding Shapley values, Least-Core values or both of them, for benchmarking purposes.

References

---

1. Castro, J., Gómez, D. and Tejada, J., 2009. Polynomial calculation of the Shapley value based on sampling. Computers & Operations Research, 36(5), pp.1726-1730. ↩

DummyGameDataset

DummyGameDataset(n_players: int, description: str | None = None)

Bases: Dataset

Dummy game dataset.

Initializes a dummy game dataset with n_players and an optional description.

This class is used internally inside the Game class.

PARAMETER	DESCRIPTION
n_players	Number of players that participate in the game. TYPE: int
description	Optional description of the dataset. TYPE: str | None DEFAULT: None

Source code in src/pydvl/valuation/games.py

def __init__(self, n_players: int, description: str | None = None) -> None:
    x = np.arange(0, n_players, 1).reshape(-1, 1)
    nil = np.zeros_like(x)
    super().__init__(
        x,
        nil.copy(),
        feature_names=["x"],
        target_names=["y"],
        description=description,
    )

indices property

indices: NDArray[int_]

Index of positions in data.x_train.

Contiguous integers from 0 to len(Dataset).

names property

names: NDArray[str_]

Names of each individual datapoint.

Used for reporting Shapley values.

n_features property

n_features: int

Returns the number of dimensions of a sample.

feature

feature(name: str) -> tuple[slice, int]

Returns a slice for the feature with the given name.

Source code in src/pydvl/valuation/dataset.py

def feature(self, name: str) -> tuple[slice, int]:
    """Returns a slice for the feature with the given name."""
    try:
        return np.index_exp[:, self.feature_names.index(name)]  # type: ignore
    except ValueError:
        raise ValueError(f"Feature {name} is not in {self.feature_names}")

data

data(
    indices: int | slice | Sequence[int] | NDArray[int_] | None = None,
) -> RawData

Given a set of indices, returns the training data that refer to those indices, as a read-only tuple-like structure.

This is used mainly by subclasses of UtilityBase to retrieve subsets of the data from indices.

PARAMETER	DESCRIPTION
indices	Optional indices that will be used to select points from the training data. If None, the entire training data will be returned. TYPE: int | slice | Sequence[int] | NDArray[int_] | None DEFAULT: None

RETURNS	DESCRIPTION
RawData	If indices is not None, the selected x and y arrays from the training data. Otherwise, the entire dataset.

Source code in src/pydvl/valuation/dataset.py

def data(
    self, indices: int | slice | Sequence[int] | NDArray[np.int_] | None = None
) -> RawData:
    """Given a set of indices, returns the training data that refer to those
    indices, as a read-only tuple-like structure.

    This is used mainly by subclasses of
    [UtilityBase][pydvl.valuation.utility.base.UtilityBase] to retrieve subsets of
    the data from indices.

    Args:
        indices: Optional indices that will be used to select points from
            the training data. If `None`, the entire training data will be
            returned.

    Returns:
        If `indices` is not `None`, the selected x and y arrays from the
            training data. Otherwise, the entire dataset.
    """
    if indices is None:
        return RawData(self._x, self._y)
    return RawData(self._x[indices], self._y[indices])

data_indices

data_indices(indices: Sequence[int] | None = None) -> NDArray[int_]

Returns a subset of indices.

This is equivalent to using Dataset.indices[logical_indices] but allows subclasses to define special behaviour, e.g. when indices in Dataset do not match the indices in the data.

For Dataset, this is a simple pass-through.

PARAMETER	DESCRIPTION
indices	A set of indices held by this object TYPE: Sequence[int] | None DEFAULT: None

RETURNS	DESCRIPTION
NDArray[int_]	The indices of the data points in the data array.

Source code in src/pydvl/valuation/dataset.py

def data_indices(self, indices: Sequence[int] | None = None) -> NDArray[np.int_]:
    """Returns a subset of indices.

    This is equivalent to using `Dataset.indices[logical_indices]` but allows
    subclasses to define special behaviour, e.g. when indices in `Dataset` do not
    match the indices in the data.

    For `Dataset`, this is a simple pass-through.

    Args:
        indices: A set of indices held by this object

    Returns:
        The indices of the data points in the data array.
    """
    if indices is None:
        return self._indices
    return self._indices[indices]

logical_indices

logical_indices(indices: Sequence[int] | None = None) -> NDArray[int_]

Returns the indices in this Dataset for the given indices in the data array.

This is equivalent to using Dataset.indices[data_indices] but allows subclasses to define special behaviour, e.g. when indices in Dataset do not match the indices in the data.

PARAMETER	DESCRIPTION
indices	A set of indices in the data array. TYPE: Sequence[int] | None DEFAULT: None

RETURNS	DESCRIPTION
NDArray[int_]	The abstract indices for the given data indices.

Source code in src/pydvl/valuation/dataset.py

def logical_indices(self, indices: Sequence[int] | None = None) -> NDArray[np.int_]:
    """Returns the indices in this `Dataset` for the given indices in the data array.

    This is equivalent to using `Dataset.indices[data_indices]` but allows
    subclasses to define special behaviour, e.g. when indices in `Dataset` do not
    match the indices in the data.

    Args:
        indices: A set of indices in the data array.

    Returns:
        The abstract indices for the given data indices.
    """
    if indices is None:
        return self._indices
    return self._indices[indices]

from_sklearn classmethod

from_sklearn(
    data: Bunch,
    train_size: int | float = 0.8,
    random_state: int | None = None,
    stratify_by_target: bool = False,
    **kwargs,
) -> tuple[Dataset, Dataset]

Constructs two Dataset objects from a sklearn.utils.Bunch, as returned by the load_* functions in scikit-learn toy datasets.

Example

>>> from pydvl.valuation.dataset import Dataset
>>> from sklearn.datasets import load_boston  # noqa
>>> train, test = Dataset.from_sklearn(load_boston())

PARAMETER	DESCRIPTION
data	scikit-learn Bunch object. The following attributes are supported: data: covariates. target: target variables (labels). feature_names (optional): the feature names. target_names (optional): the target names. DESCR (optional): a description. TYPE: Bunch
train_size	size of the training dataset. Used in train_test_split float values represent the fraction of the dataset to include in the training split and should be in (0,1). An integer value sets the absolute number of training samples. TYPE: int | float DEFAULT: 0.8

the value is automatically set to the complement of the test size. random_state: seed for train / test split stratify_by_target: If True, data is split in a stratified fashion, using the target variable as labels. Read more in scikit-learn's user guide. kwargs: Additional keyword arguments to pass to the Dataset constructor. Use this to pass e.g. is_multi_output.

RETURNS	DESCRIPTION
tuple[Dataset, Dataset]	Object with the sklearn dataset

Changed in version 0.6.0

Added kwargs to pass to the Dataset constructor.

Changed in version 0.10.0

Returns a tuple of two Dataset objects.

Source code in src/pydvl/valuation/dataset.py

@classmethod
def from_sklearn(
    cls,
    data: Bunch,
    train_size: int | float = 0.8,
    random_state: int | None = None,
    stratify_by_target: bool = False,
    **kwargs,
) -> tuple[Dataset, Dataset]:
    """Constructs two [Dataset][pydvl.valuation.dataset.Dataset] objects from a
    [sklearn.utils.Bunch][], as returned by the `load_*`
    functions in [scikit-learn toy datasets](https://scikit-learn.org/stable/datasets/toy_dataset.html).

    ??? Example
        ```pycon
        >>> from pydvl.valuation.dataset import Dataset
        >>> from sklearn.datasets import load_boston  # noqa
        >>> train, test = Dataset.from_sklearn(load_boston())
        ```

    Args:
        data: scikit-learn Bunch object. The following attributes are supported:

            - `data`: covariates.
            - `target`: target variables (labels).
            - `feature_names` (**optional**): the feature names.
            - `target_names` (**optional**): the target names.
            - `DESCR` (**optional**): a description.
        train_size: size of the training dataset. Used in `train_test_split`
            float values represent the fraction of the dataset to include in the
            training split and should be in (0,1). An integer value sets the
            absolute number of training samples.
    the value is automatically set to the complement of the test size.
        random_state: seed for train / test split
        stratify_by_target: If `True`, data is split in a stratified
            fashion, using the target variable as labels. Read more in
            [scikit-learn's user guide](https://scikit-learn.org/stable/modules/cross_validation.html#stratification).
        kwargs: Additional keyword arguments to pass to the
            [Dataset][pydvl.valuation.dataset.Dataset] constructor. Use this to pass e.g. `is_multi_output`.

    Returns:
        Object with the sklearn dataset

    !!! tip "Changed in version 0.6.0"
        Added kwargs to pass to the [Dataset][pydvl.valuation.dataset.Dataset] constructor.
    !!! tip "Changed in version 0.10.0"
        Returns a tuple of two [Dataset][pydvl.valuation.dataset.Dataset] objects.
    """
    x_train, x_test, y_train, y_test = train_test_split(
        data.data,
        data.target,
        train_size=train_size,
        random_state=random_state,
        stratify=data.target if stratify_by_target else None,
    )
    return (
        cls(
            x_train,
            y_train,
            feature_names=data.get("feature_names"),
            target_names=data.get("target_names"),
            description=data.get("DESCR"),
            **kwargs,
        ),
        cls(
            x_test,
            y_test,
            feature_names=data.get("feature_names"),
            target_names=data.get("target_names"),
            description=data.get("DESCR"),
            **kwargs,
        ),
    )

from_arrays classmethod

from_arrays(
    X: NDArray,
    y: NDArray,
    train_size: float = 0.8,
    random_state: int | None = None,
    stratify_by_target: bool = False,
    **kwargs: Any,
) -> tuple[Dataset, Dataset]

Constructs a Dataset object from X and y numpy arrays as returned by the make_* functions in sklearn generated datasets.

Example

>>> from pydvl.valuation.dataset import Dataset
>>> from sklearn.datasets import make_regression
>>> X, y = make_regression()
>>> dataset = Dataset.from_arrays(X, y)

PARAMETER	DESCRIPTION
X	numpy array of shape (n_samples, n_features) TYPE: NDArray
y	numpy array of shape (n_samples,) TYPE: NDArray
train_size	size of the training dataset. Used in train_test_split TYPE: float DEFAULT: 0.8
random_state	seed for train / test split TYPE: int | None DEFAULT: None
stratify_by_target	If True, data is split in a stratified fashion, using the y variable as labels. Read more in sklearn's user guide. TYPE: bool DEFAULT: False
kwargs	Additional keyword arguments to pass to the Dataset constructor. Use this to pass e.g. feature_names or target_names. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
tuple[Dataset, Dataset]	Object with the passed X and y arrays split across training and test sets.

New in version 0.4.0

Changed in version 0.6.0

Added kwargs to pass to the Dataset constructor.

Changed in version 0.10.0

Returns a tuple of two Dataset objects.

Source code in src/pydvl/valuation/dataset.py

@classmethod
def from_arrays(
    cls,
    X: NDArray,
    y: NDArray,
    train_size: float = 0.8,
    random_state: int | None = None,
    stratify_by_target: bool = False,
    **kwargs: Any,
) -> tuple[Dataset, Dataset]:
    """Constructs a [Dataset][pydvl.valuation.dataset.Dataset] object from X and y numpy arrays  as
    returned by the `make_*` functions in [sklearn generated datasets](https://scikit-learn.org/stable/datasets/sample_generators.html).

    ??? Example
        ```pycon
        >>> from pydvl.valuation.dataset import Dataset
        >>> from sklearn.datasets import make_regression
        >>> X, y = make_regression()
        >>> dataset = Dataset.from_arrays(X, y)
        ```

    Args:
        X: numpy array of shape (n_samples, n_features)
        y: numpy array of shape (n_samples,)
        train_size: size of the training dataset. Used in `train_test_split`
        random_state: seed for train / test split
        stratify_by_target: If `True`, data is split in a stratified fashion,
            using the y variable as labels. Read more in [sklearn's user
            guide](https://scikit-learn.org/stable/modules/cross_validation.html#stratification).
        kwargs: Additional keyword arguments to pass to the
            [Dataset][pydvl.valuation.dataset.Dataset] constructor. Use this to pass
            e.g. `feature_names` or `target_names`.

    Returns:
        Object with the passed X and y arrays split across training and test sets.

    !!! tip "New in version 0.4.0"

    !!! tip "Changed in version 0.6.0"
        Added kwargs to pass to the [Dataset][pydvl.valuation.dataset.Dataset] constructor.

    !!! tip "Changed in version 0.10.0"
        Returns a tuple of two [Dataset][pydvl.valuation.dataset.Dataset] objects.
    """
    x_train, x_test, y_train, y_test = train_test_split(
        X,
        y,
        train_size=train_size,
        random_state=random_state,
        stratify=y if stratify_by_target else None,
    )
    return cls(x_train, y_train, **kwargs), cls(x_test, y_test, **kwargs)

DummyModel

DummyModel()

Bases: SupervisedModel

Dummy model class.

A dummy supervised model used for testing purposes only.

Source code in src/pydvl/valuation/games.py

def __init__(self) -> None:
    pass

Game

Game(
    n_players: int,
    score_range: tuple[float, float] = (-inf, inf),
    description: str | None = None,
)

Bases: ABC

Base class for games

Any Game subclass has to implement the abstract _score method to assign a score to each coalition/subset and at least one of shapley_values, least_core_values, or banzhaf_values.

PARAMETER	DESCRIPTION
n_players	Number of players that participate in the game. TYPE: int
score_range	Minimum and maximum values of the _score method. TYPE: tuple[float, float] DEFAULT: (-inf, inf)
description	Optional string description of the dummy dataset that will be created. TYPE: str | None DEFAULT: None

ATTRIBUTE	DESCRIPTION
n_players	Number of players that participate in the game.
data	Dummy dataset object.
u	Utility object with a dummy model and dataset.

Source code in src/pydvl/valuation/games.py

def __init__(
    self,
    n_players: int,
    score_range: tuple[float, float] = (-np.inf, np.inf),
    description: str | None = None,
):
    self.n_players = n_players
    self.data = DummyGameDataset(self.n_players, description)
    self.u = DummyGameUtility(score=self._score, score_range=score_range)

SymmetricVotingGame

SymmetricVotingGame(n_players: int)

Bases: Game

Toy game that is used for testing and demonstration purposes.

A symmetric voting game defined in (Castro et al., 2009)¹ Section 4.1

For this game the utility of a coalition is 1 if its cardinality is greater than num_samples/2, or 0 otherwise.

\[{ v(S) = \left\{\begin{array}{ll} 1, & \text{ if} \quad \mid S \mid > \frac{N}{2} \\ 0, & \text{ otherwise} \end{array}\right. }\]

PARAMETER	DESCRIPTION
n_players	Number of players that participate in the game. TYPE: int

Source code in src/pydvl/valuation/games.py

def __init__(self, n_players: int) -> None:
    if n_players % 2 != 0:
        raise ValueError("n_players must be an even number.")
    description = "Dummy data for the symmetric voting game in Castro et al. 2009"
    super().__init__(
        n_players,
        score_range=(0, 1),
        description=description,
    )

AsymmetricVotingGame

AsymmetricVotingGame(n_players: int = 51)

Bases: Game

Toy game that is used for testing and demonstration purposes.

An asymmetric voting game defined in (Castro et al., 2009)¹ Section 4.2.

For this game the player set is \(N = \{1,\dots,51\}\) and the utility of a coalition is given by:

\[{ v(S) = \left\{\begin{array}{ll} 1, & \text{ if} \quad \sum\limits_{i \in S} w_i > \sum\limits_{j \in N}\frac{w_j}{2} \\ 0, & \text{ otherwise} \end{array}\right. }\]

where \(w = [w_1,\dots, w_{51}]\) is a list of weights associated with each player.

PARAMETER	DESCRIPTION
n_players	Number of players that participate in the game. TYPE: int DEFAULT: 51

Source code in src/pydvl/valuation/games.py

def __init__(self, n_players: int = 51) -> None:
    if n_players != 51:
        raise ValueError(
            f"{self.__class__.__name__} only supports n_players=51 but got {n_players=}."
        )
    description = "Dummy data for the asymmetric voting game in Castro et al. 2009"
    super().__init__(
        n_players,
        score_range=(0, 1),
        description=description,
    )

    ranges = [
        range(0, 1),
        range(1, 2),
        range(2, 3),
        range(3, 5),
        range(5, 6),
        range(6, 7),
        range(7, 9),
        range(9, 10),
        range(10, 12),
        range(12, 15),
        range(15, 16),
        range(16, 20),
        range(20, 24),
        range(24, 26),
        range(26, 30),
        range(30, 34),
        range(34, 35),
        range(35, 44),
        range(44, 51),
    ]

    ranges_weights = [
        45,
        41,
        27,
        26,
        25,
        21,
        17,
        14,
        13,
        12,
        11,
        10,
        9,
        8,
        7,
        6,
        5,
        4,
        3,
    ]
    ranges_values = [
        "0.08831",
        "0.07973",
        "0.05096",
        "0.04898",
        "0.047",
        "0.03917",
        "0.03147",
        "0.02577",
        "0.02388",
        "0.022",
        "0.02013",
        "0.01827",
        "0.01641",
        "0.01456",
        "0.01272",
        "0.01088",
        "0.009053",
        "0.00723",
        "0.005412",
    ]

    self.weight_table = np.zeros(self.n_players)
    exact_values = np.zeros(self.n_players)
    for r, w, v in zip(ranges, ranges_weights, ranges_values):
        self.weight_table[r] = w
        exact_values[r] = v

    self.exact_values = exact_values
    self.threshold = np.sum(self.weight_table) / 2

ShoesGame

ShoesGame(left: int, right: int)

Bases: Game

Toy game that is used for testing and demonstration purposes.

A shoes game defined in (Castro et al., 2009)¹.

In this game, some players have a left shoe and others a right shoe.

The payoff (utility) of a coalition \(S\) is:

\[{ U(S) = \min( \mid S \cap L \mid, \mid S \cap R \mid ) }\]

Where \(L\), respectively \(R\), is the set of players with left shoes, respectively right shoes. This means that the marginal contribution of a player with a left shoe to a coalition \(S\) is 1 if the number of players with a left shoe in \(S\) is strictly less than the number of players with a right shoe in \(S\), and 0 otherwise. Let player \(i\) have a left shoe, then:

\[{ U(S_{+i}) - U(S) = \left\{ \begin{array}{ll} 1, & \text{ if} \mid S \cap L \mid < \mid S \cap R \mid \\ 0, & \text{ otherwise} \end{array} \right. }\]

The situation is analogous for players with a right shoe. In order to compute the Shapley or Banzhaf value for a player \(i\) with a left shoe, we need then the number of subsets \(S\) of \(D_{-i}\) such that \(\mid S \cap L \mid < \mid S \cap R \mid\). This number is given by the sum:

\[\sum^{| L |}_{i = 0} \sum_{j > i}^{| R |} \binom{| L |}{i} \binom{| R |}{j}.\]

PARAMETER	DESCRIPTION
left	Number of players with a left shoe. TYPE: int
right	Number of players with a right shoe. TYPE: int

Source code in src/pydvl/valuation/games.py

def __init__(self, left: int, right: int) -> None:
    self.left = left
    self.right = right
    n_players = self.left + self.right
    description = "Dummy data for the shoe game in Castro et al. 2009"
    max_score = n_players // 2
    super().__init__(n_players, score_range=(0, max_score), description=description)

shapley_values cached

shapley_values() -> ValuationResult

We use the fact that the marginal utility of a coalition S of size k is 1 if |S ∩ L| < |S ∩ R| and 0 otherwise, and compute Shapley values with the formula that iterates over subset sizes.

The solution for left or right shoes is symmetrical

Source code in src/pydvl/valuation/games.py

@lru_cache
def shapley_values(self) -> ValuationResult:
    """
    We use the fact that the marginal utility of a coalition S of size k is 1 if
    |S ∩ L| < |S ∩ R| and 0 otherwise, and compute Shapley values with the formula
    that iterates over subset sizes.

    The solution for left or right shoes is symmetrical
    """
    left_value = 0.0
    right_value = 0.0
    m = self.n_players - 1
    for k in range(m + 1):
        left_value += (
            1 / math.comb(m, k) * self.n_subsets_left(self.left - 1, self.right, k)
        )
        right_value += (
            1 / math.comb(m, k) * self.n_subsets_right(self.left, self.right - 1, k)
        )
    left_value /= self.n_players
    right_value /= self.n_players
    exact_values = np.array([left_value] * self.left + [right_value] * self.right)
    return ValuationResult(
        algorithm="exact_shapley",
        status=Status.Converged,
        indices=self.data.indices,
        values=exact_values,
        variances=np.zeros_like(self.data.data().x),
        counts=np.zeros_like(self.data.data().x),
    )

banzhaf_values cached

banzhaf_values() -> ValuationResult

We use the fact that the marginal utility of a coalition S is 1 if |S ∩ L| < |S ∩ R| and 0 otherwise, and simply count those sets.

The solution for left or right shoes is symmetrical.

Source code in src/pydvl/valuation/games.py

@lru_cache
def banzhaf_values(self) -> ValuationResult:
    """
    We use the fact that the marginal utility of a coalition S is 1 if
    |S ∩ L| < |S ∩ R| and 0 otherwise, and simply count those sets.

    The solution for left or right shoes is symmetrical.
    """
    m = self.n_players - 1
    left_value = self.n_subsets_left(self.left - 1, self.right) / 2**m
    right_value = self.n_subsets_right(self.left, self.right - 1) / 2**m

    exact_values = np.array([left_value] * self.left + [right_value] * self.right)
    return ValuationResult(
        algorithm="exact_banzhaf",
        status=Status.Converged,
        indices=self.data.indices,
        values=exact_values,
        variances=np.zeros_like(self.data.data().x),
        counts=np.zeros_like(self.data.data().x),
    )

AirportGame

AirportGame(n_players: int = 100)

Bases: Game

Toy game that is used for testing and demonstration purposes.

An airport game defined in (Castro et al., 2009)¹ Section 4.3

PARAMETER	DESCRIPTION
n_players	Number of players that participate in the game. TYPE: int DEFAULT: 100

Source code in src/pydvl/valuation/games.py

def __init__(self, n_players: int = 100) -> None:
    if n_players != 100:
        raise ValueError(
            f"{self.__class__.__name__} only supports n_players=100 but got {n_players=}."
        )
    description = "A dummy dataset for the airport game in Castro et al. 2009"
    super().__init__(n_players, score_range=(0, 100), description=description)
    ranges = [
        range(0, 8),
        range(8, 20),
        range(20, 26),
        range(26, 40),
        range(40, 48),
        range(48, 57),
        range(57, 70),
        range(70, 80),
        range(80, 90),
        range(90, 100),
    ]
    exact = [
        0.01,
        0.020869565,
        0.033369565,
        0.046883079,
        0.063549745,
        0.082780515,
        0.106036329,
        0.139369662,
        0.189369662,
        0.289369662,
    ]
    c = list(range(1, 10))
    score_table = np.zeros(100)
    exact_values = np.zeros(100)

    for r, v in zip(ranges, exact):
        score_table[r] = c
        exact_values[r] = v

    self.exact_values = exact_values
    self.score_table = score_table

MinimumSpanningTreeGame

MinimumSpanningTreeGame(n_players: int = 100)

Bases: Game

Toy game that is used for testing and demonstration purposes.

A minimum spanning tree game defined in (Castro et al., 2009)¹.

Let \(G = (N \cup \{0\},E)\) be a valued graph where \(N = \{1,\dots,100\}\), and the cost associated to an edge \((i, j)\) is:

\[{ c_{ij} = \left\{\begin{array}{lll} 1, & \text{ if} & i = j + 1 \text{ or } i = j - 1 \\ & & \text{ or } (i = 1 \text{ and } j = 100) \text{ or } (i = 100 \text{ and } j = 1) \\ 101, & \text{ if} & i = 0 \text{ or } j = 0 \\ \infty, & \text{ otherwise} \end{array}\right. }\]

A minimum spanning tree game \((N, c)\) is a cost game, where for a given coalition \(S \subset N\), \(v(S)\) is the sum of the edge cost of the minimum spanning tree, i.e. \(v(S)\) = Minimum Spanning Tree of the graph \(G|_{S\cup\{0\}}\), which is the partial graph restricted to the players \(S\) and the source node \(0\).

PARAMETER	DESCRIPTION
n_players	Number of players that participate in the game. TYPE: int DEFAULT: 100

Source code in src/pydvl/valuation/games.py

def __init__(self, n_players: int = 100) -> None:
    if n_players != 100:
        raise ValueError(
            f"{self.__class__.__name__} only supports n_players=100 but got {n_players=}."
        )
    description = (
        "A dummy dataset for the minimum spanning tree game in Castro et al. 2009"
    )
    super().__init__(n_players, score_range=(0, np.inf), description=description)

    graph = np.zeros(shape=(self.n_players, self.n_players))

    for i in range(self.n_players):
        for j in range(self.n_players):
            if (
                i == j + 1
                or i == j - 1
                or (i == 1 and j == self.n_players - 1)
                or (i == self.n_players - 1 and j == 1)
            ):
                graph[i, j] = 1
            elif i == 0 or j == 0:
                graph[i, j] = 0
            else:
                graph[i, j] = np.inf
    assert np.all(graph == graph.T)

    self.graph = graph

MinerGame

MinerGame(n_players: int)

Bases: Game

Toy game that is used for testing and demonstration purposes.

Consider a group of n miners, who have discovered large bars of gold.

If two miners can carry one piece of gold, then the payoff of a coalition \(S\) is:

\[{ v(S) = \left\{\begin{array}{lll} \mid S \mid / 2, & \text{ if} & \mid S \mid \text{ is even} \\ ( \mid S \mid - 1)/2, & \text{ otherwise} \end{array}\right. }\]

If there are more than two miners and there is an even number of miners, then the core consists of the single payoff where each miner gets 1/2.

If there is an odd number of miners, then the core is empty.

Taken from Wikipedia

PARAMETER	DESCRIPTION
n_players	Number of miners that participate in the game. TYPE: int

Source code in src/pydvl/valuation/games.py

def __init__(self, n_players: int) -> None:
    if n_players <= 2:
        raise ValueError(f"n_players, {n_players}, should be > 2")
    description = "Dummy data for Miner Game taken from https://en.wikipedia.org/wiki/Core_(game_theory)"
    super().__init__(
        n_players,
        score_range=(0, n_players // 2),
        description=description,
    )