Introduction

This package, is a data only package, part of a suite, which has package ‘photobiology’ at its core. Please visit (http://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(photobiologyLEDs)
library(ggplot2)
library(ggspectra)

In this very 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 haver been measured with another spectrometers 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.

All the spectral data in this package are stored in a single R object, a collection of spectra of class source_spct. 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 or from a given manufacturer. 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.

blue_leds
## [1] "NHXRGB090_B"     "LED435_66_60"    "weili430nm"      "LZ1_10UA00_00U8"
## [5] "LZ1_10DB00"
led_engin
## [1] "LZ1_10UV00"    "LZ1_10UA00_U4" "LZ1_10UA00_U8" "LZ1_10DB00"   
## [5] "LZ1_10R302"    "LZ4_10R208"

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(leds.mspct)
##  [1] "BS436"           "CB30"            "LED405"         
##  [4] "LED740"          "UV395"           "XSL365"         
##  [7] "XSL370"          "XSL375"          "UVMAX340"       
## [10] "UVMAX305"        "TY_UV310nm"      "white"          
## [13] "Q36_4000K"       "G_P30R140A1_XT"  "weili430nm"     
## [16] "weili540nm"      "weili665nm"      "weili740nm"     
## [19] "HPR40E_48K30BG"  "NHXRGB090_R"     "NHXRGB090_G"    
## [22] "NHXRGB090_B"     "NHXRGB090"       "B5_436_30D"     
## [25] "FR_OLD"          "HLMB_CB30"       "HLMB_CD31_take2"
## [28] "HLMP_CB31"       "HLMP_CM30"       "HLMP_CM31"      
## [31] "HLMP_DJ32"       "HLMP_DL32"       "LED435_66_60"   
## [34] "LED740_01AV"     "LY5436"          "QDDH66002"      
## [37] "QDDH68002"       "QDDH70002"       "QDDH73502"      
## [40] "LZ1_10UV00"      "LZ1_10UA00_U4"   "LZ1_10UA00_U8"  
## [43] "LZ1_10DB00"      "LZ1_10R302"      "LZ4_10R208"     
## [46] "NS6L183AT_H1"    "G_P3V140B1_G"    "G_P3V140B1_GT"  
## [49] "G_P3V140A1_YG"   "G_P3V140A1_YG1"  "MTSM340UV_F5120"

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

leds.mspct$UV395
## Object: source_spct [1,425 x 2]
## Wavelength range 250.05 to 899.78 nm, step 0.43 to 0.48 nm 
## Label: Measured with spectrometer: MAYP11278 on 2012-05-16 13:47:49
## processed on 2015-09-06 with MayaCalc ver 3.2.2
## using HDR: FALSE, using NR: FALSE, method: full
## calibration dated (automatic): 2012-03-26
## number of scans, short: 3, long: 0
## integration times, short (s): 1, long (s): NA
## total measurement time, short (s): 3, long: NA
## max counts, short: 49951 out of 65000 (77%): signal O.K. 
## Time unit 1s
## Spectral data normalized to 1 at 391.03 nm 
## 
## # A tibble: 1,425 x 2
##    w.length s.e.irrad
##       <dbl>     <dbl>
##  1      250         0
##  2      251         0
##  3      251         0
##  4      251         0
##  5      252         0
##  6      252         0
##  7      253         0
##  8      253         0
##  9      254         0
## 10      254         0
## # ... with 1,415 more rows
leds.mspct[["UV395"]]
## Object: source_spct [1,425 x 2]
## Wavelength range 250.05 to 899.78 nm, step 0.43 to 0.48 nm 
## Label: Measured with spectrometer: MAYP11278 on 2012-05-16 13:47:49
## processed on 2015-09-06 with MayaCalc ver 3.2.2
## using HDR: FALSE, using NR: FALSE, method: full
## calibration dated (automatic): 2012-03-26
## number of scans, short: 3, long: 0
## integration times, short (s): 1, long (s): NA
## total measurement time, short (s): 3, long: NA
## max counts, short: 49951 out of 65000 (77%): signal O.K. 
## Time unit 1s
## Spectral data normalized to 1 at 391.03 nm 
## 
## # A tibble: 1,425 x 2
##    w.length s.e.irrad
##       <dbl>     <dbl>
##  1      250         0
##  2      251         0
##  3      251         0
##  4      251         0
##  5      252         0
##  6      252         0
##  7      253         0
##  8      253         0
##  9      254         0
## 10      254         0
## # ... with 1,415 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["UV395"]
## Object: source_mspct [1 x 1]
## --- Member: UV395 ---
## Object: source_spct [1,425 x 2]
## Wavelength range 250.05 to 899.78 nm, step 0.43 to 0.48 nm 
## Label: Measured with spectrometer: MAYP11278 on 2012-05-16 13:47:49
## processed on 2015-09-06 with MayaCalc ver 3.2.2
## using HDR: FALSE, using NR: FALSE, method: full
## calibration dated (automatic): 2012-03-26
## number of scans, short: 3, long: 0
## integration times, short (s): 1, long (s): NA
## total measurement time, short (s): 3, long: NA
## max counts, short: 49951 out of 65000 (77%): signal O.K. 
## Time unit 1s
## Spectral data normalized to 1 at 391.03 nm 
## 
## # A tibble: 1,425 x 2
##    w.length s.e.irrad
##       <dbl>     <dbl>
##  1      250         0
##  2      251         0
##  3      251         0
##  4      251         0
##  5      252         0
##  6      252         0
##  7      253         0
##  8      253         0
##  9      254         0
## 10      254         0
## # ... with 1,415 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.

leds.mspct[norlux]
## Object: source_mspct [4 x 1]
## --- Member: NHXRGB090_R ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: Norlux 90 die LED array type NHXRGB0905005, red channel 
## Time unit 1s
## Spectral data normalized to 1 at 643.08 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250         0
##  2      250         0
##  3      250         0
##  4      251         0
##  5      251         0
##  6      252         0
##  7      252         0
##  8      253         0
##  9      253         0
## 10      254         0
## # ... with 1,435 more rows
## --- Member: NHXRGB090_G ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: Norlux 90 die LED array type NHXRGB0905005, green channel 
## Time unit 1s
## Spectral data normalized to 1 at 515.52 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250         0
##  2      250         0
##  3      250         0
##  4      251         0
##  5      251         0
##  6      252         0
##  7      252         0
##  8      253         0
##  9      253         0
## 10      254         0
## # ... with 1,435 more rows
## --- Member: NHXRGB090_B ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: Norlux 90 die LED array type NHXRGB0905005, blue channel 
## Time unit 1s
## Spectral data normalized to 1 at 462.59 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250         0
##  2      250         0
##  3      250         0
##  4      251         0
##  5      251         0
##  6      252         0
##  7      252         0
##  8      253         0
##  9      253         0
## 10      254         0
## # ... with 1,435 more rows
## --- Member: NHXRGB090 ---
## Object: source_spct [4,335 x 3]
## containing 3 spectra in long form
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## R label: Norlux 90 die LED array type NHXRGB0905005, red channel
## G label: Norlux 90 die LED array type NHXRGB0905005, green channel
## B label: Norlux 90 die LED array type NHXRGB0905005, blue channel 
## R measured at NA N, NA E
## G measured at NA N, NA E
## B measured at NA N, NA E 
## Time unit 1s
## Spectral data normalized to 1 at TRUE 
## 
## # A tibble: 4,335 x 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      
## # ... with 4,325 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: QDDH66002 ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: LED, type  QDDH66002 
## Measured on 2016-07-05 10:00:00 UTC 
## Time unit 1s
## Spectral data normalized to 1 at 652.01 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250   0      
##  2      250   0      
##  3      250   0.00267
##  4      251   0.00156
##  5      251   0      
##  6      252   0      
##  7      252   0.0105 
##  8      253   0      
##  9      253   0      
## 10      254   0      
## # ... with 1,435 more rows
## --- Member: QDDH68002 ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: LED, type  QDDH68002 
## Measured on 2016-07-05 10:00:00 UTC 
## Time unit 1s
## Spectral data normalized to 1 at 673.4 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250   0      
##  2      250   0      
##  3      250   0      
##  4      251   0.00603
##  5      251   0      
##  6      252   0      
##  7      252   0.00392
##  8      253   0      
##  9      253   0      
## 10      254   0      
## # ... with 1,435 more rows
## --- Member: QDDH70002 ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: LED, type  QDDH70002 
## Measured on 2016-07-05 10:00:00 UTC 
## Time unit 1s
## Spectral data normalized to 1 at 707.13 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250         0
##  2      250         0
##  3      250         0
##  4      251         0
##  5      251         0
##  6      252         0
##  7      252         0
##  8      253         0
##  9      253         0
## 10      254         0
## # ... with 1,435 more rows
## --- Member: QDDH73502 ---
## Object: source_spct [1,445 x 2]
## Wavelength range 250 to 900 nm, step 0.01 to 0.47 nm 
## Label: LED, type  QDDH73502 
## Measured on 2016-07-05 10:00:00 UTC 
## Time unit 1s
## Spectral data normalized to 1 at 746.42 nm 
## 
## # A tibble: 1,445 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      250   0.00807
##  2      250   0.00825
##  3      250   0      
##  4      251   0      
##  5      251   0      
##  6      252   0      
##  7      252   0      
##  8      253   0      
##  9      253   0      
## 10      254   0      
## # ... with 1,435 more rows
## 
## --- END ---

Querying metadata

If package ‘photobiology’ is loaded then the specialised print() method will be used and a summary of the metadata will be included in the header of the printout.

leds.mspct$LZ1_10R302
## Object: source_spct [1,421 x 2]
## Wavelength range 251.16 to 898.81 nm, step 0.43 to 0.48 nm 
## Label: LED Engin type LZ1-10R302, Far red 740 nm
## Measured at 700 mA, and at 40 mm from cosine diffuser. 
## Measured on 2017-06-07 16:04:58 UTC 
## Time unit 1s
## 
## # A tibble: 1,421 x 2
##    w.length s.e.irrad
##  *    <dbl>     <dbl>
##  1      251   0.00308
##  2      252   0.00353
##  3      252   0.00363
##  4      253   0.00382
##  5      253   0.00314
##  6      254   0.00184
##  7      254   0.00317
##  8      254   0.00442
##  9      255   0.00281
## 10      255   0.00345
## # ... with 1,411 more rows
getWhatMeasured(leds.mspct$LZ1_10R302)
## [1] "LED Engin type LZ1-10R302, Far red 740 nm\nMeasured at 700 mA, and at 40 mm from cosine diffuser."
getWhenMeasured(leds.mspct$LZ1_10R302)
## [1] "2017-06-07 16:04:58 UTC"
getInstrDesc(leds.mspct$LZ1_10R302)
## Data acquired with 'MayaPro2000' s.n. MAYP11278
## grating 'HC1', slit '010s'
getInstrSettings(leds.mspct$LZ1_10R302)
## integ. time (s): 0.0183, 0.183
## total time (s): 5.01, 5.12
## counts @ peak (% of max): 94.1
is_normalized(leds.mspct$LZ1_10R302)
## [1] FALSE
leds.mspct$UVMAX305
## Object: source_spct [1,425 x 2]
## Wavelength range 250.14 to 899.77 nm, step 0.43 to 0.48 nm 
## Label: UVA LED 310nm Roithner-Laser (SeTi UVCLEAN) type UVMAX305-HL-15 (hemispherical lens), measured at 100 mm distance from cosine difuser 
## Time unit 1s
## Spectral data normalized to 1 at 313.14 nm 
## 
## # A tibble: 1,425 x 2
##    w.length s.e.irrad
##       <dbl>     <dbl>
##  1      250         0
##  2      251         0
##  3      251         0
##  4      252         0
##  5      252         0
##  6      253         0
##  7      253         0
##  8      253         0
##  9      254         0
## 10      254         0
## # ... with 1,415 more rows
is_normalized(leds.mspct$UVMAX305)
## [1] TRUE

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$UV395,
                  range = c(315, 400),
                  e_irrad,
                  target = 10
                  )
