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:

1. Load spatial datasets
2. Compute distance-to-home metrics (Spider model)
3. Generate activity space polygons (Home Range model)
4. Generate raster exposure surfaces (IREM model)
5. Summarize raster exposure values
6. Calculate geometric metrics of activity spaces
7. Convert IREM rasters to polygons

The example workflow uses a small sample dataset included with the
package to demonstrate how the models work together. :contentReference[oaicite:0]{index=0}


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**.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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="travelMode",
       poi_weight_col="weight",
       params=params
   )


Raster Exposure Summary
-----------------------

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

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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. :contentReference[oaicite:1]{index=1}


Further Reading
---------------

The conceptual background and methodological details of the models
implemented in this package are described in the associated
scientific publications. Users interested in the theoretical
foundations of activity space modeling and exposure analysis are
encouraged to consult these publications.