User Guide

Introduction

Package ‘photobiologyWavebands’ provides constructors for waveband objects, a class defined in package ‘photobiology’. These constructors are convenience functions that allow definition of ranges of wavelengths and biological spectral weighting functions (BSWFs) following definitions in common use, CIE recommendations and ISO standards.

This User Guide is currently very brief, please, consult the help for the individual functions for the details, including references to the literature where the equations and wavelength ranges used in the calculations have been obtained.

Preliminaries

Package ‘photobiologyWavebands’ depends on package ‘photobiology’. We can load and attach both of them with the following statement.

library(photobiologyWavebands)

## Loading required package: photobiology

## News at https://www.r4photobiology.info/

Waveband constructors for ranges

Functions for several colour bands, in some cases according to different optional definitions, are listed in the tables below.

Red("ISO")

## Red.ISO 
## low (nm) 610 
## high (nm) 760 
## weighted none

Red("Smith10")

## Red.Smith10 
## low (nm) 655 
## high (nm) 665 
## weighted none

PhR()

## PhR 
## low (nm) 400 
## high (nm) 700 
## weighted none

UV()

## UV.ISO 
## low (nm) 100 
## high (nm) 400 
## weighted none

IR()

## IR.ISO 
## low (nm) 780 
## high (nm) 1e+06 
## weighted none

UV_bands("ISO")

## [[1]]
## UVC.ISO 
## low (nm) 100 
## high (nm) 280 
## weighted none 
## 
## [[2]]
## UVB.ISO 
## low (nm) 280 
## high (nm) 315 
## weighted none 
## 
## [[3]]
## UVA.ISO 
## low (nm) 315 
## high (nm) 400 
## weighted none

UV_bands("CIE")

## [[1]]
## UVC.CIE 
## low (nm) 100 
## high (nm) 280 
## weighted none 
## 
## [[2]]
## UVB.CIE 
## low (nm) 280 
## high (nm) 315 
## weighted none 
## 
## [[3]]
## UVA2.CIE 
## low (nm) 315 
## high (nm) 340 
## weighted none 
## 
## [[4]]
## UVA1.CIE 
## low (nm) 340 
## high (nm) 400 
## weighted none

Plant_bands()

## [[1]]
## UVB.ISO 
## low (nm) 280 
## high (nm) 315 
## weighted none 
## 
## [[2]]
## UVA2.CIE 
## low (nm) 315 
## high (nm) 340 
## weighted none 
## 
## [[3]]
## UVA1.CIE 
## low (nm) 340 
## high (nm) 400 
## weighted none 
## 
## [[4]]
## Blue.Sellaro 
## low (nm) 420 
## high (nm) 490 
## weighted none 
## 
## [[5]]
## Green.Sellaro 
## low (nm) 500 
## high (nm) 570 
## weighted none 
## 
## [[6]]
## Red.Smith20 
## low (nm) 650 
## high (nm) 670 
## weighted none 
## 
## [[7]]
## FarRed.Smith20 
## low (nm) 720 
## high (nm) 740 
## weighted none

Landsat_bands("L1")

## [[1]]
## Green.LandsatRBV 
## low (nm) 480 
## high (nm) 580 
## weighted none 
## 
## [[2]]
## Red.LandsatRBV 
## low (nm) 580 
## high (nm) 680 
## weighted none 
## 
## [[3]]
## NIR.LandsatRBV 
## low (nm) 700 
## high (nm) 830 
## weighted none 
## 
## [[4]]
## Green.LandsatMSS 
## low (nm) 500 
## high (nm) 600 
## weighted none 
## 
## [[5]]
## Red.LandsatMSS 
## low (nm) 600 
## high (nm) 700 
## weighted none 
## 
## [[6]]
## NIR.LandsatMSS 
## low (nm) 800 
## high (nm) 1100 
## weighted none

Calculating irradiances

An example using sun.pct included in package ‘photobiology’. As the input spectral irradiance is units of Watt m^-2 nm^-1 the output is in mol m^-2 s^-1 or W m^-2.

