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.
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/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 noneRed("Smith10")## Red.Smith10
## low (nm) 655
## high (nm) 665
## weighted nonePAR()## PAR
## low (nm) 400
## high (nm) 700
## weighted noneUV()## UV.ISO
## low (nm) 100
## high (nm) 400
## weighted noneIR()## IR.ISO
## low (nm) 780
## high (nm) 1e+06
## weighted none| constructor | std |
|---|---|
| ultraviolet | |
| UV() | ISO |
| UVC() | ISO, medical, none |
| UVB() | ISO, none |
| UVA() | ISO, CIE, none |
| UVA1() | CIE |
| UVA2() | CIE |
| visible | |
| VIS() | ISO |
| PAR() | McCree |
| Purple() | ISO |
| Blue() | ISO, Sellaro |
| Green() | ISO, Sellaro |
| Yellow() | ISO |
| Orange() | ISO |
| Red() | ISO, Smith10, Smith20, Inada, Warrington, Sellaro |
| Far_red() | Smith10, Smith20, Inada, Warrington, Sellaro, BTV, RedEdge20, RedEdge40 |
| infrared | |
| IR() | ISO, CIE |
| NIR() | ISO |
| MIR() | ISO |
| FIR() | ISO |
| IRA() | CIE |
| IRB() | CIE |
| IRC() | CIE |
| SWIR() |
Constructors of lists of waveband definitions frequently used together are also defined in the package.
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 noneUV_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 nonePlant_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| constructor | std |
|---|---|
| UV_bands() | ISO, CIE, medical, none |
| VIS_bands() | ISO |
| IR_bands() | ISO, CIE |
| Plants_bands() | sensory, sensory10, sensory20, ISO, CIE, none |
| constructor | std |
|---|---|
| Remote sensing | |
| VIS() | LandsatRBV, LandsatOLI, Landsat7, RS |
| Blue() | LandsatTM, LandsatETM, LandsatOLI |
| Green() | LandsatTM, LandsatETM, LandsatOLI, LandsatMSS, LandsatRBV |
| Red() | LandsatTM, LandsatETM, LandsatOLI, LandsatMSS, LandsatRBV |
| NIR() | LandsatTM, LandsatETM, LandsatOLI, LandsatMSS, LandsatRBV |
| SWIR1() | LandsatTM, LandsatETM, LandsatOLI |
| SWIR2() | LandsatTM, LandsatETM, LandsatOLI |
| TIR1() | LandsatTIRS |
| TIR2() | LandsatTM, LandsatETM, LandsatTIRS |
Additional constructors are provided for Landsat missions, for example the list of wavebands used in mission Landsat 1 can be created directly.
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| constructor | std |
|---|---|
| Landsat_bands() | L1, L2, L3, L4, L5, L6; L7, L8 |
| RBV_bands() | LandsatRBV, L1, L2 |
| MSS_bands() | LandsatMSS, L1, L2, L3, L4, L5 |
| OLI_bands() | LandsatOLI, L8 |
| TIRS_bands() | LandsatTIRS, L8 |
| ETM_bands() | LandsatETM, L4, L5 |
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- 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"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.
| constructor | parameters |
|---|---|
| ultraviolet | |
| GEN_G() | norm, w.low, w.high |
| GEN_T() | norm, w.low, w.high |
| GEN_M() | norm, w.low, w.high |
| PG() | norm, w.low, w.high |
| CIE() | norm, w.low, w.high |
| ICNIRP() | norm, w.low, w.high |
| DNA_N() | norm, w.low, w.high |
| DNA_GM() | norm, w.low, w.high |
| DNA_P() | norm, w.low, w.high |
| FLAV() | norm, w.low, w.high |
| CH4() | norm, w.low, w.high |
Both waveband definitions based on a wavelength range and SWFs are
stored in waveband objects, that can be created with
function .
The same functions used in the examples above for calculation of unweighted irradiances are used to calculate effective irradiances and effective exposures (sometimes called “doses”).
e_irrad(sun.spct, CIE())## E_]CIE98.298
## 0.08181583
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"| constructor | parameters |
|---|---|
| GEN_G_q_fun() | w.length |
| GEN_T_q_fun() | w.length |
| GEN_M_q_fun() | w.length |
| PG_q_fun() | w.length |
| CIE_e_fun() | w.length |
| CIE_q_fun() | w.length |
| ICNIRP_e_fun() | w.length |
| DNA_N_q_fun() | w.length |
| DNA_GM_q_fun() | w.length |
| DNA_P_q_fun() | w.length |
| FLAV_q_fun() | w.length |
| CH4_e_fun() | w.length |
| CH4_q_fun() | w.length |
The functions available for calculating action spectra take as argument a vector of wavelengths, and return a vector of effectiveness (either quantum/photon or energy based) depending on how the original source describes them. These functions are listed in the Table above, and an example of their use follows.
# at 1 nm intervals
wavelengths1 <- 285:400
action.spectrum1 <- CIE_e_fun(wavelengths1)All functions accept a wavelengths vector with variable and arbitrary step sizes, with the condition that the wavelengths are sorted in strictly increasing order.
These functions are used internally by the package, but are also used
for the calculation of effective spectral irradiances by multiplication
of a source_spct object by a waveband
object.
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
## # … with 112 more rows
## # ℹ Use `print(n = ...)` to see more rowsThe 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.
e_response(sun.spct * CIE2008_lef2deg.spct) * photopic_sensitivity *
interpolate_spct(CIE2008_lef2deg.spct, 555)$s.e.response## R[/e]_Total
## 53910.01
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"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"