API

Python module to fit time-correlated single photon counting (TCSPC) data

Anisotropy

Create an Anisotropy object with four polarization resolved lifetime decays

Parameters:

Name	Type	Description	Default
VV		vertical excitation - vertical emission	required
VH		vertical excitation - horizontal emission	required
HV		horizontal excitation - vertical emission	required
HH		horizontal excitation - horizontal emission	required

Example:

>>> lf.tcspc.Anisotropy(decay['VV'], decay['VH'], decay['HV'],decay['HH'])

G_factor staticmethod

G_factor(HV: np.ndarray, HH: np.ndarray) -> float

Compute G-factor to correct for differences in transmittion effiency of the horizontal and vertical polarized light

Parameters:

Name	Type	Description	Default
HV		horizontal excitation - vertical emission	required
HH		horizontal excitation - horizontal emission	required

Returns:

Type	Description
float	G-factor

Note

The G-factor is defined as follows $$ G = \frac{\int HV}{\int HH} $$

aniso_decay staticmethod

aniso_decay(VV: np.ndarray, VH: np.ndarray, G: float) -> np.ndarray

Compute the anisotropy decay

Parameters:

Name	Type	Description	Default
VV		vertical excitation - vertical emission	required
VH		vertical excitation - horizontal emission	required
G		G-factor	required

Returns:

Type	Description
ndarray	anisotropy decay

Note

The anisotropy decay is calculated from the parallel and perpendicular lifetime decays as follows $$ r(t) = \frac{I_\text{VV} - GI_\text{VH}}{I_\text{VV} + 2GI_\text{VH}} $$

export

export(filename)

Export the data and the fit parameters to a json file

Parameters:

Name	Type	Description	Default
filename		Name of the JSON file	required

hindered_rotation staticmethod

hindered_rotation(time: np.ndarray, r0: float, tau_r: float, r_inf: float) -> np.ndarray

Hindered rotation in-a-cone model

Parameters:

Name	Type	Description	Default
time		time bins	required
r0		fundamental anisotropy	required
tau_r		rotational correlation time	required
r_inf		residual anisotropy at time->inf	required

Returns:

Type	Description
ndarray	hindered rotation anisotropy decay

Hindered-rotation model

\[ f(t) = (r_0 - r_\infty) \exp(-t / \tau_r) + r_\infty \]

local_global_rotation staticmethod

local_global_rotation(time: np.ndarray, r0: float, tau_rloc: float, r_inf: float, tau_rglob: float) -> np.ndarray

Local-global rotation in-a-cone model

Parameters:

Name	Type	Description	Default
time		time bins	required
r0		fundamental anisotropy	required
tau_rloc		local rotational correlation time	required
r_inf		residual anisotropy at time->inf	required
tau_rglob		global rotational correlation time	required

Returns:

Type	Description
ndarray	local-global rotation anisotropy decay

Note

Local-global rotation in-a-cone model $$ f(t) = ((r_0 - r_\infty) \exp(-t / \tau_{r,\text{loc}}) + r_\infty) \exp(-t / \tau_{r,\text{glob}}) $$

one_rotation staticmethod

one_rotation(time: np.ndarray, r0: float, tau_r: float) -> np.ndarray

Single rotator model

Parameters:

Name	Type	Description	Default
time		time bins	required
r0		fundamental anisotropy	required
tau_r		rotational correlation time	required

Returns:

Type	Description
ndarray	two-rotation anisotropy decay

One-rotation model

\[ f(t) = r_0 \exp(-t / \tau_r) \]

rotation_fit

rotation_fit(p0: list[float] = [0.4, 1], model: str = 'one_rotation', manual_interval: Optional[tuple[float]] = None, bounds: tuple[float] = (0, np.inf), verbose: bool = True, ns_before_VVmax: float = 1, signal_percentage: float = 0.01)

Fit rotation model to anisotropy decay.

Parameters:

Name	Type	Description	Default
p0		start values of the chosen anisotropy fit model	[0.4, 1]
model		one of the following anisotropy models: {'one_rotation', 'two_rotations', 'hindered_rotation', 'local_global_rotation'}	'one_rotation'
manual_interval		Time interval in which to fit the anisotropy decay	None
bounds		lower and upper bounds for each parameter in p0. Can be either a tuple of two scalars (same bound for all parameters) or a tuple of array_like with the same length as p0. To deactivate parameter bounds set: bounds=(-np.inf, np.inf)	(0, inf)
verbose		whether to print anisotropy fit result	True
ns_before_VVmax		how many nanoseconds before the maximum of the VV decay should the search for r0 start	1
signal_percentage		percentage of the VV decay serving as a treshold to define the end of the anisotropy fit interval	0.01

