
Acquire spectral irradiance or spectral fluence
Source:R/acq-irrad-interactive.R
acq_irrad_interactive.Rd
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.
See also
This function calls functions tune_interactive
,
protocol_interactive
, set_seq_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()