Tracers

A tracer watches a simulation as it runs and produces a table you can read afterward. For example, a booking-detail tracer can keep every day’s sales for two flights, while a forecast tracer can average the forecasts for those flights across samples. You choose the tracer according to the question you want the table to answer.

Callbacks and tracers observe the simulation at the same points, called hooks. A callback is a function that can act on the simulation or return a dictionary of observations from one call. A tracer is an object that can remember earlier calls, use several hooks, and decide how to lay out its results. Either can record individual observations. See the callback guide for the hooks available and when they run.

Run a built-in tracer

Suppose you want to see how sales build up on two legs of the 3MKT demo network. Create a tracer with their leg IDs and attach it before running the simulation. The tracer knows which hook to use.

import passengersim as pax
from passengersim.callbacks.booking_detail import LegBookingDetailTracer

cfg = pax.Config.from_yaml(pax.demo_network("3MKT"))
cfg.simulation_controls.num_trials = 1
cfg.simulation_controls.num_samples = 800
cfg.simulation_controls.burn_samples = 50
cfg.simulation_controls.show_progress_bar = False
cfg.db = None
cfg.outputs.reports.clear()
cfg.outputs._write_no_files()

with pax.Simulation(cfg) as sim:
    LegBookingDetailTracer(leg_ids=[101, 111]).attach(sim)
    summary = sim.run()
summary.callback_data["leg_booking_detail"].head()
leg_id 101 111
trial sample days_prior
0 50 63 0.0 0.0
62 0.0 2.0
61 0.0 3.0
60 6.0 13.0
59 8.0 17.0

Each row gives the cumulative seats sold on those legs for one trial, sample, and day before departure. The built-in tracers skip burn-in samples. A fresh run starts with empty tracers. Each worker in a multi-process run collects its own results, which PassengerSim combines at the end.

Select a tracer via configuration

Registration gives a tracer a name that a configuration file can refer to. PassengerSim already registers the built-ins. To collect the same booking table from YAML, add this to your configuration and run the simulation normally.

callbacks:
  leg_booking_detail:
    parameters:
      leg_ids: [101, 111]

Here the declaration ID, leg_booking_detail, selects the tracer and names its result table. To keep outbound and return sales in separate tables, declare the same tracer twice. Give each declaration its own ID and use type to select the tracer:

callbacks:
  outbound_sales:
    type: leg_booking_detail
    parameters:
      leg_ids: [101]
  return_sales:
    type: leg_booking_detail
    parameters:
      leg_ids: [111]

After the run, summary.callback_data["outbound_sales"] contains leg 101 and summary.callback_data["return_sales"] contains leg 111. To use the standard booking-detail summary and figures for one group, give that declaration the default ID, leg_booking_detail. To collect both legs in a single table, include both IDs in its leg_ids list.

The callbacks section accepts registered callback functions and tracers. See Writing a Tracer to register your own. The pages below give the registered type and parameters for each built-in tracer.

In Python, you can attach two instances of a tracer to watch different groups. Give the second a distinct name, for example LegBookingDetailTracer([111], name="return_sales").attach(sim), and read its table with summary.callback_data["return_sales"].

Attaching a manual tracer with the same name twice replaces the first with a warning. Keep in mind that the standard figures on most tracer read the default result name, so you’ll likely also need to write custom figure methods to visualize the second tracer’s results.

Built-in tracers

Use the name in the first column to enable a tracer under callbacks in YAML. Follow its link for a working example.

Name

Description

leg_booking_detail

Records cumulative seats sold on selected legs each day of each retained sample.

leg_bid_price_detail

Records the daily bid price for selected legs in each retained sample, so you can inspect individual prices or calculate percentiles.

leg_bid_prices

Reports the daily mean bid price, standard deviation, and observation count for each selected leg.

path_bid_prices

Reports the daily mean, standard deviation, and observation count for the total bid price of each selected itinerary.

leg_bid_price_arrays

Averages the bid-price schedules seen at the start of each sample, by leg, seats sold, and days before departure.

leg_bid_price_vectors

Tracks how the bid price at each seats-sold level changes day by day, averaged across samples for each selected leg.

selected_leg_forecasts

Averages start-of-sample forecasts for selected legs by booking class and days before departure.

selected_path_forecasts

Averages start-of-sample forecasts and adjusted fares for selected itineraries by booking class and timeframe.

segmentation_detail

Reports average cumulative sales and realized revenue by carrier, market, booking class, and passenger segment at each data collection point.

Writing a Tracer

A tracer is a subclass of GenericTracer. It needs a name for its results, a reset method that empties its accumulators, and a finalize method that turns them into a DataFrame. It observes the simulation through one or more hook methods, named for the lifecycle hooks: on_initialize_sample, on_begin_sample, on_daily, on_end_sample, and on_finalize_sample. The tracer is attached to every hook whose method it defines, and a single copy of the tracer receives all of those calls, so it can compare what it saw at different points of each sample.

The example below measures sales between two hooks. It saves the starting count (which should typically be zero, but might not be if a different callback modifies the count earlier), subtracts it from the final count, and reports mean sales per leg. The decorator registers the class under its result name, leg_sales.

import pandas as pd

