MFDFA

https://mfdfa.readthedocs.io/en/latest/
Admin
MFDFA is a Python implementation of Multifractal Detrended Fluctuation Analysis for analyzing and...
Tokens:6,067
Snippets:57
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install MFDFA

Source: https://mfdfa.readthedocs.io/en/latest/installation.html

Use this command to install the MFDFA library from PyPI.

```bash
pip install MFDFA

```

--------------------------------

### Install MFDFA and dependencies

Source: https://mfdfa.readthedocs.io/en/latest/index.html

Commands to install the core library and the optional EMD-signal extension.

```bash
pip install MFDFA
```

```bash
pip install EMD-signal
```

--------------------------------

### Install EMD-signal for EMD Detrending

Source: https://mfdfa.readthedocs.io/en/latest/installation.html

Install the EMD-signal library if you plan to use Empirical Mode Decomposition for detrending.

```bash
pip install EMD-signal

```

--------------------------------

### Import MFDFA

Source: https://mfdfa.readthedocs.io/en/latest/installation.html

Import the MFDFA class into your Python script after installation.

```python
from MFDFA import MFDFA

```

--------------------------------

### Configure MFDFA for multifractal analysis

Source: https://mfdfa.readthedocs.io/en/latest/index.html

Set up parameters for detecting the multifractal spectrum of data.

```python
# Select a band of lags, which are ints
lag = np.unique(np.logspace(0.5, 3, 100).astype(int))

# Select a list of powers q
q_list = np.linspace(-10,10,41)
q_list = q_list[q_list!=0.0]

# The order of the polynomial fitting
order = 2
```

--------------------------------

### Visualize and estimate Hurst index

Source: https://mfdfa.readthedocs.io/en/latest/1dprocess.html

Plots the results on a log-log scale and performs a linear fit to estimate the Hurst index.

```python
# To uncover the Hurst index, lets get some log-log plots
plt.loglog(lag, dfa, 'o', label='fOU: MFDFA q=2')

# And now we need to fit the line to find the slope
# in a double logaritmic scales, i.e., you need to
# fit the logs of the results
H_hat = np.polyfit(np.log(lag)[4:20],np.log(dfa[4:20]),1)[0]

print('Estimated H = '+'{:.3f}'.format(H_hat[0]))


# Now what you should obtain is: slope = H + 1
```

--------------------------------

### Perform MFDFA with Moving Window

Source: https://mfdfa.readthedocs.io/en/latest/index.html

Use a moving window to improve statistics for large lags in short time series.

```python
# Select a band of lags, which usually ranges from
# very small segments of data, to very long ones, as
lag = np.logspace(0.7, 4, 30).astype(int)

# Obtain the (MF)DFA by declaring the IMFs to subtract
# in a list in the dictionary of the extensions
lag, dfa, edfa = MFDFA(y, lag = lag, extensions = {'window': 32})
```

--------------------------------

### Generate a fractional Ornstein–Uhlenbeck process

Source: https://mfdfa.readthedocs.io/en/latest/1dprocess.html

Uses the Euler–Maruyama integration method to generate a process with a specified Hurst exponent.

```python
# Imports
from MFDFA import MFDFA
from MFDFA import fgn
# where this second library is to generate fractional Gaussian noises

# integration time and time sampling
t_final = 500
delta_t = 0.001

# Some drift theta and diffusion sigma parameters
theta = 0.3
sigma = 0.1

# The time array of the trajectory
time = np.arange(0, t_final, delta_t)

# The fractional Gaussian noise
H = 0.7
dB = (t_final ** H) * fgn(N = time.size, H = H)

# Initialise the array y
y = np.zeros([time.size])

# Integrate the process
for i in range(1, time.size):
   y[i] = y[i-1] - theta * y[i-1] * delta_t + sigma * dB[i]
```

--------------------------------

### Perform MFDFA with Moving Window Segmentation

Source: https://mfdfa.readthedocs.io/en/latest/extensions.html

Utilize a moving window for segmentation in MFDFA to improve statistics for large lags, especially with short timeseries. Specify the step-size for the moving window.

```python
# Select a band of lags, which usually ranges from
# very small segments of data, to very long ones, as
lag = np.logspace(0.7, 4, 30).astype(int)

# Obtain the (MF)DFA by declaring the IMFs to subtract

```

--------------------------------

### Generate Fractional Gaussian Noise

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Generates fractional Gaussian noise with a specified Hurst exponent H. If H = 1/2, it produces standard Gaussian noise. Currently uses the Davies–Harte method.

```python
MFDFA.fgn.fgn(N: int, H: float) -> numpy.ndarray
```

--------------------------------

### Apply MFDFA for Multifractal Analysis

Source: https://mfdfa.readthedocs.io/en/latest/1dLevy.html

