---
title: "User Guide"
subtitle: "Package 'photobiologyPlants' `r packageVersion('photobiologyPlants')` "
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, echo=FALSE}
knitr::opts_chunk$set(fig.width=7.2, fig.height=4.3)
```

```{r, printing-spectra, eval=TRUE, include=FALSE}
# library(tibble)
options(tibble.print_max = 6, tibble.print_min = 4)
```

## Introduction

This package provides data sets and functions relevant to the photobiology of
plants. It is part of a suite, which has package 'photobiology' at its core.
Please visit (http://www.r4photobiology.info/) for more details. For more
details 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'.

See the User Guide for packages 'photobiology' and 'ggspectra' for instructions
on how to work with spectral data. As package 'ggspectra' is only suggested, in
this vignette it is loaded an used conditionally on its availability.

```{r,message=FALSE}
library(photobiology)
library(photobiologyPlants)
library(photobiologyWavebands)
eval_plots <- requireNamespace("ggspectra", quietly = TRUE)
if (eval_plots) library(ggspectra)

theme_set(theme_bw())
```

## Photon ratios relevant to plants

`R_FR()`, `B_G()`, `UVB_UV()`, `UVA_UV()`, `UV_PAR()`, `UVB_PAR()`, `UVA_PAR()` are convenience functions implemented using function `q_ratio()` from package
'photobiology' and waveband definitions from package 'photobiiologyWavebands'
with defaults as commonly used in the field of _plant photobiology_.

```{r}
R_FR(sun.spct)
```

## Calculating the phytochrome photoequilibrium

In the examples below we use the solar spectral data included in package 'photobiology' as a data frame in object `sun.spct`. 

We can calculate the phytochrome photoequilibrium from spectral irradiance data contained in a `source_spct` object as follows.

```{r}
Pfr_Ptot(sun.spct)
```

We can also calcualte the red:far-red photon ratio, in this second example, for the same spectrum as above

```{r}
R_FR(sun.spct)
```

which is equivalent to calculating it using package 'photobiology' directly

```{r}
q_ratio(sun.spct, Red("Smith10"), Far_red("Smith10"))
```

We can, and should whenever spectral data are available, calculate the photoequilibrium as above, directly from these data. It is possible to obtain and approximation in case of the solar spectrum and other broad spectra, using the red:far-red photon ratio. The calculation, however, is only strictly valid, for di-chromatic illumination with red plus far-red light. 

```{r}
Pfr_Ptot_R_FR(R_FR(sun.spct))
```

Here we calculated the R:FR ratio from spectral data, but in practice one would use this function only when spectral data is not available as when a R plus FR sensor is used. We can see that in such a case the photoequilibrium calculated is only a  rough approximation. For sunlight, in the example above
when using spectral data we obtained a value of `r signif(Pfr_Ptot(sun.spct), 3)` in contrast to `r signif(Pfr_Ptot_R_FR(R_FR(sun.spct)), 3)` when using the R:FR photon ratio. For other light sources differences can be much larger. Furthermore, here we used the true R:FR ratio calculated from the spectrum, while broad-band red:far-red sensors guive only an approximation, which is good for sunlight, but which will be innacurate for artifical light, unless a special calibration is done for each type of lamp.

In the case of monochromatic light we can still use the same functions, as the defaults are such that we can use a single value as the 'w.length' argument, to obtain the Pfr:P ratio. For monochromatic light, irradiance is irrelevant for the photoequilibrium (steady-state).

```{r}
Pfr_Ptot(660)
Pfr_Ptot(735)
Pfr_Ptot(c(660, 735))
Pfr_Ptot(435)
```

We can also plot Pfr:Ptot as a function of wavelength (nm) of monochromatic light. The default is to return a vector for short input vectors, and a `response_spct` object otherwise, but this can be changed through argument `spct.out`.

```{r, eval = eval_plots}
autoplot(Pfr_Ptot(300:770), norm = NULL, unit.out = "photon",
         w.band = Plant_bands(),
         annotations = c("colour.guide", "labels", "boxes")) +
  labs(y = "Phytochrome photoequilibrium, Pfr:Ptot ratio")
```

It is, of course, also possible to use base R plotting functions, or as shown here functions from package 'ggplot2'

```{r, eval = eval_plots}
ggplot(data = Pfr_Ptot(300:770), aes(w.length, s.q.response)) +
  geom_line() +
  labs(x = "Wavelength (nm)",
       y = "Phytochrome photoequilibrium, Pfr:Ptot ratio")
```

In the case of dichromatic illumination with red (660 nm) and far-red (730 nm) light, we can use a different function that takes the R:FR photon ratio as argument.

**These computations are valid only for true mixes of light at these two wavelengths but not valid for broad spectra like sunlight and especially
inaccurate for plant growth lamps with peaks in their output spectrum, such as most discharge lamps (sodium, mercury, multi-metal, fluorescent tubes) and many LED lamps.** 

```{r}
Pfr_Ptot_R_FR(1.15)
Pfr_Ptot_R_FR(0.01)
Pfr_Ptot_R_FR(c(1.15,0.01))
```

It is also easy to plot Pfr:P ratio as a function of R:FR photon ratio. However we have to remember that such values are exact only for dichromatic light, and only a very rough approximation for wide-spectrum light sources. For wide-spectrum light sources, the photoequilibrium should, if possible, be calculated from spectral irradiance data.

```{r}
ex6.data <- data.frame(r.fr=seq(0.01, 5.0, length.out=100), Pfr.p=numeric(100))
ex6.data$Pfr.p <- Pfr_Ptot_R_FR(ex6.data$r.fr)
ggplot(data=ex6.data, aes(r.fr, Pfr.p)) +
  geom_line() +
    labs(x ="R:FR photon ratio",
         y = "Phytochrome photoequilibrium, Pfr:Ptot ratio")

