How to Use?¶

This page demonstrates a typical workflow using ActivitySpace Tools. The example follows the same steps implemented in the package’s test script and illustrates how the different models can be used together in a research pipeline.

The example script included with the package performs the following steps:

Load spatial datasets
Compute distance-to-home metrics (Spider model)
Generate activity space polygons (Home Range model)
Generate raster exposure surfaces (IREM model)
Summarize raster exposure values
Calculate geometric metrics of activity spaces
Convert IREM rasters to polygons

The example workflow uses a small sample dataset included with the package to demonstrate how the models work together.

Required Input Data¶

The example workflow uses three spatial datasets:

Home locations¶

Point dataset representing the home locations of individuals.

Everyday errand points¶

Point dataset representing activity locations or destinations visited by individuals.

Routes¶

Line dataset representing travel routes between home locations and destinations.

Loading Data¶

The workflow begins by loading spatial data using GeoPandas.

import geopandas as gpd

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

Spider Model: Distance to Home¶

The Spider model calculates the distance between each activity location and the individual’s home.

from activityspace.spider import add_distance_to_home

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

The function adds a new column dist_m representing the distance between the activity point and the home location.

Home Range Model¶

The Home Range model constructs an activity space polygon for each individual based on their home location and activity points.

from activityspace.home_range import model_home_range

home_range = model_home_range(
    poi=poi,
    home=home,
    uniqueID="uid",
    home_effect_radius_m=500,
    poi_effect_radius_m=100
)

Each individual receives a polygon representing the spatial extent of their activity space.

IREM Model¶

The Individualized Residential Exposure Model (IREM) generates continuous raster exposure surfaces representing how individuals experience spatial environments during their daily mobility.

from activityspace.irem import run_irem, IREMParams

params = IREMParams(
    home_effect_radius_m=500,
    poi_effect_radius_m=100,
    route_effect_radius_m=10,
    route_point_interval_m=10,
    boundary_point_interval_m=30,
    boundary_point_weight=0.05,
    cell_size_m=10
)

rasters = run_irem(
    home=home,
    poi=poi,
    routes=routes,
    out_dir="irem_rasters",
    uniqueID="uid",
    destinationID="DESTid",
    travel_mode_col="tmod",
    poi_weight_col="Freq",
    params=params
)

Raster Exposure Summary¶

Raster outputs generated by IREM can be summarized using built-in analytics functions.

from activityspace.analytics import summarize_rasters

summary = summarize_rasters(
    raster_dir="irem_rasters",
    filename_prefix="irem_"
)

Exposure Summary¶

Exposure values can also be summarized for each individual’s activity space polygon.

from activityspace.analytics import exposure_summary

exposure = exposure_summary(
    gdf=home_range,
    raster_dir="irem_rasters",
    uniqueID="uid"
)

Geometry Metrics¶

Activity space polygons can be analyzed using geometric metrics such as area, perimeter, elongation, and orientation.

from activityspace.analytics import as_geometry_calculator

geom = as_geometry_calculator(
    polygons=home_range,
    uniqueID="uid"
)

Converting Exposure Rasters to Polygons¶

IREM raster surfaces can also be converted into polygons representing areas where exposure exceeds a specified threshold.

from activityspace.analytics import irem_rasters_to_polygons

irem_polygons = irem_rasters_to_polygons(
    irem_raster_dir="irem_rasters",
    uniqueID="uid"
)

Example Script¶

A complete end-to-end workflow demonstrating all steps described above is provided in the package test script.

Running the script will generate all intermediate outputs and final results using the included sample dataset.

This example demonstrates the typical research pipeline supported by ActivitySpace Tools.