Package 'luxR'

Description

Tools for quantifying and modelling underwater light environments. Propagates spectral irradiance through the water column via Beer-Lambert attenuation, computes PAR, and converts between energy and photon-flux units. Provides the lux_spectrum S3 class for unit-safe spectral arithmetic and native format readers for TriOS RAMSES and Ocean Optics instruments. Optional lightr interoperability preserves native instrument records until their measurement, scale, calibration, and resampling policies are explicitly declared. Includes visual ecology utilities: Govardovskii (2000) visual-pigment templates, photoreceptor quantum catch, Vorobyev-Osorio colour discrimination (JND), Secchi depth, and heuristic horizontal visual-range and object-detection scenarios.

Author(s)

Maintainer: John D Kirwan [email protected]

Authors:

• John D Kirwan [email protected]

See Also

Useful links:

• https://johnkirwan.github.io/luxR/

• https://github.com/JohnKirwan/luxR

• Report bugs at https://github.com/JohnKirwan/luxR/issues

Description

The negative logarithm of transmittance. Natural-log absorbance (base = "e") is used by vision scientists and oceanographers; base-10 absorbance (base = "10") is "optical density" (OD), used by chemists and filter makers. They differ by a constant: $OD = A\log_{10}e \approx 0.4343\,A$ (Johnsen 2012, ch. 4).

Usage

absorbance(transmittance, base = c("e", "10"))

Arguments

Value

Absorbance / optical density (dimensionless, $\geq 0$).

References

Johnsen S (2012) The Optics of Life. Princeton University Press, ch. 4.

See Also

transmittance

Examples

absorbance(0.01, base = "10")   # OD = 2 (1% transmitted)
absorbance(exp(-1.5))           # natural-log absorbance = 1.5

Description

$AoP = \tfrac{1}{2}\,\mathrm{atan2}(U, Q)$

. Polarization orientation is axial (period 180 degrees); the value is returned in degrees in the half-open range (-90, 90].

Usage

angle_of_polarization(Q, U)

Arguments

Value

Angle of polarization in degrees, in (-90, 90]. The result is NA where both Q and U are zero because orientation is undefined. Scalar inputs are broadcast; incompatible lengths are rejected.

See Also

degree_of_polarization

Examples

angle_of_polarization(Q = 1, U = 0)   #  0
angle_of_polarization(Q = 0, U = 1)   # 45

Description

Reshapes luxR data into the plain data frame colourvision expects for an illuminant (I) or reflectance (R1, R2, Rb): the first column is wavelength and each remaining column is one spectrum. luxR handles the water (depth propagation, the in-water light field); colourvision handles the colour-space / visual model (RNLmodel(), CTTKmodel(), colour spaces). Build the receptor matrix C with species_sensitivity_matrix.

Usage

as_colourvision(x, ...)

## S3 method for class 'lux_spectrum'
as_colourvision(x, name = NULL, ...)

## S3 method for class 'list'
as_colourvision(x, ...)

Arguments

Details

Unlike as_rspec, this performs no interpolation: colourvision resamples inputs itself via its nm/interpolate arguments at model time, so the converter is a pure reshape with no hidden resampling. colourvision is an optional (Suggests) dependency.

Value

A data.frame with a wl column plus one column per spectrum, ready to pass as colourvision's I, R1, R2, or Rb.

See Also

species_sensitivity_matrix for the C matrix; as_rspec for the pavo equivalent; colourvision::RNLmodel

Examples

## Not run: 
  I  <- as_colourvision(from_solar("clear_noon"), name = "I")

## End(Not run)

Description

Converts a numeric vector or data frame to a lux_spectrum object. The data-frame method auto-detects the wavelength column (lambda > wavelength > wv) and the spectral-value column (E > irradiance > radiance > value). Passing an existing lux_spectrum returns it unchanged.

Usage

as_lux_spectrum(x, ...)

## S3 method for class 'numeric'
as_lux_spectrum(
  x,
  lambda,
  quantity = "irradiance",
  unit = "W/m2/nm",
  binwidth = NULL,
  meta = list(),
  ...
)

## S3 method for class 'data.frame'
as_lux_spectrum(
  x,
  lambda_col = NULL,
  E_col = NULL,
  quantity = "irradiance",
  unit = "W/m2/nm",
  binwidth = NULL,
  meta = list(),
  ...
)

## S3 method for class 'lux_spectrum'
as_lux_spectrum(x, ...)

## S3 method for class 'lux_instrument_spectrum'
as_lux_spectrum(
  x,
  quantity = NULL,
  unit = NULL,
  calibration = NULL,
  negative_policy = "error",
  ...
)

## S3 method for class 'rspec'
as_lux_spectrum(
  x,
  column = 2,
  quantity = "irradiance",
  unit = "W/m2/nm",
  meta = list(),
  ...
)

## S3 method for class 'source_spct'
as_lux_spectrum(
  x,
  measurement = NULL,
  negative_policy = "error",
  interpolate = FALSE,
  ...
)

## S3 method for class 'reflector_spct'
as_lux_spectrum(x, negative_policy = "error", interpolate = FALSE, ...)

Arguments

Value

A lux_spectrum object.

See Also

lux_spectrum, from_naples, from_solar

Examples

# from a numeric vector
lam <- seq(400, 700, by = 10)
as_lux_spectrum(rep(1, length(lam)), lambda = lam)

# from a data frame
df <- data.frame(lambda = lam, E = rep(1, length(lam)))
as_lux_spectrum(df)

Description

Bridges a reflectance lux_spectrum into photobiology as a reflector_spct. luxR already constrains reflectance to [0, 1], so values map onto Rfr directly.

Usage

as_reflector_spct(x, ...)

## S3 method for class 'lux_spectrum'
as_reflector_spct(x, Rfr.type = NULL, strict.range = TRUE, ...)

## S3 method for class 'list'
as_reflector_spct(x, ...)

Arguments

Details

Rfr.type is required. Whether a reflectance is total or specular is a fact about how it was measured, which luxR does not otherwise carry; defaulting it would silently mislabel the measurement inside another package's ecosystem. Record it once in the spectrum's meta$Rfr_type to have it picked up automatically.

Value

A photobiology reflector_spct.

See Also

as_source_spct, as_lux_spectrum

Examples

## Not run: 
  r <- as_reflector_spct(my_reflectance, Rfr.type = "total")

## End(Not run)

Description

Bridges luxR data into the pavo ecosystem so pavo's colour-space and visual-modelling tools (vismodel(), coldist(), colspace(), plotting) can be applied to luxR-derived spectra. The division of labour: luxR handles the water (depth propagation, inherent optical properties, the in-water light field); pavo handles the colour space.

Usage

as_rspec(x, ...)

## S3 method for class 'lux_spectrum'
as_rspec(x, name = NULL, ...)

## S3 method for class 'list'
as_rspec(x, ...)

Arguments

