peccary#

class peccary.core.peccary(data, n=5, attr=None, dt=None, ptcl=None)[source]#

Bases: object

The peccary class is the core of the PECCARY method, which is based on work by Bandt & Pompe (2002), Rosso et al. (2007), and Weck et al. (2015). The class extracts ordinal patterns of a specified sampling size \(n\) (default \(n=5\)) and calculates a probability distribution of all possible ordinal pattern permutations. After the pattern distribution has been created, the values for Permutation Entropy and Jensen-Shanon Statistical Complexity can be calculated.

The peccary class can be initialized with either a 1-D array or a Timeseries instance. In the case of a timeseries object, the desired attribute to use for analysis should be indicated with the attr parameter. If there are multiple particles for the data, the desired particle should be indexed with the ptcl parameter. Although the dt parameter is optional, it is recommended to specifiy it if data is a standard 1-D array, since it is used in the convenience methods of tPat and ell_from_tPat.

See Getting started for a demostration of how to initialize peccary with a Timeseries instance.

References

[1] Bandt, C., & Pompe, B. 2002, Phys Rev Lett, 88 (American Physical Society), 174102

[2] Rosso, O. A., Larrondo, H. A., Martin, M. T., Plastino, A., & Fuentes, M. A. 2007, Phys Rev Lett, 99 (American Physical Society), 154102

[3] Weck, P. J., Schaffner, D. A., Brown, M. R., & Wicks, R. T. 2015, Phys Rev E, 91 (American Physical Society), 023101

Methods Summary

`calcC_fromSSe`(S, Se)	Calculate normalized Jensen-Shannon statistical complexity from pre-calculated Shannon permutation entropy and disequilibrium values
`calcH`([sampInt])	Calculate normalized Permutation Entropy
`calcHC`([sampInt])	Calculate normalized Jensen-Shannon statistical complexity and normalized permutation entropy
`calcHCcurves`([min_sampInt, max_sampInt, ...])	Returns Permutation Entropy and Statistical Complexity values for multiple sampling interval values, i.e., \(H(\ell)\) and \(C(\ell)\)
`calcS`([sampInt])	Calculate Shannon permutation entropy (S) and disqeulibrium (S_e)
`calcS_fromPatternCount`(count, Ptot)	Calculate Shannon permutation entropy and disequilibrium from pattern count and total number of permutations
`constructPatternCount`([sampInt])	Count occurance of patterns and total number of permutations
`ell_from_tPat`(tPat)	Calculates the sampling interval in PECCARY routine based on the pattern time and sampling size
`getPatternsCounts`([sampInt])	Return patterns, respective counts, and total number of permutations
`getPtot`([sampInt])	Get total number of permutations based on sampling interval
`tPat`([sampInt])	Calculates pattern time of in PECCARY routine, based on sampling size and sampling interval

Methods Documentation

calcC_fromSSe(S, Se)[source]#

Calculate normalized Jensen-Shannon statistical complexity from pre-calculated Shannon permutation entropy and disequilibrium values

Parameters:

Sfloat: Shannon permutation entropy
Sefloat: Disequilibrium

Returns:

float: Normalized Jensen-Shannon statistical complexity

calcH(sampInt=1)[source]#

Calculate normalized Permutation Entropy

Parameters:

sampIntint, optional: Sampling interval, by default 1

Returns:

Spfloat: Normalized Shannon permutation entropy
Sefloat: Normalized Shannon + Uniform permutation entropy

calcHC(sampInt=1)[source]#

Calculate normalized Jensen-Shannon statistical complexity and normalized permutation entropy

Parameters:

sampIntint, optional: Sampling interval, by default 1

Returns:

Hfloat: Normalized Shannon permutation entropy
Cfloat: Normalized Jensen-Shannon statistical complexity

calcHCcurves(min_sampInt=1, max_sampInt=100, step_sampInt=1, sampIntArray=None)[source]#

Returns Permutation Entropy and Statistical Complexity values for multiple sampling interval values, i.e., \(H(\ell)\) and \(C(\ell)\)

Parameters:

dataarray: Timeseries data for PECCARY
nint, optional: Sampling size, by default 5
min_sampIntint, optional: Smallest sampling interval to loop through, by default 1
max_sampIntint, optional: Largest sampling interval to loop through, by default 100
step_sampIntint, optional: How many sampling interval values to skip over
sampIntArray: ndarray or list: Custom array of sampling intervals, supersedes min_sampInt, max_sampInt, and step_sampInt, by default None

Returns:

Hvalsndarray: Normalized Shannon Perumation Entropy as function of sampling interval, \(H(\ell)\)
Cvalsndarray: Normalized Jensen-Shannon complexity as function of sampling interval, \(C(\ell)\)
sampIntsndarray: Sampling interval (\(\ell\)) values

calcS(sampInt=1)[source]#

Calculate Shannon permutation entropy (S) and disqeulibrium (S_e)

Parameters:

sampIntint, optional: Sampling interval, by default 1

Returns:

Spfloat: Shannon permutation entropy
Sefloat: Disequilibrium

calcS_fromPatternCount(count, Ptot)[source]#

Calculate Shannon permutation entropy and disequilibrium from pattern count and total number of permutations

Parameters:

countndarray: Count occurance result (e.g., from constructPatternCount)
Ptotint: Total number of permutations (e.g., from constructPatternCount)

Returns:

Spfloat: Normalized Shannon permutation entropy
Sefloat: Normalized Shannon + Uniform permutation entropy

constructPatternCount(sampInt=1)[source]#

Count occurance of patterns and total number of permutations

Parameters:

sampIntint, optional: Sampling interval, by default 1

Returns:

countndarray: A Count occurance of patterns
Ptotint: Total number of permutations

ell_from_tPat(tPat)[source]#

Calculates the sampling interval in PECCARY routine based on the pattern time and sampling size

Parameters:

dtfloat: Timestep interval
tPatfloat or ndarray: Pattern time

Returns:

float or ndarray: Sampling interval(s) corresponding to inputted pattern time(s)

getPatternsCounts(sampInt=1)[source]#

Return patterns, respective counts, and total number of permutations

Parameters:

sampIntint, optional: Sampling interval, by default 1

Returns:

patternsndarray: Patterns
countndarray: Count occurances of patterns
Ptotint: Total number of permutations

getPtot(sampInt=1)[source]#

Get total number of permutations based on sampling interval

Parameters:

sampIntint, optional: Sampling interval, by default 1

Returns:

int: Total number of permutations

tPat(sampInt=1)[source]#

Calculates pattern time of in PECCARY routine, based on sampling size and sampling interval

Parameters:

dtfloat: Timestep interval
sampIntint or ndarray, optional: Sampling interval, by default 1

Returns:

float or ndarray: Pattern time(s) corresponding to inputted sampling interval(s)