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.
eim(X = NULL, W = NULL, V = NULL, json_path = NULL)A (b x c) matrix representing candidate votes per ballot box.
A (b x g) matrix representing group votes per ballot box.
Optional (b x a) matrix with the attributes for each ballot box. This is only used for parametric models.
A path to a JSON file containing X, W (and optionally V) fields, stored as nested arrays. It may contain additional fields with other attributes, which will be added to the returned object.
A list of class eim containing:
XThe candidate votes matrix (b x c).
WThe group votes matrix (b x g).
VThe parametric covariates matrix (b x a), when provided.
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" (and optionally "V") under the
top-level object. This two approaches are mutually exclusable, yielding an error otherwise.
When V is supplied, the object is treated as parametric and includes the V attribute.
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.
A way to generate synthetic data for X and W is by using the simulate_election function. See Example 2 below.
This constructor can be used for both non-parametric and parametric models (by providing V).
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.
plot.eim - Plots the probability matrix.
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.
# Example 1: Create an eim object from a JSON file
if (FALSE) { # \dontrun{
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)