flowstab.flow_stability ======================= .. py:module:: flowstab.flow_stability .. autoapi-nested-parse:: Flow Stability Analysis ====================== This sub-module provides tools to perform flow stability analysis on temporal networks using contact sequences. It enables loading temporal network data, computing Laplacian and inter-transition matrices, and extracting flow-based clusterings. It leverages a state-tracking system to ensure that computations are performed in the correct order and that all required data is available before each analysis step. Key Features ------------ - State-tracked analysis pipeline for reproducibility and robustness. - Support for loading and representing temporal (contact sequence) networks. - Computation of Laplacian and inter-transition matrices for random walks. - Flow integral clustering and community detection (e.g., Louvain clustering). - Flexible time scale and direction support for forward/backward dynamics. .. rubric:: Examples A typical usage workflow: >>> from flowstab.flow_stability import FlowStability >>> fs = FlowStability() >>> fs.set_temporal_network(events_table="my_contacts.csv") >>> fs.set_time_scale(10) >>> fs.compute_laplacian_matrices() >>> fs.compute_inter_transition_matrices() >>> fs.time_direction = 0 >>> fs.set_flow_clustering() >>> fs.find_louvain_clustering() >>> print(fs.flow_clustering_forward) Classes ------- FlowStability Main class for performing flow stability analysis on a temporal network. States Enum of analysis states, used for internal state tracking. ProcessException Exception raised for errors in the flow stability process. Attributes ---------- .. autoapisummary:: flowstab.flow_stability.logger flowstab.flow_stability.register Exceptions ---------- .. autoapisummary:: flowstab.flow_stability.ProcessException Classes ------- .. autoapisummary:: flowstab.flow_stability.FlowStability flowstab.flow_stability.States Module Contents --------------- .. py:exception:: ProcessException Bases: :py:obj:`Exception` Common base class for all non-exit exceptions. Initialize self. See help(type(self)) for accurate signature. .. py:class:: FlowStability(*, temporal_network: tempnet.ContTempNetwork | None = None, time_scale: int | float | None = None, t_start: int | float | None = None, t_stop: int | float | None = None, time_direction: int | None = None, **kwargs: Any) Conducts flow stability analysis using a temporal network. This class loads a temporal network (contact sequence) and provides methods for analyzing the stability of flows via Laplacian and inter-transition matrices, and clustering. :raises ValueError: If inputs are not of valid types or parameters are inconsistent. :raises TypeError: If provided types are not as expected. :raises ProcessException: For errors during the processing steps. Initialize a flow stability analysis instance. :param temporal_network: The temporal network data to analyze. :type temporal_network: ContTempNetwork or None, optional :param time_scale: Characteristic time scale for the random walk's transition rate. :type time_scale: int, float, or None, optional :param t_start: Start time for the analysis. :type t_start: int, float, or None, optional :param t_stop: End time for the analysis. :type t_stop: int, float, or None, optional :param time_direction: Direction of time for the analysis (-1, 0, or 1). :type time_direction: int or None, optional :param \*\*kwargs: Additional keyword arguments for initializing the temporal network. :type \*\*kwargs: dict .. py:method:: __repr__() .. py:method:: compute_inter_transition_matrices(linear_approx=False, **kwargs) Compute inter-transition matrices for the temporal network. :param linear_approx: If True, use a linear approximation for the computation. :type linear_approx: bool, optional :param \*\*kwargs: Additional arguments passed to the computation methods. :type \*\*kwargs: dict :returns: **self** -- The instance itself. :rtype: FlowStability .. py:method:: compute_laplacian_matrices(**kwargs) Compute Laplacian matrices for the current temporal network. :param \*\*kwargs: Additional arguments passed to ContTempNetwork's `compute_laplacian_matrices` method. :type \*\*kwargs: dict :returns: **self** -- The instance itself. :rtype: FlowStability .. py:method:: find_louvain_clustering(**kwargs) This method finds the Louvain clusters for a flow integral clustering. :param \*\*kwargs: Arguments passed to FlowIntegralClustering's `find_louvain_clustering` method. :type \*\*kwargs: dict :returns: **self** -- The instance itself. :rtype: FlowStability .. py:method:: help(subject: str | None = None, verbose: bool = False) .. py:method:: set_flow_clustering(**kwargs) Perform flow integral clustering analysis. :param \*\*kwargs: Arguments passed to FlowIntegralClustering. :type \*\*kwargs: dict :returns: **self** -- The instance itself. :rtype: FlowStability .. py:method:: set_temporal_network(**kwargs) Set the temporal network for the flow stability analysis. :param \*\*kwargs: Arguments to initialize a ContTempNetwork instance. If no arguments are provided, the temporal network is set to None. :type \*\*kwargs: dict :returns: **self** -- The instance itself. :rtype: FlowStability .. py:method:: set_time_scale(value: int | float | None = None, **kwargs) Set the time scale(s) for the analysis. :param value: Characteristic random walk inter-event time. If None and `kwargs` is empty, the median inter-event time will be used. :type value: int, float, or None, optional :param \*\*kwargs: Arguments passed to `numpy.logspace` to generate multiple time scales. :type \*\*kwargs: dict :rtype: None .. py:property:: flow_clustering_backward Get the dictionary of backward-time flow integral clustering results. :returns: Maps time_scale values to FlowIntegralClustering objects. :rtype: dict .. py:property:: flow_clustering_forward Get the dictionary of forward-time flow integral clustering results. :returns: Maps time_scale values to FlowIntegralClustering objects. :rtype: dict .. py:property:: lamda Iterator of lambda values, the inverse of the time scales. .. warning:: This attribute is deprecated and will be removed in future versions. Please use `time_scale` which is the inverse of `lambda`, instead. :returns: Each value is the inverse of a time scale, or None if time scale is None. :rtype: iterator of float or None .. py:property:: t_start Start time for Laplacian matrix calculation. The laplacian matrices will be calculated form the first event time before or equal to this time-point. :returns: Start time for Laplacian matrices; events before this time are ignored. :rtype: float or None .. py:property:: t_stop Stop time for Laplacian matrix calculation. The laplacian matrices will be calculated up to the first event time after or equal to this timepoint. :returns: End time for Laplacian matrices; events after this time are ignored. :rtype: float or None .. py:property:: temporal_network The temporal network used as basis for the analysis. :returns: The temporal network currently set for the analysis. :rtype: ContTempNetwork or None .. py:property:: time_direction Get the time direction for the analysis. :returns: Time direction: -1 (backward), 0 (both), or 1 (forward). :rtype: int or None .. py:property:: time_scale Time scales used for random walk transition rates. :returns: * *iterator* -- Iterator over the time scales. Each value determines the rate of the random walk's transitions. * *.. note::* -- Single values are alos returned as an iterator. .. py:class:: States Bases: :py:obj:`flowstab.state_tracking.OrderedEnum` Defines the stages of a flow stability analysis .. py:attribute:: CLUSTERING :value: 4 Ready to compute the Louvain clusters. .. py:attribute:: FINAL :value: 5 Computed all that there is. .. py:attribute:: INITIAL :value: 0 Initiated an flow stability analysis with no, or incomplete data .. py:attribute:: INTER_T :value: 3 Ready to compute the flow integral clustering .. py:attribute:: LAPLAC :value: 2 Ready to calculate the inter transition matrices .. py:attribute:: TEMP_NW :value: 1 Ready to calculate the Laplacian matrices .. py:data:: logger .. py:data:: register