jerlov 0.3.2__tar.gz → 0.3.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.3.2
+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.2 → jerlov-0.3.3}/jerlov/__init__.py

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

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

@@ -54,7 +54,7 @@ def _frozen(array: np.ndarray) -> np.ndarray:
     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"})
 
@@ -137,6 +137,14 @@ def austin_model() -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     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)
 def b_from_c_ratio() -> tuple[np.ndarray, dict[str, np.ndarray]]:
     """Return ``(wavelengths, {statistic: ratio})`` from Smart (2007) Table 1."""

{jerlov-0.3.2 → 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.2 → 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.
 
@@ -129,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")
@@ -163,7 +174,7 @@ 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=_data.caller_stacklevel(),
             )
@@ -190,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
@@ -201,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)")
@@ -332,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.
 
@@ -342,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=_data.caller_stacklevel(),
         )
-    result = np.interp(query, wl, m) / m1 * (kd - kw1) + np.interp(query, wl, kw)
-    return _like_input(result, at)
+
+    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(),
+        )
+
+    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"):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.3.2
+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.2 → jerlov-0.3.3}/pyproject.toml

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

{jerlov-0.3.2 → 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
 
 
@@ -268,3 +271,54 @@ def test_a_provenance_warning_points_at_the_callers_line(method):
     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.2 → 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.2 → 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)