jerlov 0.3.1__tar.gz → 0.3.3__tar.gz

{jerlov-0.3.1/jerlov.egg-info → jerlov-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.3.1
+Version: 0.3.3
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0

{jerlov-0.3.1 → jerlov-0.3.3}/jerlov/__init__.py

@@ -78,4 +78,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.3.1"
+__version__ = "0.3.3"

{jerlov-0.3.1 → jerlov-0.3.3}/jerlov/_data.py

@@ -8,13 +8,13 @@ silently cleaned up on the way in.
 from __future__ import annotations
 
 import csv
+import os
+import sys
 from functools import lru_cache
 from importlib import resources
 
 import numpy as np
 
-import numpy as np
-
 #: numpy.trapezoid is the name from NumPy 2.0; before that it was numpy.trapz,
 #: which 2.0 removed. The package claims to work from NumPy 1.22, so neither
 #: can be assumed. This lives here rather than in a module about colour so
@@ -23,8 +23,38 @@ import numpy as np
 #: supported NumPy.
 trapezoid = getattr(np, "trapezoid", None) or np.trapz
 
+_PACKAGE_DIR = os.path.dirname(os.path.abspath(__file__)) + os.sep
+
+
+def caller_stacklevel() -> int:
+    """The ``stacklevel`` that points a warning at the caller's own code.
+
+    Call it from the function that calls ``warnings.warn``. A fixed number
+    is right only for one call path: ``Water.c`` reaches the flag check one
+    frame deeper than ``Water.a`` does, and ``Scene`` deeper still, so a
+    constant pointed some warnings at this package instead of at the line
+    that asked for the value.
+    """
+    frame = sys._getframe(1)
+    level = 1
+    while frame is not None and frame.f_code.co_filename.startswith(_PACKAGE_DIR):
+        frame = frame.f_back
+        level += 1
+    return level
+
+
+def _frozen(array: np.ndarray) -> np.ndarray:
+    """Make a cached array read-only.
+
+    The loaders below are cached, so every caller gets the same array
+    objects. Writing into one would silently change the table for every
+    later caller in the process.
+    """
+    array.setflags(write=False)
+    return array
+
 #: Values whose ``status`` is one of these should not be used without the
-#: caller being told. See README sections 1-6.
+#: caller being told. See DATA.md sections 1-6.
 QUESTIONABLE = frozenset({"suspect", "missing", "extrapolated",
                           "model_extrapolation", "reconstructed"})
 
@@ -75,8 +105,8 @@ def spectrum(
         )
     order = np.argsort(wl)
     return (
-        np.asarray(wl, dtype=float)[order],
-        np.asarray(values, dtype=float)[order],
+        _frozen(np.asarray(wl, dtype=float)[order]),
+        _frozen(np.asarray(values, dtype=float)[order]),
         tuple(statuses[i] for i in order),
     )
 
@@ -104,7 +134,15 @@ def austin_model() -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     m = np.array([float(r["M_slope"]) for r in rows])
     kw = np.array([float(r["Kw_pure_seawater_per_m"]) for r in rows])
     order = np.argsort(wl)
-    return wl[order], m[order], kw[order]
+    return _frozen(wl[order]), _frozen(m[order]), _frozen(kw[order])
+
+
+@lru_cache(maxsize=None)
+def austin_model_status() -> tuple[str, ...]:
+    """The ``status`` of each row of :func:`austin_model`, in the same order."""
+    rows = sorted(_rows("austin1986_model.csv"),
+                  key=lambda r: float(r["wavelength_nm"]))
+    return tuple(r["status"] for r in rows)
 
 
 @lru_cache(maxsize=None)
@@ -119,5 +157,5 @@ def b_from_c_ratio() -> tuple[np.ndarray, dict[str, np.ndarray]]:
             for r in rows
             if r["statistic"] == stat
         }
-        out[stat] = np.array([by_wl[w] for w in wl])
-    return np.array(wl), out
+        out[stat] = _frozen(np.array([by_wl[w] for w in wl]))
+    return _frozen(np.array(wl)), out

{jerlov-0.3.1 → jerlov-0.3.3}/jerlov/backscattering.py

