brighteyes-ffs 0.0.52

Toolbox for analysing FCS/FFS data with array detectors

BrightEyes-FFS

A toolbox for analysing Fluorescence Correlation Spectroscopy (FCS) and Fluorescence Fluctuation Spectroscopy (FFS) data with array detectors. The fcs module contains libraries for:

• Calculating autocorrelations and cross-correlations of raw FCS/FFS data (i.e. photon counts vs. time or photon arrival time traces). Supported file types include .h5, .ptu, and .czi.
• Fitting correlations to various 2D and 3D diffusion models
• Calibration-free FCS/FFS analysis such as circular-scanning FCS and pair-correlation analysis
• Miscellaneous tools

The fcs_gui module contains libraries for:

• Storing and loading FCS/FFS analysis sessions, as used in the GUI

The pch module contains libraries for:

• Calculating photon counting histograms
• Fitting histograms with Fluorescence Intensity Distribution Analysis (FIDA)

The tools module contains libraries for:

• Fitting various models to data (polynomial, Gaussian, power law, etc.)
• Stokes-Einstein relation
• Save/load 2D arrays to/from .csv files
• Save data to .tiff file
• Miscellaneous tools

---

Installation

You can install brighteyes-ffs via [pip] directly from [PyPI]:

pip install brighteyes-ffs

or using the version on GitHub:

pip install git+https://github.com/VicidominiLab/BrightEyes-FFS

It requires the following Python packages

h5py
joblib
matplotlib>=3.3.2
multipletau>=0.3.3
numpy>=1.19.4
pandas>=1.1.4
scipy
tifffile>=2020.9.29
seaborn
imutils
PyQt5
qdarkstyle
nbformat
ome_types
czifile
brighteyes_ism
notebook
ptufile

Getting started

Supported file types

The current version of the package can read FFS data in .h5, .tiff, .ptu, and .czi files.

For .h5 files generated with BrightEyes-MCS, no pre-processing is needed. For custom .h5 files, make sure to use the keyword 'data' to store the [Nt x Nc] array of FFS data, with Nt the number of time points and Nc the number of channels (detector elements). The easiest way to generate correct .h5 files is with the function brighteyes_ffs.fcs.meas_to_count.numpy2h5, which takes a 2D numpy array as input. If the data contains photon arrival times, the file must contain datasets called "det0", "det1", etc., with each dataset a 2D array [Np x 2] with Np the number of photons, the first column the macrotime in ps, and the second column the microtime in ps.

For .tiff, make sure the data contains one page with a 2D array [Nt x Nc]. Make sure the dwell time in microseconds is stored as a tag called 'dwell_time'.

For .czi files, the data is automatically converted to .h5 upon calculating the correlation. However, the dwell time cannot be automatically read. Instead, make sure a .txt file with the following syntax is stored in the same location as the .czi file. If your file is located at my_path/my_file.czi, then add a .txt file with the same name, i.e. my_path/my_file.txt, with exactly the following two lines of information:

DWELL TIME [us]
17

Replace 17 with your actual dwell time in microseconds. BrightEyes-FFS will automatically generate an .h5 file stored in the same location.

For .ptu files taken with the PicoQuant Luminosa PDA-23 array detector, no pre-processing is needed.

Calculating correlations

The variable file contains the path to the data file (.h5 or .czi). The variable accuracy defines the number of points for which the correlation is calculated. The higher this number, the more points G contains. Note that accuracy does not (always) equal the number of points. The variable split contains the duration of a single chunk of data for which the correlation is calculated. E.g. for a 100 s time trace, split=20 will result in 5 correlations from a 20 s time trace each. The boolean time_trace defines whether or not the time trace should be returned. The variable algorithm defines the algorithm used to calculate the correlation. Valid options are 'multipletau' (time-based) and 'wiener-khinchin' (fft based).

The variable list_of_g contains the various correlations to be calculated. Acceptable entries are (i) integer numbers for calculating the autocorrelation of a given channel, (ii) a pre-defined string (such as 'central', 'sum3', and 'sum5') or (iii) a custom-made string with the following syntax 'Ca+b+...+cxd+...+e': starting with C (for Custom), then a list of channels to sum over (a+b+c), then x, then a second list of channels to sum over. E.g. 'C0+1x2+3' calculates tha cross-correlation between the sum of the channels 0 and 1 and the sum of channels 2 and 3. To calculate the autocorrelation, use simply 'Ca+b+c' (which is equivalent to 'Ca+b+cxa+b+c'). For cross-correlations of single channels, use 'xaabb' with aa and bb the two channel numbers (e.g. 'x0123' for the cross-correlation between channels 1 and 23).

