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: GenericTracer

A 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 via segmentation_detail_traced() (also available as the segmentation_detail_traced property 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 as segmentation_detail_traced read 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

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

Configured-callback implementation version; bump when results change meaning.

skip_burn

Burn-in samples are not recorded.

markets

Directional markets to record, or None for all markets.

carriers

Carrier names to record, or None for all carriers.

segments

Segment names requested by the user, or None to detect from demands.

priority

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 as segmentation_detail_traced read 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_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] = '1'

Configured-callback implementation version; bump when results change meaning.

reset() → None[source]

Reset all accumulated data, and forget the resolved fares.

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 columns sold and revenue, giving the mean (per sample) cumulative sales and realized revenue from the start of the booking horizon through each DCP. The DataFrame attrs n_samples and aggregation_process are set so that results from multiple processes are combined as a sample-weighted mean.