Type: Package
Title: Implementation of Voting Rules Electing the Candidate with Highest Median Grade
Version: 1.0
Description: Computes the scores and ranks candidates according to voting rules electing the highest median grade. Based on "Tie-breaking the highest median: alternatives to the majority judgment", A. Fabre, Social Choice & Welfare (forthcoming as of 2020). The paper is available here: https://github.com/bixiou/highest_median/raw/master/Tie-breaking%20Highest%20Median%20-%20Fabre%202019.pdf. Functions to plot the voting profiles can be found on github: https://github.com/bixiou/highest_median/blob/master/packages_functions_data.R.
License: AGPL-3
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.0.2.9000
Imports: RMallow
NeedsCompilation: no
Packaged: 2020-03-06 10:27:19 UTC; adrien
Author: Adrien Fabre [aut, cre]
Maintainer: Adrien Fabre <fabre.adri1@gmail.com>
Repository: CRAN
Date/Publication: 2020-03-14 15:30:10 UTC

Aggregate scores

Description

Aggregator of scores: returns a vector with the score of each row (i.e. candidate) in a matrix (i.e. the voting profile). See function 'score'.

Usage

aggregate_scores(
  grades,
  rule = "mj",
  k = 0.5,
  scale = c(),
  names = row.names(grades),
  print = FALSE,
  return_text = FALSE,
  rounds = 3
)

Arguments

grades

A voting profile, i.e. a matrix with the shares of grades of each candidate on each row, from the lowest grade to the highest.

rule

The voting rule to be used. Default to 'mj'. Possible values: 'mj' (majority judgment), 'd' (difference), 's' (relative share), 'n' (normalized difference), 'mean' (range voting). For more details, see "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

k

The quantile used to compute the gauge. Default to 0.5 (the median). For more details, see paragraph Extensions in 3.2.1 of "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

scale

A numeric vector containing the values of the scale of grades. Default to c((floor(-length(grades)/2)+1):(length(grades)+floor(-length(grades)/2))).

names

String vector, each string to be printed along the gauges in case print = TRUE and return_text = FALSE. Defaults to "".

print

Prints the gauges and the argument 'names'. Default to FALSE

return_text

Prints the gauges. Defaults to FALSE.

rounds

Number of rounding digits. Default to 3.

Value

A double vector or a character vector. The scores (double) if return_text = FALSE, the gauges (character) otherwise.

Examples

aggregate_scores(elec2012, rule='d', scale=-2:4)

Example voting profile

Description

Matrix containing the shares of grades (in -2:4) of candidates on each row. Taken from Balinski & Laraki (2016), "Majority Judgment vs Majority Rule" p. 14. Grades given by a non-representative sample of 737 voters for the 2012 French presidential election.

Usage

elec2012

Format

An object of class matrix with 10 rows and 7 columns.

Gauge

Description

This function returns a custom description of the grades of a candidate in terms of the shares of proponents (p), opponents (q), median grades (g), and the gauge (i.e. the median grade followed by + or -, a + corresponding to a larger share of proponents than opponents).

Usage

gauge(grades, k = 0.5, scale = c(), return = "qp")

Arguments

grades

A numeric vector containing the shares of each grades of a candidate, from the lowest grade to the highest.

k

The quantile used to compute the gauge. Default to 0.5 (the median). For more details, see paragraph Extensions in 3.2.1 of "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

scale

A numeric vector containing the values of the scale of grades. Default to c((floor(-length(grades)/2)+1):(length(grades)+floor(-length(grades)/2))).

return

A string containing the information to return. Default to 'qp' (shares of opponents and proponents). Possible values: 'g', 'p', 'q', 'pq', 'qp', 'qpg', 'pqg', 'gpq', 'gqp', 'text' (i.e. the gauge), 'all'. If the string does not match one of the above, 'all' is returned.

Value

A double, a character vector or a double vector. Depending on what is passed in return.

Examples

gauge(elec2012['Hollande',], return = 'gqp')

Gauges

Description

Aggregator of 'gauge': returns the gauge of each row (i.e. candidate) from a matrix (i.e. the voting profile). See function 'gauge'.

Usage

gauges(grades, k = 0.5, scale = c(), return = "qp")

Arguments

grades

A numeric vector containing the shares of each grades of a candidate, from the lowest grade to the highest.

k

The quantile used to compute the gauge. Default to 0.5 (the median). For more details, see paragraph Extensions in 3.2.1 of "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

