crt1d.spectra

Spectral manipulations.

Module Contents

Functions

avg_optical_prop(y, bounds, *[, x, xe, x_smear_nb, light])	Average reflectance or transmittance over some region,
e_wl_umol(wl_um)	J/(μmol photons) at wavelength wl_um.
l_wl_planck(T_K, wl_um)	Planck radiance.
l_wl_planck_integ(T_K, wla_um, wlb_um)	Numerical integral of Planck radiance from wla_um to wlb_um.
plot_binned(x, y, xc, yc, dx, *[, ax, xtight])	Compare an original spectrum to binned one.
plot_binned_ds(ds0, ds, *[, yname])	Compare an original spectrum in ds0 to binned one in ds.
smear(y, bins, *[, x, xname_out, method])	Smear y into bins.
smear_avg_optical_prop(x, y, bins, **kwargs)	Smear y(x) into bins,
smear_si(ds, bins, *[, xname_out])	Helper function to smear spectral irradiance
smear_trapz_interp(x, y, bins, *[, k, interp])	Smear y(x) into bins,
smear_tuv(x, y, bins)	Smear y(x) into bins,
smear_tuv2(x, y, bins)	WIP: more-efficient version of smear_tuv().

crt1d.spectra.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.

Parameters:

• y (array_like) – Reflectance or transmittance spectrum.

• bounds (array_like) – Region lower and upper bounds.

• x (array_like, optional) – 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 smear_tuv() into 200 equally spaced bins over the bounds region.

• xe (array_like, optional) – Bin edges. Don’t provide x if using xe.

• x_smear_nb (int, optional) –

  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.

• light (str, array_like, callable) –

  Method for constructing the light weights used in the weighted average.

  Default method integrates 6000 K Planck radiance over each bin using 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).

• **light_kwargs – For the light method. Currently this only includes T_K for light='planck'.

crt1d.spectra.e_wl_umol(wl_um)

J/(μmol photons) at wavelength wl_um.

crt1d.spectra.l_wl_planck(T_K, wl_um)

Planck radiance.

Parameters:

• T_K (float, numpy.ndarray) – Temperature (K).

• wl_um (float, numpy.ndarray) – Wavelength (μm).

crt1d.spectra.l_wl_planck_integ(T_K, wla_um, wlb_um)

Numerical integral of Planck radiance from wla_um to wlb_um.

Parameters:

• T_K (float, numpy.ndarray) – Temperature (K).

• wla_um (float) – Integration lower bound.

• wlb_um (float) – Upper bound.

crt1d.spectra.plot_binned(x, y, xc, yc, dx, *, ax=None, xtight='orig')

Compare an original spectrum to binned one.

If x and y are xarray.DataArray, their attrs will be used to label the plot.

Parameters:

• x (array_like) – Original/actual values at wavelengths (original spectra).

• y (array_like) – Original/actual values at wavelengths (original spectra).

• xc (array_like) – Values at wave band centers.

• yc (array_like) – Values at wave band centers.

• dx (array_like) – Wave band widths, same size as xc, yc.

• ax (plt.Axes, optional) – By default, a new ax is created.

• xtight ({'orig', 'bins'}) – Whether to set the x limits based on the original spectrum or the binned spectrum.

crt1d.spectra.plot_binned_ds(ds0, ds, *, yname=None, **kwargs)

Compare an original spectrum in ds0 to binned one in ds. Uses 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 plot_binned().

crt1d.spectra.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., smear_tuv()).

If y is array-like, this returns a numpy.ndarray.

If y is an xarray type, this returns an xarray.Dataset.

Parameters:

• y (array_like, xarray.DataArray, xarray.Dataset) – Variable(s) to smear. If xarray.Dataset, all variables that have coordinate x will be included.

• bins (array_like) – Bin edges for the smeared spectrum.

• x (str, array_like, xarray.DataArray) – 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.

• xname_out (str) – Used to label the new dimension of y is an xarray.Dataset, for example.

• method (str) –

  Smear method.

  • 'tuv': smear_tuv()

  • 'trapz_interp': smear_trapz_interp()

  • 'avg_optical_prop': smear_avg_optical_prop()

• **method_kwargs – Passed on to the smear method function.

crt1d.spectra.smear_avg_optical_prop(x, y, bins, **kwargs)

Smear y(x) into bins, using avg_optical_prop() with x as x. **kwargs are passed on to avg_optical_prop().

Parameters:

• x (array_like) – Coordinates of the y values (the original grid).

• y (array_like) – Values \(y(x)\) to be smeared/binned.

• bins (array_like) – Bin edges.

Returns:

ynew (array_like) – New values, valid for each bin (size bins.size - 1).

crt1d.spectra.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 smear()).

Parameters:

• ds (xarray.Dataset) –

  Input dataset, containing spectral irradiance.

  Note

  ds must have variables 'SI_dr' (direct spectral irradiance) and 'SI_df' (diffuse).

• bins (array_like) – Bin edges.

• xname_out (str) – Variable name to use for the x variable in the output dataset.

• **kwargs – Passed on to smear().

crt1d.spectra.smear_trapz_interp(x, y, bins, *, k=3, interp='F')

Smear y(x) into bins, using spline interpolation and trapezoidal integration.

Parameters:

• x (array_like) – Coordinates of the y values (the original grid).

• y (array_like) – Values \(y(x)\) to be smeared/binned.

• bins (array_like) – Bin edges.

• k (int) – Degree of the spline used (1–5). The spline passes through all data points.

• interp (str) – 'F' to interpolate the cumulative trapz integral, or 'f' to interpolate the y data.

Returns:

ynew (array_like) – New values, valid for each bin (size bins.size - 1).

crt1d.spectra.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 \(\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 \(y(x)\) in the corresponding bin (\(x_{l,i}\), \(x_{u,i}\)).

\[\frac{\int_{x_l}^{x_u} y(x) \, dx}{x_u - x_l}\]

Parameters:

• x (array_like) – Coordinates of the y values (the original grid).

• y (array_like) – Values \(y(x)\) to be smeared/binned.

• bins (array_like) – Bin edges.

Returns:

ynew (array_like) – New values, valid for each bin (size bins.size - 1).

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 \(x_l\) and \(x_u\) don’t have to be on the original x grid.

crt1d.spectra.smear_tuv2(x, y, bins)

WIP: more-efficient version of smear_tuv().