{ "info": { "author": "Tobias Rawald", "author_email": "pyrqa@gmx.net", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Developers", "Intended Audience :: Science/Research", "Operating System :: OS Independent", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Topic :: Scientific/Engineering :: Mathematics", "Topic :: Scientific/Engineering :: Physics" ], "description": "PyRQA\n=====\n\nHighlights\n----------\n\n- Perform recurrence analysis on long time series in a time efficient\n manner using the OpenCL framework.\n- Conduct recurrence quantification analysis (*RQA*) or cross\n recurrence quantification analysis (*CRQA*).\n- Compute recurrence plots (*RP*) or cross recurrence plots (*CRP*).\n- Employ the fixed radius or radius corridor neighbourhood condition\n for determining state similarity.\n- Apply the computing capabilities of GPUs, CPUs or other computing\n platforms that support OpenCL.\n- Use multiple computing devices of the same or different type in\n parallel.\n- Leverage machine learning techniques that automatically detect the\n fastest implementation.\n- Select either the half, single or double floating point precision for\n conducting the analytical computations.\n\nTable of Contents\n-----------------\n\n1. `General Information <#general-information>`__\n2. `Recommended Citation <#recommended-citation>`__\n3. `Installation <#installation>`__\n4. `OpenCL Setup <#opencl-setup>`__\n5. `Usage <#usage>`__\n6. `Testing <#testing>`__\n7. `Origin <#origin>`__\n8. `Acknowledgements <#acknowledgements>`__\n9. `Publications <#publications>`__\n10. `Release Notes <#release-notes>`__\n\nGeneral Information\n-------------------\n\nPyRQA is a tool to conduct recurrence analysis in a massively parallel\nmanner using the OpenCL framework. It is designed to efficiently process\ntime series consisting of hundreds of thousands of data points.\n\nPyRQA supports the computation of the following quantitative measures:\n\n- Recurrence rate (*RR*)\n- Determinism (*DET*)\n- Average diagonal line length (*L*)\n- Longest diagonal line length (*L\\_max*)\n- Divergence (*DIV*)\n- Entropy diagonal lines (*L\\_entr*)\n- Laminarity (*LAM*)\n- Trapping time (*TT*)\n- Longest vertical line length (*V\\_max*)\n- Entropy vertical lines (*V\\_entr*)\n- Average white vertical line length (*W*)\n- Longest white vertical line length (*W\\_max*)\n- Longest white vertical line length divergence (*W\\_div*)\n- Entropy white vertical lines (*W\\_entr*)\n\nPyRQA additionaly allows to compute the corresponding recurrence plot\nand to export it as an image.\n\nRecommended Citation\n--------------------\n\nPlease acknowledge the use of PyRQA by citing the following publication.\n\n Rawald, T., Sips, M., Marwan, N. (2017): PyRQA - Conducting\n Recurrence Quantification Analysis on Very Long Time Series\n Efficiently. - Computers and Geosciences, 104, pp. 101-108.\n\nInstallation\n------------\n\nPyRQA including all dependencies can be installed via the following\ncommand.\n\n.. code:: bash\n\n pip install PyRQA\n\nOpenCL Setup\n------------\n\nIt may be required to install additional software, e.g., runtimes or\ndrivers, to execute PyRQA on OpenCL devices such as GPUs and CPUs.\nReferences to vendor specific information is presented below.\n\n*AMD*:\n\n- https://community.amd.com/community/devgurus/opencl\n- https://support.amd.com/en-us/kb-articles/Pages/Installation-Instructions-for-amdgpu-Graphics-Stacks.aspx\n- https://github.com/RadeonOpenCompute/ROCm\n\n*ARM*:\n\n- https://developer.arm.com/docs/100614/0312\n\n*Intel*:\n\n- https://software.intel.com/en-us/articles/opencl-drivers\n- https://software.intel.com/en-us/articles/sdk-for-opencl-gsg\n\n*NVIDIA*:\n\n- https://developer.nvidia.com/opencl\n- https://developer.nvidia.com/cuda-downloads\n\nUsage\n-----\n\nBasic Computations\n~~~~~~~~~~~~~~~~~~\n\nRQA computations are conducted as follows.\n\n.. code:: python\n\n from pyrqa.time_series import TimeSeries\n from pyrqa.settings import Settings\n from pyrqa.computing_type import ComputingType\n from pyrqa.neighbourhood import FixedRadius\n from pyrqa.metric import EuclideanMetric\n from pyrqa.computation import RQAComputation\n 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]\n time_series = TimeSeries(data_points,\n embedding_dimension=2,\n time_delay=2)\n settings = Settings(time_series,\n computing_type=ComputingType.Classic,\n neighbourhood=FixedRadius(0.65),\n similarity_measure=EuclideanMetric,\n theiler_corrector=1)\n computation = RQAComputation.create(settings,\n verbose=True)\n result = computation.run()\n result.min_diagonal_line_length = 2\n result.min_vertical_line_length = 2\n result.min_white_vertical_line_lelngth = 2\n print(result)\n\nThe following output is expected.\n\n::\n\n RQA Result:\n ===========\n\n Minimum diagonal line length (L_min): 2\n Minimum vertical line length (V_min): 2\n Minimum white vertical line length (W_min): 2\n\n Recurrence rate (RR): 0.371901\n Determinism (DET): 0.411765\n Average diagonal line length (L): 2.333333\n Longest diagonal line length (L_max): 3\n Divergence (DIV): 0.333333\n Entropy diagonal lines (L_entr): 0.636514\n Laminarity (LAM): 0.400000\n Trapping time (TT): 2.571429\n Longest vertical line length (V_max): 4\n Entropy vertical lines (V_entr): 0.955700\n Average white vertical line length (W): 2.538462\n Longest white vertical line length (W_max): 6\n Longest white vertical line length inverse (W_div): 0.166667\n Entropy white vertical lines (W_entr): 0.839796\n\n Ratio determinism / recurrence rate (DET/RR): 1.107190\n Ratio laminarity / determinism (LAM/DET): 0.971429\n\nThe corresponding recurrence plot is computed likewise.\n\n.. code:: python\n\n from pyrqa.computation import RPComputation\n from pyrqa.image_generator import ImageGenerator\n computation = RPComputation.create(settings)\n result = computation.run()\n ImageGenerator.save_recurrence_plot(result.recurrence_matrix_reverse,\n 'recurrence_plot.png')\n\nCross Recurrence Analysis\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIn addition to classic recurrence analysis (*RQA* and *RP*), PyRQA\noffers the opportunity to conduct cross recurrence analysis (*CRQA* and\n*CRP*). For this purpose, two time series of potentially different\nlength are provided as input. Note that the corresponding computations\nrequire to set the same values regarding the embedding dimension and the\ntime delay. Furthermore, the ``computing_type`` argument when creating\nthe ``Settings`` object has to the changed from\n``ComputingType.Classic`` to ``ComputingType.Cross``. A *CRQA* example\nis given below.\n\n.. code:: python\n\n data_points_x = [0.9, 0.1, 0.2, 0.3, 0.5, 1.7, 0.4, 0.8, 1.5]\n time_series_x = TimeSeries(data_points_x,\n embedding_dimension=2,\n time_delay=1)\n 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]\n time_series_y = TimeSeries(data_points_y,\n embedding_dimension=2,\n time_delay=1)\n time_series = (time_series_x,\n time_series_y)\n settings = Settings(time_series,\n computing_type=ComputingType.Cross,\n neighbourhood=FixedRadius(0.73),\n similarity_measure=EuclideanMetric,\n theiler_corrector=1)\n computation = RQAComputation.create(settings,\n verbose=True)\n result = computation.run()\n result.min_diagonal_line_length = 2\n result.min_vertical_line_length = 2\n result.min_white_vertical_line_lelngth = 2\n print(result)\n\nThe following output is expected.\n\n::\n\n CRQA Result:\n ============\n\n Minimum diagonal line length (L_min): 2\n Minimum vertical line length (V_min): 2\n Minimum white vertical line length (W_min): 2\n\n Recurrence rate (RR): 0.270833\n Determinism (DET): 0.727273\n Average diagonal line length (L): 2.285714\n Longest diagonal line length (L_max): 4\n Divergence (DIV): 0.250000\n Entropy diagonal lines (L_entr): 0.410116\n Laminarity (LAM): 0.653846\n Trapping time (TT): 2.125000\n Longest vertical line length (V_max): 3\n Entropy vertical lines (V_entr): 0.376770\n Average white vertical line length (W): 3.823529\n Longest white vertical line length (W_max): 9\n Longest white vertical line length inverse (W_div): 0.111111\n Entropy white vertical lines (W_entr): 1.731535\n\n Ratio determinism / recurrence rate (DET/RR): 2.685315\n Ratio laminarity / determinism (LAM/DET): 0.899038\n\nThe corresponding cross recurrence plot is computed likewise.\n\n.. code:: python\n\n from pyrqa.computation import RPComputation\n from pyrqa.image_generator import ImageGenerator\n computation = RPComputation.create(settings)\n result = computation.run()\n ImageGenerator.save_recurrence_plot(result.recurrence_matrix_reverse,\n 'cross_recurrence_plot.png')\n\nNeighbourhood Condition Selection\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPyRQA currently supports the fixed radius as well as the radius corridor\nneighbourhood condition. While the first refers to a single radius, the\nlatter requires the assignment of an inner and outer radius. The\ncondition selected is passed as ``neighbourhood`` argument to the\n``Settings`` object. The creation of a fixed radius and a radius\ncorridor neighbourhood is presented below.\n\n.. code:: python\n\n from pyrqa.neighbourhood import FixedRadius, RadiusCorridor\n fixed_radius = FixedRadius(radius=0.43)\n radius_corridor = RadiusCorridor(inner_radius=0.32, \n outer_radius=0.86) \n\nCustom OpenCL Environment\n~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe previous examples use the default OpenCL environment. A custom\nenvironment can also be created via command line input. For this\npurpose, the ``command_line`` argument has to be set to ``True``.\n\n.. code:: python\n\n from pyrqa.opencl import OpenCL\n opencl = OpenCL(command_line=True)\n\nThe OpenCL platform as well as the computing devices can also be\nselected using their identifiers.\n\n.. code:: python\n\n opencl = OpenCL(platform_id=0,\n device_ids=(0,))\n computation = RQAComputation.create(settings,\n verbose=True,\n opencl=opencl)\n result = computation.run()\n\nOpenCL Compiler Optimisations Enablement\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nOpenCL compiler optimisations are disabled by default to ensure the\ncomparability of computing results. They can be enabled to leverage\nadditional performance improvements by passing the corresponding keyword\nargument with the value ``True``.\n\n.. code:: python\n\n computation = RQAComputation.create(settings,\n variants_kwargs={'optimisations_enabled': True})\n result = computation.run()\n\nAdaptive Implementation Selection\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAdaptive implementation selection allows to automatically select well\nperforming implementations regarding RQA and recurrence plot\ncomputations. The approach dynamically adapts the selection to the\ncurrent computational scenario as well as OpenCL devices employed. The\nselection is performed using one of multiple strategies, each referred\nto as ``selector``. They rely on a set of customized implementation\n``variants``, which may be parameterized using a set of keyword\narguments called ``variants_kwargs``. Note that the same ``variants``\nand selection strategies are used for *RQA*, *CRQA*, *RP* and *CRP*\ncomputations.\n\n.. code:: python\n\n from pyrqa.variants.rqa.fixed_radius.column_materialisation_bit_no_recycling import ColumnMaterialisationBitNoRecycling\n from pyrqa.variants.rqa.fixed_radius.column_materialisation_bit_recycling import ColumnMaterialisationBitRecycling\n from pyrqa.variants.rqa.fixed_radius.column_materialisation_byte_no_recycling import ColumnMaterialisationByteNoRecycling\n from pyrqa.variants.rqa.fixed_radius.column_materialisation_byte_recycling import ColumnMaterialisationByteRecycling\n from pyrqa.variants.rqa.fixed_radius.column_no_materialisation import ColumnNoMaterialisation\n from pyrqa.selector import EpsilonGreedySelector\n computation = RQAComputation.create(settings,\n selector=EpsilonGreedySelector(explore=10),\n variants=(ColumnMaterialisationBitNoRecycling,\n ColumnMaterialisationBitRecycling,\n ColumnMaterialisationByteNoRecycling,\n ColumnMaterialisationByteRecycling,\n ColumnNoMaterialisation),\n variants_kwargs={'optimisations_enabled': True})\n result = computation.run()\n\nFloating Point Precision\n~~~~~~~~~~~~~~~~~~~~~~~~\n\nIt is possible to specify the precision of the time series data points,\nwhich determines the precision of the computations conducted by the\nOpenCL devices. Currently, the following precisions are supported:\n\n- Half precision (16 bit)\n- Single precision (32 bit)\n- Double precision (64 bit)\n\nNote that not all precisions may be supported by the OpenCL devices\nemployed. Furthermore, the precision selected influences the performance\nof the computations on a particular device. The precision is selected by\nspecifying the corresponding data type of the time series data points.\nThe following example depicts the usage of double precision floating\npoint values.\n\n.. code:: python\n\n import numpy as np\n time_series = TimeSeries(data_points,\n embedding_dimension=2,\n time_delay=2,\n dtype=np.float64)\n\nTesting\n-------\n\nThe basic tests referring to classic and cross RQA as well as recurrence\nplot computations can be executed cumulatively.\n\n.. code:: bash\n\n python -m pyrqa.test\n\nThe complete set of tests can be executed by adding the option\n``--extended``.\n\n.. code:: bash\n\n python -m pyrqa.test --extended\n\nOrigin\n------\n\nThe PyRQA package was initiated by computer scientists from the\nHumboldt-Universit\u00e4t zu Berlin and the GFZ German Research Centre for\nGeosciences.\n\nAcknowledgements\n----------------\n\nWe would like to thank Norbert Marwan from the Potsdam Institute for\nClimate Impact Research for his continuous support of the project.\nPlease visit his website http://recurrence-plot.tk/ for further\ninformation on recurrence analysis.\n\nPublications\n------------\n\nThe underlying computational approach of PyRQA is described in detail\nwithin the following thesis, which is openly accessible under\nhttps://edoc.hu-berlin.de/handle/18452/19518.\n\n Rawald, T. (2018): Scalable and Efficient Analysis of Large\n High-Dimensional Data Sets in the Context of Recurrence Analysis,\n PhD Thesis, Berlin : Humboldt-Universit\u00e4t zu Berlin, 299 p.\n\nSelected aspects of the computational approach are presented within the\nfollowing publications.\n\n Rawald, T., Sips, M., Marwan, N., Dransch, D. (2014): Fast\n Computation of Recurrences in Long Time Series. - In: Marwan, N.,\n Riley, M., Guiliani, A., Webber, C. (Eds.), Translational\n Recurrences. From Mathematical Theory to Real-World Applications,\n (Springer Proceedings in Mathematics and Statistics ; 103), p.\n 17-29.\n\n Rawald, T., Sips, M., Marwan, N., Leser, U. (2015): Massively\n Parallel Analysis of Similarity Matrices on Heterogeneous Hardware.\n - In: Fischer, P. M., Alonso, G., Arenas, M., Geerts, F. (Eds.),\n Proceedings of the Workshops of the EDBT/ICDT 2015 Joint Conference\n (EDBT/ICDT), (CEUR Workshop Proceedings ; 1330), p. 56-62.\n\nRelease Notes\n-------------\n\n4.0.0\n~~~~~\n\n- Addition of the cross recurrence plot (*CRP*) and cross recurrence\n quantification analysis (*CRQA*) computations.\n- Addition of the radius corridor neighbourhood condition for\n determining state similarity.\n- Addition of an additional variant regarding recurrence plot\n computations.\n- Renaming of directories and classes referring to recurrence plot\n computations.\n- Removal of obsolete source code.\n- Updated documentation.\n\n3.0.0\n~~~~~\n\n- Source code cleanup.\n- Renaming of the implementation variants regarding RQA and recurrence\n plot processing.\n- Removal of the module ``file_reader.py``. Please refer for example to\n ``numpy.genfromtxt`` to read data from files (see\n https://docs.scipy.org/doc/numpy/reference/generated/numpy.genfromtxt.html).\n- Updated documentation.\n\n2.0.1\n~~~~~\n\n- Updated documentation.\n\n2.0.0\n~~~~~\n\n- Major refactoring.\n- Removal of operator and variant implementations that do not refer to\n OpenCL brute force computing.\n- Time series data may be represented using half, single and double\n precision floating point values, which is reflected in the\n computations on the OpenCL devices.\n- Several changes to the public API.\n\n1.0.6\n~~~~~\n\n- Changes to the public API have been made, e.g., to the definition of\n the settings. This leads to an increase in the major version number\n (see https://semver.org/).\n- Time series objects either consist of one or multiple series. The\n former requires to specify a value for the embedding delay as well as\n the time delay parameter.\n- Regarding the RQA computations, minimum line lengths are now\n specified on the result object. This allows to compute quantitative\n results using different lengths without having to inspect the matrix\n using the same parametrisation multiple times.\n- Modules for selecting well-performing implementations based on greedy\n selection strategies have been added. By default, the selection pool\n consists of a single pre-defined implementation.\n- Operators and implementation variants based on multidimensional\n search trees and grid data structures have been added.\n- The diagonal line based quantitative measures are modified regarding\n the semantics of the Theiler corrector.\n- The creation of the OpenCL environment now supports device fission.\n\n0.1.0\n~~~~~\n\n- Initial release.", "description_content_type": "", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "time series analysis,recurrence quantification analysis,RQA,cross recurrence quantification analysis,CRQA,recurrence plot,RP,cross recurrence plot,CRP", "license": "", "maintainer": "", "maintainer_email": "", "name": "PyRQA", "package_url": "https://pypi.org/project/PyRQA/", "platform": "", "project_url": "https://pypi.org/project/PyRQA/", "project_urls": null, "release_url": "https://pypi.org/project/PyRQA/4.0.0/", "requires_dist": null, "requires_python": "", "summary": "A tool to conduct recurrence analysis in a massively parallel manner using the OpenCL framework.", "version": "4.0.0" }, "last_serial": 5590665, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "b37236bea985352cf256f326ca3f9f7a", "sha256": "957894bb11598bd34451014e919a939437554f38ee4469d58e4f995173f8942f" }, "downloads": -1, "filename": "PyRQA-0.1.0.tar.gz", "has_sig": false, "md5_digest": "b37236bea985352cf256f326ca3f9f7a", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 43864, "upload_time": "2015-07-29T12:56:19", "url": "https://files.pythonhosted.org/packages/31/7d/dee51c852ad8a4d23c8a1184df779499863b80978349fef574c024a19f91/PyRQA-0.1.0.tar.gz" } ], "1.0.6": [ { "comment_text": "", "digests": { "md5": "0b8ed5c63eca77f0bbac24267a2143fc", "sha256": "51ef476c904a832f533a44cd2f6d5d547a830626ce0ce6f675684dd650f68dc9" }, "downloads": -1, "filename": "PyRQA-1.0.6.tar.gz", "has_sig": false, "md5_digest": "0b8ed5c63eca77f0bbac24267a2143fc", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 68578, "upload_time": "2018-09-14T23:19:35", "url": "https://files.pythonhosted.org/packages/44/da/1d21750c6d9750655167d662702a37155f9838f467747d5e26e3c2e148f6/PyRQA-1.0.6.tar.gz" } ], "2.0.0": [ { "comment_text": "", "digests": { "md5": "53ee829492755c8cc12b06b1ebd7b981", "sha256": "0664b2a16e91db95f32d81d3c195ceda6d892912ca5bb51ece594a2ca982e337" }, "downloads": -1, "filename": "PyRQA-2.0.0.tar.gz", "has_sig": false, "md5_digest": "53ee829492755c8cc12b06b1ebd7b981", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 57227, "upload_time": "2018-12-19T21:19:53", "url": "https://files.pythonhosted.org/packages/8c/af/83d38daab097d0deb3b9c254090ddd98ed3f1e70d00a405c765111890662/PyRQA-2.0.0.tar.gz" } ], "2.0.1": [ { "comment_text": "", "digests": { "md5": "d53dc2a14473aa78e3a868f7d8a6795e", "sha256": "8976cb8fe68617f7c9bf5fe7aba0f162b46c44770f5797ea6d3f4e0311ff0477" }, "downloads": -1, "filename": "PyRQA-2.0.1.tar.gz", "has_sig": false, "md5_digest": "d53dc2a14473aa78e3a868f7d8a6795e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 57803, "upload_time": "2019-02-02T15:21:22", "url": "https://files.pythonhosted.org/packages/2b/73/1fcc91ae4ca0d6db828a83b0f6320ab50ae204c425bb2e0582c1a5acc979/PyRQA-2.0.1.tar.gz" } ], "3.0.0": [ { "comment_text": "", "digests": { "md5": "f36da0bdc0c02cbacad1a713de76bf61", "sha256": "b59a6fd6b5cfe64c2fc4b8afe860c84fe9a3542414a59e92229fab60c1c39874" }, "downloads": -1, "filename": "PyRQA-3.0.0.tar.gz", "has_sig": false, "md5_digest": "f36da0bdc0c02cbacad1a713de76bf61", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 55957, "upload_time": "2019-04-06T20:20:54", "url": "https://files.pythonhosted.org/packages/9b/0c/45f68282cd84b886a6bf8767523c43f03f34d64eb89a67bef89ca15eeec2/PyRQA-3.0.0.tar.gz" } ], "4.0.0": [ { "comment_text": "", "digests": { "md5": "1cd31dfa8736c708e77a10b9b8d4fd6f", "sha256": "1de307d314ee3ba883cd37f289f533d75e182546632922c36df5d82b89514e5f" }, "downloads": -1, "filename": "PyRQA-4.0.0.tar.gz", "has_sig": false, "md5_digest": "1cd31dfa8736c708e77a10b9b8d4fd6f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 62199, "upload_time": "2019-07-26T20:29:16", "url": "https://files.pythonhosted.org/packages/43/90/1f458ba9cd67b9226e89f8a3d87eb4af8ed7001a109b270b813781e3a3e9/PyRQA-4.0.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "1cd31dfa8736c708e77a10b9b8d4fd6f", "sha256": "1de307d314ee3ba883cd37f289f533d75e182546632922c36df5d82b89514e5f" }, "downloads": -1, "filename": "PyRQA-4.0.0.tar.gz", "has_sig": false, "md5_digest": "1cd31dfa8736c708e77a10b9b8d4fd6f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 62199, "upload_time": "2019-07-26T20:29:16", "url": "https://files.pythonhosted.org/packages/43/90/1f458ba9cd67b9226e89f8a3d87eb4af8ed7001a109b270b813781e3a3e9/PyRQA-4.0.0.tar.gz" } ] }