# Source code for neurokit2.complexity.entropy_tsallis

import numpy as np

from .entropy_shannon import _entropy_freq

[docs]
def entropy_tsallis(signal=None, q=1, symbolize=None, show=False, freq=None, **kwargs):
"""**Tsallis entropy (TSEn)**

Tsallis Entropy is an extension of :func:Shannon entropy <entropy_shannon> to the case where
entropy is nonextensive. It is similarly computed from a vector of probabilities of different
states. Because it works on discrete inputs (e.g., [A, B, B, A, B]), it requires to transform
the continuous signal into a discrete one.

.. math::

TSEn = \\frac{1}{q - 1} \\left( 1 - \\sum_{x \\in \\mathcal{X}} p(x)^q \\right)

Parameters
----------
signal : Union[list, np.array, pd.Series]
The signal (i.e., a time series) in the form of a vector of values.
q : float
Tsallis's *q* parameter, sometimes referred to as the entropic-index (default to 1).
symbolize : str
Method to convert a continuous signal input into a symbolic (discrete) signal. None by
default, which skips the process (and assumes the input is already discrete). See
:func:complexity_symbolize for details.
show : bool
If True, will show the discrete the signal.
freq : np.array
Instead of a signal, a vector of probabilities can be provided.
**kwargs
Optional arguments. Not used for now.

Returns
--------
tsen : float
The Tsallis entropy of the signal.
info : dict
A dictionary containing additional information regarding the parameters used.

--------
entropy_shannon, fractal_petrosian, entropy_renyi

Examples
----------
.. ipython:: python

import neurokit2 as nk

signal = [1, 3, 3, 2, 6, 6, 6, 1, 0]
tsen, _ = nk.entropy_tsallis(signal, q=1)
tsen

shanen, _ = nk.entropy_shannon(signal, base=np.e)
shanen

References
-----------
* Tsallis, C. (2009). Introduction to nonextensive statistical mechanics: approaching a complex
world. Springer, 1(1), 2-1.

"""
if freq is None:
_, freq = _entropy_freq(signal, symbolize=symbolize, show=show)
freq = freq / np.sum(freq)

if np.isclose(q, 1):
lnq_1_over_p = np.log(1 / freq)
else:
lnq_1_over_p = ((1 / freq) ** (1 - q) - 1) / (1 - q)

tsens = freq * lnq_1_over_p
return np.sum(tsens), {"Symbolization": symbolize, "Values": tsens}