Bid Prices and Displacement

Bid prices help revenue management decide whether to accept a booking or keep capacity available for later passengers. Here we can watch those prices change as departure approaches, starting with carrier averages and then looking at individual legs and paths.

You can read about the underlying data and how to collect it in Bid Prices and Displacement.

When you plot twelve or fewer legs or paths, colors help you tell them apart. With more lines, the charts leave out those ID colors to avoid an oversized legend. You can still hover over a line to see its ID, day, mean price, standard deviation, and observation count. Path tooltips also identify the cabin, and comparison tooltips tell you which run the line belongs to. Missing statistics are left missing rather than treated as zero.

Collecting Price Histories

The standard demo archive does not contain path-price history or the callback observations used later on this page. Here we replay the same demos, enabling those collectors. We keep the original random seed, sample counts, and revenue-management settings. The extra results are cached in a temporary-directory cache, separately from demo_result.

We’ll track Stroop flight 211 (KEF–AMS), whose UPE revenue-management system uses bid prices. The matching nonstop path also has ID 211. The first run of this cell takes longer than loading the standard demos; later runs reuse its saved results.

from pathlib import Path
import tempfile
from passengersim.contrast import Contrast
from passengersim.callbacks.bid_price_detail import collect_leg_bid_price_detail
from passengersim.tracers import bid_price as traced_bp


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 = set()
    cfg.simulation_controls.show_progress_bar = False
    cfg.simulation_controls.collect_path_bid_prices = True
    cfg.db = None
    cache_dir = Path(tempfile.gettempdir()) / "passengersim-viz-guide" / "bid-prices-v1" / name
    simulation_class = pax.MultiSimulation if cfg.simulation_controls.num_trials > 1 else pax.Simulation
    with simulation_class(cfg) as sim:
        sim.daily_callback(collect_leg_bid_price_detail({211}))
        traced_bp.LegBidPriceTracer([211]).attach(sim)
        traced_bp.PathBidPriceTracer([211]).attach(sim)
        traced_bp.LegBidPriceArrayTracer([211]).attach(sim)
        traced_bp.LegBidPriceVectorTracer([211]).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 32f6a50ccaafe8fc83efb102bf46bf4ca643b341f7adc03d498434bd160a0709. 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 74857b6ba43c6bf53de6b005faf017b38a9bfd4221940b04bb1e92ecd911e0fd. 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                               │
╰───────────────────────────────────────────────────────────────────────────╯

Average Bid Prices by Carrier

Start with this chart for a broad view of bid prices. Each carrier’s line averages across its legs, so it is a useful overview before you investigate individual flights.

Use by_carrier to separate carriers or focus on one. You can also choose which capacity conditions to include with cap: None includes all reporting prices, "some" includes only observations with remaining capacity, and "zero" includes only sold-out observations.

Set show_stdev=True to add a band extending two standard deviations around the mean, or pass a number to choose a different multiplier. When comparing runs, select one carrier to show these bands. For a single run, trial lets you inspect one trial instead of combining all trials.

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

summary.fig_bid_price_history(by_carrier="Tapas", show_stdev=True)

To compare runs, use fig_bid_price_history on a Contrast object:

contrast.fig_bid_price_history(by_carrier="Tapas", show_stdev=True)

Bid Prices for Individual Legs

To see what is happening on particular flights, plot the native leg history. You get the daily mean price and, by default, a second panel showing how much prices varied across the samples and trials kept after burn-in.

PassengerSim collects this history by default, so you don’t need to attach a callback. Set std_dev=False if you only want the mean-price panel.

You can choose legs with ids, or narrow the chart using carrier, orig, and dest. For example, supplying both a carrier and an origin keeps only that carrier’s legs from that airport. Each of those three filters accepts one name or a tuple of names. These filters use the legs table, so keep that table with your results. When comparing runs, include lets you choose which runs to show.

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

summary.fig_leg_bid_prices(carrier="Tapas", std_dev=False)

To compare runs, use fig_leg_bid_prices on a Contrast object:

contrast.fig_leg_bid_prices(carrier="Tapas", std_dev=False)

Bid Prices for Passenger Paths

This chart follows bid prices for each path and cabin. Separate lines keep the cabins distinct, and the second panel shows how much the prices varied across the retained observations.

Turn on simulation_controls.collect_path_bid_prices=True before you run the simulation. You can then use the same filters as for legs: ids, carrier, orig, and dest. The carrier and airport filters use the paths table; the airports are the endpoints of the whole itinerary, including when it connects.

By default, the chart shows the ordinary path price, based on its legs. Set augmented=True to include the reference-class fare adjustment described in the bid-price table guide. As with legs, std_dev=False hides the variability panel, and include selects runs in a comparison.

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

recorded_summary.fig_path_bid_prices(ids=(211,), augmented=True)

To compare runs, use fig_path_bid_prices on a Contrast object:

recorded.fig_path_bid_prices(ids=(211,), augmented=True)

