---
title: "User Guide"
subtitle: "Package 'photobiologyLamps' `r packageVersion('photobiologyLamps')` "
author: "Pedro J. Aphalo"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: yes
vignette: >
  %\VignetteIndexEntry{User Guide}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

```{r, echo=FALSE}
knitr::opts_chunk$set(fig.width=8, fig.height=4)
```

## 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 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'.

```{r, message=FALSE}
library(photobiology)
library(photobiologyLamps)
# Are the packages used in examples installed?
eval_bands <- requireNamespace("photobiologyWavebands", quietly = TRUE)
if (eval_bands) library(photobiologyWavebands)
eval_plots <- eval_bands && requireNamespace("ggspectra", quietly = TRUE)
if (eval_plots) library(ggspectra)
```

In this brief User Guide we describe how to re-scale the normalized
spectra, and how to access individual spectra or subsets of spectra.

Spectra in the package are contained in several collections, listed in
the table below.

| Collection | Description | n |
|----|-------------|-:|
| `lamps.mspct` | Spectra from imdividual lamps at full power and ambient temperature | 67 |
| `amaran_m9.mspct` | Aputure Amaran M9 LED video lamp dimming | 6 |
| `andoer_ir49.mspct` | Andoer IR LED photo/video lamp dimming | 2 |
| `elgato_klm_cct.mspct` | ElGato Key Light Mini LED video lamp colour temperature | 12 |
| `elgato_klm_dim.mspct` | ElGato Key Light Mini LED video lamp dimming | 6 |
| `ledsavers.mspct` | LedSavers 4 channel LED bulb channel mixing | 16 |
| `Nichia_LED_RECOM_dim.mspct` | Custom LED light source in Aralab plant-growth chamber, dimming | 8 |
| `Osram_L_18W_840_temp.mspct` | White fluorescent tubes in Aralab plant-growth chamber at temperatures 5 C to 35 C | 8 |
| `Percival_LED_dim.mspct` | White LEDs in Percival plant-growth chamber, dimming | 11 |
| `qp_uvb313_temp.mspct` and `qp_uvb313_temp.spct` | Q-Panel UVB-313 UV-B fluorescent tubes at temperatures -5 C to 35 C | 7 |
| `sunwayfoto_fl96.mspct` | Sunwayfoto FL96 LED fill light dimming and colour temperature | 7 |

: Collections of spectra in package 'photobiologyLamps'. **n** gives the number of spectra. Collection `lamps.mspct` contains spectra for different lamps, one
spectrum for each lamp. Each of the other collections contains multiple spectra
measured under different conditions or settings from one lamp or luminaire.

In addition to the objects containing the data themselves, several
character vectors of names of spectra are provide to facilitate the
retrieval of subsets of spectra from `lamps.mspct`. These vectors group names
by colour, supplier, type of lamp, and intended use.

## Using data from `lamps.mspct`

The `lamps.mspct` collection, an object of class `source_mspct`,
contains `r length(lamps.mspct)` spectra as member objects of
class`source_spct`. The member spectra of `lamps.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
be listed with method `names()`.

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

### Accesing individual spectra

We can use a name as index to extract an individual `source_spct`
object.

```{r}
lamps.mspct$Generic.Inc.bulb.60W
```

Or a character string.

```{r}
lamps.mspct[["Generic.Inc.bulb.60W"]]
```

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}
lamps.mspct["Generic.Inc.bulb.60W"]
```

### Accessing subsets of spectra

We can subset the `source_mspct` object by indexing with vectors of
character strings. The package provides some predefined ones, and users
can easily define their own, either as constants or through computation.
Here we use a vector defined by the package.

```{r}
lamps.mspct[Toshiba_lamps]
```

And below we use a computed one. In this case we extract the member
spectra with names containing the string "toshiba". More generaly one
can search for matching names within the collection of spectra.

```{r}
lamps.mspct[grep("Toshiba", names(lamps.mspct))]
```

Set algebra operations can be used with the indexing vectors as each
vector describes a single property: color, brand, type, etc.

```{r}
lamps.mspct[intersect(Philips_lamps, red_lamps)]
```

### Accesing metadata

```{r}
what_measured(lamps.mspct$Eiko.F36T8.BLB)
```

```{r}
how_measured(lamps.mspct$Eiko.F36T8.BLB)
```

For recently measured spectra, additional information is available.

```{r}
getInstrSettings(lamps.mspct$Eiko.F36T8.BLB)
```