e_irrad(sun.spct, UV()) # W m-2

## E_]UV.ISO 
##  28.62872 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

q_irrad(sun.spct, UV()) * 1e6 # umol s-1 m-2

## Q_]UV.ISO 
##  86.49506 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

Irradiances for different wavebands can be grouped into a list of any length. If the list has named members, then these names are used instead of the default ones in the output.

e_irrad(sun.spct, list(Blue(), VIS()))

## E_Blue.ISO  E_VIS.ISO 
##   37.55207  231.86345 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

e_irrad(sun.spct, list(B = Blue(), VIS()))

##       E_B E_VIS.ISO 
##  37.55207 231.86345 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

The constructor functions for coherent lists of wavebands described above can be used directly.

e_irrad(sun.spct, VIS_bands())

## E_Purple.ISO   E_Blue.ISO  E_Green.ISO E_Yellow.ISO E_Orange.ISO    E_Red.ISO 
##     47.75529     37.55207     49.26860     13.67971     12.00432     79.38159 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

Photon ratios

Photon- and energy ratios can be calculated from any pair of waveband objects. This a convenient and very flexible way of doing this type of calculations.

q_ratio(sun.spct, Blue(), VIS())

## Blue:VIS[q:q] 
##     0.1371157 
## attr(,"radiation.unit")
## [1] "q:q ratio"

e_ratio(sun.spct, Blue(), VIS())

## Blue:VIS[e:e] 
##     0.1619577 
## attr(,"radiation.unit")
## [1] "e:e ratio"

Spectral weighting functions (SWFs)

Currently functions for constructing waveband objects describing several BSWFs are implemented (see Table below). These functions take three arguments in most cases as BSWFs have been used and continue to be used inconsistently in the scientific literature. By supplying these arguments different variations of the BSWFs can be obtained. The defaults used are those values which we consider best, usually the most frequently used ones, except in cases when we consider the use of those values problematic for the reliability of the calculations or simply unjustified.

e_irrad(sun.spct, CIE())

## E_]CIE98.298 
##   0.08181583 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

# at 1 nm intervals
wavelengths1 <- 285:400
action.spectrum1 <- CIE_e_fun(wavelengths1)

sun.spct * CIE()

## Object: source_spct [122 x 2]
## Wavelength range 280-400 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2010-06-22 09:51:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## Data weighted using 'CIE98.298' BSWF
## 
## # A tibble: 122 × 2
##    w.length s.e.irrad
##       <dbl>     <dbl>
##  1     280          0
##  2     281.         0
##  3     282.         0
##  4     283.         0
##  5     284.         0
##  6     285.         0
##  7     286.         0
##  8     286.         0
##  9     287.         0
## 10     288.         0
## # ℹ 112 more rows

Luminous flux

The luminous flux per unit area in lux can be calculated as follows using the original luminous efficiency function for the human eye used when the lumen definition was standardized. As we start with spectral irradiance we obtain luminous flux per unit area expressed in lux. The spectra luminous efficiency function data are included in package ‘photobiology’.

e_response(sun.spct * CIE1924_lef.spct) * photopic_sensitivity

## R[/e]_Total 
##    49579.93 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"

The luminous flux per unit area in lux can be calculated as follows using the latest luminous efficiency function for the human eye.

e_response(sun.spct * CIE2008_lef2deg.spct) * photopic_sensitivity

## R[/e]_Total 
##    53057.78 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"

As the luminous efficiency functions vary slightly in the wavelength at which the maximum is located, and the wavelength used for the sensitivity constant is fixed by the definition of the Lumen, a small correction is need for exact results (not shown).

An equivalent quantity can be calculated for scotopic vision, using the corresponding function and constant.

e_response(sun.spct * 1e-6 * CIE1951_scotopic_lef.spct) * scotopic_sensitivity

## R[/e]_Total 
##   0.1186256 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"