jerlov 0.2.0__tar.gz → 0.2.2__tar.gz

{jerlov-0.2.0/jerlov.egg-info → jerlov-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.2.0
+Version: 0.2.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -257,22 +257,23 @@ rather than substituting a neighbour.
 ## Examples
 
 ```
-python examples/sources_disagree.py
-python examples/synthetic_underwater_images.py
+python examples/sources_disagree.py            why the source is an argument
+python examples/from_one_measurement.py        from an instrument reading
+python examples/synthetic_underwater_images.py appearance at range and depth
+python examples/solar_heating.py               for ocean circulation models
+python examples/what_an_eye_sees.py            any spectral sensitivity
 ```
 
-The first shows why the source is an argument: at 510 nm the scattering
-coefficient of Jerlov III differs by a factor of 3.8 between the two published
-sets. The second synthesises how reflectance patches appear at range and
-depth, white-balanced two ways, and ends with a list of everything it assumed.
-
-Both are run by CI, so an example that has stopped working is a failed build.
+Five scripts, each aimed at a different reader; `examples/README.md` says
+which to start with. CI runs all of them on every push, so an example that has
+stopped working is a failed build. Every one ends with the assumptions it
+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. Fifteen entries are
-documented there: seven confirmed defects in the source literature, three
+verified, and what is known to be wrong with it. Seventeen entries are
+documented there: eight 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.2.0 → jerlov-0.2.2}/README.md

@@ -232,22 +232,23 @@ rather than substituting a neighbour.
 ## Examples
 
 ```
-python examples/sources_disagree.py
-python examples/synthetic_underwater_images.py
+python examples/sources_disagree.py            why the source is an argument
+python examples/from_one_measurement.py        from an instrument reading
+python examples/synthetic_underwater_images.py appearance at range and depth
+python examples/solar_heating.py               for ocean circulation models
+python examples/what_an_eye_sees.py            any spectral sensitivity
 ```
 
-The first shows why the source is an argument: at 510 nm the scattering
-coefficient of Jerlov III differs by a factor of 3.8 between the two published
-sets. The second synthesises how reflectance patches appear at range and
-depth, white-balanced two ways, and ends with a list of everything it assumed.
-
-Both are run by CI, so an example that has stopped working is a failed build.
+Five scripts, each aimed at a different reader; `examples/README.md` says
+which to start with. CI runs all of them on every push, so an example that has
+stopped working is a failed build. Every one ends with the assumptions it
+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. Fifteen entries are
-documented there: seven confirmed defects in the source literature, three
+verified, and what is known to be wrong with it. Seventeen entries are
+documented there: eight 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.2.0 → jerlov-0.2.2}/jerlov/__init__.py

