Acquire spectral fraction

Interactive front-end allowing acquisition of spectral fractions using Ocean Optics spectrometers. Output of spectral data in R data files stored in objects suitable for use with packages 'photobiology' and 'ggspectra' as well as plots as PDF files and summaries as comma separated files.

Usage

acq_fraction_interactive(
  tot.time.range = c(5, 15),
  target.margin = 0.1,
  HDR.mult = if (light.source == "pulsed") c(short = 1) else c(short = 1, long = 10),
  protocols = NULL,
  correction.method = NA,
  descriptors = NA,
  stray.light.method = "simple",
  seq.settings = NULL,
  light.source = "continuous",
  ref.value = 1,
  qty.out = "Tfr",
  type = "total",
  plot.lines.max = 11,
  summary.type = "VIS",
  save.pdfs = TRUE,
  save.summaries = !interface.mode %in% c("series", "series-attr"),
  save.collections = !interface.mode %in% c("simple", "series", "series-attr"),
  async.saves = FALSE,
  show.figs = TRUE,
  interface.mode = ifelse(light.source == "pulsed", "manual", "auto"),
  num.exposures = ifelse(light.source == "pulsed", 1L, -1L),
  f.trigger.init = NULL,
  f.trigger.on = f.trigger.message,
  f.trigger.off = NULL,
  triggers.enabled = c("sample", "reference"),
  folder.name = paste("acq", qty.out, lubridate::today(tzone = "UTC"), sep = "-"),
  user.name = Sys.info()[["user"]],
  session.name = paste(user.name, strftime(lubridate::now(tzone = "UTC"),
    "%Y.%b.%d_%H.%M.%S"), sep = "_"),
  verbose = getOption("photobiology.verbose", default = FALSE),
  QC.enabled = TRUE
)

Arguments

tot.time.range: numeric vector Range of total times for a measurement in seconds.
target.margin: numeric (0..1) when tuning integration time, how big a head space to leave.
HDR.mult: numeric the integration time for each bracketed integration as a multiplier of the set or tuned integration time.
protocols: named list of character vectors, or a character vector with names of at least one member of the default list of protocols.
correction.method: list The method to use when applying the calibration
descriptors: list A list of instrument descriptors containing calibration data.
stray.light.method: character Used only when the correction method is created on-the-fly.
seq.settings: named list with numeric members start.boundary, initial.delay, "step.delay" and "num.steps".
light.source: character One of "continuous", "pulsed".
ref.value: numeric or filter_spct/reflector_spct object.
qty.out: character One of "Tfr" (spectral transmittance as a fraction of one), "cps" (counts per second), or "raw" (raw sensor counts).
type: character Type of transmittance or reflectance measured.
plot.lines.max: integer Maximum number of spectra to plot as individual lines. Random sampling is used if number of spectra exceeds plot.lines.max.
summary.type: character One of "plant", "PAR" or "VIS".
save.pdfs, save.summaries, save.collections: logical Whether to save plots to PDFs files or not, and collection summaries to csv files or not, enable collections user interface or not.
async.saves: logical A flag enabling or disabling the use of concurrent processes to save data to files. Package 'mirai' must be installed before enabling this feature.
show.figs: logical Default for flag enabling display plots of acquired spectra.
interface.mode: character One of "auto", "simple", "manual", "full", "series", "auto-attr", "simple-attr", "manual-attr", "full-atr", and "series-attr".
num.exposures: integer Number or light pulses (flashes) per scan. Set to -1L to indicate that the light source is continuous.
f.trigger.on, f.trigger.off, f.trigger.init: function Functions to be called immediately before and immediately after a measurement, and any initialization code needed before a repeat. See acq_raw_spct for details.
triggers.enabled: character vector Names of protocol steps during which trigger functions should be called.
folder.name, session.name, user.name: character Default name of the folder used for output, and session and user names.
verbose: logical If TRUE additional messages are emitted, including report on memory usage.
QC.enabled: logical If FALSE return NA skipping QC.

Value

These functions return the acquired spectra through "side effects" as each spectrum is saved, both as raw counts data and optionally as spectral transmittance or counts-per-second data in an .rda file as objects of the classes defined in package 'photobiology'. Optionally, the plot for each spectrum is saved as a .pdf file. At any time, the current group of spectra can be saved as a collection. When a collection is created, spectral data for several spectra are saved together. Summaries are saved to a CSV file and joint plots to a .pdf file. The value returned by the function is that from closing the connection to the spectrometer.

Details

This function can be used to acquire spectral reflectance, spectral transmittance and/or spectral absorptance using different protocols for acquisition and stray light and dark corrections. Depending on the optical setup, solid or liquid samples can be measured. The kinetics of changes in optical properties can be captured as a time series of spectra, using `interface.mode = "series"`.

The protocols are described in the vignettes and in the help for the lower level functions called, also from this same package.

Using this function only requires an Ocean Optics spectrometer to be connected to the computer where R is running and the OmniDriver runtime from Ocean Insight installed. The connection to the spectrometer and selection of channel, when relevant, is done from within these functions. A stable and continuous source of light is also needed as well as black, white and possibly grey reflectance patches.

The calculations for reflectance and transmittance are very similar, so we provide a single function capable of handling both. For transmittance the reference is usually direct exposure to radiation but for reflectance a white reference patch is normally used. In some cases one may want to use a grey reference. We provide an argument that allows the user to supply a constant or a spectrum describing the properties of the reference. It is also important to distinguish between total and internal transmittance, and between total and specular reflectance. In both cases which of these is measured depends on the measuring protocol (condition used as reference, use of an integrating sphere versus use of a probe with a narrow angle of aperture, etc.) and consequently the correct value should be entered to ensure that data are correctly tagged and later computations valid.

A wavelength calibration is needed, but being the measurements relative, no calibration of pixel responsiveness is required. A known linearization function is also needed.

Some protocols are available by default. They differ in the additional measurements done to correct for stray light and dark noise. The default protocols are usually suitable, if new protocols are passed, each character vector must contain strings "light", "filter" and "dark".

By default the integration time is set automatically so that the number of counts at the highest peak is close to 1 - target.margin times the maximum of the range of the instrument detector (retrieved from the calibration or the instrument memory). The minimum tot.time is obtained by increasing the number of scans. The maximum integration time supported by the spectrometer is not exceeded.

Plots are produced with functions from package 'ggspectra' and respect the default annotations set with function set_annotations_default(), and default wavebands set with function set_w.band_default().

The different interface modes available are suitable for different types of measurements.

Note

Calibration data needs in most cases to be imported into R and parameters entered for the special correction algorithms into a correction method descriptor. The corrections are skipped if the needed information is missing. If no wavelength calibration is available and attempt is made to retrieve it from the spectrometer.

The function is composed in a modular way from functions that can be reshuffled and combined with other functions to define new variations possibly better suited to users' needs and tastes. Even easier is to simply change the default arguments in a wrapper function or in a script.

Examples

# please, see also the example scripts installed with the package

if (FALSE) { # \dontrun{
# requires an Ocean Insight (former Ocean Optics) spectrometer to be
# connected via USB

acq_fraction_interactive()

} # }