pudl

PUDL 数据浏览指南

此技能面向希望探索、了解和加载 PUDL 公共能源数据产品的数据用户。假设用户无法访问 PUDL Python 包或源代码仓库，只能使用公开分发的数据文件及其元数据。

PUDL 的主要输出是 Apache Parquet 文件，并由 Frictionless Data Package 描述符加以说明。如需了解通用的描述符查询模式（jq），请使用 datapackage 技能；本技能则在此基础上提供 PUDL 专属知识。

除主要 Parquet 输出外，PUDL 还分发按表单划分的原始 FERC Parquet 数据（涵盖 Forms 1/2/6/60/714，每种表单都有自己的 datapackage.json），以及 FERC EQR（分区 Parquet，与主构建分开）。这些数据的访问模式各不相同，且不包含在主要 Frictionless 描述符中——完整说明请参阅数据访问。

工作流概览

以下每一步成本都很低，只要与当前问题相关，就应默认执行，而不是只在用户明确提出时才执行。

1. 定位元数据——主要的 PUDL 描述符（Parquet 输出）位于：

   • S3：s3://pudl.catalyst.coop/nightly/pudl_parquet_datapackage.json
   • HTTPS：https://s3.us-west-2.amazonaws.com/pudl.catalyst.coop/nightly/pudl_parquet_datapackage.json

   按表单划分的原始 FERC 数据在每个表单／年代目录中都有自己的 datapackage.json，例如 s3://pudl.catalyst.coop/nightly/ferc1_xbrl/datapackage.json 和 s3://pudl.catalyst.coop/nightly/ferc1_dbf/datapackage.json——完整列表请参阅按表单划分的原始 Parquet 目录。

   FERC EQR（Electric Quarterly Reports）因体量较大而单独分发，且任一时刻只公开一个版本：

   • S3：s3://pudl.catalyst.coop/ferceqr/ferceqr_parquet_datapackage.json
   • HTTPS：https://s3.us-west-2.amazonaws.com/pudl.catalyst.coop/ferceqr/ferceqr_parquet_datapackage.json

   如需离线使用或用于开发，请通过以下命令将所有描述符下载到本地：

   python scripts/fetch_descriptor.py
   

   这会填充 assets/cache/。该脚本支持缓存——一天内缓存的文件会直接复用，不会发起网络请求，因此每次需要描述符时都可以安全地运行此脚本，无须先自行检查 assets/cache/。传入 --force 可跳过缓存，无论文件的新旧都重新获取（例如，你怀疑 PUDL 的架构今天发生了变化，需要获取最新副本时）。

   原始输入归档（用于溯源）位于 s3://pudl.catalyst.coop/zenodo/<dataset>/<concrete-doi>/datapackage.json。获取原始元数据和文件时，优先使用缓存的 S3 归档，而不是 Zenodo 网站或 API。源文档页面通常会提供覆盖整个数据集沿革的 concept DOI；S3 路径则使用指向某个特定归档版本的具体 DOI。详情请参阅数据质量与背景信息。

2. 有选择地查询元数据——使用 /datapackage 技能中的模式（jq）查找相关表、阅读说明并呈现警告。

   对于“PUDL 是否有关于 X 的数据”这类问题，不要仅凭已有印象找到一个匹配项就停止——应先对相关描述／代码字段进行更广泛的关键词检索（对于 FERC 账户，请参阅交叉参考 FERC Form 1 和 Form 2 的附表与账户；同样的做法也适用于其他数据源的 core_*__codes_* 表）。如果答案来自记忆而非检索，请明确指出。

3. 当元数据本身无法充分解释某事时，查阅一手来源的表单和说明——不要等到用户明确提出时才查阅。请参阅数据来源：空白表单和填报说明。

4. 检查表层级 — 参阅 数据质量与上下文。 优先使用 out_* 表；提醒用户注意 _core_* 表。

5. 连接表之前检查键 — 如果任务需要组合 FERC 来源表和 EIA 来源表（或任意两张表），先检查每张表的 schema.foreignKeys，并通过 utility_id_pudl / plant_id_pudl 连接公用事业单位和电厂，不要通过名称字符串匹配。参阅 PUDL 数据包扩展：连接 PUDL 表。

6. 查看方法论，再了解实现细节 — 如果用户询问 PUDL 如何清理、插补、分配、协调、估算或建模数据，请先阅读 方法论，并获取相关的公开方法论页面（在 URL 后附加 .md 供自己阅读；但向用户提供链接时，请使用普通的 .html 链接），然后再查看源代码、文档字符串或实现细节。总结公开方法论页面的内容，并将用户引导至该页面。只有在用户阅读过该说明后，或该主题没有方法论页面时，才深入了解代码级实现。

7. 高效加载数据 — 加载数据不一定意味着下载整张表。在 DuckDB 中使用 SELECT ... LIMIT、在 polars 中使用 pl.scan_parquet()，并在 .collect() 前调用 .select() / .filter()，或在 pandas 中使用 columns= 参数，都能将筛选操作下推至 Parquet 读取器本身。采样和缩减数据集应是探索表格的常规做法，而不是仅在发现文件过大时才使用的优化。进行完整、未筛选的加载之前，应先估算表格大小；只有任务确实需要所有行时，才加载整张表。具体加载模式请参阅 数据访问。

