A Python implementation of the Recurrence Period Density Entropy (RPDE)

pyRPDE

A full-python implementation of the Recurrence Period Density Entropy metric. It's based on the algorithm described in ^1, and on Max Little's R (and C) implementation in ^2. It relies on Numba to make the return distance computation as fast as possible without having to resort to Cython or C/C++ bindings.

Installation

This package needs python >= 3.6, and relies on Numba, Scipy, and Numpy. It's available on pypi, so a simple:

pip install pyrpde

should do the trick.

Usage

There pretty much is only one function in this package that you should use, rpde(). Here are its arguments:

Arguments:
----------
time_series: np.ndarray
The input time series. Has to be float32, normalized to [-1,1]
dim: int
The dimension of the time series embeddings.
Defaults to 4
tau: int
The "stride" between each of the embedding points in a time series'
embedding vector. Should be adjusted depending on the
sampling rate of your input data.
Defaults to 35.
epsilon: float
The size of the unit ball described in the RPDE algorithm.
Defaults to 0.12.
tmax: int, optional
Maximum return distance (n1-n0), return distances higher than this
are ignored. If set, can greatly improve the speed of the distance
histogram computation (especially if your input time series has a lot of points).
Defaults to None.
parallel: boolean, optional
Use the parallelized Numba implementation. The parallelization overhead
might make this slower in certain situations.
Defaults to True.

Returns
-------
rpde: float
Value of the RPDE
histogram: np.ndarray
1-dimensional array corresponding to the histogram of the return
distances

NOTE: the default values for tau, dim and epsilon are adapted from ^1 and ^2, to work on 22.5Khz PCM audio. You should probably use tau=25 for 16Khz and tau=50 for 48KHz audio.

Here's an example:

from pyrpde import  rpde

# make sure your audio data is in float32. Else, either use librosa or
# normalize it to [-1,1] by dividing it by 2 ** 16 if it's 16bit PCM
entropy, histogram = rpde(data, tau=30, dim=4, epsilon=0.01, tmax=1500)

Citing this package

This package was implemented as part of the experimental protocol used in Riad et Al. You can find this implementation of the RPDE being used in the paper's repository. If you're willing to make use of this package for your own research, you're welcome to cite our paper:

Riad, R, Titeux, H, Lemoine, L., Montillot J. Hamet Bagnou, J. Cao, X., Dupoux, E & Bachoud-Lévi A.-C.
Vocal markers from sustained phonation in Huntington's Disease.
In: INTERSPEECH-2020

Project details

This version 0.1.3 0.1.2 0.1.0