{
  "anchors": [
    {
      "about": "2-letter state/jurisdiction code (PD-003).",
      "format": "usps_state",
      "kind": "geography",
      "name": "state",
      "scope": "universal"
    },
    {
      "about": "EIA plant code; joins within the EIA family.",
      "format": "positive_int",
      "kind": "entity",
      "name": "eia_plant_id",
      "scope": "opportunistic"
    },
    {
      "about": "EIA-reported BA code; source-reported, not a validated footprint (PD-002/009).",
      "format": "ba_code",
      "kind": "entity",
      "name": "balancing_authority_code",
      "scope": "opportunistic"
    }
  ],
  "capability": "power.fuel_cost",
  "codebooks": {},
  "data_point": {
    "does_not_answer": [
      "heat rate, efficiency, generation cost, marginal cost, or dollars per MWh",
      "imputed or estimated fuel cost for withheld receipt rows",
      "normalized supplier identity or corporate matching",
      "wholesale electricity prices",
      "fuel consumption or net generation (use power.generation)"
    ],
    "grain": "fuel_receipt_row",
    "id": "power.fuel_cost",
    "product_spec": "blocks/power_fuel_cost/card.md",
    "represented_fact": "EIA-923 Page 5 reports individual fossil-fuel receipts by plant and month, including raw physical quantity and delivered fuel cost in cents per MMBtu. Confidential or otherwise unpublished costs remain explicit missing values; they are never zero-filled, imputed, or converted into heat rates or $/MWh.",
    "source_basis": [
      "energy.eia.eia923_receipts_cost"
    ],
    "source_decisions": [
      "docs/sources/energy/eia/eia923_fuel_cost/source-decision.md"
    ]
  },
  "input": {
    "controls": [
      "include_records",
      "include_evidence",
      "limit",
      "order_by",
      "top_n",
      "order"
    ],
    "date_range_params": [
      "data_month_from",
      "data_month_to"
    ],
    "date_ranges": [
      "data_month"
    ],
    "filters": [
      "as_of",
      "data_month",
      "eia_plant_id",
      "state",
      "balancing_authority_code",
      "energy_source_code",
      "fuel_group_raw",
      "purchase_type",
      "supplier",
      "fuel_cost_status",
      "is_withheld"
    ],
    "group_by": [
      "data_month",
      "eia_plant_id",
      "state",
      "balancing_authority_code",
      "energy_source_code",
      "fuel_group_raw",
      "purchase_type",
      "supplier",
      "fuel_cost_status",
      "is_withheld"
    ],
    "ranking": {
      "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
      "order": {
        "default": "desc",
        "valid_values": [
          "desc",
          "asc"
        ]
      },
      "order_by": {
        "accepts": "one of output.metrics",
        "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
        "requires": [
          "group_by"
        ],
        "valid_values": [
          "quantity",
          "delivered_fuel_cost_cents_per_mmbtu",
          "source_record_count",
          "reported_cost_count",
          "withheld_cost_count"
        ]
      },
      "top_n": {
        "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
        "requires": [
          "group_by",
          "order_by"
        ],
        "type": "positive integer"
      }
    }
  },
  "output": {
    "aggregate_citation_fields": [
      "source_id",
      "publisher",
      "source_url",
      "source_file",
      "raw_file_sha256",
      "as_of",
      "source_rows_count",
      "source_rows_sample",
      "verify",
      "lineage_filter"
    ],
    "citation_fields": [
      "source_id",
      "source_url",
      "source_file",
      "sheet",
      "source_row",
      "source_col",
      "raw_file_sha256",
      "as_of"
    ],
    "detail_fields": [
      "source_id",
      "sheet_name",
      "report_period",
      "data_month",
      "source_record_key",
      "source_row_number",
      "eia_plant_id",
      "plant_name",
      "state",
      "balancing_authority_code",
      "operator_id",
      "operator_name",
      "purchase_type",
      "energy_source_code",
      "fuel_group_raw",
      "supplier",
      "quantity",
      "quantity_unit",
      "delivered_fuel_cost_cents_per_mmbtu",
      "fuel_cost_raw",
      "fuel_cost_unit",
      "fuel_cost_status",
      "is_withheld",
      "regulated_status",
      "as_of",
      "raw_file_sha256",
      "citation"
    ],
    "metric_groups": {
      "fuel_receipt": [
        "quantity",
        "delivered_fuel_cost_cents_per_mmbtu"
      ],
      "records": [
        "source_record_count",
        "reported_cost_count",
        "withheld_cost_count"
      ]
    },
    "metric_metadata": {
      "delivered_fuel_cost_cents_per_mmbtu": {
        "additive_across_groups": false,
        "aggregation": "single receipt value only",
        "authoritative_total_path": "summary.totals.delivered_fuel_cost_cents_per_mmbtu",
        "category": "fuel_receipt",
        "definition": "EIA-923 delivered fuel cost in cents per MMBtu for one receipt row.",
        "display_name": "Delivered fuel cost",
        "display_precision": "Raw numeric value preserved to EIA's stated 0.1 cent/MMBtu precision.",
        "grain": "fuel receipt row",
        "null_handling": "Withheld or unpublished source cells remain null; never zero-filled or imputed.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.delivered_fuel_cost_cents_per_mmbtu",
        "source_fields": [
          "FUEL_COST"
        ],
        "unit": "cents/MMBtu"
      },
      "quantity": {
        "additive_across_groups": false,
        "aggregation": "single receipt value only",
        "authoritative_total_path": "summary.totals.quantity",
        "category": "fuel_receipt",
        "definition": "EIA-923 receipt quantity in the physical unit implied by the fuel code.",
        "display_name": "Receipt quantity",
        "display_precision": "Raw numeric value preserved.",
        "grain": "fuel receipt row",
        "null_handling": "Null remains null; rows of different physical units are never summed.",
        "rollup_behavior": "non_additive_measure",
        "row_metric_path": "rows[].metrics.quantity",
        "source_fields": [
          "QUANTITY"
        ],
        "unit": "source physical unit"
      },
      "reported_cost_count": {
        "additive_across_groups": true,
        "aggregation": "conditional count",
        "authoritative_total_path": "summary.totals.reported_cost_count",
        "category": "records",
        "definition": "Count of receipt rows with a numeric FUEL_COST cell.",
        "display_name": "Reported cost count",
        "display_precision": "Integer.",
        "grain": "source row",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.reported_cost_count",
        "source_fields": [
          "FUEL_COST"
        ],
        "unit": "count"
      },
      "source_record_count": {
        "additive_across_groups": true,
        "aggregation": "count source records",
        "authoritative_total_path": "summary.totals.source_record_count",
        "category": "records",
        "definition": "Count of EIA-923 Page 5 receipt rows in scope.",
        "display_name": "Source record count",
        "display_precision": "Integer.",
        "grain": "source row",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.source_record_count",
        "source_fields": [
          "source_record_key"
        ],
        "unit": "count"
      },
      "withheld_cost_count": {
        "additive_across_groups": true,
        "aggregation": "conditional count",
        "authoritative_total_path": "summary.totals.withheld_cost_count",
        "category": "records",
        "definition": "Count of unregulated receipt rows whose FUEL_COST cell is EIA's '.' marker.",
        "display_name": "Withheld cost count",
        "display_precision": "Integer.",
        "grain": "source row",
        "null_handling": "Always an integer count.",
        "rollup_behavior": "additive_partition_metric",
        "row_metric_path": "rows[].metrics.withheld_cost_count",
        "source_fields": [
          "FUEL_COST",
          "Regulated"
        ],
        "unit": "count"
      }
    },
    "metrics": [
      "quantity",
      "delivered_fuel_cost_cents_per_mmbtu",
      "source_record_count",
      "reported_cost_count",
      "withheld_cost_count"
    ],
    "summary_fields": [
      "group_count",
      "totals"
    ]
  },
  "primitive": "query_power_fuel_cost_v1",
  "status": "available"
}