本文介绍如何将带变更标记的文档词序数据按语义一致性（连续词号、相同变更类型、段落对齐）进行智能分组，生成结构化的 doc1/doc2 词号列表及合并后的 change_type。
本文介绍如何将带变更标记的文档词序数据按语义一致性（连续词号、相同变更类型、段落对齐）进行智能分组，生成结构化的 doc1/doc2 词号列表及合并后的 change_type。
在文档比对（如法律修订、版本控制、编辑追踪）场景中，原始标注数据常以“词号-变更类型-段落映射”三元组形式存在。但直接分析单行记录难以反映真实编辑行为——例如，连续插入多个词应归为同一逻辑操作；跨段落的删除/插入需与上下文段落对齐后聚合。本教程提供一套基于 Pandas 的稳健分组策略，将离散的 word_number 映射转化为语义连贯的变更块（change block），输出符合业务直觉的 [doc1_words], [doc2_words], change_type 三列结构。
核心思路是构建三层嵌套分组器（g1, g2, g3），分别捕获：
- 词序连续性（g1）：word_number.diff().ne(1).cumsum() 检测非递增+1的断点，确保 [5,6,8] 不被误拆（因 8-6=2≠1，故与 5,6 同组）；
- 变更语义一致性（g2）：忽略中间的 0（无变更）和 -1（缺失段落），用 ffill() 填充有效变更类型（如 1→0→0→1 视为 1→1→1→1），再按变化点分组，使插入操作跨多个“无变更”行仍保持逻辑统一；
- 段落对齐稳定性（g3）：对 doc1_paragraph_number 和 doc2_paragraph_number 同时处理，将 -1 替换为 None 后前向填充，再计算行间差值——仅当任一列段落号发生跳变（如 1→2 或 None→3）时触发新组，确保同一变更块内段落映射关系稳定。
以下是完整可运行代码（含关键注释与健壮性增强）：
import pandas as pd
import numpy as np
def group_document_changes(df):
"""
将细粒度词级变更数据聚合成语义变更块。
Parameters:
df (pd.DataFrame): 必须包含列 'word_number', 'change_type',
'doc1_paragraph_number', 'doc2_paragraph_number'
Returns:
pd.DataFrame: 列为 ['doc1', 'doc2', 'change_type']
"""
# Step 1: Group by consecutive word_number (allowing gaps like [5,6,8])
g1 = df['word_number'].diff().ne(1).cumsum()
# Step 2: Group by semantic change type (ignore transient 0/-1)
# Replace 0 and -1 with NaN, forward-fill real changes (1 or -1), then group
c = df['change_type'].replace({0: np.nan, -1: np.nan}).ffill().fillna(0)
g2 = c.diff().ne(0).cumsum()
# Step 3: Group by stable paragraph alignment
# Extract paragraph columns, mask -1 as NaN, ffill, then detect paragraph shifts
para_cols = ['doc1_paragraph_number', 'doc2_paragraph_number']
tmp_para = df[para_cols].replace(-1, np.nan)
filled_para = tmp_para.ffill()
# Detect row where either paragraph number changed vs previous non-NaN value
g3 = filled_para.diff().ne(0).any(axis=1).cumsum()
# Combine all groupers
groups = df.groupby([g1, g2, g3], sort=False)
# Aggregate: for each group, collect word_numbers where paragraph is valid (-1 excluded)
def collect_words(series):
mask = (series['doc1_paragraph_number'] != -1) | (series['doc2_paragraph_number'] != -1)
return series.loc[mask, 'word_number'].tolist()
result = groups.apply(lambda x: pd.Series({
'doc1': x[x['doc1_paragraph_number'] != -1]['word_number'].tolist(),
'doc2': x[x['doc2_paragraph_number'] != -1]['word_number'].tolist(),
'change_type': x['change_type'].max() # Use max to prioritize 1 over 0/-1 in mixed groups
})).reset_index(drop=True)
return result
# 示例使用
# df = pd.read_clipboard() # 或从CSV加载
# grouped_df = group_document_changes(df)
# print(grouped_df)⚠️ 注意事项：
- change_type 聚合采用 .max() 是因业务逻辑中 1（插入）和 -1（删除）优先级高于 0（无变更），混合组取最大值更符合“该块存在实质性变更”的判断；
- 若需严格按原始顺序保留空列表（如 doc1=[] 表示全删除），当前逻辑已通过布尔掩码 x['doc1_paragraph_number'] != -1 精确过滤；
- 对于超长文档，建议在分组前对 word_number 排序（df.sort_values('word_number')），避免因输入乱序导致 diff() 计算异常。
最终输出的 DataFrame 直接支持下游任务：生成差异报告、高亮变更区域、统计插入/删除词数等。此方法不依赖外部NLP库，纯Pandas实现，兼具可解释性与工程落地性。
