Light with depth¶
The type changes with depth¶
The classification is defined on the top 10 m, but clarity does not stay put. Water that is Jerlov I at the surface is typically IB below 40 m; turbid coastal water clears as you go down.
jerlov.water_type_at_depth("I", 60.0) # 'IB'
jerlov.water_type_at_depth("3C", 45.0) # 'II'
jerlov.water_type_at_depth("9C", 15.0) # None: the paper declined to say
jerlov.water_type_at_depth("I", [0, 30, 60]) # array(['I', 'IA', 'IB'], dtype=object)
None means fewer than ten measurement campaigns supported a declaration, so
nothing is asserted. This is a lookup, not a correction applied on your
behalf.
To carry the downwelling irradiance down through that profile, with each 10 m layer attenuating by the Kd of its own type:
d = jerlov.descend("1C", 45.0, wl) # source="jerlov1976" by default
d.layers # ((0, 10, '1C'), (10, 20, '1C'), (20, 30, 'III'), ..., (40, 45, 'II'))
d # <Descent 1C to 45 m: 1C 0-20, III 20-40, II 40-45 m; Kd from jerlov1976; ...>
scene = jerlov.Scene.at_depth(jerlov.water("II"), 45.0, surface, wl, kd=d)
It refuses to go through a layer the paper declared nothing for, rather than
carrying the last type on: 3C stops at 70 m, 9C at 10 m.
jerlov.profile_depth("3C") says how far a descent can go, and
d.transmittance_at(z) gives any depth above the descent’s bottom without
descending again.
Light for photosynthesis¶
PAR, the photon flux from 400 to 700 nm, attenuated wavelength by wavelength rather than with one coefficient, and the depth at which it falls to 1 percent of its surface value:
p = jerlov.par_profile(surface, wl, [0, 25, 50], kd=d, unit="energy")
p.par # umol photons m-2 s-1 at each depth
p.fraction # PAR(z) / PAR(0)
p.depth_of_fraction(0.01) # m
p.kd_par(0, 1) # effective Kd(PAR) over the top metre, 1/m
p.spectrum_at(25) # photons per nm at 25 m, on p.wavelengths_nm
kd is a Water carrying Kd, an array, or a Descent. unit has no
default, because PAR counts photons and an energy spectrum read as photons is
weighted wrongly with no sign of it. This is planar PAR, from Ed. PAR on
scalar irradiance, what a spherical sensor reads, is larger by a factor that
depends on the light field, which the package does not model; give it as the
mean cosine (Ed - Eu) / E0 and the reflectance Eu / Ed, neither of which has
a default:
p.scalar_par(mean_cosine=0.75, reflectance=0.02) # E0 = Ed (1 - R) / mu
reflectance=0 leaves out the upwelling light, as a choice you make
(DECISIONS.md section 59).
band=(lo, hi) integrates over another band instead, such as part of PAR
for the share of one colour; outside 400-700 nm the result is a photon flux
in that band, not PAR, and p.band_nm says which. photon_weight= weights
each photon by its wavelength, for a pigment’s absorption or a receptor’s
sensitivity, and the depths and Kd then follow the weighted flux.
A measured Kd with a standard uncertainty gives a range as well:
w = jerlov.Water.from_measurements(wl, kd=measured_kd,
uncertainty={"kd": sigma_kd})
p = jerlov.par_profile(surface, wl, [0, 25, 50], kd=w, unit="energy")
p.depth_of_fraction_bounds(0.01) # (shallower, deeper), m, Kd +- 1 sigma
p.par_bounds(k=2) # (lower, higher) PAR, Kd +- 2 sigma
kd_uncertainty= does the same beside an array kd. The errors are taken
as fully correlated between wavelengths, the widest range any errors within
k sigma can give (DECISIONS.md section 57). The published types carry no
uncertainty, so they and descend give no range.
Jerlov measured quanta irradiance, 350-700 nm, by water type, and his
tables are shipped for checking against, with
band=jerlov.QUANTA_BAND_NM to integrate over his band:
jerlov.jerlov1977_quanta("II") # <QuantaLevels II: 30% 10.5 m, 10% 24 m, 3% 39 m, 1% 52 m; ...>
From II to 3C the package agrees with them within 2 m at every level. For
Jerlov I it agrees only through descend; for IB it puts the 1 percent
level a third too deep, because Jerlov’s IB water grew more turbid below
15 m; the profiles of quanta and the spectra measured at the stations he
drew on show the same. DATA.md section 22; DECISIONS.md sections 53-56.
Tyler measured the radiance from every direction at seven depths in a deep lake, and his tables are shipped too, for checking a radiative transfer model against:
jerlov.tyler1958_radiance(41.3) # <RadianceDistribution Tyler 1958, 41.3 m, 19 tilts x 10 azimuths>
The package solves no radiative transfer itself; the Monte Carlo model in
examples/radiance_distribution.py is compared with these tables, and does
not match them. DATA.md section 23.
Under a wavy surface the light flickers. Two field studies that give it only in figures are shipped as values read off those figures, each with its conditions and the precision of the reading:
jerlov.darecki2011_irradiance_cv() # CV of Ed, 0.86-9.58 m, 443/532/670 nm
jerlov.darecki2011_radiance_cv("a") # CV of radiance, 13 angles in the sun's plane
jerlov.gernez2009_cv_by("sun_zenith_deg") # CV of Ed at 510 nm against the sun's zenith angle
jerlov.darecki2011_spectral_cv() # CV of Ed at 410-670 nm on five days of wind
jerlov.gernez2009_cv_by("kd490_per_m") # ... against wave height, wind or Kd(490)
jerlov.gernez2009_cv_by("wind_m_s", sky="overcast") # overcast; or irradiance="Eu"
jerlov.gernez2009_spectral_cv("Eu") # CV of Eu at 412-683 nm, clear and overcast
jerlov.gernez2009_band_cv("wind_m_s") # CV of Ed at six bands against the conditions
jerlov.gernez2009_diffuse_share() # the sky's share of the light, as printed
They carry status = read_from_figure. The package does not model the
fluctuations, which depend on the wind, the waves and the collector as much
as on the water. DATA.md sections 24 and 25; DECISIONS.md section 42.