jerlov 0.9.0__tar.gz → 0.9.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.9.0
+Version: 0.9.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -375,9 +375,13 @@ python examples/what_an_eye_sees.py            any spectral sensitivity
 python examples/light_at_depth.py              light through the depth profile
 python examples/measured_scattering.py         Petzold's measured bb/b
 python examples/what_is_in_the_water.py        absorption without the water
+python examples/euphotic_zone.py               PAR and the 1 percent depth
+python examples/optical_link.py                laser range for links and lidar
+python examples/seagrass_depth_limit.py        light at the bottom, by requirement
+python examples/isolumes.py                    light levels and vertical migration
 ```
 
-Eight scripts, each aimed at a different reader; `examples/README.md` says
+Twelve scripts, each aimed at a different reader; `examples/README.md` says
 which to start with. CI runs all of them on every push, so an example that has
 stopped working is a failed build. Every one ends with the assumptions it
 made.

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

@@ -345,9 +345,13 @@ python examples/what_an_eye_sees.py            any spectral sensitivity
 python examples/light_at_depth.py              light through the depth profile
 python examples/measured_scattering.py         Petzold's measured bb/b
 python examples/what_is_in_the_water.py        absorption without the water
+python examples/euphotic_zone.py               PAR and the 1 percent depth
+python examples/optical_link.py                laser range for links and lidar
+python examples/seagrass_depth_limit.py        light at the bottom, by requirement
+python examples/isolumes.py                    light levels and vertical migration
 ```
 
-Eight scripts, each aimed at a different reader; `examples/README.md` says
+Twelve scripts, each aimed at a different reader; `examples/README.md` says
 which to start with. CI runs all of them on every push, so an example that has
 stopped working is a failed build. Every one ends with the assumptions it
 made.

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

@@ -104,4 +104,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.9.0"
+__version__ = "0.9.2"

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

@@ -88,8 +88,11 @@ class ParProfile:
 
     @property
     def fraction(self) -> np.ndarray:
