API reference

Every name in jerlov.__all__, which is what 1.0 promises to keep working until 2.0 (“Compatibility” in CONTRIBUTING.md). Import them from jerlov itself; the modules inside the package are not part of the promise. The entries are built from the docstrings.

Water types and their coefficients

jerlov.water(water_type: str, source: str = 'williamson2022') → Water

Return the Water for a named Jerlov type.

The default source is Williamson & Hollins (2022) because it is the only published set in which a and b rest on measurements rather than on an inversion of Kd.

class jerlov.Water(wavelengths, /, a=None, b=None, *, kd=None, kd_hydrolight=None, name: str | None = None, source: Source | None = None, flags: dict[str, tuple[str, ...]] | None = None, uncertainty: dict[str, ndarray] | None = None)

Absorption and scattering coefficients as functions of wavelength.

Parameters:
  • wavelengths – Wavelengths in nm, ascending.

  • a – Absorption and scattering coefficients in 1/m. Use nan for wavelengths where the value is unknown.

  • b – Absorption and scattering coefficients in 1/m. Use nan for wavelengths where the value is unknown.

  • kd – Downwelling diffuse attenuation coefficient in 1/m, if known.

  • kd_hydrolight – Kd recomputed by a radiative transfer model from a and b, as Solonenko & Mobley (2015) publish it. See kd_hydrolight().

  • name – Jerlov water type, when the object came from one.

  • source – The Source the coefficients came from.

  • flags – Per-wavelength status strings, parallel to wavelengths, keyed by quantity ("a", "b", "Kd", "KdH").

  • uncertainty – Per-wavelength standard uncertainty in 1/m, keyed the same way. NaN where it is not known. See uncertainty().

classmethod from_measurements(wavelengths, /, a=None, b=None, *, kd=None, name: str | None = None, flags=None, uncertainty=None) → Water

Build a Water from the caller’s own measurements.

Parameters:
  • flags – Optional {quantity: statuses}, one status per wavelength, for "a", "b" or "kd". The statuses are those of the packaged tables (DATA.md, “The status column”), so that a value you mark "suspect" or "extrapolated" warns exactly as a published one does. An unknown status is refused rather than ignored, since a misspelt flag would otherwise never warn.

  • uncertainty – Optional {quantity: standard uncertainty} in 1/m, one value per wavelength, NaN where unknown. Read it back with uncertainty().

Notes

a, b and kd are totals, pure water included. A negative value, which none of them can have, is kept as given with a ProvenanceWarning, and a calculation that would rest on it refuses (DECISIONS.md section 60).

a(wl, /)

Absorption coefficient in 1/m.

b(wl, /)

Scattering coefficient in 1/m.

c(wl, /)

Beam attenuation coefficient a + b in 1/m.

One warning covers both terms: a wavelength flagged in a and in b is one fact about c, not two.

kd(wl, /)

Downwelling diffuse attenuation coefficient in 1/m.

kd_hydrolight(wl, /)

Kd recomputed by HydroLight from this water’s a and b, in 1/m.

Only Solonenko & Mobley (2015) publish it, as K_d^H in Tables 4-8. It is their check that the a and b they retrieved reproduce Jerlov’s Kd: HydroLight run with those a and b, the Petzold average-particle phase function, a clear sky, infinitely deep water and no inelastic scattering, to an optical depth of 10 scattering lengths, or 6 for Jerlov III, where that matched Jerlov better (Section 4 and Appendix A). The paper says 90 percent of the points in its Fig. 5 lie within 20 percent of Jerlov’s; the tabulated values give 87 percent. See DATA.md section 19.

It is not the same quantity as kd(), which for this source is the Kd of the paper’s own bio-optical model, fitted to Jerlov to within 15 percent. Comparing the two shows how much the retrieved IOPs depend on the model they were retrieved with.

uncertainty(quantity: str, wl, /)

The standard uncertainty of quantity at wl, in 1/m.

Only measurements carry one: pass it to from_measurements(). Between measured wavelengths it is interpolated linearly, as the values are, which assumes the errors at neighbouring wavelengths are fully correlated. NaN where it was not given.

bb(wl, /, *, backscatter_ratio: float | None = None, particle_backscatter_ratio: float | None = None)

Backscattering coefficient in 1/m.

Give exactly one of two ratios; neither has a default. Neither is determined by the Jerlov classification: deriving bb from the particle concentrations of Solonenko & Mobley and of Williamson & Hollins gives answers that differ by up to a factor of 31. See DATA.md section 10.

backscatter_ratio is bb/b for the whole water, pure water included, and returns backscatter_ratio * b. In clear water this can be less than pure water’s own backscattering.

particle_backscatter_ratio is bbp/bp, the particles’ ratio, and returns 0.5 * b_w + particle_backscatter_ratio * (b - b_w), where b_w is the pure water term of the source’s own scattering model (Water.source.scattering; Haltrin 1999, whose Eq. (3) gives the water’s backscattering as 0.5 b_w). A Water made from measurements has no such model and is refused. See DECISIONS.md section 68.

Reported ranges are roughly 0.005-0.01 for open ocean and 0.015-0.03 for coastal water; the Petzold average-particle phase function gives about 0.0183, a particles’ ratio. Petzold’s eight measured waters give 0.013 to 0.044; petzold_scattering() returns each with its own, so that a ratio can be taken from a measured water rather than invented.

caveats() → tuple[str, ...]

Return what is known to be doubtful about this water’s data.

jerlov.pure_water_absorption(wavelength_nm, /, source: str = 'williamson2022')

The absorption of pure water that source computed its a with, 1/m.

A Jerlov type’s a is that of pure water plus what is dissolved and suspended in it, and each source started from its own pure water spectrum. This returns that spectrum, so that the part of a due to the water’s contents is w.a(l) - pure_water_absorption(l) for the same source, and not a difference between two tabulations.

Only Williamson & Hollins (2022) publish theirs, in the spreadsheet that accompanies the paper: 1 nm from 300 to 800 nm. The paper attributes it to Buiteveld et al. (1994); it has not been compared with Buiteveld’s table here, but it is the aw their a was built on, which the build script checks. From 720 nm their model gives the water’s contents no absorption at all, so every type’s a is this. See DATA.md section 20.

Other sources raise MissingQuantityError, saying why. For a published spectrum in its own right, such as Pope & Fry (1997), see pure_water_absorption_table().

jerlov.pure_water_absorption_table(wavelength_nm, /, *, source: str)

A published absorption spectrum of pure water, 1/m.

Unlike pure_water_absorption(), which returns the aw a Jerlov source built its a on, this returns a spectrum published for its own sake, for use where a pure water absorption must be supplied, such as the pure_water of qaa_v6() and qaa_ioccg2006(). There is no default: which one to use is the caller’s choice. Below about 450 nm they disagree, by a factor of 7.95 between Pope & Fry and Mason et al. at 380 nm, and which is right is not settled (DATA.md section 29).

source is one of:

  • "pope1997": Pope & Fry (1997), Appl. Opt. 36, 8710-8723, Table 3. Pure water at 22 C, integrating cavity, 380-727.5 nm every 2.5 nm. Their calibration used data at 700 nm and below. The aw of IOCCG Report 5 (2006).

  • "smith1981": Smith & Baker (1981), Appl. Opt. 20, 177-184, Table I. Pure water, derived from the diffuse attenuation of the clearest natural waters, 200-800 nm every 10 nm. At 710 nm the printed aw exceeds the printed K, against the paper’s own Eq. (6), and warns.

  • "mason2016": Mason, Cone & Fry (2016), Appl. Opt. 55, 7163-7172, Table 2. Pure water at 23 C, integrating cavity, 250-550 nm: every 10 nm to 300, then every 2 nm.

  • "lee2015": Lee et al. (2015), Appl. Opt. 54, 546-558, Table 1. “Pure” seawater, inverted from the remote sensing reflectance of the clearest oceans, 350-550 nm every 5 nm, as printed.

  • "lee2015_smoothed": the same, with the paper’s smoothed values at 360, 370, 385, 395 and 400 nm, where it attributes dips to imperfect removal of Raman scattering.

  • "morel2007": Morel et al. (2007), Limnol. Oceanogr. 52, 217-229, Table 2, aw1: “a tentative upper bound” from the clearest waters of the South Pacific gyre, 300-500 nm every 5 nm; Buiteveld et al. (1994) from Boivin et al. (1986) below 366 nm, Pope & Fry’s values from 420 nm (at 425, 435, 445 and 455 nm the mean of theirs 5 nm either side), a smooth join between.

  • "morel2007_aw2": the same table’s aw2, 300-370 nm, from Quickenden & Irvin (1980), joined to aw1 at 366 nm.

Linear interpolation between the printed wavelengths, no extrapolation. Uncertainties are in the tables but not returned. See DATA.md section 29 and DECISIONS.md section 70.

jerlov.measured_points(water_type: str, quantity: str, *, include_sparse: bool = False) → MeasuredPoints

The measured a or b points behind Williamson & Hollins (2022).

The smooth spectra returned by water(..., source="williamson2022") were fitted to these. Hollins & Williamson (2023) say the fitting would bias some analyses and that the individual points are preferable for validation; they come with their spread and their campaign count.

The paper kept only averages built from five or more campaigns, 53 each for a and b. Points below that are left out unless include_sparse=True. Jerlov IA and 7C rest on a single campaign throughout, so without it they have no points at all, and this raises rather than returning nothing. See DATA.md section 9.

class jerlov.MeasuredPoints(water_type: str, quantity: str, wavelengths: ndarray, values: ndarray, std_dev: ndarray, n_campaigns: ndarray, included: ndarray)

Measured a or b of one Jerlov type, before any spectral fitting.

water_type: str
quantity: str
wavelengths: ndarray

nm, ascending.

values: ndarray

the average over campaigns.

Type:

1/m

std_dev: ndarray

1/m, across campaigns; NaN where none was given.

n_campaigns: ndarray

How many campaigns each average rests on.

included: ndarray

True where the paper kept the point (five or more campaigns).

jerlov.classify_kd(wavelengths, kd, /, *, source: str = 'jerlov1976', types=None, uncertainty=None, k: float = 1.0) → 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 wavelengths, and ranked by the root mean square of ln(Kd_measured / Kd_type). Logarithms, so that a 10 percent difference counts the same in clear blue water as in the red.

Parameters:
  • wavelengths – nm, inside the range of source. A single wavelength is allowed, Kd(490) for instance, but then oceanic and coastal types with a similar Kd there cannot be told apart, and the ranking will show it.

  • kd – Measured Kd in 1/m, on wavelengths. NaN marks a gap; it is left out and recorded in excluded_nm.

  • 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.

  • uncertainty – Optional standard uncertainty of kd, 1/m, on wavelengths. The types are ranked again with the measurement shifted by k of them up and down at every wavelength together, and nearest_within_uncertainty lists every type that comes out nearest. A shift of the whole spectrum moves a measurement between clear and turbid, along the types; a type only an error in the spectrum’s shape would make nearest is not found (DECISIONS.md section 57).

Notes

The types are points, not a continuum, and Jerlov defined them on the upper 10 m. A measurement half-way between II and III is reported as one of them, with both distances; deeper down, compare water_type_at_depth(). Nothing here says the measurement is a Jerlov type, only which one it is nearest. Check beyond and the gap to the runner-up.

class jerlov.KdClassification(water_type: str, source: str, distances: tuple[tuple[str, float], ...], wavelengths: ndarray, excluded_nm: tuple[float, ...], beyond: str | None, nearest_within_uncertainty: tuple[str, ...] | None = None)

How close a measured Kd spectrum is to each Jerlov type.

Built by classify_kd(). The distance to a type is the root mean square of ln(Kd_measured / Kd_type) over wavelengths: 0.1 means the measurement differs from that type by about 10 percent, in one direction or the other, on average.

water_type: str

The nearest type. Read distances before relying on it.

source: str

Whose Kd spectra the measurement was compared with.

distances: tuple[tuple[str, float], ...]

(type, distance) for every type, nearest first.

wavelengths: ndarray

The wavelengths compared, nm.

excluded_nm: tuple[float, ...]

a gap in the measurement, or in the Kd of some type, which would make the distances incomparable.

Type:

Wavelengths given but not compared

beyond: str | None

"clearer" if the measurement is below the Kd of the clearest type at every wavelength compared, "more turbid" if above the most turbid one, else None. The nearest type is then only an end of the classification, not a match.

nearest_within_uncertainty: tuple[str, ...] | None = None

every type that comes out nearest with the measurement as given or shifted by k uncertainties up or down at every wavelength together, the nearest first. None without one.

Type:

With uncertainty given to classify_kd()

From a measurement

jerlov.kd_spectrum(kd, wavelength_nm: float, at, /)

Reconstruct a Kd spectrum from a single measured value.

Uses the model of Austin & Petzold (1986), Eq. (6):

K(l2) = [M(l2)/M(l1)] * [K(l1) - Kw(l1)] + Kw(l2)
Parameters:
  • kd – Measured Kd in 1/m. A scalar, or an array of measurements all made at wavelength_nm (several stations, say); each is reconstructed separately.

  • wavelength_nm – Wavelength at which kd was measured. A single value.

  • at – Wavelength(s) at which to evaluate the spectrum.

Returns:

  • A float for scalar kd and at. Otherwise an array of shape

  • ``kd.shape + at.shape`` (one spectrum per measurement.)

Notes

The authors state the model holds for K(490) < 0.16 1/m, and a ProvenanceWarning is raised for any measurement whose K(490), measured or implied by the model, is not below that. Austin & Petzold (1990) put its accuracy, as a coefficient of variation over 83 stations, under 8 percent at wavelengths up to 590 nm except at 410 nm, where yellow substance makes it worse, and 9 percent or more beyond, reaching 31 percent at 670 nm. M below 365 nm is itself extrapolated, and a result that rests on it also warns.

jerlov.b_from_c(c, wavelength_nm, /, *, bw, cw, bound: str = 'average')

Estimate the scattering coefficient from the beam attenuation.

Uses the measured ratios of Smart (2007) Table 1:

b = (c - cw) * ratio + bw

bound selects "average", "min" or "max". Smart recommends the upper bound for turbid water (c at 488 nm above 1.0 1/m) and the lower bound for clear water; the average is accurate to about 10 percent. Ratios are lower than tabulated in CDOM-rich water below about 488 nm.

jerlov.k_from_secchi(secchi_depth_m, *, coefficient: float)

Estimate an attenuation coefficient from a Secchi depth.

K = coefficient / secchi_depth_m, in 1/m.

Parameters:
  • secchi_depth_m – Secchi depth(s), m: where the disc disappears from view. A scalar or an array; each must be finite and positive.

  • coefficient – The empirical ratio K * Secchi depth. There is no default: it is not a property of light in water but a rule fitted to observations, and the result is no better than it. Poole & Atkins (1929) proposed 1.7, POOLE1929_SECCHI_COEFFICIENT; Duarte (1991, p. 364) and Duarte et al. (2007, p. 653) used it for seagrass depth limits.

Return type:

A float for a scalar depth, an array of the same shape otherwise.

Notes

Every call raises a ProvenanceWarning, since the result is not a measurement and nothing else in it says so.

Poole & Atkins (1929, p. 310) compared the Secchi depth D with the attenuation of daylight from 0 to 20 m, on 14 days in 1928 in the English Channel off Plymouth. Their K is the natural-log attenuation coefficient of the light on a horizontal surface, measured with potassium photoelectric cells behind opal glass and assuming 15 percent of the light lost at the surface. K * D ran from 1.32 to 2.18, mean 1.70, which they called “a very rough rule” and, from the scatter, “a rough approximation” at best (pp. 310, 324). K is therefore the attenuation of whatever their cells responded to, not a spectral Kd and not Kd(PAR), and cannot be passed where one is expected. DECISIONS.md section 52.

jerlov.POOLE1929_SECCHI_COEFFICIENT = 1.7

K = 1.7 / Secchi depth: the mean of K times the Secchi depth over the 14 comparisons of Poole & Atkins (1929, p. 310, Table III), which ran from 1.32 to 2.18. DECISIONS.md section 52.

The type changes with depth

jerlov.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 depth: water that is Jerlov I at the surface is typically IB below about 40 m, and turbid coastal water typically clears with depth. Williamson & Hollins (2023) derived these profiles from more than 2500 measurement campaigns.

Returns None where the paper declined to declare a type, which is 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"
w = jerlov.water(deeper) if deeper else jerlov.water("I")

Notes

The profile is what was typical across the campaigns, not what holds at 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.

jerlov.profile_depth(surface_water_type: str) → float

How deep 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
jerlov.descend(surface_water_type: str, depth_m: float, wavelengths, /, *, source: str = 'jerlov1976') → Descent

Attenuate downwelling irradiance through the typical depth profile.

Scene.at_depth() uses one Kd all the way down, but water clears or darkens with depth. This takes the type of each 10 m layer from water_type_at_depth(), Williamson & Hollins (2023), and the Kd of that type from source:

Ed(z) / Ed(0) = exp(-sum over layers of Kd_type(layer) * thickness)

The top 10 m are the surface type itself. To build a scene from the result:

d = jerlov.descend("1C", 45.0, wl)
scene = jerlov.Scene(w, surface * d.transmittance, wl, depth_m=45.0)
Parameters:

source – Where every layer’s Kd comes from. Jerlov (1976), the default, covers all ten types; the profile can pass through any of them.

Raises:
  • MissingQuantityError – Where the descent reaches a layer for which Williamson & Hollins declared no type, too few campaigns supporting one, or below 200 m, where they make no statement. A coastal profile runs out quickly: Jerlov 9C below 10 m, 5C and 7C below 20 m, 3C below 70 m.

  • KeyError – Where source has no Kd for a type the profile passes through: Austin & Petzold (1986) cover I to 1C only.

Notes

Two approximations, both stated rather than hidden. The Kd of a type is that of its surface layer, applied unchanged at depth, since that is how the classification is defined. And the profile is what was typical across more than 2500 campaigns, not what holds at a given place or season; see water_type_at_depth().

class jerlov.Descent(surface_water_type: str, depth_m: float, source: str, wavelengths: ndarray, layers: tuple[tuple[float, float, str], ...], transmittance: ndarray | float, _kd: tuple[ndarray, ...] = ())

Downwelling irradiance carried down through changing water types.

surface_water_type: str
depth_m: float
source: str

The source of every layer’s Kd.

wavelengths: ndarray

nm, as asked for.

layers: tuple[tuple[float, float, str], ...]

(top, bottom, water type) of each layer crossed, in metres; the last stops at depth_m.

transmittance: ndarray | float

exp(-sum(Kd_i * thickness_i)).

Type:

Ed(depth) / Ed(0)

transmittance_at(depth_m)

Ed(z) / Ed(0) at any depth from the surface to depth_m.

Uses the layers already crossed, so it is what descend() to that depth would give, without calling it again. A single depth gives an array on wavelengths (a float if the descent was asked for at one wavelength); an array of depths gives one row per depth.

Raises:

MissingQuantityError – Below depth_m. Descend further, if the profile allows: see profile_depth().

Light for photosynthesis

jerlov.par_profile(surface_downwelling, wavelengths, /, depths_m, *, kd, unit: str, band=(400.0, 700.0), photon_weight=None, kd_uncertainty=None) → ParProfile

PAR at depths_m below a surface downwelling spectrum.

Parameters:
  • surface_downwelling – Downwelling planar irradiance just below the surface, on wavelengths.

  • wavelengths – nm, ascending, covering at least band. Values between the samples are interpolated linearly at its two ends.

  • depths_m – A depth or an array of depths, in m.

  • kd – A Water carrying Kd, such as jerlov.water("II", source="jerlov1976"), or an array on wavelengths; either is applied unchanged with depth. Or a Descent on the same wavelengths, which changes the type layer by layer and stops at the descent’s depth.

  • unit – "energy" if the spectrum is in W m-2 nm-1, "photons" if it is in umol m-2 s-1 nm-1. There is no default: PAR counts photons, and an energy spectrum read as photons would weight the blue and the red wrongly without any sign that it had.

  • band – (lo, hi), nm, the band to integrate over. 400-700 nm, the definition of PAR, by default. Another band gives the photon flux in it: QUANTA_BAND_NM for Jerlov’s quanta meters, or part of PAR for the share of one colour. Nothing outside it counts, so the spectrum and Kd may have gaps there.

  • photon_weight – Optional, on wavelengths: a weight for each photon by its wavelength, such as the absorption spectrum of a pigment or the quantum sensitivity of a photoreceptor. par is then the integral of the photon spectrum times the weight, in the weight’s units times umol m-2 s-1, and ParProfile.depth_of_fraction() and ParProfile.kd_par() follow it. Finite and not negative inside the band; its scale cancels from every fraction. A response per unit energy, as a thermopile’s, is not a photon weight: divide it by the wavelength first, since a photon of wavelength l carries an energy proportional to 1 / l.

  • kd_uncertainty – Optional, on wavelengths, beside an array kd: the standard uncertainty of Kd, 1/m. A Water built with uncertainty={"kd": ...} carries its own and takes none here. It is used only by ParProfile.depth_of_fraction_bounds() and ParProfile.par_bounds(), which take the errors as fully correlated between wavelengths (DECISIONS.md section 57).

