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.149256
1	12	13	4.726132
2	1	9	4.830354
3	14	15	0.837986
4	6	7	2.194305

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
23	2	5	4.0	24	210	119
22	2	5	4.0	23	76	117
21	2	5	4.0	22	80	529
24	2	5	4.0	25	84	530
12	6	7	3.0	13	634	144

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
23	2	5	4.0	24	210	119	50185
22	2	5	4.0	23	76	117	42610
21	2	5	4.0	22	80	529	37842
24	2	5	4.0	25	84	530	34446
12	6	7	3.0	13	634	144	31788

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): [7, 17, 3, 3]
Proportions: [0.233, 0.567, 0.1, 0.1]

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
23	2	5	210	119	50185	13:56
22	2	5	76	117	42610	11:50
21	2	5	80	529	37842	10:30
24	2	5	84	530	34446	09:34
12	6	7	634	144	31788	08:49
10	6	7	154	143	22255	06:10
11	6	7	140	182	38410	10:40
7	1	9	106	958	37047	10:17
8	1	9	188	638	39121	10:52
6	1	9	190	168	61385	17:03