Applies the MFDFA function to analyze the multifractal properties of the generated data. Requires numpy and MFDFA. Ensure lag, q_list, and order are appropriately set for the analysis.

```python
# Select a band of lags, which are ints
lag = np.unique(np.logspace(0.5, 3, 100).astype(int))

# Select a list of powers q
q_list = np.linspace(-10,10,41)
q_list = q_list[q_list!=0.0]

# The order of the polynomial fitting
order = 2

# Obtain the (MF)DFA as
lag, dfa = MFDFA(y, lag = lag, q = q_list, order = order)

```

--------------------------------

### Generate Lévy stable distribution samples

Source: https://mfdfa.readthedocs.io/en/latest/index.html

Generate random numbers from a symmetric Lévy stable distribution using scipy.

```python
# Imports
from MFDFA import MFDFA
from scipy.stats import levy_stable

# Generate 100000 points
alpha = 1.5
X = levy_stable.rvs(alpha=alpha, beta = 0, size=10000)
```

--------------------------------

### Plot Timeseries and IMFs using Matplotlib

Source: https://mfdfa.readthedocs.io/en/latest/extensions.html

Visualize the original timeseries along with selected Intrinsic Mode Functions (IMFs) using Matplotlib for analysis.

```python
# Import
import matplotlib.pyplot as plt

# Plot the timeseries and the IMFs 6,7, and 8
plt.plot(X, color='black')
plt.plot(np.sum(IMF[[6,7,8],:], axis=0).T)
```

--------------------------------

### Obtain MFDFA

Source: https://mfdfa.readthedocs.io/en/latest/index.html

Standard call to perform Multifractal Detrended Fluctuation Analysis.

```python
lag, dfa = MFDFA(y, lag = lag, q = q_list, order = order)
```

--------------------------------

### Fractional Gaussian noise

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Generates fractional Gaussian noise with a specified Hurst exponent.

```APIDOC
## MFDFA.fgn.fgn

### Description
Generates fractional Gaussian noise with a Hurst index H in (0,1). If H = 1/2, this is simply Gaussian noise. The current method employed is the Davies–Harte method, which may fail for H ≈ 0. Future versions will include Cholesky decomposition and Hosking’s methods.

### Method
`fgn`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **N** (int) - Required - Size of fractional Gaussian noise to generate.
- **H** (float) - Required - Hurst exponent H in (0,1).

### Request Example
```json
{
  "N": 100,
  "H": 0.7
}
```

### Response
#### Success Response (200)
- **f** (numpy.ndarray) - An array of size N of fractional Gaussian noise with a Hurst index H.

#### Response Example
```json
{
  "f": [0.1, -0.2, 0.3, -0.1, 0.5, ...]
}
```
```

--------------------------------

### Apply MFDFA with Extensions

Source: https://mfdfa.readthedocs.io/en/latest/extensions.html

Applies the MFDFA method to a time series 'y' with specified lag and extensions. The extensions dictionary can be used to configure window size and other parameters.

```python
lag, dfa, edfa = MFDFA(y, lag = lag, extensions = {'window': 32})
```

--------------------------------

### Perform MFDFA analysis

Source: https://mfdfa.readthedocs.io/en/latest/1dprocess.html

Applies the MFDFA function to the generated process to calculate fluctuation analysis for a specific lag band and polynomial order.

```python
# Select a band of lags, which usually ranges from
# very small segments of data, to very long ones, as
lag = np.unique(np.logspace(0.5, 3, 100, dtype=int))

# Notice these must be ints, since these will segment
# the data into chucks of lag size

# Select the power q
q = 2

# The order of the polynomial fitting
order = 1

# Obtain the (MF)DFA as
lag, dfa = MFDFA(y, lag = lag, q = q, order = order)
```

--------------------------------

### Empirical Mode Decomposition for detrending timeseries

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Functions for detrending time series using Empirical Mode Decomposition (EMD). Requires the 'pyEMD' library.

```APIDOC
## MFDFA.emddetrender.detrendedtimeseries

### Description
Calculates the Intrinsic Mode Functions (IMFs) of a given timeseries, subtracts the user-chosen IMFs for detrending, and returns the detrended timeseries. Based on Dawid Laszuk’s PyEMD.

### Method
`detrendedtimeseries`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **timeseries** (numpy.ndarray) - Required - A 1-dimensional timeseries of length N.
- **modes** (list) - Required - List of integers indicating the indices of the IMFs to be subtracted/detrended from the timeseries.

### Request Example
```json
{
  "timeseries": [1, 2, 3, 4, 5],
  "modes": [0, 1]
}
```

### Response
#### Success Response (200)
- **detrendedTimeseries** (numpy.ndarray) - Detrended 1-dimensional timeseries.

#### Response Example
```json
{
  "detrendedTimeseries": [0.1, -0.2, 0.05, -0.15, 0.2]
}
```

### Installation
To use this extension, the `pyEMD` library is needed:
```bash
pip install EMD-signal
```

### References
[Huang1998] N. E. Huang, Z. Shen, S. R. Long, M. C. Wu, H. H. Shih, Q. Zheng, N.-C. Yen, C. C. Tung, and H. H. Liu, “The empirical mode decomposition and the Hilbert spectrum for non-linear and non stationary time series analysis”, Proc. Royal Soc. London A, Vol. 454, pp. 903-995, 1998.
[Rilling2003] G. Rilling, P. Flandrin, and P. Goncalves, “On Empirical Mode Decomposition and its algorithms”, IEEE-EURASIP Workshop on Nonlinear Signal and Image Processing NSIP-03, Grado (I), June 2003.
```

