core.geo_network

Provides class for analyzing complex network embedded on a spherical surface.

class pyunicorn.core.geo_network.GeoNetwork(grid: GeoGrid, adjacency=None, edge_list=None, directed=False, node_weight_type='surface', silence_level=0)

Bases: SpatialNetwork

Encapsulates a network embedded on a spherical surface.

Particularly adds more network measures and statistics based on the spatial embedding.

Variables:

node_weight_type – (string) - The type of geographical node weight to be used.

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

Return a GeoNetwork object stored in files.

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 (tuple/list) – Tuple or list of two strings, namely the paths to the files containing the Network object and the GeoGrid object (filename_network, filename_grid)

• 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) – The inverse level of verbosity of the object.

Return type:

SpatialNetwork object

Returns:

GeolNetwork instance.

static Model(network_model, grid, node_weight_type='surface', **kwargs)

Return a new model graph generated with the specified network model and embedded on a geographical grid

static SmallTestNetwork()

Return a 6-node undirected geographically embedded test network.

The test network consists of the SmallTestNetwork of the Network class with node coordinates given by the SmallTestGrid of the GeoGrid class.

The network looks like this:

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

Return type:

GeoNetwork instance

Returns:

an instance of GeoNetwork for testing purposes.

__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__(grid: GeoGrid, adjacency=None, edge_list=None, directed=False, node_weight_type='surface', silence_level=0)

Initialize an instance of GeoNetwork.

Parameters:

• grid (GeoGrid) – The GeoGrid object describing the network’s spatial embedding.

• adjacency (2D array (int8) [index, index]) – The network’s adjacency matrix.

• 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) – Determines, whether the network is treated as directed.

• node_weight_type (str) – The type of geographical node weight to be used.

• silence_level (int) – The inverse level of verbosity of the object.

Possible choices for node_weight_type:

• None (constant unit weights)

• “surface” (cos lat)

• “irrigation” (cos² lat)

__rec_cache_state__() → Tuple[object, ...]

Similar to __cache_state__(), but lists attributes which are themselves instances of Cached. Empty by default.

__str__()

Return a string representation of the GeoNetwork object.

_calculate_general_connectivity_weighted_distance(adjacency, degrees)

Return general connectivity weighted link distances (CWD).

This method is called to calculate undirected CWD, in-CWD and out-CWD.

Parameters:

• adjacency (2D array [index, index]) – The adjacency matrix.

• degrees (1D array [index]) – The degree sequence.

Return type:

1D array [index]

Returns:

the general connectivity weighted distance sequence.

area_weighted_connectivity()

Return area weighted connectivity (\(AWC\)).

It gives the fractional area of the network, a node is connected to. \(AWC\) is closely related to node splitting invariant degree Network.nsi_degree() with area as node weight.

Example:

>>> r(GeoNetwork.SmallTestNetwork().area_weighted_connectivity())
array([ 0.4854, 0.499 , 0.3342, 0.3446, 0.5146, 0.1726])

Return type:

1D Numpy array [index]

Returns:

the area weighted connectivity sequence.

area_weighted_connectivity_cumulative_distribution(n_bins)

Return the cumulative area weighted connectivity distribution.

Also return estimated statistical error and lower bin boundaries.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                area_weighted_connectivity_cumulative_distribution(
...         n_bins=4)[0])
array([ 1. , 0.8435, 0.5068, 0.1622])

Parameters:

n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the cumulative \(AWC\) distribution, statistical error, and lower bin boundaries.

area_weighted_connectivity_distribution(n_bins)

Return the area weighted connectivity frequency distribution.

Also return estimated statistical error and lower bin boundaries.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                area_weighted_connectivity_distribution(n_bins=4)[0])
array([ 0.1565, 0.3367, 0.3446, 0.1622])

Parameters:

n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the \(AWC\) distribution, statistical error, and lower bin boundaries.

average_neighbor_area_weighted_connectivity()

Return average neighbor area weighted connectivity.

Note

Does not use directionality information.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                average_neighbor_area_weighted_connectivity())
array([ 0.3439, 0.3978, 0.5068, 0.4922, 0.4395, 0.4854])

Return type:

1D Numpy array [index]

Returns:

the average neighbor area weighted connectivity sequence.

boundary(nodes, geodesic=True, gap=0.0)

Return a list of ordered lists of nodes on the connected parts of the boundary of a subset of nodes and a list of ordered lists of (lat,lon) coordinates of the corresponding polygons

• EXPERIMENTAL! *

connectivity_weighted_distance()

Return undirected connectivity weighted link distances (CWD).

Note

Does not use directionality information.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                connectivity_weighted_distance())
array([ 0.0625, 0.0321, 0.0241, 0.0419, 0.05 , 0.0837])

