# docs/source/api.rst

API References

This is the auto-generated documentation from the docstrings of the code.

MFDFA module

Created on Wed Jun 18 12:49:42 2025

@author: Nahuel Mendez & Sebastian Jaroszewicz

mftoolkit.MFDFA.bootstrap_multifractal_parameters(scales, F_q_s, q_values, n_boot=1000, conf_interval=0.95)[source]

Performs a fully vectorized bootstrap for MFDFA parameters (h, tau, alpha, f_alpha). Uses tensor linear algebra instead of for-loops for resampling.

Parameters:

scalesarray (N_scales,)

The scales ‘s’ used in the analysis.

F_q_sarray (N_q, N_scales)

Fluctuation function matrix (pre-filtered for NaNs/Zeros).

q_valuesarray (N_q,)

The q exponents.

n_bootint

Number of bootstrap iterations.

conf_intervalfloat

Confidence level (e.g., 0.95 for 95% CI).

Returns:

dict

Dictionary with keys ‘h’, ‘tau’, ‘alpha’, ‘f_alpha’. Each value is a tuple: (mean, ci_lower, ci_upper, err_low, err_high).

mftoolkit.MFDFA.mfdfa(data, q_values, scales, order=1, num_cores=None, segments_from_both_ends=False, scale_range_for_hq=None, validate=True)[source]

Performs Multifractal Detrended Fluctuations Analysis (MFDFA) in parallel.

Parameters:

dataarray_like

The time series to analyze (one-dimensional).

q_valuesarray_like

The range of q moments for the analysis.

scalesarray_like

The scales (segment lengths) to consider. Must be integers.

orderint, optional

The order of the polynomial for detrending (default is 1, linear).

num_coresint, optional

Number of CPU cores to use. If None, use os.cpu_count().

segments_from_both_endsbool, optional

If True, segments are taken from the start and end of the series. If False (default) segments are taken only from the start.

scale_range_for_hqtuple or list, optional

Tuple (min_s, max_s) defines the scale range to be used to calculate the exponent h(q). If None (default), all valid scales are used.

validate: bool, optional

If True (default), theoretical and concavity masks are applied to validate numerical results If False, numerical values are returned without a validation step.

Return:

qndarray

q-values or moment exponents

h_qndarray

The generalized Hurst exponent for each value of q.

tau_qndarray

The mass scaling function for each value of q.

alphandarray

The singularity (or Hölder) exponent.

f_alphandarray

The singularity spectrum.

F_q_sndarray

The fluctuation function F_q(s) for each q and s..

Sources module

Created on Fri Jun 27 10:14:32 2025

@author: Nahuel Mendez & Sebastian Jaroszewicz

mftoolkit.mfsources.iaaft_surrogate(original_series, num_surrogates=1, max_iter=1000, tol=1e-08, n_jobs=-1)[source]

Generates one or more surrogate time series using the IAAFT algorithm.

This method creates surrogate series that preserve the power spectrum (autocorrelation) and the amplitude distribution of the original series. The generation can be run in parallel on multiple CPU cores.

Parameters:

  • original_series (np.ndarray) – The 1D input time series to create surrogates from.

  • num_surrogates (int, optional) – The number of surrogate series to generate. Defaults to 1.

  • max_iter (int, optional) – Maximum number of iterations for the algorithm per surrogate. Defaults to 1000.

  • tol (float, optional) – Tolerance for convergence. The iteration for a surrogate stops if the relative change in spectrum error is less than this value. Defaults to 1e-8.

  • n_jobs (int, optional) – The number of CPU cores to use for parallel generation. -1 means using all available cores. If set to 1, runs on a single thread. Defaults to -1.

Returns:

  • If num_surrogates is 1 (default), returns a single NumPy array.

  • If num_surrogates > 1, returns a list of NumPy arrays.

Return type:

np.ndarray or list[np.ndarray]

Notes

The Iterative Amplitude Adjusted Fourier Transform (IAAFT) algorithm iteratively adjusts the surrogate’s amplitudes and power spectrum to match the original series [2]. It is used to test against the null hypothesis of a stationary linear stochastic process with a possibly non-Gaussian distribution of values. This implementation uses Python’s multiprocessing module to parallelize the generation of multiple surrogates.

