fluopy.emissions

Work with observable photon emission time series.

Classes

Emissions

Container for emission-associated attributes.

Module Contents

class fluopy.emissions.Emissions(frame_time: str = '5ms', bandpass: tuple[float, float] | None = None, seed: fluopy.fluopy_types.RandomGeneratorSeed = None)[source]

Container for emission-associated attributes.

Variables:

  • parameters (dict[str, Any]) – Contains the parameters with which the instance was initialized.

  • event_time_points (npt.NDArray[np.float64]) – The time points at which emissions are happening - they may be filtered by bandpass, however it is not considered whether they actually end up being detected and converted to an electrical voltage. Array of shape (n_time_points,). None until extract(), simulate() or tcspc() has been called.

  • event_time_series (pd.Series) – Contains the time points (increasing by a defined time interval) as index and the number of events as values. Depending on the applied functions events may represent emissions effected by obstacles introduced by the optical path. None until extract(), simulate() or tcspc() has been called.

parameters: dict[str, Any]
event_time_points: numpy.typing.NDArray[numpy.float64] | None = None
event_time_series: pandas.Series[numpy.int32] | None = None
extract(simulation: fluopy.simulation.Simulation) → None[source]

Extracts events from a simulation. The events may be filtered by bandpass.

Parameters:

simulation – Container for simulation-associated attributes.

Return type:

None

simulate(transition_set: fluopy.transitions.TransitionSet, start_at: tuple[int, Ellipsis] | None = None, size: int = 100000.0, frames: int = 10, store_time_points: bool = False) → None[source]

Simulates events per time.

Parameters:

  • transition_set – Collection of all relevant transitions and related attributes.

  • start_at – If None, tuple of as many zeros as number of fluorophores. Can be any combination (size of number of fluorophores) of possible SingleState values. See transition_set.single_states.

  • size – Size of random_numbers drawn at once.

  • frames – Total number of frames to be simulated.

  • store_time_points – Whether to also create an array which contains the time points at which photons are detected.

Return type:

None

tcspc(transition_set: fluopy.transitions.TransitionSet, number_pulses: int = 10000.0, pulse_duration: float = 5e-11, time_between_pulses: float = 1e-07, excitation_rates: dict[str, float] | None = None, size: int = 100000.0, store_time_points: bool = False, details: bool = False) → tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64], fluopy.simulation.Simulation | None][source]

Simulates experimental TCSPC data (i.e., pulsed excitation for fluorescence lifetime measurements). The return value lifetimes_DA contains the S1 durations of detected emissions when energy transfer is available. This does not discriminate between the number or kind of energy transfers. Note that if energy transfer is available, the emitting fluorophore could have been the donor even if other potential donors exist, because all implemented energy transfers have S1 as the donor (e.g., S1|S1|S0 goes to S0|S1|S0 –> S0 potential acceptor, first S1 emitted, both S1 could have been donors). Also note that energy transfer may have become available during the S1 duration of the emitting fluorophore. Also note that the S1 durations are the time differences of photon emission to last laser pulse. For processes other than S0 excitation that are also dependent on the irradiance, the given rates should correspond to the mean irradiance. They will not be adjusted to pulsed excitation.

Parameters:

  • transition_set – Collection of all relevant transitions and related attributes.

  • number_pulses – Number of pulses to be simulated.

  • pulse_duration – The duration of a laser pulse in s. This time is used to calculate the probability of excitation, other than that it is neglected.

  • time_between_pulses – Time between two pulses in seconds.

  • excitation_rates – Contains the fluorophore names as keys and the excitation rates as values. Assumes uniform irradiance over the pulse duration. If None, the irradiance used for the excitation rates in transition_set is assumed to be the mean irradiance of pulse and no pulse duration.

  • size – Size of random_numbers drawn at once.

  • store_time_points – Whether to store the time points at which photons are detected.

  • details – Whether to additionally return a simulation object.

Returns:

  • lifetimes_DA (1-D array_like) – Contains the S1 durations of detected emissions when energy transfer available.

  • lifetimes_D (1-D array_like) – Contains the S1 durations of detected emissions when energy transfer not available.

  • lifetimes_all (1-D array_like) – Contains the S1 durations of all detected emissions.

  • simulation_object (fluopy.simulation.Simulation) – Container for simulation-associated attributes and methods. Only returned if details is True.

get_emission_indices(simulation: fluopy.simulation.Simulation, bandpass: tuple[float, float] | None, seed: fluopy.fluopy_types.RandomGeneratorSeed) → numpy.typing.NDArray[numpy.int64][source]

