core.network

Provides classes for analyzing spatially embedded complex networks, handling multivariate data and generating time series surrogates.

class pyunicorn.core.network.Network(adjacency=None, n_nodes=None, edge_list=None, directed=False, node_weights=None, silence_level=0)

Bases: Cached

A Network is a simple, undirected or directed graph with optional node and/or link weights. This class encapsulates data structures and methods to represent, generate and analyze such structures.

Network relies on the package igraph for many of its features, but also implements new functionality. Highlights include weighted and directed statistical network measures, measures based on random walks, and node splitting invariant network measures.

Examples:

Create an undirected network given the adjacency matrix:

>>> net = Network(adjacency=[[0,1,0,0,0,0], [1,0,1,0,0,1],
...                          [0,1,0,1,1,0], [0,0,1,0,1,0],
...                          [0,0,1,1,0,1], [0,1,0,0,1,0]])

Create an Erdos-Renyi random graph:

>>> net = Network.Model("ErdosRenyi", n_nodes=100, link_probability=0.05)
Generating Erdos-Renyi random graph with 100 nodes and probability 0.05...

static BarabasiAlbert(n_nodes=100, n_links_each=5)

Return adjacency matrix of a new undirected Barabasi-Albert random graph with exactly n_links_each * (n_nodes-n_links_each) links.

Parameters:

• n_nodes (int > 0) – Number of nodes. (Default: 100)

• n_links_each (int > 0) – Number of links to existing nodes each new node gets during construction. (Default: 5)

Return type:

square array-like [node,node]

Returns:

adjacency matrix of generated network

static BarabasiAlbert_igraph(n_nodes=100, n_links_each=5)

Return adjacency matrix of a new undirected Barabasi-Albert random graph generated by igraph.

CAUTION: actual no. of new links can be smaller than n_links_each because neighbours are drawn with replacement and graph is then simplified.

The given number of nodes are added in turn to the initially empty node set, and each new node is linked to the given number of existing nodes. The resulting link density is approx. 2 * n_links_each/n_nodes.

Example: Generating a random tree:

>>> A = Network.BarabasiAlbert_igraph(n_nodes=100, n_links_each=1)

Parameters:

• n_nodes (int > 0) – Number of nodes. (Default: 100)

• n_links_each (int > 0) – Number of links to existing nodes each new node gets during construction. (Default: 5)

Return type:

square array-like [node,node]

Returns:

adjacency matrix of generated network

static Configuration(degree)

Return adjacency matrix of a new configuration model random graph with a given degree sequence.

Example: Generate a network of 1000 nodes with degree 3 each:

>>> A = Network.Configuration([3 for _ in range(0,1000)]))
Generating configuration model random graph
from given degree sequence...

Parameters:

• degree (1d numpy array or list [node]) – Array or list of degree wanted.

• silence_level (int >= 0) – The higher, the less progress info is output.

Return type:

square array-like [node,node]

Returns:

adjacency matrix of generated network

static ErdosRenyi(n_nodes=100, link_probability=None, n_links=None, silence_level=0)

Return adjacency matrix of a new undirected Erdos-Renyi random graph with a given number of nodes and linking probability.

The expected link density equals this probability.

Example:

>>> A = Network.ErdosRenyi(n_nodes=10, n_links=18)
Generating Erdos-Renyi random graph with 10 nodes and 18 links...

Parameters:

• n_nodes (int > 0) – Number of nodes. (Default: 100)

• link_probability (float from 0 to 1, or None) – If not None, each pair of nodes is independently linked with this probability. (Default: None)

• n_links (int > 0, or None) – If not None, this many links are assigned at random. Must be None if link_probability is not None. (Default: None)

• silence_level (int >= 0) – The higher, the less progress info is output.

Return type:

square array-like [node,node]

Returns:

adjacency matrix of the generated model network

static FromIGraph(graph, silence_level=0)

Return a Network object given an igraph Graph object.

Parameters:

• graph (igraph Graph object) – The igraph Graph object to be converted.

• silence_level (int >= 0) – The higher, the less progress info is output.

Return type:

Network instance

Returns:

Network object.

static GrowWeights(n_nodes=100, n_initials=1, exponent=1, mode='exp', split_prob=0.01, split_weight=100, beta=1.0, n_increases=1e+100)

EXPERIMENTAL

static Load(filename, fileformat=None, silence_level=0, *args, **kwds)

Return a Network object stored in a file.

Unified reading function for graphs. Relies on and partially extends the corresponding igraph function. Refer to igraph documentation for further details on the various reader methods for different formats.

This method tries to identify the format of the graph given in the first parameter and calls the corresponding reader method.

Existing node and link attributes/weights are also restored depending on the chosen file format. E.g., the formats GraphML and gzipped GraphML are able to store both node and link weights.

The remaining arguments are passed to the reader method without any changes.

Parameters:

• filename (str) – The name of the file containing the Network object.

• fileformat (str) – the format of the file (if known in advance). None means auto-detection. Possible values are: "ncol" (NCOL format), "lgl" (LGL format), "graphml", "graphmlz" (GraphML and gzipped GraphML format), "gml" (GML format), "net", "pajek" (Pajek format), "dimacs" (DIMACS format), "edgelist", "edges" or "edge" (edge list), "adjacency" (adjacency matrix), "pickle" (Python pickled format).

• silence_level (int >= 0) – The higher, the less progress info is output.

Return type:

Network object

Returns:

Network instance.

static Model(network_model, **kwargs)

Return a new model graph generated with the specified network model

Example:

>>> print(Network.Model("ErdosRenyi", n_nodes=10, n_links=18))
Generating Erdos-Renyi random graph with 10 nodes and 18 links...
Network: undirected, 10 nodes, 18 links, link density 0.400.

:type network_model string :arg network_model name of the corresponding network model

Return type:

Network instance

Returns:

Network object.

Possible choices for network_model:

• “ErdosRenyi”

• “BarabasiAlbert”

• “BarabasiAlbert_igraph”

• “Configuration”

N: int

number of nodes

static SmallDirectedTestNetwork()

Return a 6-node directed test network with node and edge weights.

The node weights are [1.5, 1.7, 1.9, 2.1, 2.3, 2.5], a typical node weight for corrected n.s.i. measures would be 2.0.

Return type:

Network instance

Returns:

Network object.

static SmallTestNetwork()

Return a 6-node undirected test network with node weights.

The network looks like this:

    3 - 1
    |   | \
5 - 0 - 4 - 2

The node weights are [1.5, 1.7, 1.9, 2.1, 2.3, 2.5], a typical node weight for corrected n.s.i. measures would be 2.0.

Return type:

Network instance

Returns:

Network object.

static WattsStrogatz(N, k, p)

Return adjacency matrix of a Watt-Strogatz random graph.

Reference: [Watts1998]

Example: Generate a network of 100 nodes with rewiring probability 0.1

>>> A = Network.WattsStrogatz(N=100, k=2, p=0.1)
Generating Watts-Strogatz random graph with 100 nodes and rewiring
probability 0.1

Parameters:

• N (int > 0) – Number of nodes.

• k (int > 0) – Each node is connected to k nearest neighbors in ring topology.

• p (float > 0) – Probability of rewiring each edge.

Return type:

square array-like [node,node]

Returns:

adjacency matrix of generated network

__cache_state__() → Tuple[Hashable, ...]

Hashable tuple of mutable object attributes, which will determine the instance identity for ALL cached method lookups in this class, in addition to the built-in object id(). Returning an empty tuple amounts to declaring the object immutable in general. Mutable dependencies that are specific to a method should instead be declared via @Cached.method(attrs=(…)).

NOTE: A subclass is responsible for the consistency and cost of this state descriptor. For example, hashing a large array attribute may be circumvented by declaring it as a property, with a custom setter method that increments a dedicated mutation counter.

__init__(adjacency=None, n_nodes=None, edge_list=None, directed=False, node_weights=None, silence_level=0)

Return a new directed or undirected Network object with given adjacency matrix and optional node weights.

Parameters:

• adjacency (square array-like [node,node], or pysparse matrix of 0s and 1s) – Adjacency matrix of the new network. Entry [i,j] indicates whether node i links to node j. Its diagonal must be zero. Must be symmetric if directed=False.

• n_nodes (int) – Number of nodes, optional argument when using edge_list

• edge_list (array-like list of lists) – Edge list of the new network. Entries [i,0], [i,1] contain the end-nodes of an edge.

• directed (bool) – Indicates whether the network shall be considered as directed. If False, adjacency must be symmetric.

