oasislmf.pytools.common.input_files
===================================

.. py:module:: oasislmf.pytools.common.input_files


Attributes
----------

.. autoapisummary::

   oasislmf.pytools.common.input_files.logger
   oasislmf.pytools.common.input_files.AMPLIFICATIONS_FILE
   oasislmf.pytools.common.input_files.CORRELATIONS_FILENAME
   oasislmf.pytools.common.input_files.COVERAGES_FILE
   oasislmf.pytools.common.input_files.EVENTRATES_FILE
   oasislmf.pytools.common.input_files.FMPOLICYTC_FILE
   oasislmf.pytools.common.input_files.FMPROGRAMME_FILE
   oasislmf.pytools.common.input_files.FMPROFILE_FILE
   oasislmf.pytools.common.input_files.FMSUMMARYXREF_FILE
   oasislmf.pytools.common.input_files.FMXREF_FILE
   oasislmf.pytools.common.input_files.GULSUMMARYXREF_FILE
   oasislmf.pytools.common.input_files.ITEMS_FILE
   oasislmf.pytools.common.input_files.OCCURRENCE_FILE
   oasislmf.pytools.common.input_files.PERIODS_FILE
   oasislmf.pytools.common.input_files.QUANTILE_FILE
   oasislmf.pytools.common.input_files.RETURNPERIODS_FILE


Functions
---------

.. autoapisummary::

   oasislmf.pytools.common.input_files.read_amplifications
   oasislmf.pytools.common.input_files.read_correlations
   oasislmf.pytools.common.input_files.read_coverages
   oasislmf.pytools.common.input_files.read_event_rates
   oasislmf.pytools.common.input_files.read_quantile
   oasislmf.pytools.common.input_files.read_occurrence_bin
   oasislmf.pytools.common.input_files.read_occurrence
   oasislmf.pytools.common.input_files.occ_get_date
   oasislmf.pytools.common.input_files.occ_get_date_id
   oasislmf.pytools.common.input_files.read_periods
   oasislmf.pytools.common.input_files.read_returnperiods


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

.. py:data:: logger

.. py:data:: AMPLIFICATIONS_FILE
   :value: 'amplifications.bin'


.. py:data:: CORRELATIONS_FILENAME
   :value: 'correlations.bin'


.. py:data:: COVERAGES_FILE
   :value: 'coverages.bin'


.. py:data:: EVENTRATES_FILE
   :value: 'event_rates.csv'


.. py:data:: FMPOLICYTC_FILE
   :value: 'fm_policytc.bin'


.. py:data:: FMPROGRAMME_FILE
   :value: 'fm_programme.bin'


.. py:data:: FMPROFILE_FILE
   :value: 'fm_profile.bin'


.. py:data:: FMSUMMARYXREF_FILE
   :value: 'fmsummaryxref.bin'


.. py:data:: FMXREF_FILE
   :value: 'fmxref.bin'


.. py:data:: GULSUMMARYXREF_FILE
   :value: 'gulsummaryxref.bin'


.. py:data:: ITEMS_FILE
   :value: 'items.bin'


.. py:data:: OCCURRENCE_FILE
   :value: 'occurrence.bin'


.. py:data:: PERIODS_FILE
   :value: 'periods.bin'


.. py:data:: QUANTILE_FILE
   :value: 'quantile.bin'


.. py:data:: RETURNPERIODS_FILE
   :value: 'returnperiods.bin'


.. py:function:: read_amplifications(run_dir='', filename=AMPLIFICATIONS_FILE, use_stdin=False, raw=False)

   Get array of amplification IDs from amplifications.bin, where index
   corresponds to item ID.

   amplifications.bin is binary file with layout:
       reserved header (4-byte int),
       item ID 1 (4-byte int), amplification ID a_1 (4-byte int),
       ...
       item ID n (4-byte int), amplification ID a_n (4-byte int)

   Args:
       run_dir (str): path to amplifications.bin file
       filename (str | os.PathLike): amplifications file name
       use_stdin (bool): Use standard input for file data, ignores run_dir/filename. Defaults to False.
       raw (bool): If True, return the validated flat int32 array (zero-copy memmap for file
           inputs) instead of building the 1-based lookup copy. Intended for sequential
           read paths (e.g. bintocsv) where random access by item_id is not needed.
   Returns:
       items_amps (numpy.ndarray): If raw=False (default), a 1-based lookup array of
           amplification IDs where index corresponds to item ID. If raw=True, the flat
           validated int32 array of interleaved (item_id, amplification_id) pairs.


