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.
a0
Gets or sets the a0
parameter for the Dirichlet-tree.
min_depth
Gets or sets the min_depth
parameter for the Dirichlet-tree.
max_depth
Gets or sets the max_depth
parameter for the
Dirichlet-tree.
vd
Gets 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 )
candidates
A character vector, with each element (must be unique) representing a single candidate.
min_depth
The minimum number of candidates which must be specified for a valid ballot in the election.
max_depth
The maximum number of candidates which can be specified for a valid ballot in the election.
a0
The prior parameter for the distribution.
vd
A 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)
ballots
A 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_elections
An integer representing the number of elections to generate. A higher number yields higher precision in the output probabilities.
n_ballots
An integer representing the total number of ballots cast in the election.
n_winners
The number of candidates elected in each election.
replace
A 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_threads
The 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_ballots
An 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
)