AFL.automation.instrument.SeabreezeUVVis#
Driver for Ocean Optics UV-Vis spectrometers supported by SeaBreeze.
Classes
|
|
|
PurePath subclass that can make system calls. |
|
To Complex, Real adds the operations that work on real numbers. |
|
Collect spectra from a SeaBreeze-compatible UV-Vis spectrometer. |
|
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
darkspectrum 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_scanis enabled.file_path (str or pathlib.Path, default=".") – Directory containing the HDF5 file written when
save_single_scanis enabled.reference (str, default="AFL_HOME/uvvis/reference_spectrum.npz") – Illuminated reference path. A value ending in
.npzis a local file path; any other non-empty value is a Tiledrun_documentsentry ID.air (str, default="AFL_HOME/uvvis/air_reference_spectrum.npz") – Optional air-reference locator used to report the
mean_airdiagnostic. Local and Tiled values are selected as forreference.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.
- get_exposure() float[source]#
Return the integration time.
- Returns:
Integration time in seconds.
- Return type:
- get_exposure_delay() float[source]#
Return the delay between acquired frames.
- Returns:
Delay in seconds.
- Return type:
- get_file_name() str[source]#
Return the individual-scan file name.
- Returns:
Configured file name.
- Return type:
- get_save_single_scan() bool[source]#
Return whether individual scans are written to disk.
- Returns:
Truewhen acquired scans are saved.- Return type:
- get_file_path() str[source]#
Return the individual-scan output directory.
- Returns:
Configured output directory.
- Return type:
- 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_referencealways promotes its target slot to the uploaded Tiled entry, including when it was initially configured as a local.npzfile.measureretains 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
reducedisTrue. 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
.npzor 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.npzpath is also accepted. When omitted, the configured path is used; defaults are underAFL_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:
- 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:
transmissionandtransmission_stdand/orextinctionandextinction_std.- Return type:
- 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
extinctionfields 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:
- Warns:
DeprecationWarning – Use
get_exposure()instead.
- getExposureDelay()[source]#
Return the frame delay through the deprecated API.
- Returns:
Delay in seconds.
- Return type:
- Warns:
DeprecationWarning – Use
get_exposure_delay()instead.
- getFilename()[source]#
Return the scan file name through the deprecated API.
- Returns:
Configured file name.
- Return type:
- Warns:
DeprecationWarning – Use
get_file_name()instead.
- getSaveSingleScan()[source]#
Return the scan-save setting through the deprecated API.
- Returns:
Scan-save setting.
- Return type:
- Warns:
DeprecationWarning – Use
get_save_single_scan()instead.
- getFilepath()[source]#
Return the scan directory through the deprecated API.
- Returns:
Configured output directory.
- Return type:
- 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.
- collectSingleSpectrum(set_reference=False, set_air=False, **kwargs)[source]#
Acquire one spectrum through the deprecated API.
- Parameters:
- Returns:
Single raw spectrum.
- Return type:
xarray.Dataset
- Warns:
DeprecationWarning – Use
measure()withn_frames=1instead.
- 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.