nolitisea 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. nolitisea-0.1.0/LICENSE +21 -0
  2. nolitisea-0.1.0/PKG-INFO +217 -0
  3. nolitisea-0.1.0/README.md +192 -0
  4. nolitisea-0.1.0/pyproject.toml +50 -0
  5. nolitisea-0.1.0/setup.cfg +4 -0
  6. nolitisea-0.1.0/src/nolitisea/__init__.py +4 -0
  7. nolitisea-0.1.0/src/nolitisea/core/__init__.py +6 -0
  8. nolitisea-0.1.0/src/nolitisea/core/embed.py +289 -0
  9. nolitisea-0.1.0/src/nolitisea/core/neighbors.py +98 -0
  10. nolitisea-0.1.0/src/nolitisea/cross/__init__.py +3 -0
  11. nolitisea-0.1.0/src/nolitisea/cross/xc2.py +214 -0
  12. nolitisea-0.1.0/src/nolitisea/cross/xcor.py +75 -0
  13. nolitisea-0.1.0/src/nolitisea/cross/xrecur.py +212 -0
  14. nolitisea-0.1.0/src/nolitisea/cross/xzero.py +177 -0
  15. nolitisea-0.1.0/src/nolitisea/dimension/__init__.py +3 -0
  16. nolitisea-0.1.0/src/nolitisea/dimension/c1.py +337 -0
  17. nolitisea-0.1.0/src/nolitisea/dimension/c2.py +89 -0
  18. nolitisea-0.1.0/src/nolitisea/dimension/d2.py +229 -0
  19. nolitisea-0.1.0/src/nolitisea/embedding/__init__.py +8 -0
  20. nolitisea-0.1.0/src/nolitisea/embedding/c_c.py +166 -0
  21. nolitisea-0.1.0/src/nolitisea/embedding/false_nearest.py +181 -0
  22. nolitisea-0.1.0/src/nolitisea/embedding/mutual.py +329 -0
  23. nolitisea-0.1.0/src/nolitisea/embedding/poincare.py +255 -0
  24. nolitisea-0.1.0/src/nolitisea/entropy/__init__.py +7 -0
  25. nolitisea-0.1.0/src/nolitisea/entropy/multivariate_transfer_entropy.py +262 -0
  26. nolitisea-0.1.0/src/nolitisea/entropy/renyi_entropy.py +245 -0
  27. nolitisea-0.1.0/src/nolitisea/entropy/sample_entropy.py +59 -0
  28. nolitisea-0.1.0/src/nolitisea/entropy/transfer_entropy.py +202 -0
  29. nolitisea-0.1.0/src/nolitisea/generate/__init__.py +3 -0
  30. nolitisea-0.1.0/src/nolitisea/generate/henon.py +45 -0
  31. nolitisea-0.1.0/src/nolitisea/generate/ikeda.py +60 -0
  32. nolitisea-0.1.0/src/nolitisea/generate/logistic.py +44 -0
  33. nolitisea-0.1.0/src/nolitisea/generate/lorenz.py +82 -0
  34. nolitisea-0.1.0/src/nolitisea/generate/mackey_glass.py +76 -0
  35. nolitisea-0.1.0/src/nolitisea/generate/roessler.py +59 -0
  36. nolitisea-0.1.0/src/nolitisea/linear/__init__.py +10 -0
  37. nolitisea-0.1.0/src/nolitisea/linear/ar_model.py +224 -0
  38. nolitisea-0.1.0/src/nolitisea/linear/arima_model.py +447 -0
  39. nolitisea-0.1.0/src/nolitisea/linear/autocorr.py +52 -0
  40. nolitisea-0.1.0/src/nolitisea/linear/filters.py +211 -0
  41. nolitisea-0.1.0/src/nolitisea/linear/mem_spec.py +134 -0
  42. nolitisea-0.1.0/src/nolitisea/linear/spectrum.py +128 -0
  43. nolitisea-0.1.0/src/nolitisea/lyapunov/__init__.py +3 -0
  44. nolitisea-0.1.0/src/nolitisea/lyapunov/fsle.py +275 -0
  45. nolitisea-0.1.0/src/nolitisea/lyapunov/lyap_k.py +301 -0
  46. nolitisea-0.1.0/src/nolitisea/lyapunov/lyap_r.py +235 -0
  47. nolitisea-0.1.0/src/nolitisea/lyapunov/lyap_spec.py +344 -0
  48. nolitisea-0.1.0/src/nolitisea/noise/__init__.py +3 -0
  49. nolitisea-0.1.0/src/nolitisea/noise/add_noise.py +345 -0
  50. nolitisea-0.1.0/src/nolitisea/noise/compare.py +367 -0
  51. nolitisea-0.1.0/src/nolitisea/noise/ghkss.py +274 -0
  52. nolitisea-0.1.0/src/nolitisea/noise/lazy.py +86 -0
  53. nolitisea-0.1.0/src/nolitisea/prediction/__init__.py +21 -0
  54. nolitisea-0.1.0/src/nolitisea/prediction/esn.py +475 -0
  55. nolitisea-0.1.0/src/nolitisea/prediction/local_first.py +759 -0
  56. nolitisea-0.1.0/src/nolitisea/prediction/local_zeroth.py +773 -0
  57. nolitisea-0.1.0/src/nolitisea/prediction/neural_net.py +806 -0
  58. nolitisea-0.1.0/src/nolitisea/prediction/polynomial.py +572 -0
  59. nolitisea-0.1.0/src/nolitisea/prediction/rbf.py +455 -0
  60. nolitisea-0.1.0/src/nolitisea/stationarity/__init__.py +3 -0
  61. nolitisea-0.1.0/src/nolitisea/stationarity/nstat_z.py +256 -0
  62. nolitisea-0.1.0/src/nolitisea/stationarity/recurrence.py +364 -0
  63. nolitisea-0.1.0/src/nolitisea/stationarity/stp.py +147 -0
  64. nolitisea-0.1.0/src/nolitisea/surrogates/__init__.py +3 -0
  65. nolitisea-0.1.0/src/nolitisea/surrogates/endtoend.py +164 -0
  66. nolitisea-0.1.0/src/nolitisea/surrogates/statistics.py +172 -0
  67. nolitisea-0.1.0/src/nolitisea/surrogates/surrogates.py +145 -0
  68. nolitisea-0.1.0/src/nolitisea/utils/__init__.py +3 -0
  69. nolitisea-0.1.0/src/nolitisea/utils/dist.py +48 -0
  70. nolitisea-0.1.0/src/nolitisea/utils/parallel.py +53 -0
  71. nolitisea-0.1.0/src/nolitisea/utils/resample.py +86 -0
  72. nolitisea-0.1.0/src/nolitisea/utils/rescale.py +47 -0
  73. nolitisea-0.1.0/src/nolitisea.egg-info/PKG-INFO +217 -0
  74. nolitisea-0.1.0/src/nolitisea.egg-info/SOURCES.txt +75 -0
  75. nolitisea-0.1.0/src/nolitisea.egg-info/dependency_links.txt +1 -0
  76. nolitisea-0.1.0/src/nolitisea.egg-info/requires.txt +5 -0
  77. nolitisea-0.1.0/src/nolitisea.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 nolitisea contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,217 @@