Details

Delegates to pavo::as.rspec(), which validates the input and, by default, interpolates onto a 1 nm grid, so the result is a genuine rspec object. pavo is an optional (Suggests) dependency.

Value

A pavo rspec data frame: a wl column plus one column per spectrum.

See Also

as_lux_spectrum for the reverse conversion; pavo::as.rspec, pavo::vismodel

Examples

## Not run: 
  # A bundled solar spectrum as an rspec, ready for the pavo toolkit:
  r <- as_rspec(from_solar("clear_noon"))

  # Several spectra at once (e.g. TriOS radiance scans):
  r2 <- as_rspec(from_trios(system.file("extdata/trios.dat", package = "luxR")))

## End(Not run)

Description

Bridges luxR data into the photobiology ecosystem so its generic spectral classes, integration, and photometry can be applied to luxR-derived spectra. The division of labour: luxR handles the water (depth propagation, inherent optical properties, the in-water light field); photobiology handles generic spectral computation.

Usage

as_source_spct(x, ...)

## S3 method for class 'lux_spectrum'
as_source_spct(x, strict.range = TRUE, ...)

## S3 method for class 'list'
as_source_spct(x, ...)

Arguments

Details

as_source_spct() requires spectral irradiance and delegates to photobiology::source_spct(). Energy units become s.e.irrad and photon units become s.q.irrad, rescaled to photobiology's mol/m2/s/nm. The spectrum is not converted between energy and photon bases: it arrives in the basis it already had, and photobiology::e2q() or q2e() does any conversion, so only one implementation of that conversion is ever in play.

Radiance is refused, because source_spct has no per-steradian term. photobiology is an optional (Suggests) dependency.

Value

A photobiology source_spct.

See Also

as_reflector_spct for reflectance, as_lux_spectrum for the reverse conversion, as_rspec for the pavo bridge

Examples

## Not run: 
  # The downwelling light field at 15 m, as a photobiology source_spct:
  # Jerlov Kd data cover 350-700 nm, so trim before propagating.
  surface <- from_solar("clear_noon")[350, 700]
  at_depth <- propagate_spectrum(surface, jerlov_Kd("II", surface$lambda),
                                 from = 0, to = 15)
  s <- as_source_spct(at_depth[["15"]])
  photobiology::e_irrad(s)

## End(Not run)

Description

Computes E(z) = E0 * exp(-Kd * z). Vectorised over depth.

Usage

attenuate_depth(E0, Kd, depth)

Arguments

Details

This is the package's principal lightweight water-column model. It assumes that $K_d$ is constant over the modeled path and propagates each wavelength independently. It does not solve the angular radiance field, multiple scattering, or wavelength redistribution. The scalar API has no inherent wavelength or depth range; the caller is responsible for supplying a $K_d$ that is valid for the medium and path.

Value

Numeric vector the same length as depth.

Examples

attenuate_depth(100, Kd = 0.06, depth = c(0, 10, 25, 50))

Description

Applies per-wavelength Kd across a depth grid using the Beer-Lambert law. Returns a tidy data frame, a numeric matrix, or (for lux_spectrum input) a named list of lux_spectrum objects.

Usage

attenuate_spectrum(E0_lambda, ...)

## S3 method for class 'numeric'
attenuate_spectrum(
  E0_lambda,
  Kd_lambda,
  depths,
  format = c("long", "matrix"),
  lambda = NULL,
  ...
)

## S3 method for class 'lux_spectrum'
attenuate_spectrum(E0_lambda, Kd_lambda, depths, ...)

Arguments

Details

This is a wavelength-resolved Beer-Lambert calculation, not a radiative-transfer solution. It assumes a homogeneous $K_d(\lambda)$ over the modeled path, treats wavelengths independently, and accepts only irradiance when a lux_spectrum is supplied. The generic numeric API cannot verify physical quantity or wavelength alignment; callers must supply aligned irradiance and $K_d$ vectors. Bundled Jerlov coefficients are supported only from 350–700 nm; see jerlov_Kd.

Value

A data frame, matrix, or named list of lux_spectrum.

References

Kirk JTO (1994) Light and Photosynthesis in Aquatic Ecosystems, 2nd edn. Cambridge University Press.

See Also

propagate_spectrum, band_irradiance, jerlov_Kd

Examples

E0  <- c(10, 20, 30)
Kd  <- c(0.01, 0.05, 0.20)
lam <- c(450, 550, 650)
attenuate_spectrum(E0, Kd, depths = c(0, 10, 25), lambda = lam)

Description

Propagates a spectrum from a known depth to one or more target depths via Beer-Lambert attenuation and integrates the result over a wavelength band. Works in both directions: set from > depths to recover shallower values (including the surface) from a deeper measurement.

Usage

band_irradiance(E_lambda, ...)

## S3 method for class 'numeric'
band_irradiance(
  E_lambda,
  Kd_lambda,
  lambda,
  depths,
  from = 0,
  lambda_min = NULL,
  lambda_max = NULL,
  photonic = FALSE,
  molar_unit = "umol",
  binwidth = NULL,
  allow_above_surface = FALSE,
  ...
)

## S3 method for class 'lux_spectrum'
band_irradiance(E_lambda, Kd_lambda, depths, lambda = NULL, ...)

Arguments

Details

Two operations are applied in sequence. First, Beer-Lambert propagation at each wavelength:

$E(z,\,\lambda) = E_0(\lambda)\, \exp\!\bigl[-K_d(\lambda)\,(z - z_0)\bigr]$

where $z_0$ is the depth of the known spectrum (from) and $K_d(\lambda)$ is the diffuse attenuation coefficient. Second, the propagated spectrum is integrated over the specified wavelength window [$\lambda_{\min}$, $\lambda_{\max}$]:

$E_{\mathrm{band}}(z) = \int_{\lambda_{\min}}^{\lambda_{\max}} E(z,\,\lambda)\,d\lambda$

approximated as $\sum_i E(z,\lambda_i)\,\Delta\lambda$ over bins within the window. See propagate_spectrum for the full Beer-Lambert documentation.

Value

A data.frame with columns:

depth

Target depth in metres.

E

Band-integrated irradiance in $W\,m^{-2}$ (or $\mu$mol m$^{-2}$ s$^{-1}$ when photonic = TRUE).

See Also

propagate_spectrum, par_irradiance

Examples

sp  <- solar_irradiance("clear_noon")
keep <- sp$wavelength >= 350 & sp$wavelength <= 700
lam <- sp$wavelength[keep]
E0  <- sp$irradiance[keep]
Kd  <- jerlov_Kd("II", lam)

# surface to depth profile, 500-600 nm band
band_irradiance(E0, Kd, lam, depths = c(0, 5, 10, 20, 50),
                lambda_min = 500, lambda_max = 600)

# recover surface from a 10 m measurement
E_10m <- E0 * exp(-Kd * 10)
band_irradiance(E_10m, Kd, lam, depths = 0, from = 10)

