Metadata-Version: 2.1
Name: ts2vg
Version: 1.2.4
Summary: Build visibility graphs from time series data.
Author-email: Carlos Bergillos <c.bergillos.v@gmail.com>
License: MIT License
        
        Copyright (c) 2020 Carlos Bergillos Varela
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE. 
        
Project-URL: Homepage, https://carlosbergillos.github.io/ts2vg
Project-URL: Documentation, https://carlosbergillos.github.io/ts2vg
Project-URL: Source Code, https://github.com/CarlosBergillos/ts2vg
Keywords: graph,network,visibility,time,series
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Cython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=1.24
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"

.. |ts2vg| replace:: **ts2vg**

.. |cover| image:: https://raw.githubusercontent.com/CarlosBergillos/ts2vg/main/docs/source/images/cover_vg.png
   :width: 100 %
   :alt: Example plot of a visibility graph

.. _Examples: https://carlosbergillos.github.io/ts2vg/examples.html

.. _API Reference: https://carlosbergillos.github.io/ts2vg/api/index.html

.. sphinx-start

|ts2vg|: Time series to visibility graphs
===========================================

|pypi| |pyversions| |wheel| |license|

.. |pypi| image:: https://img.shields.io/pypi/v/ts2vg.svg
   :target: https://pypi.python.org/pypi/ts2vg

.. |pyversions| image:: https://img.shields.io/pypi/pyversions/ts2vg.svg
   :target: https://pypi.python.org/pypi/ts2vg

.. |wheel| image:: https://img.shields.io/pypi/wheel/ts2vg.svg
   :target: https://pypi.python.org/pypi/ts2vg

.. |license| image:: https://img.shields.io/pypi/l/ts2vg.svg
   :target: https://pypi.python.org/pypi/ts2vg

|cover|

|

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 [#Lacasa2008]_.

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 [#Lan2015]_.

   
Installation
------------

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

.. code:: sh

   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) [#Lacasa2008]_ (``ts2vg.NaturalVG``)
- Horizontal Visibility Graphs (HVG) [#Lacasa2009]_ (``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 [#Bezsudnov2014]_ (via the ``min_weight`` and ``max_weight`` parameters)
- Limited Penetrable Visibility Graphs (LPVG) [#Zhou2012]_ [#Xuan2021]_ (via the ``penetrable_limit`` parameter)

.. - Dual Perspective Visibility Graph [*planned, not implemented yet*]

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:

.. code:: python

   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:

.. code:: python

   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.

.. code:: python

   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:

.. code:: python

   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:** :ref:`Examples` and :ref:`API Reference`.

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:

.. -  :meth:`~ts2vg.graph.base.VG.as_igraph`
.. -  :meth:`~ts2vg.graph.base.VG.as_networkx`
.. -  :meth:`~ts2vg.graph.base.VG.as_snap`

-  ``as_igraph()``
-  ``as_networkx()``
-  ``as_snap()``

For example:

.. code:: python

   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:

.. code:: sh

   ts2vg ./timeseries.txt -o out.edg 

For more help and a list of options run:

.. code:: sh

   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`_.

.. _NumPy: https://numpy.org/
.. _Cython: https://cython.org/
.. _Python Package Index (PyPI): https://pypi.org/project/ts2vg
.. _igraph: https://igraph.org/python/
.. _NetworkX: https://networkx.github.io/
.. _SNAP: https://snap.stanford.edu/snappy/
.. _on GitHub: https://github.com/CarlosBergillos/ts2vg
.. _MIT License: https://github.com/CarlosBergillos/ts2vg/blob/main/LICENSE
.. _carlosbergillos.github.io/ts2vg: https://carlosbergillos.github.io/ts2vg/


References
----------

.. [#Lacasa2008] Lucas Lacasa et al., "*From time series to complex networks: The visibility graph*", 2008.
.. [#Lacasa2009] Lucas Lacasa et al., "*Horizontal visibility graphs: exact results for random time series*", 2009.
.. [#Lan2015] Xin Lan et al., "*Fast transformation from time series to visibility graphs*", 2015.
.. [#Zhou2012] T.T Zhou et al., "*Limited penetrable visibility graph for establishing complex network from time series*", 2012.
.. [#Bezsudnov2014] I.V. Bezsudnov et al., "*From the time series to the complex networks: The parametric natural visibility graph*", 2014
.. [#Xuan2021] Qi Xuan et al., "*CLPVG: Circular limited penetrable visibility graph as a new network model for time series*", 2021
