crt1d.spectra ============= .. py:module:: crt1d.spectra .. autoapi-nested-parse:: Spectral manipulations. Functions --------- .. autoapisummary:: crt1d.spectra.avg_optical_prop crt1d.spectra.e_wl_umol crt1d.spectra.l_wl_planck crt1d.spectra.l_wl_planck_integ crt1d.spectra.plot_binned crt1d.spectra.plot_binned_ds crt1d.spectra.smear crt1d.spectra.smear_avg_optical_prop crt1d.spectra.smear_si crt1d.spectra.smear_trapz_interp crt1d.spectra.smear_tuv crt1d.spectra.smear_tuv2 Module Contents --------------- .. py:function:: avg_optical_prop(y, bounds, *, x=None, xe=None, x_smear_nb=None, light='planck', **light_kwargs) Average reflectance or transmittance over some region, from a spectrum or binned (smeared) spectrum. The average value depends on the spectrum of the illuminating light as well as the property's spectrum. :param y: Reflectance or transmittance spectrum. :type y: :term:`array_like` :param bounds: Region lower and upper bounds. :type bounds: :term:`array_like` :param x: Wavelength values where `y` is defined. (Bin centers, or coordinates of original spectrum.) If `x` is provided (instead of `xe`), `y`\(`x`) is first smeared with :func:`smear_tuv` into 200 equally spaced bins over the `bounds` region. :type x: :term:`array_like`, *optional* :param xe: Bin edges. Don't provide `x` if using `xe`. :type xe: :term:`array_like`, *optional* :param x_smear_nb: Number of equally-spaced bands to use when smearing `x` to determine edges. Default: band widths of 5 nm or minimum spacing between `x` values---\ whichever gives a smaller number of bands. .. warning:: The default method assumes `x` is in μm when assessing spacing between `x` values. :type x_smear_nb: :class:`int`, *optional* :param light: Method for constructing the light weights used in the weighted average. Default method integrates 6000 K Planck radiance over each bin using :func:`l_wl_planck_integ`. Can be an array-like of weights (e.g., irradiances). Can be function that can take `x` as its first parameter to provide a weight for `y`\(`x`). :type light: :class:`str`, :term:`array_like`, :class:`callable` :param \*\*light_kwargs: For the `light` method. Currently this only includes ``T_K`` for ``light='planck'``. .. py:function:: e_wl_umol(wl_um) J/(μmol photons) at wavelength `wl_um`. .. py:function:: l_wl_planck(T_K, wl_um) Planck radiance. :param T_K: Temperature (K). :type T_K: :class:`float`, :class:`numpy.ndarray` :param wl_um: Wavelength (μm). :type wl_um: :class:`float`, :class:`numpy.ndarray` .. py:function:: l_wl_planck_integ(T_K, wla_um, wlb_um) Numerical integral of Planck radiance from `wla_um` to `wlb_um`. :param T_K: Temperature (K). :type T_K: :class:`float`, :class:`numpy.ndarray` :param wla_um: Integration lower bound. :type wla_um: :class:`float` :param wlb_um: Upper bound. :type wlb_um: :class:`float` .. py:function:: plot_binned(x, y, xc, yc, dx, *, ax=None, xtight='orig') Compare an original spectrum to binned one. If `x` and `y` are :class:`xarray.DataArray`, their attrs will be used to label the plot. :param x: Original/actual values at wavelengths (original spectra). :type x: :term:`array_like` :param y: Original/actual values at wavelengths (original spectra). :type y: :term:`array_like` :param xc: Values at wave band centers. :type xc: :term:`array_like` :param yc: Values at wave band centers. :type yc: :term:`array_like` :param dx: Wave band widths, same size as `xc`, `yc`. :type dx: :term:`array_like` :param ax: By default, a new ax is created. :type ax: :class:`plt.Axes`, *optional* :param xtight: Whether to set the *x* limits based on the original spectrum or the binned spectrum. :type xtight: ``{'orig', 'bins'}`` .. py:function:: plot_binned_ds(ds0, ds, *, yname=None, **kwargs) Compare an original spectrum in `ds0` to binned one in `ds`. Uses :func:`plot_binned` with auto-detection of ``x``, ``dx``, and ``xc`` (though `yname`, the ``name`` of the spectrum to be plotted, must be provided). `**kwargs` are passed on to :func:`plot_binned`. .. py:function:: smear(y, bins, *, x='wl', xname_out='wl', method='tuv', **method_kwargs) Smear `y` into `bins`. This function dispatches to the different smearing method functions, which take array-like inputs and can be used directly instead if desired (e.g., :func:`smear_tuv`). If `y` is array-like, this returns a :class:`numpy.ndarray`. If `y` is an xarray type, this returns an :class:`xarray.Dataset`. :param y: Variable(s) to smear. If :class:`xarray.Dataset`, all variables that have coordinate `x` will be included. :type y: :term:`array_like`, :class:`xarray.DataArray`, :class:`xarray.Dataset` :param bins: Bin edges for the smeared spectrum. :type bins: :term:`array_like` :param x: Coordinates at which the `y` values are valid/defined. If `y` is `array`, `x` must be provided as an `array` of the same size. If `y` is an xarray type, providing the ``name`` as a string is sufficient. :type x: :class:`str`, :term:`array_like`, :class:`xarray.DataArray` :param xname_out: Used to label the new dimension of `y` is an `xarray.Dataset`, for example. :type xname_out: :class:`str` :param method: Smear method. * ``'tuv'``: :func:`smear_tuv` * ``'trapz_interp'``: :func:`smear_trapz_interp` * ``'avg_optical_prop'``: :func:`smear_avg_optical_prop` :type method: :class:`str` :param \*\*method_kwargs: Passed on to the smear method function. .. py:function:: smear_avg_optical_prop(x, y, bins, **kwargs) Smear `y`\(`x`) into `bins`, using :func:`avg_optical_prop` with `x` as ``x``. `**kwargs` are passed on to :func:`avg_optical_prop`. :param x: Coordinates of the `y` values (the original grid). :type x: :term:`array_like` :param y: Values :math:`y(x)` to be smeared/binned. :type y: :term:`array_like` :param bins: Bin edges. :type bins: :term:`array_like` :returns: **ynew** (:term:`array_like`) -- New values, valid for each bin (size ``bins.size - 1``). .. py:function:: smear_si(ds, bins, *, xname_out='wl', **kwargs) Helper function to smear spectral irradiance and then compute in-bin irradiance in the new bins. `**kwargs` can include ``method`` and ``**method_kwargs`` (see :func:`smear`). :param ds: Input dataset, containing spectral irradiance. .. note:: `ds` must have variables ``'SI_dr'`` (direct spectral irradiance) and ``'SI_df'`` (diffuse). :type ds: :class:`xarray.Dataset` :param bins: Bin edges. :type bins: :term:`array_like` :param xname_out: Variable name to use for the *x* variable in the output dataset. :type xname_out: :class:`str` :param \*\*kwargs: Passed on to :func:`smear`. .. py:function:: smear_trapz_interp(x, y, bins, *, k=3, interp='F') Smear `y`\(`x`) into `bins`, using `spline `_ interpolation and trapezoidal integration. :param x: Coordinates of the `y` values (the original grid). :type x: :term:`array_like` :param y: Values :math:`y(x)` to be smeared/binned. :type y: :term:`array_like` :param bins: Bin edges. :type bins: :term:`array_like` :param k: Degree of the spline used (1--5). The spline passes through all data points. :type k: :class:`int` :param interp: ``'F'`` to interpolate the cumulative trapz integral, or ``'f'`` to interpolate the `y` data. :type interp: :class:`str` :returns: **ynew** (:term:`array_like`) -- New values, valid for each bin (size ``bins.size - 1``). .. py:function:: smear_tuv(x, y, bins) Smear `y`\(`x`) into `bins`, using the TUV method. Returns an array of in-bin *y*-values ``ynew``, such that :math:`\sum_i y_{\text{new}, i} \Delta x_i` (``(ynew * dx).sum()``, where ``dx = np.diff(bins)``) is equal to the original trapezoidal integral of *y(x)* over the range [``bins[0]``, ``bins[-1]``]. Each value in the result is the (trapezoidally) integrated average of :math:`y(x)` in the corresponding bin (:math:`x_{l,i}`, :math:`x_{u,i}`). .. math:: \frac{\int_{x_l}^{x_u} y(x) \, dx}{x_u - x_l} :param x: Coordinates of the `y` values (the original grid). :type x: :term:`array_like` :param y: Values :math:`y(x)` to be smeared/binned. :type y: :term:`array_like` :param bins: Bin edges. :type bins: :term:`array_like` :returns: **ynew** (:term:`array_like`) -- New values, valid for each bin (size ``bins.size - 1``). .. rubric:: Notes Implementation based on `F0AM's implementation `_ of TUV's un-named algorithm. It works by applying cumulative trapezoidal integration to the original data, interpolating within `x` so that :math:`x_l` and :math:`x_u` don't have to be on the original `x` grid. .. py:function:: smear_tuv2(x, y, bins) WIP: more-efficient version of :func:`smear_tuv`.