nflreadpy / nflverse Loader 是一个面向 NFL 数据分析的数据获取技能，目标是产出有文档记录、由用户自行持有的 NFL 数据产物，并保证其粒度符合分析需求。它要求记录赛季、加载函数与参数、检索时间、已安装包版本、来源发布、模式、自然键、行数、过滤条件与转换过程。
用途 该技能用于获取 NFL 数据，包括赛程与比分、逐回合数据、名册、球员或球队统计、出场次数、伤病，以及其他 nflverse 发布内容。非 NFL 来源应使用相应的公共包。当来源尚未确定时使用 data-sources；在把载入字段转为前瞻性预测变量之前先使用 feature-rules。核心原则是：不要让来源加载隐式决定分析粒度、预测截点或合法特征集。
安装 python -m pip install nflreadpy polars pyarrow 首次检索可能需要网络访问。需要记录包版本，并对任何用于持久结论的数据进行缓存或快照。
发布选择 根据需求选择最窄的起始发布：结果或赛程模型用 schedules，典型粒度为比赛，主要时序风险是未来/未进行与状态行；比赛分析用 play-by-play，粒度为回合，风险是赛后字段与驱动摘要；球员身份用 rosters，粒度为球员-球队-赛季/周，风险是把当前名册当作历史；球员表现用 player stats，粒度为球员-周/场/赛季，风险是聚合与可用性截点；参与度用 snap counts，粒度为球员-比赛，只有事件发生后才知道；可用性用 injuries，粒度为球员报告，风险是修订时间与报告阶段。选择发布时可阅读 references/nflverse_releases.md。应选择包含所需字段的最窄来源；例如只问赛程就不要加载所有赛季的逐回合数据。
直接加载 import nflreadpy as nfl seasons = [2022, 2023, 2024] schedules = nfl.load_schedules(seasons) pbp = nfl.load_pbp([2024]) player_stats = nfl.load_player_stats(seasons) rosters = nfl.load_rosters([2024]) 加载函数的可用性、返回类型与模式可能随发布变化。在假定某函数、列、dtype 或自然键存在之前，先检查已安装接口与一个有界结果： import nflreadpy as nfl print(getattr(nfl, "version", "unknown")) print([name for name in dir(nfl) if name.startswith("load_")])
获取工作流
- 锁定问题、分析粒度、赛季与所需字段；
- 选择最窄的 nflverse 发布；
- 先加载一个赛季并检查对象类型、模式、行数、空值与键；
- 在规范化或过滤前保存不可变原始快照；
- 识别赛程状态值，区分已排期、已完成、延期、取消与缺失比分；
- 校验球队代码、比赛标识、日期、周、赛季与比分单位；
- 在独立的派生产物中规范化，保留来源列或映射；
- 保存 Parquet 以及 JSON 或 Markdown 清单；
- 在目标粒度上校验产物并记录已知缺口；
- 把显式保存的产物交给 EDA、特征或建模工作。
团队-比赛契约 当派生为每队每场一行时，至少要求：game_id、season、week、gameday、team、opponent、is_home、game_type、points_for、points_against、won、tied、point_diff。可考虑保留 status、season type、开球时间戳、中立场标志、加时/平局指示与原始球队标识。已完成的非平局比赛应产生两条互补行：得分与分差互为反向，主客场标志相反，且恰好一个 won 为真。平局时两个 won 可能都为假，因此要保留显式 tied 标志。在把赛程规范化为团队-比赛行之前阅读 references/panel_contract.md，并保留原始赛程行以便审计每个派生行。
校验检查 原始比赛粒度：请求的赛季与赛季类型存在；game_id 唯一或重复有解释；已完成比赛有两支球队且比分合理；主客队不同；周、日期、赛季与状态字段内部一致；按赛季报告重复与缺失率；未来或未完成事件不被误标为已完成。 派生团队-比赛粒度：每场纳入比赛恰好两行；team/opponent 与 home/away 值互补；points-for/against 与分差在配对中反向；won、tied 与 point_diff 遵循文档化标签规则；在行数旁报告唯一比赛数；整体行级胜率应被解释为构造属性，而非主场优势。
连接 优先使用稳定的球员/球队/比赛标识而非显示名；检查连接基数与未匹配率；名册、伤病与周表使用文档化的 as-of 时间戳；搬迁与历史球队缩写要显式映射，不要静默重写。
体育特定陷阱 双面板陷阱：由于每场比赛贡献对手行，整体胜率约为 0.5，主场优势应从主队行估计。赛后特征陷阱：EPA、最终比分、出场份额与许多汇总都是事件后才知道，需要滞后或不同的决策时间。名册后见之明：当前名册不是历史名册快照。周排序：延期与重新排期可能导致周标签与事件时间顺序不同，as-of 特征应使用时间戳。平局：两队 won == 0 不等同于两场失利。模式漂移：列与 dtype 可能跨发布或赛季变化，拼接前要校验。标识符：显示名连接可能重复或错配球员，应使用 ID。
快照清单 记录：来源（nflverse via nflreadpy）、包版本、加载函数与参数、检索时间戳（UTC）、请求与观察到的赛季、原始产物路径与校验和、派生产物路径与校验和、粒度与自然键、行数与唯一事件数、过滤与状态规则、模式或模式路径、转换与标识映射、已知缺口与校验结果。
硬约束与完整性规则 优先使用文档化发布加载器而非临时抓取；赛程或统计足够时不要加载宽泛的逐回合数据；没有 as-of 规则时不要把原始赛后字段用作赛前预测变量；不要把当前名册当作历史；除非明确目的是预测未来事件，否则不要在未完成事件上训练结果模型；存在稳定 ID 时不要用球员姓名连接；不要静默重写历史球队代码或模式；不要在没有考虑配对比赛行的情况下对双面板建模；对用于结论的确切数据做快照；绝不要吞掉加载/模式错误并返回空产物作为成功。
反模式 为比分问题拉取每个赛季的每个回合；在开球前模型中使用赛后 EPA；从完整团队-比赛面板胜率声称主场优势；把当前名册连接到历史比赛；在检查模式漂移前拼接赛季；只保留规范化输出而没有来源快照；只报告行数而隐藏重复比赛；重试循环轰炸公共基础设施或掩盖失败。
辅助工具 python <path-to-nflreadpy>/scripts/smoke_load.py --season 2024 python <path-to-nflreadpy>/scripts/load_game_panel.py --seasons 2023-2024 --game-types REG --raw-out data/nfl_schedules.parquet --out data/nfl_team_games.parquet python <path-to-nflreadpy>/scripts/describe_panel.py --input data/nfl_team_games.parquet 所有辅助工具在导入 nflreadpy 前解析 --help。输出文件由用户持有，可被任何 dataframe 或建模工具使用。面板辅助工具默认常规赛（REG）比赛，在每个派生行记录 game_type，并要求请求范围可从来源验证。当分析包含季后赛时，传入显式的逗号分隔范围，如 REG,WC,DIV,CON,SB。面板辅助工具不替代清单审查或决策时特征校验。
示例 对于赛前主场优势分析，加载赛程而非逐回合，在显式状态规则下保留已完成的常规赛比赛，保存原始 Parquet，派生配对的团队-比赛行，并同时报告唯一比赛数与行数。在 is_home == 1 上计算主场率；不要使用完整面板的率。
输出契约 返回产物路径、来源发布、包版本、检索时间戳、加载参数、请求/观察到的赛季、粒度、自然键、行与事件数、列/模式、过滤、转换、已知缺口与合理性检查结果。指明下一个产物消费者，而不要求特定项目。
资源 references/nflverse_releases.md——在选择最窄 NFL 发布时阅读。references/panel_contract.md——在构建或校验配对团队-比赛行之前阅读。scripts/smoke_load.py——有界来源探测。scripts/load_game_panel.py——原始赛程到团队-比赛导出。scripts/describe_panel.py——独立面板校验与摘要。