r2b2.simulator

R2B2 Simulation Module.

Module Contents

class r2b2.simulator.DBInterface(host='localhost', port=27017, name='r2b2', user='reader', pwd='icanread')

Class for handling MongoDB operations.

audit_lookup(self, audit_type: str, alpha: float, qapp: dict = None, *args, **kwargs)

Find/Create an audit in database.

Searches through database for an existing audit entry with the given parameters. If none exists, an audit entry is created for the parameters.

Parameters

• audit_type (str) – Name of audit, for example: ‘minerva’, ‘brla’, etc.

• alpha (float) – Risk-limit of audit.

• qapp (dict) – Optional parameter that appends dict to mongo query.

Returns

ObjectID of new or existing audit entry.

contest_lookup(self, contest: r2b2.contest.Contest, qapp: dict = None, *args, **kwargs)

Find/Create a contest in database.

Searches through database for an existing contest entry with the given parameters. If none exists, a contest entry is created.

Parameters

• contest (r2b2.contest.Contest) – Contest with attributes to be used in the database query.

• qapp (dict) – Optional parameter that appends dict to mongo query.

Returns

ObjectID of new of existing contest entry.

simulation_lookup(self, audit, reported, underlying, invalid, qapp: dict = None, *args, **kwargs)

Find/Create a simulation in database.

Searches through database for an existing simulation entry with the given parameters. If none exists, a simulation entry is created.

Parameters

• audit – ObjectID of audit entry (from audits collection) used in the simulation.

• reported – ObjectID of reported contest entry (from contests collection) used in the simulation.

• underlying – Description of the underlying contest used in the simulation. Could be an ObjectID from the contests table, could simply be a string indicating a tie, depends on the specific simulation.

• qapp (dict) – Optional parameter that appends dict to mongo query.

Returns

ObjectID of new or existing simulation entry.

trial_lookup(self, sim_id, *args, **kwargs)

Find all trials for a given simulation ObjectID

write_trial(self, entry)

Write a trial document into the trials collection.

update_analysis(self, sim_id, entry)

Update analysis in simulation document.

class r2b2.simulator.Simulation(audit_type: str, alpha: float, reported: r2b2.contest.Contest, underlying, invalid: bool, db_mode=True, db_host='localhost', db_port=27017, db_name='r2b2', user='reader', pwd='icanread', *args, **kwargs)

Bases: abc.ABC

Abstract Base Class to define a simulation.

Variables

• db_mode (bool) – Indicates if simulation is running in Database mode or local mode.

• audit_type (str) – Indicates what type of audit is simulated.

• alpha (float) – Risk-limit of simulation.

• audit_id (str) – ObjectID of audit entry from audits collection in MongoDB.

• reported (Contest) – Reported contest results that are audited during simulation.

• reported_id (str) – ObjectID of reported contest entry from contests collection in MongoDB.

• underlying (str) – Indicates the true underlying contest results ballots are drawn from during the simulation. This might be an ObjectID similar to reported_id, it might be a string simply indicating that the underlying distribution is a tie. This field is specified by a specific simulation implementation.

• sim_id (str) – ObjectID of simulation from simulations collection in MongoDB defined by the reported contest, underlying contest, and audit.

• trials – List of trials performed in run() method. Trials are dicts formatted for JSON output or MongoDB document entry.

run(self, n: int)

Execute n trials of the simulation.

Executes n simulation trials by generating a random seed, running a trial with the given seed, and writing the trial entry to the trials collection.

Parameters

n (int) – Number of trials to execute and write to database.

get_seed(self)

Generate a random seed.

Note

This method generates 8 random bytes using os sources of randomness. If a different source of randomness is desired, overwrite the method per implementation.

output(self, fd: str = None)

Write output of simulation to JSON file.

Parameters

fd (str) – filename to write output to. If no file is passed, formatted JSON is simply printed.

output_audit(self)

Create audit output in JSON format.

Note

This functionality is separated into a method so specific audit implementations may override it and customize their output in non-database mode.

abstract trial(self, seed)

Execute a single trial given a random seed.

abstract analyze(self, *args, **kwargs)

Analyze the simulation trials.

r2b2.simulator.histogram(values: List, xlabel: str, bins='auto')

Create a histogram for a given dataset.