fathon

https://github.com/stfbnc/fathon
Admin
fathon is a Python package for fast computation of Detrended Fluctuation Analysis (DFA) and related...
Tokens:29,186
Snippets:277
Trust Score:6.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Usage Examples

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.MFDCCA.html

Provides examples of how to use the MFDCCA class and its methods.

```APIDOC
## Usage examples

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)
b = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)
b = fu.toAggregated(b)

#initialize mfdfa object
pymfdcca = fathon.MFDCCA(a, b)
#compute fluctuation function and generalized Hurst exponents
wins = fu.linRangeByStep(10, 2000)
n, F = pymfdcca.computeFlucVec(wins, np.arange(-3, 4, 0.1), revSeg=True, polOrd=1)
list_H, list_H_intercept = pymfdcca.fitFlucVec()

#compute mass exponents
tau = pymfdcca.computeMassExponents()

#compute multifractal spectrum
alpha, mfSpect = pymfdcca.computeMultifractalSpectrum()
```
```

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

### Install Fathon Package

Source: https://context7.com/stfbnc/fathon/llms.txt

Install the fathon package using pip. Ensure you have the correct Python and NumPy versions.

```bash
pip install fathon
```

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

### MFDCCA Usage Example

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.MFDCCA.rst.txt

This example demonstrates the typical workflow for using the MFDCCA class. It involves initializing the object with two time series, computing the fluctuation vector, fitting it to obtain generalized Hurst exponents, and then calculating mass exponents and the multifractal spectrum.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)
b = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)
b = fu.toAggregated(b)

#initialize mfdfa object
pymfdcca = fathon.MFDCCA(a, b)
#compute fluctuation function and generalized Hurst exponents
wins = fu.linRangeByStep(10, 2000)
n, F = pymfdcca.computeFlucVec(wins, np.arange(-3, 4, 0.1), revSeg=True, polOrd=1)
list_H, list_H_intercept = pymfdcca.fitFlucVec()

#compute mass exponents
tau = pymfdcca.computeMassExponents()

#compute multifractal spectrum
alpha, mfSpect = pymfdcca.computeMultifractalSpectrum()
```

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

### MFDFA Usage Example

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.MFDFA.rst.txt

Demonstrates the initialization and core computation steps of the MFDFA class. Requires numpy and fathon libraries. Ensure the time series is zero-mean cumulative sum.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)

#initialize mfdfa object
pymfdfa = fathon.MFDFA(a)
#compute fluctuation function and generalized Hurst exponents
wins = fu.linRangeByStep(10, 2000)
n, F = pymfdfa.computeFlucVec(wins, np.arange(-3, 4, 0.1), revSeg=True, polOrd=1)
list_H, list_H_intercept = pymfdfa.fitFlucVec()

#compute mass exponents
tau = pymfdfa.computeMassExponents()

#compute multifractal spectrum
alpha, mfSpect = pymfdfa.computeMultifractalSpectrum()
```

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

### DFA Fluctuation Analysis with fathon

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.DFA.rst.txt

This example demonstrates initializing a DFA object with aggregated time series data, computing the fluctuation function over a range of window sizes, and fitting the fluctuation function to estimate the Hurst exponent. It also shows how to compute the Hurst exponent for multiple specified ranges.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)

#initialize dfa object
pydfa = fathon.DFA(a)
#compute fluctuation function and Hurst exponent
wins = fu.linRangeByStep(10, 2000)
n, F = pydfa.computeFlucVec(wins, revSeg=True, polOrd=3)
H, H_intercept = pydfa.fitFlucVec()

#compute Hurst exponent in different ranges
limits_list = np.array([[15,2000], [200,1000]], dtype=int)
list_H, list_H_intercept = pydfa.multiFitFlucVec(limits_list)
```

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

### Get Fathon Version

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Retrieves the installed version of the Fathon library.

```python
fathon.__version__
```

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

### DCCA Usage Example

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.DCCA.rst.txt

Demonstrates initializing a DCCA object with time series data, computing fluctuation functions and Hurst exponents, and analyzing them across different ranges. Also shows how to compute the rho index.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)
b = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)
b = fu.toAggregated(b)

#initialize non-empty dcca object
pydcca = fathon.DCCA(a, b)
#compute fluctuation function and Hurst exponent
wins = fu.linRangeByStep(20, 1000, step=50)
n, F = pydcca.computeFlucVec(wins, polOrd=1)
H, H_intercept = pydcca.fitFlucVec()

#compute Hurst exponent in different ranges
limits_list = np.array([[20,120], [220,870]], dtype=int)
list_H, list_H_intercept = pydcca.multiFitFlucVec(limits_list)

#compute rho index
wins = fu.linRangeByStep(20, 100, step=50)
n, rho = pydcca.computeRho(wins, polOrd=1)
```

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

### fathon.fathonUtils.linRangeByStep

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fu/fathonUtils.linRangeByStep.md

Generates an array of linearly separated elements between a start and end value with a specified step.

```APIDOC
## fathon.fathonUtils.linRangeByStep(start, end, step=1)

### Description
Array of linearly separated elements.