Description

The beam (total) attenuation coefficient is the sum of the absorption and scattering coefficients, $c = a + b$ (Johnsen 2012, ch. 5). It governs how a collimated beam — and the contrast of a sighted object — fades with distance, and is always larger than the diffuse attenuation $K_d$.

Usage

beam_attenuation(absorption, scattering)

Arguments

Value

Beam attenuation coefficient $c$ (1/m).

References

Johnsen S (2012) The Optics of Life. Princeton University Press, ch. 5.

See Also

single_scattering_albedo, transmittance, visual_range

Examples

beam_attenuation(absorption = 0.1, scattering = 0.05)   # 0.15

Description

Given a single measured value and a reference spectral shape, returns a rescaled spectrum whose forward operator reproduces the input. The shape assumption must be provided by the caller (e.g. from solar_irradiance()).

Usage

broadband2spectrum(
  value,
  unit = c("lx", "W", "kW", "umol", "radiance_W", "cd"),
  spectrum,
  water_type = NULL,
  depth = 0,
  wavelength_policy = c("error", "trim", "constant")
)

Arguments

Details

Supported units and their forward operators:

"lx"

photopic integral via irradiance2lux()

"W"

broadband integral $\sum E \cdot \Delta\lambda$

"kW"

same as "W" divided by 1000

"umol"

PAR-band photon flux (400–700 nm) in $\mu mol\,m^{-2}\,s^{-1}$

"radiance_W"

Lambertian radiance: $E = \pi L$, then integrate

"cd"

photometric radiance: $L = \text{lux} / \pi$

Value

A data frame with columns wavelength and irradiance, with a luxR.assumption attribute recording the provenance.

Examples

lam  <- seq(400, 700, by = 10)
spec <- data.frame(wavelength = lam, irradiance = rep(1, length(lam)))
broadband2spectrum(480, unit = "W", spectrum = spec)

Description

The CIE scotopic luminous efficiency function V'(lambda) for night vision, from CIE 018:2019 Table 2. Tabulated at 1 nm intervals from 380 nm to 780 nm, with its peak at 507 nm. Used by scotopic_lux.

Usage

CIE_scotopic

Format

A data frame with 401 rows and 2 columns:

lambda

Wavelength in standard air, in nm (380-780, step 1).

W

V'(lambda), dimensionless sensitivity from 0 to 1.

Details

Generated by data-raw/build_cie_efficiency_data.R from the checksum-pinned CIE CSV and companion metadata. Source URLs, DOI, checksums, retrieval date, standard, and license are stored as data-frame attributes under "luxR.provenance".

Source

International Commission on Illumination (CIE), CIE spectral luminous efficiency for scotopic vision, DOI: doi:10.25039/CIE.DS.gr6w4b5g, licensed CC BY-SA 4.0.

Description

The CIE 1931 photopic luminous efficiency function V(lambda), also called the standard observer luminosity curve, from CIE 018:2019 Table 1. Tabulated at 1 nm intervals from 360 nm to 830 nm, with its peak at 555 nm.

Usage

CIE1931

Format

A data frame with 471 rows and 2 columns:

lambda

Wavelength in standard air, in nm (360-830, step 1).

W

V(lambda), dimensionless sensitivity from 0 to 1.

Details

Generated by data-raw/build_cie_efficiency_data.R from the checksum-pinned CIE CSV and companion metadata. Source URLs, DOI, checksums, retrieval date, standard, and license are stored as data-frame attributes under "luxR.provenance".

Source

International Commission on Illumination (CIE), CIE spectral luminous efficiency for photopic vision, DOI: doi:10.25039/CIE.DS.dktna2s3, licensed CC BY-SA 4.0.

Description

Computes the just-noticeable difference (JND) between two spectral stimuli as seen by a named species, using the receptor-noise-limited colour discrimination model of Vorobyev & Osorio (1998). A $\Delta S < 1$ indicates the pair is not reliably discriminable; $\Delta S \geq 1$ indicates discrimination is possible.

Usage

colour_jnd(
  stim1,
  stim2,
  lambda,
  species,
  receptor = NULL,
  noise = 0.05,
  binwidth = NULL
)

Arguments

Details

For each receptor type $i$, the log-ratio of quantum catches $\Delta f_i = \ln(Q_{2i} / Q_{1i})$ is computed, then the chromatic distance is:

$\Delta S^2 = \Delta\mathbf{f}^\top \Sigma^{-1} \Delta\mathbf{f} - \frac{(\mathbf{1}^\top \Sigma^{-1} \Delta\mathbf{f})^2} {\mathbf{1}^\top \Sigma^{-1} \mathbf{1}}$

where $\Sigma = \mathrm{diag}(e_i^2)$ and $e_i$ is the noise (Weber fraction) of receptor $i$. The formula is general for any number of receptor types $\geq 2$.

Value

Scalar: chromatic distance $\Delta S$ in just-noticeable differences (JNDs).

References

Vorobyev M, Osorio D (1998) Receptor noise as a determinant of colour thresholds. Proc. R. Soc. B 265:351–358.

Vorobyev M et al. (2001) Colour thresholds and receptor noise: behaviour and physiology compared. Vision Res. 41:639–653.

See Also

quantum_catch, species_brightness, species_LEF

Examples

sp1 <- solar_irradiance("clear_noon")
sp2 <- solar_irradiance("underwater_10m")

# Human trichromat
colour_jnd(sp1$irradiance, sp2$irradiance,
           lambda = sp1$wavelength, species = "Homo sapiens",
           receptor = c("L-cone", "M-cone", "S-cone"))

# Zebrafish tetrachromat (all cones)
colour_jnd(sp1$irradiance, sp2$irradiance,
           lambda = sp1$wavelength, species = "Danio rerio")

Description

Attenuates an inherent contrast over a horizontal (or vertical) viewing path as a teaching/scenario heuristic: $C(r) = C_0 \, e^{-c_{\mathrm{eff}} r}$ (Johnsen 2012, ch. 5). The beam attenuation $c$ is approximated as Kd * kd_to_c; looking up uses $c - K_d$ and looking down $c + K_d$.

Usage

contrast_at_distance(
  C0,
  distance,
  Kd,
  kd_to_c = 1.5,
  direction = c("horizontal", "up", "down"),
  beam_c = NULL
)

Arguments

Details

This scalar calculation does not propagate spectra or recompute receptor catches. In particular, applying it to a chromatic JND is not a validated chromatic-vision model; use detection_range(model = "spectral_path") for wavelength-resolved propagation.

Value

Heuristic contrast remaining at each distance.

References

Johnsen S (2012) The Optics of Life. Princeton University Press, ch. 5.

See Also

inherent_contrast, detection_range

Examples

contrast_at_distance(C0 = 1, distance = c(0, 5, 10), Kd = 0.06)

