R for Photobiology: Theory and recipes for common calculations

Table of contents :
Contents
List of Tables
List of Figures
Preface
Typographical conventions
Acknowledgements
Theory behind calculations
Radiation properties
Packages used in this chapter
Ultraviolet and visible radiation
Solar radiation
Artificial radiation
Radiation interactions
Radiation and molecules
Absorption
Fluorescence
Phosphorescence
Radiation and simple objects
Angle of incidence
Refraction
Difraction
Scatering
Radiation in tissues and cells
Radiation interactions in plant canopies
Radiation interactions in water bodies
Physical quantities
Specular and total reflectance
Internal and total transmittance
Absorbance and absorptance
Photochemistry and photobiology
Light driven reactions
Silver salts and photographic films
Bleaching by UV radiation
Chlorophyll
Plant photoreceptors
Animal photoreceptors
Action spectroscopy
Photoreception tuning
Algorithms
Integration
Area under a spectral curve
Discontinuous functions
Scaling
Normalization
Interpolation
Astronomy
Times to events
Position of the sun
Array-detector spectrometers
Measurements—problems and solutions
Data processing steps for irradiance
Tools used for calculations
Software
Introduction
The different pieces
R
RStudio
Revision control: Git and Subversion
C++ compiler
LaTeX
Markdown
R for Photobiology packages
Expected use and users
The design of the framework
The suite
The r4photobiology repository
Cookbook of calculations
Storing data
Packages used in this chapter
Introduction
Spectra
How are spectra stored?
Spectral data assumptions
Task: Create a spectral object from numeric vectors
Task: Create a spectral object from a data frame
Task: Convert a data frame into a spectral object
Task: trimming a spectrum
Task: interpolating a spectrum
Task: Row binding spectra
Task: Merging spectra
Collections of multiple spectra
Task: Constructing Scale = 0.89 0.05ptcolor push gray 0color pop_mspctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects from Scale = 0.89 0.05ptcolor push gray 0color pop_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: Retrieving Scale = 0.89 0.05ptcolor push gray 0color pop_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects from Scale = 0.89 0.05ptcolor push gray 0color pop_mspctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: Subsetting Scale = 0.89 0.05ptcolor push gray 0color pop_mspctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: Combining Scale = 0.89 0.05ptcolor push gray 0color pop_mspctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Internal-use functions
Wavebands
How are wavebands stored?
Task: Create waveband objects
Task: trimming wavebands
Arithmetic operators and mathematical functions
Packages used in this chapter
Introduction
Conversion between units of expression
Task: conversion of irradiance from energy to photon base
Task: conversion of responsivity from energy to photon base
Task: conversion irradiance from photon to energy base
Task: conversion of responsivity from photon to energy base
Task: conversion of transmittance into absorptance
Task: conversion of transmittance into absorbance
Task: conversion of absorptance into transmittance
Task: conversion of absorbance into transmittance
Arithmetic operators and mathematical functions for spectra
Operators and operations between a spectrum and a numeric vector
Math functions taking a spectrum as argument
Comparison operators
Task: Simulating spectral irradiance under a filter
Task: Uniform scaling of a spectrum
Task: Arithmetic operations within one spectrum
Task: Using operators on underlying vectors
Task: Using options to change default behaviour of maths operators and functions
Wavebands
Mathematical operators
Task: Compute weighted spectral quantities
Spectra: simple summaries and features
Packages used in this chapter
Task: Printing spectra
Task: Summaries related to object properties
Task: Integrating spectral data
Task: Averaging spectral data
Task: Summaries related to wavelength
Task: Finding the class of an object
Task: Querying other attributes
Task: Query how spectral data contained is expressed
Task: Querying about `origin' of data
Task: Plotting a spectrum
Task: Other R's methods
Task: Extract peaks and valleys
Task: finding the location of peaks as an index into vectors with spectral data
Task: Extracting peaks and valleys using vectors
Task: Refining the location of peaks and valleys
Bell-shaped function
Spline with a single node
Spline with three nodes
Wavebands: simple summaries and features
Packages used in this chapter
Task: Printing wavebands
Task: Summaries related to object properties
Task: Summaries related to wavelength
Task: Querying other properties
Task: R's methods
Task: Plotting a waveband
Irradiance (not weighted)
Packages used in this chapter
Introduction
Task: use simple predefined wavebands
Task: define simple wavebands
Task: define lists of simple wavebands
Task: (energy) irradiance from spectral irradiance
Task: photon irradiance from spectral irradiance
Task: irradiance for more than one waveband
Task: calculate fluence for an irradiation event
Task: photon ratios
Task: energy ratios
Task: calculate average number of photons per unit energy
Task: split energy irradiance into regions
Task: calculate overlap between spectra
Collections of spectra
Irradiance (weighted or effective)
Packages used in this chapter
Introduction
Task: specifying the normalization wavelength
Task: use of weighted wavebands
Task: define wavebands that use weighting functions
Task: calculate effective energy irradiance
Task: calculate effective photon irradiance
Task: calculate daily effective energy exposure
From spectral daily exposure
From spectral irradiance
Transmission and reflection
Packages used in this chapter
Introduction
Task: absorbance, absorptance and transmittance
Task: spectral absorbance from spectral transmittance
Task: spectral transmittance from spectral absorbance
Task: transmitted spectrum from spectral transmittance and spectral irradiance
Task: reflected spectrum from spectral reflectance and spectral irradiance
Task: total spectral transmittance from internal spectral transmittance and spectral reflectance
Task: combined spectral transmittance of two or more filters
Ignoring reflectance
Considering reflectance
Task: light scattering media (natural waters, plant and animal tissues)
Task: simulating the spectral irradiance under a LED luminaire
Astronomy
Packages used in this chapter
Introduction
Time coordinates
Geographic coordinates
Algorithm and peculiarities of time data
Task: calculating the length of the photoperiod
Task: Calculating times of sunrise, solar noon and sunset
Task: calculating the position of the sun
Task: plotting sun elevation through a day
Task: plotting day or night length through the year
Task: plotting local time at sunrise
Task: plotting solar time at sunrise
Colour
Packages used in this chapter
Introduction
Task: calculating an RGB colour from a single wavelength
Task: calculating an RGB colour for a range of wavelengths
Task: calculating an RGB colour for spectrum
Standard CIE illuminants
A sample of colours
Colour based indexes
Packages used in this chapter
What are colour-based indexes?
Task: Calculation of the value of a known index from spectral data
Task: Estimation of an optimal index for discrimination
Task: Fitting a simple optimal index for prediction of a continuous variable
Task: PCA or PCoA applied to spectral data
Task: Working with spectral images
Plotting spectra and colours
Packages used in this chapter
Set up
Introduction to plotting spectra
Using autoplot() methods with spectra
Task: plotting of Scale = 0.89 0.05ptcolor push gray 0color popsource_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: plotting of normalized Scale = 0.89 0.05ptcolor push gray 0color popsource_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: plotting of Scale = 0.89 0.05ptcolor push gray 0color popresponse_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: plotting of Scale = 0.89 0.05ptcolor push gray 0color popfilter_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: plotting of Scale = 0.89 0.05ptcolor push gray 0color popreflector_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: plotting of Scale = 0.89 0.05ptcolor push gray 0color popobject_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: plotting collections of spectra
Plotting spectra with ggplot
Task: plotting Scale = 0.89 0.05ptcolor push gray 0color popsource_spctcodeshadecolorcolor push gray 0color poptowidthheightdepth objects
Task: Saving axis-label definitions for re-use
Task: plotting a spectrum as discrete columns
Task: using a log scale
Task: compare energy and photon spectral units
Task: annotating peaks and valleys in spectra
Annotating wavebands and wavelengths
Task: annotate a plot with waveband names as labels
Task: annotate a plot with waveband summary values as labels
Using colour as data in plots
Task: Plots using colour for the spectral data
Task: Plots using waveband definitions
Plotting the result of operations on spectral data
Task: plotting effective spectral irradiance
Task: making a bar plot of effective irradiance
Task: plotting a spectrum using colour bars
Task: plotting colours in Maxwell's triangle
Human vision: RGB
Radiation physics
Packages used in this chapter
Introduction
Task: black body emission
Data acquisition and exchange
Importing and exporting `R' data
Packages used in this chapter
Base R
Task: Import one spectrum from a Scale = 0.89 0.05ptcolor push gray 0color popdata.framecodeshadecolorcolor push gray 0color poptowidthheightdepth
Task: Export one spectrum to a Scale = 0.89 0.05ptcolor push gray 0color popdata.framecodeshadecolorcolor push gray 0color poptowidthheightdepth
Task: Import one spectrum from a Scale = 0.89 0.05ptcolor push gray 0color popmatrixcodeshadecolorcolor push gray 0color poptowidthheightdepth
Task: Export one spectrum to Scale = 0.89 0.05ptcolor push gray 0color popmatrixcodeshadecolorcolor push gray 0color poptowidthheightdepth
Task: Import a collection of spectra from a Scale = 0.89 0.05ptcolor push gray 0color popmatrixcodeshadecolorcolor push gray 0color poptowidthheightdepth
Task: Export a collection of spectra to Scale = 0.89 0.05ptcolor push gray 0color popmatrixcodeshadecolorcolor push gray 0color poptowidthheightdepth
Package `hyperSpec'
To `hyperSpec'
From `hyperSpec'
Package `colorSpec'
From `colorSpec'
To `colorSpec'
Package `pavo'
From `pavo'
Packages `fda' and `fda.usc'
Importing and exporting `foreign' data
Introduction
Packages used in this chapter
Reading and writing common file formats
Task: Read and write spectra from text files
Task: Read a spectrum from an Excel workbook
Reading instrument-output files
Task: Import data from Ocean Optics instruments and software
Task: Import data from Avantes instruments and software
Task: Import data from Macam instruments and software
Task: Import data from LI-COR instruments and software
Task: Import data from Bentham instruments and software
Data acquisition from within R
Introduction
Packages and other software used in this chapter
Adcquiring spectra with Ocean Optics spectrometers
Task: Acquiring raw-counts data from Ocean Optics spectrometers
Task: Acquiring spectral irradiance with Ocean Optics spectrometers
Task: Acquiring spectral transmittance with Ocean Optics spectrometers
Task: Acquiring spectral reflectance with Ocean Optics spectrometers
Task: Acquiring spectral absorptance with Ocean Optics spectrometers
sglux spectrometers and sensors
Task: Acquiring spectral data with sglux instrument
YoctoPuce modules
Task: Acquiring data with YoctoPuce modules and servers
Calibration
Task: Calibration of broadband sensors
Task: Correcting for non-linearity of sensor response
Task: Applying a spectral calibration to raw spectral data
Task: Wavelength calibration and peak fitting
Simulation
Task: Running TUV in batch mode
Task: Importing into R simulated spectral data from TUV
Task: Running libRadtran in batch mode
Task: Importing into R simulated spectral data from libRadtran
Catalogue of example data
Radiation sources
Packages used in this chapter
Introduction
Data: extraterrestrial solar radiation spectra
Data: terrestrial solar radiation spectra
Data: radiation within plant canopies
Data: radiation in water bodies
Data: lamps
Data: LEDs
Optical properties of inanimate objects
Packages used in this chapter
Introduction
Data: spectral transmittance of filters, glass, plastic sheets and films
Data: spectral reflectance of materials and objects
Example data for organisms
Packages used in this chapter
Introduction
Plants
Data: Optical properties of organs
Data: Photoreceptors
Data: Photosynthesis
Data: Mass pigments and other metabolites
Animals, including humans
Data: Surface properties of organs
Data: Photoreceptors
Data: Light driven synthesis
Data: Damage
Data: Metabolites
Microbes
Data: Photoreceptors
Data: Light driven synthesis
Data: Damage
Data: Metabolites
Further reading
Radiation physics
Photochemistry
Photobiology
Using R
Programming in R
Bibliography
Appendix
Build information
Blank Page
Blank Page

Citation preview

R for Photobiology Theory and recipes for common calculations

Pedro J. Aphalo Andreas Albert, Matthew T. Robson, Titta K. Kotilainen

A handbook of theory and computations

R for Photobiology A handbook of theory and computations Pedro J. Aphalo T. Matthew Robson

Andreas Albert Titta K. Kotilainen

Helsinki, 16 April 2022

Available through Leanpub

© 2012–2022 by the authors Licensed under one of the Creative Commons licenses as indicated, or when not explicitly indicated, under the CC BY-SA 4.0 license.

Typeset with XƎLATEX in Lucida Bright and Lucida Sans using the KOMA-Script book class. The manuscript was written using R with package ‘knitr’. The manuscript was edited in WinEdt and RStudio. The source files for the whole book are available at https: //bitbucket.org/aphalo/r4photobiology.

Contents Preface 1 Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

I

Theory behind calculations

1 Radiation properties 1.1 Packages used in this chapter . . 1.2 Ultraviolet and visible radiation 1.3 Solar radiation . . . . . . . . . . . 1.4 Artificial radiation . . . . . . . . .

xix xxi xxii

1 . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

3 3 3 13 21

2 Radiation interactions 2.1 Radiation and molecules . . . . . . . . . . 2.1.1 Absorption . . . . . . . . . . . . . . 2.1.2 Fluorescence . . . . . . . . . . . . . 2.1.3 Phosphorescence . . . . . . . . . . 2.2 Radiation and simple objects . . . . . . . 2.2.1 Angle of incidence . . . . . . . . . . 2.2.2 Refraction . . . . . . . . . . . . . . . 2.2.3 Difraction . . . . . . . . . . . . . . . 2.2.4 Scatering . . . . . . . . . . . . . . . . 2.3 Radiation in tissues and cells . . . . . . . 2.4 Radiation interactions in plant canopies 2.5 Radiation interactions in water bodies . 2.6 Physical quantities . . . . . . . . . . . . . . 2.6.1 Specular and total reflectance . . . 2.6.2 Internal and total transmittance . 2.6.3 Absorbance and absorptance . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

27 27 27 27 27 27 27 27 27 27 27 27 28 28 28 28 28

3 Photochemistry and photobiology 3.1 Light driven reactions . . . . . . . . . 3.2 Silver salts and photographic films 3.3 Bleaching by UV radiation . . . . . . 3.4 Chlorophyll . . . . . . . . . . . . . . . 3.5 Plant photoreceptors . . . . . . . . . 3.6 Animal photoreceptors . . . . . . . . 3.7 Action spectroscopy . . . . . . . . . . 3.8 Photoreception tuning . . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

29 29 29 29 29 29 29 29 29

. . . . . . . .

. . . . . . . .

. . . . . . . .

v

Contents 4 Algorithms 4.1 Integration . . . . . . . . . . . . . . . . . . . . . . . 4.1.1 Area under a spectral curve . . . . . . . . 4.2 Discontinuous functions . . . . . . . . . . . . . . 4.3 Scaling . . . . . . . . . . . . . . . . . . . . . . . . . 4.4 Normalization . . . . . . . . . . . . . . . . . . . . 4.5 Interpolation . . . . . . . . . . . . . . . . . . . . . 4.6 Astronomy . . . . . . . . . . . . . . . . . . . . . . 4.6.1 Times to events . . . . . . . . . . . . . . . 4.6.2 Position of the sun . . . . . . . . . . . . . 4.7 Array-detector spectrometers . . . . . . . . . . . 4.7.1 Measurements—problems and solutions 4.7.2 Data processing steps for irradiance . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

II Tools used for calculations 5 Software 5.1 Introduction . . . . . . . 5.2 The different pieces . . 5.2.1 R . . . . . . . . . 5.2.2 RStudio . . . . . 5.2.3 Revision control: 5.2.4 C++ compiler . 5.2.5 LATEX . . . . . . . . 5.2.6 Markdown . . . .

41

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Git and Subversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6 R for Photobiology packages 6.1 Expected use and users . . . . . 6.2 The design of the framework . 6.3 The suite . . . . . . . . . . . . . . 6.4 The r4photobiology repository

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

. . . .

. . . . . . . .

43 43 43 43 44 45 45 45 46

. . . .

47 47 47 51 52

III Cookbook of calculations 7 Storing data 7.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . 7.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3 Spectra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3.1 How are spectra stored? . . . . . . . . . . . . . . . . . . 7.3.2 Spectral data assumptions . . . . . . . . . . . . . . . . . 7.3.3 Task: Create a spectral object from numeric vectors 7.3.4 Task: Create a spectral object from a data frame . . . 7.3.5 Task: Convert a data frame into a spectral object . . 7.3.6 Task: trimming a spectrum . . . . . . . . . . . . . . . .

vi

31 31 31 33 34 34 35 35 36 36 36 37 39

55 . . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

57 57 57 57 57 58 60 62 63 64

Contents 7.3.7 Task: interpolating a spectrum . . . . . . . . . . . . . . . 7.3.8 Task: Row binding spectra . . . . . . . . . . . . . . . . . 7.3.9 Task: Merging spectra . . . . . . . . . . . . . . . . . . . . 7.4 Collections of multiple spectra . . . . . . . . . . . . . . . . . . . 7.4.1 Task: Constructing _mspct objects from _spct objects 7.4.2 Task: Retrieving _spct objects from _mspct objects . . 7.4.3 Task: Subsetting _mspct objects . . . . . . . . . . . . . . 7.4.4 Task: Combining _mspct objects . . . . . . . . . . . . . . 7.5 Internal-use functions . . . . . . . . . . . . . . . . . . . . . . . . . 7.6 Wavebands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.6.1 How are wavebands stored? . . . . . . . . . . . . . . . . . 7.6.2 Task: Create waveband objects . . . . . . . . . . . . . . . 7.6.3 Task: trimming wavebands . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

66 67 70 70 70 72 72 75 75 75 75 75 77

8 Arithmetic operators and mathematical functions 81 8.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 81 8.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 8.3 Conversion between units of expression . . . . . . . . . . . . . . . . . . . 82 8.3.1 Task: conversion of irradiance from energy to photon base . . . 82 8.3.2 Task: conversion of responsivity from energy to photon base . . 84 8.3.3 Task: conversion irradiance from photon to energy base . . . . . 85 8.3.4 Task: conversion of responsivity from photon to energy base . . 86 8.3.5 Task: conversion of transmittance into absorptance . . . . . . . 87 8.3.6 Task: conversion of transmittance into absorbance . . . . . . . . 88 8.3.7 Task: conversion of absorptance into transmittance . . . . . . . 88 8.3.8 Task: conversion of absorbance into transmittance . . . . . . . . 88 8.4 Arithmetic operators and mathematical functions for spectra . . . . . . 89 8.5 Operators and operations between a spectrum and a numeric vector . 93 8.6 Math functions taking a spectrum as argument . . . . . . . . . . . . . . . 95 8.7 Comparison operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 8.8 Task: Simulating spectral irradiance under a filter . . . . . . . . . . . . . 95 8.9 Task: Uniform scaling of a spectrum . . . . . . . . . . . . . . . . . . . . . 97 8.9.1 Task: Arithmetic operations within one spectrum . . . . . . . . . 97 8.9.2 Task: Using operators on underlying vectors . . . . . . . . . . . . 98 8.9.3 Task: Using options to change default behaviour of maths operators and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 8.10 Wavebands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 8.10.1 Mathematical operators . . . . . . . . . . . . . . . . . . . . . . . . . 104 8.10.2 Task: Compute weighted spectral quantities . . . . . . . . . . . . 104 9 Spectra: simple summaries and features 9.1 Packages used in this chapter . . . . . . . . . . 9.2 Task: Printing spectra . . . . . . . . . . . . . . . 9.3 Task: Summaries related to object properties 9.4 Task: Integrating spectral data . . . . . . . . . 9.5 Task: Averaging spectral data . . . . . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

107 107 107 107 108 108

vii

Contents 9.6 Task: Summaries related to wavelength . . . . . . . . . . . . . . . . . . . 9.7 Task: Finding the class of an object . . . . . . . . . . . . . . . . . . . . . . 9.8 Task: Querying other attributes . . . . . . . . . . . . . . . . . . . . . . . . 9.9 Task: Query how spectral data contained is expressed . . . . . . . . . . 9.10 Task: Querying about ‘origin’ of data . . . . . . . . . . . . . . . . . . . . . 9.11 Task: Plotting a spectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.12 Task: Other R’s methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.13 Task: Extract peaks and valleys . . . . . . . . . . . . . . . . . . . . . . . . . 9.13.1 Task: finding the location of peaks as an index into vectors with spectral data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.13.2 Task: Extracting peaks and valleys using vectors . . . . . . . . . . 9.14 Task: Refining the location of peaks and valleys . . . . . . . . . . . . . . 9.14.1 Bell-shaped function . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.14.2 Spline with a single node . . . . . . . . . . . . . . . . . . . . . . . . . 9.14.3 Spline with three nodes . . . . . . . . . . . . . . . . . . . . . . . . . 10 Wavebands: simple summaries and features 10.1 Packages used in this chapter . . . . . . . . . . 10.2 Task: Printing wavebands . . . . . . . . . . . . 10.3 Task: Summaries related to object properties 10.4 Task: Summaries related to wavelength . . . 10.5 Task: Querying other properties . . . . . . . . 10.6 Task: R’s methods . . . . . . . . . . . . . . . . . 10.7 Task: Plotting a waveband . . . . . . . . . . . .

109 109 110 111 113 113 114 114 118 118 119 119 120 121

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

123 123 123 125 126 126 127 127

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . energy . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

. . . . . . . . . . . . . . .

129 129 129 129 132 133 137 139 140 142 143 144 145 146 149 149

12 Irradiance (weighted or effective) 12.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 12.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.3 Task: specifying the normalization wavelength . . . . . . . . . . . . . . .

151 151 151 152

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

11 Irradiance (not weighted) 11.1 Packages used in this chapter . . . . . . . . . . . . . . 11.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 11.3 Task: use simple predefined wavebands . . . . . . . 11.4 Task: define simple wavebands . . . . . . . . . . . . . 11.5 Task: define lists of simple wavebands . . . . . . . . 11.6 Task: (energy) irradiance from spectral irradiance . 11.7 Task: photon irradiance from spectral irradiance . 11.8 Task: irradiance for more than one waveband . . . . 11.9 Task: calculate fluence for an irradiation event . . . 11.10Task: photon ratios . . . . . . . . . . . . . . . . . . . . 11.11Task: energy ratios . . . . . . . . . . . . . . . . . . . . 11.12Task: calculate average number of photons per unit 11.13Task: split energy irradiance into regions . . . . . . 11.14Task: calculate overlap between spectra . . . . . . . 11.15Collections of spectra . . . . . . . . . . . . . . . . . . .

viii

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

Contents 12.4 Task: use of weighted wavebands . . . . . . . . . . . . 12.5 Task: define wavebands that use weighting functions 12.6 Task: calculate effective energy irradiance . . . . . . . 12.7 Task: calculate effective photon irradiance . . . . . . . 12.8 Task: calculate daily effective energy exposure . . . . 12.8.1 From spectral daily exposure . . . . . . . . . . . 12.8.2 From spectral irradiance . . . . . . . . . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

152 153 154 155 155 155 156

13 Transmission and reflection 13.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.3 Task: absorbance, absorptance and transmittance . . . . . . . . . . . . . 13.4 Task: spectral absorbance from spectral transmittance . . . . . . . . . . 13.5 Task: spectral transmittance from spectral absorbance . . . . . . . . . . 13.6 Task: transmitted spectrum from spectral transmittance and spectral irradiance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.7 Task: reflected spectrum from spectral reflectance and spectral irradiance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.8 Task: total spectral transmittance from internal spectral transmittance and spectral reflectance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.9 Task: combined spectral transmittance of two or more filters . . . . . . 13.9.1 Ignoring reflectance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.9.2 Considering reflectance . . . . . . . . . . . . . . . . . . . . . . . . . 13.10Task: light scattering media (natural waters, plant and animal tissues) 13.11Task: simulating the spectral irradiance under a LED luminaire . . . . .

157 157 157 157 159 160

14 Astronomy 14.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . 14.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.2.1 Time coordinates . . . . . . . . . . . . . . . . . . . . . 14.2.2 Geographic coordinates . . . . . . . . . . . . . . . . . 14.2.3 Algorithm and peculiarities of time data . . . . . . . 14.3 Task: calculating the length of the photoperiod . . . . . . 14.4 Task: Calculating times of sunrise, solar noon and sunset 14.5 Task: calculating the position of the sun . . . . . . . . . . . 14.6 Task: plotting sun elevation through a day . . . . . . . . . 14.7 Task: plotting day or night length through the year . . . . 14.8 Task: plotting local time at sunrise . . . . . . . . . . . . . . 14.9 Task: plotting solar time at sunrise . . . . . . . . . . . . . .

161 162 163 163 163 163 163 163

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

165 165 165 165 167 168 169 171 175 176 177 179 179

15 Colour 15.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . 15.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.3 Task: calculating an RGB colour from a single wavelength . 15.4 Task: calculating an RGB colour for a range of wavelengths 15.5 Task: calculating an RGB colour for spectrum . . . . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

181 181 181 182 182 183

ix

Contents 15.6 Standard CIE illuminants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.7 A sample of colours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

183 186

16 Colour based indexes 16.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2 What are colour-based indexes? . . . . . . . . . . . . . . . . . . . . . . . . 16.3 Task: Calculation of the value of a known index from spectral data . . 16.4 Task: Estimation of an optimal index for discrimination . . . . . . . . . 16.5 Task: Fitting a simple optimal index for prediction of a continuous variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.6 Task: PCA or PCoA applied to spectral data . . . . . . . . . . . . . . . . . 16.7 Task: Working with spectral images . . . . . . . . . . . . . . . . . . . . . .

189 189 189 189 190

17 Plotting spectra and colours 17.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 17.2 Set up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3 Introduction to plotting spectra . . . . . . . . . . . . . . . . . . . . . . . . 17.4 Using autoplot() methods with spectra . . . . . . . . . . . . . . . . . . . 17.4.1 Task: plotting of source_spct objects . . . . . . . . . . . . . . . . . 17.4.2 Task: plotting of normalized source_spct objects . . . . . . . . . 17.4.3 Task: plotting of response_spct objects . . . . . . . . . . . . . . . 17.4.4 Task: plotting of filter_spct objects . . . . . . . . . . . . . . . . . 17.4.5 Task: plotting of reflector_spct objects . . . . . . . . . . . . . . 17.4.6 Task: plotting of object_spct objects . . . . . . . . . . . . . . . . . 17.4.7 Task: plotting collections of spectra . . . . . . . . . . . . . . . . . 17.5 Plotting spectra with ggplot . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.5.1 Task: plotting source_spct objects . . . . . . . . . . . . . . . . . . 17.5.2 Task: Saving axis-label definitions for re-use . . . . . . . . . . . . 17.5.3 Task: plotting a spectrum as discrete columns . . . . . . . . . . . 17.5.4 Task: using a log scale . . . . . . . . . . . . . . . . . . . . . . . . . . 17.5.5 Task: compare energy and photon spectral units . . . . . . . . . 17.5.6 Task: annotating peaks and valleys in spectra . . . . . . . . . . . 17.6 Annotating wavebands and wavelengths . . . . . . . . . . . . . . . . . . . 17.6.1 Task: annotate a plot with waveband names as labels . . . . . . . 17.6.2 Task: annotate a plot with waveband summary values as labels 17.7 Using colour as data in plots . . . . . . . . . . . . . . . . . . . . . . . . . . 17.7.1 Task: Plots using colour for the spectral data . . . . . . . . . . . . 17.7.2 Task: Plots using waveband definitions . . . . . . . . . . . . . . . . 17.8 Plotting the result of operations on spectral data . . . . . . . . . . . . . . 17.8.1 Task: plotting effective spectral irradiance . . . . . . . . . . . . . 17.8.2 Task: making a bar plot of effective irradiance . . . . . . . . . . . 17.8.3 Task: plotting a spectrum using colour bars . . . . . . . . . . . . 17.9 Task: plotting colours in Maxwell’s triangle . . . . . . . . . . . . . . . . . 17.9.1 Human vision: RGB . . . . . . . . . . . . . . . . . . . . . . . . . . . .

191 191 191 191 192 192 200 202 204 207 208 212 214 214 216 217 219 220 222 229 229 234 246 246 259 275 275 276 278 279 279

x

190 190 190

Contents 18 Radiation physics 18.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.3 Task: black body emission . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IV Data acquisition and exchange 19 Importing and exporting ‘R’ data 19.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . 19.2 Base R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.2.1 Task: Import one spectrum from a data.frame . . . 19.2.2 Task: Export one spectrum to a data.frame . . . . . 19.2.3 Task: Import one spectrum from a matrix . . . . . . 19.2.4 Task: Export one spectrum to matrix . . . . . . . . . 19.2.5 Task: Import a collection of spectra from a matrix 19.2.6 Task: Export a collection of spectra to matrix . . . . 19.3 Package ‘hyperSpec’ . . . . . . . . . . . . . . . . . . . . . . . . 19.3.1 To ‘hyperSpec’ . . . . . . . . . . . . . . . . . . . . . . . 19.3.2 From ‘hyperSpec’ . . . . . . . . . . . . . . . . . . . . . 19.4 Package ‘colorSpec’ . . . . . . . . . . . . . . . . . . . . . . . . 19.4.1 From ‘colorSpec’ . . . . . . . . . . . . . . . . . . . . . . 19.4.2 To ‘colorSpec’ . . . . . . . . . . . . . . . . . . . . . . . 19.5 Package ‘pavo’ . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.5.1 From ‘pavo’ . . . . . . . . . . . . . . . . . . . . . . . . . 19.6 Packages ‘fda’ and ‘fda.usc’ . . . . . . . . . . . . . . . . . . .

281 281 281 281

285 . . . . . . . . . . . . . . . . .

287 287 287 287 288 288 290 290 292 292 292 293 295 295 298 299 299 304

20 Importing and exporting ‘foreign’ data 20.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.2 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 20.3 Reading and writing common file formats . . . . . . . . . . . . . . . . . . 20.3.1 Task: Read and write spectra from text files . . . . . . . . . . . . . 20.3.2 Task: Read a spectrum from an Excel workbook . . . . . . . . . . 20.4 Reading instrument-output files . . . . . . . . . . . . . . . . . . . . . . . . 20.4.1 Task: Import data from Ocean Optics instruments and software 20.4.2 Task: Import data from Avantes instruments and software . . . 20.4.3 Task: Import data from Macam instruments and software . . . . 20.4.4 Task: Import data from LI-COR instruments and software . . . . 20.4.5 Task: Import data from Bentham instruments and software . . .

309 309 309 309 309 310 312 312 315 315 317 318

21 Data acquisition from within R 21.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2 Packages and other software used in this chapter . . . . . . . . . . . . . 21.3 Adcquiring spectra with Ocean Optics spectrometers . . . . . . . . . . . 21.3.1 Task: Acquiring raw-counts data from Ocean Optics spectrometers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

319 319 319 319

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

319

xi

Contents 21.3.2 Task: Acquiring spectral irradiance with Ocean Optics spectrometers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.3 Task: Acquiring spectral transmittance with Ocean Optics spectrometers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.4 Task: Acquiring spectral reflectance with Ocean Optics spectrometers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3.5 Task: Acquiring spectral absorptance with Ocean Optics spectrometers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.4 sglux spectrometers and sensors . . . . . . . . . . . . . . . . . . . . . . . . 21.4.1 Task: Acquiring spectral data with sglux instrument . . . . . . . 21.5 YoctoPuce modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.5.1 Task: Acquiring data with YoctoPuce modules and servers . . . 22 Calibration 22.1 Task: Calibration of broadband sensors . . . . . . . . . . . 22.2 Task: Correcting for non-linearity of sensor response . . . 22.3 Task: Applying a spectral calibration to raw spectral data 22.4 Task: Wavelength calibration and peak fitting . . . . . . . . 23 Simulation 23.1 Task: Running TUV in batch mode . . . . . . . . 23.2 Task: Importing into R simulated spectral data 23.3 Task: Running libRadtran in batch mode . . . . 23.4 Task: Importing into R simulated spectral data

321 321 321 321 321 321 321

. . . .

. . . .

. . . .

. . . .

. . . .

323 323 323 323 323

. . . . . . . . . . . from TUV . . . . . . . . . . . . . . . from libRadtran

. . . .

. . . .

. . . .

. . . .

325 325 325 325 325

. . . .

. . . .

. . . .

V Catalogue of example data 24 Radiation sources 24.1 Packages used in this chapter . . . . . . . . . . 24.2 Introduction . . . . . . . . . . . . . . . . . . . . . 24.3 Data: extraterrestrial solar radiation spectra 24.4 Data: terrestrial solar radiation spectra . . . . 24.5 Data: radiation within plant canopies . . . . . 24.6 Data: radiation in water bodies . . . . . . . . . 24.7 Data: lamps . . . . . . . . . . . . . . . . . . . . . 24.8 Data: LEDs . . . . . . . . . . . . . . . . . . . . . .

321

327 . . . . . . . .

. . . . . . . .

329 329 329 329 329 331 333 333 334

. . . . . . . . . . . . . . . . . . . . . . sheets and films . . . . . . . . . . .

. . . .

337 337 337 337 343

26 Example data for organisms 26.1 Packages used in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . 26.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

345 345 345

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

25 Optical properties of inanimate objects 25.1 Packages used in this chapter . . . . . . . . . . . . . . 25.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 25.3 Data: spectral transmittance of filters, glass, plastic 25.4 Data: spectral reflectance of materials and objects .

xii

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

Contents 26.3 Plants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26.3.1 Data: Optical properties of organs . . . . . . 26.3.2 Data: Photoreceptors . . . . . . . . . . . . . . 26.3.3 Data: Photosynthesis . . . . . . . . . . . . . . 26.3.4 Data: Mass pigments and other metabolites 26.4 Animals, including humans . . . . . . . . . . . . . . 26.4.1 Data: Surface properties of organs . . . . . 26.4.2 Data: Photoreceptors . . . . . . . . . . . . . . 26.4.3 Data: Light driven synthesis . . . . . . . . . . 26.4.4 Data: Damage . . . . . . . . . . . . . . . . . . 26.4.5 Data: Metabolites . . . . . . . . . . . . . . . . 26.5 Microbes . . . . . . . . . . . . . . . . . . . . . . . . . . 26.5.1 Data: Photoreceptors . . . . . . . . . . . . . . 26.5.2 Data: Light driven synthesis . . . . . . . . . . 26.5.3 Data: Damage . . . . . . . . . . . . . . . . . . 26.5.4 Data: Metabolites . . . . . . . . . . . . . . . . 27 Further reading 27.1 Radiation physics 27.2 Photochemistry . . 27.3 Photobiology . . . 27.4 Using R . . . . . . . 27.5 Programming in R Bibliography

VI Appendix A Build information

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

345 345 345 346 346 346 346 346 346 346 346 346 346 346 346 346

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

347 347 347 347 347 347 349

359 361

xiii

List of Tables 1.1 1.2 1.3 1.4 1.5 1.6

Regions of the electromagnetic radiation spectrum . . . . . . . . Physical quantities of light. . . . . . . . . . . . . . . . . . . . . . . . Photometric quantities of light. . . . . . . . . . . . . . . . . . . . . Photon quantities of light. . . . . . . . . . . . . . . . . . . . . . . . . Conversion factors of photon and energy quantities . . . . . . . Partition of the solar constant in different wavelength intervals

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

5 8 11 11 12 16

6.1

Packages in the suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

52

7.1 7.2

Classes for spectral data and mandatory variable and attribute names . . Variables for spectral data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

58 59

8.1 8.2

Binary operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

90 100

17.1 Spectral features-extraction ggplot statistics defined in package ‘ggspectra’ 222 17.2 Summary ggplot statistics defined in package ‘ggspectra’ . . . . . . . . . . 230

xv

List of Figures 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 1.10 1.11 1.12 1.13 1.14 1.15 1.16 1.17

Definition of the solid angles and areas in space . . . . Path of the radiance in a thin layer . . . . . . . . . . . . Relative spectral intensity of human colour sensation Solar position . . . . . . . . . . . . . . . . . . . . . . . . . Extraterrestrial solar spectrum . . . . . . . . . . . . . . . Ground level solar spectrum . . . . . . . . . . . . . . . . Diffuse component in solar UV . . . . . . . . . . . . . . . The solar spectrum through half a day . . . . . . . . . . The solar UV spectrum at noon . . . . . . . . . . . . . . The solar UV spectrum through half a day . . . . . . . Latitudinal variation in UV-B radiation . . . . . . . . . . Spectrum of incandescent lamp . . . . . . . . . . . . . . Spectrum of germicidal lamp . . . . . . . . . . . . . . . . Spectrum of a ‘daylight’ fluorescent tube . . . . . . . . Spectrum of blue LED array . . . . . . . . . . . . . . . . . Spectrum of ‘neutral white’ LED . . . . . . . . . . . . . . Photograph of a LED array . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

6 7 10 13 15 17 18 19 19 20 21 22 23 24 24 25 25

4.1 4.2 4.3 4.4 4.5

The integral . . . . . . . . . . . . Integration as a sum . . . . . . . Trapezium rule . . . . . . . . . . Scaling to equal PAR irradiance Normalization at peak . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

32 33 33 35 36

6.1 6.2

Spectral data pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object classes used to store spectral data . . . . . . . . . . . . . . . . . . . .

48 50

20.1 20.2 20.3 20.4 20.5

Excel worksheet with spectral data Top of text file spectrum.SSirrad . Top of text file spectrum.JazIrrad Top of text file spectrum.DTA . . . . Top of text file spectrum.PRN . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

311 313 314 316 317

xvii

Preface Status as of 2016-12-26. We have updated the manuscript to track changes to package ‘ggspectra’. This required/made possible some changes to the code in Chapter 17. In addition changes in recent versions of ‘ggtern’ allowed to easily improve one of the colour plotting examples. Although ‘photobiology’ has also been updated after the last “printing” the changes introduced did not require any changes to the code examples in this handbook. The book has been built today using current versions of all packages.

Status as of 2016-10-28. We have updated the manuscript to track package updates since the previous version uploaded nearly three months ago, and added examples of the new functionality added to packages ‘ggspectra’, ‘ggrepel’, and ‘ggplot2’. Now seven of the packages in the suite are in CRAN. Package ‘photobiology’ has gone through a major update of the astronomy-related functions. The user interface has changed a little. The values returned are slightly different as a different algorithm has been implemented. Package ‘photobiologyInOut’ has been expanded in its scope. Bugs have been fixed, but most of them only affected borderline cases. Some errors in the text of the manuscript have been corrected. During the last couple of months more time was spent in trying to get all the packages in the suite ready for submission to CRAN than on expanding and revising the text of this book. However, quite many of the code examples in the book have been simplified or updated to make use of all the improvements to the packages. Many new plotting examples were added.

Status as of 2018-03-09. We have updated the manuscript to track package updates since the previous version. Now ten of the packages in the suite are in CRAN. Package ‘photobiology’ has gone through a second major update of the astronomy-related functions using much more efficient and precise algorithms. Most summary methods previously available only for individual spectra have been implemented for collections of spectra removing the need for loops in user scripts. The data-only packages have been revised in their organization and many new data sets added. The documentation has been revised and some bugs corrected with nearly four thousand test cases written to ensure the reliability of the code and facilitate future revisions. The code for handling of metadata attributes has been reorganized and additional metadata is now stored and displayed. A new class “calibration_spct” was added. Chapter Arithmetic operators and mathematical functions has been thoroughly updated to describe all the operators and functions currently available in the suite. The

xix

Preface

text of other chapters has been in places revised, but some of the chapters do not yet describe all the functionality currently available in the suite. All code examples in the book have been checked against current versions of the packages. Only a few changes were necessary, mostly in relation to the re-naming of data objects in the data-only packages of the suite. In the last year most of the effort has gone into getting all the packages ready for submission to CRAN, with the expectation that once released no significant codebreaking changes to the interface will be necessary. A stable interface is crucial for the long-term usefulness of the book once formally published. Also the package vignettes and documentation have been improved. The R for Photobiology web site now contains the documentation for all packages in HTML format. The packages and to some extent this book manuscript are gradually becoming more popular. The current update will hopefully help those exploring the use of the suite of packages.

Status as of 2018-10-09. I have continued revising the packages but with codebreaking changes only related to the names of some of the values computed in the ggplot statistics. A few examples were affected by these changes and have been revised.

Status as of 2020-05-18. I have continued revising the packages but with very few code-breaking changes. A change in package ‘tibble’ made necessary changes in two lines of example code.

Status as of 2021-04-08. I have continued revising the packages but with very few code-breaking changes. The data previously included in package ‘photobiologyReflectors’ are now in package ‘photobiologyFilters’. The updates to the packages have to some extent modified the results of computations, such columns names or how plots looks. Most of these changes are small. On the other hand, the updates have added functionality that either makes coding some operations simpler, or allow some new computations. These improvements are not yet reflected in the code examples in the book.

Status as of 2022-04-15. I have continued revising the packages with no codebreaking changes except for the naming conventions used for spectra in packages ‘photobiologyLamps’ and ‘photobiologyLEDs’. The updates to the packages have slightly altered the labelling of plots. The updates have also added functionality that makes coding some operations and creating plots simpler. These improvements are not yet fully reflected in the code examples in the book. All code examples have been

xx

1 Typographical conventions

tested and in a few cases edited to account for code-breaking changes. The text in the book remains to an extent behind the vignettes in the packages themselves. I hope to correct this during this Summer. This handbook describes how to use R as a tool for doing calculations related to research in photobiology and other related fields. Photobiology is the branch of science that studies the interactions of living organisms with visible and ultraviolet radiation. Many of the most frequently used calculations are either related to the characterization of radiation and of the responses of organisms to radiation. We use a broad definition of photobiology that includes the light environment of organisms and its description as well as characterization and design of treatment conditions. We briefly touch on atmospheric radiation physics and optics. We emphasize the spectral characterization of visible and ultraviolet radiation in relation to photobiology but many of the principles and tools are relevant to spectral measurements in other disciplines like chemistry, biochemistry, meteorology and remote sensing. Astronomical calculations for the sun have been also implemented. The R-code examples in this handbook make frequent use of the ‘r4photobiology’ suite of R packages, developed by the author. Other packages are also described: XXX. The basic theory needed to understand the purpose and use of the different calculations is presented in Part I (p. 3 ss.). This first part is simple and concise, and full understanding of the subject matter will require previous experience or further reading (e.g. Aphalo, Albert, Björn, Ylianttila et al. 2012; Björn 2015). R packages and data analysis work flows are described in Part II (p. 43 ss.). Specific computations are described together with R-code examples in Part III (p. 57 ss.). Part IV (p. 287 ss.) includes chapters dedicated to reading and writing data in foreign formats, including direct acquisition from spectrometer and other measuring instruments. Part V (p. 329 ss.) gives a brief overview of the data sets available in R packages and in on-line repositories. Although this handbook includes many different recipes, it is not comprehensive in covering all the functionality of the packages. The packages themselves include User Guides and help pages describing their functionality in detail. The documentation is available as a web site at https://docs.r4photobiology.info and updates are announced in the blog at https://www.r4photobiology.info. A series of articles describing specific aspects of the use of the suite is being published in the UV4Plants Bulletin. This handbook assumes that readers are already familiar with the R language and in Part I that they are familiar with Physics and Mathematics, including basic calculus and geometry.

1 Typographical conventions Code examples are typeset in monospaced font and syntax highlighted in colour. References to R language elements—i.e. R ‘code’—in the main text are also in a monospaced

xxi

Preface

 

font but in black on a faint background. Package names are typeset between single quotes in a ‘sans serif’ font. We use the icon exemplified in the page margin next to this paragraph to highlight contents that require special attention because they are frequent causes of errors and problems. We use the icon exemplified in the page margin next to this paragraph to highlight contents that is advanced and will require the reader to linger on it to get a deep understanding—and which can, alternatively, be skipped on first reading by those readers which want a faster path to learning to do simpler calculations.

2 Acknowledgements We thank Stefano Catola, Paula Salonen, David Israel, Neha Rai, Tendry Randriamanana, Saara Hartikainen, Christian Bianchi-Strømme, Fang Wang and …for very useful comments and suggestions on the draft manuscript and examples used in training schools. The friendly and generous R community also deserves a big ‘Thank you!’. Helsinki, April 2022. The authors.

xxii

Part I Theory behind calculations

1

Chapter 1 Radiation properties 1.1 Packages used in this chapter For executing the examples listed in this chapter you need first to load the following packages from the library: library(photobiology) library(ggplot2) library(ggspectra) library(photobiologyWavebands) library(photobiologySun) library(photobiologyLamps) library(photobiologyLEDs)

1.2 Ultraviolet and visible radiation From the viewpoint of Physics, ultraviolet (UV) and visible (VIS) radiation are both considered electromagnetic waves and are described by Maxwell’s equations.1 The wavelength ranges of UV and visible radiation and their usual names are listed in Table 1.1. The long wavelengths of solar radiation, called infrared (IR) radiation, are also listed. The colour ranges indicated in Table 1.1 are an approximation as different individual human observers will not perceive colours exactly in the same way. We follow the ISO definitions for wavelength boundaries for colours (ISO 2007). Other finer-grained colour name series are also in use (e.g. Aphalo, Albert, Björn, Ylianttila et al. 2012, Table xx)). The electromagnetic spectrum is continuous with no clear boundaries between one colour and the next, the colours could be thought as artifacts produced by our sensory system, and are meaningful only from the perspective of an average human observer. Especially in the IR region the subdivision is somewhat arbitrary and the boundaries used in the literature vary. Radiation can also be thought of as composed of quantum particles or photons. The energy of a quantum of radiation in a vacuum, 𝑞, depends on the wavelength, 𝜆, or frequency2 , 𝜈, 𝑐 𝑞 =ℎ⋅𝜈=ℎ⋅ (1.1) 𝜆 with the Planck constant ℎ = 6.626 × 10−34 J s and speed of light in vacuum 𝑐 = 2.998 × 108 m s−1 . When dealing with numbers of photons, the equation (1.1) can be 1 2

These equations are a system of four partial differential equations describing classical electromagnetism. Wavelength and frequency are related to each other by the speed of light, according to 𝜈 = 𝑐/𝜆 where 𝑐 is speed of light in vacuum. Consequently there are two equivalent formulations for equation 1.1.

3

Chapter 1 Radiation properties extended by using Avogadro’s number 𝑁A = 6.022 × 1023 mol−1 . Thus, the energy of one mole of photons, 𝑞′ , is 𝑐 (1.2) 𝑞′ = ℎ′ ⋅ 𝜈 = ℎ′ ⋅ 𝜆 with ℎ′ = ℎ ⋅ 𝑁A = 3.990 × 10−10 J s mol−1 . Example 1: red light at 600 nm has about 200 kJ mol−1 , therefore, 1 μmol photons has 0.2 J. Example 2: UV-B radiation at 300 nm has about 400 kJ mol−1 , therefore, 1 μmol photons has 0.4 J. Equations 1.1 and 1.2 are valid for all kinds of electromagnetic waves (see Sections 8.3.1 and 8.3.3 for worked-out calculation examples). One way of understanding the relationship between the distance and positions of source and observer (or sensor) on the amount of radiation received is to use a geometric model. In the model we will use, a point source is located at the centre or origin of an imaginary sphere. As the distance from the origin increases, the surface area of the sphere at this distance increases. The relationship between the distance increase and area increase is, obviously, not linear. In addition, according to the well known cosine law, the amount of radiation received per unit area depends on the angle of incidence. After this informal introduction we will describe the model in more detail. When a beam or the radiation passing into a space or sphere is analysed, two important parameters are necessary: the distance to the source and the measuring position— i.e. if the receiving surface is perpendicular to the beam or not. The geometry is illustrated in Figure 1.1 with a radiation source at the origin. The radiation is received at distance 𝑟 by a surface of area d𝐴, tilted by an angle 𝛼 to the unit sphere’s surface element, so called solid angle, dΩ, which is a two-dimensional angle in a space. The relation between d𝐴 and dΩ in spherical coordinates is geometrically explained in Figure 1.1. The solid angle is calculated from the zenith angle 𝜃 and azimuth angle 𝜙, which denote the direction of the radiation beam dΩ = d𝜃 ⋅ sin 𝜃d𝜙

(1.3)

The area of the receiving surface is calculated by a combination of the solid angle of the beam, the distance 𝑟 from the radiation source and the angle 𝛼 of the tilt: d𝐴 =

𝑟d𝜃 ⋅ 𝑟 sin 𝜃d𝜙 cos 𝛼

(1.4)

which can be rearranged to ⇒ d𝐴 =

𝑟2 cos 𝛼

dΩ

(1.5)

Thus, the solid angle is given by Ω=∫ 𝐴

d𝐴 ⋅ cos 𝛼 𝑟2

(1.6)

The unit of the solid angle is a steradian (sr). The solid angle of an entire sphere is calculated by integration of equation (1.3) over the zenith (𝜃) and azimuth (𝜙) angles, 0 ≤ 𝜃 ≤ 𝜋(180∘ ) and 0 ≤ 𝜙 ≤ 2𝜋(360∘ ), and is 4𝜋 sr. For example, the sun or

4

100≤ 𝜆