@misc{pessa2021ordpy,title={ordpy: A Python package for data analysis with permutation entropy and ordinal network methods},author={Arthur A. B. Pessa and Haroldo V. Ribeiro},journal={Chaos: An Interdisciplinary Journal of Nonlinear Science},volume={31},number={6},pages={063110},year={2021},doi={10.1063/5.0049901},}
ordpy implements the following data analysis methods:
Released on version 1.0.0 (February 2021):
Permutation entropy for time series [2] and images [3];
Complexity-entropy plane for time series [4], [5] and
images [3];
Multiscale complexity-entropy plane for time series [6] and
images [7];
Tsallis [8] and Rényi [9] generalized complexity-entropy
curves for time series and images;
Ordinal networks for time series [10], [11] and
images [12];
Global node entropy of ordinal networks for
time series [13], [11] and images [12].
Missing ordinal patterns [14] and missing transitions between ordinal
patterns [11] for time series and images.
Released on version 1.1.0 (January 2023):
Weighted permutation entropy for time series [15] and images;
Fisher-Shannon plane for time series [16] and images;
Permutation Jensen-Shannon distance for time series [17] and images;
Four pattern permutation contrasts (up-down balance, persistence,
rotational-asymmetry, and up-down scaling.) for time series [18];
We provide a notebook
illustrating how to use ordpy. This notebook reproduces all figures of our
article [1]. The code below shows simple applications of ordpy.
#Complexity-entropy plane for logistic map and Gaussian noise.importnumpyasnpimportordpyfrommatplotlibimportpylabaspltdeflogistic(a=4,n=100000,x0=0.4):x=np.zeros(n)x[0]=x0foriinrange(n-1):x[i+1]=a*x[i]*(1-x[i])return(x)time_series=[logistic(a)forain[3.05,3.55,4]]time_series+=[np.random.normal(size=100000)]HC=[ordpy.complexity_entropy(series,dx=4)forseriesintime_series]f,ax=plt.subplots(figsize=(8.19,6.3))forHC_,label_inzip(HC,['Period-2 (a=3.05)','Period-8 (a=3.55)','Chaotic (a=4)','Gaussian noise']):ax.scatter(*HC_,label=label_,s=100)ax.set_xlabel('Permutation entropy, $H$')ax.set_ylabel('Statistical complexity, $C$')ax.legend()
#Ordinal networks for logistic map and Gaussian noise.importnumpyasnpimportigraphimportordpyfrommatplotlibimportpylabaspltfromIPython.core.displayimportdisplay,SVGdeflogistic(a=4,n=100000,x0=0.4):x=np.zeros(n)x[0]=x0foriinrange(n-1):x[i+1]=a*x[i]*(1-x[i])return(x)time_series=[logistic(a=4),np.random.normal(size=100000)]vertex_list,edge_list,edge_weight_list=list(),list(),list()forseriesintime_series:v_,e_,w_=ordpy.ordinal_network(series,dx=4)vertex_list+=[v_]edge_list+=[e_]edge_weight_list+=[w_]defcreate_ig_graph(vertex_list,edge_list,edge_weight):G=igraph.Graph(directed=True)forv_invertex_list:G.add_vertex(v_)for[in_,out_],weight_inzip(edge_list,edge_weight):G.add_edge(in_,out_,weight=weight_)returnGgraphs=[]forv_,e_,w_inzip(vertex_list,edge_list,edge_weight_list):graphs+=[create_ig_graph(v_,e_,w_)]defigplot(g):f=igraph.plot(g,layout=g.layout_circle(),bbox=(500,500),margin=(40,40,40,40),vertex_label=[s.replace('|','')forsing.vs['name']],vertex_label_color='#202020',vertex_color='#969696',vertex_size=20,vertex_font_size=6,edge_width=(1+8*np.asarray(g.es['weight'])).tolist(),)returnfforgraph_,label_inzip(graphs,['Chaotic (a=4)','Gaussian noise']):print(label_)display(SVG(igplot(graph_)._repr_svg_()))
Calculates permutation entropy[2] and statistical
complexity[4],[5] using an ordinal
distribution obtained from data.
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
ordpy.ordinal_distribution()).
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Values of normalized permutation entropy and statistical complexity.
Calculates permutation entropy[2] and Fisher
information[16] using an ordinal distribution obtained
from data.
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
ordpy.ordinal_distribution()).
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Values of normalized permutation entropy and Fisher information.
Calculates global node entropy[11],[13] for an
ordinal network obtained from data. (Assumes directed and weighted edges).
Parameters:
data (array, return of ordpy.ordinal_network()) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal network returned by ordpy.ordinal_network()[*].
overlapping (boolean) – If True, data is partitioned into overlapping sliding
windows (default: True). If False, adjacent partitions are
non-overlapping.
connections (str) – The ordinal network is constructed using ‘all’ permutation
successions in a symbolic sequence or only ‘horizontal’ or
‘vertical’ successions. Parameter only valid for image data
(default: ‘all’).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Generates data corresponding to values of normalized permutation entropy and
statistical complexity which delimit the upper boundary in the
complexity-entropy causality plane[20],[‡].
dy (int) – Embedding dimension (vertical axis); must be 1 for time series
(default: 1).
m (int) – The length of the returned array containing values of permutation entropy
and statistical complexity is given by
\([(d_x \times d_y)!-1] \times m\).
Returns:
Values of normalized permutation entropy and statistical complexity
belonging to the upper limiting curve of the complexity-entropy causality
plane.
Generates data corresponding to values of normalized permutation entropy and
statistical complexity which delimit the lower boundary in the
complexity-entropy causality plane[20],[§].
Identifies transitions between ordinal patterns (permutations) not occurring
in data. (These transtitions correspond to directed edges in ordinal
networks[11].) Assumes overlapping windows and unitary embedding
delay. In case dx>1 and dy>1, both ‘horizontal’ and ‘vertical’ connections are
considered (see ordpy.ordinal_network()).
Parameters:
data (array, return of ordpy.ordinal_network()) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or the nodes, edges and edge weights
returned by ordpy.ordinal_network().
dy (int) – Embedding dimension (vertical axis); must be 1 for time series
(default: 1).
return_fraction (boolean) – if True, returns the fraction of missing links among
ordinal patterns relative to the total number of possible
links (transitions) for given values of dx and dy
(default: True). If False, returns the raw number of
missing links.
return_missing (boolean) – if True, returns the missing links in data; if False, it
only returns the fraction/number of these missing links.
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Tuple containing an array and a float indicating missing links and their
relative fraction (or raw number).
Identifies ordinal patterns (permutations) not occurring in data[14].
Parameters:
data (array, return of ordpy.ordinal_distribution()) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or the ordinal patterns and probabilities
returned by ordpy.ordinal_distribution() with return_missing=True.
return_fraction (boolean) – if True, returns the fraction of missing ordinal patterns
relative to the total number of ordinal patterns for given
values of dx and dy (default: True); if False,
returns the raw number of missing patterns.
return_missing (boolean) – if True, returns the missing ordinal patterns in data
(default: True); if False, it only returns the
fraction/number of these missing patterns.
probs (boolean) – If True, assumes data to be the return of
ordpy.ordinal_distribution() with return_missing=True.
If False, data is expected to be a one- or two-dimensional
array (default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Tuple containing an array and a float indicating missing
ordinal patterns and their relative fraction (or raw number).
Applies the Bandt and Pompe[2] symbolization approach to obtain
a probability distribution of ordinal patterns (permutations) from data.
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\).
return_missing (boolean) – If True, it returns ordinal patterns not appearing in the
symbolic sequence obtained from data. If False, these
missing patterns (permutations) are omitted (default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
ordered (boolean) – If True, it also returns ordinal patterns not appearing in the
symbolic sequence obtained from data in ascending ordered.
The return_missing parameter must also be True.
Returns:
Tuple containing two arrays, one with the ordinal patterns and another
with their corresponding probabilities.
Maps a data set into the elements (nodes, edges and edge weights) of its
corresponding ordinal network representation[10],[11],[12].
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\).
normalized (boolean) – If True, edge weights represent transition probabilities between
permutations (default: True). If False, edge weights are
transition counts.
overlapping (boolean) – If True, data is partitioned into overlapping sliding
windows (default: True). If False, adjacent partitions are
non-overlapping.
directed (boolean) – If True, ordinal network edges are directed (default: True). If
False, edges are undirected.
connections (str) – The ordinal network is constructed using ‘all’ permutation
successions in a symbolic sequence or only ‘horizontal’ or
‘vertical’ successions. Parameter only valid for image data
(default: ‘all’).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Tuple containing three arrays corresponding to nodes, edges and edge weights
of an ordinal network.
overlapping (boolean) – If True, data is partitioned into overlapping sliding
windows (default: True). If False, adjacent partitions are
non-overlapping.
tie_precision (None, int) – If not None, data is rounded with tie_precision
number of decimals (default: None).
Returns:
Array containing the sequence of ordinal patterns.
Calculates the Shannon entropy using an ordinal distribution obtained from
data[2],[3].
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
ordpy.ordinal_distribution()).
base (str, int) – Logarithm base in Shannon’s entropy. Either ‘e’ or 2 (default: 2).
normalized (boolean) – If True, permutation entropy is normalized by its maximum value
(default: True). If False, it is not.
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Calculates the permutation Jensen-Shannon distance[17] between
multiple time series (or channels of a multivariate time series) or
multiple matrices (images) using ordinal distributions obtained from data.
Parameters:
data (array) – Array object containing arrays in the format
\([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\).
Generates the nodes, edges and edge weights of a random ordinal network: the
theoretically expected network representation of a random time series[11] or a random two-dimensional array[12].
(Assumes directed edges and unitary embedding delays.)
dy (int) – Embedding dimension (vertical axis); it must be 1 for time series
(default: 1).
overlapping (boolean) – If True, data is partitioned into overlapping sliding
windows (default: True). If False, adjacent partitions are
non-overlapping.
Returns:
Tuple containing three arrays corresponding to nodes, edges and edge weights
of the random ordinal network.
Calculates the Rényi normalized permutation entropy and statistical
complexity[9] using an ordinal distribution obtained from
data.
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
ordpy.ordinal_distribution()).
alpha (float, array) – Rényi’s alpha parameter (default: 1); an array of values is also
accepted for this parameter.
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Value(s) of normalized permutation entropy and statistical complexity in
Rényi’s formalism.
Calculates the normalized Rényi permutation entropy[9] using an
ordinal distribution obtained from data.
Parameters:
data (array) –
Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Value(s) of the normalized Rényi permutation entropy.
Calculates the Tsallis normalized permutation entropy and statistical
complexity[8] using an ordinal distribution obtained from
data.
Parameters:
data (array) –
Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Value(s) of normalized permutation entropy and statistical complexity in
Tsallis’s formalism.
Calculates the normalized Tsallis permutation entropy[8] using
an ordinal distribution obtained from data.
Parameters:
data (array) –
Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\)
or an ordinal probability distribution (such as the ones returned by
probs (boolean) – If True, it assumes data is an ordinal probability distribution.
If False, data is expected to be a one- or two-dimensional array
(default: False).
tie_precision (None, int) – If not None, data is rounded with tie_precision
decimal numbers (default: None).
Returns:
Value(s) of the normalized Tsallis permutation entropy.
Calculates Shannon entropy using a weighted ordinal distribution
obtained from data[15].
Parameters:
data (array) – Array object in the format \([x_{1}, x_{2}, x_{3}, \ldots ,x_{n}]\)
or \([[x_{11}, x_{12}, x_{13}, \ldots, x_{1m}],
\ldots, [x_{n1}, x_{n2}, x_{n3}, \ldots, x_{nm}]]\).