@@ -70,11 +70,15 @@ def pure_water_vsf(angle_deg, wavelength_nm, salinity_psu: float = 37.0):
     The amplitude carries about 15 percent uncertainty, which the authors give
     as the agreement between measurement and theory.
     """
-    angle = np.atleast_1d(np.asarray(angle_deg, dtype=float))
+    angle = np.asarray(angle_deg, dtype=float)
     amplitude = (1.38 * (np.asarray(wavelength_nm, dtype=float) / 500.0) ** -4.32
                  * (1 + 0.3 * salinity_psu / 37.0) * 1e-4)
     out = amplitude * (1 + _ratio() * np.cos(np.radians(angle)) ** 2)
-    return _like_input(np.atleast_1d(out), angle_deg)
+    # Angle and wavelength broadcast against each other; the answer is a
+    # float only when neither of them was an array.
+    if np.ndim(out) == 0:
+        return float(out)
+    return out
 
 
 def pure_water_backscattering(wavelength_nm, salinity_psu: float = 37.0):
@@ -181,7 +185,7 @@ def bb_from_vsf(beta, angle_deg: float, wavelength_nm, *,
             "scattering function varies steeply here and a single-angle "
             "measurement pins bb poorly.",
             AngleWarning,
-            stacklevel=2,
+            stacklevel=_data.caller_stacklevel(),
         )
 
     scalar = np.ndim(beta) == 0 and np.ndim(wavelength_nm) == 0
@@ -198,7 +202,7 @@ def bb_from_vsf(beta, angle_deg: float, wavelength_nm, *,
             "so the particle contribution came out negative. Check the "
             "calibration, the wavelength and the salinity.",
             AngleWarning,
-            stacklevel=2,
+            stacklevel=_data.caller_stacklevel(),
         )
 
     def shape(values):

{jerlov-0.3.1 → jerlov-0.3.3}/jerlov/colour.py

@@ -163,7 +163,7 @@ def integrate_response(spectrum, wavelengths, response, response_wavelengths,
             "The integral is over the overlap and is biased by what was left "
             "out",
             CoverageWarning,
-            stacklevel=2,
+            stacklevel=_data.caller_stacklevel(),
         )
 
     resampled = np.stack(
@@ -202,7 +202,7 @@ def xyz_to_srgb(xyz, *, clip: bool = True) -> np.ndarray:
             "the colour lies outside the sRGB gamut"
             + (" and has been clipped" if clip else ""),
             GamutWarning,
-            stacklevel=2,
+            stacklevel=_data.caller_stacklevel(),
         )
     if clip:
         linear = np.clip(linear, 0.0, 1.0)

{jerlov-0.3.1 → jerlov-0.3.3}/jerlov/sources.py

@@ -55,7 +55,7 @@ HALTRIN1999 = ScatteringConstants(
 #: Solonenko & Mobley (2015) Eqs. (8a)-(8d). The small-particle coefficient
 #: 1.513 does not match Haltrin's 1.151302; the digit appears to have been
 #: dropped in transcription. Their published tables were computed with 1.513,
-#: so this value is required to reproduce them. See README section 6.
+#: so this value is required to reproduce them. See DATA.md section 6.
 SOLONENKO2015_SCATTERING = ScatteringConstants(
     bw_coeff=0.00583,
     bw_exponent=4.322,

{jerlov-0.3.1 → jerlov-0.3.3}/jerlov/water.py

@@ -44,6 +44,25 @@ def _like_input(result: np.ndarray, original) -> np.ndarray | float:
     return result
 
 
+def _support(grid: np.ndarray, query: np.ndarray) -> list[tuple[int, ...]]:
+    """The indices of the samples of ``grid`` each query's answer rests on.
+
+    A query that lands exactly on a sample rests on that sample alone: it is
+    not interpolated, so its neighbours are no part of the answer. Otherwise
+    it rests on the samples either side. The NaN check and the provenance
+    warnings all use this, so that they cannot disagree about what a value
+    depends on.
+    """
+    n = grid.size
+    out: list[tuple[int, ...]] = []
+    for i, w_query in zip(np.searchsorted(grid, query), query):
+        if i < n and grid[i] == w_query:
+            out.append((int(i),))
+        else:
+            out.append((max(int(i) - 1, 0), min(int(i), n - 1)))
+    return out
+
+
 class Water:
     """Absorption and scattering coefficients as functions of wavelength.
 
