conninfpy.utils

Statistical utilities for ConnInfPy.

Includes:

conninfpy.utils.fisher_r_to_z(r: NDArray[float64], handle_bounds: bool = True, max_z: float = 5) → NDArray[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) – Replacement value for boundary inputs when handle_bounds=True (default: 5). Note: max_z replaces z at r = ±1 and their np.isclose neighborhood; it does NOT clip other values — near-boundary inputs outside that tolerance keep their true z.

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[float64]) → NDArray[float64][source]

Convert Fisher z-scores back to correlation coefficients.

Parameters:

z (np.ndarray) – Fisher z-scores, any shape.

Returns:

Correlation coefficients in (-1, 1), same shape as z.

Return type:

np.ndarray

Examples

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

Connected components of an undirected binary graph.

Parameters:

  • A (np.ndarray of shape (N, N)) – Binary undirected adjacency matrix.

  • no_depend (bool, optional) – Does nothing; kept for backwards compatibility.

Returns:

  • comps (np.ndarray of shape (N,)) – Component index (1-based) assigned to each node.

  • comp_sizes (np.ndarray of shape (M,)) – Number of nodes in each component.

Raises:

ValueError – If A is not symmetric.

Notes

Isolated nodes form components of size 1. Component numbering is not guaranteed to match the BCT Matlab implementation, although the component topology is. Thanks to Nick Cullen for the original implementation.

Examples

>>> 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]

Binarize a weighted connectivity matrix: nonzero → 1, zero → 0.

NaN counts as absent data and becomes 0 — missing values must not turn into present edges. With copy=False the input array is modified in place.

Parameters:

  • W (np.ndarray of shape (N, N)) – Weighted connectivity matrix.

  • copy (bool, optional) – If True (default), return a new array; otherwise modify W in place.

Returns:

Binary adjacency matrix (0/1, same dtype behavior as input copy).

Return type:

np.ndarray of shape (N, N)

Examples

>>> 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.]])
>>> binarize(np.array([np.nan, 0.0, 2.0]))
array([0., 0., 1.])
conninfpy.utils.create_prior_weights(node_labels: NDArray[int64], target_network_id: int | None = None, boost_factor: float = 2.0) → NDArray[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.]])