spectroscopy-py

Spectroscopy v2.4

Table of Contents

Introduction
Application Usage
Reader Mode
Export Data
License
Contact

Introduction

Welcome to FLIM LABS Spectroscopy v2.4 usage guide. In this documentation section, you will find all the necessary information for the proper use of the application’s graphical user interface (GUI). For a general introduction to the aims and technical requirements of the project, read the Spectroscopy Homepage link.

(back to top)

Application Usage

Spectroscopy software provides users with three distinct analysis modes to suit various experimental and analytical needs:

Spectroscopy Mode;
Phasors Mode;
Fitting Mode

Spectroscopy Mode

Spectroscopy Mode allows users to perform in-depth analyses of the photon intensity decay profile as a function of time.

The decay curve displayed in the Spectroscopy plot represents the sum of the curves for each chunk, where a chunk is defined by the bin width parameter set by the user. Each decay curve is represented by 256 points, maintaining this consistency regardless of the laser frequency used.

Key features of Spectroscopy Mode include:

Real-Time Visualization and Analysis: Users can view and analyze both the intensity tracking graph (single-photon counts) and the intensity decay graph in real time.
Time Shift Application: The ability to apply a time shift to the decay curve for precise analysis.
CPS (Counts Per Second) Display: Shows the average photon counts per second.
Pile-Up Threshold Configuration: Users can set a CPS threshold. When the CPS value exceeds the threshold, a graphical effect alerts the user.
Linear and Logarithmic Scale Options: The decay plot can be displayed in either linear or logarithmic scale.
SBR (Signal-to-Background Ratio) Display:: Allows users to identify potential noise during acquisition.
Calibration Mode:: Enables the acquisition of reference parameters that can be used for more advanced analyses in Phasors Mode.

(back to top)

Phasors Mode

Phasors Mode enables users to conduct advanced analyses of the lifetime distribution using phasor plots.

Key features of Phasors Mode include:

Phasor Points Calculation: Users can compute the phasor points either from a reference acquisition recently performed in the Spectroscopy tab or by loading an external JSON calibration file.
Simultaneous Visualization: The decay curve profile and the phasor plot can be displayed side by side for comprehensive analysis.
Harmonic Selection: Users can choose which harmonic to visualize on the phasor plot for tailored insights.
Point Quantization Adjustment: The level of quantization for the phasor points can be customized to optimize rendering and enhance visibility.
Colormap Application: A default colormap is applied to the phasor points, aiding in distinguishing recorded intensity levels.
Lifetime points & laser period: The phasor semicircle is automatically populated with key lifetime points based on the selected laser period, simplifying the analysis process.
Detailed Statistics: Includes visualization of key metrics such as G mean, S mean, τ𝜙 and τ𝑚 for a deeper understanding of the lifetime distribution.

(back to top)

Fitting Mode

Fitting Mode allows users to identify and estimate the parameters of the mathematical decay model that best describes the acquired data.

Key features of Fitting Mode include:

Automated Model Estimation: Utilizes the scipy library to automatically suggest the model that best fits the decay profile, selecting from 4 exponential decay models.
R² Indicator: Displays the R² value, which quantifies the quality of the fit (values close to 1 indicate a good fit).
Graphical Representation of the Fitted Curve: Visualizes the theoretical curve derived from the estimated parameters.
Residuals Visualization: Graphically displays the difference between observed and estimated values to assess model accuracy.
Linear and Logarithmic Scale Options: Provides flexibility to view data and fits in either linear or logarithmic scale.
Region of Interest (ROI) Selection: Allows users to apply the fitting model to a specific ROI of the acquired data for targeted analysis.

(back to top)

Settings

Spectroscopy includes a comprehensive settings package that allows users to configure their acquisition parameters and hardware connections with ease.

Key features of the settings system include:

Customization: Users can tailor various parameters to match their specific acquisition needs, ensuring seamless integration with their hardware setup.
Automatic retain of configurations: Every configured setting is automatically saved in a settings.ini file, enabling the software to retain user preferences between sessions. This feature saves time by eliminating the need to reconfigure settings with each use.

Below is a list of configurable settings.

Acquisition Channels

The software allows for data acquisition in single-channel or multi-channel mode, with the user able to activate up to 8 channels simultaneously.

For each activated channel, its respective real-time acquisition plot will be displayed on the interface. If the number of activated channels exceeds 4, only the 4 plots configured via the PLOTS CONFIG button will be displayed, for optimization reasons. Data from channels not displayed will still be exported if the export option is activated.

The number of active channels affects the size of the exported data file. With the same values set for bin width and acquisition time , the file size grows proportionally to the number of activated channels.

To start acquisition, at least one channel must be activated.

Note: Ensure that the channel activated in the software corresponds to the channel number being used for acquisition on the FLIM LABS Data Acquisition Card.

Connection Type

The user can choose the type of connection for data acquisition between SMA and USB connections.

Note: The connection type set in the software must match the actual connection type activated on the FLIM LABS Data Acquisition Card.

Sync in and sync out

