Package 'ooacquire'

Description

Functions to acquire data directly from Ocean Optics spectrometers, and functions to read similar data from files. Functions to convert raw-counts into counts-per-second and physical quantities. Data are saved in objects of classes defined in package 'photobiology'. The instrument settings, instrument description, date-time of acquisition and optionally goecode are stored as attributes.

Details

Processing of raw-counts data acquired following different protocols and corrections including integration-time bracketing and merging, slit function corrections, subtraction of stray light and adaptive smoothing corrections.

Acquisition of raw-counts spectra directly from Ocean Optics' spectrometers. A high level interface to the OmniDriver library for spectrometer control and data acquisition provided by Ocean Optics for their instruments. Built on top of the 'rOmniDriver' package which provides a very thin wrapper on the Java functions giving access to the proprietary driver.

Reading of raw-counts spectra from files saved by Ocean Optics' software: OceanView, SpectraSuite, Raspberry Pi SDK, and Jaz firmware.

Note

This package is provided without any warranty of suitability for any specific purpose or instrument as it has been tested with only three different models of Ocean Optics spectrometers, each with one or two of many available hardware configurations.

Author(s)

Maintainer: Pedro J. Aphalo [email protected] [translator]

Authors:

• Pedro J. Aphalo [email protected] [translator]

• Lasse Ylianttila

Other contributors:

• Titta K. Kotilainen [contributor]

See Also

Useful links:

• https://docs.r4photobiology.info/ooacquire/

• https://github.com/aphalo/ooacquire

• Report bugs at https://github.com/aphalo/ooacquire/issues

Description

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 = ifelse(interface.mode %in% c("series", "series-attr"), 11, 50),
  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,
  figs.theme = "built.in",
  interface.mode = ifelse(light.source == "pulsed", "manual", "auto"),
  num.exposures = ifelse(light.source == "pulsed", 1L, -1L),
  f.trigger.init = NA,
  f.trigger.on = f.trigger.message,
  f.trigger.off = NA,
  triggers.enabled = c("sample", "reference"),
  folder.name = NULL,
  user.name = Sys.info()[["user"]],
  session.name = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE),
  QC.enabled = TRUE
)

Arguments

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.

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.

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()

Examples

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

## Not run: 
# requires an Ocean Insight (former Ocean Optics) spectrometer to be
# connected via USB

acq_fraction_interactive()


## End(Not run)

Description

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 = ifelse(interface.mode %in% c("series", "series-attr"), 11, 50),
  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 = NULL,
  user.name = Sys.info()[["user"]],
  session.name = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE),
  QC.enabled = TRUE
)

Arguments

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 five members of the named list passed as argument to seq.settings, or interactively through the user interface. If the fields are missing in the list, defaults are used for these fields.

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.

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.

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.

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

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()

Examples

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

## Not run: 
# requires an Ocean Optics spectrometer connected via USB

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


## End(Not run)

Description

Take readings according to parameters from a list of settings and a protocol defined by a vector of names.

Usage

acq_raw_mspct(
  descriptor,
  acq.settings,
  f.trigger.on = f.trigger.message,
  f.trigger.off = NA,
  triggers.enabled = character(),
  seq.settings = NULL,
  protocol = c("light", "filter", "dark"),
  user.label = "",
  where.measured = data.frame(lon = NA_real_, lat = NA_real_),
  pause.fun = NULL,
  verbose = TRUE,
  ...
)

Arguments

Details

Function acq_raw_mspct acquires directly from a spectrometer a collection of spectra. The settings used for the acquisition of each member spectrum are the same, and are given by the argument passed to acq.settings. The number of numbers and their names are given by the argument passed to protocol.

Two types of light sources can be measured, for continuous-emission light sources, the integration time can at later steps used to compute irradiance. In the case of flashes, the duration of the exposure is unknown and irradiance cannot be computed, while spectral energy per flash can be computed if the number of flashes is known. The argument to num.exposures must be set to the number of flashes.

Two parameters accept functions as arguments, and default to functions that request the operator to trigger the flash or change the light conditions according to the names of the steps in the argument to protocol.

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. Member start.boundary can take any input accepted by as.period() such as "none", "second", "minute", "hour", "5s", "2min", or a numeric value interpreted as seconds, indicating the time boundary at which to start the measurement of the series e.g. exactly at the next minute and 0s. Member num.steps must be an integer between 1 and small 100000 indicating the number of time steps in the series.

Value

A raw_mspct object. The names and number of member spectra are determined by protocol, and the number of columns in each member spectrum is determined by acq.settings.

Note

Obviously the duration of the time steps must be longer than the time that a measurement takes. This time can be significantly more than the sum of integration times, as there is considerable overhead in both the OmniDriver Java code, in USB communication, in the spectrometer itself and in R. The overhead depends strongly on the model of spectrometer and the acquisition protocol.

No multitasking is used or supported, so R waits for the spectrometer to answer. The operating system and other programs are not blocked, but the current R instance is.

See Also

acq_raw_spct which is used to acquire each member spectrum. Computations on date times are done with lubridate.

Other raw-counts-spectra acquisition functions: acq_raw_spct(), hs_acq_raw_mspct()

Description

Take one spectral measurement which depending on the settings can consist in multiple raw spectra meant to represent a SINGLE observation after conversion into calibrated data, such as in the case of bracketing of integration time for HDR.

Usage

acq_raw_spct(
  descriptor,
  acq.settings,
  f.trigger.on = f.trigger.message,
  f.trigger.off = NA,
  what.measured = NA,
  where.measured = data.frame(lon = NA_real_, lat = NA_real_),
  set.all = TRUE,
  verbose = TRUE
)

Arguments

Details

This function acquires one raw-detector-counts spectrum from a spectrometer, using the descriptor to connect to the spectrum and retrieve the valid range for settings. The settings in acq.settings are first sent to the spectrometer and the values retrieved in case the spectrometer has overridden the requested settings. Subsequently a spectrum, possibly obtained by averaging multiple spectra in the spectrometer is acquired, and the spectrometer queried on whether data are valid or not.

Function acq_raw_spct() can optionally call two functions, one at the start of the measurement and another one after it ends. f.trigger.on() can be used for example when measuring the output from a xenon flash lamp, to trigger a given number of light flashes. In other cases f.trigger.on() and f.trigger.off() can be used together to start and end a concurrent measurement or any other action using a relay controlled by code in a function defined by the user.

The functions passed as arguments to f.trigger.on() and f.trigger.off() should return very quickly when called, so as not to disturb the timing of the measurements of spectra as these start only after f.trigger.on() returns to the caller.

The first formal parameter of f.trigger.on() should handle as input an integer value indicating the number of events to trigger and a second argument giving the delay in seconds between pulses. Of course the arguments can be ignored if not needed, but should accepted. f.trigger.off() currently expects no arguments. Example scripts are provided for YoctoPuce USB modules.

The default function, displays a message asking the user to manually trigger the flash a number of times that depends on the settings in acq.settings.

Value

A raw_spct object with one column w.length and one column counts, or two or more columns counts1, counts2, ... containing raw counts data. The number of columns with raw counts is determined by acq.settings, with multiple columns in the case of integration time bracketing or HDR.

See Also

acq_raw_mspct which can be used to acquire multiple spectra according to a user defined protocol.

Other raw-counts-spectra acquisition functions: acq_raw_mspct(), hs_acq_raw_mspct()

Description

Validate parameters for spectral measurements and return a list of values usable as input for functions retune_acq_settings(), acq_sptc(), and acq_mspct().

Find optimal settings for spectral measurements under a given measurement protocol.

Usage

acq_settings(
  descriptor,
  integ.time = 0.01,
  num.scans = 10L,
  min.integ.time = -Inf,
  max.integ.time = Inf,
  tot.time.range = c(0, Inf),
  HDR.mult = ifelse(any(num.exposures != -1L), rep(1, length(num.exposures)), c(short =
    1, long = 10)),
  target.margin = 0.1,
  pix.selector = TRUE,
  corr.elect.dark = 0L,
  corr.sensor.nl = 0L,
  boxcar.width = 0L,
  force.valid = FALSE,
  num.exposures = -1L,
  verbose = TRUE
)

tune_acq_settings(descriptor, acq.settings, verbose = TRUE)

Arguments

Details

acq_settings() is used to create a complete set of instrument settings in a way that they can be reused as needed for repated acquisition of spectra. acq_settings() is an object constructor and tune_acq_settings() takes as argument a stored object containing settings and tunes them to optimize them for the measurement of the current spectral irradiance.

This function searches for the optimal integration time for a given condition by trial and error helped by interpolation and extrapolation when readings are not saturated. In the case of clipping or sensor signal saturation the integration time is decreased until clipping is avoided and then it is increased until optimal.

Value

a list.

a list Containing the tuned settings.

Note

pixel.selector can be used for two different purposes: to ignore bad pixels and to restrict integration-time tuning to the response from a range of pixels. The interpretation of tot.time.range is as follows: first value is minimum time, second value is maximum time. If both values are the same, then an exact measurement time is computed.

Ocean Optics spectrometers can be queried for the maximum and minimum supported integration times. This function modifies the user supplied values if outside these bounds. The defaults of -Inf and Inf force the use of the whole valid range of integration time supported by the connected intrument. pixel.selector can be used for two different purposes: to ignore bad pixels and to restrict integration-time tuning to the response from a range of pixels.

The returned value can be used as argument to acq.settings in other functions like acq_raw_spct and acq_raw_mspct

See Also

Other acquisition-settings related functions: set_integ_time(), set_linearized(), set_num_exposures()

Description

Replace "good" data from pixels adjacent to NAs with NAs as data from pixels not saturated but located in the neighbourhood of saturated pixels can return unreliable data. This correction is needed by a phenomenon similar to "blooming" in camera sensors whereby when a sensor well gets saturated some of the charge migrates to adjacent wells in the detector increasing their readings.

Usage

bleed_nas(x, n = 10)

Arguments

Value

a copy of x with values replaced by NAs as needed in all counts columns present.

Note

Avoid using very large n values as n pixels at each end of the array are assumed not to be ever saturated. The value of n needed for each detector type/instrument needs to be found through testing. As rule of thumb use 5 < n < 10 for Sony's ILxxx and 8 < n < 14 for Hamamatsu xxxx. At the moment we use a symmetric window although "blooming" could be asymmetric.

