Runs a Bootstrap to Estimate the Standard Deviation of Predicted Probabilities

This function computes the Expected-Maximization (EM) algorithm "nboot" times. It then computes the standard deviation from the nboot estimated probability matrices on each component.

Usage

bootstrap(
  object = NULL,
  X = NULL,
  W = NULL,
  json_path = NULL,
  nboot = 100,
  allow_mismatch = TRUE,
  seed = NULL,
  ...
)

Arguments

object: An object of class eim, which can be created using the eim function. This parameter should not be used if either (i) X and W matrices or (ii) json_path is supplied. See Note.
X: A (b x c) matrix representing candidate votes per ballot box.
W: A (b x g) matrix representing group votes per ballot box.
json_path: A path to a JSON file containing X and W fields, stored as nested arrays. It may contain additional fields with other attributes, which will be added to the returned object.
nboot: Integer specifying how many times to run the EM algorithm.
allow_mismatch: Boolean, if TRUE, allows a mismatch between the voters and votes for each ballot-box, only works if method is "mvn_cdf", "mvn_pdf", "mult" and "mcmc". If FALSE, throws an error if there is a mismatch. By default it is TRUE.
seed: An optional integer indicating the random seed for the randomized algorithms. This argument is only applicable if initial_prob = "random" or method is either "mcmc" or "mvn_cdf". Aditionally, it sets the random draws of the ballot boxes.
...: Additional arguments passed to the run_em function that will execute the EM algorithm.

Value

Returns an eim object with the sd field containing the estimated standard deviations of the probabilities and the amount of iterations that were made. If an eim object is provided, its attributes (see run_em) are retained in the returned object.

Note

This function can be executed using one of three mutually exclusive approaches:

By providing an existing eim object.
By supplying both input matrices (X and W) directly.
By specifying a JSON file (json_path) containing the matrices.

These input methods are mutually exclusive, meaning that you must provide exactly one of these options. Attempting to provide more than one or none of these inputs will result in an error.

When called with an eim object, the function updates the object with the computed results. If an eim object is not provided, the function will create one internally using either the supplied matrices or the data from the JSON file before executing the algorithm.

Examples

# \donttest{
# Example 1: Using an 'eim' object directly
simulations <- simulate_election(
    num_ballots = 200,
    num_candidates = 5,
    num_groups = 3,
)

model <- eim(X = simulations$X, W = simulations$W)

model <- bootstrap(
    object = model,
    nboot = 30,
    method = "mult",
    maxiter = 500,
    verbose = FALSE,
)

# Access standard deviation throughout 'model'
print(model$sd)
#>            [,1]       [,2]       [,3]       [,4]       [,5]
#> [1,] 0.00226374 0.00563111 0.00592806 0.00344514 0.00637459
#> [2,] 0.00513794 0.00432388 0.00333614 0.00851491 0.00807659
#> [3,] 0.00401287 0.00274517 0.00737540 0.00760281 0.00756489


# Example 2: Providing 'X' and 'W' matrices directly
model <- bootstrap(
    X = simulations$X,
    W = simulations$W,
    nboot = 15,
    method = "mvn_pdf",
    maxiter = 100,
    maxtime = 5,
    param_threshold = 0.01,
    allow_mismatch = FALSE
)

print(model$sd)
#>            [,1]       [,2]      [,3]       [,4]       [,5]
#> [1,] 0.00311126 0.00860623 0.0102089 0.00421175 0.00897261
#> [2,] 0.00591519 0.00339169 0.0061131 0.00953521 0.00738456
#> [3,] 0.00424751 0.00315001 0.0118022 0.00708363 0.00943713
# }

# Example 3: Using a JSON file as input

if (FALSE) { # \dontrun{
model <- bootstrap(
    json_path = "path/to/election_data.json",
    nboot = 70,
    method = "mult",
)

print(model$sd)
} # }