# pyFRET Reference¶

class pyFRET.FRET_bursts(donor, acceptor, burst_starts, burst_ends)[source]

This class holds single molecule burst data. Photon bursts are stored in numpy arrays. There is a separate array for each of the two photon streams, for the start and end of each burst and for the burst duration.

The two attributes corresponding to bursts from the four photon streams from a FRET experiment are numpy arrays:

• donor: The donor channel
• acceptor: The acceptor channel

The three further attributes, corresponding to burst duration, burst start time and burst end time are also numpy arrays:

• burst_len: Length (in bins) of each identified burst
• burst_starts: Start time (bin number) of each identified burst
• burst_ends: End time (bn number) of each identified burst

The class can be initialized directly from four lists or arrays: two of burst photon counts; the burst start times and the burst end times: bursts = FRET_bursts(donor_bursts, acceptor_bursts, burst_starts, burst_ends).

However, it is more typically achieved by running the APBS or DCBS algorithm that forms part of the FRET_data class.

RASP(Emin, Emax, Tmin, Tmax, gamma=1.0)[source]

Recurrence Analysis of Single Particles analysis as implemented in Hoffmann et al. Phys Chem Chem Phys. 2011 13(5):1857-1871. Returns a FRET_bursts object.

Arguments: * Emin: minimum value of E (proximity ratio) to consider for initial bursts * Emax: maximum value of E (proximity ratio) to consider for initial bursts * Tmin: start time (in number of bins after the initial burst) to search for recurrent bursts * Tmax: end time (in number of bins after the initial burst) to search for recurrent bursts

Keyword Arguments: * gamma: value of instrumental gamma factor to use in calculating the proximity ratio. Default value = 1.0.

From Hoffmann et al.: First, the bursts b2 must be detected during a time interval between t1 and t2 (the ‘recurrence interval’, T = (t1,t2)) after a previous burst b1 (the ‘initial burst’). Second, the initial bursts must yield a transfer efficiency, E(b1), within a defined range, Delta E1 (the ‘initial E range’).

In this implementation, Tmin and Tmax correspond to t1 and t2 respectively. The initial E range lies between Emin and Emax.

denoise_bursts(N_D, N_A)[source]

Subtract background noise from donor and acceptor bursts.

Arguments:

• N_D: average noise per time-bin in the donor channel
• N_A: average noise per time-bin in the acceptor channel
scatter_intensity(filepath, imgname, imgtype='pdf', labels=['Burst Duration', 'Burst Intensity'])[source]

Plot a scatter plot of burst brightness vs burst duration

Arguments: * filepath: file path to the directory in which the image will be saved * imgname: name under which the image will be saved

Keyword arguments: * imgtype: filetype of histogram image. Accepted values: jpg, tiff, rgba, png, ps, svg, eps, pdf * labels: labels for x and y axes, as a 2-element list of strings: [“x-title”, “y-title”]. Default value: [“Burst Duration”, “Burst Intensity”]

class pyFRET.FRET_data(donor, acceptor)[source]

This class holds single molecule data.

It has two attributes, donor and acceptor to hold photon counts from the donor and acceptor channels respectively. These are numpy arrays.

It can be initialized from two lists or two arrays of photon counts: data = FRET_data(donor_events_list, acceptor_events_list)

APBS(T, M, L)[source]

All-photon bust search algorithm as implemented in Nir et al. J Phys Chem B. 2006 110(44):22103-24. Returns a FRET_bursts object.

Arguments: * T: time-window (in bins) over which to sum photons * M: number of photons in window of length T required to identify a potential burst. * L: total number of photons required for an identified burst to be accepted.

From Nir et al.: The start (respectively, the end) of a potential burst is detected when the number of photons in the averaging window of duration T is larger (respectively, smaller) than the minimum number of photons M. A potential burst is retained if the number of photons it contains is larger than a minimum number L.

DCBS(T, M, L)[source]

Dual-channel bust search algorithm as implemented in Nir et al. J Phys Chem B. 2006 110(44):22103-24. Returns a FRET_bursts object.

Arguments: * T: time-window (in bins) over which to sum photons * M: number of photons in window of length T required to identify a potential burst. * L: total number of photons required for an identified burst to be accepted.

From Nir et al.: The start (respectively, the end) of a potential burst is detected when the number of photons in the averaging window of duration T is larger (respectively, smaller) than the minimum number of photons M. A potential burst is retained if the number of photons it contains is larger than a minimum number L.

build_histogram(filepath, csvname, gamma=1.0, bin_min=0.0, bin_max=1.0, bin_width=0.02, image=False, imgname=None, imgtype=None, gauss=True, gaussname=None, n_gauss=1)[source]

Build a proximity ratio histogram and save the frequencies and bin centres as a csv file. Optionally plot and save a graph and perform a simple gaussian fit.

Arguments:

• E: array of FRET efficiecies
• filepath: path to folder where the histogram will be saved (as a string)
• csvname: the name of the file in which the histogram will be saved (as a string)

Keyword arguments:

• gamma: Instrumental gamma factor. (float, default value 1.0)
• bin_min: the minimum value for a histogram bin (default 0.0)
• bin_max: the maximum value for a histogram bin (default 1.0)
• bin_width: the width of one bin (default 0.02)
• image: Boolean. True plots a graph of the histogram and saves it (default False)
• imgname: the name of the file in which the histogram graph will be saved (as a string)
• imgtype: filetype of histogram image. Accepted values: jpg, tiff, rgba, png, ps, svg, eps, pdf
• gauss: Boolean. True will fit the histogram with a single gaussian distribution (default False)
• gaussname: the name of the file in which the parameters of the Gaussian fit will be saved
• n_gauss: number of Gaussain distributions to fit. Default = 1
make_3d_plot(filepath, imgname, imgtype='pdf', labels=['Donor', 'Acceptor', 'Frequency'])[source]

Make a 3D histogram of donor and acceptor photon counts.

Arguments:

• filepath: path to folder where data will be saved
• filename: name of image file to save plot

Keyword arguments:

• filetype: image type (as string). Default “pdf”. Accepted values: jpg, tiff, rgba, png, ps, svg, eps, pdf
• labels: axes labels, list of strings [“Xtitle”, “Ytitle”, “Ztitle”]. Default [“Donor”, “Acceptor”, “Frequency”]
make_hex_plot(filepath, imgname, imgtype='pdf', labels=['Donor', 'Acceptor'], xmax=None, ymax=None, binning=None)[source]

Make a 2D representation of donor and acceptor photon count frequencies.

Based on the matplotlib.pyplot construction “hexbin”: http://matplotlib.org/api/pyplot_api.html

Arguments:

• filepath: path to folder where data will be saved
• imgname: name of image file to save plot

Keyword arguments:

• imgtype: image type (as string). Default “pdf”. Accepted values: jpg, tiff, rgba, png, ps, svg, eps, pdf

• labels: axes labels, list of strings [“Xtitle”, “Ytitle”]. Default [“Donor”, “Acceptor”]

• xmax: maximum x-axis value. Default None (maximum will be the brightest donor event)

• ymax: maximum x-axis value. Default None (maximum will be the brightest acceptor event)

• binning: type of binning to use for plot. Default: None (bin colour corresponds to frequency).

Accepted vals: “log” (bin colour corresponds to frequency), integer (specifies number of bins), sequence (specifies bin lower bounds)

proximity_ratio(gamma=1.0)[source]

Calculate the proximity ratio (E) and return an array of values.

Arguments: None

Keyword arguments:

• gamma (default value 1.0): the instrumental gamma-factor

Calculation:

E = nA / (nA + gamma*nD) for nA and nD photons in the acceptor and donor channels respectively

subtract_bckd(bckd_d, bckd_a)[source]

Subtract background noise from donor and acceptor channel data.

Arguments:

• bckd_d: average noise per time-bin in the donor channel
• bckd_a: average noise per time-bin in the acceptor channel
subtract_crosstalk(ct_d, ct_a)[source]

Subtract crosstalk from donor and acceptor channels.

Arguments:

• ct_d: fractional cross-talk from donor to acceptor (float between 0 and 1)
• ct_a: fractional cross-talk from acceptor to donor (float between 0 and 1)
threshold_AND(D_T, A_T)[source]

Select data based on the AND thresholding criterion.

Arguments:

• D_T: threshold for the donor channel
• A_T: threshold for the acceptor channel

An event is above threshold if nD > donor_threshold AND nA > acceptor_threshold for nD and nA photons in the donor and acceptor channels respectively

threshold_OR(D_T, A_T)[source]

Select data based on the OR thresholding criterion.

Arguments:

• D_T: threshold for the donor channel
• A_T: threshold for the acceptor channel

An event is above threshold in nD > donor_threshold OR nA > acceptor_threshold for nD and nA photons in the donor and acceptor channels respectively

threshold_SUM(T)[source]

Select data based on the SUM thresholding criterion.

Arguments: T: threshold above which a time-bin is accepted as a fluorescent burst

An event is above threshold in nD + nA > threshold for nD and nA photons in the donor and acceptor channels respectively

pyFRET.fit_mixture(data, ncomp=1)[source]

Fit data using Gaussian mixture model

Arguments:

• data: data to be fitted, as a numpy array

Key-word arguments:

• ncomp (default value 1): number of components in the mixture model.
pyFRET.parse_bin(filepath, filelist, bits=8)[source]

Read data from a list of binary files and return a FRET_data object.

Arguments:

• filepath: the path to the folder containing the files
• filelist: list of files to be analysed

Keyword arguments:

• bits (default value 8): the number of bits used to store a donor-acceptor pair of time-bins
Note: This file structure is probably specific to the Klenerman group’s .dat files.
Please don’t use it unless you know you have the same filetype!
pyFRET.parse_csv(filepath, filelist, delimiter=', ')[source]

Read data from a list of csv and return a FRET_data object.

Arguments:

• filepath: the path to the folder containing the files
• filelist: list of files to be analysed

Keyword arguments:

• delimiter (default ”,”): the delimiter between values in a row of the csv file.

This function assumes that each row of your file has the format: “donor_item,acceptor_item”

If your data does not have this format (for example if you have separate files for donor and acceptor data), this function will not work well for you.