Read wavelength and spectral data from Measurements.CSV files exported from
CID Bio-Sciences' SpectraVue CI-710s (not the older CI-710!) leaf
spectrometer, importing them into R. Available metadata is also extracted
from the file. read_cid_spectravue_csv()
only accepts "row oriented"
CSV files. These may contain multiple spectra, one per row.
Usage
read_cid_spectravue_csv(
file,
date = NULL,
geocode = NULL,
label = NULL,
tz = NULL,
locale = readr::default_locale(),
range = c(380, 1100),
simplify = TRUE,
absorbance.to = "object",
strict.range = NA,
...
)
Arguments
- file
character
- date
a
POSIXct
object to use to set the"when.measured"
attribute. IfNULL
, the default, the date and time are extracted from the file.- geocode
A data frame with columns
lon
andlat
used to set attribute"where.measured"
. IfNULL
, the default, the geocode is extracted from the file, if present, and ifNA
the "where.measured" attribute is not set.- label
character string. If
NULL
, the default, the value of the "tag" present in the file is used, and ifNA
the "what.measured" attribute is not set.- tz
character Time zone is by default that of the machine's locale.
- locale
The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use
locale
to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.- range
numeric A vector of length two, or any other object for which function
range()
will return range of wavelengths expressed in nanometres.- simplify
logical If TRUE, single spectra are returned as individual spectra instead of collections of length one.
- absorbance.to
character Affects only absorbance measurements:
"object"
,"all"
or"A"
.- strict.range
logical Flag indicating whether off-range values result in an error (
TRUE
) instead of a warning (FALSE
), or the test is disabled (NA
).- ...
additional arguments passed to the constructor of the `filter_spct` object.
Details
SpectraVue's row-wise spectral Measurements.CSV
files contain
columns with metadata on the right edge, followed by columns with data for
each of the 2048 pixels or wavelengths. The value in column "Mode"
indicates the quantity measured, decoded into variables Tpc
,
Rpc
or A
. The data the rows in the CSV file are read and
stored in filter_spct
, reflector_spct
or object_spct
objects. These objects are collected into a single filter_mspct
,
reflector_mspct
, object_mspct
or generic_spct
object
and returned.
Spectral data outside the range 400 nm to 1000 nm are very noisy and thus
outside the valid range for the measurements. Out-of-range spectral data
can also be cause by calibration drift. Consequently, reading of data is
done always with the range check disabled, while whether a check is used
before returning the collection of spectra depends on the argument passed
to strict.range
which by default is set to disable checks. This is
done, because in most cases measurements from this instrument tend to
require further processing before they comply with theoretical expectations
of \(Tfr + Rfr + Afr = 1\).
Note
SpectraVue creates three or four .CSV
files for each series of
measurements saved. Of these files, this function reads the one with name
ending in Measurements.CSV
. The first part of the file name gives
the time of the session, but as the files can contain multiple spectra
measured at different times, the time metadata is extracted separately for
each spectrum. We provide a default argument for range
that discards
data for short and long wavelengths because values outside this range are
according to the instrument's manual outside the usable range and in
practice extremely noisy.
Internal vs. total transmittance and absorbance
Spectravue
returns transmittance values labelled with Transmittance
as
Mode
. Transmittance values are not total as most of the
scattered light transmitted is not detected. Absorbance (Abs
) values
returned labelled with Absorbance
as Mode
are for absorbance
computed from the Transmittance. This estimate of absorbance overestimates
real absorbance in the case of scattering materials like plant leaves. It
is best to save spectral data acquired as absorbance into objects of class
`object_spct` containing reflectance and transmittance, the default, as
this preserves all the acquired data.
Specular vs. total reflectance
This function assumes that SpectraVue returns close to total reflectance readings. Given the optics of the instrument this is likely only an approximation.
Warning!!
CID's support has answered on 2022-05-19 that the extremely biased (plainly wrong!) values of transmittance measured by this instrument are due to a design flaw and that they are working on a solution for the problem. In practice, reflectance seems biased but usable as an instrument-specific quantity with arbitrary units. Transmittance and absorbance seem useless as values are wrong by about an order of magnitude.
Examples
# read file containing a single reflectaance spectrum
file.name <-
system.file("extdata", "cid-spectravue-Rpc-Measurements.csv",
package = "photobiologyInOut", mustWork = TRUE)
cid_filter.spct <-
read_cid_spectravue_csv(file = file.name)
#> Found 9/2048 off-range 'Rfr' values [0.00..32.42] instead of [0..1]
summary(cid_filter.spct)
#> Summary of reflector_spct [1,235 x 2] object: cid_filter.spct
#> Wavelength range 380.30945-1099.8846 nm, step 0.5594482-0.6019592 nm
#> Label: Reflectance.
#> Measured on 2022-03-08 15:02:47 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> Rfr: Total spectral reflectance [/1]
#> --
#> w.length Rfr
#> Min. : 380.3 Min. :0.0258
#> 1st Qu.: 564.8 1st Qu.:0.2392
#> Median : 746.7 Median :0.4474
#> Mean : 744.5 Mean :0.3626
#> 3rd Qu.: 925.2 3rd Qu.:0.4935
#> Max. :1099.9 Max. :0.5188
cid_filter.spct <-
read_cid_spectravue_csv(file = file.name, simplify = FALSE)
#> Found 9/2048 off-range 'Rfr' values [0.00..32.42] instead of [0..1]
summary(cid_filter.spct)
#> Summary of reflector_mspct [1 x 1] object: cid_filter.spct
#> # A tibble: 1 × 8
#> spct.idx class dim w.length.min w.length.max colnames multiple.wl Rfr.type
#> <chr> <chr> <chr> <dbl> <dbl> <list> <dbl> <chr>
#> 1 Reflectan… refl… [1,2… 380. 1100. <chr> 1 total
# read data measured as absorbance (A, Rpc and Tpc)
file.name <-
system.file("extdata", "cid-spectravue-Abs-Measurements.csv",
package = "photobiologyInOut", mustWork = TRUE)
cid.object_spct <-
read_cid_spectravue_csv(file = file.name)
#> Found 9/2048 off-range 'Rfr' values [0.00..40.93] instead of [0..1]
summary(cid.object_spct)
#> Summary of object_spct [1,235 x 3] object: cid.object_spct
#> Wavelength range 380.30945-1099.8846 nm, step 0.5594482-0.6019592 nm
#> Label: Abs.Transmittance.1086
#> Measured on 2022-03-11 17:18:08 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> Rfr: Total spectral reflectance [/1]
#> Tfr: Total spectral transmittance [/1]
#> --
#> w.length Rfr Tfr
#> Min. : 380.3 Min. :0.0000 Min. :0.0003785
#> 1st Qu.: 564.8 1st Qu.:0.1353 1st Qu.:0.0074655
#> Median : 746.7 Median :0.4305 Median :0.0287249
#> Mean : 744.5 Mean :0.3155 Mean :0.0213317
#> 3rd Qu.: 925.2 3rd Qu.:0.4729 3rd Qu.:0.0327627
#> Max. :1099.9 Max. :0.5225 Max. :0.0434706
cid_A.filter_spct <-
read_cid_spectravue_csv(file = file.name, absorbance.to = "A")
summary(cid_A.filter_spct)
#> Summary of filter_spct [1,235 x 2] object: cid_A.filter_spct
#> Wavelength range 380.30945-1099.8846 nm, step 0.5594482-0.6019592 nm
#> Label: Abs.Transmittance.1086
#> Measured on 2022-03-11 17:18:08 UTC
#> Variables:
#> w.length: Wavelength [nm]
#> A: Spectral absorbance log10 based [a.u.]
#> --
#> w.length A
#> Min. : 380.3 Min. :0.2490
#> 1st Qu.: 564.8 1st Qu.:0.2970
#> Median : 746.7 Median :0.3340
#> Mean : 744.5 Mean :0.5874
#> 3rd Qu.: 925.2 3rd Qu.:0.8448
#> Max. :1099.9 Max. :2.8014