### Parameters
#### Path Parameters
- **start** (int) - Required - Smallest element.
- **end** (int) - Required - Biggest element.
- **step** (int) - Optional - Step between two consecutive elements (default : 1).

### Returns
Array of linearly separated elements.

### Return type
numpy ndarray

### Usage examples
```python
from fathon import fathonUtils as fu

#linearly separated elements
a = fu.linRangeByStep(10, 100, step=2)
```
```

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

### linRangeByStep

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.linRangeByStep.rst.txt

Generates a list of numbers starting from a given value, incrementing by a specified step, up to a maximum value.

```APIDOC
## linRangeByStep

### Description
Generates a list of linearly separated elements.

### Signature
`linRangeByStep(start, stop, step=1)`

### Parameters
*   **start** (int) - The starting value of the range.
*   **stop** (int) - The maximum value of the range (inclusive).
*   **step** (int, optional) - The step to increment by. Defaults to 1.

### Usage Example
```python
from fathon import fathonUtils as fu

# Linearly separated elements
a = fu.linRangeByStep(10, 100, step=2)
print(a)
# Expected output: [10, 12, 14, ..., 98, 100]
```
```

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

### Generate Linearly Separated Elements

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.linRangeByStep.rst.txt

Use linRangeByStep to create a sequence of numbers starting from a given value, ending before another, with a specified step. This is useful for creating ranges with custom increments.

```python
from fathon import fathonUtils as fu

#linearly separated elements
a = fu.linRangeByStep(10, 100, step=2)
```

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

### HT Class Initialization and computeHt Method

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.HT.rst.txt

Demonstrates how to initialize the HT object with aggregated time series data and compute the time-dependent Hurst exponent using the computeHt method. It also shows the usage of optional parameters like mfdfaPolOrd and polOrd.

```APIDOC
## Class: HT

### Description
Represents a time series object for Hurst exponent calculation.

### Methods

#### `__init__(self, ts)`
Initializes the HT object with aggregated time series data.

- **ts** (numpy.ndarray): The aggregated time series data.

#### `computeHt(self, nWin=[100, 200, 1000], mfdfaPolOrd=1, polOrd=1)`
Computes the time-dependent Hurst exponent.

- **nWin** (list of int, optional): A list of window sizes to use for the computation. Defaults to [100, 200, 1000].
- **mfdfaPolOrd** (int, optional): The order of the polynomial for Multifractal Detrended Fluctuation Analysis. Defaults to 1.
- **polOrd** (int, optional): The order of the polynomial for Detrended Fluctuation Analysis. Defaults to 1.

### Usage Example

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

# time series
a = np.random.randn(10000)

# zero-mean cumulative sum
a = fu.toAggregated(a)

# initialize ht object
pyht = fathon.HT(a)
# compute time-dependent Hurst exponent
ht = pyht.computeHt([100, 200, 1000], mfdfaPolOrd=1, polOrd=1)
```
```

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

### fathon.fathonUtils.linRangeByCount

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fu/fathonUtils.linRangeByCount.md

Generates an array of linearly separated elements between a start and end value. The number of elements can be specified by the count parameter. If count is not provided, it defaults to the total number of integers between start and end (inclusive).

```APIDOC
## fathon.fathonUtils.linRangeByCount(start, end, count=-1)

### Description
Array of linearly separated elements.

### Parameters
#### Path Parameters
* **start** (int) - Required - Smallest element.
* **end** (int) - Required - Biggest element.
* **count** (int) - Optional - Number of elements (default : end - start + 1).

### Returns
Array of linearly separated elements.

### Return type
numpy ndarray

## Usage examples

```python
from fathon import fathonUtils as fu

#linearly separated elements
a = fu.linRangeByCount(10, 100, count=42)
```
```

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

### FathonUtils: Generate Power-of-2 Window Sizes

Source: https://context7.com/stfbnc/fathon/llms.txt

Generate sequences of window sizes as powers of a base using `powRangeByStep` (fixed exponent step) or `powRangeByCount` (fixed number of points).

```python
import numpy as np
from fathon import fathonUtils as fu

# --- powRangeByStep ---
# Window sizes as powers of 2: [2^4, 2^5, ..., 2^11] = [16, 32, ..., 2048]
win_pow_step = fu.powRangeByStep(4, 11)          # base=2, step=1
win_pow_step3 = fu.powRangeByStep(2, 10, base=3) # powers of 3

# --- powRangeByCount ---
# Exactly 8 window sizes as powers of 2 between exponents 4 and 11.
win_pow_count = fu.powRangeByCount(4, 11, count=8)
```

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

### linRangeByCount

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.linRangeByCount.rst.txt

Generates a list of linearly separated numbers between a start and end value, with a specified count.

```APIDOC
## linRangeByCount

### Description
Generates a list of linearly separated numbers between a start and end value, with a specified count.

### Parameters

#### Arguments

*   **start** (int) - The starting value of the range.
*   **end** (int) - The ending value of the range.
*   **count** (int) - The desired number of elements in the generated list.

### Usage Example

```python
from fathon import fathonUtils as fu

# linearly separated elements
a = fu.linRangeByCount(10, 100, count=42)
```

### Returns

*   list[int] - A list of integers representing the linearly separated range.
```

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

