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.536979
1	12	13	0.687991
2	1	9	2.057716
3	14	15	1.662270
4	6	7	1.307836

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 column 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
12	2	5	1.0	13	81	530
3	10	6	4.0	4	174	139
1	10	6	4.0	2	978	126
0	10	6	4.0	1	967	633
2	10	6	4.0	3	977	634

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
12	2	5	1.0	13	81	530	46379
3	10	6	4.0	4	174	139	46214
1	10	6	4.0	2	978	126	59993
0	10	6	4.0	1	967	633	36571
2	10	6	4.0	3	977	634	42888

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): [2, 9, 4, 4]
Proportions: [0.105, 0.474, 0.211, 0.211]

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
12	2	5	81	530	46379	12:52
3	10	6	174	139	46214	12:50
1	10	6	978	126	59993	16:39
0	10	6	967	633	36571	10:09
2	10	6	977	634	42888	11:54
8	6	7	139	142	41603	11:33
9	6	7	126	147	81659	22:40
5	1	9	193	168	71212	19:46
6	1	9	72	169	84478	23:27
13	15	10	962	953	8113	02:15