```APIDOC
## MFDFA.emddetrender.IMFs

### Description
Extracts the Intrinsic Mode Functions (IMFs) of a given timeseries using Empirical Mode Decomposition.

### Method
`IMFs`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **timeseries** (numpy.ndarray) - Required - A 1-dimensional timeseries of length N.

### Request Example
```json
{
  "timeseries": [1, 2, 3, 4, 5]
}
```

### Response
#### Success Response (200)
- **IMFs** (numpy.ndarray) - The Intrinsic Mode Functions (IMFs) of the Empirical Mode Decomposition. These are of shape (..., timeseries.size), with the first dimension varying depending on the data. The last entry represents the residuals.

#### Response Example
```json
{
  "IMFs": [[0.5, 0.4, 0.3, 0.2, 0.1], [-0.1, -0.2, -0.3, -0.4, -0.5]]
}
```
```

--------------------------------

### Extract Intrinsic Mode Functions (IMFs) with MFDFA

Source: https://mfdfa.readthedocs.io/en/latest/extensions.html

Import the IMFs function from the MFDFA library to extract the Intrinsic Mode Functions from a timeseries.

```python
# Import
from MFDFA import IMFs

# Extract the IMFs simply by employing
IMF = IMFs(y)
```

--------------------------------

### Extract Intrinsic Mode Functions (IMFs)

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Extracts the Intrinsic Mode Functions (IMFs) from a given timeseries using Empirical Mode Decomposition. The last entry in the returned array represents the residuals.

```python
MFDFA.emddetrender.IMFs(timeseries: numpy.ndarray) -> numpy.ndarray
```

--------------------------------

### Perform MFDFA with eDFA Extension

Source: https://mfdfa.readthedocs.io/en/latest/extensions.html

Calculate the Extended Detrended Fluctuation Analysis (eDFA) by setting the 'eDFA' extension to True. This extension computes the difference between the maxima and minima of segment fluctuations.

```python
# Select a band of lags, which usually ranges from
# very small segments of data, to very long ones, as
lag = np.logspace(0.7, 4, 30).astype(int)

# Obtain the (MF)DFA by declaring the IMFs to subtract
# in a list in the dictionary of the extensions
lag, dfa, edfa = MFDFA(y, lag = lag, extensions = {'eDFA': True})
```

--------------------------------

### Perform MFDFA with EMD Detrending

Source: https://mfdfa.readthedocs.io/en/latest/extensions.html

Conduct Multifractal Detrended Fluctuation Analysis (MFDFA) by specifying the IMFs to be subtracted for detrending. Setting order=0 prevents polynomial detrending.

```python
# Select a band of lags, which usually ranges from
# very small segments of data, to very long ones, as
lag = np.logspace(0.7, 4, 30).astype(int)

# Obtain the (MF)DFA by declaring the IMFs to subtract
# in a list in the dictionary of the extensions
lag, dfa = MFDFA(y, lag = lag, extensions = {"EMD": [6,7,8]})
```

--------------------------------

### Generate Lévy Stable Distribution Data

Source: https://mfdfa.readthedocs.io/en/latest/1dLevy.html

Generates random numbers from a symmetric Lévy alpha-stable distribution using scipy.stats.levy_stable. Requires scipy and numpy. Ensure alpha is set correctly for the desired distribution.

```python
# Imports
from MFDFA import MFDFA
from scipy.stats import levy_stable

# Generate 100000 points
alpha = 1.5
X = levy_stable.rvs(alpha=alpha, beta = 0, size=10000)

```

--------------------------------

### Detrend timeseries using EMD

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Calculates Intrinsic Mode Functions (IMFs) of a timeseries, subtracts specified IMFs for detrending, and returns the detrended timeseries. Requires the `pyEMD` library.

```python
MFDFA.emddetrender.detrendedtimeseries(timeseries: numpy.ndarray, modes: list) -> numpy.ndarray
```

--------------------------------

### MFDFA Function

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Calculates the Multifractal Detrended Fluctuation Analysis of a time series.