References

[2] Schreiber, T., & Schmitz, A. (2000). Surrogate time series.

Physica D: Nonlinear Phenomena, 142(3-4), 346-382.

mftoolkit.mfsources.shuffle_surrogate(original_series: ndarray, num_shuffles: int = 100) → list[ndarray][source]

Generate surrogate time series by randomly shuffling the original series.

This method creates surrogate series that have the exact same amplitude distribution (histogram) as the original series. However, it destroys all temporal structures, including both linear and non-linear correlations, by randomly reordering the data points.

Parameters:

  • original_series (array_like) – The 1D input time series to create surrogates from.

  • num_shuffles (int, optional) – The number of shuffled surrogate series to generate. Defaults to 100.

Returns:

  • If num_shuffles is 1 (default), returns a single NumPy array.

  • If num_shuffles > 1, returns a list of NumPy arrays.

Return type:

np.ndarray or list[np.ndarray]

Crossovers module

Created on Wed Jun 18 12:49:42 2025

@author: Nahuel Mendez & Sebastian Jaroszewicz

mftoolkit.crossovers.CDVA(logS, logFq, q, method=1, q_column=None, use_numba=False)[source]

Crossover Detection based on Variance of slope Differences (CDV-A).

This function implements the CDV-A algorithm [2] to find the most prominent crossover point in a log-log plot of fluctuation functions Fq(s) vs. scales s.

Parameters:

  • logS (array_like) – 1D array of the logarithm of the scales.

  • logFq (array_like) – 2D array of the logarithm of the fluctuation functions. Rows correspond to scales, columns to q-moments.

  • q (array_like) – 1D array of the q-moments.

  • method ({1, 2}, optional) – Method to use: 1 for averaging over all q-moments, 2 for using only q=2. Default is 1.

  • q_column (int, optional) – 0-based index of the column to use in logFq when method=2. If None, the column closest to q=2 is found automatically.

  • use_numba (bool, optional) – If True, attempts to use the Numba-optimized engine for speed. If Numba is not installed, it will fall back to the plain NumPy version. Defaults to False.

Returns:

A tuple containing: - index_s_cross (int): 0-based index of the crossover in the logS array. - slope_dif_mean (float): Mean of the slope differences at the crossover. - i_cut (int): Row index used to trim noise-affected variances. - valley (ndarray): Array of column indices forming the detected valley.

Return type:

tuple

Notes

The CDV-A method identifies potential crossover regions by analyzing the variance of the differences between left-side and right-side log-log slopes, computed across multiple window sizes. This implementation is based on the description and MATLAB code provided in [3].

References

[3] Moreno-Pulido, S., de la Torre, J.C., Ruiz, P. et al. Crossover

detection based on variances of slope differences for multi-fractal detrended fluctuation analysis (MF-DFA). Nonlinear Dyn 113, 7425–7457 (2025). https://doi.org/10.1007/s11071-024-10478-1

mftoolkit.crossovers.SPIC(x_obs, y_obs, max_k_to_test=3, num_permutations=200, min_points_per_segment=3, significance_level=0.05, n_jobs=-1, use_numba=True)[source]

Finds the best number of crossovers (K) using a sequential permutation test. SPIC: Sequential Permutation for Identifying Crossovers. Allows selecting between a Numba-optimized engine or a Scikit-learn based one.

Parameters:

x_obs, y_obsarray_like

The observed independent and dependent variables.

max_k_to_testint, optional

The maximum number of crossovers (K) to test for. Default is 3.

num_permutationsint, optional

Number of permutations for the significance test. Default is 200.

min_points_per_segmentint, optional

Minimum number of data points required in each linear segment. Default is 3.

significance_levelfloat, optional

The alpha level for the permutation test. Default is 0.05.

n_jobsint, optional

Number of CPU cores to use for parallel permutations. -1 means all available cores. Default is -1.

use_numbabool, optional

If True (default), tries to use the Numba-optimized engine. If Numba is not available, it will automatically switch to False. If False, uses the Scikit-learn based engine.