@@ -75,7 +94,9 @@ class Water:
         source: Source | None = None,
         flags: dict[str, tuple[str, ...]] | None = None,
     ) -> None:
-        self.wavelengths = np.asarray(wavelengths, dtype=float)
+        # Copied, so that neither the caller's arrays nor the packaged tables
+        # can change underneath this object, and it cannot change them.
+        self.wavelengths = np.array(wavelengths, dtype=float)
         if self.wavelengths.ndim != 1 or self.wavelengths.size == 0:
             raise ValueError("wavelengths must be a non-empty 1-D array")
         if np.any(np.diff(self.wavelengths) <= 0):
@@ -85,7 +106,7 @@ class Water:
         for key, value in (("a", a), ("b", b), ("Kd", kd)):
             if value is None:
                 continue
-            arr = np.asarray(value, dtype=float)
+            arr = np.array(value, dtype=float)
             if arr.shape != self.wavelengths.shape:
                 raise ValueError(f"{key} must have the same shape as wavelengths")
             self._series[key] = arr
@@ -127,33 +148,25 @@ class Water:
                 f"wavelength outside the range of the data ({lo:g}-{hi:g} nm). "
                 "This package does not extrapolate."
             )
-        self._warn_if_flagged(quantity, query)
+        support = _support(self.wavelengths, query)
+        self._warn_if_flagged(quantity, support)
         values = self._series[quantity]
         out = np.interp(query, self.wavelengths, values)
         # np.interp happily bridges a NaN-free path around a NaN, so check the
-        # samples the answer actually rests on. A query that lands exactly on
-        # a sample rests on that sample alone: it is not interpolated, so a
-        # missing neighbour must not poison it.
-        idx = np.searchsorted(self.wavelengths, query)
-        for k, (i, w_query) in enumerate(zip(idx, query)):
-            exact = i < self.wavelengths.size and self.wavelengths[i] == w_query
-            if exact:
-                if np.isnan(values[i]):
-                    out[k] = np.nan
-                continue
-            left, right = max(i - 1, 0), min(i, values.size - 1)
-            if np.any(np.isnan(values[left:right + 1])):
+        # samples the answer actually rests on.
+        for k, samples in enumerate(support):
+            if any(np.isnan(values[j]) for j in samples):
                 out[k] = np.nan
         return _like_input(out, wl)
 
-    def _warn_if_flagged(self, quantity: str, query: np.ndarray) -> None:
+    def _warn_if_flagged(self, quantity: str,
+                         support: list[tuple[int, ...]]) -> None:
         statuses = self._flags.get(quantity)
         if not statuses:
             return
         hit: set[str] = set()
-        idx = np.searchsorted(self.wavelengths, query)
-        for i in idx:
-            for j in (max(i - 1, 0), min(i, len(statuses) - 1)):
+        for samples in support:
+            for j in samples:
                 status = statuses[j]
                 if status in _data.QUESTIONABLE:
                     hit.add(f"{status} at {self.wavelengths[j]:g} nm")
@@ -161,9 +174,9 @@ class Water:
             warnings.warn(
                 f"{quantity} for Jerlov {self.name} rests on flagged values: "
                 + "; ".join(sorted(hit))
-                + ". See the package README for what is known about them.",
+                + ". See DATA.md for what is known about them.",
                 ProvenanceWarning,
-                stacklevel=3,
+                stacklevel=_data.caller_stacklevel(),
             )
 
     def a(self, wl):
@@ -188,7 +201,7 @@ class Water:
         ``backscatter_ratio`` is bb/b and has no default. It is not determined
         by the Jerlov classification: deriving it from the particle
         concentrations of Solonenko & Mobley and of Williamson & Hollins gives
-        answers that differ by up to a factor of 31. See README section 10.
+        answers that differ by up to a factor of 31. See DATA.md section 10.
 
         Reported ranges are roughly 0.005-0.01 for open ocean and 0.015-0.03
         for coastal water; the Petzold average-particle phase function gives
@@ -199,7 +212,7 @@ class Water:
                 "bb is not determined by the water type. Pass "
                 "backscatter_ratio=... explicitly (bb/b; roughly 0.005-0.01 "
                 "for open ocean, 0.015-0.03 for coastal water). "
