jerlov 0.5.2__tar.gz → 0.7.0__tar.gz

{jerlov-0.5.2/jerlov.egg-info → jerlov-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.5.2
+Version: 0.7.0
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -228,6 +228,28 @@ warns: its quoted spread is **34.8 percent** against 2.6-6.4 from 90 to 160.
 This gives the bb of the water your instrument was in. It still gives no bb
 for a Jerlov water type, because nothing does.
 
+## Measured scattering functions
+
+Without an instrument, the next best thing to a guess is a water that was
+measured. Petzold (1972) measured the volume scattering function from 0.1 to
+180 degrees in eight ocean waters, from the clear Tongue of the Ocean to San
+Diego Harbor:
+
+```python
+jerlov.PETZOLD_STATIONS                  # clearest first: 'AUTEC 8', ..., 'NUC 2040'
+f = jerlov.petzold_scattering("HAOCE 11")
+f.c, f.b, f.backscatter_ratio            # 0.398, 0.21933, 0.013  (1/m, 1/m, bb/b)
+f.vsf_at(120.0)                          # 1/(m sr), at 530 nm
+f.phase_function()                       # vsf / b, at f.angles_deg
+
+w.bb(532, backscatter_ratio=f.backscatter_ratio)   # bb/b of a measured water
+```
+
+The ratio spans **0.013 to 0.044** across the eight. These are eight waters
+on eight days in 1971, at 530 nm, water and particles together; none of them
+is a Jerlov type. Every value was transcribed from the report and checked
+against its own integrals and its second printing; DATA.md section 21.
+
 ## The type changes with depth
 
 The classification is defined on the top 10 m, but clarity does not stay put.
@@ -244,6 +266,18 @@ jerlov.water_type_at_depth("9C", 15.0)    # None: the paper declined to say
 nothing is asserted. This is a lookup, not a correction applied on your
 behalf.
 
+To carry the downwelling irradiance down through that profile, with each 10 m
+layer attenuating by the Kd of its own type:
+
+```python
+d = jerlov.descend("1C", 45.0, wl)        # source="jerlov1976" by default
+d.layers          # ((0, 10, '1C'), (10, 20, '1C'), (20, 30, 'III'), ..., (40, 45, 'II'))
+scene = jerlov.Scene(jerlov.water("II"), surface * d.transmittance, wl, depth_m=45.0)
+```
+
+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.
+
 ## Other entry points
 
 ```python
@@ -257,8 +291,15 @@ jerlov.pure_water_scattering(555)   # Morel's bw, if that is what c was correcte
 # The measured points behind the williamson2022 spectra, with their spread.
 m = jerlov.measured_points("III", "a")   # m.wavelengths, m.values, m.std_dev
 
-# Use your own measurements; they take exactly the same path.
-jerlov.Water.from_measurements(wavelengths, a=..., b=...)
+# The pure water absorption williamson2022 built its a on (300-800 nm).
+jerlov.pure_water_absorption(440)        # 0.0104; other sources say why they have none
+
+# Use your own measurements; they take exactly the same path, flags included.
+w = jerlov.Water.from_measurements(
+    wavelengths, a=..., b=...,
+    flags={"a": statuses},             # "ok", "suspect", ...: as in DATA.md; flagged ones warn
+    uncertainty={"a": sigma_a},        # 1/m; w.uncertainty("a", 532)
+)
 ```
 
 ## Solar heating of the upper ocean
@@ -302,7 +343,7 @@ 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. Nineteen entries are
+verified, and what is known to be wrong with it. Twenty-one entries are
 documented there: eight confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 

{jerlov-0.5.2 → jerlov-0.7.0}/README.md

@@ -203,6 +203,28 @@ warns: its quoted spread is **34.8 percent** against 2.6-6.4 from 90 to 160.
 This gives the bb of the water your instrument was in. It still gives no bb
 for a Jerlov water type, because nothing does.
 
+## Measured scattering functions
+
+Without an instrument, the next best thing to a guess is a water that was
+measured. Petzold (1972) measured the volume scattering function from 0.1 to
+180 degrees in eight ocean waters, from the clear Tongue of the Ocean to San
+Diego Harbor:
+
+```python
+jerlov.PETZOLD_STATIONS                  # clearest first: 'AUTEC 8', ..., 'NUC 2040'
+f = jerlov.petzold_scattering("HAOCE 11")
+f.c, f.b, f.backscatter_ratio            # 0.398, 0.21933, 0.013  (1/m, 1/m, bb/b)
+f.vsf_at(120.0)                          # 1/(m sr), at 530 nm
+f.phase_function()                       # vsf / b, at f.angles_deg
+
+w.bb(532, backscatter_ratio=f.backscatter_ratio)   # bb/b of a measured water
+```
+
+The ratio spans **0.013 to 0.044** across the eight. These are eight waters
+on eight days in 1971, at 530 nm, water and particles together; none of them
+is a Jerlov type. Every value was transcribed from the report and checked
+against its own integrals and its second printing; DATA.md section 21.
+
 ## The type changes with depth
 
 The classification is defined on the top 10 m, but clarity does not stay put.
@@ -219,6 +241,18 @@ jerlov.water_type_at_depth("9C", 15.0)    # None: the paper declined to say
 nothing is asserted. This is a lookup, not a correction applied on your
 behalf.
 
+To carry the downwelling irradiance down through that profile, with each 10 m
+layer attenuating by the Kd of its own type:
+
+```python
+d = jerlov.descend("1C", 45.0, wl)        # source="jerlov1976" by default
+d.layers          # ((0, 10, '1C'), (10, 20, '1C'), (20, 30, 'III'), ..., (40, 45, 'II'))
+scene = jerlov.Scene(jerlov.water("II"), surface * d.transmittance, wl, depth_m=45.0)
+```
+
+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.
+
 ## Other entry points
 
 ```python
@@ -232,8 +266,15 @@ jerlov.pure_water_scattering(555)   # Morel's bw, if that is what c was correcte
 # The measured points behind the williamson2022 spectra, with their spread.
 m = jerlov.measured_points("III", "a")   # m.wavelengths, m.values, m.std_dev
 
-# Use your own measurements; they take exactly the same path.
-jerlov.Water.from_measurements(wavelengths, a=..., b=...)
+# The pure water absorption williamson2022 built its a on (300-800 nm).
+jerlov.pure_water_absorption(440)        # 0.0104; other sources say why they have none
+
+# Use your own measurements; they take exactly the same path, flags included.
+w = jerlov.Water.from_measurements(
+    wavelengths, a=..., b=...,
+    flags={"a": statuses},             # "ok", "suspect", ...: as in DATA.md; flagged ones warn
+    uncertainty={"a": sigma_a},        # 1/m; w.uncertainty("a", 532)
+)
 ```
 
 ## Solar heating of the upper ocean
@@ -277,7 +318,7 @@ 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. Nineteen entries are
+verified, and what is known to be wrong with it. Twenty-one entries are
 documented there: eight confirmed defects in the source literature, three
 questions the first edition of Jerlov settled, and the rest notes.
 

{jerlov-0.5.2 → jerlov-0.7.0}/jerlov/__init__.py

@@ -23,6 +23,7 @@ from .colour import (
     spectrum_to_xyz,
     xyz_to_srgb,
 )
+from .petzold import PETZOLD_STATIONS, ScatteringFunction, petzold_scattering
 from .scene import (
     AttenuationCoefficients,
     Observation,
@@ -37,13 +38,16 @@ from .shortwave import (
 )
 from .sources import SOURCES, Source, get_source
 from .water import (
+    Descent,
     MeasuredPoints,
     MissingQuantityError,
     ProvenanceWarning,
     Water,
     b_from_c,
+    descend,
     kd_spectrum,
     measured_points,
+    pure_water_absorption,
     water,
     water_type_at_depth,
 )
@@ -67,6 +71,12 @@ __all__ = [
     "Water",
     "water",
     "water_type_at_depth",
+    "descend",
+    "Descent",
+    "pure_water_absorption",
+    "petzold_scattering",
+    "PETZOLD_STATIONS",
+    "ScatteringFunction",
     "shortwave_parameters",
     "solar_fraction",
     "jerlov1968_solar_fraction",
@@ -86,4 +96,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.5.2"
+__version__ = "0.7.0"

{jerlov-0.5.2 → jerlov-0.7.0}/jerlov/_data.py

@@ -59,6 +59,10 @@ QUESTIONABLE = frozenset({"suspect", "missing", "extrapolated",
                           "model_extrapolation", "reconstructed",
                           "extrapolated_by_dataset"})
 
+#: Every status a spectrum can carry: the table in DATA.md, "The status
+#: column". A caller's own flags must be one of these.
+STATUSES = QUESTIONABLE | {"ok", "interpolated"}
+
 
 def _read(name: str) -> list[dict[str, str]]:
     path = resources.files("jerlov.data").joinpath(name)

{jerlov-0.5.2 → jerlov-0.7.0}/jerlov/backscattering.py

@@ -57,6 +57,20 @@ class AngleWarning(UserWarning):
     """
 
 
+def _amplitude(wavelength_nm, salinity_psu) -> np.ndarray:
+    """Morel's A(lambda, S), Boss & Pegau Eq. (4), in 1/(m sr)."""
+    salinity = np.asarray(salinity_psu, dtype=float)
+    if not np.all(np.isfinite(salinity)) or np.any(salinity < 0):
+        # A negative salinity made pure water scatter less than fresh water,
+        # without complaint.
+        raise ValueError(
+            f"salinity_psu must be a finite number, 0 or more, not "
+            f"{salinity_psu!r}"
+        )
+    return (1.38 * (np.asarray(wavelength_nm, dtype=float) / 500.0) ** -4.32
+            * (1 + 0.3 * salinity / 37.0) * 1e-4)
+
+
 def _ratio() -> float:
     return (1 - DEPOLARISATION_RATIO) / (1 + DEPOLARISATION_RATIO)
 
@@ -73,8 +87,7 @@ def pure_water_vsf(angle_deg, wavelength_nm, salinity_psu: float = 37.0):
     as the agreement between measurement and theory.
     """
     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)
+    amplitude = _amplitude(wavelength_nm, salinity_psu)
     out = amplitude * (1 + _ratio() * np.cos(np.radians(angle)) ** 2)
     # Angle and wavelength broadcast against each other; the answer is a
     # float only when neither of them was an array.
@@ -90,8 +103,7 @@ def pure_water_backscattering(wavelength_nm, salinity_psu: float = 37.0):
     hemisphere, which for this angular shape is analytic.
     """
     r = _ratio()
-    amplitude = (1.38 * (np.asarray(wavelength_nm, dtype=float) / 500.0) ** -4.32
-                 * (1 + 0.3 * salinity_psu / 37.0) * 1e-4)
+    amplitude = _amplitude(wavelength_nm, salinity_psu)
     # integral of (1 + r cos^2) sin over 90..180 degrees is 1 + r/3
     out = 2.0 * math.pi * amplitude * (1 + r / 3.0)
     return _like_input(np.atleast_1d(out), wavelength_nm)

jerlov-0.7.0/jerlov/data/petzold1972_stations.csv

@@ -0,0 +1,9 @@
+station,locale,date,wavelength_nm,c_per_m,b_per_m,a_per_m,bb_over_b,slope_below_0.1deg,median_angle_deg,report_figure
+AUTEC 7,"Tongue of the Ocean, Bahamas",1971-07-09,530,0.199,0.117,0.082,0.025,-1.599,2.815,23
+AUTEC 8,"Tongue of the Ocean, Bahamas",1971-07-13,530,0.151,0.037,0.114,0.044,-1.191,6.252,25
+AUTEC 9,"Tongue of the Ocean, Bahamas",1971-07-14,530,0.165,0.043,0.122,0.038,-1.248,5.203,27
+HAOCE 5,"Avalon Cove, Catalina Island",1971-07-31,530,0.470,0.275,0.195,0.014,-1.546,2.152,29
+HAOCE 11,"Catalina Channel, offshore southern California",1971-08-05,530,0.398,0.219,0.179,0.013,-1.545,2.534,31
+NUC 2200,San Diego Harbor,1971-10-04,530,1.920,1.583,0.337,0.019,-1.249,4.497,33
+NUC 2040,San Diego Harbor,1971-10-05,530,2.190,1.824,0.366,0.020,-1.346,4.680,35
+NUC 2240,San Diego Harbor,1971-10-05,530,1.330,1.205,0.125,0.018,-1.442,4.682,37