Package 'pref'

Title: Preference Voting with Explanatory Graphics
Description: Implements the Single Transferable Vote (STV) electoral system, with clear explanatory graphics. The core function stv() uses Meek's method, the purest expression of the simple principles of STV, but which requires electronic counting. It can handle votes expressing equal preferences for subsets of the candidates. A function stv.wig() implementing the Weighted Inclusive Gregory method, as used in Scottish council elections, is also provided, and with the same options, as described in the manual. The required vote data format is as an R list: a function pref.data() is provided to transform some commonly used data formats into this format. References for methodology: Hill, Wichmann and Woodall (1987) <doi:10.1093/comjnl/30.3.277>, Hill, David (2006) <https://www.votingmatters.org.uk/ISSUE22/I22P2.pdf>, Mollison, Denis (2023) <arXiv:2303.15310>, (see also the package manual pref_pkg_manual.pdf).
Authors: Denis Mollison [aut, cre, cph]
Maintainer: Denis Mollison <[email protected]>
License: MIT + file LICENSE
Version: 0.4.0
Built: 2025-02-21 05:00:33 UTC
Source: https://github.com/denismollison/pref

Help Index

Example of an election of an academic organisation using STV allowing equal preferences frelection om an

Description

Votes are in a ballot-format matrix

Usage

c99

Format

A list with 10 variables, largest the vote matrix (343 x 10)

q()

s

number of seats

c

number of candidates

...

Example of a political STV election - Cumnock and New Cumnock 2017

Description

Votes are in a ballot-format matrix

Usage

cnc17

Format

A list with 10 variables, largest the vote matrix (930 x 8)

s

number of seats

c

number of candidates

...

Source

https://www.macs.hw.ac.uk/~denis/stv_elections/SC2017/

Unusually simple example of a political STV election - Helensburgh Central 2012

Description

Votes are in a ballot-format matrix

Usage

hc12

Format

A list with 10 variables, largest the vote matrix (629 x 6)

s

number of seats

c

number of candidates

...

Source

https://www.macs.hw.ac.uk/~denis/stv_elections/SC2012/

Example of an STV election allowing equal preferences - John Muir Trust 2002

Description

Votes are in a ballot-format matrix

Usage

j02

Format

A list with 10 variables, largest the vote matrix (1168 x 10)

q()

s

number of seats

c

number of candidates

...

Source

https://www.macs.hw.ac.uk/~denis/stv_elections/jmt2002.blt

Example of a political STV election - North West and Central Sutherland 2017 Unusual in that under WIG no candidate reaches the (fixed) quota

Description

Votes are in a ballot-format matrix

Usage

nws17

Format

A list with 10 variables, largest the vote matrix (629 x 6)

s

number of seats

c

number of candidates

...

Source

https://www.macs.hw.ac.uk/~denis/stv_elections/SC2017/

Example of a political STV election - Partick 2017

Description

Votes are in a ballot-format matrix

Usage

p17

Format

A list with 10 variables, largest the vote matrix (1456 x 8)

s

number of seats

c

number of candidates

...

Source

https://www.macs.hw.ac.uk/~denis/stv_elections/SC2017/

put election data in an R file (.rda)

Description

put election data in an R file (.rda)

Usage

pref.data(
  datafile,
  mult = FALSE,
  details = TRUE,
  parties = FALSE,
  ballot = FALSE,
  friendly = FALSE,
  header = FALSE
)

Arguments

datafile

File with election data
mult

Whether includes aggregated votes (default FALSE)
details

Whether full election detail (default) or just vote matrix
parties

File with party details (default FALSE, i.e. omit)
ballot

Default FALSE (meaning pref format)
friendly

Default FALSE (meaning most details after votes)
header

Whether a vote matrix has a header

Value

A standardised list of election info to save in a .rda file; for details see manual pref_pkg_manual.pdf (section 4)

Examples

datafile=system.file("extdata","yale.dat",package="pref")
yale=pref.data(datafile,details=FALSE)
datafile=system.file("extdata","Jedburgh2012.blt",package="pref")
parties12=system.file("extdata","parties_SC2012.txt",package="pref")
jed12=pref.data(datafile,mult=TRUE,parties=parties12)
datafile=system.file("extdata","jmt2002.blt",package="pref")
j02=pref.data(datafile,friendly=TRUE)

STV election count - uses Meek STV, allows equal preferences

Description

STV election count - uses Meek STV, allows equal preferences

Usage

stv(
  votedata,
  outdirec = tempdir(),
  plot = TRUE,
  webdisplay = FALSE,
  interactive = FALSE,
  messages = TRUE,
  timing = FALSE,
  map = FALSE
)

Arguments

votedata

File with vote data
outdirec

Needs to be set for permanent record of results
plot

If =TRUE (default) produces plots of count and webpages in outdirec
webdisplay

If =TRUE displays plots and statistics as web pages
interactive

If =TRUE reports and pauses at each stage of the count (press return to continue to next stage)
messages

If=TRUE prints 1-line initial and final reports
timing

Whether to report computing time at each stage
map

Link to a map or other URL associated with election

Value

A list containing vote and count data, + optional web pages; for details see manual pref_pkg_manual.pdf (section 3)

Examples

cnc17meek=stv(cnc17,plot=FALSE)
c99result=stv(c99,plot=FALSE)
y12meek=stv(y12,plot=FALSE)

Makes webpage plots of result of an STV election

Description

Makes webpage plots of result of an STV election

Usage

stv.plots(elecdata, outdirec = tempdir(), webdisplay = FALSE, map = FALSE)

Arguments

elecdata

An R list of results from stv or stv.wig
outdirec

A directory for web page output
webdisplay

If TRUE displays the main output web page
map

A possible extra showing map of election location

Value

Webpages with plots of election count and results

Examples

c99result=stv(c99)
c99plots=stv.plots(c99result)
nws17wig=stv.wig(nws17)
nws17plots=stv.plots(nws17wig)

STV election count using WIG as for Scottish Council elections calculated to 5 places of decimals as used for those elections

Description

STV election count using WIG as for Scottish Council elections calculated to 5 places of decimals as used for those elections

Usage

stv.wig(
  votedata,
  outdirec = tempdir(),
  plot = TRUE,
  webdisplay = FALSE,
  interactive = FALSE,
  messages = TRUE,
  timing = FALSE,
  map = FALSE
)

Arguments

votedata

File with vote data
outdirec

Needs to be set for permanent record of results (press return to continue to next stage)
plot

If =TRUE (default) produces plots of count and webpages in outdirec
webdisplay

If =TRUE displays plots and statistics as web pages
interactive

If =TRUE reports and pauses at each stage of the count
messages

If=TRUE prints 1-line initial and final reports
timing

Whether to report computing time at each stage
map

Link to a map or other URL associated with election

Value

A list containing votes at each stage, + optional web pages; for details see manual pref_pkg_manual.pdf (section 3)

Examples

hc12wig=stv.wig(hc12,plot=FALSE,messages=FALSE)
nws17wig=stv.wig(nws17,plot=FALSE)
p17wig=stv.wig(p17,plot=FALSE)
cnc17wig=stv.wig(cnc17,plot=FALSE,timing=TRUE)

Example of an STV election - Yale faculty election (last 12)

Description

Votes are in a ballot-format matrix

Usage

y12

Format

A list with 10 variables, largest the vote matrix (424 x 44)

s

number of seats

c

number of candidates

...

Source

https://cran.r-project.org/package=STV