Service Provision Analysis

This module evaluates how well services (e.g., schools, clinics, shops) cover residential buildings based on their capacity and accessibility. It models demand–supply relationships and provides tools to analyze, visualize, and adjust service coverage.

Service provision analysis helps estimate how effectively urban infrastructure meets population needs.

Evaluate Initial Provision

Calculates provision scores between population points and service facilities and returns a objectnat.ProvisionResult. The result keeps the sparse building-service allocation matrix together with per-building and per-service summary tables. This separates the calculation step from the materialization of GeoDataFrames for mapping or export.

The calculation considers:

  • Distance or time thresholds

  • Facility capacity

  • Demand distribution

objectnat.get_service_provision(*, buildings, distance_matrix, services, threshold, buildings_demand_column='demand', services_capacity_column='capacity', seed=0)[source]

Compute service provision between demand locations and service facilities.

The function implements a gravity-based allocation model: service capacity is distributed across nearby demand points with weights that decay with the square of distance (or generalized cost). Closer buildings receive proportionally higher shares of the available capacity.

Parameters:

  • buildings (GeoDataFrame) – GeoDataFrame of demand locations. Must include a numeric demand column.

  • distance_matrix (DataFrame) – OD cost matrix where rows are buildings.index and columns are services.index. Units must match threshold.

  • services (GeoDataFrame) – GeoDataFrame of service facilities. Must include a numeric capacity column.

  • threshold (float) – Normative cost threshold. Units are the same as in distance_matrix.

  • buildings_demand_column (str) – Column name of building demand values. Default is "demand".

  • services_capacity_column (str) – Column name of service capacity values. Default is "capacity".

  • seed (int) – Seed for the random number generator used to allocate demand across services. The model is otherwise deterministic, so a fixed seed yields reproducible results; vary it to sample alternative allocations. Default is 0.

Returns:

Dataclass with a sparse building-service flow matrix, building metrics, service metrics, the aligned distance matrix, and the provision threshold.

Return type:

ProvisionResult

Provision Result

ProvisionResult is the central output of service provision analysis. It is designed to be lightweight enough for recalculation and explicit enough for downstream joins.

class objectnat.ProvisionResult(flow, demand_rows, capacity_rows, distance_matrix, threshold)[source]

Result of service provision calculation.

Parameters:
flow

Sparse building-service allocation matrix. Rows match building indices, columns match service indices, and non-zero values are allocated demand units.

demand_rows

Per-building metrics indexed like flow.index. Includes original demand, remaining demand, supplied demand inside/outside the threshold, minimum distance, average weighted distance, and provision value.

capacity_rows

Per-service metrics indexed like flow.columns. Includes original capacity, remaining capacity, carried capacity inside/outside the threshold, and total service load.

distance_matrix

Aligned OD cost matrix used for the calculation. Its index and columns must match flow.

threshold

Normative distance or time threshold used to split flows into within-threshold and outside-threshold metrics.

The main fields are:

  • flow — sparse building-service matrix. Rows match building indices, columns match service indices, and non-zero values are allocated demand.

  • demand_rows — per-building metrics, including original demand, remaining demand, supplied demand inside/outside the normative threshold, minimum distance, average weighted distance, and provision value.

  • capacity_rows — per-service metrics, including capacity, remaining capacity, carried capacity inside/outside the threshold, and total service load.

  • distance_matrix — aligned cost matrix used for the calculation.

  • threshold — normative distance or time threshold used to classify within-threshold and outside-threshold flows.

Materialize GeoDataFrames

Use the helper functions below to join calculated provision metrics back to source objects and to create link geometries between buildings and services.

objectnat.get_provision_buildings(buildings_gdf, provision_result)[source]

Join provision demand metrics to buildings.

Existing columns with the same names as provision metrics are dropped and replaced. The returned object preserves the input type and index.

Return type:

GeoDataFrame | DataFrame

Parameters:
objectnat.get_provision_services(services_gdf, provision_result)[source]

Join provision capacity metrics to services.

Existing columns with the same names as provision metrics are dropped and replaced. The returned object preserves the input type and index.

Return type:

GeoDataFrame | DataFrame

Parameters:

Build building-service link geometries from non-zero provision flows.

Services are reprojected to the buildings CRS when both CRS values are set and differ. Empty flows return an empty GeoDataFrame. Links whose building or service ids are absent from the supplied GeoDataFrames are filtered out.

Return type:

GeoDataFrame

Parameters:
service_provision_initial

Initial service provision analysis — demand–supply balance based on accessibility.

Recalculate Provision

Allows recalculation of provision results after tightening the maximum allowed link distance without recomputing the full OD-matrix. Existing flows whose cost exceeds new_max_dist are removed, and aggregate metrics are rebuilt. Removed demand is not redistributed to other services; run objectnat.get_service_provision() again when a full reallocation is needed.

Recalculate provision result after tightening the maximum allowed link distance.

Flows whose cost exceeds new_max_dist are removed, and building/service aggregates are recomputed without redistributing removed demand.

Return type:

ProvisionResult

Parameters:
service_provision_recalculated

Recalculated provision results using adjusted travel-time thresholds.

Clip to Analysis Area

Restricts provision outputs to a given geographic boundary (e.g., administrative region, neighborhood, planning area).

objectnat.clip_provision(buildings, services, links, selection_zone)[source]

Clip service provision outputs to a specific geographic boundary.

Keeps only buildings that intersect selection_zone, links that connect to the kept buildings, and services referenced by those links.

Return type:

tuple[GeoDataFrame, GeoDataFrame, GeoDataFrame]

Parameters:
service_provision_clipped

Provision results clipped to a selected administrative boundary.

Example notebook

Building-to-Service Travel Time Matrix with Intermodal Graph Service Provision Analysis