• node_weights (1d numpy array or list [node] of floats >= 0) – Optional array or list of node weights to be used for node splitting invariant network measures. Entry [i] is the weight of node i. (Default: list of ones)

• silence_level (int >= 0) – The higher, the less progress info is output.

Return type:

Network instance

Returns:

The new network.

__len__()

Return the number of nodes as the ‘length’.

Example:

>>> len(Network.SmallTestNetwork())
6

Return type:

int > 0

__str__()

Return a short summary of the network.

Example:

>>> print(Network.SmallTestNetwork())
Network: undirected, 6 nodes, 7 links, link density 0.467.

Return type:

string

static _cum_histogram(values, n_bins, interval=None)

Return a normalized cumulative histogram of a list of values, and the lower bin boundaries.

Example: Get the relative frequencies only:

>>> r(Network._cum_histogram(
...     values=[1,2,13], n_bins=3, interval=(0,30))[0])
array([ 1. ,  0.3333,  0. ])

Parameters:

• values (1d array or list of floats) – The values whose distribution is wanted.

• n_bins (int > 0) – Number of bins to be used for the histogram.

• interval (tuple (float,float), or None) – Optional range to use. If None, the minimum and maximum values are used. (Default: None)

Return type:

tuple (list,list)

Returns:

A list of cumulative relative bin frequencies (entry [i] is the sum of the frequencies of all bins j >= i), and a list of lower bin boundaries.

static _histogram(values, n_bins, interval=None)

Return a normalized histogram of a list of values, its statistical error, and the lower bin boundaries.

Example: Get the relative frequencies only:

>>> r(Network._histogram(
...     values=[1,2,13], n_bins=3, interval=(0,30))[0])
array([ 0.6667,  0.3333,  0. ])

Parameters:

• values (1d array or list of floats) – The values whose distribution is wanted.

• n_bins (int > 0) – Number of bins to be used for the histogram.

• interval (tuple (float,float), or None) – Optional interval to use. If None, the minimum and maximum values are used. (Default: None)

Return type:

tuple (list,list,list)

Returns:

A list of relative bin frequencies, a list of estimated statistical errors, and a list of lower bin boundaries.

_motif_clustering_helper(t_func, T, key=None, nsi=False, typical_weight=None, ksum=None)

Helper function to compute the local motif clustering coefficients. For each node, returns a specific clustering coefficient, depending on the input arguments.

Parameters:

• t_func (function) – multiplication of adjacency-type matrices

• [node] (1d numpy array) – denominator made out of (in/out/bil)degrees

• key (str) – link attribute key (optional)

• nsi (bool) – flag for nsi calculation (default: False)

• typical_weight (float) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

1d numpy array [node] of floats between 0 and 1

_mut_A: int

mutation count tracking self.adjcency

_mut_la: int

mutation count tracking self.graph.es

_mut_nw: int

mutation count tracking self.node_weights

property adjacency

Return the (possibly non-symmetric) adjacency matrix as a dense matrix.

Example:

>>> r(Network.SmallTestNetwork().adjacency)
array([[0, 0, 0, 1, 1, 1], [0, 0, 1, 1, 1, 0], [0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0], [1, 1, 1, 0, 0, 0], [1, 0, 0, 0, 0, 0]])

Return type:

square numpy array [node,node] of 0s and 1s

arenas_betweenness()

For each node, return its Arenas-type random walk betweenness.

This measures how often a random walk search for a random target node from a random source node is expected to pass this node. (see [Arenas2003])

Example:

>>> r(Network.SmallTestNetwork().arenas_betweenness())
Calculating Arenas-type random walk betweenness...
   (giant component size: 6 (1.0))
array([ 50.1818, 50.1818, 33.4545, 33.4545, 50.1818, 16.7273])

Return type:

1d numpy array [node] of floats >= 0

assortativity()

Return the assortativity coefficient.

This follows [Newman2002].

Example:

>>> r(Network.SmallTestNetwork().assortativity())
-0.4737

Return type:

float

average_link_attribute(attribute_name: str)

For each node, return the average of a link attribute over all links of that node.

Parameters:

attribute_name (str) – Name of link attribute to be used.

Return type:

1d numpy array [node] of floats

average_neighbors_degree()

For each node, return the average degree of its neighbors.

(Does not use directionality information.)

Example:

>>> r(Network.SmallTestNetwork().average_neighbors_degree())
Calculating average neighbours' degrees...
array([ 2. ,  2.3333,  3. , 3. ,  2.6667,  3. ])

Return type:

1d numpy array [node] of floats >= 0

average_path_length(link_attribute=None)

Return the average (weighted) shortest path length between all pairs of nodes for which a path exists.

Example:

>>> print(r(Network.SmallTestNetwork().average_path_length()))
Calculating average (weighted) shortest path length...
1.6667

Parameters:

link_attribute (str) – Optional name of the link attribute to be used as the links’ length. If None, links have length 1. (Default: None)

Return type:

float

betweenness()

For each node, return its betweenness.

This measures roughly how many shortest paths pass through the node.

Example:

>>> Network.SmallTestNetwork().betweenness()
Calculating node betweenness...
array([ 4.5,  1.5,  0. ,  1. ,  3. ,  0. ])

Return type:

1d numpy array [node] of floats >= 0

bildegree(key=None)

Return list of bilateral degrees, i.e. the number of simultaneously in- and out-going edges.

If a link attribute key is specified, return the associated bilateral strength.

Exmaple:

>>> Network.SmallDirectedTestNetwork().bildegree()
array([0, 0, 0, 0, 0, 0], dtype=int16)
>>> net = Network.SmallTestNetwork()
>>> (net.bildegree() == net.degree()).all()
True

closeness(link_attribute=None)

For each node, return its (weighted) closeness.

This is the inverse of the mean shortest path length from the node to all other nodes.

Example:

>>> r(Network.SmallTestNetwork().closeness())
Calculating closeness...
array([ 0.7143, 0.625 , 0.5556, 0.625 , 0.7143, 0.4545])

Parameters:

link_attribute (str) – Optional name of the link attribute to be used as the links’ length. If None, links have length 1. (Default: None)

Return type:

1d numpy array [node] of floats between 0 and 1

copy()

Return a copy of the network.

coreness()

For each node, return its coreness.

The k-core of a network is a maximal subnetwork in which each node has at least degree k. (Degree here means the degree in the subnetwork of course). The coreness of a node is k if it is a member of the k-core but not a member of the (k+1)-core.

Example:

>>> Network.SmallTestNetwork().coreness()
Calculating coreness...
array([2, 2, 2, 2, 2, 1])

Return type:

1d numpy array [node] of floats

degree(key=None)

Return list of degrees.

If a link attribute key is specified, return the associated strength.

Example:

>>> Network.SmallTestNetwork().degree()
array([3, 3, 2, 2, 3, 1])

Parameters:

key (str) – link attribute key [optional]

Return type:

array([int>=0])

degree_cdf()

Return the cumulative degree frequency distribution.

Example:

>>> r(Network.SmallTestNetwork().degree_cdf())
Calculating the cumulative degree distribution...
array([ 1. , 0.8333,  0.5 ])

Return type:

1d numpy array [k] of ints >= 0

Returns:

Entry [k] is the number of nodes having degree k or more.

degree_distribution()

Return the degree frequency distribution.

Example:

>>> r(Network.SmallTestNetwork().degree_distribution())
Calculating the degree frequency distribution...
array([ 0.1667, 0.3333, 0.5 ])

Return type:

1d numpy array [k] of ints >= 0

Returns:

Entry [k] is the number of nodes having degree k.

del_link_attribute(attribute_name: str)

Delete a link attribute.

Parameters:

attribute_name (str) – name of link attribute to be deleted

del_node_attribute(attribute_name: str)

Delete a node attribute.

Parameters:

attribute_name (str) – Name of node attribute to be deleted.

diameter(directed=True, only_connected=True)

Return the diameter (largest shortest path length between any nodes).

Example:

>>> print(Network.SmallTestNetwork().diameter())
3

Parameters:

• directed (bool) – Indicates whether to respect link directions if the network is directed. (Default: True)

• only_connected (bool) – Indicates whether to use only pairs of nodes with a connecting path. If False and the network is unconnected, the number of all nodes is returned. (Default: True)

Return type:

int >= 0

directed: bool

indicates whether the network is directed

distance_based_measures(replace_inf_by=None)

Return a dictionary of local and global measures that are based on shortest path lengths.

This is useful for large graphs for which the matrix of all shortest path lengths cannot be stored.

EXPERIMENTAL!

Parameters:

replace_inf_by (float/inf/None) – If None, the number of nodes is used. (Default: None)

Return type:

dictionary with keys “closeness”, “harmonic_closeness”, “exponential_closeness”, “average_path_length”, “global_efficiency”, “nsi_closeness”, “nsi_harmonic_closeness”, “nsi_exponential_closeness”, “nsi_average_path_length”, “nsi_global_efficiency”

edge_betweenness()

For each link, return its betweenness.

Alias to link_betweenness(). This measures on how likely the link is on a randomly chosen shortest path in the network.

(Does not respect directionality of links.)

Example:

>>> print(Network.SmallTestNetwork().edge_betweenness())
Calculating link betweenness...
[[ 0.   0.   0.   3.5  5.5  5. ] [ 0.   0.   2.   3.5  2.5  0. ]
 [ 0.   2.   0.   0.   3.   0. ] [ 3.5  3.5  0.   0.   0.   0. ]
 [ 5.5  2.5  3.   0.   0.   0. ] [ 5.   0.   0.   0.   0.   0. ]]

Return type:

square numpy array [node,node] of floats

Returns:

Entry [i,j] is the betweenness of the link between i and j, or 0 if i is not linked to j.

edge_list()

Return the network’s edge list.

Example:

>>> print(Network.SmallTestNetwork().edge_list()[:8])
[[0 3] [0 4] [0 5] [1 2] [1 3] [1 4] [2 1] [2 4]]

Return type:

array-like (numpy matrix or list of lists/tuples)

eigenvector_centrality()

For each node, return its eigenvector centrality.

This is the load on this node from the eigenvector corresponding to the largest eigenvalue of the adjacency matrix, normalized to a maximum of 1.

Example:

>>> r(Network.SmallTestNetwork().eigenvector_centrality())
Calculating eigenvector centrality...
array([ 0.7895, 0.973 , 0.7769, 0.6941, 1. , 0.3109])

Return type:

1d numpy array [node] of floats

global_clustering()

Return the global (Watts-Strogatz) clustering coefficient.

This is the mean of the local clustering coefficients. [Newman2003] refers to this measure as C_2.

Example:

>>> r(Network.SmallTestNetwork().global_clustering())
Calculating global clustering coefficient (C_2)...
Calculating local clustering coefficients...
0.2778

Return type:

float between 0 and 1

global_efficiency(link_attribute=None)

Return the global (weighted) efficiency. (see [Costa2007])

Example:

>>> r(Network.SmallTestNetwork().global_efficiency())
Calculating all shortest path lengths...
Calculating global (weighted) efficiency...
0.7111

Parameters:

link_attribute (str) – Optional name of the link attribute to be used as the links’ length. If None, links have length 1. (Default: None)

Return type:

float

graph: Graph

embedded graph object providing some standard network measures

hamming_distance_from(other_network)

Return the normalized hamming distance between this and another network.

This is the percentage of links that have to be changed to transform this network into the other. Hamming distance is only defined for networks with an equal number of nodes.

Return type:

float between 0 and 1

higher_order_transitivity(order, estimate=False)

Return transitivity of a certain order.

The transitivity of order n is defined as:

• (n x Number of cliques of n nodes) / (Number of stars of n nodes)

It is a generalization of the standard network transitivity, which is included as a special case for n = 3.

Parameters:

• order (int) – The order (number of nodes) of cliques to be considered.

• estimate (bool) – Toggles random sampling for estimating higher order transitivity (much faster than exact calculation).

Return type:

number (float) between 0 and 1

indegree(key=None)

Return list of in-degrees.

If a link attribute key is specified, return the associated in-strength.

Example:

>>> Network.SmallDirectedTestNetwork().indegree()
array([2, 2, 2, 1, 1, 0])

Parameters:

key (str) – link attribute key [optional]

Return type:

array([int>=0])

indegree_cdf()

Return the cumulative in-degree frequency distribution.

Example:

>>> r(Network.SmallTestNetwork().indegree_cdf())
Calculating the cumulative in-degree distribution...
array([ 1. , 0.8333, 0.8333, 0.5 ])

Return type:

1d numpy array [k] of ints >= 0

Returns:

Entry [k] is the number of nodes having in-degree k or more.

indegree_distribution()

Return the in-degree frequency distribution.

Example:

>>> r(Network.SmallTestNetwork().indegree_distribution())
Calculating in-degree frequency distribution...
array([ 0.1667, 0.3333, 0.5 ])

Return type:

1d numpy array [k] of ints >= 0

Returns:

Entry [k] is the number of nodes having in-degree k.

interregional_betweenness(sources=None, targets=None)

For each node, return its interregional betweenness for given sets of source and target nodes.

This measures roughly how many shortest paths from one of the sources to one of the targets pass through the node.

Examples:

>>> Network.SmallTestNetwork().interregional_betweenness(
...     sources=[2], targets=[3,5])
Calculating interregional betweenness...
array([ 1.,  1.,  0.,  0.,  1.,  0.])
>>> Network.SmallTestNetwork().interregional_betweenness(
...     sources=range(0,6), targets=range(0,6))
Calculating interregional betweenness...
array([ 9.,  3.,  0.,  2.,  6.,  0.])

as compared to

>>> Network.SmallTestNetwork().betweenness()
Calculating node betweenness...
array([ 4.5,  1.5,  0. ,  1. ,  3. ,  0. ])

Parameters:

• sources (1d numpy array or list of ints from 0 to n_nodes-1) – Set of source node indices.

• targets (1d numpy array or list of ints from 0 to n_nodes-1) – Set of target node indices.

Return type:

1d numpy array [node] of floats

laplacian(direction='out', link_attribute=None)

Return the (possibly non-symmetric) dense Laplacian matrix.

Example:

>>> r(Network.SmallTestNetwork().laplacian())
array([[ 3,  0,  0, -1, -1, -1], [ 0,  3, -1, -1, -1,  0],
       [ 0, -1,  2,  0, -1,  0], [-1, -1,  0,  2,  0,  0],
       [-1, -1, -1,  0,  3,  0], [-1,  0,  0,  0,  0,  1]])

Parameters:

• direction (str) – This argument is ignored for undirected graphs. “out” - out-degree on diagonal of laplacian “in” - in-degree on diagonal of laplacian

• link_attribute (str) – name of link attribute to be used

Return type:

square array [node,node] of ints

link_attribute(attribute_name: str)

Return the values of a link attribute.

Parameters:

attribute_name (str) – Name of link attribute to be used.

Return type:

square numpy array [node,node]

Returns:

Entry [i,j] is the attribute of the link from i to j.

link_betweenness()

For each link, return its betweenness.

This measures on how likely the link is on a randomly chosen shortest path in the network.

(Does not respect directionality of links.)

Example:

>>> print(Network.SmallTestNetwork().link_betweenness())
Calculating link betweenness...
[[ 0.   0.   0.   3.5  5.5  5. ] [ 0.   0.   2.   3.5  2.5  0. ]
 [ 0.   2.   0.   0.   3.   0. ] [ 3.5  3.5  0.   0.   0.   0. ]
 [ 5.5  2.5  3.   0.   0.   0. ] [ 5.   0.   0.   0.   0.   0. ]]

Return type:

square numpy array [node,node] of floats

Returns:

Entry [i,j] is the betweenness of the link between i and j, or 0 if i is not linked to j.

link_density: float

proportion of linked node pairs

local_cliquishness(order)

Return local cliquishness of a certain order.

The local cliquishness measures the relative number of cliques (fully connected subgraphs) of a certain order that a node participates in.

Local cliquishness is not defined for orders 1 and 2. For order 3, it is equivalent to the local clustering coefficient local_clustering(), since cliques of order 3 are triangles.

Local cliquishness is always bounded by 0 and 1 and set to zero for nodes with degree smaller than order - 1.

Parameters:

order (number (int)) – The order (number of nodes) of cliques to be considered.

Return type:

1d numpy array [node] of floats between 0 and 1

local_clustering()

For each node, return its (Watts-Strogatz) clustering coefficient.

This is the proportion of all pairs of its neighbors which are themselves interlinked.

(Uses directionality information, if available)

Example:

>>> r(Network.SmallTestNetwork().local_clustering())
Calculating local clustering coefficients...
array([ 0. , 0.3333, 1. , 0. , 0.3333, 0. ])

Return type:

1d numpy array [node] of floats between 0 and 1

local_cyclemotif_clustering(key=None)

For each node, return the clustering coefficient with respect to the cycle motif.

If a link attribute key is specified, return the associated link weighted version.

Example:

