Acquire spectral irradiance or spectral fluence

Interactive front-end allowing acquisition of spectral irradiance and spectral fluence 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 and R objects.

Usage

acq_irrad_interactive(
  tot.time.range = if (qty.out == "fluence") 5 else c(5, 15),
  target.margin = 0.1,
  HDR.mult = if (qty.out == "fluence") c(short = 1) else c(short = 1, long = 10),
  protocols = NULL,
  correction.method = NA,
  descriptors = NA,
  entrance.optics = NULL,
  stray.light.method = "none",
  seq.settings = NULL,
  area = NULL,
  diff.type = NULL,
  qty.out = "irrad",
  plot.lines.max = 11,
  summary.type = "plant",
  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,
  figs.theme = "built.in",
  interface.mode = ifelse(qty.out == "fluence", "manual", "auto"),
  num.exposures = ifelse(qty.out == "fluence", 1L, -1L),
  f.trigger.init = NA,
  f.trigger.on = ifelse(qty.out == "fluence", f.trigger.message, NA),
  f.trigger.off = NA,
  triggers.enabled = c("light", "filter"),
  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 = ""),
    "%Y_%m_%d.%H%M"), 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.
entrance.optics: character, name or geometry of diffuser, needed only if there is more than one for the same instrument.
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".
area: numeric Passed to o_calib2irrad_mult().
diff.type: character Passed to o_calib2irrad_mult().
qty.out: character One of "irrad" (spectral irradiance), "fluence" (spectral fluence), "cps" (counts per second), or "raw" (raw sensor counts).
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.
figs.theme: character One of "built.in", "ggplot2.current", or "current".
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

This function returns the acquired spectra through "side effects" as each spectrum is saved, both as raw counts data and optionally as spectral irradiance, spectral fluence or counts-per-second spectral data in an .rda (R data) file as objects of the classes defined in package 'photobiology'. Optionally, the plot for each spectrum or a time series of spectra 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, all recently measured spectra are saved together, decreasing the number of files and keeping related spectra in the same files. Summaries of the spectra in a collection are additionally saved to a CSV file and a plot of the collected spectra saved to a .pdf file.

The value returned by the function is that from closing the connection to the spectrometer.

Details

Function acq_irrad_interactive() supports measurement of spectral irradiance from continuous light sources and spectral fluence from discontinuous ones. For spectral irradiance it assumes that the duration of the measurement event is the relevant time base for expression of the flux of radiation. For spectral fluence the flux of radiation is expressed per pulse of illumination. The acquisition of both individual spectra and time series of spectra are supported.

A tutorial guiding on the use of this function, illustrated with diagrams, is available at https://www.r4photobiology.info/pages/acq-irrad-tutorial.html. A summary is provided below.

Different arguments passed to interface.mode modify which aspects of the user interface are available through menus, without altering the ability to control the behaviour through arguments passed to formal parameters when calling the function (see section Interface Modes for details).

This function can acquire spectra using different protocols for acquisition and for stray light and dark corrections. The protocols are described in the vignettes and in the help for the low-level functions called by this function, also from this same package.

Opening the connection to the spectrometer and selection of the channel, when relevant, is done interactively from within this function.

The irradiance calibration is retrieved from the spectrometer memory as a last resource if not supplied in any other way. Given that the factors are stored by Ocean Optics in a format that ignores the entrance optics, either the effective cosine diffuser area in xxx should be passed to parameter area or a character string with the type of the diffuser passed to diff.type. If no irradiance calibration is available, counts per second (cps) or raw counts are the only options available for the returned spectral data.

Three main protocols and two variations are available by default. They differ in the additional measurements done to correct for stray light and dark noise and in the sequence in which they are acquired. In most situations, at least one of the default protocols is suitable.

In the case of spectral irradiance, the default is to set the integration time automatically so that the number of counts at the highest peak is close to 1 - target.margin times the maximum raw-counts 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 cannot be exceeded but multiple scans can be averaged.

In the case of spectral fluence the default is for the integration time to be set manually and for a message to be displayed asking for the light pulse to be manually triggered. It is possible to override the default function by one that triggers the light source automatically when suitable hardware is available.

Repeated measurements are converted into physical units immediately after acquisition and saved to file on disk. Each repeated measurement can be either a single spectrum or a time series of spectra. To avoid long delays caused by saving large files, async.saves can be enabled.

