mosg {HyRiM}R Documentation

Construction and handling of multi-objective security games

Description

this function takes a list of loss distributions construced using lossDistribution, along with a specification of the game's shape (number of strategies for both players and number of goals for the first player), and returns an object suitable for analysis by mgss to compute a multi-goal security strategy.

Usage

mosg( n,
      m,
      goals,
      losses,
      byrow = TRUE,
      goalDescriptions = NULL,
      defensesDescr = NULL,
      attacksDescr = NULL)

## S3 method for class 'mosg'
print(x, ...)

## S3 method for class 'mosg'
plot(x,
     goal = 1,
     points = 100,
     cutoff = NULL,
     largeGame = FALSE,
     subPlotWidth = 2,
     subPlotHeight = 2,
     cleanUp = TRUE, ...)

# construct a loss distribution by playing a given strategy in the game G
## S3 method for class 'mosg'
lossDistribution(G, player1Strat, player2Strat, points = 512, goal = 1)

Arguments

n

number of defense strategies (cardinality of the action space for player 1)

m

number of attack stratgies (cardinality of the action space for player 2)

goals

number of goals for player 1 (must be \geq 1)

losses

a list with n*m*goals entries, which specifies a total of goals game matrices, each with shape n-by-m. The way in which the game matrices are filled from this list is controlled by the parameter byrow. Note that in every case, it is assumed that one matrix is specified after the other in the list.

Furthermore, the function assumes all loss distributions having a common support. This is only explicitly verified for discrete distributions (with errors reported), but implicitly assumed to hold for continuous distributions without further checks.

Typically, a game will be constructed from a list of loss distributions obtained by invocations of lossDistribution.

Games can be defined with real-valued (scalar) payoffs if a list of numbers is provided instead. Internally, the function converts these numbers into Bernoulli distributions; a scalar payoff a is converted into a Bernoulli random variable X having \Pr(X=a)=p\propto a. This conversion is equivalent to an invocation of lossDistribution with the parameters dat=c(1-p, p), discrete=TRUE, dataType="pdf", smoothing="none", bw = 1 and supp=c(1,2).

If the list of losses comes as a list of vectors, mosg will construct a game assuming a lexicographic order on the loss vectors (with the order being determined from left to right along the coordinates). To this end, mosg checks for all loss vectors to have the same length (otherwise, an error is reported). Negative and zero values in the loss vector are allowed.

byrow

by default (TRUE), the game matrices are filled row-by-row from list losses. If set to FALSE, then the game matrices are filled column-by-column.

goalDescriptions

if specified, this can be any vector (e.g., textual descriptions) for the goals. Defaults to 1, 2, 3, ... if missing. The length must be equal to goals.

defensesDescr

if specified, this can be any vector (e.g., textual descriptions) for the defense strategies. Defaults to 1, 2, 3, ... if missing. The length must be equal to n.

attacksDescr

if specified, this can be any vector (e.g., textual descriptions) for the attack strategies. Defaults to 1, 2, 3, ... if missing. The length must be equal to m.

for the functions print, summary and plot

x

a game, object of class "mosg", as constructed by the function mosg

The function plot additionally takes the following parameters:

goal

an integer referring to the goal of interest (for plotting or to construct a loss distribution for). Defaults to the first goal if omitted.

points

The number of points at which the density is evaluated (for continuous losses); this parameter is ignored for categorical losses.

cutoff

the cutoff point at which all densities shall be truncated before plotting (note that the mass functions are rescaled towards unit mass).

The plot function overrides the following settings internally (so supplying these as parameters will raise an error): xlab, ylab, main, type, names.arg and font.main (applying differently for bar and line plots)

largeGame

if the plot exits with the error "figure margins too large", one can set this parameter to TRUE, causing plot to write to a temporary SVG file (scalable vector graphics), to avoid the figure space issue and hence the error. The price is a (potentially much) slower plotting, since the system creates the file, and loads it afterwards from the harddisk (cleaning up the file after displaying it). The size of the plot is controllable by setting the parameters subPlotWidth and subPlotHeight, see below.

subPlotWidth

the width in inches for each payoff distribution in the game matrix. This parameter is ignored when largeGame is set to FALSE (the default).

subPlotHeight

the height in inches for each payoff distribution in the game matrix. This parameter is ignored when largeGame is set to FALSE (the default).

cleanUp

If the graph is to be used in other programs, one can supply cleanUp = FALSE to retain the temporary SVG file for subsequent use and prints a message where to find the file. By default, the temporary file gets deleted.

The function lossDistribution.mosg can be used to play any (given) strategies for player 1 and player 2, and compute the resulting loss from the game.

G

a game constructed by mosg to deliver the loss distribution through its game matrices.

player1Strat

a discrete distribution over the action space for the defending player 1 in the game G

player2Strat

a discrete distribution over the action space for the attacking player 2 in the game G

...

further arguments passed to or from other methods

Details

Upon input, the function does some consistency checks, such as testing the length of the parameter losses to be equal to n*m*goals. The loss distributions are checked for mutual consistency in terms of all being continuous or all being discrete (a mix is not allowed), and all being not mixed distributions (that is, the output distribution of a previous call to mgss cannot be used as input to this function).

The functions print.mosg gives a brief overview of the game, listing only the shape and strategies for both players. For detailed information, use summary on a specific loss distribution in the list for the game (field losses).