from brighteyes_ffs.fcs.fcs2corr import fcs_load_and_corr_split as correlate
list_of_g = ['central', 'sum3', 'sum5']
G, time_trace = correlate(file, list_of_g=list_of_g, accuracy=16, split=10, time_trace=True, algorithm='multipletau')

G is an object with 2D arrays (tau, G) for each correlation in list_of_g and each chunk of data, e.g. G.central_chunk0 contains the autocorrelation for the central detector element for the first chunk of data. G.central_average contains the average correlation for the central element over the whole data set.

To remove bad chunks of data, e.g. caused by a bright aggregate entering the focal volume, use the following code:

good_chunks = [0, 1, 4, 5, 6, 7, 8, 9] # list with the good chunks of data, i.e., remove chunks 2 and 3 from further analysis
G.average_chunks(good_chunks)

The output of fcs_av_chunks is the same object as before, but now containing attributes such as G.central_averageX, where the X stands for the custom average of the good chunks only.

Fitting correlations

The library fcs_fit contains several fit functions. The variable fitfun can be 'fitfun_2c' (for 1 or 2-component free diffusion), 'fitfun_an' (for 1-component anomalous diffusion), 'fitfun_dualfocus' (for free diffusion with two focii displaced from each other), 'fitfun_circfcs' (for free diffusion with a circularly scanning excitation beam), 'mem_fit_free_diffusion' (for free diffusion with a large number of components), 'fitfun_free_diffusion_2d' (for 1 or 2-component free diffusion in 2D), or 'fcs_analytical_2c_anomalous' (for 2-component anomalous diffusion). The variable fit_info contains 0s and 1s for parameters that have to be kept fixed and fitted, respectively. The variable param contains the starting values for all parameters. Check the library for the order of parameters for each fit function.

from brighteyes_ffs.fcs.fcs_fit import fcs_fit
fitresults = []
for corr in list_of_g:
	Gsingle = getattr(G, corr + '_averageX') # get the average correlation curve
	Gexp = Gsingle[1:,1]
	tau = Gsingle[1:,0]
	fitfun = 'fitfun_2c'
	fit_info = np.asarray([1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0]) # fit N, tauD, and offset (we fit with one component)
	param = np.asarray([1, 1, 1, 1, 1, 0, 0, 3, 0, 0, 0]) # starting values for all parameters
	lBounds = np.asarray([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1])*(-1e6) # lower bounds for all parameters
	uBounds = np.asarray([1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1])*(1e6) # upper bounds for all parameters
	fitresult = fcs_fit(Gexp, tau, fitfun, fit_info, param, lBounds, uBounds, plotInfo=-1)
	fitresults.append(fitresult)

The variable fitresults contains a list of N elements, with N = len(list_of_g), in which each element is the output of a scipy.optimize.least_squares call. E.g. fitresults[0].fun contains the residuals for the first fit (typically the detector central element in spot-variation FCS). Similarly, fitresults[0].x contains the fitted parameter values.

Checking the diffusion law

In spot-variation FCS, the diffusion law tau_D vs w0^2 is plotted and fitted with a linear curve to derive the diffusion modality. Here, tau_D is the diffusion time and w0^2 the beam waist squared for each of the three curves, as found in a calibration measurement. For free diffusion, the fit must go through the origin. A positive intercept with the y-axis means anomalous diffusion caused by microdomain formation, a negative intercept anomalous diffusion caused by a meshwork. To check the diffusion law, use:

taufit = np.asarray([fitresults[i].x[0] for i in range(3)]) # diffusion times in ms for the three curves
w0 = np.asarray([220, 290, 364])*1e-3 # beam waists from calibration in micrometer
fitresult = fit_curve(taufit, w0**2, 'linear', [1, 1], param=[1, 1], lBounds=[-1e6, -1e6], uBounds=[1e6, 1e6], savefig=0) # use 'linear' for y = a*x + b, param = starting values

Plotting the diffusion law:

taufitres = np.zeros(len(w0) + 1)
taufitres[0] = fitresult.x[1]
taufitres[1:] = taufit - fitresult.fun

w02fit = np.zeros(len(w0) + 1)
w02fit[1:] = w0**2

plt.figure()
plt.scatter(w0**2, taufit)
plt.plot(w02fit, taufitres)

GUI

To get familiar with the BrightEyes-FFS package, we highly recommend using the GUI (https://github.com/VicidominiLab/BrightEyes-FFS-GUI) which contains an automatic Jupyter Notebook writing tool.

License

Distributed under the terms of the [GNU GPL v3.0] license, "BrightEyes-FFS" is free and open source software

Contributing

You want to contribute? Great! Contributing works best if you creat a pull request with your changes.

1. Fork the project.
2. Create a branch for your feature: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'My new feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request!