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.
See also
This function calls functions tune_interactive
,
protocol_interactive
and
set_attributes_interactive
.
Other interactive acquisition functions:
acq_irrad_interactive()