vignettes

vignettes/articles/animated-plots.Rmd

@@ -0,0 +1,166 @@
+---
+title: "Article: Animated plots of spectral data"
+subtitle: "'ggspectra' `r packageVersion('ggspectra')`"
+author: "Pedro J. Aphalo"
+date: "`r Sys.Date()`"
+output: 
+  rmarkdown::html_vignette:
+    toc: yes
+vignette: >
+  %\VignetteIndexEntry{Article: Plotting transformed spectral data}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Introduction
+
+Package `ggspectra` extends `ggplot2` with stats, geoms, scales and annotations suitable for light spectra. It also defines `ggplot()` and  `autoplot()` methods specialized for the classes defined in package `photobiology` for storing different types of spectral data. The `autoplot()` methods are described separately in vignette _User Guide: 2 Autoplot Methods_ and the `ggplot()` methods, statistics, and scales in _User Guide: 1 Grammar of Graphics_.
+
+The new elements can be freely combined with methods and functions defined in packages 'ggplot2', `scales`, `ggrepel`, `gganimate` and other extensions to 'ggplot2'.
+
+This article, focuses on the animation of plots of time-series of spectra, which can be obtained easily with the current version of package 'ooacquire' from Ocean Optics spectrometers. Such data can also be obtained with radiation transfer models. Kinetics of chemical reactions, or any other temporal change in colour and or intensity. In addition to time, other continuous explanatory variables are well suited to using animations. 
+
+Currently, plots of spectra created with method `autoplot()` cannot be animated with 'gganimate'.
+
+## Set up 
+
+```{r}
+library(ggplot2)
+library(photobiology)
+library(photobiologySun)
+library(photobiologyWavebands)
+library(ggspectra)
+library(lubridate)
+# if suggested packages are available
+gganimate_installed <- requireNamespace("gganimate", quietly = TRUE)
+eval_chunks <- gganimate_installed
+if (eval_chunks) {
+  library(gganimate)
+} else {
+  message("Please, install package 'gganimate'.")
+}
+```
+
+```{r, include=FALSE, echo=FALSE}
+library(knitr)
+opts_chunk$set(fig.align = 'center', 
+               fig.show = 'hold', fig.width = 7, fig.height = 4,
+               cache = FALSE)
+options(warnPartialMatchArgs = FALSE)
+```
+
+We change the default theme.
+
+```{r}
+theme_set(theme_bw())
+```
+
+## Short series
+
+We change the labels in the factor so that the time of measurement can be shown.
+
+```{r}
+my_sun.spct <- sun_evening.spct
+time <- when_measured(my_sun.spct, as.df = TRUE)
+my_sun.spct$spct.idx <- factor(my_sun.spct$spct.idx, 
+                               levels = time[["spct.idx"]], 
+                               labels = as.character(round_date(time[["when.measured"]], unit = "minute")))
+my_sun.spct
+```
+
+We create a base plot to play with:
+
+```{r, eval=eval_chunks}
+ggplot(data = my_sun.spct) +
+  aes(linetype = spct.idx) +
+  geom_line() +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous()
+```
+
+We can animate it in different ways.
+
+```{r, eval=eval_chunks}
+ggplot(data = my_sun.spct) +
+  geom_line() +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous() +
+  transition_states(spct.idx,
+                    transition_length = 2,
+                    state_length = 1)
+```
+We need some indication of what spectrum is being displayed.
+
+```{r, eval=eval_chunks}
+ggplot(data = my_sun.spct) +
+  geom_line() +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous() +
+  transition_states(spct.idx,
+                    transition_length = 2,
+                    state_length = 1) +
+  ggtitle('Now showing {closest_state}',
+          subtitle = 'Frame {frame} of {nframes}')
+```
+
+It is possible to add some annotations. Here some energy irradiances.
+
+```{r, eval=eval_chunks}
+ggplot(data = sun_evening.mspct |> smooth_spct(method = "supsmu", strength = 0.5)) +
+  geom_line() +
+  stat_wb_e_irrad(w.band = list(PAR(), Red("Sellaro"), Far_red("Sellaro")), ypos.fixed = 0.075) +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous() +
+  transition_states(spct.idx,
+                    transition_length = 2,
+                    state_length = 1,
+                    ) +
+  ggtitle('Now showing {closest_state}',
+          subtitle = 'Frame {frame} of {nframes}')
+```
+
+
+## A longer time series
+
+```{r}
+my_sun.spct <- sun_hourly_august.spct
+time <- when_measured(my_sun.spct, as.df = TRUE)
+my_sun.spct$spct.idx <- factor(my_sun.spct$spct.idx, 
+                               levels = time[["spct.idx"]], 
+                               labels = as.character(round_date(time[["when.measured"]], unit = "hour")))
+my_sun.spct
+```
+```{r, eval=eval_chunks}
+ggplot(data = my_sun.spct) +
+  aes(group = spct.idx) +
+  geom_line(alpha = 1/3) +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous()
+```
+
+
+```{r, eval=eval_chunks}
+anim <- ggplot(data = my_sun.spct) +
+  geom_line() +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous() +
+  transition_states(spct.idx,
+                    transition_length = 2,
+                    state_length = 1) +
+  ggtitle('Now showing {closest_state}',
+          subtitle = 'Frame {frame} of {nframes}')
+animate(anim, duration = 40, fps = 10)
+```
+
+```{r, eval=eval_chunks}
+anim <- ggplot(data = fscale(my_sun.spct, target = 0.5)) +
+  geom_line() +
+  scale_x_wl_continuous() +
+  scale_y_s.e.irrad_continuous() +
+  transition_states(spct.idx,
+                    transition_length = 2,
+                    state_length = 1) +
+  ggtitle('Now showing {closest_state}',
+          subtitle = 'Frame {frame} of {nframes}')
+animate(anim, duration = 40, fps = 10)
+```

