photobiologyLamps 0.4.1
User Guide

Pedro J. Aphalo

2016-10-22

knitr::opts_chunk$set(fig.width=8, fig.height=4)
library(photobiology)
library(photobiologyWavebands)
library(photobiologyLamps)

Introduction

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.

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

names(lamps.mspct)
##  [1] "incandescent.60w"   "osram.36w.25"       "osram.hqit.400w"   
##  [4] "osram.super.vialox" "philips.pls11w.827" "philips.tld36w.15" 
##  [7] "philips.tld36w.18"  "philips.tld36w.83"  "philips.tld36w.865"
## [10] "philips.tld36w.89"  "philips.tld36w.92"  "philips.tll36w.950"
## [13] "sylvania.215w.vho"  "qpanel.uvb313"      "qpanel.uva340"     
## [16] "philips.tl12.mc"    "philips.tl01"       "philips.tl12"      
## [19] "germicidal"

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

lamps.mspct$incandescent.60w
## Object: source_spct [601 x 2]
## Wavelength range 300 to 900 nm, step 1 nm 
## Label: File: Incandescent.60W.PRN
## Measured on 0000-08-18 15:27:00 UTC
## Time unit 1s
## Spectral data normalized to 1 at 900 nm 
## 
## # A tibble: 601 × 2
##    w.length    s.e.irrad
##       <dbl>        <dbl>
## 1       300 0.0006650365
## 2       301 0.0003254116
## 3       302 0.0009560352
## 4       303 0.0007024644
## 5       304 0.0003059931
## 6       305 0.0008253680
## 7       306 0.0010304852
## 8       307 0.0003612069
## 9       308 0.0004965400
## 10      309 0.0006271703
## # ... with 591 more rows
lamps.mspct[["incandescent.60w"]]
## Object: source_spct [601 x 2]
## Wavelength range 300 to 900 nm, step 1 nm 
## Label: File: Incandescent.60W.PRN
## Measured on 0000-08-18 15:27:00 UTC
## Time unit 1s
## Spectral data normalized to 1 at 900 nm 
## 
## # A tibble: 601 × 2
##    w.length    s.e.irrad
##       <dbl>        <dbl>
## 1       300 0.0006650365
## 2       301 0.0003254116
## 3       302 0.0009560352
## 4       303 0.0007024644
## 5       304 0.0003059931
## 6       305 0.0008253680
## 7       306 0.0010304852
## 8       307 0.0003612069
## 9       308 0.0004965400
## 10      309 0.0006271703
## # ... with 591 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["incandescent.60w"]
## Object: source_mspct [1 x 1]
## --- Member: incandescent.60w ---
## Object: source_spct [601 x 2]
## Wavelength range 300 to 900 nm, step 1 nm 
## Label: File: Incandescent.60W.PRN
## Measured on 0000-08-18 15:27:00 UTC
## Time unit 1s
## Spectral data normalized to 1 at 900 nm 
## 
## # A tibble: 601 × 2
##    w.length    s.e.irrad
##       <dbl>        <dbl>
## 1       300 0.0006650365
## 2       301 0.0003254116
## 3       302 0.0009560352
## 4       303 0.0007024644
## 5       304 0.0003059931
## 6       305 0.0008253680
## 7       306 0.0010304852
## 8       307 0.0003612069
## 9       308 0.0004965400
## 10      309 0.0006271703
## # ... with 591 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[macam]
## Object: source_mspct [3 x 1]
## --- Member: qpanel.uvb313 ---
## Object: source_spct [561 x 2]
## Wavelength range 240 to 800 nm, step 1 nm 
## Time unit 1s
## Spectral data normalized to 1 at 435 nm 
## 
## # A tibble: 561 × 2
##    w.length s.e.irrad
##       <int>     <dbl>
## 1       240         0
## 2       241         0
## 3       242         0
## 4       243         0
## 5       244         0
## 6       245         0
## 7       246         0
## 8       247         0
## 9       248         0
## 10      249         0
## # ... with 551 more rows
## --- Member: qpanel.uva340 ---
## Object: source_spct [561 x 2]
## Wavelength range 240 to 800 nm, step 1 nm 
## Time unit 1s
## Spectral data normalized to 1 at 435 nm 
## 
## # A tibble: 561 × 2
##    w.length s.e.irrad
##       <int>     <dbl>
## 1       240         0
## 2       241         0
## 3       242         0
## 4       243         0
## 5       244         0
## 6       245         0
## 7       246         0
## 8       247         0
## 9       248         0
## 10      249         0
## # ... with 551 more rows
## --- Member: philips.tl12.mc ---
## Object: source_spct [561 x 2]
## Wavelength range 240 to 800 nm, step 1 nm 
## Time unit 1s
## Spectral data normalized to 1 at 435 nm 
## 
## # A tibble: 561 × 2
##    w.length s.e.irrad
##       <int>     <dbl>
## 1       240         0
## 2       241         0
## 3       242         0
## 4       243         0
## 5       244         0
## 6       245         0
## 7       246         0
## 8       247         0
## 9       248         0
## 10      249         0
## # ... with 551 more rows
## 
## --- END ---

