netneurotools.networks.struct_consensus

netneurotools.networks.struct_consensus(data, distance, hemiid, conn_num_inter=None, conn_num_intra=None, weighted=False)[source]

Calculate distance-dependent group consensus structural connectivity graph.

Takes as input a weighted stack of connectivity matrices with dimensions (N, N, S) where N is the number of nodes and S is the number of matrices or subjects. The matrices must be weighted, and ideally with continuous weights (e.g. fractional anisotropy rather than streamline count). The second input is a pairwise distance matrix, where distance(i,j) is the Euclidean distance between nodes i and j. The final input is an (N, 1) vector which labels nodes as belonging to the right (hemiid==0) or left (hemiid=1) hemisphere (note that these values can be flipped as long as hemiid contains only values of 0 and 1).

This function estimates the average edge length distribution and builds a group-averaged connectivity matrix that approximates this distribution with density equal to the mean density across subjects.

The algorithm works as follows:

  1. Estimate the cumulative edge length distribution,

  2. Divide the distribution into M length bins, one for each edge that will be added to the group-average matrix, and

  3. Within each bin, select the edge that is most consistently expressed expressed across subjects, breaking ties according to average edge weight (which is why the input matrix data must be weighted).

The algorithm works separately on within/between hemisphere links. M is the sum of conn_num_inter and conn_num_intra, if provided. Otherwise, M is estimated from the data.

Parameters:

  • data ((N, N, S) array_like) – Weighted connectivity matrices (i.e., fractional anisotropy), where N is nodes and S is subjects

  • distance ((N, N) array_like) – Array where distance[i, j] is the Euclidean distance between nodes i and j

  • hemiid ((N, 1) array_like) – Hemisphere designation for N nodes where a value of 0/1 indicates node N_{i} is in the right/left hemisphere, respectively

  • conn_num_inter (int, optional) – Number of inter-hemispheric connections to include in the consensus matrix. If None, the number of inter-hemispheric connections will be estimated from the data. Default = None.

  • conn_num_intra (int, optional) – Number of intra-hemispheric connections to include in the consensus matrix. If None, the number of intra-hemispheric connections will be estimated from the data. Default = None.

  • weighted (bool) – Flag indicating whether or not to return a weighted consensus map. If True, the consensus will be multiplied by the mean of data.

Returns:

consensus – Binary (default) or mean-weighted group-level connectivity matrix

Return type:

(N, N) numpy.ndarray

References

Betzel, R. F., Griffa, A., Hagmann, P., & Mišić, B. (2018). Distance- dependent consensus thresholds for generating group-representative structural brain networks. Network Neuroscience, 1-22.