.. py:function:: read_correlations(run_dir, ignore_file_type=set(), filename=CORRELATIONS_FILENAME)

   Load the correlations from the correlations file.
   Args:
       run_dir (str): path to correlations file
       ignore_file_type (Set[str]): file extension to ignore when loading.
       filename (str | os.PathLike): correlations file name
   Returns:
       Tuple[Dict[int, int], List[int], Dict[int, int], List[Tuple[int, int]], List[int]]
       vulnerability dictionary, vulnerability IDs, areaperil to vulnerability index dictionary,
       areaperil ID to vulnerability index array, areaperil ID to vulnerability array


.. py:function:: read_coverages(run_dir='', ignore_file_type=set(), filename=COVERAGES_FILE, use_stdin=False)

   Load the coverages from the coverages file.
   Args:
       run_dir (str): path to coverages file
       ignore_file_type (Set[str]): file extension to ignore when loading.
       filename (str | os.PathLike): coverages file name
       use_stdin (bool): Use standard input for file data, ignores run_dir/filename. Defaults to False.
   Returns:
       numpy.array[oasis_float]: array with the coverage values for each coverage_id.


.. py:function:: read_event_rates(run_dir, filename=EVENTRATES_FILE)

   Reads event rates from a CSV file
   Args:
       run_dir (str | os.PathLike): Path to input files dir
       filename (str | os.PathLike): event rates csv file name
   Returns:
       unique_event_ids (ndarray[oasis_int]): unique event ids
       event_rates (ndarray[oasis_float]): event rates


.. py:function:: read_quantile(sample_size, run_dir, filename=QUANTILE_FILE, return_empty=False)

   Generate a quantile interval Dictionary based on sample size and quantile binary file
   Args:
       sample_size (int): Sample size
       run_dir (str | os.PathLike): Path to input files dir
       filename (str | os.PathLike): quantile binary file name
       return_empty (bool): return an empty intervals array regardless of the existence of the quantile binary
   Returns:
       intervals (quantile_interval_dtype): Numpy array emulating a dictionary for numba


.. py:function:: read_occurrence_bin(run_dir='', filename=OCCURRENCE_FILE, use_stdin=False)

   Read the occurrence binary file and returns an occurrence map
   Args:
       run_dir (str | os.PathLike): Path to input files dir
       filename (str | os.PathLike): occurrence binary file name
       use_stdin (bool): Use standard input for file data, ignores run_dir/filename. Defaults to False.
   Returns:
       occ_map (nb.typed.Dict): numpy map of event_id, period_no, occ_date_id from the occurrence file


.. py:function:: read_occurrence(run_dir, filename=OCCURRENCE_FILE)

   Read the occurrence binary file and returns an occurrence map
   Args:
       run_dir (str | os.PathLike): Path to input files dir
       filename (str | os.PathLike): occurrence binary file name
   Returns:
       occ_map (nb.typed.Dict): numpy map of event_id, period_no, occ_date_id from the occurrence file


.. py:function:: occ_get_date(occ_date_id, granular_date)

   Returns date as year, month, day, hour, minute from occ_date_id

   Args:
       occ_date_id (np.int32 | np.int64): occurrence file date id (int64 for granular dates)
       granular_date (bool): boolean for whether granular date should be extracted or not

   Returns:
       (oasis_int, oasis_int, oasis_int, oasis_int, oasis_int): Returns year, month, date, hour, minute


.. py:function:: occ_get_date_id(granular_date, occ_year, occ_month, occ_day, occ_hour=0, occ_minute=0)

   Returns the occ_date_id from year, month, day, hour, minute and whether it is a granular date
   Args:
       granular_date (bool): boolean for whether granular date should be extracted or not
       occ_year (int): Occurrence Year.
       occ_month (int): Occurrence Month.
       occ_day (int): Occurrence Day.
       occ_hour (int): Occurrence Hour. Defaults to 0.
       occ_minute (int): Occurrence Minute. Defaults to 0.
   Returns:
       occ_date_id (np.int64): occurrence file date id (int64 for granular dates)


.. py:function:: read_periods(no_of_periods, run_dir, filename=PERIODS_FILE)

   Returns an array of period weights for each period between 1 and no_of_periods inclusive (with no gaps).
   Args:
       no_of_periods (int): Number of periods
       run_dir (str | os.PathLike): Path to input files dir
       filename (str | os.PathLike): periods binary file name
   Returns:
       period_weights (ndarray[periods_dtype]): Period weights


.. py:function:: read_returnperiods(use_return_period_file, run_dir, filename=RETURNPERIODS_FILE)

   Returns an array of return periods decreasing order with no duplicates.
   Args:
       use_return_period_file (bool): Bool to use Return Period File
       run_dir (str | os.PathLike): Path to input files dir
       filename (str | os.PathLike): return periods binary file name
   Returns:
       return_periods (ndarray[np.int32]): Return Periods
       use_return_period_file (bool): Bool to use Return Period File