# User Guide

### Package ‘photobiologySun’ 0.5.1

#### Pedro J. Aphalo

#### 2025-09-27

## 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 information 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’. As package ‘ggspectra’ is only suggested, in this vignette it is loaded an used conditionally on its availability.

    library(photobiology)
    library(photobiologyWavebands)
    library(photobiologySun)
    library(lubridate)
    eval_plots <- requireNamespace("ggspectra", quietly = TRUE)
    if (eval_plots) library(ggspectra)
    theme_set(theme_bw())

One collection of spectra, `sun_reference.mspct`, contains published reference solar spectra used in model simulations and for calculations. Another collection, `gap.mspct` contains a rapid sequence of spectra measured in a forest gap. Another two time series of simulated hourly spectra `sun_hourly_june.spct` and `sun_hourly_august.spct`, are each in the format of a single spectral object. Other measured spectra is inlcuded, as well as energy- and photon-irradiance time series from broadband sensors.

## Accessing individual spectra

The `source_spct` member objects in `sun_reference.mspct` and `gap.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 also be retrieved with method `names()`.

    names(sun_reference.mspct)
    #> [1] "ASTM.E490.AM0"    "ASTM.G173.direct" "ASTM.G173.global" "Gueymard.AM0"
    #> [5] "WMO.Wehrli.AM0"

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

    sun_reference.mspct$Gueymard.AM0
    #> Object: source_spct [2,002 x 2]
    #> Wavelength range 280-4000 nm, step 0.5-5 nm
    #> Variables:
    #>  w.length: Wavelength [nm]
    #>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
    #> --
    #> # A tibble: 2,002 × 2
    #>    w.length s.e.irrad
    #>       <dbl>     <dbl>
    #>  1     280      0.082
    #>  2     280.     0.099
    #>  3     281      0.15
    #>  4     282.     0.212
    #>  5     282      0.267
    #>  6     282.     0.303
    #>  7     283      0.325
    #>  8     284.     0.323
    #>  9     284      0.299
    #> 10     284.     0.250
    #> # ℹ 1,992 more rows

    sun_reference.mspct[["Gueymard.AM0"]]
    #> Object: source_spct [2,002 x 2]
    #> Wavelength range 280-4000 nm, step 0.5-5 nm
    #> Variables:
    #>  w.length: Wavelength [nm]
    #>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
    #> --
    #> # A tibble: 2,002 × 2
    #>    w.length s.e.irrad
    #>       <dbl>     <dbl>
    #>  1     280      0.082
    #>  2     280.     0.099
    #>  3     281      0.15
    #>  4     282.     0.212
    #>  5     282      0.267
    #>  6     282.     0.303
    #>  7     283      0.325
    #>  8     284.     0.323
    #>  9     284      0.299
    #> 10     284.     0.250
    #> # ℹ 1,992 more rows

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.

    sun_reference.mspct["Gueymard.AM0"]
    #> Object: source_mspct [1 x 1]
    #> --- Member: Gueymard.AM0 ---
    #> Object: source_spct [2,002 x 2]
    #> Wavelength range 280-4000 nm, step 0.5-5 nm
    #> Variables:
    #>  w.length: Wavelength [nm]
    #>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
    #> --
    #> # A tibble: 2,002 × 2
    #>    w.length s.e.irrad
    #>       <dbl>     <dbl>
    #>  1     280      0.082
    #>  2     280.     0.099
    #>  3     281      0.15
    #>  4     282.     0.212
    #>  5     282      0.267
    #>  6     282.     0.303
    #>  7     283      0.325
    #>  8     284.     0.323
    #>  9     284      0.299
    #> 10     284.     0.250
    #> # ℹ 1,992 more rows
    #>
    #> --- END ---

## Accessing subsets of spectra

We can subset `sensors.mspct` object by indexing with vectors of character strings. More generally one can search for matching names within the collection of spectra.

    sun_reference.mspct[grep("AM0", names(sun_reference.mspct), ignore.case = TRUE)]
    #> Object: source_mspct [3 x 1]
    #> --- Member: ASTM.E490.AM0 ---
    #> Object: source_spct [1,697 x 2]
    #> Wavelength range 119.5-1e+06 nm, step 1-6e+05 nm
    #> Variables:
    #>  w.length: Wavelength [nm]
    #>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
    #> --
    #> # A tibble: 1,697 × 2
    #>    w.length s.e.irrad
    #>       <dbl>     <dbl>
    #>  1     120. 0.0000619
    #>  2     120. 0.000561
    #>  3     122. 0.00490
    #>  4     122. 0.00118
    #>  5     124. 0.0000477
    #>  6     124. 0.0000343
    #>  7     126. 0.0000288
    #>  8     126. 0.0000352
    #>  9     128. 0.0000213
    #> 10     128. 0.0000173
    #> # ℹ 1,687 more rows
    #> --- Member: Gueymard.AM0 ---
    #> Object: source_spct [2,002 x 2]
    #> Wavelength range 280-4000 nm, step 0.5-5 nm
    #> Variables:
    #>  w.length: Wavelength [nm]
    #>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
    #> --
    #> # A tibble: 2,002 × 2
    #>    w.length s.e.irrad
    #>       <dbl>     <dbl>
    #>  1     280      0.082
    #>  2     280.     0.099
    #>  3     281      0.15
    #>  4     282.     0.212
    #>  5     282      0.267
    #>  6     282.     0.303
    #>  7     283      0.325
    #>  8     284.     0.323
    #>  9     284      0.299
    #> 10     284.     0.250
    #> # ℹ 1,992 more rows
    #> --- Member: WMO.Wehrli.AM0 ---
    #> Object: source_spct [920 x 2]
    #> Wavelength range 199.5-10075 nm, step 0.1-2290 nm
    #> Variables:
    #>  w.length: Wavelength [nm]
    #>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
    #> --
    #> # A tibble: 920 × 2
    #>    w.length s.e.irrad
    #>       <dbl>     <dbl>
    #>  1     200.     0.005
    #>  2     200.     0.007
    #>  3     202.     0.007
    #>  4     202.     0.008
    #>  5     204.     0.009
    #>  6     204.     0.009
    #>  7     206.     0.01
    #>  8     206.     0.01
    #>  9     208.     0.011
    #> 10     208.     0.015
    #> # ℹ 910 more rows
    #>
    #> --- END ---

## Plotting the spectra

Using `autoplot()` methods for spectra defined in package ‘ggspectra’ annotated plotting is automatic. The defaults can be easily changed, please see the documentation in package ‘ggspectra’.

    autoplot(gap.mspct$spct.01)

Using the `ggplot()` method for spectra from package ‘ggspectra’ plus geometries and statistics from package ‘ggplot2’ we gain additional control on the design.

    ggplot(gap.mspct$spct.01, unit.out = "photon") +
      geom_line(linetype = "dashed")

In the case of spectral objects containing a time series of spectra, the index variable `UTC` containing time and date in universal time coordinates (“UTC”) can be used to select and/or highlight individual spectra.

    autoplot(sun_hourly_august.spct, unit.out = "photon")

## Using the data in other contexts

As `source_spct` is a class derived from `list`, and `source_spct` is derived from `tibble::tible` which is a compatible reimplementation of `data.frame` the data can be used very easily with any R function.

    head(as.data.frame(gap.mspct$spct.01))
    #>   w.length s.e.irrad
    #> 1   250.22         0
    #> 2   250.69         0
    #> 3   251.17         0
    #> 4   251.64         0
    #> 5   252.12         0
    #> 6   252.59         0

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

    attach(gap.mspct)
    q_irrad(gap.mspct$spct.01, Red())
    #>    Q_Red.ISO
    #> 0.0004767459
    #> attr(,"time.unit")
    #> [1] "second"
    #> attr(,"radiation.unit")
    #> [1] "total photon irradiance"
    detach(gap.mspct)

    attach(gap.mspct)
    with(spct.01, max(w.length))
    #> [1] 899.86
    detach(gap.mspct)

    with(gap.mspct, q_response(spct.01, Red()))
    #> Warning in q_response.default(spct.01, Red()): 'q_response' is not defined for
    #> objects of class source_spct
    #> [1] NA