3个Python脚本搞定抑郁症数据速查手册搭建

刚学完Python语法，对着空白的编辑器发呆？别急，这是90%新手都会遇到的“代码孤岛”困境。你会写 for 循环，会定义函数，但一让你搭个完整项目，脑子就一片空白。今天不聊虚的，直接上干货。我们要用Python从零搭建一个针对抑郁症筛查数据的自动化速查手册生成器。这不是为了做医疗诊断，而是为了帮助心理工作者、社区医生或HR快速整理患者自评量表（如PHQ-9）的统计分布、风险等级分类和关键指标汇总。很多机构还在用Excel手动统计，效率低且容易出错。我们要把这个过程代码化、自动化，生成一份清晰、可检索的PDF或Markdown格式速查手册。

项目目标与数据清洗

先明确我们要解决什么痛点。心理评估量表的数据通常是CSV或Excel格式，里面混杂着缺失值、异常值和不同编码格式的评分。我们的目标是：输入原始数据，输出结构化的风险分布报表。

这里有个关键细节：数据标准化。不同机构对“轻度抑郁”的分数段定义可能略有差异。我们参考GitHub开源仓库 psychometrics-tools 中的PHQ-9标准切分点，确保算法符合主流临床标准。

第一步是环境准备。你需要Python 3.8+，以及 pandas 和 numpy 这两个核心库。安装很简单：

pip install pandas numpy

接下来是数据加载与清洗。假设我们有一个 phq9_raw.csv 文件，包含 id, score, date, notes 四列。

import pandas as pd
import numpy as npdef load_and_clean_data(file_path):# 1. 读取CSV文件df = pd.read_csv(file_path)# 2. 处理缺失值：如果score为空，标记为'unknown'，后续单独统计df['score'] = df['score'].fillna(-1)# 3. 过滤无效数据：PHQ-9总分范围是0-27，超出视为异常df = df[(df['score'] >= 0) & (df['score'] <= 27)]# 4. 根据标准切分风险等级# 0-4: 无/极轻微, 5-9: 轻度, 10-14: 中度, 15-19: 中重度, 20-27: 重度def categorize_risk(score):if score <= 4:return 'Low'elif score <= 9:return 'Mild'elif score <= 14:return 'Moderate'elif score <= 19:return 'Moderately Severe'else:return 'Severe'df['risk_level'] = df['score'].apply(categorize_risk)return df

这段代码的逻辑非常清晰。fillna(-1) 是个小技巧，先占位再过滤，避免直接删除行导致数据量骤降。categorize_risk 函数是核心，它把连续的分数离散化为五个等级，这是生成速查手册中“风险分布图表”的基础。

目录结构设计

一个可维护的项目，目录结构比代码本身更重要。很多新手喜欢把所有代码塞进一个 main.py，这是大忌。我们采用模块化设计：

depression_manual_gen/
├── data/
│   └── phq9_raw.csv          # 原始数据
├── src/
│   ├── __init__.py
│   ├── data_processor.py     # 数据清洗与分类逻辑
│   ├── report_generator.py   # 报表生成逻辑
│   └── utils.py              # 通用工具函数
├── output/
│   └── generated/            # 最终生成的手册文件
├── requirements.txt          # 依赖库列表
└── main.py                   # 程序入口

在 src/utils.py 中，我们写一些通用函数，比如日期格式化、文件路径处理：

import os
from datetime import datetimedef ensure_dir_exists(path):"""确保目录存在，不存在则创建"""if not os.path.exists(path):os.makedirs(path)return pathdef get_current_date_string():"""获取当前日期字符串，用于文件命名"""return datetime.now().strftime("%Y%m%d")

这种结构的好处是，当你要更换数据源（比如从CSV换成SQL数据库）时，只需要修改 data_processor.py，而不用动报表生成逻辑。这就是工程化的意义。

核心代码实现

现在进入最核心的部分：统计分析与报表生成。我们要计算每个风险等级的占比、平均分、以及环比变化（如果有历史数据）。

在 src/report_generator.py 中，我们实现统计逻辑：

import pandas as pddef generate_statistics(df):"""生成统计摘要:param df: 清洗后的DataFrame:return: dict 包含各项统计指标"""# 1. 计算总人数total_count = len(df)# 2. 计算各风险等级人数risk_counts = df['risk_level'].value_counts()# 3. 计算各等级占比risk_percentages = (risk_counts / total_count) * 100# 4. 计算总体平均分avg_score = df['score'].mean()# 5. 计算中位数，排除极端值影响median_score = df['score'].median()# 构建结果字典stats = {'total_count': total_count,'avg_score': round(avg_score, 2),'median_score': round(median_score, 2),'risk_distribution': {'Low': {'count': int(risk_counts.get('Low', 0)), 'percent': round(risk_percentages.get('Low', 0), 2)},'Mild': {'count': int(risk_counts.get('Mild', 0)), 'percent': round(risk_percentages.get('Mild', 0), 2)},'Moderate': {'count': int(risk_counts.get('Moderate', 0)), 'percent': round(risk_percentages.get('Moderate', 0), 2)},'Moderately Severe': {'count': int(risk_counts.get('Moderately Severe', 0)), 'percent': round(risk_percentages.get('Moderately Severe', 0), 2)},'Severe': {'count': int(risk_counts.get('Severe', 0)), 'percent': round(risk_percentages.get('Severe', 0), 2)}}}return stats