-                "See README section 10."
+                "See DATA.md section 10."
             )
         if not 0.0 < backscatter_ratio < 0.5:
             raise ValueError("backscatter_ratio must lie in (0, 0.5)")
@@ -330,6 +343,10 @@ def water_type_at_depth(surface_water_type: str, depth_m: float) -> str | None:
     return None
 
 
+#: Austin & Petzold (1986) state their model holds below this K(490), 1/m.
+AUSTIN_KD490_LIMIT = 0.16
+
+
 def kd_spectrum(kd, wavelength_nm: float, at):
     """Reconstruct a Kd spectrum from a single measured value.
 
@@ -340,38 +357,96 @@ def kd_spectrum(kd, wavelength_nm: float, at):
     Parameters
     ----------
     kd:
-        Measured Kd in 1/m.
+        Measured Kd in 1/m. A scalar, or an array of measurements all made at
+        ``wavelength_nm`` (several stations, say); each is reconstructed
+        separately.
     wavelength_nm:
-        Wavelength at which ``kd`` was measured.
+        Wavelength at which ``kd`` was measured. A single value.
     at:
         Wavelength(s) at which to evaluate the spectrum.
 
+    Returns
+    -------
+    A float for scalar ``kd`` and ``at``. Otherwise an array of shape
+    ``kd.shape + at.shape``: one spectrum per measurement.
+
     Notes
     -----
-    The authors state the model holds for K(490) < 0.16 1/m. Accuracy is about
+    The authors state the model holds for K(490) < 0.16 1/m, and a
+    :class:`ProvenanceWarning` is raised for any measurement whose K(490),
+    measured or implied by the model, is not below that. Accuracy is about
     8 percent at wavelengths up to 590 nm and degrades to about 31 percent at
-    670 nm; M below 365 nm is itself extrapolated.
+    670 nm. M below 365 nm is itself extrapolated, and a result that rests on
+    it also warns.
     """
     wl, m, kw = _data.austin_model()
     lo, hi = float(wl[0]), float(wl[-1])
+    if np.ndim(wavelength_nm) != 0:
+        raise ValueError(
+            "wavelength_nm must be a single wavelength; for measurements at "
+            "different wavelengths, call kd_spectrum once for each"
+        )
+    wavelength_nm = float(wavelength_nm)
     query = _as_array(at)
     for value, label in ((wavelength_nm, "wavelength_nm"), (query, "at")):
         if np.any(np.asarray(value) < lo) or np.any(np.asarray(value) > hi):
             raise ValueError(f"{label} outside the model range ({lo:g}-{hi:g} nm)")
+    kd_values = np.asarray(kd, dtype=float)
 
     m1 = float(np.interp(wavelength_nm, wl, m))
     kw1 = float(np.interp(wavelength_nm, wl, kw))
-    if kd < kw1:
+    below = kd_values < kw1
+    if np.any(below):
+        shown = ", ".join(f"{v:g}" for v in np.atleast_1d(kd_values)[
+            np.atleast_1d(below)][:5])
         warnings.warn(
-            f"Kd={kd:g} is below the pure sea water value {kw1:g} at "
+            f"Kd={shown} is below the pure sea water value {kw1:g} at "
             f"{wavelength_nm:g} nm, which is not physically possible. "
             "Austin & Petzold (1986) reported exactly this problem in "
             "Jerlov's own type I values.",
             ProvenanceWarning,
-            stacklevel=2,
+            stacklevel=_data.caller_stacklevel(),
+        )
+
+    kd490 = (float(np.interp(490.0, wl, m)) / m1 * (kd_values - kw1)
+             + float(np.interp(490.0, wl, kw)))
+    outside = kd490 >= AUSTIN_KD490_LIMIT
+    if np.any(outside):
+        shown = ", ".join(f"{v:.3g}" for v in np.atleast_1d(kd490)[
+            np.atleast_1d(outside)][:5])
+        warnings.warn(
+            f"K(490) = {shown} 1/m"
+            + (" (implied by the model)" if wavelength_nm != 490.0 else "")
+            + f" is not below {AUSTIN_KD490_LIMIT:g} 1/m, the limit Austin & "
+            "Petzold (1986) give for their model. The reconstruction is "
+            "outside the range it was fitted to.",
+            ProvenanceWarning,
+            stacklevel=_data.caller_stacklevel(),
+        )
+
+    statuses = _data.austin_model_status()
+    flagged: set[str] = set()
+    for samples in _support(wl, np.concatenate(([wavelength_nm], query))):
+        for j in samples:
+            if statuses[j] in _data.QUESTIONABLE:
+                flagged.add(f"{statuses[j]} at {wl[j]:g} nm")
+    if flagged:
+        warnings.warn(
+            "the result rests on values of M that Austin & Petzold (1986) "
+            "flag as " + "; ".join(sorted(flagged)) + ", and say should be "
+            "used with caution",
+            ProvenanceWarning,
+            stacklevel=_data.caller_stacklevel(),
         )
