Burst

The burst submodule generates photon bursts using a Markov chain which is dependent on the distance between the donor and acceptor ACV, an experimental burst size distribution as well as quantum yields and fluorescence lifetimes.

class fretraj.burst.Burst(burstsize, QD, QA)

Create a new burst

Parameters:

• burstsize (int) – total number of photons (donor + acceptor) to generate in this burst

• QD (float) – donor fluorescence quantum yield

• QA (float) – acceptor fluorescence quantum yield

addRelaxationEvent(event, decaytime, polarization, is_AA)

Classify the relaxation event

Parameters:

• event (int) – type of relaxation event (1: detected donor photon, -1: internal conversion from donor, 2: detected acceptor photon, -2: internal conversion from acceptor, 0: relaxation due to inter-dye quenching)

• decaytime (float) – time in nanoseconds after the excitation event

• polarization (int) – polarization of the donor or acceptor photon (0: p, parallel, 1: s, orthogonal)

• AA (bool) – If True, relaxation event occured after acceptor excitation (as in an ns-ALEX/PIE experiment). If False, relaxation event occured after donor excitation.

calcFRET(gamma, QD, QA, etaD, etaA)

Calculate the transfer efficiency based on the donor and acceptor photon counts upon donor excitation

Parameters:

• gamma (bool) – If the simulation should be compare to a gamma-corrected experiment, set this parameter to True. If the simulation should be compared to a uncorrected experiment, set this parameter to False.

• QD (float) – donor fluorescence quantum yield

• QA (float) – acceptor fluorescence quantum yield

checkBurstSizeReached(QD, QA, QY_correction)

Check if the number of photons has reached the specified burstsize

Parameters:

• QD (float) – donor fluorescence quantum yield

• QA (float) – acceptor fluorescence quantum yield

• QY_correction (bool) – correct the number of donor and acceptor photons by their respective quantum yield when evaluating whether the burstsize is reached. e.g. say we collected 20 donor photons (with QD=0.5) and 25 acceptor photons (with QA=0.75) and the burstsize is set to be 50. If QY_correction is False, the total photon count is 20+25=45 photons, so the required burstsize is not reached yet. If QY_correction is True, the total photon count is (20/0.5 + 25/0.75 = 73) and so the burst is complete.

class fretraj.burst.Ensemble(directory, parameters, compute_anisotropy=False, verbose=True, units='A')

Instantiate a new ensemble of trajectories from different species

Parameters:

• directory (str) – path to the directory containing the .dat files (rkappa) and .xvg files (dye coordinates)

• parameters (dict) – parameters for the burst, FRET and anisotropy calculations (see tutorial for an example)

• compute_anisotropy (bool, optional=False) – Calculate the time-resolved ensemble anisotropy. Requires a donor and acceptor .xvg file in the directory. Each file should contain xyz-coordinates of two atoms which define the transition dipole of the respective dye.

• verbose (bool, optional=True) – Print status and results to the command line

checkTimeStepIdentity()

Verify that the trajectories of all species in the ensemble have the same time step

class fretraj.burst.Experiment(directory, parameters, binwidth=0.025, compute_anisotropy=False, verbose=True, show_progress=True, units='A')

Setup an in silico fluorescence experiment

Parameters:

• directory (str) – path to the directory containing the .dat files (rkappa) and .xvg files(dye coordinates)

• parameters (dict) – parameters for the burst, FRET and anisotropy calculations (see tutorial for an example)

• binwidth (float, optional=0.025) – time between photon bins

• compute_anisotropy (bool, optional=False) – Calculate the time-resolved ensemble anisotropy. Requires a donor and acceptor .xvg file in the directory where each contains xyz-coordinates of two atoms which define the transition dipole of the dye.

• verbose (bool, optional=True) – Output status and results to the command line

• show_progress (bool, optional=True) – Display the progress of the burst calculation as a status bar

static calcAnisotropy(polIntensity, dipole_angle_abs_em)

Calculate the time-resolved anisotropy decay

Parameters:

• polIntensity (ndarray) – polarization intensity array of shape [n,3] with columns: time bins, p-photons counts (parallel), s-photon counts (orthogonal)

• dipole_angle_abs_em (float) – angle between the absorption and emission dipoles in the absence of depolarization due to rotation

Returns:

ndarray – anisotropy array of shape [n,2] with columns: time bins, anisotropy

References

[1]

Lakowicz, Principles of fluorescence spectroscopy, 3rd ed. (2006), pp.355-358.

calcBurst(burstsize)

Compute a photon burst

Parameters:

burstsize (int) – total number of photons (donor + acceptor) to generate in this burst

Returns:

burst.Burst – Burst object containing a series of relaxation events with associated decaytimes, polarizations and FRET efficiencies

calcBurstsizes()

Compute random burstsizes x_1,x_2,…x_n based on an analytical burstsize distribution P(x) = x^lambda

Returns:

ndarray – array of burstsizes within a range defined by a lower and upper threshold

calcTransferRate(R)

Calculated the time-dependent transfer rate

Parameters:

R (ndarray) – inter-dye distances

Returns:

ndarray – Rates of transfer efficiency dependent on the inter-dye distance, the Förster radius and the relative dye orientation (kappasquare)

calcTransitionRates()

Calculate the time-independent transition rates and probabilities

gaussian(mean, sigma)

Calculate a Gaussian probability density function

Parameters:

• x (array) – independent variable

• mean (float) – expected value

• sigma (float) – standard deviation

Returns:

array – probability density at the given x

classmethod load(filename)

Load an instance of the experiment class from a pickle file

Parameters:

filename (str) – filename of the experiment

static polarizationIntensity(binwidth, decaytimes, polarizations)

Calculate the polarization-resolved fluorescence intensities