Description

Converts the spectral values in a lux_spectrum between energy and photon-flux units, or between mW and W for radiance spectra. Supported conversions: "W/m2/nm" $\leftrightarrow$ "umol/m2/s/nm" / "mmol/m2/s/nm" / "mol/m2/s/nm", and the corresponding "/sr" photonic units. Energy radiance units "W/m2/sr/nm" and "mW/m2/sr/nm" are also interchangeable.

Usage

convert_unit(x, to, ...)

Arguments

Value

A new lux_spectrum with updated unit and E.

Examples

lam   <- seq(400, 700, by = 10)
x_W   <- lux_spectrum(rep(1, length(lam)), lam, "irradiance", "W/m2/nm")
x_mol <- convert_unit(x_W, "umol/m2/s/nm")
x_mol$unit

Description

$DoP = \sqrt{Q^2 + U^2 + V^2} / I$

. With V = 0 (the default, and the usual case for the underwater light field, which is essentially linearly polarized) this is the degree of linear polarization.

Usage

degree_of_polarization(I, Q, U, V = 0)

Arguments

Details

All inputs must be finite numeric vectors. A Stokes vector is physical only when $I > 0$ and $\sqrt{Q^2 + U^2 + V^2} \le I$. Values exceeding this bound by more than 64 machine epsilons are rejected with a luxR_polarization_physicality_error. Values within that round-off tolerance are returned as exactly one.

Value

Degree of polarization in [0, 1]. Vectorised. Scalar inputs are broadcast; incompatible non-scalar lengths are rejected.

See Also

angle_of_polarization, underwater_polarization

Examples

degree_of_polarization(I = 1, Q = 0.4, U = 0)   # 0.4

Description

One-stop wrapper that bundles inherent_contrast, detection_range, and a contrast-vs-distance curve into a single lux_detection object with print and plot methods.

Usage

detectability(
  object,
  background,
  illuminant,
  lambda,
  Kd,
  kd_to_c = 1.5,
  species = NULL,
  receptor = NULL,
  channel = c("both", "achromatic", "chromatic"),
  contrast_threshold = 0.02,
  jnd_threshold = 1,
  direction = c("horizontal", "up", "down"),
  noise = 0.05,
  distances = NULL,
  binwidth = NULL,
  beam_c = NULL,
  model = c("scalar_heuristic", "spectral_path"),
  veiling = NULL,
  max_distance = 1000,
  search_points = 1001L,
  geometry = c("lambertian", "scalar", "collimated", "custom"),
  solid_angle = NULL
)

Arguments

Value

An object of class lux_detection: a list with inherent (zero-distance contrast), range (scenario estimate per channel), curve (data frame of contrast vs distance), status metadata, and the call settings.

References

Johnsen S (2012) The Optics of Life. Princeton University Press, ch. 5.

See Also

inherent_contrast, detection_range, contrast_at_distance

Examples

sp   <- solar_irradiance("clear_noon")
lam  <- sp$wavelength
grey <- rep(0.3, length(lam))
red  <- 0.2 + 0.25 * exp(-((lam - 625) / 35)^2)
d <- detectability(red, grey, sp$irradiance, lam,
                   Kd = jerlov_Kd("IA", lambda = 490), species = "Danio rerio")
d
## Not run: plot(d)

Description

Generalises visual_range by using the estimated inherent contrast of an object against its background (from inherent_contrast) rather than assuming a contrast of 1. The default scalar heuristic uses $r = \ln(|C_0| / \text{threshold}) / c_{\mathrm{eff}}$. The spectral-path model instead propagates object, background, and veiling radiances at every wavelength and recomputes receptor catches at each evaluated distance.

Usage

detection_range(
  object,
  background,
  illuminant,
  lambda,
  Kd,
  kd_to_c = 1.5,
  species = NULL,
  receptor = NULL,
  channel = c("both", "achromatic", "chromatic"),
  contrast_threshold = 0.02,
  jnd_threshold = 1,
  direction = c("horizontal", "up", "down"),
  noise = 0.05,
  binwidth = NULL,
  beam_c = NULL,
  model = c("scalar_heuristic", "spectral_path"),
  veiling = NULL,
  max_distance = 1000,
  search_points = 1001L,
  geometry = c("lambertian", "scalar", "collimated", "custom"),
  solid_angle = NULL
)

Arguments

Details

Neither model is an empirically validated prediction of actual organismal detection distance. They omit target angular size, acuity, photon limitation, adaptation changes, behaviour, and observation probability.

The spectral-path scenario treats object and background as coplanar stimuli sharing one water path and one asymptotic veiling radiance. For each stimulus it evaluates

$L(r, \lambda) = L_v(\lambda) + [L_0(\lambda) - L_v(\lambda)] e^{-c_{\mathrm{eff}}(\lambda) r}.$

Both stimuli therefore converge toward the supplied veiling spectrum. This is a lightweight single-path model, not a multiple-scattering radiative-transfer solution. Because wavelength-dependent signals can be non-monotonic, the reported spectral distance is the furthest downward threshold crossing bracketed by search_points; callers should check resolution sensitivity.

Value

A list with elements achromatic and chromatic giving scenario estimates in metres. A value is 0 when no evaluated distance is detectable, NA when the channel was not requested or remained detectable through max_distance. Attributes record per-channel status, model, validation state, and maximum distance.

References

Johnsen S (2012) The Optics of Life. Princeton University Press, ch. 5.

See Also

inherent_contrast, contrast_at_distance, visual_range

Examples

sp   <- solar_irradiance("clear_noon")
lam  <- sp$wavelength
grey <- rep(0.3, length(lam))
red  <- 0.2 + 0.25 * exp(-((lam - 625) / 35)^2)
Kd   <- jerlov_Kd("IA", lambda = 490)
detection_range(red, grey, sp$irradiance, lam, Kd = Kd, species = "Danio rerio")

Description

Closed-form Beer-Lambert inversion: Kd = log(E1/E2) / (z2 - z1). Works for scalar or spectral (vector) inputs, or lux_spectrum objects.

Usage

fit_Kd(E1, ...)

## S3 method for class 'numeric'
fit_Kd(E1, z1, E2, z2, ...)

## S3 method for class 'lux_spectrum'
fit_Kd(E1, z1, E2, z2, ...)

Arguments

Value

Kd in 1/m. Same length as E1/E2.

References

Kirk JTO (1994) Light and Photosynthesis in Aquatic Ecosystems, 2nd edn. Cambridge University Press.

See Also

propagate_spectrum, attenuate_spectrum, jerlov_Kd

Examples

data(Naples)
fit_Kd(sum(Naples$depth_0m), 0, sum(Naples$depth_10m), 10)

Description

Finds the peak wavelength ($\lambda_{\max}$) that minimises the sum of squared residuals between the Govardovskii (2000) template and the supplied sensitivity measurements. Uses optimize for an exact single-parameter search, so the result is a continuous estimate rather than a grid point.

