Skip to content

README_cn.md

Latest commit

 

History

History
270 lines (213 loc) · 8.01 KB

README_cn.md

File metadata and controls

270 lines (213 loc) · 8.01 KB

DASMatrix

DASMatrix Logo

分布式声学传感数据处理与分析框架

Python 版本 许可证 CI 状态 文档 English Docs

📖 项目简介

DASMatrix 是一个专为分布式声学传感（DAS）数据处理和分析设计的高性能 Python 库。该框架提供了一整套工具，用于读取、处理、分析和可视化 DAS 数据，适用于地球物理学、结构健康监测、安防监控等领域的研究和应用。

✨ 核心特性

  • 🚀 高效数据读取：支持 12+ 种数据格式（DAT、HDF5、PRODML、Silixa、Febus、Terra15、APSensing、ZARR、NetCDF、SEG-Y、MiniSEED、TDMS），支持 Lazy Loading
  • ⚡ 分布式计算核心：基于 Xarray 和 Dask 构建，支持外存处理（Out-of-Core）
  • 🔗 流畅的链式 API：通过 DASFrame 提供直观的信号处理工作流
  • 🧠 AI 推理集成：原生支持 PyTorch 和 ONNX 模型，提供高性能推理流水线
  • 📊 专业信号处理：提供频谱分析、滤波、积分、事件检测等多种功能
  • 🤖 智能 Agent 工具：提供 AI Agent 调用的工具集，支持自然语言驱动的深度分析
  • 📈 科学级可视化：包含时域波形图、频谱图、时频图、瀑布图等多种可视化方式
  • 📏 单位系统：通过 Pint 集成提供完善的物理单位支持
  • 🎲 内置示例：便捷生成合成数据（正弦波、Chirp、模拟事件）用于测试

🚀 快速开始

安装

方式一：使用 uv (推荐)

# 克隆仓库
git clone https://github.com/QIanGua/DASMatrix.git
cd DASMatrix

# 使用 uv 安装（自动创建虚拟环境）
uv sync

方式二：使用 pip

# 克隆仓库
git clone https://github.com/QIanGua/DASMatrix.git
cd DASMatrix

# 使用 pip 安装
pip install -e .

基本使用

1. 使用 DASFrame 现代 API (推荐)

from DASMatrix import df

# 创建 DASFrame（延迟加载）
frame = df.read("data.h5")

# 构建处理流程
processed = (
    frame
    .detrend(axis="time")   # 去趋势
    .bandpass(1, 500)       # 带通滤波
    .normalize()            # 归一化
)

# 执行计算
result = processed.collect()

# 快速可视化
processed.plot_heatmap(title="Processed Waterfall")

2. 传统 API

from DASMatrix.acquisition import DASReader, DataType
from DASMatrix.config import SamplingConfig

# 配置采样参数
config = SamplingConfig(
    fs=10000,      # 采样频率 10kHz
    channels=512,  # 512 个通道
    wn=5.0,        # 5Hz 高通滤波
    byte_order="big"
)

# 读取数据
reader = DASReader(config, DataType.DAT)
raw_data = reader.read_raw_data("path/to/data.dat")

3. 可视化示例

from DASMatrix.visualization import DASVisualizer
import matplotlib.pyplot as plt

# 创建可视化器
visualizer = DASVisualizer(
    output_path="./output",
    sampling_frequency=config.fs
)

# 时域波形图
visualizer.WaveformPlot(
    data[:, 100],          # 第100通道的时域数据
    time_range=(0, 10),    # 显示0-10秒
    amplitude_range=(-0.5, 0.5),
    title="Waveform Plot",
    file_name="waveform_ch100"
)

# 频谱图
visualizer.SpectrumPlot(
    data[:, 100],
    title="Spectrum Plot",
    db_range=(-80, 0),
    file_name="spectrum_ch100"
)

# 时频图
visualizer.SpectrogramPlot(
    data[:, 100],
    freq_range=(0, 500),
    time_range=(0, 10),
    cmap="inferno",
    file_name="spectrogram_ch100"
)

# 瀑布图(时间-通道)
visualizer.WaterfallPlot(
    data,
    title="Waterfall Plot",
    colorbar_label="Amplitude",
    value_range=(-0.5, 0.5),
    file_name="waterfall"
)

plt.show()

4. AI 推理与模型预测

from DASMatrix.ml.model import ONNXModel

# 加载加速模型
model = ONNXModel("path/to/model.onnx")

# 在处理链中直接预测
predictions = (
    df.read("data.h5")
    .bandpass(10, 100)
    .normalize()
    .predict(model) # 返回推理结果
)

# 使用智能 Agent 工具
from DASMatrix.agent import DASAgentTools
agent_tools = DASAgentTools()
# 通过自然语言接口由 Agent 调度模型分析异常
result = agent_tools.run_inference(data_id="...", model_path="...")

API 迁移说明

项目已统一推荐 snake_case 风格接口。旧版 CamelCase 方法保留一个兼容周期，并会发出 DeprecationWarning。

旧接口 推荐接口
reader.ReadRawData(path) reader.read_raw_data(path)
processor.FKFilter(...) processor.fk_filter(...)
processor.ComputeSpectrum(...) processor.compute_spectrum(...)
processor.FindPeakFrequencies(...) processor.find_peak_frequencies(...)
DASMatrix.api.stream_func(...) DASMatrix.stream(...)

📚 文档

🏗️ 项目结构

DASMatrix/
├── acquisition/           # 数据获取模块
│   ├── formats/          # 格式插件
│   └── das_reader.py     # DAS数据读取类
├── api/                   # 核心 API
│   ├── dasframe.py       # DASFrame (Xarray/Dask 后端)
│   └── df.py            # 函数式 API 入口
├── ml/                    # [NEW] AI/机器学习模块
│   ├── model.py          # 模型封装 (Torch/ONNX)
│   ├── pipeline.py       # 推理流水线
│   └── exporter.py       # 模型导出工具
├── agent/                 # [NEW] Agent 工程框架
│   ├── tools.py          # 智能分析工具集
│   └── session.py        # 任务会话管理
├── config/                # 配置模块
│   ├── sampling_config.py # 采样配置
│   └── visualization_config.py  # 可视化配置
├── processing/            # Data处理模块
│   ├── das_processor.py  # DAS处理类
│   ├── numba_filters.py  # Numba优化滤波器
│   └── engine.py         # 计算图引擎
├── visualization/         # 可视化模块
│   └── das_visualizer.py # DAS可视化类
├── units.py               # 单位系统 (基于 Pint)
├── examples.py            # 示例数据生成
└── utils/                 # 工具函数
    └── time.py           # 时间转换工具

🔧 开发

开发环境设置

# 安装开发依赖
uv sync --dev

# 运行测试
just test

# 运行测试
just test

# 运行性能基准测试
just benchmark

# 代码质量检查
just check-all

# 快速修复
just fix-all

代码质量工具

  • Ruff: 代码检查和格式化
  • MyPy: 类型检查
  • Pre-commit hooks: 自动代码质量检查
  • GitHub Actions: CI/CD 流水线

🤝 贡献

欢迎贡献代码、提出问题或建议！请通过 GitHub Issues 和 Pull Requests 参与项目开发。

贡献指南

  1. Fork 本仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证。

🌟 Star 历史

Star History Chart

🇺🇸 English | 🇨🇳 中文