jerlov 0.3.2__tar.gz → 0.4.0__tar.gz

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

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

{jerlov-0.3.2 → jerlov-0.4.0}/jerlov/__init__.py

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

{jerlov-0.3.2 → jerlov-0.4.0}/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.4.0}/jerlov/colour.py

@@ -136,6 +136,16 @@ def integrate_response(spectrum, wavelengths, response, response_wavelengths,
     -------
     Array of shape ``(k,)``: the integral of spectrum times each channel over
     wavelength, in the units of the spectrum times nm.
+
+    Notes
+    -----
+    The integral is taken on the spectrum's own wavelengths, with the
+    response interpolated onto them. Sample at 5 nm or finer where you can:
+    on coarser grids the narrow peaks of a response, or of the spectrum,
+    fall between samples, and the error grows quickly. Interpolating the
+    spectrum onto the response's grid instead is no cure, since it only
+    trades this error for one in the shape assumed between the spectrum's
+    samples.
     """
     spectrum = np.asarray(spectrum, dtype=float)
     wavelengths = np.asarray(wavelengths, dtype=float)
@@ -149,6 +159,12 @@ def integrate_response(spectrum, wavelengths, response, response_wavelengths,
         raise ValueError("response must be aligned with response_wavelengths")
     if wavelengths.size < 2:
         raise ValueError("at least two wavelengths are needed to integrate")
+    # Descending wavelengths make the integral negative and the coverage
+    # zero, so a reversed spectrum came out as a negative colour.
+    for grid, label in ((wavelengths, "wavelengths"),
+                        (response_wavelengths, "response_wavelengths")):
+        if np.any(np.diff(grid) <= 0):
+            raise ValueError(f"{label} must be strictly ascending")
 
     covered = [_coverage(wavelengths, response_wavelengths, response[:, k])
                for k in range(response.shape[1])]

{jerlov-0.3.2 → jerlov-0.4.0}/jerlov/scene.py

@@ -120,8 +120,27 @@ class Observation:
     def contrast(self, background_radiance) -> np.ndarray:
         """Apparent contrast against a background seen through the same path.
 
-        The path radiance is common to target and background and cancels, so
-        this is the inherent contrast reduced by the transmittance.
+        ``background_radiance`` is the radiance leaving the background, on
+        the scene's wavelengths and in the unit of the target radiance
+        (``reflectance * downwelling / pi``), not a reflectance.
+
+        With ``L_t`` and ``L_b`` the radiances leaving target and background,
+        ``t`` the transmittance and ``B`` the veiling radiance at infinity::
+
+            C(r) = (L_t - L_b) t / (L_b t + B (1 - t))
+                 = C_0 * L_b t / (L_b t + B (1 - t)),   C_0 = (L_t - L_b) / L_b
+
+        The path radiance is common to both and cancels from the numerator,
+        but not from the denominator, so the loss of contrast is the veiling
+        light's doing rather than the transmittance's:
+
+        - With no veiling radiance (``B = 0``) the contrast is not reduced at
+          all; target and background are dimmed by the same factor.
+        - Against a background that is the water itself (``L_b = B``, a
+          horizontal line of sight into open water) it is ``C_0 * t``, the
+          classic result.
+        - It falls faster than that against a background darker than ``B``,
+          and more slowly against a brighter one.
         """
         background = _as_array(background_radiance)
         observed_background = (

{jerlov-0.3.2 → jerlov-0.4.0}/jerlov/shortwave.py

@@ -63,7 +63,8 @@ def _rows():
     return _data._rows("paulson1977_shortwave.csv")
 
 
-def shortwave_parameters(water_type: str) -> ShortwaveParameters:
+def shortwave_parameters(water_type: str, *,
+                         include_non_types: bool = False) -> ShortwaveParameters:
     """Paulson & Simpson parameters for a Jerlov water type.
 
     Only the five oceanic types I, IA, IB, II and III were fitted; the paper
@@ -72,10 +73,23 @@ def shortwave_parameters(water_type: str) -> ShortwaveParameters:
     ``water_type="I_upper50"`` selects the paper's alternative fit for type I
     over the upper 50 m, which it gives because ``ln I`` against depth changes
     slope below that. The plain ``"I"`` row is the 100 m fit.
+
+    Table 2 also prints three rows that are not water types: the authors'
+    composite observations, their Run 1, and a Kraus (1972) value from Crater
+    Lake (keys ``"composite_observations"``, ``"run_1"`` and
+    ``"kraus_1972_very_clear"``). They are refused unless
+    ``include_non_types=True`` is passed, so that one cannot be mistaken for
+    a Jerlov type; their ``water_type`` is empty. See DATA.md section 14.
     """
     rows = _rows()
     for row in rows:
         if row["key"] == water_type:
+            if row["status"] == "not_a_water_type" and not include_non_types:
+                raise KeyError(
+                    f"{water_type!r} is a row of Paulson & Simpson (1977) "
+                    f"Table 2 but not a Jerlov water type: {row['note']}. "
+                    "Pass include_non_types=True to get it anyway."
+                )
             return ShortwaveParameters(
                 key=row["key"],
                 water_type=row["water_type"],

{jerlov-0.3.2 → jerlov-0.4.0}/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.4.0}/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)")
@@ -314,6 +325,11 @@ def water_type_at_depth(surface_water_type: str, depth_m: float) -> str | None:
     any particular place or season. The paper says so explicitly, and gives
     per-cell cruise and month counts for anyone who needs to judge that.
     """
+    depth_m = float(depth_m)
+    if not np.isfinite(depth_m):
+        # NaN fails every comparison below, so it would otherwise fall
+        # through to "no statement" and look like a deliberate answer.
+        raise ValueError(f"depth_m must be a finite number, not {depth_m!r}")
     if depth_m < 0:
         raise ValueError("depth_m cannot be negative")
     rows = _data._rows("williamson2023_depth.csv")
@@ -323,15 +339,23 @@ def water_type_at_depth(surface_water_type: str, depth_m: float) -> str | None:
             f"unknown water type {surface_water_type!r} "
             f"(known: {', '.join(sorted(known))})"
         )