Return type:

1D Numpy array [index]

Returns:

the undirected connectivity weighted distance sequence.

geographical_cumulative_distribution(sequence, n_bins)

Return a normalized geographical cumulative distribution.

Also return estimated statistical error and the lower bin boundaries.

This function counts which percentage of total surface area has a value of sequence larger or equal than the one bounded by a specific bin and NOT which number of nodes does so.

Note

Be aware that this method only returns meaningful results for regular rectangular grids, where the representative area of each node is proportional to the cosine of its latitude.

Example:

>>> net = GeoNetwork.SmallTestNetwork()
>>> r(net.geographical_cumulative_distribution(
...     sequence=net.degree(), n_bins=3)[0])
array([ 1. , 0.8435, 0.5068])

Parameters:

• sequence (1D Numpy array [index]) – The input sequence (e.g., some local network measure).

• n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the cumulative geographical distribution, statistical error, and lower bin boundaries.

geographical_distribution(sequence, n_bins)

Return a normalized geographical frequency distribution.

Also return the estimated statistical error and lower bin boundaries.

This function counts which percentage of total surface area falls into a bin and NOT which number of nodes does so.

Note

Be aware that this method only returns meaningful results for regular rectangular grids, where the representative area of each node is proportional to the cosine of its latitude.

Example:

>>> net = GeoNetwork.SmallTestNetwork()
>>> r(net.geographical_distribution(
...     sequence=net.degree(), n_bins=3)[0])
array([ 0.1565, 0.3367, 0.5068])

Parameters:

• sequence (1D Numpy array [index]) – The input sequence (e.g., some local network measure).

• n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the geographical distribution, statistical error, and lower bin boundaries.

grid: GeoGrid

GeoGrid object describing the network’s spatial embedding

inarea_weighted_connectivity()

Return in-area weighted connectivity.

It gives the fractional area of the netwerk that connects to a given node. For undirected networks, it calculates total area weighted connectivity.

Example:

>>> r(GeoNetwork.SmallTestNetwork().inarea_weighted_connectivity())
array([ 0.4854, 0.499 , 0.3342, 0.3446, 0.5146, 0.1726])

Return type:

1D Numpy array [index]

Returns:

the in-area weighted connectivity sequence.

inarea_weighted_connectivity_cumulative_distribution(n_bins)

Return the cumulative in-area weighted connectivity distribution.

Also return estimated statistical error and lower bin boundaries.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                inarea_weighted_connectivity_cumulative_distribution(
...         n_bins=4)[0])
array([ 1. , 0.8435, 0.5068, 0.1622])

Parameters:

n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the cumulative in-\(AWC\) distribution, statistical error, and lower bin boundaries.

inarea_weighted_connectivity_distribution(n_bins)

Return the in-area weighted connectivity frequency distribution.

Also return estimated statistical error and lower bin boundaries.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                inarea_weighted_connectivity_distribution(n_bins=4)[0])
array([ 0.1565, 0.3367, 0.3446, 0.1622])

Parameters:

n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the in-\(AWC\) distribution, statistical error, and lower bin boundaries.

inconnectivity_weighted_distance()

Return in-connectivity weighted link distances (CWD).

Example:

>>> r(GeoNetwork.SmallTestNetwork().                inconnectivity_weighted_distance())
array([ 0.0625, 0.0321, 0.0241, 0.0419, 0.05 , 0.0837])

Return type:

1D Numpy array [index]

Returns:

the in-connectivity weighted distance sequence.

intotal_link_distance(geometry_corrected=False)

Return the sequence of in-total link distances for all nodes.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                intotal_link_distance(geometry_corrected=False))
array([ 0.1886, 0.097 , 0.0486, 0.0838, 0.1498, 0.0837])

Parameters:

geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the in-total link distance sequence.

local_geographical_clustering()

Return local geographical clustering.

Returns the sequence of local clustering coefficients weighted by the inverse angular great circle distance between nodes. This guarantees, that short links between spatially neighboring nodes in a triangle are weighted higher than long links between nodes that are spatially far away.

Uses a definition of weighted clustering coefficient introduced in [Holme2007].

Note

Experimental measure!

Example:

>>> r(GeoNetwork.SmallTestNetwork().local_geographical_clustering())
Calculating local weighted clustering coefficient...
array([ 0. , 0.0998, 0.1489, 0. , 0.2842, 0. ])

Return type:

1D Numpy array (index)

Returns:

the local geographical clustering sequence.

max_neighbor_area_weighted_connectivity()

Return maximum neighbor area weighted connectivity.

Note

Does not use directionality information.