@@ -64,4 +64,4 @@ __all__ = [
     "MissingQuantityError",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{jerlov-0.2.0 → jerlov-0.2.2}/jerlov/colour.py

@@ -151,15 +151,18 @@ def integrate_response(spectrum, wavelengths, response, response_wavelengths,
     if wavelengths.size < 2:
         raise ValueError("at least two wavelengths are needed to integrate")
 
-    worst = min(
-        _coverage(wavelengths, response_wavelengths, response[:, k])
-        for k in range(response.shape[1])
-    )
+    covered = [_coverage(wavelengths, response_wavelengths, response[:, k])
+               for k in range(response.shape[1])]
+    worst = min(covered)
     if worst < 0.999:
+        which = (f"channel {covered.index(worst)} of {len(covered)}"
+                 if len(covered) > 1 else "it")
         warnings.warn(
-            f"the spectrum spans {wavelengths[0]:g}-{wavelengths[-1]:g} nm and "
-            f"covers only {worst:.1%} of the {name}; the integral is over the "
-            "overlap and is biased by what was left out",
+            f"the spectrum spans {wavelengths[0]:g}-{wavelengths[-1]:g} nm; "
+            f"of the {name}, {which} is only {worst:.1%} covered "
+            f"(all channels: {', '.join(f'{c:.1%}' for c in covered)}). "
+            "The integral is over the overlap and is biased by what was left "
+            "out",
             CoverageWarning,
             stacklevel=2,
         )

{jerlov-0.2.0 → jerlov-0.2.2}/jerlov/water.py

@@ -131,11 +131,18 @@ class Water:
         values = self._series[quantity]
         out = np.interp(query, self.wavelengths, values)
         # np.interp happily bridges a NaN-free path around a NaN, so check the
-        # bracketing samples explicitly.
+        # samples the answer actually rests on. A query that lands exactly on
+        # a sample rests on that sample alone: it is not interpolated, so a
+        # missing neighbour must not poison it.
         idx = np.searchsorted(self.wavelengths, query)
-        for k, i in enumerate(idx):
-            neighbours = values[max(i - 1, 0):min(i + 1, values.size) + 1]
-            if np.any(np.isnan(neighbours)):
+        for k, (i, w_query) in enumerate(zip(idx, query)):
+            exact = i < self.wavelengths.size and self.wavelengths[i] == w_query
+            if exact:
+                if np.isnan(values[i]):
+                    out[k] = np.nan
+                continue
+            left, right = max(i - 1, 0), min(i, values.size - 1)
+            if np.any(np.isnan(values[left:right + 1])):
                 out[k] = np.nan
         return _like_input(out, wl)
 

{jerlov-0.2.0 → jerlov-0.2.2/jerlov.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jerlov
-Version: 0.2.0
+Version: 0.2.2
 Summary: Inherent optical properties of Jerlov water types, with provenance
 Author: T. Ishibashi
 License-Expression: Apache-2.0
@@ -257,22 +257,23 @@ rather than substituting a neighbour.
 ## Examples
 
 ```
-python examples/sources_disagree.py
-python examples/synthetic_underwater_images.py
+python examples/sources_disagree.py            why the source is an argument
+python examples/from_one_measurement.py        from an instrument reading
+python examples/synthetic_underwater_images.py appearance at range and depth
+python examples/solar_heating.py               for ocean circulation models
+python examples/what_an_eye_sees.py            any spectral sensitivity
 ```
 
-The first shows why the source is an argument: at 510 nm the scattering
-coefficient of Jerlov III differs by a factor of 3.8 between the two published
-sets. The second synthesises how reflectance patches appear at range and
-depth, white-balanced two ways, and ends with a list of everything it assumed.
-
-Both are run by CI, so an example that has stopped working is a failed build.
+Five scripts, each aimed at a different reader; `examples/README.md` says
+which to start with. CI runs all of them on every push, so an example that has
+stopped working is a failed build. Every one ends with the assumptions it
+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. Fifteen entries are
-documented there: seven confirmed defects in the source literature, three
+verified, and what is known to be wrong with it. Seventeen entries are
+documented there: eight 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.2.0 → jerlov-0.2.2}/pyproject.toml

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

{jerlov-0.2.0 → jerlov-0.2.2}/tests/test_api.py

@@ -186,3 +186,30 @@ def test_a_missing_value_is_nan_whether_scalar_or_array():
         warnings.simplefilter("ignore", ProvenanceWarning)
         assert np.isnan(w.a(675))
         assert np.isnan(w.a([675.0])).all()
+
+
+# -- landing exactly on a sample -----------------------------------------
+
+
+def test_an_exact_hit_survives_a_missing_neighbour():
+    """A query on a sample is not interpolated, so a gap beside it is not its
+    problem. Found by checking the shipped 1976 file against the printed
+    table: Jerlov 7C has no data below 350 nm, and kd(350) was returning nan
+    although 350 nm itself is tabulated.
+    """
+    w = jerlov.water("7C", source="jerlov1976")
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", ProvenanceWarning)
+        assert w.kd(350.0) == pytest.approx(3.0)
+        assert np.isnan(w.kd(349.0))      # inside the gap, still nan
+        assert np.isnan(w.kd(348.0))
+
+
+def test_interpolating_across_a_gap_still_gives_nan():
+    """The guard this rests on must not have been loosened."""
+    w = jerlov.water("5C", source="solonenko2015")
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", ProvenanceWarning)
+        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))

{jerlov-0.2.0 → jerlov-0.2.2}/tests/test_colour.py

@@ -73,7 +73,7 @@ def test_each_primary_lights_only_its_own_channel():
 def test_a_narrow_spectrum_warns():
     """450-650 nm looks like a full spectrum but is not."""
     wl = np.arange(450.0, 651.0, 1.0)
-    with pytest.warns(CoverageWarning, match="covers only"):
+    with pytest.warns(CoverageWarning, match="covered"):
         spectrum_to_xyz(np.ones_like(wl), wl)
 
 
