PyRQA
=====

Table of Contents
-----------------

1.  `General Information <#general-information>`__
2.  `Contribution <#contribution>`__
3.  `Contact <#contact>`__
4.  `Installation <#installation>`__
5.  `OpenCL Setup <#opencl-setup>`__
6.  `Usage <#usage>`__
7.  `Testing <#testing>`__
8.  `Origin <#origin>`__
9.  `Acknowledgements <#acknowledgements>`__
10. `Publications <#publications>`__

General Information
-------------------

PyRQA is a tool to conduct recurrence quantification analysis (RQA) and
to create recurrence plots in a massively parallel manner using the
OpenCL framework. It is designed to efficiently process time series
consisting of hundreds of thousands of data points.

PyRQA supports the computation of the following RQA measures:

-  Recurrence rate (RR)
-  Determinism (DET)
-  Average diagonal line length (L)
-  Longest diagonal line length (L\_max)
-  Divergence (DIV)
-  Entropy diagonal lines (L\_entr)
-  Laminarity (LAM)
-  Trapping time (TT)
-  Longest vertical line length (V\_max)
-  Entropy vertical lines (V\_entr)
-  Average white vertical line length (W)
-  Longest white vertical line length (W\_max)
-  Longest white vertical line length divergence (W\_div)
-  Entropy white vertical lines (W\_entr)

In addition, PyRQA allows to compute the corresponding recurrence plot
and to export it as an image file.

Contribution
------------

The code of the PyRQA package is hosted under
https://gitlab.com/tobiasr/PyRQA.

Contact
-------

Please write an email to pyrqa@gmx.net, if you have any questions
related to the PyRQA package.

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

PyRQA can be installed via the following command.

.. code:: bash

    pip install PyRQA

OpenCL Setup
------------

It may be required to install hardware vendor specific software, e.g.,
device drivers, to run PyRQA on OpenCL devices (such as GPUs and CPUs).
Vendor-specific information is presented below.

-  AMD:

   -  https://www.amd.com/en-us/solutions/professional/hpc/opencl
   -  https://support.amd.com/en-us/kb-articles/Pages/Installation-Instructions-for-amdgpu-Graphics-Stacks.aspx

-  Intel:

   -  https://software.intel.com/en-us/articles/opencl-drivers
   -  https://software.intel.com/en-us/articles/sdk-for-opencl-gsg

-  NVIDIA:

   -  https://developer.nvidia.com/opencl

-  ARM:

   -  https://developer.arm.com/docs/100614/latest/introduction/about-opencl

Usage
-----

RQA computations are conducted as follows.

.. code:: python

    from pyrqa.time_series import SingleTimeSeries
    from pyrqa.settings import Settings
    from pyrqa.neighbourhood import FixedRadius
    from pyrqa.metric import EuclideanMetric
    from pyrqa.computation import RQAComputation
    time_series = SingleTimeSeries([0.1, 0.5, 0.3, 1.7, 0.8, 2.4, 0.6, 1.2, 1.4, 2.1, 0.8],
                                    embedding_dimension=3,
                                    time_delay=2)
    settings = Settings(time_series,
                        neighbourhood=FixedRadius(1.0),
                        similarity_measure=EuclideanMetric,
                        theiler_corrector=1)
    computation = RQAComputation.create(settings,
                                        verbose=True)
    result = computation.run()
    result.min_diagonal_line_length = 1
    result.min_vertical_line_length = 2
    result.min_white_vertical_line_length = 1
    print(result)

Recurrence plot computations can be conducted likewise.

.. code:: python

    from pyrqa.computation import RecurrencePlotComputation
    from pyrqa.image_generator import ImageGenerator
    computation = RecurrencePlotComputation.create(settings)
    result = computation.run()
    ImageGenerator.save_recurrence_plot(result.recurrence_matrix_reverse, 'recurrence_plot.png')

Moreover, it is possible to read time series data that is stored
column-wise from a file.

.. code:: python

    from pyrqa.file_reader import FileReader
    time_series = SingleTimeSeries(FileReader.file_as_float_array('data.csv',
                                                                  delimiter=';',
                                                                  column=0))

The previous examples use the default OpenCL environment. A custom
environment using command line input can also be created

.. code:: python

    from pyrqa.opencl import OpenCL
    opencl = OpenCL(command_line=True)