参考索引

• 数据源 — 如何查询 PUDL 描述符自身的 sources 数组（31 个数据集，包含简称、名称、许可信息和各数据源的 文档链接），以及在哪里查找和阅读各数据源的空白表格和填报说明；当用户询问特定 数据源数据集（EIA-860、FERC Form 714、EPA CEMS 等），或需要文档链接时阅读； 当解析原始归档 S3 路径、需要简称并且必须区分概念 DOI 和具体 DOI 时阅读； 或者在解读列、代码或报表的实际含义时阅读。
• 数据访问 — S3 路径、数据加载模式 （pandas/DuckDB/polars/纯 SQL）、按表单划分的原始 FERC Parquet 位置和 EQR 访问方式； 在生成数据加载代码或说明如何访问任何 PUDL 输出时阅读
• PUDL Datapackage 扩展 — 对标准 datapackage 架构的 PUDL 特定 补充：采用 RST/docstring 格式的描述、各资源的溯源字段、包级单位注册表，以及如何通过 utility_id_pudl/plant_id_pudl 跨 FERC/EIA ID 系统联接 表；在查询 PUDL 描述符上的 description 或其他非标准字段之前，以及在联接任意两个 PUDL 表之前阅读（通用描述符查询方法请使用 datapackage 技能）
• 数据质量与背景 — 表层级 命名约定（out_* 与 core_* 和原始数据）、警告类型，以及各层级对分析可靠性的 含义；当用户询问数据质量、需要在表层级间做出选择，或在提供加载代码前提示相关警告时阅读
• 方法论 — PUDL 数据处理和 建模方法论页面索引（实体解析、时间序列插补、所有权提取）；当用户询问 PUDL 如何 清理、协调、插补、分配、估算或建模数据时阅读。获取具体的公开方法论页面， 进行总结并指引用户查看，然后再深入介绍代码或文档字符串中的实现细节
• FERC 电力账户 — FERC 电力公用事业账户的完整分层科目表（资产负债表、电力设施、营业收入、运维费用）， 包含账户编号和说明；在解读 FERC Form 1 财务数据或用户询问特定 账户编号的含义时阅读——优先查询 ferc_electricity_accounts.json，而不是阅读此 文件
• FERC Form 1 报表 — 全部 75 份 Form 1 报表， 包含标题、说明和表格映射；当用户按编号或名称提及报表时阅读（例如“Schedule 301”、 “Page 400a”、“在役设施报表”）——优先查询 ferc1_schedules.json，而不是阅读此文件
• ferc1_schedules.json — 查询任何 FERC Form 1 报表或表格时，请先查询此文件；使用 jq 按关键词、账户编号或 PUDL 表名查找 报表，无需将完整 Markdown 加载到上下文中
• FERC Form 2 报表 — 全部 77 份 Form 2 报表， 包含标题、说明和 XBRL 表格映射（Form 2 尚未集成到 PUDL 中）；当用户提及 Form 2 报表 或询问天然气管道的财务或运营数据时阅读——优先查询 ferc2_schedules.json，而不是阅读此文件
• ferc2_schedules.json — 查询任何 FERC Form 2 报表或表格时，请先查询此文件；使用 jq 按关键词、账户编号或 XBRL 表名查找 报表，无需将完整 Markdown 加载到上下文中
• ferc_electricity_accounts.json — 查询任何 FERC Form 1（电力公用事业）账户编号时，请先查询此文件；使用 jq 确定账户 定义，并通过 ferc_accounts 数组与 Form 1 报表交叉引用

PUDL 特定约束

• 许可证：所有 PUDL 数据均以 Creative Commons Attribution 4.0 International (CC-BY-4.0) 许可证发布。用户可以自由使用、分享和改编数据，但须注明 Catalyst Cooperative。

