fluopy.transitions ================== .. py:module:: fluopy.transitions .. autoapi-nested-parse:: Define and handle photophysical transitions. Classes ------- .. autoapisummary:: fluopy.transitions.SingleState fluopy.transitions.PairedState fluopy.transitions.Transition fluopy.transitions.TransitionSet Module Contents --------------- .. py:class:: SingleState(*args, **kwds) Bases: :py:obj:`enum.Enum` Assigns a unique identifier (value) to each possible photophysical state. .. py:attribute:: S0 :value: 0 .. py:attribute:: S1 :value: 1 .. py:attribute:: S2 :value: 2 .. py:attribute:: T1 :value: 3 .. py:attribute:: T2 :value: 4 .. py:attribute:: B :value: 5 .. py:attribute:: cis :value: 6 .. py:attribute:: OFF :value: 7 .. py:attribute:: OFF2 :value: 8 .. py:attribute:: R :value: 9 .. py:class:: PairedState(*args, **kwds) Bases: :py:obj:`enum.Enum` Assigns a combination of SingleState to each energy transfer related paired state. E.g., the classical Förster resonance energy transfer needs one fluorophore to be in S1 and another fluorophore closeby to be in S0. After the transition, the first fluorophore will be in S0 and the other in S1. .. py:attribute:: S1_S0 .. py:attribute:: S0_S1 .. py:attribute:: S1_T1 .. py:attribute:: S1_Cis .. py:attribute:: S0_Cis .. py:attribute:: S1_OFF .. py:attribute:: S0_S0 .. py:attribute:: S0_T2 .. py:attribute:: S1_S1 .. py:attribute:: S0_T1 .. py:attribute:: S0_OFF2 .. py:attribute:: S0_OFF .. py:attribute:: S0_B .. py:attribute:: S1_R .. py:attribute:: S0_R .. py:property:: single_state_values :type: tuple[int, int] Returns a tuple of SingleState values. .. py:property:: acceptor :type: SingleState Returns the acceptor (second value). .. py:property:: donor :type: SingleState Returns the donor (first value). .. py:class:: Transition Contains constant and variable attributes of photophysical transitions. :ivar identity: The id of the transition. Not None if transition is part of a TransitionSet. :vartype identity: int :ivar transition_type: The photophysical type of the transitions with its constant attributes. :vartype transition_type: TransitionType :ivar abbreviation: The abbreviation of the transition. :vartype abbreviation: str :ivar initial_state: The initial state of the transition. :vartype initial_state: SingleState | PairedState :ivar final_state: The final state of the transition. :vartype final_state: SingleState | PairedState :ivar rate: The rate of the transition. :vartype rate: float :ivar photon: Whether the transition emits a photon. :vartype photon: bool :ivar fluorophore_ids: Contains the identities of relevant fluorophores. If energy transfer, tuples of fluorophore pairs, where the first is the donor and the second is the acceptor. :vartype fluorophore_ids: list[int] | list[tuple[int, int]] .. py:attribute:: identity :type: int .. py:attribute:: transition_type :type: TransitionType .. py:attribute:: abbreviation :type: str .. py:attribute:: initial_state :type: SingleState | PairedState .. py:attribute:: final_state :type: SingleState | PairedState .. py:attribute:: rate :type: float .. py:attribute:: photon :type: bool .. py:attribute:: fluorophore_ids :type: list[int] | list[tuple[int, int]] .. py:method:: __post_init__() -> None .. py:class:: TransitionSet(transitions: dict[str, list[Transition]], fluorophore_system: fluopy.fluorophores.FluorophoreSystem, keep_zero_rates: bool = False) Collection of all relevant transitions and related attributes. Allows optional post-init-modification and (subsequent) finalization. :ivar transitions: Contains lists of transitions of type Transition with non-zero rate as values and fluorophores or fluorophore-combinations as keys. :vartype transitions: dict[str, list[Transition]] :ivar fluorophore_system: Container for attributes of multiple, interrelated fluorophores. :vartype fluorophore_system: fluopy.fluorophores.FluorophoreSystem :ivar combined_state_transitions_df: Contains realizable combined_state_transitions with their id as index and their other attributes as columns. :vartype combined_state_transitions_df: pd.DataFrame :ivar row_sums: Contains the sum of each row of non-normalized transition rates, i.e., the sum of rates of all possible combined_state_transitions. :vartype row_sums: np.ndarray :ivar single_states: Contains the values of all relevant SingleStates as values. Name of fluorophores as keys. :vartype single_states: dict[str, npt.NDArray[np.int64]] :ivar transition_df: Dataframe of all given transitions with non-zero rate containing their id as second level index and their other attributes as columns. Name of fluorophores as first level index. :vartype transition_df: pd.DataFrame :ivar transition_matrix: Contains the normalized rate constants (i.e., point probabilities) for each possible combined_state_transition at the corresponding index pair. :vartype transition_matrix: np.ndarray .. py:attribute:: transitions .. py:attribute:: fluorophore_system .. py:attribute:: transition_df .. py:attribute:: single_states .. py:property:: combined_state_transitions_df :type: pandas.DataFrame .. py:property:: row_sums :type: numpy.typing.NDArray[numpy.float64] .. py:property:: transition_matrix :type: numpy.typing.NDArray[numpy.float64] .. py:method:: filter_by_identity(remove_list: collections.abc.Collection = None, keep_zero_rates: bool = False) -> TransitionSet Returns another TransitionSet with transitions removed by their identity. :param remove_list: Contains identities of type int. :param keep_zero_rates: Whether to keep transitions with rate 0. :returns: **filtered** -- Re-initialization of the object with the modified transition collection. :rtype: TransitionSet .. py:method:: adjust_rates(change_dict: dict[int, float] = None, keep_zero_rates: bool = False) -> TransitionSet Returns another TransitionSet with transition rates modified. :param change_dict: Contains identities of transitions as key and rates as values. :param keep_zero_rates: Whether to keep transitions with rate 0. :returns: **adjusted** -- Re-initialization of the object with the modified transition collection. :rtype: TransitionSet .. py:method:: remove_zero_rates() -> TransitionSet Returns another TransitionSet with all transitions removed that have a rate constant of zero. :returns: Re-initialization of the object with the modified transition collection. :rtype: TransitionSet .. py:method:: remove_absorbing_states(keep_zero_rates: bool = False) -> TransitionSet Returns another TransitionSet that contains no Markovian absorbing states. :param keep_zero_rates: Whether to keep transitions with rate 0. :returns: **no_abs** -- Re-initialization of the object with the modified transition collection. :rtype: TransitionSet .. py:method:: remove_energy_transfers(keep_zero_rates: bool = False) -> TransitionSet Return another TransitionSet that contains no transitions that are energy transfers. :param keep_zero_rates: Whether to keep transitions with rate 0. :returns: **no_ets** -- Re-initialization of the object with the modified transition collection. :rtype: TransitionSet .. py:method:: finalize() -> Self Construct combined_state_transitions_df, transition_matrix and row_sums. :rtype: self .. py:method:: plot(graph_type: str = 'shell', colors: collections.abc.Collection | None = None, scale: float = 1, axes: collections.abc.Iterable[matplotlib.axes.Axes] | None = None) -> list[matplotlib.axes.Axes] Plot photophysical system as network/graph. :param graph_type: Specifies network layout. One of 'shell', 'circular', 'planar' or 'kamada'. :param colors: Contains two colors as Hex values of type str. :param scale: Factor to scale the figure. :param axes: Axes elements to plot graphs on. :returns: Axes objects with the plots. :rtype: list[matplotlib.axes.Axes]