Usage

fit_sensitivity(
  lambda,
  sensitivity,
  chromophore = c("A1", "A2"),
  lambda_max_range = c(300, 700)
)

Arguments

Value

A list with components:

lambda_max

Best-fit peak wavelength (nm).

chromophore

Chromophore used.

SS

Residual sum of squares at the optimum.

fitted

Data frame with columns lambda and S giving the template evaluated on the input wavelength grid.

References

Govardovskii VI, Fyhrquist N, Reuter T, Kuzmin DG, Donner K (2000) In search of the visual pigment template. Visual Neuroscience 17:509–528.

See Also

govardovskii_template

Examples

lam   <- seq(400, 700, by = 10)
true  <- govardovskii_template(lam, lambda_max = 530)$S
noisy <- pmax(0, true + rnorm(length(true), 0, 0.02))
fit   <- fit_sensitivity(lam, noisy)
fit$lambda_max  # should be close to 530

Description

Unpolarised Fresnel reflectance for light crossing a flat air-water boundary, as a function of incidence angle (Johnsen 2012, ch. 5). At normal incidence about 2% of downwelling light is reflected ($R = ((n-1)/(n+1))^2$). Going from water to air, total internal reflection ($R = 1$) occurs beyond the critical angle (the edge of snells_window).

Usage

fresnel_reflectance(
  angle = 0,
  n = 1.333,
  from = c("air", "water"),
  component = c("unpolarized", "s", "p")
)

Arguments

Value

Reflectance (0-1); the transmitted fraction is $1 - R$.

References

Johnsen S (2012) The Optics of Life. Princeton University Press, ch. 5.

See Also

snells_window, underwater_polarization

Examples

fresnel_reflectance(0)                       # ~0.02 at normal incidence
fresnel_reflectance(60, from = "water")      # total internal reflection -> 1
fresnel_reflectance(53.1, component = "p")   # ~0 near Brewster's angle

Description

Load a Naples depth spectrum as a lux_spectrum

Usage

from_naples(depth = c("0m", "5m", "10m"))

Arguments

Value

A lux_spectrum with unit "umol/m2/s/nm".

See Also

Naples, as_lux_spectrum

Examples

x <- from_naples("0m")
print(x)

Description

Ocean Optics text files do not contain a standardized machine-readable unit or calibration state. All physical declarations are therefore required. Use read_ocean_optics to inspect raw or relative values.

Usage

from_ocean_optics(path, quantity = NULL, unit = NULL, calibration = NULL)

Arguments

Value

A validated lux_spectrum with import provenance in metadata.

See Also

read_ocean_optics, from_trios, read_spectrum

Description

Load a reference solar spectrum as a lux_spectrum

Usage

from_solar(condition = "clear_noon")

Arguments

Value

A lux_spectrum with unit "W/m2/nm".

See Also

solar_irradiance, as_lux_spectrum

Examples

x <- from_solar("clear_noon")
print(x)

Description

Wraps read_trios. The low-level reader preserves negative instrument values. Construction of non-negative physical radiance spectra therefore either fails (the default) or requires an explicit, recorded zero-floor preprocessing policy.

Usage

from_trios(path, negative_policy = c("error", "zero"))

Arguments

Value

A named list of radiance lux_spectrum objects.

See Also

read_trios, read_spectrum

Description

Vectorised; passes through NA.

Usage

ft2m(z)

Arguments

Value

Numeric vector in metres.

See Also

m2ft

Examples

propagate_depth(8260, Kd = 0.062, from = ft2m(72), to = 0)

Description

Reconstructs a photoreceptor's normalised absorbance spectrum from the peak wavelength alone, using the parametric template of Govardovskii et al. (2000) for A1 and A2 chromophores. This is the standard workhorse of comparative visual physiology.

Usage

govardovskii_template(lambda, lambda_max, chromophore = c("A1", "A2"))

Arguments

Details

The template models absorbance as the sum of an $\alpha$-band (main peak) and a $\beta$-band (short-wavelength shoulder). The $\alpha$-band follows the four-parameter expression:

$S_\alpha(\lambda) = \left[ e^{A(a - x)} + e^{B(0.922 - x)} + e^{C(1.104 - x)} + D \right]^{-1}, \quad x = \frac{\lambda_{\max}}{\lambda}$

where $A$, $B$, $C$, $D$, and $a$ are chromophore-specific constants (A1: $A=69.7$, $B=28$, $C=-14.9$, $D=0.674$, $a$ wavelength-dependent; A2: $A=62.7$, $B=26.5$, $C=-15.6$, $D=0.530$). The $\beta$-band is a Gaussian:

$S_\beta(\lambda) = 0.26\,\exp\!\left[ -\!\left(\frac{\lambda - \lambda_\beta}{b}\right)^2 \right]$

with $\lambda_\beta = 189 + 0.315\,\lambda_{\max}$ and $b = -40.5 + 0.195\,\lambda_{\max}$. The full template is $S(\lambda) = \max(0,\, S_\alpha + S_\beta)$, normalised to a peak of 1.

Value

A data frame with columns lambda and S (normalised absorbance, 0–1).

References

Govardovskii VI, Fyhrquist N, Reuter T, Kuzmin DG, Donner K (2000) In search of the visual pigment template. Visual Neuroscience 17:509–528.

Examples

lam <- seq(300, 750, by = 1)
govardovskii_template(lam, lambda_max = 560)

Description

Computes the contrast a viewer perceives between an object and its background at zero viewing distance, from their reflectance spectra and the in-water illuminant. Two channels are available: an achromatic (brightness) Weber contrast and a chromatic distance ($\Delta S$, in JNDs) from the Vorobyev-Osorio model. Object and background radiances are formed as reflectance times illuminant.

Usage

inherent_contrast(
  object,
  background,
  illuminant,
  lambda,
  species = NULL,
  receptor = NULL,
  noise = 0.05,
  channel = c("both", "achromatic", "chromatic"),
  binwidth = NULL
)

Arguments

Value

A list with elements achromatic (Weber contrast) and chromatic ($\Delta S$ in JNDs); unrequested channels are NA.

References

Johnsen S (2012) The Optics of Life: A Biologist's Guide to Light in Nature. Princeton University Press. (Ch. 5: contrast and sighting distance.)

See Also

contrast_at_distance, detection_range, colour_jnd, weber_contrast

Examples

sp  <- solar_irradiance("clear_noon")
lam <- sp$wavelength
grey <- rep(0.3, length(lam))
red  <- 0.2 + 0.25 * exp(-((lam - 625) / 35)^2)
inherent_contrast(red, grey, sp$irradiance, lam, species = "Danio rerio")

Description

Computes photopic illuminance (lux) by weighting spectral irradiance with the CIE 1931 V($\lambda$) luminous efficiency function. The default LEF argument can be swapped for CIE_scotopic to obtain scotopic lux, or for any user-supplied spectral sensitivity curve.

