Cross Entropies

Functions for estimating the cross-entropy between two univariate time series.

The following functions also form the cross-entropy method used by Multiscale Cross-Entropy functions.

Signals for mutliscale cross-entropy functions

For cross-entropy and multiscale cross-entropy functions, the two time series signals are passed as a two-column or two-row matrix. At present, it is not possible to pass signals of different lengths separately.

These functions are directly available when EntropyHub is imported:

julia> using EntropyHub
julia> names(EntropyHub)
 :ApEn
 :AttnEn
 :BubbEn
   ⋮
 :hXMSEn
 :rMSEn
 :rXMSEn
EntropyHub._XApEn.XApEnFunction
XAp, Phi = XApEn(Sig)

Returns the cross-approximate entropy estimates (XAp) and the average number of matched vectors (Phi) for m = [0,1,2], estimated for the data sequences contained in 'Sig' using the default parameters: embedding dimension = 2, time delay = 1, radius distance threshold= 0.2*SD(Sig), logarithm = natural

NOTE: XApEn is direction-dependent. Thus, the first column of Sig is used as the template data sequence, and the second column is the matching sequence.``

XAp, Phi = XApEn(Sig::AbstractArray{T,2} where T<:Real; m::Int=2, tau::Int=1, r::Real=0.2*std(Sig,corrected=false), Logx::Real=exp(1))

Returns the cross-approximate entropy estimates (XAp) between the data sequences contained in 'Sig' using the specified 'keyword' arguments:

Arguments:

m - Embedding Dimension, a positive integer [default: 2]

tau - Time Delay, a positive integer [default: 1]

r - Radius Distance Threshold, a positive scalar [default: 0.2*SD(Sig)]

Logx - Logarithm base, a positive scalar [default: natural]

See also XSampEn, XFuzzEn, XMSEn, ApEn, SampEn, MSEn

References:

[1] Steven Pincus and Burton H. Singer,
    "Randomness and degrees of irregularity." 
    Proceedings of the National Academy of Sciences 
    93.5 (1996): 2083-2088.

[2] Steven Pincus,
    "Assessing serial irregularity and its implications for health."
    Annals of the New York Academy of Sciences 
    954.1 (2001): 245-267.
EntropyHub._XSampEn.XSampEnFunction
XSamp, A, B = XSampEn(Sig)

Returns the cross-sample entropy estimates (XSamp) and the number of matched vectors (m:B, m+1:A) for m = [0,1,2] estimated for the two univariate data sequences contained in 'Sig' using the default parameters: embedding dimension = 2, time delay = 1, radius distance threshold= 0.2*SD(Sig), logarithm = natural

XSamp, A, B = XSampEn(Sig::AbstractArray{T,2} where T<:Real; m::Int=2, tau::Int=1, r::Real=0.2*std(Sig,corrected=false), Logx::Real=exp(1))

Returns the cross-sample entropy estimates (XSamp) for dimensions [0,1,...,m] estimated between the data sequences in Sig using the specified 'keyword' arguments:

Arguments:

m - Embedding Dimension, a positive integer [default: 2]

tau - Time Delay, a positive integer [default: 1]

r - Radius Distance Threshold, a positive scalar [default: 0.2*SD(Sig)]

Logx - Logarithm base, a positive scalar [default: natural]

See also XFuzzEn, XApEn, SampEn, SampEn2D, XMSEn, ApEn

References:

[1] Joshua S Richman and J. Randall Moorman. 
    "Physiological time-series analysis using approximate entropy
    and sample entropy." 
    American Journal of Physiology-Heart and Circulatory Physiology
    (2000)
EntropyHub._XFuzzEn.XFuzzEnFunction
XFuzz, Ps1, Ps2 = XFuzzEn(Sig)

Returns the cross-fuzzy entropy estimates (XFuzz) and the average fuzzy distances (m:Ps1, m+1:Ps2) for m = [1,2] estimated for the data sequences contained in 'Sig', using the default parameters: embedding dimension = 2, time delay = 1, fuzzy function (Fx) = 'default', fuzzy function parameters (r) = [0.2, 2], logarithm = natural

XFuzz, Ps1, Ps2 = XFuzzEn(Sig::AbstractArray{T,2} where T<:Real; m::Int=2, tau::Int=1, r::Union{Real,Tuple{Real,Real}}=(.2,2), Fx::String="default", Logx::Real=exp(1))

Returns the cross-fuzzy entropy estimates (XFuzz) for dimensions = [1,...,m] estimated for the data sequences in Sig using the specified 'keyword' arguments:

Arguments:

m - Embedding Dimension, a positive integer [default: 2]

tau - Time Delay, a positive integer [default: 1]

Fx - Fuzzy funtion name, one of the following: {default,sigmoid,modsampen,gudermannian,linear}

r - Fuzzy function parameters, a scalar or a 2 element tuple of positive values. The r parameters for each fuzzy function are defined as follows:

      sigmoid:       r(1) = divisor of the exponential argument
                     r(2) = value subtracted from argument (pre-division)
      modsampen:     r(1) = divisor of the exponential argument
                     r(2) = value subtracted from argument (pre-division)
      default:       r(1) = divisor of the exponential argument
                     r(2) = argument exponent (pre-division)
      gudermannian:  r    = a scalar whose value is the numerator of
                            argument to gudermannian function:
                            GD(x) = atan(tanh(`r`/x)).
      linear:        r    = an integer value. When `r` = 0, the
                            argument of the exponential function is 
                            normalised between [0 1]. When `r` = 1,
                            the minimuum value of the exponential 
                            argument is set to 0.

Logx - Logarithm base, a positive scalar

For further information on the 'keyword' arguments, see the EntropyHub guide.

See also FuzzEn, XSampEn, XApEn, FuzzEn2D, XMSEn, MSEn

References:

[1] Hong-Bo Xie, et al.,
    "Cross-fuzzy entropy: A new method to test pattern synchrony of
    bivariate time series." 
    Information Sciences 
    180.9 (2010): 1715-1724.
EntropyHub._XK2En.XK2EnFunction
XK2, Ci = XK2En(Sig)

Returns the cross-Kolmogorov entropy estimates (XK2) and the correlation integrals (Ci) for m = [1,2] estimated between the data sequences contained in Sig using the default parameters: embedding dimension = 2, time delay = 1, distance threshold (r) = 0.2*SD(Sig), logarithm = natural

XK2, Ci = XK2En(Sig::AbstractArray{T,2} where T<:Real; m::Int=2, tau::Int=1, r::Real=0.2*std(Sig,corrected=false), Logx::Real=exp(1))

Returns the cross-Kolmogorov entropy estimates (XK2) estimated between the data sequences contained in Sig using the specified 'keyword' arguments:

Arguments:

m - Embedding Dimension, a positive integer [default: 2]

tau - Time Delay, a positive integer [default: 1]

r - Radius Distance Threshold, a positive scalar [default: 0.2*SD(Sig)]

Logx - Logarithm base, a positive scalar [default: natural]

See also XSampEn, XFuzzEn, XApEn, K2En, XMSEn, XDistEn

References:

[1]  Matthew W. Flood,
     "XK2En - EntropyHub Project"
     (2021) https://github.com/MattWillFlood/EntropyHub
EntropyHub._XPermEn.XPermEnFunction
XPerm = XPermEn(Sig)

Returns the cross-permuation entropy estimates (XPerm) estimated betweeen the data sequences contained in Sig using the default parameters: embedding dimension = 3, time delay = 1, logarithm = base 2,

XPerm = XPermEn(Sig::AbstractArray{T,2} where T<:Real; m::Int=3, tau::Int=1, Logx::Real=exp(1))

Returns the permutation entropy estimates (XPerm) estimated between the data sequences contained in Sig using the specified 'keyword' arguments:

Arguments:

m - Embedding Dimension, an integer > 2 [default: 3]

    **Note: XPerm is undefined for embedding dimensions < 3.**

tau - Time Delay, a positive integer [default: 1]

Logx - Logarithm base, a positive scalar [default: 2] ** enter 0 for natural log.**

See also PermEn, XApEn, XSampEn, XFuzzEn, XMSEn

References:

[1] Wenbin Shi, Pengjian Shang, and Aijing Lin,
    "The coupling analysis of stock market indices based on 
    cross-permutation entropy."
    Nonlinear Dynamics
    79.4 (2015): 2439-2447.
EntropyHub._XCondEn.XCondEnFunction
XCond, SEw, SEz = XCondEn(Sig)

Returns the corrected cross-conditional entropy estimates (XCond) and the corresponding Shannon entropies (m: SEw, m+1: SEz) for m = [1,2] estimated for the data sequences contained in Sig using the default parameters: embedding dimension = 2, time delay = 1, number of symbols = 6, logarithm = natural ** Note: XCondEn is direction-dependent. Therefore, the order of the data sequences in Sig matters. If the first row/column of Sig is the sequence 'y', and the second row/column is the sequence 'u', the XCond is the amount of information carried by y(i) when the pattern u(i) is found.**

