pudl.analysis.mcoe module

A module with functions to aid generating MCOE.

pudl.analysis.mcoe.capacity_factor(pudl_out, min_cap_fact=0, max_cap_fact=1.5)[source]

Calculate the capacity factor for each generator.

Capacity Factor is calculated by using the net generation from eia923 and the nameplate capacity from eia860. The net gen and capacity are pulled into one dataframe, then the dates from that dataframe are pulled out to determine the hours in each period based on the frequency. The number of hours is used in calculating the capacity factor. Then records with capacity factors outside the range specified by min_cap_fact and max_cap_fact are dropped.


Calculate fuel costs per MWh on a per generator basis for MCOE.

Fuel costs are reported on a per-plant basis, but we want to estimate them at the generator level. This is complicated by the fact that some plants have several different types of generators, using different fuels. We have fuel costs broken out by type of fuel (coal, oil, gas), and we know which generators use which fuel based on their energy_source_code and reported prime_mover. Coal plants use a little bit of natural gas or diesel to get started, but based on our analysis of the “pure” coal plants, this amounts to only a fraction of a percent of their overal fuel consumption on a heat content basis, so we’re ignoring it for now.

For plants whose generators all rely on the same fuel source, we simply attribute the fuel costs proportional to the fuel heat content consumption associated with each generator.

For plants with more than one type of generator energy source, we need to split out the fuel costs according to fuel type – so the gas fuel costs are associated with generators that have energy_source_code gas, and the coal fuel costs are associated with the generators that have energy_source_code coal.


Convert per-unit heat rate to by-generator, adding fuel type & count.

Heat rates really only make sense at the unit level, since input fuel and output electricity are comingled at the unit level, but it is useful in many contexts to have that per-unit heat rate associated with each of the underlying generators, as much more information is available about the generators.

To combine the (potentially) more granular temporal information from the per-unit heat rates with annual generator level attributes, we have to do a many-to-many merge. This can’t be done easily with merge_asof(), so we treat the year and month fields as categorial variables, and do a normal inner merge that broadcasts monthly dates in one direction, and generator IDs in the other.


with columns report_date, plant_id_eia, unit_id_pudl, generator_id, heat_rate_mmbtu_mwh, fuel_type_code_pudl, fuel_type_count. The output will have a time frequency corresponding to that of the input pudl_out. Output data types are set to their canonical values before returning.

Return type



ValueError if pudl_out.freq is None.


Calculate heat rates (mmBTU/MWh) within separable generation units.

Assumes a “good” Boiler Generator Association (bga) i.e. one that only contains boilers and generators which have been completely associated at some point in the past.

The BGA dataframe needs to have the following columns:

  • report_date (annual)

  • plant_id_eia

  • unit_id_pudl

  • generator_id

  • boiler_id

The unit_id is associated with generation records based on report_date, plant_id_eia, and generator_id. Analogously, the unit_id is associated with boiler fuel consumption records based on report_date, plant_id_eia, and boiler_id.

Then the total net generation and fuel consumption per unit per time period are calculated, allowing the calculation of a per unit heat rate. That per unit heat rate is returned in a dataframe containing:

  • report_date

  • plant_id_eia

  • unit_id_pudl

  • net_generation_mwh

  • fuel_consumed_mmbtu

  • heat_rate_mmbtu_mwh

pudl.analysis.mcoe.mcoe(pudl_out, min_heat_rate=5.5, min_fuel_cost_per_mwh=0.0, min_cap_fact=0.0, max_cap_fact=1.5, all_gens=True)[source]

Compile marginal cost of electricity (MCOE) at the generator level.

Use data from EIA 923, EIA 860, and (someday) FERC Form 1 to estimate the MCOE of individual generating units. The calculation is performed over the range of times and at the time resolution of the input pudl_out object.

  • pudl_out (pudl.output.pudltable.PudlTabl) – a PUDL output object specifying the time resolution and date range for which the calculations should be performed.

  • min_heat_rate (float) – lowest plausible heat rate, in mmBTU/MWh. Any MCOE records with lower heat rates are presumed to be invalid, and are discarded before returning.

  • min_cap_fact (float) – minimum & maximum generator capacity factor. Generator records with a lower capacity factor will be filtered out before returning. This allows the user to exclude generators that aren’t being used enough to have valid.

  • max_cap_fact (float) – minimum & maximum generator capacity factor. Generator records with a lower capacity factor will be filtered out before returning. This allows the user to exclude generators that aren’t being used enough to have valid.

  • min_fuel_cost_per_mwh (float) – minimum fuel cost on a per MWh basis that is required for a generator record to be considered valid. For some reason there are now a large number of $0 fuel cost records, which previously would have been NaN.

  • all_gens (bool) – if True, include attributes of all generators in the generators_eia860 table, rather than just the generators which have records in the derived MCOE values. True by default.


a dataframe organized by date and generator, with lots of juicy information about the generators – including fuel cost on a per MWh and MMBTU basis, heat rates, and net generation.

Return type