Compute spectral irradiance update

Compute spectral irradiance using the instrument descriptor for the same spectrometer and date of measurement from the current version of 'ooacquire' rather than that available at the time when raw data were acquired.

Usage

s_irrad_update(
  x,
  y = NULL,
  spct.names = find_spct_names(x),
  correction.method = NULL,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = NULL,
  trim.descriptor = NULL,
  which = NULL,
  which.not = NULL,
  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.
y: source_spct Object containing spectral irradiance earlier computed from the same raw_mspct object as passed to x.
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.
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.
which, which.not: character Names of attributes to copy or not to copy.
verbose: logical Enable informative messages.

Value

A source_spct or a cps_spct object.

Details

When raw counts data are acquired with acq_irrad_interactive() or imported from text files from other software the calibration information is stored together with the data. When computing spectral irradiance with function s_irrad_corrected() at any later time, this stored calibration data are the ones used. This approach ensures reproducibility as calibrations can be, and have been, retrospectively modified when 'ooacquire' is updated. In most cases the updates have only added information about "hot" and "dead" pixels. However, in one case the range of the calibration data included was incomplete, and later expanded. These changes can be important in some cases, making it necessary or preferable to use the updated calibrations when computing spectral irradiance.

In s_irrad_update() the instr.desc attribute in x is matched based on spectrometer serial number, date and entrance optics to the possibly updated version of the same calibration data in the current version of 'ooacquire'. The instrument descriptor is replaced in a local copy of x and this local copy used to compute spectral irradiance with s_irrad_corrected(), without altering x. Explicit arguments passed to parameters in the call to s_irrad_update() are used in the call to s_irrad_corrected(), however, defaults are in some cases different.

If an argument is passed to parameter y and the value of the spectrometer serial number attributes match between x and y, default arguments for return.cps and correction.method are based on metadata from y. In this case attributes unrelated to to those in the raw data or their conversion, possibly added or modified after y was computed, are copied to the returned source_spct object using method copy_attributes() passing which and which.not in the call. This creates, as close as possible an updated version of y. Attributes "instr.desc", "instr.settings", "when.measured" and several others set by s_irrad_corrected() are never updated in the returned value to ensure they remain valid. Other attributes including "what.measured", "where.measured", "how.measured", "comment", are copied by default. If names are passed in an argument to which only these attributes are copied, with user-set attributes allowed. However, exclusion of attributes named in the union of the argument passed to which.not and those not excluded by default takes precedence.

Note

Entrance optics metadata have been saved in the instrument descriptor only since 'ooacquire' (>= 0.5.3) and correction method only from 'ooacquire' (>= 0.5.6).

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


# only metadata from x and the new descriptor
s_irrad_update(x = white_grow_LED.raw_mspct)
#> Object: source_spct [1,423 x 2]
#> Wavelength range 250.21-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,423 × 2
#>    w.length  s.e.irrad
#>       <dbl>      <dbl>
#>  1     250. -0.0000342
#>  2     251.  0.000933 
#>  3     251.  0.00101  
#>  4     252.  0.00181  
#>  5     252.  0.000342 
#>  6     253.  0.00102  
#>  7     253.  0.000757 
#>  8     254.  0.000777 
#>  9     254   0.000750 
#> 10     254.  0.000939 
#> # ℹ 1,413 more rows