-    result = np.interp(query, wl, m) / m1 * (kd - kw1) + np.interp(query, wl, kw)
-    return _like_input(result, at)
+
+    ratio = np.interp(query, wl, m) / m1
+    result = (ratio * (kd_values[..., None] - kw1)
+              + np.interp(query, wl, kw))
+    if np.ndim(at) == 0:
+        result = result[..., 0]
+    if np.ndim(result) == 0:
+        return float(result)
+    return result
 
 
 def b_from_c(c, wavelength_nm, *, bw, cw, bound: str = "average"):
@@ -395,5 +470,11 @@ def b_from_c(c, wavelength_nm, *, bw, cw, bound: str = "average"):
             f"wavelength outside the measured range ({wl[0]:g}-{wl[-1]:g} nm)"
         )
     ratio = np.interp(query, wl, ratios[bound])
+    if np.ndim(wavelength_nm) == 0:
+        ratio = ratio[0]
     result = (np.asarray(c, dtype=float) - cw) * ratio + bw
-    return _like_input(np.atleast_1d(result), wavelength_nm)
+    # c and the wavelength broadcast against each other; the answer is a
+    # float only when neither of them was an array.
+    if np.ndim(result) == 0:
+        return float(result)
+    return result

{jerlov-0.3.1 → jerlov-0.3.3/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.3.1
+Version: 0.3.3
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0

{jerlov-0.3.1 → jerlov-0.3.3}/pyproject.toml

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

{jerlov-0.3.1 → jerlov-0.3.3}/tests/test_api.py

@@ -63,7 +63,7 @@ def test_missing_values_stay_missing():
 
 
 def test_flagged_wavelengths_warn():
-    """Jerlov IA's b is inconsistent with its own Table 3; see README 4."""
+    """Jerlov IA's b is inconsistent with its own Table 3; see DATA.md section 4."""
     w = jerlov.water("IA", source="solonenko2015")
     with pytest.warns(ProvenanceWarning, match="suspect"):
         w.b(550)
@@ -112,7 +112,10 @@ def test_kd_spectrum_reproduces_austin_table6():
         "austin1986_kd.csv", "II", None, "Kd_downwelling_per_m"
     )
     k475 = float(kd[np.where(wl == 475)[0][0]])
-    predicted = jerlov.kd_spectrum(k475, 475, wl)
+    # Table VI starts at 350 nm, where the paper itself flags M as
+    # extrapolated, so reproducing it must say so.
+    with pytest.warns(ProvenanceWarning, match="extrapolated at 350 nm"):
+        predicted = jerlov.kd_spectrum(k475, 475, wl)
     assert np.max(np.abs(100 * (predicted - kd) / kd)) < 0.5
 
 
@@ -213,3 +216,109 @@ def test_interpolating_across_a_gap_still_gives_nan():
         assert np.isnan(w.a(650))          # a published value that is wrong
         assert np.isnan(w.a(660))          # and interpolation across it
         assert np.isnan(w.a(675))
