pudl.analysis.service_territory

Compile historical utility and balancing area territories.

Use the mapping of utilities to counties, and balancing areas to utilities, available within the EIA 861, in conjunction with the US Census geometries for counties, to infer the historical spatial extent of utility and balancing area territories. Output the resulting geometries for use in other applications.

Module Contents

Functions

get_all_utils(pudl_out)

Compile IDs and Names of all known EIA Utilities.

get_territory_fips(ids, assn, assn_col, st_eia861, limit_by_state=True)

Compile county FIPS codes associated with an entity's service territory.

add_geometries(df, census_gdf, dissolve=False, dissolve_by=None)

Merge census geometries into dataframe on county_id_fips, optionally dissolving.

get_territory_geometries(ids, assn, assn_col, st_eia861, census_gdf, limit_by_state=True, dissolve=False)

Compile service territory geometries based on county_id_fips.

compile_geoms(pudl_out, census_counties, entity_type, dissolve=False, limit_by_state=True, save=True)

Compile all available utility or balancing authority geometries.

_save_geoparquet(gdf, entity_type, dissolve, limit_by_state)

plot_historical_territory(gdf, id_col, id_val)

Plot all the historical geometries defined for the specified entity.

plot_all_territories(gdf, report_date, respondent_type=('balancing_authority', 'utility'), color='black', alpha=0.25)

Plot all of the planning areas of a given type for a given report date.

parse_command_line(argv)

Parse script command line arguments. See the -h option.

main()

Compile historical utility and balancing area territories.

Attributes

logger

MAP_CRS

CALC_CRS

pudl.analysis.service_territory.logger[source]
pudl.analysis.service_territory.MAP_CRS = EPSG:3857[source]
pudl.analysis.service_territory.CALC_CRS = ESRI:102003[source]
pudl.analysis.service_territory.get_all_utils(pudl_out)[source]

Compile IDs and Names of all known EIA Utilities.

Grab all EIA utility names and IDs from both the EIA 861 Service Territory table and the EIA 860 Utility entity table. This is a temporary function that’s only needed because we haven’t integrated the EIA 861 information into the entity harvesting process and PUDL database yet.

Parameters

pudl_out (pudl.output.pudltabl.PudlTabl) – The PUDL output object which should be used to obtain PUDL data.

Returns

Having 2 columns utility_id_eia and utility_name_eia.

Return type

pandas.DataFrame

pudl.analysis.service_territory.get_territory_fips(ids, assn, assn_col, st_eia861, limit_by_state=True)[source]

Compile county FIPS codes associated with an entity’s service territory.

For each entity identified by ids, look up the set of counties associated with that entity on an annual basis. Optionally limit the set of counties to those within states where the selected entities reported activity elsewhere within the EIA 861 data.

Parameters
  • ids (iterable of ints) – A collection of EIA utility or balancing authority IDs.

  • assn (pandas.DataFrame) – Association table, relating report_date,

  • state – column indicated by assn_col – if it’s not utility_id_eia.

  • other (and utility_id_eia to each) – column indicated by assn_col – if it’s not utility_id_eia.

  • the (as well as) – column indicated by assn_col – if it’s not utility_id_eia.

  • assn_col (str) – Label of the dataframe column in assn that contains the ID of the entities of interest. Should probably be either balancing_authority_id_eia or utility_id_eia.

  • st_eia861 (pandas.DataFrame) – The EIA 861 Service Territory table.

  • limit_by_state (bool) – Whether to require that the counties associated with the balancing authority are inside a state that has also been seen in association with the balancing authority and the utility whose service territory contians the county.

Returns

A table associating the entity IDs with a collection of counties annually, identifying counties both by name and county_id_fips (both state and state_id_fips are included for clarity).

Return type

pandas.DataFrame

pudl.analysis.service_territory.add_geometries(df, census_gdf, dissolve=False, dissolve_by=None)[source]

Merge census geometries into dataframe on county_id_fips, optionally dissolving.

Merge the US Census county-level geospatial information into the DataFrame df based on the the column county_id_fips (in df), which corresponds to the column GEOID10 in census_gdf. Also bring in the population and area of the counties, summing as necessary in the case of dissolved geometries.

Parameters
  • df (pandas.DataFrame) – A DataFrame containing a county_id_fips column.

  • census_gdf (geopandas.GeoDataFrame) – A GeoDataFrame based on the US Census demographic profile (DP1) data at county resolution, with the original column names as published by US Census.

  • dissolve (bool) – If True, dissolve individual county geometries into larger service territories.

  • dissolve_by (list) – The columns to group by in the dissolve. For example, dissolve_by=[“report_date”, “utility_id_eia”] might provide annual utility service territories, while [“report_date”, “balancing_authority_id_eia”] would provide annual balancing authority territories.

Returns

geopandas.GeoDataFrame

pudl.analysis.service_territory.get_territory_geometries(ids, assn, assn_col, st_eia861, census_gdf, limit_by_state=True, dissolve=False)[source]

