Loader functions

While FRETBursts can load data files from different file formats, we advocate using Photon-HDF5, a file format specifically designed for freely-diffusing single-molecule spectroscopy data.

Photon-HDF5 files can be loaded with the function photon_hdf5(), regardless of the type of excitation or number of spots.

Single-spot μs-ALEX measurement stored in SM files can be loaded via the function usalex() and single-spot ns-ALEX measurement stored in SPC files (Beckr & Hickl) can be loaded via the function nsalex(). To load data from arbitrary format see Load data manually.

Note that regardless of the format, for alternated excitation data, after loading the data you need to apply the alternation parameters using alex_apply_period(). After the parameters are applied you can proceed to background estimation and burst search.

List of loader functions

The loader module contains functions to load each supported data format. The loader functions load data from a specific format and return a new fretbursts.burstlib.Data() object containing the data.

This module contains the high-level function to load a data-file and to return a Data() object. The low-level functions that perform the binary loading and preprocessing can be found in the dataload folder.

fretbursts.loader.alex_apply_period(d, delete_ph_t=True)

Apply the ALEX period definition set in D_ON and A_ON attributes.

This function works both for us-ALEX and ns-ALEX data.

Note that you first need to load the data in a variable d and then set the alternation parameters using d.add(D_ON=..., A_ON=...).

The typical pattern for loading ALEX data is the following:

d = loader.photon_hdf5(fname=fname)
d.add(D_ON=(2850, 580), A_ON=(900, 2580))
alex_plot_alternation(d)

If the plot looks good, apply the alternation with:

loader.alex_apply_period(d)

Now d is ready for further processing such as background estimation, burst search, etc…

fretbursts.loader.nsalex(fname)

Load nsALEX data from a SPC file and return a Data() object.

This function returns a Data() object to which you need to apply an alternation selection before performing further analysis (background estimation, burst search, etc.).

The pattern to load nsALEX data is the following:

d = loader.nsalex(fname=fname)
d.add(D_ON=(2850, 580), A_ON=(900, 2580))
alex_plot_alternation(d)

If the plot looks good apply the alternation with:

loader.alex_apply_period(d)

Now d is ready for further processing such as background estimation, burst search, etc…

fretbursts.loader.nsalex_apply_period(d, delete_ph_t=True)

Applies to the Data object d the alternation period previously set.

Note that you first need to load the data in a variable d and then set the alternation parameters using d.add(D_ON=..., A_ON=...).

The typical pattern for loading ALEX data is the following:

d = loader.photon_hdf5(fname=fname)
d.add(D_ON=(2850, 580), A_ON=(900, 2580))
alex_plot_alternation(d)

If the plot looks good, apply the alternation with:

loader.alex_apply_period(d)

Now d is ready for further processing such as background estimation, burst search, etc…

See also: alex_apply_period().

fretbursts.loader.photon_hdf5(filename, ondisk=False, require_setup=True, validate=False, fix_order=True)

Load a data file saved in Photon-HDF5 format version 0.3 or higher.

Photon-HDF5 is a format for a wide range of timestamp-based single molecule data. For more info please see:

http://photon-hdf5.org/

Parameters
  • filename (str or pathlib.Path) – path of the data file to be loaded.

  • ondisk (bool) – if True, do not load the timestamps in memory using instead references to the HDF5 arrays. Default False.

  • require_setup (bool) – if True (default) the input file need to have a setup group or won’t be loaded. If False, accept files with missing setup group. Use False only for testing or DCR files.

  • validate (bool) – if True validate the Photon-HDF5 file on loading. If False skip any validation.

  • fix_order (bool) – if True fix the order of photons so all are monotonically increaseing in macrotime.

Returns

fretbursts.burstlib.Data object containing the data.

fretbursts.loader.sm_single_laser(fname)

Load SM files acquired using single-laser and 2 detectors.

fretbursts.loader.usalex(fname, leakage=0, gamma=1.0, header=None, BT=None)

Load usALEX data from a SM file and return a Data() object.

This function returns a Data() object to which you need to apply an alternation selection before performing further analysis (background estimation, burst search, etc.).

The pattern to load usALEX data is the following:

d = loader.usalex(fname=fname)
d.add(D_ON=(2850, 580), A_ON=(900, 2580), alex_period=4000)
plot_alternation_hist(d)

If the plot looks good, apply the alternation with:

loader.alex_apply_period(d)

Now d is ready for further processing such as background estimation, burst search, etc…

fretbursts.loader.usalex_apply_period(d, delete_ph_t=True, remove_d_em_a_ex=False)

Applies to the Data object d the alternation period previously set.

Note that you first need to load the data in a variable d and then set the alternation parameters using d.add(D_ON=..., A_ON=...).

The typical pattern for loading ALEX data is the following:

d = loader.photon_hdf5(fname=fname)
d.add(D_ON=(2850, 580), A_ON=(900, 2580))
alex_plot_alternation(d)

If the plot looks good, apply the alternation with:

loader.alex_apply_period(d)

Now d is ready for further processing such as background estimation, burst search, etc…

See also: alex_apply_period().

Load data manually

In case the data is available in a format not directly supported by FRETBursts it is possible to manually create a fretbursts.burstslib.Data object. For example, for non-ALEX smFRET data, two arrays of same length are needed: the timestamps and the acceptor-mask. The timestamps need to be an int64 numpy array containing the recorded photon timestamps in arbitrary units (usually dictated by the acquisition hardware clock period). The acceptor-mask needs to be a numpy boolean array that is True when the corresponding timestamps comes from the acceptor channel and False when it comes from the donor channel. Having these arrays a Data object can be manually created with:

d = Data(ph_times_m=[timestamps], A_em=[acceptor_mask],
         clk_p=10e-9, ALEX=False, nch=1, fname='file_name')

In the previous example, we set the timestamp unit (clk_p) to 10~ns and we specify that the data is not from an ALEX measurement. Creating Data objects for ALEX and ns-ALEX measurements follows the same lines.