:py:mod:`geomesher.area_weighted`
=================================

.. py:module:: geomesher.area_weighted

.. autoapi-nested-parse::

   Area Weighted Interpolation based on `tobler <https://github.com/pysal/tobler>`__.

   ..
       !! processed by numpydoc !!


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

.. py:function:: area_interpolate(source_df, target_df, extensive_variables = None, intensive_variables = None, categorical_variables = None, table = None, allocate_total = True, spatial_index = 'auto')

   
   Area interpolation for extensive, intensive and categorical variables.

   :Parameters: * **source_df** (:class:`geopandas.GeoDataFrame`) -- The source dataframe to get values from.
                * **target_df** (:class:`geopandas.GeoDataFrame`) -- The target dataframe to interpolate the values from ``source_df``.
                * **extensive_variables** (:class:`list`, *optional*) -- Columns in dataframes for extensive variables, defaults to ``None``.
                * **intensive_variables** (:class:`list`, *optional*) -- Columns in dataframes for intensive variables, defaults to ``None``.
                * **categorical_variables** (:class:`list`, *optional*) -- Columns in dataframes for categorical variables, defaults to ``None``.
                * **table** (:class:`scipy.sparse.csr_matrix`, *optional*) -- Area allocation source-target correspondence
                  table. If not provided, it will be built from ``source_df`` and
                  ``target_df``.
                * **allocate_total** (:class:`boolean`, *optional*) -- True if total value of source area should be
                  allocated. False if denominator is area of i. Note that the two cases
                  would be identical when the area of the source polygon is exhausted by
                  intersections. See Notes for more details. Defaults to True.
                * **spatial_index** (:class:`str`, *optional*) -- Spatial index to use to build the allocation of area from source
                  to target tables, defaults to ``auto``. It currently supports
                  the following values:

                  - ``source``: build the spatial index on ``source_df``
                  - ``target``: build the spatial index on ``target_df``
                  - ``auto``: attempts to guess the most efficient alternative.
                      Currently, this option uses the largest table to build the
                      index, and performs a ``query`` on the shorter table.

   :returns: :class:`geopandas.GeoDataFrame` -- new geodaraframe with interpolated variables as columns and ``target_df`` geometry
             as output geometry

   .. rubric:: Notes

   The assumption is both dataframes have the same coordinate reference system.
   For an extensive variable, the estimate at target polygon :math:`j` (default case) is:

   .. math::

       v_j = \sum_i v_i w_{i,j}

       w_{i,j} = \frac{a_{i,j}}{\sum_k a_{i,k}}

   If the area of the source polygon is not exhausted by intersections with
   target polygons and there is reason to not allocate the complete value of
   an extensive attribute, then setting ``allocate_total=False`` will use the
   following weights:

   .. math::

       v_j = \sum_i v_i w_{i,j}

       w_{i,j} = \frac{a_{i,j}}{a_i}

   where :math:`a_i` is the total area of source polygon :math:`i`.
   For an intensive variable, the estimate at target polygon :math:`j` is:

   .. math::

       v_j = \sum_i v_i w_{i,j}

       w_{i,j} = \frac{a_{i,j}}{\sum_k a_{k,j}}

   For categorical variables, the estimate returns ratio of presence of each
   unique category.















   ..
       !! processed by numpydoc !!