:py:mod:`cubnm.utils`
####################

.. py:module:: cubnm.utils

.. autoapi-nested-parse::

   Utility functions




.. autoapisummary::

   cubnm.utils.avail_gpus
   cubnm.utils.is_jupyter
   cubnm.utils.fc_norm_euclidean
   cubnm.utils.get_bw_params
   cubnm.utils.calculate_fc
   cubnm.utils.calculate_fcd



.. py:function:: avail_gpus()

   Get the number of available GPUs

   Returns
   -------
   :obj:`int`
       Number of available GPUs


.. py:function:: is_jupyter()

   This function checks if the current environment is a Jupyter notebook.

   Returns:
       bool: True if the current environment is a Jupyter notebook, False otherwise.


.. py:function:: fc_norm_euclidean(x, y)

   Calculates Euclidean distance of two FC arrays
   divided by their maximum possible distance, equal
   to the distance of np.ones(n_pairs) and -np.ones(n_pairs)
   or 2 * np.sqrt(n_pairs)

   Parameters
   ----------
   x, y: :obj:`np.ndarray`
       FC arrays. Shape: (n_pairs,)

   Returns
   -------
   :obj:`float`
       Normalized Euclidean distance


.. py:function:: get_bw_params(src)

   Get Balloon-Windkessel model parameters

   Parameters
   ----------
   src: {'friston2003', 'heinzle2016-3T'}
       - 'friston2003': Friston et al. 2003
       - 'heinzle2016-3T': Heinzle et al. 2016, 3T parameters

   Returns
   -------
   :obj:`dict`
       Balloon-Windkessel model parameters


.. py:function:: calculate_fc(bold, exc_interhemispheric=False, return_tril=True)

   Calculates functional connectivity matrix

   Parameters
   ---------
   bold: :obj:`np.ndarray`
       cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes)
       Motion outliers should either be excluded or replaced with zeros.
   exc_interhemispheric: :obj:`bool`, optional
       exclude interhemispheric connections
   return_tril: :obj:`bool`, optional
       return only the lower triangular part of the FCD matrix

   Returns
   -------
   fc: :obj:`np.ndarray`
       FC dynamics matrix. 
       Shape: (nodes, nodes) or (n_node_pairs,)
       if return_tril is True


.. py:function:: calculate_fcd(bold, window_size, window_step, drop_edges=True, outlier_threshold=0.5, exc_interhemispheric=False, return_tril=True, return_dfc=False)

   Calculates functional connectivity dynamics matrix
   and dynamic functional connectivity matrices

   Parameters
   ---------
   bold: :obj:`np.ndarray`
       cleaned and parcellated empirical BOLD time series. Shape: (nodes, volumes)
       Motion outliers should either be excluded (not recommended as it disrupts
       the temporal structure) or replaced with zeros.
   window_size: :obj:`int`, optional
       dynamic FC window size (in TR)
       Must be even. The actual window size is +1 (including center).
   window_step: :obj:`int`, optional
       dynamic FC window step (in TR)
   drop_edges: :obj:`bool`, optional
       drop edge windows which have less than window_size volumes
   outlier_threshold: :obj:`float`, optional
       threshold for the proportion of motion outliers in a window
       that would lead to discarding the window
   exc_interhemispheric: :obj:`bool`, optional
       exclude interhemispheric connections
   return_tril: :obj:`bool`, optional
       return only the lower triangular part of the FCD matrix
   return_dfc: :obj:`bool`, optional
       return dynamic FCs as well

   Returns
   -------
   fcd_matrix: :obj:`np.ndarray`
       FC dynamics matrix. 
       Shape: (n_windows, n_windows) or (n_window_pairs,)
       if return_tril is True
   window_fcs: :obj:`np.ndarray`
       dynamic FCs. Shape: (nodes, nodes, n_windows)
       Returned only if return_dfc is True