queries

queries

Functions

Name	Description
filter_by_z	Filters a list of nodes to those with a given number of neighbors
find_common_edges	Finds edges shared between two sets of nodes
find_complementary_edges	Finds the complementary edges to a given set of inputs
find_complementary_nodes	Finds the complementary nodes to a given set of inputs
find_connected_nodes	Finds which nodes are connected to a given set of edges
find_connecting_edges	Finds the edge that connects each pair of given nodes
find_coordination	Find the coordination number of nodes
find_neighbor_edges	Finds all edges that are connected to the given input nodes
find_neighbor_nodes	Finds all nodes that are directly connected to the input nodes
find_path	Find the shortest path between pairs of nodes
find_root	Given the current list of node labels, finds the root value for node i
label_clusters	Labels connected clusters in a network using the weighted quick union with
path	Computes the path of nodes between given pore and its root
plot_union	Plots the label array as a tree to visualize clusters.
quick_find	Performs a union between p and q using the Quick-Find algorithm
quick_union	Performs a union between p and q using the Quick-Union algorithm
resolve	Scans all nodes and resolves the final root node for each
union_to_conns	Generates the adjacency matrix from connections in the union in the COO format
union_to_labels	Labels each node according to which cluster is belongs
unionify	Generate a 2-row list of index numbers for each node and weights

filter_by_z

queries.filter_by_z(network, inds, z=1)

Filters a list of nodes to those with a given number of neighbors

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds	array_like	A list containing the indices of the nodes to be filtered	required
z	int	The coordination number by which to filter	1

Returns

Name	Type	Description
inds	array_like	A list of node indices which satisfy the criteria

find_common_edges

queries.find_common_edges(network, inds_1, inds_2)

Finds edges shared between two sets of nodes

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds_1	array_like	A list of indices defining the first set of nodes	required
inds_2	array_like	A list of indices defining the second set of nodes	required

Returns

Name	Type	Description
edges	ndarray	List of edge indices connecting the two given sets of nodes

find_complementary_edges

queries.find_complementary_edges(network, inds, asmask=False)

Finds the complementary edges to a given set of inputs

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds	array_like	A list of edge indices for which the complement is sought	required
asmask	bool	If set to True the result is returned as a boolean mask of the correct length with True values indicate the complements. The default is False which returns a list of indices instead.	False

Returns

Name	Type	Description
	An array containing indices of the edges that are not part of the input
	list

find_complementary_nodes

queries.find_complementary_nodes(network, inds, asmask=False)

Finds the complementary nodes to a given set of inputs

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds	array_like(optional)	A list of indices for which the complement is sought	required
asmask	bool	If set to True the result is returned as a boolean mask of the correct length with True values indicate the complements. The default is False which returns a list of indices instead.	False

Returns

Name	Type	Description
	An array containing indices of the nodes that are not part of the input
	list

find_connected_nodes

queries.find_connected_nodes(network, inds, flatten=True, logic='or')

Finds which nodes are connected to a given set of edges

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds	array_like	A list of edges indices whose connected nodes are sought	required
flatten	bool (default is True)	Indicates whether the returned result is a compressed array of all neighbors, or a list of lists with each sub-list containing the neighbors for each input edge. Note that an unflattened list might be slow to generate since it is a Python list rather than a Numpy array.	True
logic	str	Specifies logic to filter the resulting list. Options are: ======= =============================================================== logic Description ======= =============================================================== ‘or’ (default) All neighbors of the inputs. This is also known as the ‘union’ in set theory or ‘any’ in boolean logic. Both keywords are accepted and treated as ‘or’. ‘xor’ Only neighbors of one and only one inputs. This is useful for finding neighbors that are not shared by any of the input nodes. ‘exclusive_or’ is also accepted. ‘xnor’ Neighbors that are shared by two or more inputs . This is equivalent to finding all neighbors with ‘or’, minus those found with ‘xor’, and is useful for finding neighbors that the inputs have in common. ‘nxor’ is also accepted. ‘and’ Only neighbors shared by all inputs. This is also known as ‘intersection’ in set theory and (sometimes) as ‘all’ in boolean logic. Both keywords are accepted and treated as ‘and’. ======= ===============================================================	'or'

Returns

Name	Type	Description
	An array containing the connected sites, filtered by the given logic. If
	flatten is False then the result is a list of lists containing the
	neighbors of each given input edge. In this latter case, nodes that
	have been removed by the given logic are indicated by nans, thus the
	array is of type float and is not suitable for indexing.

find_connecting_edges