Get indices to apply to simulation.transition_series to yield (detected) emitting transitions.

Parameters:

  • simulation – Container of simulation-associated attributes and methods.

  • bandpass – The lowest and highest emission wavelength to be passed by the bandpass filter.

  • seed – A seed to initialize the BitGenerator.

Returns:

emission_indices – Indices of emitting transitions to apply to simulation.transition_series.

Return type:

npt.NDArray[np.int64]

construct_event_time_series(simulation: fluopy.simulation.Simulation, resample: str = '5ms') → None[source]

Counts events within a time interval (resample).

Parameters:
Return type:

None

add_photon_collection_objective(p: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) → None[source]

Adds the effect of photon collection of the objective.

Parameters:

  • p (float) – Between 0 and 1. Probability of photons being collected.

  • seed (None, int, BitGenerator, Generator) – A seed to initialize the BitGenerator.

Return type:

None

add_quantum_efficiency(p: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) → None[source]

Adds the effect of quantum efficiency of the EMCCD.

Parameters:

  • p – Between 0 and 1. Quantum efficiency of the EMCCD.

  • seed – A seed to initialize the BitGenerator.

Return type:

None

add_transmittance(p: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) → None[source]

Adds the effect of transmittance of a component of the optical path.

Parameters:

  • p – Between 0 and 1. Transmittance of the component.

  • seed – A seed to initialize the BitGenerator.

Return type:

None

add_emccd_gain(emccd_gain: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) → None[source]

Add the effect of the gain of the EMCCD.

Parameters:

  • emccd_gain – The gain of an EMCCD.

  • seed – A seed to initialize the BitGenerator.

Return type:

None

add_gaussian_noise(mean: float, std: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) → None[source]

Add artificial noise to the events. The noise is normal distributed and can represent readout noise (insignificant in the case of EMCCD).

Parameters:

  • mean – Mean of the normal distributed artificial noise.

  • std – Standard deviation of the normal distributed artificial noise.

  • seed – A seed to initialize the BitGenerator.

Return type:

None

add_poisson_noise(rate: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) → None[source]

Add Poisson noise to the events. The noise is Poisson distributed and can represent dark current noise.

Parameters:

  • rate – Rate of the Poisson distributed artificial noise.

  • seed – A seed to initialize the BitGenerator.

Return type:

None

apply_threshold(threshold: int) → None[source]

Apply a threshold to the events. All events below the threshold are set to 0.

Parameters:

threshold (int) – The minimum value of events to be considered.

Return type:

None

plot_cumulative_events(**kwargs: Any) → numpy.typing.NDArray[matplotlib.axes.Axes][source]

Plot cumulative events versus time.

Parameters:

kwargs – fluopy.figure.universal_figure arguments

Returns:

Contains matplotlib.axes._subplots.AxesSubplots.

Return type:

npt.NDArray[mplAxes]

plot_histogram(density: bool = True, display_mean: bool = False, include_0: bool = False, **kwargs: Any) → numpy.typing.NDArray[matplotlib.axes.Axes][source]

Plot histogram of events.

Parameters:

  • density – Whether to display the histogram as probability densities. Else, probabilities.

  • display_mean – Whether to display the mean inside the plot. The unit corresponds to the unit of the x-axis.

  • include_0 – Whether to include counts of 0 events.

  • kwargs – fluopy.figure.universal_figure arguments

Returns:

Contains matplotlib.axes._subplots.AxesSubplots.

Return type:

npt.NDArray[mplAxes]

plot_time_series(**kwargs: Any) → numpy.typing.NDArray[matplotlib.axes.Axes][source]

Plot time series of events.

Parameters:

kwargs – fluopy.figure.universal_figure arguments

Returns:

Contains matplotlib.axes._subplots.AxesSubplots.

Return type:

npt.NDArray[mplAxes]

save(path: str | pathlib.Path, name_extension: str = '') → None[source]

Saves event_time_series and event_time_points to a file.

Parameters:

  • path – Directory where the files shall be stored.

  • name_extension – Optional file name extension.

Return type:

None

classmethod load(path: str | pathlib.Path, name_extension: str = '') → Emissions[source]

Load event_time_series and event_time_points from file. Adapted from an unpopular answer of https://stackoverflow.com/questions/682504/what-is-a-clean-pythonic-way-to- implement-multiple-constructors

Parameters:

  • path – Directory where the files are stored.

  • name_extension – Optional file name extension.

Returns:

obj – Instance of Emissions constructed with existing data.

Return type:

fluopy.emissions.Emissions