Description

A blue interference filter from UQG measured using a household incandescent lamp as light source. The spectrometer used was an Ocean Optics Maya2000 Pro.

Usage

blue_filter.raw_mspct

Format

A raw_mspct

See Also

Other objects containing example raw-counts data: halogen.raw_mspct, red_filter.raw_mspct, sun001.raw_mspct, white_grow_LED.raw_mspct, xenon_flash.raw_mspct

Description

This method checks that the sn of the instrument used to acquire the raw counts matches that in the definition of a correction method.

Usage

check_sn_match(x, correction.method, missmatch.action = stop)

Arguments

Value

A logical vector of length one, with FALSE indicating a missmatch.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), linearize_counts(), merge_raw_mspct(), new_correction_method(), ref_correction(), trim_counts(), uvb_corrections()

Description

Choice of channel to be used if spectrometer has more than one channel.

Usage

choose_ch_interactive(
  instruments,
  sr.index = 0L,
  prompt.text = "Channels available: "
)

Arguments

Value

A numeric index suitable for use in calls to functions defined in package 'rOmniDriver' based on which package 'ooacquire' is coded.

See Also

Other interactive acquisition utility functions: choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Choice of spectrometer from a list of serial numbers, allowing the user to correct the selection if needed.

Usage

choose_sr_interactive(instruments)

Arguments

Value

A numeric index suitable for use in calls to functions defined in package 'rOmniDriver' based on which package 'ooacquire' is coded.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Read .Rda files as saved during data acquisition and build a collection with the spectra read, possibly first trimming the range of wavelengths and/or smoothing the spectral data.

Usage

collect_spct_files(
  path = ".",
  range = NULL,
  method = NULL,
  strength = 0,
  name.root = "",
  na.rm = FALSE
)

Arguments

Note

If the argument passed to method is of length 2, the first member will apply to source_spct objects and the second one to filter_spct and reflector_spct objects. A numeric vector of length 2 passed to strength is treated in the same way. This is only relevant when we are collecting spectra belonging to different classes and need to treat them differently with respect to smoohting. It also allows different defaults, as transmittance spectra tend to lack the fine structure of some emission spectra.

See Also

Function trim_wl is used to trim the range of the data to plot, and function smooth_spct is used for smoothing, and prameters range, and strength and method are passed to them, respectively.

Other functions for importing spectral data from files: map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Function to calculate from a set of three (or optionally five or two) output files from the spectrometer, as produced by SpectraSuite, for each of two calibration lamps (D2 and FEL), and calibration data for the lamps, a set of calibration multipliers for the instrument. This function applies a non-linearity correction, an slit-function correction, and stray-light correction, and optionally smoothing by means of process_maya_arrays(). Optionaly a HDR ("high dynamic range") merging of spectra (based on integration time bracketing) using two different integration times is done.

Usage

