Package {eiIT}

Title:	Ecological Inference via Information Theory
Version:	0.0.1-1
Description:	Estimates RxC transfer matrices from aggregated marginal data using a two-stage (GME+IPF) information-theoretic approach within a two-step (global+local) estimation procedure. The resulting matrices are consistent with observed row and column marginals across collections of subtables (e.g. precincts, polling stations, or districts). References: Golan, A., Judge, G., & Miller, D. (1996). Maximum Entropy Econometrics: Robust Estimation with Limited Data. Wiley. Judge, G., Miller, D.J., & Cho, W.K.T. (2004). An information theoretic approach to ecological estimation and inference. In G. King, O. Rosen, & M. A. Tanner (Eds.), Ecological Inference: New Methodological Strategies (pp. 162–187). Cambridge University Press. Mittelhammer, R., Judge, G., & Miller, D. (2000). Econometric Foundations. Cambridge University Press. Pavia, J.M. (2023) <doi:10.1007/s43545-023-00658-y> Acknowledgements: The author wish to thank Conselleria de Economia, Hacienda y Administracion Publica (grant CIACIO/2023/031) for supporting this research.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding:	UTF-8
Imports:	stats, utils, nloptr
Suggests:	ggplot2, scales
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2026-05-27 17:23:34 UTC; pavia
Author:	Jose M. Pavía [aut, cre]
Maintainer:	Jose M. Pavía <jose.m.pavia@uv.es>
Repository:	CRAN
Date/Publication:	2026-06-01 08:40:07 UTC

Ecological Inference via Generalized Maximum Entropy

Description

Estimates RxC transfer matrices from aggregated marginal data using a two-stage information-theoretic procedure combining Generalized Maximum Entropy (GME) and Iterative Proportional Fitting (IPF), together with a two-step estimation strategy based on global and local estimation. The resulting matrices are consistent with observed row and column marginals across collections of subtables (e.g. precincts, polling stations, or districts).

Usage

ei_it(
  votes.election1,
  votes.election2,
  m.bound = NULL,
  census.changes = c("adjust", "raw", "regular", "ordinary", "enriched", "simultaneous",
    "semifull", "full", "gold"),
  init = "uniform",
  lambda = 100,
  ipf = TRUE,
  ipf.tol = 1e-06,
  ipf.max.iter = 1000,
  confidence = NULL,
  ci.method = "kkt",
  B = 500,
  optimizer.opts = list(),
  ...
)

Arguments

Details

A two-stage, two-step information-theoretic procedure

The method proceeds in two steps. Each step consists of a GME and an IPF stage.

The GME stage finds the transition matrix \hat{P} that maximises the joint entropy of transition probabilities and reparametrised errors, subject to soft data constraints (allowing for measurement error in the observed margins) and Markov adding-up constraints.

The IPF stage (optional): projects \hat{P} onto the set of matrices exactly consistent with the observed margins by minimising the KL divergence from the GME solution. Both stages operate within the same information-theoretic framework: GME maximises entropy under noisy constraints; IPF minimises KL divergence under exact constraints. The combined estimator inherits the low-variance properties of GME and the exact consistency of IPF.

In the first step (global), the method estimates a global probability matrix consistent with the observed row and column marginals across a set of subtables (e.g. precincts, polling stations, or districts). By default, this corresponds to the most uniform matrix satisfying the aggregation constraints, although the estimation can also be centered around an initial matrix supplied by the user.

In the second step (local), local subtables are estimated with shrinkage toward the global estimate via a Kullback–Leibler penalty, in the first stage, and using IPF in the second stage. The final global solution is obtained as the composition (aggregation) of the local solutions.

A two-stage, two-step information-theoretic estimation

For I subtables with R row categories and C column categories, the GME estimator maximises the joint entropy of the transition probabilities and the reparametrised errors:

H(p, v) = -\sum_{j,k} p_{jk} \ln p_{jk} - \sum_{i,k} v_{ik} \ln v_{ik}

subject to the data constraints below, the Markov adding-up constraints \sum_k p_{jk} = 1, and non-negativity.

In the GME estimator the observed row margins x_{ij} and column margins y_{ik} satisfy (up to measurement error):

y_{ik} = \sum_j x_{ij}\, p_{jk} + \varepsilon_{ik}

The GME estimator allows for measurement error in the observed margins via the reparametrisation \varepsilon_{ik} = m(1 - 2v_{ik}), v_{ik} \in [0,1]. This implies that the solution \hat{P} will not in general satisfy the data constraints exactly:

\sum_j x_{\cdot j} \hat{p}_{jk} \approx y_{\cdot k}

The residual inconsistency is controlled by m.bound: smaller values force \hat{P} closer to exact consistency at the cost of less flexibility to absorb measurement error.

When ipf = TRUE, a post-hoc IPF (Iterative Proportional Fitting) step projects \hat{P} onto the set of matrices exactly consistent with the observed margins. IPF is embedded into the information-theoretic framework: it is the algorithm that solves

\min_P \; KL(P \,\|\, \hat{P}) \quad \text{s.t.} \quad \mathbf{x}_{\cdot}^\top P = \mathbf{y}_{\cdot}^\top, \; P\mathbf{1} = \mathbf{1}, \; P \geq 0

where \hat{P} is the GME solution used as the prior. The combined GME+IPF estimator can therefore be interpreted as a single entropy minimisation problem in two nested projections (Csiszár 1975; Deming and Stephan 1940).

For local matrices P_i, the same IPF projection is applied individually to each subtable using its own margins x_i and y_i, with \hat{P}_i (the GME local solution) as the prior.

Choosing m.bound

The error support m bounds how far the linear prediction can deviate from the observed marginal. Practical guidelines:

• m.bound = 1.0: maximally non-informative (full unit interval).

• m.bound = 0.5: conservative default, recommended by Judge et al. (2004).

• m.bound = 0.1: appropriate when data are precise (e.g. census counts).

The automatic rule (NULL) uses 0.5 * diff(range(Y)), which adapts to the empirical spread of the column margins.

Initialisation and the uniform prior

The uniform initialisation is not arbitrary: it is the maximum-entropy distribution on the simplex and represents a state of complete prior ignorance about the transition structure. The GME objective is strictly concave and the feasible set is convex, so the problem has a unique global optimum that is invariant to the starting point. The "random" option is provided purely for numerical sanity checks.

Local matrices and lambda

The first-step global estimator pools all subtables, imposing a single P. As heterogeneity across subtables is expected, local matrices P_i are be estimated in a second pass. Each P_i is identified only by the C data constraints from subtable i plus R Markov constraints (a total of R \cdot C free parameters), which is typically under-identified without the KL penalty. lambda regularises this by shrinking P_i toward \hat{P}.

census.changes

Census changes are usual between elections, this argument controls how differences across polling units are dealt with.

adjust:

The default value. This is the simplest solution for handling discrepancies between the total number of counts for the first and second elections. This value implies that the R1 column-aggregations of the counts in votes.election1 of the first election are proportionally adjusted to equal the aggregation of the counts in votes.election2 of the second election. In this scenario, R is equal to R1 and C equal to C2.

raw:

This argument accounts for a scenario with two elections elapsed at least some months where only the raw election data recorded in the I units, in which the electoral space under study is divided, are available and net entries and net exits are approximated from the available information. In this scenario, net exits and net entries are estimated according to Pavia (2023). When both net entries and exits are no null, constraint (15) of Pavia (2023) applies: no transfer between entries and exits are allowed. In this scenario, R could be equal to R1 or R1 + 1 and C equal to C2 or C2 + 1.

simultaneous:

This is the value to be used in classical ecological inference problems, such as in ecological studies of social or racial voting, and in scenarios with two simultaneous elections. In this scenario, the sum by rows of votes.election1 and votes.election2 must coincide.

regular:

This value accounts for a scenario with two elections elapsed at least some months where (i) the column C1 of votes.election1 corresponds to new (young) electors who have the right to vote for the first time, (ii) net exits and maybe other additional net entries are computed according to Pavia (2023). When both net entries and exits are no null, constraints (13) and (15) of Pavia (2023) apply. In this scenario, R could be equal to R1 or R1 + 1 and C equal to C2 or C2 + 1.

ordinary:

This value accounts for a scenario with two elections elapsed at least some months where (i) the column C1 of votes.election2 corresponds to electors who died in the interperiod election, (ii) net entries and maybe other additional net exits are computed according to Pavia (2023). When both net entries and net exits are no null, constraints (14) and (15) of Pavia (2023) apply. In this scenario, R could be equal to R1 or R1 + 1 and C equal to C2 or C2 + 1.

enriched:

