jerlov 0.7.2__tar.gz → 0.8.0__tar.gz

{jerlov-0.7.2/jerlov.egg-info → jerlov-0.8.0}/PKG-INFO

@@ -1,21 +1,26 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.2
+Version: 0.8.0
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
 Keywords: ocean optics,Jerlov water types,inherent optical properties
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: numpy>=1.22
-Provides-Extra: plot
-Requires-Dist: matplotlib; extra == "plot"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Provides-Extra: build
@@ -72,7 +77,8 @@ paper's own constant, so constants are attached to sources.
 
 ## What this package will not do
 
-- **Extrapolate.** Asking for a wavelength outside the data raises.
+- **Extrapolate.** Asking for a wavelength outside the data raises. Values
+  that a source itself extrapolated are returned, but marked, and they warn.
 - **Fill a gap.** Where a published value is wrong and could not be
   recovered, the value is NaN and stays NaN through interpolation.
 - **Supply bb.** The backscattering coefficient is not determined by the
@@ -260,6 +266,7 @@ coastal water clears as you go down.
 jerlov.water_type_at_depth("I", 60.0)     # 'IB'
 jerlov.water_type_at_depth("3C", 45.0)    # 'II'
 jerlov.water_type_at_depth("9C", 15.0)    # None: the paper declined to say
+jerlov.water_type_at_depth("I", [0, 30, 60])   # array(['I', 'IA', 'IB'], dtype=object)
 ```
 
 `None` means fewer than ten measurement campaigns supported a declaration, so

{jerlov-0.7.2 → jerlov-0.8.0}/README.md

@@ -47,7 +47,8 @@ paper's own constant, so constants are attached to sources.
 
 ## What this package will not do
 
-- **Extrapolate.** Asking for a wavelength outside the data raises.
+- **Extrapolate.** Asking for a wavelength outside the data raises. Values
+  that a source itself extrapolated are returned, but marked, and they warn.
 - **Fill a gap.** Where a published value is wrong and could not be
   recovered, the value is NaN and stays NaN through interpolation.
 - **Supply bb.** The backscattering coefficient is not determined by the
@@ -235,6 +236,7 @@ coastal water clears as you go down.
 jerlov.water_type_at_depth("I", 60.0)     # 'IB'
 jerlov.water_type_at_depth("3C", 45.0)    # 'II'
 jerlov.water_type_at_depth("9C", 15.0)    # None: the paper declined to say
+jerlov.water_type_at_depth("I", [0, 30, 60])   # array(['I', 'IA', 'IB'], dtype=object)
 ```
 
 `None` means fewer than ten measurement campaigns supported a declaration, so

{jerlov-0.7.2 → jerlov-0.8.0}/jerlov/__init__.py

@@ -96,4 +96,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.7.2"
+__version__ = "0.8.0"

{jerlov-0.7.2 → jerlov-0.8.0}/jerlov/shortwave.py

@@ -15,12 +15,13 @@ them from Jerlov (1968) Table XXI and reproduces R for every row.
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
 
 import numpy as np
 
 from . import _data