```

## Calculating reaction rates

```{r}
with(clip_wl(sun.spct, c(300,770)), Phy_reaction_rates(w.length, s.e.irrad))
```

## Calculating the absorption cross section at given wavelengths

The phytochrome photoequilibrium cannot be calculated from the absorptance spectra
of Pr and Pfr, because Pr and Pfr have different quantum yields for the
respective phototransformations. We need to use action spectra, which in this
context are usually called `absorption cross-sections'. They can be calculated
as the product of absorptance and quantum yield. The values in these spectra,
in the case of Phy are called `Sigma'.

Here we reproduce Figure 3 in Mancinelli (1994), which gives the 'Relative photoconversion cross-sections' of Pr ($\sigma_R$) and Pfr ($\sigma_{FR}$). The values are expressed relative to $\sigma_R$ at its maximum at $\lambda = 666$ nm.

```{r, eval = eval_plots}
ex7.data <- data.frame(w.length=seq(300, 770, length.out=100))
ex7.data$sigma.r <- Phy_Sigma_R(ex7.data$w.length)
ex7.data$sigma.fr <- Phy_Sigma_FR(ex7.data$w.length)
ex7.data$sigma <- Phy_Sigma(ex7.data$w.length)
ggplot(ex7.data, aes(x = w.length)) +
  geom_line(aes(y = sigma.r/ max(sigma.r)), colour = "red") +
  geom_line(aes(y = sigma.fr/ max(sigma.r))) +
  labs(x = "Wavelength (nm)", y = expression(sigma[R]~"and"~sigma[FR]))
rm(ex7.data)
```


## Spectral absorbance of cryptochromes

```{r}
names(CRYs.mspct)
```

Here we approximate Figure 1.B from Banerjee et al.\ (2007).

```{r, eval = eval_plots}
A_as_default()
autoplot(interpolate_wl(CRYs.mspct$CRY2_dark, 300:500))
```

```{r, eval = eval_plots, warning=FALSE}
autoplot(CRYs.mspct[c("CRY2_dark", "CRY2_light")])
```

```{r, eval = eval_plots, warning=FALSE}
autoplot(CRYs.mspct[c("CRY1_dark", "CRY1_light")])
```

```{r, eval = eval_plots}
autoplot(CRYs.mspct["CRY3_dark"], range = c(300,700))
```

```{r, eval = eval_plots}
ggplot(CRYs.mspct[c("CRY1_dark", "CRY2_dark", "CRY3_dark")]) +
  geom_line(aes(linetype = spct.idx)) +
  expand_limits(x = 300)
```

## Spectral absorbance of phototropins

```{r}
names(PHOTs.mspct)
```

```{r, eval = eval_plots}
autoplot(PHOTs.mspct[c("PHOT1_fluo", "PHOT2_fluo")]) +
  expand_limits(x = 300)
```

```{r, eval = eval_plots}
autoplot(PHOTs.mspct[c("PHOT1_dark", "PHOT1_light")])
```

## UVR8 absorbance

```{r}
autoplot(UVR8s.mspct)
```

## Spectral absorbance of zeitloupe proteins

```{r}
names(ZTLs.mspct)
```

```{r, eval = eval_plots}
autoplot(ZTLs.mspct) +
  expand_limits(x = 300)
```

## Photosynthesis action spectra

```{r, eval = eval_plots}
photon_as_default()
```

```{r}
names(McCree_photosynthesis.mspct)
```

```{r, eval = eval_plots}
autoplot(McCree_photosynthesis.mspct)
```

## Carotenoids

```{r}
A_as_default()
```

```{r}
names(carotenoids.mspct)
```

```{r, eval = eval_plots}
autoplot(carotenoids.mspct[1:4], 
         annotations = c("-", "labels", "boxes")) 
```
```{r, eval = eval_plots}
autoplot(carotenoids.mspct[5:length(carotenoids.mspct)], 
         annotations = c("-", "labels", "boxes")) 
```

## Chlorophylls

```{r}
A_as_default()
```

```{r}
names(chlorophylls.mspct)
```

```{r, eval = eval_plots}
autoplot(chlorophylls.mspct[c("Chl_a_DME", "Chl_b_DME")]) 
```

```{r}, eval = eval_plots
autoplot(chlorophylls.mspct[c("Chl_a_DME", "Chl_a_MethOH")]) 
```

### Fluorescence

```{r}
names(chlorophylls_fluorescence.mspct)
```

```{r, eval = eval_plots}
autoplot(chlorophylls_fluorescence.mspct[c("Chl_a_DME", "Chl_b_DME")]) 
```

```{r, eval = eval_plots}
autoplot(chlorophylls_fluorescence.mspct[c("Chl_a_DME", "Chl_a_MethOH")]) 
```

## Optical properties of leaves

```{r}
Tfr_as_default()
```

```{r}
names(Solidago_altissima.mspct)
```
```{r, eval = eval_plots}
autoplot(Solidago_altissima.mspct$lower_adax) 
```

```{r, eval = eval_plots}
autoplot(Solidago_altissima.mspct$lower_abax) 
```

```{r, eval = eval_plots}
autoplot(as.filter_mspct(Betula_ermanii.mspct)) 
```

```{r, eval = eval_plots}
autoplot(as.reflector_mspct(Betula_ermanii.mspct)) 
```
