jerlov 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.3.0
+Version: 0.3.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -298,6 +298,19 @@ questions the first edition of Jerlov settled, and the rest notes.
 `DECISIONS.md` records why the package is shaped the way it is, including the
 alternatives that were rejected and why.
 
+## Contributing, and reporting a wrong number
+
+`CONTRIBUTING.md` sets out what goes in and what it takes: a primary source, a
+script in `tools/` that produces the table, checks inside that script against
+the paper's own equations, an entry in `DATA.md`, and a regression test.
+
+**A coefficient that disagrees with a paper you have is the most useful report
+this package can receive.** `DATA.md` exists because several such
+disagreements turned out to be defects in the literature rather than here.
+Issues: <https://github.com/tishibashi-cpu/jerlov/issues>
+
+`CHANGELOG.md` covers every release.
+
 ## Licence
 
 Apache-2.0. The Williamson & Hollins data are Crown copyright, Dstl, under

{jerlov-0.3.0 → jerlov-0.3.2}/README.md

@@ -273,6 +273,19 @@ questions the first edition of Jerlov settled, and the rest notes.
 `DECISIONS.md` records why the package is shaped the way it is, including the
 alternatives that were rejected and why.
 
+## Contributing, and reporting a wrong number
+
+`CONTRIBUTING.md` sets out what goes in and what it takes: a primary source, a
+script in `tools/` that produces the table, checks inside that script against
+the paper's own equations, an entry in `DATA.md`, and a regression test.
+
+**A coefficient that disagrees with a paper you have is the most useful report
+this package can receive.** `DATA.md` exists because several such
+disagreements turned out to be defects in the literature rather than here.
+Issues: <https://github.com/tishibashi-cpu/jerlov/issues>
+
+`CHANGELOG.md` covers every release.
+
 ## Licence
 
 Apache-2.0. The Williamson & Hollins data are Crown copyright, Dstl, under

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

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

{jerlov-0.3.0 → jerlov-0.3.2}/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,6 +23,36 @@ 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.
 QUESTIONABLE = frozenset({"suspect", "missing", "extrapolated",
@@ -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,7 @@ 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)
@@ -119,5 +149,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.0 → jerlov-0.3.2}/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.0 → jerlov-0.3.2}/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.0 → jerlov-0.3.2}/jerlov/water.py

@@ -75,7 +75,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 +87,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
@@ -163,7 +165,7 @@ class Water:
                 + "; ".join(sorted(hit))
                 + ". See the package README for what is known about them.",
                 ProvenanceWarning,
-                stacklevel=3,
+                stacklevel=_data.caller_stacklevel(),
             )
 
     def a(self, wl):
@@ -368,7 +370,7 @@ def kd_spectrum(kd, wavelength_nm: float, at):
             "Austin & Petzold (1986) reported exactly this problem in "
             "Jerlov's own type I values.",
             ProvenanceWarning,
-            stacklevel=2,
+            stacklevel=_data.caller_stacklevel(),
         )
     result = np.interp(query, wl, m) / m1 * (kd - kw1) + np.interp(query, wl, kw)
     return _like_input(result, at)
@@ -395,5 +397,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.0 → jerlov-0.3.2/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.3.0
+Version: 0.3.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -298,6 +298,19 @@ questions the first edition of Jerlov settled, and the rest notes.
 `DECISIONS.md` records why the package is shaped the way it is, including the
 alternatives that were rejected and why.
 
+## Contributing, and reporting a wrong number
+
+`CONTRIBUTING.md` sets out what goes in and what it takes: a primary source, a
+script in `tools/` that produces the table, checks inside that script against
+the paper's own equations, an entry in `DATA.md`, and a regression test.
+
+**A coefficient that disagrees with a paper you have is the most useful report
+this package can receive.** `DATA.md` exists because several such
+disagreements turned out to be defects in the literature rather than here.
+Issues: <https://github.com/tishibashi-cpu/jerlov/issues>
+
+`CHANGELOG.md` covers every release.
+
 ## Licence
 
 Apache-2.0. The Williamson & Hollins data are Crown copyright, Dstl, under