+
+
+def test_b_from_c_keeps_every_c_at_a_single_wavelength():
+    """An array of c at one wavelength used to come back as its first value."""
+    c = np.array([0.5, 1.0, 2.0])
+    out = jerlov.b_from_c(c, 488.0, bw=0.003, cw=0.02)
+    assert out.shape == (3,)
+    for value, single in zip(out, c):
+        assert value == pytest.approx(
+            jerlov.b_from_c(float(single), 488.0, bw=0.003, cw=0.02)
+        )
+    assert isinstance(jerlov.b_from_c(0.5, 488.0, bw=0.003, cw=0.02), float)
+
+
+def test_a_returned_water_cannot_corrupt_the_packaged_table():
+    """The loaders are cached; a caller's in-place edit must stay local."""
+    w = jerlov.water("III")
+    before = jerlov.water("III").wavelengths.copy()
+    w.wavelengths *= 2.0
+    assert np.array_equal(jerlov.water("III").wavelengths, before)
+
+
+def test_the_cached_tables_are_read_only():
+    from jerlov import _data
+
+    wl, m, kw = _data.austin_model()
+    with pytest.raises(ValueError):
+        wl[0] = 0.0
+    wl, values, _ = _data.spectrum(
+        "williamson2022_iop.csv", "III", "a", "value_per_m"
+    )
+    with pytest.raises(ValueError):
+        values[0] = 0.0
+
+
+def test_measurements_are_copied_not_shared():
+    wl = np.array([400.0, 500.0, 600.0])
+    a = np.array([0.1, 0.2, 0.3])
+    mine = Water.from_measurements(wl, a=a)
+    a[1] = 99.0
+    assert mine.a(500.0) == pytest.approx(0.2)
+
+
+@pytest.mark.parametrize("method", ["kd", "c"])
+def test_a_provenance_warning_points_at_the_callers_line(method):
+    """Not at water.py: `c` reaches the check one frame deeper than `kd`."""
+    source = "jerlov1976" if method == "kd" else "williamson2022"
+    w = jerlov.water("9C" if method == "kd" else "III", source=source)
+    query = 349.5 if method == "kd" else 305.0
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        getattr(w, method)(query)
+    flagged = [c for c in caught if issubclass(c.category, ProvenanceWarning)]
+    assert flagged
+    assert all(c.filename == __file__ for c in flagged)
+
+
+def test_a_flag_on_a_neighbour_does_not_warn_at_an_exact_sample():
+    """350 nm is sound; only 349 nm is missing. The answer at 350 rests on
+    350 alone, as the NaN check already knew."""
+    w = jerlov.water("9C", source="jerlov1976")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", ProvenanceWarning)
+        assert np.isfinite(w.kd(350.0))
+    with pytest.warns(ProvenanceWarning, match="missing at 349 nm"):
+        w.kd(349.5)
+
+
+def test_kd_spectrum_takes_several_measurements_at_once():
+    kd = np.array([0.03, 0.06, 0.1])
+    at = np.array([440.0, 550.0, 650.0])
+    together = jerlov.kd_spectrum(kd, 490, at)
+    assert together.shape == (3, 3)
+    for row, single in zip(together, kd):
+        assert np.allclose(row, jerlov.kd_spectrum(float(single), 490, at))
+    at_one = jerlov.kd_spectrum(kd, 490, 550.0)
+    assert at_one.shape == (3,)
+    assert np.allclose(at_one, together[:, 1])
+
+
+def test_kd_spectrum_wants_one_measurement_wavelength():
+    with pytest.raises(ValueError, match="single wavelength"):
+        jerlov.kd_spectrum(0.06, [490, 500], 550)
+
+
+def test_kd_spectrum_warns_outside_the_fitted_range():
+    """Austin & Petzold: the model holds for K(490) < 0.16 1/m."""
+    with pytest.warns(ProvenanceWarning, match="0.16"):
+        jerlov.kd_spectrum(0.2, 490, 550)
+    # Measured elsewhere, the K(490) the model implies is what counts.
+    with pytest.warns(ProvenanceWarning, match="implied by the model"):
+        jerlov.kd_spectrum(0.3, 440, 550)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", ProvenanceWarning)
+        jerlov.kd_spectrum(0.15, 490, 550)
+
+
+def test_kd_spectrum_warns_where_m_is_extrapolated():
+    with pytest.warns(ProvenanceWarning, match="extrapolated at 355 nm"):
+        jerlov.kd_spectrum(0.06, 490, 355.0)
+    with pytest.warns(ProvenanceWarning, match="extrapolated at 360 nm"):
+        jerlov.kd_spectrum(0.06, 490, 362.0)
+    # 365 nm is the first sound value of M, and rests on it alone.
+    with warnings.catch_warnings():
+        warnings.simplefilter("error", ProvenanceWarning)
+        jerlov.kd_spectrum(0.06, 490, [365.0, 550.0])

{jerlov-0.3.1 → jerlov-0.3.3}/tests/test_backscattering.py