```{r}
getInstrDesc(lamps.mspct$Eiko.F36T8.BLB)
```

```{r}
getNormalisation(lamps.mspct$Eiko.F36T8.BLB)
```

### Rescaling spectral data

The spectra are normalized, and consequently, several summaries
expressed in absolute units are undefined, and trigger errors. Summaries
like ratios which are not affected by normalization are allowed and
valid. The data have been normalized as the measuring conditions used
are not all the same, and in many cases not well characterized (e.g.
distance to light source, or exact alignment of the spectrometer input
optics with respect to the center of the light beam from sources).

These uncertainties in the measurment conditions are likely to have
minimal effect on the shape of the spectrum when plotted. This allows us
to reconstruct the spectrum at a different distance from the lamp(s) or
under a different number of lamps as long as we know the irradiance for
some known waveband, such as PAR.

In this section we will rescale the spectral data so that after
re-scaling a given target value for a summary quantity will be true. As
an example, we will rescale one spectrum so that it yields an energy
irradiance of 100 W m-2 for the range 400 to 700 nm. By default the
returned spectrum is not labelled as being expressed in relative units,
as the expectation is that the operation is done to obtain spectral
emission data that could have been measured at a target condition that
we want to simulate or reconstruct.

```{r}
my.spct <- fscale(lamps.mspct$Generic.Inc.bulb.60W,
                  range = c(400, 700),
                  f = e_irrad,
                  target = 100
                  )
e_irrad(my.spct, waveband(c(400,700)))
```

```{r}
is_scaled(my.spct)
```

To do the scaling based on photon irradiance, different approaches are
available to change the default. Here as above we specify the function
to use through the argument passed to `f` and set a suitable target in
mol m-2 s-1. We use 300e-6 to indicate 300 umol m-2 s-1.

```{r}
my.spct <- fscale(lamps.mspct$Generic.Inc.bulb.60W,
                  range = c(400, 700),
                  f = q_irrad,
                  target = 300e-6
                  )
q_irrad(my.spct, waveband(c(400,700)))

```

In the special case when `target == 1`, the default changes, assuming
that in this case the intention is to re-express the spectral data in
relative units.

```{r}
my.spct <- fscale(lamps.mspct$Generic.Inc.bulb.60W,
                  range = c(400, 700),
                  f = e_irrad,
                  target = 1
                  )
is_scaled(my.spct)
```

If we want to override the defaults for tagging as scaled, we ccan pass
a suitable argument to parameter `set.scaled` of `fscale()`.

In addition to scaling based of the summary calculated by a function, as
shown above, it is frequent to *normalize* spectral data. In this case
scaling is done so that spectral irradiance matches a certain value at
an specific wavelength. In most cases, the wavelength used is that of
the maximal spectral irradiance, and the target value is 1. These are
the defaults and in this case the returned spectra are always labeled as
being normalized. We use a blue fluorescent tube for this example.

```{r}
normalize(lamps.mspct$Philips.FT.TLD.36W.15)
```

Ratios can be calculated directly as they are not affected by
normalization or linear rescaling.

```{r, eval=eval_bands}
q_ratio(my.spct, Red("Smith10"), Far_red("Smith10"))
```

### Plotting the spectra

Using `autoplot()` methods for spectra defined in package 'ggspectra'
annotated plotting are created with automatically genrateda xis labels,
annotations and decorations. The defaults can be easily changed, please
see the documentation in package 'ggspectra'. For most of the data
included in the package, as told above, exact alignment was not ensured
and the exact distance not recorded. In such cases the data included in
the package have been normalized to 1 at the tallest peak of emission,
as can be seen in the example below.

```{r, eval=eval_plots}
autoplot(lamps.mspct$Osram.LED.8W.2700K, w.band = VIS(), span = 51)
```

Data for a four channel, remote controlled, LED bulb is included in
object `ledsavers.mspct`.

```{r}
what_measured(ledsavers.mspct$purple)
how_measured(ledsavers.mspct$purple)
```

In this case, data are not normalized, as all spectra in the object have
been measure with the lamp and entrance optics in exactly the same
position, controlling emission with wireless remote controller. In the
next example we see that *purple* is created as a mix of blue and red
light.

```{r, eval=eval_plots}
autoplot(ledsavers.mspct$purple, w.band = VIS(), span = 51)
```

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(ledsavers.mspct$purple) +
  geom_line(linetype = "dashed") +
  theme_classic()
