core.spatial_network

Provides class for analyzing spatially embedded complex networks.

class pyunicorn.core.spatial_network.SpatialNetwork(grid: Grid, adjacency=None, edge_list=None, directed=False, silence_level=0)

Bases: Network

Encapsulates a spatially embedded network.

Adds more network measures and statistics based on the spatial embedding.

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

Return a SpatialNetwork 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 Grid 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:

SpatialNetwork instance.

static Model(network_model, grid, **kwargs)

Return a new model graph generated with the specified network model and embedded on the specified spatial 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 Grid class.

The network looks like this:

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

Return type:

SpatialNetwork object

Returns:

SpatialNetwork instance 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: Grid, adjacency=None, edge_list=None, directed=False, silence_level=0)

Initialize an instance of SpatialNetwork.

Parameters:

• grid (Grid) – The Grid 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.

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

__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 SpatialNetwork object.

_calculate_general_average_link_distance(adjacency, degrees, geometry_corrected=False)

Return general average link distances (\(ALD\)).

This general method is called to calculate undirected average link distance, average in-link distance and average out-link distance.

The resulting sequence can optionally be corrected for biases in average link distance arising due to the grid geometry. E.g., for regional networks, nodes on the boundaries may have a bias towards larger values of \(ALD\), while nodes in the center have a bias towards smaller values of \(ALD\).

Parameters:

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

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

• geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the general average link distance sequence.

average_distance_weighted_path_length()

Return average distance weighted path length.

Returns the average path length link-weighted by the angular great circle distance between nodes.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                average_distance_weighted_path_length())
0.4985

Return type:

number (float)

Returns:

the average distance weighted path length.

average_link_distance(geometry_corrected=False)

Return average link distances (undirected).

Note

Does not use directionality information.

Examples:

>>> SpatialNetwork.SmallTestNetwork().                average_link_distance(geometry_corrected=False)
array([22.36067963, 11.18033981,  8.38525486, 13.97542477, 16.77050908,
       27.95084953])
>>> SpatialNetwork.SmallTestNetwork().                average_link_distance(geometry_corrected=True)[:-1]
array([1.6       , 1.09090909, 1.        , 1.66666667, 1.63636357])

Parameters:

geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the average link distance sequence (undirected).

distance()

Return the distance matrix.

distance_weighted_closeness()

Return distance weighted closeness.

Returns the sequence of closeness centralities link-weighted by the angular great circle distance between nodes.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                distance_weighted_closeness())
array([ 2.2378, 2.4501, 2.2396, 2.4501, 2.2396, 1.1982])

Return type:

1D Numpy array [index]

Returns:

the distance weighted closeness sequence.

grid: Grid

(Grid) - Grid object describing the network’s spatial embedding

inaverage_link_distance(geometry_corrected=False)

Return in-average link distances.

Return regular average link distance for undirected networks.

Example:

>>> SpatialNetwork.SmallTestNetwork().                inaverage_link_distance(geometry_corrected=False)
array([22.36067963, 11.18033981,  8.38525486, 13.97542477, 16.77050908,
       27.95084953])

Parameters:

geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the in-average link distance sequence.

link_distance_distribution(n_bins, grid_type='euclidean', geometry_corrected=False)

Return the normalized link distance distribution.

Correct for the geometry of the embedding space by default.

Examples:

>>> GeoNetwork.SmallTestNetwork().link_distance_distribution(
...     n_bins=4, geometry_corrected=False)[0]
array([ 0.14285714,  0.28571429,  0.28571429,  0.28571429])
>>> GeoNetwork.SmallTestNetwork().link_distance_distribution(
...     n_bins=4, geometry_corrected=True)[0]
array([ 0.09836066,  0.24590164,  0.32786885,  0.32786885])

Parameters:

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

• grid_type (str) – Type of grid, used for distance calculation, can take values “euclidean” and “spherical” (only for GeoNetwork).

• geometry_corrected (bool) – Toggles correction for grid geometry.

Return type:

tuple of three 1D arrays [bin]

Returns:

the link distance distribution, statistical error, and lower bin boundaries.

local_distance_weighted_vulnerability()

Return local distance weighted vulnerability.

Return the sequence of vulnerabilities link-weighted by the angular great circle distance between nodes.

Example:

>>> r(GeoNetwork.SmallTestNetwork().                local_distance_weighted_vulnerability())
array([ 0.0325, 0.3137, 0.2056, 0.028 , -0.0283, -0.288 ])

Return type:

1D Numpy array [index]

Returns:

the local distance weighted vulnerability sequence.

max_link_distance()

Return maximum angular geodesic link distances.

Note

Does not use directionality information.

Example:

>>> SpatialNetwork.SmallTestNetwork().max_link_distance()
array([27.95085, 16.77051, 11.18034, 16.77051, 22.36068, 27.95085],
      dtype=float32)

Return type:

1D Numpy array [index]

Returns:

the maximum link distance sequence.

outaverage_link_distance(geometry_corrected=False)

Return out-average link distances.

Return regular average link distance for undirected networks.

Example:

>>> SpatialNetwork.SmallTestNetwork().
        outaverage_link_distance(geometry_corrected=False)
array([22.36067963, 11.18033981,  8.38525486, 13.97542477, 16.77050908,
       27.95084953])

Parameters:

geometry_corrected (bool) – Toggles geometry correction.

Return type:

1D array [index]

Returns:

the out-average link distance sequence.

randomly_rewire_geomodel_I(distance_matrix, iterations, inaccuracy)

Randomly rewire the current network in place using geographical model I.

Geographical model I preserves the degree sequence (exactly) and the link distance distribution \(p(l)\) (approximately).

A higher inaccuracy in the conservation of \(p(l)\) will lead to

• less deterministic links in the network and, hence,

• more degrees of freedom for the random graph and

• a shorter runtime of the algorithm, since more pairs of nodes eligible for rewiring can be found.

Example (The degree sequence should be the same after rewiring):

>>> net = SpatialNetwork.SmallTestNetwork()
>>> net.randomly_rewire_geomodel_I(
...     distance_matrix=net.grid.distance(),
...     iterations=100, inaccuracy=100)
#
>>> net.degree()
array([3, 3, 2, 2, 3, 1])

Parameters:

• distance_matrix (2D Numpy array [index, index]) – Suitable distance matrix between nodes.

• iterations (number (int)) – The number of rewirings to be performed.

• inaccuracy (number (float)) – The inaccuracy with which to conserve \(p(l)\).

randomly_rewire_geomodel_II(distance_matrix, iterations, inaccuracy)

Randomly rewire the current network in place using geographical model II.

Geographical model II preserves the degree sequence \(k_v\) (exactly), the link distance distribution \(p(l)\) (approximately), and the average link distance sequence \(<l>_v\) (approximately).

A higher inaccuracy in the conservation of \(p(l)\) and \(<l>_v\) will lead to:

• less deterministic links in the network and, hence,

• more degrees of freedom for the random graph and

• a shorter runtime of the algorithm, since more pairs of nodes eligible for rewiring can be found.

Parameters:

• distance_matrix (2D Numpy array [index, index]) – Suitable distance matrix between nodes.

• iterations (number (int)) – The number of rewirings to be performed.

• inaccuracy (number (float)) – The inaccuracy with which to conserve \(p(l)\).

randomly_rewire_geomodel_III(distance_matrix, iterations, inaccuracy)

Randomly rewire the current network in place using geographical model III.

Geographical model III preserves the degree sequence \(k_v\) (exactly), the link distance distribution \(p(l)\) (approximately), and the average link distance sequence \(<l>_v\) (approximately). Moreover, degree-degree correlations are also conserved exactly.

A higher inaccuracy in the conservation of \(p(l)\) and \(<l>_v\) will lead to:

• less deterministic links in the network and, hence,

• more degrees of freedom for the random graph and

• a shorter runtime of the algorithm, since more pairs of nodes eligible for rewiring can be found.

Parameters:

• distance_matrix (2D Numpy array [index, index]) – Suitable distance matrix between nodes.

• iterations (number (int)) – The number of rewirings to be performed.

• inaccuracy (number (float)) – The inaccuracy with which to conserve \(p(l)\).

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

Save the SpatialNetwork object to files.

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 grid is not stored if the corresponding filename is None.

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

Parameters:

• filename (tuple/list) – Tuple or list of two strings, namely the paths to the files where the Network object and the GeoGrid object are to be stored (filename_network, filename_grid)

• 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_random_links_by_distance(a, b)

Reassign links independently with link probability = \(exp(a + b*angular distance)\).

Note

Modifies network in place, creates an undirected network!

Example (Repeat until a network with 5 links is created):

>>> net = GeoNetwork.SmallTestNetwork()
>>> while (net.n_links != 5):
...     net.set_random_links_by_distance(a=0., b=-4.)
>>> net.n_links
5

Parameters:

• a (number (float)) – The a parameter.

• b (number (float)) – The b parameter.