bottleviz 0.1.0

A modern Python data visualization library with smart defaults

BottleViz

A modern Python data visualization library with smart defaults.

BottleViz addresses the gaps in Matplotlib, Seaborn, and Plotly by providing a simplified, intuitive API with beautiful defaults out of the box, excellent performance with large datasets, and seamless integration with pandas and polars.

Key Features

1. Simplified API

One function handles most use cases:

import bottleviz as vz
vz.plot(df, x='column1', y='column2')  # All in one line!

vs. Matplotlib:

fig, ax = plt.subplots()
ax.scatter(df['column1'], df['column2'])
ax.set_xlabel('column1')
ax.set_ylabel('column2')

2. Intelligent Plot Type Detection

BottleViz automatically chooses the right plot type based on your data:

• Scatter for two numeric columns
• Line for time-series data
• Histogram for single numeric column
• Bar for categorical data
• Box/violin for distributions
• Heatmap for correlations
• Sankey for flow diagrams
• Sunburst/Treemap for hierarchical data
• Network graphs for relationships
• Candlestick for financial OHLC data

vz.plot(df)  # Auto-detects appropriate visualization!

3. Beautiful Defaults

Stunning visualizations with zero configuration:

• Modern color palettes (colorblind-friendly)
• Professional typography
• Optimized layout and sizing
• Publication-ready styles
• Dark mode support

vz.set_style('dark')  # Multiple presets available
vz.plot(df)  # Automatically looks great

4. Excellent Performance

Optimized for large datasets:

• Smart downsampling for >10k points
• Optional GPU acceleration
• Datashader backend for millions of points
• Lazy evaluation where applicable

vz.plot(large_df)  # Handles 1M+ rows smoothly

5. Seamless Dataframe Integration

Works perfectly with pandas, polars, and more:

vz.plot(df, x='date', y='sales')
vz.plot(polars_df, x='col1', y='col2')

6. Unified Interface

One consistent API across all plot types:

vz.plot(df, x='col1', y='col2', kind='scatter')  # Same interface
vz.plot(df, x='col1', y='col2', kind='line')
vz.plot(df, x='col1', y='col2', kind='bar')
vz.plot(df, kind='hist')  # Even works without x/y

7. Advanced Visualizations

Explore complex data relationships with specialized chart types:

Sankey Diagrams - Flow between stages/categories

vz.plot(flow_data, kind='sankey', source='from', target='to', value='count')

Requires: networkx

Sunburst Charts - Hierarchical radial layouts

vz.plot(hierarchy_data, kind='sunburst', path=['region', 'city'], value='sales')

Optional: squarify for treemap variant

Treemaps - Hierarchical rectangular layouts

vz.plot(hierarchy_data, kind='treemap', path=['region', 'city'], value='sales')

Requires: squarify

Network Graphs - Visualize relationships and connections

vz.plot(edges, kind='network', source='node1', target='node2', layout='spring')

Requires: networkx

Candlestick Charts - Financial OHLC time series

vz.plot(stock_data, x='date', kind='candlestick', open='open', high='high', low='low', close='close')

3D Visualizations - Comprehensive 3D plotting suite

# Surface plot (points connected by planes)
fig, ax = vz.plot_3d_surface(X, Y, Z, title='Surface', cmap='viridis')

# Wireframe mesh
fig, ax = vz.plot_3d_wireframe(X, Y, Z, title='Wireframe')

# Triangular surface (for scattered data)
fig, ax = vz.plot_3d_trisurf(x, y, z, title='Triangular Surface')

# Contour lines and filled contours
fig, ax = vz.plot_3d_contour(X, Y, Z, levels=15)
fig, ax = vz.plot_3d_contourf(X, Y, Z, levels=20)

# Vector field (arrows)
fig, ax = vz.plot_3d_quiver(X, Y, Z, U, V, W, title='Vector Field')

# 3D stem plot
fig, ax = vz.plot_3d_stem(x, y, z, title='3D Stem')

# 3D bar chart
fig, ax = vz.plot_3d_bar(x, y, z, dx, dy, dz, title='3D Bars')

# 3D voxel/volume rendering
fig, ax = vz.plot_3d_voxels(voxel_array, title='3D Voxels')

# Advanced: Create custom 3D figure and add multiple elements
fig, ax = vz.figure3d(title='Custom 3D Plot')
ax.plot_surface(X, Y, Z, cmap='plasma')
ax.contour(X, Y, Z, levels=10)
vz.show()

All 3D functions support full matplotlib customization via **kwargs.

Installation

# Basic installation
pip install bottleviz

# With all optional backends
pip install bottleviz[all]

# Just pandas/numpy + matplotlib
pip install bottleviz

# For interactive plots (Plotly)
pip install bottleviz[plotly]

# For massive datasets (Datashader)
pip install bottleviz[datashader]

Quick Start

import bottleviz as vz
import pandas as pd
import numpy as np

