User Guide: 1 Radiation

Getting started

We load two packages in addition to ‘photobiology’, ‘lubridate’ and ‘dplyr’, as they will be used in the examples.

library(photobiology)
library(lubridate)
library(dplyr)

Classes

Package ‘photobiology’ defines several classes intended to be used to store different types of spectral data. They are all derived from generic_spct, which in turn is derived from tibble::tibble. Table 1 lists these classes. Attributes are used to store metadata such as information about units of expression.

Table 1. Classes for spectral data. In addition to the required variables listed in the table, additional arbitrary variables are partly supported—some operations will not include them in returned values to avoid ambiguity and other possible conflicts. In addition to the attributes listed in the table, all spectral objects support attributes multiple.wl, idfactor, normalized, scaled, when.measured, where.measured, what.measured, how.measured plus the normal attributes of tibble (and data.frame) objects including comment. All these attributes plus attributes instrument.descriptor and instrument.settings are retained across operations on spectra as long as they remain valid.

The design imposes the restriction that data from different observations are never present as different data columns, if present, additional data columns represent different properties from the same observation event. In other words, the storage format is tidy as defined by Hadley Wickham. In most cases, one spectral object should correspond to one spectral observation, but some functions are compatible or can be used to create spectral objects where the spectral data from different observations are stored “longitudinally” and “tagged” with a factor with a level for each observation event. These observations must use consistent units of expression and attribute values. This long format is useful, for example, when producing plots with package ‘ggplot2’. If spectra are stored in long form, e.g. for plotting with ‘ggplot2’, attributes are stored as named lists or enforced to be the same across spectra. This allows to reconstruct a collection of spectra from a long-form spectral object and vice versa preserving most of the metadata.

Collections of spectra should be in general preferred to multiple spectra stored in a single spectral object. This is because collections are the “native” storage approach, supporting all operations efficiently. All operations that have as return value a spectrum are not implemented for spectral objects containing multiple spectra, while those summary methods that return a single numeric value for each spectrum are implemented by on-the-fly conversion of such spectra into collections.

Data assumptions

A key assumption of the package is that wavelengths are always expressed in manometers (\(1~\mathrm{nm} = 1 \cdot 10^{-9}\,\mathrm{m}\)). If the data to be analysed use different units for wavelengths, e.g. Ångstrom (\(1~\textrm{Å} = 1 \cdot 10^{-10}\,\mathrm{m}\)), the values need to be re-expressed before creating objects of the spectral classes. The same applies to all spectral quantities, as there is an expectation in every case, of using base SI units for expression. Table 2 lists the units of expression for the different variables and the metadata attributes that may determine variations in the expression of the quantities.

Table 2. Variables used for spectral data and their units of expression. A: as stored in objects of the spectral classes, B: also recognized by the set family of functions for spectra and automatically converted. time.unit accepts in addition to the character strings listed in the table, objects of classes lubridate::duration and period, in addition numeric values are interpreted as seconds. exposure.time accepts these same values, but not the character strings.

Energy irradiance is assumed to be expressed in \(W\,m^{-2}\) and photon irradiances in \(mol^{-1}\,m^{-2}\,s^{-1}\), that is to say using second as unit for time and no SI scale factors for the measured variables. With respect to time, second is the default, but it is possible to set the unit for time to an arbitrary time duration such as day. Obviously, this applies only to rate variables like irradiance and response rates, but not to time-invariant intensive properties like transmittance of filters.

The default time unit used is second, but minute, hour, day and exposure can be used by supplying as arguments "minute", "hour", "day", or "exposure"—The meaning of "exposure" is the total exposure time, in other words, fluence instead of irradiance—to the constructor source_spct(). In addition to these character constants objects of class lubridate:duration are also accepted. In other words irradiance is a flux rate while exposure is a flux, as both are expressed per unit of illuminated area.

In the case of spectra of the molar attenuation coefficient we use \(\log_{10}\) as a base for the stored values but the constructor accepts data expressed in other log bases. The expected units are always in metres (\(m^{-1}\)) rather than the frequently used centimetres (\(cm^{-1}\)).

Transmittance, reflectance and absorptance are stored as fractions of one. The constructors also accept these quantities expressed as percentages, and convert them.

Most attributes are set when a spectral object is created, either using default values or with values supplied as arguments to the constructor. In many cases the default is NA used to indicate missing information.

Methods for querying and setting these attributes in already constructed objects are also available.

Not respecting the expectations about data inputs or setting erroneous values in the metadata attributes will yield completely wrong results if calculations are attempted! It is extremely important to make sure that the wavelengths are in nanometres as this is what all functions expect. If wavelength values are in the wrong units, the action-spectra weights and quantum to/from energy units conversions will be wrongly calculated, and the values returned by most functions wrong, without warning. Errors in some cases will be triggered at the time of object creation as the data input to constructors is tested to be within the expected range of values, which in the case of some quantities frequently allows detection of mistakes in the use unit scaling factors.

If spectral irradiance data is in \(W\,m^{-2}\,nm^{-1}\), and the wavelength in nm, as is the case for many Macam spectroradiometers, the data can be used directly and functions in the package will return irradiances in \(W\,m^{-2}\).

If, for example, the spectral irradiance data output by a spectroradiometer is expressed in \(mW\,m^{-2}\,nm^{-1}\), and the wavelengths are in Ångstrom then to obtain correct results when using any of the packages in the suite, we need to rescale the data when creating a new object.

# not run
my.spct <- source_spct(w.length = wavelength/10, s.e.irrad = irrad/1000)

In the example above, we take advantage of the behaviour of the R language: an operation between a scalar and a vector, is equivalent to applying this operation to each element of the vector. Consequently, in the code above, each value from the vector of wavelengths is divided by 10, and each value in the vector of spectral irradiances is divided by 1000.

Querying the class

Before giving examples of how to construct objects to store spectral data we show how to query the class of an object, and how to query the class of a spectrum. Consistently with R, the package provides is functions for querying the type of spectra objects. The only unusual function name, defined as a synonym for is.generic_spct: is.any_spct().

is.any_spct(sun.spct)

## [1] TRUE

is.generic_spct(sun.spct)

## [1] TRUE

is.source_spct(sun.spct)

## [1] TRUE

is.data.frame(sun.spct)

## [1] TRUE

In addition function class_spct() returns directly the spectrum-related class attributes—i.e. it filters out from the output of class() the underlying inherited classes.

class_spct(sun.spct)

## [1] "source_spct"  "generic_spct"

class(sun.spct)

## [1] "source_spct"  "generic_spct" "tbl_df"       "tbl"          "data.frame"

Construction

There are two different approaches to the creation of spectral objects by users. The first group are constructors similar to the data.frame() constructor, which take vectors as arguments. The second group are constructors that convert list objects, and because of class derivation also data.frame objects, into spectral objects. Constructors in this second group are similar to as.data.frame from base R. In contrast to the data frame constructors, spectral object constructors require the variables or the vector arguments to be suitably named so that they can be recognized.

Here we briefly describe the as constructor functions for spectra. In the first example we create an object to store spectral irradiance data for a fictitious light source, by first creating a data frame, and creating the spectral object as a copy of it. In the example below we supply a single value, 1, for the spectral irradiance. This value gets recycled as is normal in R, but of course in real use it is more usual to supply a vector of the same length as the w.length vector.

my.df <- data.frame(w.length = 400:410, s.e.irrad = 1)
my.spct <- as.source_spct(my.df)
class(my.spct)

## [1] "source_spct"  "generic_spct" "tbl_df"       "tbl"          "data.frame"

class(my.df)

## [1] "data.frame"

my.spct

## Object: source_spct [11 x 2]
## Wavelength range 400-410 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      400         1
## 2      401         1
## 3      402         1
## 4      403         1
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows

We can copy and convert any spectrum object into any of its base clases, such as generic_spct or data.frame. This can result in the immediate and surely in the delayed loss of metadata when modified. In addition, objects downgraded to a base class support fewer operations and those still available may behave differently.

my.g.spct <- as.generic_spct(my.spct)
class(my.g.spct)

## [1] "generic_spct" "tbl_df"       "tbl"          "data.frame"

When constructing spectral objects from numeric vectors the names of the arguments are meaningful and convey information on the nature of the spectral data and basis of expression.

source_spct(w.length = 300:305, s.e.irrad = 1)

## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 6 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      300         1
## 2      301         1
## 3      302         1
## 4      303         1
## 5      304         1
## 6      305         1

z <- 300:305
y <- 2
source_spct(w.length = z, s.e.irrad = y)

## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 6 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      300         2
## 2      301         2
## 3      302         2
## 4      303         2
## 5      304         2
## 6      305         2

When argument names are not supplied explicitly as above, the names of the variables are used to identify the data vectors.

w.length <- 300:305
s.e.irrad <- 1
source_spct(w.length, s.e.irrad)

## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 6 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      300         1
## 2      301         1
## 3      302         1
## 4      303         1
## 5      304         1
## 6      305         1

The different constructors have additional arguments to be used in setting non-default values for the attributes. These arguments have the same name as the attributes. Here we used the data frame created in the first code chunk of this section.

my.d.spct <- as.source_spct(my.df, time.unit = "day")

Argument strict.range can be used to override or make more strict the validation of the data values.

source_spct(w.length = 300:305, s.e.irrad = -1)

## Warning in range_check(x, strict.range = strict.range): Negative spectral energy
## irradiance values; minimum s.e.irrad = -1.00

## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 6 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      300        -1
## 2      301        -1
## 3      302        -1
## 4      303        -1
## 5      304        -1
## 6      305        -1

source_spct(w.length = 300:305, s.e.irrad = -1, strict.range = NULL)

## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 6 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      300        -1
## 2      301        -1
## 3      302        -1
## 4      303        -1
## 5      304        -1
## 6      305        -1

Argument comment can be used to add a comment to the data at the time of construction.

my.cm.spct <- source_spct(w.length = 300:305, s.e.irrad = 1,
                          comment = "This is a comment")
comment(my.cm.spct)

## [1] "This is a comment"

The constructors treat unrecognized named arguments as data to create aditional columns in the spectral objects.

Metadata attributes

Metadata attributes are used in the spectral objects to store metadata in a consistently. These metadata are in some cases required for conversion among related physical quantities, while in other cases allow printing of ancillary information needed for interpretation, like units of expression. These metadata are also used in other packages in the suite, for example in ‘ggspectra’ to automatically produce axis labels, titles and annotations. A few attributes are simply a way or organizing the storage of information which is not used in any calculations, functioning as a kind of specialized comments. The metadata described in this section are stored in spectral objects using attributes, which are a normal feature of the R language. An example, is attribute time.unit used to indicate if spectral irradiance is expressed per second or integrated over some other time duration.

my.spct <- sun.spct
when_measured(my.spct) <-  NULL
when_measured(my.spct)

## [1] NA

when_measured(my.spct) <- lubridate::ymd_hms("2015-10-31 22:55:00", tz = "EET")
when_measured(my.spct)

## [1] "2015-10-31 20:55:00 UTC"

where_measured(my.spct) <- NULL
where_measured(my.spct)

## # A tibble: 1 × 3
##     lon   lat address
##   <dbl> <dbl> <chr>  
## 1    NA    NA <NA>

where_measured(my.spct) <- data.frame(lat = 60, lon = -10)
where_measured(my.spct)

## # A tibble: 1 × 3
##     lat   lon address
##   <dbl> <dbl> <chr>  
## 1    60   -10 <NA>

where_measured(my.spct) <- data.frame(lat = 60, lon = -10, address = "Somewhere")
where_measured(my.spct)

## # A tibble: 1 × 3
##     lat   lon address  
##   <dbl> <dbl> <chr>    
## 1    60   -10 Somewhere

my.spct

## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 20:55:00 UTC 
## Measured at 60 N, -10 E; Somewhere 
## Time unit 1s
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

what_measured(my.spct) <- "something"
what_measured(my.spct)

## [1] "something"

my.spct

## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: something 
## Measured on 2015-10-31 20:55:00 UTC 
## Measured at 60 N, -10 E; Somewhere 
## Time unit 1s
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

sun.spct

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

is_effective(sun.spct)

## [1] FALSE

is_effective(sun.spct * waveband(c(400, 700)))

## [1] FALSE

ten.minutes.spct <-
  convertTimeUnit(sun.spct, time.unit = duration(10, "minutes"))
ten.minutes.spct

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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 600s (~10 minutes)
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

getTimeUnit(ten.minutes.spct)

## [1] "600s (~10 minutes)"

polyester.spct

## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length     Tfr
##      <int>   <dbl>
## 1      240 0.00482
## 2      241 0.00464
## 3      242 0.00446
## 4      243 0.00429
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

convertThickness(polyester.spct, thickness = 2e-3)

## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 2, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length      Tfr
##      <int>    <dbl>
## 1      240 2.53e-37
## 2      241 1.38e-37
## 3      242 7.39e-38
## 4      243 3.85e-38
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

Classes

The package defines several classes intended to be used to store collections of different types of spectral data. They are all derived from generic_mspct, which in turn is derived from list. Table 3 lists them.

Table 3. Classes for collections of spectral objects. Objects of class generic_mspct can have member objects of any class derived from generic_spct and can be heterogeneous, while the other classes support homogeneous collections of spectral objects. Attributes of these objects can be queried and set with the normal R methods attr and attributes as well as with functions defined in this package. See table 1 for the attributes used in individual member spectra of collections.

