Source code for AFL.automation.instrument.SeabreezeUVVis

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

import datetime
from contextlib import suppress
from numbers import Real
from pathlib import Path
from typing import List, Optional
import time
import uuid
import warnings

import h5py
import lazy_loader as lazy
import numpy as np
import xarray as xr

from AFL.automation.APIServer.Driver import Driver

seabreeze = lazy.load("seabreeze", require="AFL-automation[seabreeze]")


[docs] class SeabreezeUVVis(Driver): """Collect spectra from a SeaBreeze-compatible UV-Vis spectrometer. Other 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 = { "correct_dark_counts": False, "correct_nonlinearity": False, "exposure": 0.1, "exposure_delay": 0, "save_single_scan": False, "file_name": "test.h5", "file_path": ".", "reference": "reference_spectrum.npz", "air": "air_reference_spectrum.npz", "dark": "dark_spectrum.npz", "use_dark_spectrum": False, "transmission_denominator_epsilon": 1e-3, } _LEGACY_CONFIG_KEYS = { "correctDarkCounts": "correct_dark_counts", "correctNonlinearity": "correct_nonlinearity", "saveSingleScan": "save_single_scan", "filename": "file_name", "filepath": "file_path", } _DEFAULT_REFERENCE_FILENAMES = { "reference": "reference_spectrum.npz", "air": "air_reference_spectrum.npz", "dark": "dark_spectrum.npz", }
[docs] def __init__( self, backend: str = "cseabreeze", device_serial: Optional[str] = None, overrides: Optional[dict] = None, ) -> None: """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. """ super().__init__( name="SeabreezeUVVis", defaults=self.gather_defaults(), overrides=overrides, ) self._reference_cache = {} self._reference_directory = self.path / "uvvis" migrated_keys = [] for legacy_key, current_key in self._LEGACY_CONFIG_KEYS.items(): if legacy_key in self.config: self.config[current_key] = self.config[legacy_key] del self.config[legacy_key] migrated_keys.append(legacy_key) if migrated_keys: warnings.warn( "Deprecated configuration keys were migrated to PEP 8 names: " f"{', '.join(migrated_keys)}.", DeprecationWarning, stacklevel=2, ) self._normalize_local_reference_paths() self.log_info("Configuring SeaBreeze using backend %s" % backend) try: # ``seabreeze`` is a lazy proxy so importing this driver remains # possible on systems without the optional hardware dependency. # Accessing it here resolves the proxy at the first point the SDK # is actually required. seabreeze.use(backend) from seabreeze.spectrometers import SeaBreezeError, Spectrometer, list_devices except ImportError as error: raise RuntimeError( "SeaBreeze could not be loaded. Install the optional dependency " "with 'pip install AFL-automation[seabreeze]' and verify its " "native dependencies are available." ) from error self.log_info("Attempting to list spectrometers.") try: devices = list_devices() except (SeaBreezeError, OSError, ImportError) as error: raise RuntimeError( f"SeaBreeze could not discover UV-Vis spectrometers using {backend!r}. " "Check the USB connection, power, device permissions, and backend " f"dependencies. Original error: {error}" ) from error self.log_info("SeaBreeze sees devices: %s" % devices) if not devices: raise RuntimeError( "SeaBreeze did not detect any spectrometers. Check that the " "instrument is connected by USB, powered, and accessible to this " "process, and that another application is not using it." ) if device_serial is None: device = next((item for item in devices if not item.is_open), None) if device is None: raise RuntimeError( "SeaBreeze detected spectrometers, but all are already in use. " "Close the application using the instrument before starting this driver." ) else: device = next( (item for item in devices if item.serial_number == str(device_serial)), None, ) if device is None: detected = ", ".join( f"{item.model} (serial {item.serial_number})" for item in devices ) raise RuntimeError( f"SeaBreeze did not detect the requested spectrometer with serial " f"number {device_serial!r}. Detected devices: {detected}." ) if device.is_open: raise RuntimeError( f"Spectrometer {device_serial!r} is already in use. Close the " "application using it before starting this driver." ) device_description = f"{device.model} (serial {device.serial_number})" self.log_info(f"Connecting to UV-Vis spectrometer: {device_description}.") try: # Open the device we discovered, avoiding a second discovery pass. self.spectrometer = Spectrometer(device) self.wavelengths = self.spectrometer.wavelengths() self.set_exposure(self.config["exposure"]) except (SeaBreezeError, OSError) as error: # Spectrometer construction can fail after opening the device. with suppress(SeaBreezeError, OSError): device.close() raise RuntimeError( f"Could not initialize UV-Vis spectrometer {device_description}. " "Check the USB connection and permissions, and close any other " f"application using the instrument. Original error: {error}" ) from error self.device_description = ( f"{self.spectrometer.model} (serial {self.spectrometer.serial_number})" ) # The launcher constructs the driver before configuring server logging. # Flush the identity to the console so Andon captures it during startup. print(self.status()[0], flush=True) self.log_info("Spectrometer wavelength grid: %s" % self.wavelengths)
[docs] def status(self) -> List[str]: """Report the identity of the connected UV-Vis spectrometer.""" return [f"Connected UV-Vis spectrometer: {self.device_description}."]
[docs] @Driver.unqueued() def get_exposure(self) -> float: """Return the integration time. Returns ------- float Integration time in seconds. """ return self.config["exposure"]
[docs] @Driver.unqueued() def get_exposure_delay(self) -> float: """Return the delay between acquired frames. Returns ------- float Delay in seconds. """ return self.config["exposure_delay"]
[docs] @Driver.unqueued() def get_file_name(self) -> str: """Return the individual-scan file name. Returns ------- str Configured file name. """ return self.config["file_name"]
[docs] @Driver.unqueued() def get_save_single_scan(self) -> bool: """Return whether individual scans are written to disk. Returns ------- bool ``True`` when acquired scans are saved. """ return self.config["save_single_scan"]
[docs] @Driver.unqueued() def get_file_path(self) -> str: """Return the individual-scan output directory. Returns ------- str Configured output directory. """ return str(self.config["file_path"])
[docs] def set_file_path(self, file_path: str) -> None: """Set the individual-scan output directory. Parameters ---------- file_path : str Directory for acquired scan files. """ self.config["file_path"] = Path(file_path)
[docs] def set_file_name(self, file_name: str) -> None: """Set the individual-scan file name. Parameters ---------- file_name : str Name for acquired scan files. """ self.config["file_name"] = file_name
[docs] def set_save_single_scan(self, save_single_scan: bool) -> None: """Enable or disable writing individual scans to disk. Parameters ---------- save_single_scan : bool Whether to write acquired scans to disk. """ self.config["save_single_scan"] = save_single_scan
[docs] def set_exposure_delay(self, delay: float) -> None: """Set the delay between acquired frames. Parameters ---------- delay : float Delay in seconds. """ self.config["exposure_delay"] = delay
[docs] def set_exposure(self, exposure: float) -> None: """Set the spectrometer integration time. Parameters ---------- exposure : float Integration time in seconds. """ self.config["exposure"] = exposure integration_time_micros = int(1_000_000 * exposure) self.spectrometer.integration_time_micros(integration_time_micros) self.log_info("Integration time set to %s seconds." % (integration_time_micros / 1_000_000))
def _acquire_spectra(self, n_frames: int) -> np.ndarray: """Acquire spectra, excluding SeaBreeze's internal dark-reference pixel. Parameters ---------- n_frames : int Number of spectra to acquire. Returns ------- numpy.ndarray Array with shape ``(n_frames, n_wavelengths)``. Raises ------ ValueError If ``n_frames`` is less than one. """ if n_frames < 1: raise ValueError("n_frames must be at least 1.") spectra: List[np.ndarray] = [] for _ in range(n_frames): intensities = self.spectrometer.intensities( correct_dark_counts=self.config["correct_dark_counts"], correct_nonlinearity=self.config["correct_nonlinearity"], ) spectra.append(intensities[1:]) delay = self.config["exposure_delay"] if delay: time.sleep(delay) return np.asarray(spectra) def _write_data(self, data: np.ndarray) -> None: """Write wavelength and intensity data to the configured HDF5 file. Parameters ---------- data : numpy.ndarray Intensity data to store alongside the wavelength grid. """ output_path = Path(self.config["file_path"]) / self.config["file_name"] output_path.parent.mkdir(parents=True, exist_ok=True) with h5py.File(output_path, "w") as output_file: output_file.create_dataset("wavelength", data=self.wavelengths) output_file.create_dataset(str(uuid.uuid1()), data=data) def _reference_path(self, reference_name: str) -> Path: """Return the AFL-home path for a locally configured reference. Parameters ---------- reference_name : {"reference", "air", "dark"} Reference to locate. Returns ------- pathlib.Path Local reference file path. Raises ------ ValueError If the slot is unsupported or is configured as a Tiled entry. """ locator = self._reference_locator(reference_name) if self._reference_source(reference_name) != "local": raise ValueError( f"The {reference_name} locator {locator!r} is a Tiled entry, " "not a local .npz file." ) return self._local_reference_path(locator) def _local_reference_path(self, locator: str) -> Path: """Return an absolute local reference path from a local locator.""" reference_path = Path(locator).expanduser() if not reference_path.is_absolute(): reference_path = self._reference_directory / reference_path return reference_path.resolve() def _normalize_local_reference_paths(self) -> None: """Store local reference locators as absolute paths in configuration.""" for reference_name in self._DEFAULT_REFERENCE_FILENAMES: locator = self.config.get(reference_name) if isinstance(locator, str) and locator.strip().lower().endswith(".npz"): self.config[reference_name] = str( self._local_reference_path(locator.strip()) ) def _set_reference_save_path(self, reference_name: str, path: str) -> Path: """Configure a local save path for a reference and return that path.""" if reference_name not in self._DEFAULT_REFERENCE_FILENAMES: raise ValueError( "reference_name must be one of 'reference', 'air', or 'dark'." ) requested_path = Path(path).expanduser() if requested_path.suffix.lower() == ".npz": reference_path = requested_path else: reference_path = requested_path / self._DEFAULT_REFERENCE_FILENAMES[reference_name] self.config[reference_name] = str(reference_path.resolve()) return self._reference_path(reference_name) def _reference_locator(self, reference_name: str) -> str: """Return the configured local-file or Tiled-entry locator for a slot.""" if reference_name not in {"reference", "air", "dark"}: raise ValueError( "reference_name must be one of 'reference', 'air', or 'dark'." ) locator = self.config[reference_name] if not isinstance(locator, str) or not locator.strip(): raise ValueError( f"The {reference_name} locator must be a non-empty string." ) return locator.strip() def _reference_source(self, reference_name: str) -> str: """Classify a reference locator as a local file or Tiled entry.""" locator = self._reference_locator(reference_name) return "local" if locator.lower().endswith(".npz") else "tiled" def _has_tiled_connection(self) -> bool: """Return whether the driver has an initialized Tiled client. Returns ------- bool ``True`` when an APIServer supplied a usable Tiled data packet. """ return getattr(getattr(self, "data", None), "tiled_client", None) is not None def _has_reference(self, reference_name: str) -> bool: """Return whether the requested reference is available from its active source. Parameters ---------- reference_name : {"reference", "air", "dark"} Reference slot to check. Returns ------- bool ``True`` if the configured local file exists or a Tiled connection is available for the configured entry ID. """ if self._reference_source(reference_name) == "tiled": return self._has_tiled_connection() return ( reference_name in self._reference_cache or self._reference_path(reference_name).is_file() ) def _validate_reference_save_target(self, reference_name: str) -> None: """Ensure a configured reference save destination is usable.""" if ( self._reference_source(reference_name) == "tiled" and not self._has_tiled_connection() ): locator = self._reference_locator(reference_name) raise ValueError( f"The {reference_name} locator {locator!r} requires an " "initialized Tiled connection to save a reference." ) def _reference_metadata(self, reference_name: str) -> dict: """Return provenance metadata for a configured reference slot.""" locator = self._reference_locator(reference_name) source = self._reference_source(reference_name) metadata = { f"{reference_name}_locator": locator, f"{reference_name}_source": source, } if source == "local": path_key = ( "reference_path" if reference_name == "reference" else f"{reference_name}_reference_path" ) metadata[path_key] = str(self._reference_path(reference_name)) return metadata def _save_reference( self, spectrum_mean: np.ndarray, spectrum_std: np.ndarray, reference_name: str, ) -> Path: """Cache and persist a reference spectrum at its local-file locator. Parameters ---------- spectrum_mean : numpy.ndarray Mean intensity of the reference measurement. spectrum_std : numpy.ndarray Standard deviation of the reference measurement. reference_name : {"reference", "air", "dark"} Reference slot to update. Returns ------- pathlib.Path Path of the persisted compressed NumPy archive. Raises ------ ValueError If the configured locator is a Tiled entry. """ if self._reference_source(reference_name) != "local": raise ValueError( f"The {reference_name} locator is a Tiled entry and cannot be " "saved as a local .npz file." ) self._reference_cache[reference_name] = ( np.array(spectrum_mean, copy=True), np.array(spectrum_std, copy=True), ) reference_path = self._reference_path(reference_name) reference_path.parent.mkdir(parents=True, exist_ok=True) np.savez_compressed( reference_path, wavelength=self.wavelengths[1:], spectrum_mean=spectrum_mean, spectrum_std=spectrum_std, ) return reference_path def _load_reference(self, reference_name: str) -> tuple: """Load a reference spectrum from its configured source. Parameters ---------- reference_name : {"reference", "air", "dark"} Reference slot to load. Returns ------- tuple of numpy.ndarray Reference mean intensity and standard deviation. Raises ------ ValueError If the configured source is unavailable or incompatible. """ if self._reference_source(reference_name) == "tiled": return self._load_tiled_reference(reference_name) return self._load_local_reference(reference_name) def _load_local_reference(self, reference_name: str) -> tuple: """Load a cached or persisted local ``.npz`` reference spectrum.""" cached_reference = self._reference_cache.get(reference_name) if cached_reference is not None: return cached_reference reference_path = self._reference_path(reference_name) if not reference_path.is_file(): raise ValueError( f"No local {reference_name} reference exists at {reference_path}. " "Acquire one with save_reference() or the matching " "measure(set_reference=True, set_air=True, or set_dark=True) option." ) with np.load(reference_path) as reference_data: wavelength = reference_data["wavelength"] spectrum_mean = reference_data["spectrum_mean"] spectrum_std = reference_data["spectrum_std"] if not np.array_equal(wavelength, self.wavelengths[1:]): raise ValueError( f"The local {reference_name} reference wavelength grid does not " "match the connected spectrometer." ) self._reference_cache[reference_name] = (spectrum_mean, spectrum_std) return spectrum_mean, spectrum_std def _load_tiled_reference(self, reference_name: str) -> tuple: """Load a reference spectrum from Tiled. Parameters ---------- reference_name : {"reference", "air", "dark"} Reference slot to load. Returns ------- tuple of numpy.ndarray Reference mean intensity and standard deviation. Raises ------ ValueError If a Tiled connection is unavailable or the entry no longer exists. """ reference_entry_id = self._reference_locator(reference_name) if self._reference_source(reference_name) != "tiled": raise ValueError( f"The {reference_name} locator is a local .npz file, not a " "Tiled entry." ) if not self._has_tiled_connection(): raise ValueError( f"The {reference_name} locator {reference_entry_id!r} requires " "an initialized Tiled connection." ) try: reference_entry = self.data.tiled_client["run_documents"][ reference_entry_id ] except KeyError as error: raise ValueError( f"The configured Tiled {reference_name} entry " f"{reference_entry_id!r} no longer exists." ) from error # Tiled clients configured with ``structure_clients="dask"`` return # lazy dask arrays here. Materialize them before reduction so the # resulting xarray Dataset is NumPy-backed and can be written to Tiled. reference_spectrum = np.asarray(reference_entry["spectrum_raw"][()]) reference_std = np.asarray(reference_entry["spectrum_raw_std"][()]) return reference_spectrum, reference_std
[docs] def post_tiled_finalize(self, task, tiled_entry_id): """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. """ task_name = task.get("task_name") if task_name == "save_reference": reference_name = task.get("reference_name", "reference") self.config[reference_name] = tiled_entry_id self.log_info( f"Stored {reference_name} reference in Tiled entry {tiled_entry_id}." ) return reference_names = [] if task_name == "measure": if task.get("set_reference"): reference_names.append("reference") if task.get("set_air"): reference_names.append("air") if task.get("set_dark"): reference_names.append("dark") for reference_name in reference_names: if self._reference_source(reference_name) == "tiled": self.config[reference_name] = tiled_entry_id
[docs] @Driver.queued() def measure( self, n_frames: int, reduced: bool = False, absorbance: bool = True, set_reference: bool = False, set_air: bool = False, set_dark: bool = False, exposure: Optional[float] = None, wavelengths: Optional[list] = [300.0, 900.0], ) -> xr.Dataset: """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 ------- xarray.Dataset Raw spectra, summary statistics, and optionally reduced spectra. Raises ------ ValueError If a requested reference is unavailable or incompatible. """ if exposure is not None: self.set_exposure(exposure) wavelength_mask = self._wavelength_mask(wavelengths) for reference_name, should_save in ( ("reference", set_reference), ("air", set_air), ("dark", set_dark), ): if should_save: self._validate_reference_save_target(reference_name) raw_spectra = self._acquire_spectra(n_frames) raw_mean = np.mean(raw_spectra, axis=0) raw_std = np.std(raw_spectra, axis=0) for reference_name, should_save in ( ("reference", set_reference), ("air", set_air), ("dark", set_dark), ): if should_save and self._reference_source(reference_name) == "local": self._save_reference(raw_mean, raw_std, reference_name) selected_wavelengths = self.wavelengths[1:][wavelength_mask] raw_spectra = raw_spectra[:, wavelength_mask] raw_mean = raw_mean[wavelength_mask] raw_std = raw_std[wavelength_mask] if reduced: reduction = self.reduce( raw_mean, raw_std, transmission=True, absorbance=absorbance, wavelength_mask=wavelength_mask, ) if not set_air and self._has_reference("air"): air_reduction = self.reduce( raw_mean, raw_std, absorbance=False, transmission=True, reference_name="air", wavelength_mask=wavelength_mask, ) mean_air = np.mean(air_reduction["transmission"]) std_air = np.mean(air_reduction["transmission_std"]) else: mean_air = None std_air = None if self.config["save_single_scan"]: self._write_data(raw_spectra) dataset = xr.Dataset() dataset.attrs.update( mode="measure", reduced=reduced, absorbance=absorbance, mean_air=mean_air, std_air=std_air, ) for reference_name in ("reference", "air", "dark"): dataset.attrs.update(self._reference_metadata(reference_name)) dataset["wavelength"] = ("wavelength", selected_wavelengths) dataset["all_spectra"] = (("frame", "wavelength"), raw_spectra) dataset["spectrum_raw"] = ("wavelength", raw_mean) dataset["spectrum_raw_std"] = ("wavelength", raw_std) if reduced: for variable_name, values in reduction.items(): dataset[variable_name] = ("wavelength", values) return dataset
def _wavelength_mask(self, wavelengths: Optional[list]) -> np.ndarray: """Validate a requested wavelength range and return its inclusive mask.""" available_wavelengths = self.wavelengths[1:] if wavelengths is None: return np.ones(available_wavelengths.shape, dtype=bool) if ( not isinstance(wavelengths, list) or len(wavelengths) != 2 or any( isinstance(value, bool) or not isinstance(value, Real) or not np.isfinite(value) for value in wavelengths ) ): raise ValueError( "wavelengths must be a list of two finite numbers: [min, max]." ) minimum, maximum = wavelengths if minimum >= maximum: raise ValueError("wavelengths must satisfy min < max.") mask = (available_wavelengths >= minimum) & (available_wavelengths <= maximum) if not np.any(mask): raise ValueError( "wavelengths does not include any wavelengths measured by this spectrometer." ) return mask
[docs] @Driver.queued() def save_reference( self, n_frames: int = 1, reference_name: str = "reference", exposure: Optional[float] = None, path: Optional[str] = None, ) -> xr.Dataset: """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 ------- xarray.Dataset Saved reference spectrum and its standard deviation. """ if exposure is not None: self.set_exposure(exposure) if path is not None: self._set_reference_save_path(reference_name, path) self._validate_reference_save_target(reference_name) raw_spectra = self._acquire_spectra(n_frames) spectrum_mean = np.mean(raw_spectra, axis=0) spectrum_std = np.std(raw_spectra, axis=0) if self._reference_source(reference_name) == "local": reference_path = self._save_reference( spectrum_mean, spectrum_std, reference_name ) self.log_info( f"Stored {reference_name} reference locally at {reference_path}." ) else: self.log_info( f"Prepared {reference_name} reference for Tiled storage " f"(current locator: {self._reference_locator(reference_name)})." ) dataset = xr.Dataset() dataset.attrs.update( mode="reference", reference_name=reference_name, ) dataset.attrs.update(self._reference_metadata(reference_name)) dataset["wavelength"] = ("wavelength", self.wavelengths[1:]) dataset["spectrum_raw"] = ("wavelength", spectrum_mean) dataset["spectrum_raw_std"] = ("wavelength", spectrum_std) return dataset
[docs] @Driver.unqueued() def get_reference_path(self, reference_name: str = "reference") -> str: """Return the AFL-home path for a local reduction reference. Parameters ---------- reference_name : {"reference", "air", "dark"}, default="reference" Local reference slot to inspect. Returns ------- str Reference file path beneath ``AFL_HOME/uvvis``. Raises ------ ValueError If the slot is configured as a Tiled entry. """ return str(self._reference_path(reference_name))
[docs] def reduce( self, data_raw_mean: np.ndarray, data_raw_std: np.ndarray, absorbance: bool = True, reference_name: str = "reference", transmission: bool = True, wavelength_mask: Optional[np.ndarray] = None, use_dark_spectrum: Optional[bool] = None, ) -> dict: r"""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 ------- dict of numpy.ndarray Mapping containing the requested arrays: ``transmission`` and ``transmission_std`` and/or ``extinction`` and ``extinction_std``. 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)} $$ """ if not transmission and not absorbance: raise ValueError("At least one of transmission or absorbance must be True.") eps = 1e-3 reference_spectrum, reference_std = self._load_reference(reference_name) if wavelength_mask is not None: reference_spectrum = reference_spectrum[wavelength_mask] reference_std = reference_std[wavelength_mask] if use_dark_spectrum is None: use_dark_spectrum = self.config.get("use_dark_spectrum", False) if not isinstance(use_dark_spectrum, (bool, np.bool_)): raise ValueError("use_dark_spectrum must be a boolean.") with np.errstate(divide="ignore", invalid="ignore"): if use_dark_spectrum: dark_spectrum, dark_std = self._load_reference("dark") if wavelength_mask is not None: dark_spectrum = dark_spectrum[wavelength_mask] dark_std = dark_std[wavelength_mask] numerator = data_raw_mean - dark_spectrum denominator = reference_spectrum - dark_spectrum transmission_std = np.sqrt( (data_raw_std / denominator) ** 2 + (numerator * reference_std / denominator**2) ** 2 + ( (data_raw_mean - reference_spectrum) * dark_std / denominator**2 ) ** 2 ) else: numerator = data_raw_mean denominator = reference_spectrum transmission_std = np.sqrt( (data_raw_std / denominator) ** 2 + (numerator * reference_std / denominator**2) ** 2 ) transmission_values = numerator / (denominator + eps) result = {} if transmission: result["transmission"] = transmission_values result["transmission_std"] = transmission_std if absorbance: with np.errstate(divide="ignore", invalid="ignore"): extinction = -np.log10(transmission_values) extinction_std = transmission_std / ( np.abs(transmission_values) * np.log(10) ) result["extinction"] = extinction result["extinction_std"] = extinction_std return result
# Compatibility API: preserve existing server routes and Python callers while # directing new integrations to PEP 8 names.
[docs] @Driver.unqueued() def getExposure(self): """Return the integration time through the deprecated API. Returns ------- float Integration time in seconds. Warns ----- DeprecationWarning Use :meth:`get_exposure` instead. """ self._warn_deprecated("getExposure", "get_exposure") return self.get_exposure()
[docs] @Driver.unqueued() def getExposureDelay(self): """Return the frame delay through the deprecated API. Returns ------- float Delay in seconds. Warns ----- DeprecationWarning Use :meth:`get_exposure_delay` instead. """ self._warn_deprecated("getExposureDelay", "get_exposure_delay") return self.get_exposure_delay()
[docs] @Driver.unqueued() def getFilename(self): """Return the scan file name through the deprecated API. Returns ------- str Configured file name. Warns ----- DeprecationWarning Use :meth:`get_file_name` instead. """ self._warn_deprecated("getFilename", "get_file_name") return self.get_file_name()
[docs] @Driver.unqueued() def getSaveSingleScan(self): """Return the scan-save setting through the deprecated API. Returns ------- bool Scan-save setting. Warns ----- DeprecationWarning Use :meth:`get_save_single_scan` instead. """ self._warn_deprecated("getSaveSingleScan", "get_save_single_scan") return self.get_save_single_scan()
[docs] @Driver.unqueued() def getFilepath(self): """Return the scan directory through the deprecated API. Returns ------- str Configured output directory. Warns ----- DeprecationWarning Use :meth:`get_file_path` instead. """ self._warn_deprecated("getFilepath", "get_file_path") return self.get_file_path()
[docs] def setFilepath(self, file_path): """Set the scan directory through the deprecated API. Parameters ---------- file_path : str New output directory. Warns ----- DeprecationWarning Use :meth:`set_file_path` instead. """ self._warn_deprecated("setFilepath", "set_file_path") self.set_file_path(file_path)
[docs] def setFilename(self, file_name): """Set the scan file name through the deprecated API. Parameters ---------- file_name : str New output file name. Warns ----- DeprecationWarning Use :meth:`set_file_name` instead. """ self._warn_deprecated("setFilename", "set_file_name") self.set_file_name(file_name)
[docs] def setSaveSingleScan(self, save_single_scan): """Set scan persistence through the deprecated API. Parameters ---------- save_single_scan : bool Whether to save acquired scans. Warns ----- DeprecationWarning Use :meth:`set_save_single_scan` instead. """ self._warn_deprecated("setSaveSingleScan", "set_save_single_scan") self.set_save_single_scan(save_single_scan)
[docs] def setExposureDelay(self, delay): """Set frame delay through the deprecated API. Parameters ---------- delay : float Delay in seconds. Warns ----- DeprecationWarning Use :meth:`set_exposure_delay` instead. """ self._warn_deprecated("setExposureDelay", "set_exposure_delay") self.set_exposure_delay(delay)
[docs] def setExposure(self, exposure): """Set integration time through the deprecated API. Parameters ---------- exposure : float Integration time in seconds. Warns ----- DeprecationWarning Use :meth:`set_exposure` instead. """ self._warn_deprecated("setExposure", "set_exposure") self.set_exposure(exposure)
[docs] def collect(self, *args, **kwargs): """Acquire spectra through the deprecated API. Parameters ---------- *args Positional arguments forwarded to :meth:`measure`. **kwargs Keyword arguments forwarded to :meth:`measure`. The legacy ``nframes`` name is translated to ``n_frames``. Returns ------- xarray.Dataset Measurement result. Warns ----- DeprecationWarning Use :meth:`measure` instead. """ self._warn_deprecated("collect", "measure") kwargs.pop("return_data", None) if "nframes" in kwargs: kwargs["n_frames"] = kwargs.pop("nframes") return self.measure(*args, **kwargs)
[docs] @Driver.unqueued() def collectSingleSpectrum(self, set_reference=False, set_air=False, **kwargs): """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 ------- xarray.Dataset Single raw spectrum. Warns ----- DeprecationWarning Use :meth:`measure` with ``n_frames=1`` instead. """ self._warn_deprecated("collectSingleSpectrum", "measure(n_frames=1)") del kwargs raw_spectrum = self._acquire_spectra(1)[0] if self.config["save_single_scan"]: self._write_data(raw_spectrum) if set_reference: self._save_reference(raw_spectrum, np.zeros_like(raw_spectrum), "reference") if set_air: self._save_reference(raw_spectrum, np.zeros_like(raw_spectrum), "air") dataset = xr.Dataset() dataset.attrs.update(mode="single", reduced=False) dataset["wavelength"] = ("wavelength", self.wavelengths[1:]) dataset["spectrum_raw"] = ("wavelength", raw_spectrum) return dataset
[docs] def collectContinuous(self, duration, start=None, return_data=False, **kwargs): """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 ------- xarray.Dataset First acquired spectrum and wavelength grid. Warns ----- DeprecationWarning Use :meth:`measure` instead. """ self._warn_deprecated("collectContinuous", "measure") del return_data, kwargs start_time = start or datetime.datetime.now() duration_delta = datetime.timedelta(seconds=duration) while datetime.datetime.now() < start_time: time.sleep(0.001) spectra = [] while datetime.datetime.now() < start_time + duration_delta: spectra.append(self._acquire_spectra(1)[0]) dataset = xr.Dataset() dataset.attrs["mode"] = "continuous" dataset["wavelength"] = ("wavelength", self.wavelengths[1:]) dataset["spectra"] = ("wavelength", spectra[0]) self._write_data(np.asarray(spectra)) return dataset
[docs] def reduced(self, *args, **kwargs): """Reduce a spectrum through the deprecated API. Parameters ---------- *args Positional arguments forwarded to :meth:`reduce`. **kwargs Keyword arguments forwarded to :meth:`reduce`. The legacy ``reference_uuid`` key is translated to a local reference name. Returns ------- tuple of numpy.ndarray Reduced spectrum and propagated uncertainty. Warns ----- DeprecationWarning Use :meth:`reduce` instead. """ self._warn_deprecated("reduced", "reduce") legacy_reference_key = kwargs.pop("reference_uuid", None) if legacy_reference_key is not None: kwargs["reference_name"] = ( "air" if legacy_reference_key == "air_uuid" else "reference" ) legacy_absorbance = kwargs.get( "absorbance", args[2] if len(args) > 2 else True ) result = self.reduce(*args, **kwargs) if legacy_absorbance: return result["extinction"], result["extinction_std"] return result["transmission"], result["transmission_std"]
@staticmethod def _warn_deprecated(old_name: str, new_name: str) -> None: """Emit a consistent warning for a deprecated compatibility method. Parameters ---------- old_name : str Deprecated method name. new_name : str Preferred replacement method name. """ warnings.warn( f"{old_name}() is deprecated and will be removed in a future release; " f"use {new_name}() instead.", DeprecationWarning, stacklevel=3, )
_DEFAULT_CUSTOM_CONFIG = { "_classname": "AFL.automation.instrument.SeabreezeUVVis.SeabreezeUVVis", "backend": "pyseabreeze", } _DEFAULT_PORT = 5051 if __name__ == "__main__": from AFL.automation.shared.launcher import *