By selecting Sync In, the user will automatically initiate the process of measuring laser’s frequency. Alternatively, by selecting one of the Sync Out options, the user can choose the desired frequency (80MHz, 40MHz, 20MHz, 10MHz). When the export data mode is active, the size of the generated file will increase in accordance with the number of active channels.

Selecting the Sync value is essential, as it determines the laser frequency and directly impacts the laser period and the time resolution of the measurements. A higher frequency reduces the laser period, enhancing the time resolution and enabling the capture of events in shorter time intervals.
The X-axis of the graphs reflects the laser period, depicting the time period of a single laser pulse. This aspect is crucial because the decay curve represented on the graph is the sum of curves from each chunk, where each chunk is defined by the bin width refer to the bin width section for more details.

The software automatically adjusts the time resolution according to the selected frequency, ensuring precision.
Each decay curve is represented by 256 points, maintaining this constancy despite changes in frequency or temporal resolution.

Selecting a Sync out of 80MHz, we obtain a laser period of 12.5 ns and a temporal resolution of about 48.828 ps; thus, each point represents an interval of approximately 48.828 ps across the cumulative decay curves.

Conversely, at 20MHz, the laser period extends to 50 ns with a temporal resolution of about 195.312 ps, indicating that each point on the curve corresponds to an interval of approximately 195.312 ps across the cumulative decay curves of each chunk.

Bin width

The user can set a bin width value ranging from 100 to 1,000,000 microseconds (μs).

The bin width value specifies the time interval, in microseconds (μs), used to divide the data acquisition into chunks. For each chunk, a theoretical photon decay curve is generated. The final graph represents the cumulative decay curves of each individual chunk. This approach provides a detailed representation of fluorescence over time, illustrating both the intensity and decay of photon signals.

As an example, consider an acquisition time of 10 seconds and a bin width of 10,000 microseconds (μs). This configuration results in the creation of 1000 chunks, each contributing to the overall decay curve displayed in the graph.

This methodology allows users to analyze fluorescence data in a more granular manner, enabling the identification of specific signal characteristics and trends.

The configured bin width value affects the size of the exported data file. With the number of active channels and acquisition time unchanged, the file size grows inversely proportional to the bin width value.

Time span

Time span set the time interval, in seconds, for the last visible data range on the duration x-axis. For instance, if this value is set to 5s, the x-axis will scroll to continuously display the latest 5 seconds of real-time data on the intensity tracing chart. Users can choose a value from 1 to 300 s (seconds).

Acquisition mode

Users can choose between two data acquisition modes: free running or fixed acquisition time.

In free running mode, the total acquisition time is not specified. If users deactivate free running mode, they must set a specific acquisition time value.

The chosen acquisition mode impacts the size of the exported data file.

Acquisition time

When the free running acquisition mode is disabled, users must specify the acquisition time parameter to set the total data acquisition duration. Users can choose a value between 1 and 1800 s (seconds).

For example, if a value of 10 is set, the acquisition will stop after 10 seconds.

The acquisition time value directly affects the final size of the exported data file. Keeping the bin width and active channels values unchanged, the file size increases proportionally to the acquisition time value.

Calibration

When Calibration is set to Phasors Ref, two additional configurable parameters are enabled:

TAU (ns): Defines the decay time in nanoseconds.
Harmonics: Allows selection of up to 4 harmonics for analysis. These parameters serve as the basis for calculating the reference values used to determine the phasor points.

Pile-up thresholds

Users can set a numeric value for the Pile-up threshold (CPS) input to highlight it when the CPS for a specific channel exceeds that threshold.

Show SBR

When the Show SBR parameter is enabled, users can view a Signal-to-Noise Ratio (SBR) value for each channel, providing real-time feedback on the level of noise detected during acquisition.

Phasors Parameters

In Phasors Mode, users can configure the following three additional parameters:

Quantize Phasors: determines whether the phasor points should be quantized (grouped into bins), affecting the precision of the graphical representation.
Squares: Available only if Quantize Phasors is active. Specifies the number of bins for grouping the phasor points.
Harmonic Displayed: Visible only after a Calibration involving multiple harmonics. Allows users to select which harmonic to display on the phasor plot.

Export data

Users can choose to export acquired data in .bin file format for further analysis. Refers to this section for more details:

Spectroscopy Data Export guide

Time Tagger

If the user chooses to export the acquired data, they can also opt to enable or disable the export of Time Tagger data. When enabled, a .bin file will be exported (along with a Python script to read the .bin file) containing information on the type of event and the micro-time and macro-time (ns) at which it was recorded.

Parameters table summary

Here a table summary of the configurable parameters:

Parameter	Data Type	Config	Default	Explanation
`enabled_channels`	number[]	Set a list of enabled acquisition data channels (up to 8). e.g. [0,1,2,3,4,5,6,7]	[]	The list of enabled channels for photons data acquisition.
`connection_type`	number	Set the selected connection type for acquisition (USB or SMA).	0 (“USB”)	If USB (0) is selected, USB firmware is automatically used. If SMA (1) is selected, SMA firmware is automatically used.
`bin_width`	number	Set the numerical value in microseconds. Range: 1-1000000µs.	1000 (µs)	The time duration to wait for photons count accumulation.
`free_running`	boolean	Set the acquisition time mode (True or False).	True	If set to True, the acquisition_time is indeterminate. If set to False, the `acquisition_time` parameter is needed (acquisition duration).
`time_span`	number	Time interval, in seconds, for the visible data range on the duration x-axis. Range: 1-300s.	5	For instance, if `time_span` is set to 5s, the intensity tracing plot x-axis will scroll to continuously display the latest 5 seconds of real-time data on the chart.
`acquisition_time`	number/None	Set the data acquisition duration. Range: 1-1800s.	None	The acquisition duration is indeterminate (None) if free_running is set to True.
`cps_threshold`	number	Set the CPS threshold.	0	If set to a value greater than 0, the user will see the CPS for each channel highlighted when they exceed the set threshold.
`show_sbr`	boolean	Defines whether to visualize the Signal-to-Noise Ratio value for each channel or not.	False	Enables or disables the SBR visualization.
`sync`	string	Set the laser sync type (in/out) and optionally its frequency.	sync_in	Configures synchronization for laser input or output.
`calibration`	number	Defines whether to calculate reference parameters for phasors analysis or not.	0 (None)	If set to Phasors Ref (1), a reference file for phasors analysis will be downloaded.
`tau_ns`	number/None	Set the tau (ns) value for Phasors Ref calculation.	None	Defines the decay time in nanoseconds for Phasors Ref calculations.
`harmonics`	number	Set the number of harmonics (1 to 4) for Phasors Ref calculation.	1	Configures the number of harmonics for Phasors Ref calculations.
`quantize_phasors`	boolean	Defines whether to quantize phasors points or not.	False	If set to True, phasor points will be grouped into bins.
`plots_to_show`	number[]	Defines the number of plots to visualize (max 4).	[]	Specifies the plots to display during acquisition.
`time_shifts`	dict	Defines the key (channel index) / value (time shift) pair for decay curves time shifts.	{}	Configures time shifts for decay curve visualization by channel.
`lin_log_mode`	dict	Defines the key (channel index) / value (LIN/LOG) pair for decay curves linear/logarithmic plot visualization.	{}	Configures the visualization mode (linear or logarithmic) for decay curves by channel.
`write_data`	boolean	Set export data option to True/False.	False	If set to True, the acquired raw data will be exported locally to the computer along with script files (Python/Matlab).
`time_tagger`	boolean	Set export Time Tagger data option to True/False.	True	If set to True, the Time Tagger data will be processed and exported locally to the computer (along with a reader script in Python).

(back to top)

Parameters Configuration Saving

The saving of GUI configuration parameters has been automated. Each interaction with the parameters results in the relative value change being stored in a settings.ini internal file.

On application restart, the saved configuration is automatically loaded. If the settings.ini file is not found, or a specific parameter has not been configured yet, a default configuration will be set.

Here an example of the settings.ini structure:

[General]
app_version=2.4
free_running=false
tau_ns=1
calibration=1
connection_type=0
plots_to_show="[2, 3]"
channel_0=false
channel_1=false
channel_2=true
channel_3=true
channel_4=false
channel_5=false
channel_6=false
channel_7=false
sync=sync_out_40
time_shift="{\"2\": 64, \"3\": 0}"
acquire_read_mode=acquire
harmonic=4
write_data=true
acquisition_time=10
phasors_resolution=2
quantize_phasors=true
lin_log_mode="{\"2\": \"LOG\", \"3\": \"LIN\"}"

(back to top)

Card Connection Detection

The software supports automatic detection of the Flim Card connection. The detection is performed automatically when the app starts and when acquisition begins. The user can also manually run this check at any time by clicking the CHECK DEVICE button. If the card is connected, its ID will be displayed next to the button; otherwise, an error message will appear.

(back to top)

Channels Connections Detection

The software supports automatic detection of channels connections, simply clicking on the Detect Channels button. If connections are found, the system allows the user to update the configuration settings (Channel Type and enabled channels) in an automated way.

(back to top)

Reader Mode

The user can choose to use the software in Reader mode, loading .bin/.json files from external spectroscopy, phasors or fitting data acquisitions. The user can configure which plots to display, with up to 4 channels shown simultaneously. Additionally, they can view the metadata related to the acquisition and download an image in .png and .eps format that replicates the acquisition graphs.

(back to top)

Export Data

If the Export data option is enabled, the acquisition .bin file and the Python and Matlab scripts for manipulating and displaying the acquired data are automatically downloaded at the end of the acquisition, after the user selects a name for the files.

Note: a requirements.txt file — indicating the dependencies needed to run the Python script - will also be automatically downloaded.

Refer to this section for more details:

Spectroscopy Data Export guide

(back to top)

License

Distributed under the MIT License.

(back to top)

Contact

FLIM LABS: info@flimlabs.com

Project Link: FLIM Imager

(back to top)