IREM Model

The IREM model (Individualized Residential Exposure Model) generates one raster exposure surface per individual and writes the results as GeoTIFF files.

The model combines:

  • home locations

  • activity locations

  • routes between home and destinations

to produce individualized exposure surfaces that can be used in mobility and environmental exposure analysis.

The implementation is designed for reproducible research workflows and supports restartable processing for longer runs.

Function

run_irem()

What the model does

For each individual, the model:

  1. Builds a person-specific boundary using home locations, activity locations, and routes

  2. Generates weighted point inputs from home locations, activity points, route points, and boundary support points

  3. Creates raster surfaces using inverse distance weighting (IDW)

  4. Sums the resulting surfaces

  5. Writes the final raster as a clipped GeoTIFF

Inputs

The function requires three GeoDataFrames.

home

Point dataset containing home locations.

Required:

  • person identifier column

  • Point geometry

poi

Point dataset containing activity locations or destinations.

Required:

  • person identifier column

  • destination identifier column

  • POI weight column

  • Point geometry

Optional:

  • travel mode column

routes

Line dataset containing routes between home and destinations.

Required:

  • destination identifier column

  • LineString or MultiLineString geometry

Example

import geopandas as gpd
from activityspace.irem import run_irem, IREMParams

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

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,
)

written_files = run_irem(
    home=home,
    poi=poi,
    routes=routes,
    out_dir="outputs/irem_rasters",
    uniqueID="uid",
    destinationID="DESTid",
    travel_mode_col="travelMode",
    poi_weight_col="weight",
    params=params,
)

print(f"Wrote {len(written_files)} rasters.")

Output

The function writes one raster per individual using the naming pattern:

irem_<uniqueID>.tif

The function returns a list of output file paths.

Rasters are written in a projected metric CRS chosen automatically from the home locations, and each raster is clipped to the individual’s boundary geometry.

Parameters

run_irem(
    home,
    poi,
    routes,
    *,
    out_dir,
    uniqueID="uniqueID",
    destinationID="destinationID",
    travel_mode_col="travelMode",
    poi_weight_col="weight",
    max_poi_weight=30.0,
    params=IREMParams(),
    mode_map=None,
    default_mode="motorized",
    skip_existing=True,
    show_progress=True,
    continue_on_error=True,
)

Important parameter notes

out_dir

Output folder where GeoTIFF files will be written.

uniqueID

Column identifying individuals in the home and POI layers.

destinationID

Column linking POIs to route geometries.

travel_mode_col

Optional travel mode column stored in the POI layer.

poi_weight_col

Column storing POI weights.

max_poi_weight

Maximum allowed POI weight. Values are clamped to the range [0, max_poi_weight] and normalized internally to [0, 1].

params

Optional IREMParams object used to tune model behavior.

mode_map

Optional dictionary for custom travel mode mapping.

default_mode

Fallback travel mode used when no valid mode is available.

skip_existing

If True, existing output rasters are skipped.

show_progress

If True, a progress bar is shown when tqdm is available.

continue_on_error

If True, processing continues even if an individual fails.

Travel mode handling

Travel mode is read from the POI layer and mapped internally to one of:

  • walk

  • bike

  • motorized

If no travel mode column is available, the default mode is used.

Route influence is scaled by travel mode:

  • walk: 1.0

  • bike: 1 / 3.4

  • motorized: 1 / 10

A custom mode_map can be supplied if your data use different labels.

POI weight handling

The poi_weight_col column is optional. If the specified column does not exist in the POI dataset, a UserWarning is raised and all destinations are assigned equal weight (max_poi_weight).

When the column is present, weights are processed as follows:

  • values are converted to numeric form

  • missing values are replaced with the mean of available values

  • values below 0 are set to 0

  • values above max_poi_weight are set to max_poi_weight

  • values are normalized internally to the range [0, 1]

This makes the function easier to use with differently scaled survey data.

IREMParams

Model settings can be adjusted through IREMParams.

IREMParams(
    home_effect_radius_m=500.0,
    poi_effect_radius_m=100.0,
    route_effect_radius_m=10.0,
    route_point_interval_m=5.0,
    boundary_point_interval_m=30.0,
    boundary_point_weight=0.05,
    cell_size_m=5.0,
    idw_power=2.0,
    idw_k=12,
    nodata=0.0,
    filename_prefix="irem_",
)

These parameters control:

  • home, POI, and route influence distances

  • route densification

  • boundary support sampling

  • raster resolution

  • IDW interpolation behavior

  • output file naming

Restartable processing

The IREM workflow supports restartable processing.

If skip_existing=True, the function checks the output directory and skips any individual whose raster already exists. This makes it easier to resume long-running processing without repeating completed outputs.

Progress and failures

When progress reporting is enabled, the function iterates over individuals and reports the current identifier.

If an individual fails:

  • the identifier and error message are logged (logging.WARNING)

  • processing continues if continue_on_error=True

Progress and failure messages are emitted through Python’s standard logging module under the activityspace.irem logger. To see them, configure a handler in your application (e.g. logging.basicConfig(level=logging.INFO)).

This behavior is helpful for larger batch runs.

Notes

The IREM model is especially useful for data describing everyday mobility and spatial exposure, including participatory mapping and Public Participation GIS (PPGIS) datasets where individuals report destinations and travel behavior.

For methodological background and research applications, please refer to the associated scientific publications.