stfbnc/fathon

python package for DFA (Detrended Fluctuation Analysis) and related algorithms

fathon

fathon is a python package for DFA (Detrended Fluctuation Analysis) and related algorithms.

It is mostly written in Cython and C in order to speed up computations.

fathon provides five main algorithms, namely

• DFA (Detrended Fluctuation Analysis)
• MFDFA (Multifractal Detrended Fluctuation Analysis)
• DCCA (Detrended Cross-Correlation Analysis)
• MFDCCA (Multifractal Detrended Cross-Correlation Analysis)
• HT (Time-dependent Hurst exponent)

MFDFA and MFDCCA also provides methods for the mass exponent τ and the multifractal spectrum f(α).

DCCA has methods to compute the cross-correlation coefficient ρ_DCCA and the corresponding confidence intervals.

Supported platforms

Linux x86_64	Linux ARM64	macOS x86_64	macOS ARM64	Windows 64bit
✅	✅	✅	❌	✅

Prerequisites

• Python 3.8 or higher
• numpy (version >= 1.24.4 for Python < 3.12, version >= 1.26.2 for Python >= 3.12)

Installing

As easy as pip install fathon

Examples

A jupyter notebook can be used (fathon_example.ipynb) to play with the five algorithms provided by the fathon package.

If you cannot use the notebook, five Python scripts are provided, dfa.py, mfdfa.py, dcca.py, mfdcca.py, and ht.py.

Algorithms are implemented on two time series of gaussian white noise, but you can replace them with any time series you like.

Documentation

API documentation

Contributing

To report bugs or improvements, or for any other question, please see CONTRIBUTING.md.

Credits

If you are using fathon in your research, please cite:

Bianchi, S., (2020). fathon: A Python package for a fast computation of detrendend fluctuation analysis and related algorithms. Journal of Open Source Software, 5(45), 1828, https://doi.org/10.21105/joss.01828

Changelog

v1.3.3

• fix divergent results when q approaches 0 (affects MFDFA-like algorithms)

v1.3.2

• unbiased version of DFA, as described here

v1.3.1

• faster algorithms

v1.3

• MFDCCA algorithm
• overlap option for DCCA, to allow using both overlapping and non-overlapping windows
• OpenMP also for Windows

v1.2

• few adjustments to C extensions for Windows' C compiler compatibility

v1.1

• save object state to binary file and reload it later

v1.0

• wheels! 🎡🎡
• no more pre-installing step of the GSL library 🎉🎉
• window's sizes array must be now passed to all the methods
• logBase option for methods that perform fits
• verbose option
• pre-computed hq0 can be now passed to the computeHT method

v0.1.2

• first release

Author

• Stefano Bianchi
  • github - stfbnc

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

This code uses GSL which is licensed under the GNU General Public License v3.0, and can be obtained at https://www.gnu.org/software/gsl/.

fathon's Issues

When importing fathon into Jupyter Notebooks, I get the following error.

ValueError Traceback (most recent call last)
/Users/sabrasisler/Desktop/ActionLab/StandingPosture/dfa_analysis.ipynb Cell 1 in 1
----> 1 import fathon

File /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/fathon/init.py:20
17 import platform
18 import os
---> 20 from .dfa import DFA
21 from .mfdfa import MFDFA
22 from .dcca import DCCA

File fathon/dfa.pyx:1, in init fathon.dfa()

ValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject

Error in starting fathon

Hello! Thanks for your usefull library. I have a problem in import fathon.
Traceback (most recent call last):

File ~\untitled9.py:8 in
import fathon

File ~\AppData\Roaming\Python\Python39\site-packages\fathon_init_.py:20 in
from .dfa import DFA

File fathon\dfa.pyx:1 in init fathon.dfa

ValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject

How can i fix it?

pip install not installing latest

it seems pip wont install higher than 1.2?

ERROR: Could not find a version that satisfies the requirement fathon==1.3.2 (from versions: 1.0, 1.1, 1.2)
ERROR: No matching distribution found for fathon==1.3.2

Unbiased DFA

Hi @stfbnc
thank you very much for your package. It is super useful. I was wondering if fathon could include the unbiased DFA for short time series as is described here

Many thanks
Antonio

DeprecationWarning

Running the example code for fathon.HT I get this numpy warning:

DeprecationWarning: Conversion of an array with ndim > 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)

Difficulty installing fathon on Linux

I installed gsl through pacman but ran into a few issues.

The command given in step 3 of the README seems incorrect.

$ python setup.py build_ext -- =/usr/include/gsl/ -- =/usr/lib/ --inplace
zsh: /usr/include/gsl/ not found

so I changed it to

