Convert raw counts data into spectral irradiance or fluence

Usage

s_irrad_corrected(x, ...)

# Default S3 method
s_irrad_corrected(x, ...)

# S3 method for class 'list'
s_irrad_corrected(
  x,
  time = NULL,
  correction.method = NULL,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = FALSE,
  trim.descriptor = !return.cps,
  descriptor,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

# S3 method for class 'raw_mspct'
s_irrad_corrected(
  x,
  spct.names = find_spct_names(x),
  correction.method = NULL,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = FALSE,
  trim.descriptor = !return.cps,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

# S3 method for class 'raw_spct'
s_irrad_corrected(
  x,
  time = NULL,
  correction.method,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = FALSE,
  trim.descriptor = !return.cps,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

Arguments

x: A named list of one to three vectors of file names, with names containing "light", "filter", and "dark". Or a raw_mspt or a raw_spct object with similarly named members, or with any name if a suitable mapping is passed through parameter spct.names.
...: Named arguments passed to photobiology::cps2irrad which is the final calculation step.
time: a POSIXct object, but if NULL the date stored in file is used, and if NA, date is set to NA.
correction.method: A named list of constants and functions defining the method to be used for stray light and dark signal corrections.
hdr.tolerance: numeric Tolerance for mean deviation among cps columns as a fraction of one. Used in check of HDR consistency. A negative value disables merging using only the data for the shortest integration time.
return.cps: logical Useful when there is no need to apply a calibration, such as when computing new calibration multipliers.
trim.descriptor: logical If TRUE the spectrometer calibration constants, pixel wavelengths, slit-function "tail-correction" function code and other calibration-related information is deleted.
descriptor: A named list with a descriptor of the characteristics of the spectrometer (if serial number does not agree an error is triggered).
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.
verbose: Logical indicating the level of warnings and messages wanted.
spct.names: named list of character vectors, with one, two or three members, named "light", "dark" and "filter", used to map names in x to the measuring protocol; for time series, "light" is a vector of length > 1, while "dark" and "filter" have always length = 1 if present.

Value

A source_spct or a cps_spct object.

Details

When raw data are acquired with function acq_irrad_interactive() the raw-counts are returned in an object of class raw_mspct. The embedded metadata include the wavelength calibration, irradiance calibration, and spectrometer settings used to acquire the data. The specialization s_irrad_corrected.raw_mspct() uses these metadata to compute spectral irradiance.

The specialization s_irrad_corrected.list allows processing of files written by Ocean Optics' SpectraSuite software. Some of the metadata can be extracted from file headers, but other, such as the calibration data cannot. Based on the date of data acquisition and instrument serial number a matching calibration is searched for and must be available.

Methods (by class)

s_irrad_corrected(default): Default for generic function.
s_irrad_corrected(list): Default for generic function.
s_irrad_corrected(raw_mspct): Default for generic function.
s_irrad_corrected(raw_spct): Default for generic function.

Computation of spectral irradiance

Method s_irrad_corrected() computes spectral irradiance from raw detector counts from an Ocean Optics spectrometer. Function s_irrad_update() calls s_irrad_corrected() on a copy of x with its calibration data updated.

Depending on both the calibration data and the raw-counts data available different corrections can be applied. Raw counts data can be acquired using different protocols, and which one was used limits what corrections are applicable. If return.cps = TRUE is passed, then counts-per-second are computed instead of irradiances, applying only the wavelength calibration.

The supported protocols include single-integration time and integration-time bracketing, a dark reference measurement or use of dark sensor pixels, and a filter measurement to correct for stray light in the UV region or not. A correction for the slit function is applied non-recursively if included in the calibration.

Three measurement events are recognized: a "light" measurement, a "filter" measurement using a polycarbonate filter and a dark measurement. Only the "light" measurement is mandatory. All three measurements should have been acquired with exactly the same settings in the spectrometer, with the same instrument, and close enough in time to avoid background signal drift due to temperature changes.

The returned object is by default a source_spct object as long as spectrometer calibration data are available, and a cps_spct object otherwise. It is possible to force the return of a cps_spct object.

Passing trim.descriptor = TRUE ensures that the data objects returned are significantly smaller in size as calibration data are removed. By default, the descriptor is trimmed when the returned object is a `source_spct` object and not trimmed when the returned object is a `cps_spct`.

Examples

s_irrad_corrected(x = white_grow_LED.raw_mspct)
#> Object: source_spct [1,421 x 2]
#> Wavelength range 251.16-898.81 nm, step 0.43-0.48 nm 
#> Label: light: Nichia.horticulture.5000K 
#> Measured on 2019-06-25 14:03:10.946064 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.00101 
#>  2     252.  0.00181 
#>  3     252.  0.000342
#>  4     253.  0.00102 
#>  5     253.  0.000757
#>  6     254.  0.000777
#>  7     254   0.000750
#>  8     254.  0.000939
#>  9     255.  0.00117 
#> 10     255.  0.00198 
#> # ℹ 1,411 more rows