geoscales

Nested regions and spatial hierarchies for optimization and simulation models

geoscales is the spatial-domain package of the optimal2050 modeling stack, and the spatial companion to timescales.

A Geoscale is a nested spatial partition: a flat table of weighted leaf regions — atoms — plus the ordered levels that group them. It is what a calendar is to time, for space.

Two things about geography shape the whole design:

• Levels need not nest. Real hierarchies cross-cut: a grid zone can straddle two states. Every conversion therefore routes through the atom layer, and cross-cutting levels work without special handling.
• Region codes are not unique across levels. The same code often names a district and the state containing it, so every lookup states its level.

Aggregation and disaggregation are a single operation, geo_recast(): values are projected down to atoms and aggregated up to the target, so the direction follows the level ranks.

Documentation by language

This is a multi-language project. The R implementation is complete; the C++ core and Python bindings are planned.

Language	Status	Documentation
R	Available	R reference and articles
C++	Phase 2 — planned	—
Python	Phase 3 — planned	—

A single implementation defines the behaviour, and language-agnostic golden fixtures under specs/ will keep the ports honest.

Getting started

# install.packages("remotes")
remotes::install_github("optimal2050/geoscales")

library(geoscales)

gs <- geoscale_example()

# fine -> coarse: totals are preserved
cap <- data.frame(atom = c("A1", "A2", "A3"), capacity = c(1, 2, 3))
geo_recast(cap, gs, from = "atom", to = "country", rule = "sum")

See Getting started for the full tour, and Building a Geoscale from Natural Earth for real-world geography — including the four Natural Earth pitfalls the provider handles for you.

Project

• R documentation
• Source on GitHub
• Companion package: timescales

Released under the Apache License 2.0.