Objects of these classes, except for class generic_mspct, can only contain members belonging the matching class of spectra. As all other spectral object classes are derived from generic_spct, generic_mspct objects can contain heterogeneous collections of spectra. In all cases, there are no restrictions on the lengths, wavelength range and/or wavelength step size, or attributes other than class of the contained spectra. Mimicking R’s arrays and matrices, a dim attribute is always present and dim methods are provided. This approach allows the storage of time series of spectral data, or (hyper)spectral image data, or even higher dimensional spectral data. The handling of 1D and 2D spectral collections is already implemented in the summary methods. Handling of 3D and higher dimensional data can be implemented in the future without changing the class definitions. By having implemented dim, also methods ncol and nrow are available as they use dim internally. Array-like subscripting collections of spectra is not implemented.

Construction

two_suns.mspct <- source_mspct(list(sun1 = sun.spct, sun2 = sun.spct))
two_suns.mspct

## Object: source_mspct [2 x 1]
## --- Member: sun1 ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: sun2 ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

mixed.mspct <- generic_mspct(list(filter = polyester.spct, source = sun.spct))
class(mixed.mspct)

## [1] "generic_mspct" "list"

lapply(mixed.mspct, class_spct)

## $filter
## [1] "filter_spct"  "generic_spct"
## 
## $source
## [1] "source_spct"  "generic_spct"

two_gen.mspct <- as.generic_mspct(two_suns.mspct)
class(two_gen.mspct)

## [1] "generic_mspct" "list"

str(two_gen.mspct, max.level = 1, give.attr = FALSE)

## List of 2
##  $ sun1: source_spct [522 × 3] (S3: source_spct/generic_spct/tbl_df/tbl/data.frame)
##  $ sun2: source_spct [522 × 3] (S3: source_spct/generic_spct/tbl_df/tbl/data.frame)

one_sun.mspct <- as.source_mspct(sun.spct)
class(one_sun.mspct)

## [1] "source_mspct"  "generic_mspct" "list"

str(one_sun.mspct, max.level = 1, give.attr = FALSE)

## List of 1
##  $ spct_1: source_spct [522 × 3] (S3: source_spct/generic_spct/tbl_df/tbl/data.frame)

x <- matrix(1:100, ncol = 2)
wl <- 501:550 # wavelengths in nanometres
as.filter_mspct(x, wl, "Tpc")

## Object: filter_mspct [0 x 3]
## --- Member: spct_1 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 50 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      501  0.01
## 2      502  0.02
## 3      503  0.03
## 4      504  0.04
## # … with 46 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: spct_2 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 50 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      501  0.51
## 2      502  0.52
## 3      503  0.53
## 4      504  0.54
## # … with 46 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

as.filter_mspct(x, wl, "Tpc", spct.names = c("A", "B"))

## Object: filter_mspct [0 x 3]
## --- Member: A ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 50 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      501  0.01
## 2      502  0.02
## 3      503  0.03
## 4      504  0.04
## # … with 46 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 50 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      501  0.51
## 2      502  0.52
## 3      503  0.53
## 4      504  0.54
## # … with 46 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

xrow <- matrix(1:100, nrow = 2, byrow = TRUE)
as.filter_mspct(xrow, wl, "Tpc")

## Object: filter_mspct [0 x 3]
## --- Member: spct_1 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 50 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      501  0.01
## 2      502  0.02
## 3      503  0.03
## 4      504  0.04
## # … with 46 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: spct_2 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 50 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      501  0.51
## 2      502  0.52
## 3      503  0.53
## 4      504  0.54
## # … with 46 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

two_suns.mat <- as.matrix(two_suns.mspct, "s.e.irrad")
class(two_suns.mat)

## [1] "matrix" "array"

dim(two_suns.mat)

## [1] 522   2

head(dimnames(two_suns.mat)$spct)

## [1] "sun1" "sun2"

head(dimnames(two_suns.mat)$w.length)

## [1] "280"              "280.923076923077" "281.846153846154" "282.769230769231"
## [5] "283.692307692308" "284.615384615385"

head(attr(two_suns.mat, "w.length"))

## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154

two_suns.row_mat <- as.matrix(two_suns.mat, "s.e.irrad", byrow = TRUE)
class(two_suns.row_mat)

## [1] "matrix" "array"

dim(two_suns.row_mat)

## [1] 522   2

head(dimnames(two_suns.row_mat)$spct)

## [1] "sun1" "sun2"

head(attr(two_suns.row_mat, "w.length"))

## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154

two_suns.spct <- rbindspct(list(a = sun.spct, b = sun.spct / 2))
two_suns.spct

## Object: source_spct [1,044 x 4]
## containing 2 spectra in long form
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## a label: sunlight, simulated
## b label: sunlight, simulated 
## a measured on 2010-06-22 09:51:00 UTC
## b measured on 2010-06-22 09:51:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 1,044 × 4
##   w.length s.e.irrad spct.idx s.q.irrad
##      <dbl>     <dbl> <fct>        <dbl>
## 1     280          0 a                0
## 2     281.         0 a                0
## 3     282.         0 a                0
## 4     283.         0 a                0
## # … with 1,040 more rows
## # ℹ Use `print(n = ...)` to see more rows

subset2mspct(two_suns.spct)

## Object: source_mspct [2 x 1]
## --- Member: a ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: b ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

test1.df <- data.frame(w.length = rep(200:210, 2),
                       s.e.irrad = rep(c(1, 2), c(11, 11)),
                       spectrum = factor(rep(c("A", "B"), c(11,11))))
subset2mspct(test1.df, member.class = "source_spct", idx.var = "spectrum")

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      200         1
## 2      201         1
## 3      202         1
## 4      203         1
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      200         2
## 2      201         2
## 3      202         2
## 4      203         2
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

subset2mspct(test1.df, member.class = "source_spct", idx.var = "spectrum",
             time.unit = "day")

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 86400s (~1 days)
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      200         1
## 2      201         1
## 3      202         1
## 4      203         1
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 86400s (~1 days)
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      200         2
## 2      201         2
## 3      202         2
## 4      203         2
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

test2.df <- test1.df
setSourceSpct(test2.df, multiple.wl = 2L)
getMultipleWl(test2.df)

## [1] 2

test3.df <- test1.df
setSourceSpct(test3.df, multiple.wl = NULL)
getMultipleWl(test3.df)

## [1] 2

test2.df <- data.frame(w.length = 200:210, A = 1, B = 2, z = "A")
split2source_mspct(test2.df)

## Warning in split2mspct(x = x, member.class = "source_spct", spct.data.var =
## spct.data.var, : Skipping non-numeric column in x: z

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      200         1
## 2      201         1
## 3      202         1
## 4      203         1
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.e.irrad
##      <int>     <dbl>
## 1      200         2
## 2      201         2
## 3      202         2
## 4      203         2
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

split2source_mspct(test2.df, spct.data.var = "s.q.irrad")

## Warning in split2mspct(x = x, member.class = "source_spct", spct.data.var =
## spct.data.var, : Skipping non-numeric column in x: z

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.q.irrad
##      <int>     <dbl>
## 1      200         1
## 2      201         1
## 3      202         1
## 4      203         1
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 1s
## 
## # A tibble: 11 × 2
##   w.length s.q.irrad
##      <int>     <dbl>
## 1      200         2
## 2      201         2
## 3      202         2
## 4      203         2
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

split2source_mspct(test2.df, spct.data.var = "s.q.irrad", time.unit = "day")

## Warning in split2mspct(x = x, member.class = "source_spct", spct.data.var =
## spct.data.var, : Skipping non-numeric column in x: z

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 86400s (~1 days)
## 
## # A tibble: 11 × 2
##   w.length s.q.irrad
##      <int>     <dbl>
## 1      200         1
## 2      201         1
## 3      202         1
## 4      203         1
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm 
## Time unit 86400s (~1 days)
## 
## # A tibble: 11 × 2
##   w.length s.q.irrad
##      <int>     <dbl>
## 1      200         2
## 2      201         2
## 3      202         2
## 4      203         2
## # … with 7 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

Conversion into a “wide” data frame

Sometimes, when exporting spectral data we may need to convert a collection of spectra into an untidy or wide form data frame. In the example below we use a collection with only two member spectra, but join_mspct() can handle collections of any length.

my.mspct <- source_mspct(list(sun1 = sun.spct, sun2 = sun.spct * 2))
my.df <- join_mspct(my.mspct)
head(my.df)

##   w.length sun1 sun2
## 1 280.0000    0    0
## 2 280.9231    0    0
## 3 281.8462    0    0
## 4 282.7692    0    0
## 5 283.6923    0    0
## 6 284.6154    0    0

Querying the class

is. functions are defined for all the new classes. R’s class method can also be used.

is.source_mspct(two_suns.mspct)

## [1] TRUE

class(two_suns.mspct)

## [1] "source_mspct"  "generic_mspct" "list"

In addition to using class to query the class of the collection, we can use base R’s lapply together with class or class_spct to query the class of each of the members of the collection.

is.filter_mspct(mixed.mspct)

## [1] FALSE

is.any_mspct(mixed.mspct)

## [1] TRUE

class(mixed.mspct)

## [1] "generic_mspct" "list"

lapply(mixed.mspct, class_spct)

## $filter
## [1] "filter_spct"  "generic_spct"
## 
## $source
## [1] "source_spct"  "generic_spct"

lapply(mixed.mspct, class)

## $filter
## [1] "filter_spct"  "generic_spct" "tbl_df"       "tbl"          "data.frame"  
## 
## $source
## [1] "source_spct"  "generic_spct" "tbl_df"       "tbl"          "data.frame"

Extract, replace and combine

R’s extraction and replacement methods have specializations for collections of spectra and can be used with the same syntax and functionality as for R lists. However they test the class and validity of the returned objects and replacement members.

