bottleviz 0.1.0__tar.gz

bottleviz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DHS
+
+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.

bottleviz-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include tests *
+recursive-include examples *
+recursive-include docs *
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude .DS_Store
+prune .git
+prune .venv
+prune venv

bottleviz-0.1.0/PKG-INFO

@@ -0,0 +1,536 @@
+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.**