This value accounts for a scenario that somewhat combine regular and ordinary scenarios. We consider two elections elapsed at least some months where (i) the column R1 of votes.election1 corresponds to new (young) electors who have the right to vote for the first time, (ii) the column C2 of votes.election2 corresponds to electors who died in the interperiod election, (iii) other (net) entries and (net) exits are computed according to Pavia (2023). When both net entries and net exits are no null, constraints (12) to (15) of Pavia (2023) apply. In this scenario, R could be equal to R1 or R1 + 1 and C equal to C2 or C2 + 1.

semifull:

This value accounts for a scenario with two elections elapsed at least some months, where: (i) the column R1 = R of votes.election1 totals new electors (young and immigrants) that have the right to vote for the first time in each polling unit and (ii) the column C2 = C of votes.election2 corresponds to total exits of the census lists (due to death or emigration). In this scenario, the sum by rows of votes.election1 and votes.election2 must agree and constraint (15) of Pavia (2023) apply.

full:

This value accounts for a scenario with two elections elapsed at least some months, where R = R1, C = C2 and (i) the column R - 1 of votes.election1 totals new (young) electors that have the right to vote for the first time, (ii) the column R of votes.election1 measures new immigrants that have the right to vote and (iii) the column C of votes.election2 corresponds to total exits of the census lists (due to death or emigration). In this scenario, the sum by rows of votes.election1 and votes.election2 must agree and constraints (13) and (15) of Pavia (2023) apply.

gold:

This value accounts for a scenario similar to full, where R = R1, C = C2 where (i) the column R - 1 of votes_election1 totals new young electors that have the right to vote for the first time, (ii) the column R of votes_election1 measures new immigrants that have the right to vote, and total exits are separated out between (iii) exits due to emigration (column C - 1 of votes.election2) and (iv) deaths (column C of votes.election2). In this scenario, the sum by rows of votes.election1 and votes.election2 must agree. Constraints (12) to (15) of Pavia (2023) apply.

Confidence intervals

When confidence = TRUE, two methods are available. The "kkt" method computes asymptotic standard errors for the global GME solution using the Karush-Kuhn-Tucker conditions, and is valid as an approximation when the IPF correction is small (residual inconsistency below ~0.02) and the local composition step does not substantially alter the global estimate. The "bootstrap" method resamples subtables and repeats the full two-stage, two-step procedure, capturing uncertainty from all sources..

Value

An object of class "eiit", which is a list containing:

VTM

A matrix of shape RxC with the estimated proportions of the row-standardized vote transitions from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.votes

A matrix of shape RxC with the estimated vote transfers from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.first

A matrix of shape RxC with the first-step estimated proportions of the row-standardized vote transitions from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.votes.first

A matrix of shape RxC with the first-step estimated vote transfers from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.gme

A matrix of shape RxC with the first-stage (GME) estimated proportions of the probabilities vote transitions from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.units

An array of shape RxCxI with the estimated proportions of the row-standardized vote transitions from election 1 to election 2 attained for each unit. In raw, regular, ordinary and enriched scenarios, each unit matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.votes.units

An array of shape RxCxI with the estimated transfer of votes from election 1 to election 2 attained for each unit. In raw, regular, ordinary and enriched scenarios, each unit matrix includes the row and the column corresponding to net entries and net exits (when they are present).

VTM.lower

A matrix of shape RxC with the estimated lower limits of the confidence intervals for the proportions of the row-standardized vote transitions from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present). When confidence = NULL this is a NULL object.

VTM.upper

A matrix of shape RxC with the estimated upper limits of the confidence intervals for the proportions of the row-standardized vote transitions from election 1 to election 2. In raw, regular, ordinary and enriched scenarios, this matrix includes the row and the column corresponding to net entries and net exits (when they are present). When confidence = NULL this is a NULL object.

deterministic.bounds

A list of two matrices of shape RxC and two arrays of shape RXCxI containing for each vote transition the lower and upper allowed proportions given the observed aggregates.

entropy

Scalar. Value of the entropy objective at the first stage, first-step solution.

convergence

Character. Convergence message from the optimizer.

m.bound

The value of m.bound used (useful when auto-selected).

inputs

List containing all the objects with the values used as arguments by the function.

Author(s)

Jose M. Pavia, pavia@uv.es

References

Csiszár, I. (1975). I-divergence geometry of probability distributions and minimization problems. Annals of Probability, 3(1), 146–158.

Deming, W. E., & Stephan, F. F. (1940). On a least squares adjustment of a sampled frequency table when the expected marginal totals are known. Annals of Mathematical Statistics, 11(4), 427–444.

Golan, A., Judge, G., & Miller, D. (1996). Maximum Entropy Econometrics: Robust Estimation with Limited Data. Wiley.