-from .water import _like_input, _require_number
+from .water import ProvenanceWarning, _like_input, _require_number
 
 CITATION = (
     "Paulson, C. A. and Simpson, J. J. (1977), 'Irradiance measurements in "
@@ -42,15 +43,33 @@ class ShortwaveParameters:
     zeta2_m: float
     """Attenuation length of the slow term, metres. Blue-green light."""
     fit_depth_m: float | None
-    """Depth range the row was fitted over. Not printed in the table."""
+    """Depth the row was fitted down to: 100 m, or 50 m for ``I_upper50``.
+    The paper's text says so; the table does not. None for the rows that are
+    not Jerlov types."""
     note: str
 
     def fraction_at(self, depth_m):
-        """``I(z)/I(0)`` at one or more depths."""
+        """``I(z)/I(0)`` at one or more depths.
+
+        Below :attr:`fit_depth_m` the two exponentials are extrapolated
+        beyond the data they were fitted to, and a
+        :class:`~jerlov.ProvenanceWarning` says so. Jerlov's own Table XXI
+        goes deeper for the clearer types; see
+        :func:`jerlov1968_solar_fraction`.
+        """
         z = np.atleast_1d(np.asarray(depth_m, dtype=float))
         _require_number(z, "depth_m")
         if np.any(z < 0):
             raise ValueError("depth_m cannot be negative")
+        if self.fit_depth_m is not None and np.any(z > self.fit_depth_m):
+            warnings.warn(
+                f"{self.key}: Paulson & Simpson (1977) fitted these "
+                f"parameters to the upper {self.fit_depth_m:g} m; at "
+                f"{float(np.max(z)):g} m the two exponentials are "
+                "extrapolated. See DATA.md section 14.",
+                ProvenanceWarning,
+                stacklevel=_data.caller_stacklevel(),
+            )
         out = (self.R * np.exp(-z / self.zeta1_m)
                + (1 - self.R) * np.exp(-z / self.zeta2_m))
         return _like_input(out, depth_m)

{jerlov-0.7.2 → jerlov-0.8.0}/jerlov/water.py

@@ -148,6 +148,14 @@ class Water:
         self.source = source
         self._flags = dict(flags or {})
         for key, statuses in self._flags.items():
+            if key not in self._series:
+                # Ignoring it would drop the caller's doubt without a word,
+                # which is what flags exist to prevent; a misspelt key such
+                # as "kd" for "Kd" would never warn.
+                raise ValueError(
+                    f"flags given for {key!r}, which this water does not "
+                    f"carry (it has {', '.join(sorted(self._series))})"
+                )
             if len(statuses) != self.wavelengths.size:
                 raise ValueError(
                     f"flags[{key!r}] has {len(statuses)} entries; it needs one "
@@ -467,7 +475,7 @@ def water(water_type: str, source: str = "williamson2022") -> Water:
     )
 
 
-def water_type_at_depth(surface_water_type: str, depth_m: float) -> str | None:
+def water_type_at_depth(surface_water_type: str, depth_m):
     """The Jerlov type that typically applies at ``depth_m``.
 
     The classification is defined on the top 10 m, but clarity changes with
@@ -480,6 +488,11 @@ def water_type_at_depth(surface_water_type: str, depth_m: float) -> str | None:
     wherever fewer than ten campaigns supported one. Coastal types run out
     quickly: 3C is declared only to 70 m, and 9C not at all below 10 m.
 
+    ``depth_m`` may be a single depth, which gives a string or ``None``, or
+    an array of depths, which gives an object array of the same shape::
+
+        jerlov.water_type_at_depth("I", [0, 30, 60])   # ['I', 'IA', 'IB']
+
     This is a lookup, not a correction applied on your behalf. To use it::
 
         deeper = jerlov.water_type_at_depth("I", 60.0)      # "IB"
@@ -491,12 +504,12 @@ 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):
+    depths = np.asarray(depth_m, dtype=float)
+    if not np.all(np.isfinite(depths)):
         # 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(f"depth_m must be finite numbers, not {depth_m!r}")
+    if np.any(depths < 0):
         raise ValueError("depth_m cannot be negative")
     rows = _data._rows("williamson2023_depth.csv")
     known = {r["surface_water_type"] for r in rows}
@@ -505,20 +518,31 @@ 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))})"
         )
-    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
+    own = [(float(r["depth_min_m"]), float(r["depth_max_m"]),
+            r["water_type"] or None)
+           for r in rows if r["surface_water_type"] == surface_water_type]
+    deepest = max(bottom for _, bottom, _ in own)
+
+    def at(depth: float) -> str | None:
+        for top, bottom, water_type in own:
+            # 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 < bottom or depth == bottom == deepest:
+                return water_type
+        # Beyond 200 m the paper makes no statement at all.
+        return None
+
+    if depths.ndim == 0:
+        return at(float(depths))
+    out = np.empty(depths.shape, dtype=object)
+    for index, depth in np.ndenumerate(depths):
+        out[index] = at(float(depth))
+    return out
 
 
-@dataclass(frozen=True, eq=False)   # == on arrays has no single answer
+# == on arrays has no single answer; the generated repr printed every array.
+@dataclass(frozen=True, eq=False, repr=False)
 class Descent:
     """Downwelling irradiance carried down through changing water types."""
 
@@ -534,6 +558,23 @@ class Descent:
     transmittance: np.ndarray
     """``Ed(depth) / Ed(0)``: ``exp(-sum(Kd_i * thickness_i))``."""
 
+    def __repr__(self) -> str:
+        # Adjacent 10 m layers of one type are shown as one span.
+        spans: list[list] = []
+        for top, bottom, water_type in self.layers:
+            if spans and spans[-1][2] == water_type:
+                spans[-1][1] = bottom
+            else:
+                spans.append([top, bottom, water_type])
+        path = ", ".join(f"{t} {lo:g}-{hi:g}" for lo, hi, t in spans)
+        path = f"{path} m" if path else "no layer crossed"
+        n = np.size(self.wavelengths)
+        return (
+            f"<Descent {self.surface_water_type} to {self.depth_m:g} m: "
+            f"{path}; Kd from {self.source}; "
+            f"{n} wavelength{'s' if n != 1 else ''}>"
+        )
+
 
 def descend(surface_water_type: str, depth_m: float, wavelengths, *,
             source: str = "jerlov1976") -> Descent:

{jerlov-0.7.2 → jerlov-0.8.0/jerlov.egg-info}/PKG-INFO

@@ -1,21 +1,26 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.2
+Version: 0.8.0
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
 Keywords: ocean optics,Jerlov water types,inherent optical properties
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: numpy>=1.22
-Provides-Extra: plot
-Requires-Dist: matplotlib; extra == "plot"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Provides-Extra: build
@@ -72,7 +77,8 @@ paper's own constant, so constants are attached to sources.
 
 ## What this package will not do
 
-- **Extrapolate.** Asking for a wavelength outside the data raises.
+- **Extrapolate.** Asking for a wavelength outside the data raises. Values
+  that a source itself extrapolated are returned, but marked, and they warn.
 - **Fill a gap.** Where a published value is wrong and could not be
   recovered, the value is NaN and stays NaN through interpolation.
 - **Supply bb.** The backscattering coefficient is not determined by the
@@ -260,6 +266,7 @@ coastal water clears as you go down.
 jerlov.water_type_at_depth("I", 60.0)     # 'IB'
 jerlov.water_type_at_depth("3C", 45.0)    # 'II'
 jerlov.water_type_at_depth("9C", 15.0)    # None: the paper declined to say
+jerlov.water_type_at_depth("I", [0, 30, 60])   # array(['I', 'IA', 'IB'], dtype=object)
 ```
 
 `None` means fewer than ten measurement campaigns supported a declaration, so

{jerlov-0.7.2 → jerlov-0.8.0}/jerlov.egg-info/requires.txt

@@ -4,8 +4,5 @@ numpy>=1.22
 openpyxl
 colour-science
 
-[plot]
-matplotlib
-
 [test]
 pytest

{jerlov-0.7.2 → jerlov-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jerlov"
-version = "0.7.2"
+version = "0.8.0"
 description = "Inherent optical properties of Jerlov water types, with provenance"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,14 +14,20 @@ license-files = ["LICENSE", "NOTICE"]
 authors = [{name = "T. Ishibashi"}]
 keywords = ["ocean optics", "Jerlov water types", "inherent optical properties"]
 classifiers = [
-  "Development Status :: 2 - Pre-Alpha",
+  "Development Status :: 4 - Beta",
   "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
   "Topic :: Scientific/Engineering :: Physics",
+  "Typing :: Typed",
 ]
 
 [project.optional-dependencies]
-plot = ["matplotlib"]
 test = ["pytest"]
 build = ["openpyxl", "colour-science"]
 

{jerlov-0.7.2 → jerlov-0.8.0}/tests/test_api.py

@@ -338,6 +338,15 @@ def test_flags_must_cover_every_wavelength():
         Water([400.0, 500.0, 600.0], a=[0.1, 0.2, 0.3], flags={"a": ("ok",)})
 
 
+def test_flags_for_a_quantity_the_water_lacks_are_refused():
+    """They used to be kept and never consulted, so the doubt they recorded
+    was lost without a word; "kd" for "Kd" was lost the same way."""
+    with pytest.raises(ValueError, match="flags given for 'b'.*it has a"):
+        Water([400.0, 500.0], a=[0.1, 0.2], flags={"b": ("suspect", "ok")})
+    with pytest.raises(ValueError, match="flags given for 'kd'"):
+        Water([400.0, 500.0], kd=[0.1, 0.2], flags={"kd": ("suspect", "ok")})
+
+
 def test_b_from_c_warns_when_c_is_below_pure_water():
     """b came out negative without a word; kd_spectrum already warned in the
     same situation."""

{jerlov-0.7.2 → jerlov-0.8.0}/tests/test_depth.py

@@ -161,3 +161,32 @@ def test_descent_to_the_surface_is_no_attenuation():
     d = jerlov.descend("II", 0.0, [450.0, 550.0])
     assert np.all(d.transmittance == 1.0)
     assert d.layers == ()
+
+
+def test_an_array_of_depths_gives_one_type_per_depth():
+    depths = np.array([[0.0, 30.0], [60.0, 250.0]])
+    types = jerlov.water_type_at_depth("I", depths)
+    assert types.shape == depths.shape
+    assert types.tolist() == [["I", "IA"], ["IB", None]]
+    for depth, got in zip(depths.ravel(), types.ravel()):
+        assert got == jerlov.water_type_at_depth("I", float(depth))
+    # A list is an array too; a scalar is still a plain string.
+    assert list(jerlov.water_type_at_depth("9C", [5, 15])) == ["9C", None]
+    assert isinstance(jerlov.water_type_at_depth("I", np.float64(5)), str)
+
+
+def test_one_bad_depth_in_an_array_refuses_the_whole_array():
+    with pytest.raises(ValueError, match="finite"):
+        jerlov.water_type_at_depth("I", [10.0, float("nan")])
+    with pytest.raises(ValueError, match="cannot be negative"):
+        jerlov.water_type_at_depth("I", [10.0, -1.0])
+
+
+def test_a_descent_prints_its_path_not_its_arrays():
+    """The generated repr printed every wavelength and transmittance."""
+    d = jerlov.descend("1C", 45.0, np.arange(400.0, 701.0, 1.0))
+    text = repr(d)
+    assert text == ("<Descent 1C to 45 m: 1C 0-20, III 20-40, II 40-45 m; "
+                    "Kd from jerlov1976; 301 wavelengths>")
+    assert repr(jerlov.descend("II", 0.0, 500.0)).startswith(
+        "<Descent II to 0 m: no layer crossed;")

{jerlov-0.7.2 → jerlov-0.8.0}/tests/test_packaging.py

@@ -322,3 +322,50 @@ def test_examples_use_only_the_public_api():
     offenders = [p.name for p in ROOT.glob("examples/*.py")
                  if "_data" in p.read_text()]
     assert not offenders, f"examples reaching into jerlov._data: {offenders}"
+
+
+@source_tree
+def test_the_python_classifiers_are_the_versions_CI_runs():
+    """PyPI shows these. A version listed but never tested is a claim, as
+    section 15 of DECISIONS.md found for numpy; one tested but not listed
+    is support nobody can see."""
+    toml = (ROOT / "pyproject.toml").read_text()
+    listed = set(re.findall(
+        r'"Programming Language :: Python :: (3\.\d+)"', toml))
+    ci = (ROOT / ".github" / "workflows" / "test.yml").read_text()
+    matrix = re.search(r"python-version: \[(.+?)\]", ci).group(1)
+    tested = set(re.findall(r'"(3\.\d+)"', matrix))
+    assert listed == tested, (
+        f"pyproject.toml lists Python {sorted(listed)}, CI tests {sorted(tested)}"
+    )
+    floor = re.search(r'^requires-python = ">=(3\.\d+)"', toml, re.M).group(1)
+    assert floor == min(tested, key=lambda v: int(v.split(".")[1])), (
+        f"requires-python says >={floor}, but CI's oldest is {min(tested)}"
+    )
+
+
+#: Import name of each distribution an extra installs.
+_IMPORTED_AS = {"pytest": "pytest", "openpyxl": "openpyxl",
+                "colour-science": "colour"}
+
+
+@source_tree
+def test_every_optional_extra_is_used_by_something():
+    """The `plot` extra installed matplotlib, which nothing imported."""
+    toml = (ROOT / "pyproject.toml").read_text()
+    block = re.search(
+        r"^\[project\.optional-dependencies\]\n(.*?)(?=^\[)", toml,
+        re.M | re.S).group(1)
+    code = "\n".join(p.read_text() for d in ("jerlov", "tests", "tools",
+                                             "examples")
+                     for p in (ROOT / d).rglob("*.py"))
+    for extra, spec in re.findall(r"^(\w+) = \[(.*)\]$", block, re.M):
+        for dist in re.findall(r'"([A-Za-z0-9_.-]+)', spec):
+            assert dist in _IMPORTED_AS, (
+                f"extra {extra!r} installs {dist}; add its import name to "
+                "_IMPORTED_AS"
+            )
+            name = _IMPORTED_AS[dist]
+            assert re.search(rf"^\s*(import|from) {name}\b", code, re.M), (
+                f"extra {extra!r} installs {dist}, which nothing imports"
+            )

{jerlov-0.7.2 → jerlov-0.8.0}/tests/test_shortwave.py

@@ -84,9 +84,9 @@ def test_the_alternative_type_I_fit_is_reachable():
     assert fifty.fit_depth_m == 50
     assert fifty.water_type == "I"
     assert fifty.R != hundred.R
-    # The paper gives it because the profile changes slope; deeper down they
-    # must therefore disagree.
-    assert abs(fifty.fraction_at(80.0) - hundred.fraction_at(80.0)) > 1e-4
+    # The paper gives it because the profile changes slope; they must
+    # therefore disagree, even inside the 50 m both were fitted over.
+    assert abs(fifty.fraction_at(40.0) - hundred.fraction_at(40.0)) > 1e-4
 
 
 def test_the_rows_that_are_not_water_types_are_not_offered():
@@ -130,3 +130,27 @@ def test_table_xxi_is_public():
         assert len(jerlov.jerlov1968_solar_fraction(t)[0]) == 12
     with pytest.raises(KeyError, match="known:"):
         jerlov.jerlov1968_solar_fraction("IV")
+
+
+def test_below_the_fitted_depth_it_warns():
+    """Paulson & Simpson fitted the upper 100 m, and 50 m for I_upper50."""
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        jerlov.solar_fraction("IB", 100.0)
+        jerlov.shortwave_parameters("I_upper50").fraction_at([0.0, 50.0])
+    with pytest.warns(jerlov.ProvenanceWarning, match="upper 100 m"):
+        jerlov.solar_fraction("IB", 100.5)
+    with pytest.warns(jerlov.ProvenanceWarning, match="upper 50 m"):
+        jerlov.shortwave_parameters("I_upper50").fraction_at([10.0, 60.0])
+
+
+def test_rows_that_are_not_types_carry_no_fit_depth_and_do_not_warn():
+    import warnings
+
+    p = jerlov.shortwave_parameters("run_1", include_non_types=True)
+    assert p.fit_depth_m is None
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        p.fraction_at(150.0)