### FathonUtils: Generate Linearly Spaced Window Sizes

Source: https://context7.com/stfbnc/fathon/llms.txt

Generate sequences of window sizes using `linRangeByStep` (fixed step) or `linRangeByCount` (fixed number of points). Useful for DFA/DCCA analysis.

```python
import numpy as np
from fathon import fathonUtils as fu

# --- linRangeByStep ---
# Window sizes [10, 11, 12, ..., 2000] (step=1 by default).
win_step = fu.linRangeByStep(10, 2000)          # 1991 values
win_step50 = fu.linRangeByStep(20, 1000, step=50)  # [20, 70, 120, ..., 970]

# --- linRangeByCount ---
# Exactly 50 linearly spaced window sizes between 10 and 2000.
win_count = fu.linRangeByCount(10, 2000, count=50)
```

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

### fathonUtils - Preprocessing and Window-Size Helpers

Source: https://context7.com/stfbnc/fathon/llms.txt

Provides essential preprocessing functions and window-size generators for Fathon algorithms.

```APIDOC
## fathonUtils

### Description
Provides essential preprocessing functions and window-size generators used as inputs to all algorithm classes.

### Functions

#### subtractMean

- **Description**: Returns the input vector with its mean removed (NaN-safe).
- **Usage**: `fu.subtractMean(raw_array)`

#### toAggregated

- **Description**: Subtracts the mean then takes the cumulative sum — the standard "profile" transformation required before DFA/DCCA analysis.
- **Usage**: `fu.toAggregated(time_series)`

#### linRangeByStep

- **Description**: Generates a linearly spaced range of window sizes with a specified step.
- **Usage**: `fu.linRangeByStep(start, stop, step=1)`

#### linRangeByCount

- **Description**: Generates a specified count of linearly spaced window sizes between a start and stop.
- **Usage**: `fu.linRangeByCount(start, stop, count)`

#### powRangeByStep

- **Description**: Generates window sizes as powers of a given base, with a specified step for exponents.
- **Usage**: `fu.powRangeByStep(exp_start, exp_stop, base=2, step=1)`

#### powRangeByCount

- **Description**: Generates a specified count of window sizes as powers of a given base between exponent start and stop.
- **Usage**: `fu.powRangeByCount(exp_start, exp_stop, count, base=2)`

#### getObjectMember

- **Description**: Retrieves a specific attribute from a previously saved .fathon binary file.
- **Usage**: `fu.getObjectMember(filepath, member_name)`
```

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

### DFA Initialization and Analysis

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fathon.DFA.md

Initializes the DFA object with a time series, computes the fluctuation function, and fits it to determine the Hurst exponent. Ensure the time series is preprocessed (e.g., zero-mean cumulative sum) before initialization.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)

#initialize dfa object
pydfa = fathon.DFA(a)
#compute fluctuation function and Hurst exponent
wins = fu.linRangeByStep(10, 2000)
n, F = pydfa.computeFlucVec(wins, revSeg=True, polOrd=3)
H, H_intercept = pydfa.fitFlucVec()
```

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

### Initialize MFDCCA (Fathon)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Initializes the Multifractal Detrended Cross-Correlation Analysis (MFDCCA) object with two time series, 'a' and 'b'.

```python
pymfdcca = fathon.MFDCCA(a, b)
```

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

### DFA: Fit Fluctuation Vector to Get Hurst Exponent

Source: https://context7.com/stfbnc/fathon/llms.txt

Use `fitFlucVec` to perform a linear fit on the log-log plot of fluctuation values (F) versus window size (n) to extract the Hurst exponent (H).

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

# Prepare time series (profile = mean-subtracted cumulative sum)
ts = np.random.randn(10000)
profile = fu.toAggregated(ts)

pydfa = fathon.DFA(profile)

win = fu.linRangeByStep(10, 2000)
n, F = pydfa.computeFlucVec(win, polOrd=1, revSeg=True, unbiased=False)

# --- fitFlucVec ---
# Fits log(F) vs log(n) in [nStart, nEnd]; returns slope (H) and intercept.
H, intercept = pydfa.fitFlucVec(nStart=10, nEnd=2000, logBase=np.e, verbose=True)
# Output (verbose): "Hurst exponent H = 0.50 +/- 0.01"
print(f"Hurst exponent: {H:.4f}")
```

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

### Generate powers with a step

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.powRangeByStep.rst.txt

Use this function to create a sequence of numbers by raising a base to exponents that increase linearly with a specified step. Ensure the fathonUtils module is imported as fu.

```python
from fathon import fathonUtils as fu

#elements given by `base` raised to linearly separated exponents
a = fu.powRangeByStep(10, 1000, step=2, base=3)
```

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

### fathon.HT Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fathon.HT.md

Initializes the HT class with a time series.

```APIDOC
## class fathon.HT(tsVec)

### Description
Time-dependent local Hurst exponent class.

### Parameters
* **tsVec** (*iterable*) – Time series used for the analysis.
```

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

### Initialize MFDFA Object

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Initializes a Multifractal Detrended Fluctuation Analysis (MFDFA) object.

```python
pymfdfa = fathon.MFDFA(a)
```

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

