rf-datagen

rf-datagen是一个用于生成RF信号IQ数据集的工具，旨在为机器学习训练提供复杂IQ基带样本。它支持三个采样率域（窄带12 kHz、中等1 MHz、宽带20 MHz），每个域具有自己的窗口长度、数据类型和合成器注册表。输出存储为NumPy数组，每个窗口包含信号类别、SNR、场景和域等元数据。该生成器应用可配置的传播/接收器损伤场景，使模型能够针对现实信道条件进行训练。此外，rf-datagen还提供多层验证系统，包括结构验证、频谱指纹验证、往返解码验证和ML分类验证。

rf-datagen is a utility for generating RF signal IQ datasets, designed to provide complex IQ baseband samples for machine learning training. It supports three sample rate domains: narrowband (12 kHz), medium-band (1 MHz), and wideband (20 MHz), each with its own window length, data type, and synthesizer registry. Outputs are stored as NumPy arrays, with each window containing metadata such as signal category, SNR, scenario, and domain. This generator applies configurable propagation and receiver impairment scenarios, enabling models to be trained under realistic channel conditions. Additionally, rf-datagen provides a multi-layer validation system including structural validation, spectral fingerprint validation, round-trip decoding validation, and ML classification validation.

原始信息汇总

rf-datagen 数据集概述

数据集简介

rf-datagen 是一个用于机器学习训练的射频信号IQ数据集生成器，可合成39种业余无线电信号类别的复杂IQ基带样本，并包含现实的信道损伤。

信号类别（39种）

类别	模式
数字文本	CW, PSK31, PSK63, QPSK, PSK125, 8PSK, RTTY, OLIVIA, JS8, DOMINOEX, MT63, HELLSCHREIBER, MFSK16, MFSK32, CONTESTIA, THOR, FSQ, IFKP, THROB
WSJT-X	FT8, FT4, WSPR, JT65, JT9
模拟语音	SSB, AM, FM
图像	SSTV, FAX
数据	NAVTEX, PACKET
数字语音	FREEDV, M17, DMR, DSTAR, YSF, P25, NXDN
其他	NOISE

损伤场景

样本分布在可配置的传播/接收器场景中，包括：HF clean, HF good/poor, VHF mobile, UHF urban, SDR desktop, contest crowded, overdriven, poorly operated, vintage, near-far, auroral。信噪比水平和相对权重可配置。

先决条件

• Python >= 3.11
• NumPy, SciPy, Pillow, PySSTV（自动安装）
• 可选外部工具（按生成器需求）：
  • fldigi — fldigi（用于真实的fldigi编码数字模式）
  • wsjtx — wsjtx 工具（jt9, wsprd 等）
  • analog/digivoice — piper TTS引擎 + 语音模型
  • packet — direwolf（用于AX.25数据包编码）

安装方法

pip（仅Python）

bash pip install -e .

此方法安装Python包，但不安装外部CLI工具。需要单独提供这些工具，缺少工具的生成器会自动跳过。

Nix flake（推荐）

该flake提供了一个完整的开发环境，包含所有Python依赖项和外部CLI工具： bash nix develop

Nix flake + direnv

仓库包含一个.envrc文件，进入目录时环境会自动激活： bash direnv allow

devenv

如果使用devenv，可以直接使用该flake。在项目根目录创建devenv.nix或在devenv.yaml中指向该flake，然后激活： bash devenv shell

或使用direnv集成： bash direnv allow

使用方法

生成数据集

bash rf-datagen generate -c config.toml

列出信号类别

bash rf-datagen list

验证数据集

bash rf-datagen validate ./output

往返验证

bash rf-datagen validate-roundtrip # 所有模式 rf-datagen validate-roundtrip --clean-only --trials 3 # 快速检查

检查信号类别（从现有数据集）

bash rf-datagen inspect ./output --class FT8

质量控制检查工具

qc子命令可生成实时可视化和自包含的HTML报告，用于检查流水线阶段，无需预生成数据集。需要matplotlib。 bash

显示每种生成器类型的生成文本内容

rf-datagen qc text --generator analog --count 10 rf-datagen qc text --generator fldigi --mode PSK31

将TTS语音音频导出为WAV文件

rf-datagen qc audio --count 5 --output /tmp/qc/audio

可视化干净的调制信号（频谱图、波形、PSD）

rf-datagen qc modulated --mode FT8 CW --output /tmp/qc/modulated rf-datagen qc modulated --all-modes --snr-grid

可视化经过信道损伤后的信号

rf-datagen qc impaired --mode CW --all-snr --output /tmp/qc/impaired rf-datagen qc impaired --mode DMR --scenario hf_poor --snr 5

检查磁盘上现有的.npy数据集（类别分布、样本图）

rf-datagen qc dataset --path ./output --mode FT8 --output /tmp/qc/dataset

单一模式的完整自包含HTML报告（频谱图、音频、SNR网格、所有12种损伤场景、信号统计）

rf-datagen qc report --mode FT8 --output /tmp/qc/reports

配置

完整选项请参见config.toml。关键部分包括：

• [dataset] — 采样率、窗口长度、输出目录、种子、工作线程数
• [impairments] — 信噪比水平、频率偏移、场景权重
• [generators.*] — 每个生成器的启用/禁用、每类样本数以及生成器特定调优

输出格式

文件	描述
rf_datagen_iq.npy	(N, window_length) complex64数组 — 每行一个窗口
rf_datagen_tags.csv	每窗口元数据：模式、SNR、场景等

Flake输出

输出	描述
packages.*.default	包含所有外部工具（fldigi, wsjtx, piper等）在PATH中的CLI应用程序
packages.*.pythonPackage	用于下游flake中import rf_datagen的Python库包
devShells.*.default	包含Python依赖项和CLI工具的开发环境