The baseline Europa demo does not use bid-price control, so its native path-price table has no observations for this path. Although both results are included in the comparison, only the UPE line appears here. The tracer path-price comparison later on this page records reporting prices in both runs and can show both lines.

Displacement Costs

Displacement costs describe the opportunity cost of using capacity for a booking. This chart shows the daily averages reported by the revenue-management system for each carrier.

Use by_carrier and show_stdev as for carrier bid prices. For a single run, you can focus on one trial with trial. When comparing runs, select one carrier to show a standard-deviation band; width and height let you adjust the size of each panel.

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

summary.fig_displacement_history(by_carrier="Tapas", show_stdev=True)

To compare runs, use fig_displacement_history on a Contrast object:

contrast.fig_displacement_history(by_carrier="Tapas", show_stdev=True)

Callback Analysis: Bid-Price Distributions

Sometimes an average and a standard deviation aren’t enough. You may want to see the median price, or the range containing most of the observed prices. The callback figures below can show those details if you collect daily observations before running. These plotting methods are always available on summaries; they only need the observations recorded by the daily collector. Attach it in Python as shown above, or enable it in a configuration:

callbacks:
  leg_bid_price_detail:
    parameters:
      leg_ids: [211]

The collection cell above has already attached the daily callback for flight 211.

Price Percentiles for One Leg

This chart follows a leg’s median, mean, and selected price percentiles through the booking horizon. The percentiles help you see the range containing most observations, including when prices are spread unevenly around the mean.

Choose the flight with leg_id. You can change the colors with color and mean_color, or use raw_df=True to inspect the summarized observations.

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

recorded_summary.fig_leg_bid_price_detail_rake(leg_id=211)

To compare scenarios, make this chart once for each result. There isn’t a combined comparison method for this figure.

Price Histories Across a Carrier’s Legs

This chart lets you follow one price statistic across a carrier’s legs. For example, plotting the median for each flight can help you find flights whose typical prices are higher than the rest. Choose a carrier and a measure: "mean", "q10", "q25", "q50", "q75", "q90", or "median".

The chart uses callback observations and leg definitions for labels and distance groups. Set haul_category_labels=None to keep all distances in one panel, which is useful on small networks where several legs have the same distance. Use opacity to make overlapping lines easier to see and max_rows to limit the displayed data. This method does not support raw_df.

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

recorded_summary.fig_leg_bid_price_history("Stroop", measure="median", haul_category_labels=None)

To compare scenarios, make this chart once for each result. There isn’t a combined comparison method for this figure.

Tracer Analysis: Bid Prices

Tracers let you collect price observations for selected legs and paths. Attach a fresh tracer before each run, as described in Tracers. The observations must be collected during the simulation; they cannot be recovered from an existing result afterward.

These plotting functions live in passengersim.tracers.bid_price. They share some names with the summary methods above, so the examples use the module alias traced_bp to show which version is being called.

The setup above attaches the leg and path tracers to both demo runs.

Leg and Path Price Histories

These charts show the mean prices recorded by a tracer and, optionally, their standard deviations. Choose legs or paths with ids, hide the standard-deviation panel with std_dev=False, or inspect the plotted values with raw_df=True. When comparing runs, include selects which runs to show.

The tracer functions do not accept the carrier and airport filters or the path augmented option used by the summary methods above. They can also record at different times, so their values may differ from the native histories.

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

traced_bp.fig_leg_bid_prices(recorded_summary, ids=(211,))

For a path, call fig_path_bid_prices with a single SimulationTables object:

traced_bp.fig_path_bid_prices(recorded_summary, ids=(211,))

To compare leg prices across runs, call fig_leg_bid_prices with a Contrast object:

traced_bp.fig_leg_bid_prices(recorded, include=("europa", "europa/upe"))

To compare path prices across runs, call fig_path_bid_prices with a Contrast object:

traced_bp.fig_path_bid_prices(recorded, include=("europa", "europa/upe"))

Bid-Price Arrays

This heatmap shows a leg’s mean bid-price array across seats sold and days prior to departure. It helps you see how prices change with the number of seats sold as well as with time.

Attach LegBidPriceArrayTracer before the run. It captures arrays at the beginning of samples, so this chart does not show price updates within a sample. The collection code above attaches it for leg 211.

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

traced_bp.fig_leg_bid_price_array(recorded_summary, leg_id=211)

Use raw_df=True to inspect the plotted values. This is a single-summary function; call it separately for each run to compare arrays.

Bid-Price Vectors

This heatmap shows the mean bid-price vectors for one leg. You can use it to inspect how the recorded prices vary across the vector and the booking horizon.

Attach LegBidPriceVectorTracer before running the simulation. The collection code above does this for leg 211.

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

traced_bp.fig_leg_bid_price_vectors(recorded_summary, leg_id=211)

Use raw_df=True for the plotted data. This is a single-summary function, not a Contrast method.