dirichlet_tree: Create a Dirichlet-tree for modelling ranked ballots

In fleverest/dirtree-elections: Ranked Voting Election Audits with Dirichlet-Trees

Create a Dirichlet-tree for modelling ranked ballots

Description

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 \insertCitedtree_evoteid;textualelections.dtree. 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.

Format

An R6Class generator object.

Active bindings

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.

Methods

Public methods

• dirichlet_tree$new()

• dirichlet_tree$print()

• dirichlet_tree$update()

• dirichlet_tree$reset()

• dirichlet_tree$sample_posterior()

• dirichlet_tree$sample_predictive()

---

Method new()

Create a new dirichlet_tree prior distribution with the specified tree structure. See \insertCitedtree_evoteid;textualelections.dtree for further details.

Usage

dirichlet_tree$new(
  candidates,
  min_depth = 0,
  max_depth = length(candidates) - 1,
  a0 = 1,
  vd = FALSE
)

Arguments

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 \insertCitedtree_evoteid;textualelections.dtree.

Returns

A new dirichlet_tree prior.

Examples

dtree <- dirichlet_tree$new(candidates = LETTERS, a0 = 1., min_depth = 1)

---

Method print()

print shows some details of the distribution and its parameters.

Usage

dirichlet_tree$print()

Returns

The dirichlet_tree object.

---

Method 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 \insertCitedtree_evoteid;textualelections.dtree.

Usage

dirichlet_tree$update(ballots)

Arguments

ballots

A set of ballots of class 'prefio::preferences' or 'prefio::aggregated_preferences' to observe. The ballots should not contain any ties, but they may be incomplete.

Returns

The dirichlet_tree object.

Examples

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dirichlet_tree$new(
  candidates = LETTERS[1:3]
)$update(ballots)

---

Method reset()

Resets the dirichlet_tree observations to revert the parameter structure back to the originally specified prior.

Usage

dirichlet_tree$reset()

Returns

The dirichlet_tree object.

Examples

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dtree <- dirichlet_tree$new(
  candidates = LETTERS
)$update(ballots)
print(dtree)
dtree$reset()
print(dtree)

---

Method 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 \insertCitedtree_evoteid;textualelections.dtree for details.

Usage

dirichlet_tree$sample_posterior(
  n_elections,
  n_ballots,
  n_winners = 1,
  replace = FALSE,
  n_threads = NULL
)

Arguments

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.

Returns

A numeric vector containing the probabilities for each candidate being elected.

Examples

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dirichlet_tree$new(
  candidates = LETTERS,
  a0 = 1.,
  min_depth = 3,
  max_depth = 6,
  vd = FALSE
)$update(
  ballots
)$sample_posterior(
  n_elections = 10,
  n_ballots = 10
)

---

Method 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 \insertCitedtree_evoteid;textualelections.dtree for details.

Usage

dirichlet_tree$sample_predictive(n_ballots)

Arguments

n_ballots

An integer representing the total number of ballots cast in the election.

Returns

A prefio::preferences object containing n_ballots ballots drawn from a single realisation of the posterior Dirichlet-tree.

Examples

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dirichlet_tree$new(
  candidates = LETTERS,
  a0 = 1.,
  min_depth = 3,
  max_depth = 6,
  vd = FALSE
)$update(
  ballots
)$sample_predictive(
  n_ballots = 10
)

References

\insertRef

dtree_eiselections.dtree.

\insertRef

dtree_evoteidelections.dtree.

Examples

## ------------------------------------------------
## Method `dirichlet_tree$new`
## ------------------------------------------------

dtree <- dirichlet_tree$new(candidates = LETTERS, a0 = 1., min_depth = 1)


## ------------------------------------------------
## Method `dirichlet_tree$update`
## ------------------------------------------------

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dirichlet_tree$new(
  candidates = LETTERS[1:3]
)$update(ballots)


## ------------------------------------------------
## Method `dirichlet_tree$reset`
## ------------------------------------------------

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dtree <- dirichlet_tree$new(
  candidates = LETTERS
)$update(ballots)
print(dtree)
dtree$reset()
print(dtree)


## ------------------------------------------------
## Method `dirichlet_tree$sample_posterior`
## ------------------------------------------------

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dirichlet_tree$new(
  candidates = LETTERS,
  a0 = 1.,
  min_depth = 3,
  max_depth = 6,
  vd = FALSE
)$update(
  ballots
)$sample_posterior(
  n_elections = 10,
  n_ballots = 10
)


## ------------------------------------------------
## Method `dirichlet_tree$sample_predictive`
## ------------------------------------------------

ballots <- prefio::preferences(
  t(c(1, 2, 3)),
  format = "ranking",
  item_names = LETTERS[1:3]
)
dirichlet_tree$new(
  candidates = LETTERS,
  a0 = 1.,
  min_depth = 3,
  max_depth = 6,
  vd = FALSE
)$update(
  ballots
)$sample_predictive(
  n_ballots = 10
)

fleverest/dirtree-elections documentation built on Sept. 21, 2023, 8:33 p.m.