SegmentationTracer¶
-
class passengersim.tracers.segmentation.SegmentationTracer(markets: list[tuple[str, str] | str] | None =
None, *, carriers: list[str] | None =None, segments: list[str] | None =None, priority: int =1, name: str | None =None)[source]¶ Bases:
GenericTracerA daily tracer recording sales and revenue by segment at each DCP.
At every DCP of every post-burn sample, the cumulative (since the start of the sample) sales and realized revenue of each selected fare are read for each demand segment, using the bulk accessor
SimulationEngine.fare_segment_counters(), and added into in-memory accumulators. Nothing is written to the database.The finalized table is stored in
summary.callback_data["segmentation_detail"]and is most conveniently accessed viasegmentation_detail_traced()(also available as thesegmentation_detail_tracedproperty on summary objects).Notes
Fares sharing the same carrier, market and booking class (e.g. different brands or points of sale) are summed together in the output.
Memory used during the run is proportional to (number of selected fares) x (number of DCPs) x (number of segments); use the markets and/or carriers filters to keep this small on large networks.
Initialize the tracer.
- Parameters:
- markets : list[tuple[str, str] | str], optional¶
The O&D markets to record, as directional
(orig, dest)pairs or strings like"BOS-ORD". If not given, all markets are recorded.- carriers : list[str], optional¶
Carrier names to record. If not given, all carriers are recorded.
- segments : list[str], optional¶
Demand segment names to record. If not given, every segment used by any demand in the simulation is recorded.
- priority : int, default 1¶
Daily callback priority, in seconds after the overnight trigger time. Positive values run after RM steps and the simulation’s daily bookkeeping at the same time; zero is not allowed. No customers arrive within a few seconds of a DCP, so small positive values record the state exactly at the DCP.
- name : str, optional¶
Key for the results in
callback_data. Defaults to the class name,"segmentation_detail"; give a different name to attach two of these tracers to one simulation. Summary accessors such assegmentation_detail_tracedread only the default name.
Methods
__init__([markets, carriers, segments, ...])Initialize the tracer.
attach(sim)Attach a fresh copy of this tracer to a simulation, on all its hooks.
finalize()Convert the accumulators into a tidy DataFrame of per-sample means.
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 data, and forget the resolved fares.
setup(sim)Select the fares, segments and DCPs to record, and allocate accumulators.
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.
Directional markets to record, or None for all markets.
Carrier names to record, or None for all carriers.
Segment names requested by the user, or None to detect from demands.
Daily callback priority, see
CallbackMixin.daily_callback().-
name : str =
'segmentation_detail'¶ Identifier used to store results in
SimulationTables.callback_data.
-
hook : ClassVar[Literal['begin_sample', 'daily', 'end_sample']] =
'daily'¶ Lifecycle hook shared by manual and configured attachment.
-
skip_burn : ClassVar[bool] =
True¶ Burn-in samples are not recorded.
-
__init__(markets: list[tuple[str, str] | str] | None =
None, *, carriers: list[str] | None =None, segments: list[str] | None =None, priority: int =1, name: str | None =None)[source]¶ Initialize the tracer.
- Parameters:
- markets : list[tuple[str, str] | str], optional¶
The O&D markets to record, as directional
(orig, dest)pairs or strings like"BOS-ORD". If not given, all markets are recorded.- carriers : list[str], optional¶
Carrier names to record. If not given, all carriers are recorded.
- segments : list[str], optional¶
Demand segment names to record. If not given, every segment used by any demand in the simulation is recorded.
- priority : int, default 1¶
Daily callback priority, in seconds after the overnight trigger time. Positive values run after RM steps and the simulation’s daily bookkeeping at the same time; zero is not allowed. No customers arrive within a few seconds of a DCP, so small positive values record the state exactly at the DCP.
- name : str, optional¶
Key for the results in
callback_data. Defaults to the class name,"segmentation_detail"; give a different name to attach two of these tracers to one simulation. Summary accessors such assegmentation_detail_tracedread only the default name.
- markets : frozenset[tuple[str, str]] | None¶
Directional markets to record, or None for all markets.
- carriers : frozenset[str] | None¶
Carrier names to record, or None for all carriers.
- segments : tuple[str, ...] | None¶
Segment names requested by the user, or None to detect from demands.
- priority¶
Daily callback priority, see
CallbackMixin.daily_callback().
- 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[source]¶
Select the fares, segments and DCPs to record, and allocate accumulators.
Called once per run, after the scenario is built, so that a filter matching no fares is reported before the first sample.
- Parameters:
- sim : Simulation¶
The simulation about to run.
- Warns:
UserWarning – If no fares match a requested market, or no fares match the filters at all.
- finalize() DataFrame[source]¶
Convert the accumulators into a tidy DataFrame of per-sample means.
- Returns:
pd.DataFrame – Indexed by
(carrier, orig, dest, booking_class, segment, days_prior)with columnssoldandrevenue, giving the mean (per sample) cumulative sales and realized revenue from the start of the booking horizon through each DCP. The DataFrame attrsn_samplesandaggregation_processare set so that results from multiple processes are combined as a sample-weighted mean.