climate.climate_network

Provides classes for generating and analyzing complex climate networks.

class pyunicorn.climate.climate_network.ClimateNetwork(grid: GeoGrid, similarity_measure: ndarray, threshold=None, link_density=None, non_local=False, directed=False, node_weight_type='surface', silence_level=0)

Bases: GeoNetwork

Encapsulates a similarity network embedded on a spherical surface.

Particularly provides functionality to generate a complex network from the matrix of a similarity measure of time series.

The analysis of climate time series based on similarity networks was first introduced in [Tsonis2004].

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

Return a ClimateNetwork 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 three strings, namely the paths to the files containing the Network object, the GeoGrid object and the similarity measure matrix. (filename_network, filename_grid, filename_similarity_measure)

• 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).

Returns:

ClimateNetwork instance.

static SmallTestNetwork()

Return a 6-node undirected test climate network from a similarity matrix.

The network looks like this:

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

Example:

>>> r(ClimateNetwork.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:

Network instance

__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, similarity_measure: ndarray, threshold=None, link_density=None, non_local=False, directed=False, node_weight_type='surface', silence_level=0)

Initialize an instance of ClimateNetwork.

Note

Either threshold OR link_density have to be given!

Possible choices for node_weight_type:

• None (constant unit weights)

• “surface” (cos lat)

• “irrigation” (cos**2 lat)

Parameters:

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

• similarity_measure (2D array [index, index]) – The similarity measure for all pairs of nodes.

• threshold (float) – The threshold of similarity measure, above which two nodes are linked in the network.

• link_density (float) – The networks’s desired link density.

• non_local (bool) – Determines, whether links between spatially close nodes should be suppressed.

• 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.

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

Example:

>>> print(ClimateNetwork.SmallTestNetwork())
ClimateNetwork:
GeoNetwork:
Network: undirected, 6 nodes, 7 links, link density 0.467.
Geographical boundaries:
         time     lat     lon
   min    0.0    0.00    2.50
   max    9.0   25.00   15.00
Threshold: 0.5
Local connections filtered out: False

_calculate_non_local_adjacency(similarity_measure, threshold, a=20, d_min=0.05)

Return the adjacency matrix with suppressed spatially local links.

Physically trivial links between geographically close nodes are removed.

For large a, \(d_min\) corresponds to the minimum distance for which links are allowed to exist.

Example:

>>> net = ClimateNetwork.SmallTestNetwork()
>>> net._calculate_non_local_adjacency(
...     similarity_measure=net.similarity_measure(),
...     threshold=0.5, a=30, d_min=0.20)
array([[0, 0, 0, 1, 1, 1], [0, 0, 0, 0, 1, 0],
       [0, 0, 0, 0, 0, 0], [1, 0, 0, 0, 0, 0],
       [1, 1, 0, 0, 0, 0], [1, 0, 0, 0, 0, 0]], dtype=int8)

Parameters:

• similarity_measure (2D Numpy array [index, index]) – The similarity measure for all pairs of nodes.

• threshold (number (float)) – The threshold of similarity measure, above which two nodes are linked in the network.

• a (number (float)) – The steepness parameter of the distance weighting function in the transition region from not including any links (weight=0) to including all links (weight=1).

• d_min (number (float)) – The parameter controlling the minimum distance, above which links can be included in the network (unit radians).

Return type:

2D Numpy array (int8) [index, index]

Returns:

the network’s adjacency matrix.

_calculate_threshold_adjacency(similarity_measure, threshold)

Extract the network’s adjacency matrix by thresholding.

The resulting network is a simple graph, i.e., self-loops and multiple links are not allowed.

Example (Threshold zero should yield a fully connected network given the test similarity matrix):

>>> net = ClimateNetwork.SmallTestNetwork()
>>> net._calculate_threshold_adjacency(
...     similarity_measure=net.similarity_measure(), threshold=0.0)
array([[0, 1, 1, 1, 1, 1], [1, 0, 1, 1, 1, 1],
       [1, 1, 0, 1, 1, 1], [1, 1, 1, 0, 1, 1],
       [1, 1, 1, 1, 0, 1], [1, 1, 1, 1, 1, 0]], dtype=int8)

Parameters:

• similarity_measure (2D Numpy array [index, index]) – The similarity measure for all pairs of nodes.

• threshold (number (float)) – The threshold of similarity measure, above which two nodes are linked in the network.

Return type:

2D Numpy array (int8) [index, index]

Returns:

the network’s adjacency matrix.

_regenerate_network()

Regenerate the current climate network according to a new similarity measure.

correlation_distance()

Return correlation weighted distances between nodes.

Defined as the elementwise product of the correlation measure and angular great circle distance matrices.

This is a useful measure of the relative importance of links, since links with high geographical distance and high correlation (teleconnections) get the highest weight. Trivial correlations with small geographical distance and high correlation get a lower weight.

Correlation distance appears to be the simplest functional form of combining geographical distance and correlation measure that yields meaningful results.

Example:

>>> r(ClimateNetwork.SmallTestNetwork().correlation_distance(), 2)
array([[ 0.  , 0.01, 0.04, 0.18, 0.27, 0.27],
       [ 0.01, 0.  , 0.05, 0.18, 0.29, 0.12],
       [ 0.04, 0.05, 0.  , 0.02, 0.16, 0.03],
       [ 0.18, 0.18, 0.01, 0.  , 0.01, 0.06],
       [ 0.27, 0.29, 0.16, 0.01, 0.  , 0.04],
       [ 0.27, 0.12, 0.03, 0.06, 0.04, 0.  ]])

Return type:

2D matrix [index, index]

Returns:

the correlation distance matrix.

correlation_distance_weighted_closeness()

Return correlation distance weighted closeness.

Calculates the sequence of closeness centralities link-weighted by the inverse of correlation distance between nodes. For closeness centrality calculation, the inverse of correlation distance is used, because high values of this measure should correspond to short distances in the graph and vice versa when weighted shortest paths are calculated.

Example:

>>> r(ClimateNetwork.SmallTestNetwork().                correlation_distance_weighted_closeness())
array([ 0.1646, 0.1351, 0.0894, 0.1096, 0.1659, 0.1102])

Return type:

1D Numpy array [index]

Returns:

the correlation distance weighted closeness sequence.

inv_correlation_distance()

Return correlation weighted distances between nodes.

Return type:

2D matrix [index, index]

link_density_function(n_bins)

Return the network’s link density as a function of the threshold.

Example:

>>> r(ClimateNetwork.SmallTestNetwork().                link_density_function(3)[0])
array([ 0. , 0.3889, 0.6667])
>>> r(ClimateNetwork.SmallTestNetwork().                link_density_function(3)[1])
array([ 0.1, 0.4, 0.7, 1. ])

Parameters:

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

Return type:

tuple of two 1D Numpy arrays [bin]

Returns:

the network’s link density in dependence on threshold.

local_correlation_distance_weighted_vulnerability()

Return local correlation distance weighted vulnerability.

Calculates the sequence of vulnerabilities link-weighted by the inverse of correlation distance between nodes. For vulnerability calculation, the inverse of correlation distance is used, because high values of this measure should correspond to short distances in the graph and vice versa when weighted shortest paths are calculated.

Example:

>>> r(ClimateNetwork.SmallTestNetwork().                local_correlation_distance_weighted_vulnerability())
array([ 0.4037, 0.035 , -0.1731, -0.081 , 0.3121, -0.0533])

Return type:

1D Numpy array

Returns:

the local correlation distance weighted vulnerability sequence.

non_local()

Indicate if links between spatially close nodes were suppressed.

Example:

>>> ClimateNetwork.SmallTestNetwork().non_local()
False

Return bool:

Determines, whether links between spatially close nodes should be suppressed.

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

Save the ClimateNetwork 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.

Note

The similarity measure matrix and grid are not stored if the corresponding filenames are None.

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

Parameters:

• filename (tuple/list) – Tuple or list of three strings, namely the paths to the files where the Network object, the GeoGrid object and the similarity measure matrix are 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).

• filename_similarity_measure (str) – The name of the file where the similarity measure matrix is to be stored.

set_link_density(link_density)

Generate climate network by thresholding with prescribed link density.

Note

The desired link density can only be achieved approximately in most cases.

Example:

>>> net = ClimateNetwork.SmallTestNetwork()
>>> r(net.link_density)
0.4667
>>> net.set_link_density(link_density=0.7)
>>> r(net.link_density)
0.6667

Parameters:

link_density (number (float)) – The networks’s desired link density.

set_non_local(non_local)

Toggle suppression of links between spatially close nodes.

Example:

>>> net = ClimateNetwork.SmallTestNetwork()
>>> net.set_non_local(non_local=True)
>>> r(net.adjacency)
array([[0, 0, 0, 1, 1, 1], [0, 0, 0, 1, 1, 0], [0, 0, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0], [1, 1, 1, 0, 0, 0], [1, 0, 0, 0, 0, 0]])

Parameters:

non_local (bool) – Determines, whether links between spatially close nodes should be suppressed.

set_threshold(threshold)

Generate climate network by thresholding similarity matrix.

Example (Number of links decreases as threshold increases):

>>> net = ClimateNetwork.SmallTestNetwork()
>>> net.n_links
7
>>> net.set_threshold(threshold=0.7)
>>> net.n_links
3

Parameters:

threshold (number (float)) – the threshold used to generate the current climate network.

similarity_measure()

Return the similarity measure used for network construction.

Example:

>>> r(ClimateNetwork.SmallTestNetwork().similarity_measure()[0,:])
array([ 1. , 0.1 , 0.2 , 0.6 , 0.7 , 0.55])

Return type:

2D Numpy array [index, index]

Returns:

The similarity measure for all pairs of nodes.

threshold()

Return the threshold used to generate the current climate network.

Example:

>>> ClimateNetwork.SmallTestNetwork().threshold()
0.5

Return type:

number (float)

Returns:

the threshold used to generate the current climate network.

threshold_from_link_density(link_density)

Return the threshold for network construction given link density.

Example:

>>> r(ClimateNetwork.SmallTestNetwork().                threshold_from_link_density(link_density=0.5))
0.4

Parameters:

link_density (number (float)) – The networks’s desired link density.

Return type:

number (float)

Returns:

The threshold of similarity measure, above which two nodes are linked in the network.