nws_tools.thresh_nws¶

nws_tools.thresh_nws(nws, userdens=None, percval=0.0, force_den=False, span_tree=False)[source]¶

Threshold networks based on connection density

Parameters:

nws : NumPy 3darray Undirected N-by-N (un)weighted connection matrices of numsubs subjects. Format is corrs.shape = (N,N,numsubs) such that corrs[:,:,i] = N x N connection matrix of i-th subject userdens : int By default, the input networks are thresholded down to the lowest common connection density without disconnecting any nodes in the networks using a relative thresholding strategy (force_den = False and span_tree = False). If userdens is provided and span_tree = False, then userdens is used as target density in the relative thresholding strategy. However, if userdens is below the minimum density before networks fragment, it will not be used unless force_den = True. If span_tree = True and userdens is None, then maximum spanning trees will be returned for all input networks. If userdens is provided, the spanning trees will be populated with the strongest connections found in the original networks up to the desired edge density. For both relative thresholding and maximum spanning tree density reduction, userdens should be either None or an integer between 0 and 100. See Notes below for more details. percval : float Percentage value for computing mean network averaged across all thresholded graphs, such that connections not present in at least percval percent of subjects are not considered (0 <= percval <= 1). Default setting is percval = 0.0. See get_meannw for details. force_den : bool If force_den = True relative thresholding is applied to the networks until all graphs hit the desired density level defined by the user even if nodes get disconnected in the process. This argument has no effect if span_tree = True. By default, force_den = False. span_tree : bool If span_tree is True density reduction is performed by constructing maximum spanning trees. If userdens is None, only spanning trees for all input networks will be returned. If userdens is provided, spanning trees will be populated with the strongest connections found in the original networks up to the desired edge density. Note that foce_den is ignored if span_tree is True.

Returns:

Dictionary holding computed quantities. The fields of the dictionary depend upon the values of the optional keyword arguments userdens and span_tree. res : dict Dictionary with fields th_nws : NumPy 3darray Sparse networks. Format is the same as for nws (Not returned if userdens is None and span_tree = True). den_values : NumPy 1darray Density values of the networks stored in th_nws, such that den_values[i] is the edge density of the graph th_nws[:,:,i] (not returned if userdens is None and span_tree = True). th_mnw : NumPy 2darray Mean network averaged across all sparse networks th_nws (not returned if userdens is None and span_tree = True). mnw_percval: float Percentage value used to compute th_mnw (see documentation of get_meannw for details, not returned if userdens is None and span_tree = True). tau_levels : NumPy 1darray Cutoff values used in the relative thresholding strategy to compute th_nws, i.e., tau_levels[i] is the threshold that generated network th_nws[:,:,i] (only returned if span_tree = False). nws_forest : NumPy 3darray Maximum spanning trees calculated for all input networks (only returned if span_tree = True). mean_tree : NumPy 2darray Mean spanning tree averaged across all spanning trees stored in nws_forest (only returned if span_tree = True). mtree_percval : float Percentage value used to compute mean_tree (see documentation of get_meannw for details, only returned if span_tree = True).

See also

get_meannw

Helper function to compute group-averaged networks

backbone_wu

in the Brain Connectivity Toolbox (BCT) for MATLAB, currently available here

Notes

This routine uses either a relative thresholding strategy or a maximum spanning tree approach to decrease the density of a given set of input networks.

During relative thresholding (span_tree = False) edges are discarded based on their value relative to the maximum edge weight found across all networks beginning with the weakest links. By default, the thresholding algorithm uses the lowest common connection density across all input networks before a node is disconnected as target edge density. That means, if networks A, B and C can be thresholded down to 40%, 50% and 60% density, respectively, without disconnecting any nodes, then the lowest common density for thresholding A, B and C together is 60%. In this case the raw network A already has a density of 60% or lower, which is thus excluded from thresholding and the original network is copied into th_nws. If a density level is provided by the user, then the code tries to use it unless it violates connectedness of all thresholded networks - in this case the lowest common density of all networks is used, unless force_den = True which causes the code to employ the user-provided density level for thresholding, disconnecting nodes from the networks in the process.

The maximum spanning tree approach (span_tree = True) can be interpreted as the inverse of relative thresholding. Instead of chipping away weak edges in the input networks until a target density is met (or nodes disconnect), a minimal backbone of the network is calculated and then populated with the strongest connections found in the original network until a desired edge density level is reached. The backbone of the network is calculated by computing the graph’s maximum spanning tree, that connects all nodes with the minimum number of maximum-weight edges. Note, that unless each edge has a distinct unique weight value a graph has numerous different maximum spanning trees. Thus, the spanning trees computed by this routine are usually not unique, and consequently the thresholded networks may not be unique either (particularly for low density levels, for which the computed populated networks are very similar to the underlying spanning trees). Thus, in contrast to the more common relative thresholding strategy, this bottom-up approach allows to reduce a given network’s density to an almost arbitrary level (>= density of the maximum spanning tree) without disconnecting nodes. However, unlike relative thresholding, the computed sparse networks are not necessarily unique and strongly depend on the intial maximum spanning tree. Note that if userdens is None, only maximum spanning trees will be computed.

The code below relies on the routine get_meannw in this module to compute the group-averaged network. Futher, maximum spanning trees are calculated using backbone_wu.m from the Brain Connectivity Toolbox (BCT) for MATLAB via Octave. Thus, it requires Octave to be installed with the BCT in its search path. Further, oct2py is needed to launch an Octave instance from within Python.