# Create sample data
df = pd.DataFrame({
    'x': np.random.randn(1000),
    'y': np.random.randn(1000),
    'category': np.random.choice(['A', 'B', 'C'], 1000),
    'value': np.random.randint(0, 100, 1000)
})

# Simple plot - auto-detects scatter
vz.plot(df, x='x', y='y')

# Bar chart with categories
vz.plot(df, x='category', y='value', kind='bar')

# Histogram
vz.plot(df, kind='hist', x='value')

# Time series
dates = pd.date_range('2024-01-01', periods=100)
ts_df = pd.DataFrame({
    'date': dates,
    'price': np.random.randn(100).cumsum() + 100
})
vz.plot(ts_df, x='date', y='price')  # Auto-detects line plot

# Change style
vz.set_style('dark')
vz.plot(df, x='x', y='y')

# Get suggestions
vz.suggest_plots(df)

# Quick dashboard
vz.visualize(df)

API Reference

Main Functions

vz.plot(data, x=None, y=None, kind=None, **kwargs)

Core plotting function with smart defaults.

Parameters:

• data: DataFrame, Series, ndarray, list, or dict
• x: Column name for x-axis (optional)
• y: Column name(s) for y-axis (optional)
• kind: Plot type ('scatter', 'line', 'bar', 'hist', 'box', 'violin', 'heatmap', 'pie', 'area', 'kde', '3d', 'stem', 'errorbar', 'sankey', 'sunburst', 'treemap', 'network', 'candlestick')
• **kwargs: Additional arguments (title, xlabel, ylabel, etc.)

Examples:

vz.plot(df, x='col1', y='col2')                    # Auto-detects scatter
vz.plot(df, x='col1', y='col2', kind='line')       # Force line
vz.plot(df, kind='hist')                           # Histogram of all numeric columns
vz.plot(df, x='category', y='value', kind='bar')  # Bar chart

vz.quickplot(*args, **kwargs)

Ultra-simple one-liner plotting.

vz.quickplot([1,2,3,4,5])                      # Line plot from list
vz.quickplot(x=[1,2,3], y=[4,5,6])             # Named lists
vz.quickplot(df)                               # Auto-visualize first two numeric columns

vz.visualize(data, columns=None, plot_type='auto', max_plots=6, **kwargs)

Create a multi-panel dashboard for exploratory analysis.

vz.visualize(df)                    # Dashboard with all numeric columns
vz.visualize(df, columns=['x','y','z'])  # Specific columns only
vz.visualize(df, plot_type='dist')  # Distribution plots only

vz.suggest_plots(data)

Get recommendations for visualizations.

recs = vz.suggest_plots(df)
print(recs)
#       type    x    y                      rationale              example_code
# 0     hist   x  None  Distribution of 'x' - shows...  vz.plot(df, x='x')
# 1   scatter   x    y         Relationship between...  vz.plot(df, x='x', y='y')

vz.report(data, show_plots=False)

Generate a comprehensive report.

report = vz.report(df)  # Text report
report = vz.report(df, show_plots=True)  # Report + dashboard figure

vz.explore(data, mode='auto')

Smart exploratory data analysis.

vz.explore(df)                      # Auto-choose best visualizations
vz.explore(df, mode='distribution') # Distribution plots only
vz.explore(df, mode='relationship') # Correlation plots

Style Management

vz.set_style(style)

Set global visual style.

vz.set_style('default')    # Clean, modern default
vz.set_style('dark')       # Dark theme
vz.set_style('minimal')    # Minimal ink, maximum data
vz.set_style('publication')# Publication-ready
vz.set_style('seaborn')    # Seaborn-compatible

vz.available_styles()

List available style presets.

print(vz.available_styles())
# ['default', 'dark', 'minimal', 'publication', 'seaborn']

vz.create_custom_style(name, **kwargs)

Create your own style.

vz.create_custom_style('my_style',
    figure.figsize=(12, 8),
    axes.titlesize=16,
    axes.prop_cycle=plt.cycler('color', ['#FF0000', '#00FF00', '#0000FF'])
)
vz.set_style('my_style')

Plot Types Supported

Standard Plots

Plot Type	Use Case	Auto-detected When
scatter	Relationship between two numeric variables	Two numeric columns provided
line	Time series or sequential data	Datetime index or sorted x-axis
bar	Categorical comparisons	Categorical x with numeric y
hist	Distribution of single variable	Single numeric column
box	Distribution with outliers	Box plot recommended
violin	Detailed distribution shape	Violin plot recommended
kde	Smooth density estimate	KDE recommended
area	Cumulative totals	Area plot specified
heatmap	Correlation matrix	Matrix data or 3+ numeric columns
pie	Proportional breakdown	Single categorical column with ≤6 unique values
stem	Discrete data points with stems	Stem plot specified
errorbar	Data with error margins	Error values provided
candlestick	Financial OHLC data	Open, high, low, close columns

Advanced Visualizations