Example

d = jerlov.descend("I", 200.0, wl)
p = jerlov.par_profile(surface, wl, [0, 50, 100], kd=d, unit="energy")
p.fraction                 # PAR(z) / PAR(0) at each depth
p.depth_of_fraction(0.01)  # the 1 percent depth, m

See the module docstring for what this assumes.

class jerlov.ParProfile(depths_m, band_nm, grid, surface_q, tau, deepest, kd_from, weight=None, shifted=None)

PAR at a set of depths, and the depth at which it falls to a fraction.

Built by par_profile(). par is in umol photons m-2 s-1, whatever unit the surface spectrum was given in, integrated over band_nm: PAR when that is 400-700 nm, the photon flux in that band otherwise.

band_nm

the band integrated over.

Type:

(lo, hi), nm

weighted

True if par was integrated against a photon_weight.

wavelengths_nm

every sample inside band_nm and its two ends. spectrum_at() is on these.

Type:

The wavelengths integrated over, nm

kd_from

What the Kd came from, in words.

surface_par

PAR just below the surface, umol photons m-2 s-1.

depths_m

The depths asked for, m.

par

PAR at each depth, umol photons m-2 s-1.

spectrum_at(depth_m) → ndarray

The downwelling spectrum at depth_m, in umol photons m-2 s-1 nm-1, on wavelengths_nm.

Photons whatever unit the surface spectrum was given in, since that is what par integrates. A single depth gives one spectrum; an array of depths gives one row per depth. par at a depth is the trapezoid integral of this over wavelengths_nm, times the photon_weight if one was given; the spectrum itself is not weighted.

Raises:

MissingQuantityError – Below the bottom of a Descent.

kd_par(z1_m, z2_m) → float

The effective Kd of PAR between two depths, 1/m: ln(PAR(z1) / PAR(z2)) / (z2 - z1).

PAR does not fall off with one coefficient, so this depends on the two depths, not only on the water: near the surface it is larger, while the red is still being removed. Over a band other than 400-700 nm it is the same quantity for that band.

Raises:
property fraction: ndarray

PAR(z) / PAR(0), 0 to 1. NaN if there is no light at the surface.

depth_of_fraction(fraction: float = 0.01) → float

The depth, in m, at which PAR falls to fraction of its surface value.

The default, 1 percent, is the usual convention for the bottom of the euphotic zone. It is a convention: phytoplankton grow below it, and in clear water a good deal below it.

Raises:

MissingQuantityError – If the Kd came from a Descent and PAR has not fallen that far by the bottom of it. Descend further, or, if the descent cannot go further, there is no answer here: the typical profile says nothing about the water below.

depth_of_fraction_bounds(fraction: float = 0.01, *, k: float = 1.0) → tuple[float, float]

The depth of fraction with Kd shifted by k standard uncertainties at every wavelength together: (shallower, deeper), in m.

The errors are taken as fully correlated between wavelengths, so this is the widest range any errors within k uncertainties at every wavelength can give, and exactly plus and minus k standard deviations if they are fully correlated and normal. DECISIONS.md section 57.

Raises:
  • MissingQuantityError – If the Kd carries no uncertainty, as no published type does, or has a gap in it within the band.

  • ValueError – If Kd minus k uncertainties is negative anywhere in the band.

par_bounds(*, k: float = 1.0) → tuple[ndarray, ndarray]

(lower, higher) PAR at depths_m, with Kd shifted by k standard uncertainties at every wavelength together, as in depth_of_fraction_bounds(). The surface has no range: PAR there does not depend on Kd.

scalar_par(*, mean_cosine, reflectance) → ndarray

Scalar PAR at depths_m, umol photons m-2 s-1, from a mean cosine and a reflectance the caller gives.

par integrates the planar irradiance Ed. Scalar irradiance E0, what a spherical sensor reads, counts light from every direction equally, and by the definition of the mean cosine:

E0 = (Ed - Eu) / mean_cosine = Ed (1 - reflectance) / mean_cosine

That is exact, so the result is as good as the two numbers given. Neither has a default: both depend on the sun, the sky, the surface and the water’s scattering, which the package does not model (DECISIONS.md section 59). examples/radiance_distribution.py computes them for one water by Monte Carlo.

Parameters:
  • mean_cosine – (Ed - Eu) / E0 of the photon flux over band_nm, of the weighted flux if a photon_weight was given: the mean cosine of the whole light field, in (0, 1]. That of the downwelling light alone, Ed / E0d, is larger; with reflectance=0 it gives the downwelling part of scalar PAR only.

  • reflectance – Eu / Ed of the same flux, in [0, 1). 0 leaves out the upwelling light, and the result is then too high by a factor 1 / (1 - R) for the true reflectance R.

Notes

Each is a number, or one value per depth with the shape of depths_m. Nothing is interpolated between depths, so there is no depth of a fraction of scalar PAR here; with the same values at every depth it is depth_of_fraction(). Dividing par_bounds() the same way gives its range, for the two taken as exact.

Raises:

ValueError – Outside those ranges, or if mean_cosine exceeds (1 - R) / (1 + R): E0 is at least Ed + Eu in any light field, equal when all of it travels straight up or down.

jerlov.PAR_RANGE_NM = (400.0, 700.0)

The waveband of PAR, nm.

jerlov.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 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. (1977), “Classification of sea water in terms of quanta irradiance”, J. Cons. int. Explor. Mer 37(3), 281-287, doi:10.1093/icesjms/37.3.281.

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 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.

class jerlov.QuantaLevels(water_type: str, level_percent: tuple[float, ...], level_depth_m: ndarray, profile_depth_m: ndarray, profile_percent: ndarray, layer_m: tuple[tuple[float, float], ...], layer_kd: ndarray, suspect: tuple[str, ...])

Jerlov’s measured profiles of quanta irradiance for one water type.

Built by jerlov1977_quanta(). Every depth is in m, every coefficient in 1/m, and the band is 350-700 nm, QUANTA_BAND_NM, not the 400-700 nm of PAR. To compare, pass band=QUANTA_BAND_NM to par_profile().

water_type: str
level_percent: tuple[float, ...]

the levels of Table 2.

Type:

30, 10, 3 and 1

level_depth_m: ndarray

The depth of each level, Table 2.

profile_depth_m: ndarray

Table 3’s depths, as far as the table goes for this type.

profile_percent: ndarray

Percent of surface quanta at profile_depth_m, Table 3.

layer_m: tuple[tuple[float, float], ...]

(top, bottom) of each layer of Table 5.

layer_kd: ndarray

Kd for quanta in each layer, Table 5.

suspect: tuple[str, ...]

The layers of layer_kd whose printed Kd does not follow from Table 3, even allowing for rounding; DATA.md section 22.

jerlov.QUANTA_BAND_NM = (350.0, 700.0)

The waveband of Jerlov’s quanta meters, nm. Not that of PAR.

jerlov.morel2007_stations() → tuple[ClearWaterStation, ...]

The eight stations of the clearest waters Morel et al. (2007) measured, in the South Pacific gyre in November 2004.

Morel, A., Gentili, B., Claustre, H., Babin, M., Bricaud, A., Ras, J. and Tièche, F. (2007), “Optical properties of the ‘clearest’ natural waters”, Limnol. Oceanogr. 52(1), 217-229, doi:10.4319/lo.2007.52.1.0217, Table 1. Their pure water absorption, Table 2, is pure_water_absorption_table(..., source="morel2007").

Return type:

A tuple of ClearWaterStation, in the table’s order.

Notes

At GYR-5 and STB-14 the printed ay2 - ay1 at 310 nm is 0.0082, where it should be aw1(310) - aw2(310) = 0.0183 and is 0.0182 at the other six stations: one of the two is likely misprinted by 0.0100. They are kept as printed, marked suspect, and a ProvenanceWarning says so. DATA.md section 46.

class jerlov.ClearWaterStation(station: str, latitude_deg_s: float, longitude_deg_w: float, date_2004: str, chl_5m_mg_m3: float, chl_30_40m_mg_m3: float, zeu_m: float, z_chl_max_m: float, chl_max_mg_m3: float, kd_420_per_m: float, kd_310_per_m: float, ap_420_per_m: float, ap_310_per_m: float, r_max_percent: float, r_max_nm: float, atot_420_per_m: float, atot_310_per_m: float, ay1_310_per_m: float, ay2_310_per_m: float, status: str, note: str)

One station of Morel et al.’s (2007) Table 1, as printed.

Observed: chlorophyll a at 5 m and at 30-40 m, the euphotic depth, the depth and chlorophyll of the deep maximum, Kd and the particles’ absorption at 420 and 310 nm, and the largest irradiance reflectance below the surface with its wavelength. Derived by the authors: the total absorption at 420 and 310 nm, and yellow substance at 310 nm with their two pure water absorptions (aw1 and aw2 of their Table 2).

station: str
latitude_deg_s: float
longitude_deg_w: float
date_2004: str
chl_5m_mg_m3: float
chl_30_40m_mg_m3: float
zeu_m: float
z_chl_max_m: float
chl_max_mg_m3: float
kd_420_per_m: float
kd_310_per_m: float
ap_420_per_m: float
ap_310_per_m: float
r_max_percent: float
r_max_nm: float
atot_420_per_m: float
atot_310_per_m: float
ay1_310_per_m: float
ay2_310_per_m: float
status: str
note: str

Looking at something through water

class jerlov.Scene(water: Water, downwelling, wavelengths, /, *, depth_m: float | None = None)

An observer and a target at the same depth in one body of water.

Parameters:
  • water – The Water between them. Must carry both a and b, since the beam attenuation c = a + b drives everything.

  • downwelling – Downwelling irradiance at that depth, on wavelengths. Any unit; the veiling radiance passed to observe() must use the same one.

  • wavelengths – Wavelengths in nm at which everything is evaluated.

  • depth_m – The observer’s depth, in m. observe() does not use it: with a horizontal path the depth enters only through downwelling. observe_slant() needs it, to place the target above or below.

classmethod at_depth(water: Water, depth_m: float, surface_downwelling, wavelengths, /, *, kd) → Scene

Build a scene by attenuating a surface spectrum down to depth_m.

kd says how the light got there. Either:

  • a Water carrying Kd, such as jerlov.water("III", source="austin1986"), or an array on wavelengths. Then Ed(z) = Ed(0) * exp(-Kd * z), which assumes Kd is constant with depth. Jerlov’s classification is defined over the upper 10 m, so this is reasonable there and increasingly rough below it. The default IOP source has no Kd of its own, so it must come from somewhere explicit.

  • a Descent to depth_m on the same wavelengths, from descend(), which changes the type layer by layer:

    d = jerlov.descend("1C", 45.0, wl)
    scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0,
                                  surface, wl, kd=d)
    

water is the water along the horizontal path at depth_m, and nothing checks it against the descent: there it is the type of the last layer, d.layers[-1][2], unless you know better.

transmittance(distance_m: float) → ndarray

exp(-c*r). No approximation beyond the value of c itself.

attenuation_coefficients(distance_range_m: tuple[float, float], *, veiling_radiance=None) → AttenuationCoefficients

Coefficients for the Akkaynak-Treibitz form, from this scene.

Parameters:
  • distance_range_m – The range of distances the coefficients are meant to describe. Required, and recorded on the result. Under single scattering the coefficients do not depend on it, but Akkaynak & Treibitz (2018) showed that in reality they do, so a value quoted without its range is not a well-defined quantity.

  • veiling_radiance – Optional B_inf, carried through unchanged. There is no default; see observe().

Notes

beta_D and beta_B both come out equal to the beam attenuation coefficient c, because that is what the single-scattering model says. Check are_distinct before treating them as two independent quantities.

observe(reflectance, distance_m: float, *, veiling_radiance, face_irradiance_ratio=None) → Observation

Look at a Lambertian target distance_m away.

The radiance leaving the target is reflectance * face_irradiance_ratio * downwelling / pi.

Parameters:
  • reflectance – Spectral reflectance of the target, 0 to 1, on the scene’s wavelengths.

  • distance_m – Horizontal distance to the target.

  • veiling_radiance – The path radiance at infinite distance, B_inf, on the scene’s wavelengths and in the same unit as the downwelling irradiance. There is no default: see DECISIONS.md section 4.

  • face_irradiance_ratio –

    The irradiance on the face of the target that the observer sees, divided by the downwelling irradiance: 1 for a face turned straight up, less for one turned towards a horizontal line of sight. A number, or an array on the scene’s wavelengths, finite and not negative. It can exceed 1, for a face turned towards the sun. The water type does not determine it.

    Required: there is no default, for the reason bb has none. Releases up to 0.10.0 took it as 1 without saying so, and 0.11.0 did so with a FutureWarning. See DECISIONS.md sections 33 and 34.

observe_slant(reflectance, distance_m: float, *, target_depth_m: float, kd, water_radiance, radiance_attenuation, face_irradiance_ratio) → Observation

Look at a Lambertian target above or below, distance_m away.

Duntley (1963), “Light in the sea”, J. Opt. Soc. Am. 53, 214-233, eqs. (8)-(16), for uniform water. The observer is at the scene’s depth_m and the target at target_depth_m; with z and zt those depths, c the beam attenuation and Nw the radiance of open water seen from the observer along this line:

direct = L_target * exp(-c * r)
veiling = Nw * (1 - exp(-c * r - K * (zt - z)))

This is Duntley’s eq. (12), whose printed sign in front of the path radiance is corrected, with K r cos(theta) written as the change of ln Nw between the two depths, so that no angle and no sign convention for one is needed (DECISIONS.md section 75). Looking down (zt > z) the contrast falls faster than along a horizontal line, looking up more slowly. With zt == z it is observe().

Parameters:
  • reflectance – Spectral reflectance of the target, 0 to 1.

  • distance_m – Distance to the target along the line of sight. Not less than the difference of the two depths.

  • target_depth_m – Depth of the target, in m.

  • kd – Kd between the two depths, to light the target: Ed(zt) = Ed(z) * exp(-Kd * (zt - z)). A Water carrying Kd, or an array on the wavelengths, as at_depth() takes it.

  • water_radiance – Nw: the radiance of the water itself, with no target, seen from the observer along this line of sight, in the unit of the downwelling irradiance. No default. For a horizontal line it is B_inf; veiling_radiance_estimate() is for that case only.

  • radiance_attenuation – K = -d ln(Nw)/dz along this line of sight, in 1/m, positive when that radiance falls with depth. A number or an array on the wavelengths. No default: it is not Kd. It belongs to one direction and changes with the light field; only in the asymptotic light field is it the same in every direction (Duntley, p. 231). It is taken as constant along the path, which Duntley (p. 230) found seldom matters beyond the first metres below the surface, as sighting ranges rarely exceed 2/K. Looking up, K times the difference of the depths must not exceed c times the distance: the path radiance would be negative, and the call raises ValueError (DECISIONS.md section 80).

  • face_irradiance_ratio – As for observe(), relative to Ed at the target’s depth.

class jerlov.Observation(wavelengths, direct, veiling, transmittance, distance_m, target_radiance)

The result of looking at a target through water.

All radiances are in whatever unit the caller used for the downwelling irradiance and the veiling radiance; the package does not impose one, but the two must agree.

direct

L_target * exp(-c*r).

Type:

Target radiance surviving the path

veiling

B_inf * (1 - exp(-c*r)) along a horizontal line; along a slanted one, Nw * (1 - exp(-c*r - K*(zt - z))), see Scene.observe_slant().

Type:

Path radiance added by scattering

transmittance

exp(-c*r). Free of approximation, given c.

property radiance: ndarray

Total radiance reaching the observer.

property veiling_fraction: ndarray

Share of the observed radiance that is path radiance, 0 to 1.

Near 1 the target contributes almost nothing and the observed colour is that of the water.

contrast(background_radiance) → ndarray

Apparent contrast against a background seen through the same path.

background_radiance is the radiance leaving the background, on the scene’s wavelengths and in the unit of the target radiance (reflectance * face_irradiance_ratio * downwelling / pi, with the background’s own ratio), not a reflectance.

With L_t and L_b the radiances leaving target and background, t the transmittance and B the veiling radiance at infinity:

C(r) = (L_t - L_b) t / (L_b t + B (1 - t))
     = C_0 * L_b t / (L_b t + B (1 - t)),   C_0 = (L_t - L_b) / L_b

This is written for a horizontal line. From Scene.observe_slant() the same holds with B (1 - t) replaced by the slanted path’s veiling, and a background at the target’s depth lit as the target is.

The path radiance is common to both and cancels from the numerator, but not from the denominator, so the loss of contrast is the veiling light’s doing rather than the transmittance’s:

  • With no veiling radiance (B = 0) the contrast is not reduced at all; target and background are dimmed by the same factor.

  • Against a background that is the water itself (L_b = B, a horizontal line of sight into open water) it is C_0 * t, the classic result.

  • It falls faster than that against a background darker than B, and more slowly against a brighter one.

class jerlov.AttenuationCoefficients(wavelengths: ndarray, beta_D: ndarray, beta_B: ndarray, B_inf: ndarray | None, distance_range_m: tuple[float, float], are_distinct: bool, note: str)

The three coefficients of the Akkaynak-Treibitz image formation model.

That model, widely used in underwater vision, writes the observed radiance as:

I = J * exp(-beta_D * r) + B_inf * (1 - exp(-beta_B * r))

and its central point is that beta_D and beta_B are not equal and not constant: both depend on range, depth and the reflectance of the target.

Under the single-scattering model this package implements, they are both simply the beam attenuation coefficient c, and are_distinct is False. Separating them needs measurements that this package does not have.

This is still worth having. Implementations that fit these coefficients commonly bound them by guesswork for want of a physical starting point; c is that starting point, and are_distinct says plainly how far it can be trusted.

wavelengths: ndarray
beta_D: ndarray

Attenuation of the direct signal, 1/m.

beta_B: ndarray

Attenuation governing the growth of backscatter, 1/m.

B_inf: ndarray | None

Veiling radiance at infinite range, if the caller supplied one.

distance_range_m: tuple[float, float]

see the note.

Type:

The range the caller asked about. Recorded, not used

are_distinct: bool

False when beta_D and beta_B could not be told apart.

note: str
jerlov.veiling_radiance_estimate(water: Water, downwelling, wavelengths, /, *, backscatter_ratio: float | None = None, particle_backscatter_ratio: float | None = None) → ndarray

Single-scattering estimate of the veiling radiance B_inf.

B_inf = bb * Ed / (2 * pi * c)

This is an approximation, not a derivation. It assumes the backscattered light is spread uniformly over the backward hemisphere, which is why the factor is 2*pi. Real phase functions are strongly peaked, so the result should be treated as an order of magnitude rather than a value.

bb is Water.bb() with whichever ratio is given, exactly one of backscatter_ratio (bb/b, pure water included) and particle_backscatter_ratio (bbp/bp, the particles’; DECISIONS.md sections 68 and 69). In clear water the first can give a bb below pure water’s own. The result inherits everything uncertain about the ratio, which is not determined by the Jerlov water type; reported ranges are roughly 0.005-0.01 for open ocean and 0.015-0.03 for coastal water.

Provided so that a caller with no measurement is not stuck, but it must be called deliberately: Scene.observe() will not reach for it.

Colour

jerlov.spectrum_to_xyz(spectrum, wavelengths, /) → ndarray

Integrate a spectrum against the CIE 1931 2-degree observer.

The result is unnormalised: it carries the units of the spectrum. Divide by the XYZ of whatever counts as white before converting to a display colour, or use spectrum_to_srgb(), which requires that reference.

jerlov.spectrum_to_srgb(spectrum, wavelengths, /, *, white, clip: bool = True)

Convert a spectrum to sRGB, relative to a stated white.

