pypsa-explorer 0.1.0__tar.gz

pypsa_explorer-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-10-04
+
+### Added
+- Initial release of PyPSA Explorer
+- Interactive dashboard with multiple visualization tabs:
+  - Energy Balance Timeseries
+  - Energy Balance Totals
+  - Capacity Totals
+  - CAPEX Totals
+  - OPEX Totals
+  - Network Configuration (map + metadata)
+- Multi-network support with dropdown selector
+- Global filters for carriers and countries
+- Command-line interface for easy deployment
+- Python API for programmatic usage
+- Comprehensive documentation and examples
+- Production-ready package structure with:
+  - Modular codebase organization
+  - Type hints throughout
+  - Testing infrastructure with pytest
+  - CI/CD pipeline with GitHub Actions
+  - Pre-commit hooks for code quality
+  - Professional README and documentation
+
+### Changed
+- Refactored from single-file application to modular package structure
+- Improved code organization with separate modules for layouts, callbacks, and utilities
+
+### Fixed
+- None
+
+### Security
+- None
+
+[Unreleased]: https://github.com/openenergytransition/pypsa-explorer/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/openenergytransition/pypsa-explorer/releases/tag/v0.1.0

pypsa_explorer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,267 @@
+# Contributing to PyPSA Explorer
+
+Thank you for your interest in contributing to PyPSA Explorer! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+We are committed to providing a welcoming and inclusive environment. Please be respectful and constructive in your interactions.
+
+## Getting Started
+
+### 1. Fork and Clone
+
+```bash
+# Fork the repository on GitHub, then clone your fork
+git clone https://github.com/YOUR_USERNAME/pypsa-explorer.git
+cd pypsa-explorer
+
+# Add upstream remote
+git remote add upstream https://github.com/openenergytransition/pypsa-explorer.git
+```
+
+### 2. Set Up Development Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### 3. Create a Branch
+
+```bash
+# Update your main branch
+git checkout main
+git pull upstream main
+
+# Create a feature branch
+git checkout -b feature/your-feature-name
+```
+
+## Development Workflow
+
+### Code Style
+
+We use the following tools for code quality:
+
+- **Black**: Code formatting (line length: 125)
+- **Ruff**: Linting and code quality checks
+- **MyPy**: Static type checking
+
+Format your code before committing:
+
+```bash
+# Format code
+black src/ tests/
+ruff format src/ tests/
+
+# Check linting
+ruff check src/ tests/ --fix
+
+# Type checking
+mypy src/
+```
+
+### Testing
+
+Write tests for new features and bug fixes:
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=pypsa_explorer --cov-report=html
+
+# Run specific test
+pytest tests/test_app.py -v
+
+# Run tests in watch mode (requires pytest-watch)
+ptw
+```
+
+### Documentation
+
+Update documentation for any user-facing changes:
+
+- Update docstrings in code (Google style)
+- Update README.md if needed
+- Add examples for new features
+- Update CHANGELOG.md
+
+### Type Hints
+
+All code should include type hints:
+
+```python
+def process_network(
+    network: pypsa.Network,
+    carriers: list[str],
+    query: str | None = None,
+) -> dict[str, Any]:
+    """
+    Process network data with optional filtering.
+
+    Parameters
+    ----------
+    network : pypsa.Network
+        The PyPSA network to process
+    carriers : list[str]
+        List of carrier names to include
+    query : str | None
+        Optional pandas query string for filtering
+
+    Returns
+    -------
+    dict[str, Any]
+        Processed network data
+    """
+    # Implementation
+    pass
+```
+
+## Pull Request Process
+
+### 1. Commit Your Changes
+
+```bash
+# Stage changes
+git add .
+
+# Commit with descriptive message
+git commit -m "Add feature: description of your changes"
+```
+
+Follow these commit message guidelines:
+- Use present tense ("Add feature" not "Added feature")
+- Use imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Reference issues and pull requests where applicable
+- First line should be concise (50 chars or less)
+
+### 2. Push to Your Fork
+
+```bash
+git push origin feature/your-feature-name
+```
+
+### 3. Create Pull Request
+
+1. Go to the [PyPSA Explorer repository](https://github.com/openenergytransition/pypsa-explorer)
+2. Click "New Pull Request"
+3. Select your fork and branch
+4. Fill in the PR template:
+   - Describe the changes
+   - Reference related issues
+   - Include screenshots for UI changes
+   - List any breaking changes
+   - Confirm tests pass
+
+### 4. Code Review
+
+- Address review comments
+- Push updates to the same branch
+- Request re-review when ready
+
+### 5. Merge
+
+Once approved, a maintainer will merge your PR.
+
+## What to Contribute
+
+### Bug Reports
+
+Found a bug? Please open an issue with:
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, Python version, package versions)
+- Minimal code example if possible
+
+### Feature Requests
+
+Have an idea? Open an issue with:
+- Clear description of the feature
+- Use cases and benefits
+- Possible implementation approach
+- Willingness to contribute
+
+### Good First Issues
+
+Look for issues labeled `good-first-issue` for beginner-friendly tasks.
+
+### Priority Areas
+
+We especially welcome contributions in:
+- Additional visualization types
+- Export functionality (PNG, PDF, CSV)
+- Performance optimizations
+- Documentation improvements
+- Test coverage expansion
+- Accessibility improvements
+
+## Project Structure
+
+```
+pypsa-explorer/
+├── src/pypsa_explorer/    # Main package code
+│   ├── callbacks/         # Dash callbacks
+│   ├── layouts/           # UI components
+│   └── utils/             # Utility functions
+├── tests/                 # Test suite
+├── docs/                  # Documentation
+└── examples/              # Example scripts and notebooks
+```
+
+## Development Tips
+
+### Running in Debug Mode
+
+```python
+from pypsa_explorer import run_dashboard
+
+run_dashboard(debug=True)  # Enable hot-reloading
+```
+
+### Testing Callbacks
+
+```python
+from dash.testing.application_runners import import_app
+
+def test_callback(dash_duo):
+    app = import_app("pypsa_explorer.app")
+    dash_duo.start_server(app)
+    # Test interactions
+```
+
+### Adding New Visualizations
+
+1. Add layout in `src/pypsa_explorer/layouts/tabs.py`
+2. Add callback in `src/pypsa_explorer/callbacks/visualizations.py`
+3. Register callback in `src/pypsa_explorer/callbacks/__init__.py`
+4. Add tests in `tests/test_visualizations.py`
+
+## Release Process
+
+(For maintainers)
+
+1. Update version in `pyproject.toml` and `src/pypsa_explorer/__init__.py`
+2. Update CHANGELOG.md
+3. Create release branch: `git checkout -b release/vX.Y.Z`
+4. Tag release: `git tag vX.Y.Z`
+5. Push tag: `git push origin vX.Y.Z`
+6. Build and publish to PyPI: `python -m build && twine upload dist/*`
+7. Create GitHub release with changelog
+
+## Questions?
+
+- Open an issue for questions
+- Join our [discussions](https://github.com/openenergytransition/pypsa-explorer/discussions)
+- Contact the maintainers
+
+Thank you for contributing to PyPSA Explorer! 🎉

pypsa_explorer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OET Network Viewer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypsa_explorer-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+
+recursive-include src/pypsa_explorer *.py
+recursive-include src/pypsa_explorer py.typed
+recursive-include tests *.py
+
+exclude .gitignore
+exclude .pre-commit-config.yaml
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

pypsa_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: pypsa-explorer
+Version: 0.1.0
+Summary: Interactive dashboard for visualizing and analyzing PyPSA energy system networks
+Author-email: Open Energy Transition <info@openenergytransition.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/openenergytransition/pypsa-explorer
+Project-URL: Documentation, https://pypsa-explorer.readthedocs.io
+Project-URL: Repository, https://github.com/openenergytransition/pypsa-explorer
+Project-URL: Bug Tracker, https://github.com/openenergytransition/pypsa-explorer/issues
+Keywords: pypsa,energy,visualization,dashboard,power-system
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: plotly>=5.0
+Requires-Dist: dash>=2.14
+Requires-Dist: folium>=0.14
+Requires-Dist: mapclassify>=2.5
+Requires-Dist: dash-bootstrap-components>=1.5
+Requires-Dist: pypsa>=1.0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: pytest-mock>=3.11; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: pre-commit>=3.4; extra == "dev"
+Requires-Dist: ipython>=8.0; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Requires-Dist: nbconvert>=7.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-cov>=4.1; extra == "test"
+Requires-Dist: pytest-mock>=3.11; extra == "test"
+Dynamic: license-file
+
+# PyPSA Explorer
+
+[![PyPI version](https://badge.fury.io/py/pypsa-explorer.svg)](https://badge.fury.io/py/pypsa-explorer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+Interactive dashboard for visualizing and analyzing PyPSA energy system networks. Built with Dash and Plotly, PyPSA Explorer provides a comprehensive web interface for exploring energy system models with powerful filtering and visualization capabilities.
+
+## Features
+
+### 📊 Interactive Visualizations
+- **Energy Balance Analysis**: Timeseries and aggregated views of energy flows
+- **Capacity Planning**: Visualize optimal capacity distribution by carrier and region
+- **Economic Analysis**: CAPEX and OPEX breakdowns across the system
+- **Network Maps**: Interactive geographical visualization of network topology
+- **Multi-Network Support**: Load and compare multiple networks seamlessly
+
+### 🎯 Advanced Filtering
+- Filter by energy carrier (sector)
+- Filter by country/region
+- Dynamic updates across all visualizations
+- Tab-specific filter behavior
+
+### 🚀 Production Ready
+- Well-structured, modular codebase
+- Comprehensive type hints
+- Extensive test coverage
+- CI/CD pipeline integration
+- Professional documentation
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install pypsa-explorer
+```
+
+### From Source
+
+```bash
+git clone https://github.com/openenergytransition/pypsa-explorer.git
+cd pypsa-explorer
+pip install -e .
+```
+
+### Development Installation
+
+```bash
+git clone https://github.com/openenergytransition/pypsa-explorer.git
+cd pypsa-explorer
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Quick Start
+
+### Command Line Interface
+
+Launch the landing page and drag-and-drop networks or load the bundled example:
+```bash
+pypsa-explorer
+```
+
+Run with your own network:
+```bash
+pypsa-explorer /path/to/network.nc
+```
+
+Run with multiple networks:
+```bash
+pypsa-explorer /path/to/network1.nc:Label1 /path/to/network2.nc:Label2
+```
+
+Custom host and port:
+```bash
+pypsa-explorer --host 0.0.0.0 --port 8080
+```
+
+Production mode (no debug):
+```bash
+pypsa-explorer --no-debug
+```
+
+### Python API
+
+```python
+from pypsa_explorer import run_dashboard
+
+# Run with default network
+run_dashboard()
+
+# Run with custom network
+run_dashboard("/path/to/network.nc")
+
+# Run with multiple networks
+networks = {
+    "Scenario A": "/path/to/network1.nc",
+    "Scenario B": "/path/to/network2.nc",
+}
+run_dashboard(networks, debug=True, host="0.0.0.0", port=8050)
+
+# Run with Network objects
+import pypsa
+n1 = pypsa.Network("network1.nc")
+n2 = pypsa.Network("network2.nc")
+
+run_dashboard({"Network 1": n1, "Network 2": n2})
+```
+
+### Programmatic App Creation
+
+```python
+from pypsa_explorer import create_app
+
+# Create app instance
+app = create_app(networks_input="/path/to/network.nc", title="My Dashboard")
+
+# Run with custom server
+app.run(debug=True, host="0.0.0.0", port=8050)
+```
+
+## Project Structure
+
+```
+pypsa-explorer/
+├── src/
+│   └── pypsa_explorer/
+│       ├── __init__.py           # Package initialization
+│       ├── app.py                # Main application factory
+│       ├── cli.py                # Command-line interface
+│       ├── config.py             # Configuration and theming
+│       ├── callbacks/            # Dash callbacks
+│       │   ├── __init__.py
+│       │   ├── filters.py        # Filter callbacks
+│       │   ├── navigation.py     # Navigation callbacks
+│       │   ├── network.py        # Network callbacks
+│       │   └── visualizations.py # Visualization callbacks
+│       ├── layouts/              # UI layouts
+│       │   ├── __init__.py
+│       │   ├── components.py     # Reusable components
+│       │   ├── dashboard.py      # Main dashboard layout
+│       │   ├── tabs.py           # Tab definitions
+│       │   └── welcome.py        # Welcome page
+│       └── utils/                # Utility functions
+│           ├── __init__.py
+│           ├── helpers.py        # Helper functions
+│           └── network_loader.py # Network loading utilities
+├── tests/                        # Test suite
+├── docs/                         # Documentation
+├── examples/                     # Example notebooks and scripts
+├── pyproject.toml               # Project configuration
+├── README.md                    # This file
+├── LICENSE                      # MIT License
+└── CHANGELOG.md                 # Version history
+```
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/openenergytransition/pypsa-explorer.git
+cd pypsa-explorer
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=pypsa_explorer --cov-report=html
+
+# Run specific test file
+pytest tests/test_app.py
+```
+
+### Code Quality
+
+```bash
+# Format code
+black src/ tests/
+ruff format src/ tests/
+
+# Lint code
+ruff check src/ tests/ --fix
+
+# Type checking
+mypy src/
+```
+
+### Building Documentation
+
+```bash
+cd docs
+make html
+```
+
+## Configuration
+
+### Custom Styling
+
+The dashboard theme can be customized by modifying `src/pypsa_explorer/config.py`:
+
+```python
+COLORS = {
+    "primary": "#2c3e50",
+    "secondary": "#3498db",
+    "accent": "#2ecc71",
+    # ... more colors
+}
+```
+
+### Default Settings
+
+- **Port**: 8050
+- **Host**: 127.0.0.1 (localhost)
+- **Debug Mode**: True (disable with `--no-debug`)
+- **Default Carriers**: AC, Hydrogen Storage, Low Voltage
+
+## Requirements
+
+- Python >= 3.12
+- PyPSA (from GitHub master)
+- Dash >= 2.14
+- Plotly >= 5.0
+- Folium >= 0.14
+- dash-bootstrap-components >= 1.5
+
+See `pyproject.toml` for complete dependency list.
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and linting (`pytest && ruff check`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+Please ensure:
+- All tests pass
+- Code is properly formatted (black/ruff)
+- Type hints are included
+- Documentation is updated
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use PyPSA Explorer in your research, please cite:
+
+```bibtex
+@software{pypsa_explorer,
+  title = {PyPSA Explorer: Interactive Dashboard for Energy System Analysis},
+  author = {Open Energy Transition},
+  year = {2024},
+  url = {https://github.com/openenergytransition/pypsa-explorer}
+}
+```
+
+## Acknowledgments
+
+- Built on [PyPSA](https://pypsa.org) - Python for Power System Analysis
+- Powered by [Dash](https://dash.plotly.com/) and [Plotly](https://plotly.com/)
+- Developed by [Open Energy Transition](https://openenergytransition.org)
+
+## Support
+
+- **Documentation**: [https://pypsa-explorer.readthedocs.io](https://pypsa-explorer.readthedocs.io)
+- **Issues**: [GitHub Issues](https://github.com/openenergytransition/pypsa-explorer/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/openenergytransition/pypsa-explorer/discussions)
+
+## Roadmap
+
+- [ ] Export functionality (PNG, PDF, data export)
+- [ ] Advanced comparison mode for multiple networks
+- [ ] Custom calculation and plotting plugins
+- [ ] Real-time data streaming support
+- [ ] Collaborative features and sharing
+- [ ] Integration with cloud storage (S3, GCS)
+
+## Related Projects
+
+- [PyPSA](https://github.com/PyPSA/PyPSA) - The core power system analysis framework
+- [PyPSA-Eur](https://github.com/PyPSA/pypsa-eur) - Open energy system model for Europe
+- [PyPSA-Earth](https://github.com/pypsa-meets-earth/pypsa-earth) - Global energy system model