Example:

>>> obj.rotation_fit(p0=[0.4, 1, 10, 1], model='two_rotations')

two_rotations staticmethod

two_rotations(time: np.ndarray, r0: float, b: float, tau_r1: float, tau_r2: float) -> np.ndarray

Two-rotator model

Parameters:

Name	Type	Description	Default
time		time bins	required
r0		fundamental anisotropy	required
b		amplitude of second decay	required
tau_r1		first rotational correlation time	required
tau_r2		second rotational correlation time	required

Returns:

Type	Description
ndarray	two-rotation anisotropy decay

Two-rotation model

\[ f(t) = r_0 \exp(-t / \tau_{r1}) + (r_0 - b) \exp(-t / \tau_{r2}) \]

Lifetime

Create lifetime class

Parameters:

Name	Type	Description	Default
fluor_decay		n x 2 array containing numbered channels and intensity counts of the fluorescence decay	required
fluor_ns_per_chan		nanoseconds per channel	required
irf_decay		n x 2 array containing numbered channels and intensity counts for instrument reponse function (IRF). If None, then IRF is approximated by a Gaussian	None
gauss_sigma		standard deviation of the IRF Gaussian	None
gauss_amp		amplitude of the IRF Gaussian	None
shift_time		whether to shift time point 0 to the maximum of the decay	False

Attributes:

Name	Type	Description
ns_per_chan		nanoseconds per channel
fluor		n x 4 array containing time, channel number, intensity counts and associated Poissonian weights of the fluorescence decay
irf		n x 3 array containing time, channel number and intensity counts of the IRF
irf_type		type of IRF: {'Gaussian', 'experimental'}
fit_param		ndarray of fit parameters
fit_param_std		ndarray of standard deviations of fit parameters

Example:

>>> fluor, fluor_nsperchan = lf.tcspc.read_decay(pathToFluorDecay)
>>> irf, irf_nsperchan = lf.tcspc.read_decay(pathToIRF)
>>> lf.tcspc.Lifetime(fluor, fluor_nsperchan, irf)

average_lifetime staticmethod

average_lifetime(a: np.ndarray, tau_val: np.ndarray, tau_std: np.ndarray) -> tuple[float, float]

Calculate average lifetime according to Lakowicz (2010) [1]

Parameters:

Name	Type	Description	Default
a		weighting factors of tau	required
tau_val		fluorescence lifetimes	required
tau_std		standard deviation of the fluorescence lifetimes	required

Returns:

Type	Description
tuple[float, float]	average lifetime and associated standard deviation

References

[1] J. Lakowicz, Principles of Fluorescence, 3rd ed., Springer, 2010.

convolution staticmethod

convolution(irf: np.ndarray, sgl_exp: np.ndarray) -> np.ndarray

Compute convolution of irf with a single exponential decay

Parameters:

Name	Type	Description	Default
irf		intensity counts of the instrument reponse function (experimental of Gaussian shaped)	required
sgl_exp		single-exponential decay	required

Returns:

Type	Description
ndarray	convoluted signal of IRF and exponential decay

exp_decay staticmethod

exp_decay(time: np.ndarray, tau: float) -> np.ndarray

Create a single-exponential decay

Parameters:

Name	Type	Description	Default
time		time bins	required
tau		fluorescence lifetime	required

Returns:

Type	Description
ndarray	single-exponential decay

Note

Single-exponential decay $$ f(t) = \exp(-t / \tau) $$

from_filenames classmethod

from_filenames(fluor_file: str, irf_file: str = None, fileformat: str = 'HORIBA', gauss_sigma: Optional[float] = None, gauss_amp: Optional[float] = None, shift_time: bool = False)

Alternative constructor for the Lifetime class by reading in filename for the fluorophore and IRF decay

Parameters:

Name	Type	Description	Default
fluor_file		filename of the fluorophore decay	required
irf_file		filename of the IRF decay	None
fileformat		currently implemented formats: {'HORIBA'}	'HORIBA'
gauss_sigma		standard deviation of the IRF Gaussian	None
gauss_amp		amplitude of the IRF Gaussian	None
shift_time		whether to shift time point 0 to the maximum of the decay	False

Example:

>>> lf.tcspc.Lifetime.from_filenames(pathToFluorDecay, pathToIRFDecay)

gauss_irf staticmethod

