ts2vg.NaturalVG#

class ts2vg.NaturalVG(*, directed=None, weighted=None, min_weight=None, max_weight=None, penetrable_limit=0)[source]#

Natural Visibility Graph.

Used to transform a time series to a Natural Visibility Graph.

Parameters:

directed (str, None) – If None make an undirected graph, otherwise, a directed graph by using one of the following values: 'left_to_right', 'top_to_bottom'. See Directed graphs for more information. Default None.
weighted (str, None) – If None make an unweighted graph, otherwise, a weighted graph by using one of the following values: 'distance', 'sq_distance', 'v_distance', 'abs_v_distance', 'h_distance', 'abs_h_distance', 'slope', 'abs_slope', 'angle', 'abs_angle', 'num_penetrations'. See Weighted graphs for more information. Default None.
min_weight (float, None) – If provided, only edges with a weight higher than min_weight (non inclusive) will be included in the final graph. The graph must be weighted and the values used for weight will depend on the weighted parameter. This acts as a generalization of parametric visibility graphs. Default None.
max_weight (float, None) – If provided, only edges with a weight lower than max_weight (non inclusive) will be included in the final graph. The graph must be weighted and the values used for weight will depend on the weighted parameter. This acts as a generalization of parametric visibility graphs. Default None.
penetrable_limit (int) – If larger than 0, make a limited penetrable visibility graph (LPVG). The value for penetrable_limit indicates the maximum number of data points that are allowed to obstruct the visibility between two nodes that can still be connected in the final graph. Default 0 (regular non-penetrable visibility graph).

References

Lucas Lacasa et al., “From time series to complex networks: The visibility graph”, 2008.
Xin Lan et al., “Fast transformation from time series to visibility graphs”, 2015.

Examples

from ts2vg import NaturalVG

ts = [1.0, 0.5, 0.3, 0.7, 1.0, 0.5, 0.3, 0.8]

g = NaturalVG()
g.build(ts)

edges = g.edges

Attributes

`degree_counts`	Degree counts of the graph.
`degree_distribution`	Degree distribution of the graph.
`degrees`	Degree sequence of the graph.
`degrees_in`
`degrees_out`
`edges`	List of edges (links) of the graph.
`edges_unweighted`	List of edges (links) of the graph without including the weights.
`is_directed`	`True` if the graph is directed, `False` otherwise.
`is_weighted`	`True` if the graph is weighted, `False` otherwise.
`n_edges`	Number of edges (links) in the graph.
`n_vertices`	Number of vertices (nodes) in the graph.
`weights`	Weights of the edges of the graph.
`ts`	1D array of the time series.
`xs`	1D array of the X coordinates of the time series.
`directed`	str indicating the strategy used for the edge directions (same as passed to the constructor).
`weighted`	str indicating the strategy used for the edge weights (same as passed to the constructor).

Methods

`adjacency_matrix`([triangle, use_weights, ...])	Adjacency matrix of the graph.
`as_igraph`()	Return an igraph graph object corresponding to this graph.
`as_networkx`()	Return a NetworkX graph object corresponding to this graph.
`as_snap`()	Return a SNAP graph object corresponding to this graph.
`build`(ts[, xs, only_degrees])	Compute and build the visibility graph for the given time series.
`node_positions`()	Dictionary with nodes as keys and positions (x, y) as values.
`summary`([prints, title])	Prints (or returns) a simple text summary describing the visibility graph.

Attribute details

degree_counts[source]#

Degree counts of the graph.

Two lists ks, cs are returned. cs[i] is the number of nodes in the graph that have degree ks[i].

The count of any other degree value not listed in ks is 0.

degree_distribution[source]#

Degree distribution of the graph.

Two lists ks, ps are returned. ps[i] is the empirical probability that a node in the graph has degree ks[i].

The probability for any other degree value not listed in ks is 0.

degrees[source]#

Degree sequence of the graph.

Return a list of degree values for each node in the graph, in the same order as the input time series.

degrees_in[source]#

degrees_out[source]#

edges[source]#

List of edges (links) of the graph.

If the graph is unweighted, a list of tuple pairs (source_node, target_node). If the graph is weighted, an iterable of tuple triplets (source_node, target_node, weight).

Nodes are identified using an integer from 0 to n-1 assigned sequentially in the same order as the input time series.

edges_unweighted[source]#

List of edges (links) of the graph without including the weights.

A list of tuple pairs (source_node, target_node). For unweighted graphs this is the same as edges.

Nodes are identified using an integer from 0 to n-1 assigned sequentially in the same order as the input time series.

is_directed[source]#: True if the graph is directed, False otherwise.

is_weighted[source]#: True if the graph is weighted, False otherwise.

n_edges[source]#: Number of edges (links) in the graph.

n_vertices[source]#: Number of vertices (nodes) in the graph.

weights[source]#

Weights of the edges of the graph.

Return a 1D array containing the weights of the edges of the graph (listed in the same order as in edges). None if the graph is unweighted.

ts#: 1D array of the time series. None if the graph has not been built yet.

xs#: 1D array of the X coordinates of the time series. None if the graph has not been built yet.

directed#: str indicating the strategy used for the edge directions (same as passed to the constructor). None if the graph is undirected.

weighted#: str indicating the strategy used for the edge weights (same as passed to the constructor). None if the graph is unweighted.

Method details

adjacency_matrix(triangle='both', use_weights=False, no_weight_value=nan)[source]#

Adjacency matrix of the graph.

Parameters:

triangle (str) –
One of 'lower' (uses the lower triangle of the matrix), 'upper' (uses the upper triangle of the matrix) or 'both' (uses both). Only applicable for undirected graphs.

Default 'both'.
use_weights (bool) –
If True, return an adjacency matrix containing the edge weights, otherwise return a binary adjacency matrix. Only applicable for weighted graphs.

Default False.
no_weight_value (float) –
The default value used in the matrix for the cases where the nodes are not connected. Only applicable for weighted graphs and when using use_weights=True.

Default np.nan.

Returns:

2D array – Adjacency matrix of the graph.

as_igraph()[source]#

Return an igraph graph object corresponding to this graph.

The igraph package is required.

as_networkx()[source]#

Return a NetworkX graph object corresponding to this graph.

The networkx package is required.

as_snap()[source]#

Return a SNAP graph object corresponding to this graph.

The snap package is required.

build(ts, xs=None, only_degrees=False)[source]#

Compute and build the visibility graph for the given time series.

Parameters:

ts (1D array like) – Input time series.
xs (1D array like, optional) –
X coordinates for the time series. Length of xs must match length of ts.

If not provided, [0, 1, 2...] will be used.
only_degrees (bool) – If True only compute the graph degrees, otherwise compute the whole graph. Default False.

Returns:

self

node_positions()[source]#: Dictionary with nodes as keys and positions (x, y) as values.

summary(prints=True, title='Visibility Graph')[source]#

Prints (or returns) a simple text summary describing the visibility graph.

Parameters:

prints (bool) – If True prints the summary, otherwise returns the summary as a string. Default True.
title (str) – Title for the table. Default is ‘Visibility Graph’.

Returns:

str – A string containing the short summary (only if prints=False).