fluopy.emissions ================ .. py:module:: fluopy.emissions .. autoapi-nested-parse:: Work with observable photon emission time series. Classes ------- .. autoapisummary:: fluopy.emissions.Emissions Module Contents --------------- .. py:class:: Emissions(frame_time: str = '5ms', bandpass: tuple[float, float] | None = None, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) Container for emission-associated attributes. :ivar parameters: Contains the parameters with which the instance was initialized. :vartype parameters: dict[str, Any] :ivar event_time_points: 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. :vartype event_time_points: npt.NDArray[np.float64] :ivar event_time_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. :vartype event_time_series: pd.Series .. py:attribute:: parameters :type: dict[str, Any] .. py:attribute:: event_time_points :type: numpy.typing.NDArray[numpy.float64] | None :value: None .. py:attribute:: event_time_series :type: pandas.Series[numpy.int32] | None :value: None .. py:method:: extract(simulation: fluopy.simulation.Simulation) -> None Extracts events from a simulation. The events may be filtered by bandpass. :param simulation: Container for simulation-associated attributes. :rtype: None .. py:method:: 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 Simulates events per time. :param transition_set: Collection of all relevant transitions and related attributes. :param 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. :param size: Size of random_numbers drawn at once. :param frames: Total number of frames to be simulated. :param store_time_points: Whether to also create an array which contains the time points at which photons are detected. :rtype: None .. py:method:: 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] 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. :param transition_set: Collection of all relevant transitions and related attributes. :param number_pulses: Number of pulses to be simulated. :param 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. :param time_between_pulses: Time between two pulses in seconds. :param 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. :param size: Size of random_numbers drawn at once. :param store_time_points: Whether to store the time points at which photons are detected. :param 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. .. py:method:: get_emission_indices(simulation: fluopy.simulation.Simulation, bandpass: tuple[float, float] | None, seed: fluopy.fluopy_types.RandomGeneratorSeed) -> numpy.typing.NDArray[numpy.int64] Get indices to apply to simulation.transition_series to yield (detected) emitting transitions. :param simulation: Container of simulation-associated attributes and methods. :param bandpass: The lowest and highest emission wavelength to be passed by the bandpass filter. :param seed: A seed to initialize the BitGenerator. :returns: **emission_indices** -- Indices of emitting transitions to apply to simulation.transition_series. :rtype: npt.NDArray[np.int64] .. py:method:: construct_event_time_series(simulation: fluopy.simulation.Simulation, resample: str = '5ms') -> None Counts events within a time interval (resample). :param simulation: Container of simulation-associated attributes and methods. :param resample: For possible input values, see https://pandas.pydata.org/docs/user_guide/ timeseries.html -> Offset aliases. :rtype: None .. py:method:: add_photon_collection_objective(p: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> None Adds the effect of photon collection of the objective. :param p: Between 0 and 1. Probability of photons being collected. :type p: float :param seed: A seed to initialize the BitGenerator. :type seed: None, int, BitGenerator, Generator :rtype: None .. py:method:: add_quantum_efficiency(p: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> None Adds the effect of quantum efficiency of the EMCCD. :param p: Between 0 and 1. Quantum efficiency of the EMCCD. :param seed: A seed to initialize the BitGenerator. :rtype: None .. py:method:: add_transmittance(p: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> None Adds the effect of transmittance of a component of the optical path. :param p: Between 0 and 1. Transmittance of the component. :param seed: A seed to initialize the BitGenerator. :rtype: None .. py:method:: add_emccd_gain(emccd_gain: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> None Add the effect of the gain of the EMCCD. :param emccd_gain: The gain of an EMCCD. :param seed: A seed to initialize the BitGenerator. :rtype: None .. py:method:: add_gaussian_noise(mean: float, std: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> None Add artificial noise to the events. The noise is normal distributed and can represent readout noise (insignificant in the case of EMCCD). :param mean: Mean of the normal distributed artificial noise. :param std: Standard deviation of the normal distributed artificial noise. :param seed: A seed to initialize the BitGenerator. :rtype: None .. py:method:: add_poisson_noise(rate: float, seed: fluopy.fluopy_types.RandomGeneratorSeed = None) -> None Add Poisson noise to the events. The noise is Poisson distributed and can represent dark current noise. :param rate: Rate of the Poisson distributed artificial noise. :param seed: A seed to initialize the BitGenerator. :rtype: None .. py:method:: apply_threshold(threshold: int) -> None Apply a threshold to the events. All events below the threshold are set to 0. :param threshold: The minimum value of events to be considered. :type threshold: int :rtype: None .. py:method:: plot_cumulative_events(**kwargs: Any) -> numpy.typing.NDArray[matplotlib.axes.Axes] Plot cumulative events versus time. :param kwargs: fluopy.figure.universal_figure arguments :returns: Contains matplotlib.axes._subplots.AxesSubplots. :rtype: npt.NDArray[mplAxes] .. py:method:: plot_histogram(density: bool = True, display_mean: bool = False, include_0: bool = False, **kwargs: Any) -> numpy.typing.NDArray[matplotlib.axes.Axes] Plot histogram of events. :param density: Whether to display the histogram as probability densities. Else, probabilities. :param display_mean: Whether to display the mean inside the plot. The unit corresponds to the unit of the x-axis. :param include_0: Whether to include counts of 0 events. :param kwargs: fluopy.figure.universal_figure arguments :returns: Contains matplotlib.axes._subplots.AxesSubplots. :rtype: npt.NDArray[mplAxes] .. py:method:: plot_time_series(**kwargs: Any) -> numpy.typing.NDArray[matplotlib.axes.Axes] Plot time series of events. :param kwargs: fluopy.figure.universal_figure arguments :returns: Contains matplotlib.axes._subplots.AxesSubplots. :rtype: npt.NDArray[mplAxes] .. py:method:: save(path: str | pathlib.Path, name_extension: str = '') -> None Saves event_time_series and event_time_points to a file. :param path: Directory where the files shall be stored. :param name_extension: Optional file name extension. :rtype: None .. py:method:: load(path: str | pathlib.Path, name_extension: str = '') -> Emissions :classmethod: 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 :param path: Directory where the files are stored. :param name_extension: Optional file name extension. :returns: **obj** -- Instance of Emissions constructed with existing data. :rtype: fluopy.emissions.Emissions