I have developed a set of packages to facilitate the calculation of many different quantities that can be derived from spectral irradiance data. The core package in this suite is called ‘photobiology’, and is the package described here. Other specialized packages for quantification of ultraviolet radiation and visible radiation (‘photobiologyWavebands’), plant photoreceptors and other plant photobiology related calculations (‘photobiologyPlants’), example spectral data for filters (‘photobiologyFilters’), lamps (‘photobiologyLamps’), LEDs (‘photobiologyLEDs’), sunlight (‘photobiologySun’), light sensors (‘photobiologySensors’) and for exchange of data in foreign formats (‘photobiologyInOut’) are part of the suite. One additional package, (‘ggspectra’), implements facilities for plotting spectral data by extending package ‘ggplot2’, providing both ggplot statistics in addition to specializations of plot(). All packages that can comply with the repository rules have been submitted or will in coming months be submitted to CRAN (Comprehensive R archive network). The packages not yet in CRAN, and development versions of those already in CRAN, are available through a CRAN-like repository at https://www.r4photobiology.info/R/ while the Web site at https://www.r4photobiology.info provides news about the development of the suite and some additional information. Each package has its own public Git repository at my Bitbucket account (https://bitbucket.org/aphalo/) from where the source code of the current and previous versions can be cloned or forked.
Package ‘photobiology’ provides two sets of functions for many operations: low-level functions programmed following a functional paradigm, and higher-level functions using an object-oriented paradigm. The former functions take as arguments numeric vectors and are sometimes faster. The later ones take spectra objects as arguments, are easier to use, and at least at the moment, to some extent slower. For everyday use spectra objects are recommended, but when maximum performance or flexibility in scripts is desired, the use of the functions taking numeric vectors as arguments may allow optimizations that are not possible with the object-oriented functions. The differences in performance becomes relevant only in extreme cases such as processing in a single script tenths of thousands of spectra. In the vignettes we emphasize the use of the object-oriented classes and methods.
I have developed this package over several years, and even though I have tried to remain consistent, some inconsistencies have crept in. I have attempted to correct inconsistencies without breaking old code by providing synonyms for some functions.
In general I have used names in snake case for methods and functions, such as source_spct() and dot case for their arguments. There are two exceptions to this: the as. and is. methods which for consistency with base R, retain the dot: as.source_spct() and ìs.source_spct(). There are still some functions and methods whose names are in camel case: these are mostly accessors and setters of metadata attributes such as setWhatMeasured() and getWhatMeasured(), in which case synonyms what_measured<-() and what_measured() are now provided with a syntax that parallels that of R’s comment<-(), comment(), and similar methods for other attributes. Names of attributes themselves use dots, while classes use snake case as functions do, allowing consistency between class names and their constructor functions. There is an additional twist: functions named like clip_wl() act on the wavelengths (“wl”) modifying them, while those named like wl_range() report on the properties of the wavelengths.
In examples we use variable names ending in .spct for spectra, ending in .mspct for collections of spectra and ending in .tb for tibbles. In most cases the root of the variable names use snake case and may have a tag at the end separated with a dot. In the case of variable names used in examples I have been less strict about conventions than for the objects exported by the package.
None of these naming conventions are enforced for user defined objects and classes; these conventions are simply those I have tried to follow while developing this package as well as other packages in the r4photobiology suite.
Data for several spectra are included in this package for use in examples and vignettes, and in testing (Tables 1 and 2). Other packages in the ‘r4photobiology suite’ provide many additional data sets.
Table 1. Data sets included in the package: spectra. The CIE standard illuminant data in this package are normalized to one at \(\lambda = 560\,\)nm, while in the CIE standard they are normalized to 100 at the same wavelength. See documentation for each data object for details and data sources.
| Object | class | units | data description |
|---|---|---|---|
sun.spct |
source_spct |
\(W\,m^{-2}\,nm^{-1}\) | solar spectral irradiance |
sun.daily.spct |
source_spct |
\(J\,m^{-2}\,d^{-1}\,nm^{-1}\) | solar spectral exposure |
sun.data |
data.frame |
\(W\,m^{-2}\,nm^{-1}\) | solar spectral irradiance |
sun.daily.data |
data.frame |
\(J\,m^{-2}\,d^{-1}\,nm^{-1}\) | solar spectral exposure |
D65.illuminant.spct |
source_spct |
(norm. 560 nm) | CIE standard |
A.illuminant.spct |
source_spct |
(norm. 560 nm) | CIE standard |
clear.spct |
filter_spct |
fraction | ideal transparent filter |
opaque.spct |
filter_spct |
fraction | ideal opaque filter |
polyester.spct |
filter_spct |
fraction | plastic film |
yellow_gel.spct |
filter_spct |
fraction | theatrical gel filter |
green_leaf.spct |
reflector_spct |
fraction | a birch leaf |
clear_body.spct |
object_spct |
fraction | ideal transparent body |
black_body.spct |
object_spct |
fraction | ideal black body |
white_body.spct |
object_spct |
fraction | ideal white body |
Ler_leaf.spct |
object_spct |
fraction | Arabidopsis leaf |
Ler_leaf_trns.spct |
filter_spct |
fraction | Arabidopsis leaf (T total) |
Ler_leaf_trns_i.spct |
filter_spct |
fraction | Arabidopsis leaf (T internal) |
Ler_leaf_rflt.spct |
reflector_spct |
fraction | Arabidopsis leaf (R total) |
photodiode.spct |
response_spct |
\(A / W\) | typical Si photodiode |
ccd.spct |
response_spct |
\(A / W\) | typical CCD array |
white_led.raw_spct |
raw_spct |
counts | example raw detector counts data |
white_led.cps_spct |
cps_spct |
counts / s | example detector counts data |
white_led.source_spct |
source_spct |
\(W\,m^{-2}\,nm^{-1}\) | spectral irradiance |
filter_cps.mspct |
cps_mspct |
\(\mathrm{counts} / s\) | example detector counts data |
Table 2. Data sets included in the package: chromaticity data. See documentation for each data object for details and data sources.
| Object | class | data description |
|---|---|---|
ciexyzCC2.spct |
chroma_spct |
human chromaticity coordinates \(2^\circ\) |
ciexyzCC10.spct |
chroma_spct |
human chromaticity coordinates \(10^\circ\) |
ciexyzCMF2.spct |
chroma_spct |
human colour matching function \(2^\circ\) |
ciexyzCMF10.spct |
chroma_spct |
human colour matching function \(10^\circ\) |
ciev2.spct |
chroma_spct |
human luminous efficiency \(2^\circ\) |
beesxyzCMF.spct |
chroma_spct |
bee colour matching function |