Returns:

list

A list of the indices (in the sorted array) where the crossovers occur. Returns an empty list if K=0 is the best model.

Notes

This function implements the sequential hypothesis testing method using permutations, as described in [4], to determine the optimal number of crossovers in a piecewise linear regression model. The core idea is to sequentially test a model with K crossovers against a model with K+1 crossovers.

References

[4] Ge, E., & Leung, Y. (2012). Detection of crossover time scales in multifractal detrended fluctuation analysis.

Journal of Geographical Systems, 15(2), 115–147. doi:10.1007/s10109-012-0169-9

mftoolkit.crossovers.find_crossover(M)[source]

Finds the crossover in the slope difference matrix M.

mftoolkit.crossovers.perform_permutation_test_mp(x_obs_sorted, y_obs_sorted, k0, k1, fit_cache, fit_function, num_permutations, min_points_per_segment, significance_level, n_jobs)[source]

Performs the permutation test, dispatching to the correct fitting engine.

Generation module

Created on Thu Aug 28 12:22:42 2025

@author: Nahuel Mendez & Sebastian Jaroszewicz

mftoolkit.mfgeneration.generate_crossover_series(N, alpha1, alpha2, crossover_scale, sampling_rate=1.0, seed=None)[source]

Generate time series with DFA crossover behavior using Fourier Filtering Method (FFM).

Parameters:

Nint

Length of time series (recommended: N >= 10^4)

alpha1float

Short-term scaling exponent (DFA exponent for s < crossover_scale)

alpha2float

Long-term scaling exponent (DFA exponent for s > crossover_scale)

crossover_scalefloat

The temporal scale where transition occurs

sampling_ratefloat

Sampling rate (default: 1.0)

seedint, optional

Seed for the random number generator (default: None)

Returns:

time_seriesndarray

Generated time series with crossover behavior

timendarray

Time array

mftoolkit.mfgeneration.generate_fgn(H: float, n_points: int) → ndarray[source]

Generates a time serie of a fractional Gaussian noise (fGn) using the Davies-Harte exact method.

Parameters:

Hfloat

Hurst exponent of the serie. Must be in the range (0, 1).

n_pointsint

Length (number of points) of the time series to generate.

Returns:

fgn_seriesnp.ndarray

A 1D NumPy array containing the fGn time serie.

References:

[5] Davies, R. B., & Harte, D. S. (1987). Tests for Hurst effect. Biometrika, 74(1), 95-101.

mftoolkit.mfgeneration.generate_mf_corr(n_points: int, a: float = 0.3) → ndarray[source]

Generates a multifractal series with a perfect Gaussian PDF.

This method disentangles the PDF from the correlation structure. It first generates a standard binomial cascade to obtain a multifractal correlation structure. It then imposes this structure onto a Gaussian white noise series via rank-ordering.

The final output is a series that retains the intricate, multifractal correlation structure of the cascade model while possessing a strictly Gaussian PDF.

Parameters:

  • n_points (int) – The length of the time series to generate. Must be a positive integer and a power of 2.

  • a (float, optional) – The multiplier for the binomial cascade, by default 0.3. Must be in the range (0, 1). Values closer to 0.5 generate weaker multifractality.

Returns:

A 1D NumPy array with the correlation structure of a binomial cascade but a Gaussian distribution of values.

Return type:

np.ndarray

mftoolkit.mfgeneration.generate_mf_dist(n_points, H: float, power=2.0)[source]

Generates a multifractal time series from a probability distribution.

This function first creates a fractional Gaussian noise (fGn) series with long-range correlations defined by the Hurst exponent. Then, it applies a non-linear transformation to introduce multifractality.

Parameters:

  • n_points (int) – The length of the time series to generate.

  • H (float) – The Hurst exponent of the underlying correlation structure (0 < H < 1).

  • power (float) – The exponent for the non-linear transformation. Values > 1 introduce multifractality.

Returns:

The generated 1D multifractal time series.

Return type:

np.ndarray

Notes

The parameter H controls the long-range memory (the monofractal component), while power controls the strength of the multifractality.