dubfi.fluxes.segments_insitu
============================

.. py:module:: dubfi.fluxes.segments_insitu

.. autoapi-nested-parse::

   Split data for MPI worker processes, for in-situ observations.

   .. codeauthor:: Valentin Bruch, DWD <valentin.bruch@dwd.de>
   .. versionchanged:: 0.1.2 (renamed module)
   .. versionadded:: 0.1.0 (initial release)



Functions
---------

.. autoapisummary::

   dubfi.fluxes.segments_insitu.matrix_blocks
   dubfi.fluxes.segments_insitu.indep_blocks
   dubfi.fluxes.segments_insitu.min_combination_cost
   dubfi.fluxes.segments_insitu.split_times
   dubfi.fluxes.segments_insitu.prep_segments
   dubfi.fluxes.segments_insitu.plot_segments


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

.. py:function:: matrix_blocks(matrix)

   Given a symmetric matrix of boolean entries, return indices of independent blocks.


.. py:function:: indep_blocks(lon, lat, time, hscale, tscale)

   Given coordinates and separating scales, identify independent blocks.

   Input arrays are aligned along a common dimension "ssh" (station
   and sampling height). See
   :func:`dubfi.fluxes.readobs.coordinates_from_config` for
   generating the input coordinates.

   :param lon: longitude coordiantes per ssh (degrees)
   :type lon: np.ndarray
   :param lat: latitude coordiantes per ssh (degrees)
   :type lat: np.ndarray
   :param time: time coordinates for each ssh (must be of data type np.datetime64)
   :type time: list[np.ndarray]
   :param hscale: horizontal cutoff scale of correlations (meters)
   :type hscale: float
   :param tscale: temporal cutoff scale of correlations
   :type tscale: np.timedelta64

   :returns: list of blocks. Each block is a dictionary mapping the ssh
             index to a slice or an array of indices that shall be applied
             to the time coordinate of the station.
   :rtype: list[dict]


.. py:function:: min_combination_cost(sizes, ngroups)

   Distribute n elements to m groups and return the group indices.

   Given are n elements of different sizes. These shall be
   distributed to m groups such that each group has approximately
   the same size. The size of a group is the sum of the sizes of its
   elements.

   :param sizes: array of sizes of elements that shall be distributed
   :type sizes: list[int] | np.ndarray
   :param ngroups: number of groups
   :type ngroups: int

   :returns: * **groups** (*np.ndarray*) -- group index for each input element
             * *.. versionadded:: 0.1.1*


.. py:function:: split_times(times, buffer, nseg)

   Split array of times into buffered segments.

   Given an (unsorted) array of times, find split times that define
   segments such that the maximum size of the balanced segments is
   minimized. A buffered segment contains all times of the segment
   plus all times in a buffer zone before and after the segment.

   :param times: unsorted array of times (usually observation times)
   :type times: np.ndarray
   :param buffer: time interval defining the buffer size
   :type buffer: np.timedelta64
   :param nseg: number of segments that shall be created
   :type nseg: int

   :returns: * **split_start** (*np.ndarray*) -- times at which segments start (inclusive)
             * **split_end** (*np.ndarray*) -- times at which segments end (inclusive)
             * *.. versionadded:: 0.1.1*


.. py:function:: prep_segments(lon, lat, time, hscale, tscale, number, buffer_pref = 1.25)

   Prepare segments for in-situ observations.

   This heuristic algorithm is not guaranteed to work in all cases!
   It can fail with an assertion error if the target number of
   segments is matched exactly.

   :param lon: longitude coordiantes per ssh (degrees)
   :type lon: np.ndarray
   :param lat: latitude coordiantes per ssh (degrees)
   :type lat: np.ndarray
   :param time: time coordinates for each ssh (must be of data type np.datetime64)
   :type time: list[np.ndarray]
   :param hscale: horizontal cutoff scale of correlations (meters)
   :type hscale: float
   :param tscale: temporal cutoff scale of correlations
   :type tscale: np.timedelta64
   :param number: number of segments
   :type number: int
   :param buffer_pref: prefactor applied to tscale in buffering
   :type buffer_pref: float, default=1.25

   :returns: collection of segments
   :rtype: Segments


.. py:function:: plot_segments(segments, lon, lat, height, time, hscale, vscale, tscale)

   Plot segments created by :func:`prep_segments`, intended for debugging purposes.