conninfpy.utils

Statistical utilities for ConnInfPy.

Includes:

conninfpy.utils.fisher_r_to_z(r: ndarray[tuple[Any, ...], dtype[float64]], handle_bounds: bool = True, max_z: float = 5) → ndarray[tuple[Any, ...], dtype[float64]][source]

Apply Fisher r-to-z transformation to correlation coefficients, handling boundary cases.

Parameters:

  • r (np.ndarray) – Array of correlation coefficients with values in [-1, 1]. Can be any shape (scalar, 1D, 2D, …).

  • handle_bounds (bool, optional) – If True, replace infinite z-values (from r = ±1) with finite values. If False, allow infinities and raise a warning. (default: True).

  • max_z (float) – Maximum absolute z-value to use when handle_bounds=True (default: 5).

Returns:

z – Array of z-scores with the same shape as r.

Return type:

np.ndarray

Raises:

ValueError – If any value in r is outside [-1, 1].

Warning

UserWarning

If r contains ±1, indicating boundary values were encountered.

Notes

The transformation is \(z = \operatorname{arctanh}(r)\). For \(r = \pm 1\), \(z\) approaches \(\pm\infty\). When handle_bounds=True, these are capped at ±max_z.

Examples

>>> r_vals = np.array([1.0, -1.0])
>>> fisher_r_to_z(r_vals, handle_bounds=True, max_z=4.0)
array([ 4., -4.])
conninfpy.utils.fisher_z_to_r(z: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Convert Fisher z-scores back to correlation coefficients.

Parameters:

z (np.ndarray): Array of Fisher z-scores (any shape).

Returns:

(np.ndarray): Array of correlation coefficients in (-1, 1) with the same shape as ‘z’ input.

>>> z_vals = np.array([0.0, 1.0, -1.0, 2.0])
>>> fisher_z_to_r(z_vals)
array([ 0.        ,  0.76159416, -0.76159416,  0.96402758])
conninfpy.utils.get_components(A, no_depend=False)[source]

Returns the components of an undirected graph specified by the binary and undirected adjacency matrix adj. Components and their constitutent nodes are assigned the same index and stored in the vector, comps. The vector, comp_sizes, contains the number of nodes beloning to each component.

Parameters:

  • (np.ndarray) (A)

  • (bool (no_depend)

  • optional) (Does nothing, included for backwards compatibility)

Returns:

  • comps (np.ndarray) (Vector of component assignments for each node with dimension (N, 1))

  • comp_sizes (np.ndarray) (Vector of component sizes with dimension (M ,1))

Notes

Note: disconnected nodes will appear as components with a component size of 1

Note: The identity of each component (i.e. its numerical value in the result) is not guaranteed to be identical the value returned in BCT, matlab code, although the component topology is.

Many thanks to Nick Cullen for providing this implementation

>>> A = np.eye(3)
>>> comps, sizes = get_components(A)
>>> comps
array([1, 2, 3])
>>> sizes
array([1, 1, 1])
conninfpy.utils.binarize(W, copy=True)[source]

Binarizes an input weighted connection matrix. If copy is not set, this function will modify W in place.

Parameters:

  • W (NxN np.ndarray) – weighted connectivity matrix

  • copy (bool) – if True, returns a copy of the matrix. Otherwise, modifies the matrix in place. Default value=True.

Returns:

  • W (NxN np.ndarray) – binary connectivity matrix

  • >>> W = np.array([

  • … [0.0, 2.5, 0.0],

  • … [1.1, 0.0, 0.3],

  • … [0.0, 0.0, 0.0]

  • … ])

  • >>> binarize(W)

  • array([[0., 1., 0.], – [1., 0., 1.], [0., 0., 0.]])

conninfpy.utils.create_prior_weights(node_labels: ndarray[tuple[Any, ...], dtype[int64]], target_network_id: int | None = None, boost_factor: float = 2.0) → ndarray[tuple[Any, ...], dtype[float64]][source]

Create an (N, N) symmetric weight matrix based on node network labels.

Parameters:

  • node_labels (np.ndarray[int]) – 1D array of integer network IDs for each node (length N).

  • target_network_id (int or None, optional) – If provided, only edges where both nodes belong to this network are boosted. If None (default), all intra-network edges (nodes sharing the same label) are boosted.

  • boost_factor (float, optional) – Multiplicative weight for priority edges (default 2.0).

Returns:

weights – Symmetric (N, N) weight matrix with background value 1.0 and boost_factor for priority intra-network edges. The diagonal is left at 1.0.

Return type:

np.ndarray[float]

Examples

>>> labels = np.array([1, 1, 2, 2])
>>> create_prior_weights(labels, boost_factor=3.0)
array([[1., 3., 1., 1.],
       [3., 1., 1., 1.],
       [1., 1., 1., 3.],
       [1., 1., 3., 1.]])