--- 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. (). 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 . 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, (). 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. (). ## 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 (). 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]() 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 () 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.