Source code for pudl.metadata.resources.eia923
"""Definitions of data tables primarily coming from EIA-923."""
from typing import Any
[docs]
TABLE_DESCRIPTIONS: dict[str, str] = {
"_core_eia923__fgd_operation_maintenance": (
"""EIA-923 FGD Operation & Maintenance, from EIA-923 Schedule 8C.
Reports annual information about flue gas desulfurization systems at generation facilities,
mainly operational expenses. From 2008-2011 this table also reported operational
characteristics that are now reported in 923 Air Emissions Control Info.
Note: This table has been cleaned, but not harvested with other EIA 923 or 860 data.
The same variables present in this table may show up in other _core tables in other
years. Once this table has been harvested, it will be removed from the PUDL database."""
),
"_core_eia923__cooling_system_information": (
"""EIA-923 Cooling System Information, from EIA-923 Schedule 8D.
Reports monthly information about cooling systems at generation facilities,
mainly water volumes and temperatures. In 2008 and 2009, EIA only reports
annual averages, but in later years all data is monthly.
Note: This table has been cleaned, but not harvested with other EIA 923 or 860
data. The same variables present in this table may show up in other _core
tables in other years. Once this table has been harvested, it will be removed
from the PUDL database."""
),
"core_eia923__monthly_boiler_fuel": (
"""EIA-923 Monthly Boiler Fuel Consumption and Emissions, from EIA-923 Schedule 3.
Reports the quantity of each type of fuel consumed by each boiler on a monthly basis, as
well as the sulfur and ash content of those fuels. Fuel quantity is reported in standard
EIA fuel units (tons, barrels, Mcf). Heat content per unit of fuel is also reported,
making this table useful for calculating the thermal efficiency (heat rate) of various
generation units.
This table provides better coverage of the entire fleet of generators than the
``core_eia923__monthly_generation_fuel`` table, but the fuel consumption reported here is not directly
associated with a generator. This complicates the heat rate calculation, since the
associations between individual boilers and generators are incomplete and can be
complex.
Note that a small number of respondents only report annual fuel consumption, and all of
it is reported in December."""
),
"core_eia923__monthly_fuel_receipts_costs": (
"""Data describing fuel deliveries to power plants, reported in EIA-923 Schedule 2, Part A.
Each record describes an individual fuel delivery. There can be multiple deliveries of
the same type of fuel from the same supplier to the same plant in a single month, so the
table has no natural primary key.
There can be a significant delay between the receipt of fuel and its consumption, so
using this table to infer monthly attributes associated with power generation may not be
entirely accurate. However, this is the most granular data we have describing fuel
costs, and we use it in calculating the marginal cost of electricity for individual
generation units.
Under some circumstances utilities are allowed to treat the price of fuel as proprietary
business data, meaning it is redacted from the publicly available spreadsheets. It's
still reported to EIA and influences the aggregated (state, region, annual, etc.) fuel
prices they publish. From 2009-2021 about 1/3 of all prices are redacted. The missing
data is not randomly distributed. Deregulated markets dominated by merchant generators
(independent power producers) redact much more data, and natural gas is by far the most
likely fuel to have its price redacted. This means, for instance, that the entire
Northeastern US reports essentially no fine-grained data about its natural gas prices.
Additional data which we haven't yet integrated is available in a similar format from
2002-2008 via the EIA-423, and going back as far as 1972 from the FERC-423."""
),
"core_eia923__monthly_generation": (
"""EIA-923 Monthly Generating Unit Net Generation. From EIA-923 Schedule 3.
Reports the net electricity generated by each reporting generator on a monthly basis.
This is the most granular information we have about how much electricity individual
generators are producing, but only about half of all the generation reported in the
``core_eia923__monthly_generation_fuel`` appears in this table due to the different reporting
requirements imposed on different types and sizes of generators.
Whenever possible, we use this generator-level net generation to estimate the heat rates
of generation units and the marginal cost of electricity on a per-generator basis, but
those calculations depend on plant-level fuel costs and sometimes uncertain or
incomplete boiler-generator associations.
Note that a small number of respondents only report annual net generation, and all of
it is reported in December."""
),
"core_eia923__monthly_generation_fuel": (
"""EIA-923 Monthly Generation and Fuel Consumption Time Series. From EIA-923 Schedule 3.
Monthly electricity generation and fuel consumption reported for each combination of
fuel and prime mover within a plant. This data can't be easily linked to individual
boilers, generators, and generation units, but it is provides the most complete coverage
of fuel consumption and electricity generation for the entire generation fleet. We use
the primary fuels and prime movers reported for each generator along with their
capacities to attribute fuel consumption and generation when it isn't directly reported
in the ``core_eia923__monthly_generation`` and ``core_eia923__monthly_boiler_fuel`` tables in order to calculate
capacity factors, heat rates, and the marginal cost of electricity.
The table makes a distinction between all fuel consumed and fuel consumed for
electricity generation because some units are also combined heat and power (CHP) units,
and also provide high temperature process heat at the expense of net electricity
generation.
Note that a small number of respondents only report annual fuel consumption and net
generation, and all of it is reported in December."""
),
"core_eia923__monthly_generation_fuel_nuclear": (
"""EIA-923 Monthly Generation and Fuel Consumption Time Series. From EIA-923 Schedule 3.
Monthly electricity generation and fuel consumption reported for each combination of
fuel and prime mover within a nuclear generation unit. This data is originally reported
alongside similar information for fossil fuel plants, but the nuclear data is reported
by (nuclear) generation unit rather than fuel type and prime mover, and so has a
different primary key."""
),
"generation_fuel_combined_eia923": (
"""EIA-923 Monthly Generation and Fuel Consumption Time Series. From EIA-923 Schedule 3.
Denormalized, combined data from the ``core_eia923__monthly_generation_fuel`` and
``core_eia923__monthly_generation_fuel_nuclear`` with nuclear generation aggregated from the nuclear
generation unit level up to the plant prime mover level, so as to be compatible with
fossil fuel generation data."""
),
"core_eia923__monthly_energy_storage": (
"""EIA-923 Monthly Generation and Fuel Consumption Time Series. From EIA-923 Schedule 3.
Monthly quantities of energy consumed and discharged ("generated") by energy storage
units. The total MWh discharged from the energy storage unit during the
reporting period is the gross generation and the difference between gross generation
and consumption is the net generation."""
),
}
[docs]
RESOURCE_METADATA: dict[str, dict[str, Any]] = {
"core_eia923__monthly_boiler_fuel": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_boiler_fuel"],
"schema": {
"fields": [
"plant_id_eia",
"boiler_id",
"energy_source_code",
"prime_mover_code",
"fuel_type_code_pudl",
"report_date",
"fuel_consumed_units",
"fuel_mmbtu_per_unit",
"sulfur_content_pct",
"ash_content_pct",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"boiler_id",
"energy_source_code",
"prime_mover_code",
"report_date",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"out_eia923__boiler_fuel": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_boiler_fuel"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"boiler_id",
"unit_id_pudl",
"energy_source_code",
"prime_mover_code",
"fuel_type_code_pudl",
"fuel_consumed_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"sulfur_content_pct",
"ash_content_pct",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"boiler_id",
"energy_source_code",
"prime_mover_code",
"report_date",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__yearly_boiler_fuel": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_boiler_fuel"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"boiler_id",
"unit_id_pudl",
"energy_source_code",
"prime_mover_code",
"fuel_type_code_pudl",
"fuel_consumed_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"sulfur_content_pct",
"ash_content_pct",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"boiler_id",
"energy_source_code",
"prime_mover_code",
"report_date",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__monthly_boiler_fuel": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_boiler_fuel"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"boiler_id",
"unit_id_pudl",
"energy_source_code",
"prime_mover_code",
"fuel_type_code_pudl",
"fuel_consumed_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"sulfur_content_pct",
"ash_content_pct",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"boiler_id",
"energy_source_code",
"prime_mover_code",
"report_date",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"core_eia923__entity_coalmine": {
"description": (
"""Attributes of coal mines reporting deliveries in the Fuel Receipts and Costs table, via
EIA-923 Schedule 2, Part C.
This table is produced during the transformation of fuel delivery data, in order to
produce a better normalized database. The same coalmines report many individual
deliveries, and repeating their attributes many times in the fuel receipts and costs
table is duplicative. Unfortunately the coalmine attributes do not generally use a
controlled vocabulary or well defined IDs and so in practice there are many distinct
records in this table that correspond to the same mines in reality.
We have not yet taken the time to rigorously clean this data, but it could be linked
with both Mining Safety and Health Administration (MSHA) and USGS data to provide more
insight into where coal is coming from, and what the employment and geological context
is for those supplies."""
),
"schema": {
"fields": [
"mine_id_pudl",
"mine_name",
"mine_type_code",
"state",
"county_id_fips",
"mine_id_msha",
"data_maturity",
],
"primary_key": ["mine_id_pudl"],
"foreign_key_rules": {"fields": [["mine_id_pudl"]]},
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"core_eia923__monthly_fuel_receipts_costs": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_fuel_receipts_costs"],
"schema": {
"fields": [
"plant_id_eia",
"report_date",
"contract_type_code",
"contract_expiration_date",
"energy_source_code",
"fuel_type_code_pudl",
"fuel_group_code",
"mine_id_pudl",
"supplier_name",
"fuel_received_units",
"fuel_mmbtu_per_unit",
"sulfur_content_pct",
"ash_content_pct",
"mercury_content_ppm",
"fuel_cost_per_mmbtu",
"primary_transportation_mode_code",
"secondary_transportation_mode_code",
"natural_gas_transport_code",
"natural_gas_delivery_contract_type_code",
"moisture_content_pct",
"chlorine_content_ppm",
"data_maturity",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"out_eia923__fuel_receipts_costs": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_fuel_receipts_costs"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"state",
"contract_type_code",
"contract_expiration_date",
"energy_source_code",
"fuel_type_code_pudl",
"fuel_group_code",
"supplier_name",
"fuel_received_units",
"fuel_mmbtu_per_unit",
"fuel_cost_per_mmbtu",
"bulk_agg_fuel_cost_per_mmbtu",
"fuel_consumed_mmbtu",
"total_fuel_cost",
"fuel_cost_from_eiaapi",
"sulfur_content_pct",
"ash_content_pct",
"mercury_content_ppm",
"primary_transportation_mode_code",
"secondary_transportation_mode_code",
"natural_gas_transport_code",
"natural_gas_delivery_contract_type_code",
"moisture_content_pct",
"chlorine_content_ppm",
"data_maturity",
"mine_id_msha",
"mine_name",
"mine_state",
"coalmine_county_id_fips",
"mine_type_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__yearly_fuel_receipts_costs": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_fuel_receipts_costs"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"state",
"fuel_type_code_pudl",
"fuel_received_units",
"fuel_mmbtu_per_unit",
"fuel_cost_per_mmbtu",
"fuel_consumed_mmbtu",
"total_fuel_cost",
"fuel_cost_from_eiaapi",
"sulfur_content_pct",
"ash_content_pct",
"mercury_content_ppm",
"moisture_content_pct",
"chlorine_content_ppm",
"data_maturity",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__monthly_fuel_receipts_costs": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_fuel_receipts_costs"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"state",
"fuel_type_code_pudl",
"fuel_received_units",
"fuel_mmbtu_per_unit",
"fuel_cost_per_mmbtu",
"fuel_consumed_mmbtu",
"total_fuel_cost",
"fuel_cost_from_eiaapi",
"sulfur_content_pct",
"ash_content_pct",
"mercury_content_ppm",
"moisture_content_pct",
"chlorine_content_ppm",
"data_maturity",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"core_eia923__monthly_generation": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_generation"],
"schema": {
"fields": [
"plant_id_eia",
"generator_id",
"report_date",
"net_generation_mwh",
"data_maturity",
],
"primary_key": ["plant_id_eia", "generator_id", "report_date"],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"out_eia923__generation": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_generation"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"generator_id",
"unit_id_pudl",
"net_generation_mwh",
"data_maturity",
],
"primary_key": ["plant_id_eia", "generator_id", "report_date"],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__monthly_generation": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_generation"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"generator_id",
"unit_id_pudl",
"net_generation_mwh",
"data_maturity",
],
"primary_key": ["plant_id_eia", "generator_id", "report_date"],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__yearly_generation": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_generation"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"generator_id",
"unit_id_pudl",
"net_generation_mwh",
"data_maturity",
],
"primary_key": ["plant_id_eia", "generator_id", "report_date"],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"core_eia923__monthly_generation_fuel": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_generation_fuel"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"energy_source_code",
"fuel_type_code_pudl",
"fuel_type_code_aer",
"prime_mover_code",
"fuel_consumed_units",
"fuel_consumed_for_electricity_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"fuel_consumed_for_electricity_mmbtu",
"net_generation_mwh",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"prime_mover_code",
"energy_source_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"out_eia923__generation_fuel_combined": {
"description": TABLE_DESCRIPTIONS["generation_fuel_combined_eia923"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"energy_source_code",
"fuel_type_code_pudl",
"fuel_type_code_aer",
"prime_mover_code",
"fuel_consumed_units",
"fuel_consumed_for_electricity_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"fuel_consumed_for_electricity_mmbtu",
"net_generation_mwh",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"prime_mover_code",
"energy_source_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__yearly_generation_fuel_combined": {
"description": TABLE_DESCRIPTIONS["generation_fuel_combined_eia923"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"energy_source_code",
"fuel_type_code_pudl",
"prime_mover_code",
"fuel_consumed_units",
"fuel_consumed_for_electricity_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"fuel_consumed_for_electricity_mmbtu",
"net_generation_mwh",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"prime_mover_code",
"energy_source_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"out_eia923__monthly_generation_fuel_combined": {
"description": TABLE_DESCRIPTIONS["generation_fuel_combined_eia923"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"plant_id_pudl",
"plant_name_eia",
"utility_id_eia",
"utility_id_pudl",
"utility_name_eia",
"energy_source_code",
"fuel_type_code_pudl",
"prime_mover_code",
"fuel_consumed_units",
"fuel_consumed_for_electricity_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"fuel_consumed_for_electricity_mmbtu",
"net_generation_mwh",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"prime_mover_code",
"energy_source_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "outputs",
},
"core_eia923__monthly_generation_fuel_nuclear": {
"description": TABLE_DESCRIPTIONS[
"core_eia923__monthly_generation_fuel_nuclear"
],
"schema": {
"fields": [
"plant_id_eia",
"report_date",
"nuclear_unit_id",
"energy_source_code",
"fuel_type_code_pudl",
"fuel_type_code_aer",
"prime_mover_code",
"fuel_consumed_units",
"fuel_consumed_for_electricity_units",
"fuel_mmbtu_per_unit",
"fuel_consumed_mmbtu",
"fuel_consumed_for_electricity_mmbtu",
"net_generation_mwh",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"nuclear_unit_id",
"energy_source_code",
"prime_mover_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"_core_eia923__cooling_system_information": {
"description": TABLE_DESCRIPTIONS["_core_eia923__cooling_system_information"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"cooling_id_eia",
"cooling_status_code",
"cooling_type",
"monthly_total_cooling_hours_in_service",
"flow_rate_method",
"temperature_method",
"annual_maximum_intake_summer_temperature_fahrenheit",
"annual_maximum_intake_winter_temperature_fahrenheit",
"monthly_average_intake_temperature_fahrenheit",
"monthly_maximum_intake_temperature_fahrenheit",
"annual_maximum_outlet_summer_temperature_fahrenheit",
"annual_maximum_outlet_winter_temperature_fahrenheit",
"monthly_average_discharge_temperature_fahrenheit",
"monthly_maximum_discharge_temperature_fahrenheit",
"annual_average_consumption_rate_gallons_per_minute",
"monthly_average_consumption_rate_gallons_per_minute",
"monthly_total_consumption_volume_gallons",
"annual_average_discharge_rate_gallons_per_minute",
"monthly_average_discharge_rate_gallons_per_minute",
"monthly_total_discharge_volume_gallons",
"monthly_average_diversion_rate_gallons_per_minute",
"monthly_total_diversion_volume_gallons",
"annual_average_withdrawal_rate_gallons_per_minute",
"monthly_average_withdrawal_rate_gallons_per_minute",
"monthly_total_withdrawal_volume_gallons",
"annual_total_chlorine_lbs",
"monthly_total_chlorine_lbs",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"cooling_id_eia",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"_core_eia923__fgd_operation_maintenance": {
"description": TABLE_DESCRIPTIONS["_core_eia923__fgd_operation_maintenance"],
"schema": {
"fields": [
"report_date",
"plant_id_eia",
"so2_control_id_eia",
"opex_fgd_feed_materials_chemical",
"opex_fgd_labor_supervision",
"opex_fgd_land_acquisition",
"opex_fgd_maintenance_material_other",
"opex_fgd_waste_disposal",
"opex_fgd_total_cost",
"fgd_control_flag",
"fgd_operational_status_code",
"fgd_hours_in_service",
"fgd_electricity_consumption_mwh",
"fgd_sorbent_consumption_1000_tons",
"so2_removal_efficiency_tested",
"so2_removal_efficiency_annual",
"so2_test_date",
"data_maturity",
],
"primary_key": [
"plant_id_eia",
"report_date",
"so2_control_id_eia",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
"core_eia923__monthly_energy_storage": {
"description": TABLE_DESCRIPTIONS["core_eia923__monthly_energy_storage"],
"schema": {
"fields": [
"plant_id_eia",
"report_date",
"prime_mover_code",
"energy_source_code",
"data_maturity",
"fuel_units",
"fuel_consumed_for_electricity_units",
"fuel_consumed_units",
"gross_generation_mwh",
"net_generation_mwh",
],
"primary_key": [
"plant_id_eia",
"report_date",
"prime_mover_code",
"energy_source_code",
],
},
"field_namespace": "eia",
"sources": ["eia923"],
"etl_group": "eia923",
},
}
"""EIA-923 resource attributes organized by PUDL identifier (``resource.name``).
Keys are in alphabetical order.
See :func:`pudl.metadata.helpers.build_foreign_keys` for the expected format of
``foreign_key_rules``.
"""