Pywayne Plot

面向专业时频分析的增强型语谱图可视化工具。

快速开始

import matplotlib.pyplot as plt
from pywayne.plot import regist_projection, parula_map
import numpy as np

# 注册自定义投影
regist_projection()

# 创建语谱图
fig, ax = plt.subplots(subplot_kw={'projection': 'z_norm'})
spec, freqs, t, im = ax.specgram(
    x=signal_data,
    Fs=100,
    NFFT=128,
    noverlap=96,
    cmap=parula_map,
    scale='dB'
)
ax.set_ylabel('Frequency (Hz)')
plt.colorbar(im, label='Magnitude (dB)')
plt.show()

函数

regist_projection

注册自定义的 SpecgramAxes 投影。必须在使用增强型 specgram 功能前调用。

from pywayne.plot import regist_projection
regist_projection()

SpecgramAxes.specgram

具备高级特性的增强型语谱图绘制方法。

关键参数：

返回值：

• spec —— 二维语谱图数组（形状为 (n_freqs, n_times)）
• freqs —— 频率轴数组
• t —— 时间轴数组
• im —— matplotlib 图像对象（用于 colorbar）

get_specgram_params

根据信号特征自动推荐 STFT 参数。

from pywayne.plot import get_specgram_params

params = get_specgram_params(
    signal_length=10000,
    sampling_rate=100,
    time_resolution=0.1  # 或 freq_resolution=0.5
)
# 返回：NFFT、noverlap、actual_freq_res、actual_time_res、n_segments

parula_map

适用于科学可视化的 MATLAB 风格感知均匀色图。

from pywayne.plot import parula_map
plt.imshow(data, cmap=parula_map)

使用示例

IMU 信号分析

fs = 100  # 采样率
win_time, step_time = 1, 0.1

fig, ax = plt.subplots(subplot_kw={'projection': 'z_norm'})
spec, freqs, t, im = ax.specgram(
    x=acc_data,
    Fs=fs,
    NFFT=int(win_time * fs),
    noverlap=int((win_time - step_time) * fs),
    scale='dB',
    cmap=parula_map
)
ax.set_ylabel('Frequency (Hz)')
ax.set_ylim(0, 30)

生理信号（PPG — 心率）

# 将 Hz 转换为 bpm，用于心率可视化
fig, ax = plt.subplots(subplot_kw={'projection': 'z_norm'})
spec, freqs, t, im = ax.specgram(
    x=ppg_signal,
    Fs=100,
    NFFT=400,
    noverlap=300,
    freq_scale=60,  # Hz -> bpm
    scale='dB'
)
ax.set_ylabel('Heart Rate (bpm)')
ax.set_ylim(40, 180)

采用全局归一化的振动分析

fig, ax = plt.subplots(subplot_kw={'projection': 'z_norm'})
spec, freqs, t, im = ax.specgram(
    x=vibration_data,
    Fs=1000,
    NFFT=1024,
    noverlap=512,
    scale='linear',
    normalize='global'
)
plt.colorbar(im, label='Normalized Magnitude')

采用零填充的高分辨率分析

fig, ax = plt.subplots(subplot_kw={'projection': 'z_norm'})
spec, freqs, t, im = ax.specgram(
    x=signal,
    Fs=100,
    NFFT=100,
    pad_to=512,  # 零填充以获得更平滑的频谱
    noverlap=80,
    scale='dB'
)

缩放与归一化模式

缩放模式

归一化模式（仅对 scale='linear' 有效）

频率缩放

示例：freq_scale=60 将 2 Hz → 120 bpm

分辨率指导原则

• 频率分辨率：Δf = Fs / NFFT
• 时间分辨率：Δt = (NFFT − noverlap) / Fs
• 权衡关系：无法同时实现高频率分辨率与高时间分辨率

可使用 get_specgram_params() 自动计算最优参数。

交互式分析

spec, freqs, t, im = ax.specgram(...)

def on_click(event):
    if event.xdata and event.inaxes == ax:
        time_idx = np.argmin(np.abs(t - event.xdata))
        plt.figure()
        plt.plot(freqs, spec[:, time_idx])
        plt.title(f'FFT at t={event.xdata:.2f}s')
        plt.show()

fig.canvas.mpl_connect('button_press_event', on_click)

应用领域

• IMU 数据：加速度计与陀螺仪分析
• 生理信号：PPG（心率）、ECG、呼吸信号
• 振动分析：机械设备故障诊断
• 音频处理：语音与音频频谱分析

注意事项

• 使用 projection='z_norm' 前，务必先调用 regist_projection()
• 推荐使用 parula_map 以获得最佳感知均匀性
• dB 模式会自动处理 log(0) 异常
• 为提升 FFT 计算效率，建议将 NFFT 设为 2 的整数次幂