gameanalysis.paygame module

Module for games with potentially sparse payoff data

class gameanalysis.paygame.Game(role_names, strat_names, num_role_players, profiles, payoffs)

Bases: gameanalysis.rsgame.RsGame

Role-symmetric data game representation

This representation uses a sparse mapping from profiles to payoffs for role symmetric games. This allows it to capture arbitrary games, as well as games that are generated from data. Payoffs for specific players in a profile can be nan to indicate they are missing. The profiles will not be listed in num_complete_profiles or counted as in the game, but their data can be accessed via get_payoffs, and they will be used for calculating deviation payoffs if possible.

Parameters:

• role_names ((str,)) – The name of each role.
• strat_names (((str,),)) – The name of each strategy for each role.
• num_role_players (ndarray) – The number of players per role.
• profiles (ndarray, (num_payoffs, num_strats)) – The profiles for the game. These must be unique, and all valid for the game.
• payoffs (ndarray, (num_payoffs, num_strats)) – The payoffs for the game. This must contain zeros for profile, strategy pairs that are not played (i.e. zero). All valid payoffs for a profile can’t be nan, the profile should be omitted instead.

deviation_payoffs(mix, *, jacobian=False, ignore_incomplete=False)

Computes the expected value of deviating

More specifically, this is the expected payoff of playing each pure strategy played against all opponents playing mix.

Parameters:

• mix (ndarray) – The mix all other players are using
• jacobian (bool) – If true, the second returned argument will be the jacobian of the deviation payoffs with respect to the mixture. The first axis is the deviating strategy, the second axis is the strategy in the mix the derivative is taken with respect to. For this to be calculated correctly, the game must be complete. Thus if the game is not complete, this will be all nan.
• ignore_incomplete (bool, optional) – If True, a “best estimate” will be returned for incomplete data. This means that instead of marking a payoff where all deviations aren’t known as nan, the probability will be renormalized by the mass that is known, creating a biased estimate based of the data that is present.

get_payoffs(profiles)

Returns an array of profile payoffs

If profile is not in game, an array of nans is returned where profile has support.

max_strat_payoffs()

Returns the maximum payoff for each role

min_strat_payoffs()

Returns the minimum payoff for each role

normalize()

Return a normalized game

num_complete_profiles

num_profiles

payoff_from_json(pays, dest=None, *, verify=True)

Read a set of payoffs from json

Parameters:

• pays (json) – A description of a set of payoffs in a number of formats
• dest (ndarray, optional) – If supplied, dest will be written to instead of allocating a new array.

payoffs()

profile_from_json(prof, dest=None, *, verify=True)

Read a profile from json

A profile is an assignment from role-strategy pairs to counts. This method reads from several formats as specified in parameters.

Parameters:

• prof (json) – A description of a profile in a number of formats. The correct format will be auto detected and used. The most common are {role: {strat: count}}, {role: [(strat, count, payoff)]}, {symmetry_groups: [{role: role, strategy: strategy, count: count}]}.
• dest (ndarray, optional) – If supplied, dest will be written to instead of allocating a new array.

profile_to_assignment(prof)

profiles()

profpay_from_json(prof, dest_prof=None, dest_pays=None, *, verify=True)

Read json as a profile and a payoff

profpay_to_json(payoffs, prof)

Format a profile and payoffs as json

restrict(rest)

Remove possible strategies from consideration

to_json()

Fromat a Game as json

class gameanalysis.paygame.SampleGame(role_names, strat_names, num_role_players, profiles, sample_payoffs)

Bases: gameanalysis.paygame.Game

A Role Symmetric Game that has multiple samples per profile

This behaves the same as a normal Game object, except that it has methods for accessing several payoffs per profile. It also has a resample method which returns a Game with bootstrapped payoffs instead of mean payoffs, allowing for easy bootstrapping.

Parameters:

• role_names ((str,)) – The name of each role.
• strat_names (((str,),)) – The name of each strategy for each role.
• num_role_players (ndarray, int) – The number of players per role.
• profiles (ndarray) – The profiles for the game.
• sample_payoffs ((ndarray,)) – The sample payoffs for the game. Each element of the tuple is a set of payoff samples grouped by number of samples and parallel with profiles. The dimension of each element should be (num_payoffs, num_samples, num_strats), where num_payoffs is the number of samples for that number of observations. The number of samples for each element of the tuple must be distinct, and an element with zero samples is disallowed, it should be omitted instead. All requirements for valid payoffs also apply.

flat_payoffs()

All sample payoffs linearly concatenated together

flat_profiles()

Profiles in parallel with flat_payoffs

get_sample_payoffs(profile)

Get sample payoffs associated with a profile

This returns an array of shape (num_observations, num_role_strats). If profile has no data, num_observations will be 0.

max_strat_payoffs()

Returns the maximum payoff for each role

min_strat_payoffs()

Returns the minimum payoff for each role

normalize()

Return a normalized SampleGame

profsamplepay_from_json(prof, dest_prof=None, dest_samplepay=None)

Convert json into a profile and an observation

profsamplepay_to_json(samplepay, prof)

Convery profile and observations to prof obs output

resample(num_resamples=None, *, independent_profile=False, independent_role=False, independent_strategy=False)

Fetch a game with bootstrap sampled payoffs

Parameters:

• num_resamples (int) – The number of resamples to take for each realized payoff. By default this is equal to the number of observations for that profile, yielding proper bootstrap sampling.
• independent_profile (bool) – If true, sample each profile independently. In general, only profiles with a different number of observations will be resampled independently.
• independent_role (bool) – If true, sample each role independently. Within a profile, the payoffs for each role will be drawn independently.
• independent_strategy (bool) – IF true, sample each strategy independently. Within a profile, the payoffs for each strategy will be drawn independently. This supersceeds independent_role.

Notes

Each of the independent_ arguments will increase the time to do a resample, but may produce better results as it will remove correlations between payoffs.

restrict(rest)

Remove possible strategies from consideration

sample_payoffs()

Get the underlying sample payoffs

samplepay_from_json(prof, dest=None)

Read a set of payoff samples

Parameters:

• prof (json) – A description of a set of profiles and their payoffs. There are several formats that are acceptable, they’re all output by egta.
• dest (ndarray, options) – If supplied, dest will be written to instead of allocting a new array. This may be hard to use as you need to know how many observations are in the json.

samplepay_to_json(samplepay)

Format sample payoffs as json

to_json()

Fromat a SampleGame as json

gameanalysis.paygame.game(num_role_players, num_role_strats, profiles, payoffs)

Create a game with default names

Parameters:

• num_role_players (ndarray-like, int,) – The number of players per role.
• num_role_strats (ndarray-like, int,) – The number of strategies per role.
• profiles (ndarray-like, int) – The profiles for the game, with shape (num_profiles, num_strats).
• payoffs (ndarray-like, float) – The payoffs for the game, with shape (num_profiles, num_strats).

gameanalysis.paygame.game_copy(copy_game)

Copy structure and payoffs from an existing game

Parameters:copy_game (RsGame) – Game to copy data from. This will create a copy with the games profiles and payoffs.

gameanalysis.paygame.game_json(json)

Read a Game from json

This takes a game in any valid payoff format (i.e. output by this or by EGTA Online), and converts it into a Game. If several payoff exist, the mean is taken. This means that loading a game using this method, and loading it as a sample game produce different results, as the sample game will truncate extra payoffs for an individual profile, while this will take the minimum. Note, that there is no legitimate way to get a game with that structure, but it is possible to write the json.

gameanalysis.paygame.game_names(role_names, num_role_players, strat_names, profiles, payoffs)

Create a game with specified names

Parameters:

• role_names ([str]) – The name for each role.
• num_role_players (ndarray-like, int,) – The number of players per role.
• strat_names ([[str]]) – The name for each strategy per role.
• profiles (ndarray-like, int) – The profiles for the game, with shape (num_profiles, num_strats).
• payoffs (ndarray-like, float) – The payoffs for the game, with shape (num_profiles, num_strats).