@@ -165,3 +165,23 @@ def test_it_says_nothing_about_a_jerlov_type():
     """The point of DATA.md section 10 has not quietly gone away."""
     with pytest.raises(jerlov.MissingQuantityError):
         jerlov.water("III").bb(532)
+
+
+def test_one_angle_many_wavelengths_gives_one_value_per_wavelength():
+    """A scalar angle used to return the first wavelength's value alone."""
+    nms = [450.0, 532.0, 700.0]
+    vsf = jerlov.pure_water_vsf(124.0, nms)
+    assert np.shape(vsf) == (3,)
+    for value, nm in zip(vsf, nms):
+        assert value == pytest.approx(jerlov.pure_water_vsf(124.0, nm))
+
+
+def test_an_array_of_wavelengths_matches_one_call_per_wavelength():
+    """The water term must be subtracted at each wavelength, not the first."""
+    nms = [450.0, 532.0, 700.0]
+    together = jerlov.bb_from_vsf([0.001] * 3, 124.0, nms)
+    for k, nm in enumerate(nms):
+        alone = jerlov.bb_from_vsf(0.001, 124.0, nm)
+        assert together.bb[k] == pytest.approx(alone.bb)
+        assert together.particulate[k] == pytest.approx(alone.particulate)
+        assert together.water[k] == pytest.approx(alone.water)

{jerlov-0.3.1 → jerlov-0.3.3}/tests/test_packaging.py

@@ -273,3 +273,34 @@ def test_type_hints_reach_the_caller():
         "py.typed exists but is not listed as package data, so it will not "
         "be installed"
     )
+
+
+@source_tree
+def test_every_cited_section_exists():
+    """A reference that leads nowhere is worse than none.
+
+    Error messages and docstrings pointed readers at "README section 10",
+    but the README has no numbered sections; the numbered ones are in
+    DATA.md. Every "DATA.md section N" cited in the code must exist there,
+    and nothing may cite a numbered README section.
+    """
+    numbered = {
+        int(n) for n in re.findall(r"^## (\d+)\. ",
+                                   (ROOT / "DATA.md").read_text(), re.M)
+    }
+    offenders = []
+    for path in sorted(list(ROOT.glob("jerlov/*.py"))
+                       + list(ROOT.glob("jerlov/data/*.csv"))
+                       + list(ROOT.glob("tests/*.py"))
+                       + list(ROOT.glob("examples/*.py"))):
+        text = path.read_text()
+        where = path.relative_to(ROOT)
+        for match in re.finditer(r"README (?:sections? )?\d", text):
+            if path.name != "test_packaging.py":
+                offenders.append(f"{where}: '{match.group(0)}'")
+        for first, last in re.findall(
+                r"DATA\.md sections? (\d+)(?:\s*(?:-|and)\s*(\d+))?", text):
+            for n in {int(first), int(last or first)}:
+                if n not in numbered:
+                    offenders.append(f"{where}: DATA.md section {n}")
+    assert not offenders, f"references to nothing: {offenders}"

{jerlov-0.3.1 → jerlov-0.3.3}/tests/test_reproduces_papers.py

@@ -82,7 +82,7 @@ def test_solonenko_b_follows_from_its_own_table3(water_type):
     """Eq. (8) with the paper's own constants must give the shipped b.
 
     Jerlov I and IA are excluded: their Table 3 entries are not consistent
-    with their b column. See README section 4.
+    with their b column. See DATA.md section 4.
     """
     wl, b, statuses = series("solonenko2015_iop.csv", water_type, "b")
     _, cl, cs, _ = SM_TABLE3[water_type]
@@ -97,7 +97,7 @@ def test_solonenko_b_follows_from_its_own_table3(water_type):
 
 @pytest.mark.parametrize("water_type", ["I", "IA"])
 def test_solonenko_table3_is_inconsistent_for_the_clearest_types(water_type):
-    """Guard the known defect of README section 4, so a fix is noticed."""
+    """Guard the known defect of DATA.md section 4, so a fix is noticed."""
     wl, b, _ = series("solonenko2015_iop.csv", water_type, "b")
     _, cl, cs, _ = SM_TABLE3[water_type]
     predicted = scattering(SOLONENKO2015_SCATTERING, wl, cs, cl)