votesim.benchmarks.runtools

Tools to facilitate running a generirc voting benchmark, which contains an election model and a parametric assessment of the model.

Class Summary

CaseGenerator(**kwargs)

Generate arguments for input into model.

CreateBenchmark(name, model, case_args)

Base object for creating a benchmark

Reader([pattern, dirname, df])

Read benchmark outputs

Function Summary

benchrun(methods, model, case_args, filename)

param methods

Voter systems to be assessed by the election model.

percentile10

percentile90

Module Classes

CaseGenerator

class votesim.benchmarks.runtools.CaseGenerator(**kwargs)

Generate arguments for input into model. Call the object to generate.

Parameters

**kwargs (dict) – dict of parameters. If the value is iterable, it will be iterated upon using itertools.product

Method/Attribute Summary

CreateBenchmark

class votesim.benchmarks.runtools.CreateBenchmark(name, model, case_args)

Base object for creating a benchmark

Parameters

  • name (str) – Election benchmark name

  • model (func) –

    Election model function where

    >>> election = func(**kwargs)

  • case_args (generator) –

    Argument generator in which produces

    >>>  kwargs = next(generator(methods))

    Where methods is a list of election methods, e.g. [‘plurality’, ‘irv’]

Returns

df – Output data

Return type

DataFrame

Method/Attribute Summary

CreateBenchmark.run(methods[, cpus, …])

Run benchmark

CreateBenchmark.read([pattern, dirname])

Read benchmark output

CreateBenchmark.rerun([series, index, df])

Rerun a specific election using output data

CreateBenchmark.reader

CreateBenchmark.run(methods, cpus=1, filename='', dirname='')

Run benchmark

CreateBenchmark.read(pattern='', dirname='')

Read benchmark output

CreateBenchmark.rerun(series=None, index=None, df=None)

Rerun a specific election using output data

Parameters

  • series (Pandas Series) – Election output data

  • index (int) – Index location of election output data

  • df (Pandas DataFrame) – Dataframe of election output if available.

Returns

out – Election object.

Return type

Election

CreateBenchmark.reader()

Reader

class votesim.benchmarks.runtools.Reader(pattern=None, dirname='', df=None)

Read benchmark outputs

Parameters

  • pattern (str) –

    File name pattern match for module fnmatch. Open all dataframe files with this pattern in the working directory.

    Example – ‘file-*.gz’

  • dirname (str) – Directory containing dataframe files.

Method/Attribute Summary

Reader.parameters

non-random seed parameters

Reader.parameters_etype

Parameters for benchmark name and voting system

Reader.parameters_user

User parameters include all user defined, etype, and election name

Reader.output_keys

Reader.post_data

Retrieve filtered output Pandas DataFrame
Reader.parameters()

list of str : non-random seed parameters

Reader.parameters_etype()

list of str : Parameters for benchmark name and voting system

Reader.parameters_user()

list of str : User parameters include all user defined, etype, and election name

Reader.output_keys()
Reader.post_data()

Retrieve filtered output Pandas DataFrame

Module Functions

benchrun

votesim.benchmarks.runtools.benchrun(methods, model, case_args, filename, cpus=1)
Parameters

  • methods (list of str) – Voter systems to be assessed by the election model.

  • model (func) –

    Election model running function as

    >>> e = func(**kwargs)

    Where

    • e is an Election object

    • kwargs is a dict of arguments generated by case_args

  • case_args (generator) –

    Generator that creates the parametric arguments to input into the model. Must accept argument methods –

    >>> generator = case_args(methods)
>>> args = next(generator)

  • filename (str) – Naming prefix for output files

  • cpus (int) – Number of processes or CPU’s to use

Returns

  • e (Election object) – Base election template, can be used to regenerate election specifics

  • df (Dataframe) – Results for every election iteration assessed

percentile10

percentile90