gameanalysis.paygame.game_replace(copy_game, profiles, payoffs)

Copy structure from an existing game with new data

Parameters:

• copy_game (Game) – Game to copy structure out of. Structure includes role names, strategy names, and the number of players.
• profiles (ndarray-like, int) – The profiles for the game, with shape (num_profiles, num_strats).
• payoffs (ndarray-like, float) – The payoffs for the game, with shape (num_profiles, num_strats).

gameanalysis.paygame.samplegame(num_role_players, num_role_strats, profiles, sample_payoffs)

Create a SampleGame with default names

Parameters:

• num_role_players (ndarray-like, int) – The number of players per role.
• num_role_strats (ndarray-like, int) – The number of strategies per role.
• profiles (ndarray-like, int) – The profiles for the game, with shape (num_profiles, num_strats).
• sample_payoffs ([ndarray-like, float]) – The sample payoffs for the game.

gameanalysis.paygame.samplegame_copy(copy_game)

Copy a SampleGame from another game

If game defined sample_payoffs, this will be created with those, otherwise it will create a game with one sample per payoff.

Parameters:copy_game (RsGame) – Game to copy data from.

gameanalysis.paygame.samplegame_flat(num_role_players, num_role_strats, profiles, payoffs)

Create a SampleGame with default names and flat profiles

Parameters:

• num_role_players (ndarray-like, int) – The number of players per role.
• num_role_strats (ndarray-like, int) – The number of strategies per role.
• profiles (ndarray-like, int) – The profiles for the game, potentially with duplicates, with shape (num_sample_profiles, num_strats).
• payoffs (ndarray-like, float) – The sample payoffs for the game, in parallel with the profiles they’re samples from, with shape (num_sample_profiles, num_strats).

gameanalysis.paygame.samplegame_json(json)

Read a SampleGame from json

This will read any valid payoff game as a sample game. Invalid games will produce an empty sample game.

gameanalysis.paygame.samplegame_names(role_names, num_role_players, strat_names, profiles, sample_payoffs)

Create a SampleGame with specified names

Parameters:

• role_names ([str]) – The name of each role.
• num_role_players (ndarray) – The number of players for each role.
• strat_names ([[str]]) – The name of each strategy.
• profiles (ndarray) – The profiles for the game.
• sample_payoffs ([ndarray]) – The sample payoffs for the game.

gameanalysis.paygame.samplegame_names_flat(role_names, num_role_players, strat_names, profiles, payoffs)

Create a SampleGame with specified names and flat payoffs

Parameters:

• role_names ([str]) – The name of each role.
• num_role_players (ndarray) – The number of players for each role.
• strat_names ([[str]]) – The name of each strategy.
• profiles (ndarray-like, int) – The profiles for the game, potentially with duplicates, (num_sample_profiles, num_strats).
• payoffs (ndarray-like, float) – The sample payoffs for the game, in parallel with the profiles they’re samples from, (num_sample_profiles, num_strats).

gameanalysis.paygame.samplegame_replace(copy_game, profiles, sample_payoffs)

Replace sample payoff data for an existing game

Parameters:

• copy_game (BaseGame, optional) – Game to copy information out of.
• profiles (ndarray-like, int) – The profiles for the game, with shape (num_profiles, num_strats).
• sample_payoffs ([ndarray-like, float]) – The sample payoffs for the game.

gameanalysis.paygame.samplegame_replace_flat(copy_game, profiles, payoffs)

Replace sample payoff data for an existing game

Parameters:

• copy_game (BaseGame, optional) – Game to copy information out of.
• profiles (ndarray-like, int) – The profiles for the game, potentially with duplicates, with shape (num_sample_profiles, num_strats).
• payoffs (ndarray-like, float) – The sample payoffs for the game, in parallel with the profiles they’re samples from, with shape (num_sample_profiles, num_strats).