gauss_irf(time: np.ndarray, mu: float, sigma: float = 0.01, A: float = 10000) -> np.ndarray

Calculate a Gaussian-shaped instrument response function (IRF)

Parameters:

Name	Type	Description	Default
time		time bins	required
mu		mean of the Gaussian distribution	required
sigma		standard deviation of the Gaussian distribution	0.01
A		amplitude of the Gaussian distribution	10000

Returns:

Type	Description
ndarray	A Gaussian-shaped instrument response function

nnls_convol_irfexp

nnls_convol_irfexp(x_data: np.ndarray, p0: list[float]) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Solve non-negative least squares for series of IRF-convolved single-exponential decays. First, the IRF is shifted, then convolved with each exponential decay individually (decays 1,...,n), merged into an m x n array (=A) and finally plugged into scipy.optimize.nnls(A, experimental y-data) to compute argmin_x || Ax - y ||_2. This optimizes the relative weight of the exponential decays whereas the curve_fit function optimizes the decay parameters (tau1, taus2, etc.). See also scipy.optimize.nnls.

Parameters:

Name	Type	Description	Default
x_data		array of the independent variable	required
p0		start values for the fit model	required

Returns:

Type	Description
ndarray	A = matrix containing irf-convoluted single-exponential decays in the first n columns and ones in the last column (background counts)
ndarray	x = vector that minimizes the 2-norm || Ax - y ||_2
ndarray	y = fit vector computed as y = Ax

reconvolution_fit

reconvolution_fit(tau0: list[int] = [1], tau_bounds: tuple[float] = (0, np.inf), irf_shift: int = 0, sigma: Optional[np.ndarray] = None, verbose: bool = True)

Fit the experimental lifetime decay to a series of exponentials via interative reconvolution with the instrument reponse function (IRF).

Parameters:

Name	Type	Description	Default
tau0		start value(s) of the fluorescence lifetime(s)	[1]
tau_bounds		lower and upper bounds for each parameter in tau0. Can be either a tuple of two scalars (same bound for all parameters) or a tuple of array_like with the same length as tau0. To deactivate parameter bounds set: bounds=(-np.inf, np.inf)	(0, inf)
irf_shift		shift of the IRF on the time axis (in channel units)	0
sigma		uncertainty of the decay (same length as y_data)	None
verbose		whether to print lifetime fit result	True

Example:

>>> obj.reconvolution_fit([1,5])

fit

fit(fun: Callable, x_data: np.ndarray, y_data: np.ndarray, p0: np.ndarray, bounds: tuple[list[float]] = ([0, 0, 0], [np.inf, np.inf, np.inf]), sigma: Optional[float] = None) -> tuple[np.ndarray, np.ndarray]

Wrapper for the curve_fit function of the scipy.optimize module The curve_fit optimizes the decay parameters (tau1, tau2, etc.) while the nnls weights the exponential decays.

Parameters:

Name	Type	Description	Default
fun		callable The model function f(x,...) taking x values as a first argument followed by the function parameters	required
x_data		array_like array of the independent variable	required
y_data		array_like array of the dependent variable	required
p0		array_like start values for the fit model	required
bounds		2-tuple of float or 2-tuple of array_like, optional lower and upper bounds for each parameter in p0. Can be either a tuple of two scalars (same bound for all parameters) or a tuple of array_like with the same length as p0. To deactivate parameter bounds set: bounds=(-np.inf, np.inf)	([0, 0, 0], [inf, inf, inf])
sigma		array_like, optional uncertainty of the decay (same length as y_data)	None

Returns:

Name	Type	Description
p	ndarray	optimized fit parameters
p_std	ndarray	standard deviation of optimized fit parameters

parseCmd

parseCmd() -> tuple[str, str]

Parse the command line to get the experimental decay and instrument reponse function (IRF) file.

Returns:

Name	Type	Description
fluor_file	str	filename of the fluorescence decay
irf_file	str	filename of the IRF (if None then the IRF is approximated by a Gaussian)

read_decay

read_decay(filepath_or_buffer: Union[str, io.StringIO], fileformat: str = 'Horiba') -> tuple[np.ndarray, float]

Read TCSPC decay file from HORIBA or another data format

Parameters:

Name	Type	Description	Default
filepath_or_buffer		filename of the decay or StringIO object	required
fileformat		currently implemented formats: {'HORIBA'}	'Horiba'

Returns:

Name	Type	Description
decay_data	ndarray	n x 2 decay containing numbered channels and intensity counts for instrument response function (IRF)
ns_per_chan	float	timsteps in nanoseconds between channels