climate.coupled_climate_network

Provides classes for generating and analyzing complex coupled climate networks.

class pyunicorn.climate.coupled_climate_network.CoupledClimateNetwork(grid_1, grid_2, similarity_measure, threshold=None, link_density=None, non_local=False, directed=False, node_weight_type='surface', silence_level=0)

Bases: InteractingNetworks, ClimateNetwork

Encapsulates a coupled 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 from two different observables (temperature, pressure), vertical levels etc.

So far, most methods only give meaningful results for undirected networks!

The idea of coupled climate networks is based on the concept of coupled patterns, for a review refer to [Bretherton1992].

Note

The two observables (layers) need to have the same time grid (temporal sampling points).

N: int

(number (int)) - The total number of nodes in both layers.

N_1

(number (int)) - The number of nodes in the first layer.

N_2

(number (int)) - The number of nodes in the second layer.

__init__(grid_1, grid_2, similarity_measure, threshold=None, link_density=None, non_local=False, directed=False, node_weight_type='surface', silence_level=0)

Initialize an instance of CoupledClimateNetwork.

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_1 (GeoGrid) – The GeoGrid object describing the first layer’s spatial embedding.

• grid_2 (GeoGrid) – The GeoGrid object describing the second layer’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.

• strnode_weight_type – The type of geographical node weight to be used.

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

__str__()

Return a string representation of CoupledClimateNetwork object.

adjacency_1()

Return internal adjacency matrix of first layer.

Return type:

2D Numpy array [index_1, index_1]

Returns:

the internal adjacency matrix of first layer.

adjacency_2()

Return internal adjacency matrix of second layer.

Return type:

2D Numpy array [index_2, index_2]

Returns:

the internal adjacency matrix of second layer.

cross_average_link_distance(reverse=False)

Return the cross average link distance

The cross average link distance is the average link distance of each node of the first subnetwork to the nodes of the second subnetwork it is connected to. If reverse is set to True, the method calculates the average link distance of each node of the second subnetwork to the nodes of the first subnetwork.

Parameters:

reverse (bool) – Replace the subnetworks.

Return type:

1D Numpy array

Returns:

the cross average link distances

cross_average_path_length(link_attribute=None)

Return cross average path length.

Return the average (weighted) shortest path length between all pairs of nodes from different layers only.

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 float:

the cross average path length.

cross_betweenness()

Return the cross betweenness sequence.

Gives the normalized number of shortest paths only between nodes from different layers, in which a node \(i\) is contained. This is equivalent to the inter-regional / inter-group betweenness with respect to layer 1 and layer 2.

Return type:

tuple of two 1D arrays [index]

Returns:

the cross betweenness sequence.

cross_closeness(link_attribute=None)

Return cross closeness sequence.

Gives the inverse average geodesic distance from a node in one layer to all nodes in the other layer.

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:

tuple of two 1D arrays [index]

Returns:

the cross closeness sequence.

cross_degree()

Return the cross degree sequences.

Gives the number of links from a specific node in one layer to the other layer.

Return type:

tuple of two 1D arrays [index]

Returns:

the cross degree sequences.

cross_global_clustering()

Return global cross clustering for coupled network.

The global cross clustering coefficient C_v gives the average probability, that two randomly drawn neighbors in layer 2 of node v in layer 1 are also neighbors and vice versa. It counts triangles having one vertex in layer 1 and two vertices in layer 2 and vice versa.

Return type:

(float, float)

Returns:

the cross global clustering coefficients.

cross_layer_adjacency()

Return cross adjacency matrix of the coupled network.

The cross adjacency matrix entry \(CA_{ij} = 1\) describes that node \(i\) in the first layer is linked to node \(j\) in the second layer. Vice versa, \(CA_{ji} = 1\) indicates that node \(j\) in the first layer is linked to node \(i\) in the second layer.

Note

Cross adjacency matrix is NEITHER square NOR symmetric in general!

Return type:

2D Numpy array [index_1, index_2]

Returns:

the cross adjacency matrix.

cross_link_density()

Return the density of links between the two layers.

Return float:

the density of links between the two layers.

cross_link_distance()

Return cross link distance matrix.

Contains the distance between nodes from different layers.

Return type:

2D array [index_1, index_2]

Returns:

the cross link distance matrix.

cross_local_clustering()

Return local cross clustering for coupled network.

The local cross clustering coefficient C_v gives the probability, that two randomly drawn neighbors in layer 2 of node v in layer 1 are also neighbors and vice versa. It counts triangles having one vertex in layer 1 and two vertices in layer 2 and vice versa.

Return type:

tuple of two 1D arrays [index]

Returns:

the cross local clustering coefficients.

cross_path_lengths(link_attribute=None)

Return cross path length matrix.

Contains the path length between nodes from different layers. The paths contain nodes from both layers.

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:

2D array [index_1, index_2]

Returns:

the cross path length matrix.

cross_similarity_measure()

Return cross similarity measure matrix.

Note

Cross similarity measure matrix is NEITHER square NOR symmetric in general!

Return type:

2D Numpy array [index_1, index_2]

Returns:

the cross similarity measure matrix.

cross_transitivity()

Return cross transitivity for coupled network.

