atai-newton-omega-model-data-prep

用途

Newton Data Prep 是一个建模前的数据准备流水线，专门处理多变量时间序列传感器数据。它的目标是把原始的多变量 dataframe 清洗、切分并特征化，最终交给下游的 KNN 或 Isolation Forest 分类器使用，输出形如 (X, y, metadata) 的数组。该技能位于 Omega 嵌入步骤之前（清洗）和之后（特征化），是 atai-newton-omega-model 的上游入口与下游出口。

主要能力

该技能捆绑三个可复用的构建模块：

DataPreprocessor — 诊断 + 缺口感知分块。所谓“块”（block）是指所有选定传感器都有数据、且没有超过 gap_threshold_samples 的连续 NaN 的连续片段。长缺口区域会被拆分为独立的块，因为跨长缺口插补等于伪造数据。它分两阶段使用：先调用 diagnose() 做只读诊断，返回结构化报告，涵盖采样率变异系数（规律性）、前 N 个缺口及其起止与大小、每列空值计数、每列最大连续空值长度；再调用 build() 生成清洗后的 dataframe，并新增 block_id（所属连续块）与 imputed（该行是否有传感器原本为 NaN）两列。位于长缺口区域内的行会被整体丢弃而非插补。
DataSplitter — 按时间顺序的 out-of-time 训练/测试切分。时间序列交叉验证若用随机切分，会把未来信息泄漏进训练集，造成虚假信心；OOT 切分则不会。默认使用 mode='oot'，mode='random' 仅建议作为“我到底有没有学到东西”的合理性检查，绝不用于生产切分。对于无监督任务（如 Isolation Forest），y 可以为 None。
FeaturePreparer — 联合状态特征化。把逐传感器逐窗口的嵌入 dataframe 转换为单一的 (X, y, metadata) 矩阵，每一行是某窗口下所有传感器的联合状态（拼接后的嵌入）。可选做 L2 归一化、标准化和/或 PCA 降维。

使用方式

完整流水线示例：

# 1. 诊断，然后清洗
prep = DataPreprocessor(timestamp_col='timestamp', sampling_rate_minutes=1, gap_threshold_samples=5)
report = prep.diagnose(df_raw, verbose=True)
df_clean = prep.build(df_raw)

# 2. 嵌入（见 atai-newton-omega-model）——每行对应一个 (传感器, 窗口)，含嵌入列
df_emb = embedding_generator.generate(
    df_clean, data_columns=['sensor_a', 'sensor_b'], label_columns=['machine_state'],
)

# 3. 特征化为 (X, y, metadata)
preparer = FeaturePreparer(normalize='l2', reduce_dim=50)
X, y, metadata = preparer.prepare(df_emb, label_column='machine_state')

# 4. 按时间顺序切分
splitter = DataSplitter(mode='oot', test_size=0.3)
X_train, X_test, y_train, y_test, meta_train, meta_test = splitter.split(X, y, metadata)

# 5. 交给自选分类器（KNN / IsolationForest）

本地安装：

python3 -m venv .venv && source .venv/bin/activate
pip install -r skills/atai-newton-omega-model-data-prep/references/requirements.txt
pip install matplotlib  # 可选：仅用于 diagnose() 的 plot=True

运行测试：

pip install -r skills/atai-newton-omega-model-data-prep/references/requirements.txt pytest
pytest skills/atai-newton-omega-model-data-prep/tests/ -v

适用场景

用户拥有原始多变量传感器 CSV（一个或多个传感器、不规则时间戳、NaN 缺口），准备用 atai-newton-omega-model 做嵌入，需要先清洗数据。
用户询问“要不要丢掉含 NaN 的行”“如何处理缺口”“时间序列怎样做训练/测试切分才合理”。
分类器表现异常好或异常差，怀疑存在时间泄漏时，可用 DataSplitter(mode='oot') 修正。
用户已有逐传感器嵌入（来自 Omega 模型），需要折叠成单一特征矩阵供 KNN 使用，即 FeaturePreparer 的用途。
用户希望把 atai-newton-omega-model 中描述的“联合状态”模式落实为代码。

限制与注意事项

不适用于视频、图像或文本任务（应使用 atai-newton-fusion-model）。
若数据本身已经干净（采样规律、无 NaN、无泄漏风险），该流水线会变成空操作，可直接把 dataframe 交给下游技能。
若需要只读的 go/no-go 预检门禁，应使用外部的 omega-1-4-preflight 检查；该预检不改动数据，而本技能会做分块、插补、降维等改动，两者互补。
常见陷阱：对时间序列做随机切分（几乎总是错的，应使用 mode='oot'）；跨长缺口插补（不要为了“造更多数据”而调高 gap_threshold_samples）；逐窗口标签不一致（应在标签传播策略处解决，而非关闭检查）；训练与测试使用不同的 sensor_order（会静默破坏预测，应显式固定）；在极小数据集上做 PCA（约 100 样本以下应跳过）。
该技能为纯本地数据整理，不需要 Newton API 密钥。

文件结构

skills/atai-newton-omega-model-data-prep/
├── SKILL.md
├── references/
│   ├── requirements.txt
│   ├── data_preprocessor.py
│   ├── data_splitter.py
│   └── feature_preparer.py
└── tests/
    ├── conftest.py
    ├── test_data_preprocessor.py
    ├── test_data_splitter.py
    └── test_feature_preparer.py

CI 会在任何触及 skills/atai-newton-omega-model-data-prep/** 的 PR 上自动运行测试套件。