.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/basics/plot_custom_games.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_basics_plot_custom_games.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_basics_plot_custom_games.py:


Defining Custom Games
=====================

This example demonstrates how to define custom cooperative games and use them
with :mod:`shapiq`. We model a simple cooking game and show how to query the
value function, precompute all coalition values, and save/load them.

.. GENERATED FROM PYTHON SOURCE LINES 9-16

.. code-block:: Python


    from __future__ import annotations

    import numpy as np

    import shapiq








.. GENERATED FROM PYTHON SOURCE LINES 17-40

Introduction to Cooperative Game Theory
----------------------------------------
Cooperative game theory deals with games in which players can form groups
(coalitions) to achieve a collective payoff. A cooperative game is defined
as a tuple :math:`(N, \\nu)` where :math:`N` is a finite set of players and
:math:`\\nu: 2^N \\to \\mathbb{R}` maps every coalition to a real value.

Defining a Custom Cooperative Game
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We consider a *cooking game* with three cooks: Alice, Bob, and Charlie.

=============================  =======
Coalition                      Quality
=============================  =======
{no cook}                      0
{Alice}                        4
{Bob}                          3
{Charlie}                      2
{Alice, Bob}                   9
{Alice, Charlie}               8
{Bob, Charlie}                 7
{Alice, Bob, Charlie}          15
=============================  =======

.. GENERATED FROM PYTHON SOURCE LINES 40-70

.. code-block:: Python



    class CookingGame(shapiq.Game):
        """A cooperative game representing the cooking game with three cooks."""

        def __init__(self) -> None:
            self.characteristic_function = {
                (): 0,
                (0,): 4,
                (1,): 3,
                (2,): 2,
                (0, 1): 9,
                (0, 2): 8,
                (1, 2): 7,
                (0, 1, 2): 15,
            }
            super().__init__(
                n_players=3,
                player_names=["Alice", "Bob", "Charlie"],
                normalization_value=self.characteristic_function[()],
            )

        def value_function(self, coalitions: np.ndarray) -> np.ndarray:
            output = [self.characteristic_function[tuple(np.where(c)[0])] for c in coalitions]
            return np.array(output)


    cooking_game = CookingGame()
    print(cooking_game)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    CookingGame(3 players, normalize=False, normalization_value=0, precomputed=False)




.. GENERATED FROM PYTHON SOURCE LINES 71-74

Querying the Value Function
---------------------------
We can query the value function with binary coalition vectors or player names.

.. GENERATED FROM PYTHON SOURCE LINES 74-84

.. code-block:: Python


    coals = np.array([[0, 0, 0], [1, 1, 0], [1, 0, 1], [0, 1, 1], [1, 1, 1]])
    print("Values:", cooking_game(coals))

    coals_named = [(), ("Alice", "Bob"), ("Alice", "Charlie"), ("Bob", "Charlie")]
    print("Named:", cooking_game(coals_named))

    print("Grand coalition value:", cooking_game.grand_coalition_value)
    print("Empty coalition value:", cooking_game.empty_coalition_value)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Values: [ 0  9  8  7 15]
    Named: [0 9 8 7]
    Grand coalition value: 15.0
    Empty coalition value: 0.0




.. GENERATED FROM PYTHON SOURCE LINES 85-88

Precomputing Game Values
------------------------
For small games we can precompute all :math:`2^n` coalition values.

.. GENERATED FROM PYTHON SOURCE LINES 88-92

.. code-block:: Python


    cooking_game.precompute()
    print("Precomputed values:", cooking_game.game_values)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Precomputed values: {(): 0.0, (0,): 4.0, (1,): 3.0, (2,): 2.0, (0, 1): 9.0, (0, 2): 8.0, (1, 2): 7.0, (0, 1, 2): 15.0}




.. GENERATED FROM PYTHON SOURCE LINES 93-96

Saving and Loading
------------------
Precomputed values can be saved and loaded from disk.

.. GENERATED FROM PYTHON SOURCE LINES 96-107

.. code-block:: Python


    import tempfile
    from pathlib import Path

    with tempfile.TemporaryDirectory() as tmpdir:
        save_path = Path(tmpdir) / "cooking_game_values.npz"
        cooking_game.save_values(save_path)

        loaded_game = shapiq.Game(n_players=3, path_to_values=save_path)
        print(loaded_game)
        print("Stored game values:", loaded_game.game_values)




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /home/docs/checkouts/readthedocs.org/user_builds/shapiq/checkouts/latest/examples/basics/plot_custom_games.py:104: RuntimeWarning: Normalization value is set to `None`. No normalization value was provided at initialization. Make sure to set the normalization value before calling the game.
      loaded_game = shapiq.Game(n_players=3, path_to_values=save_path)
    Game(3 players, normalize=False, normalization_value=0.0, precomputed=False)
    Stored game values: {}





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.004 seconds)


.. _sphx_glr_download_auto_examples_basics_plot_custom_games.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_custom_games.ipynb <plot_custom_games.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_custom_games.py <plot_custom_games.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_custom_games.zip <plot_custom_games.zip>`