photobiologyInOut (version 0.4.29)

read_cid_spectravue_csv: Read File Saved by CID's SpectraVue.

Description

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

Value

An object of class filter_spct, relector_spct,

object_spct or generic_mspct.

Arguments

file

character

date

a POSIXct object to use to set the "when.measured" attribute. If NULL, the default, the date and time are extracted from the file.

geocode

A data frame with columns lon and lat used to set attribute "where.measured". If NULL, the default, the geocode is extracted from the file, if present, and if NA 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 if NA 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.

Internal <em>vs.</em> 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 <em>vs.</em> 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.

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

References

https://cid-inc.com/

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)
 summary(cid_filter.spct)

 cid_filter.spct <-
   read_cid_spectravue_csv(file = file.name, simplify = FALSE)
 summary(cid_filter.spct)

 # 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)
 summary(cid.object_spct)

 cid_A.filter_spct <-
   read_cid_spectravue_csv(file = file.name, absorbance.to = "A")
 summary(cid_A.filter_spct)