Parameters:

white – The spectrum that should come out white, on the same wavelengths. There is no default: a radiance spectrum has no colour until something is called white, and underwater the answer is usually the downwelling irradiance at that depth rather than a surface daylight.

Notes

The spectrum’s XYZ is scaled component by component so that the stated white lands on the sRGB white point, which makes it come out exactly neutral. This is a von Kries-type adaptation carried out in XYZ rather than in cone space: transparent, and less accurate than CAT02 or Bradford for strongly coloured illumination. Underwater illumination is strongly coloured, so treat the result as “what a white-balanced camera would record” rather than as a prediction of appearance.

Absolute brightness is lost: a perfect diffuser under the stated white maps to white whatever the light level.

NaN in spectrum inside the observer’s range, a gap, gives a NaN colour; a gap in white is refused, since nothing would then have a colour.

jerlov.xyz_to_srgb(xyz, *, clip: bool = True) → ndarray

Convert XYZ, normalised so that white is Y = 1, to sRGB.

Applies the sRGB transfer function of IEC 61966-2-1. Warns if any channel falls outside the display gamut, which underwater colours often do.

jerlov.integrate_response(spectrum, wavelengths, response, response_wavelengths, /, *, name: str = 'response') → ndarray

Integrate a spectrum against one or more spectral sensitivities.

Parameters:
  • spectrum – Spectral radiance or irradiance, on wavelengths.

  • response – Shape (m,) for a single channel or (m, k) for k channels, on response_wavelengths. Camera sensitivities and photoreceptor absorbances both fit here.

Returns:

  • Array of shape ``(k,)`` (the integral of spectrum times each channel over)

  • wavelength, in the units of the spectrum times nm.

Notes

The integral is taken on the spectrum’s own wavelengths, with the response interpolated onto them. Sample at 5 nm or finer where you can: on coarser grids the narrow peaks of a response, or of the spectrum, fall between samples, and the error grows quickly. Interpolating the spectrum onto the response’s grid instead is no cure, since it only trades this error for one in the shape assumed between the spectrum’s samples.

NaN in the spectrum, a gap, makes the integral NaN: it is not bridged. Infinity is refused.

jerlov.cie_1931_cmf() → tuple[ndarray, ndarray]

Return (wavelengths, cmf) for the CIE 1931 2-degree observer.

cmf has shape (n, 3), columns x-bar, y-bar, z-bar, at 1 nm from 360 to 830 nm.

jerlov.d65() → tuple[ndarray, ndarray]

Return (wavelengths, relative power) for CIE illuminant D65.

This is the sRGB reference white, tabulated at 5 nm from 300 to 780 nm.

It is a daylight phase, so it is a reasonable stand-in for the solar spectrum above the surface, but it is not a measurement of the light at any particular place or time: the real spectrum depends on solar elevation, atmosphere and the state of the surface.

exception jerlov.GamutWarning

A colour fell outside the range the display can show.

Underwater colours often do. Clipping changes them, so the caller is told rather than left to wonder.

exception jerlov.CoverageWarning

The spectrum did not span the observer’s sensitivity.

The integral is then over the overlap only, and the result is biased by however much was left out.

Scattering and backscattering

jerlov.pure_water_vsf(angle_deg, wavelength_nm, /, *, salinity_psu: float | None = None)

Volume scattering function of pure sea water, 1/(m sr).

Morel’s formula as given by Boss & Pegau Eqs. (4) and (5):

A(lambda, S) = 1.38 (lambda / 500 nm)^-4.32 (1 + 0.3 S / 37) 1e-4
beta_w(theta) = A [1 + cos^2(theta) (1 - delta) / (1 + delta)]

The amplitude carries about 15 percent uncertainty, which the authors give as the agreement between measurement and theory.

salinity_psu has no default: pure sea water at 37 scatters 30 percent more than fresh water, and only the caller knows which water it is. Leaving it out raises MissingQuantityError; releases before 1.0 assumed 37. The same holds for the other functions here.

jerlov.pure_water_backscattering(wavelength_nm, /, *, salinity_psu: float | None = None)

bb_w, the backscattering coefficient of pure sea water, 1/m.

Obtained by integrating pure_water_vsf() over the backward hemisphere, which for this angular shape is analytic. salinity_psu as for pure_water_vsf().

jerlov.pure_water_scattering(wavelength_nm, /, *, salinity_psu: float | None = None)

b_w, the total scattering coefficient of pure sea water, 1/m.

pure_water_vsf() integrated over all directions. Its shape is symmetric about 90 degrees, so this is exactly twice pure_water_backscattering(); it is Morel’s b_w = 16.06 beta_w(90) with the depolarisation ratio used here.

It is the bw that b_from_c() asks for, from the same formula as the rest of this module. Other tabulations of pure water scattering differ from Morel’s by several percent; pass whichever one your c measurement was corrected with. salinity_psu as for pure_water_vsf().

jerlov.bb_from_vsf(beta, angle_deg: float, wavelength_nm, /, *, salinity_psu: float | None = None) → Backscattering

Convert a measured volume scattering function to bb.

Parameters:
  • beta – The measured volume scattering function at angle_deg, in 1/(m sr). This is what the instrument reports once calibrated; it includes scattering by the water itself.

  • angle_deg – The instrument’s nominal scattering angle. 90 to 170 degrees.

  • wavelength_nm – Needed for the pure sea water terms, which are subtracted and then added back as bb_w. salinity_psu as for pure_water_vsf(): no default.

  • salinity_psu – Needed for the pure sea water terms, which are subtracted and then added back as bb_w. salinity_psu as for pure_water_vsf(): no default.

Notes

Boss & Pegau’s water-removal route, their Eq. (10). Removing the water first matters because chi differs between water and particles everywhere except near 118 degrees, where the two curves cross; that is why instruments cluster near 120.

The quoted error on the result is the spread of chi_p alone. The amplitude of the water term carries a further 15 percent, and your instrument’s own calibration is on top of both.

class jerlov.Backscattering(bb: float | ndarray, particulate: float | ndarray, water: float | ndarray, angle_deg: float, chi_p: float, quoted_error_percent: float)

bb recovered from a single-angle measurement.

bb: float | ndarray

Total backscattering coefficient, 1/m.

particulate: float | ndarray

The particle contribution, bb - bb_w.

water: float | ndarray

bb_w, from Morel’s formula rather than from your instrument.

angle_deg: float
chi_p: float
quoted_error_percent: float

Boss & Pegau’s own spread for chi_p at this angle. Not a total error.

jerlov.particulate_chi(angle_deg)

chi_p at one angle, interpolated within Boss & Pegau Table 1.

Refuses outside 90 to 170 degrees, the range their Table 1 covers.

exception jerlov.AngleWarning

The conversion is poorly constrained at the requested angle.

The shape of the volume scattering function varies most near 90 and 180 degrees, so a single-angle measurement there pins bb least well. Maffione & Dana (1997) recommend sensors covering roughly 110 to 160 degrees. Boss & Pegau (2001) recommend measuring near 117 degrees, and otherwise removing the water contribution first, which they support from near 90 to 160 degrees.

jerlov.petzold_scattering(station: str) → ScatteringFunction

The volume scattering function measured at one of Petzold’s stations.

station is one of PETZOLD_STATIONS: the Tongue of the Ocean in the Bahamas ("AUTEC 7", "AUTEC 8", "AUTEC 9"), off southern California ("HAOCE 5", "HAOCE 11") and San Diego Harbor ("NUC 2200", "NUC 2040", "NUC 2240").

Its backscatter_ratio is a measured bb/b that can be passed to Water.bb() in place of a guess, which is what most users of this report want from it. It is the ratio of that water, at 530 nm, with pure water included; it spans 0.013 to 0.044 across the eight.

class jerlov.ScatteringFunction(station: str, locale: str, date: str, wavelength_nm: float, angles_deg: ndarray, vsf: ndarray, statuses: tuple[str, ...], c: float, b: float, a: float, backscatter_ratio: float, fraction_below_0_1_deg: float)

One station of Petzold (1972), as the report prints it.

Every scattering quantity is total: pure water and particles together, as the instruments measured them.

station: str
locale: str
date: str
wavelength_nm: float

530 nm, at which c was measured. The scattering meters share one spectral response, a band through the green (the report’s Fig. 3).

angles_deg: ndarray

0.1 to 10 degrees evenly in log angle, then every 5 degrees to 180.

Type:

The report’s 55 angles

vsf: ndarray

The volume scattering function, 1/(m sr).

statuses: tuple[str, ...]

"extrapolated" below the first measured angle, else "ok".

c: float

Beam attenuation, 1/m, measured with a transmissometer.

b: float

the vsf integrated over all angles, including the report’s extension below 0.1 degree.

Type:

Scattering coefficient s, 1/m

a: float

c - b.

Type:

Absorption, 1/m

backscatter_ratio: float

B/S, the share of b scattered beyond 90 degrees, as printed.

fraction_below_0_1_deg: float

The share of b that lies below 0.1 degree, where nothing was measured and the report extended the vsf with a power law.

phase_function() → ndarray

The vsf divided by b, 1/sr.

Over the whole sphere it integrates to one, but only with the part below 0.1 degree that the samples do not show: fraction_below_0_1_deg of it, 3 to 15 percent.

mean_cosine() → float

The mean cosine of the scattering angle, the asymmetry g.

2 pi times the integral of the phase function times cos(theta) sin(theta) from 0.1 to 180 degrees, the vsf taken as a power law between the printed angles as vsf_at() takes it, plus fraction_below_0_1_deg at a cosine of 1.

That share, 3.4 to 14.5 percent of b, is the report’s power-law extension at every station, and it enters at full weight, so this always warns with ProvenanceWarning. Normalised by the printed b, which includes the same extension.

vsf_at(angle_deg)

The vsf at angle_deg, interpolated linearly in log-log.

Refuses angles outside 0.1 to 180 degrees. Below 0.169 degree at the Bahamas and Catalina stations the values are the report’s own extension, and a ProvenanceWarning says so.

jerlov.PETZOLD_STATIONS = ('AUTEC 8', 'AUTEC 9', 'AUTEC 7', 'HAOCE 11', 'HAOCE 5', 'NUC 2240', 'NUC 2200', 'NUC 2040')

The eight ocean stations, clearest first by b.

jerlov.forward_scatter(scattering: ScatteringFunction, half_angle_deg) → ForwardScatter

The share of a measured water’s scattering within a half-angle, and the attenuation of the light that stays within it.

A receiver that accepts light within theta0 of a beam’s direction, as a transmissometer does, reads, in single scattering:

c_within = c - b(< theta0),
b(< theta0) = 2 pi integral from 0 to theta0 of vsf sin(theta)

between c (theta0 = 0) and a (180 degrees). For an image, light from a target turned by less than theta0 arrives within theta0 of the target’s direction: blurred, not lost. That reading, and single scattering, are assumptions; DECISIONS.md section 107.

Parameters:
  • scattering – One of Petzold’s stations, from petzold_scattering(). No default: which measured water yours resembles is your choice.

  • half_angle_deg – theta0, one number from 0.1 to 180 degrees. Below 0.1 degree nothing was measured, and it is refused.

Returns:

  • ForwardScatter. At the report’s printed angles the share is

  • the report’s own cumulative integral; between them it follows the

  • vsf as a power law, as ScatteringFunction.vsf_at() takes it,

  • scaled to meet the printed values at both ends.

Notes

Every share includes the report’s power-law extension below 0.1 degree, 3.4 to 14.5 percent of b, and at AUTEC 7-9 and HAOCE 5 and 11 its extrapolated angles to 0.159 degree; a ProvenanceWarning says so. DATA.md section 49.

class jerlov.ForwardScatter(station: str, half_angle_deg: float, fraction: float, extension_fraction: float, wavelength_nm: float, c: float, c_within: float)

The share of a Petzold station’s scattering within a half-angle, from forward_scatter().

half_angle_deg: float

light turned by less than this is counted as kept.

Type:

theta0, degrees

fraction: float

the share of the scattering within theta0.

Type:

b(< theta0) / b

extension_fraction: float

The share of b below 0.1 degree, the report’s extension, included in fraction at every theta0.

wavelength_nm: float

530 nm, Petzold’s.

c: float

The station’s beam attenuation, 1/m, as measured.

c_within: float

the attenuation of the light that stays within theta0 of its direction, for the station itself at 530 nm.

Type:

c - b(< theta0), 1/m

jerlov.attenuation_within(water, wavelengths, /, *, forward: ForwardScatter)

A water’s attenuation of the light that stays within a half-angle, with the forward scattering of one of Petzold’s stations:

c_within(lambda) = c(lambda) - f b(lambda),  f = forward.fraction

Between the water’s c and its a. It assumes that the station’s phase function holds for this water and does not change with wavelength; neither is known, which is why forward has no default. DECISIONS.md section 107.

Parameters:
  • water – A Water with a and b.

  • wavelengths – nm, a number or an array, within the water’s range.

  • forward – From forward_scatter(): the station and the half-angle.

Returns:

  • 1/m, a float for a number, an array otherwise. NaN where the water

  • has a gap.

Measured reflectances

jerlov.usgs2017_reflectance(material: str) → MeasuredReflectance

The measured reflectance of one of ten materials.

material is one of USGS2017_MATERIALS: "white_pvc", "black_abs", "grey_concrete", "red_nylon", "orange_cadmium", "yellow_cadmium", "green_tarp", "blue_green_hdpe", "blue_nylon", "violet_cobalt". The three cadmium and cobalt entries are artists’ pigments.

The values are the library’s, at its own wavelengths. Interpolating them onto another grid is the caller’s choice, as for any spectrum in this package; they were measured with a bandpass of a few nm, so finer structure is not in them.

class jerlov.MeasuredReflectance(material: str, record: int, sample: str, wavelengths: ndarray, reflectance: ndarray, citation: str = "Kokaly, R. F. and others (2017), 'USGS Spectral Library Version 7 Data', U.S. Geological Survey data release, doi:10.5066/F7RR1WDJ (CC0 1.0); USGS Data Series 1035, doi:10.3133/ds1035")

One material’s reflectance, as the USGS Spectral Library measured it.

material: str

The key, one of USGS2017_MATERIALS.

record: int

The library’s record number (splib07a).

sample: str

The sample’s name as the library’s ASCII file prints it.

wavelengths: ndarray

the ASD’s channels, each with a bandpass of 3.4 to 8.7 nm (FWHM) in this range.

Type:

350 to 830 nm, every nm

reflectance: ndarray

relative to a Spectralon panel, times the panel’s own reflectance (Data Series 1035, eq. 1, p. 4).

Type:

Absolute reflectance, 0 to 1

jerlov.USGS2017_MATERIALS = ('white_pvc', 'black_abs', 'grey_concrete', 'red_nylon', 'orange_cadmium', 'yellow_cadmium', 'green_tarp', 'blue_green_hdpe', 'blue_nylon', 'violet_cobalt')

The ten materials, neutral first, then by hue from red to violet.

Measured light fields

jerlov.tyler1958_radiance(depth_m: float) → RadianceDistribution

Tyler’s measured radiance distribution at one of his seven depths.

Tyler, J. E. (1958), “Radiance distribution as a function of depth in the submarine environment”, SIO Reference 58-25, Visibility Laboratory, Scripps Institution of Oceanography, Tables IV-X. Lake Pend Oreille, Idaho, 28 April 1957, clear sky, sun altitude 56.6 degrees.

depth_m is one of TYLER1958_DEPTHS. Nothing is interpolated between them.

Notes

The report warns that the reading in the sun’s direction “could be low by a factor of 2 in the worst case” (p. 16), from the glitter of the sun on the surface, whose noise Table XI gives down to 28.95 m. Those cells, at the four depths it lists, are marked suspect, as is one cell with an overstruck digit at 4.24 m; asking for a depth that has any warns. The measurement includes the clear sky’s light and the barge’s shadow, which Tyler read around (pp. 12-13).

class jerlov.RadianceDistribution(depth_m: float, tilt_deg: ndarray, azimuth_deg: ndarray, radiance: ndarray, suspect: tuple[str, ...], sun_altitude_deg: float = 56.6, band_nm: tuple[float, float] = (430.0, 546.0), beam_attenuation: float = 0.3960099493374092, acceptance_deg: float = 6.6)

Tyler’s radiance distribution at one depth.

Built by tyler1958_radiance(). radiance[i, j] is the radiance seen looking at tilt tilt_deg[i] from straight up (0 up, 180 down) and azimuth azimuth_deg[j] from the sun’s, in one relative unit shared by all seven depths. The distribution is taken as symmetric about the sun’s vertical plane, as Tyler tabulated only one side.

depth_m: float
tilt_deg: ndarray
azimuth_deg: ndarray
radiance: ndarray
suspect: tuple[str, ...]

DATA.md section 23.

Type:

The cells marked suspect, with the reason

sun_altitude_deg: float = 56.6

The sun altitude every table is adjusted to (pp. 14-15).

band_nm: tuple[float, float] = (430.0, 546.0)

The extreme limits of the measured band; its half width is 64 nm (p. 5).

beam_attenuation: float = 0.3960099493374092

The beam attenuation c in 1/m, from a beam transmittance of 67.3 percent per metre at the surface, 29 April 1957 (p. 8). The transmissometer’s band is not given.

acceptance_deg: float = 6.6

The radiance tubes’ full angle of acceptance (p. 7).

jerlov.TYLER1958_DEPTHS = (4.24, 10.4, 16.6, 29.0, 41.3, 53.7, 66.1)

The depths of Tyler’s Tables IV to X, m, as the tables print them.

jerlov.darecki2011_irradiance_cv() → IrradianceFluctuation

The coefficient of variation of the downwelling irradiance against depth, at 443, 532 and 670 nm.

Darecki, M., Stramski, D. and Sokolski, M. (2011), “Measurements of high-frequency light fluctuations induced by sea surface waves with an Underwater Porcupine Radiometer System”, J. Geophys. Res. 116, C00H09, doi:10.1029/2011JC007338, Figure 13a, p. 12.

Read off the figure’s drawing commands, not printed: DATA.md section 24. The three wavelengths were measured at the same six depths.

class jerlov.IrradianceFluctuation(depth_m: ndarray, wavelengths_nm: ndarray, cv: ndarray, cv_reading: float = 0.0002, place: str = 'Santa Barbara Channel, 11 September 2008, 11:35-12:56 local time', sun_zenith_deg: tuple[float, float] = (30.0, 33.0), wind_m_s: tuple[float, float] = (4.1, 6.4), beam_attenuation_555: float = 0.68, collector_mm: float = 2.5)

Darecki et al.’s (2011) Figure 13a: the coefficient of variation, standard deviation over mean, of the downwelling irradiance, sampled at 1 kHz, at six depths and three wavelengths. Built by darecki2011_irradiance_cv(); cv[i, j] is at depth_m[i] and wavelengths_nm[j], a ratio, not a percentage.

depth_m: ndarray
wavelengths_nm: ndarray
cv: ndarray
cv_reading: float = 0.0002

the axis’s own tick marks lie up to 0.0001 off a straight line, and the values are kept to four places.

Type:

How closely cv is read

place: str = 'Santa Barbara Channel, 11 September 2008, 11:35-12:56 local time'
sun_zenith_deg: tuple[float, float] = (30.0, 33.0)
wind_m_s: tuple[float, float] = (4.1, 6.4)
beam_attenuation_555: float = 0.68

c at 555 nm, 1/m, as the caption gives it.

collector_mm: float = 2.5

larger ones average the flashes away and read a smaller CV.

Type:

The diameter of the irradiance collector (p. 12)

jerlov.darecki2011_radiance_cv(panel: str) → RadianceFluctuation

The coefficient of variation of the radiance against zenith angle, in the plane of the sun, from one panel of Figure 15.

panel is one of DARECKI2011_PANELS. Darecki et al. (2011), as for darecki2011_irradiance_cv(), Figure 15, p. 14; the conditions are the caption’s. Read off the figure’s drawing commands: DATA.md section 24.

class jerlov.RadianceFluctuation(panel: str, zenith_deg: ndarray, cv: ndarray, place: str, depth_m: float, sun_zenith_deg: float, refracted_sun_zenith_deg: float, wind_m_s: float, beam_attenuation_555: float, cv_reading: float = 0.002, wavelength_nm: float = 532.0, field_of_view_deg: float = 4.5)

One panel of Darecki et al.’s (2011) Figure 15: the coefficient of variation of the radiance at 532 nm, at thirteen zenith angles in the plane of the sun, positive towards the sun. Built by darecki2011_radiance_cv().

