fcs-py

FCS v1.3

Table of Contents

Introduction
GUI Usage
Parameters Configuration Saving
Plots Configuration
Exported Data Visualization
Download Acquired Data
License
Contact

Introduction

Welcome to FCS (Fluorescence Correlation Spectroscopy) v1.3 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, technical requirements and installation of the project, read the FCS Homepage. You can also follow the Data export dedicated guide link.

(back to top)

GUI Usage

The GUI offers advanced parameter configuration functionalities for real-time acquisition of photon intensity traces and subsequent computation of their G(τ) correlations during post-processing. With the ability to enable from 1 to 8 channels simultaneously and configure the desired number and type of correlations (auto and cross) between channels, the software can calculate up to a total of 64 correlation functions (G(τ)). Let’s delve into the configurable parameters in detail:

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.

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.

Correlations

The software provides a guided user interface for selecting correlations between channels, and thus between photon intensity vectors, on which to perform post-processing and calculate G(τ) correlation functions. Users can choose to set both auto-correlations (a channel correlated with itself) and cross-correlations (correlations between different channels). If the user selects a cross-correlation, for example, between channel 6 and channel 8, the reverse correlation (between channel 8 and channel 6) will be automatically set as well. With the ability to activate up to 8 acquisition channels simultaneously, it is possible, by activating all possible correlations, to calculate up to a total of 64 correlation functions.

Bin width

The user can set a bin width choosing between 1, 10, 100 and 1000 values (μs). Bin width represents the duration of time to wait for accumulating photon counts in the exported data file. In the interface plots, this value is adjusted to maintain real-time visualization.

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.

If the user chooses the free-running mode, he cannot specify a value for the averages input (number of acquisitions). Thus, this input will automatically be set to 1.

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.

Averages

The input #averages allows the user to specify the total number of acquisitions to be performed, choosing from a range of 1 to 10. This value is configurable only if the free-running mode is disabled and a specific value for the acquisition time is set. For instance, if the user chooses to conduct 5 acquisitions with an acquisition time of 1 minute, 5 acquisitions of 1-minute duration will be sequentially executed, with a small delay between them.

During FCS post-processing, for each channel pair where a correlation is set, as many G(τ) functions will be calculated as there were acquisitions. The mean of these G(τ) functions will then be computed, representing the final trace visualized on the G(τ) plots.

Note: individual G(τ) functions, along with the mean, can be further analyzed outside the GUI by enabling the data export feature.

CPS threshold

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

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 chart. Users can choose a value from 1 to 300 s (seconds).

Card Connection Detection

Since version 1.1, 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.

Channels Connections Detection

Since version 1.2, 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.

Export data

Users can choose to export FCS post-processing data in .bin and .txt file format for further analysis. Refers to this sections for more details:

Parameters table summary

Here a table summary of the configurable parameters:

	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
`selected_conn_channel`	string	set the selected connection type for acquisition (USB or SMA)	“USB”	If USB is selected, USB firmware is automatically used. If SMA is selected, SMA firmware is automatically used.
`correlations`	list of tuples	Set the list of correlations between couple of channels (from 1 to 64 correlations)	[]
`bin_width_micros`	number	Set the numerical value in microseconds. Range: 1-1000µs	10 (µs)	the time duration to wait for photons count accumulation.
`free_running_acquisition_time`	boolean	Set the acquisition time mode (True or False)	True	If set to True, the acquisition_time_millis is indeterminate. If set to False, the acquisition_time_millis param 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 x-axis will scroll to continuously display the latest 5 seconds of real-time data on the chart
`acquisition_time_millis`	number/None	Set the data acquisition duration. Range: 1-1800s	None	The acquisition duration is indeterminate (None) if free_running_acquisition_time is set to True.
`write_data`	boolean	Set export data option to True/False	False	if set to True, the FCS post-processing raw data will be exported locally to the computer
`#averages`	number	Set the number of acquisitions	1	Configurable only if free running mode is deactivated
`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 in red with a vibrant effect when they exceed the set threshold
`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)

Parameters Configuration Saving

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

The configurable parameters which can be stored in the settings file include:

enabled_channels
selected_conn_channel
selected_firmware
bin_width_micros
time_span
acquisition_time_millis
free_running_acquisition_time
write_data
averages
ch_correlation
gt_plots_to_show
intensity_plots_to_show
cps_threshold

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:

ch_correlations="[[3, 3, false], [3, 5, true], [3, 7, true], [5, 3, true], [5, 5, true], [5, 7, true], [7, 3, true], [7, 5, true], [7, 7, false]]"
gt_plots_to_show="[[3, 3], [3, 7], [7, 3], [7, 7]]"
intensity_plots_to_show="[3, 7]"
enabled_channels="[3, 5, 7]"
write_data=true
bin_width_micros=10
free_running_mode=false
acquisition_time_millis=4000
averages=2
cps_threshold=250000

(back to top)

Plots Configuration

The software provides users with the flexibility to configure the visualization of plots, avoiding cluttering the GUI and facilitating the analysis process.

The central part of the interface is divided into two sections:

The left section displays real-time acquired photon intensity data (either in plot format or showing only the CPS - average counts per second).
The right section displays, after the post-processing of intensity data, the plots related to the calculated G(τ) functions based on the set correlations. More in details:
- The Y-axis represents the values of the G(τ) correlation.
- The X-axis represents the lag index or tau (in microseconds) used for correlation calculation. Users can choose to display up to a maximum of 4 intensity tracing plots (the remaining acquisitions, if any, will be shown in CPS format) and a maximum of 4 G(τ) plots.

Note: the graphs of all calculated G(τ) functions will always be visible in the resulting .bin file if the export data feature is activated.

Exported Data Visualization

The application GUI allows the user to export the FCS post-processing data in binary file format.

The user can also preview the approximate final file size on the GUI. For a detailed guide about data export and binary file structure see:

FCS Data Export guide

(back to top)

Download Acquired Data

If the Export data option is enabled, the acquisition .bin/.txt files 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.

For more details on how to run the saved script, data export and binary file structure refer to: FCS Data Export guide

(back to top)

License

Distributed under the MIT License.

(back to top)

Contact

FLIM LABS: info@flimlabs.com

Project Link: FCS (Fluorescence Correlation Spectroscopy)

(back to top)

This site is open source. Improve this page.