isofit.core.common
==================

.. py:module:: isofit.core.common


Attributes
----------

.. autoapisummary::

   isofit.core.common.eps
   isofit.core.common.Cache


Classes
-------

.. autoapisummary::

   isofit.core.common.VectorInterpolator
   isofit.core.common.Track


Functions
---------

.. autoapisummary::

   isofit.core.common.load_wavelen
   isofit.core.common.emissive_radiance
   isofit.core.common.svd_inv
   isofit.core.common.svd_inv_sqrt
   isofit.core.common.expand_path
   isofit.core.common.recursive_replace
   isofit.core.common.get_absorption
   isofit.core.common.recursive_reencode
   isofit.core.common.json_load_ascii
   isofit.core.common.expand_all_paths
   isofit.core.common.find_header
   isofit.core.common.calculate_resample_matrix
   isofit.core.common.resample_spectrum
   isofit.core.common.load_spectrum
   isofit.core.common.spectral_response_function
   isofit.core.common.combos
   isofit.core.common.conditional_gaussian
   isofit.core.common.envi_header
   isofit.core.common.ray_start
   isofit.core.common.compare


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

.. py:data:: eps
   :value: 1e-05


.. py:data:: Cache

.. py:class:: VectorInterpolator(grid_input: List[List[float]], data_input: numpy.array, version='mlg')

   Linear look up table interpolator.  Support linear interpolation through radial space by expanding the look
   up tables with sin and cos dimensions.

   :param grid_input: list of lists of floats, indicating the gridpoint elements in each grid dimension
   :param data_input: n dimensional array of radiative transfer engine outputs (each dimension size corresponds to the
                      given grid_input list length, with the last dimensions equal to the number of sensor channels)
   :param version: version to use: 'rg' for scipy RegularGridInterpolator, 'mlg' for multilinear grid interpolator


   .. py:attribute:: single_point_data
      :value: None



   .. py:attribute:: n


   .. py:method:: _interpolate(points)

      Supports style 'rg'



   .. py:method:: _lookup(i, point)

      Calculates the slicing for the cube in _multilinear_grid



   .. py:method:: _multilinear_grid(points)

      Cached version of Jouni's implementation

      :param points: The point being interpolated. If at the limit, the extremal value in
                     the grid is returned.

      :returns: np.ndarray
      :rtype: cube



   .. py:method:: __call__(*args, **kwargs)

      Passes args to the appropriate interpolation method defined by the version at
      object init.



.. py:function:: load_wavelen(wavelength_file: str)

   Load a wavelength file, and convert to nanometers if needed.

   :param wavelength_file: file to read wavelengths from

   :returns: wavelengths, full-width-half-max
   :rtype: (np.array, np.array)


.. py:function:: emissive_radiance(emissivity: numpy.array, T: numpy.array, wl: numpy.array) -> (numpy.array, numpy.array)

   Calcluate the radiance of a surface due to emission.

   :param emissivity: surface emissivity.
   :param T: surface temperature [K]
   :param wl: emmissivity wavelengths [nm]

   :returns: surface upwelling radiance in uW $cm^{-2} sr^{-1} nm^{-nm}$
             np.array: partial derivative of radiance with respect to temperature uW $cm^{-2} sr^{-1} nm^{-1} k^{-1}$
   :rtype: np.array


.. py:function:: svd_inv(C: numpy.array, hashtable: collections.OrderedDict = None, max_hash_size: int = None)

   Matrix inversion, based on decomposition.  Built to be stable, and positive.

   :param C: matrix to invert
   :param hashtable: if used, the hashtable to store/retrieve results in/from
   :param max_hash_size: maximum size of hashtable

   :returns: inverse of C
   :rtype: np.array


.. py:function:: svd_inv_sqrt(C: numpy.array, hashtable: collections.OrderedDict = None, max_hash_size: int = None) -> (numpy.array, numpy.array)

   Matrix inversion, based on decomposition.  Built to be stable, and positive.

   :param C: matrix to invert
   :param hashtable: if used, the hashtable to store/retrieve results in/from
   :param max_hash_size: maximum size of hashtable

   :returns: inverse of C and square root of the inverse of C
   :rtype: (np.array, np.array)


.. py:function:: expand_path(directory: str, subpath: str) -> str

   Expand a path variable to an absolute path, if it is not one already.

   :param directory: absolute location
   :param subpath: path to expand

   :returns: expanded path
   :rtype: str


.. py:function:: recursive_replace(obj, key, val) -> None

   Find and replace a vector in a nested (mutable) structure.

   :param obj: object to replace within
   :param key: key to replace
   :param val: value to replace with


.. py:function:: get_absorption(wl: numpy.array, absfile: str) -> (numpy.array, numpy.array)

   Calculate water and ice absorption coefficients using indices of
   refraction, and interpolate them to new wavelengths (user specifies nm).

   :param wl: wavelengths to interpolate to
   :param absfile: file containing indices of refraction. Wavelength unts are in nm.

   :returns: interpolated, wavelength-specific water absorption coefficients
             np.array: interpolated, wavelength-specific ice absorption coefficients
   :rtype: np.array


.. py:function:: recursive_reencode(j, shell_replace: bool = True)

   Recursively re-encode a mutable object (ascii->str).

   :param j: object to reencode
   :param shell_replace: boolean helper for recursive calls

   :returns: expanded, reencoded object
   :rtype: Object