### Set MFDFA Parameters

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Defines window sizes, orders of the generalized Hurst exponent (q), reversal of segments, and polynomial order.

```python
winSizes = fu.linRangeByStep(10, 2000)
qs = np.arange(-3, 4, 0.1)
revSeg = True
polOrd = 1
```

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

### Set DFA Parameters

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Defines window sizes, whether to use reversed segments, and the polynomial order for DFA.

```python
winSizes = fu.linRangeByStep(10, 2000)
revSeg = True
polOrd = 3
```

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

### Import Libraries

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Imports necessary libraries for numerical operations, plotting, and the Fathon library.

```python
import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline
```

```python
import fathon
from fathon import fathonUtils as fu
```

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

### Initialize HT Object

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Initializes a Hurst Exponent (HT) object with a time series.

```python
pyht = fathon.HT(a)
```

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

### FathonUtils: Load Object Members from File

Source: https://context7.com/stfbnc/fathon/llms.txt

Retrieve specific attributes (like window sizes or fluctuation values) from a saved `.fathon` binary file using `getObjectMember`.

```python
import numpy as np
from fathon import fathonUtils as fu

# --- getObjectMember ---
# Retrieve a specific attribute from a previously saved .fathon binary file.
# (See saveObject() on each class for how files are created.)
n_vec = fu.getObjectMember('my_dfa_result.fathon', 'winSizes')
F_vec = fu.getObjectMember('my_dfa_result.fathon', 'F')
```

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

### fathon.DCCA Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fathon.DCCA.md

Initializes the DCCA class with two time series.

```APIDOC
## fathon.DCCA(tsVec1=[], tsVec2=[])

### Description
Initializes the Detrended Cross-Correlation Analysis class with two time series.

### Parameters
* **tsVec1** (*iterable*) – First time series used for the analysis.
* **tsVec2** (*iterable*) – Second time series used for the analysis.
```

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

### fathon.DFA

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fathon.DFA.md

Initializes the DFA class with a time series. The time series should be preprocessed (e.g., zero-mean cumulative sum).

```APIDOC
## class fathon.DFA(tsVec)

### Description
Detrended Fluctuation Analysis class.

### Parameters
* **tsVec** (*iterable*) – Time series used for the analysis.
```

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

### saveObject

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.DCCA.html

Saves the current object state to a binary file. The '.fathon' extension will be appended to the provided file name.

```APIDOC
## saveObject(outFileName)

### Description
Save current object state to binary file.

### Parameters
#### Path Parameters
- **outFileName** (str) - Required - Output binary file. .fathon extension will be appended to the file name.
```

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

### saveObject Method

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.HT.html

Saves the current object state to a binary file.

```APIDOC
## saveObject(outFileName)

### Description
Save current object state to binary file.

### Parameters
* **outFileName** (str) - Output binary file. .fathon extension will be appended to the file name.
```

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

### Set DCCA Parameters

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Defines window sizes and polynomial order for DCCA.

```python
winSizes = fu.linRangeByStep(20, 1000, step=50)
polOrd = 1
```

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

### Save and Load MFDFA Object

Source: https://context7.com/stfbnc/fathon/llms.txt

Saves the MFDFA analysis results to a file and demonstrates loading a member. The saved object is stored in a '.fathon' file.

```python
# --- saveObject ---
pymfdfa.saveObject('mfdfa_result')
tau_saved = fu.getObjectMember('mfdfa_result.fathon', 'tau')
```

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

### Initialize and Compute Fluctuation Function and Hurst Exponent

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.DCCA.html

Initializes a DCCA object with two time series, computes the fluctuation vector, and fits the fluctuation vector to determine the Hurst exponent. Requires pre-processed time series.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)
b = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)
b = fu.toAggregated(b)

#initialize non-empty dcca object
pydcca = fathon.DCCA(a, b)
#compute fluctuation function and Hurst exponent
wins = fu.linRangeByStep(20, 1000, step=50)
n, F = pydcca.computeFlucVec(wins, polOrd=1)
H, H_intercept = pydcca.fitFlucVec()
```

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

### Compute Generalized Hurst Exponents (Fathon)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Computes the generalized Hurst exponents (Ht) for a given set of scales using the pyht module. Requires pre-defined scales and optional polynomial orders for detrending.

```python
%%time
ht = pyht.computeHt(scales, mfdfaPolOrd=mfdfaPolOrd, polOrd=polOrd)
```

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

### MFDCCA Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.MFDCCA.html

Initializes the MFDCCA class with two time series.

```APIDOC
## MFDCCA Class

### Description
MultiFractal Detrended Cross-Correlation Analysis class.

### Parameters
*   **tsVec1** (_iterable_) – First time series used for the analysis.
*   **tsVec2** (_iterable_) – Second time series used for the analysis.

### Method Signature
`fathon.MFDCCA(tsVec1, tsVec2=[])`
```

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

### Compute Time-Dependent Hurst Exponent using fathon.HT

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.HT.rst.txt

Initializes an HT object with aggregated time series data and computes the time-dependent Hurst exponent for specified time scales. Requires numpy and fathon libraries.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

#time series
a = np.random.randn(10000)

#zero-mean cumulative sum
a = fu.toAggregated(a)

#initialize ht object
pyht = fathon.HT(a)
#compute time-dependent Hurst exponent
ht = pyht.computeHt([100, 200, 1000], mfdfaPolOrd=1, polOrd=1)
```

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

