jerlov 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.2.1
+Version: 0.3.0
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -203,6 +203,25 @@ Two silent errors are checked rather than assumed:
 - **Gamut.** Underwater colours often fall outside sRGB. Clipping changes
   them, so `GamutWarning` says so.
 
+## If you measured backscattering
+
+`Water.bb` refuses to guess a backscattering ratio. If you have an instrument
+you do not have to:
+
+```python
+r = jerlov.bb_from_vsf(beta=0.0021, angle_deg=140, wavelength_nm=532)
+r.bb, r.particulate, r.water     # 1/m
+r.chi_p, r.quoted_error_percent  # 1.18, 3.5
+```
+
+Boss & Pegau (2001). The pure sea water terms are analytic and are checked
+against the definition of bb rather than transcribed; only the particle
+conversion is tabulated. Angles outside 90-170 degrees are refused, and 170
+warns: its quoted spread is **34.8 percent** against 3-6 in the middle.
+
+This gives the bb of the water your instrument was in. It still gives no bb
+for a Jerlov water type, because nothing does.
+
 ## The type changes with depth
 
 The classification is defined on the top 10 m, but clarity does not stay put.
@@ -257,21 +276,22 @@ rather than substituting a neighbour.
 ## Examples
 
 ```
-python examples/sources_disagree.py
-python examples/synthetic_underwater_images.py
+python examples/sources_disagree.py            why the source is an argument
+python examples/from_one_measurement.py        from an instrument reading
+python examples/synthetic_underwater_images.py appearance at range and depth
+python examples/solar_heating.py               for ocean circulation models
+python examples/what_an_eye_sees.py            any spectral sensitivity
 ```
 
-The first shows why the source is an argument: at 510 nm the scattering
-coefficient of Jerlov III differs by a factor of 3.8 between the two published
-sets. The second synthesises how reflectance patches appear at range and
-depth, white-balanced two ways, and ends with a list of everything it assumed.
-
-Both are run by CI, so an example that has stopped working is a failed build.
+Five scripts, each aimed at a different reader; `examples/README.md` says
+which to start with. CI runs all of them on every push, so an example that has
+stopped working is a failed build. Every one ends with the assumptions it
+made.
 
 ## Provenance and design
 
 `DATA.md` records, for every shipped table, where it came from, what was
-verified, and what is known to be wrong with it. Seventeen entries are
+verified, and what is known to be wrong with it. Eighteen entries are
 documented there: eight confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 

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

@@ -178,6 +178,25 @@ Two silent errors are checked rather than assumed:
 - **Gamut.** Underwater colours often fall outside sRGB. Clipping changes
   them, so `GamutWarning` says so.
 
+## If you measured backscattering
+
+`Water.bb` refuses to guess a backscattering ratio. If you have an instrument
+you do not have to:
+
+```python
+r = jerlov.bb_from_vsf(beta=0.0021, angle_deg=140, wavelength_nm=532)
+r.bb, r.particulate, r.water     # 1/m
+r.chi_p, r.quoted_error_percent  # 1.18, 3.5
+```
+
+Boss & Pegau (2001). The pure sea water terms are analytic and are checked
+against the definition of bb rather than transcribed; only the particle
+conversion is tabulated. Angles outside 90-170 degrees are refused, and 170
+warns: its quoted spread is **34.8 percent** against 3-6 in the middle.
+
+This gives the bb of the water your instrument was in. It still gives no bb
+for a Jerlov water type, because nothing does.
+
 ## The type changes with depth
 
 The classification is defined on the top 10 m, but clarity does not stay put.
@@ -232,21 +251,22 @@ rather than substituting a neighbour.
 ## Examples
 
 ```
-python examples/sources_disagree.py
-python examples/synthetic_underwater_images.py
+python examples/sources_disagree.py            why the source is an argument
+python examples/from_one_measurement.py        from an instrument reading
+python examples/synthetic_underwater_images.py appearance at range and depth
+python examples/solar_heating.py               for ocean circulation models
+python examples/what_an_eye_sees.py            any spectral sensitivity
 ```
 
-The first shows why the source is an argument: at 510 nm the scattering
-coefficient of Jerlov III differs by a factor of 3.8 between the two published
-sets. The second synthesises how reflectance patches appear at range and
-depth, white-balanced two ways, and ends with a list of everything it assumed.
-
-Both are run by CI, so an example that has stopped working is a failed build.
+Five scripts, each aimed at a different reader; `examples/README.md` says
+which to start with. CI runs all of them on every push, so an example that has
+stopped working is a failed build. Every one ends with the assumptions it
+made.
 
 ## Provenance and design
 
 `DATA.md` records, for every shipped table, where it came from, what was
-verified, and what is known to be wrong with it. Seventeen entries are
+verified, and what is known to be wrong with it. Eighteen entries are
 documented there: eight confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 

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

