fcs-py

FCS - File Format

Table of Contents

Introduction
File Format
Data Visualization </ul>
Download Example Files
Useful links
License
Contact

Introduction

The FCS (Fluorescence Correlation Spectroscopy) tool allows export of photons intensity vectors correlations (G(τ)), outputted during post-processing, to binary files, with convenient plotting and visualization capabilities. This guide provides an in-depth exploration of the binary file structure, offering a comprehensive understanding of how exported data is formatted and can be leveraged.

(back to top)

File Format

Here a detailed explanation of the exported binary data file structure:

Header (4 bytes):

The first 4 bytes of the file must be FCS1. This serves as a validation check to ensure the correct format of the file. If the check fails, the script prints “Invalid data file” and exits.

Metadata Section (Variable length):

Following the header, metadata is stored in the file. This includes:

JSON length (4 bytes): an unsigned integer representing the length of the JSON metadata.
JSON metadata: this is a variable-length string that contains information about the data, including enabled channels, channels correlations, number of acquisitions, bin width, acquisition time, and additional notes written by the user. This information is printed to the console.

G(τ) data section (Variable length):

After the metadata, the subsequent section, of variable length, contains essential data regarding G(τ) correlations for each pair of correlated channels and the lag index (a vector of tau values used in correlation calculations). The length of this section depends on the number of correlations analyzed, which can range from 1 to 8 channels, resulting in a potential maximum of 64 correlations.

Lag index: this is a vector of unsigned integers, spanning from 0 to the length of the intensity vectors - 1. The lag index (tau) denotes the time lags in microseconds (μs) utilized in computing correlation functions.
G(τ) correlations: This section comprises essential data concerning correlations, organized as a vector of tuples with the following components:
- A tuple of 2 unsigned integers indicating the pair of correlated channels (e.g., (4,8)).
- A G(τ) vector representing the mean of all G(τ) values calculated for the correlated channel pair.
- A vector of G(τ) vectors computed for the correlated channel pair (the number of G(τ) vectors corresponds to the number of acquisitions performed. For instance, if 5 acquisitions were conducted, the resulting vector will contain 5 G(τ) vectors, with each vector derived from a separate acquisition).

(back to top)

Data Visualization

The script files are automatically downloaded along with the intensity and fcs .bin files once the acquisition and fcs post-processing is complete and a file name has been chosen. Follow one of the guides below if you wish to use the Python or Matlab script:

Python script:
- Open the terminal and navigate to the directory where the saved files are located (it is advisable to save and group them in a folder):
```
cd YOUR_DOWNLOADED_DATA_ROOT_FOLDER
```
- Create a virtual environment using the command:
```
python -m venv venv
```
- Activate the virtual environment with the command:
```
venv\Scripts\activate
```
- Install the necessary dependencies listed in the automatically downloaded requirements.txt with:
```
pip install -r requirements.txt
```
- Run your script with:
```
python YOUR_SCRIPT_NAME.py
```
Matlab script:
Simply open your MATLAB command window prompt and, after navigating to the folder containing the script, type the name of the script to launch it.

Useful Links

For more details about the project follow these links:

(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.