>>> r(Network.SmallDirectedTestNetwork().local_cyclemotif_clustering())
Calculating local cycle motif clustering coefficient...
array([ 0.25,  0.25,  0.  ,  0.  ,  0.5 ,  0.  ])

Parameters:

key (str) – link attribute key (optional)

Return type:

1d numpy array [node] of floats between 0 and 1

local_inmotif_clustering(key=None)

For each node, return the clustering coefficient with respect to the in motif.

If a link attribute key is specified, return the associated link weighted version.

Example:

>>> r(Network.SmallDirectedTestNetwork().local_inmotif_clustering())
Calculating local in motif clustering coefficient...
array([ 0. ,  0.5,  0.5,  0. ,  0. ,  0. ])

Parameters:

key (str) – link attribute key (optional)

Return type:

1d numpy array [node] of floats between 0 and 1

local_midmotif_clustering(key=None)

For each node, return the clustering coefficient with respect to the mid. motif.

If a link attribute key is specified, return the associated link weighted version.

Example:

>>> r(Network.SmallDirectedTestNetwork().local_midmotif_clustering())
Calculating local mid. motif clustering coefficient...
array([ 0. ,  0. ,  0. ,  1. ,  0.5,  0. ])

Parameters:

key (str) – link attribute key (optional)

Return type:

1d numpy array [node] of floats between 0 and 1

local_outmotif_clustering(key=None)

For each node, return the clustering coefficient with respect to the out motif.

If a link attribute key is specified, return the associated link weighted version.

Example:

>>> r(Network.SmallDirectedTestNetwork().local_outmotif_clustering())
Calculating local out motif clustering coefficient...
array([ 0.5,  0.5,  0. ,  0. ,  0. ,  0. ])

Parameters:

key (str) – link attribute key (optional)

Return type:

1d numpy array [node] of floats between 0 and 1

local_vulnerability(link_attribute=None)

For each node, return its vulnerability. (see [Costa2007])

Example:

>>> r(Network.SmallTestNetwork().local_vulnerability())
Calculating all shortest path lengths...
Calculating global (weighted) efficiency...
Calculating (weighted) node vulnerabilities...
array([ 0.2969, 0.0625, -0.0313, -0.0078, 0.0977, -0.125 ])

Parameters:

link_attribute (str) – Optional name of the link attribute to be used as the links’ length. If None, links have length 1. (Default: None)

Return type:

1d numpy array [node] of floats

matching_index()

For each pair of nodes, return their matching index.

This is the ratio of the number of common neighbors and the number of nodes linked to at least one of the two nodes.

Example:

>>> print(r(Network.SmallTestNetwork().matching_index()))
Calculating matching index matrix...
[[ 1.    0.5   0.25    0.      0.      0.    ]
 [ 0.5   1.    0.25    0.      0.2     0.    ]
 [ 0.25  0.25  1.      0.3333  0.25    0.    ]
 [ 0.    0.    0.3333  1.      0.6667  0.5   ]
 [ 0.    0.2   0.25    0.6667  1.      0.3333]
 [ 0.    0.    0.      0.5     0.3333  1.    ]]

Return type:

array([[0<=float<=1,0<=float<=1]])

max_neighbors_degree()

For each node, return the maximal degree of its neighbors.

(Does not use directionality information.)

Example:

>>> Network.SmallTestNetwork().max_neighbors_degree()
Calculating maximum neighbours' degree...
array([3, 3, 3, 3, 3, 3])

Return type:

1d numpy array [node] of ints >= 0

mean_node_weight: float

mean node weight

msf_synchronizability()

Return the synchronizability in the master stability function framework.

This is equal to the largest eigenvalue of the graph Laplacian divided by the smallest non-zero eigenvalue. A smaller value indicates higher synchronizability and vice versa. This function makes sense for undirected climate networks (with symmetric Laplacian matrix). For directed networks, the undirected Laplacian matrix is used.

(see [Pecora1998])

Note

Only defined for undirected networks.

Example:

>>> r(Network.SmallTestNetwork().msf_synchronizability())
Calculating master stability function synchronizability...
6.7784

Return type:

float

n_links: int

number of links

newman_betweenness()

For each node, return Newman’s random walk betweenness.

This measures how often a random walk search for a random target node from a random source node is expected to pass this node, not counting when the walk returns along a link it took before to leave the node. (see [Newman2005])

Example:

>>> r(Network.SmallTestNetwork().newman_betweenness())
Calculating Newman's random walk betweenness...
   (giant component size: 6 (1.0))
array([ 4.1818, 3.4182, 2.5091, 3.0182, 3.6 , 2. ])

Return type:

1d numpy array [node] of floats >= 0

node_attribute(attribute_name: str)

Return a node attribute.

Examples for node attributes/weights are degree or betweenness.

Parameters:

attribute_name (str) – The name of the node attribute.

Return type:

1D Numpy array [node]

Returns:

The node attribute sequence.

property node_weights

array of node weights

nsi_arenas_betweenness(exclude_neighbors=True, stopping_mode='neighbors')

For each node, return its n.s.i. Arenas-type random walk betweenness.

This measures how often a random walk search for a random target node from a random source node is expected to pass this node. (see [Arenas2003])

Examples:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_arenas_betweenness())
Calculating n.s.i. Arenas-type random walk betweenness...
   (giant component size: 6 (1.0))
Calculating n.s.i. degree...
array([ 20.5814, 29.2103, 27.0075, 19.5434, 25.2849, 24.8483])
>>> r(net.splitted_copy().nsi_arenas_betweenness())
Calculating n.s.i. Arenas-type random walk betweenness...
   (giant component size: 7 (1.0))
Calculating n.s.i. degree...
array([ 20.5814, 29.2103, 27.0075, 19.5434, 25.2849, 24.8483, 24.8483])
>>> r(net.nsi_arenas_betweenness(exclude_neighbors=False))
Calculating n.s.i. Arenas-type random walk betweenness...
   (giant component size: 6 (1.0))
Calculating n.s.i. degree...
array([ 44.5351, 37.4058, 27.0075, 21.7736, 31.3256, 24.8483])
>>> r(net.nsi_arenas_betweenness(stopping_mode="twinness"))
Calculating n.s.i. Arenas-type random walk betweenness...
   (giant component size: 6 (1.0))
Calculating n.s.i. degree...
Calculating n.s.i. degree...
array([ 22.6153, 41.2314, 38.6411, 28.6195, 38.5824, 30.2994])

as compared to its unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.arenas_betweenness())
Calculating Arenas-type random walk betweenness...
   (giant component size: 6 (1.0))
array([ 50.1818, 50.1818, 33.4545, 33.4545, 50.1818, 16.7273])
>>> r(net.splitted_copy().arenas_betweenness())
Calculating Arenas-type random walk betweenness...
   (giant component size: 7 (1.0))
array([ 90.4242, 67.8182, 45.2121, 45.2121, 67.8182, 45.2121, 45.2121])

Parameters:

• exclude_neighbors (bool) – Indicates whether to use only source and target nodes that are not linked to the node of interest. (Default: True)

• stopping_mode (str) – Specifies when the random walk is stopped. If “neighbors”, the walk stops as soon as it reaches a neighbor of the target node. If “twinnness”, the stopping probability at each step is the twinnness of the current and target nodes as given by nsi_twinness(). (Default: “neighbors”)

Return type:

1d numpy array [node] of floats >= 0

nsi_average_neighbors_degree()

For each node, return the average n.s.i. degree of its neighbors.

(not yet implemented for directed networks.)

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_average_neighbors_degree())
Calculating n.s.i. average neighbours' degree...
Calculating n.s.i. degree...
array([ 6.0417, 6.62 , 7.0898, 7.0434, 7.3554, 5.65 ])
>>> r(net.splitted_copy().nsi_average_neighbors_degree())
Calculating n.s.i. average neighbours' degree...
Calculating n.s.i. degree...
array([ 6.0417, 6.62 , 7.0898, 7.0434, 7.3554, 5.65 , 5.65 ])

as compared to the unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.average_neighbors_degree())
Calculating average neighbours' degrees...
array([ 2. , 2.3333, 3. , 3. , 2.6667, 3. ])
>>> r(net.splitted_copy().average_neighbors_degree())
Calculating average neighbours' degrees...
array([ 2.25 , 2.3333, 3. , 3.5 , 3. , 3. , 3. ])

Return type:

1d numpy array [node] of floats >= 0

nsi_average_path_length()

Return the n.s.i. average shortest path length between all pairs of nodes for which a path exists.

