# Source code for neurokit2.complexity.fractal_linelength

# -*- coding: utf-8 -*-
import numpy as np
import pandas as pd
[docs]
def fractal_linelength(signal):
"""**Line Length (LL)**
Line Length (LL, also known as curve length), stems from a modification of the
:func:`Katz fractal dimension <fractal_katz>` algorithm, with the goal of making it more
efficient and accurate (especially for seizure onset detection).
It basically corresponds to the average of the absolute consecutive differences of the signal,
and was made to be used within subwindows. Note that this does not technically measure the
fractal dimension, but the function was named with the ``fractal_`` prefix due to its
conceptual similarity with Katz's fractal dimension.
Parameters
----------
signal : Union[list, np.array, pd.Series]
The signal (i.e., a time series) in the form of a vector of values.
Returns
-------
float
Line Length.
dict
A dictionary containing additional information (currently empty, but returned nonetheless
for consistency with other functions).
See Also
--------
fractal_katz
Examples
----------
.. ipython:: python
import neurokit2 as nk
signal = nk.signal_simulate(duration=2, sampling_rate=200, frequency=[5, 6, 10])
ll, _ = nk.fractal_linelength(signal)
ll
References
----------
* Esteller, R., Echauz, J., Tcheng, T., Litt, B., & Pless, B. (2001, October). Line length: an
efficient feature for seizure onset detection. In 2001 Conference Proceedings of the 23rd
Annual International Conference of the IEEE Engineering in Medicine and Biology Society (Vol.
2, pp. 1707-1710). IEEE.
"""
# Sanity checks
if isinstance(signal, (np.ndarray, pd.DataFrame)) and signal.ndim > 1:
raise ValueError(
"Multidimensional inputs (e.g., matrices or multichannel data) are not supported yet."
)
# Force to array
signal = np.array(signal)
# Drop missing values
signal = signal[~np.isnan(signal)]
# Compute line length
ll = np.mean(np.abs(np.diff(signal)))
return ll, {}