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 usingd.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 usingd.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:
- 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 usingd.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.