-        """``PAR(z) / PAR(0)``, 0 to 1."""
-        return self.par / self.surface_par
+        """``PAR(z) / PAR(0)``, 0 to 1. NaN if there is no light at the
+        surface."""
+        return np.divide(self.par, self.surface_par,
+                         out=np.full_like(self.par, np.nan),
+                         where=self.surface_par != 0)
 
     def depth_of_fraction(self, fraction: float = 0.01) -> float:
         """The depth, in m, at which PAR falls to ``fraction`` of its surface value.
@@ -205,8 +208,19 @@ def par_profile(surface_downwelling, wavelengths, depths_m, *, kd,
     if surface.shape != wl.shape:
         raise ValueError(
             "surface_downwelling must have the same shape as wavelengths")
-    if np.any(surface < 0):
-        raise ValueError("downwelling irradiance cannot be negative")
+    if np.any(surface < 0) or np.any(np.isinf(surface)):
+        # NaN, a gap, passes here and is refused below only if PAR rests on it.
+        raise ValueError(
+            "downwelling irradiance must be finite and not negative")
+
+    # Only the samples that PAR rests on: those inside 400-700 nm and the
+    # one either side of each end. Kd is evaluated on these alone, so that
+    # a spectrum running past the Kd table, or a flagged Kd beyond 700 nm,
+    # neither refuses nor warns about light that PAR does not count.
+    near = np.zeros(wl.shape, dtype=bool)
+    near[np.searchsorted(wl, lo, side="right") - 1:
+         np.searchsorted(wl, hi, side="left") + 1] = True
+    sub_wl = wl[near]
 
     depths = np.array(depths_m, dtype=float)
     if not np.all(np.isfinite(depths)):
@@ -227,21 +241,22 @@ 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(wl))
+        layers = [(top, bottom, water(t, kd.source).kd(sub_wl))
                   for top, bottom, t in kd.layers]
         kd_from = (f"a descent from Jerlov {kd.surface_water_type} "
                    f"({kd.source})")
 
         def optical_depth(z):
-            total = np.zeros_like(wl)
+            total = np.zeros_like(sub_wl)
             for top, bottom, values in layers:
                 total += values * min(max(z - top, 0.0), bottom - top)
             return total
 
-        kd_values = np.vstack([v for _, _, v in layers]) if layers else wl * 0
+        kd_values = (np.vstack([v for _, _, v in layers]) if layers
+                     else np.zeros_like(sub_wl))
     else:
         if isinstance(kd, Water):
-            kd_values = np.asarray(kd.kd(wl), dtype=float)
+            kd_values = np.asarray(kd.kd(sub_wl), dtype=float)
             kd_from = f"Jerlov {kd.name}" if kd.name else "the given water"
             if kd.source is not None:
                 kd_from += f" ({kd.source.key})"
@@ -250,8 +265,11 @@ def par_profile(surface_downwelling, wavelengths, depths_m, *, kd,
             kd_from = "the given Kd"
             if kd_values.shape != wl.shape:
                 raise ValueError("kd must have the same shape as wavelengths")
-        if np.any(kd_values < 0):
-            raise ValueError("kd cannot be negative")
+            kd_values = kd_values[near]
+        if np.any(kd_values < 0) or np.any(np.isinf(kd_values)):
+            # inf times a depth of 0 is NaN, so PAR at the surface came out
+            # NaN with only a NumPy RuntimeWarning.
+            raise ValueError("kd must be finite and not negative")
 
         def optical_depth(z):
             return kd_values * z
@@ -259,18 +277,17 @@ def par_profile(surface_downwelling, wavelengths, depths_m, *, kd,
     # The band: every sample inside 400-700 nm, plus the two ends.
     inside = (wl > lo) & (wl < hi)
     band = np.concatenate(([lo], wl[inside], [hi]))
-    near = np.zeros(wl.shape, dtype=bool)
-    near[np.searchsorted(wl, lo, side="right") - 1:
-         np.searchsorted(wl, hi, side="left") + 1] = True
-    for name, values in (("surface_downwelling", surface), ("Kd", kd_values)):
-        if np.any(np.isnan(np.atleast_2d(values)[:, near])):
+    for name, values in (("surface_downwelling", surface[near]),
+                         ("Kd", kd_values)):
+        if np.any(np.isnan(values)):
             raise MissingQuantityError(
                 f"{name} has a gap between {lo:g} and {hi:g} nm, so PAR, "
                 "which integrates over all of it, is not determined"
             )
-    surface_q = np.interp(band, wl, _photons(surface, wl, unit))
+    surface_q = np.interp(band, sub_wl,
+                          _photons(surface[near], sub_wl, unit))
 
     def tau(z):
-        return np.interp(band, wl, optical_depth(z))
+        return np.interp(band, sub_wl, optical_depth(z))
 
     return ParProfile(depths, band, surface_q, tau, deepest, kd_from)

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

@@ -620,8 +620,10 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
     measured = np.array(kd, dtype=float, ndmin=1)
     if wl.ndim != 1 or measured.shape != wl.shape:
         raise ValueError("kd must be one value per wavelength")
-    if np.any(measured <= 0):
-        raise ValueError("Kd must be positive (NaN marks a gap)")
+    if np.any(measured <= 0) or np.any(np.isinf(measured)):
+        # inf would otherwise fail isfinite below and be dropped as if it
+        # 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}
     # Raises for a wavelength outside the source's range. The flags are

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.9.0
+Version: 0.9.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -375,9 +375,13 @@ python examples/what_an_eye_sees.py            any spectral sensitivity
 python examples/light_at_depth.py              light through the depth profile
 python examples/measured_scattering.py         Petzold's measured bb/b
 python examples/what_is_in_the_water.py        absorption without the water
+python examples/euphotic_zone.py               PAR and the 1 percent depth
+python examples/optical_link.py                laser range for links and lidar
+python examples/seagrass_depth_limit.py        light at the bottom, by requirement
+python examples/isolumes.py                    light levels and vertical migration
 ```
 
-Eight scripts, each aimed at a different reader; `examples/README.md` says
+Twelve scripts, each aimed at a different reader; `examples/README.md` says
 which to start with. CI runs all of them on every push, so an example that has
 stopped working is a failed build. Every one ends with the assumptions it
 made.

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

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

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

@@ -83,6 +83,8 @@ def test_what_cannot_be_compared_is_refused():
         jerlov.classify_kd([250.0, 500.0], [1.0, 0.05])
     with pytest.raises(ValueError, match="positive"):
         jerlov.classify_kd([450.0, 500.0], [0.0, 0.05])
+    with pytest.raises(ValueError, match="finite"):
+        jerlov.classify_kd([450.0, 500.0], [np.inf, 0.05])
     with pytest.raises(ValueError, match="one value per wavelength"):
         jerlov.classify_kd(WL, [0.05])
     with pytest.raises(jerlov.MissingQuantityError, match="no wavelength"):

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

@@ -370,3 +370,22 @@ def test_every_optional_extra_is_used_by_something():
             assert re.search(rf"^\s*(import|from) {name}\b", code, re.M), (
                 f"extra {extra!r} installs {dist}, which nothing imports"
             )
+
+
+WORD_COUNTS = {"Eight": 8, "Nine": 9, "Ten": 10, "Eleven": 11, "Twelve": 12}
+
+
+@source_tree
+def test_the_READMEs_count_the_examples():
+    """Both said "Eight scripts", and a ninth was about to make them wrong."""
+    scripts = len(list((ROOT / "examples").glob("*.py")))
+    for readme in (ROOT / "README.md", ROOT / "examples" / "README.md"):
+        match = re.search(r"\b(\w+) scripts[,.]", readme.read_text())
+        assert match, f"{readme.name} no longer counts the examples"
+        assert WORD_COUNTS.get(match.group(1)) == scripts, (
+            f"{readme.relative_to(ROOT)} says {match.group(1)} scripts; "
+            f"examples/ has {scripts}"
+        )
+        for script in (ROOT / "examples").glob("*.py"):
+            assert script.name in readme.read_text(), (
+                f"{readme.relative_to(ROOT)} never mentions {script.name}")

{jerlov-0.9.0 → jerlov-0.9.2}/tests/test_par.py

@@ -107,6 +107,17 @@ def test_what_par_cannot_be_computed_from_is_refused():
     for bad in (-1.0, np.nan, np.inf):
         with pytest.raises(ValueError):
             jerlov.par_profile(FLAT, WL, bad, kd=FLAT, unit="photons")
+    infinite = FLAT.copy()
+    infinite[0] = np.inf
+    with pytest.raises(ValueError, match="finite"):
+        jerlov.par_profile(infinite, WL, 0.0, kd=FLAT, unit="photons")
+    with pytest.raises(ValueError, match="finite"):
+        jerlov.par_profile(FLAT, WL, 0.0, kd=infinite, unit="photons")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        dark = jerlov.par_profile(FLAT * 0, WL, [0.0, 1.0], kd=FLAT,
+                                  unit="photons")
+        assert np.all(np.isnan(dark.fraction))
     with pytest.raises(ValueError, match="other wavelengths"):
         jerlov.par_profile(FLAT, WL, 0.0, unit="photons",
                            kd=jerlov.descend("I", 20.0, WL[::2]))
@@ -128,3 +139,29 @@ def test_the_profile_keeps_the_shape_of_the_depths_and_cannot_be_changed():
     depths[0, 0] = 99.0
     assert p.depths_m[0, 0] == 0.0
     assert repr(p).startswith("<ParProfile surface 300 umol m-2 s-1, 4 depths")
+
+
+def test_light_outside_the_band_neither_refuses_nor_warns():
+    """A radiometer's 300-800 nm spectrum was refused because Jerlov (1976)
+    stops at 715 nm, and Kd flagged at 705 nm warned, though PAR counts
+    neither."""
+    w = jerlov.water("II", source="jerlov1976")
+    wide = np.arange(300.0, 801.0, 5.0)
+    band = np.arange(400.0, 701.0, 5.0)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        p_wide = jerlov.par_profile(np.ones_like(wide), wide, [0.0, 10.0],
+                                    kd=w, unit="energy")
+        p_band = jerlov.par_profile(np.ones_like(band), band, [0.0, 10.0],
+                                    kd=w, unit="energy")
+        just_past = np.arange(380.0, 711.0, 5.0)
+        jerlov.par_profile(np.ones_like(just_past), just_past, 10.0, kd=w,
+                           unit="energy")
+    assert p_wide.par == pytest.approx(p_band.par, rel=1e-12)
+    # A gap outside the band does not matter either; one inside does.
+    kd = np.full_like(wide, 0.1)
+    kd[0] = np.nan
+    assert jerlov.par_profile(FLAT, WL, 1.0, kd=np.full_like(WL, 0.1),
+                              unit="photons").par == pytest.approx(
+        jerlov.par_profile(np.ones_like(wide), wide, 1.0, kd=kd,
+                           unit="photons").par)

{jerlov-0.9.0 → jerlov-0.9.2}/tests/test_quoted_figures.py

@@ -411,3 +411,139 @@ def test_README_figures_for_classify_kd():
         warnings.simplefilter("ignore", jerlov.ProvenanceWarning)
         result = jerlov.classify_kd(band, jerlov.kd_spectrum(0.060, 490, band))
     assert repr(result) == quoted
+
+
+def test_figures_for_the_euphotic_zone_example():
+    """examples/README.md: IA with IB close behind; 154 m by the shortcut,
+    101 m layer by layer; 87 percent violet-blue there; the editions agree
+    at Kd(490) = 0.030 and not at 0.045."""
+    band = np.arange(400.0, 701.0, 5.0)
+    surface = np.interp(band, *jerlov.d65())
+    measured = jerlov.kd_spectrum(0.030, 490.0, band)
+    r = jerlov.classify_kd(band, measured)
+    assert [t for t, _ in r.distances[:2]] == ["IA", "IB"]
+    assert round(math.log(100) / 0.030) == 154
+    d = jerlov.descend("IA", 200.0, band)
+    assert d.layers[3][2] == "IB" and d.layers[2][2] == "IA"
+    layered = jerlov.par_profile(surface, band, 0.0, kd=d, unit="energy")
+    z1 = layered.depth_of_fraction()
+    assert round(z1) == 101
+    one_kd = jerlov.par_profile(surface, band, 0.0, unit="energy",
+                                kd=jerlov.water("IA", source="jerlov1976"))
+    spectral = jerlov.par_profile(surface, band, 0.0, kd=measured,
+                                  unit="energy")
+    # "The shortcut is the deepest."
+    assert math.log(100) / 0.030 > max(one_kd.depth_of_fraction(),
+                                       spectral.depth_of_fraction(), z1)
+    blue = jerlov.par_profile(surface * (band < 500), band, [0.0, z1],
+                              kd=d, unit="energy").par
+    total = jerlov.par_profile(surface, band, [0.0, z1], kd=d,
+                               unit="energy").par
+    assert round(100 * blue[1] / total[1]) == 87
+    editions = {s: jerlov.classify_kd(band, measured, source=s).water_type
+                for s in ("jerlov1976", "jerlov1968", "austin1986")}
+    assert set(editions.values()) == {"IA"}
+    other = jerlov.kd_spectrum(0.045, 490.0, band)
+    assert (jerlov.classify_kd(band, other).water_type,
+            jerlov.classify_kd(band, other, source="jerlov1968").water_type
+            ) == ("IB", "II")
+
+
+BAND = np.arange(400.0, 701.0, 5.0)
+
+
+def _d65():
+    return np.interp(BAND, *jerlov.d65())
+
+
+def test_figures_for_the_optical_link_example():
+    """4.34 dB per attenuation length, 9.2 in 40 dB; clearest at 494 nm in
+    IB and 564 nm in 5C; the sources' ranges at 532 nm differ by up to 2.9,
+    in III."""
+    per_length = 10 * math.log10(math.e)
+    assert round(per_length, 2) == 4.34
+    assert round(40 / per_length, 1) == 9.2
+    grid = np.arange(420.0, 651.0, 1.0)
+    for t, nm in (("IB", 494), ("5C", 564)):
+        assert grid[np.argmin(jerlov.water(t).c(grid))] == nm
+    ratios = {}
+    for t in ("IB", "II", "III", "1C", "3C", "5C"):
+        a = jerlov.water(t).c(532.0)
+        b = jerlov.water(t, source="solonenko2015").c(532.0)
+        ratios[t] = max(a, b) / min(a, b)
+    assert max(ratios, key=ratios.get) == "III"
+    assert round(ratios["III"], 1) == 2.9
+
+
+def _layered_limit(water_type, fraction):
+    for depth in np.arange(200.0, 0.0, -10.0):
+        try:
+            d = jerlov.descend(water_type, depth, BAND)
+        except jerlov.MissingQuantityError:
+            continue
+        p = jerlov.par_profile(_d65(), BAND, 0.0, kd=d, unit="energy")
+        return p.depth_of_fraction(fraction)
+
+
+def test_figures_for_the_seagrass_example():
+    """At 11 percent: 13.4 m in III, 2.7 m in 9C, 3.3 m lost from 1C to 3C;
+    the top-metre Kd(PAR) puts III at 9.4 m. 5 percent in 3C goes as deep
+    as 11 percent in 1C."""
+    limit = {t: _layered_limit(t, 0.11) for t in ("III", "1C", "3C", "9C")}
+    assert round(limit["III"], 1) == 13.4
+    assert round(limit["9C"], 1) == 2.7
+    assert round(limit["1C"] - limit["3C"], 1) == 3.3
+    top = jerlov.par_profile(_d65(), BAND, 1.0, unit="energy",
+                             kd=jerlov.water("III", source="jerlov1976"))
+    assert round(math.log(1 / 0.11) / -math.log(top.fraction), 1) == 9.4
+    assert round(_layered_limit("3C", 0.05), 1) == round(limit["1C"], 1)
+
+
+def test_figures_for_the_isolumes_example():
+    """Steps of 58 and 61 m in I, 106 and 114 m with one Kd; steps grow with
+    depth in every oceanic type; 1e-3 lies 9 times shallower in 9C than in
+    II; the light peaks at 475 nm below, 550 nm at the surface."""
+    def steps(kd, n):
+        p = jerlov.par_profile(_d65(), BAND, 0.0, kd=kd, unit="energy")
+        z = []
+        for level in (1e-1, 1e-2, 1e-3, 1e-4, 1e-5)[:n]:
+            try:
+                z.append(p.depth_of_fraction(level))
+            except jerlov.MissingQuantityError:
+                break
+        return np.diff(z)
+
+    deepest = {"I": 200.0, "IA": 200.0, "IB": 200.0, "II": 200.0,
+               "III": 170.0}
+    layered_i = steps(jerlov.descend("I", 200.0, BAND), 3)
+    assert [round(s) for s in layered_i] == [58, 61]
+    flat_i = steps(jerlov.water("I", source="jerlov1976"), 3)
+    assert [round(s) for s in flat_i] == [106, 114]
+    for t, depth in deepest.items():
+        s = steps(jerlov.descend(t, depth, BAND), 5)
+        assert np.all(np.diff(s) > 0), t
+    milli = {t: jerlov.par_profile(_d65(), BAND, 0.0, unit="energy",
+                                   kd=jerlov.water(t, source="jerlov1976")
+                                   ).depth_of_fraction(1e-3)
+             for t in ("II", "9C")}
+    assert round(milli["II"] / milli["9C"]) == 9
+    photons = _d65() * BAND
+    assert BAND[np.argmax(photons)] == 550.0
+    t23 = jerlov.descend("II", 23.0, BAND).transmittance
+    assert BAND[np.argmax(photons * t23)] == 475.0
+
+
+def test_figures_for_the_turbid_seagrass_section():
+    """Kd(PAR) to the 11 percent depth is above 0.27 1/m from 3C on and
+    below it to 1C; there 33.3 percent puts the limit 2.1 to 2.2 times
+    shallower than 11 percent."""
+    kd_column, ratio = {}, {}
+    for t in ("II", "III", "1C", "3C", "5C", "7C", "9C"):
+        z11 = _layered_limit(t, 0.11)
+        kd_column[t] = math.log(1 / 0.11) / z11
+        if kd_column[t] > 0.27:
+            ratio[t] = z11 / _layered_limit(t, 0.333)
+    assert set(ratio) == {"3C", "5C", "7C", "9C"}
+    assert kd_column["1C"] < 0.27
+    assert (round(min(ratio.values()), 1), round(max(ratio.values()), 1)) \
+        == (2.1, 2.2)