### Initialize DFA Object

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Initializes a DFA object with an aggregated time series.

```python
pydfa = fathon.DFA(a)
```

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

### Initialize DCCA Threshold Object

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Initializes a DCCA object for thresholding analysis.

```python
pythresh = fathon.DCCA()
```

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

### Plot Generalized Hurst Exponents h(q) (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Visualizes the generalized Hurst exponent h(q) as a function of the order q, derived from the MFDCCA analysis.

```python
plt.plot(qs, list_H, 'ro-')
plt.xlabel('q', fontsize=14)
plt.ylabel('h(q)', fontsize=14)
plt.title('h(q)', fontsize=14)
plt.show()
```

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

### fathonUtils Functions

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.fathonUtils.html

This section lists the available utility functions within the fathonUtils module.

```APIDOC
## fathonUtils Module

This module provides various utility functions for data processing and analysis within the fathon library.

### Available Functions:

*   **subtractMean**: Subtracts the mean from a dataset.
*   **toAggregated**: Aggregates data into a specified format.
*   **linRangeByStep**: Generates a linear range with a specified step.
*   **linRangeByCount**: Generates a linear range with a specified count.
*   **powRangeByStep**: Generates a power-law range with a specified step.
*   **powRangeByCount**: Generates a power-law range with a specified count.
*   **getObjectMember**: Retrieves a member from an object.
```

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

### MFDCCA Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fathon.MFDCCA.md

Initializes the MFDCCA class with two time series. The second time series is optional.

```APIDOC
## fathon.MFDCCA(tsVec1, tsVec2=[])

### Description
MultiFractal Detrended Cross-Correlation Analysis class.

### Parameters
* **tsVec1** (*iterable*) – First time series used for the analysis.
* **tsVec2** (*iterable*) – Second time series used for the analysis.
```

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

### powRangeByStep

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.powRangeByStep.rst.txt

Generates elements by `base` raised to linearly separated exponents.

```APIDOC
## powRangeByStep

### Description
Generates a list of numbers where each element is the `base` raised to a power. The exponents are linearly separated by the specified `step`.

### Parameters

*   **base** (int or float) - The base number.
*   **end** (int or float) - The upper limit for the exponent.
*   **step** (int or float, optional) - The increment between exponents. Defaults to 1.

### Usage Example

```python
from fathon import fathonUtils as fu

# elements given by `base` raised to linearly separated exponents
a = fu.powRangeByStep(10, 1000, step=2, base=3)
```
```

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

### fathon.fathonUtils.powRangeByStep

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fu/fathonUtils.powRangeByStep.html

Calculates an array of elements given by `base` raised to linearly separated exponents.

```APIDOC
## fathon.fathonUtils.powRangeByStep

### Description
Array of elements given by base raised to linearly separated exponents.

### Signature
fathon.fathonUtils.powRangeByStep(_start_, _end_, _step_=1, _base_=2)

### Parameters
#### Path Parameters
- **start** (int) - Smallest element.
- **end** (int) - Biggest element.
- **step** (int) - Step between two consecutive exponents (default : 1).
- **base** (int) - Base of the exponential (default : 2).

### Returns
Array of elements given by base raised to linearly separated exponents.

### Return Type
numpy ndarray

### Usage Examples
```python
from fathon import fathonUtils as fu

#elements given by `base` raised to linearly separated exponents
a = fu.powRangeByStep(10, 1000, step=2, base=3)
```
```

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

### MFDFA Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.MFDFA.html

Initializes the MFDFA class with a time series vector.

```APIDOC
## class fathon.MFDFA(tsVec)

### Description
MultiFractal Detrended Fluctuation Analysis class.

### Parameters
* **tsVec** (_iterable_) – Time series used for the analysis.
```

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

### DFA Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.DFA.html

Initializes the DFA class with a time series vector.

```APIDOC
## DFA Class

### Description
Initializes the Detrended Fluctuation Analysis class with a time series vector.

### Parameters
#### Parameters
- **tsVec** (iterable) - Time series used for the analysis.
```

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

### Set HT Parameters

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Defines scales for analysis and polynomial orders for HT.

```python
scales = [100, 200, 1000]
mfdfaPolOrd = 1
polOrd = 1
```

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

### Plot Generalized Hurst Exponents (Fathon)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Visualizes the computed generalized Hurst exponents (Ht) for different scales. Adjusts plot layout based on the number of scales.

```python
plt.rc('font', size=14)
plt.figure(figsize=(10, 6))
w = 3 if len(scales) >= 3 else len(scales)
h = np.ceil(len(scales)/3)
for i, scale in enumerate(scales):
    plt.subplot(h, w, i+1)
    plt.plot(np.arange(1, len(ht[i, 0:len(a)-scale+1])+1), ht[i, 0:len(a)-scale+1],
             'r-', label='scale = {}'.format(scale))
    plt.xlabel('window number', fontsize=14)
    plt.ylabel('$h_t$', fontsize=14)
    plt.legend(loc=0, fontsize=14)
plt.subplots_adjust(hspace=0.6, wspace=0.3)
```

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

