User Guide

Introduction

This package, is a data only package, part of a suite, which has package ‘photobiology’ at its core. Please visit (https://www.r4photobiology.info/) for more details. For information on plotting spectra, please consult the documentation for package ‘ggspectra’, and for information on the calculation of summaries and maths operations between spectra, please, consult the documentation for package ‘photobiology’. As package ‘ggspectra’ is only suggested, in this vignette it is loaded an used conditionally on its availability.

library(photobiology)
library(photobiologyWavebands)
library(photobiologySun)
library(lubridate)
eval_plots <- requireNamespace("ggspectra", quietly = TRUE)
if (eval_plots) library(ggspectra)
theme_set(theme_bw())

One collection of spectra, sun_reference.mspct, contains published reference solar spectra used in model simulations and for calculations. Another collection, gap.mspct contains a rapid sequence of spectra measured in a forest gap. Another two time series of simulated hourly spectra sun_hourly_june.spct and sun_hourly_august.spct, are each in the format of a single spectral object. Other measured spectra is inlcuded, as well as energy- and photon-irradiance time series from broadband sensors.

Accessing individual spectra

The source_spct member objects in sun_reference.mspct and gap.mspct can be accessed through their names or through a numeric index. As the numeric indexes are likely to change with updates to the package, their use is discouraged. Names as character strings should be used instead. They can also be retrieved with method names().

names(sun_reference.mspct)
#> [1] "ASTM.E490.AM0"    "ASTM.G173.direct" "ASTM.G173.global" "Gueymard.AM0"    
#> [5] "WMO.Wehrli.AM0"

We can use a character string as index to extract an individual source_spct object.

sun_reference.mspct$Gueymard.AM0
#> Object: source_spct [2,002 x 2]
#> Wavelength range 280-4000 nm, step 0.5-5 nm 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 2,002 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280      0.082
#>  2     280.     0.099
#>  3     281      0.15 
#>  4     282.     0.212
#>  5     282      0.267
#>  6     282.     0.303
#>  7     283      0.325
#>  8     284.     0.323
#>  9     284      0.299
#> 10     284.     0.250
#> # ℹ 1,992 more rows
sun_reference.mspct[["Gueymard.AM0"]]
#> Object: source_spct [2,002 x 2]
#> Wavelength range 280-4000 nm, step 0.5-5 nm 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 2,002 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280      0.082
#>  2     280.     0.099
#>  3     281      0.15 
#>  4     282.     0.212
#>  5     282      0.267
#>  6     282.     0.303
#>  7     283      0.325
#>  8     284.     0.323
#>  9     284      0.299
#> 10     284.     0.250
#> # ℹ 1,992 more rows

Be aware that according to R’s rules, using single square brackets will return a source_mspct object possibly of length one. This statement is not equivalent to the one in the chunk immediately above.

sun_reference.mspct["Gueymard.AM0"]
#> Object: source_mspct [1 x 1]
#> --- Member: Gueymard.AM0 ---
#> Object: source_spct [2,002 x 2]
#> Wavelength range 280-4000 nm, step 0.5-5 nm 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 2,002 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280      0.082
#>  2     280.     0.099
#>  3     281      0.15 
#>  4     282.     0.212
#>  5     282      0.267
#>  6     282.     0.303
#>  7     283      0.325
#>  8     284.     0.323
#>  9     284      0.299
#> 10     284.     0.250
#> # ℹ 1,992 more rows
#> 
#> --- END ---

Accessing subsets of spectra

We can subset sensors.mspct object by indexing with vectors of character strings. More generally one can search for matching names within the collection of spectra.

sun_reference.mspct[grep("AM0", names(sun_reference.mspct), ignore.case = TRUE)]
#> Object: source_mspct [3 x 1]
#> --- Member: ASTM.E490.AM0 ---
#> Object: source_spct [1,697 x 2]
#> Wavelength range 119.5-1e+06 nm, step 1-6e+05 nm 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 1,697 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     120. 0.0000619
#>  2     120. 0.000561 
#>  3     122. 0.00490  
#>  4     122. 0.00118  
#>  5     124. 0.0000477
#>  6     124. 0.0000343
#>  7     126. 0.0000288
#>  8     126. 0.0000352
#>  9     128. 0.0000213
#> 10     128. 0.0000173
#> # ℹ 1,687 more rows
#> --- Member: Gueymard.AM0 ---
#> Object: source_spct [2,002 x 2]
#> Wavelength range 280-4000 nm, step 0.5-5 nm 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 2,002 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280      0.082
#>  2     280.     0.099
#>  3     281      0.15 
#>  4     282.     0.212
#>  5     282      0.267
#>  6     282.     0.303
#>  7     283      0.325
#>  8     284.     0.323
#>  9     284      0.299
#> 10     284.     0.250
#> # ℹ 1,992 more rows
#> --- Member: WMO.Wehrli.AM0 ---
#> Object: source_spct [920 x 2]
#> Wavelength range 199.5-10075 nm, step 0.1-2290 nm 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 920 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     200.     0.005
#>  2     200.     0.007
#>  3     202.     0.007
#>  4     202.     0.008
#>  5     204.     0.009
#>  6     204.     0.009
#>  7     206.     0.01 
#>  8     206.     0.01 
#>  9     208.     0.011
#> 10     208.     0.015
#> # ℹ 910 more rows
#> 
#> --- END ---

Plotting the spectra

Using autoplot() methods for spectra defined in package ‘ggspectra’ annotated plotting is automatic. The defaults can be easily changed, please see the documentation in package ‘ggspectra’.

autoplot(gap.mspct$spct.01)

Using the ggplot() method for spectra from package ‘ggspectra’ plus geometries and statistics from package ‘ggplot2’ we gain additional control on the design.

ggplot(gap.mspct$spct.01, unit.out = "photon") +
  geom_line(linetype = "dashed")

In the case of spectral objects containing a time series of spectra, the index variable UTC containing time and date in universal time coordinates (“UTC”) can be used to select and/or highlight individual spectra.

autoplot(sun_hourly_august.spct, unit.out = "photon")

Using the data in other contexts

As source_spct is a class derived from list, and source_spct is derived from tibble::tible which is a compatible reimplementation of data.frame the data can be used very easily with any R function.

head(as.data.frame(gap.mspct$spct.01))
#>   w.length s.e.irrad
#> 1   250.22         0
#> 2   250.69         0
#> 3   251.17         0
#> 4   251.64         0
#> 5   252.12         0
#> 6   252.59         0

Of course attach and with also work as expected.

attach(gap.mspct)
q_irrad(gap.mspct$spct.01, Red())
#>    Q_Red.ISO 
#> 0.0004767459 
#> attr(,"time.unit")
#> [1] "second"
#> attr(,"radiation.unit")
#> [1] "total photon irradiance"
detach(gap.mspct)
attach(gap.mspct)
with(spct.01, max(w.length))
#> [1] 899.86
detach(gap.mspct)
with(gap.mspct, q_response(spct.01, Red()))
#> Warning in q_response.default(spct.01, Red()): 'q_response' is not defined for
#> objects of class source_spct
#> [1] NA