oasislmf.preparation.summaries
==============================

.. py:module:: oasislmf.preparation.summaries


Attributes
----------

.. autoapisummary::

   oasislmf.preparation.summaries.calculated_summary_cols


Functions
---------

.. autoapisummary::

   oasislmf.preparation.summaries.get_useful_summary_cols
   oasislmf.preparation.summaries.get_xref_df
   oasislmf.preparation.summaries.get_summary_mapping
   oasislmf.preparation.summaries.merge_oed_to_mapping
   oasislmf.preparation.summaries.write_summary_levels
   oasislmf.preparation.summaries.write_mapping_file
   oasislmf.preparation.summaries.get_ri_inuring_priority_output_levels
   oasislmf.preparation.summaries.generate_summaryxref_files
   oasislmf.preparation.summaries.get_exposure_summary
   oasislmf.preparation.summaries.write_exposure_summary


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

.. py:function:: get_useful_summary_cols(oed_hierarchy)

.. py:data:: calculated_summary_cols

.. py:function:: get_xref_df(il_inputs_df)

.. py:function:: get_summary_mapping(inputs_df, oed_hierarchy, is_fm_summary=False)

   Create a DataFrame with linking information between Ktools `OasisFiles`
   And the Exposure data

   :param inputs_df: datafame from gul_inputs.get_gul_input_items(..)  / il_inputs.get_il_input_items(..)
   :type inputs_df: pandas.DataFrame
   :param oed_hierarchy: OED profile hierarchy, used to resolve the acc/loc/pol/port column names to keep
   :type oed_hierarchy: dict
   :param is_fm_summary: Indicates whether an FM summary mapping is required
   :type is_fm_summary: bool

   :returns: Subset of columns from gul_inputs_df / il_inputs_df
   :rtype: pandas.DataFrame


.. py:function:: merge_oed_to_mapping(summary_map_df, exposure_df, oed_column_join, oed_column_info)

   Create a factorized col (summary ids) based on a list of oed column names

   {'Col_A': 0, 'Col_B': 1, 'Col_C': 2}

   :param summary_map_df: dataframe return from get_summary_mapping
   :type summary_map_df: pandas.DataFrame
   :param exposure_df: Summary map file path
   :type exposure_df: pandas.DataFrame
   :param oed_column_join: column to join on
   :type oed_column_join: list
   :param oed_column_info: Dictionary of columns to pick from exposure_df and their default value
   :type oed_column_info: dict

   :returns: New DataFrame of summary_map_df + exposure_df merged on exposure index
   :rtype: pandas.DataFrame


.. py:function:: write_summary_levels(exposure_df, accounts_df, exposure_data, target_dir)

   Json file with list Available / Recommended columns for use in the summary reporting

   Available: Columns which exists in input files and has at least one non-zero / NaN value
   Recommended: Columns which are available + also in the list of `useful` groupings SUMMARY_LEVEL_LOC

   {
       'GUL': {
           'available': ['AccNumber',
                        'LocNumber',
                        'istenant',
                        'buildingid',
                        'countrycode',
                        'latitude',
                        'longitude',
                        'streetaddress',
                        'postalcode',
                        'occupancycode',
                        'constructioncode',
                        'locperilscovered',
                        'BuildingTIV',
                        'ContentsTIV',
                        'BITIV',
                        'PortNumber'],

       'IL': {
               ... etc ...
       }
   }


.. py:function:: write_mapping_file(sum_inputs_df, target_dir, is_fm_summary=False)

   Writes a summary map file, used to build summarycalc xref files.

   :param sum_inputs_df: dataframe return from get_summary_mapping
   :type sum_inputs_df: pandas.DataFrame
   :param target_dir: directory the summary map file is written to
   :type target_dir: str
   :param is_fm_summary: Indicates whether an FM summary mapping is required
   :type is_fm_summary: bool

   :returns: Summary xref file path
   :rtype: str


.. py:function:: get_ri_inuring_priority_output_levels(run_dir)

   Load the mapping from OED InuringPriority to RI output level from the input directory.

   The mapping is created during input generation and records, for each OED
   InuringPriority value, the index of the last RI layer (output level) that
   belongs to that priority.  When an InuringPriority spans multiple risk
   levels (e.g. LOC and ACC), its output level is the highest RI layer index
   among those risk levels.

   :param run_dir: Directory containing ``ri_inuring_priority_output_levels.json``
   :type run_dir: str

   :returns: mapping ``{inuring_priority: output_level}`` with integer keys/values
   :rtype: dict


.. py:function:: generate_summaryxref_files(location_df, account_df, model_run_fp, analysis_settings, il=False, ri=False, rl=False, intermediary_csv=False)

   Top level function for creating the summaryxref files from the manager.py

   :param location_df: Source locations, joined to the summary map to build the
                       summary groupings and their description files
   :type location_df: pandas.DataFrame
   :param account_df: Source accounts, joined the same way. Required for the il,
                      ri and rl summary levels
   :type account_df: pandas.DataFrame
   :param model_run_fp: Model run directory file path
   :type model_run_fp: str
   :param analysis_settings: Model analysis settings file
   :type analysis_settings: dict
   :param il: Boolean to indicate the insured loss level mode - false if the
              source accounts file path not provided to Oasis files gen.
   :type il: bool
   :param ri: Boolean to indicate the RI loss level mode - false if the
              source accounts file path not provided to Oasis files gen.
   :type ri: bool
   :param rl: Boolean to indicate the RL loss level mode - false if the
              source accounts file path not provided to Oasis files gen.
   :type rl: bool
   :param intermediary_csv: If True, also write a csv copy of each summaryxref file
                            alongside the binary
   :type intermediary_csv: bool


.. py:function:: get_exposure_summary(exposure_df, keys_df, exposure_profile=get_default_exposure_profile(), additional_fields=[])

   Create exposure summary as dictionary of TIVs and number of locations
   grouped by peril and validity respectively. returns a python dict().

   :param exposure_df: source exposure dataframe
   :type exposure_df: pandas.DataFrame
   :param keys_df: dataFrame holding keys data (success and errors)
   :type keys_df: pandas.DataFrame
   :param exposure_profile: profile defining exposure file
   :type exposure_profile: dict
   :param additional_fields: extra exposure columns to group the summary by, on top of loc_id
   :type additional_fields: list

   :returns: Exposure summary dictionary
   :rtype: dict


.. py:function:: write_exposure_summary(target_dir, exposure_df, keys_fp, keys_errors_fp, exposure_profile, additional_fields=[])

   Create exposure summary as dictionary of TIVs and number of locations
   grouped by peril and validity respectively. Writes dictionary as json file
   to disk.

   :param target_dir: directory on disk to write exposure summary file
   :type target_dir: str
   :param exposure_df: source exposure dataframe
   :type exposure_df: pandas.DataFrame
   :param keys_fp: file path to keys file
   :type keys_fp: str
   :param keys_errors_fp: file path to keys errors file
   :type keys_errors_fp: str
   :param exposure_profile: profile defining exposure file
   :type exposure_profile: dict
   :param additional_fields: list of additional OED fields to add to exposure summary file
   :type additional_fields: list[str]

   :returns: Exposure summary file path
   :rtype: str