df-merger

核心用法

Df Merger 是一款专为建筑工程领域设计的 pandas DataFrame 合并工具，旨在解决 BIM、进度计划、成本估算、传感器等多源数据的整合难题。该技能提供三层核心能力：

基础合并功能：ConstructionDFMerger 类支持五种标准合并策略（inner/left/right/outer/cross），内置智能键值检测算法，可自动识别 element_id、type_name、level 等建筑领域常见列名的多种变体形式，实现跨数据源的语义对齐。

专业场景扩展：针对典型工程场景提供专用子类——BIMScheduleMerger 实现 BIM 构件与进度活动的模糊匹配关联，，CostQTOMerger 完成成本单价与工程量清单的自动计价计算，支持 extended_cost 字段的衍生计算。

高级匹配能力：fuzzy_merge 方法基于 SequenceMatcher 实现阈值可控的模糊字符串匹配，适用于描述字段不一致但语义相近的数据对齐场景，如类型名称与 WBS 描述的关联。

显著优点

1. 领域知识内置：预置 10 组建筑工程标准列名映射（如 element_id 对应 guid/globalid/elem_id 等 5 种变体），大幅降低数据预处理工作量
2. 智能键值发现：无需手动指定合并键，自动检测共同列并优先选择 ID-like 字段
3. 质量量化评估：返回 merge_quality 分数（0-1）及匹配/未匹配行数统计，便于数据质量监控
4. 链式多表合并：merge_multiple 支持任意数量 DataFrame 的顺序外连接
5. 零外部依赖：仅依赖 pandas、numpy、difflib 标准库，部署轻量

潜在缺点与局限性

• 性能瓶颈：fuzzy_merge 采用 O(n×m) 双重循环实现，万级数据量即可能出现明显延迟，不适合大规模实时匹配
• 阈值敏感性：模糊匹配默认 0.8 阈值可能过高或过低，需根据具体数据分布调参，缺乏自适应机制
• 内存占用：多表外连接可能产生稀疏矩阵，大数据集需谨慎评估内存
• 无持久化能力：纯内存计算，不提供结果缓存或增量更新机制
• 匹配逻辑单一：仅支持字符串相似度匹配，无数值范围匹配、空间位置匹配等工程常用模式

适合的目标群体

• 施工数字化工程师：整合 BIM 与 ERP/PM 系统数据
• 成本估算师：快速关联工程量清单与造价数据库
• 进度计划工程师：将 4D BIM 与 Primavera/MS Project 数据对齐
• 数据分析师：处理多承包商提交的异构报表
• 高校研究人员：建筑信息化（BIM+GIS+IoT）相关课题研究

使用风险

• 数据一致性风险：自动列名标准化可能误将语义不同的列视为同一字段，建议关键合并前人工校验映射结果
• 模糊匹配误判：相似描述可能对应不同工程实体，高阈值下仍可能产生错误关联，重要决策场景建议人工复核
• 性能降级风险：未对输入数据规模做限制，超大 DataFrame 可能导致内存溢出或响应超时
• 版本兼容性：依赖 pandas 合并 API，跨大版本升级时需验证行为一致性

核心用法

Df Merger 是一个面向建筑信息化（AEC）领域的专业数据处理 Skill，专注于解决多源异构数据的整合难题。核心功能包括：

1. 智能列名标准化：内置 COLUMN_MAPPINGS 字典，自动识别语义相似的列名（如 element_id/elementid/elem_id/guid），通过字符串归一化和相似度计算（SequenceMatcher > 0.8）实现跨系统字段对齐。

2. 多策略合并引擎：封装 pandas 的五种合并策略（inner/left/right/outer/cross），并返回 MergeResult 结构化结果，包含匹配行数、未匹配统计及质量评分（0-1）。

3. 模糊匹配功能：针对 BIM 类型名称与进度 WBS 描述等无精确键值场景，提供基于阈值的模糊字符串匹配，支持自定义相似度阈值。

4. 领域专用子类：

• BIMScheduleMerger：BIM 元素与进度计划数据整合
• CostQTOMerger：成本单价与工程量清单（QTO）自动计算扩展成本

显著优点

• 开箱即用的建筑语义库：预置 10 余类常用字段映射（ID、类型、楼层、材料、体积、面积、成本、任务、日期等），大幅降低数据清洗工作量。
• 质量可视化：独创 merge_quality 评分机制，量化数据对齐效果，辅助识别数据治理问题。
• 渐进式合并：merge_multiple 支持多表链式合并，适合 4D/5D BIM 多维度数据整合场景。
• 类型安全：完整类型注解（typing + dataclass + Enum），符合现代 Python 工程规范。

局限性与风险

• 无实际执行能力：本 Skill 为纯 Markdown 文档，代码块仅作演示，实际使用需用户自行部署 Python 环境并安装 pandas/numpy。
• 模糊匹配性能瓶颈：SequenceMatcher 时间复杂度为 O(n²)，万级以上数据量需预建索引或改用 rapidfuzz 等高效库。
• 映射规则固化：COLUMN_MAPPINGS 为类级硬编码，非英语项目或自定义字段体系需手动扩展。
• 无实时同步机制：仅支持离线批量处理，不涉及数据库连接或 API 实时拉取。

适用人群

• BIM 数据工程师、造价分析师、施工进度管理人员
• 需整合 Revit 导出表格、Primavera P6/MicroProject 进度、ERP 成本数据的跨系统数据工作流
• 建筑信息化（Digital Construction）学术研究及教学场景

常规风险

• 数据一致性依赖输入质量：工具仅执行合并逻辑，不校验数据本身的业务正确性（如工程量单位统一、币种换算）。
• 模糊匹配误报：低阈值（<0.7）可能导致错误匹配，建议高敏感场景人工复核匹配映射表。
• 内存限制：大规模 DataFrame（百万行级）合并可能触发 OOM，需分块处理策略。