Disaggregate zone-level demand to locations with time-of-day periods (including wrap-around)

This example shows how to: - Load zones and locations from the Grid model - Create a small synthetic zone-to-zone demand table - Disaggregate those trips to origin/destination locations - Assign random start times using four time periods, one of which wraps around midnight (20:00–06:00)

Imports

from pathlib import Path

import numpy as np
import pandas as pd

from polaris import Polaris
from polaris.prepare.demand.demand_disaggregation import (
    disaggregate_column,
    assign_random_start_time,
)
from polaris.utils.database.data_table_access import DataTableAccess

model_dir = Path("/tmp/Grid")
supply_file = Polaris.from_dir(model_dir).supply_file

Read Zones and Locations tables from the Supply database

dta = DataTableAccess(supply_file)
zones = dta.get("Zone")[["zone"]]  # GeoDataFrame with at least columns: zone, geo
locations = dta.get("Location")[["location", "zone"]]  # GeoDataFrame with at least: location, zone, land_use, link, geo

Build a small synthetic zone-to-zone demand table We’ll pick a handful of zones that actually have locations and create random flows between them.

rng = np.random.default_rng(123)

origs = zones.sample(10, random_state=42).zone.to_numpy()  # For display purposes only
dests = zones.sample(10, random_state=24).zone.to_numpy()  # For display purposes only
flows = np.random.rand(10) * 5  # random number of trips between 0 and 5

zone_demand = pd.DataFrame({"zone_origin": origs, "zone_dest": dests, "trips": flows})
zone_demand.head()

	zone_origin	zone_dest	trips
0	10	6	0.103755
1	12	13	4.593396
2	1	9	3.041820
3	14	15	0.097656
4	6	7	2.727695

This is what the locations dataframe need to look like

locations.head()

	location	zone
0	63	1
1	64	1
2	65	1
3	66	1
4	67	1

Disaggregate to locations using the helper in polaris.prepare.demand.demand_disaggregation This expands each OD row into individual trips and assigns origin/destination locations in the matching zones.

# Robust rounding ensures a better match to the original totals by making multiple attempts of
# stochastic rounding. It is not needed in the vast majority of cases
trips_df = disaggregate_column(zone_demand, "trips", locations, seed=42, robust_rounding=False)
print("\nTrip-level disaggregated data (columns):", trips_df.columns.tolist())

# This is what the trips dataframe with your aggregate trips need to look like (the name of the trips colum can be
# different, as that is parameter in the disaggregation procedure
trips_df.head()

Trip-level disaggregated data (columns): ['zone_origin', 'zone_dest', 'trips', 'trip_id', 'origin_location', 'dest_location']

	zone_origin	zone_dest	trips	trip_id	origin_location	dest_location
17	2	5	2.0	18	211	117
18	2	5	2.0	19	77	529
9	6	7	3.0	10	140	143
10	6	7	3.0	11	130	182
11	6	7	3.0	12	133	743

Define four time periods and assign random start times One period wraps around midnight (20:00 → 06:00 next day).

temporal_dist = pd.DataFrame(
    {
        "start_hour": [6.0, 10.0, 16.0, 20.0],
        # end_hour <= 24; wrap-around handled internally for start > end by adding 24 to end
        "end_hour": [10, 16, 20, 6.0],
        # proportions must sum to 1.0
        "proportion": [0.20, 0.40, 0.20, 0.20],
    }
)

This is what the temporal_dist dataframe looks like

temporal_dist

	start_hour	end_hour	proportion
0	6.0	10.0	0.2
1	10.0	16.0	0.4
2	16.0	20.0	0.2
3	20.0	6.0	0.2

trips_with_time = assign_random_start_time(trips_df, temporal_dist)
trips_with_time.head()

	zone_origin	zone_dest	trips	trip_id	origin_location	dest_location	start
17	2	5	2.0	18	211	117	41835
18	2	5	2.0	19	77	529	59226
9	6	7	3.0	10	140	143	39332
10	6	7	3.0	11	130	182	34276
11	6	7	3.0	12	133	743	56604

Let’s verify the assigned start times roughly match the desired proportions

starts_h = trips_with_time["start"].to_numpy() / 3600.0
period_masks = [
    (starts_h >= 6) & (starts_h < 10),
    (starts_h >= 10) & (starts_h < 16),
    (starts_h >= 16) & (starts_h < 20),
    (starts_h >= 20) | (starts_h < 6),  # wrap-around
]
counts = np.array([m.sum() for m in period_masks], dtype=float)
print("\nAssigned starts by period (counts):", counts.astype(int).tolist())
print("Proportions:", np.round(counts / counts.sum(), 3).tolist())

Assigned starts by period (counts): [1, 13, 5, 4]
Proportions: [0.043, 0.565, 0.217, 0.174]

Show a compact preview: origin/destination locations and departure time in HH:MM

preview = trips_with_time[["zone_origin", "zone_dest", "origin_location", "dest_location", "start"]].copy()
preview["start_hm"] = (preview["start"] // 60).astype(int).map(lambda m: f"{m // 60:02d}:{m % 60:02d}")
print("\nPreview (first 10 trips):")

Preview (first 10 trips):

preview.head(10)

	zone_origin	zone_dest	origin_location	dest_location	start	start_hm
17	2	5	211	117	41835	11:37
18	2	5	77	529	59226	16:27
9	6	7	140	143	39332	10:55
10	6	7	130	182	34276	09:31
11	6	7	133	743	56604	15:43
5	1	9	103	132	49438	13:43
7	1	9	68	958	68937	19:08
6	1	9	71	638	7270	02:01
21	15	10	961	174	46291	12:51
19	15	10	962	971	51552	14:19