User Guide
Package ‘photobiologyLamps’ 0.5.1
Pedro J. Aphalo
2022-08-13
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’.
library(photobiology)
library(photobiologyWavebands)
library(photobiologyLamps)
library(ggplot2)
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 three collections:
lamps.mspct contains spectral data for various types of
lamps emiiting a fixed color of light; ledsavers.mspct
contains spectral data for a LED bulb with four color channels allowing
it to output 16 different colors of light;
qp_uvb313_temp.mspct contains spectral data for UV lamps
under seven different temperatures. In addition
qp_uvb313_temp.spct contains the same data in a single
spectral object.
In addtion to the objects containing the data itself, several
character vectors of names of spectra are provide to facilitate the
retrieval of subsets of spectra.
Accessing individual spectra
The source_spct member objects in
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. The names are listed in the
documentation and also available through the “Data Catalogue” vignette.
They can also be listed with method names().
## [1] "Airam.CF.15W.2700K"
## [2] "Airam.CF.Spiraali.14W.3000K"
## [3] "Airam.LED.11W.4000K"
## [4] "Airam.LED.14W.4000K"
## [5] "Airam.LED.9W.3000K"
## [6] "Amaran.M9.LED.video.light.5500K"
## [7] "Convoy.2plus.LED.UVA.flashlight"
## [8] "Fluence.LED.AnthoSpec"
## [9] "Fluence.LED.PhysioSpec.BROAD"
## [10] "Fluence.LED.PhysioSpec.BROAD.R3"
## [11] "Fluence.LED.PhysioSpec.BROAD.R6"
## [12] "Fluence.LED.PhysioSpec.BROAD.R9B"
## [13] "Fluence.LED.PhysioSpec.Greenhouse"
## [14] "Fluence.LED.PhysioSpec.Indoor"
## [15] "Generic.germicidal"
## [16] "Generic.Inc.bulb.60W"
## [17] "Generic.LED.9W.mosquito"
## [18] "Generic.LED.NIR.flashlight"
## [19] "Generic.LED.UVA.flashlight"
## [20] "Godox.XeF.AD200.H200.flash"
## [21] "Godox.XeF.AD200.H200j.ADFT200.flash"
## [22] "Godox.XeF.AD200.H200j.FTSTS40w.flash"
## [23] "Godox.XeF.AD200.H200R.flash"
## [24] "Ikea.LED.6.3W.2700K"
## [25] "Jaxman.U1c.LED.UVA.flood.flashlight"
## [26] "LCDlighting.FT.UVA.BL"
## [27] "Ledenergie.LED.Nano.T8.9.5W.4000K"
## [28] "Ledenergie.LED.Teho.T8.9W.4000K"
## [29] "Ledstore.LED.10W.4000K"
## [30] "Osram.FT.36W.25"
## [31] "Osram.FT.L36W.840"
## [32] "Osram.HPS.Super.Vialox"
## [33] "Osram.Inc.20W"
## [34] "Osram.LED.10W.2700K"
## [35] "Osram.LED.8W.2700K"
## [36] "Osram.MH.HQIT.400W"
## [37] "Philips.CF.PLS.11W.927"
## [38] "Philips.FT.TL.40W.01.uv"
## [39] "Philips.FT.TL.40W.12"
## [40] "Philips.FT.TL.40W.12.uv"
## [41] "Philips.FT.TL5.35W.830.HE"
## [42] "Philips.FT.TLD.36W.15"
## [43] "Philips.FT.TLD.36W.18"
## [44] "Philips.FT.TLD.36W.18.lores"
## [45] "Philips.FT.TLD.36W.83"
## [46] "Philips.FT.TLD.36W.89"
## [47] "Philips.FT.TLD.36W.92"
## [48] "Philips.FT.TLD.36W.965"
## [49] "Philips.FT.TLD.36W.BLB.108"
## [50] "Philips.FT.TLL.36W.950"
## [51] "Philips.Inc.50W.spot.halogen"
## [52] "Philips.LED.T8.10W.840"
## [53] "QPanel.FT.UVB313.40W"
## [54] "QPanel.FT.UVB340.40W"
## [55] "Sunwayfoto.LED.FL96.at.3000K"
## [56] "Sunwayfoto.LED.FL96.at.4000K"
## [57] "Sunwayfoto.LED.FL96.at.5500K"
## [58] "Sylvania.FT.215W.VHO"
## [59] "Toshiba.LED.12W.2700K"
## [60] "Toshiba.LED.9.5W.2700K"
## [61] "V.light.LED.2W.6000K"
## [62] "Valoya.LED.B50.AP67.LED.grow.lamp"
We can use a name as index to extract an individual
source_spct object.
lamps.mspct$Generic.Inc.bulb.60W
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Incandescent lamp: Generic bulb 60W ca. 1995
## Measured on 0000-08-18 13:47:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 900 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000665
## 2 301 0.000325
## 3 302 0.000956
## 4 303 0.000702
## 5 304 0.000306
## 6 305 0.000825
## 7 306 0.00103
## 8 307 0.000361
## 9 308 0.000497
## 10 309 0.000627
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see more rows
Or a character string.
lamps.mspct[["Generic.Inc.bulb.60W"]]
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Incandescent lamp: Generic bulb 60W ca. 1995
## Measured on 0000-08-18 13:47:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 900 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000665
## 2 301 0.000325
## 3 302 0.000956
## 4 303 0.000702
## 5 304 0.000306
## 6 305 0.000825
## 7 306 0.00103
## 8 307 0.000361
## 9 308 0.000497
## 10 309 0.000627
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see 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.
lamps.mspct["Generic.Inc.bulb.60W"]
## Object: source_mspct [1]
## --- Member: Generic.Inc.bulb.60W ---
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Incandescent lamp: Generic bulb 60W ca. 1995
## Measured on 0000-08-18 13:47:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 900 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000665
## 2 301 0.000325
## 3 302 0.000956
## 4 303 0.000702
## 5 304 0.000306
## 6 305 0.000825
## 7 306 0.00103
## 8 307 0.000361
## 9 308 0.000497
## 10 309 0.000627
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see more rows
##
## --- END ---
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.
lamps.mspct[Toshiba_lamps]
## Object: source_mspct [2]
## --- Member: Toshiba.LED.12W.2700K ---
## Object: source_spct [591 x 2]
## Wavelength range 251.16-898.81 nm, step 1.023182e-12-7.56 nm
## Label: LED lamp: Toshiba 12W 2700K
## Measured on 2018-02-12 09:08:23 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 607.26 nm (max)
##
## # A tibble: 591 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 251. 0
## 2 256. 0
## 3 256. 0
## 4 257. 0
## 5 257. 0
## 6 258. 0
## 7 258. 0
## 8 259. 0
## 9 259. 0
## 10 260. 0
## # … with 581 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Toshiba.LED.9.5W.2700K ---
## Object: source_spct [678 x 2]
## Wavelength range 251.29-898.97 nm, step 1.023182e-12-7.55 nm
## Label: LED lamp: Toshiba 9.5W 2700K
## Measured on 2021-09-02 19:48:00 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 605.57 nm (max)
##
## # A tibble: 678 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 251. 0
## 2 256. 0
## 3 257. 0
## 4 257. 0
## 5 257. 0
## 6 258. 0
## 7 258. 0
## 8 259. 0
## 9 259. 0
## 10 260. 0
## # … with 668 more rows
## # ℹ Use `print(n = ...)` to see more rows
##
## --- END ---
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.
lamps.mspct[grep("Toshiba", names(lamps.mspct))]
## Object: source_mspct [2]
## --- Member: Toshiba.LED.12W.2700K ---
## Object: source_spct [591 x 2]
## Wavelength range 251.16-898.81 nm, step 1.023182e-12-7.56 nm
## Label: LED lamp: Toshiba 12W 2700K
## Measured on 2018-02-12 09:08:23 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 607.26 nm (max)
##
## # A tibble: 591 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 251. 0
## 2 256. 0
## 3 256. 0
## 4 257. 0
## 5 257. 0
## 6 258. 0
## 7 258. 0
## 8 259. 0
## 9 259. 0
## 10 260. 0
## # … with 581 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Toshiba.LED.9.5W.2700K ---
## Object: source_spct [678 x 2]
## Wavelength range 251.29-898.97 nm, step 1.023182e-12-7.55 nm
## Label: LED lamp: Toshiba 9.5W 2700K
## Measured on 2021-09-02 19:48:00 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 605.57 nm (max)
##
## # A tibble: 678 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 251. 0
## 2 256. 0
## 3 257. 0
## 4 257. 0
## 5 257. 0
## 6 258. 0
## 7 258. 0
## 8 259. 0
## 9 259. 0
## 10 260. 0
## # … with 668 more rows
## # ℹ Use `print(n = ...)` to see more rows
##
## --- END ---
Set algebra operations can be used with the indexing vectors as each
vector describes a single property: color, brand, type, etc.
lamps.mspct[intersect(Philips_lamps, red_lamps)]
## Object: source_mspct [6]
## --- Member: Philips.CF.PLS.11W.927 ---
## Object: source_spct [301 x 2]
## Wavelength range 300-900 nm, step 2 nm
## Label: Compact fluorescent lamp: Philips PLS 11W 927 ca. 1995
## Measured on 0000-10-18 08:51:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 612 nm (max)
##
## # A tibble: 301 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000135
## 2 302 0.000370
## 3 304 0.000351
## 4 306 0.000227
## 5 308 0.00240
## 6 310 0.00804
## 7 312 0.0151
## 8 314 0.0171
## 9 316 0.0115
## 10 318 0.00536
## # … with 291 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Philips.FT.TL5.35W.830.HE ---
## Object: source_spct [1,101 x 2]
## Wavelength range 251.16-898.81 nm, step 0.43-4.92 nm
## Label: Fluorescent tube: Philips FT TL5 35W 830 HE
## Measured on 2018-02-12 09:57:35 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 611.35 nm (max)
##
## # A tibble: 1,101 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 251. 0.00739
## 2 252. 0
## 3 252. 0
## 4 253. 0
## 5 253. 0.00279
## 6 254. 0.00305
## 7 254 0
## 8 254. 0
## 9 255. 0.00237
## 10 255. 0.00765
## # … with 1,091 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Philips.FT.TLD.36W.15 ---
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Fluorescent tube: Philips TLD 36W 15 ca. 1995
## Measured on 0000-08-23 10:16:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 660 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000196
## 2 301 0.000959
## 3 302 0.000752
## 4 303 0.00110
## 5 304 0.00126
## 6 305 0.000885
## 7 306 0.000521
## 8 307 0.00153
## 9 308 0.000167
## 10 309 0.000493
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Philips.FT.TLD.36W.83 ---
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Fluorescent tube: Philips TLD 36W 83 ca. 1995
## Measured on 0000-08-23 11:51:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 613 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000381
## 2 301 0.000497
## 3 302 0.000426
## 4 303 0.000476
## 5 304 0.000467
## 6 305 0.000343
## 7 306 0.000449
## 8 307 0.000606
## 9 308 0.00130
## 10 309 0.00229
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Philips.FT.TLD.36W.89 ---
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Fluorescent tube: Philips TLD 36W 89 ca. 1995
## Measured on 0000-08-23 15:19:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 613 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.000477
## 2 301 0.000560
## 3 302 0.00100
## 4 303 0.000626
## 5 304 0.000965
## 6 305 0.000860
## 7 306 0.000760
## 8 307 0.000746
## 9 308 0.00114
## 10 309 0.00176
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see more rows
## --- Member: Philips.FT.TLL.36W.950 ---
## Object: source_spct [601 x 2]
## Wavelength range 300-900 nm, step 1 nm
## Label: Fluorescent tube: Philips TLL 36W 950 ca. 1995
## Measured on 0000-08-23 08:44:11 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 613 nm (max)
##
## # A tibble: 601 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 300 0.0000697
## 2 301 0.0000682
## 3 302 0.0000382
## 4 303 0.0000561
## 5 304 0.0000733
## 6 305 0.0000359
## 7 306 0.0000353
## 8 307 0.0000346
## 9 308 0.000136
## 10 309 0.000250
## # … with 591 more rows
## # ℹ Use `print(n = ...)` to see more rows
##
## --- END ---
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.
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)))
## E_range.400.700
## 100
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
## [1] FALSE
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.
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)))
## Q_range.400.700
## 3e-04
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
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.
my.spct <- fscale(lamps.mspct$Generic.Inc.bulb.60W,
range = c(400, 700),
f = e_irrad,
target = 1
)
is_scaled(my.spct)
## [1] TRUE
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.
normalize(lamps.mspct$Philips.FT.TLD.36W.15)
Ratios can be calculated directly as they are not affected by
normalization or linear rescaling.
q_ratio(my.spct, Red("Smith10"), Far_red("Smith10"))
## R:FR[q:q]
## 0.6606633
## attr(,"radiation.unit")
## [1] "q:q ratio"
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.
autoplot(lamps.mspct$Osram.LED.8W.2700K)
Data for a four channel, remote controlled, LED bulb is included in
object ledsavers.mspct.
what_measured(ledsavers.mspct$purple)
## [1] "LedSavers 7.5W four channels (WRGB) LED lamp."
how_measured(ledsavers.mspct$purple)
## [1] "Array spectrometer, Ocean Optics Maya 2000 Pro; Bentham cosine diffuser D7H; distance unknown."
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.
autoplot(ledsavers.mspct$purple)
Using the ggplot() method for spectra from package
‘ggspectra’ plus geometries and statistics from
package ‘ggplot2’ we gain additional control on the design.
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.
autoplot(ledsavers.mspct[c( "W", "R", "G", "B")],
annotations = c("+", "title:what")) +
labs(linetype = "Channel")
## Warning in autotitle(object = object, object.label = object.label, time.format =
## time.format, : Multiple spectra in long form: title annotation not supported.
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.
head(as.data.frame(lamps.mspct$Osram.LED.8W.2700K))
## w.length s.e.irrad
## 1 251.16 0
## 2 258.75 0
## 3 266.34 0
## 4 273.92 0
## 5 278.65 0
## 6 281.50 0
Of course attach and with also work as
expected.
attach(lamps.mspct)
q_ratio(Osram.LED.8W.2700K, Blue(), Red())
## Blue:Red[q:q]
## 0.1395062
## attr(,"radiation.unit")
## [1] "q:q ratio"
attach(lamps.mspct)
with(Osram.LED.8W.2700K, max(w.length))
## [1] 898.81
with(lamps.mspct, q_ratio(Osram.LED.8W.2700K, Blue(), Red()))
## Blue:Red[q:q]
## 0.1395062
## attr(,"radiation.unit")
## [1] "q:q ratio"