The cross transitivity is the probability, that two randomly drawn neighbors in layer 2 of node v in layer 1 are also neighbors and vice versa. It counts triangles having one vertex in layer 1 and two vertices in layer 2 and vice versa. Cross transitivity tends to weight low cross degree vertices less strongly when compared to the global cross clustering coefficient (see [Newman2003]).

Return type:

(float, float)

Returns:

the cross transitivities.

grid_1

(Grid) - The GeoGrid object describing the first layer’s spatial embedding.

grid_2

(Grid) - The GeoGrid object describing the second layer’s spatial embedding.

internal_average_path_length(link_attribute=None)

Return internal average path length.

Return the average (weighted) shortest path length between all pairs of nodes within each layer separately for which a path exists. Paths between nodes from different layers are not included in the averages!

However, even if the end points lie within the same layer, the paths themselves will generally contain nodes from both layers. To avoid this and only consider paths lying within layer i, do the following:

net_i = coupled_network.network_i()
path_lengths_i = net_i.path_lengths(link_attribute)

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, float)

Returns:

the internal average path length.

internal_betweenness_1()

Return the internal betweenness sequences for layer 1.

Gives the normalized number of shortest paths only between nodes from layer 1, in which a node \(i\) is contained. \(i\) can be member of any of the two layers. This is equivalent to the inter-regional / inter-group betweenness with respect to layer 1 and layer 1.

Return type:

tuple of two 1D arrays [index]

Returns:

the internal betweenness sequence for layer 1.

internal_betweenness_2()

Return the internal betweenness sequences for layer 2.

Gives the normalized number of shortest paths only between nodes from layer 2, in which a node \(i\) is contained. \(i\) can be member of any of the two layers. This is equivalent to the inter-regional / inter-group betweenness with respect to layer 2 and layer 2.

Return type:

tuple of two 1D arrays [index]

Returns:

the internal betweenness sequence for layer 2.

internal_closeness(link_attribute=None)

Return internal closeness sequence.

Gives the inverse average geodesic distance from a node to all other nodes in the same layer.

However, the included paths will generally contain nodes from both layers. To avoid this, do the following:

net_i = coupled_network.network_i()
closeness_i = net_i.closeness(link_attribute)

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:

tuple of two 1D arrays [index]

Returns:

the internal closeness sequence.

internal_degree()

Return the internal degree sequences.

Gives the number of links from a specific node to other nodes within the same layer.

Return type:

tuple of two 1D arrays [index]

Returns:

the internal degree sequences.

internal_global_clustering()

Return global clustering coefficients for each layer separately.

Internal global clustering coefficients are calculated as mean values from the local clustering sequence of the whole coupled network. This implies that triangles spanning both layers will generally contribute to the internal clustering coefficients.

To avoid this and consider only triangles lying within each layer:

net_1 = coupled_network.network_1()
clustering_1 = net_1.global_clustering()
net_2 = coupled_network.network_2()
clustering_2 = net_2.global_clustering()

Return type:

(float, float)

Returns:

the internal global clustering coefficients.

internal_link_density()

Return the density of links within the two layers.

Return type:

(float, float)

Returns:

the density of links within the two layers.

network_1()

Return network consisting of layer 1 nodes and their internal links.

This can be used to conveniently analyze the layer 1 separately, e.g., for calculation network measures solely for layer 1.

Return type:

GeoNetwork

Returns:

the network consisting of layer 1 nodes and their internal links.

network_2()

Return network consisting of layer 2 nodes and their internal links.

This can be used to conveniently analyze the layer 2 separately, e.g., for calculation network measures solely for layer 2.

Return type:

GeoNetwork

Returns:

the network consisting of layer 2 nodes and their internal links.

nodes_1

(list (int)) - List of node indices for first layer

nodes_2

(list (int)) - List of node indices for second layer

number_cross_layer_links()

Return the number of links between the two layers.

Return int:

the number of links between nodes from different layers.

number_internal_links()

Return the number of links within each layer.

Return type:

(int, int)

Returns:

the number of links within each layer.

path_lengths_1(link_attribute=None)

Return internal path length matrix of first layer.

Contains the paths length between all pairs of nodes within layer 1. However, the paths themselves will generally contain nodes from both layers. To avoid this and only consider paths lying within layer 1, do the following:

net_1 = coupled_network.network_1()
path_lengths_1 = net_1.path_lengths(link_attribute)

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:

2D array [index_1, index_1]

Returns:

the internal path length matrix of first layer.

path_lengths_2(link_attribute=None)

Return internal path length matrix of second layer.

Contains the path lengths between all pairs of nodes within layer 2. However, the paths themselves will generally contain nodes from both layers. To avoid this and only consider paths lying within layer 2, do the following:

net_2 = coupled_network.network_2()
path_lengths_2 = net_2.path_lengths(link_attribute)

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:

2D array [index_2, index_2]

Returns:

the internal path length matrix of second layer.

similarity_measure_1()

Return internal similarity measure matrix of first layer.

Return type:

2D Numpy array [index_1, index_1]

Returns:

the internal similarity measure matrix of first layer.

similarity_measure_2()

Return internal similarity measure matrix of second layer.

Return type:

2D Numpy array [index_2, index_2]

Returns:

the internal similarity measure matrix of first layer.