boviz 0.3.3

An advanced and flexible scientific plotting toolkit.

English | 中文

boviz

boviz is an advanced Python toolkit designed for generating publication-quality scientific figures with minimal code. Built on top of Matplotlib, it simplifies the creation of complex plots like multi-curve comparisons, dual-axis charts, heatmaps, and schematic diagrams, all while automatically applying academic styling conventions.

---

✨ Key Features

• Publication-Ready Aesthetics: Automatically applies academic font styles (e.g., Times New Roman) and optimizes tick marks, labels, and legends for high-resolution output.
• Streamlined Workflow:
  • CSV to Plot: The boviz.curves module allows you to generate complex comparison plots directly from CSV files with a single function call.
  • NumPy Support: Easily plot data directly from NumPy arrays.
• Advanced Plotting Capabilities:
  • Residual Analysis: Automatically calculate and visualize the difference between experimental and simulation data.
  • Dual Y-Axis: Effortlessly create plots with two different Y-axes.
  • Heatmaps & Fields: Visualize 2D fields (e.g., from finite element analysis) with boviz.heatmap.
  • Schematics: Generate academic-style schematic diagrams (e.g., particle distributions) with boviz.schematic.
• Automated Versioning: Uses setuptools_scm for seamless version management based on Git tags.

---

📦 Installation

pip install boviz

Or, to install the development or latest version from source:

# Clone the repository
git clone https://github.com/bo-qian/boviz.git
cd boviz

# (Optional) Create a virtual environment
python -m venv venv && source venv/bin/activate

# Install the package from source
pip install .

---

📖 Usage

For detailed API documentation, tutorials, and more examples, please visit the official documentation: 👉 https://boviz.readthedocs.io/zh-cn/latest/

You can quickly scaffold a new boviz-based project using the built-in CLI:

boviz init my_project

This command creates a new directory my_project with a recommended structure, including example scripts and configuration files. It helps you get started with best practices for organizing your plotting workflow.

Generated structure:

my_project/
├── data/
│   └── example.csv
└── plot.py

After initialization, you can immediately start adding your data and scripts, and use boviz's plotting functions as shown below.

---

🚀 Quick Example

from boviz import *

# Plot initial particle distribution schematic
plot_initial_particle_schematic(
  coordinates=[[90, 90], [150, 90]],
  radii=[30, 30],
  domain=[240, 180],
  title="Initial Particle Distribution",
  show=True,
  save=True
)

# Multiple feature curve plotting
plot_curves_csv(
  path=["example/data/test_plotkit_multifeature_data.csv"] * 4,
  label=["Exp 800K", "Exp 900K", "Sim 800K", "Sim 900K"],
  x=[0, 0, 0, 0],
  y=[1, 2, 3, 4],
  xy_label=["Time (s)", "Shrinkage Ratio"],
  title_figure="Shrinkage Comparison at Two Temperatures",
  use_marker=[True, True, False, False],
  legend_ncol=2,
  save=True,
  show=False
)

# Single curve plotting: Plot a single simulation curve
x = np.linspace(0, 4*np.pi, 200)
y = np.sin(x)
plot_curves(
    data=[(x, y)],
    label=["$\sin(x)$"],
    xy_label=("$x$", "$\sin(x)$"),
    title_figure="Sine Wave Example",
    save=True,
    show=True
)

# Particle heatmap example
plot_heatmap_particle(
    particle_x_num=2,
    particle_y_num=1,
    particle_radius=30,
    border=1,
    cmap='coolwarm',
    title_figure="Particle Heatmap Example",
    save=True,
    show=False
)

Initial Particle Distribution	Shrinkage Comparison
Sine Wave Example	Particle Heatmap Example

---

🧪 Testing

To run all tests, use:

python -m pytest

Note: On Windows, if you installed boviz in a Conda environment, make sure to run this command from the Conda terminal (Anaconda Prompt or your activated Conda shell), not from the default system terminal.

All core plotting functions are covered by unit tests under the tests/ directory, including:

• Curve plotting (single and multi-feature)
• Schematic particle distribution
• Residual comparison
• Style and legend configurations

---

📁 Project Structure

boviz/
├── src/
│   └── boviz/
│       ├── __init__.py
│       ├── __main__.py          # Main entry point for the package
│       ├── cli.py               # Command-line interface for plotting
│       ├── config.py            # Global parameters and color sets
│       ├── curves.py            # Core curve plotting functions
│       ├── schematic.py         # Particle schematic functions
│       ├── heatmap.py           # Particle heatmap plotting
│       ├── style.py             # Default plot styling
│       └── utils.py             # Filename generator and helpers
├── tests/                       # Pytest-based test cases
├── example/                     # Example scripts and CSV data
│   ├── data/
│   └── test_example_plot.py
├── figures/                     # Output figures (auto-generated)
│   └── ShowExample/             # Example figures for documentation
├── requirements.txt             # Required dependencies
├── pyproject.toml               # Build configuration
├── setup.py                     # Legacy install config
├── LICENSE
├── README.md
└── README_zh.md                 # Chinese version of the README

---

📚 Dependencies

matplotlib>=3.0
numpy>=1.18
pandas>=1.0
pytest>=6.0
pathlib>=1.0
argparse>=1.4.0
meshio>=4.0
netCDF4>=1.5

Install via:

pip install -r requirements.txt

---

🙌 Contributing

Feel free to contribute by:

• Reporting issues and bugs
• Improving documentation and examples
• Submitting pull requests with enhancements or new plotting modules

All contributions are welcome and appreciated.

---

📜 License

GNU General Public License v3 (GPLv3) License © 2025 Bo Qian

---

For advanced examples and API documentation, please refer to the tests/ and example/ directories, or explore the docstrings inside the src/boviz/ module.