The path length from a node to itself is considered to be 1 to achieve node splitting invariance.

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_average_path_length())
Calculating n.s.i. average shortest path length...
Calculating all shortest path lengths...
1.6003
>>> r(net.splitted_copy().nsi_average_path_length())
Calculating n.s.i. average shortest path length...
Calculating all shortest path lengths...
1.6003

as compared to the unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.average_path_length())
Calculating average (weighted) shortest path length...
1.6667
>>> r(net.splitted_copy().average_path_length())
Calculating average (weighted) shortest path length...
1.7619

Return type:

float

nsi_betweenness(sources=None, targets=None, nsi: bool = True, parallelize: bool = False)

For each node, return its n.s.i. betweenness. [Newman2001]

This measures roughly how many shortest paths pass through the node, taking node weights into account.

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_betweenness())
Calculating n.s.i. betweenness...
array([ 29.6854, 7.7129, 0. , 3.0909, 9.6996, 0. ])
>>> r(net.splitted_copy().nsi_betweenness())
Calculating n.s.i. betweenness...
array([ 29.6854, 7.7129, 0. , 3.0909, 9.6996, 0. , 0. ])

as compared to the unweighted version:

>>> net = Network.SmallTestNetwork()
>>> net.betweenness()
Calculating node betweenness...
array([ 4.5,  1.5,  0. ,  1. ,  3. ,  0. ])
>>> net.splitted_copy().betweenness()
Calculating node betweenness...
array([ 8.5,  1.5,  0. ,  1.5,  4.5,  0. ,  0. ])

Parameters:

parallelize (bool) – Toggle multiprocessing

Return type:

1d numpy array [node] of floats

nsi_bildegree(key=None, typical_weight=None)

For each node, return its n.s.i. bilateral degree.

If a link attribute key is specified, return the associated n.s.i. bilateral strength.

Parameters:

• key (str) – link attribute key [optional]

• typical_weight (float > 0) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

array([float])

nsi_closeness()

For each node, return its n.s.i. closeness.

This is the inverse of the mean shortest path length from the node to all other nodes. If the network is not connected, the result is 0.

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_closeness())
Calculating n.s.i. closeness...
Calculating all shortest path lengths...
array([ 0.7692, 0.6486, 0.5825, 0.6417, 0.7229, 0.5085])
>>> r(net.splitted_copy().nsi_closeness())
Calculating n.s.i. closeness...
Calculating all shortest path lengths...
array([ 0.7692, 0.6486, 0.5825, 0.6417, 0.7229, 0.5085, 0.5085])

as compared to the unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.closeness())
Calculating closeness...
array([ 0.7143, 0.625 , 0.5556, 0.625 , 0.7143, 0.4545])
>>> r(net.splitted_copy().closeness())
Calculating closeness...
array([ 0.75 , 0.5455, 0.5 , 0.6 , 0.6667, 0.5 , 0.5 ])

Return type:

1d numpy array [node] of floats between 0 and 1

nsi_degree(key=None, typical_weight=None)

For each node, return its uncorrected or corrected n.s.i. degree.

If a link attribute key is specified, return the associated n.s.i. strength.

Examples:

>>> net = Network.SmallTestNetwork()
>>> net.nsi_degree()
Calculating n.s.i. degree...
array([ 8.4,  8. ,  5.9,  5.3,  7.4,  4. ])
>>> net.splitted_copy().nsi_degree()
Calculating n.s.i. degree...
array([ 8.4,  8. ,  5.9,  5.3,  7.4,  4. ,  4. ])
>>> net.nsi_degree(typical_weight=2.0)
array([ 3.2 ,  3.  ,  1.95,  1.65,  2.7 ,  1.  ])
>>> net.splitted_copy().nsi_degree(typical_weight=2.0)
Calculating n.s.i. degree...
array([ 3.2 ,  3.  ,  1.95,  1.65,  2.7 ,  1.  ,  1.  ])

as compared to the unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.degree())
array([3, 3, 2, 2, 3, 1])
>>> r(net.splitted_copy().degree())
array([4, 3, 2, 2, 3, 2, 2])

Parameters:

• key (str) – link attribute key (optional)

• typical_weight (float) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

array([float])

nsi_degree_cumulative_histogram(typical_weight=None)

Return a cumulative frequency (!) histogram of n.s.i. degree.

Example:

>>> r(Network.SmallTestNetwork().nsi_degree_cumulative_histogram())
Calculating a cumulative n.s.i. degree frequency histogram...
Calculating n.s.i. degree...
(array([ 1. , 0.6667, 0.5 ]), array([ 4. , 5.4667, 6.9333]))

Parameters:

typical_weight (float > 0) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

tuple (list,list)

Returns:

List of cumulative frequencies and list of lower bin bounds.

nsi_degree_histogram(typical_weight=None)

Return a frequency (!) histogram of n.s.i. degree.

Example:

>>> r(Network.SmallTestNetwork().nsi_degree_histogram())
Calculating a n.s.i. degree frequency histogram...
Calculating n.s.i. degree...
(array([ 0.3333, 0.1667, 0.5 ]), array([ 0.1179, 0.1667, 0.0962]),
 array([ 4. , 5.4667, 6.9333]))

Parameters:

typical_weight (float > 0) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

tuple (list,list)

Returns:

List of frequencies and list of lower bin bounds.

nsi_eigenvector_centrality()

For each node, return its n.s.i. eigenvector centrality.

This is the load on this node from the eigenvector corresponding to the largest eigenvalue of the n.s.i. adjacency matrix, divided by sqrt(node weight) and normalized to a maximum of 1.

For a directed network, this uses the right eigenvectors. To get the values for the left eigenvectors, apply this to the inverse network!

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_eigenvector_centrality())
Calculating n.s.i. eigenvector centrality...
array([ 0.8045, 1. , 0.8093, 0.6179, 0.9867, 0.2804])
>>> r(net.splitted_copy().nsi_eigenvector_centrality())
Calculating n.s.i. eigenvector centrality...
array([ 0.8045, 1. , 0.8093, 0.6179, 0.9867, 0.2804, 0.2804])

as compared to the unweighted version:

>>> r(net.eigenvector_centrality())
Calculating eigenvector centrality...
array([ 0.7895, 0.973 , 0.7769, 0.6941, 1. , 0.3109])
>>> r(net.splitted_copy().eigenvector_centrality())
Calculating eigenvector centrality...
array([ 1. , 0.8008, 0.6226, 0.6625, 0.8916, 0.582 , 0.582 ])

Return type:

1d numpy array [node] of floats

nsi_exponential_closeness()

For each node, return its n.s.i. exponential harmonic closeness.

This is the mean of 2**(- shortest path length) from the node to all other nodes. If the network is not connected, the result is not necessarily 0.

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_exponential_closeness())
Calculating n.s.i. exponential closeness centrality...
Calculating all shortest path lengths...
array([ 0.425 , 0.3906, 0.3469, 0.3604, 0.4042, 0.2958])
>>> r(net.splitted_copy().nsi_exponential_closeness())
Calculating n.s.i. exponential closeness centrality...
Calculating all shortest path lengths...
array([ 0.425 , 0.3906, 0.3469, 0.3604, 0.4042, 0.2958, 0.2958])

Return type:

1d numpy array [node] of floats between 0 and 1

nsi_global_clustering()

Return the n.s.i. global clustering coefficient.

(not yet implemented for directed networks.)

Example:

>>> r(Network.SmallTestNetwork().nsi_global_clustering())
Calculating n.s.i. global topological clustering coefficient...
Calculating n.s.i. degree...
0.8353

as compared to the unweighted version:

>>> r(Network.SmallTestNetwork().global_clustering())
Calculating global clustering coefficient (C_2)...
Calculating local clustering coefficients...
0.2778

Return type:

float between 0 and 1

nsi_global_efficiency()

Return the n.s.i. global efficiency.

Example:

>>> r(Network.SmallTestNetwork().nsi_global_efficiency())
Calculating n.s.i. global efficiency...
Calculating all shortest path lengths...
0.7415

Return type:

float

nsi_harmonic_closeness()

For each node, return its n.s.i. harmonic closeness.

This is the inverse of the harmonic mean shortest path length from the node to all other nodes. If the network is not connected, the result is not necessarily 0.

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_harmonic_closeness())
Calculating n.s.i. harmonic closeness...
Calculating all shortest path lengths...
array([ 0.85 , 0.7986, 0.7111, 0.7208, 0.8083, 0.6167])
>>> r(net.splitted_copy().nsi_harmonic_closeness())
Calculating n.s.i. harmonic closeness...
Calculating all shortest path lengths...
array([ 0.85 , 0.7986, 0.7111, 0.7208, 0.8083, 0.6167, 0.6167])

