jerlov 0.3.3__tar.gz → 0.4.0__tar.gz

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

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

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

{jerlov-0.3.3 → 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.3 → 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.3 → 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.3 → jerlov-0.4.0}/jerlov/water.py

@@ -325,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")
@@ -334,10 +339,14 @@ 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

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

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

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

{jerlov-0.3.3 → 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.3 → 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.3 → 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.3 → 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