facilities
==========

.. py:module:: facilities

.. autoapi-nested-parse::

   Facility data retrieval and management module for accessibility analysis.

   This module provides functionality for retrieving, managing, and analyzing facility location data
   within specified administrative areas. It supports extracting facility data from OpenStreetMap (OSM),
   generating potential facility locations through grid sampling, and preparing data for accessibility
   and optimization analyses.

   .. rubric:: Examples

   Retrieve existing facilities and generate potential facility locations:

   >>> from pisa.administrative_area import AdministrativeArea
   >>> from pisa.facilities import Facilities
   >>>
   >>> # Get administrative area boundaries
   >>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
   >>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
   >>>
   >>> # Create a facilities object
   >>> facilities = Facilities(admin_area_boundaries=boundaries)
   >>>
   >>> # Get existing facilities from OpenStreetMap
   >>> existing = facilities.get_existing_facilities()
   >>> print(f"Found {len(existing)} existing facilities")
   >>>
   >>> # Generate potential facility locations (grid points)
   >>> potential = facilities.estimate_potential_facilities(spacing=0.05)
   >>> print(f"Generated {len(potential)} potential facility locations")

   .. seealso::

      :obj:`administrative_area`
          Module for retrieving administrative area boundaries

      :obj:`population`
          Module for population data processing

      :obj:`isopolygons`
          Module for calculating service areas around facilities



Attributes
----------

.. autoapisummary::

   facilities.logger


Classes
-------

.. autoapisummary::

   facilities.Facilities


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

.. py:data:: logger

.. py:class:: Facilities

   Retrieve and manage facility location data for a given administrative area.

   This class provides functionality to retrieve existing facilities within a specified administrative area from
   various data sources (currently supporting OpenStreetMap).

   :param admin_area_boundaries: The geographical boundaries of the administrative area for which to retrieve facilities
   :type admin_area_boundaries: Polygon or MultiPolygon
   :param data_src: The data source from which to retrieve facility data. Currently supported:
                    - "osm": OpenStreetMap (default: ``osm``)
   :type data_src: str, optional
   :param osm_tags: Dictionary of OpenStreetMap tags to identify facilities of interest (e.g., ``{'amenity': 'hospital'}``). (default: ``OSM_TAGS``)
   :type osm_tags: dict, optional

   .. rubric:: Notes

   The default OSM_TAGS are defined in the constants module and typically target health facilities. To use
   different facility types, provide custom osm_tags when creating the Facilities object.

   .. seealso::

      :obj:`AdministrativeArea`
          Class for retrieving administrative area boundaries

      :obj:`IsopolygonCalculator`
          Class for calculating service areas around facilities

   .. rubric:: Examples

   >>> from pisa.administrative_area import AdministrativeArea
   >>> from pisa.facilities import Facilities
   >>>
   >>> # Get an administrative area for a specific country and region
   >>> admin_area = AdministrativeArea("Timor-Leste", admin_level=1)
   >>> boundaries = admin_area.get_admin_area_boundaries("Baucau")
   >>>
   >>> # Get hospital facilities within the administrative area
   >>> facilities = Facilities(admin_area_boundaries=boundaries)
   >>> existing_facilities = facilities.get_existing_facilities()


   .. py:attribute:: admin_area_boundaries
      :type:  shapely.Polygon | shapely.MultiPolygon


   .. py:attribute:: data_src
      :type:  str
      :value: 'osm'



   .. py:attribute:: osm_tags
      :type:  dict


   .. py:method:: get_existing_facilities() -> pandas.DataFrame

      Retrieve existing facilities from the specified data source.

      This method acts as a dispatcher that calls the appropriate data source-specific method based on the `data_src`
      attribute of the Facilities instance.

      :returns:

                DataFrame containing facilities information with columns:

                    - ``osmid`` (index): Facility identifier (e.g., OSM ID for OpenStreetMap data)
                    - ``longitude``: Longitude coordinate of the facility
                    - ``latitude``: Latitude coordinate of the facility
      :rtype: pandas.DataFrame

      :raises NotImplementedError: If the specified data source is not implemented

      .. rubric:: Notes

      Currently, only the ``osm`` (OpenStreetMap) data source is implemented. To support additional data sources,
      implement new methods and update this dispatcher method accordingly, or refactor to use an abstract base class.



   .. py:method:: estimate_potential_facilities(spacing: float = 0.05) -> geopandas.GeoDataFrame

      Create a grid of potential facility locations within the administrative area.

      This method generates a regular grid of points within the administrative area boundaries that can be used as
      potential locations for new facilities in optimization scenarios.

      :param spacing: The distance between adjacent points in the grid, in coordinate units (degrees). Smaller values create a
                      denser grid with more potential facility locations.
      :type spacing: float

      :returns:

                GeoDataFrame containing potential facility locations with columns:

                    - ``longitude``: Longitude coordinate of the potential facility
                    - ``latitude``: Latitude coordinate of the potential facility
      :rtype: geopandas.GeoDataFrame

      .. rubric:: Notes

      The grid is created by:

          1. Finding the bounding box of the administrative area
          2. Creating a regular grid covering the entire bounding box
          3. Clipping the grid to include only points within the actual administrative area boundaries

      The resulting grid points are spaced at regular intervals determined by the spacing parameter.