• 引用：用户询问如何引用 PUDL 时，请提供以下参考文献：

  Selvans, Z., Gosnell, C., Sharpe, A., Schira, Z., Lamb, K., Belfer, E., Xia, D., & Mazaitis, K. The Public Utility Data Liberation (PUDL) Project [Data set]. Catalyst Cooperative. https://doi.org/10.5281/zenodo.3653158

  BibTeX：

  @misc{pudl,
    author       = {Selvans, Zane and Gosnell, Christina and Sharpe, Austen and
                    Schira, Zachary and Lamb, Katherine and Belfer, Ella and
                    Xia, Dazhong and Mazaitis, Kathryn},
    title        = {The Public Utility Data Liberation (PUDL) Project},
    publisher    = {Catalyst Cooperative},
    doi          = {10.5281/zenodo.3653158},
    url          = {https://doi.org/10.5281/zenodo.3653158},
  }
  

• S3 存储桶 s3://pudl.catalyst.coop 免费且可公开访问——无需 AWS 凭证；任何环境凭证（即使无效）都应明确绕过，而非假定其不存在。

• DuckDB、pandas 和 polars 都需要显式设置，才能可靠地查询此存储桶——请参阅 数据访问：DuckDB 和 S3 （s3_url_style 加上清除 S3 凭证设置；/query 也适用） 以及其下方的 pandas/polars 部分（匿名访问所需的 storage_options），了解各项设置的必要性。

• 核心 PUDL 输出表的 Parquet 路径为 s3://pudl.catalyst.coop/nightly/<table_name>.parquet。FERC 原始逐表数据使用不同的路径——请参阅 原始逐表 Parquet 目录。

• 提供加载代码前，始终先展示描述符中的使用警告。

• 方法论优先规则：如果存在与用户所询主题相关的公开方法论页面，应先使用该页面，再检查实现细节。代码层面的说明是后续步骤，而非默认的首选答复。

• 分析工作优先使用 out_* 表。如果用户询问某个主题但未指定表，应先搜索元数据中的 out_ 表。

• 使用 uv 安装 Python 包——优先使用 uv add <package>，而非 pip install <package>。uv 速度更快，并且会将包安装到虚拟环境，而非全局环境。只有在 uv 不可用时（command -v uv 无返回结果）才改用 pip；若如此，请将包安装到项目本地的虚拟环境中（如果不存在，则使用 python -m venv .venv 创建），而不是系统或全局 Python 环境。pip install --user 也不是安全的替代方案——它仍会将包写入用户的全局用户站点包目录，该目录由机器上的所有其他项目共享，而不是将更改限定在当前任务中。如果工作目录已有自己的环境管理工具（pixi、poetry、现有 venv 或 conda 环境），请使用该工具安装，而非引入第二套工具。

• PUDL 的 datapackage 描述符以几种 PUDL 特有的方式扩展了标准架构：采用 RST 格式、文档字符串风格的描述、逐资源来源元数据，以及包级单位注册表。使用 jq 查询 description 或其他非标准字段前，请阅读 PUDL Datapackage 扩展；该文档仅介绍 PUDL 特有的内容。通用的描述符查询机制请使用 datapackage 技能。

• 优先使用 ID 列连接 PUDL 表，而不是名称字符串列 （utility_name_ferc1、utility_name_eia、电厂名称等）——FERC 和 EIA 中名称相同的实体不一定属于同一家公司。通过 core_pudl__assn_* 交叉映射表，使用 utility_id_pudl / plant_id_pudl 进行连接，并先检查 schema.foreignKeys。没有可用的 ID 交叉映射时，可以使用名称匹配作为合理的后备方案，但在抽样检查之前，应将其结果视为未经验证。请参阅 PUDL 数据包扩展：连接 PUDL 表。

交叉引用 FERC Form 1 和 Form 2 的附表与账户

ferc1_schedules.json 和 ferc2_schedules.json 使用相同的架构。每条记录都有一个 ferc_accounts 数组，其中包含该附表引用的账户编号，这些编号已预先提取，可直接查找。按主题关键词搜索时使用 description；按账户编号交叉引用时使用 ferc_accounts。

快速查找模式（jq）：

# Find all Form 1 schedules that reference a specific account number
jq '[.[] | select(.ferc_accounts[] == "182.3")] | .[] | {schedule, title}' \
    assets/ferc1_schedules.json

# Find all Form 2 schedules that reference a specific account number
jq '[.[] | select(.ferc_accounts[] == "489.2")] | .[] | {schedule, title}' \
    assets/ferc2_schedules.json

# Get all account definitions for a specific Form 1 schedule
SCHED="232"
jq --arg s "$SCHED" '.[] | select(.schedule == $s) | .ferc_accounts[]' \
    assets/ferc1_schedules.json |
xargs -I{} jq --arg a {} '.[] | select(.account == $a)' assets/ferc_electricity_accounts.json

跨两个文件连接（jq）： 使用 --slurpfile 加载账户文件，并使用 INDEX() 构建账户编号查找表，然后将其与各附表的 ferc_accounts 数组连接：

# Find PUDL tables and account definitions for a Form 1 topic (e.g. "regulatory assets")
jq --slurpfile accounts assets/ferc_electricity_accounts.json '
  ($accounts[0] | INDEX(.account)) as $acct_lookup
  | .[]
  | select(.description | test("regulatory asset"; "i"))
  | .schedule as $sched | .title as $title | .pudl_tables as $tables
  | .ferc_accounts[]
  | {schedule: $sched, title: $title, pudl_tables: $tables,
     account: ., account_description: $acct_lookup[.].description}
' assets/ferc1_schedules.json

# Find Form 2 XBRL tables for a topic (e.g. "storage") — single file, no join needed
jq '[.[] | select(.description | test("storage"; "i"))] |
    .[] | {schedule, title, xbrl_tables}' assets/ferc2_schedules.json

委派

用户意图	交由
查询 datapackage.json 元数据	/datapackage
对数据运行 SQL 或自然语言查询	/query