$ python setup.py build_ext -- /usr/include/gsl/* -- /usr/lib/ --inplace
Traceback (most recent call last):
  File "setup.py", line 2, in <module>
    from Cython.Build import cythonize
ModuleNotFoundError: No module named 'Cython'

so apparently I had to install install Cython. Googling brought me to CellProfiler/centrosome#78 so it was simple to fix and now I think I got it to start compiling but I ran into another issue

$ python setup.py build_ext -- /usr/include/gsl/* -- /usr/lib/ --inplace
Compiling src/dfa.pyx because it changed.
Compiling src/dcca.pyx because it changed.
Compiling src/mfdfa.pyx because it changed.
Compiling src/ht.pyx because it changed.
[1/4] Cythonizing src/dcca.pyx
[2/4] Cythonizing src/dfa.pyx
[3/4] Cythonizing src/ht.pyx
[4/4] Cythonizing src/mfdfa.pyx
invalid command name '/usr/include/gsl/gsl_blas.h'

Apologies if I'm just doing something stupid. Just hoping to install fathon and try playing around with it.

Thanks so much!

f(alpha) > 1?

Hi there,

I was under the impression that when investigating multifractal spectra, f(alpha) should not rise above 1. Running the example notebook it looks like that f(alpha) > 1 for some (negative?) moments q.

I'm no expert on multifractal spectra, but I've been trying to apply the formalism using WTMM to some solar flare X-ray data for a while, using a Python adaptation from this paper 2007ApJ...662..691M. Usually when spectra make odd shapes like that, they are either noisy, or the algorithm is busted.

Thoughts and/or references?
I can put my code up on a public GitHub too if that would be helpful.

Best
William

Issue in Plotting 1st graph

Hy. Your code is amazing.
I am trying to implement MFDFA.py code for my data series. But the first graph of this file is plotting values from 3 to 7 on X-axis
i.e. ln(n). But I want to plot this graph against number of days i.e. 10- 1000 (according to my data). So, where I should make a change. Kindly guide

File locations in tests

Since the text files live in the test directory should these lines be changed to, e.g. ts1 = np.loadtxt('ts1.txt')?

fathon/tests/test_fathon.py

Lines 8 to 12 in ed981f6

	ts1 = np.loadtxt('./tests/ts1.txt')
	ts1 = fathon.toAggregated(ts1)
	ts2 = np.loadtxt('./tests/ts2.txt')
	ts2 = fathon.toAggregated(ts2)
	ts3 = np.loadtxt('./tests/ts3.txt')

Possible to have automated installation through pip or conda?

I wonder if providing a Python package installable via pip or conda would make fathon more accessible and easier to install. I'm not super familiar with either but because of the C depdencies, presumably conda is the better option?

GSL seems to be a pre-requisite which is available through most Linux package managers. Installing fathon on Windows might prove difficult and it looks like you might need to install all of Cygwin just to get GSL to install fathon. I might mention this as most Windows users have no idea what Cygwin is.

I was not able to install fathon myself.

I believe the installation instructions are unfriendly. fathon seems much harder to install for me than the vast majority of Python packages, many of them which depend on C libraries too.

Besides having to manually install or compile GSL, you also need to know where include and library files are placed on your operating system, and you need to know the "standard location of Python packages" for your particular OS and Python environment combination.

I think this is a huge barrier to usability and most Python users won't be able to install fathon.

How to explain H>1 calculated by DFA and MFDFA

I replaced the data for the example (DFA and MFDFA), but I found that the calculated H value was greater than 1. In theory, H should be at [0,1], but what does the test result H>1 mean

Few questions about the tests

As part of openjournals/joss-reviews#1828 my only remaining concern is regarding the tests. Perhaps my ignorance of DFA is showing but I'm actually not sure how fathon is being tested. Take the first test for example:

ts1 = np.loadtxt('./tests/ts1.txt')
ts1 = fathon.toAggregated(ts1)

def test_dfa():
    pydfa = fathon.DFA(ts1)
    n1, F1 = pydfa.computeFlucVec(10, nMax=200, revSeg=True)
    H1, H_int1 = pydfa.fitFlucVec()

    assert math.isclose(H1, 0.7982194289592676)

1. What is the data contained in ts1.txt? It looks like random numbers but maybe it's real data? Is it e.g. normally distributed?
2. What is being tested? I assume the test is computing a Hurst exponent H1 and the test is that H1 comes out correct?
3. Where did the magic number 0.7982194289592676 come from? Is it common to compute Hurst exponents to 16 significant figures? Why do you expect this exact value for H1? Does it come from some analytic expression or theory? Or is this value produced by fathon itself, in which case is this a regression test?

examples require updating

Hi @stfbnc @danielskatz

Apologies but i think the examples require updating.
Best,
Andrew

pip3?

Hi!
I just tried to install fathon via pip3 and got a "No matching distribution found for fathon".
Is that to be expected?
Thanks in advance!
Fernando