pyhctsa.operations.scaling.fluctuation_analysis

pyhctsa.operations.scaling.fluctuation_analysis(x, q=2, wtf='rsrange', tau_step=1, k=1, lag=None, log_inc=True)

Implements fluctuation analysis by a variety of methods.

Much of our implementation is based on the well-explained discussion of scaling methods [1].

The main difference between algorithms for estimating scaling exponents amount to differences in how fluctuations, F, are quantified in time-series segments. Many alternatives are implemented in this function.

References

Parameters:
x : array-like

The input time series.

q : Union[float, int], optional

The order of the fluctuation function. The default is q = 2, which gives RMS fluctuations (standard DFA for wtf='dfa'). For wtf='dfa' any real q (including negative and non-integer values, and q = 0) gives the q-th order fluctuation function of multifractal DFA (MF-DFA) [4]: with F^2(v) the variance of the detrended profile in window v, F_q(s) = ( mean_v F^2(v)^(q/2) )^(1/q), and for q = 0 the logarithmic average F_0(s) = exp( mean_v ln F^2(v) / 2 ). The scaling exponent returned is then the generalized Hurst exponent h(q); for q < 0 it is NaN if some window has zero variance. For the other wtf options, F = mean(f ** q) ** (1/q) is taken over the per-window quantity f (q must then be nonzero).

wtf : str, optional

What to fluctuate. Options are:

  • ’endptdiff’: Calculates the differences in end points in each segment

  • ’range’: Calculates the range in each segment

  • ’std’: Takes the standard deviation in each segment [1]

  • ’iqr’: Takes the interquartile range in each segment

  • ’dfa’: Detrended fluctuation analysis [5, 6]: the mean of the series is removed, the profile (cumulative sum) is formed, and a polynomial trend of order k is removed in each segment

  • ’rsrange’: Returns the range after removing a straight line fit [2]

  • ’rsrangefit’: Fits a polynomial of order k and returns the range [2]

Default is 'rsrange'.

For ‘rsrangefit’, an optional timelag can be applied for computing the cumulative sum (integrated profile) [3].

tau_step : int, optional

Number of tau (locInc true), or increments in tau for linear range. Default is 1.

k : int, optional

Polynomial order of detrending (for ‘dfa’ & ‘rsrangefit’). Default is 1 (DFA1). Note that k = 0 (only the segment mean of the profile is removed, no trend) is not DFA proper: its exponent saturates near alpha = 1 for strongly persistent series and is biased low (by about 0.05-0.1 at N of a few hundred) for weakly persistent ones.

lag : int or None, optional

Optional time-lag, as in Alvarez-Ramirez [3]. Default is None.

log_inc : bool, optional

Whether to use logarithmic increments in tau (it should be logarithmic). Default is True.

Returns:

Statistics of fitting a linear function to a plot of log(F) as a function of log(tau), and for fitting two straight lines to the same data, choosing the split point at tau = tau_{split} as that which minimizes the combined fitting errors of two least-squares lines. The lines reported are then fitted by the Theil-Sen method (the median of the slopes between all pairs of points, a robust estimator with a closed form: pyhctsa.robust.bf_theil_sen()).

  • linfitint, alpha, se1, se2, ssr, resac1: the intercept, slope (the scaling exponent alpha), standard errors of the intercept and the slope (the usual least-squares formulas applied to the residuals of the robust fit), mean squared residual, and lag-1 autocorrelation of the residuals, of the single line fitted over all timescales; r1_* and r2_*: the same for the first (shorter-timescale) and the second line of the two-line fit.

  • logtausplit, prop_r1: the value of log(tau) at the split between the two lines, and the proportion of the timescales covered by the first line.

  • splitgain: the proportional reduction in mean squared error from fitting two least-squares lines rather than one over the whole range, one minus the ratio of the minimum two-line error to the one-line error (between 0 and 1; NaN if the one-line fit is exact).

  • meanssr, stdssr: the mean and the standard deviation of the two-line fitting error across the candidate split points.

  • alphadiff: the difference r1_alpha - r2_alpha between the scaling exponents of the two lines.

NaN if there are too few timescales; the two-line outputs are NaN if the timescales are too few to support two lines.

Return type:

dict