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 = "_")
)numeric vector Range of total times for a measurement in seconds.
numeric (0..1) when tuning integration time, how big a head space to leave.
numeric the integration time for each bracketed integration as a multiplier of the set or tuned integration time.
named list of character vectors, or a character vector with names of at least one member of the default list of protocols.
list The method to use when applying the calibration
list A list of instrument descriptors containing calibration data.
character, name or geometry of diffuser, needed only if there is more than one for the same instrument.
character Used only when the correction method is created on-the-fly.
named list with numeric members start.boundary,
initial.delay, "step.delay" and "num.steps".
numeric Passed to o_calib2irrad_mult().
character Passed to o_calib2irrad_mult().
character One of "irrad" (spectral irradiance), "fluence" (spectral fluence), "cps" (counts per second), or "raw" (raw sensor counts).
integer Maximum number of spectra to plot as individual lines.
character One of "plant", "PAR" or "VIS".
logical Whether to save plots to PDFs files or not, and collection summaries to csv files or not, enable collections user interface or not..
character One of "auto", "simple", "manual", "full", "series", "auto-attr", "simple-attr", "manual-attr", "full-atr", and "series-attr".
integer Number or light pulses (flashes) per scan. Set
to -1L to indicate that the light source is continuous.
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.
character Default name of the folder used for output, and session and user names.
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.
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.
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.
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()
# 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")
}