Make目标

make generate # 运行完整生成 make validate # 验证数据集完整性 make validate-roundtrip # 往返编码/解码验证 make validate-quick # 快速验证（仅clean，3次试验） make validate-all # 所有模式（包括STT） make qc-report # HTML质量控制报告（默认：FT8；覆盖：make qc-report MODE=CW） make qc-modulated # 所有模式的频谱图/波形/PSD make qc-text # 显示所有生成器的文本内容 make clean # 删除生成的输出

许可证

MIT — 参见 https://github.com/Quantum-Serendipity/rf-datagen/blob/main/LICENSE

搜集汇总

数据集介绍

构建方式

在无线通信信号处理领域，高质量的数据集对于机器学习模型的训练至关重要。rf-datagen通过合成复杂的IQ基带样本，构建了一个包含39类业余无线电信号的多样化数据集。该生成器采用模块化设计，允许用户通过配置文件灵活调整窗口长度、采样率和信噪比水平。信号生成过程融合了多种外部工具，如fldigi用于数字模式编码、wsjtx用于WSJT-X模式，以及piper文本转语音引擎，确保信号的真实性和多样性。此外，生成器还引入了可配置的传播和接收损伤场景，模拟从高频清洁环境到拥挤竞赛条件等多种实际信道状况，使数据集能够全面反映现实世界中的信号变化。

特点

rf-datagen数据集以其广泛的信号类别和高度可配置的损伤模拟而脱颖而出。它涵盖了39种不同的业余无线电信号模式，包括数字文本、WSJT-X、模拟语音、图像传输和数据通信等多个类别，为信号分类任务提供了丰富的样本基础。数据集的核心特点在于其内置的损伤场景系统，支持12种不同的传播和接收条件，如高频良好/恶劣、超高频城市环境以及过载操作等，这些场景通过权重配置实现样本的均衡分布。输出格式采用高效的复杂64位NumPy数组，并附带详细的每窗口元数据，便于后续的数据分析和模型训练。这种设计使得数据集能够直接用于训练在真实信道条件下表现稳健的分类模型。

使用方法

使用rf-datagen生成数据集的过程简洁而高效。用户首先通过编辑config.toml文件来定义数据集参数，如采样率、窗口长度和损伤场景权重。随后，运行rf-datagen generate命令即可启动数据生成流程，该工具会自动处理信号合成、损伤添加和元数据记录。数据集生成后，用户可以利用内置的验证工具检查数据完整性，或使用qc子命令生成可视化报告，以评估信号质量和损伤效果。对于模型开发者，数据集以标准化的.npy和.csv格式输出，可直接集成到机器学习管道中。此外，该工具还支持作为库依赖项嵌入到其他项目中，通过Nix flake或Python包管理实现无缝部署，为无线通信信号分类研究提供了便捷的端到端解决方案。

背景与挑战

背景概述

在无线通信与机器学习交叉领域，射频信号分类是核心研究问题之一，旨在通过智能算法自动识别不同调制模式与通信协议。rf-datagen数据集由Quantum-Serendipity团队开发，作为一个合成射频信号IQ基带样本生成器，专注于为机器学习模型训练提供高质量数据。该数据集涵盖了39类业余无线电信号，包括数字文本、WSJT-X模式、模拟语音、图像传输及数字语音等多种通信方式，通过可配置的传播与接收损伤场景模拟真实信道条件，从而推动射频信号分类技术在实际复杂环境中的应用与发展。

当前挑战

射频信号分类领域面临的主要挑战在于信号模式的多样性与信道环境的复杂性，例如多径衰落、噪声干扰及频率偏移等现实因素会严重影响分类准确性。rf-datagen在构建过程中需克服合成数据与真实世界信号间的差距，通过集成外部工具如fldigi、wsjtx和direwolf来生成高保真信号，同时确保损伤场景的配置能全面反映HF、VHF、UHF等不同频段的典型传播条件。此外，数据生成流程需平衡计算效率与信号真实性，并维护多工具依赖的稳定集成，以支持大规模、可复现的数据集创建。

常用场景

经典使用场景

在无线通信与机器学习交叉领域，rf-datagen数据集为射频信号分类任务提供了标准化的训练与评估基准。该数据集通过合成复杂IQ基带样本，覆盖了39种业余无线电信号类别，包括数字文本、WSJT-X模式、模拟语音、图像传输及数字语音等广泛类型。其经典使用场景在于为深度学习模型提供具备真实信道损伤的合成数据，支持研究人员在可控环境下训练信号分类器，以应对实际通信中常见的多径衰落、噪声干扰和频率偏移等挑战。

实际应用

在实际应用层面，rf-datagen数据集被广泛部署于业余无线电监测、频谱管理与安全通信系统中。例如，在无线电频谱感知任务中，该数据集训练的模型可用于自动识别非法传输或干扰信号，提升频谱使用效率。此外，在应急通信和军事通信领域，基于该数据集的分类器能够实时甄别不同通信模式，辅助决策系统优化资源分配。其合成数据还支持软件定义无线电平台的算法验证，降低了实地数据采集的成本与复杂性，为工业界的通信设备测试与优化提供了可靠工具。

衍生相关工作

围绕rf-datagen数据集，已衍生出多项经典研究工作，主要集中在射频信号分类的深度学习架构创新与跨领域应用拓展上。例如，研究者利用该数据集开发了基于卷积神经网络和时序模型的混合分类器，显著提升了多模式信号在低信噪比环境下的识别准确率。此外，结合生成对抗网络的数据增强技术，进一步扩展了数据集的多样性与真实性。这些工作不仅推动了射频机器学习社区的算法进步，还为卫星通信、物联网频谱感知等新兴应用场景提供了方法论基础，形成了从数据生成到模型部署的完整研究生态。