By Krv Labs.
Retire Coal is a Python toolkit that enables researchers and policymakers to analyze US coal plant retirement strategies using advanced network analysis and contextual retirement vulnerabilities. Based on methodologies published in Nature Energy, this package provides curated datasets, graph-based analytical methods, and publication-ready visualizations to explore coal retirement pathways and their underlying drivers.
The toolkit combines operational, environmental, policy, and socio-demographic data to help understand which coal plants are most vulnerable to retirement and why, enabling evidence-based decision-making for energy transition planning.
If you use this package in your research, please cite:
@article{Gathrid2025,
author = {Gathrid, Sidney and Wayland, Jeremy and Wayland, Stuart and Deshmukh, Ranjit and Wu, Grace C.},
title = {Strategies to accelerate US coal power phase-out using contextual retirement vulnerabilities},
journal = {Nature Energy},
year = {2025},
volume = {10},
number = {10},
pages = {1274--1288},
month = {October},
doi = {10.1038/s41560-025-01871-0},
url = {https://doi.org/10.1038/s41560-025-01871-0},
issn = {2058-7546}
}We extend our gratitude to our coauthors and mentors, Dr. Grace Wu and Dr. Ranjit Deshmukh, from UCSB Environmental Studies, for their invaluable guidance and collaboration.
- Overview
- Key Features
- Prerequisites
- Installation
- Quick Start
- Documentation
- API Reference
- Development
- Citation
- License
🔬 Research-Grade Analysis
- Network analysis to quantify contextual retirement vulnerability and plant similarity
- Graph-based methods for identifying strategic retirement targets
- Reproducible manuscript outputs with group-level summaries and plant-level explanations
📊 Comprehensive Datasets
- Ready-to-use plant and generator-level data with operational, policy, environmental, and socio-demographic context
- Scenario projections for different retirement pathways
- Pre-processed and cleaned datasets for immediate analysis
📈 Publication-Quality Visualizations
- Network graphs for plant similarity and vulnerability analysis
- Geographic maps showing spatial patterns
- Sankey diagrams, stacked bar charts, heatmaps, and dot plots
- Customizable styling for publications and presentations
🛠 Developer-Friendly API
- Pure Python implementation requiring no external services
- Works seamlessly in Jupyter notebooks and Python scripts
- Intuitive object-oriented interface
- Comprehensive data loading utilities
- Python 3.10 or higher
- Required packages are automatically installed with the toolkit
pip install retire-coalFor development or to access tutorial notebooks:
git clone [email protected]:Krv-Analytics/retire.git
cd retire
uv sync --all-extras
source .venv/bin/activatefrom retire import Retire, Explore
# Initialize the analysis toolkit
retire_obj = Retire()
explore = Explore(retire_obj.graph, retire_obj.raw_df)
# Visualize the coal plant network colored by retirement status
fig, ax = explore.drawGraph(col='ret_STATUS')
# Create a geographic map of coal plants
fig, ax = explore.drawMap()
# Generate manuscript-ready results
group_analysis = retire_obj.get_group_report()
explanations = retire_obj.get_target_explanations()from retire.data import (
load_dataset, # Main plant-level dataset
load_clean_dataset, # Cleaned/scaled features
load_projection, # Scenario projections
load_graph, # Plant-similarity graph
load_generator_level_dataset # Generator-level details
)
# Load the main dataset
plants_df = load_dataset()
# Load network graph for analysis
graph = load_graph()
# Load scenario projections
projections_df = load_projection()from retire import Retire, Explore
retire_obj = Retire()
explore = Explore(retire_obj.graph, retire_obj.raw_df)
# Create a heatmap of plant characteristics
fig, ax = explore.create_heatmap(features=['capacity', 'age', 'emissions'])
# Generate dot plot for specific metrics
fig, ax = explore.create_dotplot(metric='retirement_vulnerability')
# Create Sankey diagram for retirement pathways
fig, ax = explore.create_sankey(source_col='current_status', target_col='projected_status')Comprehensive documentation is available in the docs/ directory:
- Usage Guide - Complete guide to using the toolkit
- Data Sources - Detailed description of datasets and their sources
- Visualization Methods - Guide to creating publication-quality visualizations
- Configuration - Customization and configuration options
Interactive Jupyter notebooks in the tutorials/ directory:
- Getting Started - Introduction to the basic workflow
- Using THEMA - Working with energy transition models
- Exploration Tools - Advanced visualization techniques
- Target Matching - Identifying strategic retirement targets
- Testing Guide - Running and writing tests
- Data Processing - Understanding data pipelines
- Explorer Module - Extending visualization capabilities
Main analysis class providing data access and manuscript results.
from retire import Retire
retire_obj = Retire()
group_report = retire_obj.get_group_report()
explanations = retire_obj.get_target_explanations()Key Methods:
get_group_report()- Generate group-level analysis summariesget_target_explanations()- Create plant-level retirement explanations- Access to
graph,raw_df, and other core datasets
Visualization toolkit for networks and geographic data.
from retire import Explore
explore = Explore(graph, dataframe)
fig, ax = explore.drawGraph(col='retirement_status')
fig, ax = explore.drawMap(color_by='vulnerability_score')Key Methods:
drawGraph()- Network visualization with customizable stylingdrawMap()- Geographic mapping of coal plantscreate_heatmap()- Correlation and feature heatmapscreate_dotplot()- Dot plot visualizationscreate_sankey()- Flow diagrams for retirement pathways
from retire.data import (
load_dataset, # Plant-level operational and contextual data
load_clean_dataset, # Preprocessed features for analysis
load_projection, # Scenario-based retirement projections
load_graph, # Plant similarity network graph
load_generator_level_dataset # Detailed generator-level information
)# Clone the repository
git clone [email protected]:Krv-Analytics/retire.git
cd retire
# Install development dependencies
pip install -e ".[dev]"
# Set up pre-commit hooks (optional)
pre-commit install# Run all tests
pytest
# Run tests with coverage
pytest --cov=retire
# Run specific test files
pytest tests/test_retire.pyWe welcome contributions! This is currently a v0 WIP release. When contributing:
- Fork the Repository - Create your own fork of the project
- Create a Feature Branch -
git checkout -b feature/amazing-feature - Write Tests - Ensure new functionality includes comprehensive tests
- Update Documentation - Update relevant documentation for API changes
- Follow Code Style - Maintain consistency with existing patterns and conventions
- Submit a Pull Request - Provide a clear description of your changes
- Test Coverage: Write tests for new functionality
- Documentation: Update docs for API changes
- Type Hints: Use type hints for new functions and methods
- Code Style: Follow existing patterns and PEP 8 guidelines
If you use this package in your research, please cite our Nature Energy publication:
@article{Gathrid2025,
author = {Gathrid, Sidney and Wayland, Jeremy and Wayland, Stuart and Deshmukh, Ranjit and Wu, Grace C.},
title = {Strategies to accelerate US coal power phase-out using contextual retirement vulnerabilities},
journal = {Nature Energy},
year = {2025},
volume = {10},
number = {10},
pages = {1274--1288},
month = {October},
doi = {10.1038/s41560-025-01871-0},
url = {https://doi.org/10.1038/s41560-025-01871-0},
issn = {2058-7546}
}This project is licensed under the BSD 3-Clause License - see the LICENSE.md file for details.
- Documentation: Docs
- Issues: GitHub Issues
- Website: krv.ai
- Email: [email protected]
- LinkedIn: Krv Analytics
This work was partially supported by a Manalis Scholarship awarded to S.G. We thank D. Prull at the Sierra Club for his generosity in providing insights on analytical gaps to fill to achieve practical relevancy and data on announced retirements. In addition, we thank D. Khannan and J. Daniel at Rocky Mountain Institute (RMI) for helpful suggestions and J. Graham and C. Schneider at the Clean Air Task Force for access to coal cost and health impact data.