"""熵度量算法模块

提供多种熵度量用于分析时间序列的复杂度和规律性。

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

基础熵度量：
- `sample_entropy` - 样本熵，测量序列不规则性
- `approximate_entropy` - 近似熵，样本熵的前身
- `permutation_entropy` - 排列熵，基于序列模式，抗噪声

多尺度熵：
- `multiscale_entropy` - 多尺度熵，揭示多尺度复杂度结构
- `multiscale_entropy_mean` - 多尺度熵均值，单一复杂度指标

模糊熵：
- `fuzzy_entropy` - 模糊熵，对参数更鲁棒的样本熵变体

谱域熵：
- `spectral_entropy` - 谱熵，功率谱平坦程度
- `wavelet_entropy` - 小波熵，能量在各尺度分布的均匀程度

广义熵：
- `renyi_entropy` - Renyi 熵，香农熵的推广
- `collision_entropy` - 碰撞熵，α=2 的 Renyi 熵
- `tsallis_entropy` - Tsallis 熵，非广延统计力学熵
- `shannon_entropy` - 离散香农熵，基于直方图的信息熵

分散熵：
- `dispersion_entropy` - 分散熵，比排列熵更好利用幅度信息


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

| 函数                  | 复杂度           | 备注                       |
|-----------------------|------------------|----------------------------|
| sample_entropy        | O(N² × m)        | 长序列较慢                 |
| approximate_entropy   | O(N² × m)        | 比 SampEn 略快             |
| permutation_entropy   | O(N × m × log m) | 快速                       |
| multiscale_entropy    | O(S × N² × m)    | S = max_scale，最慢        |
| fuzzy_entropy         | O(N² × m)        | 与 SampEn 相当             |
| spectral_entropy      | O(N log N)       | FFT 复杂度                 |
| wavelet_entropy       | O(N × L)         | L = level                  |
| renyi/tsallis/shannon | O(N + bins)      | 基于直方图，快速           |
| dispersion_entropy    | O(N × m)         | 快速                       |


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

样本熵 / 近似熵 / 模糊熵
------------------------
- `m` (嵌入维度): 通常取 2，较长序列可取 3
- `r` (阈值系数): 0.1 ~ 0.25，常用 0.2
  - 太小 → 匹配过少，熵值不稳定
  - 太大 → 几乎全部匹配，失去区分度
- 数据长度: 建议 N > 200，N > 10^m 为宜

排列熵
------
- `order` (阶数): 3 ~ 7，常用 3 或 4
  - 太小 → 模式数少，分辨率低
  - 太大 → 需要 N >> order!，计算量增加
- `delay` (时间延迟): 通常取 1
- `normalize`: 归一化后范围 [0, 1]，便于比较

多尺度熵
--------
- `m`: 通常取 2
- `r`: 0.15 较常用（略小于 SampEn 的 0.2）
- `max_scale`: 10 ~ 20，取决于序列长度
- 数据长度: 建议 N > max_scale × 50

小波熵
------
- `wavelet`: 'db4' 常用，也可选 'sym5', 'coif3' 等
- `level`: 4 ~ 6，取决于信号特性和采样率
- 需要安装 PyWavelets: `pip install PyWavelets`

谱熵
----
- `method`: 'welch'（默认，更平滑）或 'periodogram'
- `nperseg`: Welch 段长度，默认 min(256, N)
- `normalize`: 建议 True，归一化到 [0, 1]

广义熵 (Renyi / Tsallis)
------------------------
- `alpha` / `q`: 控制对概率分布不同部分的敏感度
  - α = 2 (碰撞熵): 与 KS 熵相关，常用
  - q > 1: 增强常见事件权重
  - q < 1: 增强稀有事件权重
- `bins`: 直方图 bin 数，50 ~ 200

分散熵
------
- `m`: 嵌入维度，通常 2 ~ 3
- `c`: 类别数，通常 5 ~ 8，常用 6
- `normalize`: 建议 True


实践经验
=======

1. **选择哪种熵？**
   - 快速概览 → `permutation_entropy` 或 `spectral_entropy`
   - 精细分析 → `sample_entropy` 或 `fuzzy_entropy`
   - 多尺度结构 → `multiscale_entropy`
   - 频域复杂度 → `spectral_entropy` 或 `wavelet_entropy`

2. **处理短序列 (N < 200)**
   - 优先使用 `permutation_entropy`（对长度要求低）
   - `sample_entropy` 可能不稳定，考虑降低 m 或增大 r

3. **批量处理优化**
   - 所有函数支持多维数组，通过 `axis` 参数指定计算轴
   - 避免 Python 循环，直接传入 (n_samples, n_channels, n_timepoints) 数组

4. **结果解释**
   - 熵值高 → 信号复杂/不规则/随机
   - 熵值低 → 信号规则/可预测/周期性
   - 常数信号 → 熵值为 0

5. **常见问题**
   - 返回

"""

# 基础熵
from ._basic import sample_entropy, approximate_entropy, permutation_entropy

# 多尺度熵
from ._multiscale import multiscale_entropy, multiscale_entropy_mean

# 模糊熵
from ._fuzzy import fuzzy_entropy

# 谱域熵
from ._spectral import spectral_entropy, wavelet_entropy

# 广义熵
from ._generalized import (
    renyi_entropy,
    collision_entropy,
    tsallis_entropy,
    shannon_entropy,
)

# 分散熵
from ._dispersion import dispersion_entropy


__all__ = [
    # 基础熵
    'sample_entropy',
    'approximate_entropy',
    'permutation_entropy',
    # 多尺度熵
    'multiscale_entropy',
    'multiscale_entropy_mean',
    # 模糊熵
    'fuzzy_entropy',
    # 谱域熵
    'spectral_entropy',
    'wavelet_entropy',
    # 广义熵
    'renyi_entropy',
    'collision_entropy',
    'tsallis_entropy',
    'shannon_entropy',
    # 分散熵
    'dispersion_entropy',
]
