"""非线性动力学特征提取模块

提供多种非线性特征用于分析时间序列的复杂动力学行为。

特征列表
========

分形维度：
- `higuchi_fractal_dimension` - Higuchi 分形维度，适用于非平稳信号
- `katz_fractal_dimension` - Katz 分形维度，计算快速
- `petrosian_fractal_dimension` - Petrosian 分形维度，最简化的分形估计
- `correlation_dimension` - 相关维数，吸引子的分形维数

Hurst 指数：
- `hurst_exponent` - Hurst 指数，评估长期记忆性

Lyapunov 指数：
- `largest_lyapunov_exponent` - 最大李雅普诺夫指数，混沌检测

递归定量分析 (RQA)：
- `recurrence_quantification_analysis` - RQA 全套指标
- `recurrence_rate` - 递归率，系统返回相似状态的频率
- `determinism` - 确定性，系统行为的可预测程度
- `laminarity` - 层叠性，系统在特定状态停留的倾向


计算复杂度
=========

| 函数                       | 复杂度         | 典型耗时 (N=1000) |
|----------------------------|----------------|-------------------|
| higuchi_fractal_dimension  | O(N × kmax)    | ~1 ms             |
| katz_fractal_dimension     | O(N)           | <1 ms             |
| petrosian_fractal_dimension| O(N)           | <1 ms             |
| hurst_exponent             | O(N × max_lag) | ~5 ms             |
| correlation_dimension      | O(N² × m)      | ~100-500 ms       |
| largest_lyapunov_exponent  | O(N² × m)      | ~100-500 ms       |
| recurrence_quantification  | O(N² × m)      | ~100-500 ms       |

注: O(N²) 算法在长序列上较慢，建议 N < 2000 或使用降采样。


参数选择建议
===========

相空间重构参数 (m, τ)
---------------------
适用于: correlation_dimension, largest_lyapunov_exponent, RQA 系列

- `m` (嵌入维度):
  - Lyapunov / RQA: 5 ~ 15，常用 10
  - Correlation Dim: 应满足 m > 2 × D₂（D₂ 为估计的相关维数）
  - 经验法则: 从小到大增加 m，直到结果稳定

- `tau` (时间延迟):
  - 默认自动估计（自相关第一过零点）
  - 也可用互信息第一极小值
  - 过采样信号: tau 应较大以解相关

- `min_tsep` (Theiler 窗口):
  - 排除时间上相近的点对，消除自相关偏差
  - 默认等于 tau，通常无需手动设置

分形维度参数
-----------
- `kmax` (Higuchi): 5 ~ 20，常用 10
  - 太小 → 拟合点不足
  - 太大 → 超出序列有效范围
- `max_lag` (Hurst): 10 ~ N//4，常用 20

RQA 阈值参数
-----------
- `threshold`: 递归阈值
  - 默认 0.1 × std(signal)
  - 调整使 RR ∈ [0.01, 0.05] 为佳
  - 太小 → RR 过低，统计不稳定
  - 太大 → RR 过高，失去区分度
- `min_diag_length`: 最小对角线长度，通常 2
- `min_vert_length`: 最小垂直线长度，通常 2


数据长度要求
===========

| 算法                  | 最小长度 | 推荐长度  |
|-----------------------|----------|-----------|
| Higuchi FD            | 2×kmax   | > 100     |
| Katz / Petrosian FD   | 10       | > 50      |
| Hurst Exponent        | 20       | > 200     |
| Correlation Dimension | 100      | > 500     |
| Lyapunov Exponent     | 100      | > 500     |
| RQA                   | 50       | > 200     |


结果解释
=======

分形维度
--------
- 范围通常 1 ~ 2（一维时间序列）
- 值越高 → 信号越复杂/不规则
- 周期信号 → 接近 1
- 白噪声 → 接近 2（或更高）

Hurst 指数
----------
- H = 0.5: 随机游走（无记忆）
- H > 0.5: 持续性序列（正长程相关，趋势延续）
- H < 0.5: 反持续性序列（负长程相关，均值回归）

Lyapunov 指数
-------------
- λ > 0: 混沌行为（相邻轨道指数分离）
- λ ≈ 0: 周期或准周期
- λ < 0: 收敛到稳定不动点

RQA 指标
--------
- RR (递归率): 系统返回相似状态的频率
- DET (确定性): 可预测程度，周期信号→1，随机→0
- L (平均对角线长度): 平均可预测时间
- Lmax (最大对角线长度): 最长可预测时间
- ENTR (熵): 对角线分布复杂度
- LAM (层叠性): 系统停滞倾向
- TT (捕获时间): 平均停滞时间


实践经验
=======

1. **快速 vs 精细分析**
   - 快速概览 → Katz FD, Petrosian FD, Hurst
   - 精细分析 → Higuchi FD, Correlation Dim, RQA

2. **混沌检测流程**
   - Step 1: 计算 Lyapunov 指数，λ > 0 提示混沌
   - Step 2: 计算相关维数，有限且非整数提示奇异吸引子
   - Step 3: RQA 的 DET 介于 0-1 之间（非周期非随机）

3. **处理长序列 (N > 5000)**
   - 降采样或分段计算后平均
   - 使用 `correlation_dimension` 时会自动采样

4. **参数敏感性**
   - Lyapunov / Correlation Dim 对 m, tau 敏感，建议多组参数验证
   - RQA 对 threshold 敏感，可绘制 threshold-RR 曲线选择

5. **常见问题**
   - 返回 `nan`: 序列过短或参数不当
   - Hurst ≈ 1: 可能是非平稳趋势，考虑先去趋势
   - Correlation Dim 过低: 检查 Theiler 窗口是否足够大


使用示例
=======

基本用法::

    import numpy as np
    from zyplib.feature import (
        higuchi_fractal_dimension,
        hurst_exponent,
        largest_lyapunov_exponent,
    )

    signal = np.random.randn(1000)

    hfd = higuchi_fractal_dimension(signal, kmax=10)
    hurst = hurst_exponent(signal, max_lag=20)
    lle = largest_lyapunov_exponent(signal, m=10, fs=250)

RQA 分析::

    from zyplib.feature import (
        recurrence_quantification_analysis,
        determinism,
    )

    # 获取全部 RQA 指标
    rqa = recurrence_quantification_analysis(signal, m=10, return_dict=True)
    print(f"RR={rqa['RR']:.3f}, DET={rqa['DET']:.3f}, LAM={rqa['LAM']:.3f}")

    # 或只获取单个指标
    det = determinism(signal, m=10)

批量处理::

    from zyplib.feature import correlation_dimension

    # (n_samples, n_channels, n_timepoints)
    signals = np.random.randn(50, 8, 500)

    # 沿最后一个轴计算，返回 (50, 8)
    cd = correlation_dimension(signals, m=10, axis=-1)

与 make_tabular 配合::

    from zyplib.feature import make_tabular
    from zyplib.feature import (
        higuchi_fractal_dimension,
        hurst_exponent,
        recurrence_rate,
        determinism,
    )
    from functools import partial

    feature_funcs = {
        'HFD': higuchi_fractal_dimension,
        'Hurst': hurst_exponent,
        'RR': partial(recurrence_rate, m=10),
        'DET': partial(determinism, m=10),
    }

    features, names = make_tabular(signals, feature_funcs, return_feat_names=True)
"""

# 分形维度
from ._fractal import (
    higuchi_fractal_dimension,
    katz_fractal_dimension,
    petrosian_fractal_dimension,
    correlation_dimension,
)

# Hurst 指数
from ._hurst import hurst_exponent

# Lyapunov 指数
from ._lyapunov import largest_lyapunov_exponent

# RQA
from ._rqa import (
    recurrence_quantification_analysis,
    recurrence_rate,
    determinism,
    laminarity,
)


__all__ = [
    # 分形维度
    'higuchi_fractal_dimension',
    'katz_fractal_dimension',
    'petrosian_fractal_dimension',
    'correlation_dimension',
    # Hurst 指数
    'hurst_exponent',
    # Lyapunov 指数
    'largest_lyapunov_exponent',
    # RQA
    'recurrence_quantification_analysis',
    'recurrence_rate',
    'determinism',
    'laminarity',
]
