SWMM结果分析进阶：用Python+pandas深度挖掘.OUT文件中的水文过程线

暴雨模型（SWMM）的.OUT文件就像一座未经开采的数据金矿，里面蕴藏着节点水深、管道流量、污染物浓度等宝贵的时间序列数据。但大多数工程师止步于用pyswmm库将二进制数据导出为Excel，却错过了隐藏在时序波动中的水文规律。本文将带您超越基础数据导出，用pandas玩转水文过程线的时空分析技巧。

1. 从数据导出到过程线分析的技术跃迁

传统的数据导出操作相当于把纸质报告扫描成PDF，而我们要做的是用自然语言处理技术解析报告中的语义关系。pyswmm输出的DataFrame只是原材料，真正的价值在于：

• 时间维度：识别降雨响应滞后时间、峰值到达时间、退水曲线斜率
• 空间维度：对比上游节点与下游管道的流量相位差
• 统计维度：计算95%峰值持续时间、洪峰流量重现期

# 典型的过程线分析代码结构示例
def analyze_hydrograph(df):
    # 重采样为5分钟间隔
    resampled = df.resample('5T').mean()  
    # 计算峰值特征
    peak_flow = resampled['flow'].max()
    peak_time = resampled['flow'].idxmax()
    # 计算涨落洪时间
    rising_time = (peak_time - resampled[resampled['flow']>0].index[0]).total_seconds()/60
    return {
        'peak_flow_m3s': round(peak_flow,3),
        'peak_time': peak_time.strftime('%H:%M'),
        'rising_minutes': int(rising_time)
    }

过程线分析的三个认知层级：

1. 基础层：单一节点的水深时间序列
2. 进阶层：多节点流量过程线的相位对比
3. 专家层：污染物负荷与水力特征的耦合分析

2. 时间序列的深度清洗与重构

原始.OUT文件数据往往存在时间戳不齐、缺失值、异常值等问题。就像考古学家修复文物，我们需要先还原数据的本来面貌。

2.1 时间对齐的魔法技巧

SWMM输出常有不规则时间步长，使用pandas的resample方法可重建完整时间轴：

# 创建包含完整时间索引的DataFrame
full_index = pd.date_range(
    start=df.index.min(),
    end=df.index.max(),
    freq='5T'  # 5分钟间隔
)
reindexed = df.reindex(full_index)

# 前向填充+线性插值组合拳
processed = reindexed.ffill().interpolate()

常见时间处理陷阱：

• 夏令时转换导致的时间跳跃
• 模拟初始期的数据震荡
• 报告步长大于分析需求时的信息丢失

2.2 异常值检测的四象限法

通过统计和可视化结合识别问题数据：

检测方法	适用场景	pandas实现
3σ原则	正态分布数据	df[(df-df.mean()).abs()>3*df.std()]
IQR过滤	非对称分布	df[df>df.quantile(0.75)+1.5*(df.quantile(0.75)-df.quantile(0.25))]
滚动标准差	突变动检测	df[df.rolling(6).std()>threshold]
物理极值校验	超越理论最大值	df[df>pipe_capacity]

3. 水文特征参数的智能提取

超越简单的最大最小值计算，我们需要提取具有水文意义的特征参数。

3.1 洪峰特征的全自动识别

from scipy.signal import find_peaks

def detect_peaks(series, height=None, distance=10):
    peaks, _ = find_peaks(series, height=height, distance=distance)
    troughs, _ = find_peaks(-series, distance=distance)
    return {
        'peak_indices': peaks,
        'peak_values': series.iloc[peaks],
        'trough_indices': troughs,
        'trough_values': series.iloc[troughs]
    }

典型洪峰参数计算：

• 起涨时间：流量超过基流10%的时刻
• 峰现时间：流量达到最大的时刻
• 退水时长：从峰值回落至90%峰值的时间
• 涨洪斜率：单位时间内的流量增加率

3.2 过程线分解技术

将复合过程线分解为直接径流和基流组分：

# 数字滤波法基流分割
def baseflow_separation(q, alpha=0.925):
    b = np.zeros_like(q)
    b[0] = q[0]
    for i in range(1, len(q)):
        b[i] = alpha*b[i-1] + (1-alpha)*(q[i]+q[i-1])/2
    return pd.Series(b, index=q.index)

组分分析结果示例：

组分类型	体积(m³)	占比(%)	峰值(m³/s)	峰现延迟(min)
直接径流	1250	68	2.41	35
基流	580	32	0.87	-

4. 多要素协同分析实战

单独分析流量或水深就像只听交响乐中的小提琴声部，真正的艺术在于各声部的配合。

4.1 流量-水深-流速三维关系

# 创建三维散点图
fig = plt.figure(figsize=(10,8))
ax = fig.add_subplot(111, projection='3d')
ax.scatter(
    df['depth'], 
    df['velocity'],
    df['flow'],
    c=df.index.hour,
    cmap='viridis'
)
ax.set_xlabel('水深(m)')
ax.set_ylabel('流速(m/s)')
ax.set_zlabel('流量(m³/s)')

典型流态识别：

1. 压力流：水深大、流速高但流量稳定
2. 明渠流：三者呈现明显线性关系
3. 过渡流：数据点分布在曲线带中

4.2 污染物输移的滞后效应分析

计算流量峰值与浓度峰值的时移：

# 计算交叉相关系数
def calc_lag(flow, conc, max_lag=12):
    corr = [flow.corr(conc.shift(lag)) for lag in range(-max_lag, max_lag+1)]
    best_lag = np.argmax(corr) - max_lag
    return best_lag * (flow.index[1]-flow.index[0]).total_seconds()/60

某雨水口分析结果：

• TSS浓度峰值滞后流量峰值约17分钟
• 初期冲刷效应明显：前30%流量携带了62%污染物负荷
• 最大浓度出现在流量上升段而非峰值时刻

5. 分析成果的专业化呈现

科研级可视化需要超越简单的折线图，展现水文分析的深层洞察。

5.1 过程线的增强型可视化

import matplotlib.dates as mdates

def enhanced_hydrograph(df, title):
    fig, ax = plt.subplots(figsize=(12,6))
    
    # 主过程线
    ax.plot(df.index, df['flow'], label='流量', color='#1f77b4')
    
    # 洪峰标注
    peaks = detect_peaks(df['flow'])
    ax.scatter(df.index[peaks['peak_indices']], 
               peaks['peak_values'], 
               color='red', zorder=5)
    
    # 背景着色
    ax.fill_between(df.index, 0, df['flow'], 
                    where=(df['flow']>df['flow'].quantile(0.9)),
                    color='lightcoral', alpha=0.3)
    
    # 时间轴格式化
    ax.xaxis.set_major_formatter(mdates.DateFormatter('%H:%M'))
    ax.grid(True, which='both', linestyle='--', alpha=0.6)
    ax.set_title(title)

5.2 专业报告中的表格呈现

表：主要水文特征参数统计

参数名称	上游节点	中游节点	下游节点	单位
洪峰流量	2.41	3.15	3.02	m³/s
峰现时间	14:25	14:38	14:45	--
涨洪历时	35	42	50	min
洪量	1250	1830	1750	m³
峰现滞后降雨峰值	65	78	85	min

在某个城市内涝分析项目中，通过这种深度分析发现：下游检查井的峰值流量反而小于中游节点。进一步排查发现是管道逆坡导致的排水能力下降，这个发现直接影响了后续改造方案的设计。