@@ -88,8 +88,13 @@ def test_the_warning_states_what_was_missed():
     with pytest.warns(CoverageWarning) as caught:
         spectrum_to_xyz(np.ones_like(wl), wl)
     message = str(caught[0].message)
-    assert "500-600 nm" in message
-    assert "CIE 1931" in message
+    assert "500-600 nm" in message          # the span it actually had
+    assert "CIE 1931" in message            # what it was integrated against
+    assert "all channels:" in message       # not just the worst one
+    # z-bar peaks at 445 nm, so 500-600 nm barely touches it. Naming the
+    # channel matters: "4.1% covered" alone reads as if the whole observer
+    # were 4.1% covered, which would be wrong.
+    assert "channel 2 of 3" in message
 
 
 # -- white, the other one ------------------------------------------------

{jerlov-0.2.0 → jerlov-0.2.2}/tests/test_packaging.py

@@ -76,3 +76,67 @@ def test_every_shipped_table_has_a_build_script_or_is_explained():
     scripts = " ".join(p.read_text() for p in (ROOT / "tools").glob("*.py"))
     for csv in sorted((ROOT / "jerlov" / "data").glob("*.csv")):
         assert csv.name in scripts, f"no build script writes {csv.name}"
+
+
+# -- the documentation counts itself -------------------------------------
+
+_SPELLED = ["zero", "one", "two", "three", "four", "five", "six", "seven",
+            "eight", "nine", "ten", "eleven", "twelve", "thirteen", "fourteen",
+            "fifteen", "sixteen", "seventeen", "eighteen", "nineteen",
+            "twenty", "twenty-one", "twenty-two", "twenty-three",
+            "twenty-four", "twenty-five"]
+WORDS = {word: value for value, word in enumerate(_SPELLED)}
+WORDS.update({word.capitalize(): value
+              for value, word in enumerate(_SPELLED)})
+
+
+def _numbered_sections(text: str) -> int:
+    return len(re.findall(r"^## \d+\. ", text, re.MULTILINE))
+
+
+def _confirmed_sections(text: str) -> int:
+    return len(re.findall(r"^## \d+\..*\(confirmed", text, re.MULTILINE))
+
+
+@source_tree
+def test_DATA_md_counts_its_own_sections():
+    """The opening summary is written by hand and has drifted three times."""
+    text = (ROOT / "DATA.md").read_text()
+    match = re.search(r"^(\w+) entries are recorded below\. (\w+) are confirmed",
+                      text, re.MULTILINE)
+    assert match, "DATA.md no longer opens with a countable summary"
+    claimed_total, claimed_confirmed = (WORDS[g] for g in match.groups())
+    assert claimed_total == _numbered_sections(text)
+    assert claimed_confirmed == _confirmed_sections(text)
+
+
+@source_tree
+def test_the_zenodo_record_will_carry_what_it_should():
+    """`.zenodo.json` is only read at archive time, so nothing else checks it."""
+    import json
+
+    record = json.loads((ROOT / ".zenodo.json").read_text())
+    assert record["upload_type"] == "software"
+    assert record["license"] == "Apache-2.0"
+    assert record["creators"], "a record with no author is not citable"
+    for creator in record["creators"]:
+        assert creator.get("orcid"), (
+            f"{creator['name']} has no ORCID, so the record will not attach "
+            "to their publication list"
+        )
+    # Every source the package ships data from should be reachable from the
+    # record, not only from DATA.md.
+    derived = [r["identifier"] for r in record["related_identifiers"]
+               if r["relation"] == "isDerivedFrom"]
+    assert len(derived) >= 8, derived
+
+
+@source_tree
+def test_the_README_agrees_with_DATA_md_on_the_count():
+    data = (ROOT / "DATA.md").read_text()
+    readme = (ROOT / "README.md").read_text()
+    match = re.search(r"(\w+) entries are\s+documented there: (\w+) confirmed",
+                      readme)
+    assert match, "the README no longer states the count"
+    assert WORDS[match.group(1)] == _numbered_sections(data)
+    assert WORDS[match.group(2)] == _confirmed_sections(data)

{jerlov-0.2.0 → jerlov-0.2.2}/tests/test_reproduces_papers.py

@@ -221,3 +221,75 @@ def test_jerlov_type_I_falls_below_pure_sea_water():
         if j < float(np.interp(nm, wl_m, kw)):
             below += 1
     assert below == 9, f"{below} of {len(checked)} wavelengths below Kw"