注意这里的 round 函数，保留两位小数是报表的惯例，既精确又整洁。risk_distribution 是一个嵌套字典，方便后续直接渲染成Markdown表格。

接下来，我们把统计结果转换成Markdown格式的速查手册。Markdown比PDF更灵活，可以直接在GitHub或Confluence中查看。

def generate_markdown_report(stats, output_path):"""生成Markdown格式报表:param stats: 统计字典:param output_path: 输出文件路径"""# 构建Markdown内容md_content = f"# 抑郁症筛查数据速查手册\n\n"md_content += f"**生成时间**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"md_content += f"## 总体概览\n\n"md_content += f"- **样本总量**: {stats['total_count']} 人\n"md_content += f"- **平均分**: {stats['avg_score']}\n"md_content += f"- **中位数**: {stats['median_score']}\n\n"md_content += f"## 风险等级分布\n\n"md_content += f"| 风险等级 | 人数 | 占比 (%) |\n"md_content += f"| :--- | :---: | :---: |\n"# 遍历风险等级，生成表格行for level, data in stats['risk_distribution'].items():md_content += f"| {level} | {data['count']} | {data['percent']} |\n"md_content += f"\n## 建议与注意事项\n\n"md_content += f"1. 数据仅供统计参考，不能作为临床诊断依据。\n"md_content += f"2. 'Severe'等级人群建议优先进行专业评估。\n"# 写入文件with open(output_path, 'w', encoding='utf-8') as f:f.write(md_content)print(f"报表已生成: {output_path}")

这段代码的关键在于 f-string 的灵活运用。它让动态内容插入变得非常直观。特别是表格生成部分，通过循环拼接字符串，实现了从数据到可视化的直接转换。

运行与测试

万事俱备，只欠东风。在 main.py 中串联所有模块：

import os
from src.data_processor import load_and_clean_data
from src.report_generator import generate_statistics, generate_markdown_report
from src.utils import ensure_dir_exists, get_current_date_stringdef main():# 1. 配置路径data_file = 'data/phq9_raw.csv'output_dir = 'output/generated'ensure_dir_exists(output_dir)# 2. 生成带日期的文件名filename = f"depression_report_{get_current_date_string()}.md"output_file = os.path.join(output_dir, filename)# 3. 执行流程try:# 加载与清洗print("正在加载与清洗数据...")df = load_and_clean_data(data_file)# 统计print("正在计算统计数据...")stats = generate_statistics(df)# 生成报表print("正在生成Markdown报表...")generate_markdown_report(stats, output_file)print("任务完成！")except FileNotFoundError:print(f"错误: 找不到数据文件 {data_file}")except Exception as e:print(f"发生未知错误: {e}")if __name__ == "__main__":main()

运行 python main.py，你应该会在控制台看到进度提示，并在 output/generated 目录下得到一个 .md 文件。用VS Code打开它，你会看到一个排版整洁的表格，清晰展示了各风险等级的人数和占比。

测试环节不能少。你可以手动修改几行数据，比如把某个 score 改成28（超出范围），运行后确认它被正确过滤。或者把 score 设为空值，确认它被标记并排除在平均分计算之外。这种边界测试是保证生产环境稳定性的关键。

优化扩展

基础版本跑通了，但这只是起点。实际工作中，数据量可能达到十万级，或者需要更复杂的分析。这里有几个优化方向：

1. 性能优化 如果数据量极大，pandas 的 apply 函数会变慢。可以尝试向量化操作，或者使用 numpy 的直接索引。对于实时性要求高的场景，可以考虑引入 polars 库，它的速度比 pandas 快一个数量级。

2. 可视化增强 纯文本表格虽然清晰，但不够直观。引入 matplotlib 或 plotly，生成柱状图或饼图，并嵌入Markdown中。例如：

import matplotlib.pyplot as pltdef plot_risk_distribution(stats):levels = list(stats['risk_distribution'].keys())counts = [stats['risk_distribution'][level]['count'] for level in levels]plt.figure(figsize=(10, 6))plt.bar(levels, counts, color=['#2ecc71', '#f1c40f', '#e67e22', '#e74c3c', '#c0392b'])plt.title('Depression Risk Distribution')plt.ylabel('Count')plt.tight_layout()plt.savefig('output/generated/risk_chart.png', dpi=150)

3. 自动化部署 利用 cron (Linux) 或任务计划程序 (Windows)，每天凌晨自动运行脚本，将最新报表推送到企业微信或钉钉群。结合 Git，可以将生成的报表提交到内部仓库，形成历史趋势对比。

4. 隐私保护 医疗数据敏感。在 data_processor.py 中增加脱敏逻辑，比如对 id 列进行哈希处理，确保速查手册中不包含任何可识别个人身份的信息。这是合规的底线。