LegBidPriceArrayTracer¶
-
class passengersim.tracers.bid_price.LegBidPriceArrayTracer(leg_ids: list[int], *, priority: int =
1, name: str | None =None)[source]¶ Bases:
GenericTracerA begin-sample tracer that records the entire bid-price arrays for specified legs.
The full bid-price array (seats-sold × days-prior) is captured at the start of each simulation sample and accumulated using a Welford online estimator. Note that because this tracer is called at the beginning of each sample, it does not reflect bid-price updates that occur during the sample (e.g., due to changes in displacement costs).
Initialize the tracer.
- Parameters:
- leg_ids : list[int]¶
IDs of the legs whose bid-price arrays should be tracked.
- priority : int, optional¶
Offset in seconds from the first DCP’s trigger time at which the arrays are captured; see
begin_sample_callback(). The default of 1 captures them after the first DCP’s RM steps.- name : str, optional¶
Key for the results in
callback_data. Defaults to the class name, ‘leg_bid_price_arrays’; give a different name to attach two of these tracers to one simulation.
Methods
__init__(leg_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 array data to empty Welford accumulators.
setup(sim)Prepare to trace a run, once its scenario has been built.
Attributes
Lifecycle hook shared by manual and configured attachment.
Identifier used to store results in
SimulationTables.callback_data.Pydantic model of the constructor's keyword options, for configured callbacks.
Configured-callback implementation version; bump when results change meaning.
Burn-in samples are not recorded.
Mapping of leg-ID → Welford accumulator over the full bid-price array.
-
name : str =
'leg_bid_price_arrays'¶ Identifier used to store results in
SimulationTables.callback_data.
- bid_price_arrays : dict[int, Welford]¶
Mapping of leg-ID → Welford accumulator over the full bid-price array.
-
hook : ClassVar[Literal['begin_sample', 'daily', 'end_sample']] =
'begin_sample'¶ Lifecycle hook shared by manual and configured attachment.
-
skip_burn : ClassVar[bool] =
True¶ Burn-in samples are not recorded.
-
__init__(leg_ids: list[int], *, priority: int =
1, name: str | None =None)[source]¶ Initialize the tracer.
- Parameters:
- leg_ids : list[int]¶
IDs of the legs whose bid-price arrays should be tracked.
- priority : int, optional¶
Offset in seconds from the first DCP’s trigger time at which the arrays are captured; see
begin_sample_callback(). The default of 1 captures them after the first DCP’s RM steps.- name : str, optional¶
Key for the results in
callback_data. Defaults to the class name, ‘leg_bid_price_arrays’; give a different name to attach two of these tracers to one simulation.
- finalize() DataFrame[source]¶
Aggregate accumulated Welford statistics into a tidy DataFrame.
- Returns:
pd.DataFrame – A DataFrame indexed by
(leg_id, SeatsSold)with columns representing days-prior values, containing the mean bid price at each cell. The DataFrame attrsn_trials(the number of trials observed) andaggregation_processare set for downstream aggregation.
- 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.
- 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.
- 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_samplehook. Its time is set by the tracer’spriorityattribute, 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
dailyhook. The time of day is set by the tracer’spriorityattribute, 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_samplehook. Its time is set by the tracer’spriorityattribute, 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_samplehook.- 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_samplehook. A returned dictionary is stored undercallback_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] =
'1'¶ Configured-callback implementation version; bump when results change meaning.
- setup(sim: Simulation) None¶
Prepare to trace a run, once its scenario has been built.
Called once per run (
runorrun_trial), afterreset()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.