Usage

irradiance2lux(irradiance, ...)

## Default S3 method:
irradiance2lux(irradiance, ...)

## S3 method for class 'numeric'
irradiance2lux(
  irradiance,
  lambda,
  photonic = FALSE,
  molar_unit = "photons",
  total = TRUE,
  LEF = CIE1931,
  binwidth = NULL,
  integration = c("rectangle", "trapezoid"),
  verbose = FALSE,
  ...
)

## S3 method for class 'lux_spectrum'
irradiance2lux(
  irradiance,
  total = TRUE,
  LEF = CIE1931,
  integration = c("rectangle", "trapezoid"),
  verbose = FALSE,
  ...
)

Arguments

Details

Photopic illuminance is a spectrally weighted integral of irradiance using the CIE 1931 photopic luminous efficiency function $V(\lambda)$. The maximum luminous efficacy $K_m = 683$ lm W$^{-1}$ occurs at 555 nm:

$E_v = 683 \int_{360}^{830} E(\lambda)\,V(\lambda)\,d\lambda$

With the default rectangular method, the integral is approximated as $E_v \approx 683 \sum_i E(\lambda_i)\,V(\lambda_i)\,\Delta\lambda$. For irregular numeric wavelength grids, callers can explicitly select composite trapezoidal integration. This treats the weighted spectrum as piecewise linear between measured wavelengths and integrates only over [min(lambda), max(lambda)]; it does not infer outer bin edges. $V(\lambda)$ values are taken from the LEF data frame by linear interpolation at each measured wavelength. Wavelengths outside the range of the supplied LEF receive zero weight.

Value

A scalar lux value (total = TRUE) or numeric vector.

References

CIE Publication 15: Colorimetry, 3rd edn (2004). Commission Internationale de l'Eclairage, Vienna.

See Also

lux2irradiance, scotopic_lux, par_irradiance

Examples

utils::data(Naples)
irradiance2lux(Naples$depth_0m, Naples$wv, photonic = TRUE, molar_unit = "umol")
irradiance2lux(c(0.2, 0.8, 0.4), c(500, 515, 540),
               integration = "trapezoid")

Description

The relationship between irradiance E and radiance L depends on the angular distribution of the light field. The caller must supply the geometry; the function refuses to silently apply the wrong identity.

Usage

irradiance2radiance(
  E,
  geometry = c("lambertian", "scalar", "collimated", "custom"),
  solid_angle = NULL
)

Arguments

Value

Radiance in $W\,m^{-2}\,sr^{-1}$ (same numeric unit as E).

References

Johnsen S (2012) The Optics of Life: A Biologist's Guide to Light in Nature. Princeton University Press. (Ch. 2: vector vs scalar irradiance.)

See Also

radiance2irradiance

Examples

irradiance2radiance(pi)                              # lambertian: L = 1
irradiance2radiance(2 * pi, "scalar")                # scalar: L = 1
irradiance2radiance(10, "collimated")                # L = E
irradiance2radiance(10, "custom", solid_angle = 2)  # L = 5

Description

Returns Kd(lambda) for the specified Jerlov water type from the bundled jerlov_types dataset (Jerlov 1976; Solonenko & Mobley 2015). Optionally interpolates onto a user-supplied wavelength grid.

Usage

jerlov_Kd(
  type = "IA",
  lambda = NULL,
  interp = c("linear", "spline", "nearest"),
  extrapolation = c("error", "constant")
)

Arguments

Details

The bundled Jerlov table supports 350–700 nm. Values outside that domain are not measured by this dataset and therefore fail by default. Constant endpoint extension is available only as an explicit modelling assumption; linear or spline extrapolation is not supported.

Value

If lambda is NULL: a data frame with columns type, lambda, Kd and dataset metadata attributes. If lambda is supplied: a numeric vector of Kd values (1/m) with a "luxR.jerlov" provenance attribute recording the water type, interpolation and extrapolation policies, supported and requested ranges, source checksum, build commit, and model version.

References

Jerlov NG (1976) Marine Optics. Elsevier, Amsterdam.

Solonenko MG, Mobley CD (2015) Inherent and apparent optical properties of Jerlov water types. Applied Optics 54(17):5392-5401.

Examples

jerlov_Kd("IA")
Kd_IA <- jerlov_Kd("IA", lambda = c(400, 450, 500, 550, 600))
as.numeric(Kd_IA)
attr(Kd_IA, "luxR.jerlov")[c("type", "interp", "extrapolation",
                              "supported_wavelength_range_nm")]

lam <- seq(400, 700, by = 10)
Kd  <- jerlov_Kd("II", lambda = lam)
attenuate_spectrum(rep(1, length(lam)), Kd, depths = c(10, 25, 50),
                  lambda = lam)

Description

Long-format table of Kd(lambda) values for five oceanic and three coastal water types from Jerlov (1976) and Solonenko & Mobley (2015). Attributes record the supported wavelength range and spacing, a table checksum, source artifact path, build commit, model version, and package version.

Usage

jerlov_types

Format

A data frame with 120 rows and 3 columns:

type

Jerlov water type (character): "I", "IA", "IB", "II", "III" (oceanic, clearest to most turbid) and "C1", "C2", "C3" (coastal).

lambda

Wavelength in nm (350 to 700, 25 nm steps).

Kd

Diffuse attenuation coefficient in 1/m.

References

Jerlov NG (1976) Marine Optics. Elsevier, Amsterdam.

Solonenko MG, Mobley CD (2015) Inherent and apparent optical properties of Jerlov water types. Applied Optics 54(17):5392-5401.

Examples

data(jerlov_types)
subset(jerlov_types, type == "IA")

Description

Convenience wrapper that takes one of the bundled reference solar spectra, converts it to $W\,m^{-2}\,nm^{-1}$, and propagates it from its recorded reference depth to a single absolute depth in a Jerlov water type via jerlov_Kd and propagate_spectrum. This is the "solar condition + water type + depth -> spectrum at depth" operation the Shiny app's colour-discrimination and detection tabs share.

Usage

light_at_depth(
  condition = "clear_noon",
  water_type = "IA",
  depth = 0,
  surface_source = c("direct", "diffuse"),
  surface_angle = 30,
  refractive_index = 1.333,
  wavelength_policy = c("error", "trim", "constant")
)

Arguments

Details

An above-surface source is multiplied by surface_transmittance before water-column attenuation. The default is a flat interface and direct illumination incident 30 degrees from vertical. An in-water source is unchanged when depth equals its reference depth. For deeper targets, only the additional water-column distance is applied. Shallower targets are rejected because reconstructing them would require an explicit inverse-propagation model. Water-column propagation is the lightweight spectral Beer-Lambert model: it assumes a depth-invariant Jerlov $K_d(\lambda)$, propagates wavelength bins independently, and is not a multiple-scattering or angular radiative-transfer calculation. No universal maximum depth is implied; the selected water type must remain representative of the whole path.

