Visualizations

Built-in figures turn simulation outputs into charts. Most such methods use Altair for plotting charts, and have names that begin fig_*. Some figures are available using other libraries, such as Plotly (plotly_* method). The API documentation for each figure method describes its plotting library and signature. This guide groups figures by subject rather than rendering library. Subjects generally mirror those in Summary Outputs, and puts single-run and comparison examples together. Each group links to its source tables and collection settings.

Figures Demo Results

We’ll use the Europa network throughout this guide.

There are in general three categories of figures: single-run, comparison, and “duo”.

Single-run figures are generated from a single simulation result. They are generally available as methods on the SimulationTables object that holds a single result. In these docs, they are usually generated from the summary object, which is the result of a single simulation run of the europa/upe demo network. A sub-genre of single-run figures are configuration-only figures, which do not require complete simulation results. These figures are covered in Configuration Visualizations.

Comparison figures are generated from two or more simulation results. They plot results side-by-side in a consolidated figure. They are generally available as methods on the Contrast object that holds multiple results, or called as result Python functions imported from passengersim.contrast and passed a mapping of results. If you have a Contrast object that includes more results than you want to compare in one figure, you can restrict the comparison to a subset of results using contrast.subset(["baseline", "upe"]), with whichever keys you want to include. In these docs, comparison figures are usually generated from the contrast object, which contains the baseline europa network and the europa/upe variant.

Duo figures are generated from exactly two simulation results, and show the difference between them. They are generally available as Python functions in the passengersim.contrast.duo module, and passed two results explicitly.

The following code will reproduce the summary and contrast objects used throughout the “Visualization” section of the guide:

import altair as alt
import passengersim as pax

# Keep all observations available when a figure contains more than 5,000 rows.
alt.data_transformers.disable_max_rows()
summary = pax.demo_result("europa/upe")
contrast = pax.demo_result({"europa": "europa", "europa/upe": "europa/upe"})
baseline = contrast["europa"]
alternative = contrast["europa/upe"]

Data, presentation, and export

Most figures accept raw_df=True to return their plotting data instead of a chart. Methods supporting also_df=True return (chart, dataframe). These are common but not universal options: each figure’s API link gives its actual signature, and the guide calls out exceptions such as revenue distributions and select-leg analysis.

data = summary.fig_carrier_revenues(raw_df=True)
chart, data = summary.fig_carrier_revenues(also_df=True)
chart

You can save the chart with chart.save("carrier-revenues.html"). HTML preserves hover tooltips. Most methods return Altair charts; some return layered, faceted, or concatenated charts, so layout customization depends on the returned type. Methods decorated for reporting additionally accept report to append the figure and trace to write plotting data to an Excel writer. These options are not available on every callback or specialized figure. See the API for details.

If a figure reports missing data, check the linked Summary Outputs activation section. Native counters, database-backed reports, and callback/tracer observations are different data sources. Saved summaries can only plot data stored in the archive or still available from their backing database.