egttools.numerical.estimators

Python wrapper classes for egttools MC estimators.

These wrappers add three things the underlying C++ classes do not provide:

  1. Rich result objects — every method returns a typed dataclass (FixationResult, StrategyDistributionResult, …) that carries the point estimate, standard error, 95 % CI, and prints a readable summary.

  2. Optional progress bar — pass verbose=1 to any estimation method and a tqdm progress bar is shown over the internal chunks. tqdm is an optional dependency; if it is absent the call runs silently.

  3. Optional checkpointing — pass checkpoint_path=<file> to any estimation method and progress is persisted to disk after every chunk (atomically, so a kill mid-write can’t corrupt it). If the same checkpoint_path is passed again with identical parameters, the call resumes from the last completed chunk instead of starting over — useful for long runs on clusters with job time limits. Resuming is statistically independent (never repeats a chunk’s random draws) and, if egttools.Random state capture succeeds, bit-exact — see egttools.Random.get_state/set_state. Passing a checkpoint_path with parameters that don’t match an existing checkpoint raises rather than silently resuming incorrectly. The checkpoint file is removed once the call completes normally, so a later call with the same path starts fresh again.

The wrappers use chunked execution: nb_runs is split into n_chunks equal pieces, each piece runs as a single C++ call, and the SE is computed as std(chunk_means) / sqrt(n_chunks). This gives SE estimates for methods that otherwise return only a point estimate (e.g. PairwiseComparisonNumerical.estimate_fixation_probability), and doubles as the natural checkpoint boundary described above.

All other attributes and methods of the underlying C++ object are accessible directly via __getattr__, so these wrappers are drop-in replacements.

Classes

AGoSResult

Average gradient of selection G^A(x) from a network MC estimator.

AbsorptionProbabilityResult

Per-strategy fixation (absorption) probabilities.

AbsorptionTimeResult

Mean absorption (fixation) time from a given initial state.

FixationResult

Fixation probability of an invading strategy into a resident population.

NetworkEstimator

Wraps any NetworkMCEstimator* C++ instance and returns rich result objects with optional progress bars.

PairwiseComparisonEstimator

Wraps egttools.numerical.PairwiseComparisonNumerical and returns rich result objects with standard errors and optional progress bars.

StationaryDistributionResult

Estimated stationary distribution over population states.

StrategyDistributionResult

Time-averaged strategy frequencies with uncertainty.