Value

A data frame with columns lambda (nm) and irradiance (downwelling spectral irradiance at depth, in $W\,m^{-2}\,nm^{-1}$). The "luxR.jerlov" attribute records the wavelength policy and data provenance.

See Also

from_solar, jerlov_Kd, propagate_spectrum

Examples

head(light_at_depth("clear_noon", "IA", depth = 5,
                    wavelength_policy = "trim"))

Description

Constructs a validated lux_spectrum — the core spectral container used throughout luxR. The object carries spectral values, wavelength grid, physical quantity, unit, bin width, and free-form metadata together, so unit conversions and arithmetic operations stay consistent.

Usage

lux_spectrum(
  E,
  lambda,
  quantity = "irradiance",
  unit = "W/m2/nm",
  binwidth = NULL,
  meta = list()
)

Arguments

Details

Valid unit strings: "W/m2/nm", "W/m2/sr/nm", "mW/m2/sr/nm", "umol/m2/s/nm", "mmol/m2/s/nm", "mol/m2/s/nm", "umol/m2/s/sr/nm", "mmol/m2/s/sr/nm", "mol/m2/s/sr/nm", "dimensionless".

Both spectral vectors must be non-empty, numeric, finite, and equal in length. Wavelengths must be strictly increasing, unique, and regularly spaced. Irradiance and radiance values must be non-negative; reflectance values must lie in [0, 1]. Units without "/sr" describe irradiance, units with "/sr" describe radiance, and "dimensionless" is valid only for reflectance.

