crt1d.data
==========

.. py:module:: crt1d.data

.. autoapi-nested-parse::

   Data provided with crt1d: default/sample spectra,
   as well as functions that use external (not-required) libraries to compute more spectra.

   Data are loaded as :class:`xarray.Dataset` for easy inspection.



Functions
---------

.. autoapisummary::

   crt1d.data.leaf_ps5
   crt1d.data.load_default
   crt1d.data.load_default_ps5
   crt1d.data.load_default_sp2
   crt1d.data.load_ideal_leaf
   crt1d.data.load_prosail_sample_soil
   crt1d.data.load_soil_fuentes2007
   crt1d.data.solar_sp2


Package Contents
----------------

.. py:function:: leaf_ps5(n=1.2, cab=30.0, car=10.0, cbr=1.0, ewt=0.015, lma=0.009)

   Run PROSPECT-5 from Python package ``prosail``
   (source `on GitHub <https://github.com/jgomezdans/prosail>`_)
   to generate leaf spectra.

   Default values are the same as those on the
   `online PROSPECT page <http://opticleaf.ipgp.fr/index.php?page=prospect>`_.

   :param n: Leaf structure parameter (number of effective layers of leaf?; dimensionless).
             Typical range: [0.8, 3.0].
   :type n: :class:`float`
   :param cab: Chlorophyll a+b concentration (μg cm-2).
               Typical range: [0, 100].
   :type cab: :class:`float`
   :param car: Carotenoid concentration (μg cm-2).
               Typical range: [0, 25].
   :type car: :class:`float`
   :param cbr: Brown pigment fraction/factor in [0, 1].
   :type cbr: :class:`float`
   :param ewt: Equivalent leaf water thickness (cm).
               Typical range: [0, 0.05].
   :type ewt: :class:`float`
   :param lma: Leaf dry mass per unit area (g cm-2).
               Typical range: [0, 0.02].
   :type lma: :class:`float`

   :returns: :class:`xarray.Dataset` -- Dataset of the leaf reflectance and transmittance spectra,
             and PROSPECT input parameters as dimensionless variables.

   .. rubric:: Notes

   Quoted typical ranges are based on the PROSPECT page and Python PROSAIL readme linked above.


.. py:function:: load_default(*, midpt=True)

   Load default toc irradiance spectra, and leaf & soil optical props,
   used in :func:`~crt1d.cases.load_default_case`.

   The defaults are given by:

   * :func:`load_ideal_leaf`

   * :func:`load_default_sp2`

   * :func:`load_soil_fuentes2007`


.. py:function:: load_default_ps5()

   Load the provided default PROSPECT5 leaf element reflectance/transmittance.

   (I believe) these are the default spectra for the online version of PROSPECT.


.. py:function:: load_default_sp2(*, midpt=True)

   Load sample SPCTRAL2 top-of-canopy spectra (direct and diffuse).

   This is the default spectrum in the Excel version of SPCTRAL2.

   :param midpt: true (default): irradiance calculated at midpts of the original grid

                 false: irradiance calculated by estimating the edges of the original grid
                 and treating the original grid as centers
   :type midpt: :class:`bool`, *optional*

   .. rubric:: Notes

   The SPCTRAL2 irradiances are in spectral form: W m-2 μm-1,
   but we need in-band irradiance for the solvers, since some compute W/m2 absorption.


.. py:function:: load_ideal_leaf(*, midpt=False)

   Load the ideal green leaf properties (at SPCTRAL2 wavelengths).


.. py:function:: load_prosail_sample_soil(*, f_wet=0)

   Sample soil spectra provided in Python PROSAIL.

   :param f_wet: Weighting factor for the wet soil spectrum (0--1)
   :type f_wet: :class:`float`

   .. rubric:: Notes

   https://github.com/jgomezdans/prosail/blob/master/prosail/soil_reflectance.txt


.. py:function:: load_soil_fuentes2007(wl_um)

   PAR and NIR values, applied to the wavelengths in `wl_um`.


.. py:function:: solar_sp2(dt, lat, lon, *, utcoffset=0, temp=25, pres=1000, ozone=None, tau500=0.2, watvap=1.36, alpha=1.14, assym=0.65, albedo=None)

   Run SPCTRAL2 using `SolarUtils <https://github.com/SunPower/SolarUtils>`_
   (Python package name ``solar_utils``).

   The defaults are mostly consistent with :func:`solar_utils.spectrl2`,
   but some of the inputs are in a different style.

   :param dt: In UTC, but with timezone not specified. (UTC offset specified separately!)
   :type dt: :class:`datetime.datetime`
   :param lat: Latitude and longitude of the location (deg.). Longitude in -180--180.
   :type lat: :class:`float`
   :param lon: Latitude and longitude of the location (deg.). Longitude in -180--180.
   :type lon: :class:`float`
   :param utcoffset: UTC offset, e.g. -5 for US Eastern Standard Time (EST)
   :type utcoffset: :class:`int`
   :param temp: Air temperature at the location (deg. C).
   :type temp: :class:`float`
   :param pres: Amospheric surface pressure at the location (hPa/mb).
   :type pres: :class:`float`
   :param ozone: Total column ozone (cm). The default is to use SPCTRAL2's internal parameterization
                 based on location and time of day/year (Heuklon 1978). Passing ``-1.0`` will have
                 the same result.
   :type ozone: :class:`float`
   :param tau500: Aerosol optical depth (base e) at 500 nm.
                  Typical range: [0.05, 0.55] for clear sky.
                  Should be in [0, 10].
   :type tau500: :class:`float`
   :param watvap: Total column precipitable water vapor (cm).
                  Typical range: [0.3, 6].
                  Should be in [0, 100].
   :type watvap: :class:`float`
   :param alpha: Power on Angstrom turbidity. If you pass a negative number, you will get ``1.14``.
   :type alpha: :class:`float`
   :param assym: Aerosol asymmetry factor. In the C code they say this is a typical rural value.
                 Should be in (0, 1). If you pass ``-1.0``, you will get 0.65.
   :type assym: :class:`float`
   :param albedo: keys: wavelength (μm), values: albedo at that wavelength; length 6.
                  The default is 0.2 (across the board) for wavelengths
                  ``[0.3, 0.7, 0.8, 1.3, 2.5, 4.0]``.
   :type albedo: :class:`dict`

   :returns: :class:`xarray.Dataset` -- Dataset containing the spectra, solar zenith angle, and time/location info.