jerlov 0.9.2__tar.gz → 0.9.3__tar.gz

{jerlov-0.9.2/jerlov.egg-info → jerlov-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.9.2
+Version: 0.9.3
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -285,6 +285,9 @@ scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
 
 It refuses to go through a layer the paper declared nothing for, rather than
 carrying the last type on: 3C stops at 70 m, 9C at 10 m.
+`jerlov.profile_depth("3C")` says how far a descent can go, and
+`d.transmittance_at(z)` gives any depth above the descent's bottom without
+descending again.
 
 ## Light for photosynthesis
 
@@ -315,7 +318,9 @@ r.beyond          # "clearer" or "more turbid" than every type, or None
 
 It ranks the types of one edition; it draws no boundaries, since those differ
 between editions. A single wavelength is accepted, and ranks oceanic and
-coastal types less well apart than a spectrum does.
+coastal types less well apart than a spectrum does. `types=` compares with
+some of the types only, which keeps the wavelengths where only the others
+have gaps.
 
 ## Other entry points
 

{jerlov-0.9.2 → jerlov-0.9.3}/README.md

@@ -255,6 +255,9 @@ scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
 
 It refuses to go through a layer the paper declared nothing for, rather than
 carrying the last type on: 3C stops at 70 m, 9C at 10 m.
+`jerlov.profile_depth("3C")` says how far a descent can go, and
+`d.transmittance_at(z)` gives any depth above the descent's bottom without
+descending again.
 
 ## Light for photosynthesis
 
@@ -285,7 +288,9 @@ r.beyond          # "clearer" or "more turbid" than every type, or None
 
 It ranks the types of one edition; it draws no boundaries, since those differ
 between editions. A single wavelength is accepted, and ranks oceanic and
-coastal types less well apart than a spectrum does.
+coastal types less well apart than a spectrum does. `types=` compares with
+some of the types only, which keeps the wavelengths where only the others
+have gaps.
 
 ## Other entry points
 

{jerlov-0.9.2 → jerlov-0.9.3}/jerlov/__init__.py

@@ -50,6 +50,7 @@ from .water import (
     descend,
     kd_spectrum,
     measured_points,
+    profile_depth,
     pure_water_absorption,
     water,
     water_type_at_depth,
@@ -75,6 +76,7 @@ __all__ = [
     "water",
     "water_type_at_depth",
     "descend",
+    "profile_depth",
     "Descent",
     "classify_kd",
     "KdClassification",
@@ -104,4 +106,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.9.2"
+__version__ = "0.9.3"

{jerlov-0.9.2 → jerlov-0.9.3}/jerlov/par.py

@@ -30,7 +30,7 @@ from __future__ import annotations
 import numpy as np
 
 from . import _data
-from .water import Descent, MissingQuantityError, Water, _require_number, water
+from .water import Descent, MissingQuantityError, Water, _require_number
 
 #: Planck constant (J s), speed of light (m/s) and Avogadro constant (1/mol),
 #: exact by the 2019 definition of the SI.
@@ -241,18 +241,20 @@ def par_profile(surface_downwelling, wavelengths, depths_m, *, kd,
                 f"the descent stops at {deepest:g} m, above the deepest depth "
                 f"asked for ({depths.max():g} m)"
             )
-        layers = [(top, bottom, water(t, kd.source).kd(sub_wl))
-                  for top, bottom, t in kd.layers]
+        if len(kd._kd) != len(kd.layers):
+            raise MissingQuantityError(
+                "this Descent was not made by descend(), so it does not "
+                "carry the Kd of its layers"
+            )
         kd_from = (f"a descent from Jerlov {kd.surface_water_type} "
                    f"({kd.source})")
+        descent = kd
 
         def optical_depth(z):
-            total = np.zeros_like(sub_wl)
-            for top, bottom, values in layers:
-                total += values * min(max(z - top, 0.0), bottom - top)
-            return total
+            # The descent's own layers, on the samples PAR rests on only.
+            return descent._optical_depth(z, near)
 
-        kd_values = (np.vstack([v for _, _, v in layers]) if layers
+        kd_values = (np.vstack([v[near] for v in kd._kd]) if kd._kd
                      else np.zeros_like(sub_wl))
     else:
         if isinstance(kd, Water):

{jerlov-0.9.2 → jerlov-0.9.3}/jerlov/water.py

@@ -9,7 +9,7 @@ same path.
 from __future__ import annotations
 
 import warnings
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 import numpy as np
 
@@ -579,8 +579,8 @@ class KdClassification:
         )
 
 
-def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
-                ) -> KdClassification:
+def classify_kd(wavelengths, kd, *, source: str = "jerlov1976",
+                types=None) -> KdClassification:
     """Find the Jerlov type whose Kd spectrum a measured one is closest to.
 
     Every type of ``source`` is compared with the measurement at the given
@@ -600,6 +600,12 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
     source:
         A source carrying Kd: ``"jerlov1976"`` (the default, all ten types),
         ``"jerlov1968"``, ``"austin1986"`` or ``"solonenko2015"``.
+    types:
+        The types to compare with, if not all of ``source``'s; the oceanic
+        ones, say, for a measurement made offshore. A wavelength is left
+        out wherever any compared type has no Kd, so leaving out types with
+        gaps keeps more wavelengths: Solonenko & Mobley's 3C and 5C have
+        none from 600 nm on.
 
     Notes
     -----
@@ -625,7 +631,24 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
         # were a gap, leaving the other wavelengths to decide alone.
         raise ValueError("Kd must be positive and finite (NaN marks a gap)")
 
-    waters = {t: water(t, source) for t in src.water_types}
+    if types is None:
+        compared = src.water_types
+    else:
+        # One type given as a string is one type: tuple("III") would be
+        # three of type "I".
+        compared = (types,) if isinstance(types, str) else tuple(types)
+        unknown = [t for t in compared if t not in src.water_types]
+        if unknown:
+            raise KeyError(
+                f"source {source!r} does not cover Jerlov "
+                f"{', '.join(map(repr, unknown))} "
+                f"(available: {', '.join(src.water_types)})"
+            )
+        if not compared:
+            raise ValueError("types must name at least one water type")
+        if len(set(compared)) != len(compared):
+            raise ValueError("types names a water type more than once")
+    waters = {t: water(t, source) for t in compared}
     # Raises for a wavelength outside the source's range. The flags are
     # checked below, once, on the wavelengths actually compared: ten
     # warnings for one comparison would bury the one that matters.
@@ -637,7 +660,7 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
     if not usable.any():
         raise MissingQuantityError(
             "no wavelength has both a measured Kd and a Kd for every type "
-            f"of {source!r}"
+            f"compared from {source!r}"
         )
     by_flags: dict[str, list[str]] = {}
     for water_type, w in waters.items():
@@ -699,6 +722,58 @@ class Descent:
     last stops at ``depth_m``."""
     transmittance: np.ndarray
     """``Ed(depth) / Ed(0)``: ``exp(-sum(Kd_i * thickness_i))``."""
+    _kd: tuple[np.ndarray, ...] = field(default=(), repr=False)
+    """The Kd of each layer in :attr:`layers`, on :attr:`wavelengths`."""
+
+    def _optical_depth(self, depth: float, columns=slice(None)) -> np.ndarray:
+        """``sum(Kd_i * thickness_i)`` from the surface to ``depth``.
+
+        ``columns`` picks wavelengths, so that a caller using only some of
+        them, as PAR does, never touches the rest.
+        """
+        total = np.zeros(np.size(self.wavelengths))[columns]
+        for (top, bottom, _), values in zip(self.layers, self._kd):
+            total = total + values[columns] * min(max(depth - top, 0.0),
+                                                  bottom - top)
+        return total
+
+    def transmittance_at(self, depth_m):
+        """``Ed(z) / Ed(0)`` at any depth from the surface to :attr:`depth_m`.
+
+        Uses the layers already crossed, so it is what :func:`descend` to
+        that depth would give, without calling it again. A single depth
+        gives an array on :attr:`wavelengths` (a float if the descent was
+        asked for at one wavelength); an array of depths gives one row per
+        depth.
+
+        Raises
+        ------
+        MissingQuantityError
+            Below :attr:`depth_m`. Descend further, if the profile allows:
+            see :func:`profile_depth`.
+        """
+        if len(self._kd) != len(self.layers):
+            # Only descend() records the Kd of each layer; without it every
+            # depth would come back as 1, looking like perfectly clear water.
+            raise MissingQuantityError(
+                "this Descent was not made by descend(), so it does not "
+                "carry the Kd of its layers"
+            )
+        depths = np.asarray(depth_m, dtype=float)
+        if not np.all(np.isfinite(depths)):
+            raise ValueError(f"depth_m must be finite numbers, not {depth_m!r}")
+        if np.any(depths < 0):
+            raise ValueError("depth_m cannot be negative")
+        if np.any(depths > self.depth_m):
+            raise MissingQuantityError(
+                f"this descent stops at {self.depth_m:g} m, above "
+                f"{depths.max():g} m; descend further to go deeper"
+            )
+        out = np.array([np.exp(-self._optical_depth(float(z)))
+                        for z in depths.ravel()])
+        if depths.ndim == 0:
+            return _like_input(out[0], self.transmittance)
+        return out.reshape(depths.shape + (np.size(self.wavelengths),))
 
     def __repr__(self) -> str:
         # Adjacent 10 m layers of one type are shown as one span.
@@ -808,7 +883,38 @@ def descend(surface_water_type: str, depth_m: float, wavelengths, *,
         wavelengths=query,
         layers=tuple(layers),
         transmittance=_like_input(np.exp(-optical_depth), wavelengths),
+        _kd=tuple(_frozen_copy(kd[t]) for _, _, t in layers),
+    )
+
+
+def _frozen_copy(values: np.ndarray) -> np.ndarray:
+    out = np.array(values, dtype=float)
+    out.setflags(write=False)
+    return out
+
+
+def profile_depth(surface_water_type: str) -> float:
+    """How deep :func:`descend` can go below ``surface_water_type``, in m.
+
+    The top of the first layer for which Williamson & Hollins (2023)
+    declared no type, or 200 m, where their profile ends. Coastal types run
+    out early: 9C at 10 m, 5C and 7C at 20 m, 3C at 70 m.
+
+    ::
+
+        d = jerlov.descend("3C", jerlov.profile_depth("3C"), wl)   # to 70 m
+    """
+    rows = sorted(
+        (r for r in _data._rows("williamson2023_depth.csv")
+         if r["surface_water_type"] == surface_water_type),
+        key=lambda r: float(r["depth_min_m"]),
     )
+    if not rows:
+        water_type_at_depth(surface_water_type, 0.0)   # raises, naming types
+    for row in rows:
+        if not row["water_type"]:
+            return float(row["depth_min_m"])
+    return float(rows[-1]["depth_max_m"])
 
 
 #: Why each source without a pure water absorption has none.

{jerlov-0.9.2 → jerlov-0.9.3/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.9.2
+Version: 0.9.3
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -285,6 +285,9 @@ scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
 
 It refuses to go through a layer the paper declared nothing for, rather than
 carrying the last type on: 3C stops at 70 m, 9C at 10 m.
+`jerlov.profile_depth("3C")` says how far a descent can go, and
+`d.transmittance_at(z)` gives any depth above the descent's bottom without
+descending again.
 
 ## Light for photosynthesis
 
@@ -315,7 +318,9 @@ r.beyond          # "clearer" or "more turbid" than every type, or None
 
 It ranks the types of one edition; it draws no boundaries, since those differ
 between editions. A single wavelength is accepted, and ranks oceanic and
-coastal types less well apart than a spectrum does.
+coastal types less well apart than a spectrum does. `types=` compares with
+some of the types only, which keeps the wavelengths where only the others
+have gaps.
 
 ## Other entry points
 

{jerlov-0.9.2 → jerlov-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jerlov"
-version = "0.9.2"
+version = "0.9.3"
 description = "Inherent optical properties of Jerlov water types, with provenance"
 readme = "README.md"
 requires-python = ">=3.10"

{jerlov-0.9.2 → jerlov-0.9.3}/tests/test_classify.py

@@ -89,3 +89,33 @@ def test_what_cannot_be_compared_is_refused():
         jerlov.classify_kd(WL, [0.05])
     with pytest.raises(jerlov.MissingQuantityError, match="no wavelength"):
         jerlov.classify_kd([500.0], [np.nan])
+
+
+def test_types_narrows_the_comparison_and_keeps_more_wavelengths():
+    """Solonenko & Mobley's 3C and 5C have no Kd from 600 nm on, which
+    took those wavelengths out of every comparison."""
+    wl = np.arange(400.0, 701.0, 25.0)
+    oceanic = ("I", "IA", "IB", "II", "III")
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", jerlov.ProvenanceWarning)
+        kd = jerlov.water("II", source="solonenko2015").kd(wl)
+        every = jerlov.classify_kd(wl, kd, source="solonenko2015")
+        some = jerlov.classify_kd(wl, kd, source="solonenko2015",
+                                  types=oceanic)
+    assert every.excluded_nm == (600.0, 625.0, 650.0, 675.0, 700.0)
+    assert some.excluded_nm == ()
+    assert some.water_type == "II"
+    assert {t for t, _ in some.distances} == set(oceanic)
+
+
+def test_types_must_be_types_of_the_source():
+    with pytest.raises(KeyError, match="does not cover Jerlov '3C'"):
+        jerlov.classify_kd(WL, _kd("II"), source="austin1986",
+                           types=("II", "IA", "3C"))
+    with pytest.raises(ValueError, match="at least one"):
+        jerlov.classify_kd(WL, _kd("II"), types=())
+    with pytest.raises(ValueError, match="more than once"):
+        jerlov.classify_kd(WL, _kd("II"), types=("II", "II"))
+    # A string is one type, not a sequence of letters.
+    alone = jerlov.classify_kd(WL, _kd("III"), types="III")
+    assert alone.distances == (("III", 0.0),)

{jerlov-0.9.2 → jerlov-0.9.3}/tests/test_depth.py

@@ -190,3 +190,50 @@ def test_a_descent_prints_its_path_not_its_arrays():
                     "Kd from jerlov1976; 301 wavelengths>")
     assert repr(jerlov.descend("II", 0.0, 500.0)).startswith(
         "<Descent II to 0 m: no layer crossed;")
+
+
+def test_profile_depth_is_where_descend_stops():
+    """Three examples searched for this by trying descend() every 10 m."""
+    expected = {"I": 200.0, "IB": 200.0, "III": 170.0, "1C": 110.0,
+                "3C": 70.0, "5C": 20.0, "7C": 20.0, "9C": 10.0}
+    for water_type, depth in expected.items():
+        assert jerlov.profile_depth(water_type) == depth
+        jerlov.descend(water_type, depth, 500.0)         # reaches it
+        with pytest.raises(jerlov.MissingQuantityError):
+            jerlov.descend(water_type, depth + 0.1, 500.0)
+    with pytest.raises(KeyError, match="known"):
+        jerlov.profile_depth("XI")
+
+
+def test_transmittance_at_is_a_shorter_descent():
+    wl = np.arange(400.0, 701.0, 10.0)
+    d = jerlov.descend("1C", 45.0, wl)
+    for z in (0.0, 7.5, 10.0, 20.0, 33.3, 45.0):
+        assert d.transmittance_at(z) == pytest.approx(
+            jerlov.descend("1C", z, wl).transmittance, rel=1e-12)
+    rows = d.transmittance_at([[0.0, 10.0], [20.0, 45.0]])
+    assert rows.shape == (2, 2, wl.size)
+    assert rows[1, 1] == pytest.approx(d.transmittance)
+    one = jerlov.descend("II", 30.0, 500.0)
+    assert isinstance(one.transmittance_at(12.0), float)
+    assert one.transmittance_at(12.0) == jerlov.descend("II", 12.0, 500.0).transmittance
+
+
+def test_transmittance_at_refuses_what_the_descent_does_not_cover():
+    d = jerlov.descend("I", 30.0, [450.0, 550.0])
+    with pytest.raises(jerlov.MissingQuantityError, match="stops at 30 m"):
+        d.transmittance_at(31.0)
+    for bad in (-1.0, float("nan"), float("inf")):
+        with pytest.raises(ValueError):
+            d.transmittance_at(bad)
+    # A Descent built by hand has no layer Kd; it must not look clear.
+    hand = jerlov.Descent("I", 30.0, "jerlov1976", d.wavelengths, d.layers,
+                          d.transmittance)
+    with pytest.raises(jerlov.MissingQuantityError, match="descend"):
+        hand.transmittance_at(10.0)
+    with pytest.raises(jerlov.MissingQuantityError, match="descend"):
+        jerlov.par_profile(np.ones(301), np.arange(400.0, 701.0), 0.0,
+                           kd=jerlov.Descent("I", 30.0, "jerlov1976",
+                                             np.arange(400.0, 701.0),
+                                             d.layers, np.ones(301)),
+                           unit="photons")

{jerlov-0.9.2 → jerlov-0.9.3}/tests/test_packaging.py

@@ -389,3 +389,29 @@ def test_the_READMEs_count_the_examples():
         for script in (ROOT / "examples").glob("*.py"):
             assert script.name in readme.read_text(), (
                 f"{readme.relative_to(ROOT)} never mentions {script.name}")
+
+
+@source_tree
+def test_the_tests_read_the_installed_tables_not_the_source_tree():
+    """The suite is also run against the wheel, where there is no
+    jerlov/data/ beside the tests. test_petzold.py read it from there, and
+    the first run against a wheel failed."""
+    offenders = []
+    for path in (ROOT / "tests").glob("test_*.py"):
+        if path.name == "test_packaging.py":
+            continue
+        if re.search(r'"jerlov"\s*/\s*"data"', path.read_text()):
+            offenders.append(path.name)
+    assert not offenders, (
+        f"{offenders} read tables from the source tree; use "
+        "importlib.resources.files('jerlov.data')"
+    )
+
+
+@source_tree
+def test_publishing_checks_the_tag_and_runs_the_suite_on_the_wheel():
+    workflow = (ROOT / ".github" / "workflows" / "publish.yml").read_text()
+    assert "GITHUB_REF_NAME" in workflow and "pyproject.toml" in workflow, (
+        "publish.yml no longer compares the tag with the version")
+    assert "pytest wheel-tests" in workflow, (
+        "publish.yml no longer runs the tests against the installed wheel")

{jerlov-0.9.2 → jerlov-0.9.3}/tests/test_petzold.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import csv
 import re
+from importlib import resources
 import warnings
 from pathlib import Path
 
@@ -18,7 +19,9 @@ ROOT = Path(__file__).resolve().parent.parent
 
 
 def _table(station):
-    path = ROOT / "jerlov" / "data" / "petzold1972_vsf.csv"
+    # The installed package's own copy, not the source tree's: the suite is
+    # also run against the wheel, where there is no source tree to read.
+    path = resources.files("jerlov.data").joinpath("petzold1972_vsf.csv")
     with path.open(encoding="utf-8") as handle:
         return [r for r in csv.DictReader(handle) if r["station"] == station]