# yaml2plot: A Python Package for Creating Plots from YAML Specifications
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
yaml2plot is a powerful yet lightweight Python package for creating interactive Plotly figures from YAML specifications and SPICE .raw files with minimal code. It loads simulation data directly into a simple {signal_name: np.ndarray} dictionary, supports declarative multi-axis plots via YAML configurations, and automatically selects the best renderer for Jupyter, VS Code, or headless environments. With case-insensitive signal lookup and robust multi-strip support, yaml2plot lets you focus on circuit analysis—not plotting boilerplate.
## Features
- **Interactive Plotly Visualization**: Modern, web-based plots with zoom, pan, and hover
- **YAML Configuration**: Flexible, reusable plotting configurations
- **Simple API**: Plot waveforms with a single function call
- **Command Line Interface**: Quick plotting from terminal with `y2p plot`
- **Automatic Environment Detection**: Auto-detection and inline plotting for Jupyter Notebooks, render in browser when running in standalone Python scripts.
## Quick Start
### Installation
```bash
pip install yaml2plot
```
yaml2plot provides two common workflows for visualizing your SPICE simulations:
* **Option A: CLI-First** – The fastest way to get from a ``.raw`` file to an interactive plot. Perfect for quick, one-off visualizations.
* **Option B: Python API** – The most flexible approach. Ideal for scripting, custom data processing, and embedding plots in notebooks or reports.
### Option A: CLI-First Workflow
Get from a raw file to a plot in three steps using the ``y2p`` command-line tool.
**Step 1: Generate a Plot Specification**
Use ``y2p init`` to create a template ``spec.yaml`` file from your simulation output. It automatically populates the file with the independent variable (like "time") and a few available signals.
```bash
y2p init your_simulation.raw > spec.yaml
```
**Step 2: Discover Signals**
Find the exact names of the signals you want to plot with ``y2p signals``.
```bash
# List the first 10 signals
y2p signals your_simulation.raw
# List all signals
y2p signals your_simulation.raw --all
# Filter signals using a regular expression
y2p signals your_simulation.raw --grep "clk"
```
**Step 3: Plot**
Edit your ``spec.yaml`` to include the signals you discovered, then use ``y2p plot`` to generate an interactive HTML file or display the plot directly. The command now supports a self-contained workflow where the raw file is specified directly in the YAML.
```bash
# This command will open a browser window with your plot
y2p plot spec.yaml
# You can also override the raw file specified in the YAML
y2p plot spec.yaml your_simulation.raw
# To save the plot to a file instead
y2p plot spec.yaml --output my_plot.html
```
This approach is fast, requires no Python code, and keeps your plot configuration version-controlled alongside your simulation files.
### Option B: Python API Workflow
For more advanced use cases, the Python API provides full control over data loading, processing, and plotting. This is ideal for Jupyter notebooks, custom analysis scripts, and automated report generation.
The API follows a clear three-step workflow:
1. **Data Loading** – Load the raw ``.raw`` file with ``yaml2plot.load_spice_raw``.
2. **Configuration** – Describe what you want to see using ``yaml2plot.PlotSpec``.
3. **Plotting** – Call ``yaml2plot.plot`` to get a Plotly figure.
**Minimal Example**
```python
import yaml2plot as y2p
# 1. Load data from a .raw file
data = y2p.load_spice_raw("your_simulation.raw")
print(f"Signals available: {list(data.keys())[:5]}...")
# 2. Configure the plot using a YAML string
spec = y2p.PlotSpec.from_yaml("""
title: "My Simulation Results"
x:
signal: "time"
label: "Time (s)"
y:
- label: "Voltage (V)"
signals:
Output: "v(out)"
Input: "v(in)"
""")
# 3. Create and display the plot
fig = y2p.plot(data, spec)
fig.show()
```
**Advanced Example: Plotting Derived Signals**
Because the API gives you direct access to the data as NumPy arrays, you can easily perform calculations and plot the results.
```python
import numpy as np
import yaml2plot as y2p
# Load the data
data = y2p.load_spice_raw("your_simulation.raw")
# Calculate a new, derived signal
data["diff_voltage"] = data["v(out_p)"] - data["v(out_n)"]
# Create a spec that plots both raw and derived signals
spec = y2p.PlotSpec.from_yaml("""
title: "Differential Output Voltage"
x:
signal: "time"
label: "Time (s)"
y:
- label: "Voltage (V)"
signals:
VOUT_P: "v(out_p)"
VOUT_N: "v(out_n)"
VOUT_DIFF: "diff_voltage"
""")
# Create and display the plot
fig = y2p.plot(data, spec)
fig.show()
```
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/Jianxun/yaml2plot.git
cd yaml2plot
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode with all dependencies
pip install -e .
pip install -r requirements-dev.txt
# Verify development setup
python -c "import yaml2plot as y2p; print('Development setup complete!')"
```
### Run Tests
```bash
# Run all tests
pytest
# With coverage
pytest --cov=yaml2plot --cov-report=html
# Run specific test file
pytest tests/workflows/test_cli_plot.py -v
```
## Project Structure
```
yaml2plot/
├── src/yaml2plot/
│ ├── core/
│ │ ├── plotspec.py # PlotSpec model
│ │ ├── plotting.py # Plotting helpers + plot()
│ │ └── wavedataset.py # WaveDataset + low-level loaders
│ ├── loader.py # load_spice_raw convenience wrapper
│ ├── cli.py # Command-line interface
│ └── __init__.py # Public symbols (plot, PlotSpec, load_spice_raw,...)
├── tests/ # Test suite
├── examples/ # Usage examples
├── docs/ # Documentation
└── pyproject.toml # Packaging
```
## Requirements
- **Python**: 3.8+
- **Core Dependencies**:
- `plotly` >= 5.0.0 (Interactive plotting)
- `numpy` >= 1.20.0 (Numerical operations)
- `PyYAML` >= 6.0 (Configuration files)
- `spicelib` >= 1.0.0 (SPICE file reading)
- `click` >= 8.0.0 (Command line interface)
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`pytest`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Documentation (https://Jianxun.github.io/yaml2plot/)
Comprehensive documentation is available with:
- **User Guides**: Installation, quickstart, and configuration
- **API Reference**: Complete function documentation
- **Examples**: Practical use cases and tutorials
- **Development**: Contributing guidelines and setup
### Build Documentation Locally
```bash
# Install documentation dependencies
pip install -e ".[docs]"
# Build documentation
make docs
# Serve documentation locally
make docs-serve # Opens at http://localhost:8000
```
## Links
- **Documentation**: [GitHub Pages](https://Jianxun.github.io/yaml2plot/)
- **PyPI Package**: [PyPI](https://pypi.org/project/yaml2plot/)
- **Issue Tracker**: [GitHub Issues](https://github.com/Jianxun/yaml2plot/issues)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
## Version
Current version: **2.0.0**
---
**yaml2plot** - Making SPICE waveform visualization simple and interactive! 🌊📈
Raw data
{
"_id": null,
"home_page": null,
"name": "yaml2plot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Jianxun Zhu <jianxun.zhu@example.com>",
"keywords": "yaml, plotting, spice, simulation, waveform, visualization, jupyter, eda",
"author": null,
"author_email": "Jianxun Zhu <jianxun.zhu@example.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/67/9c1fc3972c29ee052f553ef73e27dedd401af893a7235999705e91125f8f/yaml2plot-2.0.1.tar.gz",
"platform": null,
"description": "# yaml2plot: A Python Package for Creating Plots from YAML Specifications\n\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n\nyaml2plot is a powerful yet lightweight Python package for creating interactive Plotly figures from YAML specifications and SPICE .raw files with minimal code. It loads simulation data directly into a simple {signal_name: np.ndarray} dictionary, supports declarative multi-axis plots via YAML configurations, and automatically selects the best renderer for Jupyter, VS Code, or headless environments. With case-insensitive signal lookup and robust multi-strip support, yaml2plot lets you focus on circuit analysis\u2014not plotting boilerplate.\n\n\n\n## Features\n\n- **Interactive Plotly Visualization**: Modern, web-based plots with zoom, pan, and hover\n- **YAML Configuration**: Flexible, reusable plotting configurations\n- **Simple API**: Plot waveforms with a single function call\n- **Command Line Interface**: Quick plotting from terminal with `y2p plot`\n- **Automatic Environment Detection**: Auto-detection and inline plotting for Jupyter Notebooks, render in browser when running in standalone Python scripts.\n\n\n\n## Quick Start\n\n### Installation\n```bash\npip install yaml2plot\n```\n\nyaml2plot provides two common workflows for visualizing your SPICE simulations:\n\n* **Option A: CLI-First** \u2013 The fastest way to get from a ``.raw`` file to an interactive plot. Perfect for quick, one-off visualizations.\n* **Option B: Python API** \u2013 The most flexible approach. Ideal for scripting, custom data processing, and embedding plots in notebooks or reports.\n\n\n### Option A: CLI-First Workflow\n\nGet from a raw file to a plot in three steps using the ``y2p`` command-line tool.\n\n**Step 1: Generate a Plot Specification**\n\nUse ``y2p init`` to create a template ``spec.yaml`` file from your simulation output. It automatically populates the file with the independent variable (like \"time\") and a few available signals.\n\n```bash\ny2p init your_simulation.raw > spec.yaml\n```\n\n**Step 2: Discover Signals**\n\nFind the exact names of the signals you want to plot with ``y2p signals``.\n\n```bash\n# List the first 10 signals\ny2p signals your_simulation.raw\n\n# List all signals\ny2p signals your_simulation.raw --all\n\n# Filter signals using a regular expression\ny2p signals your_simulation.raw --grep \"clk\"\n```\n\n**Step 3: Plot**\n\nEdit your ``spec.yaml`` to include the signals you discovered, then use ``y2p plot`` to generate an interactive HTML file or display the plot directly. The command now supports a self-contained workflow where the raw file is specified directly in the YAML.\n\n```bash\n# This command will open a browser window with your plot\ny2p plot spec.yaml\n\n# You can also override the raw file specified in the YAML\ny2p plot spec.yaml your_simulation.raw\n\n# To save the plot to a file instead\ny2p plot spec.yaml --output my_plot.html\n```\n\nThis approach is fast, requires no Python code, and keeps your plot configuration version-controlled alongside your simulation files.\n\n### Option B: Python API Workflow\n\nFor more advanced use cases, the Python API provides full control over data loading, processing, and plotting. This is ideal for Jupyter notebooks, custom analysis scripts, and automated report generation.\n\nThe API follows a clear three-step workflow:\n\n1. **Data Loading** \u2013 Load the raw ``.raw`` file with ``yaml2plot.load_spice_raw``.\n2. **Configuration** \u2013 Describe what you want to see using ``yaml2plot.PlotSpec``.\n3. **Plotting** \u2013 Call ``yaml2plot.plot`` to get a Plotly figure.\n\n**Minimal Example**\n\n```python\nimport yaml2plot as y2p\n\n# 1. Load data from a .raw file\ndata = y2p.load_spice_raw(\"your_simulation.raw\")\nprint(f\"Signals available: {list(data.keys())[:5]}...\")\n\n# 2. Configure the plot using a YAML string\nspec = y2p.PlotSpec.from_yaml(\"\"\"\ntitle: \"My Simulation Results\"\nx:\n signal: \"time\"\n label: \"Time (s)\"\ny:\n - label: \"Voltage (V)\"\n signals:\n Output: \"v(out)\"\n Input: \"v(in)\"\n\"\"\")\n\n# 3. Create and display the plot\nfig = y2p.plot(data, spec)\nfig.show()\n```\n\n**Advanced Example: Plotting Derived Signals**\n\nBecause the API gives you direct access to the data as NumPy arrays, you can easily perform calculations and plot the results.\n\n```python\nimport numpy as np\nimport yaml2plot as y2p\n\n# Load the data\ndata = y2p.load_spice_raw(\"your_simulation.raw\")\n\n# Calculate a new, derived signal\ndata[\"diff_voltage\"] = data[\"v(out_p)\"] - data[\"v(out_n)\"]\n\n# Create a spec that plots both raw and derived signals\nspec = y2p.PlotSpec.from_yaml(\"\"\"\ntitle: \"Differential Output Voltage\"\nx:\n signal: \"time\"\n label: \"Time (s)\"\ny:\n - label: \"Voltage (V)\"\n signals:\n VOUT_P: \"v(out_p)\"\n VOUT_N: \"v(out_n)\"\n VOUT_DIFF: \"diff_voltage\"\n\"\"\")\n\n# Create and display the plot\nfig = y2p.plot(data, spec)\nfig.show()\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/Jianxun/yaml2plot.git\ncd yaml2plot\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode with all dependencies\npip install -e .\npip install -r requirements-dev.txt\n\n# Verify development setup\npython -c \"import yaml2plot as y2p; print('Development setup complete!')\"\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npytest\n\n# With coverage\npytest --cov=yaml2plot --cov-report=html\n\n# Run specific test file\npytest tests/workflows/test_cli_plot.py -v\n```\n\n## Project Structure\n\n```\nyaml2plot/\n\u251c\u2500\u2500 src/yaml2plot/\n\u2502 \u251c\u2500\u2500 core/\n\u2502 \u2502 \u251c\u2500\u2500 plotspec.py # PlotSpec model\n\u2502 \u2502 \u251c\u2500\u2500 plotting.py # Plotting helpers + plot()\n\u2502 \u2502 \u2514\u2500\u2500 wavedataset.py # WaveDataset + low-level loaders\n\u2502 \u251c\u2500\u2500 loader.py # load_spice_raw convenience wrapper\n\u2502 \u251c\u2500\u2500 cli.py # Command-line interface\n\u2502 \u2514\u2500\u2500 __init__.py # Public symbols (plot, PlotSpec, load_spice_raw,...)\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 examples/ # Usage examples\n\u251c\u2500\u2500 docs/ # Documentation\n\u2514\u2500\u2500 pyproject.toml # Packaging\n```\n\n## Requirements\n\n- **Python**: 3.8+\n- **Core Dependencies**:\n - `plotly` >= 5.0.0 (Interactive plotting)\n - `numpy` >= 1.20.0 (Numerical operations)\n - `PyYAML` >= 6.0 (Configuration files)\n - `spicelib` >= 1.0.0 (SPICE file reading)\n - `click` >= 8.0.0 (Command line interface)\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`pytest`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Documentation (https://Jianxun.github.io/yaml2plot/)\n\nComprehensive documentation is available with:\n- **User Guides**: Installation, quickstart, and configuration\n- **API Reference**: Complete function documentation\n- **Examples**: Practical use cases and tutorials\n- **Development**: Contributing guidelines and setup\n\n\n### Build Documentation Locally\n\n```bash\n# Install documentation dependencies\npip install -e \".[docs]\"\n\n# Build documentation\nmake docs\n\n# Serve documentation locally\nmake docs-serve # Opens at http://localhost:8000\n```\n\n## Links\n\n- **Documentation**: [GitHub Pages](https://Jianxun.github.io/yaml2plot/)\n- **PyPI Package**: [PyPI](https://pypi.org/project/yaml2plot/)\n- **Issue Tracker**: [GitHub Issues](https://github.com/Jianxun/yaml2plot/issues)\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n\n## Version\n\nCurrent version: **2.0.0**\n\n---\n\n**yaml2plot** - Making SPICE waveform visualization simple and interactive! \ud83c\udf0a\ud83d\udcc8 \n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for creating plots from YAML specifications of SPICE simulation waveforms",
"version": "2.0.1",
"project_urls": {
"Bug Reports": "https://github.com/Jianxun/yaml2plot/issues",
"Documentation": "https://github.com/Jianxun/yaml2plot/tree/main/docs",
"Homepage": "https://github.com/Jianxun/yaml2plot",
"Source": "https://github.com/Jianxun/yaml2plot"
},
"split_keywords": [
"yaml",
" plotting",
" spice",
" simulation",
" waveform",
" visualization",
" jupyter",
" eda"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9f5817324204f0f7e9b18039a145c489a885c638b9d38c7ccb9c9fbd0ba12759",
"md5": "f960f10a67cc232cf126105475a2b417",
"sha256": "b344394f11fb9dc6e658faf3b4015ec4ada068e1b0cbab0d84cb85d36c65fc29"
},
"downloads": -1,
"filename": "yaml2plot-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f960f10a67cc232cf126105475a2b417",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20997,
"upload_time": "2025-07-23T02:25:08",
"upload_time_iso_8601": "2025-07-23T02:25:08.523090Z",
"url": "https://files.pythonhosted.org/packages/9f/58/17324204f0f7e9b18039a145c489a885c638b9d38c7ccb9c9fbd0ba12759/yaml2plot-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1679c1fc3972c29ee052f553ef73e27dedd401af893a7235999705e91125f8f",
"md5": "5b329d92218607d9352e56b85a079114",
"sha256": "51e7d36b54f1d80cb5137be3741adff40787efdbb377aa3a882f8735f7f6da3e"
},
"downloads": -1,
"filename": "yaml2plot-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5b329d92218607d9352e56b85a079114",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22318,
"upload_time": "2025-07-23T02:25:09",
"upload_time_iso_8601": "2025-07-23T02:25:09.789737Z",
"url": "https://files.pythonhosted.org/packages/b1/67/9c1fc3972c29ee052f553ef73e27dedd401af893a7235999705e91125f8f/yaml2plot-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 02:25:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jianxun",
"github_project": "yaml2plot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "ipywidgets",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "jupyter",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"22.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "yaml2plot"
}
JSON
