Spider Model

The Spider model computes the Euclidean distance (in meters) between activity locations and corresponding home locations.

This module is useful for mobility studies where the spatial relationship between daily destinations and home location is required. The function matches each activity point with its corresponding home location and computes the distance between them.

Distances are always returned in meters, regardless of the original CRS.

Function

add_distance_to_home()

Example

import geopandas as gpd
from activityspace.spider import add_distance_to_home

poi = gpd.read_file("eep.shp")
home = gpd.read_file("Home.shp")

result = add_distance_to_home(
    poi=poi,
    home=home,
    uniqueID="uid"
)

print(result.head())

The output GeoDataFrame will contain a new column:

dist_m

which stores the distance between the activity location and the home location in meters.

Parameters

add_distance_to_home(
    poi,
    home,
    *,
    uniqueID,
    home_key=None,
    distance_col="dist_m",
    metric_crs="auto",
    keep_original_crs=True,
    duplicate_home_policy="error",
    missing_value=np.nan,
)

Parameter description

poi

GeoDataFrame containing activity locations (points).

home

GeoDataFrame containing home locations (points).

uniqueID

Column used to match activity locations with home locations.

home_key

Optional column name in the home dataset if it differs from the POI key.

distance_col

Name of the output distance column.

metric_crs

Projected CRS used for distance calculation. By default, a suitable local UTM CRS is automatically selected.

keep_original_crs

If True, the output geometry is returned in the original POI CRS.

duplicate_home_policy

Strategy for handling duplicate home identifiers:

  • “error” – raise an error (default)

  • “first” – keep the first occurrence

  • “mean” – average coordinates for duplicate entries

missing_value

Value assigned when no matching home location is found.

CRS Handling

Distances must be computed in a projected coordinate system.

The function automatically:

  • detects geographic CRS

  • selects a suitable projected CRS

  • performs calculations in meters

  • optionally returns results in the original CRS

Notes

The Spider model is particularly useful for datasets where individuals report locations of daily activities relative to their home location. This includes mobility datasets derived from:

  • travel surveys

  • GPS tracking

  • participatory mapping

  • Public Participation GIS (PPGIS) studies

For methodological background and research applications of activity space analysis, please refer to the associated scientific publications.