vignettes/articles/data-manipulation.Rmd

@@ -16,14 +16,14 @@ vignette: >
 
 Package `ggspectra` extends `ggplot2` with stats, geoms, scales and annotations suitable for light spectra. It also defines `ggplot()` and  `autoplot()` methods specialized for the classes defined in package `photobiology` for storing different types of spectral data. The `autoplot()` methods are described separately in vignette _User Guide: 2 Autoplot Methods_ and the `ggplot()` methods, statistics, and scales in _User Guide: 1 Grammar of Graphics_.
 
-The new elements can be freely combined with methods and functions defined in packages 'ggplot2', `scales`, `ggrepel`, `cowplot` and other extensions to 'ggplot2'.
+The new elements can be freely combined with methods and functions defined in packages 'ggplot2', `scales`, `ggrepel`, `gganimate`, `cowplot` and other extensions to 'ggplot2'.
 
-This articles, formerly the third part of the User Guide, describes how to combine manipulation of spectral data with plotting. This streamlined coding is made possible by an enhancement implemented in 'ggspectra' (>= 0.3.5). In addition, some of the examples make use of methods available only in 'photobiology' (>= 0.10.0).
+This article, formerly the third part of the User Guide, describes how to combine manipulation of spectral data with plotting. This streamlined coding is made possible by an enhancement implemented in 'ggspectra' (>= 0.3.5). In addition, some of the examples make use of methods available only in 'photobiology' (>= 0.10.0).
 
-In 'ggspectra' (>= 0.3.5) the data member of `gg` (ggplot) objects remains as an object of the classes for spectral data defined in 'photobiology' instead of being converted into a plain `data.frame`. This makes it possible data manipulations in layers to be done with methods specific to spectral data. In other words, the `data` object used a default for individual plot layers retains its original attributes, including its class. This makes it possible to use methods applicable to the original object to modify it for individual plot layers.
+In 'ggspectra' (>= 0.3.5) the data member of `gg` (ggplot) objects remains as an object of the classes for spectral data defined in 'photobiology' instead of being converted into a plain `data.frame`. This makes it possible data manipulations in layers to be done with methods specific to spectral data. In other words, the `data` object used as default for individual plot layers retains its original attributes, including its class. This makes it possible to use methods applicable to the original object to modify it for individual plot layers.
 
-The examples in this vignette depend conditionally on packages 'rlang' and 
-'magrittr'. If these packages are not available when the article is built, the
+The examples in this vignette depend conditionally on packages 'rlang', 
+'magrittr', and 'gganimate'. If these packages are not available when the article is built, the
 code chunks that require them are not evaluated.
 
 ## Set up 
@@ -43,6 +43,7 @@ if (eval_chunks) {
 } else {
   message("Please, install packages 'rlang' and 'magrittr'.")
 }
+gganimate_installed <- requireNamespace("gganimate", quietly = TRUE)
 ```
 
 ```{r, include=FALSE, echo=FALSE}
@@ -53,16 +54,6 @@ opts_chunk$set(fig.align = 'center',
 options(warnPartialMatchArgs = FALSE)
 ```
 
-Create a collection of two source_spct objects.
-
-```{r}
-two_suns.mspct <- source_mspct(list(sun1 = sun.spct, sun2 = sun.spct / 2))
-```
-
-We bind the two spectra in the collection into a single spectral object. This object
-includes an indexing factor, by default named `spct.idx`. We use this new object to 
-later on demonstrate grouping in ggplots.
-
 We change the default theme.
 
 ```{r}
@@ -278,7 +269,7 @@ There are few situations where applying different transformations to multiple
 spectra does not result in overcrowded plots, one example being animated plots 
 where different layers are displayed sequentially.
 
-```{r}
+```{r, eval=gganimate_installed}
 library(gganimate)
 ggplot(data = sun_evening.mspct) +
   geom_line() +