Spatial Access

Common errors

• ModuleNotFoundError: No module named 'spatial-access'

  cause Attempting to import the library using a hyphen instead of an underscore, or the package is not installed.
  fix Ensure the package is installed via `pip install spatial-access` and then import using `import spatial_access as sa`.

• KeyError: 'some_missing_column_name'

  cause A GeoDataFrame provided to `Network` or `Access` is missing a required column (e.g., weight, capacity, demand) that was specified by name.
  fix Check your input GeoDataFrames (`nodes`, `edges`, `facilities`, `demand`) and ensure they contain the columns specified in the `spatial_access.Network` and `spatial_access.Access` constructors. Column names are case-sensitive.

• ValueError: The input network must be connected. Consider filtering to the largest connected component.

  cause The road network provided to `spatial_access.Network` is not fully connected (e.g., contains isolated islands of roads), which prevents shortest path calculations between all points.
  fix Pre-process your road network to ensure connectivity. You can often extract the largest connected component using `networkx` functions or similar tools before passing the data to `spatial_access`.

• pygeos.GEOSException: IllegalArgumentException: Points of LineString must have distinct coordinates

  cause Input geometry data (especially LineStrings in edges) contains invalid or malformed geometries, such as a LineString with identical start and end points, or other self-intersections.
  fix Inspect and clean your input GeoDataFrames for invalid geometries. Use `gdf.geometry.is_valid` to identify issues and `gdf.geometry.buffer(0)` or other `shapely` / `geopandas` tools for minor repairs.

Warnings

• breaking Prior to version 1.0.2, the internal C++ Dijkstra implementation could crash when the input road network contained multiple disconnected components, leading to unexpected program termination.
  Fix: Upgrade to version 1.0.2 or newer. Alternatively, ensure your input network is a single connected component or filter to the largest connected component before processing.
• gotcha Dropping non-existent columns from a road network GeoDataFrame would previously raise an error, interrupting the workflow.
  Fix: Upgrade to version 1.0.2 or newer, which gracefully handles attempts to drop non-existent columns. For older versions, ensure all specified columns for removal actually exist in the DataFrame.
• gotcha Coordinate Reference System (CRS) mismatches between input GeoDataFrames (nodes, edges, facilities, demand) can lead to incorrect distance calculations or errors during spatial operations. All input GeoDataFrames must share the same CRS.
  Fix: Always ensure that `nodes`, `edges`, `facilities`, and `demand` GeoDataFrames have a consistent CRS. Reproject them if necessary using `.to_crs()` before creating `Network` or `Access` objects. For example: `gdf.to_crs('EPSG:26918')` for projected coordinates suitable for distance calculations.
• gotcha The `spatial_access.Network` object expects specific column names for weights (e.g., 'length', 'travel_time') and the `Access` object expects 'capacity' and 'demand' columns. Using incorrect column names will result in `KeyError`.
  Fix: Verify that the column names passed to `sa.Network` and `sa.Access` constructors (e.g., `weight_col`, `facility_col_name`, `demand_col_name`) exactly match the column names in your input GeoDataFrames.

Install

• pip install spatial-access Install stable version

Imports

• spatial_access
  wrong:

  import spatial-access

  correct:

  import spatial_access as sa

  Python import statements use underscores, not hyphens, even if the PyPI package name uses hyphens.
• Network

  network = sa.Network(nodes, edges, 'weight_col')

  The Network class is typically accessed via the top-level spatial_access module alias.
• Access

  access_model = sa.Access(network, facilities, demand, 'facility_col', 'demand_col')

  The Access class is typically accessed via the top-level spatial_access module alias.

Quickstart

This quickstart demonstrates how to create a simple road network, define facilities and demand points using GeoDataFrames, and then compute spatial accessibility using the Two-Step Floating Catchment Area (2SFCA) method. It uses dummy data to ensure the example is runnable out-of-the-box.

from shapely.geometry import Point, LineString
import geopandas as gpd
import pandas as pd
import spatial_access as sa

# 1. Create dummy network data (nodes and edges)
# Nodes represent intersections or endpoints
nodes_df = pd.DataFrame({
    'id': [0, 1, 2, 3],
    'geometry': [Point(0, 0), Point(1, 0), Point(0, 1), Point(1, 1)]
})
nodes = gpd.GeoDataFrame(nodes_df, crs="EPSG:4326")

# Edges represent road segments connecting nodes
edges_df = pd.DataFrame({
    'id': [0, 1, 2, 3],
    'from': [0, 0, 1, 2],
    'to': [1, 2, 3, 3],
    'length': [1.0, 1.0, 1.0, 1.0], # A 'weight' or 'cost' column
    'geometry': [
        LineString([(0, 0), (1, 0)]),
        LineString([(0, 0), (0, 1)]),
        LineString([(1, 0), (1, 1)]),
        LineString([(0, 1), (1, 1)])
    ]
})
edges = gpd.GeoDataFrame(edges_df, crs="EPSG:4326")

# 2. Create dummy facility and demand data
# Facilities (e.g., hospitals, stores) with capacity
facilities_df = pd.DataFrame({
    'id': [0, 1],
    'capacity': [10, 15],
    'geometry': [Point(0.1, 0.1), Point(0.9, 0.9)]
})
facilities = gpd.GeoDataFrame(facilities_df, crs="EPSG:4326")

# Demand points (e.g., population centroids) with demand
demand_df = pd.DataFrame({
    'id': [0, 1],
    'demand': [5, 8],
    'geometry': [Point(0.2, 0.2), Point(0.8, 0.8)]
})
demand = gpd.GeoDataFrame(demand_df, crs="EPSG:4326")


# 3. Initialize Network and Access objects
# The 'length' column is used as the weight for shortest path calculations
network = sa.Network(nodes, edges, "length")

# Create the Access model, linking network, facilities, and demand
access_model = sa.Access(network, facilities, demand, "capacity", "demand")

# 4. Compute 2SFCA accessibility
# Using a distance threshold of 10 units (arbitrary for dummy data)
# and a Gaussian weight function. The result is (Si, Dj) where Si is 
# accessibility for demand points and Dj for facilities.
print("Calculating 2SFCA accessibility...")
accessibility_scores = access_model.two_sfca(10, weight_function="gaussian")

# Print accessibility scores for demand points
print("\nAccessibility scores for demand points (Si):")
print(accessibility_scores[0].head())