jerlov 0.3.1__tar.gz → 0.3.2__tar.gz

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

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

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

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

{jerlov-0.3.1 → 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.1 → 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.1 → 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.1 → 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.1 → jerlov-0.3.2/jerlov.egg-info}/PKG-INFO

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

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

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

{jerlov-0.3.1 → 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.1 → 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)