-    for row in rows:
-        if row["surface_water_type"] != surface_water_type:
-            continue
-        if float(row["depth_min_m"]) <= depth_m < float(row["depth_max_m"]):
+    own = [r for r in rows if r["surface_water_type"] == surface_water_type]
+    deepest = max(float(r["depth_max_m"]) for r in own)
+    for row in own:
+        top, bottom = float(row["depth_min_m"]), float(row["depth_max_m"])
+        # A boundary belongs to the layer below it, except at the bottom of
+        # the deepest layer, which has no layer below: 200 m is still
+        # inside the paper's profile.
+        if top <= depth_m < bottom or depth_m == bottom == deepest:
             return row["water_type"] or None
     # Beyond 200 m the paper makes no statement at all.
     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 +366,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.4.0/jerlov.egg-info}/PKG-INFO

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

{jerlov-0.3.2 → jerlov-0.4.0}/pyproject.toml

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

{jerlov-0.3.2 → jerlov-0.4.0}/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.4.0}/tests/test_colour.py

@@ -222,3 +222,13 @@ def test_water_reddens_nothing_and_blues_everything():
     # At the surface the target is neutral; underwater it is not.
     assert np.allclose(surface, surface[0], atol=1e-6)
     assert underwater[2] > underwater[0], "blue should survive better than red"
+
+
+def test_wavelengths_must_ascend():
+    """A reversed spectrum used to integrate to a negative XYZ."""
+    wl = np.arange(360.0, 831.0, 5.0)
+    flat = np.ones_like(wl)
+    with pytest.raises(ValueError, match="strictly ascending"):
+        jerlov.spectrum_to_xyz(flat[::-1], wl[::-1])
+    with pytest.raises(ValueError, match="strictly ascending"):
+        jerlov.integrate_response(flat, wl, flat, wl[::-1])

{jerlov-0.3.2 → jerlov-0.4.0}/tests/test_depth.py