.. py:function:: json_load_ascii(filename: str, shell_replace: bool = True) -> dict

   Load a hierarchical structure, convert all unicode to ASCII and
   expand environment variables.

   :param filename: json file to load from
   :param shell_replace: boolean

   :returns: encoded dictionary
   :rtype: dict


.. py:function:: expand_all_paths(to_expand: dict, absdir: str)

   Expand any dictionary entry containing the string 'file' into
      an absolute path, if needed.

   :param to_expand: dictionary to expand
   :param absdir: path to expand with (absolute directory)

   :returns: dictionary with expanded paths
   :rtype: dict


.. py:function:: find_header(imgfile: str) -> str

   Safely return the header associated with an image file.

   :param imgfile: file name of base image

   :returns: header filename if one exists
   :rtype: str


.. py:function:: calculate_resample_matrix(wl: numpy.array, wl2: numpy.array, fwhm2: numpy.array, srf_file: str = None) -> numpy.array

   Calculate the resampling matrix for a given set of wavelengths and FWHM.
   Once calculated, resmpling is just the dot product of this matrix with the
   vector to be resampled.

   :param wl: sample starting wavelengths
   :param wl2: wavelengths to resample to
   :param fwhm2: full-width-half-max at resample resolution
   :param srf_file: SRF for the sensor if not assuming Gaussian

   :returns: transformation matrix (H)
   :rtype: np.array


.. py:function:: resample_spectrum(x: numpy.array, wl: numpy.array, wl2: numpy.array, fwhm2: numpy.array, fill: bool = False, srf_file: str = None, H: numpy.array = None) -> numpy.array

   Resample a spectrum to a new wavelength / FWHM.
      Assumes Gaussian SRFs.

   :param x: radiance vector
   :param wl: sample starting wavelengths
   :param wl2: wavelengths to resample to
   :param fwhm2: full-width-half-max at resample resolution
   :param fill: boolean indicating whether to fill in extrapolated regions
   :param ### sc Adding for non-Gaussian SRF ###:
   :param srf_file: SRF for the sensor if not assuming Gaussian
   :param H: pre-computed transformation matrix, to enable caching

   :returns: interpolated radiance vector
   :rtype: np.array


.. py:function:: load_spectrum(spectrum_file: str) -> (numpy.array, numpy.array)

   Load a single spectrum from a text file with initial columns giving
      wavelength and magnitude, respectively.

   :param spectrum_file: file to load spectrum from

   :returns: spectrum values
             np.array: wavelengths, if available in the file
   :rtype: np.array


.. py:function:: spectral_response_function(response_range: numpy.array, mu: float, sigma: float)

   Calculate the spectral response function.

   :param response_range: signal range to calculate over
   :param mu: mean signal value
   :param sigma: signal variation

   :returns: spectral response function
   :rtype: np.array


.. py:function:: combos(inds: List[List[float]]) -> numpy.array

   Return all combinations of indices in a list of index sublists.
   For example, the call::
       combos([[1, 2], [3, 4, 5]])
       ...[[1, 3], [2, 3], [1, 4], [2, 4], [1, 5], [2, 5]]

   This is used for interpolation in the high-dimensional LUT.

   :param inds: list of lists of values to expand

   :returns: meshgrid array of combinations
   :rtype: np.array


.. py:function:: conditional_gaussian(mu: numpy.array, C: numpy.array, window: numpy.array, remain: numpy.array, x: numpy.array) -> (numpy.array, numpy.array)

   Define the conditional Gaussian distribution for convenience.

   len(window)+len(remain)=len(x)

   :param mu: mean values
   :param C: matrix for conditioning
   :param window: contains all indices not in remain
   :param remain: contains indices of the observed part x1
   :param x: values to condition with

   :returns: conditional mean, conditional covariance
   :rtype: (np.array, np.array)


.. py:function:: envi_header(inputpath)

   Convert a envi binary/header path to a header, handling extensions
   :param inputpath: path to envi binary file

   :returns: the header file associated with the input reference.
   :rtype: str


.. py:function:: ray_start(num_cores, num_cpus=2, memory_b=-1)

.. py:class:: Track(total, step=5, print=print, reverse=False, message='complete')

   Tracks and reports the percentage complete for some arbitrary sized iterable.

   Borrowed from mlky


   .. py:attribute:: step
      :value: 5



   .. py:attribute:: total


   .. py:attribute:: print


   .. py:attribute:: start


   .. py:attribute:: percent
      :value: 5



   .. py:attribute:: reverse
      :value: False



   .. py:attribute:: message
      :value: 'complete'



   .. py:method:: __call__(count)

      :param count: The current count of items finished. If iterable, will call len() on it
      :type count: int, iterable

      :returns: True if a percentage step was just crossed, False otherwise
      :rtype: bool



.. py:function:: compare(a, b, threshold=0.8, not_same=True)

   Compares strings in `a` to strings in `b`

   :param a: A string or list of strings to compare with `b`
   :type a: str | list[str]
   :param a: A string or list of strings to compare with `a`
   :type a: str | list[str]
   :param threshold: Ratio threshold to meet to be considered matching. Must be between 0 and 1.
   :type threshold: float, default=0.8
   :param not_same: Only include matches in which the two strings are not the same
   :type not_same: bool, default=True

   :returns: **matching** -- For each string in `a`, return a list of strings in `b` that meet the matching
             threshold
   :rtype: dict