AFL.automation.instrument.SeabreezeUVVis#

Driver for Ocean Optics UV-Vis spectrometers supported by SeaBreeze.

Classes

Driver(name[, defaults, overrides, ...])

Path(*args, **kwargs)

PurePath subclass that can make system calls.

Real()

To Complex, Real adds the operations that work on real numbers.

SeabreezeUVVis([backend, device_serial, ...])

Collect spectra from a SeaBreeze-compatible UV-Vis spectrometer.

suppress(*exceptions)

Context manager to suppress specified exceptions

class AFL.automation.instrument.SeabreezeUVVis.SeabreezeUVVis(backend: str = 'cseabreeze', device_serial: str | None = None, overrides: dict | None = None)[source]#

Collect spectra from a SeaBreeze-compatible UV-Vis spectrometer.

Parameters:
  • correct_dark_counts (bool, default=False) – Pass SeaBreeze’s device-specific dark-count correction option to each acquired spectrum. This is separate from the stored dark spectrum used for transmission reduction.

  • correct_nonlinearity (bool, default=False) – Pass SeaBreeze’s detector nonlinearity correction option to each acquired spectrum when supported by the device.

  • exposure (float, default=0.010) – Spectrometer integration time in seconds.

  • exposure_delay (float, default=0) – Additional delay in seconds between consecutively acquired frames.

  • save_single_scan (bool, default=False) – Whether acquired spectra are also written to the configured HDF5 file.

  • file_name (str, default="test.h5") – HDF5 file name used when save_single_scan is enabled.

  • file_path (str or pathlib.Path, default=".") – Directory containing the HDF5 file written when save_single_scan is enabled.

  • reference (str, default="AFL_HOME/uvvis/reference_spectrum.npz") – Illuminated reference path. A value ending in .npz is a local file path; any other non-empty value is a Tiled run_documents entry ID.

  • air (str, default="AFL_HOME/uvvis/air_reference_spectrum.npz") – Optional air-reference locator used to report the mean_air diagnostic. Local and Tiled values are selected as for reference.

  • dark (str, default="AFL_HOME/uvvis/dark_spectrum.npz") – Dark-spectrum locator subtracted from sample and reference spectra when dark-spectrum subtraction is enabled. Local and Tiled values are selected as for reference.

  • use_dark_spectrum (bool, default=False) – Whether to subtract the stored dark spectrum from sample and reference spectra during transmission reduction.

  • transmission_denominator_epsilon (float, default=1e-3) – Minimum magnitude used for the dark-corrected reference denominator. This prevents a nearly identical reference and dark spectrum from creating an unstable transmission ratio.

defaults = {'air': 'air_reference_spectrum.npz', 'correct_dark_counts': False, 'correct_nonlinearity': False, 'dark': 'dark_spectrum.npz', 'exposure': 0.1, 'exposure_delay': 0, 'file_name': 'test.h5', 'file_path': '.', 'reference': 'reference_spectrum.npz', 'save_single_scan': False, 'transmission_denominator_epsilon': 0.001, 'use_dark_spectrum': False}#
__init__(backend: str = 'cseabreeze', device_serial: str | None = None, overrides: dict | None = None) → None[source]#

Initialize the spectrometer driver.

Parameters:
  • backend (str, default="cseabreeze") – SeaBreeze backend to use.

  • device_serial (str, optional) – Serial number of the spectrometer to connect to. The first available spectrometer is used when omitted. Startup fails if no matching, available device can be opened and initialized.

  • overrides (dict, optional) – Configuration values that override the driver defaults.

Raises:

RuntimeError – If SeaBreeze cannot discover or initialize an available spectrometer.

status() → List[str][source]#

Report the identity of the connected UV-Vis spectrometer.

get_exposure() → float[source]#

Return the integration time.

Returns:

Integration time in seconds.

Return type:

float

get_exposure_delay() → float[source]#

Return the delay between acquired frames.

Returns:

Delay in seconds.

Return type:

float

get_file_name() → str[source]#

Return the individual-scan file name.

Returns:

Configured file name.

Return type:

str

get_save_single_scan() → bool[source]#

Return whether individual scans are written to disk.

Returns:

True when acquired scans are saved.

Return type:

bool

get_file_path() → str[source]#

Return the individual-scan output directory.

Returns:

Configured output directory.

Return type:

str

set_file_path(file_path: str) → None[source]#

Set the individual-scan output directory.

Parameters:

file_path (str) – Directory for acquired scan files.

set_file_name(file_name: str) → None[source]#

Set the individual-scan file name.

Parameters:

file_name (str) – Name for acquired scan files.

set_save_single_scan(save_single_scan: bool) → None[source]#

Enable or disable writing individual scans to disk.

Parameters:

save_single_scan (bool) – Whether to write acquired scans to disk.

set_exposure_delay(delay: float) → None[source]#

Set the delay between acquired frames.

Parameters:

delay (float) – Delay in seconds.

set_exposure(exposure: float) → None[source]#

Set the spectrometer integration time.

Parameters:

exposure (float) – Integration time in seconds.

post_tiled_finalize(task, tiled_entry_id)[source]#

Persist a successfully uploaded Tiled reference entry ID.

save_reference always promotes its target slot to the uploaded Tiled entry, including when it was initially configured as a local .npz file. measure retains its existing source-selection behavior for its optional reference-setting flags.

measure(n_frames: int, reduced: bool = False, absorbance: bool = True, set_reference: bool = False, set_air: bool = False, set_dark: bool = False, exposure: float | None = None, wavelengths: list | None = [300.0, 900.0]) → Dataset[source]#

Acquire spectra and optionally reduce them against a reference.

Parameters:
  • n_frames (int) – Number of spectra to acquire.

  • reduced (bool, default=False) – Whether to include transmission and extinction variables in addition to the measured intensity spectrum.

  • absorbance (bool, default=True) – Whether to include extinction (absorbance) variables when reduced is True. Transmission variables are always included for a reduced measurement.

  • set_reference (bool, default=False) – Save this measurement as the reference source.

  • set_air (bool, default=False) – Save this measurement as the air reference source.

  • set_dark (bool, default=False) – Save this measurement as the dark reference source.

  • exposure (float, optional) – Temporary integration time in seconds.

  • wavelengths (list[float, float], optional) – Inclusive [minimum, maximum] wavelength range in nm. When supplied, only this range is reduced and included in the returned dataset. References are always acquired and stored full-spectrum.

Returns:

Raw spectra, summary statistics, and optionally reduced spectra.

Return type:

xarray.Dataset

Raises:

ValueError – If a requested reference is unavailable or incompatible.

save_reference(n_frames: int = 1, reference_name: str = 'reference', exposure: float | None = None, path: str | None = None) → Dataset[source]#

Acquire and save a reference for later spectrum reduction.

Parameters:
  • n_frames (int, default=1) – Number of spectra to average into the reference.

  • reference_name ({"reference", "air", "dark"}, default="reference") – Reference slot to update. Its configured locator selects the local .npz or Tiled save destination.

  • exposure (float, optional) – Temporary integration time in seconds.

  • path (str, optional) – Local directory in which to save the reference. The current reference filename is retained (for example, reference_spectrum.npz). An explicit .npz path is also accepted. When omitted, the configured path is used; defaults are under AFL_HOME/uvvis.

Returns:

Saved reference spectrum and its standard deviation.

Return type:

xarray.Dataset

get_reference_path(reference_name: str = 'reference') → str[source]#

Return the AFL-home path for a local reduction reference.

Parameters:

reference_name ({"reference", "air", "dark"}, default="reference") – Local reference slot to inspect.

Returns:

Reference file path beneath AFL_HOME/uvvis.

Return type:

str

Raises:

ValueError – If the slot is configured as a Tiled entry.

reduce(data_raw_mean: ndarray, data_raw_std: ndarray, absorbance: bool = True, reference_name: str = 'reference', transmission: bool = True, wavelength_mask: ndarray | None = None, use_dark_spectrum: bool | None = None) → dict[source]#

Reduce a raw spectrum against the active reference source.

Parameters:
  • data_raw_mean (numpy.ndarray) – Mean raw sample intensity.

  • data_raw_std (numpy.ndarray) – Standard deviation of the raw sample intensity.

  • absorbance (bool, default=True) – Include extinction (absorbance) and propagated-uncertainty arrays.

  • reference_name ({"reference", "air"}, default="reference") – Reference slot to use. Its configured locator selects the local or Tiled source.

  • transmission (bool, default=True) – Include transmission and propagated-uncertainty arrays.

  • use_dark_spectrum (bool, optional) – Override the configured dark-spectrum subtraction setting for this reduction. The configured default is False.

Returns:

Mapping containing the requested arrays: transmission and transmission_std and/or extinction and extinction_std.

Return type:

dict of numpy.ndarray

Raises:

ValueError – If neither transmission nor absorbance is requested.

Notes

By default, the transmission is calculated as $T = S / R$, where $S$ and $R$ are the mean sample and reference intensities. When dark-spectrum subtraction is enabled, the stored dark spectrum $D$ is subtracted from both:

