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.

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 = 50,
  summary.type = "plant",
  save.pdfs = TRUE,
  save.summaries = TRUE,
  save.collections = interface.mode != "simple",
  interface.mode = ifelse(qty.out == "fluence", "manual", "auto"),
  num.exposures = ifelse(qty.out == "fluence", 1L, -1L),
  f.trigger.pulses = f.trigger.message,
  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 = "_")
)

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.

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

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.pulses

function Function to be called to trigger light pulse(s). Should accept as its only argument the number of pulses, and return TRUE on success and FALSE on failure.

folder.name, session.name, user.name

character Default name of the folder used for output, and session and user names.

Value

These functions return 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 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 are 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

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.

This function can be used to acquire spectra using different protocols for acquisition and 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.

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.

The irradiance calibration will be 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.

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. The default protocols are usually suitable, if new protocols are passed, each character vector must contain strings "light", "filter" and "dark".

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

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.

Different argumenst passed to interface.mode modify which aspects of the user interface are available through menues, without altering the ability to control the behaviour through arguments passed to formal parameters when calling the function. For example, mode "series" exposes the menue used to change schedulling of single measurements and time series of measurements.

Sequences of light measurements using single "dark" and "filter" measurements are scheduled by setting the four members of the named list passed as argument to seq.settings. The member initial.delay is numeric and gives a minimum delay in seconds before the start of measurements with a default of 0s. Member step.delay is numeric and gives the delay in seconds between successive "light" measurements. In most cases a vector of length one is used as time delta 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. Member start.boundary can take one of "none", "second", "minute" or "hour" indicating the unit to which the start of the series should be scheduled, e.g. the next minute and 0s, for "minute". Member num.steps must be an integer between 1 and small thousands indicating the number of time steps in the series.

Plots are produced with functions from package 'ggspectra' and respect the default annotations set with function set_annotations_default(), default wavebands set with function set_w.band_default(), and irradiance quantities set with photon_as_default(), and energy_as_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 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.

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.

See also

This function calls functions tune_interactive, protocol_interactive and set_attributes_interactive. If irradiance calibration is retrieved from the instrument, functions get_oo_descriptor and oo_calib2irrad_mult are also called.

Other interactive acquisition functions: acq_fraction_interactive()

Examples

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

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

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

}