User Guide: 1 Data and their use
Package ‘photobiologyLEDs’ 0.5.2
Pedro J. Aphalo
2023-11-01
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(photobiologyLEDs)
# Are the packages used in examples installed?
eval_bands <- requireNamespace("photobiologyWavebands", quietly = TRUE)
if (eval_bands) library(photobiologyWavebands)
eval_plots <- eval_bands && requireNamespace("ggspectra", quietly = TRUE)
if (eval_plots) 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.
The data
The spectral data have been acquired mostly with one instrument, an
array spectrometer. However, some spectra have been measured with
another spectrometer that has lower wavelength resolution. This
difference in resolution and slit function can give, for the same LED,
measured peaks of slightly different width. This is an inevitable
artefact of spectral measurements, but as LEDs have relatively wide
peaks the distortion is small. With well calibrated spectrometers, the
area under a peak should not be affected by the difference in wavelength
resolution.
The spectral data in this package are stored in three R objects, each
of them a collection of spectra of class source_spct. Most
of the spectra are in data object leds.mspct. Data object
COB_reflectors.mspct contains spectra for a single COB LED
combined with different reflectors while data object
COB_dimming.mspct contains a collection of spectra from the
same LED when driven at different currents.
Individual or subsets of spectra can be retrieved by name.
The package includes also several character vectors of
names, each one containing names for LEDs of a given
color, from a given manufacturer or intended mainly
for a specific use. These are listed in the help index for the package.
The names used are in most cases the codes used by the
manufacturers for the given type. Any dashes in these codes have been
replaced by underscores.
## [1] "Agilent_HLMB_CB30" "Agilent_HLMB_CD31"
## [3] "Agilent_HLMP_CB31" "Epileds_3W_460nm"
## [5] "Epileds_3W_470nm" "Epileds_3W_495nm"
## [7] "HueyJann_HPR40E_48K30BG" "HueyJann_HPR40E_48K30BI"
## [9] "LedEngin_LZ1_10DB00_460nm" "Roithner_CB30"
## [11] NA "Weili_3W.nominal.500nm"
## [1] "LedEngin_LZ1_10UV00_365nm"
## [2] "LedEngin_LZ1_10DB00_460nm"
## [3] "LedEngin_LZ4_40R208_660nm"
## [4] "LedEngin_LZ1_10R302_740nm"
## [5] "LedEngin_LZ1_10R602_850nm"
## [6] "LedEngin_LZ1_10UB00_00U4_385nm"
## [7] "LedEngin_LZ1_10UB00_00U8_405nm"
## [8] "LedEngin_LZ7_N4M100"
## [9] "LedEngin_LZ7_N4M100_ch_A_Green"
## [10] "LedEngin_LZ7_N4M100_ch_B_Red"
## [11] "LedEngin_LZ7_N4M100_ch_C_Blue"
## [12] "LedEngin_LZ7_N4M100_ch_D_UV"
## [13] "LedEngin_LZ7_N4M100_ch_E_CW_Cool_white"
## [14] "LedEngin_LZ7_N4M100_ch_F_PC_Amber"
## [15] "LedEngin_LZ7_N4M100_ch_G_Cyan"
Accessing individual spectra
The source_spct member objects in
leds.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().
names(COB_reflectors.mspct)
## [1] "Rfl.15deg" "Rfl.25deg" "Rfl.35deg" "Rfl.None"
## [1] "CC.350mA" "CC.344mA" "CC.266mA" "CC.140mA" "CC.070mA" "CC.035mA" "CC.017mA"
## [8] "CC.011mA"
## [1] "Agilent_HLMB_CB30"
## [2] "Agilent_HLMB_CD31"
## [3] "Agilent_HLMP_CB31"
## [4] "Agilent_HLMP_CM30"
## [5] "Agilent_HLMP_CM31"
## [6] "Agilent_HLMP_DJ32"
## [7] "Agilent_HLMP_DL32"
## [8] "Bridgelux_3W_455nm"
## [9] "Bridgelux_BXRE_50S2001_c_73"
## [10] "CREE_XPE_480nm"
## [11] "Epileds_3W_410nm"
## [12] "Epileds_3W_420nm"
## [13] "Epileds_3W_430nm"
## [14] "Epileds_3W_445nm"
## [15] "Epileds_3W_460nm"
## [16] "Epileds_3W_470nm"
## [17] "Epileds_3W_495nm"
## [18] "Epileds_3W_520nm"
## [19] "Epileds_3W_560nm"
## [20] "Epileds_3W_590nm"
## [21] "Epileds_3W_600nm"
## [22] "Epileds_3W_620nm"
## [23] "Epistar_3W_Plant_Grow_LED"
## [24] "HueyJann_HPR40E_48K30BG"
## [25] "HueyJann_HPR40E_48K30BI"
## [26] "LCFOCUS_LC_10FS504_G24"
## [27] "LCFOCUS_LC_10FSCOB1411_2700"
## [28] "LCFOCUS_LC_10FSCOB1411_6000"
## [29] "LCFOCUS_LC_10FSCOB1917_4000"
## [30] "LedEngin_LZ1_10DB00_460nm"
## [31] "LedEngin_LZ1_10R302_740nm"
## [32] "LedEngin_LZ1_10R602_850nm"
## [33] "LedEngin_LZ1_10UB00_00U4_385nm"
## [34] "LedEngin_LZ1_10UB00_00U8_405nm"
## [35] "LedEngin_LZ1_10UV00_365nm"
## [36] "LedEngin_LZ4_40R208_660nm"
## [37] "LedEngin_LZ7_N4M100"
## [38] "LedEngin_LZ7_N4M100_ch_A_Green"
## [39] "LedEngin_LZ7_N4M100_ch_B_Red"
## [40] "LedEngin_LZ7_N4M100_ch_C_Blue"
## [41] "LedEngin_LZ7_N4M100_ch_D_UV"
## [42] "LedEngin_LZ7_N4M100_ch_E_CW_Cool_white"
## [43] "LedEngin_LZ7_N4M100_ch_F_PC_Amber"
## [44] "LedEngin_LZ7_N4M100_ch_G_Cyan"
## [45] "Ledguhon_10WBVG14G24_Y6C_T4"
## [46] "Ledguhon_10WBVGIR14G24_Y6C_T4"
## [47] "Luminus_CXM_14_HS_12_36_AC30"
## [48] "Marktech_MTSM340UV_F5120_340nm"
## [49] "Nichia_NF2W757GT_F1_sm505_Rfc00"
## [50] "Nichia_NFCWL036B_V3_Rfcb0"
## [51] "Nichia_NFSL757GT_Rsp0a"
## [52] "Nichia_NFSW757G_Rsp0a"
## [53] "Nichia_NFSW757G_V3_Rs060"
## [54] "Nichia_NS6L183AT_H1_sw"
## [55] "Nichia_NVSU119C_U385"
## [56] "Nichia_NVSU233B_U365"
## [57] "Nichia_unknown_757"
## [58] "Norlux_NHXRGB090S00S_blue"
## [59] "Norlux_NHXRGB090S00S_green"
## [60] "Norlux_NHXRGB090S00S_red"
## [61] "Norlux_NHXRGB090S00S_RGB"
## [62] "Osram_GF_CSHPM2.24_2T4T_1"
## [63] "Osram_GW_CSSRM3.HW"
## [64] "Osram_LY5436"
## [65] "QuantumDevices_QDDH66002"
## [66] "QuantumDevices_QDDH68002"
## [67] "QuantumDevices_QDDH70002"
## [68] "QuantumDevices_QDDH73502"
## [69] "Roithner_BS436"
## [70] "Roithner_CB30"
## [71] "Roithner_DUV289_SD353EL"
## [72] "Roithner_DUV310_SD353EL"
## [73] "Roithner_DUV325_SD353EL"
## [74] "Roithner_DUV340_SD353EL"
## [75] "Roithner_LED405"
## [76] "Roithner_LED740"
## [77] "Roithner_SMB1N_BB450"
## [78] "Roithner_UV395"
## [79] "Roithner_UVMAX305"
## [80] "Roithner_UVMAX340"
## [81] "Roithner_XSL365"
## [82] "Roithner_XSL370"
## [83] "Roithner_XSL375"
## [84] "Samsung_SPHWHAHDND25YZT3D3"
## [85] "SeoulSemicon_S4SM_1564359736_0B500H3S_00001"
## [86] "SeoulSemicon_S4SM_1564509736_0B500H3S_00001"
## [87] "SeoulSemicon_STW9C2SB_S"
## [88] "TaoYuan_LED_310nm"
## [89] "Weili_120W.array.12ch.custom.A"
## [90] "Weili_3W.nominal.500nm"
## [91] "Weili_3W.nominal.525nm"
## [92] "Weili_3W.nominal.550nm"
## [93] "Weili_3W.nominal.555nm"
We can use a character string as index to extract an individual
source_spct object.
leds.mspct$Roithner_UV395
## Object: source_spct [1,335 x 2]
## Wavelength range 250.05-899.78 nm, step 0.43-7.45 nm
## Label: LED type UV395 from Roithner-Laser
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 391.03 nm (max in 250.05-899.78 nm)
##
## # A tibble: 1,335 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258. 0
## 10 259. 0
## # ℹ 1,325 more rows
leds.mspct[["Roithner_UV395"]]
## Object: source_spct [1,335 x 2]
## Wavelength range 250.05-899.78 nm, step 0.43-7.45 nm
## Label: LED type UV395 from Roithner-Laser
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 391.03 nm (max in 250.05-899.78 nm)
##
## # A tibble: 1,335 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258. 0
## 10 259. 0
## # ℹ 1,325 more rows
Be aware that according to R’s rules, using single square brackets
will return a source_mspct object, a collection of spectra,
possibly of length one. This statement is not equivalent to the one in
the chunk immediately above.
leds.mspct["Roithner_UV395"]
## Object: source_mspct [1 x 1]
## --- Member: Roithner_UV395 ---
## Object: source_spct [1,335 x 2]
## Wavelength range 250.05-899.78 nm, step 0.43-7.45 nm
## Label: LED type UV395 from Roithner-Laser
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 391.03 nm (max in 250.05-899.78 nm)
##
## # A tibble: 1,335 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258. 0
## 10 259. 0
## # ℹ 1,325 more rows
##
## --- END ---
Of course, with this syntax it is possible to use a vector of member
names.
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.
## Object: source_mspct [4 x 1]
## --- Member: Norlux_NHXRGB090S00S_blue ---
## Object: source_spct [1,235 x 2]
## Wavelength range 250-900 nm, step 0.43-14.51 nm
## Label: 12W RGB LED COB Type NHXRGB090S00S from Norlux
## Measured on 2013-11-27 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 462.59 nm (max in 250-900 nm)
##
## # A tibble: 1,235 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250 0
## 2 254. 0
## 3 255. 0
## 4 255. 0
## 5 256. 0
## 6 256. 0
## 7 257. 0
## 8 257. 0
## 9 258. 0
## 10 258 0
## # ℹ 1,225 more rows
## --- Member: Norlux_NHXRGB090S00S_green ---
## Object: source_spct [1,190 x 2]
## Wavelength range 250-900 nm, step 0.43-14.36 nm
## Label: 12W RGB LED COB Type NHXRGB090S00S from Norlux
## Measured on 2013-11-27 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 515.52 nm (max in 250-900 nm)
##
## # A tibble: 1,190 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250 0
## 2 254. 0
## 3 255. 0
## 4 255. 0
## 5 256. 0
## 6 256. 0
## 7 257. 0
## 8 257. 0
## 9 258. 0
## 10 258 0
## # ℹ 1,180 more rows
## --- Member: Norlux_NHXRGB090S00S_red ---
## Object: source_spct [1,282 x 2]
## Wavelength range 250-900 nm, step 0.43-14.43 nm
## Label: 12W RGB LED COB Type NHXRGB090S00S from Norlux
## Measured on 2013-11-27 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 643.08 nm (max in 250-900 nm)
##
## # A tibble: 1,282 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250 0
## 2 254. 0
## 3 255. 0
## 4 255. 0
## 5 256. 0
## 6 256. 0
## 7 257. 0
## 8 257. 0
## 9 258. 0
## 10 258 0
## # ℹ 1,272 more rows
## --- Member: Norlux_NHXRGB090S00S_RGB ---
## Object: source_spct [4,323 x 3]
## containing 3 spectra in long form
## Wavelength range 250-900 nm, step 0.01-1.81 nm
## Label: 12W RGB LED COB Type NHXRGB090S00S from Norlux
## Measured on 2013-11-27 UTC
## Time unit 1s
##
## # A tibble: 4,323 × 3
## w.length s.e.irrad channel
## <dbl> <dbl> <fct>
## 1 250 0 R
## 2 250. 0 R
## 3 250. 0 R
## 4 251. 0 R
## 5 251. 0 R
## 6 252. 0 R
## 7 252. 0 R
## 8 253. 0 R
## 9 253. 0 R
## 10 254. 0 R
## # ℹ 4,313 more rows
##
## --- END ---
And below we use a computed one. In this case we extract the member
spectra with names containing the string “QDDH”.
leds.mspct[grep("QDDH", names(leds.mspct))]
## Object: source_mspct [4 x 1]
## --- Member: QuantumDevices_QDDH66002 ---
## Object: source_spct [1,267 x 2]
## Wavelength range 250.01-900 nm, step 0.43-7.19 nm
## Label: LED, type: QDDH66002 from Quantum Devices, USA; ca. 1995
## Measured on 2011-07-30 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 652.01 nm (max in 250.01-900 nm)
##
## # A tibble: 1,267 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258 0
## 10 258. 0
## # ℹ 1,257 more rows
## --- Member: QuantumDevices_QDDH68002 ---
## Object: source_spct [1,264 x 2]
## Wavelength range 250.01-900 nm, step 0.43-7.18 nm
## Label: LED, type: QDDH68002 from Quantum Devices, USA; ca. 1995
## Measured on 2011-07-30 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 673.4 nm (max in 250.01-900 nm)
##
## # A tibble: 1,264 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258 0
## 10 258. 0
## # ℹ 1,254 more rows
## --- Member: QuantumDevices_QDDH70002 ---
## Object: source_spct [1,250 x 2]
## Wavelength range 250.01-900 nm, step 0.43-7.17 nm
## Label: LED, type: QDDH70002 from Quantum Devices, USA; ca. 1995
## Measured on 2011-07-30 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 707.13 nm (max in 250.01-900 nm)
##
## # A tibble: 1,250 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258 0
## 10 258. 0
## # ℹ 1,240 more rows
## --- Member: QuantumDevices_QDDH73502 ---
## Object: source_spct [1,256 x 2]
## Wavelength range 250.01-900 nm, step 0.43-7.13 nm
## Label: LED, type: QDDH73502 from Quantum Devices, USA; ca. 1995
## Measured on 2011-07-30 UTC
## Time unit 1s
## Spectral data normalized to s.e.irrad = 1 at 746.42 nm (max in 250.01-900 nm)
##
## # A tibble: 1,256 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 250. 0
## 2 255. 0
## 3 255. 0
## 4 256. 0
## 5 256. 0
## 6 257. 0
## 7 257. 0
## 8 258. 0
## 9 258 0
## 10 258. 0
## # ℹ 1,246 more rows
##
## --- END ---
Calculating summaries from the normalized data
Many of 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 when the measuring
conditions used are not well known, and in many cases not well
characterized (e.g. distance from LED to cosine diffuser or exact
alignment of the spectrometer input optics with respect to light source
was not recorded or attempted at the time of measurement).
What we will do in this section is to rescale the spectral data so
that after conversion 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 10 W m-2 for the range 315 to 400 nm.
my.spct <- fscale(leds.mspct$Roithner_UV395,
range = c(315, 400),
e_irrad,
target = 10
)
e_irrad(my.spct, waveband(c(315,400)))
## E_range.315.400
## 10
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
The default of fscale() is to treat rescaled spectral
data as if they were true readings unless target = 1 is
passed. In this last case, the metadata will be set to indicate that the
data is in relative units and this will generate a warning during
computation of irradiance. Other methods such as
integrate_spct() will still function silently.
my.spct <- fscale(leds.mspct$Roithner_UV395,
range = c(315, 400),
e_irrad,
target = 1
)
integrate_spct(my.spct)
## e.irrad
## 1.157884
We can reset the attribute with method setScaled(). With
method getScaled() we can test if a spectrum has been
scaled.
setScaled(my.spct)
getScaled(my.spct)
## [1] FALSE
e_irrad(my.spct, waveband(c(315,400)))
## E_range.315.400
## 1
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
If for some obscure reason we want to simply “pretend” that the
spectral data have not been normalized, we can permanently override the
attribute on a copy of the data. Most of the time this is a very bad
idea!
my.UV395 <- leds.mspct$Roithner_UV395
setNormalized(my.UV395)
e_irrad(my.UV395)
## E_Total
## 16.10795
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
As mentioned above, ratios can be calculated directly as they are not
affected by normalization.
q_ratio(leds.mspct$Roithner_UV395, UVB(), UVA())
## UVB:UVA[q:q]
## 0
## attr(,"radiation.unit")
## [1] "q:q ratio"
Plotting
Spectra can be plotted in the same ways as other data stored in data
frames, using base R graphics, package ‘lattice’ or ‘ggplot2’. However,
another package in our suite, ‘ggspectra’, built as an extension to
‘ggplot2’ makes plotting spectra even easier.
autoplot() methods use the metadata in the objects to
set labels and decorations, as well as automatically setting the mapping
of the x and y aesthetics.
autoplot(leds.mspct$LedEngin_LZ1_10R302_740nm, annotations = c("+", "wls"), )
Package ‘ggspectra’ also defines specializations of method
ggplot() for spectra.
ggplot(leds.mspct$LedEngin_LZ1_10R302_740nm) +
geom_line()
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 rather compatible reimplementation
of data.frame the data can be used very easily with any R
function.
head(as.data.frame(leds.mspct$LedEngin_LZ1_10R302_740nm))
## w.length s.e.irrad
## 1 251.29 0
## 2 258.88 0
## 3 266.48 0
## 4 274.06 0
## 5 276.91 0
## 6 277.38 0
Of course attach and with also work as
expected.
attach(leds.mspct)
q_ratio(Roithner_UV395, UVB(), UVA())
## UVB:UVA[q:q]
## 0
## attr(,"radiation.unit")
## [1] "q:q ratio"
attach(leds.mspct)
with(Roithner_UV395, max(w.length))
## [1] 899.78
with(leds.mspct, q_ratio(Roithner_UV395, UVB(), UVA()))
## UVB:UVA[q:q]
## 0
## attr(,"radiation.unit")
## [1] "q:q ratio"