Methods [, and [<-, extract and replace parts of the collection, respectively. Even when only one member is extracted, the returned value is a collection of spectra. The expected replacement value is also, always a collection of spectra.

# not run as this triggers an error when building the vignette with 'devtools'
two_suns.mspct[1]
two_suns.mspct[1:2]

Avoid code like that in the chunk bellow. Collections of spectra are named lists, consequently assigning by position as shown here swaps the values without swapping the names of the slots!

# not run as this triggers an error when building the vignette with 'devtools'
two_suns.mspct[1:2] <- two_suns.mspct[2:1]

Methods [[, $ and [[<-, extract and replace individual members of the collection, respectively. They always return or expect objects of one of the spectral classes.

two_suns.mspct[[1]]

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

two_suns.mspct$sun1

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

two_suns.mspct[["sun1"]]

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

two_suns.mspct[["sun1"]] <- sun.spct * 2
two_suns.mspct[["sun2"]] <- NULL
two_suns.mspct

## Object: source_mspct [1 x 1]
## --- Member: sun1 ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

As with R’s list objects, can combine collections of spectra with method c() but we can not create new collections from individual spectra using this method.

c(two_suns.mspct, mixed.mspct)

## Object: generic_mspct [3 x 1]
## --- Member: sun1 ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: filter ---
## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length     Tfr
##      <int>   <dbl>
## 1      240 0.00482
## 2      241 0.00464
## 3      242 0.00446
## 4      243 0.00429
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: source ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

Transform or apply functions

For our apply functions we follow the naming convention used in package plyr, but using ms as prefix for _mspct objects. The apply functions implemented in the ‘photobiology’ package are msmsply, msdply, mslply and msaply which both accept a collection of spectra as first argument and return a collection of spectra, a data frame, a list, or an array respectively (see Table 4).

Table 4. Apply functions for collections of spectra. Key: v., value returned by apply function; f.v., value returned by the applied function (argument .fun). In the table generic_mspct and generic_spct indicate objects of these classes or any class derived from them. The exact class of the collection of spectra object returned will be determined by the class(es) of the values returned by the applied function.

Functions msmsply(), msdply and mslply can be used to apply a function to each member spectrum in a collection. The apply function to use depends on the return value of the applied function.

In the case of msmsply() the applied function is expected to return a transformed spectrum as another object of class generic_spct or a class derived from it. The value returned by msmsply is a collection of spectra, of a type determined by the class(es) of the member spectra in the new collection.

We start with a simple example in which we add a constant to each spectrum in the collection

two.mspct <- source_mspct(list(A = sun.spct * 1, B = sun.spct * 2))
msmsply(two.mspct, `+`, 0.1)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280        0.1
## 2     281.       0.1
## 3     282.       0.1
## 4     283.       0.1
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280        0.1
## 2     281.       0.1
## 3     282.       0.1
## 4     283.       0.1
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

and continue with a more complex example in which we trim each spectrum

msmsply(two.mspct, trim_wl, range = c(281, 500), fill = NA)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [525 x 2]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 525 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280         NA
## 2     281.        NA
## 3     281.        NA
## 4     281          0
## # … with 521 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [525 x 2]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 525 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280         NA
## 2     281.        NA
## 3     281.        NA
## 4     281          0
## # … with 521 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

In the second example we pass two arguments by name to the applied function. The number of arguments is not fixed, but the spectrum will be always passed as the first argument to the function.

In the case of msdply() the applied function is expected to return an R object of the same length for each of the member spectra.

msdply(two.mspct, max)

## # A tibble: 2 × 2
##   spct.idx max.wl
##   <fct>     <dbl>
## 1 A           800
## 2 B           800

ranges.df <- msdply(two.mspct, range)
ranges.df

## # A tibble: 2 × 3
##   spct.idx min.wl max.wl
##   <fct>     <dbl>  <dbl>
## 1 A           280    800
## 2 B           280    800

cat(comment(ranges.df))

## Applied function: 'range'.

msdply(two.mspct, range, na.rm = TRUE)

## # A tibble: 2 × 3
##   spct.idx min.wl max.wl
##   <fct>     <dbl>  <dbl>
## 1 A           280    800
## 2 B           280    800

In the case of mslply() the applied function is expected to return an R object of any length, possibly variable among members.

str(mslply(two.mspct, names))

## List of 2
##  $ A: chr [1:2] "w.length" "s.e.irrad"
##  $ B: chr [1:2] "w.length" "s.e.irrad"
##  - attr(*, "comment")= chr "Applied function: 'names'.\n"

In the case of msaply() the applied function is expected to return an R object of length 1, although a list with dimensions will be returned for longer return values.

str(msaply(two.mspct, max))

##  num [1:2] 800 800
##  - attr(*, "comment")= chr "Applied function: 'max'.\n"

str(msaply(two.mspct, range))

##  num [1:2, 1:2] 280 280 800 800
##  - attr(*, "dimnames")=List of 2
##   ..$ : NULL
##   ..$ : chr [1:2] "1" "2"
##  - attr(*, "comment")= chr "Applied function: 'range'.\n"

For the most common cases for which one would use the apply functions described in the previous section methods and functions for operations on collections of spectra are defined in the package. These methods are described in a later section and listed in Table 9.

Summary spectra

Starting from a collection of spectra we may want to obtain a single spectrum containing a summary of them. The current implementation of the methods described in this section expects that all spectra in a collection are of the same class, and data is available for each of them at exactly the same set of wavelengths.

The calculations are done wavelength by wavelength yielding a spectrum at the same wavelengths than those in the input. Removal of NA values is done wavelength by wavelength. As shown in the table above, depending on the operation the returned quantity may be equivalent or not to the quantity in the input. When the quantity changes, even if units of expression remain the same, the name of the variable and class of the returned spectrum are different to those in the input.

Methods in this “family” are fast and are specially useful for large collections of spectra containing even thousands of individual spectra. Nonetheless, for the example below we use a collection of two spectra. As computing the mean returns values of the same quantity as in the input the returned value is a source_spct object, in other words of the same class as the members of two.mspct.

s_mean(two.mspct)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: Mean of 2 source_spct objects. 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

When we compute the standard error, the quantity returned is not the same. Consequently, the object returned is in this case a generic_spct instead of source_spc as it does not contain spectral irradiance data as the input did. The variable name is in addition tagged with .se to advertise the change in the quantity.

s_se(two.mspct)

## Object: generic_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: Standard error for 2 source_spct objects. 
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad.se
##      <dbl>        <dbl>
## 1     280             0
## 2     281.            0
## 3     282.            0
## 4     283.            0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

We can also compute both the mean and standard error simultaneously.

s_mean_se(two.mspct)

## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: Mean and SEM of 2 source_spct objects. 
## Time unit 1s
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.e.irrad.se
##      <dbl>     <dbl>        <dbl>
## 1     280          0            0
## 2     281.         0            0
## 3     282.         0            0
## 4     283.         0            0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

The other functions in this family work in a similar way to those described here.

Convolution

By convolution we normally mean the multiplication value by value at matching wavelengths of two spectra. The function described in this section facilitates this and similar operations among collections of spectra. An example use case could be the convolution of spectral irradiance by spectral transmittance for all combinations of light sources and filters in a collection of source spectra and a collection of filter spectra.

Default operator (or function) is that for multiplication, either one or both of the two first arguments must be a collection of spectra. When only one argument is a collection of spectra, the other one can be a spectrum, or even a numeric vector. For multiplication the order of the operands does not affect the returned value. With operators or functions for non-transitive operations the order does matter.

convolve_each(two.mspct, sun.spct)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

convolve_each(sun.spct, two.mspct)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

another_two.mspct <- two.mspct
names(another_two.mspct) <- c("a", "b")
convolve_each(another_two.mspct, two.mspct)

## Object: source_mspct [2 x 2]
## --- Member: a_A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: a_B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: b_A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: b_B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

The function convolve_each will use other operators or functions and even pass additional named arguments when these are supplied as arguments.

convolve_each(two.mspct, sun.spct, oper = `+`)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

There are cases where functions convolve_each() and msmsply() can be both used, but there are also cases where their differences matter. An example is convolving two collections of spectra, a case where only convolve_each() can be used. In contrast, when one of the arguments is not a spectrum or a collection of spectra, msmsply() should be used instead.

Metadata attributes

Some of the set and get functions used with attributes have method definitions for collections of spectra. Some examples follow.

when_measured(two.mspct)

## # A tibble: 2 × 2
##   spct.idx when.measured      
##   <fct>    <dttm>             
## 1 A        2010-06-22 09:51:00
## 2 B        2010-06-22 09:51:00

when_measured(two.mspct) <- ymd("2015-10-31", tz = "EET")
when_measured(two.mspct)

## # A tibble: 2 × 2
##   spct.idx when.measured      
##   <fct>    <dttm>             
## 1 A        2015-10-30 22:00:00
## 2 B        2015-10-30 22:00:00

when_measured(two.mspct) <- list(ymd_hm("2015-10-31 10:00", tz = "EET"),
                                 ymd_hm("2015-10-31 11:00", tz = "EET"))
when_measured(two.mspct)

## # A tibble: 2 × 2
##   spct.idx when.measured      
##   <fct>    <dttm>             
## 1 A        2015-10-31 08:00:00
## 2 B        2015-10-31 09:00:00

two.mspct

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 08:00:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 09:00:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

Other methods available are getWhereMeasured and setWhereMeasured, and getWhatMeasured and setWhatMeasured.

Functions when.measured2tb(), geocode2tb(), lon2tb(), lat2tb() and what.measured2tb() extract these same attributes from collection members into a tibble or data frame. In contrast to the “get” methods described above, if an existing data frame or tibble with a matching number of rows is passed as second argument, the values for the attribute are saved into a new column appended at the right edge of the tibble or data frame.

when_measured2tb(two.mspct)

## # A tibble: 2 × 2
##   spct.idx when.measured      
##   <fct>    <dttm>             
## 1 A        2015-10-31 08:00:00
## 2 B        2015-10-31 09:00:00

By default the new column is named after the name of the attribute, but this default can be overridden by the user.

when_measured2tb(two.mspct, col.names = c(when.measured = "time"))

## # A tibble: 2 × 2
##   spct.idx time               
##   <fct>    <dttm>             
## 1 A        2015-10-31 08:00:00
## 2 B        2015-10-31 09:00:00

Function spct_metadata() returns the metadata in a tibble. Unless the user supplies a list of names of attributes, all applicable metadata values are returned. A single spectrum or a collection of spectra can be passed. By default columns containing only missing data are dropped.

spct_metadata(two.mspct)

## # A tibble: 2 × 10
##   spct.idx   lat   lon address       when.measured       what.…¹ norma…² multi…³
##   <fct>    <dbl> <dbl> <chr>         <dttm>              <chr>     <dbl>   <dbl>
## 1 A         60.2  25.0 Kumpula, Hel… 2015-10-31 08:00:00 sunlig…       0       1
## 2 B         60.2  25.0 Kumpula, Hel… 2015-10-31 09:00:00 sunlig…       0       1
## # … with 2 more variables: time.unit <dbl>, bswf.used <chr>, and abbreviated
## #   variable names ¹​what.measured, ²​normalized, ³​multiplier
## # ℹ Use `colnames()` to see all variable names

spct_metadata(two.mspct, 
              col.names = c("when.measured" = "time", 
                            "where.measured" = "geocode"),
              unnest = FALSE)

## # A tibble: 2 × 3
##   spct.idx time                geocode         
##   <fct>    <dttm>              <named list>    
## 1 A        2015-10-31 08:00:00 <tibble [1 × 3]>
## 2 B        2015-10-31 09:00:00 <tibble [1 × 3]>

Function add_attr2tb() adds one or more columns with attributes to a tibble or data frame. We here also demonstrate that because the data frame object is passed to the first positional argument, we can use a pipe. This difference in interface is the main difference between this function and spct_metadata().

q_irrad(two.mspct) %>%
  add_attr2tb(two.mspct, 
              col.names = c("lon", "lat", "when.measured"))

## # A tibble: 2 × 5
##   spct.idx Q_Total   lon   lat when.measured      
##   <fct>      <dbl> <dbl> <dbl> <dttm>             
## 1 A        0.00126  25.0  60.2 2015-10-31 08:00:00
## 2 B        0.00251  25.0  60.2 2015-10-31 09:00:00

We can set the desired names for the columns if we wish them to be something else than the default.

q_irrad(two.mspct) %>%
  add_attr2tb(two.mspct, 
              col.names = c(lon = "longitude", 
                            lat = "latitude", 
                            when.measured = "time"))

## # A tibble: 2 × 5
##   spct.idx Q_Total longitude latitude time               
##   <fct>      <dbl>     <dbl>    <dbl> <dttm>             
## 1 A        0.00126      25.0     60.2 2015-10-31 08:00:00
## 2 B        0.00251      25.0     60.2 2015-10-31 09:00:00

Construction

To create a waveband object we use constructor function waveband, and optionally giving a name to it. We will use these objects in many of the examples below, so you will need to run the code chunk bellow to be able to reproduce those examples. It should be noted that waveband constructors for the most frequently used wavelength-range definitions are provided by package ‘photobiologyWavebands’.

PAR.wb <- waveband(c(400, 700), wb.name = "PAR")
UVA.wb <- waveband(c(315, 400), wb.name = "UVA")
UVB.wb <- waveband(c(280, 315), wb.name = "UVB")
UVC.wb <- waveband(c(100, 280), wb.name = "UVC")
UV.wb  <- waveband(c(100, 400), wb.name =  "UV")
UV_bands.lst <- list(UVC.wb, UVB.wb, UVA.wb)

When including a BSWF, we can supply, one or two versions of functions returning the weights as a function of wavelength. Several such functions are defined in package ‘photobiologyWavebands’ as well as waveband constructors using them. Here we show how a waveband can be defined based on a SWF, using the CIE definition for the erythemal spectral weighting function. Although the constructor is smart enough to derive the missing function when only one function is supplied, performance may suffer unless two performance-optimized function are provided, one for energy-based effect and a second one for photon-based effect.

CIE_e_fun <-
function(w.length){
    CIE.energy <- numeric(length(w.length))
    CIE.energy[w.length <= 298] <- 1
    CIE.energy[(w.length > 298) & (w.length <= 328)] <-
      10^(0.094*(298-w.length[(w.length > 298) & (w.length <= 328)]))
    CIE.energy[(w.length > 328) & (w.length <= 400)] <-
      10^(0.015*(139-w.length[(w.length > 328) & (w.length <= 400)]))
    CIE.energy[w.length > 400] <- 0
    return(CIE.energy)
}

CIE.wb <- waveband(c(250, 400), weight = "SWF",
                   SWF.e.fun = CIE_e_fun, SWF.norm = 298)

Another case where you might want to enter the same function twice, is if you are using an absorptance spectrum as SWF, as the percent of radiation absorbed will be independent of whether photon or energy units are used for the spectral irradiance.

The first argument to waveband() does not need to be a numeric vector of length two. Any R object of a class that supplies a range() method definition that can be interpreted as a range of wavelengths in nanometres can be used. As a consequence, when wanting to construct a waveband covering the whole range of a spectrum one can simply supply the spectrum as argument, or to construct an non-weighed waveband which covers exactly the same range of wavelengths as an existing effective (weighted) waveband, one can supply a waveband object as an argument.

waveband(sun.spct)

## Total 
## low (nm) 280 
## high (nm) 800 
## weighted none

An “empty” waveband is returned by some functions as a “null” value.

waveband()

## range.NA.NA 
## low (nm) NA 
## high (nm) NA 
## weighted none

Querying the class

The function is.waveband can the used to query any R object. This function returns a logical value.

is.waveband(PAR.wb)

## [1] TRUE

Above, we demonstrate that PAR.wb is a waveband object, the function photobiologyWavebands::PAR() is a waveband constructor returning a waveband object. See package ‘photobiologyWavebands’ for details on pre-defined waveband constructors for frequently used wavelength ranges and biological spectral weighting functions (BSWFs).

Retrieving properties

The function is_effective can the used to query any R object.

is_effective(waveband(c(400,500)))

## [1] FALSE

Construction

wavebands <- list(waveband(c(300,400)), waveband(c(400,500)))
wavebands

## [[1]]
## range.300.400 
## low (nm) 300 
## high (nm) 400 
## weighted none 
## 
## [[2]]
## range.400.500 
## low (nm) 400 
## high (nm) 500 
## weighted none

split_bands(c(200, 225, 300))

## $wb1
## range.200.225 
## low (nm) 200 
## high (nm) 225 
## weighted none 
## 
## $wb2
## range.225.300 
## low (nm) 225 
## high (nm) 300 
## weighted none

split_bands(c(200, 225, 300), length.out = 2)

## $wb1
## range.200.250 
## low (nm) 200 
## high (nm) 250 
## weighted none 
## 
## $wb2
## range.250.300 
## low (nm) 250 
## high (nm) 300 
## weighted none

split_bands(sun.spct, length.out = 2)

## $wb1
## range.280.540 
## low (nm) 280 
## high (nm) 540 
## weighted none 
## 
## $wb2
## range.540.800 
## low (nm) 540 
## high (nm) 800 
## weighted none

split_bands(PAR.wb, length.out = 2)

## $wb1
## range.400.550 
## low (nm) 400 
## high (nm) 550 
## weighted none 
## 
## $wb2
## range.550.700 
## low (nm) 550 
## high (nm) 700 
## weighted none

split_bands(c(200, 800), length.out = 3)

## $wb1
## range.200.400 
## low (nm) 200 
## high (nm) 400 
## weighted none 
## 
## $wb2
## range.400.600 
## low (nm) 400 
## high (nm) 600 
## weighted none 
## 
## $wb3
## range.600.800 
## low (nm) 600 
## high (nm) 800 
## weighted none

split_bands(list(A = c(200, 300), B = c(400, 500), C = c(250, 350)))

## $A
## range.200.300 
## low (nm) 200 
## high (nm) 300 
## weighted none 
## 
## $B
## range.400.500 
## low (nm) 400 
## high (nm) 500 
## weighted none 
## 
## $C
## range.250.350 
## low (nm) 250 
## high (nm) 350 
## weighted none

split_bands(list(c(100, 150, 200), c(800, 825)))

## $wb.a
## range.100.150 
## low (nm) 100 
## high (nm) 150 
## weighted none 
## 
## $<NA>
## range.150.200 
## low (nm) 150 
## high (nm) 200 
## weighted none 
## 
## $wb.b
## range.800.825 
## low (nm) 800 
## high (nm) 825 
## weighted none

split_bands(UV_bands.lst, length.out  =  2)

## $wb.a
## range.100.190 
## low (nm) 100 
## high (nm) 190 
## weighted none 
## 
## $<NA>
## range.190.280 
## low (nm) 190 
## high (nm) 280 
## weighted none 
## 
## $wb.b
## range.280.297.5 
## low (nm) 280 
## high (nm) 298 
## weighted none 
## 
## $<NA>
## range.297.5.315 
## low (nm) 298 
## high (nm) 315 
## weighted none 
## 
## $wb.c
## range.315.357.5 
## low (nm) 315 
## high (nm) 358 
## weighted none 
## 
## $<NA>
## range.357.5.400 
## low (nm) 358 
## high (nm) 400 
## weighted none

split_bands(list(c(100, 150, 200), c(800, 825)), length.out = 1)

## $wb.a
## range.100.200 
## low (nm) 100 
## high (nm) 200 
## weighted none 
## 
## $wb.b
## range.800.825 
## low (nm) 800 
## high (nm) 825 
## weighted none

Printing

The print() method for spectra is based on the method defined in package ‘tibble’, consequently, it is possible to use the options from this package to control printing. In the code chunk below, tibble.print_max, the number of rows in the spectral object above which only tibble.print_min rows are printed, are both set to 5, instead of the default 20 and 10, to avoid excessive clutter in our examples.

options(tibble.print_max = 4)
options(tibble.print_min = 4)

For explicit calls to print() its argument n can be used to control the number of lines printed. If n is set to Inf the whole spectrum is always printed. The output differs from that of the print() method from package ‘dplyr’ in that additional metadata specific to spectra are shown.

print(sun.spct, n = 3)

Specialized print() methods for collections of spectra and for waveband objects are also defined.

Summary

The summary() method for spectra is based on base R’s summary() method for data frames, and accepts the same arguments. The main difference is that the attributes containing metadata and dimensions of the original spectrum object are copied to the summary object.

summary(sun.spct)

Specialized print() methods for summaries of spectra are defined. The output differs from that of the print() method from base R in that additional metadata specific to spectra are shown.

Handling NAs

Functions na.omit() and na.exclude are implemented for all spectral classes. These methods test for NAs only the spectral data, not wavelength. They set the "na.action" attribute in the same way as the corresponding methods for data frames. In the case of na.fail(), na.pass() and na.action(), the methods from base R, can be used with spectra.

na.omit(sun.spct)

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

na.exclude(sun.spct)

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

Binary operators

All of R’s built-in maths operators have definitions for spectra. It is possible to sum, subtract, multiply and divide spectra. These operators can be used even if the spectral data is on different arbitrary sets of wavelengths. Operators by default return values expressed in energy units. Only certain operations are meaningful for a given combination of objects belonging to different classes, and meaningless combinations return NA also issuing a warning (see Table 5). By default operations are carried out on spectral energy irradiance for source_spct objects and transmittance for filter_spct objects.

Table 5. Binary operators and their operands. Validity and class of result. All operations marked \Y' are allowed, those marked’ are forbidden and return NA and issue a warning. Operators %/% and %% follow /.

sun.spct * sun.spct

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

When meaningful, operations between different spectra are also allowed. For example, it is possible to simulate the effect of a filter on a light source by multiplying (or convolving) the two spectra.

sun.spct * polyester.spct

## Object: source_spct [533 x 2]
## Wavelength range 280-800 nm, step 0.07692308-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
## 
## # A tibble: 533 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     281          0
## 4     282.         0
## # … with 529 more rows
## # ℹ Use `print(n = ...)` to see more rows

If we have two layers of the filter, this can be approximated using either of these two statements.

sun.spct * polyester.spct * polyester.spct

## Object: source_spct [533 x 2]
## Wavelength range 280-800 nm, step 0.07692308-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
## 
## # A tibble: 533 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     281          0
## 4     282.         0
## # … with 529 more rows
## # ℹ Use `print(n = ...)` to see more rows

sun.spct * polyester.spct^2

## Object: source_spct [533 x 2]
## Wavelength range 280-800 nm, step 0.07692308-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
## 
## # A tibble: 533 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     281          0
## 4     282.         0
## # … with 529 more rows
## # ℹ Use `print(n = ...)` to see more rows

Operators are also defined for operations between a spectrum and a numeric vector (with normal recycling).

sun.spct * 2

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

2 * sun.spct

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

sun.spct * c(0,1)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

There is one special case, for chroma_spct: if the numeric operand has length three, containing three named values x, y and z, the corresponding value is used for each of the chromaticity columns in the chroma_spct. Un-named values or differently named values are not treated specially.

Operators are also defined for operations between an spectrum and a waveband object. The next to code chunks demonstrate how the class of the result depends on whether the waveband object describes a range of wavelengths or a range of wavelengths plus a BSWF.

sun.spct * UVB.wb

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

sun.spct * CIE.wb

And of course these operations can be combined into more complex statements, including parentheses, when needed. The example below estimates the difference in effective spectral irradiance according to the CIE98 definition, between sunlight and sunlight filtered with a polyester film. Of course, the result is valid only for the solar spectral data used, which corresponds to Southern Finland.

sun.spct * CIE.wb - sun.spct * polyester.spct * CIE.wb

## Object: source_spct [133 x 2]
## Wavelength range 280-400 nm, step 0.07692308-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 'range.250.400.wtd' BSWF
## 
## # A tibble: 133 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     281          0
## 4     282.         0
## # … with 129 more rows
## # ℹ Use `print(n = ...)` to see more rows

Unary operators and maths functions

Many common maths functions, as well as unary minus and plus, are implemented for spectral objects (see Table 6).

Table 6. Unary operators and maths functions for spectra. Classes for which they are implemented and class of the result. All operations marked Y are allowed, those marked N are not implemented and return NA and issue a warning. Additional supported functions: log2, log10, sin, cos, tan, asin, acos, atan, sinpi, cospi, tanpi, signif, floor, ceiling, trunc, sign, abs.

-sun.spct

## Warning in range_check(x, strict.range = strict.range): Negative spectral energy
## irradiance values; minimum s.e.irrad = -0.82

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

sqrt(sun.spct)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

Options

Table 7 lists all the recognized options affecting maths operators and functions, and their default values. Within the suite all functions have a default value which is used when the options are undefined. Options are set using base R’s function options, and queried with functions options and getOption.

Table 7. Options used in the ‘r4photobiology suite’ and recognized by methods, operators and functions in the ‘photobiology’ package. Option names, accepted and default values, and the purpose of the options are given. Option photobiology.verbose is set to the value of R’s own verbose option at the time the ‘photobiology’ package is attached to the session.

The behaviour of the operators defined in this package depends on the value of two global options. For example, if we would like the operators to operate on spectral photon irradiance and return spectral photon irradiance instead of spectral energy irradiance, this behaviour can be set, and will remain active until unset or reset. It is possible to change options using base R’s function options() as shown in the next code chunk. The other options listed in the Table above can be set similarly, while to unset any option, they can be given a NULL value.

options(photobiology.radiation.unit = "photon")
sun.spct * UVB.wb

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.q.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

options(photobiology.radiation.unit = "energy")
sun.spct * UVB.wb

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

However using convenience functions is easier. The chunk above can be rewritten as below.

photon_as_default()
sun.spct * UVB.wb

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.q.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

energy_as_default()
sun.spct * UVB.wb

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

unset_radiation_unit_default()

Furthermore, it is possible to temporarily change the options for the evaluation of a single, possibly compound, R expression using a different syntax, reminiscent of that of R’s with().

using_photon(sun.spct * UVB.wb)

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.q.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

using_energy(sun.spct * UVB.wb)

## Object: source_spct [37 x 2]
## Wavelength range 280-315 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
## 
## # A tibble: 37 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 33 more rows
## # ℹ Use `print(n = ...)` to see more rows

Manipulating spectra

Sometimes, especially for plotting, we may want to row-bind spectra. When the aim is that the returned object retains its class and other attributes like the time unit. Package ‘photobiology’ provides function rbinspct for row-binding spectra, with the necessary checks for consistency of the bound spectra.

# STOPGAP
shade.spct <- sun.spct

By default an ID factor named spct.idx is added allow to identify the source of the observations after the binding. If the supplied list has named members, then these names are used as factor levels. If a character value is supplied to as idfactor argument, this is used as name for the factor.

rbindspct(list(sun.spct, shade.spct))

## Object: source_spct [1,044 x 4]
## containing 2 spectra in long form
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## spct_1 label: sunlight, simulated
## spct_2 label: sunlight, simulated 
## spct_1 measured on 2010-06-22 09:51:00 UTC
## spct_2 measured on 2010-06-22 09:51:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 1,044 × 4
##   w.length s.e.irrad s.q.irrad spct.idx
##      <dbl>     <dbl>     <dbl> <fct>   
## 1     280          0         0 spct_1  
## 2     281.         0         0 spct_1  
## 3     282.         0         0 spct_1  
## 4     283.         0         0 spct_1  
## # … with 1,040 more rows
## # ℹ Use `print(n = ...)` to see more rows

rbindspct(list(A = sun.spct, B = shade.spct), idfactor = "site")

## Object: source_spct [1,044 x 4]
## containing 2 spectra in long form
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## A label: sunlight, simulated
## B label: sunlight, simulated 
## A measured on 2010-06-22 09:51:00 UTC
## B measured on 2010-06-22 09:51:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 1,044 × 4
##   w.length s.e.irrad s.q.irrad site 
##      <dbl>     <dbl>     <dbl> <fct>
## 1     280          0         0 A    
## 2     281.         0         0 A    
## 3     282.         0         0 A    
## 4     283.         0         0 A    
## # … with 1,040 more rows
## # ℹ Use `print(n = ...)` to see more rows

The name of the ID factor is stored as metadata in attribute "idfactor" of the spectral data object.

Special Extract methods for spectral objects have been implemented. These are used by default and preserve the attributes used by this package, except when the returned value is a single column from the spectral object.

sun.spct[1:10, ]

## Object: source_spct [10 x 3]
## Wavelength range 280-288.30769 nm, step 0.9230769 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
## 
## # A tibble: 10 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 6 more rows
## # ℹ Use `print(n = ...)` to see more rows

sun.spct[1:10, 1]

##  [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154 285.5385 286.4615
##  [9] 287.3846 288.3077

sun.spct[1:10, 1, drop = TRUE]

##  [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154 285.5385 286.4615
##  [9] 287.3846 288.3077

sun.spct[1:10, "w.length", drop = TRUE]

##  [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154 285.5385 286.4615
##  [9] 287.3846 288.3077

In contrast to trim_spct, subset never interpolates or inserts hinges. On the other hand, the subset argument accepts any logical expression and can be consequently used to do subsetting, for example, based on factors. Both subset() and trim() methods preserve attributes.

subset(sun.spct, s.e.irrad > 0.2)

## Object: source_spct [475 x 3]
## Wavelength range 324-800 nm, step 1-3 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
## 
## # A tibble: 475 × 3
##   w.length s.e.irrad   s.q.irrad
##      <dbl>     <dbl>       <dbl>
## 1      324     0.208 0.000000562
## 2      325     0.217 0.000000589
## 3      326     0.277 0.000000756
## 4      327     0.285 0.000000779
## # … with 471 more rows
## # ℹ Use `print(n = ...)` to see more rows

subset(sun.spct, w.length > 600)

## Object: source_spct [200 x 3]
## Wavelength range 601-800 nm, step 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
## 
## # A tibble: 200 × 3
##   w.length s.e.irrad  s.q.irrad
##      <dbl>     <dbl>      <dbl>
## 1      601     0.630 0.00000316
## 2      602     0.631 0.00000317
## 3      603     0.636 0.00000321
## 4      604     0.658 0.00000332
## # … with 196 more rows
## # ℹ Use `print(n = ...)` to see more rows

subset(sun.spct, c(TRUE, rep(FALSE, 99)))

## Object: source_spct [6 x 3]
## Wavelength range 280-779 nm, step 99-100 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
## 
## # A tibble: 6 × 3
##   w.length s.e.irrad  s.q.irrad
##      <dbl>     <dbl>      <dbl>
## 1      280     0     0         
## 2      379     0.413 0.00000131
## 3      479     0.754 0.00000302
## 4      579     0.647 0.00000313
## 5      679     0.580 0.00000329
## 6      779     0.471 0.00000307

R’s Extract methods $ and [[ can be used to extract whole columns. Replace methods $<- and [<- have definitions for spectral objects, which allow their safe use. They work identically to those for data frames but check the validity of the spectra after the replacement.

Conversions between radiation units

The functions e2q and q2e can be used on source spectra to convert spectral energy irradiance into spectral photon irradiance and vice versa. A second optional argument sets the action with "add" and "replace" as possible values. By default these functions use normal reference semantics.

e2q(sun.spct, "add")

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

e2q(sun.spct, "replace")

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.q.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

Conversions among transmission quantities

For filter_spct objects functions any2T(), any2A(), and any2Afr() allow conversion among spectral transmittance, spectral absorptance and spectral absorbance. Although some conversions require a known reflectance, either as an Rfr column in the data or an Rfr.constant in the attribute filter.properties.

polyester.spct

## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length     Tfr
##      <int>   <dbl>
## 1      240 0.00482
## 2      241 0.00464
## 3      242 0.00446
## 4      243 0.00429
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

any2Afr(polyester.spct, "add")

## Object: filter_spct [561 x 3]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 3
##   w.length     Tfr   Afr
##      <int>   <dbl> <dbl>
## 1      240 0.00482 0.995
## 2      241 0.00464 0.995
## 3      242 0.00446 0.995
## 4      243 0.00429 0.995
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

any2Afr(polyester.spct, "replace")

## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length   Afr
##      <int> <dbl>
## 1      240 0.995
## 2      241 0.995
## 3      242 0.995
## 4      243 0.995
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

Normalizing a spectrum

Normalization is a way rescaling a spectrum so that the spectral quantity takes a fixed value, in most cases exactly 1, at a specific wavelength. Frequently this wavelength corresponds to the maximum value of the spectral quantity.

\[Q_\mathrm{norm}(\lambda) = \frac{Q(\lambda)}{\max{Q(\lambda)}}\] When normalizing to a specific wavelength, say 300 nm, the equation becomes \[Q_\mathrm{norm}(\lambda) = \frac{Q(\lambda)}{{Q(\lambda = 300)}}\] Function normalize permits normalizing a spectrum to a value of one at an arbitrary wavelength (nm) or to the wavelength of either the maximum or the minimum spectral value. It supports all the different spectral classes, In the example we use a source_spct object. (Equivalent functions with names spelled with “s” instead of “z” are available.)

normalize(sun.spct)

Which is equivalent to supplying "max" as argument to norm, it is also possible to give a range within which the maximum should be searched.

normalize(sun.spct, range = PAR.wb, norm = "max")

It is also possible to normalize to an arbitrary wavelength within the range of the data, even if it is not one of the wavelength values present in the spectral object, as interpolation is used when needed.

normalize(sun.spct, norm = 600.3)

The normalization status of a spectral object can be tested with method is_normalized() and the normalization used can be recalled with method getNormalized().

my.spct <- normalize(sun.spct)
is_normalized(my.spct)

## [1] TRUE

getNormalized(my.spct)

## [1] 451

Once a spectrum is normalized, summary methods that return values in absolute units such as irrad(), will trigger an error if applied. Ratios and similar summaries that are invariant with respect to normalization can be calculated.

Applying method fscale() removes the normalization and clears the corresponding attribute where the normalization information is stored. This attribute also can be cleared with method setNormalized(), but this is rarely valid or of any use.

Rescaling a spectrum

While normalization is done with respect to a single wavelength, rescaling as implemented in this package is more flexible. The scaling factor is computed as a summary over a range of wavelengths. This allows us, among other things to rescale spectral irradiance so that irradiance in a specific waveband is equal to one, or to some other user supplied target value.

\[Q^\prime(\lambda) = \frac{Q(\lambda)}{f(Q(\lambda))_{\ \mathrm{for}\ \ \lambda_1\geq\lambda>\lambda_2}}\times \alpha\] where \(\alpha\) is the target value for \(f(Q(\lambda))\).

In other words, function fscale() rescales a spectrum by dividing each spectral data value by a value calculated with a function (f) selected by a character string (“total” or “mean”), or an actual R function which can accept the spectrum object supplied as its first argument. Additional named arguments can be also passed.

How metadata is set in the returned object is controlled by a logical argument to parameter set.scaled. If TRUE, the data are labelled as being expressed in relative units and if FALSE this attribute is not set. The default argument depends on the value passed as argument to target. If this value is one, then the data are marked as no longer being expressed in absolute units. If the target is any other numeric value then it is assumed that the intention is to re-scale the data and that absolute physical units remain meaningful. It is important that the metadata matches the actual use as printing of summaries and plot labelling depends on them.

fscale(sun.spct)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

fscale(sun.spct, set.scaled = FALSE)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

fscale(sun.spct, target = 100)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

fscale(sun.spct, target = 100, set.scaled = TRUE)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## Rescaled to 'mean of s.e.irrad' = 100 for wavelengths in 280-800 nm
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

The default for f can be overridden. R functions passed as argument should be suitable for summarizing spectral objects as they will receive as first argument a spectrum rather than a numeric vector. Behind this requirement is the need to take into account wavelength steps for integration to be meaningful. In the example below we compute energy and photon irradiances. (The character arguments "mean" and "total" call functions specific to spectral data.)

fscale(sun.spct, f = "integral")

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## Rescaled to 'integral of s.e.irrad' = 1 for wavelengths in 280-800 nm
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

fscale(sun.spct, range = PAR.wb, f = e_irrad)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## Rescaled to 'a user supplied R function of s.e.irrad' = 1 for wavelengths in 400-700-none-NULL-NULL-NULL-NULL-c(399.999999999999, 400, 699.999999999999, 700)-PAR-PAR nm
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

fscale(sun.spct, range = PAR.wb, f = q_irrad, target = 800e-6)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

In the third example, the spectral data is rescaled so that the corresponding photosynthetically-active irradiance is equal to one.

The normalization status of a spectral object can be tested with method is_normalized() and the normalization used can be recalled with method getNormalized().

my.spct <- fscale(sun.spct)
is_scaled(my.spct)

## [1] TRUE

getScaled(my.spct)

## $multiplier
## [1] 1.932188
## 
## $f
## [1] "mean"
## 
## $range
## [1] 280 800
## 
## $target
## [1] 1
## 
## $cols
## [1] "s.e.irrad"

Once a spectrum is scaled, summary methods that return values in absolute units such as irrad(), will trigger a warning if applied. Ratios and similar summaries that are invariant with respect to normalization do not trigger warnings.

Applying method normalize() removes the scaling and clears the corresponding attribute where the scaling information is stored. This attribute also can be cleared with method setScaled(), and this can be useful is some cases such as when irradiance has been measured separately from the emission spectrum.

Shifting the zero of the spectral data scale

While re-scaling relies on a multiplicative factor shifting of the scale is done by addition (or subtraction) or constant. This allows us, among other things to remove a baseline computed from a region known to be equal to zero.

\[Q^\prime(\lambda) = Q(\lambda) - f(Q(\lambda))_{\ \mathrm{for}\ \ \lambda_1\geq\lambda>\lambda_2}\] Function fshift() shifts the zero of the scale of a spectrum by subtracting from each spectral data value a value calculated with a function (f) selected by a character string (“mean”, “min” or “max”), or an actual R function which can accept the spectrum object supplied as its first argument. The range argument selects a region of the spectrum to be used as reference in the calculation of the summary.

fshift(white_led.source_spct, range = UVB.wb, f = "mean")

## Object: source_spct [1,421 x 2]
## Wavelength range 251.16-898.81 nm, step 0.43-0.48 nm 
## Label: led_desk201 
## Measured on 2016-12-19 16:19:57 UTC 
## Time unit 1s
## 
## # A tibble: 1,421 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     251.         0
## 2     252.         0
## 3     252.         0
## 4     253.         0
## # … with 1,417 more rows
## # ℹ Use `print(n = ...)` to see more rows

fshift(sun.spct, range = c(280,290), f = "min")

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

In the first example, the spectral data shifted so that the mean spectral irradiance becomes zero for the UV-B region. In the second example the minimum value in the range of wavelengths between 280~nm and 290~nm is used as zero reference for the scale.

Replacing off-range spectral data values

Method clean() should be used with care as off-range values stem almost always from calibration errors or measuring noise. This function allows one to replace such values, but in many cases a zero shift or rescaling could be a better option. Even when the off-range values are the result of random noise, replacing them with the boundary values can cause bias, by censoring the data. In such cases smoothing may be applied first to reduce the possible bias caused by clean(). Here we create artificial off-range values by subtracting a constant from each spectrum.

clean(polyester.spct - 0.053)

## Warning in range_check_Tfr(x, strict.range = strict.range): Off-range
## transmittance values [-0.050..0.872] instead of [0..1]

## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      240     0
## 2      241     0
## 3      242     0
## 4      243     0
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

It is possible to restrict the cleaning to a range of wavelengths and to provide a value to be used as replacement for the off-range data.

clean(sun.spct - 0.01, range = c(280.5, 282), fill = NA)

## Object: source_spct [522 x 2]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280      -0.01
## 2     281.     NA   
## 3     282.     NA   
## 4     283.     -0.01
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

Removing spikes

Method despike() replaces spikes (very narrow peaks, or valleys) by values estimated from neighbouring pixels. This method should be also used carefully and the results inspected as it can remove features of interest from the data. Usually one knows from theory or experience if spikes can be real features or not.

spikes(sun.spct)

## Object: source_spct [2 x 2]
## Wavelength range 398-432 nm, step 34 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
## 
## # A tibble: 2 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1      398     0.504
## 2      432     0.646

my_sun.spct <- despike(sun.spct)
spikes(my_sun.spct)

## Object: source_spct [0 x 2]
## 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
## 
## # A tibble: 0 × 2
## # … with 2 variables: w.length <dbl>, s.e.irrad <dbl>
## # ℹ Use `colnames()` to see all variable names

Smoothing of spectra

We can use smoothing both to average out random variation among nearby pixels caused by measuring noise, or to filter out the real fine structure of a spectrum to better assess the larger features. The methods described here work by averaging the spectral data from neighbouring wavelengths. The simplest methods are running medians and running means (or “boxcar smoothing” in the terminology used in some software). There are several methods for smoothing available in R based on different algorithms. Some of these methods also automatically set the degree of smoothing based on the data being smoothed. Package ‘photobiology’ defines function smooth_spct, which at the moment supports three different methods. Two are wrappers on R’s own methods and a third one, "custom", is designed to use stronger smoothing for values close to zero, where noise in spectral irradiance measurements is proportionally more. The strength of the smoothing and the range of wavelengths operated upon can be adjusted through arguments to parameters. The comment attribute is updated.

smooth_spct(sun.spct)

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

smooth_spct(polyester.spct, method = "supsmu", strength = 2)

## Object: filter_spct [561 x 2]
## Wavelength range 240-800 nm, step 1 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 561 × 2
##   w.length     Tfr
##      <int>   <dbl>
## 1      240 0.00460
## 2      241 0.00453
## 3      242 0.00445
## 4      243 0.00438
## # … with 557 more rows
## # ℹ Use `print(n = ...)` to see more rows

Wavelength interpolation

Converting spectra available at a given set of wavelengths values to a different one, is frequently needed when operating with several spectra of different origin. One can increase the apparent resolution by interpolation, and reduce it by local averaging or smoothing and resampling. The same function works on all spct objects, interpolating every numeric column except w.length which is set to the new wavelength values supplied as argument. The optional argument fill.value controls what value is assigned to the “interpolated” data columns at wavelengths in the new data that are outside the range of wavelengths in the original spectrum being interpolated.

interpolate_wl(sun.spct, seq(400, 500, by = 0.1))

## Object: source_spct [1,001 x 3]
## Wavelength range 400-500 nm, step 0.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
## 
## # A tibble: 1,001 × 3
##   w.length s.e.irrad  s.q.irrad
##      <dbl>     <dbl>      <dbl>
## 1     400      0.608 0.00000203
## 2     400.     0.610 0.00000204
## 3     400.     0.612 0.00000205
## 4     400.     0.614 0.00000205
## # … with 997 more rows
## # ℹ Use `print(n = ...)` to see more rows

Trimming, clipping and thining

clip_wl(sun.spct, range = c(400, 402))

## Object: source_spct [3 x 3]
## Wavelength range 400-402 nm, step 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
## 
## # A tibble: 3 × 3
##   w.length s.e.irrad  s.q.irrad
##      <dbl>     <dbl>      <dbl>
## 1      400     0.608 0.00000203
## 2      401     0.626 0.00000210
## 3      402     0.650 0.00000218

clip_wl(sun.spct, range = c(400, NA))

## Object: source_spct [401 x 3]
## Wavelength range 400-800 nm, step 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
## 
## # A tibble: 401 × 3
##   w.length s.e.irrad  s.q.irrad
##      <dbl>     <dbl>      <dbl>
## 1      400     0.608 0.00000203
## 2      401     0.626 0.00000210
## 3      402     0.650 0.00000218
## 4      403     0.621 0.00000209
## # … with 397 more rows
## # ℹ Use `print(n = ...)` to see more rows

clip_wl(sun.spct, range = UVA.wb)

## Object: source_spct [86 x 3]
## Wavelength range 315-400 nm, step 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
## 
## # A tibble: 86 × 3
##   w.length s.e.irrad   s.q.irrad
##      <dbl>     <dbl>       <dbl>
## 1      315     0.113 0.000000297
## 2      316     0.102 0.000000270
## 3      317     0.149 0.000000394
## 4      318     0.141 0.000000376
## # … with 82 more rows
## # ℹ Use `print(n = ...)` to see more rows

clip_wl(sun.spct, range = c(100, 200))

## Object: source_spct [0 x 3]
## 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
## 
## # A tibble: 0 × 3
## # … with 3 variables: w.length <dbl>, s.e.irrad <dbl>, s.q.irrad <dbl>
## # ℹ Use `colnames()` to see all variable names

trim_wl(sun.spct, c(282.5, NA))

## Object: source_spct [520 x 3]
## Wavelength range 282.5-800 nm, step 0.2692308-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
## 
## # A tibble: 520 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     282.         0         0
## 2     283.         0         0
## 3     284.         0         0
## 4     285.         0         0
## # … with 516 more rows
## # ℹ Use `print(n = ...)` to see more rows

clip_wl(sun.spct, c(282.5, NA))

## Object: source_spct [519 x 3]
## Wavelength range 282.76923-800 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
## 
## # A tibble: 519 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     283.         0         0
## 2     284.         0         0
## 3     285.         0         0
## 4     286.         0         0
## # … with 515 more rows
## # ℹ Use `print(n = ...)` to see more rows

trim_wl(sun.spct, PAR.wb)

## Object: source_spct [301 x 3]
## Wavelength range 400-700 nm, step 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
## 
## # A tibble: 301 × 3
##   w.length s.e.irrad  s.q.irrad
##      <dbl>     <dbl>      <dbl>
## 1      400     0.608 0.00000203
## 2      401     0.626 0.00000210
## 3      402     0.650 0.00000218
## 4      403     0.621 0.00000209
## # … with 297 more rows
## # ℹ Use `print(n = ...)` to see more rows

trim_wl(sun.spct, c(281.5, NA), fill = NA)

## Object: source_spct [524 x 3]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 524 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280         NA        NA
## 2     281.        NA        NA
## 3     281.        NA        NA
## 4     282.         0         0
## # … with 520 more rows
## # ℹ Use `print(n = ...)` to see more rows

trim_wl(sun.spct, c(275, NA), fill = 0)

## Object: source_spct [529 x 3]
## Wavelength range 275-800 nm, step 1.023182e-12-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
## 
## # A tibble: 529 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     275          0         0
## 2     276.         0         0
## 3     277.         0         0
## 4     277.         0         0
## # … with 525 more rows
## # ℹ Use `print(n = ...)` to see more rows

trim_wl(sun.spct, c(281.5, NA), fill = NA)

## Object: source_spct [524 x 3]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 524 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280         NA        NA
## 2     281.        NA        NA
## 3     281.        NA        NA
## 4     282.         0         0
## # … with 520 more rows
## # ℹ Use `print(n = ...)` to see more rows

trim_wl(sun.spct, c(281.5, NA), fill = NA, use.hinges = FALSE)

## Object: source_spct [522 x 3]
## Wavelength range 280-800 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
## 
## # A tibble: 522 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280         NA        NA
## 2     281.        NA        NA
## 3     282.         0         0
## 4     283.         0         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows

trim2overlap(two.mspct)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 08:00:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 09:00:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

extend2extremes(two.mspct, fill = 0)

## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 08:00:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: B ---
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm 
## Label: sunlight, simulated 
## Measured on 2015-10-31 09:00:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
## # A tibble: 522 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 518 more rows
## # ℹ Use `print(n = ...)` to see more rows
## 
## --- END ---

nrow(yellow_gel.spct)

## [1] 611

wl_stepsize(yellow_gel.spct)

## [1] 1 1

thinned.spct <- thin_wl(yellow_gel.spct)
nrow(thinned.spct)

## [1] 267

wl_stepsize(thinned.spct)

## [1] 1 8

Convolving weights

It is very instructive to look at weighted spectral data to understand how effective irradiances are calculated. Plotting effective spectral irradiance data can be very informative when analysing interactions among photoreceptors and ambient radiation. It can also illustrate the large effect that small measuring errors can have on the estimated effective irradiances or exposures when SWFs have a steep slope.

For biologically effective energy irradiance \(E_\mathrm{BE}\) the following equation describes the convolution, wavelength by wavelength, between spectral energy irradiance and a biological spectral weighting function

\[E_\mathrm{BE}(\lambda) = E(\lambda) \times w_E(\lambda)\] or for biologically effective photon irradiance \(Q_\mathrm{BE}\) \[Q_\mathrm{BE}(\lambda) = Q(\lambda) \times w_Q(\lambda)\] For the convolution to be possible, both spectral irradiance and spectral weights should be available for the same basis of expression and at the same discrete wavelength values.

sun.spct * CIE.wb

## 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 'range.250.400.wtd' BSWF
## 
## # A tibble: 122 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     280          0
## 2     281.         0
## 3     282.         0
## 4     283.         0
## # … with 118 more rows
## # ℹ Use `print(n = ...)` to see more rows

Tagging with bands and colours

We call tagging, to the process of adding reference information to spectral data. For example we can add a factor indicating regions or bands in the spectrum. We can add also information on the colour, as seen by humans, for each observed value, or for individual regions or bands of the spectrum. In most cases this additional information is used for annotations when plotting the spectral data.

tag(sun.spct, PAR.wb)

## Object: source_spct [524 x 6]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 524 × 6
##   w.length s.e.irrad s.q.irrad wl.color wb.color wb.f 
##      <dbl>     <dbl>     <dbl> <chr>    <chr>    <fct>
## 1     280          0         0 #000000  <NA>     <NA> 
## 2     281.         0         0 #000000  <NA>     <NA> 
## 3     282.         0         0 #000000  <NA>     <NA> 
## 4     283.         0         0 #000000  <NA>     <NA> 
## # … with 520 more rows
## # ℹ Use `print(n = ...)` to see more rows

tag(sun.spct, UV_bands.lst)

## Object: source_spct [524 x 6]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 524 × 6
##   w.length s.e.irrad s.q.irrad wl.color wb.color wb.f 
##      <dbl>     <dbl>     <dbl> <chr>    <chr>    <fct>
## 1     280          0         0 #000000  black    UVB  
## 2     281.         0         0 #000000  black    UVB  
## 3     282.         0         0 #000000  black    UVB  
## 4     283.         0         0 #000000  black    UVB  
## # … with 520 more rows
## # ℹ Use `print(n = ...)` to see more rows

tg.sun.spct <- tag(sun.spct, PAR.wb)
attr(tg.sun.spct, "spct.tags")

## $valid
## [1] TRUE
## 
## $time.unit
## [1] "second"
## 
## $wb.key.name
## [1] "Bands"
## 
## $wl.color
## [1] TRUE
## 
## $wb.color
## [1] TRUE
## 
## $wb.num
## [1] 1
## 
## $wb.colors
## [1] "#735B57"
## 
## $wb.names
## [1] "PAR"
## 
## $wb.list
## $wb.list[[1]]
## PAR 
## low (nm) 400 
## high (nm) 700 
## weighted none

wb2tagged_spct(UV_bands.lst)

## Object: generic_spct [8 x 12]
## Wavelength range 100-400 nm, step 9.947598e-13-180 nm 
## 
## # A tibble: 8 × 12
##   w.len…¹ counts   cps s.e.i…² s.q.i…³   Tfr   Rfl s.e.r…⁴ wl.co…⁵ wb.co…⁶ wb.f 
##     <dbl>  <dbl> <dbl>   <dbl>   <dbl> <dbl> <dbl>   <dbl> <chr>   <chr>   <fct>
## 1    100.      0     0       0       0     0     0       0 #000000 <NA>    <NA> 
## 2    100       0     0       0       0     0     0       0 #000000 black   UVC  
## 3    280.      0     0       0       0     0     0       0 #000000 black   UVC  
## 4    280       0     0       0       0     0     0       0 #000000 black   UVB  
## # … with 4 more rows, 1 more variable: y <dbl>, and abbreviated variable names
## #   ¹​w.length, ²​s.e.irrad, ³​s.q.irrad, ⁴​s.e.response, ⁵​wl.color, ⁶​wb.color
## # ℹ Use `print(n = ...)` to see more rows, and `colnames()` to see all variable names

wb2rect_spct(UV_bands.lst)

## Object: generic_spct [3 x 15]
## Wavelength range 190-357.5 nm, step 60-107.5 nm 
## 
## # A tibble: 3 × 15
##   w.length counts   cps s.e.irrad s.q.irrad   Tfr   Rfl s.e.re…¹ wl.co…² wb.co…³
##      <dbl>  <dbl> <dbl>     <dbl>     <dbl> <dbl> <dbl>    <dbl> <chr>   <chr>  
## 1     190       0     0         0         0     0     0        0 #000000 black  
## 2     298.      0     0         0         0     0     0        0 #000000 black  
## 3     358.      0     0         0         0     0     0        0 #000000 #02000F
## # … with 5 more variables: wb.name <chr>, wb.f <fct>, wl.high <dbl>,
## #   wl.low <dbl>, y <dbl>, and abbreviated variable names ¹​s.e.response,
## #   ²​wl.color, ³​wb.color
## # ℹ Use `colnames()` to see all variable names

tg.sun.spct

## Object: source_spct [524 x 6]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 524 × 6
##   w.length s.e.irrad s.q.irrad wl.color wb.color wb.f 
##      <dbl>     <dbl>     <dbl> <chr>    <chr>    <fct>
## 1     280          0         0 #000000  <NA>     <NA> 
## 2     281.         0         0 #000000  <NA>     <NA> 
## 3     282.         0         0 #000000  <NA>     <NA> 
## 4     283.         0         0 #000000  <NA>     <NA> 
## # … with 520 more rows
## # ℹ Use `print(n = ...)` to see more rows

is_tagged(tg.sun.spct)

## [1] TRUE

untg.sun.spct <- untag(tg.sun.spct)
is_tagged(untg.sun.spct)

## [1] FALSE

is_tagged(untg.sun.spct)

## [1] FALSE

untag(tg.sun.spct, byref = TRUE)

## Object: source_spct [524 x 3]
## Wavelength range 280-800 nm, step 1.023182e-12-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
## 
## # A tibble: 524 × 3
##   w.length s.e.irrad s.q.irrad
##      <dbl>     <dbl>     <dbl>
## 1     280          0         0
## 2     281.         0         0
## 3     282.         0         0
## 4     283.         0         0
## # … with 520 more rows
## # ℹ Use `print(n = ...)` to see more rows

is_tagged(untg.sun.spct)

## [1] FALSE

Summary

Specialized definitions of summary and the corresponding print methods are available for spectral objects. Attributes "what.measured", "when.measured" and "where.measured" are included in the summary print out only if set in the spectral object summarized.

summary(sun.spct)

## Summary of source_spct [522 x 3] object: sun.spct
## Wavelength range 280-800 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
## 
##     w.length       s.e.irrad        s.q.irrad        
##  Min.   :280.0   Min.   :0.0000   Min.   :0.000e+00  
##  1st Qu.:409.2   1st Qu.:0.4115   1st Qu.:1.980e-06  
##  Median :539.5   Median :0.5799   Median :2.929e-06  
##  Mean   :539.5   Mean   :0.5160   Mean   :2.407e-06  
##  3rd Qu.:669.8   3rd Qu.:0.6664   3rd Qu.:3.154e-06  
##  Max.   :800.0   Max.   :0.8205   Max.   :3.375e-06

summary(two_suns.spct)

## Summary of source_spct [1,044 x 4] object: two_suns.spct
## containing  2  spectra in long form
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## a label: sunlight, simulated
## b label: sunlight, simulated 
## a measured on 2010-06-22 09:51:00 UTC
## b measured on 2010-06-22 09:51:00 UTC 
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
## Time unit 1s
## 
##     w.length       s.e.irrad      spct.idx   s.q.irrad        
##  Min.   :280.0   Min.   :0.0000   a:522    Min.   :0.000e+00  
##  1st Qu.:409.0   1st Qu.:0.2471   b:522    1st Qu.:1.159e-06  
##  Median :539.5   Median :0.3494            Median :1.580e-06  
##  Mean   :539.5   Mean   :0.3870            Mean   :1.806e-06  
##  3rd Qu.:670.0   3rd Qu.:0.5799            3rd Qu.:2.928e-06  
##  Max.   :800.0   Max.   :0.8205            Max.   :3.375e-06

Wavelength

wl_range(sun.spct)

## [1] 280 800

wl_min(sun.spct)

## [1] 280

wl_max(sun.spct)

## [1] 800

wl_midpoint(sun.spct)

## [1] 540

wl_expanse(sun.spct)

## [1] 520

wl_stepsize(sun.spct)

## [1] 0.9230769 1.0000000

filters.mspct <- filter_mspct(list(none = clear.spct,
                                   pet = polyester.spct,
                                   yellow = yellow_gel.spct))
wl_range(filters.mspct)

## # A tibble: 3 × 3
##   spct.idx min.wl max.wl
##   <fct>     <dbl>  <dbl>
## 1 none        100   5000
## 2 pet         240    800
## 3 yellow      190    800

Peaks, valleys and spikes

Peaks and valleys in spectra are usually features of interest, while in most cases spikes (very narrow peaks or valleys) are undesired “noise”. Of course, there are exceptions and for this reason methods used for extract any of these features have a similar interface.

Peaks and valleys can be identified simply as local maxima and minima, or their actual location better estimated by fitted a model to the local maximum or minimum and its neighbours.

peaks(sun.spct, span = 51)

## Object: source_spct [3 x 2]
## Wavelength range 451-747 nm, step 44-252 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
## 
## # A tibble: 3 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1      451     0.820
## 2      495     0.790
## 3      747     0.503

valleys(sun.spct, span = 51)

## Object: source_spct [9 x 2]
## Wavelength range 358-761 nm, step 30-72 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
## 
## # A tibble: 9 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1      358     0.254
## 2      393     0.242
## 3      431     0.414
## 4      487     0.651
## # … with 5 more rows
## # ℹ Use `print(n = ...)` to see more rows

peaks(white_led.source_spct, 
      span = 101, 
      unit.out = "photon")$w.length

## [1] 455.48 608.62

peaks(white_led.source_spct, 
      span = 101, 
      unit.out = "photon", 
      refine.wl = TRUE)$w.length

## [1] 455.3068 608.8524

peaks(sun.spct, span = 21)

## Object: source_spct [18 x 2]
## Wavelength range 354-774 nm, step 11-51 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
## 
## # A tibble: 18 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1      354     0.376
## 2      366     0.449
## 3      378     0.497
## 4      416     0.676
## # … with 14 more rows
## # ℹ Use `print(n = ...)` to see more rows

peaks(sun.spct, span = NULL)

## Object: source_spct [1 x 2]
## Wavelength range 451-451 nm, step NA 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
## 
## # A tibble: 1 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1      451     0.820

peaks(sun.spct, span = NULL, refine.wl = TRUE)

## Object: source_spct [1 x 2]
## Wavelength range 451.02685-451.02685 nm, step NA 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
## 
## # A tibble: 1 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1     451.     0.821

spikes(sun.spct)

## Object: source_spct [2 x 2]
## Wavelength range 398-432 nm, step 34 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
## 
## # A tibble: 2 × 2
##   w.length s.e.irrad
##      <dbl>     <dbl>
## 1      398     0.504
## 2      432     0.646

msmsply(filters.mspct, peaks, span = 21)

## Object: filter_mspct [3 x 1]
## --- Member: none ---
## Object: filter_spct [0 x 5]
## Label: theoretical fully transparent object 
## Transmittance of type 'internal'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 0 × 5
## # … with 5 variables: w.length <dbl>, Tfr <dbl>, Rfr.constant <dbl>,
## #   thickness <dbl>, attenuation.mode <chr>
## # ℹ Use `colnames()` to see all variable names
## --- Member: pet ---
## Object: filter_spct [3 x 2]
## Wavelength range 451-714 nm, step 102-161 nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 3 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      451 0.925
## 2      612 0.918
## 3      714 0.913
## --- Member: yellow ---
## Object: filter_spct [5 x 2]
## Wavelength range 331-768 nm, step 23-293 nm 
## Label: yellow theatrical 'gel', Rosco supergel no. 312, 'canary yellow' 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.085, attenuation mode: absorption.
## 
## # A tibble: 5 × 2
##   w.length     Tfr
##      <int>   <dbl>
## 1      331 0.00471
## 2      624 0.898  
## 3      708 0.900  
## 4      731 0.901  
## 5      768 0.902  
## 
## --- END ---

Wavelengths at target value

Method wls_at_target takes a spectrum as first argument and returns a subset of the spectral object data or a new object corresponding to wavelengths at which the spectrum is at the target value. Geometrically is equivalent to finding the wavelengths at which a horizontal target line intercepts the curve depicting the spectrum.

wls_at_target(Ler_leaf_trns.spct, target = "half.maximum")

## Object: filter_spct [1 x 2]
## Wavelength range 709.35352-709.35352 nm, step NA nm 
## Label: Ler_06_black.spct 
## Measured on 2017-07-03 13:18:18 UTC 
## Transmittance of type 'total'
## 
## # A tibble: 1 × 2
##   w.length   Tfr
##      <dbl> <dbl>
## 1     709. 0.222

wls_at_target(Ler_leaf_trns.spct, target = "half.maximum", interpolate = TRUE)

## Object: filter_spct [1 x 2]
## Wavelength range 709.50991-709.50991 nm, step NA nm 
## Label: Ler_06_black.spct 
## Measured on 2017-07-03 13:18:18 UTC 
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 1 × 2
##   w.length   Tfr
##      <dbl> <dbl>
## 1     710. 0.224

This function can be used with all spectral classes defined in the package. In the case of source_spct and response_spct methods parameter unit.out allows to switch between energy and photon units for the search and returned value, while in the case of filter_spct methods filter.qty` allows to switch between transmittance, absorptance and absorbance.

wls_at_target(filters.mspct, target = "half.maximum")

## Object: filter_mspct [3 x 1]
## --- Member: none ---
## Object: filter_spct [0 x 2]
## Transmittance of type 'total'
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## 
## # A tibble: 0 × 2
## # … with 2 variables: w.length <dbl>, Tfr <dbl>
## # ℹ Use `colnames()` to see all variable names
## --- Member: pet ---
## Object: filter_spct [1 x 2]
## Wavelength range 322-322 nm, step NA nm 
## Label: clear polyester film 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.125, attenuation mode: absorption.
## 
## # A tibble: 1 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      322 0.462
## --- Member: yellow ---
## Object: filter_spct [1 x 2]
## Wavelength range 509-509 nm, step NA nm 
## Label: yellow theatrical 'gel', Rosco supergel no. 312, 'canary yellow' 
## Transmittance of type 'total'
## Rfr (/1): 0.07, thickness (mm): 0.085, attenuation mode: absorption.
## 
## # A tibble: 1 × 2
##   w.length   Tfr
##      <int> <dbl>
## 1      509 0.457
## 
## --- END ---

Irradiance

Energy irradiance is the integral over wavelengths of spectral energy irradiance

\[E = \int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda)\ \mathrm{d}\lambda\] where \(\lambda_1 \geq \lambda > \lambda_2\) defines a waveband, or range of wavelengths.

Photon (=quantum) irradiance is the integral over wavelengths of spectral photon irradiance.

\[Q = \int_{\lambda = \lambda_1}^{\lambda = \lambda_2} Q(\lambda)\ \mathrm{d}\lambda\] Spectrally weighted (or biologically effective) energy irradiance is the integral of the result of the convolution of spectral energy irradiance by a spectral weighting function \(w(\lambda)\).

\[E_{BE} = \int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda) \cdot w_E(\lambda)\ \mathrm{d}\lambda\] Spectrally weighted (or effective) photon irradiance can be computed similarly with the corresponding weighting function \(w_Q(\lambda)\).

e_irrad(sun.spct)

##  E_Total 
## 269.1249 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

e_irrad(sun.spct, PAR.wb)

##    E_PAR 
## 196.6343 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

e_irrad(sun.spct, c(400, 700))

## E_range.400.700 
##        196.6343 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

q_irrad(sun.spct, PAR.wb, scale.factor = 1e6) # umol s-1 m-2

##    Q_PAR 
## 894.1352 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

q_irrad(white_led.source_spct, PAR.wb, time.unit = "hour")

##    Q_PAR 
## 1.584957 
## attr(,"time.unit")
## [1] "hour"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

e_irrad(sun.daily.spct, PAR.wb, time.unit = "second")

##    E_PAR 
## 92.16251 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

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

##      E_UVB      E_UVA 
##  0.6445105 27.9842061 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

q_irrad(sun.spct, UV_bands.lst) # mol s-1 m-2

##        Q_UVB        Q_UVA 
## 1.675362e-06 8.481970e-05 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

q_irrad(sun.spct, UV_bands.lst, scale.factor = 1e6) # umol s-1 m-2

##     Q_UVB     Q_UVA 
##  1.675362 84.819697 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

e_irrad(sun.spct, UV_bands.lst, quantity = "total") # watt m-2

##      E_UVB      E_UVA 
##  0.6445105 27.9842061 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

e_irrad(sun.spct, UV_bands.lst, quantity = "average") # watt m-2 nm-1

##  E(wl)_UVB  E(wl)_UVA 
## 0.01841458 0.32922595 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "average energy irradiance"

e_irrad(sun.spct, UV_bands.lst, quantity = "contribution")

##  E/Etot_UVB  E/Etot_UVA 
## 0.002394838 0.103982226 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "contribution energy irradiance"

e_irrad(sun.spct, UV_bands.lst, quantity = "relative")

## E/Esum_UVB E/Esum_UVA 
## 0.02251273 0.97748727 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "relative energy irradiance"

e_irrad(sun.spct, UV_bands.lst, quantity = "contribution.pc")

## E/Etot_UVB E/Etot_UVA 
##  0.2394838 10.3982226 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "contribution.pc energy irradiance"

e_irrad(sun.spct, UV_bands.lst, quantity = "relative.pc")

## E/Esum_UVB E/Esum_UVA 
##   2.251273  97.748727 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "relative.pc energy irradiance"

e_irrad(sun.spct, PAR.wb, time.unit = duration(8, "hours"))

##   E_PAR 
## 5663067 
## attr(,"time.unit")
## [1] "28800s (~8 hours)"
## attr(,"radiation.unit")
## [1] "total energy irradiance"

e_fluence(sun.spct, PAR.wb, exposure.time = duration(8, "hours"))

##   E_PAR 
## 5663067 
## attr(,"radiation.unit")
## [1] "energy fluence (J m-2)"
## attr(,"exposure.duration")
## [1] "28800s (~8 hours)"

q_irrad(sun.spct, UV_bands.lst, naming = "short")

##          UVB          UVA 
## 1.675362e-06 8.481970e-05 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

q_irrad(sun.spct, UV_bands.lst, naming = "none")

## [1] 1.675362e-06 8.481970e-05
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

names(UV_bands.lst) <- c("UV-C", "UV-B", "UV-A")
q_irrad(sun.spct, UV_bands.lst, naming = "short", scale.factor = 1e6)

##      UV-B      UV-A 
##  1.675362 84.819697 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"

two_suns.mspct <- source_mspct(list(sun1 = sun.spct, sun2 = sun.spct * 2))

e_irrad(two_suns.mspct, w.band = PAR.wb)

## # A tibble: 2 × 2
##   spct.idx E_PAR
##   <fct>    <dbl>
## 1 sun1      197.
## 2 sun2      393.

q_irrad(two_suns.mspct, 
        w.band = PAR.wb,
        scale.factor = 1e6, # umol m-2 s-1
        attr2tb = c(when.measured = "time", lon = "lon", lat = "lat"))

## # A tibble: 2 × 5
##   spct.idx Q_PAR time                  lon   lat
##   <fct>    <dbl> <dttm>              <dbl> <dbl>
## 1 sun1      894. 2010-06-22 09:51:00  25.0  60.2
## 2 sun2     1788. 2010-06-22 09:51:00  25.0  60.2

filtered_sun <- convolve_each(filters.mspct, sun.spct)
q_irrad(filtered_sun,
        list(UVA.wb, PAR.wb),
        scale.factor = 1e6,
        idx = "Filter")

## # A tibble: 3 × 3
##   Filter  Q_UVA Q_PAR
##   <fct>   <dbl> <dbl>
## 1 none   84.8    894.
## 2 pet    70.2    823.
## 3 yellow  0.105  536.

q_irrad(convolve_each(filters.mspct, sun.spct), 
        list("UV-A" = UVA.wb, PAR.wb),
        scale.factor = 1e6,  # umol m-2 s-1
        naming = "short",
        attr2tb = c(what.measured = "Filter type"))[ , c(4, 2, 3)]

## # A tibble: 3 × 3
##   `Filter type`                                                    `UV-A`   PAR
##   <chr>                                                             <dbl> <dbl>
## 1 theoretical fully transparent object                             84.8    894.
## 2 clear polyester film                                             70.2    823.
## 3 yellow theatrical 'gel', Rosco supergel no. 312, 'canary yellow'  0.105  536.

Fluence

Energy fluence is energy irradiance integrated over a lapse of time or event, and is expressed as energy per area.

Energy fluence is the integral over wavelengths and time of spectral energy irradiance

\[F_E = \int_{\lambda = \lambda_1}^{\lambda = \lambda_2} \int_{t = t_1}^{t = t_2} E(\lambda)\ \mathrm{d}\lambda\,\mathrm{d}t\] where \(\lambda_1 \geq \lambda > \lambda_2\) defines a waveband, or range of wavelengths, and \(t_1 \geq t > t_2\).

However, if we assume that irradiance does not vary in time it simplifies to \[F_E = \Delta t\times\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda)\ \mathrm{d}\lambda\] where \(\Delta t = t_2 - t_1\).

The equivalent equation for photon fluence is \[F_Q = \Delta t\times\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} Q(\lambda)\ \mathrm{d}\lambda\]

Spectrally weighted (or effective) energy fluence is the integral over wavelengths and time of the result of the convolution of spectral energy irradiance by a spectral weight function \(w(\lambda)\). Assuming that spectral irradiance does not vary with time the corresponding equation is

\[F_{E_{BE}} = \Delta t\times\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda) \times w_E(\lambda)\ \mathrm{d}\lambda\]

Spectrally weighted (or effective) photon fluence can be computed similarly with the corresponding weighting function \(w_Q(\lambda)\).

fluence(sun.spct, exposure.time = duration(1, "hours"))

##  E_Total 
## 968849.6 
## attr(,"radiation.unit")
## [1] "energy fluence (J m-2)"
## attr(,"exposure.duration")
## [1] "3600s (~1 hours)"

fluence(sun.spct, exposure.time = 3600) # seconds

## converting 'time.unit' 3600 into a lubridate::duration

##  E_Total 
## 968849.6 
## attr(,"radiation.unit")
## [1] "energy fluence (J m-2)"
## attr(,"exposure.duration")
## [1] 3600

q_fluence(sun.spct, PAR.wb, exposure.time = duration(25, "minutes"))

##    Q_PAR 
## 1.341203 
## attr(,"radiation.unit")
## [1] "photon fluence (mol m-2)"
## attr(,"exposure.duration")
## [1] "1500s (~25 minutes)"

Photon and energy ratios

A way to summarize the “colour” of light is to compute a ratio between irradiances computed for two different wavebands of the same spectrum. They can be computed either on an energy or photon (quantum) basis, and although not a requirement, use of two wavelength bands with the same expanse is usually most informative. Photon ratios are usually preferred compared to energy ratios in work related to photobiology and photochemistry.

\[Q_1 : Q_2 = \frac{\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} Q(\lambda)\ \mathrm{d}\lambda} {\int_{\lambda = \lambda_3}^{\lambda = \lambda_4} Q(\lambda)\ \mathrm{d}\lambda}\]

where \(\lambda_1 \geq \lambda > \lambda_2\) defines the waveband for the numerator and \(\lambda_3 \geq \lambda > \lambda_4\) defines the waveband for the denominator, i.e., two ranges of wavelengths.

Energy ratios are computed similarly

\[E_1 : E_2 = \frac{\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda)\ \mathrm{d}\lambda} {\int_{\lambda = \lambda_3}^{\lambda = \lambda_4} E(\lambda)\ \mathrm{d}\lambda}\]

where \(\lambda_1 \geq \lambda > \lambda_2\) defines the waveband for the numerator and \(\lambda_3 \geq \lambda > \lambda_4\) defines the waveband for the denominator, i.e., two ranges of wavelengths.

An energy irradiance to photon irradiance ratio describes the average energy per mol of photon for a waveband or range of wavelengths.

\[E : Q = \frac{\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda)\ \mathrm{d}\lambda} {\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} Q(\lambda)\ \mathrm{d}\lambda}\]

where \(\lambda_1 \geq \lambda > \lambda_2\) defines a waveband, or range of wavelengths.

We can compute the photon to energy ratio (\(Q : E\)) similarly.

Although all these ratios are usually computed without use of spectral weighting functions, their computation can be easily done by including in the equations above a weighting functions (\(w(\lambda)\)) as described in the section on irradiance.

q_ratio(sun.spct, UVB.wb, PAR.wb)

## UVB:PAR[q:q] 
##  0.001873724 
## attr(,"radiation.unit")
## [1] "q:q ratio"

q_ratio(sun.spct, list(UVC.wb, UVB.wb, UVA.wb))

## UVB:Total[q:q] UVA:Total[q:q] 
##    0.001334593    0.067567343 
## attr(,"radiation.unit")
## [1] "q:q ratio"

q_ratio(sun.spct, list(UVC.wb, UVB.wb, UVA.wb), PAR.wb)

## UVB:PAR[q:q] UVA:PAR[q:q] 
##  0.001873724  0.094862270 
## attr(,"radiation.unit")
## [1] "q:q ratio"

qe_ratio(sun.spct,
         list("UV-B" = UVB.wb, PAR.wb), 
         scale.factor = 1e6,
         name.tag = " (umol/J)")

## UV-B (umol/J)  PAR (umol/J) 
##      2.599434      4.547199 
## attr(,"radiation.unit")
## [1] "q:e ratio"

q_ratio(filtered_sun, 
        list(UVB.wb, UVA.wb),
        PAR.wb)

## # A tibble: 3 × 3
##   spct.idx `UVB:PAR[q:q]` `UVA:PAR[q:q]`
##   <fct>             <dbl>          <dbl>
## 1 none         0.00187          0.0949  
## 2 pet          0.0000720        0.0853  
## 3 yellow       0.00000387       0.000196

q_ratio(filtered_sun, 
        list(UVB.wb, UVA.wb),
        PAR.wb, 
        scale.factor = 100, 
        name.tag = " (% photons)", 
        idx = "Filter")

## # A tibble: 3 × 3
##   Filter `UVB:PAR (% photons)` `UVA:PAR (% photons)`
##   <fct>                  <dbl>                 <dbl>
## 1 none                0.187                   9.49  
## 2 pet                 0.00720                 8.53  
## 3 yellow              0.000387                0.0196

Transmittance, reflectance, absorptance and absorbance

Given the laws of conservation of energy, transmittance, reflectance and absorptance, expressed as fractions, always add up to one.

\[1 = R_\mathrm{fr,total} + A_\mathrm{fr,total} + T_\mathrm{fr,total}\] Transmittance can be defined either as the fraction of the radiation “entering” an object that is transmitted, called internal transmittance (\(T_\mathrm{fr,internal}\)) or as the fraction of the ration incident on an object that is transmitted (\(T_\mathrm{fr,total}\)).

\[1 \times R_\mathrm{fr,total} = A_\mathrm{fr,internal} + T_\mathrm{fr,internal}\] giving

\[T_\mathrm{fr,internal} = T_\mathrm{fr,total} / R_\mathrm{fr,total}\] and \[A_\mathrm{fr,internal} = T_\mathrm{fr,total} / R_\mathrm{fr,total}\] In the case of reflectance, “total” has a different meaning, and refers to whether all reflected light or that an specific angle in considered.

In practice, both definitions of transmittance and absorptance are in use, while as it is easier to measure total- than internal transmittance, internal transmittance allows the computation of transmittance for different thickness of a material.

Consequently, absorptance can be computed as:

\[A_\mathrm{fr,internal} = 1 - T_\mathrm{fr,internal}\] or as

\[A_\mathrm{fr,total} = 1 - T_\mathrm{fr,total} - R_\mathrm{fr,total}\] Absorbance, is a log transformed quantity that tends to be used when the range of values spans several orders of magnitude. It is frequently based on internal absorptance, but can be also based on total absorptance.

\[A_\mathrm{internal} = -\log_{10}(1 -A_\mathrm{fr,internal}) = -\log_{10}(T_\mathrm{fr,internal}) \] and

\[A_\mathrm{total} = -\log_{10}(1 - A_\mathrm{fr,total}) = -\log_{10}(T_\mathrm{fr,total} + R_\mathrm{fr,total})\] When using a spectrophotometer, if our reference is a cuvette with pure solvent and the sample a solution of a compound in the same solvent we measure internal transmittance, absorptance or absorbance. If we instead measure the transmittance of a piece of glass or plastic with air as reference, we measure total transmittance, absorptance or absorbance. This is so because in the first case the reference is the light transmitted after the reflectance on the cuvette walls has taken place while in the second case the reflections at the glass-air interfaces are missing from the reference.

As a result of these different definitions, the implementation of the class filter_spct() and object_spct and their methods, need to keep track of whether quantities are expressed as internal or total. As in many glasses reflectance varies very weakly with wavelength, storing a constant value for \(R_\mathrm{fr,total}\) is also supported. The refractive index of a material can also be used to estimate \(R_\mathrm{fr,total}\) for a polished surface. Lack of a value for \(R_\mathrm{fr,total}\) can make some conversions and computations impossible.

transmittance(polyester.spct, list(UVB.wb, UVA.wb, PAR.wb))

## Tfr(wl)_UVB Tfr(wl)_UVA Tfr(wl)_PAR 
## 0.009722449 0.781851261 0.920239286 
## attr(,"Tfr.type")
## [1] "unknown"
## attr(,"radiation.unit")
## [1] "transmittance average"

transmittance(polyester.spct, 
              list(UVB.wb, UVA.wb, PAR.wb),
              naming = "none")

## [1] 0.009722449 0.781851261 0.920239286
## attr(,"Tfr.type")
## [1] "unknown"
## attr(,"radiation.unit")
## [1] "transmittance average"

transmittance(polyester.spct, 
              list(UVB.wb, UVA.wb, PAR.wb),
              naming = "short")

##         UVB         UVA         PAR 
## 0.009722449 0.781851261 0.920239286 
## attr(,"Tfr.type")
## [1] "unknown"
## attr(,"radiation.unit")
## [1] "transmittance average"

reflectance(green_leaf.spct, waveband(c(600, 700)))

## Rfr(wl)_range.600.700 
##              0.089647 
## attr(,"Rfr.type")
## [1] "unknown"
## attr(,"radiation.unit")
## [1] "reflectance average"

transmittance(filters.mspct, 
              w.band = list(UVA.wb, PAR.wb))

## # A tibble: 3 × 3
##   spct.idx `Tfr(wl)_UVA` `Tfr(wl)_PAR`
##   <fct>            <dbl>         <dbl>
## 1 none           1.00            1.00 
## 2 pet            0.782           0.920
## 3 yellow         0.00160         0.566

transmittance(filters.mspct, 
              w.band = list(UVA.wb, PAR.wb),
              naming = "short")

## # A tibble: 3 × 3
##   spct.idx     UVA   PAR
##   <fct>      <dbl> <dbl>
## 1 none     1.00    1.00 
## 2 pet      0.782   0.920
## 3 yellow   0.00160 0.566

transmittance(filters.mspct, 
              w.band = list("UV-A" = UVA.wb, PAR = PAR.wb))

## # A tibble: 3 × 3
##   spct.idx `Tfr(wl)_UV-A` `Tfr(wl)_PAR`
##   <fct>             <dbl>         <dbl>
## 1 none            1.00            1.00 
## 2 pet             0.782           0.920
## 3 yellow          0.00160         0.566

transmittance(filters.mspct, 
              w.band = list(UVA = UVA.wb, PAR = PAR.wb),
              naming = "short")

## # A tibble: 3 × 3
##   spct.idx     UVA   PAR
##   <fct>      <dbl> <dbl>
## 1 none     1.00    1.00 
## 2 pet      0.782   0.920
## 3 yellow   0.00160 0.566

transmittance(filters.mspct, 
              w.band = UVA.wb,
              naming = "short",
              attr2tb = c("what.measured" = "Filter type"))

## # A tibble: 3 × 3
##   spct.idx     UVA `Filter type`                                                
##   <fct>      <dbl> <chr>                                                        
## 1 none     1.00    theoretical fully transparent object                         
## 2 pet      0.782   clear polyester film                                         
## 3 yellow   0.00160 yellow theatrical 'gel', Rosco supergel no. 312, 'canary yel…

transmittance(filters.mspct,
              w.band = UVA.wb,
              attr2tb = "what.measured")[ , c(3, 2)]

## # A tibble: 3 × 2
##   what.measured                                                    `Tfr(wl)_UVA`
##   <chr>                                                                    <dbl>
## 1 theoretical fully transparent object                                   1.00   
## 2 clear polyester film                                                   0.782  
## 3 yellow theatrical 'gel', Rosco supergel no. 312, 'canary yellow'       0.00160

Normalized difference indexes

Like the ratios discussed above normalized differences are a way of summarizing or describing the colour of light sources or objects independently of the overall irradiance. As their name tells, they are defined as differences relative to a sum.

Normalized difference indexes are used to summarize the spectral characteristics of light or objects. They are most frequently used in the analysis of spectral reflectance data in remote sensing.

\[NDI_{a, b} = \frac{R_a - R_b}{R_a + R_b}\]

where \(R_a\) and \(R_b\) are reflectances computed from the same spectrum using two different wavebands.

The most frequently used NDI is the NDVI or normalized difference vegetation index, which compares reflectance in the red and far-red regions as a way of assessing the presence of vegetation vs. bare land in remote sensing imagery.

However, they can be computed based on energy or photon irradiances for two wavebands as shown here, or for any other spectral quantity.

\[NDI_{a, b} = \frac{Q_a - Q_b}{Q_a + Q_b}\]

where \(Q_a\) and \(Q_b\) are irradiances computed from the same spectrum using two different wavebands.

Although we here describe how to compute normalized difference indexes from spectral data, they are most frequently generated from data from broad-band sensors in satellite, air-borne or terrestrial imagers. To reconstruct from spectral data indexes computed from these instruments we need to use waveband definitions that mimic the spectral response of the imager of interest. Package ‘photobiologyWavebands’ provides pre-defined wavebands for several different satellite imagers as well as for wavelength ranges in common use.

normalized_diff_ind(Ler_leaf_rflt.spct,
                    waveband(c(740, 840)), waveband(c(590, 690)),
                    reflectance)

## NDI reflectance [740.840] - [590.690] 
##                             0.7653852

normalized_diff_ind(sun.spct,
                    waveband(c(600, 700)), waveband(c(400, 500)),
                    q_irrad)

## NDI q_irrad [600.700] - [400.500] 
##                        0.09188363

Integrated response

As with other spectral quantities, we can integrate over wavelengths spectral responsiveness. In response and action spectra the quantity is a response measured in some arbitrary unit expressed per unit wavelengths and per unit energy or quantum.

\[X_E = \int_{\lambda = \lambda_1}^{\lambda = \lambda_2} X_E(\lambda)\ \mathrm{d}\lambda\] where \(\lambda_1 \geq \lambda > \lambda_2\) defines a waveband, or range of wavelengths.

The conversion between energy and photon (= quantum) basis of expression is possible as it is for radiation spectra. Depending on the base of expression the returned integrated value is computed assuming either a light source with a flat spectral energy irradiance of 1 or spectral photon irradiance of 1, respectively.

response(photodiode.spct)

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

e_response(photodiode.spct, list(UVB.wb, UVA.wb))

## R[/e]_]UVB  R[/e]_UVA 
##   0.346462   5.981818 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"

sensors <- response_mspct(list(GaAsP = photodiode.spct,
                               CCD = ccd.spct))
response(sensors, list(UVB.wb, UVA.wb, PAR.wb), quantity = "contribution")

## # A tibble: 2 × 4
##   spct.idx `R/Rtot[/e]_]UVB` `R/Rtot[/e]_UVA` `R/Rtot[/e]_PAR[`
##   <fct>                <dbl>            <dbl>             <dbl>
## 1 GaAsP               0.0142           0.245              0.741
## 2 CCD                 0.0215           0.0634             0.411

Integration over wavelengths

When we need to integrate some numeric variable stored in a spectral object we can use functions integrate_spct or average_spct.

integrate_spct(sun.spct)

##      e.irrad      q.irrad 
## 2.691249e+02 1.255336e-03

average_spct(sun.spct)

##      e.irrad      q.irrad 
## 5.175479e-01 2.414107e-06