library(ooacquire)
options(warn = 1)
acq_irrad_interactive()
Note
Package ‘ooacquire’ is part of the R for Photobiology suite of R packages and its full documentation is available on-line. It depends on package ‘rOmniDriver’, whose full documentation is also available on-line.
Warning
The description and diagrams shown in this page are valid for ‘ooacquire’ versions >= 0.3.2-1. Versions <= 0.3.2 differ from version 0.3.2-1 in the user interface implemented in function acq_irrad_interactive() described in this page. Acquisition of fluence spectra with function acq_irrad_interactive() is possible only in versions >= 0.3.4 of ‘ooacquire’.
Introduction
R package ‘ooacquire’ is a component of the R for Photobiology suite of packages and supports the near-real-time acquisition of spectral data using Ocean Optics spectrometers from Ocean Insight. Package ‘ooacquire’ imports and uses classes, methods and functions defined in other packages of the suite.
Spectral energy irradiance is expressed in \(W\,m^{-2}\,nm^{-1}\) and spectral fluence in \(J\,m^{-2}\,nm^{-1}\). The corresponding photon-based units are \(mol\,s^{-1}\,m^{-2}\,nm^{-1}\) and \(mol\,m^{-2}\,nm^{-1}\). Irradiance is a flux rate expressed per unit time and fluence is an exposure expressed per event. When illumination is constant during a short measurement event, it is customary to describe its intensity using irradiance. When illumination is a discrete pulse shorter than the duration of the measurement event, fluence is used to describe the amount of energy or number of photons per pulse. Fluence can be easily computed from irradiance if we known the duration of the exposure. Computing actual irradiance from fluence is nearly impossible unless the pulse are from a square wave and we know their duration. Of course, if pulse are regularly spaced in time, have the same duration and amplitude and the measurement last for long enough, we can obtain an average irradiance across a train of pulses, as emitted by some light sources, e.g., because of AC mains power. PWM dimming or other non-DC power lamp drivers.
Function acq_irrad_interactive() implements the interactive acquisition of spectral irradiance and spectral fluence data using Ocean Optics array spectrometers. It returns the acquired data as a side effect by saving them to files on disk. The raw-counts data are acquired and converted into spectral irradiance values. The data for each measurement event are saved as soon as acquired, but a group of successively acquired spectra can be collected into a single object, summarized and/or saved to a file on disk in addition to the individual files per measurement event. In every case the raw counts data, instrument descriptor, instrument settings and either computed spectral irradiance or computed counts per second are saved to disk. Plots are displayed on the screen for each measurement event. A measurement event consists of either a single light spectrum or of a time series of light spectra.
Package ‘ooacquire’ has been evolving for several years and will continue to evolve, specially with respect to interactive acquisition of spectral data. The user interface for spectral irradiance is currently more polished and complex than the interfaces for fluence spectra and transmittance and reflectance spectra. This is because both myself and other users most of the time use ‘ooacquire’ to measure spectral irradiance.
The user interfaces (UIs) implemented in functions acq_irrad_interactive(), acq_fluence_interactive(), acq_fraction_interactive() and their variations are text based rather than graphical. The design is optimized for frequent users rather than for occasional users. A key design objective has been to make the acquisition of multiple spectra per measurement session as comfortable and as fast as possible, i.e., avoid tedious. This is different to what is usually meant by user friendly involving hand-holding and verbose options within the interface.
As much as possible, options are selected by typing a single character, or even just the enter key, thanks to context and state dependent defaults. The interface is as far as it can be from visually attractive, but it works well for myself, and most other people who use it.
To start a session within R for the measurement of spectral irradiance accepting all defaults we can type at the R console, one statement to load and attach package ‘ooacquire’, a second, optional statement to set an option to tell R to print warning immediately instead of delayed, and a third statement to call the function and then use the UI it opens.
The video below demonstrates the use of the interface for an old version of ‘ooacquire’ (will be replaced by an up-to-date one).
The UI implemented in acq_irrad_interactive() is rather terse and, thus, needs to be clearly documented. The vignettes of package ‘ooacquire’ include some examples. However, a description of the logic can be best done using diagrams. Mermaid is a markdown-like language for the easy creation of diagrams, but not yet supported in vignettes. As its many diagrams are encoded using Mermaid and it includes video content, this tutorial is published as a page at the R for Photobioly web site instead of as part of the ‘ooacquire’ R pakage documentation.
Interface modes
Function acq_irrad_interactive() is like a Swiss Army Knife. It has multiple ‘’personalities’’ and the first step is the choice of interface.mode, which determines which interface will be shown to the user. Basically, the selected interface.mode determines which options can be modified by the user through the interactive UI and which ones are fixed at the values set when the function is called.
In addition, whether PDF files containing plots of individual measurements, and whether different summaries and plots from the created collectiond of spectra are saved to files or not can be controlled also by passing arguments to formal parameters when the function is called.
Normally, when measuring several spectra in a row, any redundant need to select choices in a menue or enter repeatedly the same setting values by the user is distracting and time consuming. This is tackled using three three strategies: 1) with multiple interface modes with each mode displaying the parts of the user interface used in the case of a given type of measurements, and 2) by context-dependent defaults in menues, and 3) by easily repeating measurements with the most recently used settings and reference readings.
In this section we describe the overall logic behind strategies 1) and 3). Four modes are available, and which one is used is selected by the argument passed to formal parameter interface.mode when acq_irrad_interactive() is called to start a spectral-data acquisition session. There are four main interface modes built into acq_irrad_interactive() with "auto" as default.
%%{ init: {"graph": {"htmlLabels": true}} }%%
%%| fig-align: center
flowchart TB
A[interface.mode = ] -.-> B("simple")
A --> C(<b>auto</b>)
A -.-> D("series")
A -.-> E("manual")
A -.-> F("full")
"auto", is highlighted.
Appending -attr to these mode names enables the UI for setting the values of attributes what.measured and comment. For example, "simple" becomes "simple-attr".
Start up
The UI does not differ among interface modes for the initialization steps, and it is not part of the loop for the acquisition of individual spectra or series of spectra.
flowchart TB A((<b>start</b>)) --> B(select spectrometer\nand channel?) B --> C(session name?) --> C1(user name?) --> D(folder name?) --> E(((<b>1</b>)))
The loop diagrams shown in the sections below, are all active after these first steps are completed. The encircled 1, simply signals this connection.
User Interface Loop
In the diagrams below I show single boxes not only for the input of single values but also for menus containing multiple options. These menues are attribute?, acquisition parameters?, and series parameters?. Within plot and save and plot and save collection there are options about the formatting of the plot, and in the second case also about the file name used to save the collection.
We start with a complete flowchart of the UI loop for the acquisition of spectra, which shows all the possibilities, but does not correspond to any interface.mode, because all of them are subsets.
Once one measurement is completed and saved, a new measurement can be acquire using the same settings for the acquisition as well as reusing the same dark and filter reference spectra (repeat) or with the possibility of changing these settings and acquiring fresh dark and filter reference spectra (next).
flowchart TB
E(((<b>1</b>))) --> G(protocol?)
G --> I(object name?) --> J(attributes?) --> K(acquisition\nparameters?)
K --> L(series parameters?) --> M[[measure\nspectra]] --> N[(plot and save)]
N --> N1{collect?} --yes--> N2[(plot and save\ncollection)] --> O{next\n repeat\n or end?}
N1 --no--> O
J -.repeat.-> L
O -.repeat.-> I
O --next--> G
O --> P((<b>end</b>))
"simple" mode
The "simple" interface mode provides a minimalist UI, quite similar to the only UI available in early versions of ‘ooacquire’. It is intended for the acquisition of individual irradiance spectra.
%%{ init: {"graph": {"htmlLabels": true}} }%%
flowchart
E(((<b>1</b>))) --> G(protocol?)
G --> I(object name?) --> K(acquisition\nparameters?\n<i>simplified</i>)
K --> M[[measure\nspectra]] --> N[(plot and save)] --> O{next\nrepeat\nor end?}
I -.repeat.-> M
O -.repeat.-> I
O --next--> G
O --> P((<b>end</b>))
"simple".
"auto" mode
The "auto" interface mode provides a complete UI intended for the acquisition of individual spectra and possibly packing groups of spectra into collections and computing summaries. The default is to adjust the integration time automatically by measurement, and it is best suited to the measurement of sources that emit light continuously with an output that varies little in the short time.
%%{ init: {"graph": {"htmlLabels": true}} }%%
flowchart TB
E(((<b>1</b>))) --> G(protocol?)
G --> I(object name?) --> K(acquisition\nparameters?\n<i>full</i>)
K --> M[[measure\nspectra]] --> N[(plot and save)]
N --> N1{collect?} --yes--> N2[(plot and save\ncollection)] --> O{next\nrepeat\nor end?}
N1 --no--> O
I -.repeat.-> M
O -.repeat.-> I
O --next--> G
O --> P((<b>end</b>))
"auto".
"manual" mode
Mode "manual" differs from "auto" in that the default is for the user to directly set the integration time. It is most useful when measuring fluence from manually triggered light pulses, such as a xenon flash.
"series" mode
The "series" interface mode provides a complete UI intended for the acquisition of time series of spectra and possibly packing groups of time series of spectra into collections and computing summaries.
%%{ init: {"graph": {"htmlLabels": true}} }%%
flowchart TB
E(((<b>1</b>))) --> G(protocol?)
G --> I(object name?) --> K(acquisition\nparameters?\n<i>full</i>)
K --> L(series parameters?) --> M[[measure\nspectra]] --> N[(plot and save)]
N --> N1{collect?} --yes--> N2[(plot and save\ncollection)] --> O{next\nrepeat\nor end?}
N1 --no--> O
I -.repeat.-> L
O -.repeat.-> I
O --next--> G
O --> P((<b>end</b>))
"series".
"full" mode
Mode “full” is in practice of little or no use except for testing as it makes all settings of the UI visible to the user.
"-attr" variants of the modes
Appending "-attr" to the name of any interface.mode enables the menu and dialogues that enable the setting of the what.measured and comment attributes of the source_spct objects into which spectra are saved. This could be represented in the diagrams by the insertion of an attributes? box immediately below object name? as shown in the first diagram showing the full logic.
Selecting the interface mode
When calling function acq_irrad_interactive() we can pass arguments to tailor the UI to our current needs. For example, to use the "simple" mode instead of the default "auto" mode we can call the function as follows.
acq_irrad_interactive(interface.mode = "simple")We can in addition disable the saving of specific output to files. For example to disable the saving of PDF files of the plots from individual measurements and from collections of spectra we can use:
acq_irrad_interactive(save.pdfs = FALSE)If we do not intend to create and save collections of spectra or summaries, we can disable these steps, removing from users’ view one menu that becomes redundant.
acq_irrad_interactive(save.collections = FALSE,
save.summaries = FALSE)If we do not want to save ready made summaries but still be able to create and save collections of spectra we can use.
acq_irrad_interactive(save.summaries = FALSE)Of course, these options are independent of each other, and can be combined as needed.
Note
Saving plots of large collections of spectra or of long time series of spectra to disk is a slow process. Disabling this step by passing save.pdfs = FALSE could be worthwhile in such cases.
Measurement protocols
The different diagrams below open the actions that take place within the measure spectra boxes in the diagrams above, previously treated as black boxes. These actions depend on the protocol used for the measurements and on whether the measurement is a fresh one (next) or one reusing settings and reference measurements (repeat). The same measurement protocols are available in the different user interface modes. We show here the protocols available by default. However, users can define their own protocols. In the diagrams below, start and end represent the start and end of a measurement event, i.e., the boundaries of the generic measure spectra boxes in the diagrams above. Within each step in most cases several spectra are acquired, with the same integration time when averaging is used and with different integration times when HDR is used. In all modes except series, the same number of raw spectra are acquired for dark, filter and light if used, and combined into a single irradiance or fluence spectrum. In the case of series, measurements are repeated in time for light so that several irradiance spectra are obtained measured at regular time intervals.
Protocol l
l stands for acquisition of light scans.
flowchart LR S((<b>start</b>)) --> C C[light\nspectrum or\nspectra] --> E((<b>end</b>)) C -.series.-> C
l.
Protocol ld
ld stands for acquisition of light and dark scans sequentially in this order.
flowchart LR S((<b>start</b>)) --> A A -.repeat.-> E A[light\nspectrum or\nspectra] --next--> D[dark\nspectrum] --> E((<b>end</b>)) A -.series.-> A
ld.
Protocol lfd
lfd stands for acquisition of light, filter and dark scans sequentially in this order.
flowchart LR S((<b>start</b>)) --> A A -.repeat.-> E A[light\nspectrum or\nspectra] --next--> B[filter\nspectrum] --> C[dark\nspectrum] --> E((<b>end</b>)) A -.series.-> A
lfd.
Protocol dl
dl is identical to ld except for the sequential order of the acquisition of data.
flowchart LR S((<b>start</b>)) --next--> A S -.repeat.-> C A[dark\nspectrum] --> C[light\nspectrum or\nspectra] --> E((<b>end</b>)) C -.series.-> C
dl.
Protocol dfl
dfl is identical to lfd except for the sequential order of the acquisition of data.
flowchart LR S((<b>start</b>)) --next--> A S -.repeat.-> C A[dark\nspectrum] --> B[filter\nspectrum] --> C[light\nspectrum or\nspectra] --> E((<b>end</b>)) C -.series.-> C
dfl.
Spectral quantity
Through parameter qty.out we can choose between four alternatives: "raw" (raw instrument counts for each detector pixel), "cps" (counts per second for each detector pixel), "irrad" (energy and/or photon spectral irradiance) and "fluence" (energy and/or photon spectral fluence). Spectral irradiance and spectral fluence can be computed in near real time only if irradiance calibration factors and correction method definitions are available for the spectrometer used. The raw detector counts are always returned allowing in all cases spectral irradiance and spectral fluence to be computed or recomputed at a later time.
Acquisition parameters
We describe the data acquisition parameters affecting the acquisition of spectral irardiance only briefly here, and refer the reader to the vignette that describes the algorithms used included in package ‘ooacquire’.
For the integration time used for the acquisition of data a distinction is made between the duration of a single integration event and the total added-up integration time resulting from successive integrations averaged by the spectrometer or driver. The duration of individual integrations needs to be adjusted or tuned so that full use is made of the dynamic range and signal to noise headroom of the instrument. The total measured time, can obviously be only as long or longer than a single integration. When spectral irradiance is constant in time, the longer the total time over which scans are averaged the better “random” noise is controlled.
To increase the dynamic range we can use different integration times for different wavelength-regions of the spectrum (HDR or “bracketing”) and splice the counts per second spectra during their conversion into spectral irradiance. Dynamic range is not the only limiting factor. Stray light and thermal noise limit the signal to noise ratio. Stray light may depend on the shape of the measured spectrum and thermal noise on the temperature of the spectrometer. In normal cases the achievable increase in dynamic range with the HDR approach is approxinately one order of magnitude.
Stray light can be most effectively corrected for by measuring it separately from the target of the measurements. This is the role of the filter measurements in the protocols described above.
Acquisition parameters include the integration time (= duration of a single integration) which is normally, but not always, adjusted by automatic tuning (i.e., by trial and error, taking into account a target margin of headroom supplied by the user), and a target duration range for the sum of multiple integration times desired, which is always explicitly supplied by the user. For bracketing the user supplies a vector of multipliers to be applied to the optimal or set integration time. All parameters have defaults, and user-entered values persist between successive measurement events unless modified again by the user.
In the case of spectral fluence, although available, several of the corrections are in practice difficult to implement because of the discontinuous light emission by the sources. If pulses can be triggered on demand and the output per pulse is reproducible, stray light correction is applicable. Adjustment of signal level and eventually bracketing need to be done based on the number of pulses per detector integration.
Note
For additional information, please, see the help page for acq_irrad_interactive() and the vignetters of package ‘ooacquire’, especially that describing the algorithms used.