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

water(), then a(), b(), c(), kd()

the source= you name (default Williamson & Hollins 2022)

A type’s bb

bb(), with a ratio you give: no source determines it

the source’s b; with bbp/bp, Haltrin’s (1999) term for pure water

What a source is and what is doubtful in it

get_source(), jerlov.SOURCES, caveats()

The measured points behind a type’s spectrum

measured_points()

Williamson & Hollins (2022)

Your own a, b or Kd, treated like a type

from_measurements()

you

The type that applies deeper down

water_type_at_depth(), profile_depth()

Williamson & Hollins (2023)

The type a measured Kd spectrum is nearest

classify_kd()

the edition you name

Kd, from what you have

You have

Use

From

A Jerlov type

kd(); jerlov1976 and the other Kd-only sources carry Jerlov’s own

Jerlov (1968, 1976), Austin & Petzold (1986)

One Kd at one wavelength

kd_spectrum()

Austin & Petzold (1986)

Chlorophyll, in case 1 water

morel2001_kd()

Morel & Maritorena (2001)

Chlorophyll a plus pheophytin a, in case 1 water

morel1988_kd(), the earlier edition of the same model

Morel (1988)

a, bb and the sun

lee2005_kd()

Lee et al. (2005, C02016)

a, bb, pure water’s part of bb, and the sun

lee2013_kd(), which revises lee2005_kd() and lets molecular scattering count for less

Lee et al. (2013)

A Kd measured under one sun and sky, wanted under another

gordon1989_kd(), with both D0 from gordon1989_d0() or your own

Gordon (1989)

A Secchi depth

k_from_secchi(), by a rule you name, such as jerlov.POOLE1929_SECCHI_COEFFICIENT

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

descend()

Williamson & Hollins (2023), and the Kd source you name

PAR at depth, and the depth of a fraction of it

par_profile(), from a surface spectrum and any Kd

The visible energy’s attenuation, and the euphotic depth, from a(490) and bb(490)

lee2005_kvis(), lee2007_depth_of_fraction()

Lee et al. (2005, C09019), Lee et al. (2007)

A target seen through water, horizontally or looking up or down

Scene, at_depth(), observe(), observe_slant()

Duntley (1963) for the slant

The veiling radiance, if you have nothing better

veiling_radiance_estimate()

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

forward_scatter() for a measured water, attenuation_within() for a type, with a station you name

Petzold (1972)

The irradiance at the surface under a clear sky

gregg1990_irradiance()

Gregg & Carder (1990)

Reflectance and ocean colour

You have, and want

Use

From

a and bb; rrs just below the surface

subsurface_rrs(), with jerlov.GORDON1988_RRS_COEFFICIENTS or jerlov.LEE2002_RRS_COEFFICIENTS

Gordon et al. (1988), Lee et al. (2002)

rrs below; Rrs above

above_surface_rrs()

Lee et al. (2002)

a, bb and pure water’s part of bb; Rrs above at one of seven viewing geometries

lee2011_rrs(), with jerlov.LEE2011_RRS_COEFFICIENTS; not followed by above_surface_rrs()

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

lee1999_shallow_rrs()

Lee et al. (1998, 1999)

f and Q for the radiance from the nadir

morel2002_nadir_fq()

Morel et al. (2002), Appendix B

f and Q for other views

morel2002_fq_tables(), from your own copy of the authors’ archive

Morel et al. (2002), Appendix A

Radiances measured above the water; Rrs

rrs_from_above_water(), with rho from mobley_rho() or your own

Mobley (1999, 2015)

A measured Rrs; the same without Raman scattering

lee2013_raman_correction()

Lee et al. (2013)

Rrs; a and bbp

qaa_v6(), or qaa_ioccg2006(), the version IOCCG Report 5 tested

Lee (QAA_v6), IOCCG (2006)

Kd and Rrs; the Secchi depth

lee2015_secchi_depth()

Lee et al. (2015)

Chlorophyll; aph or bbp

bricaud1995_aph(), morel2001_bbp()

Bricaud et al. (1995), Morel & Maritorena (2001)

From an instrument

You measured

Use

From

The volume scattering function at one angle; bb

bb_from_vsf(), particulate_chi()

Boss & Pegau (2001)

c with a transmissometer; b

b_from_c()

Smart (2007)

a and c with an ac-9 or ac-s; a corrected for scattering

rottgers2013_scatter_correction(), and rottgers2013_a715() for the absorption at the reference wavelength

Röttgers et al. (2013), Zaneveld et al. (1994)

Pure water

You want

Use

From

The aw a source built its a on

pure_water_absorption()

that source

A published aw, by your choice

pure_water_absorption_table()

the source= you name

Its scattering, backscattering or volume scattering function

pure_water_scattering(), pure_water_backscattering(), pure_water_vsf(), at a salinity you give

Colour and vision

You want

Use

From

CIE XYZ or sRGB of a spectrum, against a white you name

spectrum_to_xyz(), spectrum_to_srgb(), xyz_to_srgb()

CIE 1931

The colour matching functions, or D65

cie_1931_cmf(), d65()

CIE

A spectrum against any sensitivity: camera channels or receptors

integrate_response()

A visual pigment’s absorbance

visual_pigment_template()

Govardovskii et al. (2000)

The distance between two colours to an eye

receptor_noise_distance()

Vorobyev & Osorio (1998)

Real materials to look at

usgs2017_reflectance()

USGS Spectral Library 7

For other software

You want

Use

From

Coefficients per RGB channel, or the transmittance itself

rgb_attenuation(), rgb_transmittance()

A Henyey-Greenstein g

henyey_greenstein_fit()

Petzold (1972)

a, b and c for a spectral renderer

spectral_coefficients()

Input files for OSOAA or HydroLight

osoaa_user_profile(), osoaa_phase_function(), hydrolight_ac9_file()

OSOAA’s results read back

read_osoaa_flux(), read_osoaa_radiance_vs_depth(), read_osoaa_radiance_vs_vza()

Heating of the upper ocean

You want

Use

From

The shortwave left at a depth, by type, as ocean models write it

solar_fraction(), shortwave_parameters()

Paulson & Simpson (1977)

The table those were fitted to

jerlov1968_solar_fraction()

Jerlov (1968)

The shortwave left at a depth, from a(490), bb(490) and the sun

lee2005_shortwave_transmittance(), lee2005_kir() for the infrared

Lee et al. (2005, C09019)

Measurements to check against

Measured

Use

From

Volume scattering functions of eight waters

petzold_scattering()

Petzold (1972)

Quanta irradiance by type

jerlov1977_quanta()

Jerlov (1977)

The radiance from every direction in a lake

tyler1958_radiance()

Tyler (1958)

The clearest ocean water measured

morel2007_stations()

Morel et al. (2007)

The flicker of the light under waves, read off figures

darecki2011_irradiance_cv(), darecki2011_radiance_cv(), darecki2011_spectral_cv(), gernez2009_cv_by(), gernez2009_spectral_cv(), gernez2009_band_cv(), gernez2009_diffuse_share(); gernez2009_cv_by_sun_zenith() is the name before 0.24.0, kept until 2.0

Darecki et al. (2011), Gernez & Antoine (2009)