fluopy.fluorophores
===================

.. py:module:: fluopy.fluorophores

.. autoapi-nested-parse::

   Define and work with fluorophores.



Classes
-------

.. autoapisummary::

   fluopy.fluorophores.Fluorophore
   fluopy.fluorophores.FluorophoreSystem


Module Contents
---------------

.. py:class:: Fluorophore

   Contains attributes of a fluorophore.

   :ivar identity: The id of the fluorophore. Not None if fluorophore is part of a
                   FluorophoreSystem.
   :vartype identity: int
   :ivar name: Name of the fluorophore.
   :vartype name: str
   :ivar position: The position of the fluorophore in space in nm.
   :vartype position: Collection[float]
   :ivar constants: If None an instance of FluorophoreData with the same name is inserted
                    if available in fluopy.fluo_data.

   :vartype constants: FluorophoreData | None


   .. py:attribute:: identity
      :type:  int
      :value: None



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: position
      :type:  collections.abc.Collection[float]


   .. py:attribute:: constants
      :type:  fluopy.fluo_data.FluorophoreData | None
      :value: None



   .. py:method:: __post_init__() -> None


.. py:class:: FluorophoreSystem

   Container for attributes of multiple, interrelated fluorophores.

   :ivar fluorophores: Contains all given fluorophores of type Fluorophore.
   :vartype fluorophores: Sequence[Fluorophore]
   :ivar multi_type: Whether there are multiple types of fluorophores in the system.
   :vartype multi_type: bool
   :ivar distances: Contains tuples of 2 fluorophore ids as keys and their distance as values.
                    The distances are given in nm and are rounded to 3 decimals.
   :vartype distances: dict[tuple[int, int], np.float64]
   :ivar count: The total number of fluorophores given.

   :vartype count: int


   .. py:attribute:: fluorophores
      :type:  collections.abc.Sequence[Fluorophore]


   .. py:attribute:: multi_type
      :type:  bool


   .. py:attribute:: distances
      :type:  dict[tuple[int, int], numpy.float64]


   .. py:attribute:: count
      :type:  int


   .. py:method:: __post_init__() -> None


   .. py:method:: load_transitions(summarize: bool = False, irradiance: float = 2, wavelength: float = 600, bleaching: bool = False, energy_transfer: bool = True, dstorm: bool = True, energy_transfer_parameters: dict[Literal['dipole_orientation_factor', 'refractive_index', 'overwrite', 'exclude', 'include'], Any] | None = None, dstorm_parameters: dict[str, Any] | None = None) -> dict[str, list[fluopy.transitions.Transition]]

      Derives transitions based on fluorophore and the experimental conditions to be
      mimicked.

      :param summarize: Whether to summarize some transitions into fewer.
      :param irradiance: Irradiance in kW/cm².
      :param wavelength: Wavelength in nm.
      :param bleaching: Whether to incorporate bleaching as a possible transition.
      :param energy_transfer: Whether to incorporate energy transfers as possible transitions.
      :param dstorm: Whether to incorporate dstorm photoswitching as possible transitions.
      :param energy_transfer_parameters: May contain the following keys: dipole_orientation_factor, refractive_index,
                                         overwrite, exclude, include.
                                         Only used if energy_transfer is True.
                                         - overwrite : dict
                                             Contains the type of acceptor state as key and a list with a factor for
                                             the rate as well as an efficiency (of not recycling acceptor state) as
                                             value.
                                         - exclude : list
                                             Contains the type of acceptor state (lowercase) to be excluded.
                                         - include : dict
                                             Contains the type of acceptor state as key and a list of tuples as
                                             values. The tuples contain the transition type and an efficiency. If the
                                             summed efficiencies is e.g., 0.5, all other energy transfers affecting
                                             the acceptor state are multiplied by 1-0.5.
      :param dstorm_parameters: May contain the following keys: reducing_agent, concentration, k_pet, ph.
                                Only used if dstorm is True.

      :returns: **transitions** -- Contains lists of transitions of type Transition as values and fluorophores
                or fluorophore-combinations (D: <donor>, A: <acceptor>, dist: <distance>) as
                keys.
      :rtype: dict[str, list[Transition]]



   .. py:method:: plot(quadratic: bool = True, **kwargs) -> numpy.typing.NDArray[matplotlib.axes.Axes]

      Plot the positions of fluorophores.

      :param quadratic: Whether to display the plot with same x and y axis scaling.
      :param kwargs: fluopy.figure.universal_figure arguments

      :returns: **axes** -- Contains matplotlib.axes._subplots.AxesSubplots.
      :rtype: npt.NDArray[matplotlib.axes.Axes]