fastei (version 0.0.0.12)

eim: S3 Object for the Expectation-Maximization Algorithm

Description

This constructor creates an eim S3 object, either by using matrices X and W directly or by reading them from a JSON file. Each eim object encapsulates the data (votes for candidates and demographic groups) required by the underlying Expectation-Maximization algorithm.

Usage

eim(X = NULL, W = NULL, json_path = NULL)

Value

A list of class eim containing:

X

The candidate votes matrix (b x c).

W

The group votes matrix (b x g).

Arguments

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.

Methods

In addition to this constructor, the "eim" class provides several S3 methods for common operations. Some of these methods are fully documented, while others are ommited due to its straightfoward implementantion. The available methods are:

• run_em - Runs the EM algorithm.

• bootstrap - Estimates the standard deviation.

• save_eim - Saves the object to a file.

• get_agg_proxy - Estimates an ideal group aggregation given their standard deviations.

• get_agg_opt - Estimates an ideal group aggregation among all combinations, given the log-likelihood.

• print.eim - Print info about the object.

• summary.eim - Summarize the object.

• as.matrix.eim - Returns the probability matrix.

• logLik.eim - Returns the final log-likelihood.

Details

If X and W are directly supplied, they must match the dimensions of ballot boxes (b). Alternatively, if json_path is provided, the function expects the JSON file to contain elements named "X" and "W" under the top-level object. This two approaches are mutually exclusable, yielding an error otherwise.

Internally, this function also initializes the corresponding instance within the low-level (C-based) API, ensuring the data is correctly registered for further processing by the EM algorithm.

Examples

# Example 1: Create an eim object from a JSON file
if (FALSE) {
model1 <- eim(json_path = "path/to/file.json")
}

# Example 2: Use simulate_election with optional parameters, then create an eim object
# from matrices

# Simulate data for 500 ballot boxes, 4 candidates and 5 groups
sim_result <- simulate_election(
    num_ballots = 500,
    num_candidates = 3,
    num_groups = 5,
    group_proportions = c(0.2, 0.2, 0.4, 0.1, 0.1)
)

model2 <- eim(X = sim_result$X, W = sim_result$W)

# Example 3: Create an object from a user defined matrix with 8 ballot boxes,
# 2 candidates and 7 groups.

x_mat <- matrix(c(
    57, 90,
    60, 84,
    43, 102,
    72, 71,
    63, 94,
    52, 80,
    60, 72,
    54, 77
), nrow = 8, ncol = 2, byrow = TRUE)

w_mat <- matrix(c(
    10, 15, 25, 21, 10, 40, 26,
    11, 21, 37, 32, 8, 23, 12,
    17, 12, 43, 27, 12, 19, 15,
    20, 18, 25, 15, 22, 17, 26,
    21, 19, 27, 16, 23, 22, 29,
    18, 16, 20, 14, 19, 22, 23,
    10, 15, 21, 18, 20, 16, 32,
    12, 17, 19, 22, 15, 18, 28
), nrow = 8, ncol = 7, byrow = TRUE)

model3 <- eim(X = x_mat, W = w_mat)