| dirichlet_tree {elections.dtree} | R Documentation |
A dirichlet_tree object represents a Dirichlet-tree distribution
on ballots. By specifying the tree structure for the ranked ballots,
the Dirichlet-tree is initialized with the same prior structure described by
Everest et al. (2022). There are
methods provided for observing data (to obtain a posterior distribution)
along with methods to sample election outcomes and sets of ballots from
the posterior predictive distribution.
An R6Class generator object.
a0Gets or sets the a0 parameter for the Dirichlet-tree.
min_depthGets or sets the min_depth parameter for the Dirichlet-tree.
max_depthGets or sets the max_depth parameter for the
Dirichlet-tree.
vdGets or sets the vd parameter for the Dirichlet-tree.
new()Create a new dirichlet_tree prior distribution with the specified
tree structure. See Everest et al. (2022)
for further details.
dirichlet_tree$new( candidates, min_depth = 0, max_depth = length(candidates) - 1, a0 = 1, vd = FALSE )
candidatesA character vector, with each element (must be unique) representing a single candidate.
min_depthThe minimum number of candidates which must be specified for a valid ballot in the election.
max_depthThe maximum number of candidates which can be specified for a valid ballot in the election.
a0The prior parameter for the distribution.
vdA flag which, when TRUE, employs a parameter structure which
reduces to a regular Dirichlet distribution as described by
Everest et al. (2022).
A new dirichlet_tree prior.
dtree <- dirichlet_tree$new(candidates = LETTERS, a0 = 1., min_depth = 1)
print()print shows some details of the distribution and its parameters.
dirichlet_tree$print()
The dirichlet_tree object.
update()Updates the dirichlet_tree object with observations of ballots.
This updates the parameter structure of the tree to yield the posterior
Dirichlet-tree, as described in
Everest et al. (2022).
dirichlet_tree$update(ballots)
ballotsA set of ballots to observe - must be of class ranked_ballots.
The dirichlet_tree object.
dirichlet_tree$new(
candidates = LETTERS
)$update(
ranked_ballots(c("A", "B", "C"))
)
reset()Resets the dirichlet_tree observations to revert the
parameter structure back to the originally specified prior.
dirichlet_tree$reset()
The dirichlet_tree object.
dirichlet_tree$new(
candidates = LETTERS
)$update(
ranked_ballots(c("A", "B", "C"))
)$reset()
sample_posterior()Draws sets of ballots from independent realizations of the Dirichlet-tree posterior, then determines the probability for each candidate being elected by aggregating the results of the social choice function. See Everest et al. (2022) for details.
dirichlet_tree$sample_posterior( n_elections, n_ballots, n_winners = 1, replace = FALSE, n_threads = NULL )
n_electionsAn integer representing the number of elections to generate. A higher number yields higher precision in the output probabilities.
n_ballotsAn integer representing the total number of ballots cast in the election.
n_winnersThe number of candidates elected in each election.
replaceA boolean indicating whether or not we should replace our sample in the monte-carlo step, drawing the full set of election ballots from the posterior
n_threadsThe maximum number of threads for the process. The default value of
NULL will default to 2 threads. Inf will default to the maximum
available, and any value greater than or equal to the maximum available will
result in the maximum available.
A numeric vector containing the probabilities for each candidate being elected.
dirichlet_tree$new(
candidates = LETTERS,
a0 = 1.,
min_depth = 3,
max_depth = 6,
vd = FALSE
)$update(
ranked_ballots(c("A","B","C"))
)$sample_posterior(
n_elections = 10,
n_ballots = 10
)
sample_predictive()sample_predictive draws ballots from a multinomial distribution
with ballot probabilities obtained from a single realization of the
Dirichlet-tree posterior on the ranked ballots. See
Everest et al. (2022) for details.
dirichlet_tree$sample_predictive(n_ballots)
n_ballotsAn integer representing the total number of ballots cast in the election.
A ranked_ballots object containing n_ballots
ballots drawn from a single realisation of the posterior Dirichlet-tree.
dirichlet_tree$new(
candidates = LETTERS,
a0 = 1.,
min_depth = 3,
max_depth = 6,
vd = FALSE
)$update(
ranked_ballots(c("A","B","C"))
)$sample_predictive(
n_ballots = 10
)
Everest F, Blom M, Stark PB, Stuckey PJ, Teague V, Vukcevic D (2022). “Ballot-Polling Audits of Instant-Runoff Voting Elections with a Dirichlet-Tree Model.” doi:10.48550/ARXIV.2209.03881..
Everest F, Blom M, Stark PB, Stuckey PJ, Teague V, Vukcevic D (2022). “Auditing Ranked Voting Elections with Dirichlet-Tree Models: First Steps.” doi:10.48550/ARXIV.2206.14605..
## ------------------------------------------------
## Method `dirichlet_tree$new`
## ------------------------------------------------
dtree <- dirichlet_tree$new(candidates = LETTERS, a0 = 1., min_depth = 1)
## ------------------------------------------------
## Method `dirichlet_tree$update`
## ------------------------------------------------
dirichlet_tree$new(
candidates = LETTERS
)$update(
ranked_ballots(c("A", "B", "C"))
)
## ------------------------------------------------
## Method `dirichlet_tree$reset`
## ------------------------------------------------
dirichlet_tree$new(
candidates = LETTERS
)$update(
ranked_ballots(c("A", "B", "C"))
)$reset()
## ------------------------------------------------
## Method `dirichlet_tree$sample_posterior`
## ------------------------------------------------
dirichlet_tree$new(
candidates = LETTERS,
a0 = 1.,
min_depth = 3,
max_depth = 6,
vd = FALSE
)$update(
ranked_ballots(c("A","B","C"))
)$sample_posterior(
n_elections = 10,
n_ballots = 10
)
## ------------------------------------------------
## Method `dirichlet_tree$sample_predictive`
## ------------------------------------------------
dirichlet_tree$new(
candidates = LETTERS,
a0 = 1.,
min_depth = 3,
max_depth = 6,
vd = FALSE
)$update(
ranked_ballots(c("A","B","C"))
)$sample_predictive(
n_ballots = 10
)