scale

A numeric vector containing the values of the scale of grades. Default to c((floor(-length(grades)/2)+1):(length(grades)+floor(-length(grades)/2))).

return

A string containing the information to return. Default to 'qp' (shares of opponents and proponents). Possible values: 'g', 'p', 'q', 'pq', 'qp', 'qpg', 'pqg', 'gpq', 'gqp', 'text' (i.e. the gauge), 'all'. If the string does not match one of the above, 'all' is returned.

Value

An array with as many columns as elements of grades, with the return of gauge in each column.

Examples

gauges(grades = elec2012, return = 'gqp')

Ranking

Description

Returns a matrix with the scores of candidates sorted in decreasing order, for a given voting rule.

Usage

ranking(
  grades,
  rule = "mj",
  k = 0.5,
  scale = c(),
  names = row.names(grades),
  print = FALSE
)

Arguments

grades

A voting profile, i.e. a matrix with the shares of grades of each candidate on each row, from the lowest grade to the highest.

rule

The voting rule to be used. Default to 'mj'. Possible values: 'mj' (majority judgment), 'd' (difference), 's' (relative share), 'n' (normalized difference), 'mean' (range voting). For more details, see "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

k

The quantile used to compute the gauge. Default to 0.5 (the median). For more details, see paragraph Extensions in 3.2.1 of "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

scale

A numeric vector containing the values of the scale of grades. Default to c((floor(-length(grades)/2)+1):(length(grades)+floor(-length(grades)/2))).

names

String vector, each string to be printed in case print = TRUE. Defaults to c().

print

Prints the argument 'names'. Default to FALSE

Value

A character matrix with as many rows as elements of grades, and with the name, gauge and score (according to rule) on each row.

Examples

ranking(elec2012, rule='d', scale=-2:4)

Rankings

Description

Returns a matrix with the scores of candidates sorted in decreasing order of score mj, for the five following voting rules (with k=0.5): mj, d, s, n, mean. See function 'score' for more details.

Usage

rankings(
  grades,
  scale = c(),
  names = row.names(grades),
  return_distance = FALSE,
  rounds = TRUE
)

Arguments

grades

A voting profile, i.e. a matrix with the shares of grades of each candidate on each row, from the lowest grade to the highest.

scale

A numeric vector containing the values of the scale of grades. Default to c((floor(-length(grades)/2)+1):(length(grades)+floor(-length(grades)/2))).

names

String vector, each string to be printed in case print = TRUE. Defaults to c().

return_distance

If TRUE, returns the Kendall distance between the rules (using AllKendall) instead of the matrix of scores. Default to FALSE.

rounds

If TRUE, rounds the scores (to 3 digits for highest median rules and 2 digits for range voting). Default to TRUE.

Value

A character matrix with as many rows as elements of grades, and with the name, gauge and scores (according to five different rules) on each row.

Examples

rankings(elec2012, scale=-2:4)

Score

Description

This function returns the score of a candidate, using a custom voting rule.

Usage

score(
  rule = "mj",
  grades = elec2012["Hollande", ],
  k = 0.5,
  scale = c(),
  name = "",
  print = TRUE,
  return_text = FALSE
)

Arguments

rule

The voting rule to be used. Default to 'mj'. Possible values: 'mj' (majority judgment), 'd' (difference), 's' (relative share), 'n' (normalized difference), 'mean' (range voting). For more details, see "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

grades

A numeric vector containing the shares of each grades of a candidate, from the lowest grade to the highest.

k

The quantile used to compute the gauge. Default to 0.5 (the median). For more details, see paragraph Extensions in 3.2.1 of "Tie-Breaking the Highest Median", Fabre, Social Choice & Welfare (forthcoming).

scale

A numeric vector containing the values of the scale of grades. Default to c((floor(-length(grades)/2)+1):(length(grades)+floor(-length(grades)/2))).

name

Text to be printed along the gauge in case print = TRUE and return_text = FALSE. Defaults to "".

print

Prints the gauge and the argument 'name'. Default to TRUE.

return_text

Prints the gauge. Defaults to FALSE. The gauge is less informative than the score, it is the median grade and + if there are grades higher than the median than lower, - otherwise.

Value

A double or a character. The score (a double) if return_text = FALSE, the gauge (a character) otherwise.

Examples

score(rule='d', elec2012['Hollande',], scale=-2:4, name="Hollande")