PySpecTrace: A Python-based Graphical User Interface for Real-Time Spectroscopy Analysis and Data Analysis

2.1 Implementation and architecture

PySpecTrace is structured using a Model-View-Presenter (MVP) architecture to partition the programming logic to its specific roles, i.e., Model Class, View Class and Presenter Class¹⁹ ( Figure 1 and more details in Supporting Information Section I).³⁶ In detail, the Model Class retrieves and provides a spectrum from either a physical spectrometer or a built-in spectrum simulator. The View Class manages the GUI, while the Presenter class acts as a mediator between the Model Class and the View Class, coordinates data flow, and executes calculations such as referencing and fitting. Such an implementation of a well-defined architecture streamlines both maintenance and further software development processes.

Figure 1. Schematic of the Model-View-Presenter (MVP) architecture behind PySpectrace.

Model class retrieves raw spectra from the spectrophotometer and stores the processed spectra in preparation for fitting. Presenter class handles spectrum processing including background corrections and descriptors fitting. Finally, View class provides the platform for two types of data visualizations: (i) processed spectrum overlayed with the fittings and (ii) descriptors tracking in Sensorgram.

PySpecTrace is built upon available Python libraries as follows: (i) The PyQt5for the GUI visualisation, (ii) NumPy for the numerical computing, (iii) SciPy for the fitting routine, (iv) Pandas for tabular-based data handling, (v) Seatease for generation of simulated spectrum, and (vi) Matplotlib and PyQtgraph for the minor and the major plotting, respectively.

The data handling across MVP classes proceeds as follows: (i) The Model Class retrieves the spectral data via a vendor-specific API module. (ii) The Presenter processes the data (e.g., spectrum normalization with respect to bright and dark backgrounds) and subsequently stores it in the Model. This processed data can later be retrieved again for further analysis in the Presenter. (iii) Finally, all the processed data is delivered to the View Class for visualization.

To this end, PySpecTrace has been demonstrated successfully on spectrometer from Avantes^®, CNI Laser^®, and Ocean Optics^®. One should note, however, that an API module from the spectrometer manufacturer is required for the PySpecTrace to work. This API module is a driver that enables real-time data stream from the spectromenter. In addition to the real spectrometer data, PySpecTrace also provides a spectrometer simulator to test the PySpecTrace features without connection to a physical spectrometer. This feature enables a wide access for interested users—even ones without spectrometers—to further develop the software.

2.1.1 Software Installation

PySpecTrace can be installed using either (a) the Python Package Index (PyPI) or (b) manual installation from the source code repository. We recommend installation via PyPI because it automatically resolves and installs the required dependencies. Python 3.9–3.12 are recommended to ensure compatibility with all supported libraries and hardware drivers.

(a) Installation via PyPI (recommended)

The simplest way to install PySpecTrace is through PyPI:²⁰

pip install pyspectrace==2.0.0

(the 2.0.0 refers to the specific version 2.0.0).

After installation, the software can be launched directly from a terminal using:

pyspectrace

(b) Manual installation from source

Alternatively, PySpecTrace can be executed directly from the source code repository. In the directory where main.py is located, open a terminal and run:

python main.py

This command launches the PySpecTrace graphical user interface. Please note that core functionalities remain unavailable until a spectrum source is selected (see the Spectrometer Source panel in Figure 2).

Figure 2. Layout of the PySpecTrace Graphical User Interface (GUI).

The GUI consists of six main sections: (1) menu bar, (2) spectrometer source panel, (3) configuration panel (includes configuration for spectrometer and fitting), (4) statistics panel, (5) spectrum panel, and (6) sensorgram panel.

External spectrometers will be detected only when the SDK files (DLLs/shared libraries) are supplemented into PyspecTrace which can be uploaded via menu bar ( Figure 2) with these steps:

PySpecTrace stores user-provided SDK files in the user data directory. This keeps the PyPI package free from proprietary SDK files.

Detailed installation instructions, dependency management, hardware configuration, measurement procedures, and analysis workflows are beyond the scope of the present article and are therefore provided in the user manual available through Github¹ and Zenodo.³⁶

2.1.2 Graphical user interface (GUI)

To enable intuitive control yet comprehensive analysis, PySpecTrace interface is divided into five sections ( Figure 2). The Spectrometer source panel allows users to detect and connect to a spectrometer. The Configuration panel provides control for spectrometer acquisition parameters (such as integration time and spectra averaging), background referencing, fitting parameters, data recording and plotting. The Statistics panel shows real-time data stream information including rate of retrieved and processed spectra, elapsed monitoring time, and saved file counting. The Spectrum panel presents the acquired or processed spectrum in various modes such as transmission, absorbance, and reflectance. Finally, the Sensorgram displays the dynamic descriptor tracing.

2.1.3 Software features

PySpecTrace features several key capabilities as presented below. The corresponding detailed discussion and practical steps are documented in the provided Supporting Information and Manual, respectively (Github¹ and Zenodo).³⁶

PySpecTrace features background correction for dark and bright conditions. The dark background adjusts for the spectrometer’s electronic noise in complete darkness. The bright background, recorded when the light source is on, corrects for background materials such as the sample container and/or solvent. Both bright and dark references can be saved and reloaded, preventing the need for repeated recording. The corresponding mathematical details in determining the background spectrum are provided in the supporting documentation (Supporting Information Section II).³⁶

