| Title: | Obfuscation Game Designs |
|---|---|
| Description: | When people make decisions, they may do so using a wide variety of decision rules. The package allows users to easily create obfuscation games to test the obfuscation hypothesis. It provides an easy to use interface and multiple options designed to vary the difficulty of the game and tailor it to the user's needs. For more detail: Chorus et al., 2021, Obfuscation maximization-based decision-making: Theory, methodology and first empirical evidence, Mathematical Social Sciences, 109, 28-44, <doi:10.1016/j.mathsocsci.2020.10.002>. |
| Authors: | Erlend Dancke Sandorf [aut, cre], Caspar Chorus [aut], Sander van Cranenburgh [aut] |
| Maintainer: | Erlend Dancke Sandorf <[email protected]> |
| License: | GPL-3 |
| Version: | 0.2.2 |
| Built: | 2024-09-01 03:31:43 UTC |
| Source: | https://github.com/edsandorf/obfuscator |
The function is called when the package is loaded through library or require.
.onAttach(libname, pkgname).onAttach(libname, pkgname)
libname |
Library name |
pkgname |
Package name |
Nothing
The function calculates Shannon's Entropy. The function is
meant for internal use only. To calculate the entropy for each action in the
design, please use the wrapper function calculate_entropy
calc_entropy(design, priors = NULL)calc_entropy(design, priors = NULL)
design |
A matrix with rows equal to the number of rules and columns equal to the number of actions or a list of such matrices. |
priors |
A vector of prior values. If the design is a list of matrices, priors can be a matrix with rows equal to the length of the design and columns equal to the number of rules. |
Returns a vector of entropies for each possible action with the following attributes:
design
priors
pr_aj_rk
pr_rk_aj
The function calculates the expected payout to the decision maker. The payout
to the decision maker depends on whether or not the observer tries to guess
the rule, and the monetary payout for choosing an action that leaves the
observer clueless enough about the rule to refrain from guessing. The
function is meant for internal use only. To calculate the payout to the
decision maker, use the wrapper function calculate_payouts.
calc_payout_dm(pr_guess, pay_dm)calc_payout_dm(pr_guess, pay_dm)
pr_guess |
A vector of probabilities that the observer will guess. |
pay_dm |
The pay to the decision maker if the observer does not guess. |
A vector of expected payouts for each possible guess made by the observer
The function calculates the expected payout to the observer. The payout to
the observer depends on the posterior probabilities, i.e. the probability
of a rule conditional on observing an action, and the monetary payout for
guessing correctly. The function is meant for internal use only. To calculate
the payout to the observer, use the wrapper function
calculate_payouts.
calc_payout_obs(pr_rk_aj, pay_obs)calc_payout_obs(pr_rk_aj, pay_obs)
pr_rk_aj |
A matrix of posterior probabilities |
pay_obs |
The pay to the observer for guessing correctly. |
A vector of expected pays for each possible guess
The function calculates the probability of an action conditional on a given rule and is part of calculating the entropy of an action. The function is meant for internal use only.
calc_pr_aj_rk(design)calc_pr_aj_rk(design)
design |
A matrix with rows equal to the number of rules and columns equal to the number of actions or a list of such matrices. |
An r x a matrix of probabilities
The function calculates the probability that an observer will try to guess
which rule governs the decision maker's actions. The function is meant for
internal use only. It can be printed alongside the payouts calculated using
print_payout if print_all = TRUE.
calc_pr_guess(expected_payout_obs, payout_obs_no_guess, deterministic)calc_pr_guess(expected_payout_obs, payout_obs_no_guess, deterministic)
expected_payout_obs |
Vector of expected payout to the observer from guessing |
payout_obs_no_guess |
The payout to the observer from not guessing |
deterministic |
A boolean equal to TRUE if we treat the decision to guess as deterministic. Defaults to TRUE. |
A vector with the probabilities that an observer will guess
The function calculates the probability of a rule conditional on observing a given action and is part of calculating the entropy of an action. This probability is also referred to as the posterior probability. The function is meant for internal use only.
calc_pr_rk_aj(pr_aj_rk, priors)calc_pr_rk_aj(pr_aj_rk, priors)
pr_aj_rk |
A matrix with the probabilities of actions conditional on a given rule. |
priors |
A vector of prior values. If the design is a list of matrices, priors can be a matrix with rows equal to the length of the design and columns equal to the number of rules. |
An r x a matrix of probabilities
The function is a wrapper for calc_entropy and is meant for
external use by the user. The goal for the decision maker is
to choose an action such that the observer is left as clueless as possible
as to which rule governs his actions, i.e. maximize entropy.
calculate_entropy(design, priors = NULL)calculate_entropy(design, priors = NULL)
design |
A matrix with rows equal to the number of rules and columns equal to the number of actions or a list of such matrices. |
priors |
A vector of prior values. If the design is a list of matrices, priors can be a matrix with rows equal to the length of the design and columns equal to the number of rules. |
A list of of vectors of entropies for each possible action with the following attributes:
design
priors
pr_aj_rk
pr_rk_aj
design <- matrix(c(-1, -1, -1, -1, 1, -1, 0, 0, -1, 0, -1, 0, -1, 0, 0, 0, 0, -1, 0, -1), nrow = 4L, byrow = TRUE) calculate_entropy(design)design <- matrix(c(-1, -1, -1, -1, 1, -1, 0, 0, -1, 0, -1, 0, -1, 0, 0, 0, 0, -1, 0, -1), nrow = 4L, byrow = TRUE) calculate_entropy(design)
The function is a wrapper function for calc_payout_obs and
calc_payout_dm, and exported to be used by the user.
It calculates the expected payout to both
observers and decision makers for each possible action undertaken by the
decision maker, and the observers choice of whether or not to try and guess
the rule.
calculate_payouts( entropy, pay_obs, pay_dm, pay_no_guess, deterministic = FALSE )calculate_payouts( entropy, pay_obs, pay_dm, pay_no_guess, deterministic = FALSE )
entropy |
A list containing the entropy |
pay_obs |
A numeric with pay to the observer for guessing correctly |
pay_dm |
A numeric with pay to the decision maker if the observer does not guess |
pay_no_guess |
A numeric with pay to the observer for not guessing |
deterministic |
If TRUE a deterministic procedure is used to determine whether the observer tries to guess. Default is FALSE and the probability is calculated using a logit expression |
A list or list of lists where each list contains the payout to the observer and decision maker.
The function checks the list of design options specified by the user and
sets sensible defaults where no option is specified. The function is meant
for internal use only and is not exported to be used by the users. All
options can be overridden by the the user by appropriately specifying
design_opt_input.
Below is a list defining each of the options available to be specified in
design_opt_input.
check_design_opt(design_opt_input)check_design_opt(design_opt_input)
design_opt_input |
A list of user supplied design options. |
Number of rules (i.e. rows)
Number of actions (i.e. columns)
Minimum number of actions available for the considered rule
Maximum number of actions available for the considered rule
Minimum number of rules fitting each permitted action conditional on the rule
Number of rules with obligatory actions
Specifies the standard deviation of the entropy values
Number of designs to generate
Maximum number of iterations before stopping search for designs
A seed for the random number generator. Useful for replicability
Returns a list of design options with the missing from input replaced by default values
The function creates a rule-action matrix (i.e. an obfuscation design)
subject to a list of pre-programmed restrictions. These restrictions are in
place to ensure that no invalid designs are created. Some of these restrictions
can be changed by the user by appropriately specifying the
design_opt_input. Each matrix is a design for one period of the
the obfuscation game. This function is for internal use only. To create
an obfuscation design, the user should use generate_designs.
construct_design(design_opt)construct_design(design_opt)
design_opt |
List of design options |
A rules-action matrix
Extracts the attributes of objects nested in a list
extract_attr(x, str_attr)extract_attr(x, str_attr)
x |
A list of objects with attributes or an object with an attribute |
str_attr |
A non-empty character string specifying which attribute is to be extracted |
Returns a list the length of x containing the specified attribute. If the attribute does not exist, returns NULL
design_opt_input <- list(rules = 4, actions = 5) design <- generate_designs(design_opt_input) extract_attr(design, "design_conditions") design_opt_input <- list(rules = 4, actions = 5, designs = 2) design <- generate_designs(design_opt_input) extract_attr(design, "design_conditions")design_opt_input <- list(rules = 4, actions = 5) design <- generate_designs(design_opt_input) extract_attr(design, "design_conditions") design_opt_input <- list(rules = 4, actions = 5, designs = 2) design <- generate_designs(design_opt_input) extract_attr(design, "design_conditions")
The function takes the list of design options design_opt_input and
generates one or more obfuscation designs subject to the specified
restrictions. A full specification of all the options available can be found
in the manual along with detailed examples of different designs. At a minimum
the user must supply the number of rules and actions, i.e. the dimensions of
the design problem.
generate_designs(design_opt_input = list())generate_designs(design_opt_input = list())
design_opt_input |
A list of user supplied design options. |
A list of matrices with rules and actions
design_opt_input <- list(rules = 4, actions = 5) generate_designs(design_opt_input)design_opt_input <- list(rules = 4, actions = 5) generate_designs(design_opt_input)
last extracts the last element of a vector
last(x)last(x)
x |
A vector |
x <- 1:4 last(x) x <- c("hello", "my", "name", "is", "buttons") last(x)x <- 1:4 last(x) x <- c("hello", "my", "name", "is", "buttons") last(x)
Takes a design or list of designs and prints them to the console. To store a
design, please see save_design. Depending on the print options,
additional text is provided with information on the considered rule and/or
the design generation process.
print_design(design, print_all = FALSE)print_design(design, print_all = FALSE)
design |
A matrix with rows equal to the number of rules and columns equal to the number of actions |
print_all |
If TRUE prints information on the number of iterations and and whether all design conditions were met. Default is FALSE |
design_opt_input <- list(rules = 4, actions = 5) design <- generate_designs(design_opt_input) print_design(design) print_design(design, TRUE)design_opt_input <- list(rules = 4, actions = 5) design <- generate_designs(design_opt_input) print_design(design) print_design(design, TRUE)
The function prints the vector of entropies for each possible action. Depending on printing options, additional information about the probability calculations can be provided.
print_entropy(entropy, digits = 3, print_all = FALSE)print_entropy(entropy, digits = 3, print_all = FALSE)
entropy |
The entropy measure from |
digits |
The number of digits to round to. Default 3. |
print_all |
If TRUE will print all information on intermediary calculations |
design <- matrix(c(-1, -1, -1, -1, 1, -1, 0, 0, -1, 0, -1, 0, -1, 0, 0, 0, 0, -1, 0, -1), nrow = 4, byrow = TRUE) entropy <- calculate_entropy(design) print_entropy(entropy) print_entropy(entropy, digits = 4) print_entropy(entropy, print_all = TRUE)design <- matrix(c(-1, -1, -1, -1, 1, -1, 0, 0, -1, 0, -1, 0, -1, 0, 0, 0, 0, -1, 0, -1), nrow = 4, byrow = TRUE) entropy <- calculate_entropy(design) print_entropy(entropy) print_entropy(entropy, digits = 4) print_entropy(entropy, print_all = TRUE)
The function formats and prints the payout to the observer and decision maker.
print_payout(payout, digits = 3, print_all = FALSE)print_payout(payout, digits = 3, print_all = FALSE)
payout |
A list of calculated payouts |
digits |
The number of digits to round to. Default 3. |
print_all |
If TRUE will print the probabilities of guessing |
The function takes a design or a list of designs and stores them in .csv files in the specified folder.
save_design(x, x_name, path = getwd())save_design(x, x_name, path = getwd())
x |
A design or list of designs |
x_name |
A character string with the name of the file |
path |
A string giving the path to where the designs are stored. The default is the current working directory |
Nothing is returned