fluopy.network
==============

.. py:module:: fluopy.network

.. autoapi-nested-parse::

   Represent states and transitions as graph.



Functions
---------

.. autoapisummary::

   fluopy.network.construct_state_graphs
   fluopy.network.construct_transition_graph
   fluopy.network.check_graph_suitable
   fluopy.network.determine_node_order
   fluopy.network.plot_graph
   fluopy.network.draw_networkx_curved_edge_labels


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

.. py:function:: construct_state_graphs(transition_df: pandas.DataFrame) -> list[networkx.MultiDiGraph]

   Constructs graphs of states (nodes) and their transitions (edges). Each fluorophore
   or fluorophore combination gets a separate graph.

   :param 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.

   :returns: **graphs** -- Contains objects of type nx.MultiDiGraph.
   :rtype: list[nx.MultiDiGraph]


.. py:function:: construct_transition_graph(transition_df: pandas.DataFrame) -> networkx.MultiDiGraph

   Constructs a graph of transitions (nodes) and their involved states (edges).

   :param 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.

   :returns: **G** -- Markov chain representation by nodes and edges.
   :rtype: nx.MultiDiGraph


.. py:function:: check_graph_suitable(G: networkx.MultiDiGraph, starting_node: int) -> tuple[bool, list[Any]]

   Checks whether a Markov chain is suitable for an approximation of its development
   in time. This means being acyclic (except cycles that include the starting node).

   :param G: Markov Chain representation by nodes and edges.
   :param starting_node: Numeric value representing the starting node (i.e., state).

   :returns: * **graph_suited** (*bool*) -- Whether the graph is suited for the algorithms.
             * **cycles** (*list*) -- Contains each simple cycle of G.


.. py:function:: determine_node_order(G: networkx.MultiDiGraph, starting_node: int) -> collections.abc.Generator[Any, None, None]

   Determine the order of nodes of a graph such that each node that leads to another
   node has been visited before the other node. Requires the graph to be a DAG
   (directed acyclic graph). If the starting node is part of each cycle, it can be
   removed to convert the graph to DAG.

   :param G: Markov Chain representation by nodes and edges.
   :param starting_node: Numeric value representing the starting node (i.e., state).

   :returns: **node_order** -- Yields the topological sort of the graph.
   :rtype: generator


.. py:function:: plot_graph(G: networkx.MultiDiGraph, graph_type: str = 'shell', colors: collections.abc.Sequence[str] = None, scale: float = 1, ax: matplotlib.axes.Axes | None = None) -> matplotlib.axes.Axes

   Plot graph.
   Adapted from https://stackoverflow.com/questions/22785849/drawing-multiple-edges-
   between-two-nodes-with-networkx.

   :param G: Markov Chain representation by nodes and edges.
   :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 ax: The axes on which to show the image
   :type ax: mpl.Axes

   :returns: Axes object with the plot.
   :rtype: mpl.Axes


.. py:function:: draw_networkx_curved_edge_labels(G: networkx.Graph, pos: dict[Any, Any], ax: matplotlib.axes.Axes | None = None, edge_labels: dict[Any, Any] = None, rad: float = 0) -> matplotlib.axes.Axes

   Draws labels to curved edges.
   Adapted from https://stackoverflow.com/questions/22785849/drawing-multiple-edges-
   between-two-nodes-with-networkx.

   :param G: A networkx graph.
   :param pos: Nodes as keys and positions as values.
   :param ax: Axis to plot on.
   :param edge_labels: Edges (tuples) as keys and labels as values.
   :param rad: Rounding radius of curved edge.

   :returns: **ax**
   :rtype: mpl.Axes