Results And Indicators

For project work, use population_trips.results(...) as the main results entry point.

It can gather one or several scenarios, and one or several replications, for the same day type:

results = population_trips.results(
    "weekday",
    scenarios=["default", "project"],
)

The returned object gives access to:

results.metrics,
results.diagnostics,
results.tables.

Use population_trips.run(...) when you need to execute or inspect one concrete run. Use population_trips.results(...) when you want indicators.

Most result metrics are population-weighted. Trip counts sum the represented people attached to simulated trips. Distance, time, cost, and emissions multiply each trip quantity by the represented-person weight before aggregation. When several replications are selected, metric values are averaged across replications and standard-deviation columns describe the spread across replications.

Common Indicators

Trip count:

results.metrics.trip_count(
    by_variable="mode",
    iterations="last",
    output="table",
)

Travel distance:

results.metrics.travel_distance(
    by_variable="mode",
    iterations="last",
    output="table",
)

Travel time:

results.metrics.travel_time(
    by_variable="activity",
    iterations="last",
    output="table",
)

Greenhouse gas emissions:

results.metrics.ghg_emissions(
    by_variable="mode",
    iterations="last",
    output="table",
)

These indicators can also be read with output="plot" when you want a visual check of a table.

Metric tables usually contain:

scenario,
day_type,
iteration,
optional grouping columns such as mode, activity, or a zone id,
one metric column, such as trip_count, travel_distance, travel_time, cost, or ghg_emissions.

If several replications are selected, the result can also contain uncertainty columns such as standard deviations or replication counts depending on the metric.

Typical units are:

trip_count: represented trips for the selected day type,
travel_distance: passenger-kilometres,
travel_time: passenger-hours,
cost: generalized-cost units defined by the mode parameters,
ghg_emissions: kgCO2e when the mode emission factors are in kgCO2e per passenger-kilometre.

Group Results

The main grouping arguments are:

by_variable, for dimensions such as "mode", "activity", "distance_bin", "time_bin", or "csp",
by_zone, for "home_zone", "origin_zone", or "destination_zone".

If you need to decode survey categories such as csp, see the definitions page.

Example:

results.metrics.trip_count(
    by_zone="home_zone",
    by_variable="mode",
    iterations="last",
    output="plot",
    inner_zone_residents_only=True,
)

inner_zone_residents_only=True is useful when the model has a large routing area but the study focuses on residents inside the main perimeter.

Normalize Results

You can normalize by population:

results.metrics.travel_distance(
    by_variable="mode",
    normalize_by="person_count",
    normalize_scope="study_area",
    iterations="last",
    output="table",
)

You can also compute shares:

results.metrics.trip_count(
    by_variable="mode",
    normalize_by="metric_total",
    normalize_scope="study_area",
    iterations="last",
    output="table",
)

Compare A Scenario To A Reference

comparison = results.metrics.travel_distance(
    by_variable="mode",
    iterations="last",
    reference=("scenario", "default"),
    output="table",
)

This compares each selected scenario to the default scenario. With the default reference_view="gap", values are returned as scenario minus reference. Use reference_view="values" when you want model and reference values side by side.

Some metrics can also be compared with survey references:

results.metrics.trip_count(
    by_variable="mode",
    iterations="last",
    reference="external",
    output="plot",
)

External references are available for some dimensions and final-iteration results. They are mainly available for survey-comparable indicators such as trip counts, distances, times, immobility, activity-duration distributions, and activity time series. Model-only quantities such as generalized cost usually have no external reference.

Survey-Comparable Checks

Some checks are especially useful for comparing the model with survey evidence:

results.metrics.immobility(reference="external")
results.metrics.activity_duration_distribution(reference="external")
results.metrics.activity_time_series(reference="external")

These checks compare modelled behaviour with the survey reference used by the run. Use them as a first check before local validation.

Iterations And Replications

Use iterations="last" for final-iteration indicators after checking the iteration diagnostics.

Use iterations="all" when you want to inspect how an indicator changes during the run:

results.metrics.trip_count(
    by_variable="mode",
    iterations="all",
    output="plot",
)

If the setup has several replications, population_trips.results(...) selects all of them by default. You can select one replication with replication=0, or several with replications=[0, 1].

First Results Checklist

For a new project setup, start with these checks:

trip_count(by_variable="mode"): are the main modes present, and do totals match the scale expected from the population sample?
travel_distance(by_variable="mode"): are distances in the expected order of magnitude for the territory?
ghg_emissions(by_variable="mode"): are emissions consistent with the modes and emission factors used?
trip_count(by_zone="home_zone", by_variable="mode"): do maps or zone tables reveal missing areas, boundary effects, or unexpected spatial concentration?
diagnostics.iteration_metrics(iterations="all"): do indicators behave consistently across iterations?
immobility(reference="external"): does immobility remain close to the survey reference for the relevant groups?
activity_duration_distribution(reference="external"): do activity durations keep a credible shape?

These checks are a first screen before calibration, validation against independent observations, sensitivity tests, or scenario interpretation.

Raw Plan Steps On One Run

When you need to inspect one concrete run, keep the Run object returned by population_trips.run(...):

weekday_run = population_trips.run("weekday")
weekday_plan_steps = weekday_run.get()["plan_steps"].collect()

This is useful for checking raw simulated plan steps. For indicators, diagnostics, scenario comparison, and project reporting, prefer population_trips.results(...).

Diagnostics

Diagnostics help check whether the model behaves as expected:

diagnostics = results.diagnostics.iteration_metrics(
    iterations="all",
).collect()

Use diagnostics when a scenario result looks surprising, when the model varies across iterations, or when you need to check that a scenario gap is larger than iteration variation.