Analytics Module

The analytics module provides tools for analyzing outputs generated by the ActivitySpace Tools workflow.

These functions are designed to work with:

  • home range polygons

  • IREM raster outputs

  • optional environmental rasters

  • numeric vectors (e.g., travel distances)

The tools support common post-processing tasks in mobility and exposure analysis workflows.

Expected IREM Raster Structure

The raster directory must contain files named:

irem_<uniqueID>.tif

Example:

irem_409683.tif
irem_425004.tif

The <uniqueID> component must correspond to the identifier used in your vector datasets.

Raster Summary Tools

summarize_rasters()

Compute exposure summaries for each raster in an IREM output directory.

For each raster, the function:

  1. Reads the raster values

  2. Replaces nodata values (default: 0)

  3. Computes mean exposure

  4. Computes total exposure

Example:

from activityspace.analytics import summarize_rasters

df = summarize_rasters(
    raster_dir="outputs/irem_rasters",
    filename_prefix="irem_"
)

The result is a pandas DataFrame containing:

  • uniqueID

  • raster_path

  • mean

  • total

exposure_summary()

Attach raster exposure metrics to a GeoDataFrame.

Example:

import geopandas as gpd
from activityspace.analytics import exposure_summary

gdf = gpd.read_file("people.gpkg")

gdf2 = exposure_summary(
    gdf=gdf,
    raster_dir="outputs/irem_rasters",
    uniqueID="uid",
)

The returned GeoDataFrame contains additional exposure columns.

Geometry Metrics

as_geometry_calculator()

Compute geometric properties of polygon datasets.

Internally, geometries are temporarily reprojected to an automatically selected local projected CRS so that measurements are computed in meters.

Metrics added:

  • area_m2 – polygon area in square meters

  • perim_m – polygon perimeter in meters

  • elong – elongation ratio

  • orient – orientation of the major axis (degrees)

Example:

import geopandas as gpd
from activityspace.analytics import as_geometry_calculator

hr = gpd.read_file("home_ranges.gpkg")

hr_metrics = as_geometry_calculator(
    polygons=hr,
    uniqueID="uid"
)

Landtype Exposure Tools

These functions combine IREM rasters with an environmental raster (e.g., green space mask, NDVI, water, or noise).

Exposure is calculated as:

IREM * LANDTYPE

Two metrics are produced:

  • total exposure

  • average exposure

compute_landtype_exposure()

Return exposure statistics in a table.

Example:

from activityspace.analytics import compute_landtype_exposure

df = compute_landtype_exposure(
    irem_raster_dir="outputs/irem_rasters",
    landtype_raster="rasters/green_mask.tif",
    label="green"
)

attach_landtype_exposure()

Attach exposure metrics to a GeoDataFrame.

Example:

from activityspace.analytics import attach_landtype_exposure

gdf2 = attach_landtype_exposure(
    gdf=gdf,
    irem_raster_dir="outputs/irem_rasters",
    landtype_raster="rasters/green_mask.tif",
    label="green",
    uniqueID="uid"
)

IREM Raster to Polygon Conversion

irem_rasters_to_polygons()

Convert IREM rasters into polygons using percentile thresholding.

Algorithm:

  1. Read raster values

  2. Compute percentile threshold

  3. Mask pixels above the threshold

  4. Polygonize the mask

  5. Dissolve into one polygon per individual

Example:

from activityspace.analytics import irem_rasters_to_polygons

polys = irem_rasters_to_polygons(
    irem_raster_dir="outputs/irem_rasters",
    uniqueID="uid"
)

Jenks Threshold Tool

optimum_distance_jenks()

Estimate an empirical threshold from a numeric vector using Jenks natural breaks.

Example:

from activityspace.analytics import optimum_distance_jenks

values = poi["dist_m"].dropna()

result = optimum_distance_jenks(
    values,
    gvf_target=0.98,
    percentile=80
)

Typical Workflow

A common workflow using these tools is:

  1. Run run_irem() to generate exposure rasters.

  2. Summarize rasters using summarize_rasters().

  3. Attach exposure metrics using exposure_summary().

  4. Compute geometry metrics for activity space polygons.

  5. Convert rasters to polygons if needed.

  6. Optionally compute landtype exposure.

  7. Derive empirical thresholds using Jenks.

Notes

The analytics module is designed for reproducible research workflows in activity space modeling and environmental exposure analysis.

These tools are particularly useful for datasets describing everyday mobility and participatory mapping data, including Public Participation GIS (PPGIS) studies.