Skip to main content

A tool to conduct recurrence analysis in a massively parallel manner using the OpenCL framework.

Project description

Highlights

  • Perform recurrence analysis on long time series in a time efficient manner using the OpenCL framework.
  • Conduct recurrence quantification analysis (RQA) or cross recurrence quantification analysis (CRQA).
  • Compute recurrence plots (RP) or cross recurrence plots (CRP).
  • Employ the fixed radius or radius corridor neighbourhood condition for determining state similarity.
  • Apply the computing capabilities of GPUs, CPUs or other computing platforms that support OpenCL.
  • Use multiple computing devices of the same or different type in parallel.
  • Leverage machine learning techniques that automatically detect the fastest implementation.
  • Select either the half, single or double floating point precision for conducting the analytical computations.

General Information

PyRQA is a tool to conduct recurrence analysis 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 quantitative 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)

PyRQA additionaly allows to compute the corresponding recurrence plot and to export it as an image.

Installation

PyRQA including all dependencies can be installed via the following command.

pip install PyRQA

Usage

Basic Computations

RQA computations are conducted as follows.

from pyrqa.time_series import TimeSeries
from pyrqa.settings import Settings
from pyrqa.computing_type import ComputingType
from pyrqa.neighbourhood import FixedRadius
from pyrqa.metric import EuclideanMetric
from pyrqa.computation import RQAComputation
data_points = [0.1, 0.5, 1.3, 0.7, 0.8, 1.4, 1.6, 1.2, 0.4, 1.1, 0.8, 0.2, 1.3]
time_series = TimeSeries(data_points,
                         embedding_dimension=2,
                         time_delay=2)
settings = Settings(time_series,
                    computing_type=ComputingType.Classic,
                    neighbourhood=FixedRadius(0.65),
                    similarity_measure=EuclideanMetric,
                    theiler_corrector=1)
computation = RQAComputation.create(settings,
                                    verbose=True)
result = computation.run()
result.min_diagonal_line_length = 2
result.min_vertical_line_length = 2
result.min_white_vertical_line_lelngth = 2
print(result)

The following output is expected.

RQA Result:
===========

Minimum diagonal line length (L_min): 2
Minimum vertical line length (V_min): 2
Minimum white vertical line length (W_min): 2

Recurrence rate (RR): 0.371901
Determinism (DET): 0.411765
Average diagonal line length (L): 2.333333
Longest diagonal line length (L_max): 3
Divergence (DIV): 0.333333
Entropy diagonal lines (L_entr): 0.636514
Laminarity (LAM): 0.400000
Trapping time (TT): 2.571429
Longest vertical line length (V_max): 4
Entropy vertical lines (V_entr): 0.955700
Average white vertical line length (W): 2.538462
Longest white vertical line length (W_max): 6
Longest white vertical line length inverse (W_div): 0.166667
Entropy white vertical lines (W_entr): 0.839796

Ratio determinism / recurrence rate (DET/RR): 1.107190
Ratio laminarity / determinism (LAM/DET): 0.971429

The corresponding recurrence plot is computed likewise.

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

Cross Recurrence Analysis

In addition to classic recurrence analysis (RQA and RP), PyRQA offers the opportunity to conduct cross recurrence analysis (CRQA and CRP). For this purpose, two time series of potentially different length are provided as input. Note that the corresponding computations require to set the same values regarding the embedding dimension and the time delay. Furthermore, the computing_type argument when creating the Settings object has to the changed from ComputingType.Classic to ComputingType.Cross. A CRQA example is given below.

data_points_x = [0.9, 0.1, 0.2, 0.3, 0.5, 1.7, 0.4, 0.8, 1.5]
time_series_x = TimeSeries(data_points_x,
                           embedding_dimension=2,
                           time_delay=1)
data_points_y = [0.3, 1.3, 0.6, 0.2, 1.1, 1.9, 1,3, 0.4, 0.7, 0.9, 1,6]
time_series_y = TimeSeries(data_points_y,
                           embedding_dimension=2,
                           time_delay=1)
time_series = (time_series_x,
               time_series_y)
settings = Settings(time_series,
                    computing_type=ComputingType.Cross,
                    neighbourhood=FixedRadius(0.73),
                    similarity_measure=EuclideanMetric,
                    theiler_corrector=1)
computation = RQAComputation.create(settings,
                                    verbose=True)
result = computation.run()
result.min_diagonal_line_length = 2
result.min_vertical_line_length = 2
result.min_white_vertical_line_lelngth = 2
print(result)

The following output is expected.

CRQA Result:
============

Minimum diagonal line length (L_min): 2
Minimum vertical line length (V_min): 2
Minimum white vertical line length (W_min): 2

Recurrence rate (RR): 0.270833
Determinism (DET): 0.727273
Average diagonal line length (L): 2.285714
Longest diagonal line length (L_max): 4
Divergence (DIV): 0.250000
Entropy diagonal lines (L_entr): 0.410116
Laminarity (LAM): 0.653846
Trapping time (TT): 2.125000
Longest vertical line length (V_max): 3
Entropy vertical lines (V_entr): 0.376770
Average white vertical line length (W): 3.823529
Longest white vertical line length (W_max): 9
Longest white vertical line length inverse (W_div): 0.111111
Entropy white vertical lines (W_entr): 1.731535

