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	4.046393
1	12	13	4.305254
2	1	9	3.997326
3	14	15	4.625380
4	6	7	3.122175

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
26	2	5	2.0	27	81	529
27	2	5	2.0	28	82	530
1	10	6	4.0	2	964	125
2	10	6	4.0	3	972	637
3	10	6	4.0	4	982	135

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
26	2	5	2.0	27	81	529	57777
27	2	5	2.0	28	82	530	47606
1	10	6	4.0	2	964	125	10379
2	10	6	4.0	3	972	637	18384
3	10	6	4.0	4	982	135	70524

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): [3, 11, 8, 8]
Proportions: [0.1, 0.367, 0.267, 0.267]

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
26	2	5	81	529	57777	16:02
27	2	5	82	530	47606	13:13
1	10	6	964	125	10379	02:52
2	10	6	972	637	18384	05:06
3	10	6	982	135	70524	19:35
0	10	6	954	137	39644	11:00
18	6	7	137	744	37952	10:32
16	6	7	135	741	48440	13:27
17	6	7	129	152	37332	10:22
8	1	9	189	165	67449	18:44