### FathonUtils: Create Time Series Profile for DFA

Source: https://context7.com/stfbnc/fathon/llms.txt

Use `toAggregated` to subtract the mean and compute the cumulative sum of a time series, creating the 'profile' required for DFA and DCCA.

```python
import numpy as np
from fathon import fathonUtils as fu

# --- toAggregated ---
# Subtracts the mean then takes the cumulative sum — the standard
# "profile" transformation required before DFA/DCCA analysis.
ts = np.random.randn(10000)
profile = fu.toAggregated(ts)  # shape (10000,), dtype float64
```

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

### DFA: Save DFA Object to File

Source: https://context7.com/stfbnc/fathon/llms.txt

Use `saveObject` to serialize the entire DFA computation results (window sizes, fluctuations, exponents) into a binary `.fathon` file for later retrieval.

```python
import numpy as np
import fathon
from fathon import fathonUtils as fu

# Prepare time series (profile = mean-subtracted cumulative sum)
ts = np.random.randn(10000)
profile = fu.toAggregated(ts)

pydfa = fathon.DFA(profile)

win = fu.linRangeByStep(10, 2000)
n, F = pydfa.computeFlucVec(win, polOrd=1, revSeg=True, unbiased=False)
H, intercept = pydfa.fitFlucVec(nStart=10, nEnd=2000, logBase=np.e, verbose=True)

# --- saveObject ---
# Serializes the full DFA object (n, F, H, etc.) to a binary .fathon file.
pydfa.saveObject('dfa_result')
# Creates 'dfa_result.fathon'; reload specific fields later with getObjectMember.
H_saved = fu.getObjectMember('dfa_result.fathon', 'H')
```

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

### Save and Load MFDCCA Object

Source: https://context7.com/stfbnc/fathon/llms.txt

Saves the MFDCCA analysis results to a file and demonstrates loading a member. The saved object is stored in a '.fathon' file.

```python
# --- saveObject ---
pymfdcca.saveObject('mfdcca_result')
alpha_saved = fu.getObjectMember('mfdcca_result.fathon', 'singStrengths')
```

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

### DCCA Class Initialization

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.DCCA.html

Initializes the DCCA class with two time series.

```APIDOC
## DCCA Class

### Description

Detrended Cross-Correlation Analysis class.

### Parameters

*   **tsVec1** (_iterable_) – First time series used for the analysis.
*   **tsVec2** (_iterable_) – Second time series used for the analysis.

### Example

```python
from fathon import DCCA

dcca = DCCA(tsVec1, tsVec2)
```
```

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

### Plot Mass Exponents tau(q) (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Visualizes the mass exponents tau(q) as a function of the order q, obtained from the MFDCCA analysis.

```python
plt.plot(qs, tau, 'ro-')
plt.xlabel('q', fontsize=14)
plt.ylabel('$\tau$(q)', fontsize=14)
plt.title('$\tau$(q)', fontsize=14)
plt.show()
```

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

### fathon.MFDFA

Source: https://github.com/stfbnc/fathon/blob/master/docs/fun_class/fathon.MFDFA.md

Initializes the MFDFA class with a time series vector.

```APIDOC
## class fathon.MFDFA(tsVec)

### Description
MultiFractal Detrended Fluctuation Analysis class.

### Parameters
* **tsVec** (*iterable*) – Time series used for the analysis.
```

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

### Initialize DCCA Object

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Initializes a Detrended Cross-Correlation Analysis (DCCA) object with two time series.

```python
pydcca = fathon.DCCA(a, b)
```

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

### Save and Load HT Results

Source: https://context7.com/stfbnc/fathon/llms.txt

Saves the computed HT results to a file and then loads them back using utility functions. This is useful for checkpointing expensive computations and ensuring reproducibility in analysis pipelines.

```python
# --- saveObject ---
pyht.saveObject('ht_result')
ht_saved = fu.getObjectMember('ht_result.fathon', 'ht')
```

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

### Fit Fluctuation Functions (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Fits the fluctuation functions to determine the generalized Hurst exponents (h(q)) and their intercepts. This is a necessary step before plotting.

```python
list_H, list_H_intercept = pymfdcca.fitFlucVec()
```

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

### multiFitFlucVec Method

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.DFA.html

Fits the fluctuations values in different intervals simultaneously.

```APIDOC
## multiFitFlucVec Method

### Description
Fit of the fluctuations values in different intervals at the same time.

### Parameters
#### Parameters
- **limitsList** (numpy ndarray) - kx2 array with the sizes of k starting and ending windows used to fit F.
- **logBase** (float, optional) - Base of the logarithm for the log-log fit of n vs F (default : e).
- **verbose** (bool, optional) - Verbosity (default : False).

### Returns
- **numpy ndarray** - Slopes of the fits.
- **numpy ndarray** - Intercepts of the fits.
```

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

### saveObject Method

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.HT.rst.txt

Details the saveObject method, which is used to save the computed Hurst exponent data to a file.

