---
title: "User Guide: 0 The R for Photobiology Suite"
subtitle: "Photobiology-related computations in R"
author: "Pedro J. Aphalo"
date: "Built: `r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: yes
vignette: >
  %\VignetteIndexEntry{User Guide: 0 The R for Photobiology Suite}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

The citation for the suite is given by

```{r}
print(citation('photobiology'), style = "textVersion")
```

## Introduction

Package ['photobiology'](https://docs.r4photobiology.info/photobiology/)
is at the core of a suite of packages for analysis and
plotting of data relevant to photobiology. The accompanying packages provide data and
definitions that are to a large extent application-area specific while the
functions in the package 'photobioloy' are widely useful in photobiology and in
radiation quantification in geophysics and meteorology. Package 'photobiology'
has its main focus in the characterization of the light environment in a
biologically relevant manner and in the manipulation of spectral data to
simulate photo-physical, photo-chemical and photo-biological interactions and
responses. In addition it gives access to the implementation of the algorithms
of Jean Meeus for the position of the sun from package 'SunCalcMeeus', including
derived quantities like day- and night length that are important for most
organisms.

Data exchange with packages 'pavo', 'colorSpec' and 'hyperSpec' is supported.
The focus of package 'pavo' (Maia et al. 2003) is on color perception by animals
and assessment of animal coloration. The focus of package 'colorSpec' (Davis
2019) is on color-related computations: "Calculate with spectral properties of
light sources, materials, cameras, eyes, and scanners." The focus of package
'hyperSpec' (Beleites and Sergo) is the handling of hyperspectral data sets,
such as spectral images and time series of spectra. Because of their different
focus, these packages mostly complement each other and this suite, in spite of
some overlap and differences in approach or even, in philosophy about data
handling.'

### References

Aphalo, Pedro J. (2015) The r4photobiology suite. *UV4Plants Bulletin*,
2015:1, 21-29. (<https://doi.org/10.19232/uv4pb.2015.1.14>).

Aphalo, Pedro J. (2024) *Learn R: As a Language.* 2ed. The R Series. 
Boca Raton: Chapman & Hall/CRC. ([Web page](https://www.learnr-book.info/))

Aphalo, P. J., Albert, A., Björn, L. O., McLeod, A. R., Robson, T. M.,
Rosenqvist, E. (Eds.). (2012). *Beyond the Visible: A handbook of best
practice in plant UV photobiology* (1st ed., p. xx + 174). Helsinki:
University of Helsinki, Department of Biosciences, Division of Plant
Biology. ISBN 978-952-10-8363-1 (PDF), 978-952-10-8362-4 (paperback).
Open access at <https://doi.org/10.31885/9789521083631>.

Aphalo, Pedro J., Robson, T. Matthew, Kotilainen, Titta K. (2016-2025)
*R for Photobiology: Theory and recipes for common calculations.* 
Pre-release available at [LeanPub](https://leanpub.com/r4photobiology).

Davis G (2019). *A Centroid for Sections of a Cube in a Function Space,
with application to Colorimetry.* *ArXiv e-prints*. 1811.00990,
(<https://arxiv.org/abs/1811.00990>).

Maia, R., Eliason, C. M., Bitton, P. P., Doucet, S. M., Shawkey, M. D.
(2013) pavo: an R package for the analysis, visualization and
organization of spectral data. *Methods in Ecology and Evolution*,
4(10):906-913. (<https://doi.org/10.1111/2041-210X.12069>).

## Packages in the suite

The core packages in this suite are called
['photobiology'](https://docs.r4photobiology.info/photobiology/) and 
['SunCalcMeeus'](https://docs.r4photobiology.info/SunCalcMeeus/).
All other packages in the suite depend on them (see Table below).

The current and archived releases of all packages except
(['rOmniDriver'](https://docs.r4photobiology.info/rOmniDriver/)) and
(['ooacquire'](https://docs.r4photobiology.info/ooacquire/)) are available
through CRAN. The most recent, including pre-release versions, of all the
packages in the suite are available through an [R-Universe
repository](https://aphalo.r-universe.dev/). Installation instructions are given
in the README file in each package's documentation accessible through the links
in the Table below.

| Package                     | Provides                                                                                                                                                                                                |
|------------------------------------|------------------------------------|
| ['photobiology'](https://docs.r4photobiology.info/photobiology/)              | Core classes, methods and functions                                                                                                                                                                     |
| ['SunCalcMeeus'](https://docs.r4photobiology.info/SunCalcMeeus/)              | Functions for the position of the Sun                                                                                                                                                                     |
| ['photobiologyWavebands'](https://docs.r4photobiology.info/photobiologyWavebands/)     | Definitions of standardized and frequently used wavelength band definitions and spectral weighting functions.                                                                                           |
| ['photobiologyPlants'](https://docs.r4photobiology.info/photobiologyPlants/)        | Methods, functions and data for plants and vegetation.                                                                                                                                                  |
| ['photobiologyInOut'](https://docs.r4photobiology.info/photobiologyInOut/)         | Exchange of data within R and using different proprietary and standard-based formats.                                                                                                                   |
| ['photobiologyLamps'](https://docs.r4photobiology.info/photobiologyLamps/)         | Spectral emission and other data for various lamp types.                                                                                                                                                |
| ['photobiologyLEDs'](https://docs.r4photobiology.info/photobiologyLEDs/)          | Spectral emission and other data for various LEDs and LED arrays.                                                                                                                                       |
| ['photobiologySensors'](https://docs.r4photobiology.info/photobiologySensors/)       | Spectral response and other data for various UV, VIS and NIR sensors.                                                                                                                                   |
| ['photobiologySun'](https://docs.r4photobiology.info/photobiologySun/)           | Spectral irradiance and other data for sunlight. Both measured and standard definitions for ground level and top of the atmosphere.                                                                     |
| ['photobiologyFilters'](https://docs.r4photobiology.info/photobiologyFilters/)       | Spectral transmittance and spectral reflectance data for different materials including optical filters. Spectral data on refractive index.                                                              |
| ['ggspectra'](https://docs.r4photobiology.info/ggspectra/)                 | Extensions to package 'ggplot2' for easier plotting of spectral data, including `autoplot()` and `ggplot()` methods for the classes defined in package 'photobiology' and scales, geoms and statistics. |
| ['ooacquire'](https://docs.r4photobiology.info/ooacquire/) (Not in CRAN)    | Data acquisition and control of Ocean Optics spectrometers.                                                                                                                           |
| ['rOmniDriver'](https://docs.r4photobiology.info/rOmniDriver/) (Not in CRAN) | Interface to OmniDriver drivers for communication with spectrometers from Ocean Optics                                                                                              |

For information on other packages by the author please visit
(<https://www.r4photobiology.info>). The current status of the packages is
summarised by badges in their README files, which function as the home page of
their on-line documentation (linked in the table above). Each package has its
own public Git repository at my [GitHub account](<https://github.com/aphalo/>)
from where the source code of the current and earlier versions can be cloned or
forked. Support questions, bug reports and suggestions for improvements are
welcome as Git issues.

## Acknowledgements

The development of the software was funded in part by the Academy of Finland
(decision 252548), and done mainly while the author was employed (2006 to 2024)
at the University of Helsinki, Finland. The sources of the data included are
described in the documentation of the packages. We thank all those who
authorized reuse of their data or published their data in the open.

COST Action FA9604 'UV4Growth' facilitated
discussions and exchanges of ideas that lead to the development of this
package. 

The contributions of Andy McLeod, Lars Olof Björn, Nigel Paul,
Lasse Ylianttila, Glen Davis, Agnese Fazio, T. Matthew Robson and Titta
Kotilainen were specially significant. Other members of the UV4Plants
Association (<https://www.uv4plants.org/>) and participants in workshops
and training events contributed both problems in need of being solved
and solutions to implement.

Tutorials by Hadley Wickham and comments on my presentation at
*UseR!2015* allowed me to significantly improve the coding and
functionality. The generous and friendly help from many members of the R
community since 1999 is also warmly thanked.