@@ -4,6 +4,14 @@ Every coefficient carries its source, and values that a published table got
 wrong are flagged rather than quietly repaired.
 """
 
+from .backscattering import (
+    AngleWarning,
+    Backscattering,
+    bb_from_vsf,
+    particulate_chi,
+    pure_water_backscattering,
+    pure_water_vsf,
+)
 from .colour import (
     CoverageWarning,
     GamutWarning,
@@ -57,6 +65,12 @@ __all__ = [
     "water_type_at_depth",
     "shortwave_parameters",
     "solar_fraction",
+    "bb_from_vsf",
+    "particulate_chi",
+    "pure_water_vsf",
+    "pure_water_backscattering",
+    "Backscattering",
+    "AngleWarning",
     "ShortwaveParameters",
     "kd_spectrum",
     "b_from_c",
@@ -64,4 +78,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{jerlov-0.2.1 → jerlov-0.3.0}/jerlov/_data.py

@@ -13,6 +13,16 @@ 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
+#: that anything integrating over a grid finds it: putting it in colour.py
+#: meant two later modules reached for np.trapezoid and broke the oldest
+#: supported NumPy.
+trapezoid = getattr(np, "trapezoid", None) or np.trapz
+
 #: 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",

jerlov-0.3.0/jerlov/backscattering.py

@@ -0,0 +1,215 @@
+"""From a backscattering sensor's reading to the backscattering coefficient.
+
+`Water.bb` refuses to guess a backscattering ratio, because the Jerlov
+classification does not determine one. If you have an instrument, you do not
+have to guess: a HydroScat, an ECO-BB or a VSF meter measures the volume
+scattering function at one angle in the backward hemisphere, and there is a
+published relation from that to bb.
+
+    bb = 2 pi chi_p(theta) [beta(theta) - beta_w(theta)] + bb_w
+
+Boss & Pegau (2001) Eq. (10). The water terms are analytic, from Morel's
+formula for the volume scattering function of pure sea water; only chi_p is
+tabulated, from 41 measured scattering functions.
+
+This does not tell you the bb of a Jerlov water type. Nothing does. It tells
+you the bb of the water your instrument was in.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+
+from . import _data
+from .water import _like_input
+
+CITATION = (
+    "Boss, E. and Pegau, W. S. (2001), 'Relationship of light scattering at "
+    "an angle in the backward direction to the backscattering coefficient', "
+    "Appl. Opt. 40, 5503-5507"
+)
+DOI = "10.1364/AO.40.005503"
+
+#: Depolarisation ratio of pure sea water. Morel gives a range of 0.07 to
+#: 0.11 and suggests 0.09, which is what Boss & Pegau use.
+DEPOLARISATION_RATIO = 0.09
+
+#: The angles the tabulation covers. Outside this the relation is not defined.
+MIN_ANGLE_DEG, MAX_ANGLE_DEG = 90.0, 170.0
+
+#: Above this the tabulated error exceeds 10 percent and a warning is raised.
+_ERROR_WARN_PERCENT = 10.0
+
+
+class AngleWarning(UserWarning):
+    """The conversion is poorly constrained at the requested angle.
+
+    The shape of the volume scattering function varies most steeply near 90
+    and 180 degrees, so a single-angle measurement there pins bb least well.
+    Both Boss & Pegau (2001) and Maffione & Dana (1997) recommend 110 to 160
+    degrees.
+    """
+
+
+def _ratio() -> float:
+    return (1 - DEPOLARISATION_RATIO) / (1 + DEPOLARISATION_RATIO)
+
+
+def pure_water_vsf(angle_deg, wavelength_nm, salinity_psu: float = 37.0):
+    """Volume scattering function of pure sea water, 1/(m sr).
+
+    Morel's formula as given by Boss & Pegau Eqs. (4) and (5)::
+
+        A(lambda, S) = 1.38 (lambda / 500 nm)^-4.32 (1 + 0.3 S / 37) 1e-4
+        beta_w(theta) = A [1 + cos^2(theta) (1 - delta) / (1 + delta)]
+
+    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))
+    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)
+
+
+def pure_water_backscattering(wavelength_nm, salinity_psu: float = 37.0):
+    """``bb_w``, the backscattering coefficient of pure sea water, 1/m.
+
+    Obtained by integrating :func:`pure_water_vsf` over the backward
+    hemisphere, which for this angular shape is analytic.
+    """
+    r = _ratio()
+    amplitude = (1.38 * (np.asarray(wavelength_nm, dtype=float) / 500.0) ** -4.32
+                 * (1 + 0.3 * salinity_psu / 37.0) * 1e-4)
+    # integral of (1 + r cos^2) sin over 90..180 degrees is 1 + r/3
+    out = 2.0 * math.pi * amplitude * (1 + r / 3.0)
+    return _like_input(np.atleast_1d(out), wavelength_nm)
+
+
+def _chi_table():
+    rows = [r for r in _data._rows("boss2001_chi.csv")
+            if r["source"] == "boss2001"]
+    angles = np.array([float(r["angle_deg"]) for r in rows])
+    order = np.argsort(angles)
+    return (angles[order],
+            np.array([float(rows[i]["chi"]) for i in order]),
+            np.array([float(rows[i]["percent_error"]) for i in order]))
+
+
+def particulate_chi(angle_deg):
+    """``chi_p`` at one angle, interpolated within Boss & Pegau Table 1.
+
+    Refuses outside 90 to 170 degrees, the range their measurements cover.
+    """
+    angle = float(angle_deg)
+    if not MIN_ANGLE_DEG <= angle <= MAX_ANGLE_DEG:
+        raise ValueError(
+            f"chi_p is tabulated from {MIN_ANGLE_DEG:g} to {MAX_ANGLE_DEG:g} "
+            f"degrees and {angle:g} is outside that. Boss & Pegau made no "
+            "measurement beyond 170 degrees, and this package does not "
+            "extrapolate."
+        )
+    angles, values, _ = _chi_table()
+    return float(np.interp(angle, angles, values))
+
+
+def _quoted_error(angle_deg: float) -> float:
+    angles, _, errors = _chi_table()
+    return float(np.interp(angle_deg, angles, errors))
+
+
+@dataclass(frozen=True)
+class Backscattering:
+    """``bb`` recovered from a single-angle measurement."""
+
+    bb: float | np.ndarray
+    """Total backscattering coefficient, 1/m."""
+    particulate: float | np.ndarray
+    """The particle contribution, ``bb - bb_w``."""
+    water: float | np.ndarray
+    """``bb_w``, from Morel's formula rather than from your instrument."""
+    angle_deg: float
+    chi_p: float
+    quoted_error_percent: float
+    """Boss & Pegau's own spread for chi_p at this angle. Not a total error."""
+
+    def __repr__(self) -> str:  # pragma: no cover - convenience only
+        return (f"<Backscattering bb={np.mean(self.bb):.5f} 1/m at "
+                f"{self.angle_deg:g} deg, chi_p={self.chi_p:.3f} "
+                f"+-{self.quoted_error_percent:.1f}%>")
+
+
+def bb_from_vsf(beta, angle_deg: float, wavelength_nm, *,
+                salinity_psu: float = 37.0) -> Backscattering:
+    """Convert a measured volume scattering function to ``bb``.
+
+    Parameters
+    ----------
+    beta:
+        The measured volume scattering function at ``angle_deg``, in
+        1/(m sr). This is what the instrument reports once calibrated; it
+        includes scattering by the water itself.
+    angle_deg:
+        The instrument's nominal scattering angle. 90 to 170 degrees.
+    wavelength_nm, salinity_psu:
+        Needed for the pure sea water terms, which are subtracted and then
+        added back as ``bb_w``.
+
+    Notes
+    -----
+    Boss & Pegau's water-removal route, their Eq. (10). Removing the water
+    first matters because chi differs between water and particles everywhere
+    except near 118 degrees, where the two curves cross; that is why
+    instruments cluster near 120.
+
+    The quoted error on the result is the spread of chi_p alone. The amplitude
+    of the water term carries a further 15 percent, and your instrument's own
+    calibration is on top of both.
+    """
+    angle = float(angle_deg)
+    chi_p = particulate_chi(angle)
+    error = _quoted_error(angle)
+    if error > _ERROR_WARN_PERCENT:
+        warnings.warn(
+            f"chi_p at {angle:g} degrees carries a quoted spread of "
+            f"{error:.1f}%, against 3-6% between 100 and 160 degrees. The "
+            "scattering function varies steeply here and a single-angle "
+            "measurement pins bb poorly.",
+            AngleWarning,
+            stacklevel=2,
+        )
+
+    scalar = np.ndim(beta) == 0 and np.ndim(wavelength_nm) == 0
+    beta = np.atleast_1d(np.asarray(beta, dtype=float))
+    if np.any(beta < 0):
+        raise ValueError("a volume scattering function cannot be negative")
+    beta_w = np.atleast_1d(pure_water_vsf(angle, wavelength_nm, salinity_psu))
+    bb_w = np.atleast_1d(pure_water_backscattering(wavelength_nm, salinity_psu))
+
+    particulate = 2.0 * math.pi * chi_p * (beta - beta_w)
+    if np.any(particulate < 0):
+        warnings.warn(
+            "the measured scattering is below that of pure sea water alone, "
+            "so the particle contribution came out negative. Check the "
+            "calibration, the wavelength and the salinity.",
+            AngleWarning,
+            stacklevel=2,
+        )
+
+    def shape(values):
+        values = np.atleast_1d(values)
+        return float(values[0]) if scalar else values
+
+    return Backscattering(
+        bb=shape(particulate + bb_w),
+        particulate=shape(particulate),
+        water=shape(np.broadcast_to(bb_w, particulate.shape)),
+        angle_deg=angle,
+        chi_p=chi_p,
+        quoted_error_percent=error,
+    )