```APIDOC
## Method: saveObject

### Description
Saves the computed Hurst exponent data to a file.

### Parameters

- **obj** (object): The object containing the data to be saved.
- **filename** (str): The name of the file to save the data to.

### Usage Example

```python
# Assuming 'pyht' is an instance of HT and 'ht' contains the computed data
pyht.saveObject(ht, 'hurst_exponent_data.pkl')
```
```

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

### MFDCCA Class Methods

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.MFDCCA.rst.txt

This section details the core methods available within the MFDCCA class for performing multifractal analysis.

```APIDOC
## MFDCCA Class

Provides methods for Multifractal Detrended Cross-Correlation Analysis (MFDCCA).

### Methods

- **`computeFlucVec(wins, q, revSeg=False, polOrd=1)`**: Computes the fluctuation function and generalized Hurst exponents.
- **`computeMassExponents()`**: Computes the mass exponents (tau).
- **`computeMultifractalSpectrum()`**: Computes the multifractal spectrum (alpha and F(alpha)).
- **`fitFlucVec()`**: Fits the fluctuation vector to obtain generalized Hurst exponents and their intercepts.
- **`saveObject(filename)`**: Saves the MFDCCA object to a file.
```

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

### Save and Load DCCA Object

Source: https://context7.com/stfbnc/fathon/llms.txt

Saves the DCCA analysis results to a file and demonstrates loading a member. The saved object is stored in a '.fathon' file.

```python
# --- saveObject ---
pydcca.saveObject('dcca_result')
rho_saved = fu.getObjectMember('dcca_result.fathon', 'rho')
```

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

### DCCA Rho Thresholds Computation

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.DCCA.rst.txt

Shows how to initialize an empty DCCA object and compute confidence levels for the rho index. This is useful for statistical significance testing.

```python
#initialize empty dcca object
pythresh = fathon.DCCA()
#compute confidence levels
wins = fu.linRangeByStep(4, 100)
n, cInt1, cInt2 = pythresh.rhoThresholds(300, wins, 100, 0.95, polOrd=1)
```

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

### Compute MFDFA Mass Exponents

Source: https://context7.com/stfbnc/fathon/llms.txt

Computes the mass exponents τ(q) using the formula τ(q) = q·h(q) - 1. Requires fitFlucVec() to have been called first.

```python
# --- computeMassExponents ---
# Requires fitFlucVec() to have been called first.
# Returns τ(q) = q·h(q) - 1
tau = pymfdfa.computeMassExponents()  # shape: (len(qs),)
```

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

### fitFlucVec Method

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.DFA.html

Fits the computed fluctuations values to determine the Hurst exponent.

```APIDOC
## fitFlucVec Method

### Description
Fit of the fluctuations values.

### Parameters
#### Parameters
- **nStart** (int, optional) - Size of the smaller window used to fit F (default : first value of n).
- **nEnd** (int, optional) - Size of the bigger window used to fit F (default : last value of n).
- **logBase** (float, optional) - Base of the logarithm for the log-log fit of n vs F (default : e).
- **verbose** (bool, optional) - Verbosity (default : False).

### Returns
- **float** - Slope of the fit.
- **float** - Intercept of the fit.
```

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

### Compute Mass Exponents (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Computes the mass exponents (tau(q)) for the MFDCCA analysis. These exponents characterize the scaling behavior of the moments of the time series.

```python
tau = pymfdcca.computeMassExponents()
```

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

### computeHt Method

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.HT.html

Computes the time-dependent local Hurst exponent at each scale using Ihlen’s approach.

```APIDOC
## computeHt(scales, polOrd=1, mfdfaPolOrd=1, q0Fit=[], verbose=False)

### Description
Computation of the time-dependent local Hurst exponent at each scale, using Ihlen’s approach.

### Parameters
* **scales** (int or iterable or numpy ndarray) - Window’s sizes used for the computation of the time-dependent local Hurst exponent.
* **polOrd** (int, optional) - Order of the polynomial to be fitted in each window (default : 1).
* **mfdfaPolOrd** (int, optional) - Order of the polynomial to be fitted to MFDFA’s fluctuations at q = 0 (default : 1).
* **q0Fit** (iterable or numpy ndarray of floats, optional) - MFDFA’s Hurst exponent at order q = 0 and the corresponding intercept of the fit, [hq0, hq0_intercept]. These values must come from a log-log fit, with the log base equal to e. If not empty, it will be directly used to compute the time-dependent local Hurst exponent, ignoring mfdfaPolOrd value (default : []).
* **verbose** (bool, optional) - Verbosity (default : False).

### Returns
Time-dependent local Hurst exponent.

### Return Type
numpy ndarray
```

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

### Compute MFDFA Mass Exponents

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Computes the mass exponents tau(q) from the MFDFA results.

```python
tau = pymfdfa.computeMassExponents()
```

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

### Compute Multifractal Spectrum (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Computes the multifractal spectrum (f(alpha)) from the mass exponents derived during MFDCCA analysis. This spectrum describes the distribution of scaling exponents.

```python
alpha, mfSpect = pymfdcca.computeMultifractalSpectrum()
```

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

### Plot MFDFA h(q) Spectrum

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Plots the generalized Hurst exponent h(q) as a function of q.

