r2b2.simulation.minerva

Module Contents

class r2b2.simulation.minerva.MinervaOneRoundRisk(alpha, reported, sample_size, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a 1-round Minerva audit for a given sample size to compute risk limit.

trial(self, seed)

Execute a 1-round minerva audit (using r2b2.minerva.Minerva)

analyze(self, verbose: bool = False, hist: bool = False)

Analyze trials to get experimental risk.

Parameters

• verbose (bool) – If true, analyze will print simulation analysis information.

• hist (bool) – If true, analyze will generate and display 2 histograms: winner ballots found in the sample size and computed risk.

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.

class r2b2.simulation.minerva.MinervaOneRoundStoppingProb(alpha, reported, sample_size, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a 1-round Minerva audit for a given sample size to compute stopping probability.

trial(self, seed)

Execute a 1-round minerva audit.

analyze(self, verbose: bool = False, hist: bool = False)

Analyse trials to get experimental stopping probability

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.

class r2b2.simulation.minerva.MinervaOneRoundAlteredMargin(alpha, reported, underlying, underlying_margin, sample_size, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a 1-round Minerva audit for a given sample size with a correct outcome but incorrect reported margin

trial(self, seed)

Execute a 1-round minerva audit.

analyze(self, verbose: bool = False, hist: bool = False)

Analyse trials to get experimental stopping probability

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.

class r2b2.simulation.minerva.MinervaMultiRoundStoppingProb(alpha, reported, max_rounds, sample_size=None, sample_mult=None, sample_sprob=None, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a multi-round Minerva audit.

If sample_sprob is provided, sample sizes to achieve a sample_sprob probability of stopping will be computed and used. Otherwise, the initial sample size, sample_size, is given as input and further sample sizes are an additional (sample_mult) * (sample_size) ballots. The audit executes until it stops or reaches the maximum number of rounds.

trial(self, seed)

Execute a multiround minerva audit (using r2b2.minerva.Minerva)

analyze(self, verbose: bool = False, hist: bool = False)

Analyze trials to get experimental stopping probability.

Parameters

• verbose (bool) – If true, analyze will print simulation analysis information.

• hist (bool) – If true, analyze will generate and display 2 histograms: winner ballots found in the sample size and computed stopping probability.

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.

class r2b2.simulation.minerva.MinervaMultiRoundRisk(alpha, reported, max_rounds, sample_size=None, sample_mult=None, sample_sprob=None, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a multi-round Minerva audit.

If sample_sprob is provided, sample sizes to achieve a sample_sprob probability of stopping will be computed and used. Otherwise, the initial sample size, x, is given as input and further sample sizes are an additional (sample_mult) * x ballots. The audit executes until it stops or reaches the maximum number of rounds.

trial(self, seed)

Execute a multiround minerva audit (using r2b2.minerva.Minerva)

analyze(self, verbose: bool = False, hist: bool = False)

Analyze trials to get experimental risk.

Parameters

• verbose (bool) – If true, analyze will print simulation analysis information.

• hist (bool) – If true, analyze will generate and display 2 histograms: winner ballots found in the sample size and computed risk.

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.

class r2b2.simulation.minerva.MinervaRandomMultiRoundRisk(alpha, reported, sample_size, max_rounds, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a multi-round Minerva audit for random subsequent sample sizes.

The initial sample size, x, is given as input and further sample sizes are chosen randomly as an additioanl 0.5x to 1.5x ballots in the next round. The audit executes until it stops or reaches the maximum number of rounds.

trial(self, seed)

Execute a 1-round minerva audit (using r2b2.minerva.Minerva)

analyze(self, verbose: bool = False, hist: bool = False)

Analyze trials to get experimental risk.

Parameters

• verbose (bool) – If true, analyze will print simulation analysis information.

• hist (bool) – If true, analyze will generate and display 2 histograms: winner ballots found in the sample size and computed risk.

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.

class r2b2.simulation.minerva.MinervaRandomMultiRoundStoppingProb(alpha, reported, sample_size, max_rounds, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a multi-round Minerva audit for random subsequent sample sizes.

The initial sample size, x, is given as input and further sample sizes are chosen randomly as an additioanl 0.5x to 1.5x ballots in the next round. The audit executes until it stops or reaches the maximum number of rounds.

trial(self, seed)

Execute a 1-round minerva audit (using r2b2.minerva.Minerva)

analyze(self, verbose: bool = False, hist: bool = False)

Analyze trials to get experimental risk.

Parameters

• verbose (bool) – If true, analyze will print simulation analysis information.

• hist (bool) – If true, analyze will generate and display 2 histograms: winner ballots found in the sample size and computed risk.

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.

class r2b2.simulation.minerva.MinervaMultiRoundAlteredMargin(alpha, reported, underlying, underlying_margin, sample_size, max_rounds, db_mode=True, db_host='localhost', db_name='r2b2', db_port=27017, user='writer', pwd='icanwrite', *args, **kwargs)

Bases: r2b2.simulator.Simulation

Simulate a Minerva audit for a given sample size with a correct outcome but incorrect reported margin

trial(self, seed)

Execute a multiround minerva audit.

analyze(self, verbose: bool = False, hist: bool = False)

Analyse trials to get experimental stopping probability

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.