Return type:

1d numpy array [node] of floats between 0 and 1

nsi_indegree(key=None, typical_weight=None)

For each node, return its n.s.i. indegree.

If a link attribute key is specified, return the associated n.s.i. in-strength.

Examples:

>>> net = Network.SmallDirectedTestNetwork()
>>> net.nsi_indegree()
array([ 6.3,  5.3,  5.9,  3.6,  4. ,  2.5])
>>> net.splitted_copy().nsi_indegree()
array([ 6.3,  5.3,  5.9,  3.6,  4. ,  2.5,  2.5])

as compared to the unweighted version:

>>> net = Network.SmallDirectedTestNetwork()
>>> net.indegree()
array([2, 2, 2, 1, 1, 0])
>>> net.splitted_copy().indegree()
array([3, 2, 2, 1, 1, 1, 1])

Parameters:

• key (str) – link attribute key [optional]

• typical_weight (float > 0) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

array([float])

nsi_interregional_betweenness(sources, targets)

For each node, return its n.s.i. interregional betweenness for given sets of source and target nodes.

This measures roughly how many shortest paths from one of the sources to one of the targets pass through the node, taking node weights into account.

Example:

>>> r(Network.SmallTestNetwork().nsi_interregional_betweenness(
...     sources=[2], targets=[3,5]))
Calculating n.s.i. interregional betweenness...
array([ 3.1667, 2.3471, 0. , 0. , 2.0652, 0. ])

as compared to the unweighted version:

>>> Network.SmallTestNetwork().interregional_betweenness(
...     sources=[2], targets=[3,5])
Calculating interregional betweenness...
array([ 1.,  1.,  0.,  0.,  1.,  0.])

Return type:

1d numpy array [node] of floats

nsi_laplacian()

Return the n.s.i. Laplacian matrix (undirected networks only!).

Example:

>>> Network.SmallTestNetwork().nsi_laplacian()
Calculating n.s.i. degree...
array([[ 6.9,  0. ,  0. , -2.1, -2.3, -2.5],
       [ 0. ,  6.3, -1.9, -2.1, -2.3,  0. ],
       [ 0. , -1.7,  4. ,  0. , -2.3,  0. ],
       [-1.5, -1.7,  0. ,  3.2,  0. ,  0. ],
       [-1.5, -1.7, -1.9,  0. ,  5.1,  0. ],
       [-1.5,  0. ,  0. ,  0. ,  0. ,  1.5]])

Return type:

square array([[float]])

nsi_local_clustering(typical_weight=None)

For each node, return its uncorrected (between 0 and 1) or corrected (at most 1 / negative / NaN) n.s.i. clustering coefficient.

(not yet implemented for directed networks)

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_local_clustering())
Calculating n.s.i. degree...
array([ 0.5513, 0.7244, 1. , 0.8184, 0.8028, 1. ])
>>> r(net.splitted_copy().nsi_local_clustering())
Calculating n.s.i. degree...
array([ 0.5513, 0.7244, 1. , 0.8184, 0.8028, 1. , 1. ])

as compared to the unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.local_clustering())
Calculating local clustering coefficients...
array([ 0. , 0.3333, 1. , 0. , 0.3333, 0. ])
>>> r(net.splitted_copy().local_clustering())
Calculating local clustering coefficients...
array([ 0.1667, 0.3333, 1. ,  0. , 0.3333, 1. , 1. ])

Parameters:

typical_weight (float > 0) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

array([float])

nsi_local_cyclemotif_clustering(key=None, typical_weight=None)

For each node, return the nsi clustering coefficient with respect to the cycle motif.

If a link attribute key is specified, return the associated link weighted version.

Reference: [Zemp2014]

Examples:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.nsi_local_cyclemotif_clustering())
Calculating local nsi cycle motif clustering coefficient...
array([ 0.1845,  0.2028,  0.322 ,  0.3224,  0.3439,  0.625 ])
>>> r(net.splitted_copy(node=1).nsi_local_cyclemotif_clustering())
Calculating local nsi cycle motif clustering coefficient...
array([ 0.1845,  0.2028,  0.322 ,  0.3224,  0.3439,  0.625 ,  0.2028])

as compared to the unweighted version:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.local_cyclemotif_clustering())
Calculating local cycle motif clustering coefficient...
array([ 0.25,  0.25,  0.  ,  0.  ,  0.5 ,  0.  ])
>>> r(net.splitted_copy(node=1).local_cyclemotif_clustering())
Calculating local cycle motif clustering coefficient...
array([ 0.3333,  0.125 ,  0.    ,  0.    ,  0.5   ,  0.    ,  0.125 ])

Parameters:

• key (str) – link attribute key (optional)

• typical_weight (float) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

nsi_local_inmotif_clustering(key=None, typical_weight=None)

For each node, return the nsi clustering coefficient with respect to the in motif.

If a link attribute key is specified, return the associated link weighted version.

Reference: [Zemp2014]

Examples:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.nsi_local_inmotif_clustering())
Calculating local nsi in motif clustering coefficient...
array([ 0.5288,  0.67  ,  0.6693,  0.7569,  0.7556,  1.    ])
>>> r(net.splitted_copy(node=1).nsi_local_inmotif_clustering())
Calculating local nsi in motif clustering coefficient...
array([ 0.5288,  0.67  ,  0.6693,  0.7569,  0.7556,  1.    ,  0.67  ])

as compared to the unweighted version:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.local_inmotif_clustering())
Calculating local in motif clustering coefficient...
array([ 0. ,  0.5,  0.5,  0. ,  0. ,  0. ])
>>> r(net.splitted_copy(node=1).local_inmotif_clustering())
Calculating local in motif clustering coefficient...
array([ 0.    ,  0.5   ,  0.6667,  0.    ,  1.    ,  0.    ,  0.5   ])

Parameters:

• key (str) – link attribute key (optional)

• typical_weight (float) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

nsi_local_midmotif_clustering(key=None, typical_weight=None)

For each node, return the nsi clustering coefficient with respect to the mid motif.

If a link attribute key is specified, return the associated link weighted version.

Reference: [Zemp2014]

Examples:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.nsi_local_midmotif_clustering())
Calculating local nsi mid. motif clustering coefficient...
array([ 0.4537,  0.5165,  1.    ,  1.    ,  0.8882,  1.    ])
>>> r(net.splitted_copy(node=4).nsi_local_midmotif_clustering())
Calculating local nsi mid. motif clustering coefficient...
array([ 0.4537,  0.5165,  1.    ,  1.    ,  0.8882,  1.    ,  0.8882])

as compared to the unweighted version:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.local_midmotif_clustering())
Calculating local mid. motif clustering coefficient...
array([ 0. ,  0. ,  0. ,  1. ,  0.5,  0. ])
>>> r(net.splitted_copy(node=4).local_midmotif_clustering())
Calculating local mid. motif clustering coefficient...
array([ 0. ,  0. ,  0. ,  1. ,  0.8,  0. ,  0.8])

Parameters:

• key (str) – link attribute key (optional)

• typical_weight (float) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

nsi_local_outmotif_clustering(key=None, typical_weight=None)

For each node, return the nsi clustering coefficient with respect to the out motif.

If a link attribute key is specified, return the associated link weighted version.

Reference: [Zemp2014]

Examples:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.nsi_local_outmotif_clustering())
Calculating local nsi out motif clustering coefficient...
array([ 0.67  ,  0.6693,  1.    ,  0.7528,  0.5839,  0.7656])
>>> r(net.splitted_copy(node=0).nsi_local_outmotif_clustering())
Calculating local nsi out motif clustering coefficient...
array([ 0.67  ,  0.6693,  1.    ,  0.7528,  0.5839,  0.7656,  0.67  ])

as compared to the unweighted version:

>>> net = Network.SmallDirectedTestNetwork()
>>> r(net.local_outmotif_clustering())
Calculating local out motif clustering coefficient...
array([ 0.5,  0.5,  0. ,  0. ,  0. ,  0. ])
>>> r(net.splitted_copy(node=0).local_outmotif_clustering())
Calculating local out motif clustering coefficient...
array([ 0.5   ,  0.5   ,  0.    ,  0.    ,  0.3333,  1.    ,  0.5   ])

Parameters:

• key (str) – link attribute key (optional)

• typical_weight (float) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

nsi_local_soffer_clustering()

For each node, return its n.s.i. clustering coefficient with bias-reduction following [Soffer2005].

