User Guide
Package ‘photobiologySun’ 0.5.0
Pedro J. Aphalo
2024-04-01
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’.
library(photobiology)
library(photobiologyWavebands)
library(photobiologySun)
library(lubridate)
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
## Time unit 1s
##
## # 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
## Time unit 1s
##
## # 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
## Time unit 1s
##
## # 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
## Time unit 1s
##
## # 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
## Time unit 1s
##
## # 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
## Time unit 1s
##
## # 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"
attach(gap.mspct)
with(spct.01, max(w.length))
## [1] 899.86
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