@@ -48,6 +48,20 @@ def test_boundaries_belong_to_the_layer_below():
     assert jerlov.water_type_at_depth("I", 19.999) == "I"  # end of 10-20
 
 
+def test_the_bottom_of_the_profile_is_inside_it():
+    """200 m closes the deepest layer; there is no layer below to own it."""
+    assert jerlov.water_type_at_depth("I", 200.0) == "IB"
+    assert jerlov.water_type_at_depth("I", 199.9) == "IB"
+    assert jerlov.water_type_at_depth("I", 200.1) is None
+
+
+def test_a_depth_that_is_not_a_number_is_refused():
+    """NaN used to fall through to None, which reads as the paper's answer."""
+    for bad in (float("nan"), float("inf")):
+        with pytest.raises(ValueError, match="finite"):
+            jerlov.water_type_at_depth("I", bad)
+
+
 def test_unknown_type_names_the_alternatives():
     with pytest.raises(KeyError, match="known:"):
         jerlov.water_type_at_depth("IV", 10.0)

{jerlov-0.3.2 → jerlov-0.4.0}/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.4.0}/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)

{jerlov-0.3.2 → jerlov-0.4.0}/tests/test_scene.py

@@ -89,6 +89,34 @@ def test_contrast_decays_with_distance():
     assert contrasts[-1] < 0.01
 
 
+def test_contrast_follows_the_formula_in_its_docstring():
+    """The docstring used to say the inherent contrast is simply reduced by
+    the transmittance. That holds only against a background as bright as the
+    water's own veiling light."""
+    s = scene()
+    target = flat(0.8) * s.downwelling / np.pi
+    background = flat(0.1) * s.downwelling / np.pi
+    inherent = (target - background) / background
+    veil = flat(0.02)
+    for r in (0.5, 2.0, 8.0):
+        t = s.transmittance(r)
+        obs = s.observe(flat(0.8), r, veiling_radiance=veil)
+        expected = inherent * background * t / (background * t + veil * (1 - t))
+        assert np.allclose(obs.contrast(background), expected)
+        # No veiling light: dimming target and background alike leaves the
+        # contrast where it was.
+        bare = s.observe(flat(0.8), r, veiling_radiance=flat(0.0))
+        assert np.allclose(bare.contrast(background), inherent)
+        # A background that is the water itself gives the classic C_0 * t.
+        water = s.observe(flat(0.8), r, veiling_radiance=background)
+        assert np.allclose(water.contrast(background), inherent * t)
+        # Darker than the water, it falls faster than that; brighter, slower.
+        assert np.all(np.abs(s.observe(flat(0.8), r, veiling_radiance=2 * background)
+                             .contrast(background)) < np.abs(inherent * t))
+        assert np.all(np.abs(s.observe(flat(0.8), r, veiling_radiance=background / 2)
+                             .contrast(background)) > np.abs(inherent * t))
+
+
 def test_turbid_water_veils_faster_than_clear():
     clear = scene("IB").observe(flat(), 3.0, veiling_radiance=flat(0.01))
     turbid = scene("5C").observe(flat(), 3.0, veiling_radiance=flat(0.01))

{jerlov-0.3.2 → jerlov-0.4.0}/tests/test_shortwave.py

@@ -96,9 +96,15 @@ def test_the_alternative_type_I_fit_is_reachable():
 
 
 def test_the_rows_that_are_not_water_types_are_not_offered():
+    """They used to come back like any type, so `solar_fraction("run_1", z)`
+    gave a Jerlov-looking answer for one cruise's run."""
     for key in ("composite_observations", "run_1", "kraus_1972_very_clear"):
-        p = jerlov.shortwave_parameters(key)
-        assert p.water_type == ""      # reachable by key, but not a type
+        with pytest.raises(KeyError, match="not a Jerlov water type"):
+            jerlov.shortwave_parameters(key)
+        with pytest.raises(KeyError, match="not a Jerlov water type"):
+            jerlov.solar_fraction(key, 10.0)
+        p = jerlov.shortwave_parameters(key, include_non_types=True)
+        assert p.water_type == ""      # reachable when asked for, not a type
         assert "Not a Jerlov type" in p.note