Judge, G., Miller, D.J., & Cho, W.K.T. (2004). An information theoretic approach to ecological estimation and inference. In G. King, O. Rosen, & M. A. Tanner (Eds.), Ecological Inference: New Methodological Strategies (pp. 162–187). Cambridge University Press.

Mittelhammer, R., Judge, G., & Miller, D. (2000). Econometric Foundations. Cambridge University Press.

Pavia, J.M. (2023). Adjustment of initial estimates of voter transition probabilities to guarantee consistency and completeness. SN Social Sciences, 3, 75. doi:10.1007/s43545-023-00658-y.

Examples

votes1 <- structure(list(P1 = c(16L, 4L, 13L, 6L, 1L, 16L, 6L, 17L, 48L, 14L),
                         P2 = c(8L, 3L, 0L, 5L, 1L, 4L, 7L, 6L, 28L, 8L),
                         P3 = c(38L, 11L, 11L, 3L, 13L, 39L, 14L, 34L, 280L, 84L),
                         P4 = c(66L, 5L, 18L, 39L, 30L, 57L, 35L, 65L, 180L, 78L),
                         P5 = c(14L, 0L, 5L, 2L, 4L, 21L, 6L, 11L, 54L, 9L),
                         P6 = c(8L, 2L, 5L, 3L, 0L, 7L, 7L, 11L, 45L, 17L),
                         P7 = c(7L, 3L, 5L, 2L, 3L, 17L, 7L, 13L, 40L, 8L)),
                         row.names = c(NA, 10L), class = "data.frame")
votes2 <- structure(list(C1 = c(2L, 1L, 2L, 2L, 0L, 4L, 0L, 4L, 19L, 14L),
                         C2 = c(7L, 3L, 1L, 7L, 2L, 5L, 3L, 10L, 21L, 6L),
                         C3 = c(78L, 7L, 28L, 42L, 28L, 84L, 49L, 85L, 260L, 100L),
                         C4 = c(56L, 14L, 20L, 7L, 19L, 54L, 22L, 50L, 330L, 91L),
                         C5 = c(14L, 3L, 6L, 2L, 3L, 14L, 8L, 8L, 45L, 7L)),
                         row.names = c(NA, 10L), class = "data.frame")
example <- ei_it(votes1, votes2)$VTM

Graphical representation of a RxC ecological inference (vote transfer) matrix

Description

Plot method for objects obtained with ei_it.

Usage

## S3 method for class 'eiit'
plot(
  x,
  margins = TRUE,
  digits = 2,
  row.names = NULL,
  col.names = NULL,
  size.numbers = 6,
  size.labels = 4,
  size.margins = 4,
  colour.cells = "steelblue",
  colour.grid = "bisque2",
  alpha = 0.5,
  which = NULL,
  ...,
  show.plot = TRUE
)

Arguments

Value

Invisibly returns the (ggplot) description of the plot, which is a list with components that contain the plot itself, the data, information about the scales, panels etc.

Note

ggplot2 is needed to be installed for this function to work.

Author(s)

Jose M. Pavia, pavia@uv.es

Examples

votes1 <- structure(list(P1 = c(16L, 4L, 13L, 6L, 1L, 16L, 6L, 17L, 48L, 14L),
                         P2 = c(8L, 3L, 0L, 5L, 1L, 4L, 7L, 6L, 28L, 8L),
                         P3 = c(38L, 11L, 11L, 3L, 13L, 39L, 14L, 34L, 280L, 84L),
                         P4 = c(66L, 5L, 18L, 39L, 30L, 57L, 35L, 65L, 180L, 78L),
                         P5 = c(14L, 0L, 5L, 2L, 4L, 21L, 6L, 11L, 54L, 9L),
                         P6 = c(8L, 2L, 5L, 3L, 0L, 7L, 7L, 11L, 45L, 17L),
                         P7 = c(7L, 3L, 5L, 2L, 3L, 17L, 7L, 13L, 40L, 8L)),
                         row.names = c(NA, 10L), class = "data.frame")
votes2 <- structure(list(C1 = c(2L, 1L, 2L, 2L, 0L, 4L, 0L, 4L, 19L, 14L),
                         C2 = c(7L, 3L, 1L, 7L, 2L, 5L, 3L, 10L, 21L, 6L),
                         C3 = c(78L, 7L, 28L, 42L, 28L, 84L, 49L, 85L, 260L, 100L),
                         C4 = c(56L, 14L, 20L, 7L, 19L, 54L, 22L, 50L, 330L, 91L),
                         C5 = c(14L, 3L, 6L, 2L, 3L, 14L, 8L, 8L, 45L, 7L)),
                         row.names = c(NA, 10L), class = "data.frame")