queries.find_connecting_edges(inds, network=None, am=None)

Finds the edge that connects each pair of given nodes

Parameters

Name	Type	Description	Default
inds	array_like	A 2-column vector containing pairs of node indices	required
network	dict	The network dictionary. Either this or am must be provided	None
am	scipy.sparse matrix	The adjacency matrix of the network. Must be symmetrical such that if nodes i and j are connected, the matrix contains non-zero values at locations (i, j) and (j, i). Either this or g must be provided.	None

Returns

Name	Type	Description
edges	ndarray	An ndarry the same length as P1 (and P2) with each element containing the edge number that connects the corresponding nodes, or `nan`` if nodes are not connected.

Notes

The adjacency matrix is converted to the DOK format internally if needed, so if this format is already available it should be provided to save time.

find_coordination

queries.find_coordination(network, nodes=None)

Find the coordination number of nodes

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
nodes	array_like	The nodes for which coordination is sought. If not provided then coordination for all nodes is returned	None

Returns

Name	Type	Description
z	ndarray	An array containing the number of neighbors for each given node

Notes

Supports directed and undirected graphs

find_neighbor_edges

queries.find_neighbor_edges(network, inds, flatten=True, logic='or')

Finds all edges that are connected to the given input nodes

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds	array_like(optional)	A list of node indices whose neighbor edges are sought	required
flatten	bool (default is True)	Indicates whether the returned result is a compressed array of all neighbors, or a list of lists with each sub-list containing the neighbors for each input node. Note that an unflattened list might be slow to generate since it is a Python list rather than a Numpy array.	True
logic	str	Specifies logic to filter the resulting list. Options are: ======= =============================================================== logic Description ======= =============================================================== ‘or’ (default) All neighbors of the inputs. This is also known as the ‘union’ in set theory or ‘any’ in boolean logic. Both keywords are accepted and treated as ‘or’. ‘xor’ Only neighbors of one and only one inputs. This is useful for finding neighbors that are not shared by any of the input nodes. ‘exclusive_or’ is also accepted. ‘xnor’ Neighbors that are shared by two or more inputs . This is equivalent to finding all neighbors with ‘or’, minus those found with ‘xor’, and is useful for finding neighbors that the inputs have in common. ‘nxor’ is also accepted. ‘and’ Only neighbors shared by all inputs. This is also known as ‘intersection’ in set theory and (somtimes) as ‘all’ in boolean logic. Both keywords are accepted and treated as ‘and’. ======= ===============================================================	'or'

Returns

Name	Type	Description
	An array containing the neighboring edges filtered by the given logic. If
	flatten is False then the result is a list of lists containing the
	neighbors of each given input node.

Notes

The logic options are applied to neighboring edges only, thus it is not possible to obtain edges that are part of the global set but not neighbors. This is because (a) the list of global edges might be very large, and (b) it is not possible to return a list of neighbors for each input site if global sites are considered.

find_neighbor_nodes

queries.find_neighbor_nodes(
    network,
    inds,
    flatten=True,
    include_input=False,
    logic='or',
)

Finds all nodes that are directly connected to the input nodes

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
inds	array_like	A list of node indices whose neighbors are sought	required
flatten	bool	If True (default) the returned result is a compressed array of all neighbors, or a list of lists with each sub-list containing the neighbors for each input site. Note that an unflattened list might be slow to generate since it is a Python list rather than a Numpy array.	True
include_input	bool	If False (default) the input nodes will be removed from the result.	False
logic	str	Specifies logic to filter the resulting list. Options are: ======= =============================================================== logic Description ======= =============================================================== ‘or’ (default) All neighbors of the inputs. This is also known as the ‘union’ in set theory or ‘any’ in boolean logic. Both keywords are accepted and treated as ‘or’. ‘xor’ Only neighbors of one and only one inputs. This is useful for finding neighbors that are not shared by any of the input nodes. ‘exclusive_or’ is also accepted. ‘xnor’ Neighbors that are shared by two or more inputs . This is equivalent to finding all neighbors with ‘or’, minus those found with ‘xor’, and is useful for finding neighbors that the inputs have in common. ‘nxor’ is also accepted. ‘and’ Only neighbors shared by all inputs. This is also known as ‘intersection’ in set theory and (somtimes) as ‘all’ in boolean logic. Both keywords are accepted and treated as ‘and’. ======= ===============================================================	'or'

Returns

Name	Type	Description
nodes	ndarray	An array containing the neighboring nodes filtered by the given logic. If flatten is False then the result is a list of lists containing the neighbors of each input site.

Notes

The logic options are applied to neighboring nodes only, thus it is not possible to obtain nodes that are part of the global set but not neighbors. This is because the list of global nodes might be very large.

find_path

queries.find_path(network, pairs, weights=None)

Find the shortest path between pairs of nodes

Parameters

Name	Type	Description	Default
network	dict	The network dictionary	required
pairs	array_like	An N x 2 array containing N pairs of nodes between which the shortest path is sought	required
weights	ndarray	The edge weights to use when traversing the path. If not provided then 1’s will be used.	None

Returns

Name	Type	Description
paths	dict	A dictionary containing 'node_paths' and 'edge_paths', each containing a list of lists indicating the path between each set of nodes given in pairs. An empty list indicates that no path was found between a given set of pairs.

Notes

The shortest path is found using Dijkstra’s algorithm included in the scipy.sparse.csgraph module

find_root

queries.find_root(ind, i, compress=False)

Given the current list of node labels, finds the root value for node i

Parameters

Name	Type	Description	Default
inds	ndarray	The array of current node labels	required
i	int	The index of the node whose actual root is sought	required
compress	boolean	If True this will take the opportunity to compress the tree as it performs the search for the root of i.	False

Returns

Name	Type	Description
root	int	The index of the root node of node i.

label_clusters

queries.label_clusters(conns, active)

Labels connected clusters in a network using the weighted quick union with path compression algorithm

Parameters

Name	Type	Description	Default
conns	ndarray	The COO sparse representation of the networks adjacency matrix	required
active	ndarray	A boolean array the same length as conns with True values indicating that a bond is open or active, meaning that the two sites connected by that bond are part of the same cluster.	required

Returns

Name	Type	Description
labels	ndarray	An array containing the label number of each site in the network.

Notes

Sites not appearing in the conns list (i.e., because they are isolated) will get a label unless their index number is larger than the largest value in conns. In other words, if sites 10 and 100 are both isolated, and the largest value in conns is 99, the site 10 will be given a label, but site 100 will not. The returned array will only be 100 elements long.

path

queries.path(ind, i)

Computes the path of nodes between given pore and its root

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required
i	int	The index of the node whose path is sought	required
Returns			required
path	list	A list of node numbers, starting from i and ending at the root node.	required

plot_union

queries.plot_union(ind, color_by=None, size_by=None, ax=None, **kwargs)

Plots the label array as a tree to visualize clusters.

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required

quick_find

queries.quick_find(ind, p, q)

Performs a union between p and q using the Quick-Find algorithm

The Quick-Find algorithm uses eager relabeling of nodes so all nodes on the same cluster have the same label.

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required
p	int	The index of the two nodes which are to be joined	required
q	int	The index of the two nodes which are to be joined	required

Returns

Name	Type	Description
ind	ndarray	The array of cluster labels updated to indicate the joining of nodes p and q.

Notes

The Quick-Find algorithm is unreasonably slow. It is only included here for comparison, completeness, and academic interest.

quick_union

queries.quick_union(ind, p, q, compress=True, weighted=True)

Performs a union between p and q using the Quick-Union algorithm

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required
p	int	The index of the two nodes which are to be joined.	required
q	int	The index of the two nodes which are to be joined.	required
compress	boolean	This is passed on to the root function to indicate if paths should be compressed while searching for root nodes. This keeps the tree shallow and enhances performance.	True
weighted	boolean	If True then q is attached to p if q is part of a smaller tree, otherwise p is attached to q.	True

Returns

Name	Type	Description
ind	ndarray	The array of updated node labels after connected p and q.

resolve

queries.resolve(ind)

Scans all nodes and resolves the final root node for each

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required

Returns

Name	Type	Description
ind	ndarray	An array containing the node labels all updated to their final root value

union_to_conns

queries.union_to_conns(ind)

Generates the adjacency matrix from connections in the union in the COO format

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required

union_to_labels

queries.union_to_labels(ind)

Labels each node according to which cluster is belongs

Parameters

Name	Type	Description	Default
ind	ndarray	The array of current node labels	required

Returns

Name	Type	Description
labels	ndarray	The cluster label to which each node belongs, starting from 0 and following continously increasing values. Note that in this form the array is no longer a union data set and will provide erroneous results if used as such.

unionify

queries.unionify(N)

Generate a 2-row list of index numbers for each node and weights

Parameters

Name	Type	Description	Default
N	int	The number of elements in the set	required

Returns

Name	Type	Description
inds	ndarray	A numpy array of values ranging from 0 to N in the first row, and weights of 1 for all elements in the second row.