+
+
+# -- checked against independent transcriptions ---------------------------
+
+#: Jerlov (1976) Table XXVII, Kd x 100 in 1/m, as reprinted by Paglierani et
+#: al. (2023) Table 10 and by Wozniak & Pelevin (1991) Table 1. The two agree
+#: with each other and with the original scan except at IB 700 nm, where
+#: Wozniak & Pelevin print 59; see DATA.md section 16.
+JERLOV1976_TABLE_XXVII = {
+    "I": [15, 6.2, 3.8, 2.8, 2.2, 1.9, 1.8, 2.7, 4.3, 6.3, 8.9, 23.5, 30.5,
+          36, 42, 56],
+    "IA": [18, 7.8, 5.2, 3.8, 3.1, 2.6, 2.5, 3.2, 4.8, 6.7, 9.4, 24, 31, 37,
+           43, 57],
+    "IB": [22, 10, 6.6, 5.1, 4.2, 3.6, 3.3, 4.2, 5.4, 7.2, 9.9, 24.5, 31.5,
+           37.5, 43.5, 58],
+    "II": [37, 17.5, 12.2, 9.6, 8.1, 6.8, 6.2, 7.0, 7.6, 8.9, 11.5, 26, 33.5,
+           40, 46.5, 61],
+    "III": [65, 32, 22, 18.5, 16, 13.5, 11.6, 11.5, 11.6, 12.0, 14.8, 29.5,
+            37.5, 44.5, 52, 66],
+    "1C": [180, 120, 80, 51, 36, 25, 17, 14, 13, 12, 15, 30, 37, 45, 51, 65],
+    "3C": [240, 170, 110, 78, 54, 39, 29, 22, 20, 19, 21, 33, 40, 46, 56, 71],
+    "5C": [350, 230, 160, 110, 78, 56, 43, 36, 31, 30, 33, 40, 48, 54, 65, 80],
+    "7C": [None, 300, 210, 160, 120, 89, 71, 58, 49, 46, 46, 48, 54, 63, 78,
+           92],
+    "9C": [None, 390, 300, 240, 190, 160, 123, 99, 78, 63, 58, 60, 65, 76, 92,
+           110],
+}
+TABLE_XXVII_WAVELENGTHS = [310, 350, 375, 400, 425, 450, 475, 500, 525, 550,
+                           575, 600, 625, 650, 675, 700]
+
+
+def test_the_shipped_1976_file_matches_the_printed_table():
+    """The Dstl file reaches us second-hand; the printed table does not."""
+    w = {t: jerlov.water(t, source="jerlov1976")
+         for t in JERLOV1976_TABLE_XXVII}
+    checked = 0
+    for water_type, row in JERLOV1976_TABLE_XXVII.items():
+        for nm, printed in zip(TABLE_XXVII_WAVELENGTHS, row):
+            if printed is None:
+                continue
+            got = w[water_type].kd(float(nm))
+            assert got == pytest.approx(printed / 100.0, rel=0.005), (
+                f"{water_type} at {nm} nm: shipped {got}, printed "
+                f"{printed / 100.0}"
+            )
+            checked += 1
+    assert checked == 158
+
+
+def test_the_wozniak_pelevin_reprint_differs_at_exactly_one_cell():
+    """DATA.md section 16. A standing record of what that reprint got wrong."""
+    reprint = {k: list(v) for k, v in JERLOV1976_TABLE_XXVII.items()}
+    reprint["IB"][TABLE_XXVII_WAVELENGTHS.index(700)] = 59      # as printed
+    differing = [
+        (t, nm)
+        for t, row in reprint.items()
+        for nm, value in zip(TABLE_XXVII_WAVELENGTHS, row)
+        if value is not None
+        and value != JERLOV1976_TABLE_XXVII[t][
+            TABLE_XXVII_WAVELENGTHS.index(nm)]
+    ]
+    assert differing == [("IB", 700)]
+
+
+def test_the_stated_unit_of_that_reprint_is_impossible():
+    """Its header says 1e-3 m^-1, which puts Jerlov I below pure sea water."""
+    printed = JERLOV1976_TABLE_XXVII["I"][TABLE_XXVII_WAVELENGTHS.index(475)]
+    as_stated = printed * 1e-3
+    correct = printed * 1e-2
+    pure_water_absorption_at_475 = 0.011    # Austin & Petzold Kw, 1/m
+    assert as_stated < pure_water_absorption_at_475
+    assert correct > pure_water_absorption_at_475