FLUTE: A Python GUI for interactive phasor analysis of FLIM data

Fluorescence lifetime imaging microscopy (FLIM) is a powerful technique used to probe the local environment of fluorophores. The fit-free phasor approach to FLIM data is increasingly being used due to its ease of interpretation. To date, no open-source graphical user interface (GUI) for phasor analysis of FLIM data is available in Python, thus limiting the widespread use of phasor analysis in biomedical research. Here, we present Fluorescence Lifetime Ultimate Explorer (FLUTE), a Python GUI that is designed to fill this gap. FLUTE simplifies and automates many aspects of the analysis of FLIM data acquired in the time domain, such as calibrating the FLIM data, performing interactive exploration of the phasor plot, displaying phasor plots and FLIM images with different lifetime contrasts simultaneously, and calculating the distance from known molecular species. After applying desired filters and thresholds, the final edited datasets can be exported for further user-specific analysis. FLUTE has been tested using several FLIM datasets including autofluorescence of zebrafish embryos and in vitro cells. In summary, our user-friendly GUI extends the advantages of phasor plotting by making the data visualization and analysis easy and interactive, allows for analysis of large FLIM datasets, and accelerates FLIM analysis for non-specialized labs.


Running FLUTE
FLUTE can be run in two different ways.

Run exe file in Windows operating system
Download FLUTE.exe from GitHub (https://github.com/LaboratoryOpticsBiosciences/FLUTE)and doubleclick FLUTE.exe.Here we describe an easy procedure to run main.pywith a Mac and/or Windows by automatically downloading all the necessary files from FLUTE's GitHub page: a) Install Anaconda Navigator, which is a GUI to manage Python environments and libraries.The documentation is available here: https://docs.anaconda.com/free/navigator/index.html b) Go to the Environments tab and create a new environment for running FLUTE.It  After installing all dependencies (PyQt5, matplotlib, numpy,opencv-python and scikit-image) with the "pip install" command, the program "python main.py" may fail with the message : qt.qpa.plugin:Could not load the Qt platform plugin "xcb" in "/home/lambry/.local/lib/python3.10/sitepackages/cv2/qt/plugins"This application fails to start because no Qt platform plugin could be initialized.Reinstalling the application fixes this problem.This problem is solved with the commands: pip uninstall opencv-python pip install opencv-python-headless.

Main window navigation
Figure S3 shows how the main window is divided into several sections, referred to as Home, Interactivity, Thresholding, and Table for the remainder of this document.The names of the windows are accessed by pressing the Menu button. Harmonic: Integer multiple applied to laser frequency that will be used to calculate the Fourier Transform FLUTE calculates the Phi Calibration (∆) and M Calibration (∆ ) values (equations 9 and 10 of main text) to be applied for calibration and displays them in the home menu as shown in Fig. 8.An example of fluorescein decay is uploaded on our GitHub repository [1] as Fluorescein.tiffstack.After calibration if you load the same calibration file (Fluorescein.tiff)it is now located at the correct location of 4 ns in the phasor plot (Fig. S4).The same Phi Calibration (∆) and M Calibration (∆ ) values will be applied to all the FLIM data opened with the Load FLIM function.With FLUTE it is possible to perform Phasor analysis at higher frequency of the laser repetition rate, by changing the "Harmonic" parameter in the "Load Calibration" window.An example of calibration with a 0 ns lifetime SHG starch sample (starch SHG-IRF.tiff in our GitHub repository [1]) is shown in Figure S5: the FLIM data set ZF-1100_noEF.tiff is phasor transformed with the first harmonic of the laser repetition rate, i.e. 80MHz (Fig. S5a) and with the second harmonic of the laser repetition rate, i.e. 160MHz (Fig. S5b).

Loading FLIM data
In the Home window, press Load FLIM, and select the data to open.FLIM data must be uploaded as a .tiffstack.You can use the shortcut ctrl+click or shift+click to select multiple datasets at once.The phasor plot with a histogram density color map and intensity image will open for each dataset, and the table will be populated.Figure S6 shows the example of Embryo.tifFLIM file that can be found in on our GitHub repository.

Selecting active datasets using the table
In all following sections, changes to datasets are only applied when the data is active and selected in the table.To select data, either click whichever is desired, or ctrl+click or shift+click to select multiple sets of data.In the example provided in figure S7, changing parameters such as color maps or intensity threshold will only apply to windows 1, 3, and 4, but will not be applied to windows 2 and 5.

Median filter
Successive median filters can be applied to the g and s matrices using the Median Filt entry box within the Thresholding window.A 3x3 convolutional median filter is applied n times to the s and s coordinates of the phasor plot using scipy.signal.medfilt.Figure S8 displays the use of 3 median filters applied to the Embryo.tifFLIM file of a Zebrafish embryo at three hours post fertilization (as for now referred to as 3hpf):

Intensity filter
Minimum and maximum intensity thresholds can be applied using the IntensityMin and IntensityMax entry boxes inside the Thresholding window.The intensity is calculated as the sum of all images in the .tiffstack.As shown in figure S9, applying a min intensity threshold of 25 counts to the 3hpf dataset removes the background:

Changing color maps
FLUTE gives to the user the flexibility to choose the appropriate color mapping to be applied to the FLIM image and the phasor plot simultaneously.For FLIM data exploration and visualization the image window is switchable between the options presented in figure S10.Or, via the thresholding window, shown in figure S12:      Enter Lifetime of Fluorophore (ns) takes in account the phasor coordinates of the molecular species B either inserting the single exponential lifetime or the phasor coordinates g and s in the case of a multiexponential decay.FLUTE then calculates the distance from molecular species B by using equation 15.For example, the distance from free NADH can be calculated graphically and mapped in every pixel from the location of the free NADH that has a known single lifetime of 0.4 ns. Figure S16 displays the application of the distance from free NADH color map in the Embryo.tifFLIM file.

Circle selection
Interactive exploration of the FLIM data can be performed by using multiple colored cursors of variable sizes to select pixels with similar decays and to highlight simultaneously the corresponding pixels in the image.Areas on the phasor plot can be selected by clicking on an active plot.The modification of color and size is done through the Interactivity window using the Color and Radius options.In figure S17, the embryo image is highlighted with a red circle of radius 0.05, and a green circle of radius 0.1, with a greyscale color map.Clicking Clear All Circles removes all circles from the plot.
If there are multiple active datasets, clicking on one active phasor plot will draw the same circle on all other active phasor plots.

Interactivity window
The Interactivity window is used for quick and coarse thresholding of the FLIM data and interactive data exploration.

Range adjustment
Through the interactivity window we can apply a threshold to the phase (), modulation ( ), and distance range simultaneously using the sliders as displayed in figure S18.For example, the phasor of the Embryo.tifFLIM image in (figure S18b) has been applied different parameter thresholds that are represented by the colored lines (red for phase and modulation and blue for distance).The thresholded pixels are represented in black in the phasor plot.Clicking Reset Range function (Fig. 18a) will remove all the applied threshold modifications and will reset the range of the parameters to the default values.
Unclicking Show Range Lines function (Fig. 18a) will remove all the threshold lines from the phasor plot, while keeping the applied threshold to the FLIM data and phasor cloud (Fig. 18c).

Closing datasets
Closing multiple active datasets is possible by choosing all in the table and clicking Close Selected, as shown in figure S19.

Saving data
In addition to fast and interactive FLIM data visualization, analyzed data with applied parameter thresholds can be saved in FLUTE using the Save Data button.Clicking Save Data is followed by a popup window that can save either all the color maps (All Data) or the color map that is on display (Currently Displayed).Saved data is listed below; also, an example is given in figure S20. 10.Batch processing FLUTE has been designed for bulk processing, which is useful for the fast analysis of multiple FLIM data from a single experimental session.
To perform bulk processing, first apply the desired thresholding values in the Thresholding window.On the Home window, click Bulk Process.In the first popup window (figure S21), select the desired data to be processed using ctrl+click or shift+click, and click Open.In the next window, select a folder to save the data.FLUTE will open all datasets; perform the phasor transformation, apply the indicated filters and thresholds, and save all the output data.

Conversion of ISS (.fbd) files to .tiff files
.fbd files from ISS can be exported into .tifffiles from The VistaVision software (See also VistaVision manual pages 28-29) a) Click the icon under the decay plot to open che "Export Data" dropdown list, from which the user can export the raw decay data (Fig. S24).b) Click the "Export Frame Time Decay Raw Data" tab to export the photon counts per time bin, as a single TIFF image file containing a series of images.c) The number of images contained in the signgle TIFF image file is the same as the number of the time bins specified by the TD resolution.The i-th image in the sequence represents the corresponding time bin along the time decay d) When you open the .fbdfile, make sure the supporting files (ifil, xlm) with the same file name is in the same folder as the .fbd.These supporting files are usually automatically generated when the images are saved.e) From the metadata .xlmfile (Fig. S25) extract the acquisition parameters: "Phase" that indicates the number of temporal bins and "Excitation Frequency" that indicated the laser repetition rate f) Calculate the value of the bin width: bin width =1/ Excitation Frequency /Phase

