jerlov 0.9.2__tar.gz → 0.9.4__tar.gz

{jerlov-0.9.2/jerlov.egg-info → jerlov-0.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.9.2
+Version: 0.9.4
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -285,6 +285,9 @@ scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
 
 It refuses to go through a layer the paper declared nothing for, rather than
 carrying the last type on: 3C stops at 70 m, 9C at 10 m.
+`jerlov.profile_depth("3C")` says how far a descent can go, and
+`d.transmittance_at(z)` gives any depth above the descent's bottom without
+descending again.
 
 ## Light for photosynthesis
 
@@ -304,6 +307,18 @@ default, because PAR counts photons and an energy spectrum read as photons is
 weighted wrongly with no sign of it. This is planar PAR, from Ed; PAR on
 scalar irradiance is larger by a factor this package cannot supply.
 
+Jerlov measured quanta irradiance, 350-700 nm, by water type, and his
+tables are shipped for checking against:
+
+```python
+jerlov.jerlov1977_quanta("II")   # <QuantaLevels II: 30% 10.5 m, 10% 24 m, 3% 39 m, 1% 52 m; ...>
+```
+
+From II to 3C the package agrees with them within 2 m at every level. For
+Jerlov I it agrees only through `descend`; for IB it puts the 1 percent
+level a third too deep, because Jerlov's IB water grew more turbid below
+15 m. DATA.md section 22.
+
 ## Which type is my water nearest?
 
 ```python
@@ -315,7 +330,9 @@ r.beyond          # "clearer" or "more turbid" than every type, or None
 
 It ranks the types of one edition; it draws no boundaries, since those differ
 between editions. A single wavelength is accepted, and ranks oceanic and
-coastal types less well apart than a spectrum does.
+coastal types less well apart than a spectrum does. `types=` compares with
+some of the types only, which keeps the wavelengths where only the others
+have gaps.
 
 ## Other entry points
 
@@ -389,8 +406,8 @@ 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. Twenty-one entries are
-documented there: eight confirmed defects in the source literature, three
+verified, and what is known to be wrong with it. Twenty-two entries are
+documented there: nine confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 
 `DECISIONS.md` records why the package is shaped the way it is, including the

{jerlov-0.9.2 → jerlov-0.9.4}/README.md

@@ -255,6 +255,9 @@ scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
 
 It refuses to go through a layer the paper declared nothing for, rather than
 carrying the last type on: 3C stops at 70 m, 9C at 10 m.
+`jerlov.profile_depth("3C")` says how far a descent can go, and
+`d.transmittance_at(z)` gives any depth above the descent's bottom without
+descending again.
 
 ## Light for photosynthesis
 
@@ -274,6 +277,18 @@ default, because PAR counts photons and an energy spectrum read as photons is
 weighted wrongly with no sign of it. This is planar PAR, from Ed; PAR on
 scalar irradiance is larger by a factor this package cannot supply.
 
+Jerlov measured quanta irradiance, 350-700 nm, by water type, and his
+tables are shipped for checking against:
+
+```python
+jerlov.jerlov1977_quanta("II")   # <QuantaLevels II: 30% 10.5 m, 10% 24 m, 3% 39 m, 1% 52 m; ...>
+```
+
+From II to 3C the package agrees with them within 2 m at every level. For
+Jerlov I it agrees only through `descend`; for IB it puts the 1 percent
+level a third too deep, because Jerlov's IB water grew more turbid below
+15 m. DATA.md section 22.
+
 ## Which type is my water nearest?
 
 ```python
@@ -285,7 +300,9 @@ r.beyond          # "clearer" or "more turbid" than every type, or None
 
 It ranks the types of one edition; it draws no boundaries, since those differ
 between editions. A single wavelength is accepted, and ranks oceanic and
-coastal types less well apart than a spectrum does.
+coastal types less well apart than a spectrum does. `types=` compares with
+some of the types only, which keeps the wavelengths where only the others
+have gaps.
 
 ## Other entry points
 
@@ -359,8 +376,8 @@ 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. Twenty-one entries are
-documented there: eight confirmed defects in the source literature, three
+verified, and what is known to be wrong with it. Twenty-two entries are
+documented there: nine confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 
 `DECISIONS.md` records why the package is shaped the way it is, including the

{jerlov-0.9.2 → jerlov-0.9.4}/jerlov/__init__.py

@@ -23,7 +23,14 @@ from .colour import (
     spectrum_to_xyz,
     xyz_to_srgb,
 )
-from .par import PAR_RANGE_NM, ParProfile, par_profile
+from .par import (
+    PAR_RANGE_NM,
+    QUANTA_BAND_NM,
+    ParProfile,
+    QuantaLevels,
+    jerlov1977_quanta,
+    par_profile,
+)
 from .petzold import PETZOLD_STATIONS, ScatteringFunction, petzold_scattering
 from .scene import (
     AttenuationCoefficients,
@@ -50,6 +57,7 @@ from .water import (
     descend,
     kd_spectrum,
     measured_points,
+    profile_depth,
     pure_water_absorption,
     water,
     water_type_at_depth,
@@ -75,12 +83,16 @@ __all__ = [
     "water",
     "water_type_at_depth",
     "descend",
+    "profile_depth",
     "Descent",
     "classify_kd",
     "KdClassification",
     "par_profile",
     "ParProfile",
     "PAR_RANGE_NM",
+    "jerlov1977_quanta",
+    "QuantaLevels",
+    "QUANTA_BAND_NM",
     "pure_water_absorption",
     "petzold_scattering",
     "PETZOLD_STATIONS",
@@ -104,4 +116,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.9.2"
+__version__ = "0.9.4"

jerlov-0.9.4/jerlov/data/jerlov1977_quanta.csv

@@ -0,0 +1,203 @@
+table,water_type,depth_top_m,depth_bottom_m,percent_top,percent_bottom,value,unit,status,note
+2,I,19,19,30,30,19,m,ok,
+2,I,49,49,10,10,49,m,ok,
+2,I,79,79,3,3,79,m,ok,
+2,I,103,103,1,1,103,m,ok,
+2n,I,,,30,30,0.39,z/z(10),ok,
+2n,I,,,3,3,1.65,z/z(10),suspect,"does not follow from the depths in Table 2, even allowing for rounding (DATA.md section 22)"
+2n,I,,,1,1,2.15,z/z(10),suspect,"does not follow from the depths in Table 2, even allowing for rounding (DATA.md section 22)"
+3,I,0,0,,,100,percent,ok,
+3,I,2,2,,,79,percent,ok,
+3,I,5,5,,,64,percent,ok,
+3,I,10,10,,,46,percent,ok,
+3,I,15,15,,,35.5,percent,ok,
+3,I,20,20,,,29,percent,ok,
+3,I,30,30,,,20,percent,ok,
+3,I,40,40,,,13.7,percent,ok,
+3,I,50,50,,,9.5,percent,ok,
+3,I,60,60,,,6.5,percent,ok,
+3,I,70,70,,,4.3,percent,ok,
+3,I,80,80,,,2.9,percent,ok,
+3,I,90,90,,,1.85,percent,ok,
+3,I,100,100,,,1.14,percent,ok,
+4,I,0,19,100,30,0.063,1/m,ok,
+4,I,19,49,30,10,0.037,1/m,ok,
+4,I,49,79,10,3,0.04,1/m,ok,
+4,I,79,103,3,1,0.046,1/m,ok,
+5,I,0,2,,,0.118,1/m,ok,
+5,I,2,5,,,0.073,1/m,ok,
+5,I,5,10,,,0.065,1/m,ok,
+5,I,10,15,,,0.052,1/m,ok,
+5,I,15,20,,,0.04,1/m,ok,
+5,I,20,30,,,0.039,1/m,ok,
+5,I,30,40,,,0.039,1/m,ok,
+5,I,40,50,,,0.037,1/m,ok,
+5,I,50,60,,,0.038,1/m,ok,
+5,I,60,70,,,0.04,1/m,ok,
+5,I,70,80,,,0.04,1/m,ok,
+5,I,80,90,,,0.045,1/m,ok,
+5,I,90,100,,,0.048,1/m,ok,
+2,IA,16.5,16.5,30,30,16.5,m,ok,
+2,IA,41,41,10,10,41,m,ok,
+2,IA,66,66,3,3,66,m,ok,
+2,IA,87,87,1,1,87,m,ok,
+2n,IA,,,30,30,0.4,z/z(10),ok,
+2n,IA,,,3,3,1.66,z/z(10),suspect,"does not follow from the depths in Table 2, even allowing for rounding (DATA.md section 22)"
+2n,IA,,,1,1,2.12,z/z(10),ok,
+3,IA,0,0,,,100,percent,ok,
+3,IA,2,2,,,77,percent,ok,
+3,IA,5,5,,,59,percent,ok,
+3,IA,10,10,,,42,percent,ok,
+3,IA,15,15,,,32,percent,ok,
+3,IA,20,20,,,25.5,percent,ok,
+3,IA,30,30,,,16.4,percent,ok,
+3,IA,40,40,,,10.3,percent,ok,
+3,IA,50,50,,,6.6,percent,ok,
+3,IA,60,60,,,4.1,percent,ok,
+3,IA,70,70,,,2.5,percent,ok,
+3,IA,80,80,,,1.47,percent,ok,
+4,IA,0,16.5,100,30,0.073,1/m,ok,
+4,IA,16.5,41,30,10,0.043,1/m,suspect,"does not follow from the depths in Table 2, even allowing for rounding (DATA.md section 22)"
+4,IA,41,66,10,3,0.048,1/m,ok,
+4,IA,66,87,3,1,0.052,1/m,ok,
+5,IA,0,2,,,0.13,1/m,ok,
+5,IA,2,5,,,0.089,1/m,ok,
+5,IA,5,10,,,0.068,1/m,ok,
+5,IA,10,15,,,0.054,1/m,ok,
+5,IA,15,20,,,0.042,1/m,ok,
+5,IA,20,30,,,0.046,1/m,suspect,"does not follow from the percentages in Table 3, even allowing for rounding (DATA.md section 22)"
+5,IA,30,40,,,0.046,1/m,ok,
+5,IA,40,50,,,0.045,1/m,ok,
+5,IA,50,60,,,0.048,1/m,ok,
+5,IA,60,70,,,0.049,1/m,ok,
+5,IA,70,80,,,0.053,1/m,ok,
+2,IB,14,14,30,30,14,m,ok,
+2,IB,33,33,10,10,33,m,ok,
+2,IB,54,54,3,3,54,m,ok,
+2,IB,70,70,1,1,70,m,ok,
+2n,IB,,,30,30,0.42,z/z(10),ok,
+2n,IB,,,3,3,1.63,z/z(10),ok,
+2n,IB,,,1,1,2.12,z/z(10),ok,
+3,IB,0,0,,,100,percent,ok,
+3,IB,2,2,,,75,percent,ok,
+3,IB,5,5,,,54,percent,ok,
+3,IB,10,10,,,38,percent,ok,
+3,IB,15,15,,,28,percent,ok,
+3,IB,20,20,,,21,percent,ok,
+3,IB,30,30,,,12.0,percent,ok,
+3,IB,40,40,,,6.7,percent,ok,
+3,IB,50,50,,,3.8,percent,ok,
+3,IB,60,60,,,2.0,percent,ok,
+3,IB,70,70,,,1.01,percent,ok,
+4,IB,0,14,100,30,0.086,1/m,ok,
+4,IB,14,33,30,10,0.053,1/m,suspect,"does not follow from the depths in Table 2, even allowing for rounding (DATA.md section 22)"
+4,IB,33,54,10,3,0.057,1/m,ok,
+4,IB,54,70,3,1,0.068,1/m,ok,
+5,IB,0,2,,,0.144,1/m,ok,
+5,IB,2,5,,,0.107,1/m,ok,
+5,IB,5,10,,,0.071,1/m,ok,
+5,IB,10,15,,,0.061,1/m,ok,
+5,IB,15,20,,,0.056,1/m,ok,
+5,IB,20,30,,,0.057,1/m,ok,
+5,IB,30,40,,,0.058,1/m,ok,
+5,IB,40,50,,,0.059,1/m,ok,
+5,IB,50,60,,,0.064,1/m,ok,
+5,IB,60,70,,,0.069,1/m,ok,
+2,II,10.5,10.5,30,30,10.5,m,ok,
+2,II,24,24,10,10,24,m,ok,
+2,II,39,39,3,3,39,m,ok,
+2,II,52,52,1,1,52,m,ok,
+2n,II,,,30,30,0.44,z/z(10),ok,
+2n,II,,,3,3,1.63,z/z(10),ok,
+2n,II,,,1,1,2.17,z/z(10),ok,
+3,II,0,0,,,100,percent,ok,
+3,II,2,2,,,70,percent,ok,
+3,II,5,5,,,48,percent,ok,
+3,II,10,10,,,32,percent,ok,
+3,II,15,15,,,21,percent,ok,
+3,II,20,20,,,14.2,percent,ok,
+3,II,30,30,,,6.4,percent,ok,
+3,II,40,40,,,2.8,percent,ok,
+3,II,50,50,,,1.23,percent,ok,
+4,II,0,10.5,100,30,0.114,1/m,ok,
+4,II,10.5,24,30,10,0.082,1/m,ok,
+4,II,24,39,10,3,0.08,1/m,ok,
+4,II,39,52,3,1,0.084,1/m,ok,
+5,II,0,2,,,0.178,1/m,ok,
+5,II,2,5,,,0.126,1/m,ok,
+5,II,5,10,,,0.099,1/m,suspect,"does not follow from the percentages in Table 3, even allowing for rounding (DATA.md section 22)"
+5,II,10,15,,,0.084,1/m,ok,
+5,II,15,20,,,0.078,1/m,ok,
+5,II,20,30,,,0.08,1/m,ok,
+5,II,30,40,,,0.082,1/m,ok,
+5,II,40,50,,,0.082,1/m,ok,
+2,III,6.5,6.5,30,30,6.5,m,ok,
+2,III,14,14,10,10,14,m,ok,
+2,III,23,23,3,3,23,m,ok,
+2,III,31,31,1,1,31,m,ok,
+2n,III,,,30,30,0.46,z/z(10),ok,
+2n,III,,,3,3,1.64,z/z(10),ok,
+2n,III,,,1,1,2.21,z/z(10),ok,
+3,III,0,0,,,100,percent,ok,
+3,III,2,2,,,63,percent,ok,
+3,III,5,5,,,38,percent,ok,
+3,III,10,10,,,17.5,percent,ok,
+3,III,15,15,,,8.5,percent,ok,
+3,III,20,20,,,4.6,percent,ok,
+3,III,30,30,,,1.22,percent,ok,
+4,III,0,6.5,100,30,0.185,1/m,ok,
+4,III,6.5,14,30,10,0.146,1/m,ok,
+4,III,14,23,10,3,0.134,1/m,ok,
+4,III,23,31,3,1,0.137,1/m,ok,
+5,III,0,2,,,0.23,1/m,ok,
+5,III,2,5,,,0.169,1/m,ok,
+5,III,5,10,,,0.155,1/m,ok,
+5,III,10,15,,,0.144,1/m,ok,
+5,III,15,20,,,0.123,1/m,ok,
+5,III,20,30,,,0.134,1/m,ok,
+2,1C,5.3,5.3,30,30,5.3,m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2,1C,12,12,10,10,12,m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2,1C,20,20,3,3,20,m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2,1C,27,27,1,1,27,m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2n,1C,,,30,30,0.44,z/z(10),ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2n,1C,,,3,3,1.67,z/z(10),ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2n,1C,,,1,1,2.25,z/z(10),ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,0,0,,,100,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,2,2,,,54,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,5,5,,,30,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,10,10,,,13.3,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,15,15,,,6.0,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,20,20,,,3.0,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+3,1C,30,30,,,0.65,percent,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+4,1C,0,5.3,100,30,0.227,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+4,1C,5.3,12,30,10,0.164,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+4,1C,12,20,10,3,0.15,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+4,1C,20,27,3,1,0.157,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+5,1C,0,2,,,0.31,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+5,1C,2,5,,,0.196,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+5,1C,5,10,,,0.163,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+5,1C,10,15,,,0.154,1/m,suspect,"does not follow from the percentages in Table 3, even allowing for rounding (DATA.md section 22)"
+5,1C,15,20,,,0.14,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+5,1C,20,30,,,0.153,1/m,ok,printed as coastal type '1'; written 1C here as elsewhere in this package
+2,3C,3.7,3.7,30,30,3.7,m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+2,3C,8.5,8.5,10,10,8.5,m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+2,3C,14,14,3,3,14,m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+2,3C,19,19,1,1,19,m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+2n,3C,,,30,30,0.44,z/z(10),ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+2n,3C,,,3,3,1.65,z/z(10),ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+2n,3C,,,1,1,2.23,z/z(10),ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+3,3C,0,0,,,100,percent,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+3,3C,2,2,,,44,percent,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+3,3C,5,5,,,21,percent,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+3,3C,10,10,,,7.0,percent,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+3,3C,15,15,,,2.3,percent,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+3,3C,20,20,,,0.73,percent,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+4,3C,0,3.7,100,30,0.325,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+4,3C,3.7,8.5,30,10,0.229,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+4,3C,8.5,14,10,3,0.218,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+4,3C,14,19,3,1,0.22,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+5,3C,0,2,,,0.41,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+5,3C,2,5,,,0.25,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+5,3C,5,10,,,0.22,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+5,3C,10,15,,,0.22,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package
+5,3C,15,20,,,0.23,1/m,ok,printed as coastal type '3'; written 3C here as elsewhere in this package

{jerlov-0.9.2 → jerlov-0.9.4}/jerlov/par.py

@@ -27,10 +27,19 @@ Three things are stated rather than hidden:
 
 from __future__ import annotations
 
+import warnings
+from dataclasses import dataclass
+
 import numpy as np
 
 from . import _data
-from .water import Descent, MissingQuantityError, Water, _require_number, water
+from .water import (
+    Descent,
+    MissingQuantityError,
+    ProvenanceWarning,
+    Water,
+    _require_number,
+)
 
 #: Planck constant (J s), speed of light (m/s) and Avogadro constant (1/mol),
 #: exact by the 2019 definition of the SI.
@@ -241,18 +250,20 @@ def par_profile(surface_downwelling, wavelengths, depths_m, *, kd,
                 f"the descent stops at {deepest:g} m, above the deepest depth "
                 f"asked for ({depths.max():g} m)"
             )
-        layers = [(top, bottom, water(t, kd.source).kd(sub_wl))
-                  for top, bottom, t in kd.layers]
+        if len(kd._kd) != len(kd.layers):
+            raise MissingQuantityError(
+                "this Descent was not made by descend(), so it does not "
+                "carry the Kd of its layers"
+            )
         kd_from = (f"a descent from Jerlov {kd.surface_water_type} "
                    f"({kd.source})")
+        descent = kd
 
         def optical_depth(z):
-            total = np.zeros_like(sub_wl)
-            for top, bottom, values in layers:
-                total += values * min(max(z - top, 0.0), bottom - top)
-            return total
+            # The descent's own layers, on the samples PAR rests on only.
+            return descent._optical_depth(z, near)
 
-        kd_values = (np.vstack([v for _, _, v in layers]) if layers
+        kd_values = (np.vstack([v[near] for v in kd._kd]) if kd._kd
                      else np.zeros_like(sub_wl))
     else:
         if isinstance(kd, Water):
@@ -291,3 +302,111 @@ def par_profile(surface_downwelling, wavelengths, depths_m, *, kd,
         return np.interp(band, sub_wl, optical_depth(z))
 
     return ParProfile(depths, band, surface_q, tau, deepest, kd_from)
+
+
+QUANTA_BAND_NM = (350.0, 700.0)
+"""The waveband of Jerlov's quanta meters, nm. Not that of PAR."""
+
+
+@dataclass(frozen=True, eq=False, repr=False)
+class QuantaLevels:
+    """Jerlov's measured profiles of quanta irradiance for one water type.
+
+    Built by :func:`jerlov1977_quanta`. Every depth is in m, every
+    coefficient in 1/m, and the band is 350-700 nm, :data:`QUANTA_BAND_NM`,
+    not the 400-700 nm of :func:`par_profile`.
+    """
+
+    water_type: str
+    level_percent: tuple[float, ...]
+    """30, 10, 3 and 1: the levels of Table 2."""
+    level_depth_m: np.ndarray
+    """The depth of each level, Table 2."""
+    profile_depth_m: np.ndarray
+    """Table 3's depths, as far as the table goes for this type."""
+    profile_percent: np.ndarray
+    """Percent of surface quanta at :attr:`profile_depth_m`, Table 3."""
+    layer_m: tuple[tuple[float, float], ...]
+    """``(top, bottom)`` of each layer of Table 5."""
+    layer_kd: np.ndarray
+    """Kd for quanta in each layer, Table 5."""
+    suspect: tuple[str, ...]
+    """The layers of :attr:`layer_kd` whose printed Kd does not follow from
+    Table 3, even allowing for rounding; DATA.md section 22."""
+
+    def __repr__(self) -> str:
+        levels = ", ".join(f"{p:g}% {z:g} m" for p, z in
+                           zip(self.level_percent, self.level_depth_m))
+        flag = f"; {len(self.suspect)} suspect" if self.suspect else ""
+        return f"<QuantaLevels {self.water_type}: {levels}{flag}>"
+
+
+def jerlov1977_quanta(water_type: str) -> QuantaLevels:
+    """Jerlov's measured quanta irradiance, 350-700 nm, by water type.
+
+    From profiles measured with quanta meters in fourteen regions, Jerlov
+    tabulated the depth at which 30, 10, 3 and 1 percent of the surface
+    quanta remain (Table 2), the percentage at depth (Table 3) and Kd for
+    quanta layer by layer (Table 5), for types I, IA, IB, II, III, 1C and 3C.
+    They are measurements, so they are what to compare :func:`par_profile`
+    against; DATA.md section 22 does, and finds agreement within 2 m at
+    every level from II to 3C, and a 1 percent depth 33 percent too deep
+    for IB.
+
+    Jerlov, N. G., "Classification of sea water in terms of quanta
+    irradiance", J. Cons. int. Explor. Mer 37(3), 281-287.
+
+    Notes
+    -----
+    The band is 350-700 nm, wider than PAR's. The profiles are of real
+    water at real stations, so they include whatever changed with depth
+    there; Jerlov says so himself (p. 286). Three of the Kd values in Table
+    5 do not follow from Table 3, even allowing for rounding: for IA, II
+    and 1C, one layer each. They are listed in :attr:`QuantaLevels.suspect`,
+    and asking for those types warns. Table 2's normalised column and Table
+    4, which have five more such values, are in the shipped table
+    ``jerlov1977_quanta.csv`` but not returned here, since both follow from
+    the depths that are.
+    """
+    rows = [r for r in _data._rows("jerlov1977_quanta.csv")
+            if r["water_type"] == water_type]
+    if not rows:
+        known = []
+        for r in _data._rows("jerlov1977_quanta.csv"):
+            if r["water_type"] not in known:
+                known.append(r["water_type"])
+        raise KeyError(f"Jerlov's quanta tables have no water type "
+                       f"{water_type!r} (known: {', '.join(known)})")
+
+    def table(name):
+        return [r for r in rows if r["table"] == name]
+
+    layers = table("5")
+    suspect = tuple(
+        f"Kd {r['value']} 1/m at {r['depth_top_m']}-{r['depth_bottom_m']} m"
+        for r in layers if r["status"] in _data.QUESTIONABLE
+    )
+    if suspect:
+        warnings.warn(
+            f"Jerlov's Table 5 for {water_type} prints a Kd that does not "
+            f"follow from his Table 3: " + "; ".join(suspect)
+            + ". See DATA.md section 22.",
+            ProvenanceWarning,
+            stacklevel=_data.caller_stacklevel(),
+        )
+    levels = table("2")
+    profile = table("3")
+    return QuantaLevels(
+        water_type=water_type,
+        level_percent=tuple(float(r["percent_top"]) for r in levels),
+        level_depth_m=_data._frozen(np.array([float(r["value"])
+                                              for r in levels])),
+        profile_depth_m=_data._frozen(np.array([float(r["depth_top_m"])
+                                                for r in profile])),
+        profile_percent=_data._frozen(np.array([float(r["value"])
+                                                for r in profile])),
+        layer_m=tuple((float(r["depth_top_m"]), float(r["depth_bottom_m"]))
+                      for r in layers),
+        layer_kd=_data._frozen(np.array([float(r["value"]) for r in layers])),
+        suspect=suspect,
+    )

{jerlov-0.9.2 → jerlov-0.9.4}/jerlov/water.py

@@ -9,7 +9,7 @@ same path.
 from __future__ import annotations
 
 import warnings
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 import numpy as np
 
@@ -579,8 +579,8 @@ class KdClassification:
         )
 
 
-def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
-                ) -> KdClassification:
+def classify_kd(wavelengths, kd, *, source: str = "jerlov1976",
+                types=None) -> KdClassification:
     """Find the Jerlov type whose Kd spectrum a measured one is closest to.
 
     Every type of ``source`` is compared with the measurement at the given
@@ -600,6 +600,12 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
     source:
         A source carrying Kd: ``"jerlov1976"`` (the default, all ten types),
         ``"jerlov1968"``, ``"austin1986"`` or ``"solonenko2015"``.
+    types:
+        The types to compare with, if not all of ``source``'s; the oceanic
+        ones, say, for a measurement made offshore. A wavelength is left
+        out wherever any compared type has no Kd, so leaving out types with
+        gaps keeps more wavelengths: Solonenko & Mobley's 3C and 5C have
+        none from 600 nm on.
 
     Notes
     -----
@@ -625,7 +631,24 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
         # were a gap, leaving the other wavelengths to decide alone.
         raise ValueError("Kd must be positive and finite (NaN marks a gap)")
 
-    waters = {t: water(t, source) for t in src.water_types}
+    if types is None:
+        compared = src.water_types
+    else:
+        # One type given as a string is one type: tuple("III") would be
+        # three of type "I".
+        compared = (types,) if isinstance(types, str) else tuple(types)
+        unknown = [t for t in compared if t not in src.water_types]
+        if unknown:
+            raise KeyError(
+                f"source {source!r} does not cover Jerlov "
+                f"{', '.join(map(repr, unknown))} "
+                f"(available: {', '.join(src.water_types)})"
+            )
+        if not compared:
+            raise ValueError("types must name at least one water type")
+        if len(set(compared)) != len(compared):
+            raise ValueError("types names a water type more than once")
+    waters = {t: water(t, source) for t in compared}
     # Raises for a wavelength outside the source's range. The flags are
     # checked below, once, on the wavelengths actually compared: ten
     # warnings for one comparison would bury the one that matters.
@@ -637,7 +660,7 @@ def classify_kd(wavelengths, kd, *, source: str = "jerlov1976"
     if not usable.any():
         raise MissingQuantityError(
             "no wavelength has both a measured Kd and a Kd for every type "
-            f"of {source!r}"
+            f"compared from {source!r}"
         )
     by_flags: dict[str, list[str]] = {}
     for water_type, w in waters.items():
@@ -699,6 +722,58 @@ class Descent:
     last stops at ``depth_m``."""
     transmittance: np.ndarray
     """``Ed(depth) / Ed(0)``: ``exp(-sum(Kd_i * thickness_i))``."""
+    _kd: tuple[np.ndarray, ...] = field(default=(), repr=False)
+    """The Kd of each layer in :attr:`layers`, on :attr:`wavelengths`."""
+
+    def _optical_depth(self, depth: float, columns=slice(None)) -> np.ndarray:
+        """``sum(Kd_i * thickness_i)`` from the surface to ``depth``.
+
+        ``columns`` picks wavelengths, so that a caller using only some of
+        them, as PAR does, never touches the rest.
+        """
+        total = np.zeros(np.size(self.wavelengths))[columns]
+        for (top, bottom, _), values in zip(self.layers, self._kd):
+            total = total + values[columns] * min(max(depth - top, 0.0),
+                                                  bottom - top)
+        return total
+
+    def transmittance_at(self, depth_m):
+        """``Ed(z) / Ed(0)`` at any depth from the surface to :attr:`depth_m`.
+
+        Uses the layers already crossed, so it is what :func:`descend` to
+        that depth would give, without calling it again. A single depth
+        gives an array on :attr:`wavelengths` (a float if the descent was
+        asked for at one wavelength); an array of depths gives one row per
+        depth.
+
+        Raises
+        ------
+        MissingQuantityError
+            Below :attr:`depth_m`. Descend further, if the profile allows:
+            see :func:`profile_depth`.
+        """
+        if len(self._kd) != len(self.layers):
+            # Only descend() records the Kd of each layer; without it every
+            # depth would come back as 1, looking like perfectly clear water.
+            raise MissingQuantityError(
+                "this Descent was not made by descend(), so it does not "
+                "carry the Kd of its layers"
+            )
+        depths = np.asarray(depth_m, dtype=float)
+        if not np.all(np.isfinite(depths)):
+            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")
+        if np.any(depths > self.depth_m):
+            raise MissingQuantityError(
+                f"this descent stops at {self.depth_m:g} m, above "
+                f"{depths.max():g} m; descend further to go deeper"
+            )
+        out = np.array([np.exp(-self._optical_depth(float(z)))
+                        for z in depths.ravel()])
+        if depths.ndim == 0:
+            return _like_input(out[0], self.transmittance)
+        return out.reshape(depths.shape + (np.size(self.wavelengths),))
 
     def __repr__(self) -> str:
         # Adjacent 10 m layers of one type are shown as one span.
@@ -808,7 +883,38 @@ def descend(surface_water_type: str, depth_m: float, wavelengths, *,
         wavelengths=query,
         layers=tuple(layers),
         transmittance=_like_input(np.exp(-optical_depth), wavelengths),
+        _kd=tuple(_frozen_copy(kd[t]) for _, _, t in layers),
+    )
+
+
+def _frozen_copy(values: np.ndarray) -> np.ndarray:
+    out = np.array(values, dtype=float)
+    out.setflags(write=False)
+    return out
+
+
+def profile_depth(surface_water_type: str) -> float:
+    """How deep :func:`descend` can go below ``surface_water_type``, in m.
+
+    The top of the first layer for which Williamson & Hollins (2023)
+    declared no type, or 200 m, where their profile ends. Coastal types run
+    out early: 9C at 10 m, 5C and 7C at 20 m, 3C at 70 m.
+
+    ::
+
+        d = jerlov.descend("3C", jerlov.profile_depth("3C"), wl)   # to 70 m
+    """
+    rows = sorted(
+        (r for r in _data._rows("williamson2023_depth.csv")
+         if r["surface_water_type"] == surface_water_type),
+        key=lambda r: float(r["depth_min_m"]),
     )
+    if not rows:
+        water_type_at_depth(surface_water_type, 0.0)   # raises, naming types
+    for row in rows:
+        if not row["water_type"]:
+            return float(row["depth_min_m"])
+    return float(rows[-1]["depth_max_m"])
 
 
 #: Why each source without a pure water absorption has none.

{jerlov-0.9.2 → jerlov-0.9.4/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.9.2
+Version: 0.9.4
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -285,6 +285,9 @@ scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
 
 It refuses to go through a layer the paper declared nothing for, rather than
 carrying the last type on: 3C stops at 70 m, 9C at 10 m.
+`jerlov.profile_depth("3C")` says how far a descent can go, and
+`d.transmittance_at(z)` gives any depth above the descent's bottom without
+descending again.
 
 ## Light for photosynthesis
 
@@ -304,6 +307,18 @@ default, because PAR counts photons and an energy spectrum read as photons is
 weighted wrongly with no sign of it. This is planar PAR, from Ed; PAR on
 scalar irradiance is larger by a factor this package cannot supply.
 
+Jerlov measured quanta irradiance, 350-700 nm, by water type, and his
+tables are shipped for checking against:
+
+```python
+jerlov.jerlov1977_quanta("II")   # <QuantaLevels II: 30% 10.5 m, 10% 24 m, 3% 39 m, 1% 52 m; ...>
+```
+
+From II to 3C the package agrees with them within 2 m at every level. For
+Jerlov I it agrees only through `descend`; for IB it puts the 1 percent
+level a third too deep, because Jerlov's IB water grew more turbid below
+15 m. DATA.md section 22.
+
 ## Which type is my water nearest?
 
 ```python
@@ -315,7 +330,9 @@ r.beyond          # "clearer" or "more turbid" than every type, or None
 
 It ranks the types of one edition; it draws no boundaries, since those differ
 between editions. A single wavelength is accepted, and ranks oceanic and
-coastal types less well apart than a spectrum does.
+coastal types less well apart than a spectrum does. `types=` compares with
+some of the types only, which keeps the wavelengths where only the others
+have gaps.
 
 ## Other entry points
 
@@ -389,8 +406,8 @@ 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. Twenty-one entries are
-documented there: eight confirmed defects in the source literature, three
+verified, and what is known to be wrong with it. Twenty-two entries are
+documented there: nine confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 
 `DECISIONS.md` records why the package is shaped the way it is, including the

{jerlov-0.9.2 → jerlov-0.9.4}/jerlov.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ jerlov/data/cie_d65.csv
 jerlov/data/jerlov1968_kd.csv
 jerlov/data/jerlov1968_total_irradiance.csv
 jerlov/data/jerlov1976_kd.csv
+jerlov/data/jerlov1977_quanta.csv
 jerlov/data/paulson1977_shortwave.csv
 jerlov/data/petzold1972_stations.csv
 jerlov/data/petzold1972_vsf.csv
@@ -44,6 +45,7 @@ tests/test_depth.py
 tests/test_packaging.py
 tests/test_par.py
 tests/test_petzold.py
+tests/test_quanta.py
 tests/test_quoted_figures.py
 tests/test_reproduces_papers.py
 tests/test_scene.py

{jerlov-0.9.2 → jerlov-0.9.4}/pyproject.toml

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

{jerlov-0.9.2 → jerlov-0.9.4}/tests/test_classify.py

@@ -89,3 +89,33 @@ def test_what_cannot_be_compared_is_refused():
         jerlov.classify_kd(WL, [0.05])
     with pytest.raises(jerlov.MissingQuantityError, match="no wavelength"):
         jerlov.classify_kd([500.0], [np.nan])
+
+
+def test_types_narrows_the_comparison_and_keeps_more_wavelengths():
+    """Solonenko & Mobley's 3C and 5C have no Kd from 600 nm on, which
+    took those wavelengths out of every comparison."""
+    wl = np.arange(400.0, 701.0, 25.0)
+    oceanic = ("I", "IA", "IB", "II", "III")
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", jerlov.ProvenanceWarning)
+        kd = jerlov.water("II", source="solonenko2015").kd(wl)
+        every = jerlov.classify_kd(wl, kd, source="solonenko2015")
+        some = jerlov.classify_kd(wl, kd, source="solonenko2015",
+                                  types=oceanic)
+    assert every.excluded_nm == (600.0, 625.0, 650.0, 675.0, 700.0)
+    assert some.excluded_nm == ()
+    assert some.water_type == "II"
+    assert {t for t, _ in some.distances} == set(oceanic)
+
+
+def test_types_must_be_types_of_the_source():
+    with pytest.raises(KeyError, match="does not cover Jerlov '3C'"):
+        jerlov.classify_kd(WL, _kd("II"), source="austin1986",
+                           types=("II", "IA", "3C"))
+    with pytest.raises(ValueError, match="at least one"):
+        jerlov.classify_kd(WL, _kd("II"), types=())
+    with pytest.raises(ValueError, match="more than once"):
+        jerlov.classify_kd(WL, _kd("II"), types=("II", "II"))
+    # A string is one type, not a sequence of letters.
+    alone = jerlov.classify_kd(WL, _kd("III"), types="III")
+    assert alone.distances == (("III", 0.0),)

{jerlov-0.9.2 → jerlov-0.9.4}/tests/test_depth.py

@@ -190,3 +190,50 @@ def test_a_descent_prints_its_path_not_its_arrays():
                     "Kd from jerlov1976; 301 wavelengths>")
     assert repr(jerlov.descend("II", 0.0, 500.0)).startswith(
         "<Descent II to 0 m: no layer crossed;")
+
+
+def test_profile_depth_is_where_descend_stops():
+    """Three examples searched for this by trying descend() every 10 m."""
+    expected = {"I": 200.0, "IB": 200.0, "III": 170.0, "1C": 110.0,
+                "3C": 70.0, "5C": 20.0, "7C": 20.0, "9C": 10.0}
+    for water_type, depth in expected.items():
+        assert jerlov.profile_depth(water_type) == depth
+        jerlov.descend(water_type, depth, 500.0)         # reaches it
+        with pytest.raises(jerlov.MissingQuantityError):
+            jerlov.descend(water_type, depth + 0.1, 500.0)
+    with pytest.raises(KeyError, match="known"):
+        jerlov.profile_depth("XI")
+
+
+def test_transmittance_at_is_a_shorter_descent():
+    wl = np.arange(400.0, 701.0, 10.0)
+    d = jerlov.descend("1C", 45.0, wl)
+    for z in (0.0, 7.5, 10.0, 20.0, 33.3, 45.0):
+        assert d.transmittance_at(z) == pytest.approx(
+            jerlov.descend("1C", z, wl).transmittance, rel=1e-12)
+    rows = d.transmittance_at([[0.0, 10.0], [20.0, 45.0]])
+    assert rows.shape == (2, 2, wl.size)
+    assert rows[1, 1] == pytest.approx(d.transmittance)
+    one = jerlov.descend("II", 30.0, 500.0)
+    assert isinstance(one.transmittance_at(12.0), float)
+    assert one.transmittance_at(12.0) == jerlov.descend("II", 12.0, 500.0).transmittance
+
+
+def test_transmittance_at_refuses_what_the_descent_does_not_cover():
+    d = jerlov.descend("I", 30.0, [450.0, 550.0])
+    with pytest.raises(jerlov.MissingQuantityError, match="stops at 30 m"):
+        d.transmittance_at(31.0)
+    for bad in (-1.0, float("nan"), float("inf")):
+        with pytest.raises(ValueError):
+            d.transmittance_at(bad)
+    # A Descent built by hand has no layer Kd; it must not look clear.
+    hand = jerlov.Descent("I", 30.0, "jerlov1976", d.wavelengths, d.layers,
+                          d.transmittance)
+    with pytest.raises(jerlov.MissingQuantityError, match="descend"):
+        hand.transmittance_at(10.0)
+    with pytest.raises(jerlov.MissingQuantityError, match="descend"):
+        jerlov.par_profile(np.ones(301), np.arange(400.0, 701.0), 0.0,
+                           kd=jerlov.Descent("I", 30.0, "jerlov1976",
+                                             np.arange(400.0, 701.0),
+                                             d.layers, np.ones(301)),
+                           unit="photons")

{jerlov-0.9.2 → jerlov-0.9.4}/tests/test_packaging.py

@@ -389,3 +389,29 @@ def test_the_READMEs_count_the_examples():
         for script in (ROOT / "examples").glob("*.py"):
             assert script.name in readme.read_text(), (
                 f"{readme.relative_to(ROOT)} never mentions {script.name}")
+
+
+@source_tree
+def test_the_tests_read_the_installed_tables_not_the_source_tree():
+    """The suite is also run against the wheel, where there is no
+    jerlov/data/ beside the tests. test_petzold.py read it from there, and
+    the first run against a wheel failed."""
+    offenders = []
+    for path in (ROOT / "tests").glob("test_*.py"):
+        if path.name == "test_packaging.py":
+            continue
+        if re.search(r'"jerlov"\s*/\s*"data"', path.read_text()):
+            offenders.append(path.name)
+    assert not offenders, (
+        f"{offenders} read tables from the source tree; use "
+        "importlib.resources.files('jerlov.data')"
+    )
+
+
+@source_tree
+def test_publishing_checks_the_tag_and_runs_the_suite_on_the_wheel():
+    workflow = (ROOT / ".github" / "workflows" / "publish.yml").read_text()
+    assert "GITHUB_REF_NAME" in workflow and "pyproject.toml" in workflow, (
+        "publish.yml no longer compares the tag with the version")
+    assert "pytest wheel-tests" in workflow, (
+        "publish.yml no longer runs the tests against the installed wheel")

{jerlov-0.9.2 → jerlov-0.9.4}/tests/test_petzold.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import csv
 import re
+from importlib import resources
 import warnings
 from pathlib import Path
 
@@ -18,7 +19,9 @@ ROOT = Path(__file__).resolve().parent.parent
 
 
 def _table(station):
-    path = ROOT / "jerlov" / "data" / "petzold1972_vsf.csv"
+    # The installed package's own copy, not the source tree's: the suite is
+    # also run against the wheel, where there is no source tree to read.
+    path = resources.files("jerlov.data").joinpath("petzold1972_vsf.csv")
     with path.open(encoding="utf-8") as handle:
         return [r for r in csv.DictReader(handle) if r["station"] == station]
 

jerlov-0.9.4/tests/test_quanta.py

@@ -0,0 +1,168 @@
+"""Jerlov's measured quanta irradiance, and the package checked against it.
+
+The tables are transcribed in tools/build_jerlov1977.py, which also checks
+them against each other. Here: that they are read back as printed, and the
+comparison DATA.md section 22 makes between them and what `descend` and
+Jerlov's (1976) Kd predict.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+
+import numpy as np
+import pytest
+
+import jerlov
+from jerlov._data import trapezoid
+
+TYPES = ("I", "IA", "IB", "II", "III", "1C", "3C")
+BAND = np.arange(350.0, 701.0, 5.0)          # Jerlov's quanta band
+PHOTONS = np.interp(BAND, *jerlov.d65()) * BAND
+
+
+def _quanta(water_type):
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", jerlov.ProvenanceWarning)
+        return jerlov.jerlov1977_quanta(water_type)
+
+
+def _level_depths(transmittance_at, deepest):
+    """Depths of 30, 10, 3 and 1 percent of surface quanta, 350-700 nm."""
+    surface = trapezoid(PHOTONS, BAND)
+
+    def fraction(z):
+        return trapezoid(PHOTONS * transmittance_at(z), BAND) / surface
+
+    out = []
+    for level in (0.30, 0.10, 0.03, 0.01):
+        low, high = 0.0, deepest
+        if fraction(high) > level:
+            out.append(None)
+            continue
+        for _ in range(60):
+            middle = 0.5 * (low + high)
+            if fraction(middle) > level:
+                low = middle
+            else:
+                high = middle
+        out.append(0.5 * (low + high))
+    return out
+
+
+def _one_kd(water_type):
+    kd = jerlov.water(water_type, source="jerlov1976").kd(BAND)
+    return _level_depths(lambda z: np.exp(-kd * z), 1000.0)
+
+
+def _layered(water_type):
+    d = jerlov.descend(water_type, jerlov.profile_depth(water_type), BAND)
+    return _level_depths(d.transmittance_at, d.depth_m)
+
+
+# -- the tables as printed ---------------------------------------------------
+
+def test_table_2_is_read_back_as_printed():
+    q = _quanta("I")
+    assert q.level_percent == (30.0, 10.0, 3.0, 1.0)
+    assert q.level_depth_m.tolist() == [19, 49, 79, 103]
+    assert _quanta("3C").level_depth_m.tolist() == [3.7, 8.5, 14, 19]
+    assert repr(_quanta("II")) == (
+        "<QuantaLevels II: 30% 10.5 m, 10% 24 m, 3% 39 m, 1% 52 m; "
+        "1 suspect>")
+
+
+def test_tables_3_and_5_go_as_deep_as_the_paper():
+    q = _quanta("I")
+    assert q.profile_depth_m[-1] == 100 and q.profile_percent[-1] == 1.14
+    assert q.layer_m[-1] == (90.0, 100.0) and q.layer_kd[-1] == 0.048
+    q = _quanta("3C")
+    assert q.profile_depth_m.tolist() == [0, 2, 5, 10, 15, 20]
+    assert len(q.layer_kd) == 5
+    for array in (q.level_depth_m, q.profile_percent, q.layer_kd):
+        with pytest.raises(ValueError):
+            array[0] = 0.0
+
+
+def test_the_suspect_layers_warn_and_the_others_do_not():
+    for water_type, layer in (("IA", "20.0-30.0"), ("II", "5.0-10.0"),
+                              ("1C", "10.0-15.0")):
+        with pytest.warns(jerlov.ProvenanceWarning, match="Table 5"):
+            q = jerlov.jerlov1977_quanta(water_type)
+        assert len(q.suspect) == 1 and layer.replace(".0", "") in \
+            q.suspect[0].replace(".0", "")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        for water_type in ("I", "IB", "III", "3C"):
+            assert jerlov.jerlov1977_quanta(water_type).suspect == ()
+
+
+def test_an_unknown_type_names_the_known_ones():
+    with pytest.raises(KeyError, match="known: I, IA, IB, II, III, 1C, 3C"):
+        jerlov.jerlov1977_quanta("5C")
+
+
+# -- the package against the measurements: DATA.md section 22 ---------------
+
+def test_from_II_to_3C_one_kd_agrees_within_2_m_at_every_level():
+    for water_type in ("II", "III", "1C", "3C"):
+        model = _one_kd(water_type)
+        printed = _quanta(water_type).level_depth_m
+        assert max(abs(m - p) for m, p in zip(model, printed)) < 2.0, \
+            water_type
+
+
+def test_jerlov_I_needs_the_depth_profile():
+    """One Kd puts the 1 percent level of I at 165 m; Jerlov measured 103;
+    layer by layer it is 106."""
+    assert round(_one_kd("I")[3]) == 165
+    assert round(_layered("I")[3]) == 106
+    assert round(_layered("I")[1]) == 49          # 10 percent: 49 printed
+
+
+def test_IA_and_IB_stay_too_deep():
+    """Layer by layer IA reaches 1 percent at 100 m against 87, and IB at
+    93 m against 70: 15 and 33 percent too deep."""
+    ia, ib = _layered("IA")[3], _layered("IB")[3]
+    assert (round(ia), round(ib)) == (100, 93)
+    assert round(100 * (ia / 87 - 1)) == 15
+    assert round(100 * (ib / 70 - 1)) == 33
+
+
+def test_IB_agrees_in_its_own_10_m_and_departs_below():
+    """Kd for quanta in IB, Jerlov (1976) against Table 5: within 0.004 1/m
+    above 10 m; below 15 m one falls from 0.051 to 0.041, the other rises
+    from 0.056 to 0.069."""
+    kd = jerlov.water("IB", source="jerlov1976").kd(BAND)
+
+    def quanta(z):
+        return trapezoid(PHOTONS * np.exp(-kd * z), BAND)
+
+    q = _quanta("IB")
+    model = np.array([math.log(quanta(a) / quanta(b)) / (b - a)
+                      for a, b in q.layer_m])
+    top = [i for i, (a, b) in enumerate(q.layer_m) if b <= 10]
+    deep = [i for i, (a, b) in enumerate(q.layer_m) if a >= 15]
+    assert np.max(np.abs(model[top] - q.layer_kd[top])) < 0.004
+    assert (round(model[deep[0]], 3),
+            round(model[deep[-1]], 3)) == (0.051, 0.041)
+    assert (q.layer_kd[deep[0]], q.layer_kd[deep[-1]]) == (0.056, 0.069)
+    assert np.all(np.diff(model[deep]) < 0)
+    assert np.all(np.diff(q.layer_kd[deep]) >= 0)
+
+
+def test_DATA_md_figures_for_the_tables_against_each_other():
+    """The recomputed ranges in DATA.md section 22, and integrating Table 5
+    down to 10 m for II gives 29 percent against Table 3's 32."""
+    def ratio_range(z, z10):
+        r = [(z + a) / (z10 + b) for a in (-0.5, 0.5) for b in (-0.5, 0.5)]
+        return f"{min(r):.2f}-{max(r):.2f}"
+    assert ratio_range(79, 49) == "1.59-1.64"
+    assert ratio_range(103, 49) == "2.07-2.13"
+    assert ratio_range(66, 41) == "1.58-1.64"
+    q = _quanta("II")
+    tau = sum(k * (b - a) for (a, b), k in zip(q.layer_m, q.layer_kd)
+              if b <= 10)
+    assert round(100 * math.exp(-tau)) == 29
+    assert q.profile_percent[q.profile_depth_m.tolist().index(10)] == 32