PathBidPriceTracer

class passengersim.callbacks.builtins.PathBidPriceTracer(path_ids: list[int], *, priority: int = 1, name: str | None = None)[source]

Bases: _BidPriceTracer

A daily tracer that records the bid prices for specified paths.

At each day, the total bid price for each tracked path is captured and accumulated using a Welford online estimator, so that the mean and standard deviation across simulation samples can be computed efficiently.

Initialize the tracer.

Parameters:
path_ids : list[int]

IDs of the paths whose bid prices should be tracked.

priority : int, optional

Daily offset in seconds from the overnight trigger. Negative values run before the simulation’s daily bookkeeping, positive values after it; zero is not allowed. Defaults to 1.

name : str, optional

Key for the results in callback_data. Defaults to the class name, ‘path_bid_prices’; give a different name to attach two of these tracers to one simulation.

Methods

__init__(path_ids, *[, priority, name])

Initialize the tracer.

attach(sim)

Attach a fresh copy of this tracer to a simulation, on all its hooks.

finalize()

Aggregate accumulated Welford statistics into a tidy DataFrame.

fresh()

Return a fresh copy of this tracer, tracing the same targets but not sharing state.

on_begin_sample(sim)

Observe a sample after its first DCP, before any customer arrives.

on_daily(sim, days_prior)

Observe each day of a sample.

on_end_sample(sim)

Observe the end of a sample, before counters are reset.

on_finalize_sample(sim)

Observe a sample after its events and bookkeeping have finished.

on_initialize_sample(sim)

Observe the start of a sample, before its demand is generated.

reset()

Reset all accumulated bid-price data to empty Welford accumulators.

setup(sim)

Prepare to trace a run, once its scenario has been built.

Attributes

hook

Lifecycle hook shared by manual and configured attachment.

name

Identifier used to store results in SimulationTables.callback_data.

options_model

Pydantic model of the constructor's keyword options, for configured callbacks.

options_version

Version 2 added the n statistic and exact pooling of std_dev.

skip_burn

Burn-in samples are not recorded.

bid_prices

Nested mapping of entity-ID → days-prior → Welford accumulator.

name : str = 'path_bid_prices'

Identifier used to store results in SimulationTables.callback_data.

__init__(path_ids: list[int], *, priority: int = 1, name: str | None = None)[source]

Initialize the tracer.

Parameters:
path_ids : list[int]

IDs of the paths whose bid prices should be tracked.

priority : int, optional

Daily offset in seconds from the overnight trigger. Negative values run before the simulation’s daily bookkeeping, positive values after it; zero is not allowed. Defaults to 1.

name : str, optional

Key for the results in callback_data. Defaults to the class name, ‘path_bid_prices’; give a different name to attach two of these tracers to one simulation.

attach(sim: Simulation) → None

Attach a fresh copy of this tracer to a simulation, on all its hooks.

Parameters:
sim : Simulation or MultiSimulation or Experiments

The object to attach to. The simulation stores a copy made with fresh(), so this tracer object itself is never modified by a run and can be attached to several simulations.

Raises:

TypeError – If the tracer declares no hook and overrides no hook method.

finalize() → DataFrame

Aggregate accumulated Welford statistics into a tidy DataFrame.

Returns:

pd.DataFrame – A DataFrame with a MultiIndex of (statistic, days_prior) and one column per tracked entity. The statistic level holds mean, std_dev (the sample standard deviation, missing for a cell observed only once), and n (the number of observations in each cell). The DataFrame attrs n_trials (the number of trials observed) and aggregation_process ("pooled_moments") are set for downstream aggregation.

fresh() → GenericTracer

Return a fresh copy of this tracer, tracing the same targets but not sharing state.

The default makes a deep copy of this tracer and then calls reset() on the copy. Override it if a tracer holds something that cannot be deep-copied, or that is expensive to copy.

Returns:

GenericTracer – A new tracer of the same type and configuration, with no accumulated data.

hook : ClassVar[Literal['begin_sample', 'daily', 'end_sample']] = 'daily'

Lifecycle hook shared by manual and configured attachment.

on_begin_sample(sim: Simulation) → dict | None

Observe a sample after its first DCP, before any customer arrives.

Override this to attach the tracer to the begin_sample hook. Its time is set by the tracer’s priority attribute, if it has one, as for a plain begin-sample callback.

Parameters:
sim : Simulation

The running simulation.

on_daily(sim: Simulation, days_prior: int) → dict | None

Observe each day of a sample.

Override this to attach the tracer to the daily hook. The time of day is set by the tracer’s priority attribute, if it has one, as for a plain daily callback.

Parameters:
sim : Simulation

The running simulation.

days_prior : int

Days remaining before departure.

on_end_sample(sim: Simulation) → dict | None

Observe the end of a sample, before counters are reset.

Override this to attach the tracer to the end_sample hook. Its time is set by the tracer’s priority attribute, if it has one, as for a plain end-sample callback.

Parameters:
sim : Simulation

The running simulation.

on_finalize_sample(sim: Simulation) → dict | None

Observe a sample after its events and bookkeeping have finished.

Override this to attach the tracer to the finalize_sample hook.

Parameters:
sim : Simulation

The running simulation.

on_initialize_sample(sim: Simulation) → dict | None

Observe the start of a sample, before its demand is generated.

Override this to attach the tracer to the initialize_sample hook. A returned dictionary is stored under callback_data.initialize_sample, as for a plain callback.

Parameters:
sim : Simulation

The running simulation.

options_model : ClassVar[type[BaseModel] | None] = None

Pydantic model of the constructor’s keyword options, for configured callbacks.

By default, registration derives the model from the annotated constructor.

options_version : ClassVar[str] = '2'

Version 2 added the n statistic and exact pooling of std_dev.

Version 1 tables averaged standard deviations across trials.

reset() → None

Reset all accumulated bid-price data to empty Welford accumulators.

setup(sim: Simulation) → None

Prepare to trace a run, once its scenario has been built.

Called once per run (run or run_trial), after reset() and after the simulation has built its network, fares, and demands, but before the first sample. Override it to look up what the tracer will observe and to allocate its accumulators, so that problems are reported before the run starts. The default does nothing.

An exception raised here stops the run; nothing is finalized, and the next run starts from a fresh reset.

Parameters:
sim : Simulation

The simulation about to run.

skip_burn : ClassVar[bool] = True

Burn-in samples are not recorded.

bid_prices : dict[int, dict[int, Welford]]

Nested mapping of entity-ID → days-prior → Welford accumulator.