{jerlov-0.3.0 → jerlov-0.3.2}/jerlov.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ jerlov/__init__.py
 jerlov/_data.py
 jerlov/backscattering.py
 jerlov/colour.py
+jerlov/py.typed
 jerlov/scene.py
 jerlov/shortwave.py
 jerlov/sources.py
@@ -35,6 +36,7 @@ tests/test_backscattering.py
 tests/test_colour.py
 tests/test_depth.py
 tests/test_packaging.py
+tests/test_quoted_figures.py
 tests/test_reproduces_papers.py
 tests/test_scene.py
 tests/test_shortwave.py

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jerlov"
-version = "0.3.0"
+version = "0.3.2"
 description = "Inherent optical properties of Jerlov water types, with provenance"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,3 +30,4 @@ include = ["jerlov*"]
 
 [tool.setuptools.package-data]
 "jerlov.data" = ["*.csv"]
+"jerlov" = ["py.typed"]

{jerlov-0.3.0 → jerlov-0.3.2}/tests/test_api.py

@@ -213,3 +213,58 @@ 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)

{jerlov-0.3.0 → jerlov-0.3.2}/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.0 → jerlov-0.3.2}/tests/test_packaging.py

@@ -235,3 +235,41 @@ def test_nothing_reaches_for_a_numpy_2_only_name():
         "use jerlov._data.trapezoid instead, which resolves whichever name "
         f"the installed NumPy has: {offenders}"
     )
+
+
+@source_tree
+def test_the_files_a_reviewer_looks_for_are_present():
+    """JOSS checks for community guidelines; the rest are cheap to keep."""
+    for name in ("README.md", "LICENSE", "NOTICE", "CITATION.cff",
+                 "CONTRIBUTING.md", "CODE_OF_CONDUCT.md", "CHANGELOG.md",
+                 "DATA.md", "DECISIONS.md", ".zenodo.json"):
+        assert (ROOT / name).exists(), f"{name} is missing"
+
+
+@source_tree
+def test_contributing_says_how_to_report_and_how_to_contribute():
+    """The three things JOSS asks a contributing guide to cover."""
+    text = (ROOT / "CONTRIBUTING.md").read_text().lower()
+    assert "issues" in text, "no way to report a problem is given"
+    assert "pip install -e" in text, "no way to set the package up is given"
+    assert "pull request" in text, "no way to contribute a change is given"
+
+
+@source_tree
+def test_the_changelog_covers_the_current_version():
+    """A release whose changes are only in a GitHub Release is invisible to
+    anyone who installed from PyPI."""
+    changelog = (ROOT / "CHANGELOG.md").read_text()
+    assert f"## {jerlov.__version__}" in changelog, (
+        f"CHANGELOG.md has no entry for {jerlov.__version__}"
+    )
+
+
+@source_tree
+def test_type_hints_reach_the_caller():
+    """Annotations are useless to a user without the marker file."""
+    assert (ROOT / "jerlov" / "py.typed").exists()
+    assert '"jerlov" = ["py.typed"]' in (ROOT / "pyproject.toml").read_text(), (
+        "py.typed exists but is not listed as package data, so it will not "
+        "be installed"
+    )

jerlov-0.3.2/tests/test_quoted_figures.py