```

We can also plot multiple spectra. In this example we plot the pure
emission from each of the four channels of the bulb.

```{r, eval=eval_plots}
autoplot(ledsavers.mspct[c( "W", "R", "G", "B")],
         annotations = c("+", "title:what"), w.band = VIS(), span = 51) +
  labs(linetype = "Channel")
```

### Using the data in other contexts

In general it will be easiest to use methods from packages in the
'r4photobiology' suite for plotting and calculation of various
summaries. However, as `source_mspct` is a class derived from `list`,
and `source_spct` is derived from `tibble::tibble` that is a partly
compatible reimplementation of `data.frame` the data can be used very
easily with R functions expecting data frames as input.

```{r}
head(as.data.frame(lamps.mspct$Osram.LED.8W.2700K))
```

Of course `attach` and `with` also work as expected.

```{r, eval=eval_bands}
attach(lamps.mspct)
q_ratio(Osram.LED.8W.2700K, Blue(), Red())
detach(lamps.mspct)
```

```{r}
attach(lamps.mspct)
with(Osram.LED.8W.2700K, max(w.length))
detach(lamps.mspct)
```

```{r, eval=eval_bands}
with(lamps.mspct, q_ratio(Osram.LED.8W.2700K, Blue(), Red()))
```

## Other data sets

The additional data sets can be used similarly as described above for
`lamps.spct` when stored as collections. For datasets stored in
long-form an additional variable or column identifies the individual
spectra.

## Ultraviolet-B lamps and temperature

Object `qp_uvb313_temp.spct` is a `source_spct` object that contains
spectra in long form for a pair of UV-B lamps measured at
`r length(unique(qp_uvb313_temp.spct$temperature))` different air
temperatures.

```{r}
head(qp_uvb313_temp.spct)
```

```{r}
unique(qp_uvb313_temp.spct$temperature)
```

Collection `qp_uvb313_temp.mspct` contains the same spectra as
`qp_uvb313_temp.spct` as a collection of individual `source_spct`
objects.

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

```{r}
summary(qp_uvb313_temp.mspct)
```

```{r}
head(qp_uvb313_temp.mspct$minus05C)
```

## Multicolour LED lamp

Collection `ledsavers.mspct` contains `r length(ledsavers.mspct)`
spectra. Each spectrum corresponds to a different combination of dimming
settings of the four channels in this RGBW (red, green, blue, white)
lamp.

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

We can plot the spectra for the individual channels by selecting them.

```{r, eval=eval_plots}
autoplot(ledsavers.mspct[c("R", "G", "B", "W")], 
         w.band = VIS_bands(), span = 51)
```

## Video and photography lamps

Collection `sunwayfoto_fl96.mspct` contains
`r length(sunwayfoto_fl96.mspct)` spectra. Each spectrum corresponds to
a different combination of dimming and colour temperature settings of a
two channel or bi-colour (warm white and cool white) lamp sold for use
in photography and video..

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

```{r}
what_measured(sunwayfoto_fl96.mspct)
```

Collection `elgato_klm_cct.mspct` contains
`r length(elgato_klm_cct.mspct)` spectra. Each spectrum corresponds to a
different colour temperature setting of a two channel or bi-colour (warm
white and cool white) lamp sold for use in photography and video.
Measurements were done with dimming set at full power.

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

```{r}
what_measured(elgato_klm_cct.mspct)
```

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

Collection `elgato_klm_dim.mspct` contains
`r length(elgato_klm_dim.mspct)` spectra. Each spectrum corresponds to a
different dimming setting of a two channel or bi-colour (warm white and
cool white) lamp sold for use in photography and video. Measurements
were done with colour temperature (CCT) set to 4000K.

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

```{r}
what_measured(elgato_klm_dim.mspct)
```

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

Collection `amaran_m9.mspct` contains `r length(amaran_m9.mspct)`
spectra. Each spectrum corresponds to a different dimming setting of a
single channel (cool white) lamp sold for use in photography and video.

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

```{r}
what_measured(amaran_m9.mspct)
```

## Night vision video and photography lamp

Collection `andoer_ir49.mspct` contains `r length(andoer_ir49.mspct)`
spectra. Each spectrum corresponds to a different dimming setting of a
single channel (infra-red) lamp sold for use in photography and video.
This requires a modified or special camera sensitive to near infrared
radiation (NIR)

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

```{r}
what_measured(andoer_ir49.mspct)
```