SegmentationTracer

class passengersim.tracers.segmentation.SegmentationTracer(markets: Iterable[tuple[str, str] | str] | None = None, *, carriers: Iterable[str] | None = None, segments: Iterable[str] | None = None, priority: int = 1)[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 : Iterable[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 : Iterable[str], optional

Carrier names to record. If not given, all carriers are recorded.

segments : Iterable[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 at the same time; no customers arrive within a few seconds of a DCP, so small positive values record the state exactly at the DCP.

Methods

__init__([markets, carriers, segments, priority])

Initialize the tracer.

attach(sim)

Attach a fresh instance of this tracer to sim as a daily callback.

finalize()

Convert the accumulators into a tidy DataFrame of per-sample means.

fresh()

Return a new, empty tracer with the same configuration.

reset()

Reset all accumulated data, and forget the resolved fares.

Attributes

hook

Lifecycle hook shared by manual and configured attachment.

name

Identifier used to store results in SimulationTables.callback_data.

options_version

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

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.

options_model

Configured-callback options; fields mirror the constructor.

alias of SegmentationTracerOptions

__init__(markets: Iterable[tuple[str, str] | str] | None = None, *, carriers: Iterable[str] | None = None, segments: Iterable[str] | None = None, priority: int = 1)[source]

Initialize the tracer.

Parameters:
markets : Iterable[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 : Iterable[str], optional

Carrier names to record. If not given, all carriers are recorded.

segments : Iterable[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 at the same time; no customers arrive within a few seconds of a DCP, so small positive values record the state exactly at the DCP.

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.

options_version : ClassVar[str] = '1'

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

segments : tuple[str, ...] | None

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

priority

Daily callback priority, see CallbackMixin.daily_callback().

reset() → None[source]

Reset all accumulated data, and forget the resolved fares.

fresh() → SegmentationTracer[source]

Return a new, empty tracer with the same configuration.

Returns:

SegmentationTracer – A freshly initialized tracer with the same filters and priority but no accumulated data.

attach(sim: Simulation) → None[source]

Attach a fresh instance of this tracer to sim as a daily callback.

Parameters:
sim : Simulation or MultiSimulation

The simulation to attach the callback to.

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.