panel: str
zenith_deg: ndarray
cv: ndarray
place: str
depth_m: float
sun_zenith_deg: float
refracted_sun_zenith_deg: float

The mean zenith angle of the sunbeam in the water, as the caption gives it.

wind_m_s: float
beam_attenuation_555: float
cv_reading: float = 0.002

the tick marks lie up to 0.001 off a straight line.

Type:

How closely cv is read

wavelength_nm: float = 532.0
field_of_view_deg: float = 4.5

The radiance sensors’ field of view in water (p. 4).

jerlov.DARECKI2011_PANELS = ('a', 'b', 'c')

The three panels of Darecki et al.’s (2011) Figure 15.

jerlov.darecki2011_spectral_cv() → SpectralFluctuation

The coefficient of variation of the downwelling irradiance against wavelength, 410 to 670 nm, at about 1 m on five days of different wind.

Darecki et al. (2011), as for darecki2011_irradiance_cv(), Figure 13b, p. 12; the conditions are the caption’s. Read off the figure’s drawing commands: DATA.md section 24.

class jerlov.SpectralFluctuation(wind_m_s: ndarray, wavelengths_nm: ndarray, cv: ndarray, days: tuple[str, ...], cv_reading: float = 0.0002, place: str = 'Santa Barbara Channel, September 2008', depth_m: tuple[float, float] = (0.91, 1.25), sun_zenith_deg: tuple[float, float] = (42.0, 46.0), beam_attenuation_555: tuple[float, float] = (0.55, 0.78), collector_mm: float = 2.5)

Darecki et al.’s (2011) Figure 13b: the coefficient of variation of the downwelling irradiance at about 1 m, at six wavelengths, on five days of different wind. Built by darecki2011_spectral_cv(); cv[i, j] is at wind_m_s[i] and wavelengths_nm[j].

wind_m_s: ndarray
wavelengths_nm: ndarray
cv: ndarray
days: tuple[str, ...]

The date and local time of each wind’s measurement, as the caption gives them.

cv_reading: float = 0.0002
place: str = 'Santa Barbara Channel, September 2008'
depth_m: tuple[float, float] = (0.91, 1.25)
sun_zenith_deg: tuple[float, float] = (42.0, 46.0)
beam_attenuation_555: tuple[float, float] = (0.55, 0.78)
collector_mm: float = 2.5
jerlov.gernez2009_cv_by(variable: str, sky: str = 'clear', irradiance: str = 'Ed') → ConditionFluctuation

The coefficient of variation of the irradiance at 510 nm at the upper depth, and the period of its strongest fluctuation, against one of the conditions: the sun’s zenith angle, the wave height, the wind or Kd(490).

sky is "clear" or "overcast" and irradiance "Ed" or "Eu"; GERNEZ2009_PLOTS gives the variables for each pair the paper plots. Gernez, P. and Antoine, D. (2009), “Field characterization of wave-induced underwater light field fluctuations”, J. Geophys. Res. 114, C06025, doi:10.1029/2008JC005059: Figures 8a-8d (clear, Ed, p. 9), 7 (overcast, Ed, p. 8) and 13 (clear, Eu, p. 12). Read off the figures’ pixels: DATA.md section 25. The values are the medians of each class; the period’s standard deviation is not read, and that of CV only where its bar is clear.

An unknown variable, sky or irradiance raises ValueError; up to 0.23.0 it raised KeyError (DECISIONS.md section 61).

class jerlov.ConditionFluctuation(variable: str, x: ndarray, irradiance: str, figure: str, cv: ndarray, cv_sd: ndarray, tmax_s: ndarray, tmax_reading_s: ndarray, cv_reading: float = 0.0011, place: str = 'BOUSSOLE buoy, Ligurian Sea', wavelength_nm: float = 510.0, depth_m: tuple[float, float] = (2.7, 3.7), collector_mm: float = 8.0, sampling_hz: float = 6.0, sky: str = 'clear: above-water irradiance at least 0.85 of the clear-sky model')

One panel of Gernez & Antoine’s (2009) Figures 7, 8 or 13: the median coefficient of variation of the irradiance at 510 nm at the upper depth, its standard deviation, and the median period of the strongest fluctuation, against one of the conditions in GERNEZ2009_PLOTS. Built by gernez2009_cv_by().

variable: str
x: ndarray

The class, in the unit the variable’s name gives.

irradiance: str

"Ed", downwelling, or "Eu", upwelling.

figure: str

"8", "7" or "13".

Type:

The paper’s figure

cv: ndarray
cv_sd: ndarray

The standard deviation of CV among the minutes in each class; nan where the figure’s bar cannot be told from the other series’.

tmax_s: ndarray
tmax_reading_s: ndarray
cv_reading: float = 0.0011
place: str = 'BOUSSOLE buoy, Ligurian Sea'
wavelength_nm: float = 510.0
depth_m: tuple[float, float] = (2.7, 3.7)
collector_mm: float = 8.0
sampling_hz: float = 6.0
sky: str = 'clear: above-water irradiance at least 0.85 of the clear-sky model'
jerlov.GERNEZ2009_PLOTS = {('clear', 'Ed'): ('sun_zenith_deg', 'wave_height_m', 'sqrt_wind', 'kd490_per_m'), ('clear', 'Eu'): ('sun_zenith_deg', 'wave_height_m', 'wind_m_s', 'kd490_per_m'), ('overcast', 'Ed'): ('sun_zenith_deg', 'wave_height_m', 'wind_m_s', 'kd490_per_m')}

For each sky and irradiance that Gernez & Antoine (2009) plot against the conditions, what they plot them against: Figure 8b-d (clear sky, downwelling), Figure 7 (overcast, downwelling) and Figure 13 (clear sky, upwelling), all at the upper depth. wind_m_s is the wind speed itself, in m/s.

jerlov.GERNEZ2009_VARIABLES = ('wave_height_m', 'sqrt_wind', 'kd490_per_m')

What Gernez & Antoine’s (2009) Figures 8b, 8c and 8d are plotted against: the wave height, m; the square root of the wind speed, the wind in m/s; and Kd at 490 nm, 1/m. Figure 8a, against the sun’s zenith angle, is not among them: GERNEZ2009_PLOTS lists all four panels.

jerlov.gernez2009_cv_by_sun_zenith() → SunZenithFluctuation

The coefficient of variation of the downwelling irradiance at 510 nm, and the period of its strongest fluctuation, against the sun’s zenith angle, under clear skies.

Superseded in 0.24.0 by gernez2009_cv_by("sun_zenith_deg"), which gives the same values as a ConditionFluctuation, like the other panels. This raises a FutureWarning and will be removed in 2.0 (DECISIONS.md section 61).

Gernez, P. and Antoine, D. (2009), “Field characterization of wave-induced underwater light field fluctuations”, J. Geophys. Res. 114, C06025, doi:10.1029/2008JC005059, Figure 8a, p. 9.

Read off the figure’s pixels, not printed: DATA.md section 25. The standard deviation of the period is in the figure but cannot be read: its dashed bars end between dashes.

class jerlov.SunZenithFluctuation(sun_zenith_deg: ndarray, cv: ndarray, cv_sd: ndarray, tmax_s: ndarray, tmax_reading_s: ndarray, cv_reading: float = 0.0011, place: str = 'BOUSSOLE buoy, Ligurian Sea', wavelength_nm: float = 510.0, depth_m: tuple[float, float] = (2.7, 3.7), collector_mm: float = 8.0, sampling_hz: float = 6.0, sky: str = 'clear: above-water irradiance at least 0.85 of the clear-sky model')

Gernez & Antoine’s (2009) Figure 8a: under clear skies, the median coefficient of variation of the downwelling irradiance at 510 nm, its standard deviation, and the median period of the strongest fluctuation, against the sun’s zenith angle. Built by gernez2009_cv_by_sun_zenith(), which is superseded by gernez2009_cv_by("sun_zenith_deg"); CV as a ratio.

sun_zenith_deg: ndarray
cv: ndarray
cv_sd: ndarray

The standard deviation of CV among the minutes in each class.

tmax_s: ndarray
tmax_reading_s: ndarray

How closely tmax_s is read, one or two pixels of the figure.

cv_reading: float = 0.0011

one pixel of the figure.

Type:

How closely cv and cv_sd are read

place: str = 'BOUSSOLE buoy, Ligurian Sea'
wavelength_nm: float = 510.0
depth_m: tuple[float, float] = (2.7, 3.7)

The nominal depth of the upper radiometers, which changed between deployments (p. 3).

collector_mm: float = 8.0
sampling_hz: float = 6.0

Fluctuations shorter than a third of a second are not resolved (p. 4).

sky: str = 'clear: above-water irradiance at least 0.85 of the clear-sky model'
jerlov.gernez2009_spectral_cv(irradiance: str = 'Ed') → SkySpectralFluctuation

The average coefficient of variation and period of the strongest fluctuation at 412 to 683 nm, under clear and overcast skies: of the downwelling irradiance at the upper depth ("Ed", Figure 11, p. 11) or of the upwelling at the lower depth, 8 to 8.7 m ("Eu", Figure 14, p. 13).

Gernez & Antoine (2009), as for gernez2009_cv_by(). Read off the figures’ pixels: DATA.md section 25. The captions call these averages, not medians. The overcast standard deviations are drawn dotted and not read. An unknown irradiance raises ValueError (KeyError up to 0.23.0).

class jerlov.SkySpectralFluctuation(irradiance: str, figure: str, wavelengths_nm: ndarray, cv: ndarray, cv_sd: ndarray, tmax_s: ndarray, tmax_sd_s: ndarray, cv_reading: float, tmax_reading_s: float, depth_m: tuple[float, float], skies: tuple[str, str] = ('clear', 'overcast'), place: str = 'BOUSSOLE buoy, Ligurian Sea', collector_mm: float = 8.0, sampling_hz: float = 6.0)

Gernez & Antoine’s (2009) Figure 11 (downwelling irradiance, upper depth) or 14 (upwelling, lower depth): the average coefficient of variation and period of the strongest fluctuation at seven wavelengths, under clear and overcast skies. Built by gernez2009_spectral_cv(); cv[i, j] is for skies[i] at wavelengths_nm[j].

irradiance: str
figure: str
wavelengths_nm: ndarray
cv: ndarray
cv_sd: ndarray

The standard deviation among the minutes; nan for the overcast sky, whose dotted bars are not read.

tmax_s: ndarray
tmax_sd_s: ndarray
cv_reading: float
tmax_reading_s: float
depth_m: tuple[float, float]
skies: tuple[str, str] = ('clear', 'overcast')
place: str = 'BOUSSOLE buoy, Ligurian Sea'
collector_mm: float = 8.0
sampling_hz: float = 6.0
jerlov.gernez2009_band_cv(variable: str) → BandConditionFluctuation

The median coefficient of variation of the downwelling irradiance at 443, 490, 510, 560, 670 and 683 nm, at the upper depth under clear skies, against the sun’s zenith angle, the wave height, the wind speed or Kd(490): Gernez & Antoine (2009), Figure 10 (p. 11), as for gernez2009_cv_by().

Read off the figure’s coloured lines: DATA.md section 25. The 510 nm line is Figure 8’s medians. The periods, drawn in the same colours, are not read. An unknown variable raises ValueError (KeyError up to 0.23.0).

class jerlov.BandConditionFluctuation(variable: str, x: ndarray, wavelengths_nm: ndarray, cv: ndarray, cv_reading: float, place: str = 'BOUSSOLE buoy, Ligurian Sea', depth_m: tuple[float, float] = (2.7, 3.7), collector_mm: float = 8.0, sampling_hz: float = 6.0, sky: str = 'clear: above-water irradiance at least 0.85 of the clear-sky model')

One panel of Gernez & Antoine’s (2009) Figure 10: the median coefficient of variation of the downwelling irradiance at the upper depth under clear skies, at six bands, against one of GERNEZ2009_BAND_VARIABLES. Built by gernez2009_band_cv(); cv[i, j] is at x[i] and wavelengths_nm[j].

variable: str
x: ndarray
wavelengths_nm: ndarray
cv: ndarray

nan where the line leaves the figure’s axes, above 35 percent.

cv_reading: float
place: str = 'BOUSSOLE buoy, Ligurian Sea'
depth_m: tuple[float, float] = (2.7, 3.7)
collector_mm: float = 8.0
sampling_hz: float = 6.0
sky: str = 'clear: above-water irradiance at least 0.85 of the clear-sky model'
jerlov.GERNEZ2009_BAND_VARIABLES = ('sun_zenith_deg', 'wave_height_m', 'wind_m_s', 'kd490_per_m')

What Gernez & Antoine’s (2009) Figure 10, CV at six bands, is plotted against: as Figure 8, but the wind speed itself, in m/s.

jerlov.gernez2009_diffuse_share() → DiffuseShare

The share of diffuse light in the above-water downwelling irradiance under a clear sky, every 10 degrees of the sun’s zenith angle from 20 to 90, as Gernez & Antoine (2009) print it along the top of Figures 8a and 10a, from a model of the sky (DiffuseShare.model), not a measurement.

Whole percents as printed. The axis is labelled Ediffuse / Etotal; the caption of Figure 8 calls it the ratio of direct to total, which the numbers, rising to 100 percent at the horizon, are not: DATA.md section 25.

class jerlov.DiffuseShare(sun_zenith_deg: ndarray, diffuse_fraction: ndarray, model: str = "Gregg and Carder (1990), with the buoy's air pressure, 80 percent relative humidity, TOMS ozone and a maritime aerosol of Shettle and Fenn (1979) of optical thickness 0.2 at 550 nm (p. 4)", wavelength_nm: float = nan)

The share of diffuse light in the downwelling irradiance above the water that Gernez & Antoine (2009) print along the top of their Figures 8a and 10a. Built by gernez2009_diffuse_share().

sun_zenith_deg: ndarray
diffuse_fraction: ndarray
model: str = "Gregg and Carder (1990), with the buoy's air pressure, 80 percent relative humidity, TOMS ozone and a maritime aerosol of Shettle and Fenn (1979) of optical thickness 0.2 at 550 nm (p. 4)"
wavelength_nm: float = nan

Not stated.

Visual pigments and receptor noise

jerlov.visual_pigment_template(wavelengths, /, *, lambda_max: float, chromophore: str, beta: bool = True)

The absorbance of a visual pigment, relative to its peak.

Govardovskii, V. I., Fyhrquist, N., Reuter, T., Kuzmin, D. G. and Donner, K. (2000), “In search of the visual pigment template”, Visual Neuroscience 17, 509-528, doi:10.1017/S0952523800174036.

The alpha-band is Lamb’s (1995) form, eq. (1):

S(x) = 1 / (exp[A(a - x)] + exp[B(b - x)] + exp[C(c - x)] + D)

with x = lambda_max / wavelength and the constants of p. 515 and eq. (2) for A1 pigments, of p. 517 and eqs. (6a) and (6b) for A2. The beta-band is the Gaussian of eq. (4), from eqs. (5a) and (5b) for A1 and (8a) and (8b) for A2.

Parameters:
  • wavelengths – nm, a number or an array; each above 330 nm, the range the paper gives its templates for (p. 525).

  • lambda_max – The wavelength of the alpha-band’s peak, nm, above 350 nm (the paper’s abstract). It belongs to the species and the cell, so it has no default.

  • chromophore – "A1" or "A2", the pigment’s chromophore. The two have different templates, and the paper measured both in fish and amphibians (Table 1), so it has no default either.

  • beta – True for the sum of the two bands, which the paper calls a complete description of the absorbance (p. 525); False for the alpha-band alone.

Returns:

  • A float for a number, an array otherwise. The alpha-band as printed

  • peaks within 0.2 percent of 1, not at exactly 1, and within 0.5 nm of

  • lambda_max; it is returned as printed.

Notes

The amplitude of A2’s beta-band has no equation in the paper, which says it “shows no correlation with lambda_max” and fixed it at 0.37 where the beta-peak lay outside the recording (p. 517). This uses that 0.37.

The paper’s own measurements have peaks from 357 to 569 nm for A1 and from 444 to 619 nm for A2 (Table 1). A lambda_max outside those gives the template the paper claims for it, with a ProvenanceWarning. DECISIONS.md section 64.

jerlov.receptor_noise_distance(catches_a, catches_b, /, *, noise)

The distance between two colours in units of receptor noise.

Vorobyev, M. and Osorio, D. (1998), “Receptor noise as a determinant of colour thresholds”, Proc. R. Soc. Lond. B 265, 351-358, doi:10.1098/rspb.1998.0302.

Colour is taken to be coded by n - 1 opponent channels whose form does not matter, with the achromatic signal disregarded, and discrimination to be limited by noise in the receptors, independent between them (p. 352). The distance between two stimuli is then their general form (A7), p. 356, which this computes for any number of receptor types; for two, three and four it is their eqs. (3) to (5), p. 353.

Parameters:
  • catches_a – The quantum catch of each receptor type, scaled so that the background gives 1 in every receptor (eqs. 1 and 2). With sensitivities r on r_wl, shape (m, k) for k receptor types, integrate_response(spectrum, wl, r, r_wl) / integrate_response(background, wl, r, r_wl), with both spectra in photons: a catch counts photons, and an energy spectrum would weight each wavelength differently. The receptor types run along the last axis; other axes broadcast.

  • catches_b – The quantum catch of each receptor type, scaled so that the background gives 1 in every receptor (eqs. 1 and 2). With sensitivities r on r_wl, shape (m, k) for k receptor types, integrate_response(spectrum, wl, r, r_wl) / integrate_response(background, wl, r, r_wl), with both spectra in photons: a catch counts photons, and an energy spectrum would weight each wavelength differently. The receptor types run along the last axis; other axes broadcast.

  • noise – The standard deviation of the noise in each receptor channel, e_i, in the same scaled units, one for each receptor type. No default: the paper derives it from the noise of one cell and the number of cells, e_i = nu_i / sqrt(eta_i) (eq. 7), and both belong to the species.

Returns:

  • Delta S (a float for one pair of stimuli, an array otherwise. Stimuli)

  • are indistinguishable when it is below a threshold distance, which

  • depends on the criterion adopted (p. 353).

Notes

The model holds for stimuli close to the background, in bright light, for large static targets on an achromatic background (p. 353), and is linear in the differences of the scaled catches, as the paper gives it. The logarithmic form used in later work is not this paper’s, and is not included.

The paper’s eq. (4), for three receptor types, prints its last term as e_3^2 (Delta q_1 - q_2)^2; computed from (A7), as the paper says it is, it is e_3^2 (Delta q_1 - Delta q_2)^2 (DECISIONS.md section 64).

The irradiance at the sea surface under a clear sky

jerlov.gregg1990_irradiance(wavelength_nm, /, *, sun_zenith_deg, day_of_year, pressure_hpa, air_mass_type, relative_humidity, precipitable_water_cm, wind_speed_24h, wind_speed, ozone_du, visibility_km=None, aerosol_optical_thickness_550=None) → SurfaceIrradiance

Direct and diffuse irradiance at the sea surface under a clear sky.

The model of Gregg and Carder (1990), Limnol. Oceanogr. 35(8), 1657-1675, doi:10.4319/lo.1990.35.8.1657, eqs. (2)-(47), with the sun’s spectrum and the ozone, water vapour and oxygen absorption of its Table 1. Section 76 of DECISIONS.md gives the design.

Parameters:
  • wavelength_nm – Whole nanometres from 350 to 700, the rows of Table 1; a number or an array. Nothing is interpolated.

  • sun_zenith_deg – The sun’s zenith angle, degrees, 0 up to but not including 90.

  • day_of_year – 1-366, for the earth’s distance from the sun, eq. (12).

  • pressure_hpa – Air pressure at the surface, hPa (mb).

  • air_mass_type – 1 (open-ocean aerosol) to 10 (continental), eq. (21).

  • relative_humidity – Percent, 0 up to but not including 100 (eq. 24 divides by zero there).

  • precipitable_water_cm – Total precipitable water vapour, cm.

  • wind_speed_24h – Wind speed averaged over the previous 24 hours, m/s, eq. (22).

  • wind_speed – The wind speed now, m/s: the large aerosol particles, eq. (23), and the sea surface’s reflectance, eqs. (39)-(47).

  • ozone_du – Total ozone, Dobson units.

  • visibility_km – Exactly one. The paper takes the visibility V and sets tau_a(550) = 3.91 / V with a 1 km scale height (eqs. 28, 29); a measured tau_a(550) replaces that step and nothing else. Neither raises MissingQuantityError, both ValueError.

  • aerosol_optical_thickness_550 – Exactly one. The paper takes the visibility V and sets tau_a(550) = 3.91 / V with a 1 km scale height (eqs. 28, 29); a measured tau_a(550) replaces that step and nothing else. Neither raises MissingQuantityError, both ValueError.

  • default (No input has a)

  • 2 (The paper's observations spanned (Table)

  • hPa (p. 1667) 1002-1019)

  • air

  • 1-10 (mass type)

  • percent (humidity 46-91)

  • water (1.8-4.7 cm of)

  • wind (mean)

  • m/s (1.7-4.2 and wind 0-5.7)

  • km (visibility 8-24)

  • sun (263-313 DU and the)

  • the (29-82 degrees from the zenith; it states no limit beyond which)

  • fails (model)

  • warns. (and nothing here)