Time series of spectra are acquired as fast as possible, converted into physical units after the acquisition of all individual raw-counts spectra and saved as a single cps_spct or source_spct in long form.

Time series of light measurements using single "dark" and "filter" measurements are scheduled by setting four members of the named list passed as argument to seq.settings, or interactively through the user interface.

The initial.delay is numeric and gives a minimum delay in seconds before the start of measurements with a default of 0s.

The step.delay is numeric and gives the length of time between successive "light" measurements. The value entered by the user is adjusted based on the estimated duration of individual spectrum acquisition. In most cases a vector of length one is used as time step lengths in seconds. Any vector shorter than the number of steps will be extended with rep_len(), and the values interpreted as the time increment in seconds between the start of successive measurements. If the length is the same as "num.steps", and the values are monotonically increasing, they are interpreted as time offsets from the start of the sequence.

The start.boundary must be set to a character string, with "none", or a number of seconds, minutes or hours indicated by a number followed by S, M, or H (capital letters) the round value of the current time at which the measurement event will start. For example,1H indicates that measurements should be scheduled to start exactly at the hour, and 5M at the next time the minutes in the current time are divisible by 5.

The num.steps must be an integer between 1 and an 100000 indicating the number of time points at which spectra should be acquired for the time series. The maximum value depends on the available memory and in many computers 5000 spectra is a more realistic limit than 100000. Applying corrections and applying the calibration are computation intensive, consequently for long series is wise to set `qty.out = "raw"` to speed up the measurement session.

Plots are produced with functions from package 'ggspectra' and respect the defaults for plot annotations set in R options. The options can be easily set with functions set_annotations_default(), set_w.band_default(), photon_as_default(), and energy_as_default(). The ggplots are not saved as 'gg' objects as they contain redundant copies of the spectral data. They can be easily recreated using function autoplot() after attaching package 'ggspectra'.

The screen display of plots can be disabled, as in some cases the delay introduced by rendering can be a nuisance. Alternatively, the value of plot.lines.max can be changes from its default to change the maximum number of spectra displayed. If the number of spectra available for plotting exceeds the limit, a random sample of spectra of size plot.lines.max is displayed, on screen and in PDF files.

Note

The function is composed in a modular way from functions defined in this same package, R or imported from other R packages. The code of the function can be reshuffled combining the functions used here with other functions to create new variations, possibly better suited to users' specific needs and tastes.

A "light-weight" approach to tweaking the user interface is to implement new modes by simply changing which of the logical flags that control the display of menus are enabled or not in a wrapper function. And even easier approach is to create a simple script that passes suitable arguments to the different formal parameters of this function. Example scripts are included in the package in the folder extdata/example-scripts/.

Interface Modes

Mode simple displays a simplified user interface, supporting the acquisition of individual irradiance spectra. Integration time is adjusted automatically.

Mode auto displays a user interface supporting the acquisition of individual irradiance spectra and creation of collections of spectra. Integration time is adjusted automatically.

Mode manual displays a user interface supporting the acquisition of individual fluence or irradiance spectra and creation of collections of spectra. Integration time can adjusted automatically but also set manually.

Mode series displays a user interface supporting the acquisition of individual spectra and time series of irradiance spectra. Integration time can adjusted automatically but also set manually.

All these modes with -attr appended, enable a menu and dialogues that make it possible to set the values stored in attributes comment and what.measured interactively.

All modes support repeated measurements with unchanged acquisition settings reusing the reference spectra ('dark' and 'filter') from the most recent previous measurement.

Object names

Object names entered interactively are sanitized if necessary. Sequentially numbered object names are enabled by appending "#" to the desired base name. As long as no new name is entered, the sequence continues. If a new name is entered, numbering restarts at 001 or stops depending on whether the new name ends in "#" or not. In the case of repeated measurements, sequential numbering is enforced to ensure unique names.

Irradiance calibration

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 spectral irradiance calibration is available and attempt is made to retrieve it from the spectrometer, but given the format used by Ocean Optics/Ocean Insight, in this case the effective area of the cosine diffuser used (or the model name if from Ocean Optics) should be supplied by the user.

Quality control of dark spectra

Disabling the quality control with QC.enabled = FALSE is useful when when the "dark" reference is a measurement of ambient light instead of true darkness; i.e., when the irradiance of one light source is measured as the difference between background illumination and background illumination plus the target light source.

Examples

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

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

acq_irrad_interactive()
acq_irrad_interactive(qty.out = "cps")

} # }