Figure S1 :
Figure S1: Running FLUTE.exe1.2.Run main.py in different operating systems If Python is installed on your system, open the terminal; install all the necessary packages: "pip install PyQt5, numpy, opencv-python, matplotlib, scikit-image"; navigate to the folder containing main.py and type: python main.py.

Figure S2 :
Figure S2: Running main.py using a computer with Python installed Running 'main.py'has been tested to work on different Operating systems: Windows, Linux (with Ubuntu 20 and 22.04) and MacOS including M1 and M2 chips.

Figure S3 :
Figure S3: labeled windows for FLUTE main user interface.On the left, there are the Home window, Interactivity window, and Thresholding window buttons.Table displays the list of loaded data.
To calibrate FLIM data with FLUTE, click Load Calibration on the Home window and enter the setup parameters in the popup window:  Bin Width (ns): Duration of a single temporal bin of the time-domain FLIM acquisition  Laser Freq.(MHz): Laser repetition rate  Tau Ref. (ns): Known lifetime of the single-exponential reference sample (e. g. 4 ns for fluorescein)

Figure S4 :
Figure S4: Calibration windows of FLUTE and example of calibrated experimental fluorescein sample with 4 ns lifetime.

Figure S5 :
Figure S5: Calibration of FLIM image (ZF-1100_noEF.tiff) using the SHG at 0 ns lifetime (starch SHG-IRF.tiff) as a calibration.Phasor transformation and plot are calculated at the first (A) and second (B) harmonic of the laser repetition rate.

