上个月帮朋友复现一份CHARLS数据分析光是算Framingham风险评分就耗了两个晚上。核心问题不在算法——计分公式早已公开可查真正折磨人的是数据本身血压测了三次到底用哪一次、总胆固醇单位怎么换算、吸烟和糖尿病的判定口径在不同问卷里不完全一致。这些细节任何一个出错审稿人只要抽查一例就能看出来整个结果的可靠性都会被打上问号。那段时间我干脆把整套计算过程封装成了一个可复用的函数charls_framingham_score。它面向CHARLS数据的实际结构做了适配只要把整理好的列名传进去几秒钟就能得到每个人的评分点数和10年心血管疾病风险概率。不少做数据分析的朋友看到之后问我底层逻辑和具体用法这篇就把函数的设计思路、操作流程、以及我在真实数据上踩过的坑完整梳理一遍。1. 手动计算Framingham评分到底难在哪CHARLS数据的三大现实问题1.1 数据不是拿来就能用的格式CHARLS作为大型追踪调查项目原始数据结构非常庞杂。单一主题的问卷变量分散在不同模块体检数据、血检数据和家庭问卷又往往分属不同的文件。你在做Framingham评分时起码要同时满足年龄、性别、总胆固醇、高密度脂蛋白胆固醇HDL-C、收缩压、降压药使用情况、吸烟状态、糖尿病状态这几类信息。把这些变量从原始问卷中一一提取并合并到同一张表上就是第一道坎。很多人第一次处理CHARLS时都会犯一个相同错误以为下载一个dta文件直接读进来就能开始算。实际上基线数据和随访数据要按个人ID精确匹配不同批次变量名还可能带有不同后缀甚至同一生理指标在两次测量中的字段含义也有细微差异。如果合并逻辑不严谨极容易出现ID错位、变量串行的问题。这类错误最危险——计算本身没有任何报错但结果完全不可用。1.2 评分模型有多套版本参数口径经常混用Framingham风险评分在文献中有多个版本。用得最广的是ATP III版本它基于Wilson在1998年提出的框架针对的是10年冠心病风险而DAgostino在2008年提出的改良版本则覆盖更广泛的心血管事件也就是大家常说的一般心血管疾病风险。这两个版本的计分权重完全不同年龄段划分也不同。有些人做CHARLS分析时参考A论文用了ATP III的计分表却在讨论里引用了B论文中基于DAgostino模型的风险阈值——这属于典型的版本混用在评审阶段极其致命。我在函数里默认采用ATP III框架计算传统Framingham评分点数同时保留对DAgostino风险表进行映射的选项用输出结果的字段加以区分从源头上避免口径混淆。1.3 缺失和异常值会悄无声息地污染结果CHARLS是实地调查数据存在大量缺失、拒绝回答和逻辑跳转。血压可能测了三次但某一次读数异常血检报告中的总胆固醇可能有超出合理生理范围的离群值吸烟问卷里还区分现在吸烟过去吸烟从不吸烟。如果不对这些情况做明确规则评分函数会在缺失值面前报错或者更隐蔽——用错误值算出一个看似合理、实际离谱的风险概率。charls_framingham_score在设计时就把这些问题作为一等公民处理而不是假设输入数据已经完美整洁。下面我会逐个拆解它是怎么处理这些现实问题的。2. charls_framingham_score的核心设计变量映射、计分逻辑与输出结构2.1 函数的输入参数不是随便传的先给一个最简调用示例再解释每个参数的含义from charls_framingham_score import charls_framingham_score result charls_framingham_score( datadf, age_colage, sex_colgender, tc_colchol_total, hdl_colchol_hdl, sbp_colsbp_mean, bp_treat_colbp_med, smoking_colsmoker_current, diabetes_coldiabetes_flag, modeatp3 )data接收一个标准的DataFrame各行代表一个受访样本。其余列参数指定对应的原始字段名。这里的关键是函数内部不会假设你的列名它完全依赖你传入的映射关系。这样做的好处是适应不同年份CHARLS数据之间变量名的变化比如2011年基线和2013年随访的血压变量命名规则略有不同只需要调整传入的列名核心计算逻辑完全复用。sex_col的编码也在内部做了兼容既接受男性为1、女性为0的数据格式也接受男性为1、女性为2的字符型格式甚至还能识别人数为Male/Female的字符串。让数据预处理环节少一层编码转换也能避免在性别语义上产生歧义。2.2 ATP III计分表的内部实现逻辑函数内部按照性别分别维护计分表。以基线场景中常见的40-79岁年龄段为例主要变量包括年龄、总胆固醇、HDL-C、收缩压、吸烟和糖尿病。每一项落在不同区间获得相应分数最后累加。年龄分组在不同性别中的积分曲线并不对称。比如在ATP III框架下男性年龄每跨越一个年龄段分数递增幅度明显女性则在绝经后阶段风险权重上升更快。这种性别差异不是统计噪声而是Framingham原始队列中真实的风险模式所以实现时必须严格区分两套计分表不能为了简化合并成一套。总胆固醇的计分区间分为160、160-199、200-239、240-279、≥280五档HDL-C则分为40、40-59、≥60三档。收缩压的计分会额外结合是否正在服用降压药服用者与未服药者的权重完全不同。这里我用一个内部字典来组织计分权重例如男性中年龄段与总胆固醇维度的交叉计分矩阵逻辑上是完整对应原表而不是近似拟合。2.3 输出的结果列是怎么设计的函数返回的DataFrame在原始数据基础上增加了三列列名类型说明fram_score_pointsintATP III框架下的累计风险分数即各单项分数之和fram_score_probfloat10年冠心病风险概率由总分映射得到risk_stratastr根据常见临床界值生成的风险分层low、moderate、highfram_score_prob的计算不是简单百分比而是通过Framingham原始研究中发布的10年绝对风险对应表实现分数到概率的映射。这个映射表在不同性别中是独立维护的所以函数内部会根据sex_col自动选择对应的查找表。总分如果超出表内上限按上限风险值处理总分低于下限则取下限风险值保证输出永远落在合理的概率区间内。risk_strata的界值也有讲究。传统Framingham工具一般分为10%、10%-20%、20%三档但很多医学研究在描述基线特征时会使用不同切点。函数默认按10%和20%这两个常用阈值分三层同时提供risk_cut_low和risk_cut_high参数允许你自行调整。该字段在设计上定位为辅助描述不是诊断依据。3. 完整落地实操从原始CHARLS数据到一键出分的全过程3.1 第一步把问卷数据对齐到统一的个人维度无论你用哪个wave的CHARLS数据第一步都建议先把人口学、生活方式、体检和血检数据合并到统一的个人ID维度上。CHARLS中每个人的唯一标识由家庭ID和个人ID组合而成合并时务必确保使用两者拼接后的ID单纯使用家庭ID会直接把同一家庭成员当作同一个人造成严重错配。实际操作中我习惯先对需要使用的数据文件分别检查ID变量的唯一性再执行merge。不同来源的数据可能存在重复ID条目比如一个人在同一次wave中有两套体检记录这种数据需要先按规则去重或决定保留哪一套以免合并后行数膨胀。合并完成后检查行数是否等于基线样本量这一步看似基础却能拦截掉大量合并异常。3.2 第二步构建函数要求的核心变量评分模型需要的最小变量集就是七个年龄、性别、总胆固醇、HDL-C、收缩压、降压药使用、吸烟、糖尿病。对于CHARLS这些变量的常见来源如下年龄由出生年份与调查年份计算注意CHARLS问卷中年龄字段是变化的建议根据出生日期动态计算。性别大部分wave里有直接字段清洗时统一编码。总胆固醇与HDL-C来自血检数据。注意血检报告的单位通常是mg/dL国内医院习惯使用mmol/L函数内部不做自动单位假设需要你在预处理时统一。收缩压CHALRS体检部分通常有多次读数。多数学术论文使用第二次或第三次读数的平均值也有研究使用三次读数平均我建议你明确写明自己选取的规则并且保持前后一致。降压药使用来自问卷部分需根据是否服用降压药物构建二值变量。吸烟常见口径是当前是否吸烟。注意要区分现在吸与过去吸Framingham标准模型只把当前吸烟视为风险因素。糖尿病可以使用自报诊断、空腹血糖、糖化血红蛋白等口径。自报比较简单但在以血糖值判定时需设定明确阈值。这一步是最耗时、最琐碎的部分。做一个辅助函数先把这些字段从原始数据中构建出来再统一格式转给charls_framingham_score会让后续迭代轻松很多。3.3 第三步调用函数并核对返回结果预处理完成后调用函数本身非常简单。以合并好的DataFrame为例scored_df charls_framingham_score( datamerged_df, age_colage_calc, sex_colgender_num, tc_coltc_mgdl, hdl_colhdl_mgdl, sbp_colsbp_mean, bp_treat_colanti_htn_med, smoking_colsmoke_now, diabetes_coldiab_final, modeatp3 )跑完之后不要急着拿去分析先做几项合理性检查。看fram_score_prob的分布范围绝大多数40岁以上人群的10年风险应该在1%到50%之间如果出现大量超过80%甚至等于100%的情况几乎可以肯定是变量构造出了问题。再按性别分别检查均值男性通常高于同龄女性三个月内没有生理机制让这个趋势反转。我曾在一份数据里发现50岁以上男性的平均风险概率高达61%当时第一反应是计分表映射出错但排查后发现问题出在糖尿病变量把空腹血糖值偏高的受试者全部标记成了糖尿病患者导致风险权重被系统性放大。所以评分结果本身也是对预处理质量的检验异常分布往往指向数据构造环节而不是函数本身。3.4 纵向数据的批量处理CHARLS是多期追踪调查不少研究会同时使用两到三个wave的数据。函数在纵向场景下同样适用只要在不同wave的数据上分别做合并和预处理再按ID纵向拼接即可。唯一要注意的是Framingham公式本身是针对10年风险设计的直接计算每个wave的风险概率在语义上各有独立含义不能把一个wave中10年风险较高就解读为另一wave的预测变化。更稳妥的做法是计算完毕后把风险分层当作时间变化的状态变量来使用而不是进行差值的简单计算。4. 真实数据上最容易翻车的三类问题缺失值、单位换算与判定口径4.1 血压变量多次测量到底取哪个CHARLS的血压测量通常在同一访问中重复多次常见的有三次。不同论文的取法有三种取第一次取第二次取三次平均值。这三种方式在数值上差异可能不大但在高龄人群中血压波动明显可能直接影响一个人的风险分层。比如收缩压135和142在计分权重上可能跨档对应分数发生变化最终导致风险从低危变成中危。函数本身不会替你决定取哪个值因为研究设计的要求可能各有不同。但你可以在预处理阶段统一处理。我的建议是如果你们课题组的统计计划书写的是以三次测量的平均值作为分析用血压那就严格计算平均值如果没写直接取后两次的平均值在流行病学中更常见因为第一次测量往往包含适应效应数值偏高。比取哪个值更隐蔽的问题是有些人三次测量并不完整可能只有两次甚至一次有效记录。对这类个体简单取平均会引入偏倚。我的处理习惯是如果有三次取三次平均如果只有两次取两次平均如果只有一次就保留这一次并单独标记让审稿人能明确看到你的缺失策略也方便主分析进行敏感性检验。4.2 总胆固醇和HDL-C单位换算差一点风险差一档Framingham计分表里的胆固醇区间是基于mg/dL设计的CHARLS血检数据通常也报告为mg/dL但国内不少医院和研究机构习惯于mmol/L。两者换算系数是乘38.6准确说是mmol/L→mg/dL乘38.67。比如某人总胆固醇5.0 mmol/L换算后大约是193 mg/dL在ATP III表里落在160-199档如果不换算直接按5.0进表就会落在最低档160评分直接少几分。这个错误极其常见因为数值刚好在正常范围内不会触发任何程序报错混在数据流里很难被发现。我把单位转换放在函数外的预处理阶段来做就是为了让转换逻辑对使用者可见。强烈建议你在代码里写明确注释并在最终表格中单独列出血脂列的单位无论论文还是内部复核都能一眼检查清楚。另外还需要留意一点部分CHARLS配套数据集中的血脂变量已经换算成了国际标准单位或者用不同字段名区分原始单位和导出单位。合并前一定要读变量说明文档确认使用的到底哪一列不能想当然地把chol开头的字段都当成同一单位。4.3 吸烟和糖尿病判定口径直接决定模型的预测方向吸烟变量在不同wave中的问卷设计有一定差异。一部分wave里区分现在吸与以前吸另一部分则直接问是否吸烟。Framingham模型在计分表中用的是当前吸烟这一二值状态所以函数内部要求smoking_col对应的列务必是0/1二值编码其中1代表当前正在吸烟。有人会把过去吸烟但已戒烟也计为1。这个偏差的影响比想象中大吸烟在计分表中通常占据数分权重放在10年风险上可能让一个本处于中危的患者被划入高危。审稿人如果看到戒烟者的吸烟标志被置为1会直接质疑数据处理可靠性。糖尿病判定则是另一个重灾区。CHARLS中有自报确诊、血糖值、糖化血红蛋白等多重信息来源。Framingham原始模型使用的糖尿病定义是临床诊断或正在接受降糖治疗也就是说它是一个二元状态不是血糖数值本身。如果你用空腹血糖阈值来判定一个未诊断但血糖偏高的个体就会被错误地标记为糖尿病患者。解决思路是优先使用自报确诊或降糖药物使用记录构建糖尿病变量。如果样本量不够必须用血糖值辅助判定建议同时对齐ADA或中国糖尿病防治指南的阈值标准并在代码注释中写明依据和判定规则。两个口径可以各建一版变量主分析使用临床诊断口径敏感性分析使用血糖辅助口径这样结果更扎实。5. 评分到手之后风险分层描述、合理性验证与进一步扩展5.1 把10年风险概率变成论文里的基线表格拿到fram_score_prob之后最常见的用途是作为基线特征纳入论文的Table 1。很多文章会报告全人群和分性别的平均10年心血管风险以及低危、中危、高危三组占比。这里有个特别容易被忽略的细节Framingham风险评分是为无心血管疾病史人群设计的如果你纳入了既往有心肌梗死或脑卒中病史的受访者计算出来的风险对这些个体没有临床预测价值必须事先排除或用单独类别描述。推荐的表格呈现方式是按性别分层报告。因为评分本质上是性别特异性的直接合并全人群均值会抹掉这种结构差异。我的做法是分别计算男性、女性各自的风险概率均值和标准差再用t检验或非参数检验比较组间差异。不同的CHARLS分析中常见的结果模式是女性平均风险低于男性但如果年龄结构差异大女性老年占比高时这一差异也可能被部分抵消。risk_strata三分类同样适合做Table 1分组变量。你可以按低危、中危、高危分别列样本量、年龄均值、性别占比等直观展示不同风险层级的人群画像。后续如果要做关联分析比如探讨某行为因素与心血管风险的关联这个分层变量也可直接作为有序多分类变量进入模型。5.2 怎么验证你算出来的风险是靠谱的我每次拿到新函数或新数据跑完分都会执行三道验证。先把全样本的风险概率分布画出来看是否有明显的极端堆积。正常数据下40岁组风险应该集中在低值区域70岁以上逐渐抬高曲线整体应单调。如果70岁以上出现回落往往是年龄字段计算有误或样本构成异常。第二道验证是把你的评分和CHARLS官方或已发表文献中的总体分布做粗略对比。北大相关团队和众多基于CHARLS发表的心血管论文通常会报告分析人群的平均Framingham风险概率。不必要求完全一致——随访年份、纳入排除标准、变量定义都可能引起差异——但数量级不应差出10个百分点以上。如果差异过大优先检查变量口径而不是模型实现。第三道验证是内部一致性抽查。另写一段代码从总样本中随机抽取几十人用临床线上Framingham计算器手工核对其中几例。即使只核对5例也能有效发现比例因子放错、维度错位等大问题。5.3 从Framingham评分出发还能做哪些扩展如果你熟练掌握这套数据整理与评分流程后续扩展其实水到渠成。CHARLS本身包含的身体功能量表、抑郁症状、社交参与、睡眠时长等模块都可以与Framingham风险分层做交叉分析。由于二次分析本身不是新的队列研究你的核心竞争力就在于把评分变量用得干净、透明。对R用户也可以把同一套逻辑改造为R函数对需要极简操作的人还可以进一步将评分函数封装进shiny应用或Python Web API让其他课题组成员通过界面提交CSV文件直接拿结果。这样处理的好处是数据清洗责任依然在数据提供方而评分计算得到统一口径不再出现三个人跑出来三种版本的情况。我个人在实际操作中的体会是任何评分工具的价值都建立在数据口径的严格定义之上。charls_framingham_score解决的只是从七个字段到三个结果指标这最后一段路的机械化工作真正决定分析质量的是你在预处理环节是否把每个变量的语义都搞得明明白白。建议在使用前把这个函数在自己的数据上跑通一次全空值测试——如果对所有变量都输入空值函数应该返回空结果而不是哑值这个行为本身就是对你的数据管线的第一层安全检查。