reblock

Detect the deeply-nested fabric of an informal settlement and thread streets through it so every home lands within a few parcels of a road. reblock screens a whole city for its most access-starved blocks, grows each into a right-sized region, routes complementary roads with a pluggable method, and grades every proposal on the same two axes — permeability bought against displacement — all as composable Hydra stages.

Setup

git clone --recurse-submodules <repo-url>
# (or, if already cloned: git submodule update --init --recursive)

# Install uv: https://docs.astral.sh/uv/getting-started/installation/
uv sync          # the environment, from uv.lock (`make` and `uv run` keep it in sync after)
make hooks       # once per clone: points core.hooksPath at .githooks/

Common tasks

make test        # pytest + coverage, then the web/ node suite (~4 min with the derivation
                 #   cache warm, measured 2026-10-05; the slow tests re-solve permeability on
                 #   the 6,619-parcel spine block, which a cold cache makes much longer.
                 #   `make wheel && uv run pytest -m "not slow"` skips them; the wheel is what
                 #   the site-page tests read from dist/.)
make typecheck   # mypy --strict + tsc --noEmit (web/)
make lint        # ruff check -- the formatting gate, in the hook and in CI
make hooks       # install the pre-commit hook (once per clone)
make check       # lint + typecheck + test

There is no fmt task, deliberately. ruff format reformats 200 of this repo's 215 files, leaves 12 lines over the E501 limit it cannot split, and moves a # type: ignore off the line it suppresses — measured, and argued in full at .githooks/pre-commit. ruff check is the gate instead, and it already owns line length (E501) and import order (I).

Quickstart

Render one block's access-depth heatmaps (before, and after a road-building method) by targeting it with block_ids — no whole-city pass needed:

uv run python -m reblock.run data=capetown method=clearance eval=kcomplexity \
  "block_ids=[[ZAF.9.3.1_1_44882]]" render.enabled=true

Or screen a whole city for dense/deep informal blocks and reblock the worst survivors in one command:

uv run python -m reblock.run data=capetown_full screen=dense_compact method=clearance \
  eval=kcomplexity render.enabled=true flagged_map.enabled=true max_blocks=5

The first capetown_full run downloads + caches the full metro under ~/.cache/reblock (nothing committed); later runs are instant. Outputs land in the Hydra run dir (outputs/<date>/<time>/). Quote "block_ids=[...]" so the shell doesn't glob the brackets.

The pipeline

Each stage is a swappable Hydra config group; a run composes them left to right:

data (the city) → screen (pick blocks) → region_builder (grow each into a region) → method (route the roads) → eval (score) → render.

• screen — identity (reblock exactly what you list) or dense_compact (flag deep informal blocks). What it scores on is the top-level metric group: the default depth_density_proxy is √(n·A)/P · n/A — the depth proxy times density — computed from building count, area and perimeter alone, so it sweeps a whole metro in one pass. metric=depth and metric=depth_density instead peel a proxy-pre-filtered top slice (proxy_keep_n); metric_gate sets the absolute floor. Validated against ground truth in the screen bake-off.
• region_builder — identity, convex_hull (bridge disjoint seed blocks), dense_cluster (grow a seed into a max_buildings-sized contiguous region by that same metric, so growth follows the deep fabric), or shape_standardizing.
• method — the reblocker: clearance (least-cost roads on a parametric routing substrate — the default), peel, topology, greedy_arterial, resistance_lp, euclidean_grid, or osm_footpaths (the network residents already walk, used as an as-built baseline). See conf/method/ for the full set, and Methods for each one on the ground with its own numbers.
• eval — the per-run scorer: kcomplexity by default, with access_burden, structure and weakdual_k as alternatives. The published head-to-head grading is separate: reblock.compare sweeps permeability against displacement and emits the frontier every method is compared on: uv run python -m reblock.compare, which takes Hydra overrides of conf/compare_config.yaml the same way reblock.run does of conf/config.yaml.

Examples

Every flagship run lives in examples/ — figures, lens CSVs, and a generated README per run. The results themselves are written up on the site, which builds its tables and figures from those same artifacts: Frontier grades the reblockers, Screen bake-off grades the screen against the City of Cape Town's structure survey, and Nairobi runs the same metric variants on a second city.

method-comparison	multiblock_depth_density