In addition, the program also provides baseline correction to eliminate spectrum baseline fluctuation or drift, which are common in real-time spectrum monitoring. This correction is executed by defining a baseline typically at longer wavelength where the spectrum band is flat (non-absorbing) as reference point. The baseline can be single wavelength (setting fitting order to zero) or averaged over defined wavelength range (setting fitting order to non-zero).

When both bright and dark references are recorded, the raw spectrum can be converted into different output modes: absorbance, transmission, reflection, and extinction (the formulas are described in Supporting Information Section II). The processed spectrum is displayed in a dedicated spectrum panel ( Figure 3A). If the user clears either the bright or dark spectrum, the output automatically reverts to the raw spectrum.

The main feature of PySpecTrace is spectral change tracking available in two options: (i) peak tracking and (ii) fixed-wavelength intensity tracking. The tracking employs a specific fitting that is displayed in real time in the Sensorgram panel ( Figure 3B).

Figure 3.

(A) Spectrum Panel showing an example of a spectrum with the corresponding peak fitting. (B) Sensorgram panel displaying the real time evolution of the peak wavelength and peak width in panel (A).

For peak position tracking, the descriptors are extracted using three kinds of optional fittings: Gaussian, Lorentzian, and polynomial. For these fittings, the user may adjust initial peak guess, fitting range, degree of polynomial and select the output descriptors. Gaussian and Lorentzian fittings return several descriptors such as peak wavelength position, peak width, and peak inflection point. The peak inflection point is determined using the definition by Chen et al.²¹ Polynomial fitting offers an extra feature to compute the centroid (i.e. the center of mass) of the peak adopted from Dahlin et al.²² Both the inflection points and centroid methods provide additional tools for tracking subtle peak transformations, which is crucial in applications reliant on peak monitoring, for example plasmonics spectroscopy²³ and photoluminescence.²⁴ Tracking of peak inflection points has proven more sensitive for monitoring changes in peak shoulders – a feature missed when only the peak position is tracked. Moreover, the centroid method inherently incorporate baseline correction, resulting in a signal that is more robust to baseline drift.

Another advanced feature offered by PySpecTrace is the dynamic fitting range (as opposed to the traditional static mode). In this dynamic mode, the initial peak position guess is adapted from fitting output executed one step before. This is advantageous for peak tracing where the shift is significantly larger than the peak width, which may lead to inaccurate peak fitting. This dynamic fitting mode can be activated by ticking the “Auto” box in the fitting panel (see Figure 4B).

Last, PySpecTrace allows users to track modulation of the recorded intensity at a fixed wavelength. This tracking is executed by fitting the wavelength band around the target wavelength, followed by averaging the intensity of the fitted band. Typically, the polynomial order is set to 1 for a linear-type averaging. In addition, it is also possible to report the actual intensity of a single point wavelength without fitting by setting the fitting order to zero. All details of the available tracking methods can be found in Supporting Information Section III.³⁶

The descriptors obtained from the tracking are displayed in the Sensorgram panel ( Figure 3B). The sensorgram can, in principle, display the real time evolution of an unlimited number of variables at once. In addition, the descriptors may independently be transformed using various standard mathematical functions (for example $\mathit{ln}\left(x\right)$ , $\frac{1}{x}$ , …) typically used in chemical kinetic studies. Lastly, the $y$ -axis scaling of each descriptor in the sensorgram is independent of the scaling of the other descriptors.

PySpecTrace provides saving features for: (i) spectral data, (ii) sensorgram data, and (iii) generated plots. For spectral data, both raw and processed spectra are saved simultaneously. Saving raw data is encouraged to enable future unanticipated post-processing and re-analysis.

Furthermore, data saving can be paused and resumed at any time, preserving both time interval and actual timestamp. Each spectral data (including wavelength and intensity) for every data acquisition time is saved in an independent .txt file, instead of being appended to a growing collective file, to prevent potential data loss when data saving is interrupted.

For a quick visualization of the spectral evolution, PySpecTrace includes a dedicated panel that overlays spectra over time (tab ‘Spectrum multiplot’, see Manual Section IV-7³⁶). The accumulation interval can be resumed and paused as needed. These overlaid spectra can be exported as .csv files or image formats.

Furthermore, the sensorgram tracking can also be exported as a .csv file or image formats. All recorded descriptors are organized within a single .csv file, with each descriptor allocated to separate column.

In addition to real-time data analysis, PySpecTrace is also equipped with a spectrum post-processing capability. This allows users to replay previously recorded spectra and apply additional tracking functions for extended analysis.

This feature also allows self-reference mode, in which each spectrum is referenced to the initial spectrum acquired at $t=0$ . This mode is beneficial to identify the most significant spectral changes across the wavelength range.

2.1.4 Demonstration video

Finally, we provided the demonstration of the software usage and the features overview in the accompanying demonstration video.³⁷ In this illustrative example, the program’s operation is presented, with its main functionalities are highlighted in Table 1.

2.2 Operation

This program is written based on Python; therefore, it will be able to operate in Windows, Linux, and macOS. However, one should ensure that the spectrometer hardware driver also works within the operating system.

Additional system requirements

Input device: UV-visible-NIR spectrometer.

Computer system requirements: This program can be run on an entry level laptop or desktop PC with processor Core i3 (or equivalent) and RAM 8 GB.

Dependencies

Linux, Windows 10 or 11, python==3.9–3.12, numpy (2.2.5), pandas (2.2.3), matplotlib (3.10.1), pyqt5 (5.15.11), pyqtgraph (0.13.7), scipy (1.15.2), seatease (0.4.0).