compute_irrad_calibration(
  FEL.raw.counts,
  D2.raw.counts,
  pix.wavelengths = NULL,
  wl.range = c(250, 900),
  FEL.k,
  D2.k,
  method,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Value

An instrument descriptor as a list containing the updated wavelengths and multipliers from the calibration.

Note

To calculate new multipliers we set the calibration multipliers equal to 1. Do the calculations as usual and calculate new multipliers based on the known spectral irradiance for the calibration lamps.

Description

Close the connection to the spectrometer pointed at by the Java object referenced in x.

Usage

end_session(w)

Arguments

See Also

Other spectrometer-connection functions: list_instruments(), start_session()

Description

Package 'ooacquire' includes example scripts for acquisition of spectral data using Ocean Optics spectrometers. These scripts demonstrate the use of functions acq_irrad_interactive() and acq_fraction_interactive().

Details

The default behaviour of functions acq_irrad_interactive() and acq_fraction_interactive() is controlled by passing arguments to their formal parameters when called as well as by R options set before calling them.

Some of these defaults affect the type of data returned and the computation of physical quantities from the detector raw-counts data received from the spectrometer and which type of graphical and textual summaries are computed an saved.

One parameter can be passed as argument the definition of an R function used to controll a lamp or some other device by a trigger or a message to the user.

However, the majority of the options make it possible to chose which menues and features are accesible interactively through menues. Experience has shown that in a long data acquisition session, displaying to the operator only those options relevant to the current protocol or measurement approach reduces operator stress, decreases the oportunities for mistakes and allows measurements to be done faster and more consistently. The folder, operator, and file names used can be also set by arguments.

These functions have what at first sight is an excessive number of formal parameters. This is true if arguments to these parameters are entered manually each time spectral measurements are acquired. The idea is that using a simple R script, users can setup the default behaviour of these functions to match their needs. Once a script is available, it can be sourced to start a measurement session.

The scripts included in 'ooacquire' provide several examples of how to customize the default behaviour of the functions. Some of the files also include commented-out variations on the code example.

Examples

# find where the example files are installed as part of the package
path <- system.file("example-scripts", package = "ooacquire")

# list the files in the folder
list.files(path)

# read and display one example file
readLines(paste(path, "irrad-acq-interac-simple.R", sep = "/"))

Description

This function is used by default. It prints a message asking the operator to manually trigger a flash. A more elaborate function, using specific hardware can be used to automatically trigger a light source or some other synchronized event such as releasing the shutter of a camera.

Usage

f.trigger.message(n = 1L, delay = 0)

Arguments

Note

When using this function, set an integration time that gives enough time for the manual triggering of the flash to reliably fall within the integration.

See Also

Sys.sleep for a description of the variation in the effective duration of the delay.

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Remove Java wrappers stored in field "w" from the instr.descriptor metadata attribute of spectral objects and of members of collections of spectra loaded from R data files, saving them using their original name and location, after renaming the original files to serve as backups.

Usage

files_rm_jwrapper(
  path = ".",
  pattern = "\\.spct\\.[Rr]da",
  recursive = TRUE,
  date.limit = NULL,
  trim.descriptor = TRUE,
  save.files = FALSE,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

Spectral data objects acquired directly from a connected spectrometer with 'ooacquire' (< 0.2.5) contain a leftover Java wrapper used to connect to the spectrometer. This is of no use after disconnection, but if it remains in the objects saved to an .rda file loading these files requires 'rJava' and the Java JDK to be available. Some old source_spct and filter_spct objects can also contain the full instrument descriptor including calibration data, which makes the objects unnecessarily large.

This function, searches folders for files with names matching pattern, loads them one by one if modified before the date.limit, removes the spurious Java wrapper and saves the updated objects into a file with the original name after renaming the original file.

The defaults match the defaults of s_irrad_corected() and acq_irrad_interactive() in the current version of 'ooacquire'. Field w containing the jwrapper is deleted from all spectral objects, and for objects containing spectral data expressed in physical units, also fields related to instrument calibration are deleted. If trim.descriptor = FALSE is passed in the call, deleting the w is the action applied to all objects. Any objects in the loaded files that are not spectral objects or collections of spectral objects are kept unchanged.

Value

A character vector with the paths to the updated files, returned silently. As a side effect files can be saved containing updated objects while keeping original files renamed as backups. By default no files are saved.

Date related uncertainties

The date-based file selection uses file modification time as Windows has an unusual logic for file creation time, resulting in creation times being later than modification time when a file is copied. When attached files are downloaded or when files are downloaded they may get the creation and modification times set to the time of downloading. This is only a speed up for avoiding loading of files. Files containing objects that do not need updating will not be modified even if they are loaded.

Warning!

It is strongly recommended that before committing changes a test is first done to check which files will be updated.

See Also

ls(), and list.files(), which are used to list objects and files, and rm_jwrapper() used to remove the Java wrapper from the instrument descriptor embedded in objects of class generic_spct and derived classes, respectively.

Use function rm_jwrapper() for individual objects in the R workspace.

Other Functions and methods related to instrument descriptors.: files_s_irrad_update(), instr_defaults(), rm_jwrapper(), update_bad_pixs()

Description

Recompute spectral irradiance in source_spct objects stored in .rda files created with acq_irrad_interactive() from earlier versions of 'ooacquire' using the calibrations and methods in the current version of 'ooacquire'.

Usage

files_s_irrad_update(
  path = ".",
  pattern = "\\.spct\\.[Rr]da",
  recursive = TRUE,
  date.limit = NULL,
  spct.names = NULL,
  correction.method = NULL,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = NULL,
  trim.descriptor = TRUE,
  which = NULL,
  which.not = NULL,
  save.files = FALSE,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

Spectral data objects acquired directly from a connected spectrometer with 'ooacquire' contain embedded calibration data and correction algorithms that by default are used when spectral irradiance is computed. In addition, quality control of raw counts data has been enhanced. Function s_irrad_update() uses the current matching descriptor, quality control and conversion default settings.

This function, searches folders for files with names matching pattern, loads them one by one if modified before the date.limit, removes the Java wrapper if present and recomputes spectral irradiance with s_irrad_update() and saves the updated objects into a file with the original name after renaming the original file. If the "raw_mspct" object is not accompanied by a "source_spct" object with a matching name, the file is skipped.

The defaults match the defaults of s_irrad_corrected() and acq_irrad_interactive() in the current version of 'ooacquire'. If spct.names = NULL, the default, is passed, find_spct_names() is called on each raw_mspct object found. Field w containing the jwrapper is deleted from all spectral objects, and for objects containing spectral data expressed in physical units, fields related to instrument calibration are also deleted by default. If trim.descriptor = FALSE is passed in the call, deleting the w is the action applied to all objects.

Value

A character vector with the paths to the updated files, returned silently. As a side effect files can be saved containing updated objects while keeping original files renamed as backups. By default no files are saved.

Date related uncertainties

The date-based file selection uses file modification time as Windows has an unusual logic for file creation time, resulting in creation times being later than modification time when a file is copied. When attached files are downloaded or when files are downloaded they may get the creation and modification times set to the time of downloading. This is only a speed up for avoiding loading of files. Files containing objects that do not need updating will not be modified even if they are loaded.

Warning!

It is strongly recommended that before committing changes a test is first done to check which files will be updated.

See Also

ls(), list.files(), s_irrad_update() which are used to list objects and files, and to update spectral irradiance, respectively.

Use function s_irrad_update() for individual objects in the R workspace.

Other Functions and methods related to instrument descriptors.: files_rm_jwrapper(), instr_defaults(), rm_jwrapper(), update_bad_pixs()

Description

Correct cps readings for stray light, using either measured stray light, or using a non-excited region of the detector array.

Usage

filter_correction(
  x,
  flt,
  stray.light.method = "original",
  stray.light.wl = c(218.5, 228.5),
  flt.dark.wl = c(193, 209.5),
  flt.ref.wl = c(360, 379.5),
  flt.Tfr = 1,
  trim = 0.05,
  filter.nir.adjust = FALSE,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.1),
  verbose = getOption("photobiology.verbose", default = FALSE)
)

no_filter_correction(
  x,
  stray.light.wl = c(218.5, 228.5),
  flt.dark.wl = c(193, 209.5),
  flt.ref.wl = NULL,
  flt.Tfr = 1,
  trim = 0,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.1),
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Description

Find member names matching the different stages of a measurement protocol.

Usage

find_spct_names(
  x,
  qty = "s.irrad",
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

When qty = "irrad" is passed in the call, search for members of x with names containing each of the character strings "dark", "filter", and "light", returning them in a list of character vectors with members named "dark", "filter", and "light". In case of no matching names in x the corresponding member of the returned list is missing. Thus, when no matches are found for any of the three strings, the object returned is list(), the empty list.

When data have been acquired with 'acq_irrad_interactive()' both single and time series measurements and all default protocols are supported when using default measurement protocols or if user created protocols use names that contain suitable matched strings embedded.

When data are imported with 'read_files2mspct()' the names are always set by the user, and for this function to work correctly, the names used must contain suitable matched strings embedded.

When x contains members named not following the convention expected by find_spct_names(), a mapping of member names to protocol steps can be created using a different approach, either manually or in user written code.

Value

A named list of character vectors containing member names for each stage of a measurement protocol.

See Also

Function find_spct_names() is used to set the default argument for formal parameter spct.names in s_irrad_corrected() and s_irrad_update().

Examples

find_spct_names(x = white_grow_LED.raw_mspct)
find_spct_names(x = white_grow_LED.raw_mspct, verbose = TRUE)
find_spct_names(x = sun001.raw_mspct, verbose = TRUE)

Description

Calibration data, descriptors and methods for correction of stray light and high dynamic range based on multiple integrations times per spectrum.

Usage

FLMS00416_descriptors

FLMS00416_cal.spct

FLMS00416_calib_dates.df

FLMS00416_ylianttila.mthd

FLMS00416_sun.mthd

FLMS00416_simple.mthd

FLMS00416_none.mthd

Format

Lists and data frames.

An object of class calibration_spct (inherits from generic_spct, tbl_df, tbl, data.frame) with 2048 rows and 2 columns.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 1 rows and 6 columns.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 11.

Note

Some of the method definitions are fill-ins for methods not implemented. In this case no characterizations of the slit function are available.

See Also

Other objects containing instrument-specific data: FLMS00440_descriptors, FLMS00673_descriptors, FLMS04133_descriptors, JAZA3098_calib_dates.df, MAYP112785_descriptors, MAYP11278_descriptors, MAYP114590_descriptors

Description

Calibration data, descriptors and methods for correction of stray light and high dynamic range based on multiple integrations times per spectrum.

Usage

FLMS00440_descriptors

FLMS00440_cal.spct

FLMS00440_calib_dates.df

FLMS00440_ylianttila.mthd

FLMS00440_sun.mthd

FLMS00440_simple.mthd

FLMS00440_none.mthd

Format

Lists and data frames.

An object of class calibration_spct (inherits from generic_spct, tbl_df, tbl, data.frame) with 2048 rows and 2 columns.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 1 rows and 6 columns.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 11.

Note

Some of the method definitions are fill-ins for methods not implemented. In this case no characterizations of the slit function are available.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00673_descriptors, FLMS04133_descriptors, JAZA3098_calib_dates.df, MAYP112785_descriptors, MAYP11278_descriptors, MAYP114590_descriptors

Description

Calibration data, descriptors and methods for correction of stray light and high dynamic range based on multiple integrations times per spectrum.

Usage

FLMS00673_descriptors

FLMS00673_cal.spct

FLMS00673_calib_dates.df

FLMS00673_ylianttila.mthd

FLMS00673_sun.mthd

FLMS00673_simple.mthd

FLMS00673_none.mthd

Format

Lists and data frames.

An object of class calibration_spct (inherits from generic_spct, tbl_df, tbl, data.frame) with 2048 rows and 2 columns.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 1 rows and 6 columns.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 11.

Note

Some of the method definitions are fill-ins for methods not implemented. In this case no characterizations of the slit function are available.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00440_descriptors, FLMS04133_descriptors, JAZA3098_calib_dates.df, MAYP112785_descriptors, MAYP11278_descriptors, MAYP114590_descriptors

Description

Calibration data, descriptors and methods for correction of stray light and high dynamic range based on multiple integrations times per spectrum.

Usage

FLMS04133_descriptors

FLMS04133_cal.spct

FLMS04133_calib_dates.df

FLMS04133_ylianttila.mthd

FLMS04133_sun.mthd

FLMS04133_simple.mthd

FLMS04133_none.mthd

Format

Lists and data frames.

An object of class calibration_spct (inherits from generic_spct, spec_tbl_df, tbl_df, tbl, data.frame) with 2048 rows and 2 columns.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 1 rows and 6 columns.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 11.

An object of class list of length 11.

Note

Some of the method definitions are fill-ins for methods not implemented. In this case no characterizations of the slit function are available.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00440_descriptors, FLMS00673_descriptors, JAZA3098_calib_dates.df, MAYP112785_descriptors, MAYP11278_descriptors, MAYP114590_descriptors

Description

Package 'ooacquire' includes example data files. Some of these files are in foreign formats, mostly variations of text file formats with raw-counts data obtained with the software from spectrometer manufacturer Ocean Optics.

Details

These files are used in the documentation and for testing file import functions. The files can be also useful when learning to use 'ooacquire'. The collection is incomplete as it covers only a few models of spectrometers. There is some variation in the file format used by Ocean Optics. Please share your files acquired with Ocean Optics spectrometers, especially examples of those that fail to be correctly imported, if you encounter them.

See Also

Package photobiologyInOut supports the import of additional formats, including those acquired with other brands of spectrometers. However, the conversion of raw counts into physical quantities is not directly supported for these other spectrometers.

Examples

# find where the foreign files are installed as part of the package
path <- system.file("extdata", "foreign-files", package = "ooacquire")

# list the files in the folder
list.files(path)

# read the top 20 lines of an example file
readLines(paste(path, "led-light.txt", sep = "/"), n = 20)

Description

Model, configuration, serial number, and calibration data stored in the EEPROM of an Ocean Optics spectrometer are retrieved and returned in a list.

Usage

get_oo_descriptor(
  w,
  sr.index = 0L,
  ch.index = 0L,
  area = NULL,
  diff.type = NULL
)

Arguments

Details

Instrument descriptors are "list" objects with fields describing features of a spectrometer that remain consistent across data acquisition events, including calibration data, entrance optics, serial number, optical configuration, etc. Some of these field can be obtained from the EEPROM inside Ocean Optics spectrometers.

One and only one of area or diff.type is needed if an irradiance calibration stored in the EEPROM is to be retrieved. If both are null, as by default, the irradiance calibration factors will not be retrieved even if present in the EEPROM.

Value

a list

See Also

Other Functions and methods related to instrument descriptors: set_descriptor_bad_pixs(), set_descriptor_entrance_optics(), set_descriptor_integ_time(), set_descriptor_irrad_mult(), set_descriptor_nl(), set_descriptor_wl()

Description

Query the spectrometer for the settings currently in use for corrections, smoothing and acquisition parameters integration time and number of scans.

Usage

get_oo_settings(descriptor)

Arguments

Details

Instrument settings, are settings whose values can vary between data acquisition events. They are stored as a list. The descriptor object is used to access the spectrometer and the currently in use settings are retrieved, formated and returned.

Value

a list

Description

A household Osram tungsten halogen 25W E27 lamp measured at short distance. The spectrometer used was an Ocean Optics Maya2000 Pro.

Usage

halogen.raw_mspct

Format

A raw_mspct

See Also

Other objects containing example raw-counts data: blue_filter.raw_mspct, red_filter.raw_mspct, sun001.raw_mspct, white_grow_LED.raw_mspct, xenon_flash.raw_mspct

Description

Take one set of spectra at high speed using unchanged instrument settings special OmniDriver API functions for buffered acquisition. No HDR bracketing is possible, and synchronization with a pulsed light source is not supported.

Usage

hs_acq_raw_mspct(
  descriptor,
  acq.settings,
  num.spectra = 100L,
  base.name = NULL,
  f.trigger.on = f.trigger.message,
  f.trigger.off = NA,
  what.measured = NA,
  where.measured = data.frame(lon = NA_real_, lat = NA_real_),
  set.all = TRUE,
  verbose = TRUE,
  return.list = FALSE
)

Arguments

Value

A raw_mspct containing one raw_spct object with one column w.length and one column counts for each spectrum. The number of columns with raw counts is always one and integration time bracketing or HDR values in acq.settings are ignored except for the smallest value.

See Also

For normal speed acquisition of a single spectrum and multiple spectra according to a user defined protocol see acq_raw_spct and acq_raw_mspct.

Other raw-counts-spectra acquisition functions: acq_raw_mspct(), acq_raw_spct()

Description

Find default instrument descriptor and correction method based on spectrometer serial number and entrance optics.

Usage

instr_defaults(
  serial_no,
  entrance.optics = "cosine",
  date = lubridate::now(tzone = "UTC"),
  descriptor = NA,
  correction.method = NA
)

default_descriptor(
  serial_no,
  entrance.optics = "cosine",
  date = lubridate::now(tzone = "UTC"),
  descriptor = NA
)

default_method(serial_no, correction.method = NA, descriptor = NA)

Arguments

Details

When protocols or descriptor is not available (NA), the missing value is replaced by a default based on the arguments passed to serial_no, entrance.optics, and protocols.

See Also

Other Functions and methods related to instrument descriptors.: files_rm_jwrapper(), files_s_irrad_update(), rm_jwrapper(), update_bad_pixs()

Examples

str(
  default_descriptor(serial_no = "MAYP114590",
                     date = lubridate::ymd("2020-01-01"))
   )
str(
  default_method(serial_no = "MAYP114590")
   )
str(
  instr_defaults(serial_no = "MAYP114590",
                     date = lubridate::ymd("2020-01-01"))
   )

Description

Compute irradiance or fluence by waveband and energy or photon ratios between wavebands of interest to plants' and human visual responses to light.

Usage

irrad_summary_table(
  mspct,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  scale.factor = ifelse(unit.out == "photon", 1e+06, 1),
  attr2tb = "when.measured",
  summary.type = "plant",
  digits = 3L
)

Arguments

Details

This function packages different functions from pacakge 'photobiology' and returns a typical set of summaries for different purposes.

Value

A tibble with one row per spectrum and one column per summary quantity and attribute and a column with the names of the spectra.

See Also

See the documentation for functions irrad, q_ratio, e_ratio, add_attr2tb, spct_CRI, spct_CCT and signif which are called to build the summary table.

Examples

irrad_summary_table(sun.spct)
irrad_summary_table(sun.spct, attr2tb = c("what.measured", "where.measured"))
irrad_summary_table(sun.spct, summary.type = "plant", unit.out = "photon")
irrad_summary_table(sun.spct, summary.type = "PAR", unit.out = "photon")
# temporary kludge until fixed in photobiologyInOut
# irrad_summary_table(sun.spct, summary.type = "VIS", unit.out = "energy")

Description

Calibration data, descriptors and methods for correction of stray light and high dynamic range based on multiple integrations times per spectrum.

Usage

JAZA3098_calib_dates.df

JAZA3098_ch1_descriptors

JAZA3098_ch1_ylianttila.mthd

JAZA3098_ch1_sun.mthd

JAZA3098_ch1_simple.mthd

JAZA3098_ch1_none.mthd

JAZA3098_ch2_descriptors

JAZA3098_ch2_ylianttila.mthd

JAZA3098_ch2_sun.mthd

JAZA3098_ch2_simple.mthd

JAZA3098_ch2_none.mthd

Format

Lists and data frames.

An object of class list of length 1.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 10.

An object of class list of length 10.

An object of class list of length 1.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 10.

An object of class list of length 10.

Note

Some of the method definitions are fill-ins for methods not implemented. In this case no calibration for spectral irradiance or characterizations of the slit function are available.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00440_descriptors, FLMS00673_descriptors, FLMS04133_descriptors, MAYP112785_descriptors, MAYP11278_descriptors, MAYP114590_descriptors

Description

Uses a function stored as an attribute of x, by default retrieved from the instrument's firmware at the time of data acquisition or possibly a replacement set by the user.

Usage

linearize_counts(
  x,
  force.zero = TRUE,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Value

A raw_spct object containing the adjusted values, still as uncalibrated counts. The object is tagged with the with attribute "linearized" set to the function used for linearization.

Note

In contrast to other classes defined in package 'photobiology', class "raw_spct" can have more than one column of raw counts in cases where the intention is to merge these values as part of the processing at the time the calibration is applied. In other words these columns are not separate observations but instrumental replicates or bracketing readings part of the same "logical" or "effective" observation. The contents of any column whose name starts with "counts" will have the intrument response linearization function applied.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), check_sn_match(), merge_raw_mspct(), new_correction_method(), ref_correction(), trim_counts(), uvb_corrections()

Description

List all connected spectrometers by model name and serial number, plus the number of channels in each of them.

Usage

list_instruments(w)

Arguments

Value

a list

See Also

Other spectrometer-connection functions: end_session(), start_session()

Description

Get list of spectrometers requesting user to connect one or abort if none found.

Usage

list_srs_interactive(w)

Arguments

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Locate in which lines of the file header different metadata features are located. Parsing is needed because the format used varies with among Ocean Optics programs and instruments. Even the number of lines in the header, and the position of the first line with spectral data vary.

Usage

map_oofile_header_rows(lines, header.end = NULL, grammar = oo.minimum.gr)

Arguments

Value

A data frame with two variables, "feature" of class character, and "line.idx" of class integer.

See Also

Other functions for importing spectral data from files: collect_spct_files(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

List of instrument descriptors, each one containing the calibration data needed to convert raw data acquired on different dates. Calibration data from STUK's non-ionising radiation laboratory. Correction method algorithms for stray light and slit function by Lasse Ylianttila, and variations by Pedro J. Aphalo..

Usage

MAYP11278_descriptors

MAYP11278_calib_dates.df

MAYP11278_ylianttila.mthd

MAYP11278_short_flt_ref.mthd

MAYP11278_sun.mthd

MAYP11278_simple.mthd

MAYP11278_none.mthd

Format

Lists and data frames.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 9 rows and 8 columns.

An object of class list of length 11.

An object of class list of length 11.

An object of class list of length 11.

An object of class list of length 11.

An object of class list of length 11.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00440_descriptors, FLMS00673_descriptors, FLMS04133_descriptors, JAZA3098_calib_dates.df, MAYP112785_descriptors, MAYP114590_descriptors

Description

Function to compute the tail correction

Usage

MAYP11278_tail_correction(w_length, cts_second)

Arguments

Value

tail returned as numeric vector within a list.

Tail correction is a reimplementation of the calculations developed by Lasse Ylianttila (STUK, Finland), originally in Excel.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), check_sn_match(), linearize_counts(), merge_raw_mspct(), new_correction_method(), ref_correction(), trim_counts(), uvb_corrections()

Description

List of instrument descriptors, each one containing the calibration data needed to convert raw data acquired on different dates. Calibration data from STUK's non-ionising radiation laboratory. Correction method algorithms for stray light and slit function by Lasse Ylianttila, and variations by Pedro J. Aphalo..

Usage

MAYP112785_descriptors

MAYP112785_calib_dates.df

MAYP112785_ylianttila.mthd

MAYP112785_sun.mthd

MAYP112785_simple.mthd

MAYP112785_none.mthd

Format

Lists and data frames.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 4 rows and 8 columns.

An object of class list of length 11.

An object of class list of length 11.

An object of class list of length 11.

An object of class list of length 11.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00440_descriptors, FLMS00673_descriptors, FLMS04133_descriptors, JAZA3098_calib_dates.df, MAYP11278_descriptors, MAYP114590_descriptors

Description

Function to compute the tail correction

Usage

MAYP112785_tail_correction(w_length, cts_second)

Arguments

Value

tail returned as numeric vector within a list.

Tail correction is a reimplementation of the calculations developed by Lasse Ylianttila (STUK, Finland), originally in Excel.

See Also

Other spectral data-processing functions: MAYP11278_tail_correction(), check_sn_match(), linearize_counts(), merge_raw_mspct(), new_correction_method(), ref_correction(), trim_counts(), uvb_corrections()

Description

List of instrument descriptors, each one containing the calibration data needed to convert raw data acquired on different dates. Calibration data from STUK's non-ionising radiation laboratory. Correction method algorithms for stray light and slit function by Lasse Ylianttila, and variations by Pedro J. Aphalo..

Usage

MAYP114590_descriptors

MAYP114590_cal.spct

MAYP114590_calib_dates.df

MAYP114590_ylianttila.mthd

MAYP114590_sun.mthd

MAYP114590_simple.mthd

MAYP114590_none.mthd

Format

Lists and data frames.

An object of class calibration_spct (inherits from generic_spct, spec_tbl_df, tbl_df, tbl, data.frame) with 2068 rows and 2 columns.

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 1 rows and 7 columns.

An object of class list of length 0.

An object of class list of length 0.

An object of class list of length 12.

An object of class list of length 12.

Note

Some of the method definitions are fill-ins for methods not implemented. In this case no characterization of the slit function is available.

See Also

Other objects containing instrument-specific data: FLMS00416_descriptors, FLMS00440_descriptors, FLMS00673_descriptors, FLMS04133_descriptors, JAZA3098_calib_dates.df, MAYP112785_descriptors, MAYP11278_descriptors

Description

In a cps_spct object with multiple columns of CPS data, each acquired using a different integration time, merge columns into a single column.

Usage

merge_cps(
  x,
  tolerance = 0.05,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

Pixels affected directly, or by neighbourhood, by clipping, should be set to NA in each variable of CPS values, before passing the spectrum as argument to parameter x of this function.

The merging of the CPS variables starts from the one corresponding to the longest integration time, expected to contain the largest number of NA values, by replacing NA values by cps values from the variable corresponding to the next shorter integration. The procedure is repeated until no NA remains or until no shorter integration time data are available. The process stops when all NAs have been replaced, and, even when available, CPS values for unnecesarilly short integration times discarded.

When measuring daylight different exposures for HDR are taken sequentially, and if light conditions change rapidly the cps values may be inconsistent. If the mean ratio of cps values is outside plus/minus the tolerance, instead of merging, the data for the longer of the two exposures is discarded instead of merged (or spliced) with the longer exposure, in which case a message is emitted. Ratio is computed after discarding low signal pixels as these readings are affected by noise, distorting the ratio when the light source-spectrum has only narrow peaks of emission.

Value

a copy of x with values replaced as needed in all counts columns present.

Description

Member spectra are sorted according to integration time stored in the inst.settings attribute and merged into a single raw_spct object with raw counts variables named counts_1, counts_2, etc.

Usage

merge_raw_mspct(x)

Arguments

Note

The individual raw_spct objects contained in x must have identical values in w.length.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), check_sn_match(), linearize_counts(), new_correction_method(), ref_correction(), trim_counts(), uvb_corrections()

Description

A function that builds a default method from an instrument descriptor. Useful when the spectrometers has not been characterized as needed for the more sofisticated methods. Can use stray light correction but not slit function correction. Stray light correction is valid only if it was also used during irradiance callibration. Suitablity of wavelengths and method depends on the instrument configuration so they are set to NA as default..

Usage

new_correction_method(
  descriptor,
  stray.light.method = "none",
  stray.light.wl = c(NA_real_, NA_real_),
  flt.dark.wl = c(NA_real_, NA_real_),
  flt.ref.wl = c(NA_real_, NA_real_),
  flt.Tfr = NA_real_
)

Arguments

Details

The currently recognized methods for stray-light correction are "none", "original", "sun", and "simple". With the default method "none", the values of the remaining parameters are ignored.

Value

a list

Note

Defaults for indexes are for the first channel of the first spectrometer currently connected.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), check_sn_match(), linearize_counts(), merge_raw_mspct(), ref_correction(), trim_counts(), uvb_corrections()

Description

Convert irradiance calibration values as supplied by Ocean Optics into multipliers expressed in the units and format expected by the functions in this package.

Usage

oo_calib2irrad_mult(
  x,
  area = NULL,
  diff.type = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

Ocean Optics expresses spectroradiometer calibrations in a format that is independent of the diffuser user. Such a calibration cannot be used as is, it needs to be scaled based on the effective light collecting surface area of the diffuser used. It is crucial that the correct area or diff.type is entered when calling this function. (This is an unusual approach as there is variation among individual diffusers of a given type. Calibrations are also affected by the optical fibre and even the alignment of the fibre at the spectrometer attachment bulkhead.)

Value

A calibration_spct object of the same number of rows as x containing wavelengths in variable w.length and the re-scaled calibration factors in variable irrad.mult. In practice the calibration_spct object contains one row for each pixel in the detector array of the spectrometer.

Cosine diffusers

Ocean Optics spectrometers can be used with cosine diffusers supplied by Ocean Optics or by third parties. Some diffusers are recognised by name (argument passed to diff.type) while others can be described by their light collecting area expressed in $mm^2$ (argument passed to area). The known cosine diffuser names are tabulated below.

See Also

read_oo_caldata

Description

Ocean Optics files can have varying numbers of rows containing spectral data, but these rows are fenced between two lines containing recognizable character strings. This function, detects these strings.

Usage

oofile_data_rows(lines)

Arguments

Value

integer vector of length two, containing the indexes to the first last rows containing spectral data.

Note

This is a rather slow operation, so if all files to be read have the same format, it is inefficient to call this function for each file.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Package 'ooacquire' includes example data files. R .rda files contain spectral data acquired or imported using 'ooacquire'.

Details

When spectral data are acquired or imported with 'ooacquire' they are stored in classes defined in package photobiology and normally saved as R data files. Examples of these files are used in the documentation and for testing functions designed for data import and conversion of detector-raw-counts into calibrated physical quantityy values. As it is possible to use many of the functions from 'ooacquire' off-line without a live connection to a spectrometer, testing when binaries are built in R-Universe or locally during development is enabled in many cases when no spectromter is attached. The files can be also useful when learning to use 'ooacquire'.

Examples

# find where the R files are installed as part of the package
path <- system.file("extdata", package = "ooacquire")

# list the files in the folder
list.files(path, pattern = "*.Rda$")

# load R objects from the file
## Not run: 
load(paste(path, "sun001.spct.Rda", sep = "/"))
summary(sun001.spct)
summary(sun001.raw_mspct)
## End(Not run)

Description

Read an .Rda file as saved during data acquisition and plot it, possibly first trimming the range of wavelengths and/or smoothing the spectral data.

Usage

plot_spct_file(file, range = NULL, method = NULL, strength = 0, na.rm = FALSE)

Arguments

Note

If the argument passed to method is of length 2, the first member will apply to source_spct objects and the second one to filter_spct and reflector_spct objects. A numeric vector of length 2 passed to strength is treated in the same way. This is only relevant when we are collecting spectra belonging to different classes and need to treat them differently with respect to smoohting. It also allows different defaults, as transmittance spectra tend to lack the fine structure of some emission spectra.

See Also

Function trim_wl is used to trim the range of the data to plot, and function smooth_spct is used for smoothing, and prameters range, and strength and method are passed to them, respectively.

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Choose a protocol by name from a list of protocols, allowing the user to correct the selection if needed. Protocols are not hard-wired, but instead defined by the list passed as argument to protocols.

Usage

protocol_interactive(protocols, default = names(protocols)[[1]])

Arguments

Details

A protocol is defined as a named list of character strings, and consist in multiple acquisition of spectra contributing to the same logical measurement. The name of the list member is the name of the protocol, while the members of each character vector correspond to spectra to be acquired, after some change in the measurement conditions. For example the list list(rsd = c("reference", "sample", "dark"), rs = c("reference", "sample")) defines two protocols.

Value

The member vector corresponding to the protocol selected by the user.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Function used to check the number of pixels that deviate from the median.

Usage

QC_dark(
  x,
  range = NULL,
  tol.margin = 1,
  max.hot = 60,
  max.cold = 20,
  spct.label = "Spectrum",
  verbose = getOption("photobiology.verbose", default = TRUE),
  QC.enabled = getOption("ooacquire.qc.enabled", default = TRUE)
)

Arguments

Details

The expectation is that in a spectrum measured in the dark, to be used as a reference, the variation among pixel counts is small. This also applies in some cases to ranges of pixels protected from radiation by a long pass or short pass filter. By default the whole spectrum is included in the QC check, but if needed an argument can be passed to range to select a smaller region.

Value

A logical value.

Note

Disabling the quality control is necessary 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 illuminations plus the target light source.

Description

Replace data from bad pixels with interpolated values, replace data from saturated and nearby pixels with NAs, apply linearization function if data is not already linearized, optionally use a range of pixels as dark reference, convert the raw counts for each integration time used into counts-per-second, if data from bracketed integration times is available, splice the different spectra.

Usage

raw2corr_cps(x, ref.pixs.range, ...)

## Default S3 method:
raw2corr_cps(x, ref.pixs.range = NULL, ...)

## S3 method for class 'raw_spct'
raw2corr_cps(
  x,
  ref.pixs.range = c(1, 100),
  despike = FALSE,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  ...
)

## S3 method for class 'raw_mspct'
raw2corr_cps(x, ref.pixs.range = c(1, 100), despike = FALSE, ...)

Arguments

Value

a cps_spct object with one spectrum preserving the metadata present in x.

Methods (by class)

• raw2corr_cps(default): Default method

• raw2corr_cps(raw_spct): raw_spct method

• raw2corr_cps(raw_mspct): raw_spct method

See Also

despike()

Other functions for conversion of raw-counts data: raw2cps(), s_fraction_corrected(), s_irrad_corrected(), s_irrad_update()

Description

These functions simply divide "raw counts" by the integration time used for acquisition.

Usage

raw2cps(x, ...)

## Default S3 method:
raw2cps(x, ...)

## S3 method for class 'raw_spct'
raw2cps(x, ...)

## S3 method for class 'raw_mspct'
raw2cps(x, ...)

Arguments

Value

an object of class "cps_spct"

an object of class "cps_mspct"

Methods (by class)

• raw2cps(default): Default method

• raw2cps(raw_spct): Method for spectral data expressed as raw instrument counts.

• raw2cps(raw_mspct): Method for collections of raw-counts spectra

Note

In the case of objects of class "raw_spct" the columns with names starting with "counts" are processed and renamed to columns with names starting with "cps". All other columns are left unchanded.

See Also

Other functions for conversion of raw-counts data: raw2corr_cps(), s_fraction_corrected(), s_irrad_corrected(), s_irrad_update()

Description

Read multiple files and return a collection of raw spectra as a raw_spct object.

Usage

read_files2mspct(files, read.f = ooacquire::read_oo_data, ...)

Arguments

Note

Depending of the function passed to read.f more or less complete metadata information will be stored as attributes in the raw_spct objects.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Reads a calibration data file as supplied by Ocean Optics. Wavelength and calibration values are stored as data and the metadata parsed from the header or supplied as arguments as attributes of the same object, including the time and date of the calibration. The whole file header is in addition stored as a comment.

Usage

read_oo_caldata(
  file,
  time = NULL,
  geocode = NULL,
  label = NULL,
  descriptor = NULL,
  tz = NULL,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

The format of the data used by Ocean Optics seems to have remained consistent in time and with spectrometer model, but not the header. In particular, the format of the date and whether time is included or not varies. The function is able to decode three different date formats that I have come across. If decoding fails with a message indicating that parsing has failed, the problem can be overcome by passing the date as an argument to parameter time when calling the function, as in this case no decoding of the date is attempted. The easiest approach is to use function dmy or similar from package 'lubridate'. When no time zone information is included in the file header, the local time zone is used, which in many cases will shift the date by one day. If you know where the calibration was done, the correct TZ can be passed as an argument. Anyway as calibrations are usually considered valid for one or two years, this shift is only rarely important,

Value

A generic_spct object, with columns w.length and oo.cal.

See Also

oo_calib2irrad_mult

Description

Reads and parses the header of a processed data file as output by SpectraSuite to extract the whole header remark field. The time field is retrieved and decoded.

Usage

read_oo_data(
  file,
  time = NULL,
  geocode = NULL,
  label = NULL,
  descriptor = NULL,
  tz = NULL,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Value

A raw_spct object.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Reads and parses the header of a processed data file as output by OceanView to extract the whole header remark field. The time field is retrieved and decoded.

Usage

read_oo_ovdata(
  file,
  time = NULL,
  geocode = NULL,
  label = NULL,
  descriptor = NULL,
  tz = NULL,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Value

A raw_spct object.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Reads and parses the header of a raw data file as output by the server running on a Raspberry Pi board to extract the whole header remark field. The time field is retrieved and decoded.

Usage

read_oo_pidata(
  file,
  date = NULL,
  geocode = NULL,
  label = NULL,
  tz = NULL,
  locale = readr::default_locale(),
  descriptor = NULL,
  corr.sensor.nl = FALSE,
  spectrometer.name = "Unknown via Raspberry Pi",
  spectrometer.sn = "Unknown via Raspberry Pi",
  npixels = 2048
)

Arguments

Value

A raw_spct object.

Note

The header in these files has very little information, so the user needs to supply the number of pixels in the array as well as the date-time. The file contains a date in milliseconds but as the Raspberry Pi board contains no real-time clock, it seems to default to number of milliseconds since the Pi was switched on.

References

http://www.r4photobiology.info

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_ssdata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

Reads and parses the header of a processed data file as output by SpectraSuite to extract the whole header remark field. The time field is retrieved and decoded.

Usage

read_oo_ssdata(
  file,
  time = NULL,
  geocode = NULL,
  label = NULL,
  descriptor = NULL,
  tz = NULL,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Value

A raw_spct object.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), set_oo_ssdata_descriptor(), set_oo_ssdata_settings()

Description

A red long-pass filter from Heliopan (695 nm) measured using a household incandescent lamp as light source. The spectrometer used was an Ocean Optics Maya2000 Pro.

Usage

red_filter.raw_mspct

Format

A raw_mspct

See Also

Other objects containing example raw-counts data: blue_filter.raw_mspct, halogen.raw_mspct, sun001.raw_mspct, white_grow_LED.raw_mspct, xenon_flash.raw_mspct

Description

These functions simply subtract (by default) detector counts data (raw or cps) of one spectrum by the corresponding columns in another spectrum, or apply a user supplied operator or function to them.

Usage

ref_correction(x, y, .oper, ...)

## Default S3 method:
ref_correction(x, y, .oper, ...)

## S3 method for class 'numeric'
ref_correction(x, y, .oper = `-`, ...)

## S3 method for class 'raw_spct'
ref_correction(x, y, .oper = `-`, ...)

## S3 method for class 'cps_spct'
ref_correction(x, y, .oper = `-`, ...)

## S3 method for class 'cps_mspct'
ref_correction(x, y = x, .oper = `-`, ref_name = "dark", ...)

Arguments

Value

a numeric vector of the same length as x

an object of class "cps_spct"

an object of class "cps_spct"

an object of class "cps_mspct"

Methods (by class)

• ref_correction(default): Default method

• ref_correction(numeric): Numeric method

• ref_correction(raw_spct): Method for spectral data expressed as raw instrument counts.

• ref_correction(cps_spct): Method for spectral data expressed as counts per second.

• ref_correction(cps_mspct): Method for collections of spectral data objects containing data expressed as counts per second.

Note

In the case of objects of class "raw_spct" the columns with names starting with "counts" are processed. All other columns are left unchanded.

If x and y are both cps_mspct objects, y[[ref_name]] will be used as reference, otherwise y itself should be a cps_spct and will be used as is. In all cases variables in ref.name will be skipped in x.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), check_sn_match(), linearize_counts(), merge_raw_mspct(), new_correction_method(), trim_counts(), uvb_corrections()

Description

Clean up left-behind wrappers used to communicate with Java code using 'rJava'.

Usage

rm_jwrapper(x, verbose = getOption("photobiology.verbose", default = FALSE))

Arguments

Details

Field w contains a wrapper on a Java object used to communicate with the OmniDriver driver during data acquisition. Once the current connection between R and a spectrometer ends, these wrappers are invalidated, becoming useless. However, if present they create a dependency on 'rJava', possibly triggering errors. In recent versions of 'ooacquire' this wrapper is removed immediately after acquisition. However, the instrument descriptor of spectral objects created with versions of 'ooacquire' from some years ago can contain a member storing the useless Java wrapper. This function removes this field if present.

Method getInstrDesc() removes member field w from the returned value but does not modify its argument, it returns the modified object.

Value

a copy of x possibly with field "w" removed, if present, from the embedded instr.desc attribute of spectral objects.

See Also

Use function files_rm_jwrapper() to apply function rm_jwrapper() to objects stored in .rda files,

Other Functions and methods related to instrument descriptors.: files_rm_jwrapper(), files_s_irrad_update(), instr_defaults(), update_bad_pixs()

Description

Convert raw counts data into spectral transmittance or spectral reflectance.

Usage

s_fraction_corrected(x, ...)

## Default S3 method:
s_fraction_corrected(x, ...)

## S3 method for class 'list'
s_fraction_corrected(
  x,
  reference.value = 1,
  type = "internal",
  time = NULL,
  correction.method,
  qty.out = "Tfr",
  descriptor = NULL,
  dyn.range = NULL,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

## S3 method for class 'raw_mspct'
s_fraction_corrected(
  x,
  spct.names = c(sample = "sample", reference = "reference", dark = "dark"),
  reference.value = 1,
  type = switch(qty.out, Tfr = "internal", Rfr = "total"),
  correction.method,
  dyn.range = NULL,
  qty.out = "Tfr",
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

Arguments

Methods (by class)

• s_fraction_corrected(default): Default for generic function.

• s_fraction_corrected(list): Default for generic function.

• s_fraction_corrected(raw_mspct): Default for generic function.

Note

Currently s_fraction_corrected.list allows processing of files written by OceanOptics' SpectraSuite software, from protocols with integration-time bracketing or not, with a dark reference measurement or not. Four measurements components are recognized: a "sample" measurement, a "referenece" measurement using a clear or white, a "filter" measurement with a UV-blocking filter in the light pass, and a "dark" measurement. Only "sample" and "reference" are mandatory. Data should be raw counts, either corrected for detector non-linearity or not. All three spectra should be acquired using the same instrument settings to achieve good accuracy.

See Also

Other functions for conversion of raw-counts data: raw2corr_cps(), raw2cps(), s_irrad_corrected(), s_irrad_update()

Description

Convert raw counts data into spectral irradiance or fluence

Usage

s_irrad_corrected(x, ...)

## Default S3 method:
s_irrad_corrected(x, ...)

## S3 method for class 'list'
s_irrad_corrected(
  x,
  time = NULL,
  correction.method = NULL,
  filter.nir.adjust = FALSE,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = FALSE,
  trim.descriptor = !return.cps,
  descriptor,
  locale = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

## S3 method for class 'raw_mspct'
s_irrad_corrected(
  x,
  spct.names = find_spct_names(x),
  correction.method = NULL,
  filter.nir.adjust = FALSE,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = FALSE,
  trim.descriptor = !return.cps,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

## S3 method for class 'raw_spct'
s_irrad_corrected(
  x,
  time = NULL,
  correction.method,
  filter.nir.adjust = FALSE,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = FALSE,
  trim.descriptor = !return.cps,
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

Arguments

Details

When raw data are acquired with function acq_irrad_interactive() the raw-counts are returned in an object of class raw_mspct. The embedded metadata include the wavelength calibration, irradiance calibration, and spectrometer settings used to acquire the data. The specialization s_irrad_corrected.raw_mspct() uses these metadata to compute spectral irradiance.

The specialization s_irrad_corrected.list allows processing of files written by Ocean Optics' SpectraSuite software. Some of the metadata can be extracted from file headers, but other, such as the calibration data cannot. Based on the date of data acquisition and instrument serial number a matching calibration is searched for and must be available.

Value

A source_spct or a cps_spct object.

Methods (by class)

• s_irrad_corrected(default): Default for generic function.

• s_irrad_corrected(list): Default for generic function.

• s_irrad_corrected(raw_mspct): Default for generic function.

• s_irrad_corrected(raw_spct): Default for generic function.

Computation of spectral irradiance

Method s_irrad_corrected() computes spectral irradiance from raw detector counts from an Ocean Optics spectrometer. Function s_irrad_update() calls s_irrad_corrected() on a copy of x with its calibration data updated.

Depending on both the calibration data and the raw-counts data available different corrections can be applied. Raw counts data can be acquired using different protocols, and which one was used limits what corrections are applicable. If return.cps = TRUE is passed, then counts-per-second are computed instead of irradiances, applying only the wavelength calibration.

The supported protocols include single-integration time and integration-time bracketing, a dark reference measurement or use of dark sensor pixels, and a filter measurement to correct for stray light in the UV region or not. A correction for the slit function is applied non-recursively if included in the calibration.

Three measurement events are recognized: a "light" measurement, a "filter" measurement using a polycarbonate filter and a dark measurement. Only the "light" measurement is mandatory. All three measurements should have been acquired with exactly the same settings in the spectrometer, with the same instrument, and close enough in time to avoid background signal drift due to temperature changes.

The returned object is by default a source_spct object as long as spectrometer calibration data are available, and a cps_spct object otherwise. It is possible to force the return of a cps_spct object.

Passing trim.descriptor = TRUE ensures that the data objects returned are significantly smaller in size as calibration data are removed. By default, the descriptor is trimmed when the returned object is a 'source_spct' object and not trimmed when the returned object is a 'cps_spct'.

See Also

Other functions for conversion of raw-counts data: raw2corr_cps(), raw2cps(), s_fraction_corrected(), s_irrad_update()

Examples

s_irrad_corrected(x = white_grow_LED.raw_mspct)

Description

Compute spectral irradiance using the instrument descriptor for the same spectrometer and date of measurement from the current version of 'ooacquire' rather than that available at the time when raw data were acquired.

Usage

s_irrad_update(
  x,
  y = NULL,
  spct.names = find_spct_names(x),
  correction.method = NULL,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  return.cps = NULL,
  trim.descriptor = NULL,
  which = NULL,
  which.not = NULL,
  verbose = getOption("photobiology.verbose", default = FALSE)
)

Arguments

Details

When raw counts data are acquired with acq_irrad_interactive() or imported from text files from other software the calibration information is stored together with the data. When computing spectral irradiance with function s_irrad_corrected() at any later time, this stored calibration data are the ones used. This approach ensures reproducibility as calibrations can be, and have been, retrospectively modified when 'ooacquire' is updated. In most cases the updates have only added information about "hot" and "dead" pixels. However, in one case the range of the calibration data included was incomplete, and later expanded. These changes can be important in some cases, making it necessary or preferable to use the updated calibrations when computing spectral irradiance.

In s_irrad_update() the instr.desc attribute in x is matched based on spectrometer serial number, date and entrance optics to the possibly updated version of the same calibration data in the current version of 'ooacquire'. The instrument descriptor is replaced in a local copy of x and this local copy used to compute spectral irradiance with s_irrad_corrected(), without altering x. Explicit arguments passed to parameters in the call to s_irrad_update() are used in the call to s_irrad_corrected(), however, defaults are in some cases different.

If an argument is passed to parameter y and the value of the spectrometer serial number attributes match between x and y, default arguments for return.cps and correction.method are based on metadata from y. In this case attributes unrelated to to those in the raw data or their conversion, possibly added or modified after y was computed, are copied to the returned source_spct object using method copy_attributes() passing which and which.not in the call. This creates, as close as possible an updated version of y. Attributes "instr.desc", "instr.settings", "when.measured" and several others set by s_irrad_corrected() are never updated in the returned value to ensure they remain valid. Other attributes including "what.measured", "where.measured", "how.measured", "comment", are copied by default. If names are passed in an argument to which only these attributes are copied, with user-set attributes allowed. However, exclusion of attributes named in the union of the argument passed to which.not and those not excluded by default takes precedence.

Value

A source_spct or a cps_spct object.

Computation of spectral irradiance

Method s_irrad_corrected() computes spectral irradiance from raw detector counts from an Ocean Optics spectrometer. Function s_irrad_update() calls s_irrad_corrected() on a copy of x with its calibration data updated.

Depending on both the calibration data and the raw-counts data available different corrections can be applied. Raw counts data can be acquired using different protocols, and which one was used limits what corrections are applicable. If return.cps = TRUE is passed, then counts-per-second are computed instead of irradiances, applying only the wavelength calibration.

The supported protocols include single-integration time and integration-time bracketing, a dark reference measurement or use of dark sensor pixels, and a filter measurement to correct for stray light in the UV region or not. A correction for the slit function is applied non-recursively if included in the calibration.

Three measurement events are recognized: a "light" measurement, a "filter" measurement using a polycarbonate filter and a dark measurement. Only the "light" measurement is mandatory. All three measurements should have been acquired with exactly the same settings in the spectrometer, with the same instrument, and close enough in time to avoid background signal drift due to temperature changes.

The returned object is by default a source_spct object as long as spectrometer calibration data are available, and a cps_spct object otherwise. It is possible to force the return of a cps_spct object.

Passing trim.descriptor = TRUE ensures that the data objects returned are significantly smaller in size as calibration data are removed. By default, the descriptor is trimmed when the returned object is a 'source_spct' object and not trimmed when the returned object is a 'cps_spct'.

Note

Entrance optics metadata have been saved in the instrument descriptor only since 'ooacquire' (>= 0.5.3) and correction method only from 'ooacquire' (>= 0.5.6).

See Also

copy_attributes()

Other functions for conversion of raw-counts data: raw2corr_cps(), raw2cps(), s_fraction_corrected(), s_irrad_corrected()

Examples

# only metadata from x and the new descriptor
s_irrad_update(x = white_grow_LED.raw_mspct)

Description

Allow user to provide values for "user supplied" attribute values "comment" and "what.measured".

Usage

set_attributes_interactive(
  user.attrs = list(what.measured = "", comment.text = "")
)

Arguments

Value

a named list of character vectors.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

A integer vector of indexes to bad pixels in the instrument array is stored in the instrument descriptor.

Usage

set_descriptor_bad_pixs(descriptor, bad.pixs)

update_spct_bad_pixs(spct, bad.pixs)

update_mspct_bad_pixs(mspct, bad.pixs)

Arguments

Details

When a descriptor contains indexes to bad pixels, data from these array pixels will is replaced by interpolation when a acquired data is converted into physical units. Although the indexes to bad pixels are normally set when a new calibration is stored in a descriptor, new bad pixels can develop later or some bad pixels can be identified at a later time even if present. The current method is used when creating a descriptor but it is also useful when a descriptor needs to be updated.

Value

A copy of the argument passed to descriptor, spct or mspct with the descriptor with indexes to bad pixels set to the new values.

Note

Following R's syntax the first pixel in the detector array has index 1.

See Also

Other Functions and methods related to instrument descriptors: get_oo_descriptor(), set_descriptor_entrance_optics(), set_descriptor_integ_time(), set_descriptor_irrad_mult(), set_descriptor_nl(), set_descriptor_wl()

Description

Replace or add a description of the fibre and diffuser or other entrance optics to the instrument descriptor.

Usage

set_descriptor_entrance_optics(
  descriptor,
  make = NA_character_,
  model = NA_character_,
  geometry = NA_character_,
  serial.number = NA_character_,
  area = NA_real_
)

Arguments

Value

a copy of the argument passed for oo_descriptor with the entrance.optics field of the calibration data adde or replace by the new list.

See Also

Other Functions and methods related to instrument descriptors: get_oo_descriptor(), set_descriptor_bad_pixs(), set_descriptor_integ_time(), set_descriptor_irrad_mult(), set_descriptor_nl(), set_descriptor_wl()

Description

This function can be needed in exceptional cases such as when the limits stored in the intrument's persistent memory are wrong. In other cases it can be used to restrict the range of values allowed to be set to a smaller range than natively supported by the spectrometer.

Usage

set_descriptor_integ_time(
  descriptor,
  min.integ.time = NA_integer_,
  max.integ.time = NA_integer_,
  force.change = FALSE
)

Arguments

Value

a copy of the argument passed for oo_descriptor with the integration time fields of the descriptor modified.

Note

This function should not be needed, but for some instruments the query may fail or return the wrong value. Values should be within the range in the instrument's specifications. Setting wrong values can result in invalid data without an error being triggered.

See Also

Other Functions and methods related to instrument descriptors: get_oo_descriptor(), set_descriptor_bad_pixs(), set_descriptor_entrance_optics(), set_descriptor_irrad_mult(), set_descriptor_nl(), set_descriptor_wl()

Description

Adds calibration data expressed as multipliers for each pixel stored in a numeric vector.

Usage

set_descriptor_irrad_mult(
  descriptor,
  irrad.mult,
  wl.range = NULL,
  start.date = lubridate::today(tzone = "UTC") - lubridate::days(1),
  end.date = lubridate::today(tzone = "UTC") + lubridate::days(1),
  cal.source = "unknown"
)

Arguments

Value

A copy of the argument passed for oo_descriptor with the irrad.mult field of the calibration data replaced by the new values.

See Also

Other Functions and methods related to instrument descriptors: get_oo_descriptor(), set_descriptor_bad_pixs(), set_descriptor_entrance_optics(), set_descriptor_integ_time(), set_descriptor_nl(), set_descriptor_wl()

Description

Uses a user supplied function, possibly that supplied by a manufacturer like Ocean Optics stored in firmware or in any other form.

Usage

set_descriptor_nl(descriptor, nl.coeff = NA_real_, nl.fun = NULL)

Arguments

Value

A copy of the argument passed for oo_descriptor with the wavelengths field of the calibration data replaced by the new values.

See Also

Other Functions and methods related to instrument descriptors: get_oo_descriptor(), set_descriptor_bad_pixs(), set_descriptor_entrance_optics(), set_descriptor_integ_time(), set_descriptor_irrad_mult(), set_descriptor_wl()

Description

Replace wavelength values in an instrument descriptor for an Ocean Optics spectrometer with new values. (e.g. when wavelength calibration is not stored in firmware).

Usage

set_descriptor_wl(descriptor, wl)

Arguments

Value

a copy of the argument passed for oo_descriptor with the wavelengths field of the calibration data replaced by the new values.

See Also

Other Functions and methods related to instrument descriptors: get_oo_descriptor(), set_descriptor_bad_pixs(), set_descriptor_entrance_optics(), set_descriptor_integ_time(), set_descriptor_irrad_mult(), set_descriptor_nl()

Description

Enter values for "user supplied" folder.

Usage

set_folder_interactive(folder.name = NULL)

Arguments

Details

If the requested folder does not already exist it will be created. The name of the folder is returned, but NOT set as working directory.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Model and serial number are retrieved from the file header, the remaining unknown parameter values are set to NA. These values are used to set the "inst.desc" atrribute of x.

Usage

set_oo_ssdata_descriptor(
  x,
  file.header = comment(x),
  descriptor = photobiology::getInstrDesc(x),
  action = "merge"
)

Arguments

Value

A copy of x with updated attributes.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_settings()

Description

Parse the header of the file returned by SpectraSuite for corrections, smoothing and acquisition parameters used. These values are used to set the "inst.settings" attribute of x.

Usage

set_oo_ssdata_settings(x, file.header = comment(x), overwrite = TRUE)

Arguments

Value

A copy of x with updated attributes.

See Also

Other functions for importing spectral data from files: collect_spct_files(), map_oofile_header_rows(), oofile_data_rows(), plot_spct_file(), read_files2mspct(), read_oo_data(), read_oo_ovdata(), read_oo_pidata(), read_oo_ssdata(), set_oo_ssdata_descriptor()

Description

Enter settings defining a sequence of spectra to be measured as a time series.

Usage

set_seq_interactive(
  seq.settings = NULL,
  measurement.duration = 0,
  minimum.step.delay = measurement.duration,
  time.division = 0
)

check_seq_settings(seq.settings = NULL)

Arguments

Details

In a sequence, measurements share a single reference, filter and/or dark scan, and are acquired as a sequence. For "sequences" of any length, including single spectra, the initial delay or time unit boundary can be used to schedule the start of a sequence of measurements or a single measurement. Using a step multiplier, it is possible to automatically generate time steps that increase in length exponentialy.

Function set_seq_interactive() allows users to change values in the list seq.settings(), which to define a sequence of spectral acquisitions. These are the time unit boundary to synchronize to, the delay or duration of the time step between successive acquisitions and the number of acquisitions in the series. The measurement.time determines the minimum length for "step".

Function check_seq_interactive() checks the validity, fills incomplete list with defaults and expands the time steps into a sequence based on fields step.multiplier and num.steps, resetting step.multiplier = 1.

Value

A named numeric vector of length two.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Enter values for "session" name.

Usage

set_session_name_interactive(session.name = NULL)

Arguments

Details

Validate seesionr name, and allow user to change the default.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_user_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Enter values for "user supplied" name.

Usage

set_user_name_interactive(user.name = NULL)

Arguments

Details

Validate user name, and allow user to change the default.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_wlrange_interactive(), tune_interactive()

Description

Replace bad pixels with the average of the counts from the two neighbouring pixels.

Usage

skip_bad_pixs(x)

Arguments

Value

a copy of x with values replaced as needed in all counts columns present.

Description

Open a connection to the first spectrometer found and initialize an object with a reference to the Java object returned by Omni Driver.

Usage

start_session(error.action = stop)

Arguments

Value

On success a java wrapper which allows access to the driver with an open connection to the instrument.

See Also

Other spectrometer-connection functions: end_session(), list_instruments()

Description

Solar radiation at ground level measured in Helsinki Finland. The spectrometer used was an Ocean Optics Maya2000 Pro.

Usage

sun001.raw_mspct

Format

A raw_mspct

See Also

Other objects containing example raw-counts data: blue_filter.raw_mspct, halogen.raw_mspct, red_filter.raw_mspct, white_grow_LED.raw_mspct, xenon_flash.raw_mspct

Description

Compute transmittance by waveband of interest to plants' and human visual responses to light.

Usage

Tfr_summary_table(
  mspct,
  quantity = "average",
  attr2tb = "when.measured",
  summary.type = "VIS",
  digits = 3L
)

Arguments

Details

This function calls different functions from package 'photobiology' and returns a typical set of summaries.

Value

A tibble with one row per spectrum and one column per summary quantity and attribute and a column with the names of the spectra.

See Also

See the documentation for functions transmittance, add_attr2tb and signif which are called to build the summary table.

Examples

Tfr_summary_table(yellow_gel.spct)
Tfr_summary_table(yellow_gel.spct, attr2tb = c("what.measured", "where.measured"))
Tfr_summary_table(yellow_gel.spct, summary.type = "plant")
Tfr_summary_table(yellow_gel.spct, summary.type = "PAR")
Tfr_summary_table(yellow_gel.spct, summary.type = "VIS")

Description

Trim out-of-range counts values in data stored in a "raw_spct" object. The values are replaced with the supplied fill value.

Usage

trim_counts(x, range = c(NA, getInstrDesc(x)[["max.counts"]] - 1), fill = NA)

Arguments

Value

a copy of x with values replaced as needed in all counts columns present.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), check_sn_match(), linearize_counts(), merge_raw_mspct(), new_correction_method(), ref_correction(), uvb_corrections()

Description

Adjust integration time settings, allowing the user to repeat the tuning, and to change some of the parameters used for tuning such as total compound integration time and integration time bracketing.

Usage

tune_interactive(
  descriptor,
  acq.settings,
  start.int.time = 0.1,
  interface.mode = "auto"
)

Arguments

Details

This function implements three different user interfaces: 1) "simple" is an interface suitable for the most usual measurements using automatic tuning of integration time and hides some of the less frequently used options, 2) "auto" gives access to all available options offering maximum flexibility when using automatic tuning of integration time, and 3) "manual" supports use of fixed integration times directly entered by the user.

Tuning of the integration time takes into account the range of times supported by the connected instrument, read from the instrument descriptor. The algorithm also makes use of the linearisation function when extrapolating to guess the integration time needed. Initial (default) values are read from acq.settings while start.int.time provides a default starting value for integration time for tuning when the user chooses not to use the value stored in acq.settings.

See Also

Other interactive acquisition utility functions: choose_ch_interactive(), choose_sr_interactive(), f.trigger.message(), list_srs_interactive(), protocol_interactive(), set_attributes_interactive(), set_folder_interactive(), set_seq_interactive(), set_session_name_interactive(), set_user_name_interactive(), set_wlrange_interactive()

Description

Update field bad.pixs of the instrument descriptor embedded in raw_spct and raw_mspct objects.

Usage

update_bad_pixs(x, bad.pixs = NULL, action = "replace")

Arguments

Details

Spectral objects, including those with raw counts data can contain an instrument descriptor. One member of this attribute is a vector of indexes to bad pixels. New bad pixels can be identified in some cases after data are acquired. Recomputing of physical quantities from raw counts normally reuses the embedded calibration data. Function update_bad_pixs() makes it possible to update the embedded bad pixels information before recomputing derived quantities. This function can be applied only to raw_spct objects created with functions from package 'ooacquire'.

With defaults arguments for formal parameters bad.pixs and action, the bad.pixs field of the descriptor is updated to match that in the matching calibration data in the version of 'ooacquire' currently loaded. However, if a numeric vector to positions in the detector array is passed as argument, depending on the argument passed to action, this vector will be used either to replace the existing one, or the indexes in the vector "added" to those already stored, using union().

Value

a copy of x with an updated instr.desc attribute embedded.

Note

Only objects of class raw_spct, individually or as members of a raw_mspct object, are supported as the update must precede any conversion into physical units, and will propagate to returned values when computations are applied to the updated raw_spct objects.

See Also

Other Functions and methods related to instrument descriptors.: files_rm_jwrapper(), files_s_irrad_update(), instr_defaults(), rm_jwrapper()

Description

Update the instrument descriptor embedded in raw_spct and raw_mspct objects.

Usage

update_instr_desc(x, which.descriptor.args = list())

Arguments

Details

Recomputing of physical quantities from raw counts normally reuses the embedded calibration data in raw_spct objects. Function update_inst_desc() makes it possible to update the embedded calibration before recomputing derived quantities.

Spectral objects, including those with raw counts data contain an instrument descriptor when measured or imported using functions from 'ooacquire'. The descriptor can include calibration data as well as details of the instrument used. If a calibration has been retroactively modified after data acquisition, the descriptor can be refreshed in existing raw_spct or raw_mspct objects. By default the the version of the new descriptor is that in the loaded version of 'ooacquire', corresponding to the same instrument, data acquisition date and entrance optics.

If for some reason, an instrument descriptor for the wrong spectrometer, the wrong entrance optics or for a wrong data acquisition date, a non-matching replacement can be used by passing suitable arguments through parameter which.descriptor.arg. See which_descriptor() for the details.

Value

a copy of x with an updated instr.desc attribute embedded.

Warning!

This function is intended only to repair objects that have corrupted information. Typical cases are acquisition using a computer with wrong date settings, unrecognized instrument serial number, or measurements done before the valid calibration was added to 'ooacquire'.

The special case when the only change to the calibration is adding newly identified bad pixels in the sensor array, function update_bad_pixs provides a "light weight" alternative.

Note

The replacement of the instrument descriptor is not supported for spectral data not expressed as raw counts, because this would create an inconsistency between the computed data and its metadata. To achieve such a change data in physical units have to be recomputed from raw instrument counts after updating the object containing the raw detector counts.

Description

Apply to a counts-per-second spectrum corrections based of a paired reading obtained with a polycarbonate filter (long-pass with cut-in at 400 nm). This is a bit more sophisticated than simple subtracting the filter reading from the measurement as the effect of the filter itself on stray light is corrected for.

Usage

uvb_corrections(
  x,
  spct.names = c(light = "light", filter = "filter", dark = "dark"),
  stray.light.method = "original",
  stray.light.wl = c(218.5, 228.5),
  flt.dark.wl = c(193, 209.5),
  flt.ref.wl = c(360, 379.5),
  flt.Tfr = 0.9,
  inst.dark.pixs = 1:4,
  worker.fun = NULL,
  trim = 0.05,
  filter.nir.adjust = FALSE,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

slit_function_correction(
  x,
  worker.fun = NULL,
  hdr.tolerance = getOption("ooacquire.hdr.tolerance", default = 0.05),
  verbose = getOption("photobiology.verbose", default = FALSE),
  ...
)

Arguments

Value

A cps_spct object with the corrected count-per-second values in coulmn "cps".

Note

stray.light.method = "none" is a valid argument only for function uvb_corrections(). The default worker.fun is just an example. Corrections are specific to each individual spectrometer unit (not just type or configuration) and code needs to be written for most individual use cases. The slit function tail correction requires the characterization of the shape of the slit function by measuring one or more laser beams at suitable wavelengths.

Author(s)

Algorithm for method "original" developed by Lasse Ylianttila. Other methods are modified from Ylianttila's method by Pedro J. Aphalo.

See Also

Other spectral data-processing functions: MAYP112785_tail_correction(), MAYP11278_tail_correction(), check_sn_match(), linearize_counts(), merge_raw_mspct(), new_correction_method(), ref_correction(), trim_counts()

Description

Select from a list of instrument descriptors which one to use based on date of measurement.

Usage

which_descriptor(
  date = lubridate::now(tzone = "UTC"),
  descriptors = ooacquire::MAYP11278_descriptors,
  verbose = getOption("photobiology.verbose", TRUE),
  strict.calib = getOption("photobiology.strict.calib", FALSE),
  entrance.optics = NULL,
  ...
)

Arguments

Details

Calibrations for instruments stored in a list and passed as argument to descriptors, also store the dates between which they are valid. This function walks the list searching for a calibration valid for date. If no valid calibration is found and strict.calib = FALSE, the calibration valid closest in time is returned with a warning while if no valid calibration is found and strict.calib = TRUE an error is triggered.

If a character string is passed as argument to date, it must be in a format suitable for anytime::anydate(). One needs to be careful with months and days of the month when supplying them as numbers, so using months names or their abbreviations can be safer.

Note

The default argument for verbose is for this function TRUE as conversion of other objects to a date may fail.

Examples

d1 <- which_descriptor()
d1$spectrometer.sn
d1$entrance.optics$geometry

d2 <- which_descriptor(entrance.optics = "hemispherical")
d2$spectrometer.sn
d2$entrance.optics$geometry

d3 <- which_descriptor(descriptors = ooacquire::MAYP112785_descriptors)
d3$spectrometer.sn
d3$entrance.optics$geometry

# gives error, as expected
# which_descriptor(descriptors = ooacquire::MAYP112785_descriptors,
#                  entrance.optics = "hemispherical")

# gives error
# which_descriptor(date = lubridate::now() + lubridate::years(1))

Description

A zhaga standard module with Nichia "horticulture" LEDs measured at short distance. The spectrometer used was an Ocean Optics Maya2000 Pro.

Usage

white_grow_LED.raw_mspct

Format

A raw_mspct

See Also

Other objects containing example raw-counts data: blue_filter.raw_mspct, halogen.raw_mspct, red_filter.raw_mspct, sun001.raw_mspct, xenon_flash.raw_mspct

Description

A photography flash Godox AD200 with a bare lamp in a head with a reflector fitted. The spectrometer used was an Ocean Optics Maya2000 Pro.

Usage

xenon_flash.raw_mspct

Format

A raw_mspct

See Also

Other objects containing example raw-counts data: blue_filter.raw_mspct, halogen.raw_mspct, red_filter.raw_mspct, sun001.raw_mspct, white_grow_LED.raw_mspct