Metadata-Version: 2.4
Name: bottleviz
Version: 0.1.0
Summary: A modern Python data visualization library with smart defaults
Author-email: BottleViz Team <bottleviz@example.com>
License: MIT
Project-URL: Homepage, https://github.com/bottleviz/bottleviz
Project-URL: Documentation, https://bottleviz.readthedocs.io
Project-URL: Repository, https://github.com/bottleviz/bottleviz
Project-URL: Bug Tracker, https://github.com/bottleviz/bottleviz/issues
Keywords: visualization,plotting,matplotlib,seaborn,data-science
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.18.0
Requires-Dist: pandas>=1.0.0
Requires-Dist: matplotlib>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Provides-Extra: plotly
Requires-Dist: plotly>=5.0.0; extra == "plotly"
Provides-Extra: datashader
Requires-Dist: datashader>=0.13.0; extra == "datashader"
Provides-Extra: network
Requires-Dist: networkx>=2.0; extra == "network"
Provides-Extra: treemap
Requires-Dist: squarify>=0.4.0; extra == "treemap"
Provides-Extra: all
Requires-Dist: plotly>=5.0.0; extra == "all"
Requires-Dist: datashader>=0.13.0; extra == "all"
Requires-Dist: networkx>=2.0; extra == "all"
Requires-Dist: squarify>=0.4.0; extra == "all"
Requires-Dist: scipy>=1.6.0; extra == "all"
Requires-Dist: polars>=0.19.0; extra == "all"
Dynamic: license-file

# 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:
```python
import bottleviz as vz
vz.plot(df, x='column1', y='column2')  # All in one line!
```

vs. Matplotlib:
```python
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

```python
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

```python
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

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

### 5. **Seamless Dataframe Integration**
Works perfectly with pandas, polars, and more:
```python
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:
```python
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
```python
vz.plot(flow_data, kind='sankey', source='from', target='to', value='count')
```
*Requires: `networkx`*

**Sunburst Charts** - Hierarchical radial layouts
```python
vz.plot(hierarchy_data, kind='sunburst', path=['region', 'city'], value='sales')
```
*Optional: `squarify` for treemap variant*

**Treemaps** - Hierarchical rectangular layouts
```python
vz.plot(hierarchy_data, kind='treemap', path=['region', 'city'], value='sales')
```
*Requires: `squarify`*

**Network Graphs** - Visualize relationships and connections
```python
vz.plot(edges, kind='network', source='node1', target='node2', layout='spring')
```
*Requires: `networkx`*

**Candlestick Charts** - Financial OHLC time series
```python
vz.plot(stock_data, x='date', kind='candlestick', open='open', high='high', low='low', close='close')
```

**3D Visualizations** - Comprehensive 3D plotting suite
```python
# 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

```bash
# 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

```python
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:**
```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

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

#### `vz.create_custom_style(name, **kwargs)`
Create your own style.

```python
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
```python
# Automatic downsampling for >10k points
vz.plot(huge_df)  # Smooth even with 1M rows
```

### Smart Color Palettes
```python
# 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
```python
# Automatically arranges subplots
vz.visualize(df, max_plots=6)  # Smart 2x3 layout
```

### Pandas/Polars Integration
```python
# 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:
```bash
python -m bottleviz.examples
```

## Citation

If you use BottleViz in your research, please cite:

```bibtex
@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.**