@@ -0,0 +1,192 @@
+"""The numbers the prose quotes must still be the numbers the code gives.
+
+README.md, DATA.md and the examples all state figures: a factor of 3.8 here, 46
+percent there. Those were computed once. Nothing has been stopping them from
+drifting away from what the package now returns, and a reader has no way to
+tell when they have.
+
+Each test below recomputes one quoted figure. When one fails, the prose is
+what needs fixing, not the test — unless the change to the code was a mistake,
+in which case it is the other way round and the test has done its job.
+"""
+
+from __future__ import annotations
+
+import math
+import pathlib
+import re
+import warnings
+
+import numpy as np
+import pytest
+
+import jerlov
+from jerlov import _data
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+source_tree = pytest.mark.skipif(
+    not (ROOT / "README.md").exists(),
+    reason="not running from a source tree",
+)
+
+
+def quiet():
+    return warnings.catch_warnings()
+
+
+# -- the sources disagree, and by how much --------------------------------
+
+
+def test_scattering_at_510nm_differs_by_the_stated_factor():
+    """README and sources_disagree.py both say 3.8 for Jerlov III."""
+    with quiet():
+        warnings.simplefilter("ignore")
+        measured = float(jerlov.water("III").b(510))
+        inverted = float(jerlov.water("III", source="solonenko2015").b(510))
+    assert inverted / measured == pytest.approx(3.8, abs=0.05)
+
+
+def test_the_disagreement_does_not_run_one_way():
+    """sources_disagree.py claims Jerlov IB goes the other direction."""
+    with quiet():
+        warnings.simplefilter("ignore")
+        measured = float(jerlov.water("IB").b(510))
+        inverted = float(jerlov.water("IB", source="solonenko2015").b(510))
+    assert inverted / measured < 0.5
+
+
+def test_the_three_routes_span_the_stated_factor_at_532nm():
+    """DATA.md section 17 says 5.1 for Jerlov III."""
+    chlorophyll_model = 1.8998          # Abd El-Mottaleb et al. (2024)
+    with quiet():
+        warnings.simplefilter("ignore")
+        measured = float(jerlov.water("III").c(532))
+        inverted = float(jerlov.water("III", source="solonenko2015").c(532))
+    assert measured == pytest.approx(0.371, abs=0.001)
+    assert inverted == pytest.approx(1.092, abs=0.001)
+    assert chlorophyll_model / measured == pytest.approx(5.1, abs=0.05)
+
+
+# -- the scattering model constants ---------------------------------------
+
+
+def test_the_small_particle_coefficients_differ_by_the_stated_amount():
+    """DATA.md section 6: 1.513 is 31 percent larger than 1.151302."""
+    haltrin = jerlov.get_source("williamson2022").scattering.small_coeff
+    solonenko = jerlov.get_source("solonenko2015").scattering.small_coeff
+    assert haltrin == pytest.approx(1.151302)
+    assert solonenko == pytest.approx(1.513)
+    assert solonenko / haltrin - 1 == pytest.approx(0.31, abs=0.005)
+
+
+# -- shortwave penetration ------------------------------------------------
+
+
+def test_the_shortwave_fit_misses_its_source_by_the_stated_amount():
+    """README, DATA.md section 14 and solar_heating.py all say 46 percent."""
+    rows = _data._rows("jerlov1968_total_irradiance.csv")
+    worst = 0.0
+    for row in rows:
+        if row["water_type"] not in ("I", "IA", "IB", "II", "III"):
+            continue
+        if not row["percent_of_surface"]:
+            continue
+        depth = float(row["depth_m"])
+        if depth == 0 or depth > 100:
+            continue
+        want = float(row["percent_of_surface"]) / 100
+        got = jerlov.solar_fraction(row["water_type"], depth)
+        worst = max(worst, abs(got - want) / want)
+    assert worst == pytest.approx(0.46, abs=0.01)
+
+
+def test_the_published_R_values_are_what_the_docs_print():
+    published = {"I": 0.58, "IA": 0.62, "IB": 0.67, "II": 0.77, "III": 0.78}
+    for water_type, value in published.items():
+        assert jerlov.shortwave_parameters(water_type).R == pytest.approx(value)
+
+
+# -- backscattering -------------------------------------------------------
+
+
+def test_the_worst_chi_p_spread_is_the_stated_figure():
+    """README and DATA.md section 18 both say 34.8 percent at 170 degrees."""
+    with pytest.warns(jerlov.AngleWarning, match="34.8"):
+        result = jerlov.bb_from_vsf(0.002, 170.0, 532.0)
+    assert result.quoted_error_percent == pytest.approx(34.8)
+    middle = [jerlov.bb_from_vsf(0.002, a, 532.0).quoted_error_percent
+              for a in (100.0, 120.0, 140.0, 160.0)]
+    assert max(middle) <= 6.5, "the 3-6 percent claim no longer holds"
+
+
+def test_chi_w_and_chi_p_cross_where_the_docs_say():
+    """DATA.md section 18 quotes 116.9 degrees against the paper's ~118."""
+    r = (1 - jerlov.backscattering.DEPOLARISATION_RATIO) / (
+        1 + jerlov.backscattering.DEPOLARISATION_RATIO)
+    angles = np.linspace(90.0, 170.0, 80001)
+    gap = [(1 + r / 3) / (1 + r * math.cos(math.radians(a)) ** 2)
+           - jerlov.particulate_chi(a) for a in angles]
+    crossing = float(angles[int(np.argmin(np.abs(gap)))])
+    assert crossing == pytest.approx(116.9, abs=0.1)
+
+
+# -- the example that argues against defaults -----------------------------
+
+
+def test_the_guess_overstates_contrast_by_the_stated_amount():
+    """from_one_measurement.py computes 65 percent and the prose repeats it.
+
+    The example computes this rather than hard-coding it, so this test is
+    what stops the *prose* around it from going stale.
+    """
+    wl = np.arange(420.0, 681.0, 20.0)
+    a = 0.02 + 0.35 * np.exp(-(wl - 420.0) / 90.0) + 0.30 * (wl > 600)
+    b = 0.45 * (550.0 / wl) ** 0.8
+    water = jerlov.Water.from_measurements(wl, a=a, b=b)
+
+    measured = jerlov.bb_from_vsf(0.0021, 140.0, 532.0, salinity_psu=35.0)
+    ratio = measured.bb / water.b(532.0)
+    assert ratio == pytest.approx(0.033, abs=0.001)
+
+    surface = np.interp(wl, *jerlov.d65(), left=0.0, right=0.0)
+    with quiet():
+        warnings.simplefilter("ignore")
+        scene = jerlov.Scene.at_depth(
+            water, 8.0, surface, wl,
+            kd=jerlov.water("II", source="austin1986"))
+        white = scene.downwelling / np.pi
+        contrasts = {}
+        for label, value in (("guess", 0.015), ("measured", ratio)):
+            b_inf = jerlov.veiling_radiance_estimate(
+                water, scene.downwelling, wl, backscatter_ratio=value)
+            observed = scene.observe(np.full_like(wl, 0.5), 5.0,
+                                     veiling_radiance=b_inf)
+            contrasts[label] = float(
+                np.mean(np.abs(observed.contrast(0.1 * white))))
+    overstatement = contrasts["guess"] / contrasts["measured"] - 1
+    assert overstatement == pytest.approx(0.65, abs=0.03)
+
+
+# -- the prose and the code are checked against each other ----------------
+
+
+@source_tree
+def test_the_readme_quotes_a_transmittance_the_package_produces():
+    """`solar_fraction("IB", 10.0)` appears in the README with its answer."""
+    readme = (ROOT / "README.md").read_text()
+    match = re.search(
+        r'solar_fraction\("IB", 10\.0\).*?#\s*([\d.]+)', readme)
+    assert match, "the README no longer shows that call with its result"
+    assert jerlov.solar_fraction("IB", 10.0) == pytest.approx(
+        float(match.group(1)), abs=0.0005)
+
+
+@source_tree
+def test_the_readme_quotes_a_chi_p_the_package_produces():
+    readme = (ROOT / "README.md").read_text()
+    match = re.search(r"r\.chi_p, r\.quoted_error_percent\s*#\s*([\d.]+),\s*([\d.]+)",
+                      readme)
+    assert match, "the README no longer shows chi_p with its value"
+    result = jerlov.bb_from_vsf(0.0021, 140.0, 532.0)
+    assert result.chi_p == pytest.approx(float(match.group(1)))
+    assert result.quoted_error_percent == pytest.approx(float(match.group(2)))