from passengersim.callbacks import register_tracer
from passengersim.tracers.generic import GenericTracer


@register_tracer
class LegSalesTracer(GenericTracer):
    name = "leg_sales"
    skip_burn = True  # The simulation skips burn-in samples for every hook.

    def __init__(self, leg_ids: list[int], *, name: str | None = None):
        self.leg_ids = list(leg_ids)
        self._set_name(name)  # Optional instance-level result name.
        self.reset()

    def reset(self):
        self.legs = None
        self.at_start = {}
        self.totals = dict.fromkeys(self.leg_ids, 0)
        self.samples = 0

    def setup(self, sim):
        # Look up the legs once per run, so a bad leg ID fails before any sample.
        self.legs = {leg_id: sim.eng.legs.select(leg_id=leg_id) for leg_id in self.leg_ids}

    def on_begin_sample(self, sim):
        self.at_start = {leg_id: leg.sold for leg_id, leg in self.legs.items()}

    def on_end_sample(self, sim):
        for leg_id, leg in self.legs.items():
            self.totals[leg_id] += leg.sold - self.at_start[leg_id]
        self.samples += 1

    def finalize(self):
        mean = {leg_id: total / max(self.samples, 1) for leg_id, total in self.totals.items()}
        df = pd.DataFrame({"mean_sold": mean})
        df.attrs["n_samples"] = self.samples
        df.attrs["aggregation_process"] = "wgt_by_samples"
        return df

The decorator makes leg_sales available to the configuration as soon as this class definition runs. In a separate Python session, import the module containing the class before starting the simulation. The constructor annotation leg_ids: list[int] tells PassengerSim how to validate the configured IDs.

The following cell reads the same callbacks section you could put in a YAML file. When the run starts, PassengerSim looks up leg_sales, creates the tracer with those IDs, and attaches its hooks.

import yaml

settings = yaml.safe_load("""
callbacks:
  leg_sales:
    parameters:
      leg_ids: [101, 111]
""")
cfg.callbacks = settings["callbacks"]
with pax.Simulation(cfg) as sim:
    summary = sim.run()

Read the result under the registered name. Each row gives one leg’s average increase in seats sold between the beginning and end of a retained sample.

summary.callback_data["leg_sales"]
mean_sold
101 83.546667
111 107.216000

Hook methods take the same arguments as the corresponding callback functions: the simulation, plus the days prior to departure for on_daily. Like a callback function, a hook method may return a dictionary to store as ordinary callback data, though most tracers keep what they observe and report it from finalize. A tracer can set a priority attribute, which works as it does for a callback: it is the offset in seconds from each DCP’s trigger time. A tracer has just one priority, which applies to all of its queued hook methods (on_begin_sample, on_daily, and on_end_sample), so the tracer observes every DCP from the same side of the RM systems and the simulation’s bookkeeping. A priority given when attaching the tracer, as in sim.begin_sample_callback(tracer, priority=-5), likewise applies to all of these methods, whichever registration method was used. When two of a tracer’s methods fall at the same moment, they run in lifecycle order: on_begin_sample before the first on_daily call of a sample, and the last on_daily call before on_end_sample. The same order holds between different callbacks and tracers that share a moment (after any RM systems, which always run first). A tracer that needs different timing for different hooks can be split into two tracers.

For each run, the simulation takes the tracer through these steps:

  1. reset(), once, at the start of the run. A tracer is never reset between the trials of one run, so its results cover all of them.

  2. The scenario is built: the network, fares, and demands now exist.

  3. setup(sim), once. This is the place to look up the legs, paths, or fares the tracer will observe, to allocate its arrays, and to report problems before the run gets going. The default does nothing.

  4. The hook methods, for every trial and sample of the run (skipping burn-in samples, if skip_burn is set).

  5. finalize(), once, after the last trial. Its result is stored in callback_data under the tracer’s name.

If setup or a hook method raises an exception, the run stops, finalize is not called, and no result is stored. Running again starts over from reset. When a multi-process simulation runs, each worker gets its own fresh copy of the tracer, so no state is shared between workers, or between experiments.

Combining results

When a simulation runs in several processes, or results are added together, the tables from each part are combined. A tracer chooses how by setting df.attrs["aggregation_process"] on the table its finalize method returns:

Process

Combination

(none)

The tables are added together with +.

wgt_by_samples

A mean weighted by df.attrs["n_samples"], as in the example above.

wgt_by_trials

A mean weighted by df.attrs["n_trials"].

pooled_moments

Exact pooling of the mean, std_dev, and n rows of a statistic level.

concat_rows

The rows of both tables are stacked, for tables that keep every observation.

Two tables declaring different processes cannot be combined, and raise an error. A tracer can define its own process with passengersim.callbacks.register_combiner, giving it a function that combines two such tables into a new one. Register it in the module that defines the tracer, since saved results only record the process’s name: combining saved results in a new session raises an error naming the process until that module has been imported. Once results using a process exist, never change what the process name means; choose a new name instead.

Legacy tracers

Tracers written before hook methods existed set a hook class attribute and define __call__ instead. They work as before, on that one hook. A tracer uses one form or the other: defining hook together with any hook method is an error.