dubfi.fluxes.localization
=========================

.. py:module:: dubfi.fluxes.localization

.. autoapi-nested-parse::

   Localization utilities.

   .. versionadded:: 0.1.1
   .. versionchanged:: 0.1.2 (renamed some methods)



Attributes
----------

.. autoapisummary::

   dubfi.fluxes.localization.GASPARI_COHN_CUTOFF
   dubfi.fluxes.localization.GASPARI_COHN_GAUSS_CUTOFF
   dubfi.fluxes.localization.LOCALIZATION_FUNCTIONS


Classes
-------

.. autoapisummary::

   dubfi.fluxes.localization.Localization


Functions
---------

.. autoapisummary::

   dubfi.fluxes.localization.gaspari_cohn
   dubfi.fluxes.localization.gaspari_cohn_gauss
   dubfi.fluxes.localization.gauss


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

.. py:function:: gaspari_cohn(x)

   Gaspari-Cohn function.

   This function has compact support on [-2, 2].

   .. seealso:: :meth:`gaspari_cohn_gauss`


.. py:data:: GASPARI_COHN_CUTOFF
   :value: 2.0


   Cutoff scale of :func:`gaspari_cohn`.

   :code:`gaspari_cohn(x) == 0` for :code:`abs(x) > GASPARI_COHN_CUTOFF`.

.. py:function:: gaspari_cohn_gauss(x)

   Gaspari-Cohn with scale adjusted to match Gaussian.

   This function has compact support on [-2/sqrt(0.3), 2/sqrt(0.3)]
   and is guaranteed to be zero for \|x\| >= 3.6515.

   .. seealso:: :meth:`gaspari_cohn_gauss`


.. py:data:: GASPARI_COHN_GAUSS_CUTOFF
   :value: 3.6514837167011076


   Cutoff scale of :func:`gaspari_cohn_gauss`.

   :code:`gaspari_cohn_gauss(x) == 0` for :code:`abs(x) > GASPARI_COHN_GAUSS_CUTOFF`.

.. py:function:: gauss(x)

   Gaussian, :math:`\exp(-\tfrac{1}{2} x^2)`.


.. py:data:: LOCALIZATION_FUNCTIONS

   Access localization functions by (lower case) name.

.. py:class:: Localization(func, hscale, vscale, tscale)

   Localization class for in-situ observations.

   Localization object allows creating localization matrices.

   :param func: localization function. This must take an array as argument
                and describe a positive, symmetric function f(x) that
                decreases monotonically from \|x\| from f(0)=1 to f(x)=0
                (at least asymptotically) for large x.
                Names for known localization functions are allowed. Note
                that "Gaspari-Cohn-scaled" is an approximation of a
                Gaussian with compact support, see
                :func:`gaspari_cohn_gauss`.
   :type func: callable | {"Gauss", "Gaspari-Cohn", "Gaspari-Cohn-scaled"}
   :param hscale: horizontal scale in meters
   :type hscale: float
   :param vscale: vertical scale in meters
   :type vscale: float
   :param tscale: temporal scale
   :type tscale: np.timedelta64


   .. py:method:: from_config(config)
      :classmethod:


      Construct Localization from configuration.



   .. py:property:: function

      Localization function, requires normalized input.


   .. py:method:: rel_dist_horizontal(lon, lat, lon2 = None, lat2 = None)

      Matrix of normalized horizontal distances.

      .. versionchanged:: 0.1.2 (renamed, added optional variables)



   .. py:method:: weights_spatial(lon, lat, height, lon2 = None, lat2 = None, height2 = None)

      Spatial weights (localization) matrix.

      .. versionchanged:: 0.1.2 (added optional variables)



   .. py:method:: weights_time(time, time2 = None)

      Temporal weights (localization) matrix.

      .. versionchanged:: 0.1.2 (added optional variables)



   .. py:method:: rel_dist_horizontal_unique(lon, lat)

      Return normalized horizontal distance matrix for unique coordinates.

      :returns: * **dist** (*np.ndarray*) -- distance matrix
                * **indices** (*np.ndarray*) -- indices into dist along lon, lat coordinates
                * *.. versionchanged:: 0.1.2 (renamed)*



   .. py:method:: matrix(lon, lat, height, time)

      Construct localization matrix based on coordinates.

      All input arrays must be one-dimensional and aligned.

      :param lon: longitude (degrees east)
      :type lon: np.ndarray
      :param lat: latitude (degrees east)
      :type lat: np.ndarray
      :param height: vertical coordinate in meters
      :type height: np.ndarray
      :param time: time relative to localization time scale with arbitrary offset
      :type time: np.ndarray

      :returns: **localization_weights** -- localization matrix specifying weights between each combination
                of coordiniates
      :rtype: np.ndarray



   .. py:method:: matrix_sparse(lon, lat, height, time, threshold = 1e-05, chunk = 500)

      Construct localization matrix based on coordinates, see :meth:`~matrix`.