population_served_by_isopolygons
================================

.. py:module:: population_served_by_isopolygons

.. autoapi-nested-parse::

   Compute population coverage by facility service areas (isopolygons).

   This module provides functions to determine which population points are covered by service areas
   (isopolygons) around facilities at different distance thresholds. It helps answer questions such as
   "How many people can reach a facility within X minutes?" or "Which populations are served by which
   facilities at different distance thresholds?"

   .. rubric:: Examples

   Retrieve population coverage for example points and polygons::

   >>> from shapely.geometry import Point, Polygon
   >>> import geopandas as gpd
   >>> import pandas as pd
   >>> from pisa.population_served_by_isopolygons import get_population_served_by_isopolygons
   >>>
   >>> # Get administrative area and facilities
   >>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
   >>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
   >>>
   >>> # Get grouped population
   >>> population = WorldpopPopulation(
   >>>     admin_area_boundaries=boundaries,
   >>>     iso3_country_code=country_code
   >>> )
   >>> grouped_population = population.get_population_gdf()
   >>>
   >>> facilities = Facilities(admin_area_boundaries=boundaries)
   >>> existing_facilities = facilities.get_existing_facilities()
   >>>
   >>> # Create a road network for travel time calculations
   >>> road_network = OsmRoadNetwork(
   >>>     admin_area_boundaries=boundaries,
   >>>     mode_of_transport="walking",
   >>>     distance_type="travel_time"
   >>> )
   >>> graph = road_network.get_osm_road_network()
   >>>
   >>> # Calculate isochrones (5, 10, 15 minutes walking)
   >>> isopolygon_calculator = OsmIsopolygonCalculator(
   >>>     facilities_df=existing_facilities,
   >>>     distance_type="travel_time",
   >>>     distance_values=[5, 10, 15],
   >>>     road_network=graph
   >>> )
   >>> isopolygons = isopolygon_calculator.calculate_isopolygons()
   >>>
   >>> # Find which population points are served by each isopolygon
   >>> result = get_population_served_by_isopolygons(grouped_population, isopolygons)

   .. seealso::

      :obj:`isopolygons`
          Module for generating service area polygons

      :obj:`facilities`
          Module for facility location and clustering

      :obj:`get_population_served_by_isopolygons`
          Main function for population coverage analysis



Functions
---------

.. autoapisummary::

   population_served_by_isopolygons.get_population_served_by_isopolygons


Module Contents
---------------

.. py:function:: get_population_served_by_isopolygons(grouped_population: geopandas.GeoDataFrame, isopolygons: pandas.DataFrame) -> pandas.DataFrame

   Identify population points that fall within each facility's isopolygons.

   This function performs a spatial join between population points and isopolygons
   representing service areas at various distances from facilities. It returns a DataFrame
   showing, for each facility (cluster) and distance threshold, which population points
   are contained within the corresponding service area.

   :param grouped_population: GeoDataFrame containing population points with geometry column.
                              The index values are used as identifiers in the result.
                              Must include a valid geometry column with point geometries.
   :type grouped_population: geopandas.GeoDataFrame
   :param isopolygons: DataFrame where each column starting with ``ID_`` contains Shapely Polygon objects
                       representing service areas at different distances. Each row represents a facility
                       isopolygon. The index values are used as ``Cluster_ID`` in the result.
   :type isopolygons: pandas.DataFrame

   :returns:

             DataFrame with columns:

                 - ``Cluster_ID``: The index from the isopolygons input
                 - One column for each ``ID_`` column in isopolygons, containing lists of
                   population indices that fall within the corresponding polygon
   :rtype: pandas.DataFrame

   :raises ValueError: If either input DataFrame is empty

   .. rubric:: Notes

   This function:

       1. Ensures both inputs have proper CRS (Coordinate Reference System)
       2. Performs a spatial join to find population points within each isopolygon
       3. Groups results by facility and distance threshold
       4. Returns population indices served by each facility at each distance threshold

   .. rubric:: Example

   Basic usage with sample data::

       grouped_population:
           index   geometry
           p0      POINT (...)
           p1      POINT (...)
           p2      POINT (...)

       isopolygons:
           index   ID_10           ID_20
           i0      POLYGON (...)   POLYGON (...)
           i1      POLYGON (...)   POLYGON (...)
           i2      POLYGON (...)   POLYGON (...)

       result = get_population_served_by_isopolygons(grouped_population, isopolygons):
           index   Cluster_ID   ID_10           ID_20
           0      i0          [p0, p1]       [p0, p1]
           1      i1          [p2]           []
           2      i2          []             [p1, p2]