Skip to main content

Build visibility graphs from time series data.

Project description

pypi pyversions wheel license

Example plot of a visibility graph


The Python ts2vg package provides high-performance algorithm implementations to build visibility graphs from time series data, as first introduced by Lucas Lacasa et al. in 2008 [1].

The visibility graphs and some of their properties (e.g. degree distributions) are computed quickly and efficiently even for time series with millions of observations. An efficient divide-and-conquer algorithm is used to compute the graphs whenever possible [3].

Installation

The latest released ts2vg version is available at the Python Package Index (PyPI) and can be easily installed by running:

pip install ts2vg

For other advanced uses, to build ts2vg from source Cython is required.

Supported graph types

Main graph types

  • Natural Visibility Graphs (NVG) [1] (ts2vg.NaturalVG)

  • Horizontal Visibility Graphs (HVG) [2] (ts2vg.HorizontalVG)

Available variations

Additionally, the following variations of the previous main graph types are available:

  • Weighted Visibility Graphs (via the weighted parameter)

  • Directed Visibility Graphs (via the directed parameter)

  • Parametric Visibility Graphs [5] (via the min_weight and max_weight parameters)

  • Limited Penetrable Visibility Graphs (LPVG) [4] [6] (via the penetrable_limit parameter)

Note that multiple graph variations can be combined and used at the same time.

Documentation

Usage and reference documentation for ts2vg can be found at carlosbergillos.github.io/ts2vg.

Basic usage

To build a visibility graph from a time series do:

from ts2vg import NaturalVG

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

vg = NaturalVG()
vg.build(ts)

edges = vg.edges

The time series passed (ts) can be any one-dimensional iterable, such as a list or a numpy 1D array.

By default, the input observations are assumed to be equally spaced in time. Alternatively, a second 1D iterable (xs) can be provided for unevenly spaced time series.

Horizontal visibility graphs can be obtained in a very similar way:

from ts2vg import HorizontalVG

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

vg = HorizontalVG()
vg.build(ts)

edges = vg.edges

If we are only interested in the degree distribution of the visibility graph we can pass only_degrees=True to the build method. This will be more efficient in time and memory than storing the whole graph.

vg = NaturalVG()
vg.build(ts, only_degrees=True)

ks, ps = vg.degree_distribution

Directed graphs can be obtained by using the directed parameter and weighted graphs can be obtained by using the weighted parameter:

vg1 = NaturalVG(directed="left_to_right")
vg1.build(ts)

vg2 = NaturalVG(weighted="distance")
vg2.build(ts)

vg3 = NaturalVG(directed="left_to_right", weighted="distance")
vg3.build(ts)

vg4 = HorizontalVG(directed="left_to_right", weighted="h_distance")
vg4.build(ts)

For more information and options see: Examples and API Reference.

Interoperability with other libraries

The graphs obtained can be easily converted to graph objects from other common Python graph libraries such as igraph, NetworkX and SNAP for further analysis.

The following methods are provided:

  • as_igraph()

  • as_networkx()

  • as_snap()

For example:

vg = NaturalVG()
vg.build(ts)

g = vg.as_networkx()

Command line interface

ts2vg can also be used as a command line program directly from the console:

ts2vg ./timeseries.txt -o out.edg

For more help and a list of options run:

ts2vg --help

Contributing

ts2vg can be found on GitHub. Pull requests and issue reports are welcome.

License

ts2vg is licensed under the terms of the MIT License.

References

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ts2vg-1.2.3.tar.gz (762.7 kB view hashes)

Uploaded source

Built Distributions

ts2vg-1.2.3-pp37-pypy37_pp73-win_amd64.whl (346.2 kB view hashes)

Uploaded pp37

ts2vg-1.2.3-cp311-cp311-win_amd64.whl (379.3 kB view hashes)

Uploaded cp311

ts2vg-1.2.3-cp311-cp311-win32.whl (322.6 kB view hashes)

Uploaded cp311

ts2vg-1.2.3-cp311-cp311-macosx_11_0_arm64.whl (410.2 kB view hashes)

Uploaded cp311

ts2vg-1.2.3-cp311-cp311-macosx_10_9_x86_64.whl (442.0 kB view hashes)

Uploaded cp311

ts2vg-1.2.3-cp310-cp310-win_amd64.whl (378.3 kB view hashes)

Uploaded cp310

ts2vg-1.2.3-cp310-cp310-win32.whl (323.4 kB view hashes)

Uploaded cp310

ts2vg-1.2.3-cp310-cp310-macosx_11_0_arm64.whl (409.7 kB view hashes)

Uploaded cp310

ts2vg-1.2.3-cp310-cp310-macosx_10_9_x86_64.whl (441.6 kB view hashes)

Uploaded cp310

ts2vg-1.2.3-cp39-cp39-win_amd64.whl (381.4 kB view hashes)

Uploaded cp39

ts2vg-1.2.3-cp39-cp39-win32.whl (326.5 kB view hashes)

Uploaded cp39

ts2vg-1.2.3-cp39-cp39-macosx_11_0_arm64.whl (412.4 kB view hashes)

Uploaded cp39

ts2vg-1.2.3-cp39-cp39-macosx_10_9_x86_64.whl (444.3 kB view hashes)

Uploaded cp39

ts2vg-1.2.3-cp38-cp38-win_amd64.whl (381.2 kB view hashes)

Uploaded cp38

ts2vg-1.2.3-cp38-cp38-win32.whl (326.8 kB view hashes)

Uploaded cp38

ts2vg-1.2.3-cp38-cp38-macosx_11_0_arm64.whl (410.1 kB view hashes)

Uploaded cp38

ts2vg-1.2.3-cp38-cp38-macosx_10_9_x86_64.whl (442.8 kB view hashes)

Uploaded cp38

ts2vg-1.2.3-cp37-cp37m-win_amd64.whl (377.7 kB view hashes)

Uploaded cp37

ts2vg-1.2.3-cp37-cp37m-win32.whl (322.4 kB view hashes)

Uploaded cp37

ts2vg-1.2.3-cp37-cp37m-macosx_10_9_x86_64.whl (443.6 kB view hashes)

Uploaded cp37

ts2vg-1.2.3-cp36-cp36m-win_amd64.whl (431.6 kB view hashes)

Uploaded cp36

ts2vg-1.2.3-cp36-cp36m-win32.whl (353.7 kB view hashes)

Uploaded cp36

ts2vg-1.2.3-cp36-cp36m-macosx_10_9_x86_64.whl (433.0 kB view hashes)

Uploaded cp36

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page