jerlov 0.7.2__tar.gz → 0.7.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.2
+Version: 0.7.3
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -72,7 +72,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

{jerlov-0.7.2 → jerlov-0.7.3}/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

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

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

{jerlov-0.7.2 → jerlov-0.7.3}/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.7.3/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.7.2
+Version: 0.7.3
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -72,7 +72,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

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

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

{jerlov-0.7.2 → jerlov-0.7.3}/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)