Plot Type	Use Case	Requirements
sankey	Flow between stages/categories	Multi-stage path or source-target pairs; requires networkx
sunburst	Hierarchical radial layout	Hierarchical path with value; optional squarify
treemap	Hierarchical rectangular layout	Hierarchical path with value; requires squarify
network	Graph relationships	Edge list (source, target); requires networkx

3D Visualizations

Plot Type	Use Case	Data Format
plot_3d_surface	Continuous surface (points connected as planes)	2D meshgrid arrays (X, Y, Z)
plot_3d_wireframe	Wireframe mesh showing grid structure	2D meshgrid arrays (X, Y, Z)
plot_3d_trisurf	Triangular surface for scattered data	1D arrays (x, y, z) - triangulated automatically
plot_3d_contour	3D contour lines	2D meshgrid arrays (X, Y, Z)
plot_3d_contourf	Filled 3D contours	2D meshgrid arrays (X, Y, Z)
plot_3d_quiver	3D vector field (arrows)	Grid coordinates (X, Y, Z) and vector components (U, V, W)
plot_3d_stem	3D stem plots	1D arrays (x, y, z)
plot_3d_bar	3D bar chart	Positions (x, y, z) and dimensions (dx, dy, dz)
plot_3d_voxels	3D volume/cube rendering	3D boolean or scalar array
figure3d	Create empty 3D figure for custom plotting	Returns (fig, ax) for manual plotting

All 3D functions provide full access to matplotlib's 3D API via **kwargs.

Solving Gaps in Existing Libraries

vs Matplotlib

• Simplicity: No more verbose fig, ax = plt.subplots() boilerplate
• Smarter defaults: Beautiful plots automatically
• Type inference: No need to specify plot type manually

vs Seaborn

• Performance: Better optimization for large datasets
• Consistency: One function for all plot types
• Flexibility: Works with numpy arrays directly

vs Plotly

• Lightweight: Pure Python core, no JavaScript needed
• Static quality: Publication-ready out of the box
• Easier deployment: No browser dependencies

Advanced Features

Large Dataset Optimization

# Automatic downsampling for >10k points
vz.plot(huge_df)  # Smooth even with 1M rows

Smart Color Palettes

# Automatically colorblind-friendly
vz.plot(df, x='cat', y='val', kind='bar')  # Beautiful colors

# Custom palette
vz.plot(df, x='cat', y='val', kind='bar', palette='pastel')

Automatic Subplot Layout

# Automatically arranges subplots
vz.visualize(df, max_plots=6)  # Smart 2x3 layout

Pandas/Polars Integration

# Works with many data structures
vz.plot(df)                    # pandas DataFrame
vz.plot(pl.DataFrame(...))    # polars DataFrame
vz.plot(np_array)             # NumPy array
vz.plot([1,2,3,4,5])          # Python list
vz.plot({'x': [...], 'y': [...]})  # Dictionary

Limitations and Future Work

Current limitations:

• Only matplotlib backend implemented (Plotly backend planned)
• Advanced charts (Sankey, Sunburst, Treemap, Network, Candlestick) require optional dependencies
• 3D visualizations use matplotlib's mplot3d (limited interactivity compared to Plotly)

Planned features:

• Plotly interactive backend with enhanced 3D
• Bokeh backend
• GPU acceleration with CuPy
• Map/geographic visualizations
• Animation support
• Export to HTML with interactivity
• Graphviz layout for network graphs

Requirements

• Python >= 3.8
• NumPy >= 1.18.0
• Pandas >= 1.0.0
• Matplotlib >= 3.0.0

Optional:

• plotly >= 5.0.0 (for interactive plots)
• datashader >= 0.13.0 (for massive datasets)
• networkx (for network graphs and Sankey diagrams)
• squarify (for treemaps)
• polars (alternative to pandas)

Contributing

We welcome contributions! Please see our contributing guide in the repository.

License

MIT License - see LICENSE file for details.

Examples Gallery

More examples available in the examples/ directory:

1. Basic Plots: Line, scatter, bar, histogram (demo.py, example.py)
2. Statistical: Box, violin, KDE
3. Compositional: Pie, area, stacked charts
4. Multivariate: Heatmap, pair plots, 3D
5. Time Series: Date handling, rolling windows
6. Large Data: Downsampling, datashader
7. Styling: Themes, custom palettes, publication tips
8. Advanced: Sankey, Sunburst, Treemap, Network, Candlestick
9. 3D Visualizations:
   • all_3d_plots.py - Comprehensive demo of all 10+ 3D plot types (surface, wireframe, trisurf, contour, quiver, stem, bar3d, voxels)
   • array_slices_3d.py - Advanced 3D array slices with intersecting planes
   • demo_show_close.py - Cone surface plot with show/close functions

Run examples:

python -m bottleviz.examples

Citation

If you use BottleViz in your research, please cite:

@software{bottleviz2024,
  author = {{BottleViz Team}},
  title = {{BottleViz: A Modern Python Visualization Library}},
  year = {2024},
  url = {https://github.com/bottleviz/bottleviz}
}

---

Made with ❤️ for data scientists, analysts, and engineers who believe visualization should be simple and beautiful.