eradiate 0.31.0.dev0__tar.gz → 0.31.0.dev1__tar.gz

{eradiate-0.31.0.dev0/src/eradiate.egg-info → eradiate-0.31.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eradiate
-Version: 0.31.0.dev0
+Version: 0.31.0.dev1
 Summary: A radiative transfer model for the Earth observation community
 Author: The Eradiate Team
 Maintainer: The Eradiate Team

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/pyproject.toml

@@ -10,7 +10,7 @@ maintainers = [{ name = "The Eradiate Team" }]
 name = "eradiate"
 readme = "resources/README_PyPI.md"
 requires-python = ">=3.9,<3.13"
-version = "0.31.0-dev0"
+version = "0.31.0-dev1"
 dependencies = [
   "aenum",
   "attrs>=22.2",
@@ -78,8 +78,9 @@ test = [
   "pytest-robotframework",
 ]
 dev = [
-  "bump-my-version>=0.28.0,<0.29.0",
+  "bump-my-version>=1.2.0,<1.3.0",
   "uv==0.6.*", # Used to lock docs dependencies
+  "pandas-stubs",
 ]
 
 [project.scripts]

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/config/_settings.py

@@ -104,7 +104,7 @@ def _validate_source_dir(value: Path | None) -> bool:
     return True
 
 
-#: Main settings data structure. See the `Dynaconf documentation <https://www.dynaconf.com/>`_
+#: Main settings data structure. See the `Dynaconf documentation <https://www.dynaconf.com/>`__
 #: for details.
 settings = Dynaconf(
     settings_files=["eradiate.yml", "eradiate.yaml", "eradiate.toml"],

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/data/_asset_manager.py

@@ -648,7 +648,7 @@ class AssetManager:
                         shutil.rmtree(fname, ignore_errors=True)
 
 
-#: Unique asset manager instance
+#: Unique asset manager instance (exposed as :data:`eradiate.asset_manager`).
 asset_manager = AssetManager(
     cache_dir=Path(settings["data_path"]) / "cached",
     unpack_dir=Path(settings["data_path"]) / "unpacked",

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/data/_file_resolver.py

@@ -49,7 +49,19 @@ class FileResolver:
     :data:`eradiate.fresolver <.fresolver>`:
 
     >>> from eradiate import fresolver
+
+    To add a path to the file resolver, use the :meth:`~.FileResolver.append`
+    or :meth:`~.FileResolver.prepend` methods, *e.g.*:
+
+    >>> fresolver.append("some/path/on/the/drive")
+
+    To resolve a relative path, use the :meth:`~.FileResolver.resolve` method:
+
     >>> fresolver.resolve("srf/sentinel_2a-msi-3.nc")
+
+    If the path is expected to point to an existing dataset file, the
+    :meth:`~.FileResolver.load_dataset` method can be used to load it immediately:
+
     >>> fresolver.load_dataset("srf/sentinel_2a-msi-3.nc")
     """
 
@@ -70,6 +82,10 @@ class FileResolver:
 
         avoid_duplicates : bool, optional
             If ``True``, do not append again a path that is already registered.
+
+        See Also
+        --------
+        :meth:`.prepend`
         """
         path = Path(path).resolve()
         if not path.is_dir():
@@ -98,6 +114,9 @@ class FileResolver:
         avoid_duplicates : bool, optional
             If ``True``, do not prepend again a path that is already registered.
 
+        See Also
+        --------
+        :meth:`.append`
         """
         path = Path(path).resolve()
         if not path.is_dir():
@@ -127,7 +146,8 @@ class FileResolver:
 
         Returns
         -------
-        Resolved path
+        Path
+            Resolved path
 
         Raises
         ------
@@ -153,6 +173,22 @@ class FileResolver:
     ) -> xr.Dataset:
         """
         Chain :meth:`resolve` and :func:`xarray.load_dataset`.
+
+        Parameters
+        ----------
+        path : path-like
+            Path to be resolved.
+
+        strict : bool, default: False
+            If ``True``, resolution failure will raise.
+
+        cwd : bool, default: False
+            If ``True``, check first if a file relative to the current working
+            directory exists.
+
+        Returns
+        -------
+        Dataset
         """
         fname = self.resolve(path, strict=strict, cwd=cwd)
         return xr.load_dataset(fname)
@@ -166,6 +202,10 @@ class FileResolver:
         show : bool
             If ``True``, display information to the terminal. Otherwise, return
             it as a dictionary.
+
+        Returns
+        -------
+        dict or None
         """
         if show:
             title = "File resolver"
@@ -181,7 +221,7 @@ class FileResolver:
             return {"paths": self.paths}
 
 
-#: Unique file resolver instance
+#: Unique file resolver instance (exposed as :data:`eradiate.fresolver`)
 fresolver = FileResolver(settings["path"])
 fresolver.append(asset_manager.install_dir)
 if SOURCE_DIR:

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/data/io.py

@@ -24,11 +24,25 @@ def _convert_units(value: str):
     return value
 
 
+def _get_units(ds, var, fallback_units=None):
+    if "units" in ds[var].attrs:
+        return ureg.Unit(_convert_units(ds[var].attrs["units"]))
+    elif fallback_units is not None and var in fallback_units:
+        return ureg.Unit(_convert_units(fallback_units[var]))
+    else:
+        raise ValueError(
+            "load_aerosol_libradtran(): The input dataset specifies no units "
+            f"for variable '{var}'; this can be addressed by passing them through "
+            "the 'fallback_units' parameter."
+        )
+
+
 def load_aerosol_libradtran(
     data: PathLike | xr.Dataset,
     particle_shape: Literal["spherical", "spheroidal"] | None = None,
     tolerance: dict[str, pint.Quantity | float] | None = None,
     wbounds: tuple = (None, None),
+    fallback_units: dict[str, str] | None = None,
     **kwargs,
 ) -> xr.Dataset:
     """
@@ -66,6 +80,9 @@ def load_aerosol_libradtran(
         lookup for relevant parameters. Units are applied with the same rules as
         for the ``reff`` and ``hum`` parameters.
 
+    fallback_units : dict, optional
+        A mapping that specifies units to apply to variables that are missing them.
+
     Returns
     -------
     Dataset
@@ -124,8 +141,8 @@ def load_aerosol_libradtran(
         if var not in data:
             continue
 
+        units = _get_units(data, var, fallback_units)
         da = data[var]
-        units = ureg.Unit(_convert_units(data[var].units))
         default_units = KWARG_TO_DEFAULT_UNITS[kwarg]
 
         if len(da) > 1:
@@ -162,7 +179,8 @@ def load_aerosol_libradtran(
 
     # Filter wavelengths if requested
     wmin, wmax = wbounds
-    units = ureg.Unit(_convert_units(data["wavelen"].units))
+
+    units = _get_units(data, "wavelen", fallback_units)
     default_units = KWARG_TO_DEFAULT_UNITS["w"]
 
     if wmin is not None:
@@ -176,7 +194,7 @@ def load_aerosol_libradtran(
         )
         data = data.where(data["wavelen"] <= wmax).dropna("nlam", how="all")
 
-    wavelength = data["wavelen"].values * ureg(data["wavelen"].units)
+    wavelength = data["wavelen"].values * units
 
     # Phase function
     if particle_shape is None:
@@ -229,7 +247,6 @@ def load_aerosol_libradtran(
                 "nthetamax"
             )
             x = mus
-            xp = data_selected["theta"].values
             xp = np.cos(np.deg2rad(data_selected["theta"].values)).ravel()
             fp = data_selected["phase"].values
             p = np.interp(x, xp, fp)

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/notebook/__init__.py

@@ -14,7 +14,7 @@ def install(*extensions):
         parameter is unset):
 
         * :monobold:`kernel_logging`: Route kernel logs through standard logging
-          facilities. Progress display uses `tqdm <https://tqdm.github.io/>`_.
+          facilities. Progress display uses `tqdm <https://tqdm.github.io/>`__.
         * :monobold:`rich_pretty`: Install :func:`rich.pretty <rich.pretty.install>`
           with default configuration to the current Python REPL.
         * :monobold:`rich_traceback`:

eradiate-0.31.0.dev1/src/eradiate/notebook/tutorials.py

@@ -0,0 +1,14 @@
+"""
+Extensions and helpers for tutorials (legacy).
+"""
+
+import warnings
+
+from eradiate.tutorials import *  # noqa: F403
+
+warnings.warn(
+    DeprecationWarning(
+        "The 'eradiate.notebook.tutorials' module is deprecated: its features "
+        "have been moved to 'eradiate.tutorials'."
+    )
+)

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/pipelines/__init__.py

@@ -28,7 +28,7 @@ See Also
 
 * :class:`hamilton.driver.Driver`
 * `Hamilton's documentation on tags \
-  <https://hamilton.dagworks.io/en/latest/reference/decorators/tag/#tag>`_
+  <https://hamilton.dagworks.io/en/latest/reference/decorators/tag/#tag>`__
 """
 
 import lazy_loader

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/radprops/_absorption.py

@@ -1061,14 +1061,6 @@ KNOWN_DATABASES = {
         "path": "absorption_ckd/monotropa",
     },
     "mycena": {
-        "cls": CKDAbsorptionDatabase,
-        "path": "absorption_ckd/mycena_v2",
-    },
-    "mycena_v2": {
-        "cls": CKDAbsorptionDatabase,
-        "path": "absorption_ckd/mycena_v2",
-    },
-    "mycena_v1": {  # Deprecated
         "cls": CKDAbsorptionDatabase,
         "path": "absorption_ckd/mycena",
     },

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/radprops/_atmosphere.py

@@ -64,7 +64,7 @@ class AtmosphereRadProfile(RadProfile):
         "look it up and load it. If a dictionary is passed, it will be passed "
         "as keyword argument to ``joseki.make()``. The default is "
         '``{"identifier": "afgl_1986-us_standard",  "z": np.linspace(0, 120, 121) * ureg.km), "additional_molecules": False}``. '
-        "See `the Joseki docs <https://rayference.github.io/joseki/latest/reference/#src.joseki.core.make>`_ "
+        "See the `Joseki documentation <https://joseki.readthedocs.io/en/latest/reference/joseki/index.html#joseki.make>`__ "
         "for details.",
         type="Dataset",
         init_type="Dataset or path-like or dict",

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/rng.py

@@ -1,7 +1,7 @@
 """
 Components related with pseudo-random number generation.
 
-Inspired by `SeedBank <https://github.com/lenskit/seedbank>`_.
+Inspired by `SeedBank <https://github.com/lenskit/seedbank>`__.
 """
 
 from __future__ import annotations

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/scenes/atmosphere/_molecular.py

@@ -109,7 +109,7 @@ class MolecularAtmosphere(AbstractHeterogeneousAtmosphere):
         "look it up and load it. If a dictionary is passed, it will be passed "
         "as keyword argument to ``joseki.make()``. The default is "
         '``joseki.make(identifier="afgl_1986-us_standard",  z=np.linspace(0.0, 120.0, 121) * ureg.km)``. '
-        "See `the Joseki docs <https://rayference.github.io/joseki/latest/reference/#src.joseki.core.make>`_ "
+        "See the `Joseki documentation <https://joseki.readthedocs.io/en/latest/reference/joseki/index.html#joseki.make>`__ "
         "for details.",
         type="Dataset or None",
         init_type="Dataset or path-like or dict or None",

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/scenes/atmosphere/_particle_layer.py

@@ -65,6 +65,11 @@ class ParticleLayer(AbstractHeterogeneousAtmosphere):
     specified value (``tau_ref``).
     The particles radiative properties are specified by a data set
     (``dataset``).
+
+    Notes
+    -----
+    If the optical property dataset contains only one spectral data point, the
+    data is considered uniform throughout the entire spectrum.
     """
 
     bottom: pint.Quantity = documented(
@@ -164,9 +169,9 @@ class ParticleLayer(AbstractHeterogeneousAtmosphere):
             validator=attrs.validators.instance_of(xr.Dataset),
             repr=summary_repr,
         ),
-        doc="Particle radiative property data set."
+        doc="Particle radiative property data set. "
         "If an xarray dataset is passed, the dataset is used as is "
-        "(refer to the data guide for the format requirements of this dataset)."
+        "(refer to the data guide for the format requirements of this dataset). "
         "If a path is passed, the converter looks it up on the hard drive, using "
         "the file resolver. "
         "If a string is passed, it is interpreted as a particle radiative "
@@ -264,7 +269,11 @@ class ParticleLayer(AbstractHeterogeneousAtmosphere):
         # (n_wavelengths, n_layers)
         ds = self.dataset
         wavelengths = w.m_as(ds.w.attrs["units"])
-        interpolated = to_quantity(ds.albedo.interp(w=wavelengths))
+
+        if len(ds["w"]) == 1:
+            interpolated = to_quantity(ds.albedo.sel(w=wavelengths, method="nearest"))
+        else:
+            interpolated = to_quantity(ds.albedo.interp(w=wavelengths))
         where_present = np.reshape(self.eval_fractions(zgrid) > 0, (1, -1))
         return interpolated * where_present
 
@@ -278,8 +287,17 @@ class ParticleLayer(AbstractHeterogeneousAtmosphere):
         ds = self.dataset
         ds_w_units = ureg(ds.w.attrs["units"])
         wavelengths = np.atleast_1d(w.m_as(ds_w_units))
-        sigma_t_star = to_quantity(ds.sigma_t.interp(w=wavelengths))
-        sigma_t_star_ref = to_quantity(ds.sigma_t.interp(w=self.w_ref.m_as(ds_w_units)))
+
+        if len(ds["w"]) == 1:
+            sigma_t_star = to_quantity(ds.sigma_t.sel(w=wavelengths, method="nearest"))
+            sigma_t_star_ref = to_quantity(
+                ds.sigma_t.sel(w=self.w_ref.m_as(ds_w_units), method="nearest")
+            )
+        else:
+            sigma_t_star = to_quantity(ds.sigma_t.interp(w=wavelengths))
+            sigma_t_star_ref = to_quantity(
+                ds.sigma_t.interp(w=self.w_ref.m_as(ds_w_units))
+            )
 
         # Compute target optical thickness value
         tau = self.tau_ref * sigma_t_star / sigma_t_star_ref

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/scenes/biosphere/__init__.pyi

@@ -12,7 +12,7 @@ from ._rami_scenarios import (
 from ._rami_scenarios import (
     RAMIHomogeneousAbstractCanopies as RAMIHomogeneousAbstractCanopies,
 )
-from ._rami_scenarios import RAMIScenarioVersion as RAMIScenarioVersion
+from ._rami_scenarios import RAMIScenarioVariant as RAMIScenarioVariant
 from ._rami_scenarios import load_rami_scenario as load_rami_scenario
 from ._tree import AbstractTree as AbstractTree
 from ._tree import MeshTree as MeshTree

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/scenes/biosphere/_rami_scenarios.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import itertools
 from enum import Enum
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 from urllib.parse import urljoin
 
 import pooch
@@ -14,6 +14,8 @@ _DATA_URL_ROOT = "https://eradiate.eu/data/store/unstable/scenarios/rami5/"
 
 
 class RAMIActualCanopies(Enum):
+    """Enumeration of RAMI actual canopies."""
+
     JARVSELJA_PINE_STAND = "HET07_JPS_SUM"  # Summer
     OFENPASS_PINE_STAND = "HET08_OPS_WIN"  # Winter
     JARVSELJA_BIRCH_STAND_SUMMER = "HET09_JBS_SUM"  # Summer
@@ -25,6 +27,8 @@ class RAMIActualCanopies(Enum):
 
 
 class RAMIHeterogeneousAbstractCanopies(Enum):
+    """Enumeration of RAMI heterogeneous abstract canopies."""
+
     ANISOTROPIC_BACKGROUND_OVERSTOREY_SPARSE_BRF_MODEL_A = "HET10_DIS_S1A"
     ANISOTROPIC_BACKGROUND_OVERSTOREY_SPARSE_BRF_MODEL_B = "HET11_DIS_S1B"
     ANISOTROPIC_BACKGROUND_OVERSTOREY_SPARSE_BRF_MODEL_C = "HET12_DIS_S1C"
@@ -44,6 +48,8 @@ class RAMIHeterogeneousAbstractCanopies(Enum):
 
 
 class RAMIHomogeneousAbstractCanopies(Enum):
+    """Enumeration of RAMI homogeneous abstract canopies."""
+
     ANISOTROPIC_BACKGROUND_PLANOPHILE_A = "HOM23_DIS_P1A"
     ANISOTROPIC_BACKGROUND_PLANOPHILE_B = "HOM24_DIS_P1B"
     ANISOTROPIC_BACKGROUND_PLANOPHILE_C = "HOM25_DIS_P1C"
@@ -60,25 +66,30 @@ class RAMIHomogeneousAbstractCanopies(Enum):
     ADJACENT_CANOPIES_MEDIUM_ERECTOPHILE_SPARSE_PLANOPHILE = "HOM30_DIS_ED0"
 
 
-class RAMIScenarioVersion(Enum):
+RAMICanopies = Union[
+    RAMIActualCanopies,
+    RAMIHomogeneousAbstractCanopies,
+    RAMIHeterogeneousAbstractCanopies,
+]  #: Type alias to a union of all RAMI canopy enumerations.
+
+
+class RAMIScenarioVariant(Enum):
+    """Enumeration of RAMI scenario variants (original or simplified)."""
+
     ORIGINAL = "original"
     SIMPLIFIED = "simplified"
 
 
 def generate_name(
-    scenario_name: (
-        RAMIActualCanopies
-        | RAMIHeterogeneousAbstractCanopies
-        | RAMIHomogeneousAbstractCanopies
-    ),
-    version: RAMIScenarioVersion = RAMIScenarioVersion.ORIGINAL,
+    scenario_name: RAMICanopies,
+    version: RAMIScenarioVariant = RAMIScenarioVariant.ORIGINAL,
 ) -> str:
     """
     Generate a name for a scenario based on its name and version.
 
     Parameters
     ----------
-    scenario_name : RAMIActualCanopies or RAMIHeterogeneousAbstractCanopies or RAMIHomogeneousAbstractCanopies
+    scenario_name : RAMICanopies
         The name of the scenario.
     version : ScenarioVersion
         The version of the scenario.
@@ -90,29 +101,18 @@ def generate_name(
     """
     return (
         f"{scenario_name.value}-{version.value}"
-        if version == RAMIScenarioVersion.SIMPLIFIED
+        if version == RAMIScenarioVariant.SIMPLIFIED
         else scenario_name.value
     )
 
 
-def _convert_to_enum(
-    scenario_name: (
-        str
-        | RAMIActualCanopies
-        | RAMIHeterogeneousAbstractCanopies
-        | RAMIHomogeneousAbstractCanopies
-    ),
-) -> (
-    RAMIActualCanopies
-    | RAMIHeterogeneousAbstractCanopies
-    | RAMIHomogeneousAbstractCanopies
-):
+def _convert_to_enum(scenario_name: str | RAMICanopies) -> RAMICanopies:
     """
     Convert a scenario name to an enum if it is a string.
 
     Parameters
     ----------
-    scenario_name : str or RAMIActualCanopies or RAMIHeterogeneousAbstractCanopies or RAMIHomogeneousAbstractCanopies
+    scenario_name : str or RAMICanopies
         The name of the scenario.
 
     Returns
@@ -138,13 +138,8 @@ def _convert_to_enum(
 
 
 def load_rami_scenario(
-    scenario_name: (
-        str
-        | RAMIActualCanopies
-        | RAMIHeterogeneousAbstractCanopies
-        | RAMIHomogeneousAbstractCanopies
-    ),
-    version: RAMIScenarioVersion = RAMIScenarioVersion.ORIGINAL,
+    scenario_name: str | RAMICanopies,
+    version: RAMIScenarioVariant = RAMIScenarioVariant.ORIGINAL,
     padding: int = 0,
     unpack_folder: Optional[Path] = None,
     spectral_data: Optional[dict] = None,
@@ -160,7 +155,7 @@ def load_rami_scenario(
     scenario_name : str or RAMIActualCanopies or RAMIHeterogeneousAbstractCanopies or RAMIHomogeneousAbstractCanopies
         The name of the RAMI-V scenario. If a string is provided, it will
         automatically be converted to the appropriate enum.
-    version : RAMIScenarioVersion
+    version : RAMIScenarioVariant
         The version of the scenario.
     padding : int, optional
         The padding to apply to the scenario, defaults to 0.

{eradiate-0.31.0.dev0 → eradiate-0.31.0.dev1}/src/eradiate/scenes/core.py

@@ -32,7 +32,7 @@ class SceneElement(ABC):
     Warnings
     --------
     All subclasses *must* have a hash, thus ``eq`` must be ``False`` (see
-    `attrs docs on hashing <https://www.attrs.org/en/stable/hashing.html>`_
+    `attrs docs on hashing <https://www.attrs.org/en/stable/hashing.html>`__
     for a complete explanation). This is required in order to make it possible
     to use caching decorators on instance methods.