$$ T = frac{S - D}{R - D} $$

With dark-spectrum subtraction enabled, the propagated uncertainty is:

$$ sigma_T = sqrt{

left(frac{sigma_S}{R - D}right)^2 + left(frac{(S - D)sigma_R}{(R - D)^2}right)^2 + left(frac{(S - R)sigma_D}{(R - D)^2}right)^2

}#

When the denominator is close to zero, it is replaced by a signed epsilon before calculating transmission and its uncertainty. The returned extinction fields are absorbance values and use:

$$ A = -log_{10}(T), qquad sigma_A = frac{sigma_T}{|T|ln(10)} $$

getExposure()[source]#

Return the integration time through the deprecated API.

Returns:

Integration time in seconds.

Return type:

float

Warns:

DeprecationWarning – Use get_exposure() instead.

getExposureDelay()[source]#

Return the frame delay through the deprecated API.

Returns:

Delay in seconds.

Return type:

float

Warns:

DeprecationWarning – Use get_exposure_delay() instead.

getFilename()[source]#

Return the scan file name through the deprecated API.

Returns:

Configured file name.

Return type:

str

Warns:

DeprecationWarning – Use get_file_name() instead.

getSaveSingleScan()[source]#

Return the scan-save setting through the deprecated API.

Returns:

Scan-save setting.

Return type:

bool

Warns:

DeprecationWarning – Use get_save_single_scan() instead.

getFilepath()[source]#

Return the scan directory through the deprecated API.

Returns:

Configured output directory.

Return type:

str

Warns:

DeprecationWarning – Use get_file_path() instead.

setFilepath(file_path)[source]#

Set the scan directory through the deprecated API.

Parameters:

file_path (str) – New output directory.

Warns:

DeprecationWarning – Use set_file_path() instead.

setFilename(file_name)[source]#

Set the scan file name through the deprecated API.

Parameters:

file_name (str) – New output file name.

Warns:

DeprecationWarning – Use set_file_name() instead.

setSaveSingleScan(save_single_scan)[source]#

Set scan persistence through the deprecated API.

Parameters:

save_single_scan (bool) – Whether to save acquired scans.

Warns:

DeprecationWarning – Use set_save_single_scan() instead.

setExposureDelay(delay)[source]#

Set frame delay through the deprecated API.

Parameters:

delay (float) – Delay in seconds.

Warns:

DeprecationWarning – Use set_exposure_delay() instead.

setExposure(exposure)[source]#

Set integration time through the deprecated API.

Parameters:

exposure (float) – Integration time in seconds.

Warns:

DeprecationWarning – Use set_exposure() instead.

collect(*args, **kwargs)[source]#

Acquire spectra through the deprecated API.

Parameters:
  • *args – Positional arguments forwarded to measure().

  • **kwargs – Keyword arguments forwarded to measure(). The legacy nframes name is translated to n_frames.

Returns:

Measurement result.

Return type:

xarray.Dataset

Warns:

DeprecationWarning – Use measure() instead.

collectSingleSpectrum(set_reference=False, set_air=False, **kwargs)[source]#

Acquire one spectrum through the deprecated API.

Parameters:
  • set_reference (bool, default=False) – Save the spectrum as the local reference.

  • set_air (bool, default=False) – Save the spectrum as the local air reference.

  • **kwargs – Ignored legacy keyword arguments.

Returns:

Single raw spectrum.

Return type:

xarray.Dataset

Warns:

DeprecationWarning – Use measure() with n_frames=1 instead.

collectContinuous(duration, start=None, return_data=False, **kwargs)[source]#

Acquire continuously through the deprecated API.

Parameters:
  • duration (float) – Acquisition duration in seconds.

  • start (datetime.datetime, optional) – Time at which acquisition begins. Starts immediately when omitted.

  • return_data (bool, default=False) – Retained for compatibility and ignored.

  • **kwargs – Ignored legacy keyword arguments.

Returns:

First acquired spectrum and wavelength grid.

Return type:

xarray.Dataset

Warns:

DeprecationWarning – Use measure() instead.

reduced(*args, **kwargs)[source]#

Reduce a spectrum through the deprecated API.

Parameters:
  • *args – Positional arguments forwarded to reduce().

  • **kwargs – Keyword arguments forwarded to reduce(). The legacy reference_uuid key is translated to a local reference name.

Returns:

Reduced spectrum and propagated uncertainty.

Return type:

tuple of numpy.ndarray

Warns:

DeprecationWarning – Use reduce() instead.