{jerlov-0.2.1 → jerlov-0.3.0}/jerlov/colour.py

@@ -22,9 +22,8 @@ import numpy as np
 
 from . import _data
 
-# numpy.trapezoid is the name from NumPy 2.0; before that it was numpy.trapz.
-# The package claims to work from NumPy 1.22, so it must not assume either.
-_trapezoid = getattr(np, "trapezoid", None) or np.trapz
+#: Kept as a module-level name because tests and examples import it.
+_trapezoid = _data.trapezoid
 
 #: sRGB primaries and white point, IEC 61966-2-1.
 SRGB_PRIMARIES = np.array([
@@ -151,15 +150,18 @@ def integrate_response(spectrum, wavelengths, response, response_wavelengths,
     if wavelengths.size < 2:
         raise ValueError("at least two wavelengths are needed to integrate")
 
-    worst = min(
-        _coverage(wavelengths, response_wavelengths, response[:, k])
-        for k in range(response.shape[1])
-    )
+    covered = [_coverage(wavelengths, response_wavelengths, response[:, k])
+               for k in range(response.shape[1])]
+    worst = min(covered)
     if worst < 0.999:
+        which = (f"channel {covered.index(worst)} of {len(covered)}"
+                 if len(covered) > 1 else "it")
         warnings.warn(
-            f"the spectrum spans {wavelengths[0]:g}-{wavelengths[-1]:g} nm and "
-            f"covers only {worst:.1%} of the {name}; the integral is over the "
-            "overlap and is biased by what was left out",
+            f"the spectrum spans {wavelengths[0]:g}-{wavelengths[-1]:g} nm; "
+            f"of the {name}, {which} is only {worst:.1%} covered "
+            f"(all channels: {', '.join(f'{c:.1%}' for c in covered)}). "
+            "The integral is over the overlap and is biased by what was left "
+            "out",
             CoverageWarning,
             stacklevel=2,
         )

jerlov-0.3.0/jerlov/data/boss2001_chi.csv

@@ -0,0 +1,13 @@
+source,angle_deg,chi,quantity,percent_error,status,note
+boss2001,90,0.71,chi_p,4.3,ok,"the water contribution to the measured signal is largest here, so removing it matters most"
+boss2001,100,0.9,chi_p,2.6,ok,
+boss2001,110,1.03,chi_p,3.1,ok,
+boss2001,120,1.12,chi_p,4.2,ok,
+boss2001,130,1.17,chi_p,3.3,ok,
+boss2001,140,1.18,chi_p,3.5,ok,
+boss2001,150,1.13,chi_p,4.2,ok,
+boss2001,160,1.0,chi_p,6.4,ok,
+boss2001,170,0.62,chi_p,34.8,suspect,"the volume scattering function varies most steeply here, and no measurement in the set went beyond 170 deg"
+oishi1990,120,1.14,chi,,other_definition,"chi including water, quoted by Maffione & Dana (1997) from Oishi (1990), Appl. Opt. 29, 4658"
+oishi1990,140,1.08,chi,,other_definition,as above
+maffione1997,140,1.08,chi,9.0,other_definition,"chi including water, Maffione & Dana (1997), Appl. Opt. 36, 6057, from Mie computations; the 9 percent is their standard deviation"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.2.1
+Version: 0.3.0
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -203,6 +203,25 @@ Two silent errors are checked rather than assumed:
 - **Gamut.** Underwater colours often fall outside sRGB. Clipping changes
   them, so `GamutWarning` says so.
 
+## If you measured backscattering
+
+`Water.bb` refuses to guess a backscattering ratio. If you have an instrument
+you do not have to:
+
+```python
+r = jerlov.bb_from_vsf(beta=0.0021, angle_deg=140, wavelength_nm=532)
+r.bb, r.particulate, r.water     # 1/m
+r.chi_p, r.quoted_error_percent  # 1.18, 3.5
+```
+
+Boss & Pegau (2001). The pure sea water terms are analytic and are checked
+against the definition of bb rather than transcribed; only the particle
+conversion is tabulated. Angles outside 90-170 degrees are refused, and 170
+warns: its quoted spread is **34.8 percent** against 3-6 in the middle.
+
+This gives the bb of the water your instrument was in. It still gives no bb
+for a Jerlov water type, because nothing does.
+
 ## The type changes with depth
 
 The classification is defined on the top 10 m, but clarity does not stay put.
@@ -257,21 +276,22 @@ rather than substituting a neighbour.
 ## Examples
 
 ```
-python examples/sources_disagree.py
-python examples/synthetic_underwater_images.py
+python examples/sources_disagree.py            why the source is an argument
+python examples/from_one_measurement.py        from an instrument reading
+python examples/synthetic_underwater_images.py appearance at range and depth
+python examples/solar_heating.py               for ocean circulation models
+python examples/what_an_eye_sees.py            any spectral sensitivity
 ```
 
-The first shows why the source is an argument: at 510 nm the scattering
-coefficient of Jerlov III differs by a factor of 3.8 between the two published
-sets. The second synthesises how reflectance patches appear at range and
-depth, white-balanced two ways, and ends with a list of everything it assumed.
-
-Both are run by CI, so an example that has stopped working is a failed build.
+Five scripts, each aimed at a different reader; `examples/README.md` says
+which to start with. CI runs all of them on every push, so an example that has
+stopped working is a failed build. Every one ends with the assumptions it
+made.
 
 ## Provenance and design
 
 `DATA.md` records, for every shipped table, where it came from, what was
-verified, and what is known to be wrong with it. Seventeen entries are
+verified, and what is known to be wrong with it. Eighteen entries are
 documented there: eight confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 

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

@@ -4,6 +4,7 @@ README.md
 pyproject.toml
 jerlov/__init__.py
 jerlov/_data.py
+jerlov/backscattering.py
 jerlov/colour.py
 jerlov/scene.py
 jerlov/shortwave.py
@@ -17,6 +18,7 @@ jerlov.egg-info/top_level.txt
 jerlov/data/__init__.py
 jerlov/data/austin1986_kd.csv
 jerlov/data/austin1986_model.csv
+jerlov/data/boss2001_chi.csv
 jerlov/data/cie1931_2deg_cmf.csv
 jerlov/data/cie_d65.csv
 jerlov/data/jerlov1968_kd.csv
@@ -29,6 +31,7 @@ jerlov/data/williamson2022_iop.csv
 jerlov/data/williamson2022_measured.csv
 jerlov/data/williamson2023_depth.csv
 tests/test_api.py
+tests/test_backscattering.py
 tests/test_colour.py
 tests/test_depth.py
 tests/test_packaging.py

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

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

jerlov-0.3.0/tests/test_backscattering.py

@@ -0,0 +1,167 @@
+"""Turning a single-angle measurement into bb, and the limits of doing so."""
+
+from __future__ import annotations
+
+import math
+import warnings
+
+import numpy as np
+import pytest
+
+import jerlov
+from jerlov._data import trapezoid
+from jerlov.backscattering import AngleWarning, DEPOLARISATION_RATIO
+
+
+# -- the analytic half ----------------------------------------------------
+
+
+def test_pure_water_backscattering_is_the_integral_of_its_own_vsf():
+    """bb_w must be what Eq. (3) gives when applied to Eq. (4)."""
+    for nm in (440.0, 532.0, 650.0):
+        theta = np.radians(np.linspace(90.0, 180.0, 90001))
+        vsf = jerlov.pure_water_vsf(np.degrees(theta), nm)
+        integrated = 2 * math.pi * float(trapezoid(vsf * np.sin(theta), theta))
+        assert jerlov.pure_water_backscattering(nm) == pytest.approx(
+            integrated, rel=1e-6
+        )
+
+
+def test_chi_w_gives_the_same_answer_at_every_angle():
+    """The water conversion is exact, so it cannot depend on where you look."""
+    r = (1 - DEPOLARISATION_RATIO) / (1 + DEPOLARISATION_RATIO)
+    nm = 532.0
+    expected = jerlov.pure_water_backscattering(nm)
+    for angle in (90.0, 110.0, 130.0, 150.0, 170.0):
+        chi_w = (1 + r / 3) / (1 + r * math.cos(math.radians(angle)) ** 2)
+        recovered = 2 * math.pi * jerlov.pure_water_vsf(angle, nm) * chi_w
+        assert recovered == pytest.approx(expected, rel=1e-9)
+
+
+def test_pure_water_scattering_rises_steeply_towards_the_blue():
+    """Morel's exponent is -4.32, close to Rayleigh's -4."""
+    blue = jerlov.pure_water_backscattering(400.0)
+    red = jerlov.pure_water_backscattering(700.0)
+    assert blue / red == pytest.approx((700.0 / 400.0) ** 4.32, rel=1e-9)
+
+
+def test_fresher_water_scatters_less():
+    assert (jerlov.pure_water_backscattering(532.0, salinity_psu=0.0)
+            < jerlov.pure_water_backscattering(532.0, salinity_psu=37.0))
+
+
+# -- the tabulated half ---------------------------------------------------
+
+
+def test_chi_p_matches_the_published_table():
+    published = {90: 0.71, 100: 0.90, 110: 1.03, 120: 1.12, 130: 1.17,
+                 140: 1.18, 150: 1.13, 160: 1.00, 170: 0.62}
+    for angle, value in published.items():
+        assert jerlov.particulate_chi(angle) == pytest.approx(value)
+
+
+def test_chi_p_peaks_in_the_middle_of_the_backward_hemisphere():
+    """Which is why both papers recommend 110-160 degrees."""
+    angles = np.arange(90.0, 171.0, 1.0)
+    values = [jerlov.particulate_chi(a) for a in angles]
+    assert 130.0 <= angles[int(np.argmax(values))] <= 145.0
+
+
+def test_chi_w_and_chi_p_cross_near_118_degrees():
+    """The paper's reason that instruments settled on 120."""
+    r = (1 - DEPOLARISATION_RATIO) / (1 + DEPOLARISATION_RATIO)
+    angles = np.linspace(90.0, 170.0, 8001)
+    gap = [
+        (1 + r / 3) / (1 + r * math.cos(math.radians(a)) ** 2)
+        - jerlov.particulate_chi(a)
+        for a in angles
+    ]
+    crossing = angles[int(np.argmin(np.abs(gap)))]
+    assert 114.0 < crossing < 122.0, crossing
+
+
+def test_angles_outside_the_measurements_are_refused():
+    for angle in (89.0, 171.0, 180.0, 0.0):
+        with pytest.raises(ValueError, match="90 to 170"):
+            jerlov.particulate_chi(angle)
+
+
+# -- the conversion -------------------------------------------------------
+
+
+def test_it_reproduces_the_published_equation():
+    beta, angle, nm = 0.0021, 140.0, 532.0
+    result = jerlov.bb_from_vsf(beta, angle, nm)
+    chi_p = jerlov.particulate_chi(angle)
+    expected = (2 * math.pi * chi_p
+                * (beta - jerlov.pure_water_vsf(angle, nm))
+                + jerlov.pure_water_backscattering(nm))
+    assert result.bb == pytest.approx(expected)
+    assert result.particulate + result.water == pytest.approx(result.bb)
+
+
+def test_water_alone_gives_the_water_answer():
+    """Measuring pure sea water must return bb_w and no particles."""
+    nm = 532.0
+    beta = jerlov.pure_water_vsf(130.0, nm)
+    result = jerlov.bb_from_vsf(beta, 130.0, nm)
+    assert result.particulate == pytest.approx(0.0, abs=1e-12)
+    assert result.bb == pytest.approx(jerlov.pure_water_backscattering(nm))
+
+
+def test_more_scattering_gives_more_backscattering():
+    previous = -1.0
+    for beta in (0.0005, 0.001, 0.002, 0.005):
+        value = jerlov.bb_from_vsf(beta, 140.0, 532.0).bb
+        assert value > previous
+        previous = value
+
+
+def test_a_typical_coastal_reading_lands_in_the_reported_range():
+    """A sanity anchor, not a validation. Coastal bb/b is put at 0.015-0.03."""
+    result = jerlov.bb_from_vsf(0.0021, 140.0, 532.0, salinity_psu=35.0)
+    assert 0.005 < result.bb < 0.05
+
+
+def test_170_degrees_warns_about_its_own_error():
+    with pytest.warns(AngleWarning, match="34.8%"):
+        jerlov.bb_from_vsf(0.002, 170.0, 532.0)
+
+
+def test_the_recommended_angles_do_not_warn():
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        for angle in (110.0, 120.0, 130.0, 140.0, 150.0, 160.0):
+            jerlov.bb_from_vsf(0.002, angle, 532.0)
+
+
+def test_a_reading_below_pure_water_warns_rather_than_passing():
+    with pytest.warns(AngleWarning, match="below that of pure sea water"):
+        jerlov.bb_from_vsf(1e-6, 140.0, 400.0)
+
+
+def test_negative_scattering_is_refused():
+    with pytest.raises(ValueError, match="cannot be negative"):
+        jerlov.bb_from_vsf(-0.001, 140.0, 532.0)
+
+
+def test_the_result_carries_the_quoted_error():
+    result = jerlov.bb_from_vsf(0.002, 140.0, 532.0)
+    assert result.chi_p == pytest.approx(1.18)
+    assert result.quoted_error_percent == pytest.approx(3.5)
+    assert result.angle_deg == 140.0
+
+
+def test_scalar_in_scalar_out():
+    assert isinstance(jerlov.bb_from_vsf(0.002, 140.0, 532.0).bb, float)
+    array = jerlov.bb_from_vsf([0.001, 0.002], 140.0, 532.0).bb
+    assert isinstance(array, np.ndarray) and array.shape == (2,)
+
+
+# -- what it does not do --------------------------------------------------
+
+
+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)

{jerlov-0.2.1 → jerlov-0.3.0}/tests/test_colour.py

@@ -73,7 +73,7 @@ def test_each_primary_lights_only_its_own_channel():
 def test_a_narrow_spectrum_warns():
     """450-650 nm looks like a full spectrum but is not."""
     wl = np.arange(450.0, 651.0, 1.0)
-    with pytest.warns(CoverageWarning, match="covers only"):
+    with pytest.warns(CoverageWarning, match="covered"):
         spectrum_to_xyz(np.ones_like(wl), wl)
 
 
@@ -88,8 +88,13 @@ def test_the_warning_states_what_was_missed():
     with pytest.warns(CoverageWarning) as caught:
         spectrum_to_xyz(np.ones_like(wl), wl)
     message = str(caught[0].message)
-    assert "500-600 nm" in message
-    assert "CIE 1931" in message
+    assert "500-600 nm" in message          # the span it actually had
+    assert "CIE 1931" in message            # what it was integrated against
+    assert "all channels:" in message       # not just the worst one
+    # z-bar peaks at 445 nm, so 500-600 nm barely touches it. Naming the
+    # channel matters: "4.1% covered" alone reads as if the whole observer
+    # were 4.1% covered, which would be wrong.
+    assert "channel 2 of 3" in message
 
 
 # -- white, the other one ------------------------------------------------

jerlov-0.3.0/tests/test_packaging.py

@@ -0,0 +1,237 @@
+"""The version is written in three files, so it drifts.
+
+It has drifted twice: once between `pyproject.toml` and `jerlov/__init__.py`,
+and once between the working tree and an installed copy. Both were found by
+someone noticing a wrong number in output, which is not a method.
+
+These checks only apply to a source tree. Running the suite against an
+installed wheel skips them, because `pyproject.toml` and `CITATION.cff` are
+not shipped.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+
+import pytest
+
+import jerlov
+
+ROOT = pathlib.Path(__file__).resolve().parent.parent
+source_tree = pytest.mark.skipif(
+    not (ROOT / "pyproject.toml").exists(),
+    reason="not running from a source tree",
+)
+
+
+def _declared(path: pathlib.Path, pattern: str) -> str:
+    match = re.search(pattern, path.read_text(), re.MULTILINE)
+    assert match, f"no version found in {path.name}"
+    return match.group(1).strip()
+
+
+@source_tree
+def test_the_three_declared_versions_agree():
+    toml = _declared(ROOT / "pyproject.toml", r'^version = "(.+?)"')
+    cff = _declared(ROOT / "CITATION.cff", r"^version: (.+)$")
+    assert jerlov.__version__ == toml, (
+        f"jerlov/__init__.py says {jerlov.__version__}, "
+        f"pyproject.toml says {toml}"
+    )
+    assert jerlov.__version__ == cff, (
+        f"jerlov/__init__.py says {jerlov.__version__}, "
+        f"CITATION.cff says {cff}"
+    )
+
+
+@source_tree
+def test_the_version_looks_like_a_release():
+    assert re.fullmatch(r"\d+\.\d+\.\d+", jerlov.__version__), (
+        f"{jerlov.__version__!r} is not a plain release version"
+    )
+
+
+@source_tree
+def test_the_package_under_test_is_the_one_in_this_tree():
+    """Guards the sys.path trap that made the examples load an old install."""
+    imported = pathlib.Path(jerlov.__file__).resolve().parent
+    assert imported == ROOT / "jerlov", (
+        f"tests import jerlov from {imported}, not from {ROOT / 'jerlov'}; "
+        "run `pip install -e .` in the repository"
+    )
+
+
+@source_tree
+def test_every_shipped_table_is_listed_in_DATA_md():
+    """A table nobody documented is a table with no provenance."""
+    documented = (ROOT / "DATA.md").read_text()
+    for csv in sorted((ROOT / "jerlov" / "data").glob("*.csv")):
+        assert csv.name in documented, f"{csv.name} is not mentioned in DATA.md"
+
+
+@source_tree
+def test_every_shipped_table_has_a_build_script_or_is_explained():
+    """Each table should be regenerable; tools/README.md says so."""
+    scripts = " ".join(p.read_text() for p in (ROOT / "tools").glob("*.py"))
+    for csv in sorted((ROOT / "jerlov" / "data").glob("*.csv")):
+        assert csv.name in scripts, f"no build script writes {csv.name}"
+
+
+# -- the documentation counts itself -------------------------------------
+
+_SPELLED = ["zero", "one", "two", "three", "four", "five", "six", "seven",
+            "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen",
+            "fifteen", "sixteen", "seventeen", "eighteen", "nineteen",
+            "twenty", "twenty-one", "twenty-two", "twenty-three",
+            "twenty-four", "twenty-five"]
+WORDS = {word: value for value, word in enumerate(_SPELLED)}
+WORDS.update({word.capitalize(): value
+              for value, word in enumerate(_SPELLED)})
+
+
+def _numbered_sections(text: str) -> int:
+    return len(re.findall(r"^## \d+\. ", text, re.MULTILINE))
+
+
+def _confirmed_sections(text: str) -> int:
+    return len(re.findall(r"^## \d+\..*\(confirmed", text, re.MULTILINE))
+
+
+@source_tree
+def test_DATA_md_counts_its_own_sections():
+    """The opening summary is written by hand and has drifted three times."""
+    text = (ROOT / "DATA.md").read_text()
+    match = re.search(r"^(\w+) entries are recorded below\. (\w+) are confirmed",
+                      text, re.MULTILINE)
+    assert match, "DATA.md no longer opens with a countable summary"
+    claimed_total, claimed_confirmed = (WORDS[g] for g in match.groups())
+    assert claimed_total == _numbered_sections(text)
+    assert claimed_confirmed == _confirmed_sections(text)
+
+
+@source_tree
+def test_the_zenodo_record_will_carry_what_it_should():
+    """`.zenodo.json` is only read at archive time, so nothing else checks it."""
+    import json
+
+    record = json.loads((ROOT / ".zenodo.json").read_text())
+    assert record["upload_type"] == "software"
+    assert record["license"] == "Apache-2.0"
+    assert record["creators"], "a record with no author is not citable"
+    for creator in record["creators"]:
+        assert creator.get("orcid"), (
+            f"{creator['name']} has no ORCID, so the record will not attach "
+            "to their publication list"
+        )
+    # Every source the package ships data from should be reachable from the
+    # record, not only from DATA.md.
+    derived = [r["identifier"] for r in record["related_identifiers"]
+               if r["relation"] == "isDerivedFrom"]
+    assert len(derived) >= 8, derived
+
+
+@source_tree
+def test_the_README_agrees_with_DATA_md_on_the_count():
+    data = (ROOT / "DATA.md").read_text()
+    readme = (ROOT / "README.md").read_text()
+    match = re.search(r"(\w+) entries are\s+documented there: (\w+) confirmed",
+                      readme)
+    assert match, "the README no longer states the count"
+    assert WORDS[match.group(1)] == _numbered_sections(data)
+    assert WORDS[match.group(2)] == _confirmed_sections(data)
+
+
+@source_tree
+def test_the_zenodo_description_agrees_with_DATA_md():
+    """It has now gone stale four times, and only an archive run reads it."""
+    import json
+
+    record = json.loads((ROOT / ".zenodo.json").read_text())
+    data = (ROOT / "DATA.md").read_text()
+    description = record["description"]
+
+    match = re.search(r"(\w+) entries are documented, (\w+) of them confirmed",
+                      description)
+    assert match, "the Zenodo description no longer states a countable summary"
+    assert WORDS[match.group(1)] == _numbered_sections(data), (
+        f".zenodo.json says {match.group(1)}, DATA.md has "
+        f"{_numbered_sections(data)} sections"
+    )
+    assert WORDS[match.group(2)] == _confirmed_sections(data)
+
+
+@source_tree
+def test_the_zenodo_record_names_every_shipped_module():
+    """A capability the record does not mention is one nobody will find."""
+    record = __import__("json").loads((ROOT / ".zenodo.json").read_text())
+    described = record["description"].lower()
+    for module, phrase in (
+        ("scene.py", "veiling"),
+        ("colour.py", "srgb"),
+        ("shortwave.py", "shortwave"),
+        ("backscattering.py", "backscattering coefficient"),
+        ("water.py", "scattering coefficients"),
+    ):
+        assert (ROOT / "jerlov" / module).exists()
+        assert phrase in described, (
+            f"{module} ships but the Zenodo description never mentions "
+            f"{phrase!r}"
+        )
+
+
+@source_tree
+def test_every_module_can_find_the_tables_it_reads():
+    """A missing data file should fail here, not thirteen tests later.
+
+    `jerlov/data/boss2001_chi.csv` once failed to reach a working copy, and
+    the first sign of it was thirteen unrelated-looking FileNotFoundErrors
+    deep inside the backscattering tests.
+    """
+    shipped = {p.name for p in (ROOT / "jerlov" / "data").glob("*.csv")}
+    wanted = set()
+    for module in (ROOT / "jerlov").glob("*.py"):
+        wanted |= set(re.findall(r'_rows\(\s*"([^"]+\.csv)"', module.read_text()))
+    assert wanted, "no module reads a table any more, which cannot be right"
+    missing = sorted(wanted - shipped)
+    assert not missing, (
+        f"these are read by jerlov/*.py but not present in jerlov/data/: "
+        f"{missing}. Run the matching script in tools/."
+    )
+
+
+@source_tree
+def test_every_build_script_produces_a_shipped_table():
+    """The other direction: a script whose output never arrived."""
+    shipped = {p.name for p in (ROOT / "jerlov" / "data").glob("*.csv")}
+    for script in sorted((ROOT / "tools").glob("build_*.py")):
+        written = set(re.findall(r'DATA_DIR / "([^"]+\.csv)"', script.read_text()))
+        written |= set(re.findall(r'report\(\s*"([^"]+\.csv)"', script.read_text()))
+        assert written, f"{script.name} writes no table"
+        missing = sorted(written - shipped)
+        assert not missing, (
+            f"{script.name} writes {missing}, which is not in jerlov/data/"
+        )
+
+
+@source_tree
+def test_nothing_reaches_for_a_numpy_2_only_name():
+    """`numpy.trapezoid` arrived in NumPy 2.0 and `numpy.trapz` left in it.
+
+    `jerlov._data.trapezoid` resolves whichever exists. This has now been got
+    wrong twice: once in colour.py, shipped in 0.1.1, and once in the
+    backscattering tests, caught by CI before release. Both times the local
+    NumPy was new enough for it to pass.
+    """
+    offenders = []
+    for path in list(ROOT.glob("jerlov/*.py")) + list(ROOT.glob("tests/*.py")) \
+            + list(ROOT.glob("tools/*.py")) + list(ROOT.glob("examples/*.py")):
+        text = path.read_text()
+        for name in ("np.trapezoid", "np.trapz", "numpy.trapezoid",
+                     "numpy.trapz"):
+            if name + "(" in text:
+                offenders.append(f"{path.relative_to(ROOT)}: {name}")
+    assert not offenders, (
+        "use jerlov._data.trapezoid instead, which resolves whichever name "
+        f"the installed NumPy has: {offenders}"
+    )

jerlov-0.2.1/tests/test_packaging.py

@@ -1,78 +0,0 @@
-"""The version is written in three files, so it drifts.
-
-It has drifted twice: once between `pyproject.toml` and `jerlov/__init__.py`,
-and once between the working tree and an installed copy. Both were found by
-someone noticing a wrong number in output, which is not a method.
-
-These checks only apply to a source tree. Running the suite against an
-installed wheel skips them, because `pyproject.toml` and `CITATION.cff` are
-not shipped.
-"""
-
-from __future__ import annotations
-
-import pathlib
-import re
-
-import pytest
-
-import jerlov
-
-ROOT = pathlib.Path(__file__).resolve().parent.parent
-source_tree = pytest.mark.skipif(
-    not (ROOT / "pyproject.toml").exists(),
-    reason="not running from a source tree",
-)
-
-
-def _declared(path: pathlib.Path, pattern: str) -> str:
-    match = re.search(pattern, path.read_text(), re.MULTILINE)
-    assert match, f"no version found in {path.name}"
-    return match.group(1).strip()
-
-
-@source_tree
-def test_the_three_declared_versions_agree():
-    toml = _declared(ROOT / "pyproject.toml", r'^version = "(.+?)"')
-    cff = _declared(ROOT / "CITATION.cff", r"^version: (.+)$")
-    assert jerlov.__version__ == toml, (
-        f"jerlov/__init__.py says {jerlov.__version__}, "
-        f"pyproject.toml says {toml}"
-    )
-    assert jerlov.__version__ == cff, (
-        f"jerlov/__init__.py says {jerlov.__version__}, "
-        f"CITATION.cff says {cff}"
-    )
-
-
-@source_tree
-def test_the_version_looks_like_a_release():
-    assert re.fullmatch(r"\d+\.\d+\.\d+", jerlov.__version__), (
-        f"{jerlov.__version__!r} is not a plain release version"
-    )
-
-
-@source_tree
-def test_the_package_under_test_is_the_one_in_this_tree():
-    """Guards the sys.path trap that made the examples load an old install."""
-    imported = pathlib.Path(jerlov.__file__).resolve().parent
-    assert imported == ROOT / "jerlov", (
-        f"tests import jerlov from {imported}, not from {ROOT / 'jerlov'}; "
-        "run `pip install -e .` in the repository"
-    )
-
-
-@source_tree
-def test_every_shipped_table_is_listed_in_DATA_md():
-    """A table nobody documented is a table with no provenance."""
-    documented = (ROOT / "DATA.md").read_text()
-    for csv in sorted((ROOT / "jerlov" / "data").glob("*.csv")):
-        assert csv.name in documented, f"{csv.name} is not mentioned in DATA.md"
-
-
-@source_tree
-def test_every_shipped_table_has_a_build_script_or_is_explained():
-    """Each table should be regenerable; tools/README.md says so."""
-    scripts = " ".join(p.read_text() for p in (ROOT / "tools").glob("*.py"))
-    for csv in sorted((ROOT / "jerlov" / "data").glob("*.csv")):
-        assert csv.name in scripts, f"no build script writes {csv.name}"