Package: ts2vg
The Pythonts2vgpackage 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].InstallationThe latest releasedts2vgversion is available at thePython Package Index (PyPI)and can be easily installed by running:pipinstallts2vgFor other advanced uses, to buildts2vgfrom source Cython is required.Supported graph typesMain graph typesNatural Visibility Graphs (NVG)[1](ts2vg.NaturalVG)Horizontal Visibility Graphs (HVG)[2](ts2vg.HorizontalVG)Available variationsAdditionally, the following variations of the previous main graph types are available:Weighted Visibility Graphs (via theweightedparameter)Directed Visibility Graphs (via thedirectedparameter)Parametric Visibility Graphs[5](via themin_weightandmax_weightparameters)Limited Penetrable Visibility Graphs (LPVG)[4][6](via thepenetrable_limitparameter)Note that multiple graph variations can be combined and used at the same time.DocumentationUsage and reference documentation forts2vgcan be found atcarlosbergillos.github.io/ts2vg.Basic usageTo build a visibility graph from a time series do:fromts2vgimportNaturalVGts=[1.0,0.5,0.3,0.7,1.0,0.5,0.3,0.8]vg=NaturalVG()vg.build(ts)edges=vg.edgesThe time series passed (ts) can be any one-dimensional iterable, such as a list or anumpy1D 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:fromts2vgimportHorizontalVGts=[1.0,0.5,0.3,0.7,1.0,0.5,0.3,0.8]vg=HorizontalVG()vg.build(ts)edges=vg.edgesIf we are only interested in the degree distribution of the visibility graph
we can passonly_degrees=Trueto thebuildmethod.
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_distributionDirected graphs can be obtained by using thedirectedparameter
and weighted graphs can be obtained by using theweightedparameter: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:ExamplesandAPI Reference.Interoperability with other librariesThe graphs obtained can be easily converted to graph objects
from other common Python graph libraries such asigraph,NetworkXandSNAPfor 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 interfacets2vgcan also be used as a command line program directly from the console:ts2vg./timeseries.txt-oout.edgFor more help and a list of options run:ts2vg--helpContributingts2vgcan be foundon GitHub.
Pull requests and issue reports are welcome.Licensets2vgis licensed under the terms of theMIT License.References[1](1,2)Lucas Lacasa et al., “From time series to complex networks: The visibility graph”, 2008.[2]Lucas Lacasa et al., “Horizontal visibility graphs: exact results for random time series”, 2009.[3]Xin Lan et al., “Fast transformation from time series to visibility graphs”, 2015.[4]T.T Zhou et al., “Limited penetrable visibility graph for establishing complex network from time series”, 2012.[5]I.V. Bezsudnov et al., “From the time series to the complex networks: The parametric natural visibility graph”, 2014[6]Qi Xuan et al., “CLPVG: Circular limited penetrable visibility graph as a new network model for time series”, 2021