For plotting games, plot.mosg constructs an (n x m)-matrix of loss distributions with rows and columns in the grid being labeled by the values in defensesDescr and attacksDescr. The plot heading is the name for the specified goal. The function makes no changes to the plot parameters, so fine tuning can be done by changing the settings using the par function.

The function lossDistribution.mosg can be used to compute the distribution x^T*A*y, for the payoff distribution matrix A, and mixed strategies x (player1strat) and y (player2strat) in the game. The computation is by a pointwise addition of loss distributions, with the number of points being specifiable by the parameter points, which defaults to 512.

Value

The function returns an object of class mosg, usable with the function mgss to determine a security strategy (i.e., a lexicographic Nash equilibrium assuming a zero-sum one-against-all competition). The fields returned in the mosg object are filled with the input values supplied. In detail, the fields are:

nDefenses

the value of the parameter n

nAttacks

the value of the parameter m

dim

the value of the parameter goals

attacksDescriptions, defensesDescriptions, goalDescriptions

if supplied, then these are filled with the values of goalDescr, defensesDescr and attacksDescr; otherwise, they contain the default values described above.

maximumLoss

the maximal loss taken over all specified loss distributions

loc

a locus-function for accessing the list losses using a triple notation (goal,i,j), where goal addresses the game matrix and i,j are the row and column indices (starting from 1 as the smallest index). This function is used internally (only).

Warning

Games constructed with real-valued payoffs or payoff vectors over the reals are allowed with negative or zero values in the list of losses. In that case, embeds the loss values or vector into a lossDistribution object after shifting and scaling the values into the strictly positive range. This operation creates a strategically equivalent game, i.e., leaves the set of equilibria unchanged, yet the resulting mosg object is not useful with the lossDistribution.mosg, moment, cdf, or any other member functions for lossDistribution objects obtained from equilibria. Those have to be computed manually. Be aware that there will be no warnings issued whatsoever in that case of misuse, since the lossDistribution objects constructed to carry the real or vector-valued payoffs of the original game carry no information about the semantics of the values or vectors that they have been created from. Hence, the computation of equilibria works correctly using mosg, while any further analysis (including plots) needs to be done manually.

Note

It is important to remark that player 1 is always minimizing. To treat a maximizing player, one must reconstruct the game using regrets instead of losses, i.e., if the data for a specific loss distribution is D, then the game for a maximizing player 1 must be constructed from (max(D) - D) instead of D.

Author(s)

Stefan Rass

See Also

Security strategies for a mosg object can be obtained by calling mgss. The game itself can be constructed from the output of lossDistribution.

Examples

library(compare)

## raw data (PURELY ARTIFICIAL, for demo purposes only)
# N=100 observations in each category
obs111<-c(rep(1,40),rep(3,20),rep(5,10),rep(7,20),rep(9,10));
obs112<-c(rep(1,50),rep(2,10),rep(4,10),rep(6,20),rep(8,10));
obs121<-c(rep(1,20),rep(4,30),rep(6,20),rep(8,10),rep(10,20));
obs122<-c(rep(1,40),rep(2.5,20),rep(5,20),rep(7.5,10),rep(9,10));
obs211<-c(rep(1,30),rep(2,30),rep(5,10),rep(8,10),rep(10,20));
obs212<-c(rep(1,10),rep(2,10),rep(4,20),rep(7,20),rep(10,40));
obs221<-c(rep(1,30),rep(3,30),rep(4,10),rep(7,20),rep(9,10));
obs222<-c(rep(1,10),rep(3,10),rep(5,50),rep(8,20),rep(10,10));
obs311<-c(rep(1,40),rep(2,30),rep(4,10),rep(7,10),rep(9,10));
obs312<-c(rep(1,20),rep(3,20),rep(4,20),rep(7,20),rep(10,20));
obs321<-c(rep(1,10),rep(3,40),rep(4,30),rep(7,10),rep(9,10));
obs322<-c(rep(1,10),rep(4,30),rep(5,30),rep(7,10),rep(10,20));

## compute payoff densities
f111<-lossDistribution(obs111)
f112<-lossDistribution(obs112)
f121<-lossDistribution(obs121)
f122<-lossDistribution(obs122)
f211<-lossDistribution(obs211)
f212<-lossDistribution(obs212)
f221<-lossDistribution(obs221)
f222<-lossDistribution(obs222)
f311<-lossDistribution(obs311)
f312<-lossDistribution(obs312)
f321<-lossDistribution(obs321)
f322<-lossDistribution(obs322)

payoffs<-list(f111,f112,f121, f122,f211,f212,f221,f222, f311,f312,f321,f322)
G <- mosg( n=2,
            m=2,
            payoffs,
            goals=3,
            goalDescriptions=c("g1", "g2", "g3"),
            defensesDescr = c("d1", "d2"),
            attacksDescr = c("a1", "a2"))
print(G)
summary(G)
plot(G)

# construct and solve scalar valued (classical) game;
# losses are all numbers (degenerate distributions)
# the resulting matrix game has the payoff structure:
#     [,1] [,2]
#[1,]    3    4
#[2,]    6    1
G <- mosg(n = 2, m = 2, goals = 1, losses = list(3,6,4,1), byrow=FALSE)
mgss(G)  # compute a lexicographic Nash equilibrium

[Package HyRiM version 2.0.2 Index]