Which function to use¶
Several functions often give the same quantity, each from a different starting point and a different paper. This page lists them by what you want, so that you can pick one by what you have. The details, ranges and warnings of each are in the API reference; the topic pages show the calls.
Every function here takes its inputs without defaults where the data do not decide them: a source, a ratio, a sun, a coefficient. The page says which papers a function follows, not how well; that is in each docstring and in DATA.md.
The water of a Jerlov type¶
You have, and want |
Use |
From |
|---|---|---|
A type’s a, b, c or Kd |
the |
|
A type’s bb |
|
the source’s b; with bbp/bp, Haltrin’s (1999) term for pure water |
What a source is and what is doubtful in it |
|
|
The measured points behind a type’s spectrum |
Williamson & Hollins (2022) |
|
Your own a, b or Kd, treated like a type |
you |
|
The type that applies deeper down |
Williamson & Hollins (2023) |
|
The type a measured Kd spectrum is nearest |
the edition you name |
Kd, from what you have¶
You have |
Use |
From |
|---|---|---|
A Jerlov type |
|
Jerlov (1968, 1976), Austin & Petzold (1986) |
One Kd at one wavelength |
Austin & Petzold (1986) |
|
Chlorophyll, in case 1 water |
Morel & Maritorena (2001) |
|
Chlorophyll a plus pheophytin a, in case 1 water |
|
Morel (1988) |
a, bb and the sun |
Lee et al. (2005, C02016) |
|
a, bb, pure water’s part of bb, and the sun |
|
Lee et al. (2013) |
A Kd measured under one sun and sky, wanted under another |
|
Gordon (1989) |
A Secchi depth |
|
Poole & Atkins (1929) |
The Kd of lee2005_kd() and lee2013_kd() is
the mean from the surface to where 10 percent of the light is left.
Light below the surface¶
You want |
Use |
From |
|---|---|---|
The downwelling irradiance through the typical depth profile |
Williamson & Hollins (2023), and the Kd source you name |
|
PAR at depth, and the depth of a fraction of it |
|
|
The visible energy’s attenuation, and the euphotic depth, from a(490) and bb(490) |
Lee et al. (2005, C09019), Lee et al. (2007) |
|
A target seen through water, horizontally or looking up or down |
Duntley (1963) for the slant |
|
The veiling radiance, if you have nothing better |
single scattering |
|
The attenuation of the light that stays within an angle of its direction: what a transmissometer of that acceptance reads, or light from a target blurred rather than lost |
|
Petzold (1972) |
The irradiance at the surface under a clear sky |
Gregg & Carder (1990) |
Reflectance and ocean colour¶
You have, and want |
Use |
From |
|---|---|---|
a and bb; rrs just below the surface |
|
Gordon et al. (1988), Lee et al. (2002) |
rrs below; Rrs above |
Lee et al. (2002) |
|
a, bb and pure water’s part of bb; Rrs above at one of seven viewing geometries |
|
Lee et al. (2011) |
a, bb, the depth of the bottom and its albedo; rrs and Rrs of shallow water, straight down, with the bottom’s part apart |
Lee et al. (1998, 1999) |
|
f and Q for the radiance from the nadir |
Morel et al. (2002), Appendix B |
|
f and Q for other views |
|
Morel et al. (2002), Appendix A |
Radiances measured above the water; Rrs |
|
Mobley (1999, 2015) |
A measured Rrs; the same without Raman scattering |
Lee et al. (2013) |
|
Rrs; a and bbp |
|
Lee (QAA_v6), IOCCG (2006) |
Kd and Rrs; the Secchi depth |
Lee et al. (2015) |
|
Chlorophyll; aph or bbp |
Bricaud et al. (1995), Morel & Maritorena (2001) |
From an instrument¶
You measured |
Use |
From |
|---|---|---|
The volume scattering function at one angle; bb |
Boss & Pegau (2001) |
|
c with a transmissometer; b |
Smart (2007) |
|
a and c with an ac-9 or ac-s; a corrected for scattering |
|
Röttgers et al. (2013), Zaneveld et al. (1994) |
Pure water¶
You want |
Use |
From |
|---|---|---|
The aw a source built its a on |
that source |
|
A published aw, by your choice |
the |
|
Its scattering, backscattering or volume scattering function |
|
Colour and vision¶
You want |
Use |
From |
|---|---|---|
CIE XYZ or sRGB of a spectrum, against a white you name |
CIE 1931 |
|
The colour matching functions, or D65 |
CIE |
|
A spectrum against any sensitivity: camera channels or receptors |
||
A visual pigment’s absorbance |
Govardovskii et al. (2000) |
|
The distance between two colours to an eye |
Vorobyev & Osorio (1998) |
|
Real materials to look at |
USGS Spectral Library 7 |
For other software¶
You want |
Use |
From |
|---|---|---|
Coefficients per RGB channel, or the transmittance itself |
||
A Henyey-Greenstein g |
Petzold (1972) |
|
a, b and c for a spectral renderer |
||
Input files for OSOAA or HydroLight |
|
|
OSOAA’s results read back |
|
Heating of the upper ocean¶
You want |
Use |
From |
|---|---|---|
The shortwave left at a depth, by type, as ocean models write it |
Paulson & Simpson (1977) |
|
The table those were fitted to |
Jerlov (1968) |
|
The shortwave left at a depth, from a(490), bb(490) and the sun |
|
Lee et al. (2005, C09019) |
Measurements to check against¶
Measured |
Use |
From |
|---|---|---|
Volume scattering functions of eight waters |
Petzold (1972) |
|
Quanta irradiance by type |
Jerlov (1977) |
|
The radiance from every direction in a lake |
Tyler (1958) |
|
The clearest ocean water measured |
Morel et al. (2007) |
|
The flicker of the light under waves, read off figures |
|
Darecki et al. (2011), Gernez & Antoine (2009) |