e_irrad(my.spct, waveband(c(315,400)))
## Warning in irrad_spct(spct, w.band = w.band, unit.out = "energy", quantity
## = quantity, : Summarized spectral data have been rescaled
##  range.315.400 
##             10 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "energy irradiance total"

If we want to treat the rescaled spectral data, as if they were true readings with no scaling we can reset the attribute with method setScaled(). With method getScaled() we can test if a spectrum has been scaled.

getScaled(my.spct)
## $multiplier
## [1] 0.7190004
## 
## $f
## [1] "a user supplied R function"
## 
## $range
## [1] 315 400
## 
## $target
## [1] 10
setScaled(my.spct)
getScaled(my.spct)
## [1] FALSE

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$UV395
setNormalized(my.UV395)
e_irrad(my.UV395)
##    Total 
## 16.10323 
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "energy irradiance total"

As mentioned above, ratios can be calculated directly as they are not affected by normalization.

q_ratio(leds.mspct$UV395, UVB(), UVA())
##  UVB.ISO: UVA.ISO(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.

plot() 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.

plot(leds.mspct$LZ1_10R302)

Package ‘ggspectra’ also defines specializations of method ggplot() for spectra.

ggplot(leds.mspct$LZ1_10R302) +
  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$UV395))
##   w.length s.e.irrad
## 1   250.05         0
## 2   250.52         0
## 3   251.00         0
## 4   251.47         0
## 5   251.95         0
## 6   252.42         0

Of course attach and with also work as expected.

attach(leds.mspct)
q_ratio(UV395, UVB(), UVA())
##  UVB.ISO: UVA.ISO(q:q) 
##                      0 
## attr(,"radiation.unit")
## [1] "q:q ratio"
detach(leds.mspct)
attach(leds.mspct)
with(UV395, max(w.length))
## [1] 899.78
detach(leds.mspct)
with(leds.mspct, q_ratio(UV395, UVB(), UVA()))
##  UVB.ISO: UVA.ISO(q:q) 
##                      0 
## attr(,"radiation.unit")
## [1] "q:q ratio"