--- title: "User Guide" subtitle: "Package 'photobiologySun' `r packageVersion('photobiologySun')` " author: "Pedro J. Aphalo" date: "`r Sys.Date()`" output: rmarkdown::html_vignette: toc: yes vignette: > %\VignetteIndexEntry{User Guide} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include=FALSE} knitr::opts_chunk$set(fig.width=8, fig.height=4, collapse = TRUE, comment = "#>") ``` ## 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. ```{r, message=FALSE} 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()`. ```{r} names(sun_reference.mspct) ``` We can use a character string as index to extract an individual `source_spct` object. ```{r} sun_reference.mspct$Gueymard.AM0 ``` ```{r} sun_reference.mspct[["Gueymard.AM0"]] ``` 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. ```{r} sun_reference.mspct["Gueymard.AM0"] ``` ## 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. ```{r} sun_reference.mspct[grep("AM0", names(sun_reference.mspct), ignore.case = TRUE)] ``` ## 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'. ```{r, eval = eval_plots} 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. ```{r, eval = eval_plots} 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. ```{r, eval = eval_plots} 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. ```{r} head(as.data.frame(gap.mspct$spct.01)) ``` Of course `attach` and `with` also work as expected. ```{r} attach(gap.mspct) q_irrad(gap.mspct$spct.01, Red()) detach(gap.mspct) ``` ```{r} attach(gap.mspct) with(spct.01, max(w.length)) detach(gap.mspct) ``` ```{r} with(gap.mspct, q_response(spct.01, Red())) ```