Returns:

In W m-2 nm-1, shaped like wavelength_nm.

Return type:

SurfaceIrradiance

Notes

Clouds are not modelled, nor the light reflected between the sea and the sky, which the paper drops (p. 1661). Eq. (44) is printed with a second 1/2 inside Fresnel’s law; it is used without it (DATA.md section 35).

class jerlov.SurfaceIrradiance(wavelengths: ndarray, direct_above: ndarray, diffuse_above: ndarray, direct_below: ndarray, diffuse_below: ndarray, angstrom_exponent: float, aerosol_optical_thickness: ndarray, direct_reflectance: float, diffuse_reflectance: float)

Downwelling irradiance at the sea surface, W m-2 nm-1.

“Above” is just above the surface (eqs. 2, 4 and 6 of Gregg and Carder 1990, without the ground-air term the paper drops); “below” is just beneath it, after the surface’s reflection (eqs. 9 and 10).

angstrom_exponent: float

alpha of eq. (26), from the aerosol model.

aerosol_optical_thickness: ndarray

tau_a at each wavelength, eq. (27).

direct_reflectance: float

specular and foam.

Type:

rho_d, eq. (37)

diffuse_reflectance: float

specular and foam.

Type:

rho_s, eq. (38)

property above: ndarray

Global irradiance just above the surface.

property below: ndarray

Global irradiance just below the surface, eq. (11).

Coefficients for renderers

jerlov.rgb_attenuation(water, /, *, colour_space, illuminant, distance_range_m) → RgbAttenuation

Extinction, absorption and scattering per channel of an RGB space.

A renderer in RGB attenuates each channel as exp(-sigma r). Light of spectrum S that has crossed r metres of water has the spectrum S exp(-c r), and its channel k is R_k(r) = M_k . XYZ, with M the space’s matrix from XYZ. The channel’s transmittance T_k(r) = R_k(r) / R_k(0) is not one exponential, and depends on S. So sigma_k is fitted, by least squares in ln T_k at 201 evenly spaced distances over distance_range_m, through T = 1 at r = 0, and the result says how far the fit is from T_k.

Parameters:
  • water – A Water with a and b.

  • colour_space – One of RGB_COLOUR_SPACES, linear: "linear_srgb", "acescg" or "rec2020". No default.

  • illuminant – (wavelengths, power), the light entering the water, as jerlov.d65() returns it. No default: above the sea D65 is one choice and jerlov.gregg1990_irradiance() another; under water, the light at that depth.

  • distance_range_m – (near, far) in metres, 0 <= near < far. No default.

Returns:

  • RgbAttenuation. sigma_t is fitted from c, sigma_a from a, and

  • sigma_s = sigma_t - sigma_a.

Raises:
  • ValueError – When a channel’s transmittance falls to zero or below inside the range. Clear water leaves a blue-green light outside the sRGB gamut after a few metres, and the red channel, whose matching function is negative there, goes below zero. The message gives the largest distance at which every channel is still positive; a narrower range or a wider space is the remedy. Also for a gap (NaN) in a or c where the colour is formed, an illuminant with no power in a channel, a sigma_t or sigma_a that is not positive (a channel that grows across the water), and a negative sigma_s.

  • MissingQuantityError – When the water has no a or no b.

Notes

The spectra are integrated at 1 nm where the water, the illuminant and the CIE 1931 observer overlap; a CoverageWarning says when that leaves part of the observer out. Flagged values of a, b or c warn with ProvenanceWarning, as they do from Water. No chromatic adaptation is made: a ratio within one channel needs none. RgbAttenuation.illuminant_rgb gives the illuminant’s own colour in the space, for the light in the scene.

class jerlov.RgbAttenuation(colour_space: str, distance_range_m: tuple[float, float], wavelength_range_nm: tuple[float, float], illuminant_rgb: ndarray, sigma_t: ndarray, sigma_a: ndarray, sigma_s: ndarray, max_relative_error_t: ndarray, max_relative_error_a: ndarray, water: str, source: str)

Coefficients per channel of a linear RGB space, 1/m.

Each is the exponent of one exponential fitted to the channel’s true transmittance over distance_range_m; the true transmittance is not one exponential, and max_relative_error_t and max_relative_error_a say how far the fit is from it.

colour_space: str

One of RGB_COLOUR_SPACES.

distance_range_m: tuple[float, float]

The distances the fit was made over, (near, far) in metres.

wavelength_range_nm: tuple[float, float]

Where the water, the illuminant and the CIE 1931 observer overlap, integrated at 1 nm.

illuminant_rgb: ndarray

The illuminant’s RGB in this space, scaled so that its luminance Y is 1: the colour to give the light in the scene.

sigma_t: ndarray

Extinction per channel, fitted from c.

sigma_a: ndarray

Absorption per channel, fitted from a.

sigma_s: ndarray

Scattering per channel, sigma_t - sigma_a, so that the three add up as a renderer assumes.

max_relative_error_t: ndarray

The largest abs(exp(-sigma_t r) / T(r) - 1) over the range, per channel, with T the channel’s transmittance through c.

max_relative_error_a: ndarray

The same for sigma_a and the transmittance through a alone.

water: str

Which water the coefficients came from.

source: str

The source’s citation, or an empty string for the caller’s own.

property albedo: ndarray

Single-scattering albedo per channel, sigma_s / sigma_t.

as_dict() → dict[str, Any]

Plain numbers, lists and strings, for json.dump().

jerlov.RGB_COLOUR_SPACES = ('linear_srgb', 'acescg', 'rec2020')

The linear RGB spaces rgb_attenuation() works in. Each is its primaries and white, as chromaticities: no transfer function is applied, since renderers take coefficients in linear values.

jerlov.rgb_transmittance(water, distances_m, /, *, colour_space, illuminant) → RgbTransmittance

The transmittance per channel of an RGB space, at given distances.

For each distance r, T_k(r) = R_k(S exp(-c r)) / R_k(S): the light S of the illuminant after r metres of water, in channel k of the space, over the same light before it. This is the transmittance rgb_attenuation() fits one exponential to; here it is returned as it is, for a renderer that reads a table (DECISIONS.md section 84).

Parameters:
  • water – A Water with a and b.

  • distances_m – A number or an array of numbers, in metres, finite and not negative, in any order. The result has its shape plus a last axis of three channels.

  • colour_space – One of RGB_COLOUR_SPACES. No default.

  • illuminant – (wavelengths, power), the light that enters the water, as jerlov.d65() returns it. No default. For a table by depth, pass the light at each depth, from Scene.at_depth() or a measurement: how the light got down is the caller’s choice.

Raises:
  • ValueError – When a channel is at zero or below at a requested distance: the light left lies outside the space’s gamut. The message gives the distance up to which every channel stays positive. Also for a gap (NaN) in c where the colour is formed, and an illuminant with no power in a channel.

  • MissingQuantityError – When the water has no a or no b.

Notes

As for rgb_attenuation(), the spectra are integrated at 1 nm where the water, the illuminant and the CIE 1931 observer overlap, and the water’s flagged values warn with ProvenanceWarning.

class jerlov.RgbTransmittance(colour_space: str, distances_m: ndarray, transmittance: ndarray, wavelength_range_nm: tuple[float, float], illuminant_rgb: ndarray, water: str, source: str)

The transmittance per channel of a linear RGB space, by distance.

Nothing is fitted: each value is the channel’s own transmittance of the illuminant’s light through c, as rgb_attenuation() defines it before fitting one exponential to it.

colour_space: str

One of RGB_COLOUR_SPACES.

distances_m: ndarray

The distances asked for, in metres, in the shape given.

transmittance: ndarray

T per channel, the shape of distances_m plus a last axis of three: red, green, blue.

wavelength_range_nm: tuple[float, float]

Where the water, the illuminant and the CIE 1931 observer overlap, integrated at 1 nm.

illuminant_rgb: ndarray

The illuminant’s RGB in this space, scaled so that its luminance Y is 1.

source: str

The source’s citation, or an empty string for the caller’s own.

as_dict() → dict[str, Any]

Plain numbers, lists and strings, for json.dump().

jerlov.henyey_greenstein_fit(scattering, /, *, method) → HenyeyGreensteinFit

The g of a Henyey-Greenstein phase function for a Petzold station.

Parameters:
  • scattering – A ScatteringFunction, from petzold_scattering().

  • method –

    What g is made to match. No default:

    • "backscatter_ratio": the HG scatters the station’s printed B/S beyond 90 degrees. B(g) = (1 - g) / (2 g) [(1 + g) / sqrt(1 + g^2) - 1] is solved by bisection.

    • "mean_cosine": g is the station’s mean cosine, ScatteringFunction.mean_cosine(). It rests at full weight on the report’s extension below 0.1 degree and warns with ProvenanceWarning.

Notes

HG has one parameter and cannot match both: matched to B/S, its mean cosine is lower than the station’s; matched to the mean cosine, it backscatters less than the station. At small angles it falls short of the measurement by tens to hundreds of times whichever is matched; HenyeyGreensteinFit.log_ratio gives the shortfall at each of Petzold’s angles. Petzold measured in one band in the green, total scattering of water and particles; a renderer will apply the one g at every wavelength.

class jerlov.HenyeyGreensteinFit(station: str, wavelength_nm: float, method: str, g: float, backscatter_ratio: float, measured_backscatter_ratio: float, angles_deg: ndarray, log_ratio: ndarray)

A Henyey-Greenstein g for one of Petzold’s stations, and its error.

The phase function is p(theta) = (1 - g^2) / (4 pi (1 + g^2 - 2 g cos theta)^(3/2)). It fits ocean water badly at small angles, and log_ratio shows where.

wavelength_nm: float

530 nm, the wavelength of Petzold’s c. One g serves every wavelength in a renderer; nothing here varies it.

method: str

What g was made to match, "backscatter_ratio" or "mean_cosine".

backscatter_ratio: float

The HG’s share beyond 90 degrees.

measured_backscatter_ratio: float

The station’s B/S, as printed.

angles_deg: ndarray

Petzold’s 55 angles.

log_ratio: ndarray

ln(p_HG / p) at each angle, p the measured phase function, vsf / b. Negative where HG falls short of the measurement.

as_dict() → dict[str, Any]

Plain numbers, lists and strings, for json.dump().

jerlov.spectral_coefficients(water, /, *, range_nm) → SpectralCoefficients

a, b and c at the water’s own wavelengths inside range_nm.

Parameters:
  • water – A Water with a and b.

  • range_nm – (low, high) in nm, inside the water’s range. No default: a spectral renderer samples where its observer or camera is sensitive, and the water’s range may run past that into flagged values.

Notes

Gaps stay NaN; flagged values warn with ProvenanceWarning when the result is made, and each value carries its status.

class jerlov.SpectralCoefficients(wavelengths: ndarray, a: ndarray, b: ndarray, c: ndarray, a_status: tuple[str, ...], b_status: tuple[str, ...], water: str, source: str)

a, b and c at a water’s own wavelengths, 1/m, for spectral renderers. Nothing is resampled: a renderer interpolates them as it does its own spectra.

c: ndarray

a + b.

a_status: tuple[str, ...]

The status of each value of a, as in “The status column” of DATA.md.

source: str

The source’s citation, or an empty string for the caller’s own.

property albedo: ndarray

Single-scattering albedo, b / c.

as_dict() → dict[str, Any]

Plain numbers, lists and strings, for json.dump().

A gap (NaN) becomes None, JSON’s null.

Radiative transfer codes: input files and OSOAA’s results

What each code adds back, and what was run, are in DATA.md section 38.

jerlov.osoaa_user_profile(water, wavelength_nm, /, *, depths_m, pure_water) → str

OSOAA’s -HYD.UserProfile file for a water at one wavelength.

Five comment lines, then for each depth: the depth (m), the hydrosols’ absorption a - a_w and their scattering b - b_w (1/m), the format of the OSOAA User Manual V2.0, section 3.6.4, pp. 81-82. OSOAA runs at one wavelength (-OSOAA.Wa), adds its own pure seawater back, and takes this file with -HYD.Model 3.

Parameters:
  • water – A Water with a and b.

  • wavelength_nm – The run’s wavelength, a number, inside the water’s range.

  • depths_m – Starting at 0, just below the surface, ascending, fewer than 500 (OSOAA’s limit). A Jerlov type does not vary with depth, so every depth carries the same values; OSOAA repeats the deepest to the seabed.

  • pure_water – (a_w, b_w) at the wavelength, 1/m: the pure seawater OSOAA will add back, which its file fic/OSOAA_SEA_MOL_COEFFS_JUNE_2013.txt tabulates. No default.

Raises:

ValueError – When a - a_w or b - b_w is negative, and for any input that is not a number, finite, or in range.

jerlov.osoaa_phase_function(scattering, /, *, minus_f12_over_f11, f22_over_f11, f33_over_f11) → str

OSOAA’s -HYD.ExtData file from one of Petzold’s stations.

F11 is 4 pi times the station’s vsf / b at Petzold’s 55 angles, from 180 degrees down, as the OSOAA User Manual V2.0 orders its example (section 3.6.3, pp. 80-81): a phase function whose integral over the sphere is 4 pi, as OSOAA takes it. OSOAA fits it with a spline in the cosine of the angle and computes its truncation coefficient from it without normalising it first, so the scale matters (DECISIONS.md section 93). Below Petzold’s first angle, 0.1 degree, the spline is OSOAA’s; the report’s extension there, 3.4 to 14.5 percent of b, is not in the file, so F11’s integral over the sphere is 4 pi times one less that share.

Parameters:
  • scattering – A ScatteringFunction, from petzold_scattering().

  • minus_f12_over_f11 – The polarization ratios -F12/F11, F22/F11 and F33/F11 of the Mueller matrix, each a number for every angle or one value per angle in Petzold’s order (0.1 to 180 degrees), each in [-1, 1]: no element of the Mueller matrix exceeds F11 in magnitude. Petzold measured intensity only, so they have no default.

  • f22_over_f11 – The polarization ratios -F12/F11, F22/F11 and F33/F11 of the Mueller matrix, each a number for every angle or one value per angle in Petzold’s order (0.1 to 180 degrees), each in [-1, 1]: no element of the Mueller matrix exceeds F11 in magnitude. Petzold measured intensity only, so they have no default.

  • f33_over_f11 – The polarization ratios -F12/F11, F22/F11 and F33/F11 of the Mueller matrix, each a number for every angle or one value per angle in Petzold’s order (0.1 to 180 degrees), each in [-1, 1]: no element of the Mueller matrix exceeds F11 in magnitude. Petzold measured intensity only, so they have no default.

Notes

The file’s first two lines are cross-sections in square micrometres in OSOAA’s format. They carry the station’s c and b in 1/m, which -HYD.Model 3 does not read: two runs differing only in them gave identical results (DECISIONS.md section 86). The file is for that model, with osoaa_user_profile(), and its comment line says so. At the Bahamas and southern California stations the values below 0.169 degree are the report’s extension, and warn.

Releases 1.14.0 to 1.15.4 wrote F11 as vsf / b, 4 pi too small; OSOAA then treated 96.5 to 97.8 percent of the hydrosols’ scattering as unscattered and its Kd came out too low (DATA.md section 38).

jerlov.hydrolight_ac9_file(water, wavelengths, /, *, depths_m, pure_water) → str

HydroLight’s standard-format file of a and c, for its IOP DATA option.

Ten header records, a record of the number of wavelengths and the wavelengths, then one record per depth of the depth, a - a_w at each wavelength and c - c_w at each, ended by the last record repeated with a depth of -1: the format of the HydroLight 5.1 Technical Documentation (Mobley 2012), section 7.3, pp. 55-56. HydroLight adds its own pure water back. It was not available here, and files written by this function have not been run.

Parameters:
  • water – A Water with a and b.

  • wavelengths – The wavelengths, nm, inside the water’s range, strictly ascending.

  • depths_m – At least two, from 0, ascending: HydroLight fits linear splines in depth. Every depth carries the same values, a Jerlov type not varying with depth.

  • pure_water – (a_w, b_w) on wavelengths, 1/m: the pure water HydroLight will add back. c_w = a_w + b_w. No default.

Raises:

ValueError – When a - a_w or c - c_w is negative, and for any input that is not a number, finite, or in range.

jerlov.read_osoaa_flux(text, /) → OsoaaFlux

Read OSOAA’s Advanced_outputs/Flux.txt.

text is the file’s text. Five header lines, then for each level its number, altitude and the seven columns of the OSOAA User Manual V2.0, section 3.5.6, pp. 75-76. Lines that are not nine numbers, and fields OSOAA could not print, are refused.

class jerlov.OsoaaFlux(level: ndarray, altitude_m: ndarray, in_sea: ndarray, direct_down: ndarray, diffuse_down: ndarray, total_down: ndarray, direct_up: ndarray, diffuse_up: ndarray, total_up: ndarray, up_over_down: ndarray)

OSOAA’s profile of fluxes, Flux.txt, as it prints them.

The fluxes are normalized so that the extraterrestrial solar irradiance is pi: multiply by Esun / pi for W/m2 (OSOAA User Manual V2.0, section 3.5.6). “Direct” is not the unscattered beam: OSOAA truncates the forward peak of the hydrosols’ phase function and counts the light so removed as transmitted (section 4.2.3). The totals are unaffected.

level: ndarray

OSOAA’s level numbers, from the top of the atmosphere down.

altitude_m: ndarray

positive in the atmosphere, negative in the sea.

Type:

As printed

in_sea: ndarray

True for the levels in the sea, the sign of the printed altitude, -0.00000 included: OSOAA prints the surface once above (0.00000) and twice below.

direct_down: ndarray

The direct downward flux, normalized, after OSOAA’s truncation.

diffuse_down: ndarray

The diffuse downward flux, normalized.

total_down: ndarray

Ed, normalized.

direct_up: ndarray

The direct upward flux, normalized.

diffuse_up: ndarray

The diffuse upward flux, normalized.

total_up: ndarray

Eu, normalized.

up_over_down: ndarray

Eu / Ed as OSOAA prints it.

property sea_depths_m: ndarray

The depths of the sea’s levels, positive, from the surface.

kd(upper_m: float, lower_m: float) → float

The mean Kd of Ed between two depths, 1/m.

ln(Ed(upper) / Ed(lower)) / (lower - upper), with ln Ed interpolated linearly between OSOAA’s levels and the first level below the surface standing for depth 0. Depths outside the levels are refused.

jerlov.read_osoaa_radiance_vs_depth(text, /) → OsoaaRadianceProfile

Read OSOAA’s Standard_outputs/RESLUM_vsZ.txt.

text is the file’s text: the header’s relative azimuth and viewing zenith angle, then for each depth the six columns of the OSOAA User Manual V2.0, section 3.5.1. The two rows at depth 0 are OSOAA’s two levels just below the surface.

class jerlov.OsoaaRadianceProfile(direction: str, relative_azimuth_deg: float, viewing_zenith_deg: float, depth_m: ndarray, scattering_angle_deg: ndarray, radiance: ndarray, reflectance: ndarray, polarization_percent: ndarray, polarized_radiance: ndarray, polarized_reflectance: ndarray)

OSOAA’s radiance against depth, RESLUM_vsZ.txt, as it prints it.

The radiances are normalized, I = pi L / Esun in 1/sr (multiply by Esun / pi for W/m2/sr), and the reflectances are pi L / Ed (OSOAA User Manual V2.0, section 3.5.1). Angles are in degrees.

direction: str

"upward" or "downward", as the header says.

relative_azimuth_deg: float

sensor and sun in the same half-plane).