XCond, SEw, SEz = XCondEn(Sig::AbstractArray{T,2} where T<:Real; m::Int=2, tau::Int=1, c::Int=6, Logx::Real=exp(1), Norm::Bool=false)

Returns the corrected cross-conditional entropy estimates (XCond) for the data sequences contained in Sig using the specified 'keyword' arguments:

Arguments:

m - Embedding Dimension, an integer > 1 [default: 2]

tau - Time Delay, a positive integer [default: 1]

c - Number of symbols, an integer > 1 [default: 6]

Logx - Logarithm base, a positive scalar [default: natural]

Norm - Normalisation of XCond values: [false] no normalisation [default]

        [true]   normalises w.r.t cross-Shannon entropy.

See also XFuzzEn, XSampEn, XApEn, XPermEn, CondEn, XMSEn

References:

[1] Alberto Porta, et al.,
    "Conditional entropy approach for the evaluation of the 
    coupling strength." 
    Biological cybernetics 
    81.2 (1999): 119-129.
EntropyHub._XDistEn.XDistEnFunction
XDist, Ppi = XDistEn(Sig)

Returns the cross-distribution entropy estimate (XDist) and the corresponding distribution probabilities (Ppi) estimated between the data sequences contained in Sig using the default parameters: embedding dimension = 2, time delay = 1, binning method = 'Sturges', logarithm = base 2, normalisation = w.r.t # of histogram bins

XDist, Ppi = XDistEn(Sig::AbstractArray{T,2} where T<:Real; m::Int=2, tau::Int=1, Bins::Union{Int,String}="Sturges", Logx::Real=2, Norm::Bool=true)

Returns the cross-distribution entropy estimate (XDist) estimated between the data sequences contained in Sig using the specified 'keyword' = arguments:

Arguments:

m - Embedding Dimension, a positive integer [default: 2]

tau - Time Delay, a positive integer [default: 1]

Bins - Histogram bin selection method for distance distribution, an integer > 1 indicating the number of bins, or one of the following strings {'sturges','sqrt','rice','doanes'} [default: 'sturges']

Logx - Logarithm base, a positive scalar [default: 2] ** enter 0 for natural log**

Norm - Normalisation of DistEn value: [false] no normalisation. [true] normalises w.r.t # of histogram bins [default]

See also XSampEn, XApEn, XPermEn, XCondEn, DistEn, DistEn2D, XMSEn

References:

[1] Yuanyuan Wang and Pengjian Shang,
    "Analysis of financial stock markets through the multiscale
    cross-distribution entropy based on the Tsallis entropy."
    Nonlinear Dynamics 
    94.2 (2018): 1361-1376.
EntropyHub._XSpecEn.XSpecEnFunction
XSpec, BandEn = XSpecEn(Sig)

Returns the cross-spectral entropy estimate (XSpec) of the full cross- spectrum and the within-band entropy (BandEn) estimated between the data sequences contained in Sig using the default parameters: N-point FFT = 2*len(Sig) + 1, normalised band edge frequencies = [0 1], logarithm = base 2, normalisation = w.r.t # of spectrum/band frequency values.

XSpec, BandEn = XSpecEn(Sig::AbstractArray{T,2} where T<:Real; N::Int=1 + (2*size(Sig,1)), Freqs::Tuple{Real,Real}=(0,1), Logx::Real=exp(1), Norm::Bool=true)

Returns the cross-spectral entropy (XSpec) and the within-band entropy (BandEn) estimate between the data sequences contained in Sig using the following specified 'keyword' arguments:

Arguments:

N - Resolution of spectrum (N-point FFT), an integer > 1

Freqs - Normalised band edge frequencies, a scalar in range [0 1] where 1 corresponds to the Nyquist frequency (Fs/2). Note: When no band frequencies are entered, BandEn == SpecEn

Logx - Logarithm base, a positive scalar [default: base 2] ** enter 0 for natural log**

Norm - Normalisation of XSpec value: [false] no normalisation. [true] normalises w.r.t # of spectrum/band frequency values [default]

For more info, see the EntropyHub guide

See also SpecEn, fft, XDistEn, periodogram, XSampEn, XApEn

References:

[1]  Matthew W. Flood,
    "XSpecEn - EntropyHub Project"
    (2021) https://github.com/MattWillFlood/EntropyHub