:py:mod:`hazimp.aggregate`
==========================

.. py:module:: hazimp.aggregate

.. autoapi-nested-parse::

   Aggregating impact data into a chloropleth map.



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


Functions
~~~~~~~~~

.. autoapisummary::

   hazimp.aggregate.choropleth
   hazimp.aggregate.aggregate_categorisation
   hazimp.aggregate.aggregate_loss_atts



Attributes
~~~~~~~~~~

.. autoapisummary::

   hazimp.aggregate.LOGGER
   hazimp.aggregate.DRIVERS
   hazimp.aggregate.COLNAMES
   hazimp.aggregate.loss_categories
   hazimp.aggregate.aggregate_functions
   hazimp.aggregate.aggregate_label


.. py:data:: LOGGER
   

   

.. py:data:: DRIVERS
   

   

.. py:data:: COLNAMES
   

   

.. py:data:: loss_categories
   

   

.. py:data:: aggregate_functions
   :annotation: = ['mean', 'min', 'max']

   

.. py:data:: aggregate_label
   

   

.. py:function:: choropleth(dframe, boundaries, impactcode, bcode, filename, fields, categories, categorise) -> bool

   Aggregate to geospatial boundaries using joins on attributes and save to
   file.

   :param dframe: `pandas.DataFrame` containing point data to be aggregated
   :param str boundaries: File name of a geospatial dataset that contains
                 geographical boundaries to serve as aggregation boundaries
   :param str impactcode: Field name in the `dframe` to aggregate by
   :param str bcode: Corresponding field name in the geospatial dataset.
   :param str filename: Destination file name. Must have a valid extension of
                        `shp`, `json` or `gpkg`.
                        See `import fiona; fiona.supported_drivers` for a
                        complete list of options, but at this time only three
                        have been implemented.
   :param boolean categories: Add columns for the number of buildings in each
                              damage state defined in the 'Damage state'
                              attribute. This requires that a 'categorise`
                              job has been included in the pipeline, which in
                              turn requires the bins and labels to be defined
                              in the job configuration.
   :param dict categorise: categorise job attributes

   NOTE::

       Presently, using `categories`=True will not do any categorisation of
       the mean damage index for the aggregation areas.

   :param dict fields: A `dict` with keys of valid column names (from the
                       `DataFrame`) and values being lists of aggregation
                       functions to apply to the columns.

   For example::

       fields = {'structural': ['mean']}

   See
   https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html#aggregation
   for more guidance on using aggregation with `DataFrames`


.. py:function:: aggregate_categorisation(aggregate, categorise: dict, fields: dict, field_name: str)

   Categorise aggregated field values into discrete intervals.

   :param aggregate: `pandas.DataFrame` containing aggregated data
   :param categorise: categorise job attributes
   :param fields: fields to aggregate
   :param field_name: name of categorised column


.. py:function:: aggregate_loss_atts(dframe, groupby=None, kwargs=None)

   Aggregate the impact data contained in a `pandas.DataFrame`

   :param dframe: `pandas.DataFrame` that contains impact data
   :param str groupby: A column in the `DataFrame` that corresponds to
           regions by which to aggregate data
   :param dict kwargs: A `dict` with keys of valid column names (from the
           `DataFrame`) and values being lists of aggregation functions to
           apply to the columns.

   For example::

       kwargs = {'REPLACEMENT_VALUE': ['mean', 'sum'],
               'structural': ['mean', 'std']}

   See
   https://pandas.pydata.org/pandas-docs/stable/user_guide/groupby.html#aggregation
   for more guidance on using aggregation with `DataFrames`

   :returns: A `pandas.GroupBy` object.