Skip to content

Games

The games module contains all the game-theoretic explanation games of HyperSHAP.

AblationGame

Bases: AbstractHPIGame

The ablation game generates local explanations for hyperparameter configurations.

It does so by evaluating all potential ablation paths, switching from a baseline configuration to an optimized configuration value by value. It leverages a surrogate model to estimate performance based on blended configurations.

Source code in src/hypershap/games/ablation.py 
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
class AblationGame(AbstractHPIGame):
    """The ablation game generates local explanations for hyperparameter configurations.

    It does so by evaluating all potential ablation paths, switching from a baseline configuration
    to an optimized configuration value by value. It leverages a surrogate model to estimate
    performance based on blended configurations.
    """

    def __init__(
        self,
        explanation_task: AblationExplanationTask,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize an AblationGame.

        Args:
        explanation_task (AblationExplanationTask): An instance of `AblationExplanationTask`
            providing access to the baseline configuration, configuration of interest,
            and the surrogate model for evaluation.
        n_workers (int | None): The number of worker threads to use for parallel
            evaluation of coalitions. Defaults to None, which disables parallelization.
            Using more workers can significantly speed up the computation of Shapley values.
            The maximum number of workers is capped by the number of coalitions.
        verbose (bool | None): A boolean indicating whether to print verbose messages
            during computation. Defaults to None. When set to True, the method prints
            debugging information and progress updates.

        """
        super().__init__(explanation_task, n_workers=n_workers, verbose=verbose)

    def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
        """Evaluate a single coalition (combination of baseline and optimized hyperparameters).

        This method blends the baseline and optimized configurations based on the provided coalition,
        then uses the surrogate model to estimate the performance of the blended configuration.

        Args:
            coalition (np.ndarray): A Boolean array indicating which hyperparameters should be taken from the
                baseline configuration (False) and which from the configuration of interest (True).

        Returns:
            float: The performance score of the blended configuration as estimated by the surrogate model.

        """
        baseline_cfg = self._get_explanation_task().baseline_config.get_array()
        cfg_of_interest = self._get_explanation_task().config_of_interest.get_array()
        blend = np.where(coalition == 0, baseline_cfg, cfg_of_interest)

        res = self._get_explanation_task().get_single_surrogate_model().evaluate(blend)

        # validate that we do not get a list of floats by accident
        if isinstance(res, list):  # pragma: no cover
            raise TypeError  # pragma: no cover

        return res

    def _get_explanation_task(self) -> AblationExplanationTask:
        """Retrieve the explanation task associated with this ablation game.

        This method simply returns the `explanation_task` attribute, which provides
        access to the baseline configuration, configuration of interest, and surrogate model.

        Returns:
            AblationExplanationTask: The explanation task associated with this ablation game.

        """
        if isinstance(self.explanation_task, AblationExplanationTask):
            return self.explanation_task

        raise ValueError  # pragma: no cover

__init__(explanation_task, n_workers=None, verbose=None)

Initialize an AblationGame.

explanation_task (AblationExplanationTask): An instance of AblationExplanationTask providing access to the baseline configuration, configuration of interest, and the surrogate model for evaluation. n_workers (int | None): The number of worker threads to use for parallel evaluation of coalitions. Defaults to None, which disables parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions. verbose (bool | None): A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

Source code in src/hypershap/games/ablation.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def __init__(
    self,
    explanation_task: AblationExplanationTask,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize an AblationGame.

    Args:
    explanation_task (AblationExplanationTask): An instance of `AblationExplanationTask`
        providing access to the baseline configuration, configuration of interest,
        and the surrogate model for evaluation.
    n_workers (int | None): The number of worker threads to use for parallel
        evaluation of coalitions. Defaults to None, which disables parallelization.
        Using more workers can significantly speed up the computation of Shapley values.
        The maximum number of workers is capped by the number of coalitions.
    verbose (bool | None): A boolean indicating whether to print verbose messages
        during computation. Defaults to None. When set to True, the method prints
        debugging information and progress updates.

    """
    super().__init__(explanation_task, n_workers=n_workers, verbose=verbose)

evaluate_single_coalition(coalition)

Evaluate a single coalition (combination of baseline and optimized hyperparameters).

This method blends the baseline and optimized configurations based on the provided coalition, then uses the surrogate model to estimate the performance of the blended configuration.

Parameters:

Name Type Description Default
coalition ndarray

A Boolean array indicating which hyperparameters should be taken from the baseline configuration (False) and which from the configuration of interest (True).

 required

Returns:

Name Type Description
float float

The performance score of the blended configuration as estimated by the surrogate model.
Source code in src/hypershap/games/ablation.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
    """Evaluate a single coalition (combination of baseline and optimized hyperparameters).

    This method blends the baseline and optimized configurations based on the provided coalition,
    then uses the surrogate model to estimate the performance of the blended configuration.

    Args:
        coalition (np.ndarray): A Boolean array indicating which hyperparameters should be taken from the
            baseline configuration (False) and which from the configuration of interest (True).

    Returns:
        float: The performance score of the blended configuration as estimated by the surrogate model.

    """
    baseline_cfg = self._get_explanation_task().baseline_config.get_array()
    cfg_of_interest = self._get_explanation_task().config_of_interest.get_array()
    blend = np.where(coalition == 0, baseline_cfg, cfg_of_interest)

    res = self._get_explanation_task().get_single_surrogate_model().evaluate(blend)

    # validate that we do not get a list of floats by accident
    if isinstance(res, list):  # pragma: no cover
        raise TypeError  # pragma: no cover

    return res

AbstractHPIGame

Bases: Game

Abstract base class for Hyperparameter Importance Games (HPIGames).

Represents a game-theoretic framework for analyzing the importance of hyperparameters for HPO. It leverages the shapiq library to compute Shapley values and analyze coalition behavior.

Parameters:

Name Type Description Default
explanation_task ExplanationTask

The ExplanationTask containing information about the configuration space and surrogate model.

 required
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to 1. Using more workers can significantly speed up the computation of Shapley values.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to False.

 None
Source code in src/hypershap/games/abstract.py 
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
class AbstractHPIGame(Game):
    """Abstract base class for Hyperparameter Importance Games (HPIGames).

    Represents a game-theoretic framework for analyzing the importance of
    hyperparameters for HPO. It leverages the `shapiq` library to compute
    Shapley values and analyze coalition behavior.

    Args:
        explanation_task: The `ExplanationTask` containing information about
            the configuration space and surrogate model.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to 1.  Using more workers can significantly
            speed up the computation of Shapley values.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to False.

    """

    def __init__(
        self,
        explanation_task: ExplanationTask,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize the Hyperparameter Interaction Game (HPIGame).

        Args:
            explanation_task: The `ExplanationTask` containing information about
                the configuration space and surrogate model. This task defines the
                hyperparameter search space and the model used to estimate performance.
            n_workers: The number of worker threads to use for parallel evaluation
                of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
                speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
            verbose:  A boolean indicating whether to print verbose messages during
                computation. Defaults to None.  When set to True, the method prints
                debugging information and progress updates.

        """
        self.explanation_task = explanation_task
        self.n_workers = n_workers if n_workers is not None else 1
        self.verbose = verbose if verbose is not None else False

        # determine the value of the empty coalition so that we can normalize wrt to that performance
        normalization_value = self.evaluate_single_coalition(
            np.array([False] * explanation_task.get_num_hyperparameters()),
        )

        super().__init__(
            n_players=explanation_task.get_num_hyperparameters(),
            normalize=True,
            normalization_value=normalization_value,
        )

    def _process_chunk(self, chunk: np.ndarray) -> list:
        """Process a chunk of coalitions, evaluating each coalition using the `evaluate_single_coalition` method.

        Args:
            chunk: A NumPy array representing a subset of coalitions.

        Returns:
            A list of floats, where each float is the value of a coalition
            in the input chunk.

        """
        return [self.evaluate_single_coalition(c) for c in chunk]

    def value_function(self, coalitions: np.ndarray) -> np.ndarray:
        """Calculate the value of a list of coalitions.

        This method handles both single-worker and multi-worker scenarios for efficient computation.

        Args:
            coalitions: A NumPy array representing a list of coalitions.  Each
                coalition is a Boolean array indicating which hyperparameters
                are included in that coalition.

        Returns:
            A NumPy array containing the values of the input coalitions.

        """
        if self.n_workers == 1:
            value_list = []
            for coalition in coalitions:
                value_list += [self.evaluate_single_coalition(coalition)]
        else:
            m = len(coalitions)
            num_workers = min(self.n_workers, m)
            base_size = m // num_workers
            remainder = m % num_workers

            chunk_indices: Iterable[tuple[int, int]] = []
            start = 0
            for i in range(num_workers):
                size = base_size + (1 if i < remainder else 0)
                chunk_indices.append((start, start + size))
                start += size

            chunks = [coalitions[start:end] for start, end in chunk_indices]

            with ThreadPoolExecutor(max_workers=self.n_workers) as executor:
                partial_results = list(executor.map(self._process_chunk, chunks))

            value_list = [val for sublist in partial_results for val in sublist]
        return np.array(value_list)

    @abstractmethod
    def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
        """Evaluate the value of a single coalition.

        This method *must* be implemented by subclasses.

        Args:
            coalition: A boolean array representing a coalition of hyperparameters.

        Returns:
            The value of the coalition (a float).

        """

    def get_num_hyperparameters(self) -> int:
        """Return the number of hyperparameters being considered.

        Returns:
            The number of hyperparameters (an integer).

        """
        return self.explanation_task.get_num_hyperparameters()

    def get_hyperparameter_names(self) -> list[str]:
        """Return a list of the names of the hyperparameters.

        Returns:
            A list of strings, where each string is the name of a hyperparameter.

        """
        return self.explanation_task.get_hyperparameter_names()

__init__(explanation_task, n_workers=None, verbose=None)

Initialize the Hyperparameter Interaction Game (HPIGame).

Parameters:

Name Type Description Default
explanation_task ExplanationTask

The ExplanationTask containing information about the configuration space and surrogate model. This task defines the hyperparameter search space and the model used to estimate performance.

 required
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to None meaning no parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

 None
Source code in src/hypershap/games/abstract.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def __init__(
    self,
    explanation_task: ExplanationTask,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize the Hyperparameter Interaction Game (HPIGame).

    Args:
        explanation_task: The `ExplanationTask` containing information about
            the configuration space and surrogate model. This task defines the
            hyperparameter search space and the model used to estimate performance.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
            speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to None.  When set to True, the method prints
            debugging information and progress updates.

    """
    self.explanation_task = explanation_task
    self.n_workers = n_workers if n_workers is not None else 1
    self.verbose = verbose if verbose is not None else False

    # determine the value of the empty coalition so that we can normalize wrt to that performance
    normalization_value = self.evaluate_single_coalition(
        np.array([False] * explanation_task.get_num_hyperparameters()),
    )

    super().__init__(
        n_players=explanation_task.get_num_hyperparameters(),
        normalize=True,
        normalization_value=normalization_value,
    )

evaluate_single_coalition(coalition) abstractmethod

Evaluate the value of a single coalition.

This method must be implemented by subclasses.

Parameters:

Name Type Description Default
coalition ndarray

A boolean array representing a coalition of hyperparameters.

 required

Returns:

Type Description
float

The value of the coalition (a float).
Source code in src/hypershap/games/abstract.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
@abstractmethod
def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
    """Evaluate the value of a single coalition.

    This method *must* be implemented by subclasses.

    Args:
        coalition: A boolean array representing a coalition of hyperparameters.

    Returns:
        The value of the coalition (a float).

    """

get_hyperparameter_names()

Return a list of the names of the hyperparameters.

Returns:

Type Description
list[str]

A list of strings, where each string is the name of a hyperparameter.
Source code in src/hypershap/games/abstract.py 
154
155
156
157
158
159
160
161
def get_hyperparameter_names(self) -> list[str]:
    """Return a list of the names of the hyperparameters.

    Returns:
        A list of strings, where each string is the name of a hyperparameter.

    """
    return self.explanation_task.get_hyperparameter_names()

get_num_hyperparameters()

Return the number of hyperparameters being considered.

Returns:

Type Description
int

The number of hyperparameters (an integer).
Source code in src/hypershap/games/abstract.py 
145
146
147
148
149
150
151
152
def get_num_hyperparameters(self) -> int:
    """Return the number of hyperparameters being considered.

    Returns:
        The number of hyperparameters (an integer).

    """
    return self.explanation_task.get_num_hyperparameters()

value_function(coalitions)

Calculate the value of a list of coalitions.

This method handles both single-worker and multi-worker scenarios for efficient computation.

Parameters:

Name Type Description Default
coalitions ndarray

A NumPy array representing a list of coalitions. Each coalition is a Boolean array indicating which hyperparameters are included in that coalition.

 required

Returns:

Type Description
ndarray

A NumPy array containing the values of the input coalitions.
Source code in src/hypershap/games/abstract.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def value_function(self, coalitions: np.ndarray) -> np.ndarray:
    """Calculate the value of a list of coalitions.

    This method handles both single-worker and multi-worker scenarios for efficient computation.

    Args:
        coalitions: A NumPy array representing a list of coalitions.  Each
            coalition is a Boolean array indicating which hyperparameters
            are included in that coalition.

    Returns:
        A NumPy array containing the values of the input coalitions.

    """
    if self.n_workers == 1:
        value_list = []
        for coalition in coalitions:
            value_list += [self.evaluate_single_coalition(coalition)]
    else:
        m = len(coalitions)
        num_workers = min(self.n_workers, m)
        base_size = m // num_workers
        remainder = m % num_workers

        chunk_indices: Iterable[tuple[int, int]] = []
        start = 0
        for i in range(num_workers):
            size = base_size + (1 if i < remainder else 0)
            chunk_indices.append((start, start + size))
            start += size

        chunks = [coalitions[start:end] for start, end in chunk_indices]

        with ThreadPoolExecutor(max_workers=self.n_workers) as executor:
            partial_results = list(executor.map(self._process_chunk, chunks))

        value_list = [val for sublist in partial_results for val in sublist]
    return np.array(value_list)

MistunabilityGame

Bases: SearchBasedGame

Game representing the mistunability of hyperparameters.

Source code in src/hypershap/games/tunability.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class MistunabilityGame(SearchBasedGame):
    """Game representing the mistunability of hyperparameters."""

    def __init__(
        self,
        explanation_task: MistunabilityExplanationTask,
        cs_searcher: ConfigSpaceSearcher | None = None,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize the mistunability game.

        Args:
            explanation_task: The explanation task containing the configuration
                space and surrogate model.
            cs_searcher: The configuration space searcher. If None, a
                RandomConfigSpaceSearcher is used by default.
            n_workers: The number of worker threads to use for parallel evaluation
                of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
                speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
            verbose:  A boolean indicating whether to print verbose messages during
                computation. Defaults to None.  When set to True, the method prints
                debugging information and progress updates.

        """
        # set cs searcher if not given by default to a random config space searcher.
        if cs_searcher is None:
            cs_searcher = RandomConfigSpaceSearcher(explanation_task, mode=Aggregation.MIN)
        elif cs_searcher.mode != Aggregation.MIN:  # ensure that cs_searcher is maximizing
            logger.warning("WARN: Mistunability game set mode of given ConfigSpaceSearcher to minimize.")
            cs_searcher.mode = Aggregation.MIN

        super().__init__(explanation_task, cs_searcher, n_workers=n_workers, verbose=verbose)

__init__(explanation_task, cs_searcher=None, n_workers=None, verbose=None)

Initialize the mistunability game.

Parameters:

Name Type Description Default
explanation_task MistunabilityExplanationTask

The explanation task containing the configuration space and surrogate model.

 required
cs_searcher ConfigSpaceSearcher | None

The configuration space searcher. If None, a RandomConfigSpaceSearcher is used by default.

 None
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to None meaning no parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

 None
Source code in src/hypershap/games/tunability.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def __init__(
    self,
    explanation_task: MistunabilityExplanationTask,
    cs_searcher: ConfigSpaceSearcher | None = None,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize the mistunability game.

    Args:
        explanation_task: The explanation task containing the configuration
            space and surrogate model.
        cs_searcher: The configuration space searcher. If None, a
            RandomConfigSpaceSearcher is used by default.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
            speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to None.  When set to True, the method prints
            debugging information and progress updates.

    """
    # set cs searcher if not given by default to a random config space searcher.
    if cs_searcher is None:
        cs_searcher = RandomConfigSpaceSearcher(explanation_task, mode=Aggregation.MIN)
    elif cs_searcher.mode != Aggregation.MIN:  # ensure that cs_searcher is maximizing
        logger.warning("WARN: Mistunability game set mode of given ConfigSpaceSearcher to minimize.")
        cs_searcher.mode = Aggregation.MIN

    super().__init__(explanation_task, cs_searcher, n_workers=n_workers, verbose=verbose)

MultiBaselineAblationGame

Bases: AbstractHPIGame

The multi-baseline ablation game generates local explanations for hyperparameter configurations.

It does so by considering multiple baseline configurations as starting points.

Source code in src/hypershap/games/ablation.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
class MultiBaselineAblationGame(AbstractHPIGame):
    """The multi-baseline ablation game generates local explanations for hyperparameter configurations.

    It does so by considering multiple baseline configurations as starting points.
    """

    def __init__(
        self,
        explanation_task: MultiBaselineAblationExplanationTask,
        aggregation: Aggregation = Aggregation.AVG,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize a MultiBaselineAblationGame.

        n_workers (int | None): The number of worker threads to use for parallel
            evaluation of coalitions. Defaults to None, which disables parallelization.
            Using more workers can significantly speed up the computation of Shapley values.
            The maximum number of workers is capped by the number of coalitions.
        verbose (bool | None): A boolean indicating whether to print verbose messages
            during computation. Defaults to None. When set to True, the method prints
            debugging information and progress updates.
        """
        self.aggregation = aggregation
        self.ablation_games = [
            AblationGame(
                AblationExplanationTask(
                    config_space=explanation_task.config_space,
                    surrogate_model=explanation_task.surrogate_model,
                    baseline_config=baseline_config,
                    config_of_interest=explanation_task.config_of_interest,
                ),
                n_workers=n_workers,
                verbose=verbose,
            )
            for baseline_config in explanation_task.baseline_configs
        ]
        super().__init__(explanation_task, n_workers, verbose)

    def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
        """Evaluate a single coalition (combination of baseline and optimized hyperparameters)."""
        vals = np.array([ag.evaluate_single_coalition(coalition) for ag in self.ablation_games])
        return evaluate_aggregation(self.aggregation, vals)

__init__(explanation_task, aggregation=Aggregation.AVG, n_workers=None, verbose=None)

Initialize a MultiBaselineAblationGame.

n_workers (int | None): The number of worker threads to use for parallel evaluation of coalitions. Defaults to None, which disables parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions. verbose (bool | None): A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

Source code in src/hypershap/games/ablation.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def __init__(
    self,
    explanation_task: MultiBaselineAblationExplanationTask,
    aggregation: Aggregation = Aggregation.AVG,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize a MultiBaselineAblationGame.

    n_workers (int | None): The number of worker threads to use for parallel
        evaluation of coalitions. Defaults to None, which disables parallelization.
        Using more workers can significantly speed up the computation of Shapley values.
        The maximum number of workers is capped by the number of coalitions.
    verbose (bool | None): A boolean indicating whether to print verbose messages
        during computation. Defaults to None. When set to True, the method prints
        debugging information and progress updates.
    """
    self.aggregation = aggregation
    self.ablation_games = [
        AblationGame(
            AblationExplanationTask(
                config_space=explanation_task.config_space,
                surrogate_model=explanation_task.surrogate_model,
                baseline_config=baseline_config,
                config_of_interest=explanation_task.config_of_interest,
            ),
            n_workers=n_workers,
            verbose=verbose,
        )
        for baseline_config in explanation_task.baseline_configs
    ]
    super().__init__(explanation_task, n_workers, verbose)

evaluate_single_coalition(coalition)

Evaluate a single coalition (combination of baseline and optimized hyperparameters).

Source code in src/hypershap/games/ablation.py 
146
147
148
149
def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
    """Evaluate a single coalition (combination of baseline and optimized hyperparameters)."""
    vals = np.array([ag.evaluate_single_coalition(coalition) for ag in self.ablation_games])
    return evaluate_aggregation(self.aggregation, vals)

MultiDataHPIGame

Bases: AbstractHPIGame

The multi-data game generalizes an explanation game to multiple datasets.

Source code in src/hypershap/games/multi_data.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class MultiDataHPIGame(AbstractHPIGame):
    """The multi-data game generalizes an explanation game to multiple datasets."""

    def __init__(
        self,
        explanation_task: ExplanationTask,
        base_game: AbstractHPIGame,
        aggregation: Aggregation,
    ) -> None:
        """Initialize the multi-data game wrapper.

        Args:
            explanation_task: The explanation task containing the configuration space and surrogate model.
            base_game: The base game instance.
            aggregation: The aggregation method to use.

        """
        self.aggregation = aggregation
        self.base_game = base_game

        self.sub_games = []
        for surrogate_model in explanation_task.get_surrogate_model_list():
            game_copy = copy.deepcopy(base_game)
            game_copy.explanation_task.surrogate_model = surrogate_model
            if isinstance(game_copy, SearchBasedGame):
                game_copy.cs_searcher.explanation_task.surrogate_model = surrogate_model
            if isinstance(game_copy, MultiBaselineAblationGame):
                for ag in game_copy.ablation_games:
                    ag.explanation_task.surrogate_model = surrogate_model
            self.sub_games.append(game_copy)

        super().__init__(explanation_task)

    def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
        """Evaluate the multi-data game on the coalition.

        Args:
            coalition: The coalition to evaluate.

        Returns: The value of the multi-data game on the coalition.

        """
        vals = np.array([game.evaluate_single_coalition(coalition) for game in self.sub_games])
        return evaluate_aggregation(self.aggregation, vals)

__init__(explanation_task, base_game, aggregation)

Initialize the multi-data game wrapper.

Parameters:

Name Type Description Default
explanation_task ExplanationTask

The explanation task containing the configuration space and surrogate model.

 required
base_game AbstractHPIGame

The base game instance.

 required
aggregation Aggregation

The aggregation method to use.

 required
Source code in src/hypershap/games/multi_data.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(
    self,
    explanation_task: ExplanationTask,
    base_game: AbstractHPIGame,
    aggregation: Aggregation,
) -> None:
    """Initialize the multi-data game wrapper.

    Args:
        explanation_task: The explanation task containing the configuration space and surrogate model.
        base_game: The base game instance.
        aggregation: The aggregation method to use.

    """
    self.aggregation = aggregation
    self.base_game = base_game

    self.sub_games = []
    for surrogate_model in explanation_task.get_surrogate_model_list():
        game_copy = copy.deepcopy(base_game)
        game_copy.explanation_task.surrogate_model = surrogate_model
        if isinstance(game_copy, SearchBasedGame):
            game_copy.cs_searcher.explanation_task.surrogate_model = surrogate_model
        if isinstance(game_copy, MultiBaselineAblationGame):
            for ag in game_copy.ablation_games:
                ag.explanation_task.surrogate_model = surrogate_model
        self.sub_games.append(game_copy)

    super().__init__(explanation_task)

evaluate_single_coalition(coalition)

Evaluate the multi-data game on the coalition.

Parameters:

Name Type Description Default
coalition ndarray

The coalition to evaluate.

 required

Returns: The value of the multi-data game on the coalition.

Source code in src/hypershap/games/multi_data.py 
53
54
55
56
57
58
59
60
61
62
63
def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
    """Evaluate the multi-data game on the coalition.

    Args:
        coalition: The coalition to evaluate.

    Returns: The value of the multi-data game on the coalition.

    """
    vals = np.array([game.evaluate_single_coalition(coalition) for game in self.sub_games])
    return evaluate_aggregation(self.aggregation, vals)

OptimizerBiasGame

Bases: AbstractHPIGame

An explanation game to measure bias in hyperparameter optimizers.

This class extends the AbstractHPIGame base class and is specifically designed to quantify how much an optimizer is biased toward tuning certain hyperparameters. To this end a set of diverse optimizers is used as a reference.

Attributes:

Name Type Description
explanation_task OptimizerBiasExplanationTask

The task that defines the game. This includes the configuration sapce, the surrogate model and a baseline configuration, as well as the optimizer of interest and the ensemble of diverse optimizers.

Methods:

Name Description
evaluate_single_coalition

Computes the marginal contribution of a coalition (subset of features) by comparing the optimizer of interest against an optimizer ensemble. This method is called internally during the game's main evaluation process.
Note

The game evaluates coalitions based on the difference between the outcome using the primary optimizer and the maximum outcome achieved by any optimizer in the provided ensemble.

Source code in src/hypershap/games/optimizerbias.py 
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
class OptimizerBiasGame(AbstractHPIGame):
    """An explanation game to measure bias in hyperparameter optimizers.

    This class extends the `AbstractHPIGame` base class and is specifically designed
    to quantify how much an optimizer is biased toward tuning certain hyperparameters.
    To this end a set of diverse optimizers is used as a reference.

    Attributes:
        explanation_task (OptimizerBiasExplanationTask): The task that defines the game.
            This includes the configuration sapce, the surrogate model and a baseline configuration, as well as the
            optimizer of interest and the ensemble of diverse optimizers.


    Methods:
        evaluate_single_coalition: Computes the marginal contribution of a coalition (subset of features)
            by comparing the optimizer of interest against an optimizer ensemble. This method is called internally
            during the game's main evaluation process.

    Note:
        The game evaluates coalitions based on the difference between the outcome using the primary optimizer
        and the maximum outcome achieved by any optimizer in the provided ensemble.

    """

    def __init__(
        self,
        explanation_task: OptimizerBiasExplanationTask,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize an instance of `OptimizerBiasGame`.

        Args:
            explanation_task (OptimizerBiasExplanationTask): The task that contains all necessary
                information for defining the game. This includes the configuration space, the surrogate model, the
                optimizer of interest, and the ensemble of diverse optimizers.
            n_workers: The number of worker threads to use for parallel evaluation
                of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
                speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
            verbose:  A boolean indicating whether to print verbose messages during
                computation. Defaults to None.  When set to True, the method prints
                debugging information and progress updates.

        Example:
            >>> from hypershap.task import OptimizerBiasExplanationTask
            >>> # Create an explanation task instance with specific parameters
            >>> expl_task = OptimizerBiasExplanationTask(...)
            >>> game = OptimizerBiasGame(expl_task)

        """
        super().__init__(explanation_task, n_workers=n_workers, verbose=verbose)

    def _get_explanation_task(self) -> OptimizerBiasExplanationTask:
        if isinstance(self.explanation_task, OptimizerBiasExplanationTask):
            return self.explanation_task
        raise ValueError  # pragma: no cover

    def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
        """Evaluate a single coalition by comparing against an optimizer ensemble.

        Args:
            coalition (np.ndarray): A binary array indicating which hyperparameters are included in the coalition.
                The array has shape (n_hyperparameters,) where True means hyperparameters is included and False
                 otherwise.

        Returns:
            float: The marginal contribution of the coalition. It is computed as the difference between
                the outcome when using the optimizer of interest with the given coalition, versus the best outcome
                achievable by any optimizer in the ensemble (including the one of interest).

        Note:
            This method overrides a base class abstract method and must be implemented to provide specific game logic.
            The value returned here is used for computing Shapley values or other cooperative game theory measures.

        Example:
            >>> coalition = np.array([1, 0, 1])  # Hyperparameters 0 and 2 are included
            >>> marginal_contribution = game.evaluate_single_coalition(coalition)
            >>> print(marginal_contribution)  # Outputs the difference in outcomes for this coalition.

        """
        optimizer_res = self._get_explanation_task().optimizer_of_interest.search(coalition)
        optimizer_ensemble_res = [
            optimizer.search(coalition) for optimizer in self._get_explanation_task().optimizer_ensemble
        ]
        return optimizer_res - max([*optimizer_ensemble_res, optimizer_res])

__init__(explanation_task, n_workers=None, verbose=None)

Initialize an instance of OptimizerBiasGame.

Parameters:

Name Type Description Default
explanation_task OptimizerBiasExplanationTask

The task that contains all necessary information for defining the game. This includes the configuration space, the surrogate model, the optimizer of interest, and the ensemble of diverse optimizers.

 required
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to None meaning no parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

 None
Example

from hypershap.task import OptimizerBiasExplanationTask

Create an explanation task instance with specific parameters

expl_task = OptimizerBiasExplanationTask(...) game = OptimizerBiasGame(expl_task)

Source code in src/hypershap/games/optimizerbias.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def __init__(
    self,
    explanation_task: OptimizerBiasExplanationTask,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize an instance of `OptimizerBiasGame`.

    Args:
        explanation_task (OptimizerBiasExplanationTask): The task that contains all necessary
            information for defining the game. This includes the configuration space, the surrogate model, the
            optimizer of interest, and the ensemble of diverse optimizers.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
            speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to None.  When set to True, the method prints
            debugging information and progress updates.

    Example:
        >>> from hypershap.task import OptimizerBiasExplanationTask
        >>> # Create an explanation task instance with specific parameters
        >>> expl_task = OptimizerBiasExplanationTask(...)
        >>> game = OptimizerBiasGame(expl_task)

    """
    super().__init__(explanation_task, n_workers=n_workers, verbose=verbose)

evaluate_single_coalition(coalition)

Evaluate a single coalition by comparing against an optimizer ensemble.

Parameters:

Name Type Description Default
coalition ndarray

A binary array indicating which hyperparameters are included in the coalition. The array has shape (n_hyperparameters,) where True means hyperparameters is included and False otherwise.

 required

Returns:

Name Type Description
float float

The marginal contribution of the coalition. It is computed as the difference between the outcome when using the optimizer of interest with the given coalition, versus the best outcome achievable by any optimizer in the ensemble (including the one of interest).
Note

This method overrides a base class abstract method and must be implemented to provide specific game logic. The value returned here is used for computing Shapley values or other cooperative game theory measures.

Example

coalition = np.array([1, 0, 1]) # Hyperparameters 0 and 2 are included marginal_contribution = game.evaluate_single_coalition(coalition) print(marginal_contribution) # Outputs the difference in outcomes for this coalition.

Source code in src/hypershap/games/optimizerbias.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
    """Evaluate a single coalition by comparing against an optimizer ensemble.

    Args:
        coalition (np.ndarray): A binary array indicating which hyperparameters are included in the coalition.
            The array has shape (n_hyperparameters,) where True means hyperparameters is included and False
             otherwise.

    Returns:
        float: The marginal contribution of the coalition. It is computed as the difference between
            the outcome when using the optimizer of interest with the given coalition, versus the best outcome
            achievable by any optimizer in the ensemble (including the one of interest).

    Note:
        This method overrides a base class abstract method and must be implemented to provide specific game logic.
        The value returned here is used for computing Shapley values or other cooperative game theory measures.

    Example:
        >>> coalition = np.array([1, 0, 1])  # Hyperparameters 0 and 2 are included
        >>> marginal_contribution = game.evaluate_single_coalition(coalition)
        >>> print(marginal_contribution)  # Outputs the difference in outcomes for this coalition.

    """
    optimizer_res = self._get_explanation_task().optimizer_of_interest.search(coalition)
    optimizer_ensemble_res = [
        optimizer.search(coalition) for optimizer in self._get_explanation_task().optimizer_ensemble
    ]
    return optimizer_res - max([*optimizer_ensemble_res, optimizer_res])

SearchBasedGame

Bases: AbstractHPIGame

Base class for games that rely on searching the configuration space.

Source code in src/hypershap/games/tunability.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class SearchBasedGame(AbstractHPIGame):
    """Base class for games that rely on searching the configuration space."""

    def __init__(
        self,
        explanation_task: BaselineExplanationTask,
        cs_searcher: ConfigSpaceSearcher,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize the search-based game.

        Args:
            explanation_task: The explanation task containing the configuration
                space and surrogate model.
            cs_searcher: The configuration space searcher. If None, a
                RandomConfigSpaceSearcher is used by default.
            n_workers: The number of worker threads to use for parallel evaluation
                of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
                speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
            verbose:  A boolean indicating whether to print verbose messages during
                computation. Defaults to None.  When set to True, the method prints
                debugging information and progress updates.

        """
        self.cs_searcher = cs_searcher
        super().__init__(explanation_task, n_workers=n_workers, verbose=verbose)

    def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
        """Evaluate the value of a single coalition using the configuration space searcher.

        Args:
            coalition: A boolean array indicating which hyperparameters are
                constrained by the coalition.

        Returns:
            The value of the coalition based on the search results.

        """
        return self.cs_searcher.search(coalition)

__init__(explanation_task, cs_searcher, n_workers=None, verbose=None)

Initialize the search-based game.

Parameters:

Name Type Description Default
explanation_task BaselineExplanationTask

The explanation task containing the configuration space and surrogate model.

 required
cs_searcher ConfigSpaceSearcher

The configuration space searcher. If None, a RandomConfigSpaceSearcher is used by default.

 required
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to None meaning no parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

 None
Source code in src/hypershap/games/tunability.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def __init__(
    self,
    explanation_task: BaselineExplanationTask,
    cs_searcher: ConfigSpaceSearcher,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize the search-based game.

    Args:
        explanation_task: The explanation task containing the configuration
            space and surrogate model.
        cs_searcher: The configuration space searcher. If None, a
            RandomConfigSpaceSearcher is used by default.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
            speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to None.  When set to True, the method prints
            debugging information and progress updates.

    """
    self.cs_searcher = cs_searcher
    super().__init__(explanation_task, n_workers=n_workers, verbose=verbose)

evaluate_single_coalition(coalition)

Evaluate the value of a single coalition using the configuration space searcher.

Parameters:

Name Type Description Default
coalition ndarray

A boolean array indicating which hyperparameters are constrained by the coalition.

 required

Returns:

Type Description
float

The value of the coalition based on the search results.
Source code in src/hypershap/games/tunability.py 
68
69
70
71
72
73
74
75
76
77
78
79
def evaluate_single_coalition(self, coalition: np.ndarray) -> float:
    """Evaluate the value of a single coalition using the configuration space searcher.

    Args:
        coalition: A boolean array indicating which hyperparameters are
            constrained by the coalition.

    Returns:
        The value of the coalition based on the search results.

    """
    return self.cs_searcher.search(coalition)

SensitivityGame

Bases: SearchBasedGame

Game representing the sensitivity of hyperparameters.

Source code in src/hypershap/games/tunability.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
class SensitivityGame(SearchBasedGame):
    """Game representing the sensitivity of hyperparameters."""

    def __init__(
        self,
        explanation_task: SensitivityExplanationTask,
        cs_searcher: ConfigSpaceSearcher | None = None,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize the sensitivity game.

        Args:
            explanation_task: The explanation task containing the configuration
                space and surrogate model.
            cs_searcher: The configuration space searcher. If None, a
                RandomConfigSpaceSearcher is used by default.
            n_workers: The number of worker threads to use for parallel evaluation
                of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
                speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
            verbose:  A boolean indicating whether to print verbose messages during
                computation. Defaults to None.  When set to True, the method prints
                debugging information and progress updates.

        """
        # set cs searcher if not given by default to a random config space searcher.
        if cs_searcher is None:
            cs_searcher = RandomConfigSpaceSearcher(explanation_task, mode=Aggregation.VAR)
        elif cs_searcher.mode != Aggregation.VAR:  # ensure that cs_searcher is maximizing
            logger.warning("WARN: Sensitivity game set mode of given ConfigSpaceSearcher to variance.")
            cs_searcher.mode = Aggregation.VAR

        super().__init__(explanation_task, cs_searcher, n_workers=n_workers, verbose=verbose)

__init__(explanation_task, cs_searcher=None, n_workers=None, verbose=None)

Initialize the sensitivity game.

Parameters:

Name Type Description Default
explanation_task SensitivityExplanationTask

The explanation task containing the configuration space and surrogate model.

 required
cs_searcher ConfigSpaceSearcher | None

The configuration space searcher. If None, a RandomConfigSpaceSearcher is used by default.

 None
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to None meaning no parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

 None
Source code in src/hypershap/games/tunability.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def __init__(
    self,
    explanation_task: SensitivityExplanationTask,
    cs_searcher: ConfigSpaceSearcher | None = None,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize the sensitivity game.

    Args:
        explanation_task: The explanation task containing the configuration
            space and surrogate model.
        cs_searcher: The configuration space searcher. If None, a
            RandomConfigSpaceSearcher is used by default.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
            speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to None.  When set to True, the method prints
            debugging information and progress updates.

    """
    # set cs searcher if not given by default to a random config space searcher.
    if cs_searcher is None:
        cs_searcher = RandomConfigSpaceSearcher(explanation_task, mode=Aggregation.VAR)
    elif cs_searcher.mode != Aggregation.VAR:  # ensure that cs_searcher is maximizing
        logger.warning("WARN: Sensitivity game set mode of given ConfigSpaceSearcher to variance.")
        cs_searcher.mode = Aggregation.VAR

    super().__init__(explanation_task, cs_searcher, n_workers=n_workers, verbose=verbose)

TunabilityGame

Bases: SearchBasedGame

Game representing the tunability of hyperparameters.

Source code in src/hypershap/games/tunability.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class TunabilityGame(SearchBasedGame):
    """Game representing the tunability of hyperparameters."""

    def __init__(
        self,
        explanation_task: TunabilityExplanationTask,
        cs_searcher: ConfigSpaceSearcher | None = None,
        n_workers: int | None = None,
        verbose: bool | None = None,
    ) -> None:
        """Initialize the tunability game.

        Args:
            explanation_task: The explanation task containing the configuration
                space and surrogate model.
            cs_searcher: The configuration space searcher. If None, a
                RandomConfigSpaceSearcher is used by default.
            n_workers: The number of worker threads to use for parallel evaluation
                of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
                speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
            verbose:  A boolean indicating whether to print verbose messages during
                computation. Defaults to None.  When set to True, the method prints
                debugging information and progress updates.

        """
        # set cs searcher if not given by default to a random config space searcher.
        if cs_searcher is None:
            cs_searcher = RandomConfigSpaceSearcher(explanation_task, mode=Aggregation.MAX)
        elif cs_searcher.mode != Aggregation.MAX:  # ensure that cs_searcher is maximizing
            logger.warning("WARN: Tunability game set mode of given ConfigSpaceSearcher to maximize.")
            cs_searcher.mode = Aggregation.MAX
        super().__init__(explanation_task, cs_searcher, n_workers=n_workers, verbose=verbose)

__init__(explanation_task, cs_searcher=None, n_workers=None, verbose=None)

Initialize the tunability game.

Parameters:

Name Type Description Default
explanation_task TunabilityExplanationTask

The explanation task containing the configuration space and surrogate model.

 required
cs_searcher ConfigSpaceSearcher | None

The configuration space searcher. If None, a RandomConfigSpaceSearcher is used by default.

 None
n_workers int | None

The number of worker threads to use for parallel evaluation of coalitions. Defaults to None meaning no parallelization. Using more workers can significantly speed up the computation of Shapley values. The maximum number of workers is capped by the number of coalitions.

 None
verbose bool | None

A boolean indicating whether to print verbose messages during computation. Defaults to None. When set to True, the method prints debugging information and progress updates.

 None
Source code in src/hypershap/games/tunability.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def __init__(
    self,
    explanation_task: TunabilityExplanationTask,
    cs_searcher: ConfigSpaceSearcher | None = None,
    n_workers: int | None = None,
    verbose: bool | None = None,
) -> None:
    """Initialize the tunability game.

    Args:
        explanation_task: The explanation task containing the configuration
            space and surrogate model.
        cs_searcher: The configuration space searcher. If None, a
            RandomConfigSpaceSearcher is used by default.
        n_workers: The number of worker threads to use for parallel evaluation
            of coalitions. Defaults to None meaning no parallelization.  Using more workers can significantly
            speed up the computation of Shapley values.  The maximum number of workers is capped by the number of coalitions.
        verbose:  A boolean indicating whether to print verbose messages during
            computation. Defaults to None.  When set to True, the method prints
            debugging information and progress updates.

    """
    # set cs searcher if not given by default to a random config space searcher.
    if cs_searcher is None:
        cs_searcher = RandomConfigSpaceSearcher(explanation_task, mode=Aggregation.MAX)
    elif cs_searcher.mode != Aggregation.MAX:  # ensure that cs_searcher is maximizing
        logger.warning("WARN: Tunability game set mode of given ConfigSpaceSearcher to maximize.")
        cs_searcher.mode = Aggregation.MAX
    super().__init__(explanation_task, cs_searcher, n_workers=n_workers, verbose=verbose)