fig_market_shifts

passengersim.contrast.duo.fig_market_shifts(baseline: SimulationTables, treatment: SimulationTables, *, coloring: 'avg_revenue' | 'change_revenue' | 'change_revenue_pct' | None = 'change_revenue', size_range: tuple[int, int] = (10, 100), facet_width: int = 400, facet_height: int = 400, facet_columns: int = 2, opacity: float = 1.0, fillOpacity: float = 1.0, strokeOpacity: float = 1.0, strokeWidth: float = 1.0) → FacetChart[source]

Create a scatter/shift chart comparing carrier-market metrics between two simulations.

For each carrier in each O&D market, a “lollipop” is drawn, with the stick showing the shift from the baseline to the treatment position in average-sold vs. average-price space, and the point marking the treatment result. The size of the point reflects the carrier’s treatment market share (by passengers sold) in that O&D market. Market results are the aggregation of all path classes sharing a common carrier, origin, and destination, so they include both nonstop and connecting itineraries. This makes it easy to see whether a carrier gained or lost traffic in a market, and whether it did so by moving price, volume, or both.

Values are averaged per sample, i.e. the grand totals for each simulation are divided by that simulation’s n_total_samples. Average price is computed as average revenue divided by average passengers sold. Only carrier-markets present in both simulations are shown.

Parameters:
baseline : SimulationTables

Simulation results to use as the reference (baseline) scenario. Must include the pathclasses table.

treatment : SimulationTables

Simulation results to compare against the baseline (treatment) scenario. Must include the pathclasses table.

coloring : {"avg_revenue", "change_revenue", "change_revenue_pct", None}, optional

Determines how points and lines are colored:

  • "avg_revenue" – color by absolute average revenue in the treatment.

  • "change_revenue" – color by the absolute change in average revenue (treatment minus baseline), using a diverging red-blue scale centered at 0. This is the default.

  • "change_revenue_pct" – color by the percentage change in average revenue, using a diverging red-blue scale centered at 0. Markets with zero baseline revenue have no defined percentage change and are left uncolored.

  • None – color by carrier (nominal color encoding).

size_range : tuple[int, int], optional

Minimum and maximum point sizes (in pixels²) used to encode the carrier’s treatment market share.

facet_width : int, optional

Width of each facet panel in pixels.

facet_height : int, optional

Height of each facet panel in pixels.

facet_columns : int, optional

Number of columns in the faceted layout (one facet per carrier).

opacity : float, optional

Overall opacity of the point marks.

fillOpacity : float, optional

Fill opacity of the point marks.

strokeOpacity : float, optional

Stroke opacity of both point and line marks.

strokeWidth : float, optional

Stroke width of the line (rule) marks.

Returns:

altair.FacetChart – An interactive Altair faceted chart (faceted by carrier) showing the shift in average sold and average price for each carrier-market between baseline and treatment.

Raises:

ValueError – If coloring is not one of the recognized options.