Type:

The relative azimuth of the header (180

viewing_zenith_deg: float

The viewing zenith angle of the header.

depth_m: ndarray

Positive, from the surface; OSOAA prints them negative.

scattering_angle_deg: ndarray

The scattering angle of each row.

radiance: ndarray

I = pi L / Esun, 1/sr.

reflectance: ndarray

pi L / Ed.

polarization_percent: ndarray

The degree of polarization, percent.

polarized_radiance: ndarray

pi L_pol / Esun, 1/sr.

polarized_reflectance: ndarray

pi L_pol / Ed.

jerlov.read_osoaa_radiance_vs_vza(text, /) → OsoaaRadianceScan

Read OSOAA’s Standard_outputs/RESLUM_vsVZA.txt.

text is the file’s text: the header’s two relative azimuths and the output level, then for each viewing zenith angle the six columns of the OSOAA User Manual V2.0, section 3.5.1.

class jerlov.OsoaaRadianceScan(level: str, altitude_m: float, azimuth_negative_deg: float, azimuth_positive_deg: float, viewing_zenith_deg: ndarray, scattering_angle_deg: ndarray, radiance: ndarray, reflectance: ndarray, polarization_percent: ndarray, polarized_radiance: ndarray, polarized_reflectance: ndarray)

OSOAA’s radiance against the viewing zenith angle, RESLUM_vsVZA.txt, as it prints it.

The radiances are normalized, I = pi L / Esun in 1/sr (multiply by Esun / pi for W/m2/sr), and the reflectances are pi L / Ed (OSOAA User Manual V2.0, section 3.5.1). Angles are in degrees.

level: str

The header’s line naming the output level, as printed.

altitude_m: float

negative in the sea.

Type:

That level’s altitude, m

azimuth_negative_deg: float

The relative azimuth for negative viewing zenith angles.

azimuth_positive_deg: float

The relative azimuth for positive viewing zenith angles.

viewing_zenith_deg: ndarray

Signed by the half-plane, as OSOAA prints them; the angle 0 appears twice, as -0 and 0, one row for each half-plane.

scattering_angle_deg: ndarray

The scattering angle of each row.

radiance: ndarray

I = pi L / Esun, 1/sr.

reflectance: ndarray

pi L / Ed.

polarization_percent: ndarray

The degree of polarization, percent.

polarized_radiance: ndarray

pi L_pol / Esun, 1/sr.

polarized_reflectance: ndarray

pi L_pol / Ed.

Kd without a water type, Rrs and the Secchi depth

jerlov.morel2001_kd(wavelengths, /, *, chlorophyll_mg_m3: float)

Kd of case 1 water from its chlorophyll concentration.

Morel, A. and Maritorena, S. (2001), “Bio-optical properties of oceanic waters: A reappraisal”, J. Geophys. Res. 106(C4), 7163-7180, doi:10.1029/2000JC000319. Eqs. (3) and (5):

Kd = Kw + chi [Chl]^e

with Kw, chi and e from their Table 2, 350-700 nm every 5 nm. Kd is computed on that grid and interpolated linearly between.

Parameters:
  • wavelengths – nm, a number or an array, within 350-700 nm.

  • chlorophyll_mg_m3 – [Chl], mg m^-3: chlorophyll a plus divinyl chlorophyll a, as by HPLC (p. 7164). One number; no default.

Returns:

  • Kd, 1/m (a float for a number, an array otherwise. It is the Kd of the)

  • upper layer, from the surface to about one penetration depth (pp.

  • 7165-7166).

Notes

The relation is a statistical mean for case 1 water, whose optical properties follow its phytoplankton; individual waters scatter about it (p. 7164), and coastal water with sediment or dissolved matter of other origin is not case 1. The data spanned 0.02 to more than 30 mg m^-3 (p. 7164); outside 0.02-30 the result comes with a ProvenanceWarning.

Below 400 nm Table 2 repeats the chi and e that Morel & Antoine (1994) extrapolated, which the authors call a lower limit for oligotrophic water and found unsuited to their Mediterranean data (p. 7170); those wavelengths warn too. Beyond 590-600 nm the values are Morel’s (1988), not revised (p. 7168). DATA.md section 27, DECISIONS.md section 66.

jerlov.morel1988_kd(wavelengths, /, *, pigment_mg_m3: float)

Kd of case 1 water from its pigment concentration, Morel’s (1988) edition.

Morel, A. (1988), “Optical modeling of the upper ocean in relation to its biogenous matter content (case I waters)”, J. Geophys. Res. 93(C9), 10749-10768, doi:10.1029/JC093iC09p10749. Eqs. (8) and (9):

K = Kw + chi C^e,    Kw = aw + bw / 2

with Kw, chi and e from Table 2, 400-700 nm every 5 nm; K is computed on that grid and interpolated linearly between. morel2001_kd() is the revision of Morel & Maritorena (2001), which keeps this edition’s chi and e from 560 nm on and changes Kw everywhere (DATA.md section 45).

Parameters:
  • wavelengths – nm, a number or an array, within 400-700 nm.

  • pigment_mg_m3 – C, mg m^-3: chlorophyll a plus pheophytin a, averaged over the layer, not the HPLC chlorophyll a of morel2001_kd(). One number; no default.

Returns:

Kd, 1/m

Return type:

a float for a number, an array otherwise.

Notes

Fitted to 176 spectra of case 1 water; the paper uses the model from 0.03 to 30 mg m^-3 and outside that range the result comes with a ProvenanceWarning. Beyond 650 nm “the chi and e values … are only extracted from the mesotrophic and eutrophic waters” (p. 10,755), and those wavelengths warn too. DECISIONS.md section 101.

jerlov.bricaud1995_aph(wavelengths, /, *, chlorophyll_mg_m3: float)

Absorption by phytoplankton, aph, from the chlorophyll concentration.

Bricaud, A., Babin, M., Morel, A. and Claustre, H. (1995), “Variability in the chlorophyll-specific absorption coefficients of natural phytoplankton: Analysis and parameterization”, J. Geophys. Res. 100(C7), 13321-13332, doi:10.1029/95JC00463. Table 2:

a*ph = A [Chl]^-B,    aph = [Chl] a*ph = A [Chl]^(1 - B)

with A and B every 2 nm from 400 to 700 nm and at 675 nm. aph is computed at those wavelengths and interpolated linearly between them; outside 400-700 nm it raises ValueError.

Parameters:
  • wavelengths – nm, a number or an array, within 400-700 nm.

  • chlorophyll_mg_m3 – [Chl], mg m^-3: chlorophyll a plus divinyl chlorophyll a. One number; no default.

Returns:

aph, 1/m

Return type:

a float for a number, an array otherwise.

Notes

A statistical mean of 815 spectra from many oceans, spanning [Chl] 0.02-25 mg m^-3; outside that range the result comes with a ProvenanceWarning. Individual waters scatter widely about it, and the fit is poor where phytoplankton absorb little: r2 on the log-transformed data is below 0.01 from 556 to 578 nm and at 696 and 698 nm (Table 2). Only phytoplankton: nonalgal particles, dissolved matter and water are not included. Bricaud et al. (1998) refit the relation to 1166 spectra but print the spectral coefficients only as a figure. DATA.md section 31, DECISIONS.md section 72.

jerlov.morel2001_bbp(wavelengths, /, *, chlorophyll_mg_m3: float)

Backscattering by particles, bbp, from the chlorophyll concentration.

Morel, A. and Maritorena, S. (2001), J. Geophys. Res. 106(C4), 7163-7180, doi:10.1029/2000JC000319, eqs. (13), (14) and (9):

bbp = {0.002 + 0.01 [0.50 - 0.25 log10 Chl] (l/550)^v} bp550
v = (1/2)(log10 Chl - 0.3)    for Chl < 2 mg m^-3
v = 0                         above 2
bp550 = 0.30 Chl^0.62
Parameters:
  • wavelengths – nm, a number or an array, within 350-700 nm, the model’s domain.

  • chlorophyll_mg_m3 – [Chl], mg m^-3. One number; no default.

Returns:

  • bbp, 1/m (a float for a number, an array otherwise. Add pure water’s)

  • backscattering for the total bb (their eq. 11).

Notes

This is the form the paper’s model uses. Its eq. (10) is the 1988 form (a maximum efficiency of 0.02 and a (550/l) dependence at every [Chl]), which the paper then modifies “in two ways” into (13) and (14) (p. 7171). Eq. (9) is the paper’s; its (9’), which subtracts pure water’s scattering at 550 nm, is called negligible there and is not applied. (14) is written for 0.02-2 mg m^-3 and is used as written below 0.02, with a ProvenanceWarning, as is anything above 30; above 100 mg m^-3, where the bracket turns negative, it raises ValueError. DATA.md section 31, DECISIONS.md section 72.

jerlov.lee2005_kd(a, bb, /, *, sun_zenith_deg)

Kd from the absorption and backscattering coefficients and the sun.

Lee, Z.-P., Du, K.-P. and Arnone, R. (2005), “A model for the diffuse attenuation coefficient of downwelling irradiance”, J. Geophys. Res. 110, C02016, doi:10.1029/2004JC002275. Eq. (11):

Kd = (1 + 0.005 theta) a + 4.18 (1 - 0.52 exp(-10.8 a)) bb
Parameters:
  • a – Absorption and backscattering coefficients, 1/m, positive; numbers or arrays that broadcast together and with the sun. NaN marks a gap and gives NaN.

  • bb – Absorption and backscattering coefficients, 1/m, positive; numbers or arrays that broadcast together and with the sun. NaN marks a gap and gives NaN.

  • sun_zenith_deg – theta, the sun’s zenith angle above the surface, degrees, in [0, 90). No default.

Returns:

  • Kd(E10%), 1/m (the mean from the surface to the depth where the)

  • downwelling irradiance is 10 percent of its value at the surface. A

  • float if every input is a number, an array otherwise.

Notes

Fitted to HydroLight runs with the sun 10 to 60 degrees from the zenith and stated good for Kd of about 0.05 to 5.7 1/m (pp. 6-7 of 10); outside either the result comes with a ProvenanceWarning. Lee et al. (2013) found it overestimates Kd in clear water and the UV, and revised it: lee2013_kd(). DECISIONS.md section 66.

jerlov.lee2013_kd(a, bb, /, *, bb_water, sun_zenith_deg)

Kd from a, bb, the backscattering of pure water, and the sun.

Lee, Z., Hu, C., Shang, S., Du, K., Lewis, M., Arnone, R. and Brewin, R. (2013), “Penetration of UV-visible solar radiation in the global oceans: Insights from ocean color remote sensing”, J. Geophys. Res. Oceans 118, 4241-4255, doi:10.1002/jgrc.20308. Eqs. (3) and (5) with Table 1:

Kd = (1 + 0.005 theta) a
     + (1 - 0.265 bb_water / bb) 4.259 (1 - 0.52 exp(-10.8 a)) bb
Parameters:
  • a – Absorption and total backscattering coefficients, 1/m, positive; numbers or arrays that broadcast together and with the rest. NaN marks a gap and gives NaN.

  • bb – Absorption and total backscattering coefficients, 1/m, positive; numbers or arrays that broadcast together and with the rest. NaN marks a gap and gives NaN.

  • bb_water – The backscattering coefficient of pure sea water, 1/m, part of bb: not negative and not above it. No default; pure_water_backscattering() gives one for a stated salinity.

  • sun_zenith_deg – theta, the sun’s zenith angle above the surface, degrees, in [0, 90). No default.

Returns:

  • Kd, 1/m, of the same layer as :func:`lee2005_kd` (from the surface to)

  • 10 percent of the surface irradiance. A float if every input is a

  • number, an array otherwise.

Notes

The term in bb_water lets molecular scattering, whose phase function differs from that of particles, count for less (p. 4242). Fitted to HydroLight runs with the sun at 5, 30 and 60 degrees, 360-560 nm, and stated good for Kd of about 0.02 to 5.0 1/m (p. 4243); outside the angles or the range the result comes with a ProvenanceWarning. DECISIONS.md section 66.

jerlov.lee2005_kvis(a490, bb490, depth_m, /, *, sun_zenith_deg)

The attenuation of visible solar energy, from the surface to a depth.

Lee, Z., Du, K., Arnone, R., Liew, S. and Penta, B. (2005), “Penetration of solar radiation in the upper ocean: A numerical model for oceanic and coastal waters”, J. Geophys. Res. 110, C09019, doi:10.1029/2004JC002780 (not the C02016 of lee2005_kd()). Eqs. (7) and (9), Table 2:

K_VIS(z) = K1 + K2 / (1 + z)^0.5
K1 = [chi0 + chi1 a(490)^0.5 + chi2 bb(490)] (1 + alpha0 sin theta)
K2 = [zeta0 + zeta1 a(490) + zeta2 bb(490)] (alpha1 + alpha2 cos theta)

with the constants jerlov.ocean_colour.LEE2005_KVIS_CHI, LEE2005_KVIS_ZETA and LEE2005_KVIS_ALPHA. E_VIS(z) = E_VIS(0) exp(-K_VIS(z) z).

Parameters:
  • a490 – The total absorption and backscattering coefficients at 490 nm, 1/m, positive; numbers or arrays that broadcast together and with the rest. NaN marks a gap and gives NaN.

  • bb490 – The total absorption and backscattering coefficients at 490 nm, 1/m, positive; numbers or arrays that broadcast together and with the rest. NaN marks a gap and gives NaN.

  • depth_m – z, metres below the surface, not negative.

  • sun_zenith_deg – theta, the sun’s zenith angle above the surface, degrees, in [0, 90). No default.

Returns:

  • K_VIS(z), 1/m (the mean attenuation from just below the surface to z)

  • of the downwelling irradiance Ed, in energy, summed over 350-700 nm

  • (Lee et al. 2007 call it the “downwelling vector irradiance”). A

  • float if every input is a number, an array otherwise.

Raises:

ValueError – For input that is not a number, infinite or out of range, and where K1 would not be positive or K2 would be negative.

Notes

Fitted to 300 HydroLight runs (pp. 4-5): Pope & Fry’s pure water, Petzold’s average-particle phase function, Gregg & Carder’s clear sky, wind 5 m/s, the sun at 10, 30 and 60 degrees, K_VIS 0.04 to 1.6 1/m; the average error of T_VIS was 9 percent above 0.003 (p. 7). Outside the sun, the K_VIS or a T_VIS of 0.001 the result comes with a ProvenanceWarning. This is energy over 350-700 nm; PAR is quanta over 400-700 nm. Lee et al. (2007, p. 4) found “the difference between zx% measured by either EVIS or PAR is small (less than 10%)”. DECISIONS.md section 98.

jerlov.lee2007_depth_of_fraction(a490, bb490, /, *, sun_zenith_deg, fraction)

The depth where visible solar energy falls to a fraction of its surface value; at 0.01, the euphotic depth.

Lee, Z., Weidemann, A., Kindle, J., Arnone, R., Carder, K. L. and Davis, C. (2007), “Euphotic zone depth: Its derivation and implication to ocean-color remote sensing”, J. Geophys. Res. 112, C03009, doi:10.1029/2006JC003802. Eqs. (5)-(9): with tau = -ln(fraction), z solves K_VIS(z) z = tau, K_VIS of lee2005_kvis(); squared, the cubic z^3 + y1 z^2 + y2 z + y3 = 0 with:

y1 = (K1^2 - K2^2 - 2 tau K1) / K1^2
y2 = (tau^2 - 2 tau K1) / K1^2
y3 = tau^2 / K1^2

of whose roots the smaller positive one is the depth (p. 3). Here each root is also put back into the unsquared equation, and only one that satisfies it is returned.

Parameters:
  • a490 – As for lee2005_kvis().

  • bb490 – As for lee2005_kvis().

  • sun_zenith_deg – As for lee2005_kvis(). No default.

  • fraction – E_VIS(z) / E_VIS(0), in (0, 1): 0.01 for the euphotic depth, 0.1 and 0.5 as the paper also uses. No default.

Return type:

z, metres. A float if every input is a number, an array otherwise.

Notes

The paper takes this depth for that of PAR, 400-700 nm in quanta: “the difference between zx% measured by either EVIS or PAR is small (less than 10%)” (p. 4). The warnings of lee2005_kvis() apply at the depth found. DECISIONS.md section 98.

jerlov.mobley_rho(*, source, wind_speed, sun_zenith_deg, view_nadir_deg, view_azimuth_deg)

The sea surface’s reflectance factor rho for an above-water radiometer, from Mobley’s tables.

rho = Lr / Ls: the sky radiance the sea surface reflects into the radiometer, over the sky radiance measured in the mirror direction (Mobley 1999, Eq. 4). It is “not an IOP of the sea surface”: it depends on the sun, the viewing direction, the wind, the sky and the wavelength. Rrs = (Lt - rho Ls) / Ed (rrs_from_above_water()).

Parameters:
  • source – No default. "mobley1999": Mobley, C. D. (1999), “Estimation of the remote-sensing reflectance from above-surface measurements”, Appl. Opt. 38, 7442-7455, doi:10.1364/AO.38.007442; Cox-Munk surfaces, unpolarised ray tracing, the clear sky of Harrison & Coombes; wind 0-14 m/s, sun 0-80 degrees. "mobley2015": Mobley, C. D. (2015), “Polarized reflectance and transmittance properties of windblown sea surfaces”, Appl. Opt. 54, 4828-4849, doi:10.1364/AO.54.004828; surfaces from wave spectra, polarised ray tracing, a single-scattering Rayleigh sky, a fully developed sea with the sun’s rays along the wind; wind 0-15 m/s, sun 0-87.5 degrees. Both are for 550 nm, as the Ocean Optics Web Book distributes them; neither paper prints its table.

  • wind_speed – m/s, within the table’s range; linear between its points.

  • sun_zenith_deg – Degrees, within the table’s range; linear between its points.

  • view_nadir_deg – The radiometer’s angle from the nadir, one of 0, 10, …, 80 and 87.5: each value is the mean over a 10-degree band of nadir angle (a polar cap at 0), the field of view of a typical radiometer, so no value between two is given.

  • view_azimuth_deg – The radiometer’s azimuth from the sun’s, one of 0, 15, …, 180 (a 15-degree band each); not used at nadir 0. Mobley (1999) recommends 40 degrees from the nadir and 135 from the sun.

  • a (All four take numbers or arrays that broadcast together. Returns)

  • number (float if every input is a)

  • otherwise. (an array)

Raises:

ValueError – For an unknown or missing source, a wind or sun outside the table, or a viewing direction that is not one of its own.

Notes

The 2015 table’s own header calls it “a preliminary table for use during review”; the Web Book offers it as the paper’s revised table. It gives a ProvenanceWarning. The two tables differ by up to a factor of two at the same conditions; Mobley (2015) found the 1999 method “not adequate for accurate estimation of water-leaving radiance”. The value for a real sky, with clouds or aerosol, is neither (Mobley 1999, section 5). DECISIONS.md section 99, DATA.md section 43.

jerlov.rrs_from_above_water(lt, lsky, ed, /, *, rho)

The remote sensing reflectance from above-water radiances.

Mobley, C. D. (1999), Appl. Opt. 38, 7442-7455, Eqs. (1), (2) and (4):

Rrs = (Lt - rho Lsky) / Ed

Lt is the radiance seen looking at the sea, Lsky the sky radiance in the mirror direction, Ed the downwelling irradiance above the surface. With a grey plaque of reflectance Rg read as Lg, Ed = pi Lg / Rg (Eq. 6). Mobley’s Eq. (7), taking off Rrs(750 nm), is not applied.

Parameters:
  • lt – In consistent units (or raw counts of one instrument, which divide out); numbers or arrays that broadcast. Ed must be positive. NaN marks a gap and gives NaN.

  • lsky – In consistent units (or raw counts of one instrument, which divide out); numbers or arrays that broadcast. Ed must be positive. NaN marks a gap and gives NaN.

  • ed – In consistent units (or raw counts of one instrument, which divide out); numbers or arrays that broadcast. Ed must be positive. NaN marks a gap and gives NaN.

  • rho – The reflectance factor, no default: mobley_rho(), or a value you choose. Not negative.

Returns:

  • Rrs, 1/sr. A float if every input is a number, an array otherwise.

  • A negative value is kept (it says rho Lsky was more than Lt, so rho)

  • was too large or Lsky not from the mirror direction.

jerlov.morel2002_nadir_fq(wavelength_nm, /, *, chlorophyll_mg_m3, sun_zenith_deg)

f, Q and their ratio for an upward radiance from the nadir.

Morel, A., Antoine, D. and Gentili, B. (2002), “Bidirectional reflectance of oceanic waters: accounting for Raman emission and varying particle scattering phase function”, Appl. Opt. 41(30), 6289-6306, doi:10.1364/AO.41.006289, Appendix B, Tables 1-3, Raman emission included, case 1 water:

f(theta_s)   = f0 + Sf (1 - cos theta_s)            (B1)
Qn(theta_s)  = Q0 + SQ (1 - cos theta_s)            (B2)
f/Qn         = f0/Q0 + Sf/Q (1 - cos theta_s)       (B4)

Only the nadir view is tabulated in the paper; the full tables, for other views, are read from your own copy of the authors’ archive by morel2002_fq_tables() (DATA.md sections 47 and 48).

Parameters:
  • wavelength_nm – One of 412.5, 442.5, 490, 510, 560, 620 and 660, the paper’s own. No value between them is given: each was fitted on its own.

  • chlorophyll_mg_m3 – One of 0.03, 0.1, 0.3, 1, 3 and 10, the paper’s own. No default.

  • sun_zenith_deg – The sun’s zenith angle above the surface, 0 to 75 degrees. No default. Eqs. (B1) and (B2) hold to 60 degrees (“may reach 2%” off at 60 for B1), and beyond it f and q are NaN; Eq. (B4) holds to 75 with errors that “might reach +-3.4%”. From 60 degrees on a ProvenanceWarning is given.

Return type:

NadirFQ.

Raises:

ValueError – For an argument that is not one finite number, a wavelength or chlorophyll that is not one of the table’s, or a sun outside 0 to 75 degrees.

Notes

The accuracies above are the paper’s, against the values the fits were fitted to. Against the f of the authors’ distributed archive (f.dat), Eq. (B1) departs by up to 0.47 percent with the sun at 15 degrees, 1.10 at 30, 2.70 at 45 and 1.29 at 60 (DATA.md section 48). The largest is at the archive’s one suspect run (the sun at 45 degrees, 0.03 mg/m3), whose values the paper’s own Fig. 13 plots (since 1.26.5): the fits do not follow what was computed there. DECISIONS.md sections 103, 105 and 118, DATA.md section 47.

class jerlov.NadirFQ(wavelength_nm: float, chlorophyll_mg_m3: float, sun_zenith_deg: float, f: float, q: float, f_over_q: float, correction: float)

Morel et al.’s (2002) f and Q for the radiance from the nadir.

f relates the irradiance reflectance below the surface to the IOPs, Eu/Ed = f bb/a (their Eq. 11); q is Qn = Eu/Lu for the upward radiance from the nadir (Eq. 10); both from Eqs. (B1) and (B2), NaN with the sun beyond 60 degrees. f_over_q is Eq. (B4), fitted to 75 degrees. correction is (f0/Q0) / (f/Qn), the factor of Eq. (B3) that takes a normalised water-leaving radiance measured with the sun at sun_zenith_deg to the sun at the zenith, from Eq. (B4).

wavelength_nm: float
chlorophyll_mg_m3: float
sun_zenith_deg: float
f: float
q: float
f_over_q: float
correction: float
jerlov.morel2002_fq_tables(path, /)

Read Morel, Antoine & Gentili’s (2002) full f and f/Q tables from the user’s own copy of the authors’ archive.

Morel, A., Antoine, D. and Gentili, B. (2002), Appl. Opt. 41(30), 6289-6306, doi:10.1364/AO.41.006289, Appendix A: f and f/Q for seven wavelengths, six sun angles and six Chl, f/Q for 17 nadir angles in water by 13 azimuths, Raman emission included, case 1 water; and the surface factor R-gothic. The archive states no licence, so this package does not ship it: get DISTRIB_fQ_with_Raman.tar.gz from ftp://oceane.obs-vlfr.fr/pub/gentili/AppliedOptics2002/ and pass its path. It is read as it is, without extracting.

Parameters:

path – The archive. Its MD5 must be MOREL2002_FQ_MD5, the copy this package was checked against; another is refused.

Return type:

Morel2002FQTables.

Notes

The nadir view alone, as the paper prints it, is morel2002_nadir_fq(), which needs no file. DECISIONS.md section 104, DATA.md section 48.

class jerlov.Morel2002FQTables(foq: dict, f: dict, nadir: tuple, azimuth: tuple, surface: dict)

The tables of Morel et al.’s (2002) archive, read by morel2002_fq_tables().

Attributes wavelengths_nm, sun_zenith_deg, chlorophyll_mg_m3, nadir_deg (17, in water) and azimuth_deg (13) give the grid. Azimuth 0 is the sensor and the sun on opposite sides of the vertical, 180 on the same side (the archive’s README_FIRST).

f(wavelength_nm, /, *, sun_zenith_deg, chlorophyll_mg_m3)

f of R = Eu/Ed = f bb/a (their Eq. 11), from f.dat.

At a sun of 45 degrees and 0.03 mg/m3 the value is suspect and comes with a ProvenanceWarning (DATA.md section 48).

f_over_q(wavelength_nm, /, *, sun_zenith_deg, chlorophyll_mg_m3, nadir_deg, azimuth_deg)

f/Q for the upward radiance in water at nadir_deg (one of the 17, or 0, which takes the 1.078 degree row as the paper says) and azimuth_deg (0 to 180 every 15). At a sun of 45 degrees and 0.03 mg/m3 the value is suspect and comes with a ProvenanceWarning (DATA.md section 48).

surface_factor(*, wind, nadir_deg)

The R-gothic of rgoth_Ebuchi.dat for wind (“flat”, or 0, 4, 6, 8 or 16 m/s) and the nadir angle in water, 0 to 90 every 1.

jerlov.rottgers2013_scatter_correction(am, cm, am_ref, cm_ref, /, *, method, ec=None, a_ref=None)

Absorption corrected for the scattering error of a reflective-tube absorption meter, by one of the methods Röttgers et al. (2013) compared.

With am and cm the absorption and attenuation the instrument reads (after its temperature, salinity and pure-water corrections), and _ref their values at the reference wavelength (715 nm on an ac-9):

  • "flat", Eq. (1): a = am - am_ref

  • "proportional", Eq. (2b): a = am - am_ref [(1/ec) cm - am] / [(1/ec) cm_ref - am_ref]; with ec = 1 it is Eq. (2a), the method of Zaneveld et al. (1994)

  • "flat+", Eq. (3): a = am - (am_ref - a_ref)

  • "proportional+", Eq. (4): a = am - (am_ref - a_ref) [(1/ec) cm - am] / [(1/ec) cm_ref - a_ref]. The paper writes ac, “either am or a”; am is used here, since a is what is sought.

The first two assume that nothing absorbs at the reference wavelength; Röttgers et al. found that “generally not valid”, and the “+” methods take the true absorption there, a_ref, measured or estimated (rottgers2013_a715()). Eq. (4) with a_ref = 0 is not Eq. (2b): the denominators differ by am_ref.

Parameters:
  • am – The measured absorption and attenuation, 1/m, at the wavelengths to correct; numbers or arrays that broadcast. NaN marks a gap, and a gap in either is a gap in the result, by the flat methods too, which do not use cm: a wavelength the measurement has a gap at gives nothing there (DECISIONS.md section 105).

  • cm – The measured absorption and attenuation, 1/m, at the wavelengths to correct; numbers or arrays that broadcast. NaN marks a gap, and a gap in either is a gap in the result, by the flat methods too, which do not use cm: a wavelength the measurement has a gap at gives nothing there (DECISIONS.md section 105).

  • am_ref – The same at the reference wavelength, 1/m; cm_ref is not used by the flat methods but must still be a number.

  • cm_ref – The same at the reference wavelength, 1/m; cm_ref is not used by the flat methods but must still be a number.

  • method – One of ROTTGERS2013_METHODS. No default.

  • ec – The proportional methods only: the factor the attenuation is divided by, 1 for none; Röttgers et al. used 0.56, after Boss et al. (2009), for the ac-9’s acceptance angle. No default.

  • a_ref – The “+” methods only: the true absorption at the reference wavelength, 1/m. No default.

Returns:

  • The corrected absorption, 1/m (a float if am and cm are numbers, an)

  • array otherwise.

Raises:

ValueError – For an unknown method, ec or a_ref given where the method does not use it or missing where it does, input that is not finite, and a denominator that is not positive.

jerlov.rottgers2013_a715(am715, /)

The true absorption at 715 nm estimated from an ac-9’s uncorrected reading there, Röttgers et al. (2013), Eq. (5):

a715 = 0.212 am715^1.135

fitted to 85 natural samples from coastal European waters (r2 = 0.930), algal cultures left out, against a PSICAM. For the a_ref of rottgers2013_scatter_correction().

Parameters:

am715 – 1/m, positive; a number or an array. NaN marks a gap.

Returns:

  • The estimated absorption at 715 nm, 1/m (a float for a number, an)

  • array otherwise.

Notes

Outside about 0.02 to 8 1/m, the span of their Fig. 4, a ProvenanceWarning is given. They found it “most useful when am715 >~ 0.1 1/m”, and their further work required “to establish the general applicability of Eq. (5)”. It is for 715 nm on an ac-9.

jerlov.gordon1989_d0(sun_zenith_deg, /, *, direct_fraction)

D0, the downwelling distribution function just beneath the surface.

Gordon, H. R. (1989), “Can the Lambert-Beer law be applied to the diffuse attenuation coefficient of ocean water?”, Limnol. Oceanogr. 34(8), 1389-1409, doi:10.4319/lo.1989.34.8.1389, eq. (12):

D0 = f / cos(theta_w) + 1.197 (1 - f)

for a sky of uniform radiance. D0 is the reciprocal of the mean cosine of the downwelling light: 1 for the sun overhead, more as it slants.

Parameters:
  • sun_zenith_deg – The sun’s zenith angle in air, degrees, 0 up to but not including 90; a number or an array. It is refracted into the water by Snell’s law with n = 1.333, which reproduces six of the seven rows of the paper’s Table 3 secant column, the most any index does (its text says “about 1.33”; DECISIONS.md section 74).

  • direct_fraction – f, the share of the irradiance transmitted through the surface that is direct sunlight, 0-1. No default: it depends on the sky, and the paper estimates it by shading the sun from an irradiance meter (p. 1401). A number, or an array of the sun’s shape.

Returns:

D0

Return type:

a float for numbers, an array otherwise.

Notes

Against D0 computed exactly with a model atmosphere (Table 3), eq. (12) is within about 3 percent for the sun up to 60 degrees and 5-8 percent too low at 80 (p. 1402); above 60 degrees the result comes with a ProvenanceWarning. A flat surface; the paper’s correction for waves is given only as a figure. See gordon1989_kd() for its use.

jerlov.gordon1989_kd(kd, /, *, d0_from, d0_to)

Kd under one light field rescaled to another: kd * d0_to / d0_from.

Gordon (1989) found Kd/D0 nearly independent of the light field for a given water: computed for many sun angles and wavelengths, K/(c D0) fell on single curves with an average error of 1.8 percent, and the mean over the upper half of the euphotic zone with 2.2 (p. 1399). So a Kd measured when D0 was d0_from becomes, under d0_to, about kd * d0_to / d0_from.

Parameters:
  • kd – Kd, 1/m, not negative; a number or an array. The paper’s K is Kd just beneath the surface, and <K> its mean over the upper half of the euphotic zone (p. 1398); the rescaling is for those, not for Kd at depth, where the light field has changed.

  • d0_from – D0 when kd was measured, and D0 wanted, both positive; numbers or arrays broadcasting with kd. Both are required. Jerlov’s Kd tables do not record the sun angle or the sky they were measured under, so this package cannot supply d0_from for them; a caller who rescales them states an assumption. gordon1989_d0() gives D0 from the sun and the sky.

  • d0_to – D0 when kd was measured, and D0 wanted, both positive; numbers or arrays broadcasting with kd. Both are required. Jerlov’s Kd tables do not record the sun angle or the sky they were measured under, so this package cannot supply d0_from for them; a caller who rescales them states an assumption. gordon1989_d0() gives D0 from the sun and the sky.

Returns:

  • Kd, 1/m (a float for numbers, an array otherwise. DECISIONS.md section)

  • 74.

jerlov.subsurface_rrs(a, bb, /, *, coefficients)

The remote sensing reflectance just below the surface, from a and bb.

rrs = g0 u + g1 u^2, u = bb / (a + bb): Gordon, H. R. et al. (1988), “A semianalytic radiance model of ocean color”, J. Geophys. Res. 93(D9), 10909-10924, doi:10.1029/JD093iD09p10909, eq. (2), there written as R/Q; and Lee, Z., Carder, K. L. and Arnone, R. A. (2002), Appl. Opt. 41, 5755-5772, doi:10.1364/AO.41.005755, eq. (1).

Parameters:
  • a – Absorption and backscattering coefficients, 1/m, positive; numbers or arrays that broadcast together. NaN marks a gap and gives NaN.

  • bb – Absorption and backscattering coefficients, 1/m, positive; numbers or arrays that broadcast together. NaN marks a gap and gives NaN.

  • coefficients – (g0, g1). No default: GORDON1988_RRS_COEFFICIENTS, (0.0949, 0.0794), Gordon et al.’s for case 1 water; or LEE2002_RRS_COEFFICIENTS, (0.0895, 0.1247), Lee et al.’s mean of those and a pair for more turbid coastal water.

Returns:

  • rrs, sr^-1 (upwelling radiance over downwelling irradiance just below)

  • the surface. A float if both inputs are numbers, an array otherwise.

Notes

Gordon et al. give the error as significantly less than 10 percent for realistic phase functions, with the sun 20 degrees or more from the zenith; nearer the zenith it depends on the phase function (p. 10910). The values of g0 and g1 vary with the phase function (Lee et al. 2002, p. 5756). The relation is for optically deep water: no bottom, and no Raman scattering or fluorescence. DECISIONS.md section 66. To remove Raman scattering from a measured Rrs before comparing, see lee2013_raman_correction().

jerlov.GORDON1988_RRS_COEFFICIENTS = (0.0949, 0.0794)

g0 and g1 of rrs = g0 u + g1 u^2, as Gordon et al. (1988) eq. (2) gives them (l1 and l2, p. 10910).

jerlov.LEE2002_RRS_COEFFICIENTS = (0.0895, 0.1247)

g0 and g1 of Lee, Carder & Arnone (2002, p. 5756): the mean of Gordon et al.’s pair and a pair for coastal water from another paper.

jerlov.above_surface_rrs(rrs, /)

The remote sensing reflectance above the surface, from that below.

Rrs = 0.52 rrs / (1 - 1.7 rrs), the inverse of Lee, Z., Carder, K. L. and Arnone, R. A. (2002), “Deriving inherent optical properties from water color: a multiband quasi-analytical algorithm for optically deep waters”, Appl. Opt. 41, 5755-5772, doi:10.1364/AO.41.005755, eq. (8): rrs = Rrs / (0.52 + 1.7 Rrs).

Parameters:

rrs – The reflectance just below the surface, sr^-1, as from subsurface_rrs(); not negative, and below 1/1.7.

Returns:

  • Rrs, sr^-1 (water-leaving radiance over downwelling irradiance above)

  • the surface. A float for a number, an array otherwise.

Notes

0.52 stands for the transmission of the surface both ways over the square of the refractive index, and 1.7 for the reflection of upwelling light back down; Lee et al. found these from HydroLight for optically deep water and a sensor looking straight down (p. 5757). DECISIONS.md section 66.

jerlov.lee2011_rrs(a, bb, /, *, bb_water, coefficients)

The remote sensing reflectance above the surface, water and particles apart, Lee et al. (2011).

Lee, Z. P., Du, K., Voss, K. J., Zibordi, G., Lubac, B., Arnone, R. and Weidemann, A. (2011), “An inherent-optical-property-centered approach to correct the angular effects in water-leaving radiance”, Appl. Opt. 50(19), 3155-3167, doi:10.1364/AO.50.003155, eq. (14):

Rrs = (G0w + G1w bbw/k) bbw/k + (G0p + G1p bbp/k) bbp/k,
k = a + bb,  bbp = bb - bbw
Parameters:
  • a – Absorption and backscattering coefficients, 1/m, positive; numbers or arrays of one shape. NaN marks a gap and gives NaN.

  • bb – Absorption and backscattering coefficients, 1/m, positive; numbers or arrays of one shape. NaN marks a gap and gives NaN.

  • bb_water – Pure water’s part of bb, 1/m: not negative and not above bb.

  • coefficients – (G0w, G1w, G0p, G1p), sr^-1, four positive numbers; no default. LEE2011_RRS_COEFFICIENTS holds the seven sets Table 2 prints, by (sun zenith, viewing zenith, relative azimuth); its (0, 0, 0) is straight down with the sun overhead.

Returns:

  • Rrs above the surface, sr^-1 (the coefficients include the crossing of)

  • the surface, so above_surface_rrs() is not applied to it.

Notes

The coefficients were fitted to HydroLight runs on the IOP sets of IOCCG Report 5, with bb/(a + bb) from 0.0002 to 0.37 (p. 3159); outside that range the result comes with a ProvenanceWarning. The particle phase function was a blend of Petzold’s average and a Fournier-Forand of backscattering ratio 1 percent. The paper derived coefficients for many more geometries but prints only these seven; it describes no interpolation between them, and none is done here. Optically deep water; no Raman scattering. DECISIONS.md section 73.

jerlov.LEE2011_RRS_COEFFICIENTS

(G0w, G1w, G0p, G1p) of Lee et al. (2011), Table 2 (p. 3159), sr^-1, by (sun zenith, viewing zenith, relative azimuth) in degrees: the seven geometries the paper prints, of the many it derived. Read-only.

jerlov.lee1999_shallow_rrs(a, bb, /, *, depth_m, bottom_albedo, sun_zenith_deg)

The remote sensing reflectance of shallow water, with the bottom in view, straight down.

Lee, Z., Carder, K. L., Mobley, C. D., Steward, R. G. and Patch, J. S. (1999), “Hyperspectral remote sensing for shallow waters: 2. Deriving bottom depths and water properties by optimization”, Appl. Opt. 38(18), 3831-3843, doi:10.1364/AO.38.003831, Eqs. (A6), (A7) and (A9), which update the model of their 1998 paper (Appl. Opt. 37(27), 6329-6338, doi:10.1364/AO.37.006329):

rrs = rrs_dp (1 - exp(-(1/cos theta_w + 1.03 (1 + 2.4 u)^0.5) kappa H))
      + (rho/pi) exp(-(1/cos theta_w + 1.04 (1 + 5.4 u)^0.5) kappa H)
rrs_dp = (0.084 + 0.170 u) u,  u = bb / (a + bb),  kappa = a + bb
Rrs = 0.5 rrs / (1 - 1.5 rrs)
Parameters:
  • a – Absorption and backscattering coefficients of the water column, 1/m, positive. NaN marks a gap and gives NaN.

  • bb – Absorption and backscattering coefficients of the water column, 1/m, positive. NaN marks a gap and gives NaN.

  • depth_m – H, the depth of the bottom, m: positive and finite. With no bottom in view, use the result’s deep.

  • bottom_albedo – rho, the bottom’s irradiance reflectance, 0 to 1, taken as Lambertian. No default: the package ships no albedos of sea beds.

  • sun_zenith_deg – The sun’s zenith angle in air, degrees, in [0, 90). It is refracted into the water with n = 1.34, the refractive index of the paper’s runs (1998, p. 6331), to give theta_w.

  • together (All five broadcast)

  • spectrum (so a)

  • depths (a map of)

  • both (or)

  • given. (may be)

Returns:

  • :class:`ShallowRrs` (rrs and its two terms column and)

  • bottom, deep for the same water without a bottom, and

  • above_surface.

Notes

The 1998 paper fitted the model to HydroLight 3.0 runs: a homogeneous water with Petzold’s average particle phase function, a bottom of albedo 0, 0.1, 0.3 or 1 flat in wavelength, H from 0.5 to 32 m and infinite, the sun at 0, 30 and 60 degrees under clear and cloudy skies, wind 5 m/s, 400-700 nm, bb/a up to 1.5 (Table 1, p. 6331). The 1999 paper refitted it with more runs, correcting a calculation error it does not describe; only those constants are used (DECISIONS.md section 113, DATA.md section 50). The sun beyond 60 degrees, H outside 0.5-32 m, or u above 0.6 gives a ProvenanceWarning.

The downwelling light is treated as the sun’s beam (D_d = 1/cos theta_w), the view is straight down (the 1999 paper’s change for other views is left out), and Raman scattering and fluorescence are not in the model.

Against a Monte Carlo with a flat surface and another of Petzold’s phase functions (DATA.md section 50) the model agrees well over a bright bottom. It runs low where pure water carries most of the backscattering, and high over a dark bottom a few metres down in turbid water.

class jerlov.ShallowRrs(rrs: ndarray, column: ndarray, bottom: ndarray, deep: ndarray, above_surface: ndarray)

The remote sensing reflectance of shallow water, straight down, from lee1999_shallow_rrs().

Each field is a float when every input was a number, otherwise an array of the inputs’ broadcast shape. All are sr^-1.

rrs: ndarray

rrs just below the surface, column + bottom (Eq. A6).

column: ndarray

The water column’s part rrs_C, rrs_dp (1 - exp(-(1/cos theta_w + D_u^C) kappa H)).

bottom: ndarray

The bottom’s part rrs_B, (rho / pi) exp(-(1/cos theta_w + D_u^B) kappa H).

deep: ndarray

rrs_dp, the same water with no bottom in view (Eq. A7).

above_surface: ndarray

Rrs just above the surface, 0.5 rrs / (1 - 1.5 rrs) (Eq. A9).

jerlov.lee2015_secchi_depth(wavelengths, kd, rrs, /)

The Secchi depth from Kd and the remote sensing reflectance.

Lee, Z., Shang, S., Hu, C., Du, K., Weidemann, A., Hou, W., Lin, J. and Lin, G. (2015), “Secchi disk depth: A new theory and mechanistic model for underwater visibility”, Remote Sens. Environ. 169, 139-149, doi:10.1016/j.rse.2015.08.002. Eq. (33):

Z_SD = ln(|0.14 - Rrs_tr| / 0.013) / (2.5 Kd_tr)

where Kd_tr is the smallest Kd of the spectrum, at the wavelength where the water is most transparent, and Rrs_tr the reflectance there.

Parameters:
  • wavelengths – nm, one spectrum within the visible, 400-700 nm; Lee et al. used 443-665 nm.

  • kd – Kd at those wavelengths, 1/m, positive. Lee et al. used Kd from a and bb for a sun 30 degrees from the zenith (p. 146), as lee2013_kd() gives.

  • rrs – The remote sensing reflectance above the surface at those wavelengths, sr^-1, not negative, as above_surface_rrs() gives.

  • gaps (Neither kd nor rrs may have)

  • one (could lie in)

  • here. (so NaN is refused)

Returns:

  • Z_SD, m, the depth at which a white disc disappears from the view of

  • someone above the surface.

Notes

0.14 is a white disc of reflectance 0.85 seen through the surface (p. 146; the paper’s own 0.85 / pi times 0.54 is 0.146, and eq. (33) uses 0.14), 0.013 sr^-1 the contrast the eye needs to see it (p. 147), and 2.5 counts the attenuation of the light on its way down and up (p. 145). The model was checked against 338 measured depths from 0.1 to 30 m, to about 18 percent (pp. 146-147); outside that range the result comes with a ProvenanceWarning. DECISIONS.md section 66.

From Rrs to a and bb

jerlov.qaa_ioccg2006(wavelengths, rrs, /, *, bands, pure_water)

a and bbp from Rrs by the QAA of IOCCG Report 5 (2006).

IOCCG (2006), Remote Sensing of Inherent Optical Properties: Fundamentals, Tests of Algorithms, and Applications, Lee, Z.-P. (ed.), Reports of the International Ocean-Colour Coordinating Group No. 5, chapter 10 (Lee, Carder and Arnone), pp. 73-77: the version that report tested on its synthetic and in situ data.

Two references. At 555 nm, with rho = log10[max(Rrs440, Rrs490, Rrs510) / Rrs555], Kd(555) = 0.0605 + 10^(-1.163 - 1.969 rho + 1.239 rho^2 + 0.417 rho^3 - 0.984 rho^4) and a(555) = 0.9 Kd(555) (1 - 6.8 Rrs555) / (1 + 15.3 Rrs555) (eqs. 10.2, 10.3). At 640 nm, Rrs(640) = 0.01 Rrs555 + 1.4 Rrs670 - 0.0005 Rrs670 / Rrs490 and a(640) = 0.31 + 0.07 (rrs640 / rrs440)^1.1 (eqs. 10.4, 10.5). rrs = Rrs / (0.52 + 1.7 Rrs); u = (-0.0895 + sqrt(0.008 + 0.499 rrs)) / 0.249; Y = 2.2 [1 - 1.2 exp(-0.9 rrs440 / rrs555)]; bb(l) = bbw(l) + bbp(ref) (ref / l)^Y; a = (1 - u) bb / u (eqs. 10.6 to 10.10). The two solutions are blended by a(440) from 555 nm: that one below 0.3, the 640 nm one above 0.5, and linearly between (eq. 10.11); bbp follows from u and the blended a. The split of a takes zeta = 0.71 + 0.06 / (0.8 + rrs440 / rrs555), S = 0.015 and xi = exp[S (440 - 410)] (eqs. 10.12 to 10.14), with 440 and 410 the bands’ own wavelengths.

Parameters:
  • wavelengths – nm, the bands of the Rrs, ascending.

  • rrs – The remote sensing reflectance above the surface, sr^-1, one value per band along the last axis; other axes are spectra. NaN gives NaN.

  • bands – A dict naming which of wavelengths plays each role: "410", "440", "490", "510", "555" and "670". No default. The report used 410, 440, 490, 510 and 670 nm of its synthetic data, and for 555 the mean of 550 and 560 (p. 76).

  • pure_water – (wavelengths, aw, bbw), 1/m, interpolated linearly; it must cover the bands and 640 nm. No default: the report used Pope & Fry (1997) for aw and Morel (1974) for bbw (pp. 73-75); pure_water_absorption_table(..., source="pope1997") is the first, and pure_water_backscattering() gives a bbw.

Returns:

  • A :class:`QAAResult`. Nothing is filtered (the report counts 476 of its)

  • 500 synthetic decompositions as valid without saying by what rule, so

  • negative and NaN values are returned as computed.

Notes

The report’s results on its synthetic data, Table 10.1 (p. 76), are reproduced to within 0.002 in RMSE and bias (DATA.md section 28). DECISIONS.md section 67.

jerlov.qaa_v6(wavelengths, rrs, /, *, bands, pure_water)

a and bbp from Rrs by QAA_v6.

Lee, Z. P., “Steps and calculations of the Quasi-Analytical Algorithm (QAA_v6)”, IOCCG (qaa_v6_202011.pdf), computed as the spreadsheet the IOCCG distributes with it computes it, QAA_v6-202011.xlsm, where the two differ (DATA.md section 28).

Steps: rrs = Rrs / (0.52 + 1.7 Rrs); u = bb / (a + bb) from rrs = g0 u + g1 u^2, g0 = 0.08945, g1 = 0.1247. If Rrs(670) < 0.0015 sr^-1 the reference is 55x nm:

chi = log10[(rrs443 + rrs490) / (rrs55x + 5 rrs670^2 / rrs490)]
a(55x) = aw(55x) + 10^(h0 + h1 chi + h2 chi^2)

else it is 670 nm, a(670) = aw(670) + 0.39 [rrs670 / (rrs443 + rrs490)]^1.14. Then bbp(ref) = u a / (1 - u) - bbw at the reference, eta = 2.0 [1 - 1.2 exp(-0.9 rrs443 / rrs55x)], bbp(l) = bbp(ref) (ref / l)^eta and a(l) = (1 - u)(bbw + bbp) / u. The split of a takes zeta = 0.74 + 0.2 / (0.8 + rrs443 / rrs55x) for aph(412) / aph(443), S = 0.015 + 0.002 / (0.6 + rrs443 / rrs55x) and xi = exp[S (443 - 412)], with 443 and 412 the bands’ own wavelengths.

Parameters:
  • wavelengths – nm, the bands of the Rrs, ascending.

  • rrs – The remote sensing reflectance above the surface, sr^-1, one value per band along the last axis; other axes are spectra. NaN gives NaN.

  • bands – A dict naming which of wavelengths plays each role: "412", "443", "490", "55x" and "670". No default: it is the sensor’s. The document gives 547 nm (MODIS), 555 (SeaWiFS, VIIRS) or 560 (MERIS, OLCI) for 55x in its table of steps, and 550 for MODIS in its text.

  • pure_water – (wavelengths, aw, bbw): pure water’s absorption and backscattering, 1/m, interpolated linearly; it must cover the bands. No default: the spreadsheet uses its own values; pure_water_absorption_table() gives published spectra of aw to choose from and pure_water_backscattering() a bbw.

Returns:

  • A :class:`QAAResult`. Nothing is filtered (a spectrum the algorithm)

  • cannot invert gives a negative or NaN value, returned as computed.

Notes

The document’s table of steps prints g0 = 0.089 and g1 = 0.1245, its text 0.0895 and 0.1247, and the spreadsheet 0.08945 and 0.1247; for xi the table has 442.5 - 415.5 nm, the text 443 - 411 and the spreadsheet 443 - 412. This follows the spreadsheet, whose stored results it reproduces. The limits and the estimate of Rrs(670) in the text (eqs. 7 to 9) are for satellite data and are not applied. DECISIONS.md section 67.

class jerlov.QAAResult(wavelengths: ndarray, a: ndarray, bbp: ndarray, adg: ndarray, aph: ndarray, eta: ndarray, reference_nm: ndarray, version: str)

What the quasi-analytical algorithm derives from one or more spectra of Rrs.

a, bbp, adg and aph are in 1/m, at wavelengths along the last axis, with the other axes those of the Rrs given.

wavelengths: ndarray

nm, the wavelengths of the Rrs given.

a: ndarray

Total absorption coefficient.

bbp: ndarray

Backscattering coefficient of particles, bb minus pure water’s.

adg: ndarray

Absorption by dissolved and detrital matter.

aph: ndarray

a - adg - aw.

Type:

Absorption by phytoplankton

eta: ndarray

The exponent of the power law of bbp with wavelength (Y in Report 5, eta in QAA_v6), one per spectrum.

reference_nm: ndarray

The reference wavelength each spectrum used, nm. For qaa_ioccg2006(), NaN where its 555 and 640 nm solutions were blended (eq. 10.11).

version: str

"ioccg2006" or "v6".

jerlov.lee2013_raman_correction(wavelengths, rrs, /, *, bands)

Remove Raman scattering from a measured Rrs, Lee et al. (2013).

RF(l) = alpha(l) Rrs_T(440) / Rrs_T(550)
        + beta1(l) Rrs_T(550) ** beta2(l)       (11)
Rrs(l) = Rrs_T(l) / (1 + RF(l))                  (13)

Rrs_T is the remote sensing reflectance as measured above the surface, sr^-1, Raman scattering included; the corrected Rrs is what the forward relations of this package and both QAA versions describe. rrs holds Rrs_T at wavelengths, along its last axis. bands names the wavelengths that play “440” and “550”, each one of wavelengths; there is no default (for MODIS, 443 and 547 or 551 nm).

alpha, beta1 and beta2 are Table 2’s, at the MODIS bands 412, 443, 488, 531, 551 and 667 nm, fitted to Hydrolight runs of the case 1 model of Morel & Maritorena (2001) with chlorophyll from 0.02 to 3 mg m^-3; the paper puts the fit within about 15 percent of Hydrolight’s RF. RF is computed at those six bands and interpolated linearly in wavelength between them, as the paper does for hyperspectral data (p. 4246). Outside 412-667 nm it raises ValueError. For its own hyperspectral data the paper also extrapolated RF to 350 nm, without saying how, and set it to 0 below 400 nm, an assumption; this function does neither (DECISIONS.md section 71).

NaN in Rrs_T passes through. Rrs_T must not be negative or infinite, and at the “550” band must be positive.

class jerlov.RamanCorrection(wavelengths: ndarray, raman_factor: ndarray, rrs: ndarray)

Rrs with the light Raman-scattered by the water removed.

Arrays have the shape of the Rrs given, wavelengths along the last axis.

wavelengths: ndarray

nm, the wavelengths of the Rrs given.

raman_factor: ndarray

RF, the Raman part of the measured Rrs over the rest (eq. 12).

rrs: ndarray

The corrected Rrs, Rrs_T / (1 + RF), sr^-1 (eq. 13).

Solar heating

jerlov.shortwave_parameters(water_type: str, *, include_non_types: bool = False) → ShortwaveParameters

Paulson & Simpson parameters for a Jerlov water type.

Only the five oceanic types I, IA, IB, II and III were fitted; the paper covers no coastal type, and this raises rather than substituting one.

water_type="I_upper50" selects the paper’s alternative fit for type I over the upper 50 m, which it gives because ln I against depth changes slope below that. The plain "I" row is the 100 m fit.

Table 2 also prints three rows that are not water types: the authors’ composite observations, their Run 1, and a Kraus (1972) value from Crater Lake (keys "composite_observations", "run_1" and "kraus_1972_very_clear"). They are refused unless include_non_types=True is passed, so that one cannot be mistaken for a Jerlov type; their water_type is empty. See DATA.md section 14.

class jerlov.ShortwaveParameters(key: str, water_type: str, R: float, zeta1_m: float, zeta2_m: float, fit_depth_m: float | None, note: str)

One row of Paulson & Simpson (1977) Table 2.

key: str
water_type: str
R: float

Share of the surface irradiance in the fast-decaying term.

zeta1_m: float

Attenuation length of the fast term, metres. Red light.

zeta2_m: float

Attenuation length of the slow term, metres. Blue-green light.

fit_depth_m: float | None

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.

Type:

Depth the row was fitted down to

note: str
fraction_at(depth_m)

I(z)/I(0) at one or more depths.

Below fit_depth_m the two exponentials are extrapolated beyond the data they were fitted to, and a ProvenanceWarning says so. Jerlov’s own Table XXI goes deeper for the clearer types; see jerlov1968_solar_fraction().

jerlov.solar_fraction(water_type: str, depth_m)

Fraction of surface solar irradiance surviving to depth_m.

Broadband, 300-2500 nm.

>>> round(solar_fraction("IB", 10.0), 3)
0.183

Jerlov’s own Table XXI gives 16.9 percent for IB at 10 m. The difference is expected: Paulson & Simpson fitted the table “neglecting the 10 m value”, and say that “the fit is least accurate in the upper 10 m” and “could be improved by including the value at 10 m”. They give no reason for leaving it out.

jerlov.jerlov1968_solar_fraction(water_type: str) → tuple[ndarray, ndarray]

Jerlov (1968) Table XXI: (depths_m, fraction) of surface irradiance.

Broadband, 300-2500 nm, as measured and tabulated by Jerlov, for all ten types including the coastal ones. These are the values Paulson & Simpson fitted, for the oceanic types, to obtain shortwave_parameters(), so they are what to compare the fit against.

fraction is 0 to 1, not percent. Depths the table leaves blank are kept, as NaN, so that a gap stays visible.

The table’s footnote gives the conditions: a solar altitude of 90 degrees for the oceanic types and 45 degrees for the coastal ones. The Paulson & Simpson parameters, fitted to the oceanic columns, carry the first of these with them.

jerlov.lee2005_kir(depth_m, /, *, sun_zenith_deg)

The attenuation of infrared solar energy, from the surface to a depth.

Lee, Z., Du, K., Arnone, R., Liew, S. and Penta, B. (2005), “Penetration of solar radiation in the upper ocean: A numerical model for oceanic and coastal waters”, J. Geophys. Res. 110, C09019, doi:10.1029/2004JC002780, Eq. (4):

K_IR(z) = [0.560 + 2.304 / (0.001 + z)^0.65] (1 + 0.002 theta)

theta in degrees (jerlov.shortwave.LEE2005_KIR_COEFFICIENTS). E_IR(z) = E_IR(0) exp(-K_IR(z) z), E_IR the energy of 700-2500 nm, whose attenuation “is almost completely dominated by water absorption” (p. 1): nothing of what is in the water enters.

Parameters:
  • depth_m – z, metres below the surface, not negative; a number or an array.

  • sun_zenith_deg – theta, degrees, in [0, 90). No default.

Return type:

K_IR(z), 1/m. A float if both inputs are numbers, an array otherwise.

Notes

Fitted for z of 0.01 to 3 m and the sun 0 to 60 degrees from the zenith (p. 3), with an average error of 3.0 percent; “for z deeper than 3 m, E_IR is negligible”. Outside these a ProvenanceWarning is given. DECISIONS.md section 98.

jerlov.lee2005_shortwave_transmittance(a490, bb490, depth_m, /, *, sun_zenith_deg, visible_fraction)

The share of the shortwave solar energy at the surface that is left at a depth.

Lee et al. (2005, C09019; see lee2005_kir()), Eq. (11):

T(z) = F_VIS exp(-K_VIS(z) z) + (1 - F_VIS) exp(-K_IR(z) z)

with K_VIS of lee2005_kvis() and K_IR of lee2005_kir().

Parameters:
  • a490 – As for lee2005_kvis().

  • bb490 – As for lee2005_kvis().

  • depth_m – z, metres, not negative.

  • sun_zenith_deg – degrees, in [0, 90). No default.

  • visible_fraction – F_VIS = E_VIS(0) / E_SR(0), the share of 350-700 nm in the 350-2500 nm energy just below the surface, one number in (0, 1). The paper gives “around 0.424 [Mobley, 1994]” (p. 7); it depends on the sun and the sky, so it has no default here.

Return type:

T(z), 0 to 1. A float if every input is a number, an array otherwise.

Notes

The warnings of lee2005_kvis() apply. Those of lee2005_kir() apply above 0.01 m only (at z = 0, T is 1 by construction): below 3 m the paper calls E_IR negligible. DECISIONS.md section 98.

Sources

jerlov.SOURCES: dict[str, Source]

Every published set of coefficients the package ships, by the key that source= takes. get_source() looks one up and names the others when the key is unknown. Writing to it is not part of what 1.0 promises.

class jerlov.Source(key: str, citation: str, doi: str | None, quantities: tuple[str, ...], water_types: tuple[str, ...], wavelength_range_nm: tuple[float, float], measured: bool, scattering: ~jerlov.sources.ScatteringConstants | None = None, caveats: tuple[str, ...] = <factory>)

A published set of inherent optical properties.

key: str
citation: str
doi: str | None
quantities: tuple[str, ...]
water_types: tuple[str, ...]
wavelength_range_nm: tuple[float, float]
measured: bool

True if a and b rest on measurements rather than on inversion of Kd.

scattering: ScatteringConstants | None = None
caveats: tuple[str, ...]
jerlov.get_source(key: str) → Source

Return the Source registered under key.

class jerlov.ScatteringConstants(bw_coeff: float, bw_exponent: float, small_coeff: float, small_exponent: float, large_coeff: float, large_exponent: float, small_backscatter_prob: float | None = None, large_backscatter_prob: float | None = None)

Constants of the two-component scattering model:

b(lam) = bw_coeff * (400/lam)**bw_exponent
       + Cs * small_coeff * (400/lam)**small_exponent
       + Cl * large_coeff * (400/lam)**large_exponent

Cs and Cl are the small- and large-particle concentrations (g/m3). Note that Haltrin writes these as Cs, Cl and reserves Bs, Bl for the backscattering probabilities; Solonenko & Mobley and Williamson & Hollins rename the concentrations to Bs, Bl. This package follows Haltrin.

bw_coeff: float
bw_exponent: float
small_coeff: float
small_exponent: float
large_coeff: float
large_exponent: float
small_backscatter_prob: float | None = None
large_backscatter_prob: float | None = None
jerlov.HALTRIN1999 = ScatteringConstants(bw_coeff=0.005826, bw_exponent=4.322, small_coeff=1.151302, small_exponent=1.7, large_coeff=0.341074, large_exponent=0.3, small_backscatter_prob=0.039, large_backscatter_prob=0.00064)

Haltrin (1999) Eqs. (5)-(7) as printed in the original paper.

Warnings and errors

exception jerlov.ProvenanceWarning

Raised when a returned value rests on something the caller should know.

Interpolating across a wavelength that a published table got wrong, or that was itself extrapolated, gives a number that looks no different from a sound one. This warning is the only thing that distinguishes them.

exception jerlov.MissingQuantityError

Raised when a quantity is not determined by the available data.