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

## Introduction

I have developed a set of packages to
facilitate the calculation of many different quantities that can be derived from spectral irradiance data. The core package in this suite is called '**photobiology**', and is the package described here. Other specialized packages for quantification of ultraviolet radiation and visible radiation ('**photobiologyWavebands**'), plant photoreceptors and other plant photobiology related calculations ('**photobiologyPlants**'), example spectral data for filters ('**photobiologyFilters**'), lamps ('**photobiologyLamps**'), LEDs ('**photobiologyLEDs**'), sunlight ('**photobiologySun**'), light sensors ('**photobiologySensors**') and for exchange of data in _foreign_ formats ('**photobiologyInOut**') are part of the suite. One additional package, ('*ggspectra*'), implements facilities for plotting spectral data by extending package '**ggplot2**', providing both ggplot statistics in addition to specializations of `plot()`. All packages that can comply with the repository rules have been submitted or will in coming months be submitted to **CRAN** (Comprehensive R archive network). The packages not yet in **CRAN**, and development versions of those already in **CRAN**, are available through a CRAN-like repository at <https://www.r4photobiology.info/R/> while the Web site at <https://www.r4photobiology.info> provides news about the development of the suite and some additional information. Each package has its own public Git repository at my Bitbucket account (<https://bitbucket.org/aphalo/>) from where the source code of the current and previous versions can be cloned or forked.

Package '**photobiology**' provides two sets of functions for many operations: low-level functions programmed following a functional paradigm, and higher-level functions using an object-oriented paradigm. The former functions take as arguments numeric vectors and are sometimes faster. The later ones take _spectra_ objects as arguments, are easier to use, and at least at the moment, to some extent slower. For everyday use _spectra_ objects are recommended, but when maximum performance or flexibility in scripts is desired, the use of the functions taking numeric vectors as arguments may allow optimizations that are not possible with the object-oriented functions. The differences in performance becomes relevant only in extreme cases such as processing in a single script tenths of thousands of spectra. In the vignettes we emphasize the use of the object-oriented classes and methods.

## Naming conventions

I have developed this package over several years, and even though I have tried to remain consistent, some inconsistencies have crept in. I have attempted to correct inconsistencies without breaking old code by providing synonyms for some functions. 

In general I have used names in _snake case_ for methods and functions, such as `source_spct()` and _dot case_ for their arguments. There are two exceptions to this: the `as.` and `is.` methods which for consistency with base R, retain the dot: `as.source_spct()` and `ìs.source_spct()`. There are still some functions and methods whose names are in _camel case_: these are mostly accessors and setters of metadata attributes such as `setWhatMeasured()` and `getWhatMeasured()`, in which case synonyms `what_measured<-()` and `what_measured()` are now provided with a syntax that parallels that of R's `comment<-()`, `comment()`, and similar methods for other attributes. Names of attributes themselves use dots, while classes use snake case as functions do, allowing consistency between class names and their constructor functions. There is an additional twist: functions named like `clip_wl()` act on the wavelengths ("wl") modifying them, while those named like `wl_range()` report on the properties of the wavelengths.

In examples we use variable names ending in `.spct` for spectra, ending in `.mspct` for collections of spectra and ending in `.tb` for tibbles. In most cases the root of the variable names use snake case and may have a tag at the end separated with a dot. In the case of variable names used in examples I have been less strict about conventions than for the objects exported by the package.

None of these naming conventions are enforced for user defined objects and classes; these conventions are simply those I have tried to follow while developing this package as well as other packages in the r4photobiology suite.

## Example data

Data for several spectra are included in this package for use in examples and vignettes, and in testing (Tables 1 and 2). Other packages in the '**r4photobiology suite**' provide many additional data sets.

<hr>

**Table 1. Data sets included in the package: spectra.** The CIE standard illuminant data in this package are normalized to one at $\lambda = 560\,$nm, while in the CIE standard they are normalized to 100 at the same wavelength. See documentation for each data object for details and data sources.
 
| Object | class | units      | data description          |
|:--------|:-------|:----------|:---------------------------|
| `sun.spct` | `source_spct` | $W\,m^{-2}\,nm^{-1}$ | solar spectral irradiance |
| `sun.daily.spct` | `source_spct` | $J\,m^{-2}\,d^{-1}\,nm^{-1}$  | solar spectral exposure |
| `sun.data` | `data.frame` | $W\,m^{-2}\,nm^{-1}$ | solar spectral irradiance |
| `sun.daily.data` | `data.frame` | $J\,m^{-2}\,d^{-1}\,nm^{-1}$  | solar spectral exposure|
| `D65.illuminant.spct` | `source_spct` | (norm. 560 nm) | CIE standard |
| `A.illuminant.spct` | `source_spct` | (norm. 560 nm)  | CIE standard |
| `clear.spct` | `filter_spct` | fraction | ideal transparent filter |
| `opaque.spct` | `filter_spct` | fraction | ideal opaque filter |
| `polyester.spct` | `filter_spct` | fraction | plastic film |
| `yellow_gel.spct` | `filter_spct` | fraction | theatrical _gel_ filter |
| `green_leaf.spct` | `reflector_spct` | fraction | a birch leaf |
| `clear_body.spct` | `object_spct` | fraction | ideal transparent body |
| `black_body.spct` | `object_spct` | fraction | ideal black body |
| `white_body.spct` | `object_spct` | fraction | ideal white body |
| `Ler_leaf.spct` | `object_spct` | fraction | Arabidopsis leaf |
| `Ler_leaf_trns.spct` | `filter_spct` | fraction | Arabidopsis leaf (T total) |
| `Ler_leaf_trns_i.spct` | `filter_spct` | fraction | Arabidopsis leaf (T internal) |
| `Ler_leaf_rflt.spct` | `reflector_spct` | fraction | Arabidopsis leaf (R total) |
| `photodiode.spct` | `response_spct` |  $A / W$  | typical Si photodiode |
| `ccd.spct` | `response_spct` |  $A / W$ | typical CCD array |
| `white_led.raw_spct` | `raw_spct` | counts | example raw detector counts data |
| `white_led.cps_spct` | `cps_spct` | counts / s | example detector counts data |
| `white_led.source_spct` | `source_spct` | $W\,m^{-2}\,nm^{-1}$ | spectral irradiance |
| `filter_cps.mspct` | `cps_mspct` | $\mathrm{counts} / s$ | example detector counts data |
<hr>

<hr>

**Table 2. Data sets included in the package: chromaticity data.** See documentation for each data object for details and data sources.

| Object  | class  | data description                 |
|:--------|:-------|:-------------------------------|
| `ciexyzCC2.spct` | `chroma_spct` |  human chromaticity coordinates $2^\circ$ |
| `ciexyzCC10.spct` | `chroma_spct` |   human chromaticity coordinates $10^\circ$  |
| `ciexyzCMF2.spct` | `chroma_spct` |   human colour matching function $2^\circ$ |
| `ciexyzCMF10.spct` | `chroma_spct` |  human colour matching function $10^\circ$ |
| `ciev2.spct` | `chroma_spct` |  human luminous efficiency $2^\circ$ |
| `beesxyzCMF.spct` |  `chroma_spct` |  bee colour matching function |

<hr>
