Forecasts

These charts show what the revenue-management system expected as departure approached. You can look at expected demand, the uncertainty in that forecast, and other recorded measures for individual legs or paths.

You can read about the underlying data and how to collect it in Forecasts.

To use the forecast tables, record bucket data for legs and pathclass data for paths during the simulation. The linked table guide explains how to prepare the reports or retain the database so you can load them later.

The standard deviations in these charts describe uncertainty in the demand forecast. They do not measure how much the plotted average varies across simulation samples.

Collecting Forecasts

The cached demo summaries do not include the detailed forecast tables or tracer observations. We’ll replay the same two demos with those collectors enabled. This changes only recording, not the original simulation settings. The database is temporary: the requested reports are prepared before it is discarded, and the results are cached separately for this page.

from pathlib import Path
import tempfile
from passengersim.contrast import Contrast
from passengersim.tracers.forecasts import (
    LegForecastTracer,
    PathForecastTracer,
    fig_leg_forecast_dashboard,
    fig_path_forecast_dashboard,
)


def collect_demo(name: str) -> pax.SimulationTables:
    """Replay a demo with the recording needed by this page."""
    cfg = pax.Config.from_yaml(pax.demo_network(name))
    cfg.outputs._write_no_files()
    cfg.outputs.reports = {"path_forecasts", "leg_forecasts"}
    cfg.simulation_controls.show_progress_bar = False
    cfg.db.write_items = {"bucket", "pathclass"}
    cfg.db.filename = None
    cfg.db.result_directory = None
    cfg.db.result_storage = "summary_only"
    cache_dir = Path(tempfile.gettempdir()) / "passengersim-viz-guide" / "forecasts-v1" / name
    simulation_class = pax.MultiSimulation if cfg.simulation_controls.num_trials > 1 else pax.Simulation
    with simulation_class(cfg) as sim:
        LegForecastTracer(leg_ids=[111]).attach(sim)
        PathForecastTracer(path_ids=[111]).attach(sim)
        return sim.run(cache_dir=cache_dir)


recorded = Contrast({name: collect_demo(name) for name in ("europa", "europa/upe")})
recorded_summary = recorded["europa/upe"]
Cache miss for config with hash 9b8defb6e298e5a907e4f575771cf85bab7dc527a1f33a6be684b52787a4da6d. Running simulation and saving summary to cache.

╭─────────────────── Summary revenue statistics · Europa ───────────────────╮
│                            Brat            Stroop             Tapas       │
│ Run      Samples     Mean  ~95% CI     Mean  ~95% CI     Mean  ~95% CI    │
│ Europa       900   943.2K   ±7,066   920.6K   ±7,443   292.5K   ±2,336    │
│ Post-burn-in only · Approx. 95% CI for mean                               │
╰───────────────────────────────────────────────────────────────────────────╯
Cache miss for config with hash e1ad3f9396fbfbe9e101d20088caa04a0cc7bb511cc768c5fde07052ab80951a. Running simulation and saving summary to cache.

╭─────────────────── Summary revenue statistics · Europa ───────────────────╮
│                            Brat            Stroop             Tapas       │
│ Run      Samples     Mean  ~95% CI     Mean  ~95% CI     Mean  ~95% CI    │
│ Europa       900   968.6K   ±8,193   935.5K   ±8,308   291.7K   ±2,130    │
│ Post-burn-in only · Approx. 95% CI for mean                               │
╰───────────────────────────────────────────────────────────────────────────╯

Forecasts for Individual Legs

Choose a leg to see how its demand forecasts changed over the booking horizon—the period leading up to departure. You can separate the booking classes to see which forecasts are driving the overall picture.

The of option chooses what to show: "mu" is the forecast mean, "sigma" is its standard deviation (a measure of uncertainty), and "closed" describes booking closures. For a single run, you can also pass a list to see several measures together. Comparisons support "mu" and "sigma", either individually or as a list.

Use by_leg_id to choose a leg. With by_class=True, you can see the booking classes separately; a class name selects just that class. When comparing runs, agg_booking_classes=True combines the classes.

For one run, call fig_leg_forecasts on a single SimulationTables object:

recorded_summary.fig_leg_forecasts(by_leg_id=111, of="mu")

To compare runs, use fig_leg_forecasts on a Contrast object:

recorded.fig_leg_forecasts(by_leg_id=111, of="mu")

Forecasts for Passenger Paths

A path is an itinerary that may use one leg or several connecting legs. This chart lets you follow its demand forecasts, how often it was closed to bookings, or its adjusted fares as departure approached.

As with leg forecasts, "mu" shows the mean, "sigma" shows uncertainty, and "closed" shows closures. Paths also support of="adj_price" to show adjusted fares. Choose a path with by_path_id, and use by_class to separate or select booking classes.

For comparisons, you can request several measures with a list, give paths friendlier labels with path_names, or combine booking classes with agg_booking_classes=True.

For one run, call fig_path_forecasts on a single SimulationTables object:

recorded_summary.fig_path_forecasts(by_path_id=111, of="mu")

To compare runs, use fig_path_forecasts on a Contrast object:

recorded.fig_path_forecasts(by_path_id=111, of="mu")

Tracer Analysis: Forecast Dashboards

These dashboards bring several recorded forecast measures together, so you can examine a leg or path in more detail. They use observations collected by forecast tracers during the simulation. Attach LegForecastTracer or PathForecastTracer before each run; the collection code above attaches both to each demo.

Leg Forecast Dashboard

This dashboard shows forecast statistics for one leg across booking classes and days. It helps you see which classes contribute to the forecast and how those expectations change as departure approaches. Choose the leg with leg_id.

For one run, call fig_leg_forecast_dashboard with a single SimulationTables object. This is a standalone function, imported in the collection code above:

fig_leg_forecast_dashboard(recorded_summary, leg_id=111)

To compare runs, call fig_leg_forecast_dashboard with a Contrast object. Use include to select which runs appear side by side:

fig_leg_forecast_dashboard(recorded, leg_id=111, include=("europa", "europa/upe"))

Path Forecast Dashboard

This dashboard follows forecast statistics for a particular path. It also includes a panel of adjusted fares by timeframe, so you can review those alongside the demand forecasts. Choose the path with path_id.

For one run, call fig_path_forecast_dashboard with a single SimulationTables object:

fig_path_forecast_dashboard(recorded_summary, path_id=111)

To compare runs, call fig_path_forecast_dashboard with a Contrast object. As with the leg dashboard, include selects which runs to show:

fig_path_forecast_dashboard(recorded, path_id=111, include=("europa", "europa/upe"))

Neither dashboard supports raw_df. If you need the underlying observations, inspect the collected tracer data described in Forecasts.