example <- ei_it(votes1, votes2)
p <- plot(example, show.plot = FALSE)
p

Print a summary of an output of the ei_it function

Description

Print method for objects obtained with the ei_it function.

Usage

## S3 method for class 'eiit'
print(x, ..., margins = TRUE, digits = 2)

Arguments

Value

No return value, called for side effects.

Author(s)

Jose M. Pavia, pavia@uv.es

Examples

votes1 <- structure(list(P1 = c(16L, 4L, 13L, 6L, 1L, 16L, 6L, 17L, 48L, 14L),
                         P2 = c(8L, 3L, 0L, 5L, 1L, 4L, 7L, 6L, 28L, 8L),
                         P3 = c(38L, 11L, 11L, 3L, 13L, 39L, 14L, 34L, 280L, 84L),
                         P4 = c(66L, 5L, 18L, 39L, 30L, 57L, 35L, 65L, 180L, 78L),
                         P5 = c(14L, 0L, 5L, 2L, 4L, 21L, 6L, 11L, 54L, 9L),
                         P6 = c(8L, 2L, 5L, 3L, 0L, 7L, 7L, 11L, 45L, 17L),
                         P7 = c(7L, 3L, 5L, 2L, 3L, 17L, 7L, 13L, 40L, 8L)),
                         row.names = c(NA, 10L), class = "data.frame")
votes2 <- structure(list(C1 = c(2L, 1L, 2L, 2L, 0L, 4L, 0L, 4L, 19L, 14L),
                         C2 = c(7L, 3L, 1L, 7L, 2L, 5L, 3L, 10L, 21L, 6L),
                         C3 = c(78L, 7L, 28L, 42L, 28L, 84L, 49L, 85L, 260L, 100L),
                         C4 = c(56L, 14L, 20L, 7L, 19L, 54L, 22L, 50L, 330L, 91L),
                         C5 = c(14L, 3L, 6L, 2L, 3L, 14L, 8L, 8L, 45L, 7L)),
                         row.names = c(NA, 10L), class = "data.frame")
example <- ei_it(votes1, votes2)
print(example, digits = 1, margins = TRUE)

Print a summary of a summary.eiit object

Description

Print method for summary.eiit objects

Usage

## S3 method for class 'summary.eiit'
print(x, ..., margins = TRUE, digits = 2)

Arguments

Value

No return value, called for side effects.

Summarize an eiit output object

Description

Summary method for objects obtained with the ei_it function

Usage

## S3 method for class 'eiit'
summary(object, ...)

Arguments

Value

An object of class "summary.eiit". A list with four components:

Author(s)

Jose M. Pavia, pavia@uv.es

Examples

votes1 <- structure(list(P1 = c(16L, 4L, 13L, 6L, 1L, 16L, 6L, 17L, 48L, 14L),
                         P2 = c(8L, 3L, 0L, 5L, 1L, 4L, 7L, 6L, 28L, 8L),
                         P3 = c(38L, 11L, 11L, 3L, 13L, 39L, 14L, 34L, 280L, 84L),
                         P4 = c(66L, 5L, 18L, 39L, 30L, 57L, 35L, 65L, 180L, 78L),
                         P5 = c(14L, 0L, 5L, 2L, 4L, 21L, 6L, 11L, 54L, 9L),
                         P6 = c(8L, 2L, 5L, 3L, 0L, 7L, 7L, 11L, 45L, 17L),
                         P7 = c(7L, 3L, 5L, 2L, 3L, 17L, 7L, 13L, 40L, 8L)),
                         row.names = c(NA, 10L), class = "data.frame")
votes2 <- structure(list(C1 = c(2L, 1L, 2L, 2L, 0L, 4L, 0L, 4L, 19L, 14L),
                         C2 = c(7L, 3L, 1L, 7L, 2L, 5L, 3L, 10L, 21L, 6L),
                         C3 = c(78L, 7L, 28L, 42L, 28L, 84L, 49L, 85L, 260L, 100L),
                         C4 = c(56L, 14L, 20L, 7L, 19L, 54L, 22L, 50L, 330L, 91L),
                         C5 = c(14L, 3L, 6L, 2L, 3L, 14L, 8L, 8L, 45L, 7L)),
                         row.names = c(NA, 10L), class = "data.frame")
example <- ei_it(votes1, votes2)
summary(example)