Ratio determinism / recurrence rate (DET/RR): 2.685315
Ratio laminarity / determinism (LAM/DET): 0.899038

The corresponding cross recurrence plot is computed likewise.

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

Neighbourhood Condition Selection

PyRQA currently supports the fixed radius as well as the radius corridor neighbourhood condition. While the first refers to a single radius, the latter requires the assignment of an inner and outer radius. The condition selected is passed as neighbourhood argument to the Settings object. The creation of a fixed radius and a radius corridor neighbourhood is presented below.

from pyrqa.neighbourhood import FixedRadius, RadiusCorridor
fixed_radius = FixedRadius(radius=0.43)
radius_corridor = RadiusCorridor(inner_radius=0.32,
                                 outer_radius=0.86)

Custom OpenCL Environment

The previous examples use the default OpenCL environment. A custom environment can also be created via command line input. For this purpose, the command_line argument has to be set to True.

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 identifiers.

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

OpenCL Compiler Optimisations Enablement

OpenCL compiler optimisations are disabled by default to ensure the comparability of computing results. They can be enabled to leverage additional performance improvements by passing the corresponding keyword argument with the value True.

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

Adaptive Implementation Selection

Adaptive implementation selection allows to automatically select well performing implementations regarding RQA and recurrence plot computations. The approach dynamically adapts the selection to the current computational scenario as well as OpenCL devices employed. The selection is performed using one of multiple strategies, each referred to as selector. They rely on a set of customized implementation variants, which may be parameterized using a set of keyword arguments called variants_kwargs. Note that the same variants and selection strategies are used for RQA, CRQA, RP and CRP computations.

from pyrqa.variants.rqa.fixed_radius.column_materialisation_bit_no_recycling import ColumnMaterialisationBitNoRecycling
from pyrqa.variants.rqa.fixed_radius.column_materialisation_bit_recycling import ColumnMaterialisationBitRecycling
from pyrqa.variants.rqa.fixed_radius.column_materialisation_byte_no_recycling import ColumnMaterialisationByteNoRecycling
from pyrqa.variants.rqa.fixed_radius.column_materialisation_byte_recycling import ColumnMaterialisationByteRecycling
from pyrqa.variants.rqa.fixed_radius.column_no_materialisation import ColumnNoMaterialisation
from pyrqa.selector import EpsilonGreedySelector
computation = RQAComputation.create(settings,
                                    selector=EpsilonGreedySelector(explore=10),
                                    variants=(ColumnMaterialisationBitNoRecycling,
                                              ColumnMaterialisationBitRecycling,
                                              ColumnMaterialisationByteNoRecycling,
                                              ColumnMaterialisationByteRecycling,
                                              ColumnNoMaterialisation),
                                    variants_kwargs={'optimisations_enabled': True})
result = computation.run()

Floating Point Precision

It is possible to specify the precision of the time series data points, which determines the precision of the computations conducted by the OpenCL devices. Currently, the following precisions are supported:

  • Half precision (16 bit)
  • Single precision (32 bit)
  • Double precision (64 bit)

Note that not all precisions may be supported by the OpenCL devices employed. Furthermore, the precision selected influences the performance of the computations on a particular device. The precision is selected by specifying the corresponding data type of the time series data points. The following example depicts the usage of double precision floating point values.

import numpy as np
time_series = TimeSeries(data_points,
                         embedding_dimension=2,
                         time_delay=2,
                         dtype=np.float64)

Testing

The basic tests referring to classic and cross RQA as well as recurrence plot computations can be executed cumulatively.

python -m pyrqa.test

The complete set of tests can be executed by adding the option --extended.

python -m pyrqa.test --extended

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

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.

Release Notes

4.0.0

  • Addition of the cross recurrence plot (CRP) and cross recurrence quantification analysis (CRQA) computations.
  • Addition of the radius corridor neighbourhood condition for determining state similarity.
  • Addition of an additional variant regarding recurrence plot computations.
  • Renaming of directories and classes referring to recurrence plot computations.
  • Removal of obsolete source code.
  • Updated documentation.

3.0.0

2.0.1

  • Updated documentation.

2.0.0

  • Major refactoring.
  • Removal of operator and variant implementations that do not refer to OpenCL brute force computing.
  • Time series data may be represented using half, single and double precision floating point values, which is reflected in the computations on the OpenCL devices.
  • Several changes to the public API.

1.0.6

  • Changes to the public API have been made, e.g., to the definition of the settings. This leads to an increase in the major version number (see https://semver.org/).
  • Time series objects either consist of one or multiple series. The former requires to specify a value for the embedding delay as well as the time delay parameter.
  • Regarding the RQA computations, minimum line lengths are now specified on the result object. This allows to compute quantitative results using different lengths without having to inspect the matrix using the same parametrisation multiple times.
  • Modules for selecting well-performing implementations based on greedy selection strategies have been added. By default, the selection pool consists of a single pre-defined implementation.
  • Operators and implementation variants based on multidimensional search trees and grid data structures have been added.
  • The diagonal line based quantitative measures are modified regarding the semantics of the Theiler corrector.
  • The creation of the OpenCL environment now supports device fission.

0.1.0

  • Initial release.

Project details


Download files

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

Files for PyRQA, version 4.0.0
Filename, size & hash File type Python version Upload date
PyRQA-4.0.0.tar.gz (62.2 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page