And below we use a computed one. In this case we extract the member spectra with names containing the string “osram”.

lamps.mspct[grep("osram", names(lamps.mspct))]
## Object: source_mspct [3 x 1]
## --- Member: osram.36w.25 ---
## Object: source_spct [301 x 2]
## Wavelength range 300 to 900 nm, step 2 nm 
## Label: File: Osram.36W.25.PRN
## Measured on 0000-06-09 09:00:00 UTC
## Time unit 1s
## Spectral data normalized to 1 at 436 nm 
## 
## # A tibble: 301 × 2
##    w.length    s.e.irrad
##       <dbl>        <dbl>
## 1       300 2.994543e-04
## 2       302 2.049395e-04
## 3       304 3.542166e-04
## 4       306 7.574829e-05
## 5       308 2.918957e-04
## 6       310 2.466197e-04
## 7       312 2.385391e-04
## 8       314 3.298040e-04
## 9       316 3.195879e-04
## 10      318 1.550902e-04
## # ... with 291 more rows
## --- Member: osram.hqit.400w ---
## Object: source_spct [301 x 2]
## Wavelength range 300 to 900 nm, step 2 nm 
## Label: File: Osram.HQIT.400W.PRN
## Measured on 0000-10-11 18:57:00 UTC
## Time unit 1s
## Spectral data normalized to 1 at 592 nm 
## 
## # A tibble: 301 × 2
##    w.length    s.e.irrad
##       <dbl>        <dbl>
## 1       300 0.0003819866
## 2       302 0.0006407381
## 3       304 0.0006153198
## 4       306 0.0007611658
## 5       308 0.0007947333
## 6       310 0.0010225850
## 7       312 0.0014072015
## 8       314 0.0016203412
## 9       316 0.0016059060
## 10      318 0.0016971534
## # ... with 291 more rows
## --- Member: osram.super.vialox ---
## Object: source_spct [301 x 2]
## Wavelength range 300 to 900 nm, step 2 nm 
## Label: File: Osram.Super.Vialox.PRN
## Measured on 0000-10-17 13:54:00 UTC
## Time unit 1s
## Spectral data normalized to 1 at 820 nm 
## 
## # A tibble: 301 × 2
##    w.length    s.e.irrad
##       <dbl>        <dbl>
## 1       300 0.0002346271
## 2       302 0.0001961201
## 3       304 0.0002365132
## 4       306 0.0003779954
## 5       308 0.0005526084
## 6       310 0.0009019995
## 7       312 0.0013867891
## 8       314 0.0019810600
## 9       316 0.0026955577
## 10      318 0.0034839014
## # ... with 291 more rows
## 
## --- END ---

Calculating summaries from the normalized 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 nearby reflecting walls, or exact alignment of the spectrometer input optics with respect to light sources).

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 100 W m-2 for the range 400 to 700 nm.

my.spct <- fscale(lamps.mspct$incandescent.60w,
                  range = c(400, 700),
                  e_irrad,
                  target = 100
                  )
e_irrad(my.spct, waveband(c(400,700)))
## Warning in irrad_spct(spct, w.band = w.band, unit.out = "energy", quantity
## = quantity, : Summarized spectral data have been rescaled
##  range.400.700 
##            100 
## 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 spectrun has been scaled.

getScaled(my.spct)
## $multiplier
## [1] 1.293194
## 
## $f
## [1] "a user supplied R function"
## 
## $range
## [1] 400 700
## 
## $target
## [1] 100
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.lamp <- lamps.mspct$incandescent.60w
setNormalized(my.lamp)
e_irrad(my.lamp)
##    Total 
## 247.1079 
## 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(lamps.mspct$incandescent.60w, Red("Smith10"), Far_red("Smith10"))
##  Red.Smith10: FarRed.Smith10(q:q) 
##                         0.6606633 
## attr(,"radiation.unit")
## [1] "q:q ratio"

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(lamps.mspct$incandescent.60w))
##   w.length    s.e.irrad
## 1      300 0.0006650365
## 2      301 0.0003254116
## 3      302 0.0009560352
## 4      303 0.0007024644
## 5      304 0.0003059931
## 6      305 0.0008253680

Of course attach and with also work as expected.

attach(lamps.mspct)
q_ratio(incandescent.60w, Blue(), Red())
##  Blue.ISO: Red.ISO(q:q) 
##              0.03251342 
## attr(,"radiation.unit")
## [1] "q:q ratio"
detach(lamps.mspct)
attach(lamps.mspct)
with(incandescent.60w, max(w.length))
## [1] 900
detach(lamps.mspct)
with(lamps.mspct, q_ratio(incandescent.60w, Blue(), Red()))
##  Blue.ISO: Red.ISO(q:q) 
##              0.03251342 
## attr(,"radiation.unit")
## [1] "q:q ratio"