Parameters:

• binwidth (float) – time between photon bins

• decaytimes (dict of ndarray) – Decaytimes for the different relaxation types collected from all bursts

• polarizations (dict of ndarray) – Photon polarization for donor photons after donor excitation and acceptor photons after acceptor excitation The encoding is 0 = parallel (p) and 1 = orthogonal (s)

Returns:

ndarray – polarization intensity array of shape [n,3] with columns: time bins, p-photons counts (parallel), s-photon counts (orthogonal)

print_results()

print_settings(compute_anisotropy)

Print the rates and settings of the in-silico experiment

Parameters:

compute_anisotropy (bool) – calculate anisotropy decays from the time-dependent orientation of the dye dipole vector

save(filename, remove_bursts=False)

Pickle the experiment class to a file

Parameters:

• filename (str) – filename for the experiment

• remove_bursts (bool) – remove the bursts from the experiments (strongly reduces the file size)

static shot_noise_width(mean_E, N)

Compute the width (standard deviation) expected due to shot noise given the total number of photons N. When N is the minimal photon threshold for a burst, i.e. parameters[‘burst’][‘lower_limit’], then function returns the maximum width expected solely due to shot noise.

Parameters:

• mean_E (float) – mean transfer efficiency

• N (int) – total number of photons

Returns:

float – standard deviation of a shot-noise limited Gaussian

class fretraj.burst.Relaxation(trajectory, pD_tot, pA_tot, quenching_radius, skipframesatstart, skipframesatend, QD, QA, etaD, etaA, compute_anisotropy)

Create a relaxation event (photon emission or internal conversion)

Parameters:

• trajectory (burst.Trajectory) – trajectory object containing inter-dye distances, kappasquare values and donor/acceptor dye transition dipoles

• pD_tot (float) – probability of a donor relaxation event (photon emission + internal conversion)

• pA_tot (float) – probability of a acceptor relaxation event (photon emission + internal conversion)

• quenching_radius (float) – minimum distance beyond which inter-dye quenching will lead to a non-radiative decay (e.g. Dexter energy transfer)

• skipframesatstart (int) – number of frames to skip at the beginning of the trajectory

• skipframesatend (int) – number of frames to skip at the end of the trajectory

• QD (float) – donor fluorescence quantum yield

• QA (float) – acceptor fluorescence quantum yield

• compute_anisotropy (bool) – Calculate the time-resolved ensemble anisotropy. Requires a donor and acceptor transition dipole to be present in the trajectory.

class fretraj.burst.Species(name, probability, filelist_rkappa, n_trajectory_splits=None, filelist_don_coords=None, filelist_acc_coords=None, units='A')

Create a new species of trajectories

Parameters:

• name (str) – name of the species

• probability (float) – relative weight of the species in the ensemble

• filelist_rkappa (list of str) – list of .dat filenames with inter-dye distance (R) and kappasquare values

• n_trajectory_splits (int, optional=None) – split the trajectory into n parts. Together with averaging=”trajectory” this simulates non-interconverting species which leads to broadening; usually this should be left at the default: None

• filelist_don_coords, filelist_acc_coords (list of str, optional=None) – list of .xvg filenames with xyz coordinates of two atoms defining the transition dipole of the donor or acceptor dye

class fretraj.burst.Trajectory(time, R, kappasquare, donor_xyz=None, acceptor_xyz=None, units='A')

Time trajectory (in ps) of inter-dye distances (in nm) and kappa-square values

Parameters:

• time (array) – time in picoseconds

• R (array) – inter-dye distance in nanometers

• kappasquare (array) – kappasquare values calculated from the orientation of the donor and acceptor transition dipoles

• donor_xyz, acceptor_xyz (ndarray, optional=None) – xyz coordinates of two atoms defining the transition dipole of the donor or the acceptor dye

checkLengthIdentity(traj_length, donor_xyz, acceptor_xyz)

Check that rkappa and dye coordinate files have the same length

Parameters:

• traj_length (int) – number of frames in the trajectory

• donor_xyz, acceptor_xyz (ndarray, optional=None) – xyz coordinates of two atoms defining the transition dipole of the donor or the acceptor dye

classmethod from_file(rkappa_filename, don_coords_filename=None, acc_coords_filename=None, units='A')

Create a burst.Trajectory class from filenames

Parameters:

• rkappa_filename (str) – name of a .dat file containing inter-dye distances and kappasquare values

• don_coords_filename, acc_coords_filename (str, optional=None) – name of an .xvg file containing xyz-coordinates of two atoms defining the transition dipole of the donor or acceptor dye respectively

• units ({‘A’, ‘nm’}, optional=’A’) – distance units (‘A’: Angstroms, ‘nm’: nanometers)

static transitionDipole(dye_xyz)

Compute a normalized transition dipole vector

Parameters:

dye_xyz (numpy.ndarray) – array of shape [n,7] with columns: time, x1, y1, z1, x2, y2, z2 where 1 and 2 are two atoms defining the transition dipole

fretraj.burst.in_notebook()

Check if code is run in IPython notebook. The variable __IPYTHON__ is defined in Jupyter or IPython but not a normal Python interpreter.

Returns:

bool – Returns True if code is executed from Jupyter/IPython notebook

fretraj.burst.parseCmd()

Read the command line arguments

Returns:

tuple of str – path to the directory containing the .dat files (rkappa) and .xvg files(dye coordinates) as well as the path to a JSON-formatted parameter file for the burst, FRET and anisotropy calculations

fretraj.burst.readParameters(parameter_file)

Read parameters from a JSON file

Parameters:

parameter_file (str) – path to a JSON-formatted parameter file (see tutorial for an example)

Returns:

dict – parameters for the burst, FRET and anisotropy calculations