S3 methods available on lux_spectrum objects: print(), summary(), plot(), as.data.frame(), [ (wavelength subsetting), and the arithmetic operators +, -, *, /. A list of lux_spectrum objects can be plotted with plot_spectra.

Value

An S3 object of class "lux_spectrum".

See Also

as_lux_spectrum, convert_unit, plot_spectra

Examples

lam <- seq(400, 700, by = 10)
x   <- lux_spectrum(rep(1, length(lam)), lam, "irradiance", "W/m2/nm")
print(x)

Description

lux is a single scalar; a spectrum has many degrees of freedom. This function takes a reference shape and rescales it so its photopic integral equals lx. The shape assumption must be supplied by the caller.

Usage

lux2irradiance(
  lx,
  spectrum,
  lambda = NULL,
  LEF = CIE1931,
  binwidth = NULL,
  integration = c("rectangle", "trapezoid")
)

Arguments

Value

Numeric vector of rescaled spectral irradiance (same length as the wavelength grid).

Examples

spec <- data.frame(lambda = CIE1931$lambda, irradiance = CIE1931$W)
irr  <- lux2irradiance(5000, spec)

Description

Vectorised; passes through NA.

Usage

m2ft(z)

Arguments

Value

Numeric vector in feet.

See Also

ft2m

Examples

m2ft(30)

Description

Computes the Michelson (sinusoidal) contrast: $(I_{bright} - I_{dark}) / (I_{bright} + I_{dark})$. Values range from 0 (no contrast) to 1 (maximum contrast). Commonly used for periodic patterns such as gratings.

Usage

michelson_contrast(I_bright, I_dark)

Arguments

Value

Contrast value(s) in $[0, 1]$.

See Also

[weber_contrast()]

Examples

michelson_contrast(I_bright = 8, I_dark = 2)

Description

Converts per-bin photon flux (photons m$^{-2}$ s$^{-1}$ nm$^{-1}$, or molar equivalents) to energy-based spectral irradiance in W m$^{-2}$ nm$^{-1}$. The inverse operation is W2mol_spec_irradiance.

Usage

n2W_spec_irradiance(value, ...)

## S3 method for class 'numeric'
n2W_spec_irradiance(
  value,
  lambda,
  photonic = FALSE,
  molar_unit = "photons",
  ...
)

## S3 method for class 'lux_spectrum'
n2W_spec_irradiance(value, ...)

Arguments

Details

Each photon at wavelength $\lambda$ carries energy $E = hc/\lambda$. Spectral irradiance in W m$^{-2}$ nm$^{-1}$ is therefore the photon flux $N$ (photons m$^{-2}$ s$^{-1}$ nm$^{-1}$) multiplied by the per-photon energy:

$E(\lambda) = N(\lambda) \cdot \frac{hc}{\lambda}$

where $h = 6.626 \times 10^{-34}$ J s (Planck constant) and $c = 2.998 \times 10^8$ m s$^{-1}$ (speed of light). The constant $hc$ in nm-compatible units is $1.98645 \times 10^{-16}$ J nm, the value used internally.

Value

Numeric vector of spectral irradiance in $W\,m^{-2}\,nm^{-1}$, or a lux_spectrum with unit = "W/m2/nm" or "W/m2/sr/nm" according to the input dimensionality.

Examples

utils::data(Naples)
n2W_spec_irradiance(Naples$depth_0m, Naples$wv, photonic = TRUE, molar_unit = "umol")

Description

A small set of downwelling spectral irradiance measurements made at three depths at Mare Chiaro in the Gulf of Naples, Italy. This is example field data — a single site on particular days — provided to illustrate working with measured spectra; it is not a general reference spectrum (cf. the ASTM solar_spectra). Values are in micromol photons per square metre per second per nm ($\mu mol\,m^{-2}\,s^{-1}\,nm^{-1}$); wavelength bins are approximately 5 nm wide.

Usage

Naples

Format

A data frame with 103 rows and 4 columns:

wv

Bin-centre wavelength in nm.

depth_0m

Irradiance at the surface (0 m depth).

depth_5m

Irradiance at 5 m depth.

depth_10m

Irradiance at 10 m depth.

Source

Field measurements of downwelling spectral irradiance at Mare Chiaro, Gulf of Naples, Italy, attributed to M. J. Bok and J. D. Kirwan (2021, unpublished data). The bundled object is regenerated from an explicitly labelled legacy canonical snapshot; original acquisition metadata and redistribution terms are not documented.

Examples

data(Naples)
irradiance2lux(Naples$depth_0m, Naples$wv, photonic = TRUE, molar_unit = "umol")

Description

Returns the ratio of band-integrated irradiance over 400–700 nm to the total integrated irradiance across the full wavelength range supplied. Useful for characterising how spectrally narrowed a light field has become (e.g. at depth, where red wavelengths are preferentially removed).

Usage

par_fraction(irradiance, ...)

## S3 method for class 'numeric'
par_fraction(irradiance, lambda, binwidth = NULL, ...)

## S3 method for class 'lux_spectrum'
par_fraction(irradiance, ...)

Arguments

Value

Numeric scalar in (0, 1].

Examples

sp <- solar_irradiance("clear_noon")
par_fraction(sp$irradiance, sp$wavelength)

Description

Integrates spectral irradiance over the photosynthetically active range 400–700 nm and returns the result in µmol photons m$^{-2}$ s$^{-1}$. Accepts energy units (W m$^{-2}$ nm$^{-1}$), raw photon counts, or a lux_spectrum object in any supported unit.

Usage

par_irradiance(irradiance, ...)

## S3 method for class 'numeric'
par_irradiance(irradiance, lambda, photonic = FALSE, binwidth = NULL, ...)

## S3 method for class 'lux_spectrum'
par_irradiance(irradiance, ...)

Arguments

Details

PAR is the photon flux integrated over the photosynthetically active range 400–700 nm, expressed in µmol photons m$^{-2}$ s$^{-1}$. When input is in energy units (W m$^{-2}$ nm$^{-1}$), each bin is first converted to photon flux via $N = E\lambda/(hc)$, then the total is divided by Avogadro's constant scaled to µmol:

$Q_{\mathrm{PAR}} = \frac{1}{N_A \times 10^{-6}} \int_{400}^{700} \frac{E(\lambda)\,\lambda}{hc}\,d\lambda$

where $N_A = 6.022 \times 10^{23}$ mol$^{-1}$ and $hc = 1.98645 \times 10^{-16}$ J nm. The result is in µmol photons m$^{-2}$ s$^{-1}$.

Value

Scalar PAR irradiance in µmol photons m$^{-2}$ s$^{-1}$.

References

Thimijan RW, Heins RD (1983) HortScience 18:818-822.

See Also

par_fraction, irradiance2lux, band_irradiance

Examples

sp  <- solar_irradiance("clear_noon")
par_irradiance(sp$irradiance, sp$wavelength)

Description

Solves exp(-Kd * z) = fraction for z, giving -log(fraction) / Kd. The default 1

Usage

photic_depth(Kd, fraction = 0.01)

Arguments

Value

Depth(s) in metres at which fraction of surface light remains.

Examples

photic_depth(0.06)
photic_depth(0.06, fraction = 0.1)

Description

Uses E_photon = hc / lambda, with hc = 1.98644585714893e-16 J·nm. Vectorised over both n and lambda.

Usage

photon2W(n, lambda)

Arguments

Value

Numeric vector of spectral irradiance in $W\,m^{-2}\,nm^{-1}$.

See Also

W2photon

Examples

photon2W(1e15, 555)

Description

Draws all spectra in x on a single plot with a shared wavelength axis. Line colours cycle through the default palette. Names of the list (or meta$label if present) are used for the legend. Additional arguments in ... are passed to the initial plot() call.

Usage

plot_spectra(x, ...)

Arguments

Value

invisible(x) — called for its side effect (plot).

Description

How distinct a target's polarization is from its background, for a polarization-sensitive viewer. Each polarization state is mapped to its normalised linear-polarization (Stokes) coordinates

$q = DoP\cos 2\psi, \qquad u = DoP\sin 2\psi,$

where $\psi$ is the angle of polarization; the polarization distance is the Euclidean separation in this plane,

$\Delta P = \sqrt{(q_t - q_b)^2 + (u_t - u_b)^2}.$

The factor of two in the angle correctly handles the 180-degree periodicity of polarization orientation, so orthogonal e-vectors (90 degrees apart) at equal degree of polarization give the maximal angular contrast. This is the geometric core of How & Marshall's (2014) polarization-distance model.

Usage

polarization_contrast(target_dop, target_aop, background_dop, background_aop)

Arguments

Value

A data frame with columns delta_dop (absolute difference in degree of polarization), delta_aop (axial angular difference in degrees, [0, 90]), and distance (the polarization distance $\Delta P$).

References

How MJ, Marshall NJ (2014) Polarization distance: a framework for modelling object detection by polarization vision systems. Proceedings of the Royal Society B 281:20131632.

See Also

underwater_polarization, degree_of_polarization, weber_contrast

Examples

# A horizontally polarized target against a weakly polarized background:
polarization_contrast(target_dop = 0.5, target_aop = 0,
                      background_dop = 0.1, background_aop = 45)

Description

Computes E(to) = E_known * exp(-Kd * (to - from)). Works forward (to > from), inverse (to < from, recovering a shallower value), and between any two depths.

Usage

propagate_depth(E_known, Kd, from = 0, to, allow_above_surface = FALSE)

Arguments

Value

Irradiance at to, in the same units as E_known.

Note

Un-attenuating with a negative depth delta assumes the water column is homogeneous above the measurement point. For stratified water bodies (thermocline, chlorophyll layer) the result will be approximate. Inverse propagation also amplifies measurement noise and can overflow for long or strongly attenuating paths. This model does not cross the air-water interface; use surface_transmittance explicitly or a high-level workflow such as light_at_depth.

Examples

propagate_depth(112400, Kd = 0.062, from = 0, to = 30)
propagate_depth(8260,   Kd = 0.062, from = 22, to = 0)

Description

Applies Beer-Lambert attenuation at each wavelength independently, propagating a known spectral irradiance from depth from to one or more target depths to. Works in both directions: set to < from to recover a shallower (or surface) spectrum from a deeper measurement, assuming a homogeneous water column.

Usage

propagate_spectrum(E_lambda, ...)

## S3 method for class 'numeric'
propagate_spectrum(
  E_lambda,
  Kd_lambda,
  from = 0,
  to,
  format = c("long", "matrix"),
  lambda = NULL,
  allow_above_surface = FALSE,
  ...
)

## S3 method for class 'lux_spectrum'
propagate_spectrum(
  E_lambda,
  Kd_lambda,
  from = 0,
  to,
  allow_above_surface = FALSE,
  ...
)

Arguments

Details

This is the package's principal lightweight propagation tier. It applies $E(z,\lambda) = E(z_0,\lambda) \exp[-K_d(\lambda)(z-z_0)]$, assuming $K_d$ is constant along the path and wavelengths propagate independently. It does not model an angular radiance field, multiple scattering, or spectral redistribution. There is no universal supported depth range: validity depends on whether the supplied $K_d$ represents the entire path. Bundled Jerlov data are limited to 350–700 nm. Inverse propagation is an assumption-heavy reconstruction that amplifies noise.

Value

A data frame, matrix, or named list of lux_spectrum.

References

Kirk JTO (1994) Light and Photosynthesis in Aquatic Ecosystems, 2nd edn. Cambridge University Press.

Examples

E_10m <- c(8, 15, 20)
Kd    <- c(0.02, 0.06, 0.25)
propagate_spectrum(E_10m, Kd, from = 10, to = c(0, 25, 50))

Description

Computes $Q_w = \sum E_p(\lambda) S(\lambda) \Delta\lambda$, where $E_p$ is spectral photon irradiance and $S$ is a dimensionless sensitivity or absorptance curve. The result is a photon irradiance weighted by the supplied curve, not an absolute photon rate for one receptor.