```python
plt.plot(qs, list_H, 'ro-')
plt.xlabel('q', fontsize=14)
plt.ylabel('h(q)', fontsize=14)
plt.title('h(q)', fontsize=14)
```

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

### Plot Multifractal Spectrum f(alpha) (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Visualizes the multifractal spectrum f(alpha) against the singularity spectrum alpha, providing insights into the multifractal properties of the time series.

```python
plt.plot(alpha, mfSpect, 'ro-')
plt.xlabel('$\alpha$', fontsize=14)
plt.ylabel('f($\alpha$)', fontsize=14)
plt.title('f($\alpha$)', fontsize=14)
plt.show()
```

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

### computeMassExponents

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/fun_class/fathon.MFDFA.html

Computes the mass exponents.

```APIDOC
## MFDFA.computeMassExponents()

### Description
Computation of the mass exponents.

### Returns
Mass exponents.

### Return type
numpy ndarray
```

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

### Generate Linearly Separated Elements

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.linRangeByCount.rst.txt

Use linRangeByCount to create a list of numbers linearly separated by a specified count. Ensure fathonUtils is imported as fu.

```python
from fathon import fathonUtils as fu

#linearly separated elements
a = fu.linRangeByCount(10, 100, count=42)
```

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

### Plot DFA with Multiple Fits

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Visualizes DFA results, plotting the fluctuation function and fitted lines for different window size ranges.

```python
clrs = ['k', 'b', 'm', 'c', 'y']
stls = ['-', '--', '.-']
plt.plot(np.log(n), np.log(F), 'ro')
for i in range(len(list_H)):
    n_rng = np.arange(limits_list[i][0], limits_list[i][1]+1)
    plt.plot(np.log(n_rng), list_H_intercept[i]+list_H[i]*np.log(n_rng),
             clrs[i%len(clrs)]+stls[(i//len(clrs))%len(stls)], label='H = {:.2f}'.format(list_H[i]))
plt.xlabel('ln(n)', fontsize=14)
plt.ylabel('ln(F(n))', fontsize=14)
plt.title('DFA', fontsize=14)
plt.legend(loc=0, fontsize=14)
```

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

### Plot Log-Log Fluctuation Functions and Fits (MFDCCA)

Source: https://github.com/stfbnc/fathon/blob/master/examples/fathon_example.ipynb

Visualizes the log-log plot of fluctuation functions F(n) against window size n, along with the fitted linear regressions for selected q-values.

```python
plt.plot(np.log(n), np.log(F[0, :]), 'ro')
plt.plot(np.log(n), list_H_intercept[0]+list_H[0]*np.log(n), 'k-', label='h_{:.1f} = {:.2f}'.format(qs[0], list_H[0]))
half_idx = int(len(qs)/2)
plt.plot(np.log(n), np.log(F[half_idx, :]), 'co')
plt.plot(np.log(n), list_H_intercept[half_idx]+list_H[half_idx]*np.log(n),
         'k-', label='h_{:.1f} = {:.2f}'.format(qs[half_idx], list_H[half_idx]))
plt.plot(np.log(n), np.log(F[-1, :]), 'yo')
plt.plot(np.log(n), list_H_intercept[-1]+list_H[-1]*np.log(n), 'k-',
         label='h_{:.1f} = {:.2f}'.format(qs[-1], list_H[-1]))
plt.xlabel('ln(n)', fontsize=14)
plt.ylabel('ln(F(n))', fontsize=14)
plt.title('MFDCCA', fontsize=14)
plt.legend(loc=0, fontsize=14)
plt.show()
```

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

### MFDFA Class Methods

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fathon.MFDFA.rst.txt

This section details the methods available within the MFDFA class for performing multifractal analysis.

```APIDOC
## MFDFA Class

Provides methods for multifractal detrended fluctuation analysis.

### Methods

- **`computeFlucVec(wins, q, revSeg=False, polOrd=1)`**: Computes the fluctuation function and generalized Hurst exponents for a given set of window sizes and q-orders.
- **`computeMassExponents()`**: Computes the mass exponents (tau) from the fluctuation function.
- **`computeMultifractalSpectrum()`**: Computes the multifractal spectrum (alpha and MfSpect) from the mass exponents.
- **`fitFlucVec()`**: Fits the fluctuation vector to determine the generalized Hurst exponents and their intercepts.
- **`saveObject(path)`**: Saves the current state of the MFDFA object to a specified file path.
```

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

### Generate powers with a specific count

Source: https://github.com/stfbnc/fathon/blob/master/docs/_build/html/_sources/fun_class/fu/fathonUtils.powRangeByCount.rst.txt

Use `powRangeByCount` to generate elements by raising a `base` to linearly separated exponents. This is useful for creating sequences with exponential growth.

```python
from fathon import fathonUtils as fu

#elements given by `base` raised to linearly separated exponents
a = fu.powRangeByCount(10, 1000, base=3, count=42)
```

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

### Compute MFDCCA Mass Exponents

Source: https://context7.com/stfbnc/fathon/llms.txt

Computes the mass exponents τ(q) for MFDCCA. Requires fitFlucVec() to have been called first.

```python
# --- computeMassExponents ---
tau = pymfdcca.computeMassExponents()
```
Tokens:
Raw