scienceplots-toolkit 0.1.1__tar.gz

scienceplots_toolkit-0.1.1/.agents/skills/scienceplots-viz/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: scienceplots-viz
+description: How to create scientific visualizations with SciencePlots and LaTeX. Use this skill whenever the user wants to create publication-quality plots, scientific figures, data visualizations with matplotlib, or needs to follow the project's strict plotting standards. This includes 24h load profiles, energy visualizations, quantile shading, statistical annotations, or any matplotlib plotting in this repository. Also use this skill for any Python coding tasks in this project - it contains all the coding standards, path handling requirements, and implementation workflows. Make sure to use this skill even if the user doesn't explicitly mention "SciencePlots" - if they're asking for plots, charts, figures, or Python scripts in this project, trigger this skill.
+---
+
+# SciencePlots Visualization
+
+A skill for creating publication-quality scientific visualizations using Matplotlib with SciencePlots styles and LaTeX typesetting, and for implementing Python scripts following project standards.
+
+## Domain
+
+Data visualization, scientific plotting, Python implementation
+
+## When to Use
+
+Use this skill whenever:
+
+- Creating any matplotlib plot, chart, or figure
+- Working with scientific data visualization
+- Needing publication-quality plots with LaTeX typesetting
+- Creating 24h time-series profiles (energy load curves, daily patterns)
+- Adding statistical annotations (average, peak values)
+- Visualizing uncertainty with quantile shading
+- Following the project's plotting standards
+- **Writing any Python code in this repository**
+- **Creating or modifying scripts**
+- **Implementing data processing or analysis**
+
+## Core Mandates
+
+These are absolute requirements that MUST be followed in all implementations:
+
+### Path Handling
+
+ALWAYS use `pathlib.Path` for all path operations. Scripts MUST work from any execution directory.
+
+**NEVER use:**
+
+- `os.chdir()` - changing directory is forbidden
+- `sys.path.insert()` - manipulating import paths is forbidden
+- String concatenation for paths (e.g., `dir + "/" + file`)
+
+**ALWAYS use:**
+
+```python
+from pathlib import Path
+
+# Correct - works from any directory
+OUTPUT_DIR = Path("output")
+OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+# Correct - relative to script location
+SCRIPT_DIR = Path(__file__).parent
+DATA_DIR = SCRIPT_DIR / "data"
+```
+
+### Plotting Excellence
+
+Adhere strictly to the Matplotlib Object-Oriented API and the project's custom styling:
+
+- **ALWAYS** use `fig, ax = plt.subplots()` instead of `plt.plot()`
+- **ALWAYS** call `configure_matplotlib_style()` at the start
+- **ALWAYS** use professional LaTeX typesetting for labels
+- **ALWAYS** save plots using `save_plot(fig, filename)`
+
+### Reliability
+
+All findings MUST be reproducible via permanent, executable scripts:
+
+- No interactive-only code
+- All scripts must be runnable from command line
+- Include `if __name__ == "__main__":` blocks
+- Document dependencies and usage
+
+## Implementation Workflow
+
+### 1. Check Existing Utilities
+
+Before implementing custom logic, check:
+
+- `src/scienceplots_toolkit/utils.py` - Common plotting helpers
+- `src/scienceplots_toolkit/analysis.py` - Advanced analysis tools
+
+Common utilities:
+
+- `save_plot(fig, filename)` - Save to PNG and PDF
+- `configure_24h_axis(ax)` - Set up 0-24h x-axis
+- `add_stats_box(ax, avg, peak)` - Add statistical annotations
+- `plot_profile_with_quantiles(ax, x, mean, q10, q90)` - Uncertainty shading
+- `generate_profile_grid(n_rows, n_cols)` - Multi-panel layouts
+
+### 2. Setup
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+from scienceplots_toolkit import configure_matplotlib_style, save_plot
+from scienceplots_toolkit.utils import configure_24h_axis, add_stats_box
+```
+
+### 3. Implementation Standards
+
+- **Type hints**: Use modern type hints (`list[str]`, `tuple[float, ...]`)
+- **Strings**: Use f-strings for formatting
+- **Spelling**: Use English in docstrings
+- **Docstrings**: Include Args sections for all functions
+- **LaTeX labels**: Use raw strings: `r"$\sin(x)$"`, `r"Power (kW)"`
+
+### 4. Plotting Guidelines
+
+- **LaTeX typesetting**: Professional math mode for all labels and units
+- **Constrained layout**: Active by default (don't disable)
+- **Saving**: Always save both PNG and PDF formats
+- **Cleanup**: Always call `plt.close(fig)` after saving
+- **24h profiles**: Use `configure_24h_axis(ax)` for daily time series
+- **Statistics**: Use `add_stats_box()` for average/peak annotations
+- **Uncertainty**: Use `plot_profile_with_quantiles()` for shaded regions
+
+### 5. Verification
+
+After implementation:
+
+```bash
+# Linting
+uv run ruff check .
+
+# Formatting
+uv run ruff format .
+
+# Type checking
+uv run ty check .
+```
+
+## Example
+
+```python
+"""Generate a 24h load profile with uncertainty shading."""
+
+from pathlib import Path
+import matplotlib.pyplot as plt
+import numpy as np
+from scienceplots_toolkit import configure_matplotlib_style, save_plot
+from scienceplots_toolkit.utils import configure_24h_axis, add_stats_box
+from scienceplots_toolkit.analysis import plot_profile_with_quantiles
+
+def main() -> None:
+    """Generate example 24h load profile."""
+    configure_matplotlib_style(use_latex=True)
+    
+    # Generate mock data
+    x = np.arange(24)
+    mean = 5 + 3 * np.exp(-((x - 19) ** 2) / 20)
+    q10 = mean * 0.8
+    q90 = mean * 1.2
+    
+    # Create plot
+    fig, ax = plt.subplots(figsize=(10, 6))
+    plot_profile_with_quantiles(
+        ax, x, mean, q10, q90,
+        label="Load Profile",
+        color="C0"
+    )
+    
+    configure_24h_axis(ax)
+    add_stats_box(ax, avg=mean.mean(), peak=mean.max(), unit=r"\text{kW}")
+    
+    ax.set_xlabel(r"Time of Day (h)")
+    ax.set_ylabel(r"Power Consumption (kW)")
+    ax.legend()
+    
+    # Save and cleanup
+    save_plot(fig, "load_profile")
+    plt.close(fig)
+
+if __name__ == "__main__":
+    main()
+```
+
+## Quality Checklist
+
+Before considering a visualization or script complete:
+
+- [ ] English spelling in docstrings
+- [ ] Matplotlib Object-Oriented API used (`fig, ax = plt.subplots()`)
+- [ ] `configure_matplotlib_style()` called at start
+- [ ] LaTeX math mode for labels and units
+- [ ] Both PNG and PDF formats saved
+- [ ] `plt.close(fig)` called after saving
+- [ ] Type hints present on all functions
+- [ ] Docstrings with Args sections
+- [ ] Script works from any execution directory
+
+## Bundled Resources
+
+- `scripts/` - Executable utilities for common tasks
+- `references/` - Documentation on matplotlib best practices, coding standards
+- `assets/` - Templates and style configurations
+
+## Related Files
+
+- `src/scienceplots_toolkit/style.py` - Style configuration
+- `src/scienceplots_toolkit/utils.py` - Utility functions
+- `src/scienceplots_toolkit/analysis.py` - Analysis tools
+- `examples/` - Working example scripts
+- `PUBLICATION_PLAN.md` - PyPI publication workflow
+- `CHANGELOG.md` - Version history

scienceplots_toolkit-0.1.1/.envrc

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+# `use devenv` supports the same options as the `devenv shell` command.
+#
+# To silence all output, use `--quiet`.
+#
+# Example usage: use devenv --quiet --impure --option services.postgres.enable:bool true
+use devenv

scienceplots_toolkit-0.1.1/.gitignore

@@ -0,0 +1,73 @@
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Python cache and compiled files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+nosetests.xml
+coverage.xml
+
+# mypy / ruff / other tool caches
+.mypy_cache/
+.ruff_cache/
+
+# Build / packaging
+build/
+dist/
+*.egg-info/
+# Logs and runtime files
+*.log
+analysis.log
+
+# Output artifacts (generated by the examples / container)
+output/
+*.png
+*.pdf
+
+# Old redundant files (cleanup)
+example.py
+example_energy.py
+MatplotlibStyle.py
+plotting_utils.py
+profile_analysis.py
+requirements.txt
+# Editor / OS files
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Sensitive files (if you add them)
+.env
+.env.* 
+
+# Devenv
+.devenv*
+devenv.local.nix
+devenv.local.yaml
+.flake.nix.swp
+*swp
+
+# direnv
+.direnv
+
+# pre-commit
+# pre-commit
+.pre-commit-config.yaml
+
+# devenv null directory (temporary interpreter issue)
+null/
+
+# AI agent session data
+.sisyphus/

scienceplots_toolkit-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

scienceplots_toolkit-0.1.1/AGENTS.md

@@ -0,0 +1,41 @@
+# AI Agent Mandates
+
+This repository uses a specialized skill for all Python development and data visualization work.
+
+## Primary Skill
+
+**ALWAYS use the [scienceplots-viz](.agents/skills/scienceplots-viz/SKILL.md) skill for:**
+
+- Any Python coding tasks
+- Creating or modifying scripts
+- Data visualization and plotting
+- Implementation workflows
+- Coding standards and best practices
+
+The skill contains comprehensive instructions for:
+
+- Path handling requirements
+- Plotting standards
+- Implementation workflows
+- Verification procedures
+
+## How to Use
+
+1. **Trigger the skill** - It will automatically activate when you work on Python files or plotting tasks
+2. **Follow the skill instructions** - All coding and plotting standards are documented there
+3. **Use bundled resources** - Check `references/` for additional documentation
+
+## Project Context
+
+- **Package**: `scienceplots_toolkit` - Publication-quality Matplotlib utilities
+- **Source**: `src/scienceplots_toolkit/`
+- **Examples**: `examples/`
+- **Documentation**: `README.md`, `PUBLICATION_PLAN.md`
+
+## Questions?
+
+Refer to:
+
+- [scienceplots-viz Skill](.agents/skills/scienceplots-viz/SKILL.md) - Complete implementation guide
+- [README.md](README.md) - Project overview
+- [PUBLICATION_PLAN.md](PUBLICATION_PLAN.md) - Publication workflow

scienceplots_toolkit-0.1.1/CHANGELOG.md

@@ -0,0 +1,72 @@
+# 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).
+
+## [0.1.0] - 2026-05-07
+
+### Added
+
+- **Initial release** of scienceplots-toolkit v0.1.0
+- **Style configuration** - `configure_matplotlib_style()` with SciencePlots integration
+- **Utility functions**:
+  - `save_plot()` - Save figures to PNG and PDF with logging
+  - `configure_24h_axis()` - Standard 24-hour time axis configuration
+  - `add_stats_box()` - Statistical annotation boxes for average/peak values
+- **Analysis tools**:
+  - `plot_profile_with_quantiles()` - Plot mean with shaded 10%-90% quantiles
+  - `generate_profile_grid()` - Multi-panel grid generation for comparative plots
+- **Colormap utilities** - `qual_cmap()` for qualitative color schemes
+- **Comprehensive test suite** - 36 unit tests covering all public functions
+- **Example scripts** - Basic plots and energy profile examples with CLI interface
+- **Documentation** - Complete README with API reference, installation guide, and examples
+- **Development tooling** - Pre-commit hooks, ruff, ty, pytest configuration
+
+### Changed
+
+- **Logging** - Replaced `print()` statements with proper logging in `save_plot()`
+- **API** - Added optional `output_dir` parameter to `save_plot()` function
+- **Documentation** - Removed Docker references, simplified to user-managed environments
+
+### Technical Details
+
+- **Package structure** - Modern src/ layout with PEP 621 pyproject.toml
+- **Type hints** - Complete type annotations across all modules
+- **Docstrings** - NumPy-style documentation for all public functions
+- **Testing** - pytest suite with 100% coverage of public API
+
+---
+
+## [Unreleased]
+
+### Added (Historical)
+
+- **Workflow Instructions**: Added mandatory instructions for AI agents to
+  maintain `CHANGELOG.md` with each significant change, ensuring a transparent
+  and up-to-date project history without additional tools.
+- **AI Agent Workflow**: Introduced a tool-agnostic agent instruction set to
+  ensure high-quality code and consistent scientific visualization across
+  different AI assistants (Copilot, Claude, Gemini).
+  - Refactored `AGENTS.md` into high-level mandates.
+  - Created `.agents/instructions/` for specialized coding, plotting,
+    documentation, and data handling standards.
+  - Created `.agents/skills/` for high-level task workflows.
+- **Project Infrastructure**: Added `devenv` configuration and integrated
+  `pre-commit` hooks for automated linting and type checking.
+
+### Changed (Historical)
+
+- **Documentation**: Updated `README.md` with new project layout and AI agent
+  workflow details.
+- **Tooling**: Updated `ty` type checking command to use the `check`
+  subcommand.
+
+### Fixed (Historical)
+
+- **Type Checking**: Resolved a `ty` warning in `MatplotlibStyle.py` by
+  removing an unused `type: ignore` directive.
+
+---
+*Last Updated: 2026-05-07*

scienceplots_toolkit-0.1.1/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 Jakob Buchmeier
+
+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.
+
+---
+
+## Acknowledgments
+
+This package builds upon the excellent [SciencePlots](https://github.com/garrettj403/SciencePlots)
+library by John Garrett, which is also licensed under the MIT License.
+
+SciencePlots provides Matplotlib styles for publication-quality plots.
+For more information, see: https://github.com/garrettj403/SciencePlots

scienceplots_toolkit-0.1.1/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: scienceplots-toolkit
+Version: 0.1.1
+Summary: Publication-quality Matplotlib plotting utilities with SciencePlots styles and LaTeX typesetting
+Project-URL: Homepage, https://github.com/jakobbuch/scienceplots-toolkit
+Project-URL: Bug Tracker, https://github.com/jakobbuch/scienceplots-toolkit/issues
+Project-URL: Source, https://github.com/jakobbuch/scienceplots-toolkit
+Project-URL: Changelog, https://github.com/jakobbuch/scienceplots-toolkit/blob/main/CHANGELOG.md
+Author-email: Jakob Buchmeier <jakob.buchmeier@tuwien.ac.at>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cmap>=0.6.2
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: scienceplots>=2.1.1
+Provides-Extra: dev
+Requires-Dist: pre-commit>=4.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Provides-Extra: tests
+Requires-Dist: numpy>=1.24; extra == 'tests'
+Requires-Dist: pytest-cov>=4; extra == 'tests'
+Requires-Dist: pytest>=8; extra == 'tests'
+Description-Content-Type: text/markdown
+
+# SciencePlots Toolkit
+
+[![PyPI - Version](https://img.shields.io/pypi/v/scienceplots-toolkit.svg)](https://pypi.org/project/scienceplots-toolkit)
+[![Python Version](https://img.shields.io/pypi/pyversions/scienceplots-toolkit)](https://pypi.org/project/scienceplots-toolkit)
+[![License](https://img.shields.io/pypi/l/scienceplots-toolkit)](https://github.com/jakobbuch/scienceplots-toolkit/blob/main/LICENSE)
+
+Publication-quality Matplotlib plotting utilities with SciencePlots styles and LaTeX typesetting.
+
+## Features
+
+- **Pre-configured SciencePlots styles** with professional defaults
+- **LaTeX typesetting** for mathematical expressions and units
+- **24-hour time axis** utilities for daily profiles
+- **Statistical annotations** for average/peak values
+- **Quantile shading** for uncertainty visualization
+- **Multi-panel grid** generation for comparative plots
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install scienceplots-toolkit
+```
+
+### From source with uv
+
+```bash
+git clone https://github.com/jakobbuch/scienceplots-toolkit.git
+cd scienceplots-toolkit
+uv sync
+```
+
+### From source with pip
+
+```bash
+git clone https://github.com/jakobbuch/scienceplots-toolkit.git
+cd scienceplots-toolkit
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from scienceplots_toolkit import configure_matplotlib_style, save_plot
+from scienceplots_toolkit.utils import configure_24h_axis, add_stats_box
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Configure the style
+configure_matplotlib_style(use_latex=True)
+
+# Create a simple plot
+fig, ax = plt.subplots()
+x = np.linspace(0, 10, 400)
+ax.plot(x, np.sin(x), label=r"$\sin(x)$")
+ax.set_xlabel(r"Time (s)")
+ax.set_ylabel(r"Amplitude")
+ax.legend()
+
+# Save the plot
+save_plot(fig, "my_first_plot")
+```
+
+## Examples
+
+### Basic Plots
+
+Run the basic examples to see all features in action:
+
+```bash
+# Without LaTeX (uses mathtext)
+uv run examples/example_basic.py
+
+# With LaTeX rendering (requires LaTeX installation)
+uv run examples/example_basic.py --latex
+```
+
+### Energy Profiles
+
+Advanced examples with 24h load profiles and quantile shading:
+
+```bash
+uv run examples/example_energy.py
+uv run examples/example_energy.py --latex
+```
+
+Generated plots are saved to the `output/` directory in both PNG and PDF formats.
+
+## API Reference
+
+### Style Configuration
+
+```python
+from scienceplots_toolkit import configure_matplotlib_style
+
+configure_matplotlib_style(
+    styles=["science", "ieee", "grid"],  # SciencePlots styles to use
+    grid_linewidth=3,                     # Grid line width in points
+    lines_linewidth=4,                    # Plot line width in points
+    fontsize=26,                          # Base font size
+    figsize=(16, 10),                     # Default figure size (inches)
+    font="serif",                         # Font family
+    sans_serif_math=False,                # Use sans-serif for math
+    cmap_name="seaborn:tab10_new",       # Qualitative colormap
+    use_latex=False,                      # Enable LaTeX rendering
+    grid=True,                            # Enable axis gridlines
+    legend_framealpha=1.0,                # Legend background transparency
+    legend_shadow=True,                   # Legend shadow effect
+)
+```
+
+### Utilities
+
+```python
+from scienceplots_toolkit.utils import (
+    save_plot,              # Save figure to PNG and PDF
+    configure_24h_axis,     # Set up 0-24h x-axis with 4h ticks
+    add_stats_box,          # Add average/peak annotation box
+)
+
+# Save a figure
+save_plot(fig, "my_plot", dpi=300)
+
+# Configure 24-hour axis
+configure_24h_axis(ax)
+
+# Add statistics box
+add_stats_box(ax, avg=5.2, peak=12.3, unit=r"\text{kW}")
+```
+
+### Analysis Tools
+
+```python
+from scienceplots_toolkit import (
+    plot_profile_with_quantiles,  # Plot mean with shaded quantiles
+    generate_profile_grid,        # Create multi-panel grid of plots
+)
+
+# Plot with uncertainty shading
+plot_profile_with_quantiles(
+    ax, x, mean, q10, q90,
+    label="Load Profile",
+    color="C0"
+)
+
+# Create a 2x2 grid of subplots
+fig, axes = generate_profile_grid(n_rows=2, n_cols=2)
+```
+
+## LaTeX Support
+
+The package supports two modes:
+
+1. **Mathtext (default)**: Uses Matplotlib's built-in math renderer. No external dependencies.
+2. **LaTeX**: Uses system LaTeX for professional typesetting. Requires:
+   - TeX Live or MiKTeX installation
+   - Packages: `amsmath`, `amssymb`, `amsfonts`, `textcomp`, `gensymb`, `siunitx`, `graphicx`
+
+Enable LaTeX mode:
+
+```python
+configure_matplotlib_style(use_latex=True)
+```
+
+Or via CLI:
+
+```bash
+uv run examples/example_basic.py --latex
+```
+
+## Project Structure
+
+```text
+scienceplots-toolkit/
+├── src/scienceplots_toolkit/
+│   ├── __init__.py          # Public API exports
+│   ├── style.py             # Matplotlib style configuration
+│   ├── utils.py             # Utility functions
+│   └── analysis.py          # Analysis and visualization tools
+├── examples/
+│   ├── example_basic.py     # Basic plotting examples
+│   └── example_energy.py    # Energy profile examples
+├── tests/
+├── pyproject.toml
+├── README.md
+└── LICENSE
+## Development
+
+### Setup
+
+```bash
+uv sync --group dev
+```
+
+### Run Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+### Linting and Formatting
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run ty check .
+```
+
+## Acknowledgments
+
+This package builds upon the excellent [SciencePlots](https://github.com/garrettj403/SciencePlots) library by John Garrett, which is also licensed under the MIT License.
+
+SciencePlots provides Matplotlib styles for publication-quality plots. For more information, see: <https://github.com/garrettj403/SciencePlots>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Contact
+
+Jakob Buchmeier - <jakob.buchmeier@tuwien.ac.at>
+
+Project Link: <https://github.com/jakobbuch/scienceplots-toolkit>