Figure S9 :
Figure S9: Applying Intensity threshold to FLIM data.

Figure S10 :
Figure S10: Image visualization options: intensity, lifetime contrasts and distance

Figure S11 :
Figure S11: Thresholding range sliders available in the Interactivity window.

Figure S12 :
Figure S12: Thresholding entry boxes available in the Thresholding window.

8. 2
TauM color map TauModulation (TauM) is calculated with equation 9. Applying the TauM color map to the data and setting the Modulation Min and Modulation Max values to 0.59 and 0.92 in the Thresholding window respectively will produce the image presented in figure S14.

FLUTE
can be used to calculate and map the distance from the molecular species B by inserting the known phasor coordinates of species B. When the Distance color map is selected, a popup window (figureS15) appears with two options: insert the single lifetime of the fluorophore or the g and s phasor location of the molecule in the phasor plot.

Figure S15 :
Figure S15: Entry box to apply options for distance color mapping

Figure S16 :
Figure S16: FLIM Data mapped with the distance from free NADH contrast.

Figure S17 :
Figure S17: Data with intensity color mapping and regions selected with a red circle of radius 0.05 and a green circle of radius 0.1.

Figure S18 :
Figure S18: Range adjustment thought the interactivity window (a) Overview of all available thresholds applied to the data.(b-c) Phasor plots with applied thresholds on the different parameters (phase and modulation and distance with (b) and without (c) colored lines that represent the thresholds.

Figure S19 :
Figure S19: Closing multiple sets of data at once.

Figure S20 :
Figure S20: Example of saved files (left) and parameter file (right)

Figure S21 :
Figure S21: Batch processing five images leads to 75 saved data files inside the selected folder

Figure S24 :Figure S26 :Figure S28 :Figure S29 :
Figure S24: Screenshot of the VistaVision software to Export data is not mandatory, but much recommended, because it will help you to avoid library dependencies in case if you use Python to run other programs.c) In the same Environments tab with the FLUTE environment activated, on the top right corner you can search and install specific versions of libraries.Install necessary packages into new environment with the following command: "pip install PyQt5, numpy, opencv-python, matplotlib, /github.com/LaboratoryOpticsBiosciences/FLUTEand all necessary files will download automatically.Then go to Preferences -> Project: main.py-> Python Interpreter, and select Anaconda environment you've created.e) Run main.pyHere we describe a troubleshooting procedure to run 'main.py'on Linux Operating systems.

Table 1 .
Comparison between FLUTE and other free and open-source software tools for Phasor analysis.