Compile service territory geometries based on county_id_fips.

Calls get_territory_fips to generate the list of counties associated with each entity identified by ids, and then merges in the corresponding county geometries from the US Census DP1 data passed in via census_gdf.

Optionally dissolve all of the county level geometries into a single geometry for each combination of entity and year.

Note

Dissolving geometires is a costly operation, and may take half an hour or more if you are processing all entities for all years. Dissolving also means that all the per-county information will be lost, rendering the output inappropriate for use in many analyses. Dissolving is mostly useful for generating visualizations.

Parameters
  • ids (iterable of ints) – A collection of EIA balancing authority IDs.

  • assn (pandas.DataFrame) – Association table, relating report_date,

  • state – column indicated by assn_col – if it’s not utility_id_eia.

  • other (and utility_id_eia to each) – column indicated by assn_col – if it’s not utility_id_eia.

  • the (as well as) – column indicated by assn_col – if it’s not utility_id_eia.

  • assn_col (str) – Label of the dataframe column in assn that contains the ID of the entities of interest. Should probably be either balancing_authority_id_eia or utility_id_eia.

  • st_eia861 (pandas.DataFrame) – The EIA 861 Service Territory table.

  • census_gdf (geopandas.GeoDataFrame) – The US Census DP1 county-level geometries as returned by pudl.output.censusdp1tract.get_layer(“county”).

  • limit_by_state (bool) – Whether to require that the counties associated with the balancing authority are inside a state that has also been seen in association with the balancing authority and the utility whose service territory contians the county.

  • dissolve (bool) – If False, each record in the compiled territory will correspond to a single county, with a county-level geometry, and there will be many records enumerating all the counties associated with a given balancing_authority_id_eia in each year. If dissolve=True, all of the county-level geometries for each utility in each year will be merged together (“dissolved”) resulting in a single geometry and record for each balancing_authority-year.

Returns

geopandas.GeoDataFrame

pudl.analysis.service_territory.compile_geoms(pudl_out, census_counties, entity_type, dissolve=False, limit_by_state=True, save=True)[source]

Compile all available utility or balancing authority geometries.

Parameters
  • pudl_out (pudl.output.pudltabl.PudlTabl) – A PUDL output object, which will be used to extract and cache the EIA 861 tables.

  • census_counties (geopandas.GeoDataFrame) – A GeoDataFrame containing the county level US Census DP1 data and county geometries.

  • entity_type (str) – The type of service territory geometry to compile. Must be either “ba” (balancing authority) or “util” (utility).

  • dissolve (bool) – Whether to dissolve the compiled geometries to the utility/balancing authority level, or leave them as counties.

  • limit_by_state (bool) – Whether to limit included counties to those with observed EIA 861 data in association with the state and utility/balancing authority.

  • save (bool) – If True, save the compiled GeoDataFrame as a GeoParquet file before returning. Especially useful in the case of dissolved geometries, as they are computationally expensive.

Returns

geopandas.GeoDataFrame

pudl.analysis.service_territory._save_geoparquet(gdf, entity_type, dissolve, limit_by_state)[source]
pudl.analysis.service_territory.plot_historical_territory(gdf, id_col, id_val)[source]

Plot all the historical geometries defined for the specified entity.

This is useful for exploring how a particular entity’s service territory has evolved over time, or for identifying individual missing or inaccurate territories.

Parameters
  • gdf (geopandas.GeoDataFrame) – A geodataframe containing geometries pertaining electricity planning areas. Can be broken down by county FIPS code, or have a single record containing a geometry for each combination of report_date and the column being used to select planning areas (see below).

  • id_col (str) – The label of a column in gdf that identifies the planning area to be visualized, like utility_id_eia, balancing_authority_id_eia, or balancing_authority_code_eia.

  • id_val (str or int) – The value identifying the

Returns

None

pudl.analysis.service_territory.plot_all_territories(gdf, report_date, respondent_type=('balancing_authority', 'utility'), color='black', alpha=0.25)[source]

Plot all of the planning areas of a given type for a given report date.

Todo

This function needs to be made more general purpose, and less entangled with the FERC 714 data.

Parameters
  • gdf (geopandas.GeoDataFrame) – GeoDataFrame containing planning area geometries, organized by respondent_id_ferc714 and report_date.

  • report_date (datetime) – A Datetime indicating what year’s planning areas should be displayed.

  • respondent_type (str or iterable) – Type of respondent whose planning areas should be displayed. Either “utility” or “balancing_authority” or an iterable collection containing both.

  • color (str) – Color to use for the planning areas.

  • alpha (float) – Transparency to use for the planning areas.

Returns

matplotlib.axes.Axes

pudl.analysis.service_territory.parse_command_line(argv)[source]

Parse script command line arguments. See the -h option.

Parameters

argv (list) – command line arguments including caller file name.

Returns

A dictionary mapping command line arguments to their values.

Return type

dict

pudl.analysis.service_territory.main()[source]

Compile historical utility and balancing area territories.