```APIDOC
## MFDFA.MFDFA.MFDFA

### Description
Multifractal Detrended Fluctuation Analysis of timeseries. MFDFA generates a fluctuation function F²(q,s), with s the segment size and q the q-powers. It calculates the fluctuation function F²q(s) and its scaling exponent h(q).

### Method
`MFDFA`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **timeseries** (numpy.ndarray) - Required - A 1-dimensional timeseries (N, 1).
* **lag** (numpy.ndarray of ints) - Required - An array with the window sizes to calculate.
* **order** (int) - Optional (default 1) - The order of the polynomials to approximate.
* **q** (numpy.ndarray) - Optional (default 2) - Fractal exponent to calculate. Array in [-10,10].
* **stat** (bool) - Optional (default False) - Calculates the standard deviation associated with each segment’s averaging.
* **modified** (bool) - Optional (default False) - For data with the Hurst index ≈ 0, a further integration of the timeseries yields a modified scaling coefficient.
* **extensions** (dict) - Optional (default {'EMD': False, 'eDFA': False, 'window': False}) - Dictionary for extensions:
  * **EMD** (list) - If not None, requires a list of indices of the user-chosen IMFs.
  * **eDFA** (bool) - If True, calls function eDFA().
  * **window** (bool) - If True, uses a moving window for smaller timeseries.

### Request Example
```json
{
  "timeseries": "[1, 2, 3, 4, 5, ...]",
  "lag": "[10, 20, 30, 40, 50]",
  "order": 1,
  "q": "[-5, -4, -3, -2, -1, 1, 2, 3, 4, 5]",
  "stat": false,
  "modified": false,
  "extensions": {
    "EMD": null,
    "eDFA": false,
    "window": false
  }
}
```

### Response
#### Success Response (200)
* **lag** (numpy.ndarray of ints) - Array of lags, realigned, preserving only different lags and with entries > order + 1.
* **f** (numpy.ndarray) - A array of shape (size(lag),size(q)) of variances over the indicated lag windows and the indicated q-fractal powers.

#### Response Example
```json
{
  "lag": "[10, 20, 30, 40, 50]",
  "f": "[[0.1, 0.2, ...], [0.3, 0.4, ...], ...]"
}
```

### References
* [Peng1994] C.-K. Peng, S. V. Buldyrev, S. Havlin, M. Simons, H. E. Stanley, and A. L. Goldberger. “Mosaic organization of DNA nucleotides.” Phys. Rev. E, 49(2), 1685–1689, 1994.
* [Kantelhardt2002] J. W. Kantelhardt, S. A. Zschiegner, E. Koscielny-Bunde, S. Havlin, A. Bunde, H. E. Stanley. “Multifractal detrended fluctuation analysis of nonstationary time series.” Physica A, 316(1-4), 87–114, 2002.
```

--------------------------------

### MFDFA Function Signature

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

The primary function for performing Multifractal Detrended Fluctuation Analysis on a 1D timeseries.

```python
MFDFA.MFDFA.MFDFA(timeseries: numpy.ndarray , lag: numpy.ndarray , order: int = 1 , q: numpy.ndarray = 2 , stat: bool = False , modified: bool = False , extensions: dict = {'EMD': False , 'eDFA': False , 'window': False}) → Tuple[numpy.array, numpy.ndarray]
```

--------------------------------

### eDFA Function Signature

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Calculates a measure of nonstationarity based on the extrema of the DFA fluctuation function.

```python
MFDFA.MFDFA.eDFA(F: numpy.ndarray) → numpy.ndarray
```

--------------------------------

### eDFA Function

Source: https://mfdfa.readthedocs.io/en/latest/functions/index.html

Calculates the difference of the extrema of the fluctuation function, a measure of nonstationarity.

```APIDOC
## MFDFA.MFDFA.eDFA

### Description
Calculates the difference between the maximum and minimum values of the fluctuation function F²q(s), denoted as dF²q(s). This serves as a measure of nonstationarity.

### Method
`eDFA`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **F** (numpy.ndarray) - Required - The fluctuation function obtained from the MFDFA() function.

### Request Example
```json
{
  "F": "[[0.1, 0.2, ...], [0.3, 0.4, ...], ...]"
}
```

### Response
#### Success Response (200)
* **res** (np.ndarray) - The difference between the maximum and minimum values of the fluctuation function.

#### Response Example
```json
{
  "res": "[0.5, 0.7, ...]"
}
```

### Notes
New in version 0.3.

### References
* [Pavlov2020] A. N. Pavlov, A. S. Abdurashitov, A. A. Koronovskii Jr., O. N. Pavlova, O. V. Semyachkina-Glushkovskaya, and J. Kurths. “Detrended fluctuation analysis of cerebrovascular responses to abrupt changes in peripheral arterial pressure in rats.” CNSNS 85, 105232, 2020.
```
Tokens:
Raw