>>> r(GeoNetwork.SmallTestNetwork().                max_neighbor_area_weighted_connectivity())
array([ 0.5146, 0.5146, 0.5146, 0.499 , 0.499 , 0.4854])

Return type:

1D Numpy array [index]

Returns:

the maximum neighbor area weighted connectivity sequence.

nsi_connected_hamming_cluster_tree(lon_closed=True, lat_closed=False, alpha=0.01)

Perform NSI agglomerative clustering.

Minimize in each step the Hamming distance between the original and the clustered network, but only joins connected clusters.

Return c,h where c[i,j] = i iff node j is in cluster no. i, and 0 otherwise, and h is the corresponding list of total resulting relative Hamming distance between 0 and 1. The cluster numbers for all nodes and a k clusters solution is then c[:2*N-k,:].max(axis=0)

Parameters:

• lon_closed (bool) – TODO

• lat_closed (bool) – TODO

• alpha (float) – TODO

Return type:

TODO

Returns:

TODO

outarea_weighted_connectivity()

Return out-area weighted connectivity.

It gives the fractional area of the netwerk that a given node connects to. For undirected networks, it calculates total area weighted connectivity.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                outarea_weighted_connectivity())
array([ 0.4854, 0.499 , 0.3342, 0.3446, 0.5146, 0.1726])

Return type:

1D Numpy array [index]

Returns:

the out-area weighted connectivity sequence.

outarea_weighted_connectivity_cumulative_distribution(n_bins)

Return the cumulative out-area weighted connectivity distribution.

Also return estimated statistical error and lower bin boundaries.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                outarea_weighted_connectivity_cumulative_distribution(
...         n_bins=4)[0])
array([ 1. , 0.8435, 0.5068, 0.1622])

Parameters:

n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the cumulative out-\(AWC\) distribution, statistical error, and lower bin boundaries.

outarea_weighted_connectivity_distribution(n_bins)

Return the out-area weighted connectivity frequency distribution.

Also return estimated statistical error and lower bin boundaries.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                outarea_weighted_connectivity_distribution(n_bins=4)[0])
array([ 0.1565, 0.3367, 0.3446, 0.1622])

Parameters:

n_bins (number (int)) – The number of bins for histogram.

Return type:

tuple of three 1D Numpy arrays [bin]

Returns:

the out-\(AWC\) distribution, statistical error, and lower bin boundaries.

outconnectivity_weighted_distance()

Return out-connectivity weighted link distances (CWD).

Example:

>>> r(GeoNetwork.SmallTestNetwork().                outconnectivity_weighted_distance())
array([ 0.0625, 0.0321, 0.0241, 0.0419, 0.05 , 0.0837])

Return type:

1D Numpy array [index]

Returns:

the out-connectivity weighted distance sequence.

outtotal_link_distance(geometry_corrected=False)

Return the sequence of out-total link distances for all nodes.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                outtotal_link_distance(geometry_corrected=False))
array([ 0.1886, 0.097 , 0.0486, 0.0838, 0.1498, 0.0837])

Parameters:

geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the out-total link distance sequence.

save_for_cgv(filename, fileformat='graphml')

Save the GeoNetwork and its attributes for the CGV visualization software.

The node coordinates are stored as node attributes by default, likewise angular link distances are stored as edge attributes by default. All additional node and link properties are also stored for visualization.

This format is intended for being used by the spatial graph visualization software CGV developed in Rostock (contact Thomas Nocke, nocke@pik-potsdam.de). By default, the file includes the latitude and longitude vectors as node properties, as well as the geodesic angular distance as an link property.

Parameters:

• file_name (str) – The file name should end with “.dot” or “.gml”.

• fileformat (str) – The file format: “graphml” - GraphML format “graphmlz” - gzipped GraphML format “graphviz” - GraphViz format

set_node_weight_type(node_weight_type)

Set node weights for calculation of n.s.i. measures according to requested type.

Possible choices for node_weight_type:

• None (constant unit weights)

• “surface” (cos lat)

• “irrigation” (cos² lat)

Parameters:

node_weight_type (str) – The type of geographical node weight to be used.

shuffled_by_distance_copy()

Return a copy of the network where all links in each node-distance class have been randomly re-assigned.

In other words, the result is a random network in which the link probability only depends on the nodes’ distance and is the same as in the original network.

Return type:

GeoNetwork

Returns:

the distance shuffled copy.

total_link_distance(geometry_corrected=False)

Return the sequence of total link distances for all nodes.

Note

Does not use directionality information.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                total_link_distance(geometry_corrected=False))
array([ 0.1886, 0.097 , 0.0486, 0.0838, 0.1498, 0.0837])

Parameters:

geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the total link distance sequence.