(not yet implemented for directed networks.)

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_local_soffer_clustering())
Calculating n.s.i. local Soffer clustering coefficients...
Calculating n.s.i. degree...
array([ 0.7665, 0.8754, 1. , 0.8184, 0.8469, 1. ])
>>> r(net.splitted_copy().nsi_local_soffer_clustering())
Calculating n.s.i. local Soffer clustering coefficients...
Calculating n.s.i. degree...
array([ 0.7665, 0.8754, 1. , 0.8184, 0.8469, 1. , 1. ])

as compared to the version without bias-reduction:

>>> r(Network.SmallTestNetwork().nsi_local_clustering())
Calculating n.s.i. degree...
array([ 0.5513, 0.7244, 1. , 0.8184, 0.8028, 1. ])

Return type:

1d numpy array [node] of floats between 0 and 1

nsi_max_neighbors_degree()

For each node, return the maximal n.s.i. degree of its neighbors.

(not yet implemented for directed networks.)

Example:

>>> Network.SmallTestNetwork().nsi_max_neighbors_degree()
Calculating n.s.i. maximum neighbour degree...
Calculating n.s.i. degree...
array([ 8.4,  8. ,  8. ,  8.4,  8.4,  8.4])

as compared to the unweighted version:

>>> print(Network.SmallTestNetwork().max_neighbors_degree())
Calculating maximum neighbours' degree...
[3 3 3 3 3 3]

Return type:

1d numpy array [node] of floats >= 0

nsi_newman_betweenness(add_local_ends=False)

For each node, return its n.s.i. Newman-type random walk betweenness.

This measures how often a random walk search for a random target node from a random source node is expected to pass this node, not counting when the walk returns along a link it took before to leave the node. (see [Newman2005])

In this n.s.i. version, node weights are taken into account, and only random walks are used that do not start or end in neighbors of the node.

Example:

>>> net = Network.SmallTestNetwork()
>>> r(net.nsi_newman_betweenness())
Calculating n.s.i. Newman-type random walk betweenness...
   (giant component size: 6 (1.0))
Calculating n.s.i. degree...
array([ 0.4048, 0. , 0.8521, 3.3357, 1.3662, 0. ])
>>> r(net.splitted_copy().nsi_newman_betweenness())
Calculating n.s.i. Newman-type random walk betweenness...
   (giant component size: 7 (1.0))
Calculating n.s.i. degree...
array([ 0.4048, 0. , 0.8521, 3.3357, 1.3662, 0. , 0. ])
>>> r(net.nsi_newman_betweenness(add_local_ends=True))
Calculating n.s.i. Newman-type random walk betweenness...
   (giant component size: 6 (1.0))
Calculating n.s.i. degree...
array([ 131.4448, 128. , 107.6421, 102.4457, 124.2062, 80. ])
>>> r(net.splitted_copy().nsi_newman_betweenness(
...     add_local_ends=True))
Calculating n.s.i. Newman-type random walk betweenness...
   (giant component size: 7 (1.0))
Calculating n.s.i. degree...
array([ 131.4448, 128. , 107.6421, 102.4457, 124.2062, 80. , 80. ])

as compared to its unweighted version:

>>> net = Network.SmallTestNetwork()
>>> r(net.newman_betweenness())
Calculating Newman's random walk betweenness...
   (giant component size: 6 (1.0))
array([ 4.1818, 3.4182, 2.5091, 3.0182, 3.6 , 2. ])
>>> r(net.splitted_copy().newman_betweenness())
Calculating Newman's random walk betweenness...
   (giant component size: 7 (1.0))
array([ 5.2626, 3.5152, 2.5455, 3.2121, 3.8182, 2.5556, 2.5556])

Parameters:

add_local_ends (bool) – Indicates whether to add a correction for the fact that walks starting or ending in neighbors are not used. (Default: false)

Return type:

array [float>=0]

nsi_outdegree(key=None, typical_weight=None)

For each node, return its n.s.i. outdegree.

If a link attribute key is specified, return the associated n.s.i. out-strength.

Examples:

>>> net = Network.SmallDirectedTestNetwork()
>>> net.nsi_outdegree()
array([ 5.3,  5.9,  1.9,  3.8,  5.7,  4. ])
>>> net.splitted_copy().nsi_outdegree()
array([ 5.3,  5.9,  1.9,  3.8,  5.7,  4. ,  4. ])

as compared to the unweighted version:

>>> net = Network.SmallDirectedTestNetwork()
>>> net.outdegree()
array([2, 2, 0, 1, 2, 1])
>>> net.splitted_copy().outdegree()
array([2, 2, 0, 1, 2, 2, 2])

Parameters:

• key (str) – link attribute key [optional]

• typical_weight (float > 0) – Optional typical node weight to be used for correction. If None, the uncorrected measure is returned. (Default: None)

Return type:

array([float])

nsi_spreading(alpha=None)

For each node, return its n.s.i. “spreading” value.

Note

This is still EXPERIMENTAL!

Return type:

1d numpy array [node] of floats

nsi_transitivity()

Return the n.s.i. transitivity.

Warning

Not yet implemented!

Return type:

float between 0 and 1

nsi_twinness()

For each pair of nodes, return an n.s.i. measure of ‘twinness’.

This varies from 0.0 for unlinked nodes to 1.0 for linked nodes having exactly the same neighbors (called twins).

Example:

>>> net = Network.SmallTestNetwork()
>>> print(r(net.nsi_twinness()))
Calculating n.s.i. degree...
[[ 1.      0.      0.      0.4286  0.4524  0.4762]
 [ 0.      1.      0.7375  0.475   0.7375  0.    ]
 [ 0.      0.7375  1.      0.      0.7973  0.    ]
 [ 0.4286  0.475   0.      1.      0.      0.    ]
 [ 0.4524  0.7375  0.7973  0.      1.      0.    ]
 [ 0.4762  0.      0.      0.      0.      1.    ]]
>>> print(r(net.splitted_copy().nsi_twinness()))
Calculating n.s.i. degree...
[[ 1.      0.      0.      0.4286  0.4524  0.4762  0.4762]
 [ 0.      1.      0.7375  0.475   0.7375  0.      0.    ]
 [ 0.      0.7375  1.      0.      0.7973  0.      0.    ]
 [ 0.4286  0.475   0.      1.      0.      0.      0.    ]
 [ 0.4524  0.7375  0.7973  0.      1.      0.      0.    ]
 [ 0.4762  0.      0.      0.      0.      1.      1.    ]
 [ 0.4762  0.      0.      0.      0.      1.      1.    ]]

Return type:

square array [node,node] of floats between 0 and 1

outdegree(key=None)

Return list of out-degrees.

If a link attribute key is specified, return the associated out-strength.

Example:

>>> Network.SmallDirectedTestNetwork().outdegree()
array([2, 2, 0, 1, 2, 1])

Parameters:

key (str) – link attribute key [optional]

Return type:

array([int>=0])

outdegree_cdf()

Return the cumulative out-degree frequency distribution.

Example:

>>> r(Network.SmallTestNetwork().outdegree_cdf())
Calculating the cumulative out-degree distribution...
array([ 1. , 0.8333, 0.8333, 0.5 ])

Return type:

1d numpy array [k] of ints >= 0

Returns:

Entry [k] is the number of nodes having out-degree k or more.

outdegree_distribution()

Return the out-degree frequency distribution.

Example:

>>> r(Network.SmallTestNetwork().outdegree_distribution())
Calculating out-degree frequency distribution...
array([ 0.1667, 0. , 0.3333, 0.5 ])

Return type:

1d numpy array [k] of ints >= 0

Returns:

Entry [k] is the number of nodes having out-degree k.

pagerank(link_attribute=None, use_directed=True)

For each node, return its (weighted) PageRank.

This is the load on this node from the eigenvector corresponding to the largest eigenvalue of a modified adjacency matrix, normalized to a maximum of 1.

Example:

>>> r(Network.SmallTestNetwork().pagerank())
Calculating PageRank...
array([ 0.2184, 0.2044, 0.1409, 0.1448, 0.2047, 0.0869])

Parameters:

link_attribute (str) – Optional name of the link attribute to be used as the links’ weight. If None, links have weight 1. (Default: None)

Return type:

1d numpy array [node] of

path_lengths(link_attribute=None)

For each pair of nodes i,j, return the (weighted) shortest path length from i to j (also called the distance from i to j).

This is the shortest length of a path from i to j along links, or infinity if there is no such path.

The length of links can be specified by an optional link attribute.

Example:

>>> print(Network.SmallTestNetwork().path_lengths())
Calculating all shortest path lengths...
[[ 0.  2.  2.  1.  1.  1.]
 [ 2.  0.  1.  1.  1.  3.]
 [ 2.  1.  0.  2.  1.  3.]
 [ 1.  1.  2.  0.  2.  2.]
 [ 1.  1.  1.  2.  0.  2.]
 [ 1.  3.  3.  2.  2.  0.]]

Parameters:

link_attribute (str) – Optional name of the link attribute to be used as the links’ length. If None, links have length 1. (Default: None)

Return type:

square array [[float]]

permuted_copy(permutation)

Return a copy of the network with node numbers rearranged. This operation should not change topological information and network measures.

Parameters:

permutation (array-like [int]) – desired permutation of nodes

Return type:

Network instance

randomly_rewire(iterations)

Randomly rewire the network, preserving the degree sequence.

Example: Generate a network of 100 nodes with degree 5 each:

>>> net = Network.SmallTestNetwork(); print(net)
Network: undirected, 6 nodes, 7 links, link density 0.467.
>>> net.randomly_rewire(iterations=10); print(net)
Randomly rewiring the network,preserving the degree sequence...
Network: undirected, 6 nodes, 7 links, link density 0.467.

Parameters:

iterations (int > 0) – Number of iterations. In each iteration, two randomly chosen links a–b and c–d for which {a,c} and {b,d} are not linked, are replaced by the links a–c and b–d.

save(filename, fileformat=None, *args, **kwds)

Save the Network object to a file.

Unified writing function for graphs. Relies on and partially extends the corresponding igraph function. Refer to igraph documentation for further details on the various writer methods for different formats.

This method tries to identify the format of the graph given in the first parameter (based on extension) and calls the corresponding writer method.

Existing node and link attributes/weights are also stored depending on the chosen file format. E.g., the formats GraphML and gzipped GraphML are able to store both node and link weights.

The remaining arguments are passed to the writer method without any changes.

Parameters:

• filename (str) – The name of the file where the Network object is to be stored.

• fileformat (str) – the format of the file (if one wants to override the format determined from the filename extension, or the filename itself is a stream). None means auto-detection. Possible values are: "ncol" (NCOL format), "lgl" (LGL format), "graphml", "graphmlz" (GraphML and gzipped GraphML format), "gml" (GML format), "dot", "graphviz" (DOT format, used by GraphViz), "net", "pajek" (Pajek format), "dimacs" (DIMACS format), "edgelist", "edges" or "edge" (edge list), "adjacency" (adjacency matrix), "pickle" (Python pickled format), "svg" (Scalable Vector Graphics).

set_edge_list(edge_list, n_nodes=None)

Reset network from an edge list representation.

Note

Assumes that nodes are numbered by natural numbers from 0 to N-1 without gaps!

Example:

Parameters:

edge_list (array-like [[int>=0,int>=0]]) – [[i,j]] for edges i -> j

set_link_attribute(attribute_name, values)

Set the values of some link attribute.

These can be used as weights in measures requiring link weights.

Note

The attribute/weight matrix should be symmetric for undirected networks.

Parameters:

• attribute_name (str) – name of link attribute to be set

• values (square numpy array [node,node]) – Entry [i,j] is the attribute of the link from i to j.

set_node_attribute(attribute_name: str, values)

Add a node attribute.

Examples for node attributes/weights are degree or betweenness.

Parameters:

• attribute_name (str) – The name of the node attribute.

• values (1D Numpy array [node]) – The node attribute sequence.

silence_level: int

higher -> less progress info

sp_A: csc_matrix

Adjacency matrix. A[i,j]=1 indicates a link i -> j. Symmetric if the network is undirected.

sp_Aplus()

A^+ = A + Id. matrix used in n.s.i. measures

sp_diag_sqrt_w()

Sparse diagonal matrix of square roots of node weights

sp_diag_w()

Sparse diagonal matrix of node weights

sp_diag_w_inv()

Sparse diagonal matrix of inverse node weights

sp_nsi_diag_k()

Sparse diagonal matrix of n.s.i. degrees

sp_nsi_diag_k_inv()

Sparse diagonal matrix of inverse n.s.i. degrees

splitted_copy(node=-1, proportion=0.5)

Return a copy of the network with one node splitted.

The specified node is split in two interlinked nodes which are linked to the same nodes as the original node, and the weight is splitted according to the given proportion.

(This method is useful for testing the node splitting invariance of measures since a n.s.i. measure will be the same before and after the split.)

Example:

>>> net = Network.SmallTestNetwork(); print(net)
Network: undirected, 6 nodes, 7 links, link density 0.467.
>>> net2 = net.splitted_copy(node=5, proportion=0.2); print(net2)
Network: undirected, 7 nodes, 9 links, link density 0.429.
>>> print(net.node_weights); print(net2.node_weights)
[ 1.5  1.7  1.9  2.1  2.3  2.5]
[ 1.5  1.7  1.9  2.1  2.3  2.  0.5]

Parameters:

• node (int) – The index of the node to be splitted. If negative, N + index is used. The new node gets index N. (Default: -1)

• proportion (float from 0 to 1) – The splitted node gets a new weight of (1-proportion) * (weight of splitted node), and the new node gets a weight of proportion * (weight of splitted node). (Default: 0.5)

Return type:

Network

spreading(alpha=None)

For each node, return its “spreading” value.

Note

This is still EXPERIMENTAL!

Return type:

1d numpy array [node] of floats

total_node_weight: float

total node weight

transitivity()

Return the transitivity (coefficient).

This is the ratio of three times the number of triangles to the number of connected triples of vertices. [Newman2003] refers to this measure as C_1.

Example:

>>> r(Network.SmallTestNetwork().transitivity())
Calculating transitivity coefficient (C_1)...
0.2727

Return type:

float between 0 and 1

undirected_adjacency()

Return the adjacency matrix of the undirected version of the network as a dense numpy array. Entry [i,j] is 1 if i links to j or j links to i.

Example:

>>> net = Network(adjacency=[[0,1],[0,0]], directed=True)
>>> print(net.undirected_adjacency().toarray())
[[0 1] [1 0]]

Return type:

array([[0|1]])

undirected_copy()

Return an undirected copy of the network.

Nodes i and j are linked in the copy if, in the current network, i links to j or j links to i or both.

Example:

>>> net = Network(adjacency=[[0,1],[0,0]], directed=True); print(net)
Network: directed, 2 nodes, 1 links, link density 0.500.
>>> print(net.undirected_copy())
Network: undirected, 2 nodes, 1 links, link density 1.000.

Return type:

Network instance

static weighted_local_clustering(weighted_A)

For each node, return its weighted clustering coefficient, given a weighted adjacency matrix.

This follows [Holme2007].

Example:

>>> print(r(Network.weighted_local_clustering(weighted_A=[
...     [ 0.  , 0.  , 0.  , 0.55, 0.65, 0.75],
...     [ 0.  , 0.  , 0.63, 0.77, 0.91, 0.  ],
...     [ 0.  , 0.63, 0.  , 0.  , 1.17, 0.  ],
...     [ 0.55, 0.77, 0.  , 0.  , 0.  , 0.  ],
...     [ 0.65, 0.91, 1.17, 0.  , 0.  , 0.  ],
...     [ 0.75, 0.  , 0.  , 0.  , 0.  , 0.  ]])))
Calculating local weighted clustering coefficient...
[ 0.  0.2149  0.3539  0.  0.1538  0. ]

as compared to the unweighted version:

>>> print(r(Network.SmallTestNetwork().local_clustering()))
Calculating local clustering coefficients...
[ 0.  0.3333  1.  0.  0.3333  0. ]

Parameters:

weighted_A (square numpy array [node,node] of floats >= 0) – Entry [i,j] is the link weight from i to j. A value of 0 means there is no link.

Return type:

1d numpy array [node] of floats between 0 and 1

exception pyunicorn.core.network.NetworkError(value)

Bases: Exception

Used for all exceptions raised by Network.

__init__(value)

__str__()

Return str(self).

__weakref__

list of weak references to the object

pyunicorn.core.network.nz_coords(matrix)

Find coordinates of all non-zero entries in a sparse matrix.

Returns:

list of coordinates [row,col]

Return type:

array([[int>=0,int>=0]])

pyunicorn.core.network.r(obj, decimals=4)

Round numbers, arrays or iterables thereof. Only used in docstrings.

pyunicorn.core.network.rr(obj, decimals=4)

Round arrays in scientific notation. Only used in docstrings.