The User Guide is divided into two volumes: 1. Radiation and 2. Astronomy. The second volume also describes functions related to water vapour in the atmosphere.
I have developed package ‘photobiology’ over several years, and even though I have tried to remain consistent, some inconsistencies have crept in. I have attempted to correct inconsistencies without breaking old code by providing synonyms for some functions.
In general I have used names in snake case for methods and
functions, such as source_spct()
and dot case for
their arguments. There are two exceptions to this: the as.
and is.
methods which for consistency with base R, retain
the dot: as.source_spct()
and
ìs.source_spct()
. There are still some functions and
methods whose names are in camel case: these are mostly
accessors and setters of metadata attributes such as
setWhatMeasured()
and getWhatMeasured()
, in
which case synonyms what_measured<-()
and
what_measured()
are now provided with a syntax that
parallels that of R’s comment<-()
,
comment()
, and similar methods for other attributes. Names
of attributes themselves use dots, while classes use snake case as
functions do, allowing consistency between class names and their
constructor functions. There is an additional twist: functions named
like clip_wl()
are “verbs” that act on the wavelengths
(“wl”) modifying them, while those named like wl_range()
are “nouns” for the properties of the wavelengths.
In examples we use variable names ending in .spct
for
spectra, ending in .mspct
for collections of spectra and
ending in .tb
for tibbles. In most cases the root of the
variable names use “snake case” and may have a tag at the end separated
with a dot. In the case of variable names used in examples I have been
less strict about conventions than for the objects exported by the
package.
None of these naming conventions are enforced for user defined objects and classes; these conventions are simply those I have tried to follow while developing this package as well as other packages in the r4photobiology suite.
The package exports two sets of functions for many operations: low-level functions programmed following a functional paradigm, and higher-level functions using an object-oriented paradigm. The former functions take as arguments numeric vectors and are sometimes faster. The later ones take spectra objects as arguments, are easier to use, and at least at the moment, to some extent slower. For everyday use, methods for spectra objects are recommended, but when maximum performance or flexibility in scripts is desired, the use of the functions taking numeric vectors as arguments may allow optimizations that are not possible with the object-oriented functions. The differences in performance becomes relevant only in extreme cases such as processing in a single script tenths of thousands of spectra. In the vignettes we emphasize the use of the object-oriented classes and methods.
Data for several spectra are included for use in examples and vignettes, and in testing (Tables 1 and 2). Other packages in the ‘r4photobiology suite’ provide many additional data sets.
Table 1. Data sets included in the package: spectra. The CIE standard illuminant data in this package are normalized to one at λ = 560 nm, while in the CIE standard they are normalized to 100 at the same wavelength. See documentation for each data object for details and data sources.
Object | class | units | data description |
---|---|---|---|
sun.spct |
source_spct |
W m−2 nm−1 | solar spectral irradiance |
sun_daily.spct |
source_spct |
J m−2 d−1 nm−1 | solar spectral exposure |
sun.data |
data.frame |
W m−2 nm−1 | solar spectral irradiance |
sun_daily.data |
data.frame |
J m−2 d−1 nm−1 | solar spectral exposure |
D65.illuminant.spct |
source_spct |
(norm. 560 nm) | CIE standard |
A.illuminant.spct |
source_spct |
(norm. 560 nm) | CIE standard |
clear.spct |
filter_spct |
fraction | ideal transparent filter |
opaque.spct |
filter_spct |
fraction | ideal opaque filter |
polyester.spct |
filter_spct |
fraction | plastic film |
yellow_gel.spct |
filter_spct |
fraction | theatrical gel filter |
green_leaf.spct |
reflector_spct |
fraction | a birch leaf |
clear_body.spct |
object_spct |
fraction | ideal transparent body |
black_body.spct |
object_spct |
fraction | ideal black body |
white_body.spct |
object_spct |
fraction | ideal white body |
Ler_leaf.spct |
object_spct |
fraction | Arabidopsis leaf |
Ler_leaf_trns.spct |
filter_spct |
fraction | Arabidopsis leaf (T total) |
Ler_leaf_trns_i.spct |
filter_spct |
fraction | Arabidopsis leaf (T internal) |
Ler_leaf_rflt.spct |
reflector_spct |
fraction | Arabidopsis leaf (R total) |
water.spct |
solute_spct |
m−1 | pure water molar att. coef. |
phenylalanine |
solute_spct |
m−1 | phenylalanine molar att. coef. |
photodiode.spct |
response_spct |
A/W | typical Si photodiode |
ccd.spct |
response_spct |
A/W | typical CCD array |
white_led.raw_spct |
raw_spct |
counts | example raw detector counts data |
white_led.cps_spct |
cps_spct |
counts / s | example detector counts data |
white_led.source_spct |
source_spct |
W m−2 nm−1 | spectral irradiance |
filter_cps.mspct |
cps_mspct |
counts/s | example detector counts data |
Table 2. Data sets included in the package: chromaticity data. See documentation for each data object for details and data sources.
Object | class | data description |
---|---|---|
ciexyzCC2.spct |
chroma_spct |
human chromaticity coordinates 2∘ |
ciexyzCC10.spct |
chroma_spct |
human chromaticity coordinates 10∘ |
ciexyzCMF2.spct |
chroma_spct |
human colour matching function 2∘ |
ciexyzCMF10.spct |
chroma_spct |
human colour matching function 10∘ |
ciev2.spct |
chroma_spct |
human luminous efficiency 2∘ |
beesxyzCMF.spct |
chroma_spct |
bee colour matching function |
Package ‘photobiology’ defines a family of classes
based on the tibble
class, mostly compatible with R’s data
frames. The present package by imposing some restrictions on the naming
of the member vectors, allows methods to find the data when
passed one of these objects as argument. In addition, as the data are
checked when the object is built or modified, there is no need to test
for their validity each time a calculation is carried out. Another
advantage of using spectrum objects, is that specialized versions of
generic functions like print
and operators like
+
are defined for spectra. Objects of all the
..._spct
classes are also tibble
and
data.frame
objects, as a result of how classes have been
derived.
In this package we define a generic or base
spectrum class, derived from tibble
, which in turn has been
derived from data.frame
. Classes for specialized types of
spectra are derived from generic_spct
. This
parenthood hierarchy means that spectral objects can be used
almost anywhere where a data.frame
is expected (and also
converted into data frames with R’s function
as.data.frame()
). Specializations of many methods including
extraction (indexing) methods and partial assignment methods are defined
to ensure that the expectations on the variables contained in objects of
these classes remain valid in most situations. Other specializations of
methods and functions are related to achieving a convenient and concise
syntax tailored for spectral data as in the case of mathematical
operators and functions.
Another important aspect is that when spectral data are stored in objects of these classes, the physical quantities and units of expression are also stored as metadata. Furthermore, attributes are used to keep track of both metadata related to the origin of the data and of later transformations that affect their interpretation, such as normalization or re-scaling. Although sanity tests are applied at the time of object creation, to a large extent the responsibility of ensuring that the numbers provided as argument to object constructors comply with expectations remains with the users of the package.
In addition to the classes for storing individual spectra, classes
for storing collections of these spectral objects are defined. These
classes are derived from class list
and can contain member
spectra of different lengths and measured at different wavelength
values.
We give in this vignette brief descriptions and examples of the use of different classes, methods, functions and operators. We start with the simplest and most frequently used methods.
We load two packages in addition to ‘photobiology’, ‘lubridate’ and ‘dplyr’, as they will be used in the examples.
Package ‘photobiology’ defines several classes
intended to be used to store different types of spectral data. They are
all derived from generic_spct
, which in turn is derived
from tibble::tibble
. Table 1 lists these classes.
Attributes are used to store metadata such as information about
units of expression.
Table 1. Classes for spectral data. In addition to
the required variables listed in the table, additional arbitrary
variables are partly supported—some operations will not include them in
returned values to avoid ambiguity and other possible conflicts. In
addition to the attributes listed in the table, all spectral objects
support attributes multiple.wl
, idfactor
,
normalized
, scaled
,
when.measured
, where.measured
,
what.measured
, how.measured
plus the normal
attributes of tibble
(and data.frame
) objects
including comment
. All these attributes plus attributes
instrument.descriptor
and instrument.settings
are retained across operations on spectra as long as they remain
valid.
Class name | Required variables | Attributes |
---|---|---|
generic_spct |
w.length |
|
calib ration_spct |
w.length , irrad.mult |
instr.desc |
raw_spct |
w.length , counts |
instr.desc , instr.settings ,
linearized |
cps_spct |
w.length , cps |
instr.desc , instr.settings ,
linearized |
source_spct |
w.length , s.e.irrad |
instr.desc , instr.settings ,
time.unit , bswf |
w.length , s.q.irrad |
time.unit , bswf |
|
filter_spct |
w.length , Tfr |
Tfr.type ,
filter.properties |
w.length , A |
Tfr.type ,
filter.roperties |
|
ref lector_spct |
w.length , Rfr |
Rfr.type |
object_spct |
w.length , Tfr ,
Rfr |
Tfr.type , Rfr.type |
re sponse_spct |
w.length , s.e.response |
time.unit |
w.length , s.q.response |
time.unit |
|
chroma_spct |
w.length , x , y ,
z |
|
solute_spct |
w.length , K.mole |
K.type ,
solute.properties |
w.length , K.mass |
K.type ,
solute.properties |
The design imposes the restriction that data from different observations are never present as different data columns, if present, additional data columns represent different properties from the same observation event. In other words, the storage format is tidy as nicknamed by Hadley Wickham. In most cases, one spectral object correspond to one spectral observation, but most functions and methods are compatible or can be used to create spectral objects where the spectral data from different observations are stored “longitudinally” and “tagged” with a factor with a level for each observation event. These observations must use consistent units of expression. This long format is useful, for example, when producing plots with package ‘ggplot2’ or when acquiring or storing time series of spectra. If spectra are stored in long form, e.g. for plotting with ‘ggplot2’, attributes are stored as named lists or enforced to be the same across spectra. This allows to reconstruct a collection of spectra from a long-form spectral object and vice versa preserving nearly all of the metadata. In ‘photobiology’ (<= 0.11.0) the support for these conversions was limited and spectral objects with multiple spectra in long form created with these versions lack complete metadata or have the metadata stored in a way that cannot be easily retrieved, leading to metadata loss on conversion to collections of spectra.
Collections of spectra are to be in general preferred to multiple spectra stored in a single spectral object. This is because collections are the “native” storage approach in the ‘photobiology’ package, supporting all operations efficiently, while operations on spectra stored in long form are implemented by means of two way on-the-fly conversions into collections of spectra. Two-way conversions can be expected to depend on memory allocation and thus to decrease performance.
A key assumption of the package is that wavelengths are always expressed in manometers (1 nm = 1 ⋅ 10−9 m). If the data to be analysed use different units for wavelengths, e.g. Ångstrom (1 Å = 1 ⋅ 10−10 m), the values need to be re-expressed before creating objects of the spectral classes. The same applies to all spectral quantities, as there is an expectation in every case, of using base SI units for expression. Table 2 lists the units of expression for the different variables and the metadata attributes that may determine variations in the expression of the quantities.
Table 2. Variables used for spectral data and their units of
expression. A: as stored in objects of the
spectral classes, B: also recognized by the
set
family of functions for spectra and automatically
converted. time.unit
accepts in addition to the character
strings listed in the table, objects of classes
lubridate::duration
and period
, in addition
numeric
values are interpreted as seconds.
exposure.time
accepts these same values, but not the
character strings.
Variables | Unit of expression | Attribute value |
---|---|---|
A: stored | ||
w.length | nm | |
counts | n | |
cps | n s−1 | |
irrad.mult | J m−2 nm−1 n−1 | |
s.e.irrad | W m−2 nm−1 | time.unit = “second” |
s.e.irrad | J m−2 d−1 nm−1 | time.unit = “day” |
s.e.irrad | J m−2 nm−1 | time.unit = “exposure” |
s.e.irrad | varies | time.unit = duration |
s.q.irrad | mol m−2 s−1 nm−1 | time.unit = “second” |
s.q.irrad | mol m−2 d−1 nm−1 | time.unit = “day” |
s.q.irrad | mol m−2 nm−1 | time.unit = “exposure” |
s.q.irrad | varies | time.unit = duration |
Tfr | [0..1] | Tfr.type = “total” |
Tfr | [0..1] | Tfr.type = “internal” |
A | a.u. | |
Afr | [0..1] | |
Rfr | [0..1] | Rfr.type = “total” |
Rfr | [0..1] | Rfr.type = “specular” |
s.e.response | x J−1 s−1 nm−1 | time.unit = “second” |
s.e.response | x mol−1 d−1 nm−1 | time.unit = “day” |
s.e.response | x J−1 nm−1 | time.unit = “exposure” |
s.e.response | varies | time.unit = duration |
s.q.response | x mol−1 s−1 nm−1 | time.unit = “second” |
s.q.response | x mol−1 d−1 nm−1 | time.unit = “day” |
s.q.response | x mol−1 nm−1 | time.unit = “exposure” |
s.q.response | varies | time.unit = duration |
x, y, z | [0,1] | |
K.mole | m2 mol−1, log10 based | K.type = “attenuation” |
K.mole | m2 mol−1, log10 based | K.type = “absorption” |
K.mole | m2 mol−1, log10 based | K.type = “scattering” |
K.mass | m2 g−1, log10 based | K.type = “attenuation” |
K.mass | m2 g−1, log10 based | K.type = “absorption” |
K.mass | m2 g−1, log10 based | K.type = “scattering” |
B: converted | ||
wl → w.length | nm | |
wavelength → w.length | nm | |
Tpc → Tfr | [0..100] | Tfr.type = “total” |
Tpc → Tfr | [0..100] | Tfr.type = “internal” |
Rpc → Rfr | [0..100] | Rfr.type = “total” |
Rpc → Rfr | [0..100] | Rfr.type = “specular” |
counts.per.second → cps | n s−1 | |
K.mole loge → log10 | m−1 mol−1, loge based | K.type = “attenuation” |
K.mole loge → log10 | m−1 mol−1, loge based | K.type = “absorption” |
K.mole loge → log10 | m−1 mol−1, loge based | K.type = “scattering” |
K.mass loge → log10 | m−1 g−1, loge based | K.type = “attenuation” |
K.mass loge → log10 | m−1 g−1, loge based | K.type = “absorption” |
K.mass loge → log10 | m−1 g−1, loge based | K.type = “scattering” |
Energy irradiance is assumed to be expressed in W m−2 and photon irradiance in mol−1 m−2 s−1, that is to say using second as unit for time and no SI scale factors for the measured variables. With respect to time, second is the default, but it is possible to set the unit for time to an arbitrary time duration such as day. Obviously, this applies only to rate variables like irradiance and response rates, but not to time-invariant intensive properties like transmittance of filters.
The default time unit used is second, but minute,
hour, day and exposure can be used by
supplying as arguments "minute"
, "hour"
,
"day"
, or "exposure"
—The meaning of
"exposure"
is the total exposure time, in other words,
fluence instead of irradiance—to the constructor
source_spct()
. In addition to these character constants
objects of class lubridate:duration
are also accepted. In
other words irradiance is a flux rate while exposure is a flux, as both
are expressed per unit of illuminated area.
In the case of spectra of the molar attenuation coefficient we use log10 as a base for the stored values but the constructor accepts data expressed in other log bases. The expected units are always in metres (m−1) rather than the frequently used centimetres (cm−1).
Transmittance, reflectance and absorptance are stored as fractions of one. The constructors also accept these quantities expressed as percentages, and convert them.
Most attributes are set when a spectral object is created, either
using default values or with values supplied as arguments to the
constructor. In many cases the default is NA
used to
indicate missing information.
Methods for querying and setting these attributes in already constructed objects are also available.
Not respecting the expectations about data inputs or setting erroneous values in the metadata attributes will yield completely wrong results if calculations are attempted! It is extremely important to make sure that the wavelengths are in nanometres as this is what all functions expect. If wavelength values are in the wrong units, the action-spectra weights and quantum to/from energy units conversions will be wrongly calculated, and the values returned by most functions wrong, without warning. Errors in some cases will be triggered at the time of object creation as the data input to constructors is tested to be within the expected range of values, which in the case of some quantities frequently allows detection of mistakes in the use unit scaling factors.
If spectral irradiance data is in W m−2 nm−1, and the wavelength in nm, as is the case for many Macam spectroradiometers, the data can be used directly and functions in the package will return irradiances in W m−2.
If, for example, the spectral irradiance data output by a spectroradiometer is expressed in mW m−2 nm−1, and the wavelengths are in Ångstrom then to obtain correct results when using any of the packages in the suite, we need to rescale the data when creating a new object.
In the example above, we take advantage of the behaviour of the R language: an operation between a scalar and a vector, is equivalent to applying this operation to each element of the vector. Consequently, in the code above, each value from the vector of wavelengths is divided by 10, and each value in the vector of spectral irradiances is divided by 1000.
Before giving examples of how to construct objects to store spectral
data we show how to query the class of an object, and how to query the
class of a spectrum. Consistently with R, the package provides
is functions for querying the type of spectra objects. The only
unusual function name, defined as a synonym for
is.generic_spct
: is.any_spct()
.
## [1] TRUE
## [1] TRUE
## [1] TRUE
## [1] TRUE
In addition function class_spct()
returns directly the
spectrum-related class attributes—i.e. it filters out from the output of
class()
the underlying inherited classes.
## [1] "source_spct" "generic_spct"
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
There are two different approaches to the creation of spectral
objects by users. The first group are constructors similar to the
data.frame()
constructor, which take vectors as arguments.
The second group are constructors that convert list
objects, and because of class derivation also data.frame
objects, into spectral objects. Constructors in this second group are
similar to as.data.frame
from base R. In contrast to the
data frame constructors, spectral object constructors require the
variables or the vector arguments to be suitably named so that they can
be recognized.
Here we briefly describe the as constructor functions for
spectra. In the first example we create an object to store spectral
irradiance data for a fictitious light source, by first
creating a data frame, and creating the spectral object as a copy of it.
In the example below we supply a single value, 1, for the spectral
irradiance. This value gets recycled as is normal in R, but of course in
real use it is more usual to supply a vector of the same length as the
w.length
vector.
my.df <- data.frame(w.length = 400:410, s.e.irrad = 1)
my.spct <- as.source_spct(my.df)
class(my.spct)
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
## [1] "data.frame"
## Object: source_spct [11 x 2]
## Wavelength range 400-410 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 400 1
## 2 401 1
## 3 402 1
## 4 403 1
## # ℹ 7 more rows
We can copy and convert any spectrum object into any of its base
clases, such as generic_spct
or data.frame
.
This can result in the immediate and surely in the delayed loss of
metadata when modified. In addition, objects downgraded to a
base class support fewer operations and those still available may behave
differently.
## [1] "generic_spct" "tbl_df" "tbl" "data.frame"
When constructing spectral objects from numeric vectors the names of the arguments are meaningful and convey information on the nature of the spectral data and basis of expression.
## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 6 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 300 1
## 2 301 1
## 3 302 1
## 4 303 1
## 5 304 1
## 6 305 1
## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 6 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 300 2
## 2 301 2
## 3 302 2
## 4 303 2
## 5 304 2
## 6 305 2
When argument names are not supplied explicitly as above, the names of the variables are used to identify the data vectors.
## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 6 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 300 1
## 2 301 1
## 3 302 1
## 4 303 1
## 5 304 1
## 6 305 1
The different constructors have additional arguments to be used in setting non-default values for the attributes. These arguments have the same name as the attributes. Here we used the data frame created in the first code chunk of this section.
Argument strict.range
can be used to override or make
more strict the validation of the data values.
## Warning in range_check(x, strict.range = strict.range): Negative spectral
## energy irradiance values; minimum s.e.irrad = -1.00
## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 6 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 300 -1
## 2 301 -1
## 3 302 -1
## 4 303 -1
## 5 304 -1
## 6 305 -1
## Object: source_spct [6 x 2]
## Wavelength range 300-305 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 6 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 300 -1
## 2 301 -1
## 3 302 -1
## 4 303 -1
## 5 304 -1
## 6 305 -1
Argument comment
can be used to add a comment to the
data at the time of construction.
my.cm.spct <- source_spct(w.length = 300:305, s.e.irrad = 1,
comment = "This is a comment")
comment(my.cm.spct)
## [1] "This is a comment"
The constructors treat unrecognized named arguments as data to create aditional columns in the spectral objects.
Metadata attributes are used in the spectral objects to store
metadata in a consistently. These metadata are in some cases required
for conversion among related physical quantities, while in other cases
allow printing of ancillary information needed for interpretation, like
units of expression. These metadata are also used in other packages in
the suite, for example in ‘ggspectra’ to automatically produce axis
labels, titles and annotations. A few attributes are simply a way or
organizing the storage of information which is not used in any
calculations, functioning as a kind of specialized comments. The
metadata described in this section are stored in spectral objects using
attributes, which are a normal feature of the R language. An example, is
attribute time.unit
used to indicate if spectral irradiance
is expressed per second or integrated over some other time duration.
Some attributes are meaningful for all the classes of spectra defined
in the package, while most others a specific to individual classes
(Table 1). Those that apply to all spectral objects and their summaries
are time of measurement using attribute
"when.measured"
, place of measurement using
attribute "where.measured"
, a user supplied label
using attribute "what.measured"
, a label describing origin
of the data using attribute "how.measured"
and free-text
comments. One can set and get comments stored in spectra by
means of base R’s comment()
and
comment() <-
functions and the other attributes listed
above with functions following the same syntax and named after the
attributes but replacing any .
by _
. Functions
in this package may set additional attributes to keep track of the
actions. For example when a spectrum is normalized or scaled a record of
these action is kept in attributes. When spectra are are operated upon
the metadata that is not invalidated will be merged when possible—e.g.,
comments of operands are concatenated comments and set as comment to the
returned object.
Functions when_measured()
and
when_measured<-()
are used for retrieving and setting
the "when.measured"
attribute to a date supplied as a
POSIXct
value. Note: we use POSIXct
objects
which describes instants in time in absolute terms as they include time
zone information. Package lubridate
makes entering and
operating on POSIXct
objects rather easy.
## [1] NA
when_measured(my.spct) <- lubridate::ymd_hms("2015-10-31 22:55:00", tz = "EET")
when_measured(my.spct)
## [1] "2015-10-31 20:55:00 UTC"
Functions where_measured()
and
where_measured<-()
are used for retrieving and setting a
geocode stored in a data.frame
. This format is compatible
with function geocode()
from package ggmap
. We
pass latitude and longitude coordinates, as shown below. The returned
value is always a data frame with columns "lon"
,
"lat"
and "address"
.
## # A tibble: 1 × 3
## lon lat address
## <dbl> <dbl> <chr>
## 1 NA NA <NA>
## # A tibble: 1 × 3
## lat lon address
## <dbl> <dbl> <chr>
## 1 60 -10 <NA>
where_measured(my.spct) <- data.frame(lat = 60, lon = -10, address = "Somewhere")
where_measured(my.spct)
## # A tibble: 1 × 3
## lat lon address
## <dbl> <dbl> <chr>
## 1 60 -10 Somewhere
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2015-10-31 20:55:00 UTC
## Measured at 60 N, -10 E; Somewhere
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
Functions what_measured()
and
where_measured<-()
, and how_measured()
and
how_measured<-()
are used for retrieving or setting a
text value containing information about what was measured to obtain the
data.
## [1] "something"
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: something
## Measured on 2015-10-31 20:55:00 UTC
## Measured at 60 N, -10 E; Somewhere
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
Functions using a different syntax are also available, for these and other attributes which are not likely to be set by users. Many of these additional attributes are meaningful only for some types of spectra.
source_spct
objectsOne example is the time unit used to express spectral irradiance.
Functions are available for querying and setting the state if these
attributes. is_
functions return a logical value, and
get
functions return the values of the attributes
themselves. In addition set
functions can be used to set
the value stored in the attributes. Several of the set
functions are very rarely needed in user code, as these attributes are
set during construction or as a side effect of applying other functions
and/or operators to the objects. Function setBSWFUsed()
and
other set functions are mainly useful to programmers extending
the package, but only exceptionally to users. One exception is the case
when a wrong value has been assigned by mistake and needs to be
overwritten.
We can see in the printout that the time unit is reported in the header.
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
For example function is_effective()
returns
TRUE
if the spectral data has been weighted with a BSWF.
The corresponding getBSWFUsed()
function can be used, in
this case to retrieve the name of the BSWF that was used. Here we
demonstrate with one example, where we use a waveband
object—constructed on-the-fly with a constructor function—, defining a
range of wavelengths.
## [1] FALSE
## [1] FALSE
Sometimes it may be desired to change the time unit used for
expressing spectral irradiance or spectral response, and this can be
achieved with the conversion function
convertTimeUnit
. This function both converts spectral data
to the new unit of expression and sets the time.unit
attribute, preserving the validity of the data object.
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy exposure [J m-2 nm-1]
## s.q.irrad: Spectral photon exposure [mol m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
## [1] "600s (~10 minutes)"
filter_spct
objectsA crucial information is whether transmittance (Tfr
) is
expressed as internal or total, stored in attribute
Tfr.type
, as this affects how absorptances and absorbances
are computed. The key step is when a filter_spct
object is
created, when the user has to be careful to set this attribute
correctly.
The objects from which transmittance can differ in additional
properties that affect possible calculations. Attribute
filter.properties
is used to store these in an object with
fields Rfr.constant
, thickness
and
attenuation.mode
. When these metadata are available, in
many cases we can use function convertTfrType()
to convert
internal transmittance into total transmittance and vice versa
and function convertThickness()
to compute the spectral
transmittance of a filter of the same material but different
thickness.
These attributes are also allowed in the case of
object_spct
and reflector_spct
and retained
during class conversions between them and filter_spct
objects.
They are included in the printout of filter.spct
objects.
## Object: filter_spct [454 x 2]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 454 × 2
## w.length Tfr
## <int> <dbl>
## 1 240 0.00482
## 2 241 0.00464
## 3 242 0.00446
## 4 244 0.00414
## # ℹ 450 more rows
We estimate the spectral transmittance of 2 mm-thick PET film.
## Object: filter_spct [454 x 2]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 2.00, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 454 × 2
## w.length Tfr
## <int> <dbl>
## 1 240 2.70e-37
## 2 241 1.48e-37
## 3 242 7.89e-38
## 4 244 2.39e-38
## # ℹ 450 more rows
Attributes instr_desc
and instr_settings
are used to store measurement-related metadata, describing the
instrument used and its settings. These attributes are lists, with a few
default fields and possibly unlimited special attributes. The
present package provides functions for operating on them and print-outs
include some of the default fields if the attribute is set. The
expectation is that these attributes are set by other packages such as
‘ooacquire’ used for direct data acquisition or raw instrument data
import.
These instrument-specific attributes can contain lots of information
and bloat the size of spectral objects. Two methods,
trimInstrDesc()
and trimInstrSettings()
can be
used to discard parts of these metadata, such as instrument calibration
information, once the raw-counts data have been converted into physical
units.
Spectral objects created with earlier versions (from before the first
CRAN release in 2016) of this package are missing some metadata
attributes. For this reason summary methods from this package
and autoplot()
and ggplot()
methods from
package ‘ggspectra’ may print warnings. These very old objects
can be updated by adding the missing attributes using functions
setTimeUnit
, setBSWFUsed
,
setTfrType
and setRfrType
. However, in many
cases function update_spct
can be used to set the missing
attributes to default values, or user scripts re-run to rebuild the data
objects from raw data.
The package defines several classes intended to be used to store
collections of different types of spectral data. They are all
derived from generic_mspct
, which in turn is derived from
list
. Table 3 lists them.
Table 3. Classes for collections of spectral
objects. Objects of class generic_mspct
can have
member objects of any class derived from generic_spct
and
can be heterogeneous, while the other classes support homogeneous
collections of spectral objects. Attributes of these objects can be
queried and set with the normal R methods attr
and
attributes
as well as with functions defined in this
package. See table 1 for the attributes used in individual member
spectra of collections.
Class name | Class of member objects | Attributes |
---|---|---|
generic_mspct |
generic_spct |
names , dim , comment |
calibration_mspct |
calibration_spct |
names , dim , comment |
raw_mspct |
raw_spct |
names , dim , comment |
cps_mspct |
cps_spct |
names , dim , comment |
source_mspct |
source_spct |
names , dim , comment |
filter_mspct |
filter_spct |
names , dim , comment |
reflector_mspct |
reflector_spct |
names , dim , comment |
object_mspct |
object_spct |
names , dim , comment |
response_mspct |
response_spct |
names , dim , comment |
chroma_mspct |
chroma_spct |
names , dim , comment |
solute_mspct |
solute_spct |
names , dim , comment |
Objects of these classes, except for class
generic_mspct
, can only contain members belonging the
matching class of spectra. As all other spectral object classes are
derived from generic_spct
, generic_mspct
objects can contain heterogeneous collections of spectra. In all cases,
there are no restrictions on the lengths, wavelength range and/or
wavelength step size, or attributes other than class
of the
contained spectra. Mimicking R’s arrays and matrices, a dim
attribute is always present and dim
methods are provided.
This approach is expected to allow the storage of time series of
spectral data, or (hyper)spectral image data, or even higher dimensional
spectral data. The handling of 1D and 2D spectral collections is already
implemented in the summary methods. Handling of 3D and higher
dimensional data can be implemented in the future without changing the
class definitions. By having implemented dim
, also methods
ncol
and nrow
are available as they use
dim
internally. Array-like subscripting collections of
spectra is not implemented.
We can construct a collection using a list of spectral objects as a starting point, in this case the spectral irradiance for sunlight.
## Object: source_mspct [2 x 1]
## --- Member: sun1 ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
## --- Member: sun2 ---
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
##
## --- END ---
We can also create heterogeneous collections, but this drastically limits the methods that are applicable to the resulting collection.
## [1] "generic_mspct" "list"
## $filter
## [1] "filter_spct" "generic_spct"
##
## $source
## [1] "source_spct" "generic_spct"
The as.
coercion methods for collections of spectra, not
only change the class of the collection object, but can also optionally
apply the corresponding as.
functions to the member
objects. A copy of the original object is made and then class-converted
and returned.
## [1] "generic_mspct" "list"
## List of 2
## $ sun1: src_spct [522 × 3] (S3: source_spct/generic_spct/tbl_df/tbl/data.frame)
## $ sun2: src_spct [522 × 3] (S3: source_spct/generic_spct/tbl_df/tbl/data.frame)
In addition to coercion methods for lists of spectra objects, coercion methods are available for lists of data frames (or tibbles) and from matrix objects.
One additional feature is that if a single spectrum object or data frame are coerced into a collection of spectra, the behaviour is equivalent to having passed as argument a list containing such object as its only member.
## [1] "source_mspct" "generic_mspct" "list"
## List of 1
## $ spct_1: src_spct [522 × 3] (S3: source_spct/generic_spct/tbl_df/tbl/data.frame)
Sometimes spectral data stored in a matrix need to be coerced into a collection of spectra. Coercion methods are defined also for this cases. Several spectra may be stored in a matrix either by row or by column, but this can be deduced automatically in the case of rectangular matrices. Wavelengths values are not expected to be part of the matrix, and need to be supplied as a separate numeric vector sorted in ascending order. As in a spectrum wavelength values never repeat, the vector of wavelengths is never recycled and uniqueness of values is enforced.
We here use artificial data, in this first example with spectra saved by column. We assume that the values in the matrix are spectral transmittance stored as percentages (hence “Tpc”).
x <- matrix(1:100, ncol = 2)
wl <- 501:550 # wavelengths in nanometres
as.filter_mspct(x, wl, "Tpc")
## Object: filter_mspct [0 x 3]
## --- Member: spct_1 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 50 × 2
## w.length Tfr
## <int> <dbl>
## 1 501 0.01
## 2 502 0.02
## 3 503 0.03
## 4 504 0.04
## # ℹ 46 more rows
## --- Member: spct_2 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 50 × 2
## w.length Tfr
## <int> <dbl>
## 1 501 0.51
## 2 502 0.52
## 3 503 0.53
## 4 504 0.54
## # ℹ 46 more rows
##
## --- END ---
In a second example we supply explicit names for the spectra.
## Object: filter_mspct [0 x 3]
## --- Member: A ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 50 × 2
## w.length Tfr
## <int> <dbl>
## 1 501 0.01
## 2 502 0.02
## 3 503 0.03
## 4 504 0.04
## # ℹ 46 more rows
## --- Member: B ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 50 × 2
## w.length Tfr
## <int> <dbl>
## 1 501 0.51
## 2 502 0.52
## 3 503 0.53
## 4 504 0.54
## # ℹ 46 more rows
##
## --- END ---
There is no change in the call for data stored by row. We create a new matrix, with the same data as above, but stored by row, as some R packages do.
## Object: filter_mspct [0 x 3]
## --- Member: spct_1 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 50 × 2
## w.length Tfr
## <int> <dbl>
## 1 501 0.01
## 2 502 0.02
## 3 503 0.03
## 4 504 0.04
## # ℹ 46 more rows
## --- Member: spct_2 ---
## Object: filter_spct [50 x 2]
## Wavelength range 501-550 nm, step 1 nm
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 50 × 2
## w.length Tfr
## <int> <dbl>
## 1 501 0.51
## 2 502 0.52
## 3 503 0.53
## 4 504 0.54
## # ℹ 46 more rows
##
## --- END ---
There is only one case when an explicit argument for
byrow
is needed: square matrices (same number of spectra as
of wavelength values in each spectrum).
When coercing collections of spectra into matrices, the metadata
contained in the individual spectral objects is discarded, and only the
"comment"
attribute of the collection of spectra copied to
the returned object. The wavelength values are preserved in an attribute
named “w.length”, but are not included as part of the matrix.
## [1] "matrix" "array"
## [1] 522 2
## [1] "sun1" "sun2"
## [1] "280" "280.923076923077" "281.846153846154" "282.769230769231"
## [5] "283.692307692308" "284.615384615385"
## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154
The argument byrow
in the coercion into matrix methods
has the same meaning as in the matrix
constructor
function.
## [1] "matrix" "array"
## [1] 522 2
## [1] "sun1" "sun2"
## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154
Collections of spectra have a dim
attribute but it is
discarded as it describes dimensions that could require spectral data to
be stored in a three dimensional array and cannot be mapped to the two
dimensions of a matrix.
These functions are not fully automatic, the user needs to provide the name of the variable to extract from each spectrum. If the wavelength values are not consistent among spectra, only those with the same values as the first spectrum in the collection are retained and the remaining ones dropped with a warning.
Spectral objects containing multiple spectra identified by a factor
can be created by row-binding compatible spectral objects. For for
binding to succeed, the list of spectra passed as argument must be
homogeneous with respect to member class, as well as for certain
attributes such as time.unit
. Other metadata attributes are
retained as named lists or multi-row data frames. We use a time series
of sunlight spectra. The default name spct.idx
is used for
the idfactor
unless an argument is passed to parameter
idfactor
.
## Object: source_spct [3,186 x 3]
## containing 2 spectra in long form
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## time.01 label: cosine.hour.9
## time.02 label: cosine.hour.9
## time.01 measured on 2023-06-12 18:38:00.379657 UTC
## time.02 measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 3,186 × 3
## w.length s.e.irrad spct.idx
## <dbl> <dbl> <fct>
## 1 290 0 time.01
## 2 290. 0 time.01
## 3 291. 0 time.01
## 4 291. 0 time.01
## # ℹ 3,182 more rows
The reverse operation, separating the individual spectra from a
spectrum object containing multiple spectra in long form and
storing them as a collection, is implemented in method
subset2mspct
. In this case, metadata is set for the
individual spectra if it is available in the object being subset. What
metadata is automatically stored depends on the version of this package
used when creating the long form spectrum object by means of
rbindspct()
. Versions 0.9.14 and later preserve most of the
metadata.
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
If multiple spectra are stored in long form (as tidy data)
in an ordinary data.frame
or a tibble
object
with columns with suitable names, the same subset2mspct
method can be used. In these case, arguments indicating the target class
for conversion and supplying the name of the index variable encoding the
grouping into multiple spectra need to be supplied. A call as in the
example below, adds only default metadata to spectral objects.
test1.df <- data.frame(w.length = rep(200:210, 2),
s.e.irrad = rep(c(1, 2), c(11, 11)),
spectrum = factor(rep(c("A", "B"), c(11,11))))
subset2mspct(test1.df, member.class = "source_spct", idx.var = "spectrum")
## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 200 1
## 2 201 1
## 3 202 1
## 4 203 1
## # ℹ 7 more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 200 2
## 2 201 2
## 3 202 2
## 4 203 2
## # ℹ 7 more rows
##
## --- END ---
If all member spectra share the same metadata, and the constructor has a parameter allowing it to be set, it can be passed as a named argument. Here we set the time base of expression of the spectral data to a whole day instead of the default of using seconds as is usual for irradiance.
## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy exposure [J d-1 m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 200 1
## 2 201 1
## 3 202 1
## 4 203 1
## # ℹ 7 more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy exposure [J d-1 m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 200 2
## 2 201 2
## 3 202 2
## 4 203 2
## # ℹ 7 more rows
##
## --- END ---
To directly convert a tidy data frame into a long form
spectral object we need to pass the number of spectra through parameter
multiple.wl
to change the target value of the check for
unique wavelength values (default is multiple.wl = 1L
). The
data should be anyway ordered by increasing wavelength and the name of
the factor distinguishing the spectra also passed as an argument.
test2.df <- test1.df
setSourceSpct(test2.df, multiple.wl = 2L, idfactor = "spectrum")
getMultipleWl(test2.df)
## [1] 2
## [1] "spectrum"
If multiple.wl = NULL
a suitable value is guessed from
the data frame passed as first argument. This should work in most cases,
but is more time consuming. Using this approach in addition disables the
check for a fixed number of spectra.
test3.df <- test1.df
setSourceSpct(test3.df, multiple.wl = NULL, idfactor = "spectrum")
getMultipleWl(test3.df)
## [1] 2
## [1] "spectrum"
In a broad form (or untidy) data.frame the spectral
values for different spectra are stored side-by-side as columns, and a
single additional column used to store the shared wavelength values. To
create a collection of spectral objects, with each member containing a
single spectrum, we use function split2source_mspct
and its
equivalents for the remaining classes of spectral objects (class is
determined by the function used, and columns which are not
numeric
are skipped). The column containing wavelength
values in nanometres is recognized by means of its name. The names used
for the spectra in the collection are derived from the names of the
columns containing numeric (assumed spectral data) values.
Using defaults when variables have the names expected by default.
## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 200 1
## 2 201 1
## 3 202 1
## 4 203 1
## # ℹ 7 more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.e.irrad
## <int> <dbl>
## 1 200 2
## 2 201 2
## 3 202 2
## 4 203 2
## # ℹ 7 more rows
##
## --- END ---
If variable names differ from the default expectation, they can be named in the call.
test3.df <- data.frame(w = 200:210, A = 1, B = 2, z = "Z")
split2source_mspct(x = test3.df, w.length.var = "w", idx.var = "z")
## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 3]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 3
## w.length s.e.irrad z
## <int> <dbl> <chr>
## 1 200 1 Z
## 2 201 1 Z
## 3 202 1 Z
## 4 203 1 Z
## # ℹ 7 more rows
## --- Member: B ---
## Object: source_spct [11 x 3]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 11 × 3
## w.length s.e.irrad z
## <int> <dbl> <chr>
## 1 200 2 Z
## 2 201 2 Z
## 3 202 2 Z
## 4 203 2 Z
## # ℹ 7 more rows
##
## --- END ---
The interpretation of the data in the numeric columns other than the wavelengths can be changed.
## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.q.irrad
## <int> <dbl>
## 1 200 1
## 2 201 1
## 3 202 1
## 4 203 1
## # ℹ 7 more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.q.irrad
## <int> <dbl>
## 1 200 2
## 2 201 2
## 3 202 2
## 4 203 2
## # ℹ 7 more rows
##
## --- END ---
Also in this case, it is possible to pass additional named arguments to the constructor of spectral objects.
## Object: source_mspct [2 x 1]
## --- Member: A ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon exposure [mol d-1 m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.q.irrad
## <int> <dbl>
## 1 200 1
## 2 201 1
## 3 202 1
## 4 203 1
## # ℹ 7 more rows
## --- Member: B ---
## Object: source_spct [11 x 2]
## Wavelength range 200-210 nm, step 1 nm
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon exposure [mol d-1 m-2 nm-1]
## --
## # A tibble: 11 × 2
## w.length s.q.irrad
## <int> <dbl>
## 1 200 2
## 2 201 2
## 3 202 2
## 4 203 2
## # ℹ 7 more rows
##
## --- END ---
An additional way of storing spectral data is with one spectrum per
row and one wavelength per coulmn. In such a case, we can transpose the
data frame with function t()
before pasing it as argument
to split2source_mspct()
, taking care to copy wavelength
values into a column and that the column names of the transposed data
frame match the expected ones.
Sometimes, when exporting spectral data we may need to convert a
collection of spectra into an untidy or wide form data
frame. In the example below we use a collection with only two member
spectra, but join_mspct()
can handle collections of any
length.
## w.length time.01 time.02 time.03 time.04 time.05
## 1 290.00 0 0 0 0 0
## 2 290.39 0 0 0 0 0
## 3 290.86 0 0 0 0 0
## 4 291.32 0 0 0 0 0
## 5 291.79 0 0 0 0 0
## 6 292.26 0 0 0 0 0
is.
functions are defined for all the new classes. R’s
class
method can also be used.
## [1] TRUE
## [1] "source_mspct" "generic_mspct" "list"
In addition to using class
to query the class of the
collection, we can use base R’s lapply
together with
class
or class_spct
to query the class of each
of the members of the collection.
## [1] FALSE
## [1] TRUE
## [1] "source_mspct" "generic_mspct" "list"
## $time.01
## [1] "source_spct" "generic_spct"
##
## $time.02
## [1] "source_spct" "generic_spct"
##
## $time.03
## [1] "source_spct" "generic_spct"
##
## $time.04
## [1] "source_spct" "generic_spct"
##
## $time.05
## [1] "source_spct" "generic_spct"
## $time.01
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
##
## $time.02
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
##
## $time.03
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
##
## $time.04
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
##
## $time.05
## [1] "source_spct" "generic_spct" "tbl_df" "tbl" "data.frame"
R’s extraction and replacement methods have specializations for collections of spectra and can be used with the same syntax and functionality as for R lists. However they test the class and validity of the returned objects and replacement members.
Methods [
, and [<-
, extract and replace
parts of the collection, respectively. Even when only one
member is extracted, the returned value is a collection of spectra. The
expected replacement value is also, always a collection of spectra.
## Object: source_mspct [1 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
## Object: source_mspct [3 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: time.03 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:40:00.714554 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
Code like that in the chunk below, may be counterintuitive. Collections of spectra are named lists, consequently assigning by position as shown here swaps the values without swapping the names of the slots!
Using summary to check the names and time stamps we can demonstrate this behaviour.
# warning: this does not swap the names, even if it swaps the spectra
my.mspct <- sun_evening.mspct
summary(my.mspct, which.metadata = "when.measured")$summary[ , -(2:6)]
## # A tibble: 5 × 2
## spct.idx when.measured
## <chr> <dttm>
## 1 time.01 2023-06-12 18:38:00
## 2 time.02 2023-06-12 18:39:00
## 3 time.03 2023-06-12 18:40:00
## 4 time.04 2023-06-12 18:41:00
## 5 time.05 2023-06-12 18:42:00
# member spectr swapped positions, but not the slot names
my.mspct[1:2] <- my.mspct[2:1]
summary(my.mspct, which.metadata = "when.measured")$summary[ , -(2:6)]
## # A tibble: 5 × 2
## spct.idx when.measured
## <chr> <dttm>
## 1 time.01 2023-06-12 18:39:00
## 2 time.02 2023-06-12 18:38:00
## 3 time.03 2023-06-12 18:40:00
## 4 time.04 2023-06-12 18:41:00
## 5 time.05 2023-06-12 18:42:00
# of course, we can also swap the names if needed
names(my.mspct)[1:2] <- names(my.mspct)[2:1]
summary(my.mspct, which.metadata = "when.measured")$summary[ , -(2:6)]
## # A tibble: 5 × 2
## spct.idx when.measured
## <chr> <dttm>
## 1 time.02 2023-06-12 18:39:00
## 2 time.01 2023-06-12 18:38:00
## 3 time.03 2023-06-12 18:40:00
## 4 time.04 2023-06-12 18:41:00
## 5 time.05 2023-06-12 18:42:00
Methods [[
, $
and [[<-
,
extract and replace individual members of the collection, respectively.
They always return or expect objects of one of the spectral classes.
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## [1] "time.01" "time.02" "time.03" "time.04" "time.05"
## [1] "time.01" "time.02" "time.03" "time.04" "time.05" "time.01x2"
## [1] "time.01" "time.02" "time.03" "time.04" "time.05"
As with R’s list
objects, can combine collections of
spectra with method c()
but we can not create new
collections from individual spectra using this method. Extraction plus
concatenation, moves names together with spectra.
new.spct <- c(my.mspct[5:4], my.mspct[3])
summary(new.spct, which.metadata = "when.measured")$summary[ , -(2:6)]
## # A tibble: 3 × 2
## spct.idx when.measured
## <chr> <dttm>
## 1 time.05 2023-06-12 18:42:00
## 2 time.04 2023-06-12 18:41:00
## 3 time.03 2023-06-12 18:40:00
With large collections of spectra it can be useful to extract a
random subset of spectra. Method pull_sample()
make this
easy for multiple spectra, stored either in long form or in collections
of spectra. (We can set the seed of the pseudo-random number generator
to ensure repeatability).
set.seed(1234564)
sampled.mspct <- pull_sample(sun_evening.mspct, size = 2)
summary(sampled.mspct, which.metadata = "when.measured")$summary[ , -(2:6)]
## # A tibble: 2 × 2
## spct.idx when.measured
## <chr> <dttm>
## 1 time.02 2023-06-12 18:39:00
## 2 time.05 2023-06-12 18:42:00
## Summary of source_spct [3,186 x 3] object: sampled.spct
## containing 2 spectra in long form
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## time.02 measured on 2023-06-12 18:39:00.797266 UTC
## time.05 measured on 2023-06-12 18:42:00.769065 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## w.length s.e.irrad spct.idx
## Min. : 290.0 Min. :0.00000 time.02:1593
## 1st Qu.: 474.4 1st Qu.:0.02434 time.05:1593
## Median : 654.8 Median :0.04106
## Mean : 651.6 Mean :0.03739
## 3rd Qu.: 830.3 3rd Qu.:0.05124
## Max. :1000.0 Max. :0.07321
For our apply functions we follow the naming convention used
in package plyr
, but using ms
as prefix for
_mspct
objects. The apply functions implemented in
the ‘photobiology’ package are msmsply
,
msdply
, mslply
and msaply
which
both accept a collection of spectra as first argument and return a
collection of spectra, a data frame, a list, or an array respectively
(see Table 4).
Table 4. Apply functions for collections of spectra.
Key: v., value returned by apply function; f.v., value returned
by the applied function (argument .fun
). In the table
generic_mspct
and generic_spct
indicate
objects of these classes or any class derived from them. The exact class
of the collection of spectra object returned will be determined by the
class(es) of the values returned by the applied function.
apply function | first arg. class | v. class | f.v. class | f.v. length | f.v. dims |
---|---|---|---|---|---|
msmsply |
generic_mspct |
generic_mspct |
generic_spct |
1 | any |
msdply |
generic_mspct |
data.frame |
numeric |
1…n | 1 |
mslply |
generic_mspct |
list |
any | any | any |
msaply |
generic_mspct |
vector |
any simple | 1 | 0 |
msaply |
generic_mspct |
matrix |
any simple | 2…n | 2…n |
concolve_each |
generic_mspct |
generic_mspct |
generic_spct |
1 | any |
Functions msmsply()
, msdply
and
mslply
can be used to apply a function to each member
spectrum in a collection. The apply function to use depends on
the return value of the applied function.
In the case of msmsply()
the applied function is
expected to return a transformed spectrum as another object of
class generic_spct
or a class derived from it. The value
returned by msmsply
is a collection of spectra, of a type
determined by the class(es) of the member spectra in the new
collection.
We start with a simple example in which we add a constant to each spectrum in the collection
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0.1
## 2 290. 0.1
## 3 291. 0.1
## 4 291. 0.1
## # ℹ 1,589 more rows
## --- Member: time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0.1
## 2 290. 0.1
## 3 291. 0.1
## 4 291. 0.1
## # ℹ 1,589 more rows
##
## --- END ---
and continue with a more complex example in which we trim each
spectrum, and fill the added values with NA
values.
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,602 x 2]
## Wavelength range 285-1000 nm, step 1.023182e-12-0.8333333 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,602 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 285 NA
## 2 286. NA
## 3 287. NA
## 4 287. NA
## # ℹ 1,598 more rows
## --- Member: time.02 ---
## Object: source_spct [1,602 x 2]
## Wavelength range 285-1000 nm, step 1.023182e-12-0.8333333 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,602 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 285 NA
## 2 286. NA
## 3 287. NA
## 4 287. NA
## # ℹ 1,598 more rows
##
## --- END ---
In the second example we pass two arguments by name to the applied function. The number of arguments is not fixed, but the spectrum will be always passed as the first argument to the function.
In the case of msdply()
the applied function is expected
to return an R object of the same length for each of the member
spectra.
## # A tibble: 2 × 2
## spct.idx max.wl
## <fct> <dbl>
## 1 time.01 1000.
## 2 time.02 1000.
## # A tibble: 2 × 3
## spct.idx min.wl max.wl
## <fct> <dbl> <dbl>
## 1 time.01 290 1000.
## 2 time.02 290 1000.
## Applied function: 'range'.
## # A tibble: 2 × 3
## spct.idx min.wl max.wl
## <fct> <dbl> <dbl>
## 1 time.01 290 1000.
## 2 time.02 290 1000.
In the case of mslply()
the applied function is expected
to return an R object of any length, possibly variable among
members.
## List of 2
## $ time.01: chr [1:2] "w.length" "s.e.irrad"
## $ time.02: chr [1:2] "w.length" "s.e.irrad"
## - attr(*, "comment")= chr "Applied function: 'colnames'.\n"
In the case of msaply()
the applied function is expected
to return an R object of length 1, although a list with dimensions will
be returned for longer return values.
## num [1:2] 1000 1000
## - attr(*, "comment")= chr "Applied function: 'max'.\n"
## 1 2
## [1,] 290 1000
## [2,] 290 1000
For the most common cases for which one would use the apply functions described in the previous section methods and functions for operations on collections of spectra are defined in the package. These methods are described in a later section and listed in Table 9.
Starting from a collection of spectra, or multiple spectra stored in
long form, we can obtain a single spectrum containing a “parallel”
summary across them. The current implementation of the methods described
in this section expects that all spectra in a collection are of the same
class, and data is available for each of them at exactly the same set of
wavelengths. In the table below, source_spct/mspct
is an
abbreviation for source_spct
or
source_mspct
.
functions | class of argument | class of returned spectrum | variables in spectrum |
---|---|---|---|
s_sum |
source_spct/mspct |
source_spct |
same as input |
s_sum |
response_spct/mspct |
response_spct |
same as input |
s_sum |
filter_spct/mspct |
generic_spct |
input tagged .sum |
s_sum |
reflector_spct/mspct |
generic_spct |
input tagged .sum |
s_sum |
calibration_spct/mspct |
generic_spct |
input tagged .sum |
s_prod |
source_spct/mspct |
source_spct |
input tagged .prod |
s_prod |
response_spct/mspct |
response_spct |
input tagged .prod |
s_prod |
filter_spct/mspct |
filter_spct |
same as input |
s_prod |
reflector_spct/mspct |
reflector_spct |
same as input |
s_prod |
calibration_spct/mspct |
generic_spct |
input tagged .prod |
s_mean or s_median |
source_spct/mspct |
source_spct |
same as input |
s_mean or s_median |
response_spct/mspct |
response_spct |
same as input |
s_mean or s_median |
filter_spct/mspct |
filter_spct |
same as input |
s_mean or s_median |
reflector_spct/mspct |
reflector_spct |
same as input |
s_mean or s_median |
calibration_spct/mspct |
calibration_spct |
same as input |
s_var , s_se or
s_sd |
source_spct/mspct |
generic_spct |
input tagged .var , .se or
.sd |
s_var , s_se or
s_sd |
response_spct/mspct |
generic_spct |
input tagged .var , .se or
.sd |
s_var , s_se or
s_sd |
filter_spct/mspct |
generic_spct |
input tagged .var , .se or
.sd |
s_var , s_se or
s_sd |
reflector_spct/mspct |
generic_spct |
input tagged .var , .se or
.sd |
s_var , s_se or
s_sd |
calibration_spct/mspct |
generic_spct |
input tagged .var , .se or
.sd |
s_mean_se |
source_spct/mspct |
source_spct |
same as input plus col. tagged .se |
s_mean_se |
response_spct/mspct |
response_spct |
same as input plus col. tagged .se |
s_mean_se |
filter_spct/mspct |
filter_spct |
same as input plus col. tagged .se |
s_mean_se |
reflector_spct/mspct |
reflector_spct |
same as input plus col. tagged .se |
s_mean_se |
calibration_spct/mspct |
calibration_spct |
same as input plus col. tagged .se |
s_range |
source_spct/mspct |
generic_spct |
input tagged .min and
.max |
s_range |
response_spct/mspct |
generic_spct |
input tagged .min and
.max |
s_range |
filter_spct/mspct |
generic_spct |
input tagged .min and
.max |
s_range |
reflector_spct/mspct |
generic_spct |
input tagged .min and
.max |
s_range |
calibration_spct/mspct |
generic_spct |
input tagged .min and
.max |
The calculations are done wavelength by wavelength yielding a
spectrum at the same wavelengths than those in the input. Removal of
NA
values is done wavelength by wavelength. As shown in the
table above, depending on the operation the returned quantity may be
equivalent or not to the quantity in the input. When the quantity
changes, even if units of expression remain the same, the name of the
variable and class of the returned spectrum are different to those in
the input.
Methods in this “family” are fast and are specially useful for large
collections of spectra containing even thousands of individual spectra.
Nonetheless, for the example below we use a collection of two spectra.
As computing the mean returns values of the same quantity as in the
input the returned value is a source_spct
object, in other
words of the same class as the members of two.mspct
.
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: Mean of 5 source_spct objects.
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
When we compute the standard error, the quantity returned is not the
same. Consequently, the object returned is in this case a
generic_spct
instead of source_spc
as it does
not contain spectral irradiance data as the input did. The variable name
is in addition tagged with .se
to advertise the
change in the quantity.
## Object: generic_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: Standard error for 5 source_spct objects.
## Variables:
##
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad.se
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
We can also compute both the mean and standard error simultaneously.
## Object: source_spct [1,593 x 3]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: Mean and SEM of 5 source_spct objects.
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 3
## w.length s.e.irrad s.e.irrad.se
## <dbl> <dbl> <dbl>
## 1 290 0 0
## 2 290. 0 0
## 3 291. 0 0
## 4 291. 0 0
## # ℹ 1,589 more rows
The other functions in this family work in a similar way to those described here.
By convolution we normally mean the multiplication value by value at matching wavelengths of two spectra. The function described in this section facilitates this and similar operations among collections of spectra. An example use case could be the convolution of spectral irradiance by spectral transmittance for all combinations of light sources and filters in a collection of source spectra and a collection of filter spectra.
Default operator (or function) is that for multiplication, either one or both of the two first arguments must be a collection of spectra. When only one argument is a collection of spectra, the other one can be a spectrum, or even a numeric vector. For multiplication the order of the operands does not affect the returned value. With operators or functions for non-transitive operations the order does, obviously, matter.
Convolution can be used, for example to simulate the effect of an optical filter on the irradiance from a light source.
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,449 x 2]
## Wavelength range 290-800 nm, step 0.01-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,449 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291 0
## # ℹ 1,445 more rows
## --- Member: time.02 ---
## Object: source_spct [1,449 x 2]
## Wavelength range 290-800 nm, step 0.01-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,449 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291 0
## # ℹ 1,445 more rows
##
## --- END ---
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,449 x 2]
## Wavelength range 290-800 nm, step 0.01-0.47 nm
## Label: Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, UK
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,449 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291 0
## # ℹ 1,445 more rows
## --- Member: time.02 ---
## Object: source_spct [1,449 x 2]
## Wavelength range 290-800 nm, step 0.01-0.47 nm
## Label: Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, UK
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,449 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291 0
## # ℹ 1,445 more rows
##
## --- END ---
another_two.mspct <- two.mspct
names(another_two.mspct) <- c("a", "b")
convolve_each(another_two.mspct, two.mspct)
## Object: source_mspct [2 x 2]
## --- Member: a_time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: a_time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: b_time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: b_time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
The function convolve_each
will use other operators or
functions and even pass additional named arguments when these are
supplied as arguments.
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,630 x 2]
## Wavelength range 290-800 nm, step 0.01-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:38:00.379657 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,630 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 290. 0
## 4 291. 0
## # ℹ 1,626 more rows
## --- Member: time.02 ---
## Object: source_spct [1,630 x 2]
## Wavelength range 290-800 nm, step 0.01-0.47 nm
## Label: cosine.hour.9
## Measured on 2023-06-12 18:39:00.797266 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,630 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 290. 0
## 4 291. 0
## # ℹ 1,626 more rows
##
## --- END ---
There are cases where functions convolve_each()
and
msmsply()
can be both used, but there are also cases where
their differences matter. An example is convolving two collections of
spectra, a case where only convolve_each()
can be used. In
contrast, when one of the arguments is not a spectrum or a collection of
spectra, msmsply()
should be used instead.
Some of the set
and get
functions used with
attributes have method definitions for collections of spectra. Some
examples follow.
## # A tibble: 2 × 2
## spct.idx when.measured
## <fct> <dttm>
## 1 time.01 2023-06-12 18:38:00
## 2 time.02 2023-06-12 18:39:00
## # A tibble: 2 × 2
## spct.idx when.measured
## <fct> <dttm>
## 1 time.01 2015-10-30 22:00:00
## 2 time.02 2015-10-30 22:00:00
when_measured(two.mspct) <- list(ymd_hm("2015-10-31 10:00", tz = "EET"),
ymd_hm("2015-10-31 11:00", tz = "EET"))
when_measured(two.mspct) # UTC shown!
## # A tibble: 2 × 2
## spct.idx when.measured
## <fct> <dttm>
## 1 time.01 2015-10-31 08:00:00
## 2 time.02 2015-10-31 09:00:00
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2015-10-31 08:00:00 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2015-10-31 09:00:00 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
Other methods available are getWhereMeasured
and
setWhereMeasured
, and getWhatMeasured
and
setWhatMeasured
.
Functions when.measured2tb()
, geocode2tb()
,
lon2tb()
, lat2tb()
and
what.measured2tb()
extract these same attributes from
collection members into a tibble or data frame. In contrast to the “get”
methods described above, if an existing data frame or tibble with a
matching number of rows is passed as second argument, the values for the
attribute are saved into a new column appended at the right edge of the
tibble or data frame.
## # A tibble: 5 × 2
## spct.idx when.measured
## <fct> <dttm>
## 1 time.01 2023-06-12 18:38:00
## 2 time.02 2023-06-12 18:39:00
## 3 time.03 2023-06-12 18:40:00
## 4 time.04 2023-06-12 18:41:00
## 5 time.05 2023-06-12 18:42:00
By default the new column is named after the name of the attribute, but this default can be overridden by the user.
## # A tibble: 5 × 2
## spct.idx acquisition.time
## <fct> <dttm>
## 1 time.01 2023-06-12 18:38:00
## 2 time.02 2023-06-12 18:39:00
## 3 time.03 2023-06-12 18:40:00
## 4 time.04 2023-06-12 18:41:00
## 5 time.05 2023-06-12 18:42:00
Function spct_metadata()
returns the metadata in a
tibble. Unless the user supplies a list of names of attributes, all
applicable metadata values are returned. A single spectrum or a
collection of spectra can be passed. By default columns containing only
missing data are dropped.
## # A tibble: 2 × 11
## spct.idx lat lon address when.measured what.measured how.measured
## <fct> <dbl> <dbl> <chr> <dttm> <chr> <chr>
## 1 time.01 60.2 24.0 Viikki, H… 2015-10-31 08:00:00 cosine.hour.9 "Acquired w…
## 2 time.02 60.2 24.0 Viikki, H… 2015-10-31 09:00:00 cosine.hour.9 "Acquired w…
## # ℹ 4 more variables: normalized <dbl>, multiplier <dbl>, time.unit <Duration>,
## # bswf.used <chr>
spct_metadata(two.mspct,
col.names = c("when.measured" = "time",
"where.measured" = "geocode"),
unnest = FALSE)
## # A tibble: 2 × 3
## spct.idx time geocode
## <fct> <dttm> <named list>
## 1 time.01 2015-10-31 08:00:00 <tibble [1 × 3]>
## 2 time.02 2015-10-31 09:00:00 <tibble [1 × 3]>
Function add_attr2tb()
adds one or more columns with
attributes to a tibble or data frame. We here also demonstrate that
because the data frame object is passed to the first positional
argument, we can use a pipe. This difference in interface is
the main difference between this function and
spct_metadata()
.
## # A tibble: 2 × 5
## spct.idx Q_Total lon lat when.measured
## <fct> <dbl> <dbl> <dbl> <dttm>
## 1 time.01 0.000132 24.0 60.2 2015-10-31 08:00:00
## 2 time.02 0.000126 24.0 60.2 2015-10-31 09:00:00
We can set the desired names for the columns if we wish them to be something else than the default.
q_irrad(two.mspct) %>%
add_attr2tb(two.mspct,
col.names = c(lon = "longitude",
lat = "latitude",
when.measured = "time"))
## # A tibble: 2 × 5
## spct.idx Q_Total longitude latitude time
## <fct> <dbl> <dbl> <dbl> <dttm>
## 1 time.01 0.000132 24.0 60.2 2015-10-31 08:00:00
## 2 time.02 0.000126 24.0 60.2 2015-10-31 09:00:00
When a range of wavelengths or a range of wavelengths plus a spectral
weighting function (SWF) is needed for radiation summaries or
transformations, methods, operators and functions defined in package
‘photobiology’ use waveband
objects to
store these data. A few other bits of information can be included to
fine-tune calculations. The waveband definitions do NOT describe whether
input spectral irradiances are photon or energy based, nor whether the
output irradiance will be based on photon or energy units. All waveband
objects belong to the S3 class waveband
.
A waveband stores the boundaries of a range of wavelengths, λ1 and λ2, so that wavelengths within λ1 ≥ λ > λ2 belong to the waveband. If the waveband describes a spectral weighting function, in addition to the range, two formulations of the function used to compute the weights as a function of wavelength are also stored, wE(λ) and wQ(λ) to be used with energy- or photon based irradiances.
Spectral weighting functions are normally used to compute effective irradiances. In the current implementation their use is limited to this case, while for other summaries only the wavelength range is made use of, even when weighting functions are available.
To create a waveband object we use constructor function
waveband
, and optionally giving a name to it. We
will use these objects in many of the examples below, so you will need
to run the code chunk bellow to be able to reproduce those
examples. It should be noted that waveband constructors for the
most frequently used wavelength-range definitions are provided by
package ‘photobiologyWavebands’.
PAR.wb <- waveband(c(400, 700), wb.name = "PAR")
UVA.wb <- waveband(c(315, 400), wb.name = "UVA")
UVB.wb <- waveband(c(280, 315), wb.name = "UVB")
UVC.wb <- waveband(c(100, 280), wb.name = "UVC")
UV.wb <- waveband(c(100, 400), wb.name = "UV")
UV_bands.lst <- list(UVC.wb, UVB.wb, UVA.wb)
When including a BSWF, we can supply, one or two versions of functions returning the weights as a function of wavelength. Several such functions are defined in package ‘photobiologyWavebands’ as well as waveband constructors using them. Here we show how a waveband can be defined based on a SWF, using the CIE definition for the erythemal spectral weighting function. Although the constructor is smart enough to derive the missing function when only one function is supplied, performance may suffer unless two performance-optimized function are provided, one for energy-based effect and a second one for photon-based effect.
CIE_e_fun <-
function(w.length){
CIE.energy <- numeric(length(w.length))
CIE.energy[w.length <= 298] <- 1
CIE.energy[(w.length > 298) & (w.length <= 328)] <-
10^(0.094*(298-w.length[(w.length > 298) & (w.length <= 328)]))
CIE.energy[(w.length > 328) & (w.length <= 400)] <-
10^(0.015*(139-w.length[(w.length > 328) & (w.length <= 400)]))
CIE.energy[w.length > 400] <- 0
return(CIE.energy)
}
Another case where you might want to enter the same function twice, is if you are using an absorptance spectrum as SWF, as the percent of radiation absorbed will be independent of whether photon or energy units are used for the spectral irradiance.
The first argument to waveband()
does not need to be a
numeric vector of length two. Any R object of a class that supplies a
range()
method definition that can be interpreted as a
range of wavelengths in nanometres can be used. As a consequence, when
wanting to construct a waveband covering the whole range of a spectrum
one can simply supply the spectrum as argument, or to construct an
non-weighed waveband which covers exactly the same range of wavelengths
as an existing effective (weighted) waveband, one can supply a waveband
object as an argument.
## Total
## low (nm) 280
## high (nm) 800
## weighted none
An “empty” waveband is returned by some functions as a “null” value.
## Not available
## low (nm) NA
## high (nm) NA
## weighted none
The function is.waveband
can the used to query any R
object. This function returns a logical value.
## [1] TRUE
Above, we demonstrate that PAR.wb
is a waveband object,
the function photobiologyWavebands::PAR()
is a waveband
constructor returning a waveband object. See package
‘photobiologyWavebands’ for details on pre-defined
waveband constructors for frequently used wavelength ranges and
biological spectral weighting functions (BSWFs).
In the current implementation there is no special class used for
storing collections of waveband
objects. We simply use base
R’s list
class.
Just base R’s functions used to create a list object.
## [[1]]
## range.300.400
## low (nm) 300
## high (nm) 400
## weighted none
##
## [[2]]
## range.400.500
## low (nm) 400
## high (nm) 500
## weighted none
The function split_bands
can be used to generate lists
of non-weighed wavebands in two different ways: a) it can be used to
split a range of wavelengths given by an R object into a series of
adjacent wavebands, or b) with a list of objects returning ranges, it
can be used to create non-adjacent and even overlapping wavebands.
The code chunk bellow shows an example of two variations of case a).
With the default value for length.out
of NULL
each numerical value in the input is taken as a wavelength (nm) at the
boundary between adjacent wavebands. If a numerical value is supplied to
length.out
, then the whole wavelength range of the input is
split into this number of equally spaced adjacent wavebands.
## $wb1
## range.200.225
## low (nm) 200
## high (nm) 225
## weighted none
##
## $wb2
## range.225.300
## low (nm) 225
## high (nm) 300
## weighted none
## $wb1
## range.200.250
## low (nm) 200
## high (nm) 250
## weighted none
##
## $wb2
## range.250.300
## low (nm) 250
## high (nm) 300
## weighted none
In both examples above, the output is a list of two wavebands, but the split boundaries are at a different wavelength. The chunk bellow gives a few more examples of the use of case a).
## $wb1
## range.280.540
## low (nm) 280
## high (nm) 540
## weighted none
##
## $wb2
## range.540.800
## low (nm) 540
## high (nm) 800
## weighted none
## $wb1
## range.400.550
## low (nm) 400
## high (nm) 550
## weighted none
##
## $wb2
## range.550.700
## low (nm) 550
## high (nm) 700
## weighted none
## $wb1
## range.200.400
## low (nm) 200
## high (nm) 400
## weighted none
##
## $wb2
## range.400.600
## low (nm) 400
## high (nm) 600
## weighted none
##
## $wb3
## range.600.800
## low (nm) 600
## high (nm) 800
## weighted none
Now we demonstrate case b). This case is handled by recursion, so each list element can be anything that is a valid input to the function, including a nested list. However, the returned value is always a flat list of wavebands.
## $A
## range.200.300
## low (nm) 200
## high (nm) 300
## weighted none
##
## $B
## range.400.500
## low (nm) 400
## high (nm) 500
## weighted none
##
## $C
## range.250.350
## low (nm) 250
## high (nm) 350
## weighted none
## $wb.a
## range.100.150
## low (nm) 100
## high (nm) 150
## weighted none
##
## $<NA>
## range.150.200
## low (nm) 150
## high (nm) 200
## weighted none
##
## $wb.b
## range.800.825
## low (nm) 800
## high (nm) 825
## weighted none
In case b) if we supply a numeric value to length.out
,
this value is used recursively for each element of the list.
## $wb.a
## range.100.190
## low (nm) 100
## high (nm) 190
## weighted none
##
## $<NA>
## range.190.280
## low (nm) 190
## high (nm) 280
## weighted none
##
## $wb.b
## range.280.297.5
## low (nm) 280
## high (nm) 298
## weighted none
##
## $<NA>
## range.297.5.315
## low (nm) 298
## high (nm) 315
## weighted none
##
## $wb.c
## range.315.357.5
## low (nm) 315
## high (nm) 358
## weighted none
##
## $<NA>
## range.357.5.400
## low (nm) 358
## high (nm) 400
## weighted none
## $wb.a
## range.100.200
## low (nm) 100
## high (nm) 200
## weighted none
##
## $wb.b
## range.800.825
## low (nm) 800
## high (nm) 825
## weighted none
The print()
method for spectra is based on the method
defined in package ‘tibble’, consequently, it is
possible to use the options from this package to control printing. In
the code chunk below, tibble.print_max
, the number of rows
in the spectral object above which only tibble.print_min
rows are printed, are both set to 5, instead of the default 20 and 10,
to avoid excessive clutter in our examples.
For explicit calls to print()
its argument
n
can be used to control the number of lines printed. If
n
is set to Inf
the whole spectrum is always
printed. The output differs from that of the print()
method
from package ‘dplyr’ in that additional metadata specific to spectra are
shown.
Specialized print()
methods for collections of spectra
and for waveband
objects are also defined.
The summary()
method for spectra is based on base R’s
summary()
method for data frames, and accepts the same
arguments. The main difference is that the attributes containing
metadata and dimensions of the original spectrum object are copied to
the summary object.
Specialized print()
methods for summaries of spectra are
defined. The output differs from that of the print()
method
from base R in that additional metadata specific to spectra are
shown.
NA
sFunctions na.omit()
and na.exclude
are
implemented for all spectral classes. These methods test for
NA
s only the spectral data, not wavelength. They set the
"na.action"
attribute in the same way as the corresponding
methods for data frames. In the case of na.fail()
,
na.pass()
and na.action()
, the methods from
base R, can be used with spectra.
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
All of R’s built-in maths operators have definitions for spectra. It
is possible to sum, subtract, multiply and divide spectra. These
operators can be used even if the spectral data is on different
arbitrary sets of wavelengths. Operators by default return values
expressed in energy units. Only certain operations are meaningful for a
given combination of objects belonging to different classes, and
meaningless combinations return NA
also issuing a warning
(see Table 5). By default operations are carried out on spectral energy
irradiance for source_spct
objects and transmittance for
filter_spct
objects.
Table 5. Binary operators and their operands.
Validity and class of result. All operations marked
\Y' are allowed, those marked
’ are forbidden and return
NA
and issue a warning. Operators %/%
and
%%
follow /
.
e1 | + |
- |
* |
/ |
^ |
e2 | value |
---|---|---|---|---|---|---|---|
raw_spct |
Y | Y | Y | Y | Y | raw_spct |
raw_spct |
cps_spct |
Y | Y | Y | Y | Y | cps_spct |
cps_spct |
source_spct |
Y | Y | Y | Y | Y | source_spct |
source_spct |
filter_spct (T) |
N | N | Y | Y | N | filter_spct |
filter_spct |
filter_spct (A) |
Y | Y | N | N | N | filter_spct |
filter_spct |
reflector_spct |
N | N | Y | Y | N | reflector_spct |
reflector_spct |
object_spct |
N | N | N | N | N | object_spct |
– |
response_spct |
Y | Y | Y | Y | N | response_spct |
response_spct |
chroma_spct |
Y | Y | Y | Y | Y | chroma_spct |
chroma_spct |
raw_spct |
Y | Y | Y | Y | Y | numeric |
raw_spct |
cps_spct |
Y | Y | Y | Y | Y | numeric |
cps_spct |
calibration_spct |
Y | Y | Y | Y | Y | numeric |
calibration_spct |
source_spct |
Y | Y | Y | Y | Y | numeric |
source_spct |
filter_spct |
Y | Y | Y | Y | Y | numeric |
filter_spct |
reflector_spct |
Y | Y | Y | Y | Y | numeric |
reflector_spct |
object_spct |
N | N | N | N | N | numeric |
– |
response_spct |
Y | Y | Y | Y | Y | numeric |
response_spct |
chroma_spct |
Y | Y | Y | Y | Y | numeric |
chroma_spct |
cps_spct |
N | N | Y | N | N | calibration_spct |
source_spct |
source_spct |
N | N | Y | Y | N | response_spct |
response_spct |
source_spct |
N | N | Y | Y | N | filter_spct (T) |
source_spct |
source_spct |
N | N | Y | Y | N | filter_spct (A) |
source_spct |
source_spct |
N | N | Y | Y | N | reflector_spct |
source_spct |
source_spct |
N | N | N | N | N | object_spct |
– |
source_spct |
N | N | Y | N | N | waveband (no BSWF) |
source_spct |
source_spct |
N | N | Y | N | N | waveband (BSWF) |
source_spct (effective) |
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
When meaningful, operations between different spectra are also allowed. For example, it is possible to simulate the effect of a filter on a light source by multiplying (or convolving) the two spectra.
## Object: source_spct [532 x 2]
## Wavelength range 280-800 nm, step 0.07692308-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 532 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 281 0
## 4 282. 0
## # ℹ 528 more rows
If we have two layers of the filter, this can be approximated using either of these two statements.
## Object: source_spct [532 x 2]
## Wavelength range 280-800 nm, step 0.07692308-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 532 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 281 0
## 4 282. 0
## # ℹ 528 more rows
## Object: source_spct [532 x 2]
## Wavelength range 280-800 nm, step 0.07692308-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 532 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 281 0
## 4 282. 0
## # ℹ 528 more rows
Operators are also defined for operations between a spectrum and a numeric vector (with normal recycling).
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
There is one special case, for chroma_spct
: if the
numeric operand has length three, containing three named values
x, y and z, the corresponding value is used
for each of the chromaticity columns in the
chroma_spct
. Un-named values or differently named values
are not treated specially.
Operators are also defined for operations between an spectrum and a
waveband
object. The next to code chunks demonstrate how
the class of the result depends on whether the waveband
object describes a range of wavelengths or a range of wavelengths plus a
BSWF.
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
And of course these operations can be combined into more complex statements, including parentheses, when needed. The example below estimates the difference in effective spectral irradiance according to the CIE98 definition, between sunlight and sunlight filtered with a polyester film. Of course, the result is valid only for the solar spectral data used, which corresponds to Southern Finland.
## Object: source_spct [132 x 2]
## Wavelength range 280-400 nm, step 0.07692308-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Data weighted using 'range.250.400.wtd' BSWF
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 132 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 281 0
## 4 282. 0
## # ℹ 128 more rows
Many common maths functions, as well as unary minus and plus, are implemented for spectral objects (see Table 6).
Table 6. Unary operators and maths functions for
spectra. Classes for which they are implemented and class of
the result. All operations marked Y are allowed, those marked N are not
implemented and return NA
and issue a warning. Additional
supported functions:
log2, log10, sin, cos, tan, asin, acos, atan, sinpi, cospi, tanpi, signif, floor, ceiling, trunc, sign, abs
.
e1 | +, - |
log, exp |
trig. | round |
sqrt |
value |
---|---|---|---|---|---|---|
raw_spct |
Y | Y | Y | Y | Y | raw_spct |
cps_spct |
Y | Y | Y | Y | Y | cps_spct |
calibration_spct |
Y | Y | Y | Y | Y | calibration_spct |
source_spct |
Y | Y | Y | Y | Y | source_spct |
filter_spct |
Y | Y | Y | Y | Y | filter_spct |
reflector_spct |
Y | Y | Y | Y | Y | reflector_spct |
object_spct |
N | N | N | N | N | – |
response_spct |
Y | Y | Y | Y | Y | response_spct |
chroma_spct |
Y | Y | Y | Y | Y | chroma_spct |
## Warning in range_check(x, strict.range = strict.range): Negative spectral
## energy irradiance values; minimum s.e.irrad = -0.82
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
Table 7 lists all the recognized options affecting maths operators
and functions, and their default values. Within the suite all functions
have a default value which is used when the options are undefined.
Options are set using base R’s function options
, and
queried with functions options
and
getOption
.
Table 7. Options used in the ‘r4photobiology suite’ and
recognized by methods, operators and functions in the ‘photobiology’
package. Option names, accepted and default values, and the
purpose of the options are given. Option
photobiology.verbose
is set to the value of R’s own
verbose
option at the time the ‘photobiology’ package is
attached to the session.
Option | values , default |
purpose, unit | convenience function |
---|---|---|---|
Base R | |||
digits |
7 | d − 3 used by
summary |
|
tibble | |||
tibble.print_max | 20 | Maximum number of rows printed | |
tibble.print_min | 10 | Number of rows printed if row number threshold is exceeded | |
tibble.width | NULL | Output width | |
r4photobiology | |||
photobiology.radiation.unit | “energy” | W m−2 nm−1 | using_energy() , energy_as_default() |
"photon" |
μmol m−2 nm−1 | using_photon() , photon_as_default() |
|
photobiology.filter.qty | “transmittance” | /1 | using_Tfr() , Tfr_as_default() |
"absorptance" |
/1 | using_Afr() , Afr_as_default() |
|
"absorbance" |
a.u. log10 base | using_A() , A_as_default() |
|
photobiology.strict.range | NA |
skip range test | strict_range_as_default(NA) |
TRUE |
trigger an error | strict_range_as_default(TRUE) |
|
FALSE | trigger a warning | strict_range_as_default(FALSE) |
|
photobiology.check.spct | TRUE | enable check_spct() |
enable_check_spct() |
FALSE |
disable check_spct() |
disable_check_spct() |
|
photobiology.waveband.trim | FALSE |
exclude | wb_trim_as_default(FALSE) |
TRUE | trim or exclude | wb_trim_as_default(TRUE) |
|
photobiology.use.cached.mult | FALSE | do not cache intermediate results | use_cached_mult_as_default(FALSE) |
TRUE |
cache intermediate results | use_cached_mult_as_default(TRUE) |
|
photobiology.verbose | FALSE |
minimal warnings and messages | verbose_as_default(FALSE) |
TRUE |
all warnings and messages | verbose_as_default(TRUE) |
The behaviour of the operators defined in this package depends on the
value of two global options. For example, if we would like the operators
to operate on spectral photon irradiance and return spectral photon
irradiance instead of spectral energy irradiance, this behaviour can be
set, and will remain active until unset or reset. It is possible to
change options using base R’s function options()
as shown
in the next code chunk. The other options listed in the Table above can
be set similarly, while to unset any option, they can be given a
NULL
value.
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.q.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
However using convenience functions is easier. The chunk above can be rewritten as below.
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.q.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
Furthermore, it is possible to temporarily change the options for the
evaluation of a single, possibly compound, R expression using a
different syntax, reminiscent of that of R’s with()
.
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.q.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
## Object: source_spct [37 x 2]
## Wavelength range 280-315 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 37 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 33 more rows
In this section we describe methods and functions that take one or more spectral objects, and in some cases also waveband objects, as arguments and return another spectral object (see Tables 8 and 9) or that take a collection of spectral objects, and in some cases also waveband objects, as arguments and return a collection of spectral objects.
Table 8. Transformation methods for spectra. Key: + available, – not available.
methods | raw/cps | source | response | filter | reflector | object | chroma |
---|---|---|---|---|---|---|---|
merge | + | + | + | + | + | + | + |
rbindspct | + | + | + | + | + | + | + |
e2q, q2e | – | + | + | – | – | – | – |
A2T, T2A | – | – | – | + | – | – | – |
Afr2T, T2Afr | – | – | – | + | – | – | – |
any2T, any2A, any2Afr | – | – | – | + | – | – | – |
convertTfrType | – | – | – | + | – | – | – |
convertThickness | – | – | – | + | – | – | – |
subset | + | + | + | + | + | + | + |
clip_wl | + | + | + | + | + | + | + |
trim_wl | + | + | + | + | + | + | + |
(trim_spct) | + | + | + | + | + | + | + |
thin_wl | + | + | + | + | + | – | – |
interpolate_wl | – | + | + | + | + | + | + |
(interpolate_spct) | – | + | + | + | + | + | + |
fscale | + | + | + | + | + | – | – |
fshift | + | + | + | + | + | – | – |
normalize | + | + | + | + | + | – | – |
clean | – | + | + | + | + | – | – |
despike | – | + | + | + | + | – | – |
maths operators | + | + | + | + | + | + | + |
maths functions | + | + | + | + | + | + | + |
tag | – | + | + | + | + | + | + |
untag | – | + | + | + | + | + | + |
Table 9. Transformation methods for collections of
spectra. Key: + available, – not available, ms
use msmsply()
or convolve_each()
to apply
function or operator to collection members.
methods | raw/cps | source | response | filter | reflector | object | chroma |
---|---|---|---|---|---|---|---|
convolve_each | – | + | + | + | + | + | + |
msmsply | + | + | + | + | + | + | + |
msdply | + | + | + | + | + | + | + |
mslply | + | + | + | + | + | + | + |
msaply | + | + | + | + | + | + | + |
rbindspct | + | + | + | + | + | + | + |
c | + | + | + | + | + | + | + |
maths operators | ms | ms | ms | ms | ms | ms | ms |
maths functions | ms | ms | ms | ms | ms | ms | ms |
e2q, q2e | – | + | + | – | – | – | – |
A2T, T2A | – | – | – | + | – | – | – |
Afr2T, T2Afr | – | – | – | + | – | – | – |
any2T, any2A, any2Afr | – | – | – | + | – | – | – |
convertTfrType | – | – | – | + | – | – | – |
convertThickness | – | – | – | + | – | – | – |
clip_wl | + | + | + | + | + | + | + |
trim_wl | + | + | + | + | + | + | + |
trim2overlap | + | + | + | + | + | + | + |
extend2extremes | + | + | + | + | + | + | + |
(trim_mspct) | + | + | + | + | + | + | + |
thin_wl | + | + | + | + | + | – | – |
interpolate_wl | – | + | + | + | + | + | + |
(interpolate_mspct) | – | + | + | + | + | + | + |
fscale | + | + | + | + | + | – | – |
fshift | + | + | + | + | + | – | – |
normalize | + | + | + | + | + | – | – |
clean | – | + | + | + | + | – | – |
despike | – | + | + | + | + | – | – |
tag | – | + | + | + | + | + | + |
untag | – | + | + | + | + | + | + |
Sometimes, especially for plotting, we may want to row-bind spectra.
When the aim is that the returned object retains its class and other
attributes like the time unit. Package ‘photobiology’
provides function rbinspct
for row-binding spectra, with
the necessary checks for consistency of the bound spectra.
By default an ID factor named spct.idx
is added allow to
identify the source of the observations after the binding. If the
supplied list has named members, then these names are used as factor
levels. If a character value is supplied to as idfactor
argument, this is used as name for the factor.
## Object: source_spct [1,044 x 4]
## containing 2 spectra in long form
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## spct_1 label: sunlight, simulated
## spct_2 label: sunlight, simulated
## spct_1 measured on 2010-06-22 09:51:00 UTC
## spct_2 measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 1,044 × 4
## w.length s.e.irrad s.q.irrad spct.idx
## <dbl> <dbl> <dbl> <fct>
## 1 280 0 0 spct_1
## 2 281. 0 0 spct_1
## 3 282. 0 0 spct_1
## 4 283. 0 0 spct_1
## # ℹ 1,040 more rows
## Object: source_spct [1,044 x 4]
## containing 2 spectra in long form
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## A label: sunlight, simulated
## B label: sunlight, simulated
## A measured on 2010-06-22 09:51:00 UTC
## B measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 1,044 × 4
## w.length s.e.irrad s.q.irrad site
## <dbl> <dbl> <dbl> <fct>
## 1 280 0 0 A
## 2 281. 0 0 A
## 3 282. 0 0 A
## 4 283. 0 0 A
## # ℹ 1,040 more rows
The name of the ID factor is stored as metadata in attribute
"idfactor"
of the spectral data object.
Special Extract methods for spectral objects have been implemented. These are used by default and preserve the attributes used by this package, except when the returned value is a single column from the spectral object.
## Object: source_spct [10 x 3]
## Wavelength range 280-288.30769 nm, step 0.9230769 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 10 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 6 more rows
## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154 285.5385 286.4615
## [9] 287.3846 288.3077
## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154 285.5385 286.4615
## [9] 287.3846 288.3077
## [1] 280.0000 280.9231 281.8462 282.7692 283.6923 284.6154 285.5385 286.4615
## [9] 287.3846 288.3077
In contrast to trim_spct
, subset
never
interpolates or inserts hinges. On the other hand, the
subset
argument accepts any logical expression and can be
consequently used to do subsetting, for example, based on factors. Both
subset()
and trim()
methods preserve
attributes.
## Object: source_spct [475 x 3]
## Wavelength range 324-800 nm, step 1-3 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 475 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 324 0.208 0.000000562
## 2 325 0.217 0.000000589
## 3 326 0.277 0.000000756
## 4 327 0.285 0.000000779
## # ℹ 471 more rows
## Object: source_spct [200 x 3]
## Wavelength range 601-800 nm, step 1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 200 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 601 0.630 0.00000316
## 2 602 0.631 0.00000317
## 3 603 0.636 0.00000321
## 4 604 0.658 0.00000332
## # ℹ 196 more rows
## Object: source_spct [6 x 3]
## Wavelength range 280-779 nm, step 99-100 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 6 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 379 0.413 0.00000131
## 3 479 0.754 0.00000302
## 4 579 0.647 0.00000313
## 5 679 0.580 0.00000329
## 6 779 0.471 0.00000307
R’s Extract methods $
and [[
can be used to
extract whole columns. Replace methods $<-
and
[<-
have definitions for spectral objects, which allow
their safe use. They work identically to those for data frames but check
the validity of the spectra after the replacement.
The functions e2q
and q2e
can be used on
source spectra to convert spectral energy irradiance into spectral
photon irradiance and vice versa. They can be also used with response
spectra. A second optional argument sets the action with
"add"
and "replace"
as possible values. By
default these functions use normal copy semantics but also support
reference semantics.
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.q.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
When a normalized spectrum is converted, the normalization is reapplied to the converted data.
For filter_spct
objects functions any2T()
,
any2A()
, and any2Afr()
allow conversion among
spectral transmittance, spectral absorptance and spectral absorbance.
Although some conversions require a known reflectance, either as an
Rfr
column in the data or an Rfr.constant
in
the attribute filter.properties
.
## Object: filter_spct [454 x 2]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 454 × 2
## w.length Tfr
## <int> <dbl>
## 1 240 0.00482
## 2 241 0.00464
## 3 242 0.00446
## 4 244 0.00414
## # ℹ 450 more rows
## Object: filter_spct [454 x 3]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## Afr: Spectral absorptance [/1]
## --
## # A tibble: 454 × 3
## w.length Tfr Afr
## <int> <dbl> <dbl>
## 1 240 0.00482 0.921
## 2 241 0.00464 0.921
## 3 242 0.00446 0.922
## 4 244 0.00414 0.922
## # ℹ 450 more rows
## Object: filter_spct [454 x 2]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Afr: Spectral absorptance [/1]
## --
## # A tibble: 454 × 2
## w.length Afr
## <int> <dbl>
## 1 240 0.921
## 2 241 0.921
## 3 242 0.922
## 4 244 0.922
## # ℹ 450 more rows
When a normalized spectrum is converted, the normalization is not reapplied to the converted data. This will change in the future.
Normalization is a way rescaling a spectrum so that the spectral quantity takes a fixed value, in most cases exactly 1, at a specific wavelength. Frequently this wavelength corresponds to the maximum value of the spectral quantity.
$$Q_\mathrm{norm}(\lambda) =
\frac{Q(\lambda)}{\max{Q(\lambda)}}$$ When normalizing to a
specific wavelength, say 300 nm, the equation becomes $$Q_\mathrm{norm}(\lambda) =
\frac{Q(\lambda)}{{Q(\lambda = 300)}}$$ Function
normalize
permits normalizing a spectrum to a value of one
at an arbitrary wavelength (nm) or to the wavelength of either the
maximum or the minimum spectral value. It supports all the different
spectral classes. In the example we use a source_spct
object. (Equivalent functions with names spelled with “s” instead of “z”
are available.)
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Spectral data normalized to s.e.irrad = 1 at 451 nm (max in 280-800 nm)
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [normalized]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
Which is equivalent to supplying "max"
as argument to
norm
, it is also possible to give a range within which the
maximum should be searched.
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Spectral data normalized to s.e.irrad = 1 at 451 nm (max in 400-700 nm)
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [normalized]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
It is also possible to normalize to an arbitrary wavelength within the range of the data, even if it is not one of the wavelength values present in the spectral object, as interpolation is used when needed.
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Spectral data normalized to s.e.irrad = 1 at 600.3 nm (wavelength)
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [normalized]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
The normalization status of a spectral object can be tested with
method is_normalized()
and the normalization used can be
recalled with method getNormalized()
.
## [1] TRUE
## [1] 451
Once a spectrum is normalized, summary methods that return values in
absolute units such as irrad()
, will trigger an error if
applied. Ratios and similar summaries that are invariant with respect to
normalization can be calculated. Already normalized spectra can be
normalized again.
Applying method fscale()
removes the normalization and
clears the corresponding attribute where the normalization information
is stored. This attribute also can be cleared with method
setNormalized()
, but this is rarely valid or of any
use.
While normalization is done with respect to a single wavelength, rescaling as implemented in this package is more flexible. The scaling factor is computed as a summary over a range of wavelengths. This allows us, among other things to rescale spectral irradiance so that irradiance in a specific waveband is equal to one, or to some other user supplied target value.
$$Q^\prime(\lambda) = \frac{Q(\lambda)}{f(Q(\lambda))_{\ \mathrm{for}\ \ \lambda_1\geq\lambda>\lambda_2}}\times \alpha$$ where α is the target value for f(Q(λ)).
In other words, function fscale()
rescales a spectrum by
dividing each spectral data value by a value calculated with a function
(f) selected by a character string (“total” or “mean”), or an actual R
function which can accept the spectrum object supplied as its first
argument. Additional named arguments can be also passed.
How metadata is set in the returned object is controlled by a logical
argument to parameter set.scaled
. If TRUE
, the
data are labelled as being expressed in relative units and if
FALSE
this attribute is not set. The default argument
depends on the value passed as argument to target
. If this
value is one, then the data are marked as no longer being expressed in
absolute units. If the target
is any other numeric value
then it is assumed that the intention is to re-scale the data and that
absolute physical units remain meaningful. It is important that the
metadata matches the actual use as printing of summaries and plot
labelling depends on them.
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [scaled]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Rescaled to 'mean of s.e.irrad' = 100 for wavelengths in 280-800 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [scaled]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
The default for f
can be overridden. R functions passed
as argument should be suitable for summarizing spectral objects as they
will receive as first argument a spectrum rather than a numeric vector.
Behind this requirement is the need to take into account wavelength
steps for integration to be meaningful. In the example below we compute
energy and photon irradiances. (The character arguments
"mean"
and "total"
call functions specific to
spectral data.)
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Rescaled to 'integral of s.e.irrad' = 1 for wavelengths in 280-800 nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [scaled]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Rescaled to 'a user supplied R function of s.e.irrad' = 1 for wavelengths in 400-700-none-NULL-NULL-NULL-NULL-c(399.999999999999, 400, 699.999999999999, 700)-PAR-PAR nm
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [scaled]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
In the third example, the spectral data is rescaled so that the corresponding photosynthetically-active irradiance is equal to one.
The normalization status of a spectral object can be tested with
method is_normalized()
and the normalization used can be
recalled with method getNormalized()
.
## [1] TRUE
## $multiplier
## [1] 1.932188
##
## $f
## [1] "mean"
##
## $range
## [1] 280 800
##
## $target
## [1] 1
##
## $cols
## [1] "s.e.irrad"
Once a spectrum is scaled, summary methods that return values in
absolute units such as irrad()
, will trigger a warning if
applied. Ratios and similar summaries that are invariant with respect to
normalization do not trigger warnings.
Applying method normalize()
removes the scaling and
clears the corresponding attribute where the scaling information is
stored. This attribute also can be cleared with method
setScaled()
, and this can be useful is some cases such as
when irradiance has been measured separately from the emission
spectrum.
While re-scaling relies on a multiplicative factor shifting of the scale is done by addition (or subtraction) or constant. This allows us, among other things to remove a baseline computed from a region known to be equal to zero.
Q′(λ) = Q(λ) − f(Q(λ)) for λ1 ≥ λ > λ2
Function fshift()
shifts the zero of the scale of a
spectrum by subtracting from each spectral data value a value calculated
with a function (f) selected by a character string (“mean”, “min” or
“max”), or an actual R function which can accept the spectrum object
supplied as its first argument. The range argument selects a region of
the spectrum to be used as reference in the calculation of the
summary.
## Object: source_spct [1,421 x 2]
## Wavelength range 251.16-898.81 nm, step 0.43-0.48 nm
## Label: led_desk201
## Measured on 2016-12-19 16:19:57.298874 UTC
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,421 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 251. 0
## 2 252. 0
## 3 252. 0
## 4 253. 0
## # ℹ 1,417 more rows
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 518 more rows
In the first example, the spectral data shifted so that the mean spectral irradiance becomes zero for the UV-B region. In the second example the minimum value in the range of wavelengths between 280~nm and 290~nm is used as zero reference for the scale.
Method clean()
should be used with care as off-range
values stem almost always from calibration errors or measuring noise.
This function allows one to replace such values, but in many cases a
zero shift or rescaling could be a better option. Even when the
off-range values are the result of random noise, replacing them with the
boundary values can cause bias, by censoring the data. In such cases
smoothing may be applied first to reduce the possible bias caused by
clean()
. Here we create artificial off-range
values by subtracting a constant from each spectrum.
## Warning in range_check_Tfr(x, strict.range = strict.range): Off-range
## transmittance values [-0.050..0.872] instead of [0..1]
## Object: filter_spct [454 x 2]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 454 × 2
## w.length Tfr
## <int> <dbl>
## 1 240 0
## 2 241 0
## 3 242 0
## 4 244 0
## # ℹ 450 more rows
It is possible to restrict the cleaning to a range of wavelengths and to provide a value to be used as replacement for the off-range data.
## Object: source_spct [522 x 2]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 522 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 -0.01
## 2 281. NA
## 3 282. NA
## 4 283. -0.01
## # ℹ 518 more rows
Method despike()
replaces spikes (very narrow peaks, or
valleys) by values estimated from neighbouring pixels. This method
should be also used carefully and the results inspected as it can remove
features of interest from the data. Usually one knows from theory or
experience if spikes can be real features or not.
## Object: source_spct [2 x 2]
## Wavelength range 398-432 nm, step 34 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 2 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 398 0.504
## 2 432 0.646
## Object: source_spct [0 x 2]
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 0 × 2
## # ℹ 2 variables: w.length <dbl>, s.e.irrad <dbl>
We can use smoothing both to average out random variation among
nearby pixels caused by measuring noise, or to filter out the real fine
structure of a spectrum to better assess the larger features. The
methods described here work by averaging the spectral data from
neighbouring wavelengths. The simplest methods are running medians and
running means (or “boxcar smoothing” in the terminology used in some
software). There are several methods for smoothing available in R based
on different algorithms. Some of these methods also automatically set
the degree of smoothing based on the data being smoothed. Package
‘photobiology’ defines function smooth_spct
, which at the
moment supports three different methods. Two are wrappers on R’s own
methods and a third one, "custom"
, is designed to use
stronger smoothing for values close to zero, where noise in spectral
irradiance measurements is proportionally more. The strength of the
smoothing and the range of wavelengths operated upon can be adjusted
through arguments to parameters. The comment
attribute is
updated.
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
## Object: filter_spct [454 x 2]
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 454 × 2
## w.length Tfr
## <int> <dbl>
## 1 240 0.00421
## 2 241 0.00418
## 3 242 0.00416
## 4 244 0.00411
## # ℹ 450 more rows
Converting spectra available at a given set of wavelengths values to
a different one, is frequently needed when operating with several
spectra of different origin. One can increase the apparent
resolution by interpolation, and reduce it by local averaging or
smoothing and resampling. The same function works on all
spct
objects, interpolating every numeric column except
w.length
which is set to the new wavelength values supplied
as argument. The optional argument fill.value
controls what
value is assigned to the “interpolated” data columns at wavelengths in
the new data that are outside the range of wavelengths in the original
spectrum being interpolated.
## Object: source_spct [1,001 x 3]
## Wavelength range 400-500 nm, step 0.1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 1,001 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 400 0.608 0.00000203
## 2 400. 0.610 0.00000204
## 3 400. 0.612 0.00000205
## 4 400. 0.614 0.00000205
## # ℹ 997 more rows
clip_wl()
Sometimes it is desirable to change the range of wavelengths included
in a spectrum. If we are interested in a given part of the spectrum,
there is no need to do calculations or plotting the whole spectrum. To
select part of a spectrum based on a range of wavelengths we may use the
clip_wl()
method. Method clip_wl()
simply
selects a range from the existing spectrum, and unless the range exactly
matches the wavelength values present in the spectrum, the range of
wavelengths in the returned clipped spectrum will be slightly narrower
than the requested by range
.
The range of wavelengths expressed in nanometres can be given as numeric vector of length two.
## Object: source_spct [3 x 3]
## Wavelength range 400-402 nm, step 1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 3 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 400 0.608 0.00000203
## 2 401 0.626 0.00000210
## 3 402 0.650 0.00000218
## Object: source_spct [401 x 3]
## Wavelength range 400-800 nm, step 1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 401 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 400 0.608 0.00000203
## 2 401 0.626 0.00000210
## 3 402 0.650 0.00000218
## 4 403 0.621 0.00000209
## # ℹ 397 more rows
As for other methods in the package, the range can be also supplied
as a waveband
object, or any other object for which
range()
returns a numeric range. Even a different spectrum
object is acceptable, and in many cases useful.
## Object: source_spct [86 x 3]
## Wavelength range 315-400 nm, step 1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 86 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 315 0.113 0.000000297
## 2 316 0.102 0.000000270
## 3 317 0.149 0.000000394
## 4 318 0.141 0.000000376
## # ℹ 82 more rows
The result can be a spectrum of length zero.
## Object: source_spct [0 x 3]
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 0 × 3
## # ℹ 3 variables: w.length <dbl>, s.e.irrad <dbl>, s.q.irrad <dbl>
trim_wl()
Sometimes, we need more flexibility. We may want to replace the observed values outside a certain range or expand the range of wavelengths, filling the expansion of all other variables with a certain value (i.e. a number, or NA.). In contrast to clipping (or functionally equivalent, indexing, or subsetting), trimming ensures that there will be spectral data returned at the boundaries of the trimmed region. These values are obtained by interpolation when they are not already present in the data.
More flexibility is available in method trim_wl()
, to
which we can supply arguments range
,
use.hinges
, and fill
. By default interpolation
is used at the boundaries of the range
, in which case the
range of wavelengths in the returned spectrum is that passed as argument
to range
.
## Object: source_spct [520 x 3]
## Wavelength range 282.5-800 nm, step 0.2692308-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 520 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 282. 0 0
## 2 283. 0 0
## 3 284. 0 0
## 4 285. 0 0
## # ℹ 516 more rows
## Object: source_spct [519 x 3]
## Wavelength range 282.76923-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 519 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 283. 0 0
## 2 284. 0 0
## 3 285. 0 0
## 4 286. 0 0
## # ℹ 515 more rows
As for clip_wl()
the range can be also supplied as a
waveband
object, or any other object for which
range()
returns a numeric range. Even a different spectrum
object is acceptable.
## Object: source_spct [301 x 3]
## Wavelength range 400-700 nm, step 1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 301 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 400 0.608 0.00000203
## 2 401 0.626 0.00000210
## 3 402 0.650 0.00000218
## 4 403 0.621 0.00000209
## # ℹ 297 more rows
The default for fill
is NULL
which results
in deletion values outside the trimmed region. However, it is possible
to supply a different argument, to be used to replace the off-range data
values.
## Object: source_spct [524 x 3]
## Wavelength range 280-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 524 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 NA NA
## 2 281. NA NA
## 3 281. NA NA
## 4 282. 0 0
## # ℹ 520 more rows
Furthermore, when fill is not NULL
, expansion is
possible.
## Object: source_spct [529 x 3]
## Wavelength range 275-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 529 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 275 0 0
## 2 276. 0 0
## 3 277. 0 0
## 4 277. 0 0
## # ℹ 525 more rows
By default interpolation at the boundaries is used, but setting
use.hinges
to FALSE
results in clipping, a
behaviour similar to that of clip_wl
only if
fill == NULL
.
## Object: source_spct [524 x 3]
## Wavelength range 280-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 524 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 NA NA
## 2 281. NA NA
## 3 281. NA NA
## 4 282. 0 0
## # ℹ 520 more rows
## Object: source_spct [522 x 3]
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 522 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 NA NA
## 2 281. NA NA
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 518 more rows
When use.hinges == TRUE
and expansion or replacement is
done, two observations are inserted at each boundary, differing in
wavelength by 1 × 10−12,nm
to prevent rounding errors in later calculations.
trim2ovelap()
and
extend2extremes()
Functions trim2ovelap()
and
extend2extremes()
are defined only for collections of
spectra. They are convenience functions, as they handle special use
cases of trim_wl()
with a simplified syntax. They can be
used to make the wavelength range of the different members of a
collection of spectra consistent, either by trimming all spectra to the
range of overlapping wavelengths, or by extending the wavelength ranges
as needed and filling the added spectral values with a constant
value.
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2015-10-31 08:00:00 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2015-10-31 09:00:00 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
## Object: source_mspct [2 x 1]
## --- Member: time.01 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2015-10-31 08:00:00 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
## --- Member: time.02 ---
## Object: source_spct [1,593 x 2]
## Wavelength range 290-1000 nm, step 0.34-0.47 nm
## Label: cosine.hour.9
## Measured on 2015-10-31 09:00:00 UTC
## Measured at 60.227 N, 24.018 E; Viikki, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1,593 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 290 0
## 2 290. 0
## 3 291. 0
## 4 291. 0
## # ℹ 1,589 more rows
##
## --- END ---
thin_wl()
One possible way of decreasing the storage space occupied by spectral
data is to vary the density of wavelength values stored based on the
local change in slope (second derivative) of the plot a spectrum. Method
thin_wl()
can be used to remove or “thin” down the
wavelength values stored in those regions of the spectrum where this
would result in minimal loss of information. The algorithm currently in
use is suboptimal in the removal of wavelength values but fast and easy
to implement. Which wavelength values are retained or not could
change with future implementations.
## [1] 425
## [1] 1 4
## [1] 233
## [1] 1 18
The strength of the thinning can be adjusted by passing arguments to
parameters max.wl.step
and max.slope.delta
.
This method is implemented for objects of all spectral classes that a
single default data column in addition to wavelengths and also for
collections of those objects.
NOTE: Thinning, obviously, almost always changes spectra originally expressed at the same set of wavelength values into spectra expressed at two different sets of wavelengths values. This forbid some operations among them, like parallel operations in collections of spectra or combining them into a wide data frame. Most of these restrictions have been removed by implementing on-the-fly interpolation in version 0.10.15.
It is very instructive to look at weighted spectral data to understand how effective irradiances are calculated. Plotting effective spectral irradiance data can be very informative when analysing interactions among photoreceptors and ambient radiation. It can also illustrate the large effect that small measuring errors can have on the estimated effective irradiances or exposures when SWFs have a steep slope.
For biologically effective energy irradiance EBE the following equation describes the convolution, wavelength by wavelength, between spectral energy irradiance and a biological spectral weighting function
EBE(λ) = E(λ) × wE(λ) or for biologically effective photon irradiance QBE QBE(λ) = Q(λ) × wQ(λ) For the convolution to be possible, both spectral irradiance and spectral weights should be available for the same basis of expression and at the same discrete wavelength values.
The multiplication operator is defined for operations between a
source_spct
and a waveband
, so this is the
easiest way of doing the calculations.
## Object: source_spct [122 x 2]
## Wavelength range 280-400 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Data weighted using 'range.250.400.wtd' BSWF
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 122 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 280 0
## 2 281. 0
## 3 282. 0
## 4 283. 0
## # ℹ 118 more rows
We call tagging, to the process of adding reference information to spectral data. For example we can add a factor indicating regions or bands in the spectrum. We can add also information on the colour, as seen by humans, for each observed value, or for individual regions or bands of the spectrum. In most cases this additional information is used for annotations when plotting the spectral data.
The function tag
can be used to tag different parts of a
spectrum according to wavebands.
## Object: source_spct [524 x 6]
## Wavelength range 280-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 524 × 6
## w.length s.e.irrad s.q.irrad wl.color wb.color wb.f
## <dbl> <dbl> <dbl> <chr> <chr> <fct>
## 1 280 0 0 #000000 <NA> <NA>
## 2 281. 0 0 #000000 <NA> <NA>
## 3 282. 0 0 #000000 <NA> <NA>
## 4 283. 0 0 #000000 <NA> <NA>
## # ℹ 520 more rows
## Object: source_spct [524 x 6]
## Wavelength range 280-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 524 × 6
## w.length s.e.irrad s.q.irrad wl.color wb.color wb.f
## <dbl> <dbl> <dbl> <chr> <chr> <fct>
## 1 280 0 0 #000000 black UVB
## 2 281. 0 0 #000000 black UVB
## 3 282. 0 0 #000000 black UVB
## 4 283. 0 0 #000000 black UVB
## # ℹ 520 more rows
The added factor and colour data can be used for further processing
or for plotting. Information about the tagging and wavebands is stored
in an attribute tag.attr
in every tagged spectrum, this
yields a more compact output and keeps a trace of the
tagging.
## $valid
## [1] TRUE
##
## $time.unit
## [1] "second"
##
## $wb.key.name
## [1] "Bands"
##
## $wl.color
## [1] TRUE
##
## $wb.color
## [1] TRUE
##
## $wb.num
## [1] 1
##
## $wb.colors
## [1] "#735B57"
##
## $wb.names
## [1] "PAR"
##
## $wb.list
## $wb.list[[1]]
## PAR
## low (nm) 400
## high (nm) 700
## weighted none
Additional functions are available which return a tagged spectrum and take as input a list of wavebands, but no spectral data. They build a spectrum from the data in the wavebands, and are useful for plotting the boundaries of wavebands.
## Object: generic_spct [8 x 12]
## Wavelength range 100-400 nm, step 9.947598e-13-180 nm
## Variables:
##
## --
## # A tibble: 8 × 12
## w.length counts cps s.e.irrad s.q.irrad Tfr Rfl s.e.response wl.color
## <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>
## 1 100. 0 0 0 0 0 0 0 #000000
## 2 100 0 0 0 0 0 0 0 #000000
## 3 280. 0 0 0 0 0 0 0 #000000
## 4 280 0 0 0 0 0 0 0 #000000
## # ℹ 4 more rows
## # ℹ 3 more variables: wb.color <chr>, wb.f <fct>, y <dbl>
## Object: generic_spct [3 x 15]
## Wavelength range 190-357.5 nm, step 60-107.5 nm
## Variables:
##
## --
## # A tibble: 3 × 15
## w.length counts cps s.e.irrad s.q.irrad Tfr Rfl s.e.response wl.color
## <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>
## 1 190 0 0 0 0 0 0 0 #000000
## 2 298. 0 0 0 0 0 0 0 #000000
## 3 358. 0 0 0 0 0 0 0 #000000
## # ℹ 6 more variables: wb.color <chr>, wb.name <chr>, wb.f <fct>, wl.high <dbl>,
## # wl.low <dbl>, y <dbl>
Function wb2tagged_spct
returns a tagged spectrum, with
two rows for each waveband, corresponding to the low and high wavelength
boundaries, while function wb2rect_spct
returns a spectrum
with only one row per waveband, with w.length
set to its
midpoint but with additional columns xmin
and
xmax
corresponding to the low and high wavelength
boundaries of the wavebands.
Function is_tagged
can be used to query if an spectrum
is tagged or not, and function untag
removes the tags.
## Object: source_spct [524 x 6]
## Wavelength range 280-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 524 × 6
## w.length s.e.irrad s.q.irrad wl.color wb.color wb.f
## <dbl> <dbl> <dbl> <chr> <chr> <fct>
## 1 280 0 0 #000000 <NA> <NA>
## 2 281. 0 0 #000000 <NA> <NA>
## 3 282. 0 0 #000000 <NA> <NA>
## 4 283. 0 0 #000000 <NA> <NA>
## # ℹ 520 more rows
## [1] TRUE
## [1] FALSE
In the chuck above, we can see how this works, using in this case the
default byref = FALSE
which adds the tags to a copy of the
spectrum object. In contrast, setting byref = TRUE
adds the
tags in place, or “by reference”“, to the spct object supplied as
argument. Passing arguments by reference is unusual for R and is best
avoided.
## [1] FALSE
## Object: source_spct [524 x 3]
## Wavelength range 280-800 nm, step 1.023182e-12-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## # A tibble: 524 × 3
## w.length s.e.irrad s.q.irrad
## <dbl> <dbl> <dbl>
## 1 280 0 0
## 2 281. 0 0
## 3 282. 0 0
## 4 283. 0 0
## # ℹ 520 more rows
## [1] FALSE
Summaries can be calculated both from individual spectral objects (Table 10) and from collections of spectral objects (Table 11). They return a simpler object than the spectral data in their arguments. For example a vector of numeric values, possibly of length one, in the case of individual spectra, or a data frame containing one row of summary data for each spectrum in a collection of spectra.
Table 10. Summary methods for spectra. Key: + available, - not available, (+) object_spct objects can be converted into filter_spct or reflector_spct objects before applying these methods.
methods | raw/cps | source | response | filter | reflector | object | chroma |
---|---|---|---|---|---|---|---|
irrad | – | + | – | – | – | – | – |
e_irrad | – | + | – | – | – | – | – |
q_irrad | – | + | – | – | – | – | – |
fluence | – | + | – | – | – | – | – |
e_fluence | – | + | – | – | – | – | – |
q_fluence | – | + | – | – | – | – | – |
ratio | – | + | – | – | – | – | – |
e_ratio | – | + | – | – | – | – | – |
q_ratio | – | + | – | – | – | – | – |
qe_ratio | – | + | – | – | – | – | – |
eq_ratio | – | + | – | – | – | – | – |
response | – | – | + | – | – | – | – |
e_response | – | – | + | – | – | – | – |
q_response | – | – | + | – | – | – | – |
transmittance | – | – | – | + | – | + | – |
absorptance | – | – | – | + | – | + | – |
absorbance | – | – | – | + | – | + | – |
reflectance | – | – | – | – | + | + | – |
wl_range | + | + | + | + | + | + | + |
wl_min | + | + | + | + | + | + | + |
wl_max | + | + | + | + | + | + | + |
wl_stepsize | + | + | + | + | + | + | + |
wl_expanse | + | + | + | + | + | + | + |
wl_midpoint | + | + | + | + | + | + | + |
labels | + | + | + | + | + | + | + |
summary | + | + | + | + | + | + | + |
peaks | – | + | + | + | + | (+) | - |
spikes | – | + | + | + | + | (+) | - |
valleys | – | + | + | + | + | (+) | - |
wls_at_target | – | + | + | + | + | (+) | - |
integrate_spct | + | + | + | + | + | + | + |
average_spct | + | + | + | + | + | + | + |
color_of | – | + | – | – | – | – | – |
As mentioned above, summary methods for collections of spectra return
data frame objects. In many cases preserving the attributes from the
different members of the collection in the returned value is important,
and can be achieved easily by passing a suitable character vector as
argument to parameter attr2tb
, using the same syntax as
described for function add_attr2tb
.
Table 11. Summary methods for collections of
spectra. Key: + available, * attr2tb
supported, –
not available, ms use msmsply()
to apply
function to collection members, d use
msdply()
, l use mslply
to
apply function to collection members, a use
msaply
to apply function to collection members.
methods | raw/cps | source | response | filter | reflector | object | chroma |
---|---|---|---|---|---|---|---|
irrad | – | * | – | – | – | – | – |
e_irrad | – | * | – | – | – | – | – |
q_irrad | – | * | – | – | – | – | – |
fluence | – | * | – | – | – | – | – |
e_fluence | – | * | – | – | – | – | – |
q_fluence | – | * | – | – | – | – | – |
ratio | – | * | – | – | – | – | – |
e_ratio | – | * | – | – | – | – | – |
q_ratio | – | * | – | – | – | – | – |
qe_ratio | – | * | – | – | – | – | – |
eq_ratio | – | * | – | – | – | – | – |
response | – | – | * | – | – | – | – |
e_response | – | – | * | – | – | – | – |
q_response | – | – | * | – | – | – | – |
transmittance | – | – | – | * | – | * | – |
absorptance | – | – | – | * | – | * | – |
absorbance | – | – | – | * | – | * | – |
reflectance | – | – | – | – | * | * | – |
color_of | – | + | – | – | – | – | – |
wl_range | + | + | + | + | + | + | + |
wl_min | + | + | + | + | + | + | + |
wl_max | + | + | + | + | + | + | + |
wl_stepsize | + | + | + | + | + | + | + |
wl_spread | + | + | + | + | + | + | + |
wl_midpoint | + | + | + | + | + | + | + |
labels | l | l | l | l | l | l | l |
summary | l | l | l | l | l | l | l |
peaks | – | + | + | + | + | (+) | - |
valleys | – | + | + | + | + | (+) | - |
spikes | – | + | + | + | + | (+) | - |
wls_at_target | – | + | + | + | + | (+) | - |
integrate_spct | a, d, l | a, d, l | a, d, l | a, d, l | a, d, l | a, d, l | a, d, l |
average_spct | a, d, l | a, d, l | a, d, l | a, d, l | a, d, l | a, d, l | a, d, l |
Specialized definitions of summary
and the corresponding
print
methods are available for spectral objects.
Attributes "what.measured"
, "when.measured"
and "where.measured"
are included in the summary print out
only if set in the spectral object summarized.
## Summary of source_spct [522 x 3] object: sun.spct
## Wavelength range 280-800 nm, step 0.9230769-1 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## s.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1]
## --
## w.length s.e.irrad s.q.irrad
## Min. :280.0 Min. :0.0000 Min. :0.000e+00
## 1st Qu.:409.2 1st Qu.:0.4115 1st Qu.:1.980e-06
## Median :539.5 Median :0.5799 Median :2.929e-06
## Mean :539.5 Mean :0.5160 Mean :2.407e-06
## 3rd Qu.:669.8 3rd Qu.:0.6664 3rd Qu.:3.155e-06
## Max. :800.0 Max. :0.8205 Max. :3.375e-06
In the case of collections of spectra, by default a conscise summary is printed.
## Summary of filter_mspct [2 x 1] object: two_filters.mspct
## # A tibble: 2 × 8
## spct.idx class dim w.length.min w.length.max colnames multiple.wl Tfr.type
## <chr> <chr> <chr> <int> <int> <list> <dbl> <chr>
## 1 spct_1 filter… [454… 240 800 <chr> 1 total
## 2 spct_2 filter… [425… 190 800 <chr> 1 total
However, the spectra can be also summarized individually.
## $spct_1
## Summary of filter_spct [454 x 2] object: anonymous
## Wavelength range 240-800 nm, step 1-4 nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## w.length Tfr
## Min. :240.0 Min. :0.0030
## 1st Qu.:376.2 1st Qu.:0.8920
## Median :513.5 Median :0.9140
## Mean :519.1 Mean :0.7835
## 3rd Qu.:661.8 3rd Qu.:0.9211
## Max. :800.0 Max. :0.9254
##
## $spct_2
## Summary of filter_spct [425 x 2] object: anonymous
## Wavelength range 190-800 nm, step 1-4 nm
## Label: Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, UK
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## w.length Tfr
## Min. :190.0 Min. :0.00001
## 1st Qu.:314.0 1st Qu.:0.00001
## Median :473.0 Median :0.01421
## Mean :472.4 Mean :0.37195
## 3rd Qu.:603.0 3rd Qu.:0.89521
## Max. :800.0 Max. :0.90179
In the case of multiple spectra in long form, by default a single summary is printed.
## Summary of filter_spct [879 x 3] object: two_filters.spct
## containing 2 spectra in long form
## Wavelength range 240-800 nm, step -610-67 nm
## spct_1 label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## spct_2 label: Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, UK
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## w.length Tfr spct.idx
## Min. :190.0 Min. :0.00001 spct_1:454
## 1st Qu.:359.5 1st Qu.:0.00400 spct_2:425
## Median :492.0 Median :0.89664
## Mean :496.6 Mean :0.58450
## 3rd Qu.:643.5 3rd Qu.:0.91429
## Max. :800.0 Max. :0.92543
Passing eval="collection"
we obtain the same condensed
summary as shown above as the default for collections of spectra.
(Output not shown here.)
Passing eval="each"
we obtain the same expanded summary
as shown above for eval="each"
for collections of spectra.
(Output not shown here.)
The usual and three new summary methods are available for
spectra, but redefined to return wavelength-based summaries in
nanometres (nm) directly from spectra. For clarity, synonyms with names
starting with wl_
are provided. The three new generic
methods midpoint()
, expanse()
and
stepsize()
are also defined for numeric
.
## [1] 280 800
## [1] 280
## [1] 800
## [1] 540
## [1] 520
## [1] 0.9230769 1.0000000
Most frequently used summary methods are implemented for collections
of spectra. See the Table 11 for those methods that need to be applied
with functions msaply
, msdply
or
mslply
to members in a collection returning the results in
an array (vector, or matrix), a data frame or a list object. In many
cases depending of the class desired for the result, one can chose a
suitable apply function, and sometimes it is best to use such a
function, even when the corresponding method is implemented for
collections of spectra.
Collections of spectra can be useful not only for time-series of spectra or spectral images, but also when dealing with a small group of related spectra. In the example below we show how to use a collection of spectra for calculating summaries. The spectra in a collection do not need to have been measured at the same wavelength values, or have the same number of rows or even of columns. Consequently, in many cases applying the wavelength summary functions described above to collections of spectra can be useful. The value returned is a data frame, with a number of data columns equal to the length of the returned value by the corresponding method for individual spectra.
filters.mspct <- filter_mspct(list(none = clear.spct,
pet = polyester.spct,
yellow = yellow_gel.spct))
wl_range(filters.mspct)
## # A tibble: 3 × 3
## spct.idx min.wl max.wl
## <fct> <dbl> <dbl>
## 1 none 100 5000
## 2 pet 240 800
## 3 yellow 190 800
Peaks and valleys in spectra are usually features of interest, while in most cases spikes (very narrow peaks or valleys) are undesired “noise”. Of course, there are exceptions and for this reason methods used for extract any of these features have a similar interface.
Peaks and valleys can be identified simply as local maxima and minima, or their actual location better estimated by fitted a model to the local maximum or minimum and its neighbours.
Methods peaks
and valleys
take spectra as
first argument and return a subset of the spectral object data
corresponding to local maxima and local minima of the measured variable.
span
defines the width of the window used as a
number of observations.
## Object: source_spct [3 x 2]
## Wavelength range 451-747 nm, step 44-252 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 3 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 451 0.820
## 2 495 0.790
## 3 747 0.503
## Object: source_spct [9 x 2]
## Wavelength range 358-761 nm, step 30-72 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 9 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 358 0.254
## 2 393 0.242
## 3 431 0.414
## 4 487 0.651
## # ℹ 5 more rows
In the case of source_spct
and
response_spct
methods unit.out
can be used to
force peaks to be searched using either energy or photon based spectral
irradiance. The default is energy, or the option
"photobiology.radiation.unit"
if set.
## [1] 455.48 608.62
By passing refine.wl = TRUE
we request that location of
the peaks is refined by fitting a model to describe the
peak.
## [1] 455.3069 608.8525
It is possible to approximately set the width in nanometres of the
moving window within which a maximum is searched by passing an odd
number as argument to span
. However, even numbers if passed
are increased with a warning.
## Object: source_spct [18 x 2]
## Wavelength range 354-774 nm, step 11-51 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 18 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 354 0.376
## 2 366 0.449
## 3 378 0.497
## 4 416 0.676
## # ℹ 14 more rows
A value of NULL
as argument to span
searches for a single maximum for the whole spectrum.
## Object: source_spct [1 x 2]
## Wavelength range 451-451 nm, step NA nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 451 0.820
The position of peaks can be refined by spline interpolation. This is still an experimental feature, that may fail, especially in the estimate of the value of the spectral quantity at the peak.
## Object: source_spct [1 x 2]
## Wavelength range 451.02685-451.02685 nm, step NA nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 1 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 451. 0.821
Method spikes
differs from peaks
in that it
uses a different algorithm that detects only very narrow peaks, usually
called by the name of spikes. The value returned is as in the case of
peaks
a subset of the original spectrum. The parameters
controlling the sensitivity also differ.
## Object: source_spct [2 x 2]
## Wavelength range 398-432 nm, step 34 nm
## Label: sunlight, simulated
## Measured on 2010-06-22 09:51:00 UTC
## Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI
## Variables:
## w.length: Wavelength [nm]
## s.e.irrad: Spectral energy irradiance [W m-2 nm-1]
## --
## # A tibble: 2 × 2
## w.length s.e.irrad
## <dbl> <dbl>
## 1 398 0.504
## 2 432 0.646
Low level functions find_peaks
, get_peaks
,
get_valleys
, fit_peaks
,
fit_valleys
, and find_spikes
take numeric
vectors as first argument.
The methods are also implemented for collections of spectra.
## Object: filter_mspct [3 x 1]
## --- Member: none ---
## Object: filter_spct [0 x 2]
## Label: theoretical fully transparent object
## Rfr (/1): 0.000, thickness (mm): 1.00e+03, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Internal spectral transmittance [/1]
## --
## # A tibble: 0 × 2
## # ℹ 2 variables: w.length <dbl>, Tfr <dbl>
## --- Member: pet ---
## Object: filter_spct [1 x 2]
## Wavelength range 451-451 nm, step NA nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 1 × 2
## w.length Tfr
## <int> <dbl>
## 1 451 0.925
## --- Member: yellow ---
## Object: filter_spct [4 x 2]
## Wavelength range 331-768 nm, step 60-293 nm
## Label: Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, UK
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 4 × 2
## w.length Tfr
## <int> <dbl>
## 1 331 0.00471
## 2 624 0.898
## 3 708 0.900
## 4 768 0.902
##
## --- END ---
Two of the filters in the collection do not have peaks, and a spectrum object of length zero is returned for them.
Method wls_at_target
takes a spectrum as first argument
and returns a subset of the spectral object data or a new object
corresponding to wavelengths at which the spectrum is at the target
value. Geometrically is equivalent to finding the wavelengths at which a
horizontal target line intercepts the curve depicting the
spectrum.
## Object: filter_spct [1 x 2]
## Wavelength range 709.35352-709.35352 nm, step NA nm
## Label: Ler_06_black.spct
## Measured on 2017-07-03 13:18:18.615114 UTC
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 1 × 2
## w.length Tfr
## <dbl> <dbl>
## 1 709. 0.222
## Object: filter_spct [1 x 2]
## Wavelength range 709.50991-709.50991 nm, step NA nm
## Label: Ler_06_black.spct
## Measured on 2017-07-03 13:18:18.615114 UTC
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 1 × 2
## w.length Tfr
## <dbl> <dbl>
## 1 710. 0.224
This function can be used with all spectral classes defined in the
package. In the case of source_spct
and
response_spct
methods parameter unit.out
allows to switch between energy and photon units for the search and
returned value, while in the case of filter_spct
methods
filter.qty` allows to switch between transmittance, absorptance and
absorbance.
The method is also implemented for collections of spectra.
## Object: filter_mspct [3 x 1]
## --- Member: none ---
## Object: filter_spct [0 x 2]
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 0 × 2
## # ℹ 2 variables: w.length <dbl>, Tfr <dbl>
## --- Member: pet ---
## Object: filter_spct [1 x 2]
## Wavelength range 322-322 nm, step NA nm
## Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new
## Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 1 × 2
## w.length Tfr
## <int> <dbl>
## 1 322 0.462
## --- Member: yellow ---
## Object: filter_spct [1 x 2]
## Wavelength range 509-509 nm, step NA nm
## Label: Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, UK
## Rfr (/1): NA, thickness (mm): NA, attenuation mode: NA.
## Variables:
## w.length: Wavelength [nm]
## Tfr: Total spectral transmittance [/1]
## --
## # A tibble: 1 × 2
## w.length Tfr
## <int> <dbl>
## 1 509 0.457
##
## --- END ---
Energy irradiance is the integral over wavelengths of spectral energy irradiance
E = ∫λ = λ1λ = λ2E(λ) dλ where λ1 ≥ λ > λ2 defines a waveband, or range of wavelengths.
Photon (=quantum) irradiance is the integral over wavelengths of spectral photon irradiance.
Q = ∫λ = λ1λ = λ2Q(λ) dλ Spectrally weighted (or biologically effective) energy irradiance is the integral of the result of the convolution of spectral energy irradiance by a spectral weighting function w(λ).
EBE = ∫λ = λ1λ = λ2E(λ) ⋅ wE(λ) dλ Spectrally weighted (or effective) photon irradiance can be computed similarly with the corresponding weighting function wQ(λ).
The code using spct
objects is simple; to integrate the
whole spectrum we can use irrad()
that returns by default
energy irradiance, unless an R option is set to make photon-based units
the default. When this flexibility is not needed, e_irrad()
and q_irrad()
should be preferred. For most examples we use
energy-based units and e_irrad()
, but they also apply
unchanged to q_irrad()
and photon-based units, and
vice-versa for those examples using q_irrad()
.
The abbreviations E and Q are used to denote these two quantities, usually with the waveband as a subscript. In what follows “Total” as subscript denotes the whole range of wavelengths in the spectrum. This is the default.
## E_Total
## 269.1249
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
To integrate one restricted range of wavelengths from a spectrum, we
can provide a wavelength definition. In this example, waveband
PAR.wb
giving the definition of photosynthetically
active radiation. (PAR.wb
was defined above.)
## E_PAR
## 196.6343
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
It is also valid to pass as argument for w.band
a
numeric range representing wavelengths in manometers (nm), which is
converted into a waveband definition on-the-fly. Note, however, that the
automatically assigned name gives only the range.
## E_range.400.700
## 196.6343
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
The ‘photobiology’ package uses base SI units, so by default photon irradiance (= quantum irradiance) is expressed in mol s−1 m−2. We can pass a scaling factor as shown below if needed.
## Q_PAR
## 894.1483
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
It is possible to supply a time unit to use, instead of the default of seconds, as basis of expression for the returned value. However, be aware that conversion into a different time unit than that used during measurement, is only valid for sources like lamps, which have an output the remains constant in time.
## Q_PAR
## 1.585662
## attr(,"time.unit")
## [1] "hour"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
Using a shorter time unit than the original, yields an average value re-expressed on a new time unit base.
## E_PAR
## 92.16251
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
Lists of wavebands are also accepted as argument for parameter
w.band
in which case a named numeric vector of summary
values is returned by default.
## E_UVB E_UVA
## 0.6445105 27.9842061
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
## Q_UVB Q_UVA
## 1.675387e-06 8.482093e-05
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
## Q_UVB Q_UVA
## 1.675387 84.820933
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
These functions have an additional argument quantity
,
with default "total"
, which can take values controlling the
output. The value “total” yields irradiance in W m−2,
integrated over wavelengths for each waveband, while “average” yields
the mean spectral irradiance within each waveband in
W m−2 nm−1.
## E_UVB E_UVA
## 0.6445105 27.9842061
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
## E(wl)_UVB E(wl)_UVA
## 0.01841458 0.32922595
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "average energy irradiance"
When quantity = "contribution"
irradiances for
individual wavebands are expressed relative to the irradiance computed
for the whole spectrum, while for quantity = "relative"
they are expressed relative to the sum of the irradiances for all the
wavebands. In both cases values are expressed as fractions of one.
## E/Etot_UVB E/Etot_UVA
## 0.002394838 0.103982226
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "contribution energy irradiance"
## E/Esum_UVB E/Esum_UVA
## 0.02251273 0.97748727
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "relative energy irradiance"
When setting "contribution.pc"
or
"relative.pc"
as quantity
the same values as
in the examples above, are expressed as percentages instead of
fractions.
## E/Etot_UVB E/Etot_UVA
## 0.2394838 10.3982226
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "contribution.pc energy irradiance"
## E/Esum_UVB E/Esum_UVA
## 2.251273 97.748727
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "relative.pc energy irradiance"
The total radiation received on a surface during an exposure event
can be also calculated with methods irrad()
,
e_irrad()
and q_irrad()
, but the values
returned are irradiances expressed on a very unusual time basis. These
are no longer W m-2 (J s-1 m-2), but instead J per 8 hours per square
meter.
## E_PAR
## 5663067
## attr(,"time.unit")
## [1] "28800s (~8 hours)"
## attr(,"radiation.unit")
## [1] "total energy irradiance"
When the intention is to calculate a total fluence or exposure for an
event, function fluence()
, e_fluence()
or
q_fluence()
should be used as this will add the correct
metadata attributes to the returned value: expressed as energy or
photons per unit area per event. See later sections for details.
## E_PAR
## 5663067
## attr(,"radiation.unit")
## [1] "energy fluence (J m-2)"
## attr(,"exposure.duration")
## [1] "28800s (~8 hours)"
In all earlier examples in this section, the default naming of
returned values was active. The default naming of the values is an
abbreviation of the physical quantity plus the name of the wavelength.
Alternatively "short"
naming uses only the name of the
wavebands as shown below, obtained from the label stored in the waveband
definitions.
## UVB UVA
## 1.675387e-06 8.482093e-05
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
Naming can also be completely suppressed.
## [1] 1.675387e-06 8.482093e-05
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
Names of members of a list of wavebands, override the labels in waveband definitions.
names(UV_bands.lst) <- c("UV-C", "UV-B", "UV-A")
q_irrad(sun.spct, UV_bands.lst, naming = "short", scale.factor = 1e6)
## UV-B UV-A
## 1.675387 84.820933
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total photon irradiance"
Collections of spectra can be useful not only for time-series of spectra or spectral images, but also when dealing with a small group of related spectra. In the example below we show how to use a collection of spectra to estimate irradiances under different filters set up in sunlight.
Methods irrad()
, e_irrad()
and
q_irrad()
can be used for collections of spectra exactly as
for a single spectrum (as described above). We here only show the
additional features that apply to collections. In this first example, we
can see that the returned object is a data frame instead of a named
numeric vector.
## # A tibble: 5 × 2
## spct.idx E_PAR
## <fct> <dbl>
## 1 time.01 16.2
## 2 time.02 15.7
## 3 time.03 15.7
## 4 time.04 15.8
## 5 time.05 16.4
Spectral objects can contain metadata as attributes. When summarizing a collection of spectra it is frequently very useful to copy some of these metadata, extracted from each member of the collection, to columns in the returned data frame. This can be done as follows.
q_irrad(sun_evening.mspct,
w.band = PAR.wb,
scale.factor = 1e6, # umol m-2 s-1
attr2tb = c(when.measured = "time", lon = "lon", lat = "lat"))
## # A tibble: 5 × 5
## spct.idx Q_PAR time lon lat
## <fct> <dbl> <dttm> <dbl> <dbl>
## 1 time.01 72.7 2023-06-12 18:38:00 24.0 60.2
## 2 time.02 70.5 2023-06-12 18:39:00 24.0 60.2
## 3 time.03 70.7 2023-06-12 18:40:00 24.0 60.2
## 4 time.04 70.9 2023-06-12 18:41:00 24.0 60.2
## 5 time.05 74.2 2023-06-12 18:42:00 24.0 60.2
For a more advanced example, we reuse the collection of filter
spectra filters.mspct
from an earlier section. We convolve
each filter’s spectral transmittance by the spectral irradiance of the
light source so as to predict the irradiances under the filters. We
specify the name of the column where the names of the spectra (their
index) is stored.
filtered_sun <- convolve_each(filters.mspct, sun.spct)
q_irrad(filtered_sun,
list(UVA.wb, PAR.wb),
scale.factor = 1e6,
idx = "Filter")
## # A tibble: 3 × 3
## Filter Q_UVA Q_PAR
## <fct> <dbl> <dbl>
## 1 none 84.8 894.
## 2 pet 70.2 823.
## 3 yellow 0.104 536.
The code above example can also be written as a single statement. Here we also tweak column names, delete one column, and swap the position of the remaining columns.
q_irrad(convolve_each(filters.mspct, sun.spct),
list("UV-A" = UVA.wb, PAR.wb),
scale.factor = 1e6, # umol m-2 s-1
naming = "short",
attr2tb = c(what.measured = "Filter type"))[ , c(4, 2, 3)]
## # A tibble: 3 × 3
## `Filter type` `UV-A` PAR
## <chr> <dbl> <dbl>
## 1 theoretical fully transparent object 84.8 894.
## 2 Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDer… 70.2 823.
## 3 Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco, … 0.104 536.
It is also possible to use an apply function. See sections
apply functions and convolve
for more details, as
in certain cases only one or the other can be used.
Energy fluence is energy irradiance integrated over a lapse of time or event, and is expressed as energy per area.
Energy fluence is the integral over wavelengths and time of spectral energy irradiance
FE = ∫λ = λ1λ = λ2∫t = t1t = t2E(λ) dλ dt where λ1 ≥ λ > λ2 defines a waveband, or range of wavelengths, and t1 ≥ t > t2.
However, if we assume that irradiance does not vary in time it simplifies to FE = Δt × ∫λ = λ1λ = λ2E(λ) dλ where Δt = t2 − t1.
The equivalent equation for photon fluence is FQ = Δt × ∫λ = λ1λ = λ2Q(λ) dλ
Spectrally weighted (or effective) energy fluence is the integral over wavelengths and time of the result of the convolution of spectral energy irradiance by a spectral weight function w(λ). Assuming that spectral irradiance does not vary with time the corresponding equation is
FEBE = Δt × ∫λ = λ1λ = λ2E(λ) × wE(λ) dλ
Spectrally weighted (or effective) photon fluence can be computed similarly with the corresponding weighting function wQ(λ).
The calculation of fluence values (time-integrated irradiance) is
identical to that for irradiance, except that a
exposure.time
argument needs to be supplied. The exposure
time must be a lubridate::duration
, but any argument
accepted by as.duration
can also be used. Functions
fluence
, e_fluence
and q_fluence
correspond to irrad
, e_irrad
and
q_irrad
,
## E_Total
## 968849.6
## attr(,"radiation.unit")
## [1] "energy fluence (J m-2)"
## attr(,"exposure.duration")
## [1] "3600s (~1 hours)"
or
## converting 'time.unit' 3600 into a lubridate::duration
## E_Total
## 968849.6
## attr(,"radiation.unit")
## [1] "energy fluence (J m-2)"
## attr(,"exposure.duration")
## [1] 3600
and, to obtain the photon fluence for a range of wavelengths, in the
example, photosynthetically active radiation, we use the
PAR.wb
waveband object earlier defined, and integrate for
25 minutes of exposure.
## Q_PAR
## 1.341222
## attr(,"radiation.unit")
## [1] "photon fluence (mol m-2)"
## attr(,"exposure.duration")
## [1] "1500s (~25 minutes)"
A way to summarize the “colour” of light is to compute a ratio between irradiances computed for two different wavebands of the same spectrum. They can be computed either on an energy or photon (quantum) basis, and although not a requirement, use of two wavelength bands with the same expanse is usually most informative. Photon ratios are usually preferred compared to energy ratios in work related to photobiology and photochemistry.
$$Q_1 : Q_2 = \frac{\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} Q(\lambda)\ \mathrm{d}\lambda} {\int_{\lambda = \lambda_3}^{\lambda = \lambda_4} Q(\lambda)\ \mathrm{d}\lambda}$$
where λ1 ≥ λ > λ2 defines the waveband for the numerator and λ3 ≥ λ > λ4 defines the waveband for the denominator, i.e., two ranges of wavelengths.
Energy ratios are computed similarly
$$E_1 : E_2 = \frac{\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda)\ \mathrm{d}\lambda} {\int_{\lambda = \lambda_3}^{\lambda = \lambda_4} E(\lambda)\ \mathrm{d}\lambda}$$
where λ1 ≥ λ > λ2 defines the waveband for the numerator and λ3 ≥ λ > λ4 defines the waveband for the denominator, i.e., two ranges of wavelengths.
An energy irradiance to photon irradiance ratio describes the average energy per mol of photon for a waveband or range of wavelengths.
$$E : Q = \frac{\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} E(\lambda)\ \mathrm{d}\lambda} {\int_{\lambda = \lambda_1}^{\lambda = \lambda_2} Q(\lambda)\ \mathrm{d}\lambda}$$
where λ1 ≥ λ > λ2 defines a waveband, or range of wavelengths.
We can compute the photon to energy ratio (Q : E) similarly.
Although all these ratios are usually computed without use of spectral weighting functions, their computation can be easily done by including in the equations above a weighting functions (w(λ)) as described in the section on irradiance.
The functions described here, in there simplest use, calculate a
ratio between two wavebands. The function q_ratio
returning
photon ratios. However both waveband parameters can take lists of
wavebands as arguments, with normal recycling rules in effect. The
corresponding function e_ratio
returns energy ratios.
A single ratio.
## UVB:PAR[q:q]
## 0.001873724
## attr(,"radiation.unit")
## [1] "q:q ratio"
If no waveband is passed as numerator, the whole spectrum is used. The waveband fully outside the wavelength range of the spectrum is dropped silently.
## UVB:Total[q:q] UVA:Total[q:q]
## 0.001334593 0.067567343
## attr(,"radiation.unit")
## [1] "q:q ratio"
Three denominators (one skipped) and a single denominator.
## UVB:PAR[q:q] UVA:PAR[q:q]
## 0.001873724 0.094862270
## attr(,"radiation.unit")
## [1] "q:q ratio"
Function qe_ratio
, has only one waveband parameter, and
returns the photon to energy ratio, while its
complement eq_ratio
returns the energy to
photon ratio. Here we show how parameters
scale.factor
and name.tag
make scaling the
returned value easy.
## UV-B (umol/J) PAR (umol/J)
## 2.599472 4.547266
## attr(,"radiation.unit")
## [1] "q:e ratio"
As other summary methods, q_ratio()
,
e_ratio()
, qe_ratio()
and
eq_ratio()
when applied to a collection of spectra, they
return a data frame.
## # A tibble: 3 × 3
## spct.idx `UVB:PAR[q:q]` `UVA:PAR[q:q]`
## <fct> <dbl> <dbl>
## 1 none 0.00187 0.0949
## 2 pet 0.0000720 0.0853
## 3 yellow 0.00000395 0.000194
Additional parameters allow the scaling and customized column names possible.
q_ratio(filtered_sun,
list(UVB.wb, UVA.wb),
PAR.wb,
scale.factor = 100,
name.tag = " (% photons)",
idx = "Filter")
## # A tibble: 3 × 3
## Filter `UVB:PAR (% photons)` `UVA:PAR (% photons)`
## <fct> <dbl> <dbl>
## 1 none 0.187 9.49
## 2 pet 0.00720 8.53
## 3 yellow 0.000395 0.0194
Given the laws of conservation of energy, transmittance, reflectance and absorptance, expressed as fractions, always add up to one.
1 = Rfr, total + Afr, total + Tfr, total Transmittance can be defined either as the fraction of the radiation “entering” an object that is transmitted, called internal transmittance (Tfr, internal) or as the fraction of the ration incident on an object that is transmitted (Tfr, total).
1 × Rfr, total = Afr, internal + Tfr, internal giving
Tfr, internal = Tfr, total/Rfr, total and Afr, internal = Tfr, total/Rfr, total In the case of reflectance, “total” has a different meaning, and refers to whether all reflected light or that an specific angle in considered.
In practice, both definitions of transmittance and absorptance are in use, while as it is easier to measure total- than internal transmittance, internal transmittance allows the computation of transmittance for different thickness of a material.
Consequently, absorptance can be computed as:
Afr, internal = 1 − Tfr, internal or as
Afr, total = 1 − Tfr, total − Rfr, total Absorbance, is a log transformed quantity that tends to be used when the range of values spans several orders of magnitude. It is frequently based on internal absorptance, but can be also based on total absorptance.
Ainternal = −log10(1 − Afr, internal) = −log10(Tfr, internal) and
Atotal = −log10(1 − Afr, total) = −log10(Tfr, total + Rfr, total) When using a spectrophotometer, if our reference is a cuvette with pure solvent and the sample a solution of a compound in the same solvent we measure internal transmittance, absorptance or absorbance. If we instead measure the transmittance of a piece of glass or plastic with air as reference, we measure total transmittance, absorptance or absorbance. This is so because in the first case the reference is the light transmitted after the reflectance on the cuvette walls has taken place while in the second case the reflections at the glass-air interfaces are missing from the reference.
As a result of these different definitions, the implementation of the
class filter_spct()
and object_spct
and their
methods, need to keep track of whether quantities are expressed as
internal or total. As in many glasses reflectance varies very weakly
with wavelength, storing a constant value for Rfr, total is also
supported. The refractive index of a material can also be used to
estimate Rfr, total
for a polished surface. Lack of a value for Rfr, total can make some
conversions and computations impossible.
The functions transmittance
, absorptance
and absorbance
take filter_spct
as argument,
while function reflectance
takes
reflector_spct
objects as argument. Functions
transmittance
, reflectance
and
absorptance
are also implemented for
object_spct
. These functions return as default an average
value for these quantities assuming a light source with
a flat spectral energy output, but this can be changed as described
above for irrad()
.
## Tfr(wl)_UVB Tfr(wl)_UVA Tfr(wl)_PAR
## 0.009730612 0.781851261 0.920241429
## attr(,"Tfr.type")
## [1] "total"
## attr(,"radiation.unit")
## [1] "transmittance average"
We can obtain numerical values without names if needed,
## [1] 0.009730612 0.781851261 0.920241429
## attr(,"Tfr.type")
## [1] "total"
## attr(,"radiation.unit")
## [1] "transmittance average"
or named only according to the wavebands.
## UVB UVA PAR
## 0.009730612 0.781851261 0.920241429
## attr(,"Tfr.type")
## [1] "total"
## attr(,"radiation.unit")
## [1] "transmittance average"
The reflectance of a leaf.
## Rfr(wl)_range.600.700
## 0.089647
## attr(,"Rfr.type")
## [1] "total"
## attr(,"radiation.unit")
## [1] "reflectance average"
Here we calculate the transmittance of a collection of spectra for
three filters in two wavebands, obtaining the results as a data frame,
with one row per filter, and one column per waveband. We reuse once more
filters.mspct
from an earlier section.
Column names formed from quantity abbreviation and label in waveband definitions.
## # A tibble: 3 × 3
## spct.idx `Tfr(wl)_UVA` `Tfr(wl)_PAR`
## <fct> <dbl> <dbl>
## 1 none 1.00 1.00
## 2 pet 0.782 0.920
## 3 yellow 0.00159 0.566
With naming = "short"
column names are the labels of
waveband definitions.
## # A tibble: 3 × 3
## spct.idx UVA PAR
## <fct> <dbl> <dbl>
## 1 none 1.00 1.00
## 2 pet 0.782 0.920
## 3 yellow 0.00159 0.566
If list members are named, column names are formed from quantity abbreviation and name of list members, overriding the labels in the waveband definitions.
## # A tibble: 3 × 3
## spct.idx `Tfr(wl)_UV-A` `Tfr(wl)_PAR`
## <fct> <dbl> <dbl>
## 1 none 1.00 1.00
## 2 pet 0.782 0.920
## 3 yellow 0.00159 0.566
If list members are named, with naming = "short"
column
names are the names of list members.
## # A tibble: 3 × 3
## spct.idx UVA PAR
## <fct> <dbl> <dbl>
## 1 none 1.00 1.00
## 2 pet 0.782 0.920
## 3 yellow 0.00159 0.566
We can add metadata attributes as columns, changing the name if desired.
transmittance(filters.mspct,
w.band = UVA.wb,
naming = "short",
attr2tb = c("what.measured" = "Filter type"))
## # A tibble: 3 × 3
## spct.idx UVA `Filter type`
## <fct> <dbl> <chr>
## 1 none 1.00 theoretical fully transparent object
## 2 pet 0.782 Polyester, clear film, 0.000125 m thick, Autostat CT5 from M…
## 3 yellow 0.00159 Theatrical 'gel', type 'Canary Supergel no312; new; from Ros…
We can add metadata attributes as a column, and select and rearrange the columns.
## # A tibble: 3 × 2
## what.measured `Tfr(wl)_UVA`
## <chr> <dbl>
## 1 theoretical fully transparent object 1.00
## 2 Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDe… 0.782
## 3 Theatrical 'gel', type 'Canary Supergel no312; new; from Rosco,… 0.00159
Like the ratios discussed above normalized differences are a way of summarizing or describing the colour of light sources or objects independently of the overall irradiance. As their name tells, they are defined as differences relative to a sum.
Normalized difference indexes are used to summarize the spectral characteristics of light or objects. They are most frequently used in the analysis of spectral reflectance data in remote sensing.
$$NDI_{a, b} = \frac{R_a - R_b}{R_a + R_b}$$
where Ra and Rb are reflectances computed from the same spectrum using two different wavebands.
The most frequently used NDI is the NDVI or normalized difference vegetation index, which compares reflectance in the red and far-red regions as a way of assessing the presence of vegetation vs. bare land in remote sensing imagery.
However, they can be computed based on energy or photon irradiances for two wavebands as shown here, or for any other spectral quantity.
$$NDI_{a, b} = \frac{Q_a - Q_b}{Q_a + Q_b}$$
where Qa and Qb are irradiances computed from the same spectrum using two different wavebands.
Although we here describe how to compute normalized difference indexes from spectral data, they are most frequently generated from data from broad-band sensors in satellite, air-borne or terrestrial imagers. To reconstruct from spectral data indexes computed from these instruments we need to use waveband definitions that mimic the spectral response of the imager of interest. Package ‘photobiologyWavebands’ provides pre-defined wavebands for several different satellite imagers as well as for wavelength ranges in common use.
Here we give an example of a possible definition of NDVI using
function normalized_diff_ind()
can be used to calculate, or
any index with a similar formulation structure.
## NDI reflectance [740.840] - [590.690]
## 0.7653852
Here we give an unusual example to demonstrate that function
normalized_diff_ind()
can be used to calculate any index
with a similar formulation structure and using other spectral quantities
and summary functions.
## NDI q_irrad [600.700] - [400.500]
## 0.09188363
As with other spectral quantities, we can integrate over wavelengths spectral responsiveness. In response and action spectra the quantity is a response measured in some arbitrary unit expressed per unit wavelengths and per unit energy or quantum.
XE = ∫λ = λ1λ = λ2XE(λ) dλ where λ1 ≥ λ > λ2 defines a waveband, or range of wavelengths.
The conversion between energy and photon (= quantum) basis of expression is possible as it is for radiation spectra. Depending on the base of expression the returned integrated value is computed assuming either a light source with a flat spectral energy irradiance of 1 or spectral photon irradiance of 1, respectively.
The functions response
, e_response
and
q_response
take response_spct
objects as
arguments. If no waveband is supplied as argument, the whole spectrum is
integrated.
## R[/e]_Total
## 24.40478
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"
When a waveband, or list of wavebands, is supplied the response is calculated for the wavebands.
## R[/e]_]UVB R[/e]_UVA
## 0.346462 5.981818
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "total energy response"
This function has an additional argument quantity
, with
default "total"
, as described for irrad()
.
sensors <- response_mspct(list(GaAsP = photodiode.spct,
CCD = ccd.spct))
response(sensors, list(UVB.wb, UVA.wb, PAR.wb), quantity = "contribution")
## # A tibble: 2 × 4
## spct.idx `R/Rtot[/e]_]UVB` `R/Rtot[/e]_UVA` `R/Rtot[/e]_PAR[`
## <fct> <dbl> <dbl> <dbl>
## 1 GaAsP 0.0142 0.245 0.741
## 2 CCD 0.0215 0.0634 0.411
When we need to integrate some numeric
variable stored
in a spectral object we can use functions integrate_spct
or
average_spct
.
We can integrate the values of arbitrary numeric
columns
other than w.length
in an spectral object. All spectral
classes are derived from generic_spct
, so the examples in
this section apply to objects of any of the derived spectral classes as
well.
## e.irrad q.irrad
## 2.691249e+02 1.255354e-03
The function average_spct
integrates every column
holding numeric values from a spectrum object, except for
w.length
, and divides the result by the spread or
width of the wavelength range integrated, returning a value expressed in
the same units as the spectral data.
## e.irrad q.irrad
## 5.175479e-01 2.414142e-06
Comparison of spectra for which data is expressed at different
discrete wavelength values can be easily affected by bias if
interpolation is used. Function compare_spct()
does a
coarse grained comparison by first summarizing each spectrum over
consecutive ranges of wavelengths, and then applying a comparison
function to these summary values.
The function can be used to compare pairs of spectra, stored as a
collection. In the next example we compare two source_spct
objects using defaults for most arguments.
## Object: generic_spct [52 x 6]
## Wavelength range 285-795 nm, step 10 nm
## Variables:
##
## --
## # A tibble: 52 × 6
## w.length wl.min wl.max sun1.irrad sun2.irrad comparison.result
## <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
## 1 285 280 290 0 0 NaN
## 2 295 290 300 0.00204 0.00407 2
## 3 305 300 310 0.203 0.406 2
## 4 315 310 320 1.13 2.26 2
## # ℹ 48 more rows
The value returned by default is a generic_spct
object
containing the computed summaries for each waveband plus the result of
the comparison between the summaries. The first three columns contain
the wavelength at the midpoint of the wavelength range of waveband plus
its extremes.
In this example we compare two filter_spct
objects,
using summaries over 50-nm-wide bands, and using an operator returning a
logical value for the comparison instead of the default division
operator.
compare_spct(filter_mspct(list(pet = polyester.spct,
yllw = yellow_gel.spct)),
w.band = 50,
.comparison.fun = `<`)
## Object: generic_spct [11 x 6]
## Wavelength range 265-765 nm, step 50 nm
## Variables:
##
## --
## # A tibble: 11 × 6
## w.length wl.min wl.max pet.transmittance yllw.transmittance comparison.result
## <dbl> <dbl> <dbl> <dbl> <dbl> <lgl>
## 1 265 240 290 0.00385 0.0000100 TRUE
## 2 315 290 340 0.292 0.00219 TRUE
## 3 365 340 390 0.861 0.000821 TRUE
## 4 415 390 440 0.918 0.0000100 TRUE
## # ℹ 7 more rows
Illuminance, or luminous flux incident on a surface, is relevant to human vision. It is an approximate quantity as the spectral response function of human vision varies among individuals, with their age and the conditions during measurement. The SI unit for illuminance is lux (lx) or lumnes per square meter.
When function illuminance()
is applied to spectral
(energy) irradiance or spectral photon irradiance, illuminance can be
directly computed using the same time base of 1 s.
## Ev[lx]
## 52191.33
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "scaled illuminance [lx]; CIE2deg"
The response of the human eye depends on the size of the target, and response spectra have been defined by CIE for both 2 degrees and 10 degrees targets.
## Ev[lx]
## 55066.41
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "scaled illuminance [lx]; CIE10deg"
If one attempts to compute illuminance from spectral fluence or radiation spectra expressed as a flux of energy or photons over a period of time different to 1 s, the average illuminance is returned, in lux.
## Ev[lx]
## 24475.59
## attr(,"time.unit")
## [1] "second"
## attr(,"radiation.unit")
## [1] "mean illuminance [lx]; CIE2deg"
Colour temperature and colour rendition index can be computed from
spectral irradiance. Package ‘colorSpec’ implement these and other
calcualtions related to colour. Package ‘photobiologyInOut’ provides
wrappers to facilitate the computation of CCT and CRI directly from
source_spct
objects by on-the-fly conversion and calling
functions from ‘colorSpec’.
Different color_of()
methods allow calculation of RGB
colour values for light sources or objects. The returned values are R
colour definitions. Method color_of()
works rather
differently depending on the object. The method for numeric
vectors assumes the numbers are wavelengths in nanometres, and returns a
vector of colour definitions of the same length assuming monochromatic
light.
## wl.550.nm.CMF
## "#00FF00"
## wl.630.nm.CMF
## "#FF0000"
## wl.550.nm.CMF wl.630.nm.CMF wl.380.nm.CMF wl.750.nm.CMF
## "#00FF00" "#FF0000" "#000000" "#000000"
The method for source_spct
objects returns a single
colour definition corresponding to the whole spectrum of a light
sources.
## source.CMF
## "#544F4B"
## source.CMF
## "#946000"
There are no methods for filter_spct
and
reflector_spct
objects so as shown above we need to
convolve them with spectral irradiance from a source_spct
object.
The method for waveband
objects returns one colour
definition per waveband, corresponding to their central wavelength.
## my_BL.CMF
## "#000EFF"
By default CIE coordinates for typical human vision are
used, but the functions have a parameter that can be used for supplying
a different chromaticity definition as a chroma_spct
object.
## source.CC
## "#B63C37"
## source.CMF
## "#544F4B"
## source.chroma
## "#CD1F11"
In the case of bees, the RGB values represent a shift towards longer wavelengths compared to the true sensitivity. In other words, they are translated into colours that humans can see and monitors and printers can generate.