1
+ Metadata-Version: 2.4
2
+ Name: nolitisea
3
+ Version: 0.1.0
4
+ Summary: A Python toolkit for nonlinear time series analysis
5
+ Author-email: WenqingNie <nie_wq@163.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ieeningnwq/nolitisea
8
+ Project-URL: Repository, https://github.com/ieeningnwq/nolitisea
9
+ Keywords: nonlinear time series,chaos,phase-space reconstruction,embedding,lyapunov exponent,correlation dimension,surrogates,recurrence plot
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.10
12
+ Classifier: Programming Language :: Python :: 3.11
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
15
+ Classifier: Topic :: Scientific/Engineering :: Physics
16
+ Classifier: Intended Audience :: Science/Research
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: numpy
21
+ Requires-Dist: scipy
22
+ Provides-Extra: nn
23
+ Requires-Dist: torch>=2.0; extra == "nn"
24
+ Dynamic: license-file
25
+
26
+ # nolitisea
27
+
28
+ A Python toolkit for **nonlinear time series analysis**.
29
+
30
+ `nolitisea` bundles the classical work flow of nonlinear dynamics into a single,
31
+ dependency-light library: reconstruct a scalar measurement in phase space,
32
+ choose embedding parameters, estimate dimensions and Lyapunov exponents,
33
+ forecast with local or neural models, test for stationarity and nonlinearity,
34
+ reduce noise, and generate benchmark dynamical systems. Multivariate series
35
+ are supported throughout, and computationally heavy routines ship with
36
+ built-in parallelism.
37
+
38
+ ## Features
39
+
40
+ - **Phase-space reconstruction** — delay embedding, mixed/multivariate embedding, Theiler-window-aware neighbour search
41
+ - **Embedding parameter selection** — mutual information and kernel/Renyi MI for the time delay, Kennel and Cao false-nearest-neighbour methods for the embedding dimension, the C-C method, Poincare sections
42
+ - **Invariant estimates** — correlation sums and correlation dimension (`c1`, `c2`, `d2`), largest Lyapunov exponent (`lyap_r`, `lyap_k`), full Lyapunov spectrum (`lyap_spec`), finite-size Lyapunov exponents (`fsle`)
43
+ - **Entropy** — sample entropy, Renyi/box-counting entropy, transfer entropy and multivariate transfer entropy
44
+ - **Prediction** — zeroth- and first-order local predictors (`lzo_*`, `lfo_*`), RBF networks, polynomial models, echo state networks, and PyTorch neural networks (MLP, LSTM, GRU, TCN, NARX, neural ODE, transformer) behind a unified `fit_*` / `predict_*` API
45
+ - **Stationarity** — cross-prediction nonstationarity test (`nstat_z`), space-time separation plot (`stp`) for Theiler-window selection, recurrence plots and recurrence quantification analysis (RR, DET, LAM, TT, ENTR, ...)
46
+ - **Surrogates & nonlinearity tests** — Fourier, AAFT and IAAFT surrogates, end-to-end nonlinearity testing, time-reversibility and prediction statistics
47
+ - **Cross-analysis** — cross-zeroth prediction, cross-recurrence, cross-correlation and cross-correlation integrals for coupled/driver-response series
48
+ - **Noise reduction & linear tools** — GHKSS and local-average denoising, synthetic noise, error metrics, AR/ARIMA models, power and maximum-entropy spectra, autocorrelation, notch/Wiener/Savitzky-Golay filters
49
+ - **Benchmark systems** — Lorenz, Rossler, Henon, Ikeda, logistic map and Mackey-Glass generators
50
+ - **Performance** — `cKDTree`-based neighbour searches and an optional `n_jobs` / `backend` ("thread" or "process") parallel layer for the expensive scans
51
+
52
+ ## Installation
53
+
54
+ The package is not yet published on PyPI — install it locally from a clone:
55
+
56
+ ```bash
57
+ git clone https://github.com/ieeningnwq/nolitisea.git
58
+ cd nolitisea
59
+ pip install .
60
+ ```
61
+
62
+ For development or running the example notebooks, an editable install is
63
+ recommended:
64
+
65
+ ```bash
66
+ pip install -e .
67
+ ```
68
+
69
+ Core dependencies (NumPy, SciPy) are installed automatically. The
70
+ neural-network predictors additionally need PyTorch, which is an optional
71
+ extra (imported lazily, only needed when you call the `nolitisea.prediction`
72
+ neural-network functions):
73
+
74
+ ```bash
75
+ pip install -e ".[nn]"
76
+ ```
77
+
78
+ Requires Python 3.10 or newer.
79
+
80
+ ## Quickstart
81
+
82
+ ```python
83
+ import numpy as np
84
+ from nolitisea.generate.lorenz import lorenz
85
+
86
+ # Generate a benchmark trajectory (sampled Lorenz system).
87
+ t, states = lorenz(length=2000)
88
+ x = states[:, 0]
89
+ ```
90
+
91
+ Choose embedding parameters — the first minimum of the time-delayed mutual
92
+ information gives the delay, and the false-nearest-neighbour fraction gives
93
+ the embedding dimension:
94
+
95
+ ```python
96
+ from nolitisea.embedding.mutual import first_minimum
97
+ from nolitisea.embedding.false_nearest import kennel_method
98
+
99
+ tau = first_minimum(x, max_lag=100)
100
+ fnn = kennel_method(x, min_emb=1, max_emb=8, delay=tau)
101
+ print("delay:", tau)
102
+ ```
103
+
104
+ Estimate the largest Lyapunov exponent (the average logarithmic divergence
105
+ of nearby trajectories should grow linearly for chaotic data):
106
+
107
+ ```python
108
+ from nolitisea.lyapunov.lyap_r import lyap_r
109
+
110
+ lam = lyap_r(x, dim=5, delay=tau, max_steps=20, theiler=tau, n_jobs=-1)
111
+ # lam["times"], lam["divergence"]
112
+ ```
113
+
114
+ Forecast the series with a radial-basis-function model:
115
+
116
+ ```python
117
+ from nolitisea.prediction.rbf import fit_rbf, predict_rbf
118
+
119
+ model = fit_rbf(x, dim=5, delay=tau, n_centers=50, insample=1800)
120
+ forecast = predict_rbf(model, x[:1800], n_steps=50)
121
+ ```
122
+
123
+ Or with a neural network (requires the `[nn]` extra):
124
+
125
+ ```python
126
+ from nolitisea.prediction.neural_net import fit_nn, predict_nn
127
+
128
+ nn = fit_nn(x[:1500], model_type="mlp", dim=3, delay=tau,
129
+ hidden_layers=(32,), epochs=200, seed=0)
130
+ nn_forecast = predict_nn(nn, x[:1500], n_steps=20)
131
+ ```
132
+
133
+ Test stationarity with the cross-prediction error matrix — stationary data
134
+ give a roughly uniform matrix, while nonstationary data show a diagonal
135
+ valley:
136
+
137
+ ```python
138
+ from nolitisea.stationarity.nstat_z import nstat_z
139
+
140
+ rng = np.random.default_rng(0)
141
+ result = nstat_z(rng.standard_normal(2000), dim=3, delay=1,
142
+ n_pieces=4, min_neighbors=20)
143
+ print(result["matrix"].shape) # (4, 4) normalised forecast-error matrix
144
+ ```
145
+
146
+ Test for nonlinearity against surrogates:
147
+
148
+ ```python
149
+ from nolitisea.surrogates.surrogates import aaft
150
+
151
+ surrogate = aaft(x[:1000]) # amplitude-adjusted Fourier surrogate
152
+ ```
153
+
154
+ `iaaft` (iterative refinement) and the `endtoend` nonlinearity test are also
155
+ available in `nolitisea.surrogates`.
156
+
157
+ ## Module reference
158
+
159
+ | Module | Highlights |
160
+ |---|---|
161
+ | `nolitisea.generate` | `lorenz`, `roessler`, `henon`, `ikeda`, `logistic`, `mackey_glass` |
162
+ | `nolitisea.core` | `delay_embedding`, `lag_block_delay_embed`, `delay_vectors`, `mixed_embedding`, `find_neighbors` |
163
+ | `nolitisea.embedding` | `first_minimum`, `embedded_mutual_information`, `matrix_renyi_mutual_information`, `cc_method`, `kennel_method`, `cao_method`, `poincare_section` |
164
+ | `nolitisea.dimension` | `c1`, `correlation_integral`, `d2` |
165
+ | `nolitisea.lyapunov` | `lyap_r`, `lyap_k`, `lyap_spec`, `fsle` |
166
+ | `nolitisea.entropy` | `sample_entropy`, `renyi_entropy`, `transfer_entropy`, `multivariate_transfer_entropy` |
167
+ | `nolitisea.prediction` | `lzo_run`/`lzo_test`/`lzo_gm`, `lfo_run`/`lfo_test`/`lfo_ar`, `fit_rbf`/`predict_rbf`, `fit_polynom`, `fit_esn`/`predict_esn`, `fit_nn`/`predict_nn` |
168
+ | `nolitisea.stationarity` | `nstat_z`, `stp`, `recurr`, `recurrence_matrix` plus RQA metrics (`recurrence_rate`, `determinism`, `laminarity`, `trapping_time`, ...) |
169
+ | `nolitisea.surrogates` | `ft`, `aaft`, `iaaft`, `endtoend`, `time_reversibility`, `predict_stat` |
170
+ | `nolitisea.cross` | `cross_zeroth`, `cross_recurrence`, `cross_correlation`, `cross_correlation_integral` |
171
+ | `nolitisea.linear` | `fit_ar_model`, `fit_arima`, `autocorrelation`, `power_spectrum`, `mem_spectrum`, `notch_filter`, `wiener_filter`, `savitzky_golay` |
172
+ | `nolitisea.noise` | `ghkss`, `lazy`, `add_noise`, error metrics (`mae`, `mse`, `rmse`, `r2_score`, ...) |
173
+ | `nolitisea.utils` | `rescale_data`, `resample`, `parallel_map`, pairwise distance helpers |
174
+
175
+ Every public function has a numpydoc docstring describing parameters,
176
+ returns, conventions (Chebyshev metric, per-component `[0, 1]` rescaling,
177
+ Theiler windows) and references.
178
+
179
+ ## Examples
180
+
181
+ Runnable, end-to-end Jupyter notebooks live in
182
+ [`examples/`](examples/):
183
+
184
+ - `generate.ipynb` — benchmark dynamical systems
185
+ - `embedding.ipynb` — delay, dimension and Poincare analysis
186
+ - `dimension.ipynb` — correlation sums and dimension estimates
187
+ - `lyapunov.ipynb` — Lyapunov exponents and spectra
188
+ - `entropy.ipynb` — entropies and information transfer
189
+ - `prediction.ipynb` — local, RBF, polynomial, ESN and neural predictors
190
+ - `stationarity.ipynb` — recurrence plots, space-time separation, cross-prediction test
191
+ - `surrogates.ipynb` — surrogate generation and nonlinearity tests
192
+ - `cross.ipynb`, `linear.ipynb`, `noise.ipynb`, `core.ipynb`, `utils.ipynb`
193
+
194
+ ## Testing
195
+
196
+ The test suite is written with `unittest` and cross-checks the vectorised
197
+ implementations against independent brute-force references:
198
+
199
+ ```bash
200
+ python -m unittest discover -s tests
201
+ ```
202
+
203
+ ## References
204
+
205
+ The implemented methods follow the standard literature on nonlinear time
206
+ series analysis:
207
+
208
+ - Kantz, H., & Schreiber, T. (2004). *Nonlinear Time Series Analysis*. Cambridge University Press.
209
+ - Hegger, R., Kantz, H., & Schreiber, T. (1999). Practical implementation of nonlinear time series methods. *Chaos*, 9(2), 413–435.
210
+ - Kennel, M. B., Brown, R., & Abarbanel, H. D. I. (1992). Determining embedding dimension for phase-space reconstruction using a geometrical construction. *Phys. Rev. A*, 45, 3403.
211
+ - Cao, L. (1997). Practical method for determining the minimum embedding dimension of a scalar time series. *Physica D*, 110, 43–50.
212
+ - Rosenstein, M. T., Collins, J. J., & De Luca, C. J. (1993). A practical method for calculating largest Lyapunov exponents. *Physica D*, 65, 117–134.
213
+ - Marwan, N., Romano, M. C., Thiel, M., & Kurths, J. (2007). Recurrence plots for the analysis of complex systems. *Physics Reports*, 438, 237–329.
214
+
215
+ ## License
216
+
217
+ See [LICENSE](LICENSE).
@@ -0,0 +1,192 @@
1
+ # nolitisea
2
+
3
+ A Python toolkit for **nonlinear time series analysis**.
4
+
5
+ `nolitisea` bundles the classical work flow of nonlinear dynamics into a single,
6
+ dependency-light library: reconstruct a scalar measurement in phase space,
7
+ choose embedding parameters, estimate dimensions and Lyapunov exponents,
8
+ forecast with local or neural models, test for stationarity and nonlinearity,
9
+ reduce noise, and generate benchmark dynamical systems. Multivariate series
10
+ are supported throughout, and computationally heavy routines ship with
11
+ built-in parallelism.
12
+
13
+ ## Features
14
+
15
+ - **Phase-space reconstruction** — delay embedding, mixed/multivariate embedding, Theiler-window-aware neighbour search
16
+ - **Embedding parameter selection** — mutual information and kernel/Renyi MI for the time delay, Kennel and Cao false-nearest-neighbour methods for the embedding dimension, the C-C method, Poincare sections
17
+ - **Invariant estimates** — correlation sums and correlation dimension (`c1`, `c2`, `d2`), largest Lyapunov exponent (`lyap_r`, `lyap_k`), full Lyapunov spectrum (`lyap_spec`), finite-size Lyapunov exponents (`fsle`)
18
+ - **Entropy** — sample entropy, Renyi/box-counting entropy, transfer entropy and multivariate transfer entropy
19
+ - **Prediction** — zeroth- and first-order local predictors (`lzo_*`, `lfo_*`), RBF networks, polynomial models, echo state networks, and PyTorch neural networks (MLP, LSTM, GRU, TCN, NARX, neural ODE, transformer) behind a unified `fit_*` / `predict_*` API
20
+ - **Stationarity** — cross-prediction nonstationarity test (`nstat_z`), space-time separation plot (`stp`) for Theiler-window selection, recurrence plots and recurrence quantification analysis (RR, DET, LAM, TT, ENTR, ...)
21
+ - **Surrogates & nonlinearity tests** — Fourier, AAFT and IAAFT surrogates, end-to-end nonlinearity testing, time-reversibility and prediction statistics
22
+ - **Cross-analysis** — cross-zeroth prediction, cross-recurrence, cross-correlation and cross-correlation integrals for coupled/driver-response series
23
+ - **Noise reduction & linear tools** — GHKSS and local-average denoising, synthetic noise, error metrics, AR/ARIMA models, power and maximum-entropy spectra, autocorrelation, notch/Wiener/Savitzky-Golay filters
24
+ - **Benchmark systems** — Lorenz, Rossler, Henon, Ikeda, logistic map and Mackey-Glass generators
25
+ - **Performance** — `cKDTree`-based neighbour searches and an optional `n_jobs` / `backend` ("thread" or "process") parallel layer for the expensive scans
26
+
27
+ ## Installation
28
+
29
+ The package is not yet published on PyPI — install it locally from a clone:
30
+
31
+ ```bash
32
+ git clone https://github.com/ieeningnwq/nolitisea.git
33
+ cd nolitisea
34
+ pip install .
35
+ ```
36
+
37
+ For development or running the example notebooks, an editable install is
38
+ recommended:
39
+
40
+ ```bash
41
+ pip install -e .
42
+ ```
43
+
44
+ Core dependencies (NumPy, SciPy) are installed automatically. The
45
+ neural-network predictors additionally need PyTorch, which is an optional
46
+ extra (imported lazily, only needed when you call the `nolitisea.prediction`
47
+ neural-network functions):
48
+
49
+ ```bash
50
+ pip install -e ".[nn]"
51
+ ```
52
+
53
+ Requires Python 3.10 or newer.
54
+
55
+ ## Quickstart
56
+
57
+ ```python
58
+ import numpy as np
59
+ from nolitisea.generate.lorenz import lorenz
60
+
61
+ # Generate a benchmark trajectory (sampled Lorenz system).
62
+ t, states = lorenz(length=2000)
63
+ x = states[:, 0]
64
+ ```
65
+
66
+ Choose embedding parameters — the first minimum of the time-delayed mutual
67
+ information gives the delay, and the false-nearest-neighbour fraction gives
68
+ the embedding dimension:
69
+
70
+ ```python
71
+ from nolitisea.embedding.mutual import first_minimum
72
+ from nolitisea.embedding.false_nearest import kennel_method
73
+
74
+ tau = first_minimum(x, max_lag=100)
75
+ fnn = kennel_method(x, min_emb=1, max_emb=8, delay=tau)
76
+ print("delay:", tau)
77
+ ```
78
+
79
+ Estimate the largest Lyapunov exponent (the average logarithmic divergence
80
+ of nearby trajectories should grow linearly for chaotic data):
81
+
82
+ ```python
83
+ from nolitisea.lyapunov.lyap_r import lyap_r
84
+
85
+ lam = lyap_r(x, dim=5, delay=tau, max_steps=20, theiler=tau, n_jobs=-1)
86
+ # lam["times"], lam["divergence"]
87
+ ```
88
+
89
+ Forecast the series with a radial-basis-function model:
90
+
91
+ ```python
92
+ from nolitisea.prediction.rbf import fit_rbf, predict_rbf
93
+
94
+ model = fit_rbf(x, dim=5, delay=tau, n_centers=50, insample=1800)
95
+ forecast = predict_rbf(model, x[:1800], n_steps=50)
96
+ ```
97
+
98
+ Or with a neural network (requires the `[nn]` extra):
99
+
100
+ ```python
101
+ from nolitisea.prediction.neural_net import fit_nn, predict_nn
102
+
103
+ nn = fit_nn(x[:1500], model_type="mlp", dim=3, delay=tau,
104
+ hidden_layers=(32,), epochs=200, seed=0)
105
+ nn_forecast = predict_nn(nn, x[:1500], n_steps=20)
106
+ ```
107
+
108
+ Test stationarity with the cross-prediction error matrix — stationary data
109
+ give a roughly uniform matrix, while nonstationary data show a diagonal
110
+ valley:
111
+
112
+ ```python
113
+ from nolitisea.stationarity.nstat_z import nstat_z
114
+
115
+ rng = np.random.default_rng(0)
116
+ result = nstat_z(rng.standard_normal(2000), dim=3, delay=1,
117
+ n_pieces=4, min_neighbors=20)
118
+ print(result["matrix"].shape) # (4, 4) normalised forecast-error matrix
119
+ ```
120
+
121
+ Test for nonlinearity against surrogates:
122
+
123
+ ```python
124
+ from nolitisea.surrogates.surrogates import aaft
125
+
126
+ surrogate = aaft(x[:1000]) # amplitude-adjusted Fourier surrogate
127
+ ```
128
+
129
+ `iaaft` (iterative refinement) and the `endtoend` nonlinearity test are also
130
+ available in `nolitisea.surrogates`.
131
+
132
+ ## Module reference
133
+
134
+ | Module | Highlights |
135
+ |---|---|
136
+ | `nolitisea.generate` | `lorenz`, `roessler`, `henon`, `ikeda`, `logistic`, `mackey_glass` |
137
+ | `nolitisea.core` | `delay_embedding`, `lag_block_delay_embed`, `delay_vectors`, `mixed_embedding`, `find_neighbors` |
138
+ | `nolitisea.embedding` | `first_minimum`, `embedded_mutual_information`, `matrix_renyi_mutual_information`, `cc_method`, `kennel_method`, `cao_method`, `poincare_section` |
139
+ | `nolitisea.dimension` | `c1`, `correlation_integral`, `d2` |
140
+ | `nolitisea.lyapunov` | `lyap_r`, `lyap_k`, `lyap_spec`, `fsle` |
141
+ | `nolitisea.entropy` | `sample_entropy`, `renyi_entropy`, `transfer_entropy`, `multivariate_transfer_entropy` |
142
+ | `nolitisea.prediction` | `lzo_run`/`lzo_test`/`lzo_gm`, `lfo_run`/`lfo_test`/`lfo_ar`, `fit_rbf`/`predict_rbf`, `fit_polynom`, `fit_esn`/`predict_esn`, `fit_nn`/`predict_nn` |
143
+ | `nolitisea.stationarity` | `nstat_z`, `stp`, `recurr`, `recurrence_matrix` plus RQA metrics (`recurrence_rate`, `determinism`, `laminarity`, `trapping_time`, ...) |
144
+ | `nolitisea.surrogates` | `ft`, `aaft`, `iaaft`, `endtoend`, `time_reversibility`, `predict_stat` |
145
+ | `nolitisea.cross` | `cross_zeroth`, `cross_recurrence`, `cross_correlation`, `cross_correlation_integral` |
146
+ | `nolitisea.linear` | `fit_ar_model`, `fit_arima`, `autocorrelation`, `power_spectrum`, `mem_spectrum`, `notch_filter`, `wiener_filter`, `savitzky_golay` |
147
+ | `nolitisea.noise` | `ghkss`, `lazy`, `add_noise`, error metrics (`mae`, `mse`, `rmse`, `r2_score`, ...) |
148
+ | `nolitisea.utils` | `rescale_data`, `resample`, `parallel_map`, pairwise distance helpers |
149
+
150
+ Every public function has a numpydoc docstring describing parameters,
151
+ returns, conventions (Chebyshev metric, per-component `[0, 1]` rescaling,
152
+ Theiler windows) and references.
153
+
154
+ ## Examples
155
+
156
+ Runnable, end-to-end Jupyter notebooks live in
157
+ [`examples/`](examples/):
158
+
159
+ - `generate.ipynb` — benchmark dynamical systems
160
+ - `embedding.ipynb` — delay, dimension and Poincare analysis
161
+ - `dimension.ipynb` — correlation sums and dimension estimates
162
+ - `lyapunov.ipynb` — Lyapunov exponents and spectra
163
+ - `entropy.ipynb` — entropies and information transfer
164
+ - `prediction.ipynb` — local, RBF, polynomial, ESN and neural predictors
165
+ - `stationarity.ipynb` — recurrence plots, space-time separation, cross-prediction test
166
+ - `surrogates.ipynb` — surrogate generation and nonlinearity tests
167
+ - `cross.ipynb`, `linear.ipynb`, `noise.ipynb`, `core.ipynb`, `utils.ipynb`
168
+
169
+ ## Testing
170
+
171
+ The test suite is written with `unittest` and cross-checks the vectorised
172
+ implementations against independent brute-force references:
173
+
174
+ ```bash
175
+ python -m unittest discover -s tests
176
+ ```
177
+
178
+ ## References
179
+
180
+ The implemented methods follow the standard literature on nonlinear time
181
+ series analysis:
182
+
183
+ - Kantz, H., & Schreiber, T. (2004). *Nonlinear Time Series Analysis*. Cambridge University Press.
184
+ - Hegger, R., Kantz, H., & Schreiber, T. (1999). Practical implementation of nonlinear time series methods. *Chaos*, 9(2), 413–435.
185
+ - Kennel, M. B., Brown, R., & Abarbanel, H. D. I. (1992). Determining embedding dimension for phase-space reconstruction using a geometrical construction. *Phys. Rev. A*, 45, 3403.
186
+ - Cao, L. (1997). Practical method for determining the minimum embedding dimension of a scalar time series. *Physica D*, 110, 43–50.
187
+ - Rosenstein, M. T., Collins, J. J., & De Luca, C. J. (1993). A practical method for calculating largest Lyapunov exponents. *Physica D*, 65, 117–134.
188
+ - Marwan, N., Romano, M. C., Thiel, M., & Kurths, J. (2007). Recurrence plots for the analysis of complex systems. *Physics Reports*, 438, 237–329.
189
+
190
+ ## License
191
+
192
+ See [LICENSE](LICENSE).
@@ -0,0 +1,50 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "nolitisea"
7
+ version = "0.1.0"
8
+ description = "A Python toolkit for nonlinear time series analysis"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ authors = [
13
+ { name = "WenqingNie", email="nie_wq@163.com" },
14
+ ]
15
+ keywords = [
16
+ "nonlinear time series",
17
+ "chaos",
18
+ "phase-space reconstruction",
19
+ "embedding",
20
+ "lyapunov exponent",
21
+ "correlation dimension",
22
+ "surrogates",
23
+ "recurrence plot",
24
+ ]
25
+ classifiers = [
26
+ "Programming Language :: Python :: 3",
27
+ "Programming Language :: Python :: 3.10",
28
+ "Programming Language :: Python :: 3.11",
29
+ "Programming Language :: Python :: 3.12",
30
+ "Topic :: Scientific/Engineering :: Mathematics",
31
+ "Topic :: Scientific/Engineering :: Physics",
32
+ "Intended Audience :: Science/Research",
33
+ ]
34
+ dependencies = [
35
+ "numpy",
36
+ "scipy",
37
+ ]
38
+
39
+ [project.optional-dependencies]
40
+ nn = ["torch>=2.0"]
41
+
42
+ [project.urls]
43
+ Homepage = "https://github.com/ieeningnwq/nolitisea"
44
+ Repository = "https://github.com/ieeningnwq/nolitisea"
45
+
46
+ [tool.setuptools]
47
+ package-dir = { "" = "src" }
48
+
49
+ [tool.setuptools.packages.find]
50
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,4 @@
1
+ """nolitisea: A Python toolkit for nonlinear time series analysis."""
2
+
3
+ __version__ = "0.1.0"
4
+
@@ -0,0 +1,6 @@
1
+ """Core infrastructure: embedding, neighbor search."""
2
+
3
+ from . import ( # noqa: F401
4
+ embed,
5
+ neighbors,
6
+ )