The OpenCL platform as well as the computing devices can also be
selected using their IDs.

.. code:: python

    opencl = OpenCL(platform_id=0,
                    device_ids=(0,))
    computation = RQAComputation.create(settings,
                                        verbose=True,
                                        opencl=opencl)
    result = computation.run()

Default OpenCL compiler optimisation are deactivated by default to
ensure the comparability of computing results. They can be activated to
leverage additional performance improvements.

.. code:: python

    computation = RQAComputation.create(settings,
                                        variants_kwargs={'optimisation_enabled': True})
    result = computation.run()

Adaptive implementation selection is performed using one of multiple
greedy selection strategies supported. It is conducted based on a
customized pool of implementation variants. These variants may be
enriched with a set of keyword arguments.

.. code:: python

    from pyrqa.variants.rqa.fixed_radius.brute_force.column_materialisation_uncompressed_bit_no_recycling import ColumnMaterialisationUncompressedBitNoRecycling
    from pyrqa.variants.rqa.fixed_radius.brute_force.column_materialisation_uncompressed_bit_recycling import ColumnMaterialisationUncompressedBitRecycling
    from pyrqa.variants.rqa.fixed_radius.brute_force.column_materialisation_uncompressed_byte_no_recycling import ColumnMaterialisationUncompressedByteNoRecycling
    from pyrqa.variants.rqa.fixed_radius.brute_force.column_materialisation_uncompressed_byte_recycling import ColumnMaterialisationUncompressedByteRecycling
    from pyrqa.variants.rqa.fixed_radius.brute_force.column_no_materialisation import ColumnNoMaterialisation
    from pyrqa.selector import EpsilonGreedySelector
    computation = RQAComputation.create(settings,
                                        selector=EpsilonGreedySelector(explore=10),
                                        variants=(ColumnMaterialisationUncompressedBitNoRecycling,
                                                  ColumnMaterialisationUncompressedBitRecycling,
                                                  ColumnMaterialisationUncompressedByteNoRecycling,
                                                  ColumnMaterialisationUncompressedByteRecycling,
                                                  ColumnNoMaterialisation),
                                        variants_kwargs={'optimisations_enabled': True})
    result = computation.run()

Testing
-------

All tests available within the PyRQA package can be executed
cumulatively.

.. code:: bash

    python -m pyrqa.test

Note that it might be required to execute the command as super user.

Origin
------

The PyRQA package was initiated by computer scientists from the
Humboldt-Universität zu Berlin and the GFZ German Research Centre for
Geosciences.

Acknowledgements
----------------

We would like to thank Norbert Marwan from the Potsdam Institute for
Climate Impact Research for his continuous support of the project.
Please visit his website http://recurrence-plot.tk/ for further
information on recurrence analysis.

Publications
------------

Please acknowledge the use of PyRQA by citing the following publication.

::

    Rawald, T., Sips, M., Marwan, N. (2017): PyRQA - Conducting Recurrence Quantification Analysis on Very Long Time Series Efficiently. - Computers and Geosciences, 104, pp. 101-108.

The underlying computational approach of PyRQA is described in detail
within the following thesis, which is openly accessible under
https://edoc.hu-berlin.de/handle/18452/19518.

::

    Rawald, T. (2018): Scalable and Efficient Analysis of Large High-Dimensional Data Sets in the Context of Recurrence Analysis, PhD Thesis, Berlin : Humboldt-Universität zu Berlin, 299 p.

Selected aspects of the computational approach are presented within the
following publications.

::

    Rawald, T., Sips, M., Marwan, N., Dransch, D. (2014): Fast Computation of Recurrences in Long Time Series. - In: Marwan, N., Riley, M., Guiliani, A., Webber, C. (Eds.), Translational Recurrences. From Mathematical Theory to Real-World Applications, (Springer Proceedings in Mathematics and Statistics ; 103), p. 17-29.

    Rawald, T., Sips, M., Marwan, N., Leser, U. (2015): Massively Parallel Analysis of Similarity Matrices on Heterogeneous Hardware. - In: Fischer, P. M., Alonso, G., Arenas, M., Geerts, F. (Eds.), Proceedings of the Workshops of the EDBT/ICDT 2015 Joint Conference (EDBT/ICDT), (CEUR Workshop Proceedings ; 1330), p. 56-62.
