Metadata-Version: 2.3
Name: fractal-analysis
Version: 0.3.2
Summary: 
License: MIT
Author: yujiading
Author-email: yujia.ding@cgu.edu
Requires-Python: >=3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: matplotlib (>=3.10.1,<4.0.0)
Requires-Dist: mpmath (>=1.3.0,<2.0.0)
Requires-Dist: notebook (>=7.3.3,<8.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
Requires-Dist: scipy (>=1.15.2,<2.0.0)
Requires-Dist: tqdm (>=4.67.1,<5.0.0)
Project-URL: Homepage, https://github.com/yujiading/fractals
Project-URL: Repository, https://github.com/yujiading/fractals
Description-Content-Type: text/markdown

# Fractal Analysis
Fractal and multifractal methods, including 

- testers:
  - fractional Brownian motion (FBM) tester
  - multifractional Brownian motion (MBM) tester
- estimators:
  - IR hurst exponents estimator of multifractional Brownian motion (MBM)
  - QV hurst exponents estimator of multifractional Brownian motion (MBM)
- simulators:
  - Wood and Chan methods:
    - Wood and Chan fractional Brownian motion (FBM) simulator
    - Wood and Chan multifractional Brownian motion (MBM) simulator
  - DPRW methods:
    - DPRW fractional Brownian motion (FBM) simulator
    - DPRW sub-fractional Brownian motion (sub-FBM) simulator
    - DPRW bi-fractional Brownian motion (bi-FBM) simulator
    - DPRW tri-fractional Brownian motion (tri-FBM) simulator
    - DPRW general fractional self similar process simulator
    - DPRW multifractional Brownian motion (MBM) simulator

## FBM / MBM tester
Test if a series is FBM (MBM) given the hurst parameter (hurst exponents series).
The implementation is based on the following papers:

>Michał Balcerek, Krzysztof Burnecki. (2020)  
Testing of fractional Brownian motion in a noisy environment.  
Chaos, Solitons & Fractals, Volume 140, 110097.  
https://doi.org/10.1016/j.chaos.2020.110097

>Balcerek, Michał, and Krzysztof Burnecki. (2020)  
Testing of Multifractional Brownian Motion. Entropy 22, no. 12: 1403.  
https://doi.org/10.3390/e22121403 

We added the following improvements to the FBM and/or MBM tester:
- option for automatically estimating sigma 
  - based on Theorem 2.3 of the following paper:
    >Ayache A., Peng Q. (2012)  
     Stochastic Volatility and Multifractional Brownian Motion.  
     In: Zili M., Filatova D. (eds) Stochastic Differential Equations and Processes. 
     Springer Proceedings in Mathematics, vol 7. Springer, Berlin, Heidelberg.  
     https://doi.org/10.1007/978-3-642-22368-6_6

[//]: # (  - a detailed introduction can be found in the section 5 of the following paper:)

[//]: # (    > todo: add paper name)
- option for testing if the series itself is a FBM (MBM)
- option for testing if the increment of the series is the increment of a FBM (MBM)
- option for testing if the series is a FBM (MBM) with an add-on noise
- option for testing if the increment of the series is the increment of a FBM (MBM) with an add-on noise

## IR / QV hurst estimator of MBM
Estimate the hurst parameter (hurst exponent series) of a MBM.
The implementation is based on the following paper:

>Bardet, Jean-Marc & Surgailis, Donatas, 2013.  
Nonparametric estimation of the local Hurst function of multifractional Gaussian processes.  
Stochastic Processes and their Applications, Elsevier, vol. 123(3), pages 1004-1045.


Bardet, the author in the above paper, provides a Matlab code that can be found at: 
>http://samm.univ-paris1.fr/Sofwares-Logiciels  
Software for estimating the Hurst function H of a Multifractional Brownian Motion:
 Quadratic Variation estimator and IR estimator

## Wood and Chan FBM simulator
Generate a Fractional Brownian Motion (FBM) using Wood and Chan circulant matrix. The implementation is based on the following paper:
>A.T.A. Wood, G. Chan, Simulation of stationary Gaussian process in [0,1]d.
Journal of Computational and Graphical Statistics, Vol. 3 (1994) 409-432.

and based on a Matlab library ```Fraclab``` and its function ```fbmwoodchan.m``` that can be found at:

>https://project.inria.fr/fraclab

## Wood and Chan MBM simulator
Generate a Multi-fractional Brownian Motion (mBm) using Wood&Chan circulant matrix, some krigging and a prequantification.
The implementation is based on the following paper:
>O. Barrie,"Synthe et estimation de mouvements Browniens multifractionnaires et autres processus rularit prescrite. 
Dinition du processus autorul multifractionnaire et applications", PhD Thesis (2007)

and based on a Matlab library ```Fraclab``` and its function ```mBmQuantifKrigeage.m``` that can be found at:

>https://project.inria.fr/fraclab

## DPRW FBM / sub-FBM / bi-FBM / tri-FBM / self similar fractal simulator
Generate a fractional self similar processes. 

The main idea is:  use Lamperti transform to transfer a self-similar process to a stationary process, and
                   simulate the stationary process using circulant embedding approach (Wood, A.T.A., Chan, G., 1994.
                   Simulation of stationary Gaussian processes in [0, 1]^d. Journal of computational and graphical
                   statistics 3, 409–432). Then a subsequence of the simulated stationary process is convert back to
                   the series. 

The implementation is based on our paper:
>Y. Ding, Q. Peng, G. Ren, W. Wu "Simulation of Self-similar Processes using Lamperti Transformation
                      with An Application to Generate Multifractional Brownian Motion." 

[//]: # (> #todo: add paper link )


## DPRW MBM simulator
Generates a Multi-fractional Brownian Motion (mBm) using DPRW Lamperti Transformation, some krigging and a prequantification.

The implementation is based on our paper:
>Y. Ding, Q. Peng, G. Ren, W. Wu "Simulation of Self-similar Processes using Lamperti Transformation
                      with An Application to Generate Multifractional Brownian Motion." 

[//]: # (> #todo: add paper link )


## To install
To get started, simply do:
```
pip install fractal-analysis
```
or check out the code from out GitHub repository.

You can now use the series tester module in Python with:
```
from fractal_analysis import tester
```
or use the hurst estimators with
```
from fractal_analysis import estimator
```
or use the simulators with
```
from fractal_analysis import simulator
```

## Examples
### FBM / MBM tester
Import:
```
from fractal_analysis.tester.series_tester import MBMSeriesTester, FBMSeriesTester
from fractal_analysis.tester.critical_surface import CriticalSurfaceFBM, CriticalSurfaceMFBM
```
To test if a series ```series``` is FBM, use ```CriticalSurfaceFBM``` with length of the series ```N```,
the significance level ```alpha``` (look at quantiles of order ```alpha/2``` and ```1 − alpha/2```), and  choose to test
on the series itself or its increment series using ```is_increment_series``` (default is ```False```, meaning to test on
the series itself),
```
fbm_tester = FBMSeriesTester(critical_surface=CriticalSurfaceFBM(N=N, alpha=0.05, is_increment_series=False))
```

To test if the series is FBM with hurst parameter 0.3 and use auto estimated sigma square (set ```sig2=None```):

```
is_fbm, sig2 = fbm_tester.test(h=0.3, x=series, sig2=None, add_on_sig2=0)
```
If the output contains, for example:
> Bad auto sigma square calculated with error 6.239236333681868. Suggest to give sigma square and rerun.

The auto sigma square estimated is not accurate. You may want to manually choose a sigma square and rerun. For example:
```
is_fbm, sig2 = fbm_tester.test(h=0.3, x=series, sig2=1, add_on_sig2=0)
```
If you want to test with an add-on noise, change the value of ```add_on_sig2```.




To test if the series is MBM,  use ```CriticalSurfaceMFBM``` with length of the series ```N```
and the significance level ```alpha``` (look at quantiles of order ```alpha/2``` and ```1 − alpha/2```) 
```
mbm_tester = MBMSeriesTester(critical_surface=CriticalSurfaceMFBM(N=N, alpha=0.05, is_increment_series=False))
```
To test if the series is MBM with a given holder exponent series ```h_mbm_series``` and use auto estimated sigma square:
```
is_mbm, sig2 = mbm_tester.test(h=h_mbm_series, x=series, sig2=None, add_on_sig2=0)
```
Be aware that ```MBMSeriesTester``` requires ```len(h_mbm_series)==len(series)```.

#### Use of cache
Use caching to speed up the testing process. If the series ```x``` for testing is unchanged and multiple ```h``` 
and/or ```sig2``` are used, you may want to set 
```is_cache_stat=True``` to allow cache variable ```stat```. If ```h``` and ```sig2``` are unchanged and multiple ```x```
are used, you may want to set ```is_cache_quantile=True``` to allow cache variable ```quantile```. For example:
```
mbm_tester = MBMSeriesTester(critical_surface=CriticalSurfaceMFBM(N=N, alpha=0.05), is_cache_stat=True, is_cache_quantile=False)
```

### IR / QV hurst estimator of MBM
Import:
```
from fractal_analysis.estimator.hurst_estimator import IrHurstEstimator, QvHurstEstimator
import numpy as np
import math
```
Generate a standard brownian motion
```
N = 100
series = np.random.randn(N) * 0.5 * math.sqrt(1 / N)
series = np.cumsum(series)
```
To estimate the hurst exponents series of the above series with ```alpha=0.2``` using IR estimator,
```
estimator = IrHurstEstimator(mbm_series=series, alpha=0.2)
print(estimator.holder_exponents)
```
To estimate the hurst exponents series of the above series with ```alpha=0.2``` using QV estimator,
```
estimator = QvHurstEstimator(mbm_series=series, alpha=0.2)
print(estimator.holder_exponents)
```
Here the value of ```alpha``` decides how many observations on the ```mbm_series``` is used to estimate a point of the
holder exponent; small alpha means more observations are used for a single point and therefore the variance is small.
   
### Simulators

#### Wood and Chan FBM simulator
Import:
```
from fractal_analysis.simulator.wood_chan.wood_chan_fractal_simulator import WoodChanFbmSimulator
```
To simulate a FBM series with ```1000``` samples and ```0.8``` hurst parameter,
```
woodchan_fbm = WoodChanFbmSimulator(sample_size=1000, hurst_parameter=0.8).get_fbm()
```


#### Wood and Chan MBM simulator
Import:
```
from fractal_analysis.simulator.wood_chan.wood_chan_multi_fractal_simulator import WoodChanMbmSimulator
```
To simulate a MBM series with ```1000``` samples and a sin shape holder function,
```
sample_size=1000
t = np.linspace(0, 1, sample_size)
holder_exponents = 0.5 + 0.3 * np.sin(4 * np.pi * t)
woodchan_mbm = WoodChanMbmSimulator(sample_size=sample_size,holder_exponents=holder_exponents).get_mbm()
```

#### DPRW FBM simulator
Import:
```
from fractal_analysis.simulator.dprw.dprw_fractal_simulator import DprwFbmSimulator
```
To simulate a FBM series with ```1000``` samples and ```0.8``` hurst parameter,
```
dprw_fbm = DprwFbmSimulator(sample_size=1000, hurst_parameter=0.8).get_fbm()
```

#### DPRW sub-FBM simulator
Import:
```
from fractal_analysis.simulator.dprw.dprw_fractal_simulator import DprwSubFbmSimulator
```
To simulate a sub-FBM series with ```1000``` samples and ```0.8``` hurst parameter,
```
dprw_sub_fbm = DprwSubFbmSimulator(sample_size=1000, hurst_parameter=0.8).get_sub_fbm()
```
#### DPRW bi-FBM simulator
Import:
```
from fractal_analysis.simulator.dprw.dprw_fractal_simulator import DprwBiFbmSimulator
```
To simulate a bi-FBM series with ```1000``` samples, ```0.8``` hurst parameter, and ```0.2``` bi factor,
```
dprw_bi_fbm = DprwBiFbmSimulator(sample_size=1000, hurst_parameter=0.8, bi_factor=0.2).get_bi_fbm()
```
When ```bi_factor=1```, bi-FBM becomes FBM

#### DPRW tri-FBM simulator
Import:
```
from fractal_analysis.simulator.dprw.dprw_fractal_simulator import DprwTriFbmSimulator
```
To simulate a tri-FBM series with ```1000``` samples, ```0.8``` hurst parameter, and ```0.2``` tri factor,
```
dprw_tri_fbm = DprwTriFbmSimulator(sample_size=1000, hurst_parameter=0.8, tri_factor=0.2).get_tri_fbm()
```
When ```tri_factor=1```, tri-FBM becomes FBM with multiplier 2.

#### DPRW self similar fractal simulator
Import:
```
from fractal_analysis.simulator.dprw.dprw_fractal_simulator import DprwSelfSimilarFractalSimulator
```
To simulate a customized self similar fractal series, you need to input ```covariance_func```. For example,
```
dprw_self_similar_fractal = DprwSelfSimilarFractalSimulator(sample_size, hurst_parameter, covariance_func).get_self_similar_process()
```

#### DPRW MBM simulator
Import:
```
from fractal_analysis.simulator.dprw.dprw_multi_fractal_simulator import DprwMbmSimulator
```
To simulate a MBM series with ```1000``` samples and a sin shape holder function,
```
sample_size = 1000
t = np.linspace(0, 1, sample_size)
holder_exponents = 0.5 + 0.3 * np.sin(4 * np.pi * t)
dprw_mbm = DprwMbmSimulator(sample_size=sample_size, holder_exponents=holder_exponents).get_mbm()
```

#### Plot or seed a simulated series

In all simulators, you can use ```is_plot``` (default is ```False```) to show or not show the plot of the series. 
Set ```is_plot=True``` and ```plot_path="path_to_save/plot_name.png"``` (default is ```None```) to save the plot. 
Use ```seed```  (default is ```None```) to fix the random state. Use ```y_limits``` to fix y-axis range. 
In the mbm simulators, use ```hurst_name``` to name the holder exponent function in plot tile.  
For example,
```
dprw_fbm = DprwFbmSimulator(sample_size=1000, hurst_parameter=0.8).get_fbm(is_plot=True, seed=1, plot_path="path_to_save/plot_name.png")
```

#### To use ```lamperti_multiplier``` in DPRW simulators
```lamperti_multiplier``` is a positive integer used for Lamperti transform. 
Bigger value (usually <=10) provides more accuracy; default value is 5. For example,
```
dprw_fbm = DprwFbmSimulator(sample_size=1000, hurst_parameter=0.8, lamperti_multiplier=10).get_fbm()
```
