Metadata-Version: 2.4
Name: fmus-viz
Version: 0.1.0
Summary: A human-oriented visualization library with unified interface across multiple backends
Author-email: Yusef Ulum <yusef314159@gmail.com>
License: MIT
Project-URL: Documentation, https://fmus-viz.readthedocs.io
Project-URL: Source, https://github.com/mexyusef/fmus-viz
Project-URL: Issues, https://github.com/mexyusef/fmus-viz/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Provides-Extra: matplotlib
Requires-Dist: matplotlib>=3.5.0; extra == "matplotlib"
Provides-Extra: plotly
Requires-Dist: plotly>=5.5.0; extra == "plotly"
Provides-Extra: seaborn
Requires-Dist: seaborn>=0.11.0; extra == "seaborn"
Provides-Extra: bokeh
Requires-Dist: bokeh>=2.4.0; extra == "bokeh"
Provides-Extra: altair
Requires-Dist: altair>=4.2.0; extra == "altair"
Provides-Extra: networkx
Requires-Dist: networkx>=2.7.0; extra == "networkx"
Requires-Dist: pyvis>=0.2.0; extra == "networkx"
Provides-Extra: folium
Requires-Dist: folium>=0.12.0; extra == "folium"
Requires-Dist: geojson>=2.5.0; extra == "folium"
Provides-Extra: holoviews
Requires-Dist: holoviews>=1.14.0; extra == "holoviews"
Requires-Dist: datashader>=0.13.0; extra == "holoviews"
Provides-Extra: all
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: plotly>=5.5.0; extra == "all"
Requires-Dist: seaborn>=0.11.0; extra == "all"
Requires-Dist: bokeh>=2.4.0; extra == "all"
Requires-Dist: altair>=4.2.0; extra == "all"
Requires-Dist: networkx>=2.7.0; extra == "all"
Requires-Dist: pyvis>=0.2.0; extra == "all"
Requires-Dist: folium>=0.12.0; extra == "all"
Requires-Dist: geojson>=2.5.0; extra == "all"
Requires-Dist: holoviews>=1.14.0; extra == "all"
Requires-Dist: datashader>=0.13.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: black>=22.3.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: sphinx>=4.5.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.18.0; extra == "dev"
Dynamic: license-file

# fmus-viz: A Human-Oriented Visualization Library

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

fmus-viz is a human-oriented visualization library that provides a unified interface across multiple backend visualization engines. It focuses on intuitive API design, smart defaults, and a great developer experience.

## Features

- **Unified Interface**: A single API that works with multiple visualization backends
- **Human-Oriented Design**: Intuitive and memorable function names and parameters
- **Smart Defaults**: Sensible defaults that "just work" for most use cases
- **Backend Flexibility**: Switch between Matplotlib, Plotly, and Seaborn seamlessly
- **Method Chaining**: Fluent interface for customizing visualizations
- **Rich Visualization Types**: Basic charts and statistical visualizations

## Installation

```bash
# Basic installation with minimal dependencies
pip install fmus-viz

# Install with specific backend support
pip install fmus-viz[matplotlib]
pip install fmus-viz[plotly]

# Install with all backends
pip install fmus-viz[all]
```

## Quick Start

```python
import fmus_viz as viz
import pandas as pd
import numpy as np

# Create sample data
data = pd.DataFrame({
    'category': ['A', 'B', 'C', 'D', 'E'],
    'value': [10, 15, 7, 12, 9]
})

# Basic bar chart
viz.bar(data, x='category', y='value').show()

# Switch to Plotly backend for interactive plots
viz.set_backend('plotly')
viz.line(data, x='category', y='value').title('Category Values').show()

# Method chaining for customization
viz.scatter(data, x='category', y='value')\
   .color('blue')\
   .title('Scatter Plot Example')\
   .xlabel('Categories')\
   .ylabel('Values')\
   .show()

# Statistical visualizations
grouped_data = pd.DataFrame({
    'category': ['A', 'B', 'C'] * 100,
    'value': np.random.randn(300) * 10 + 50
})

viz.boxplot(grouped_data, x='category', y='value').show()

# Correlation matrix
corr_data = pd.DataFrame(np.random.rand(50, 4), columns=['a', 'b', 'c', 'd'])
viz.corr(corr_data, annot=True).show()
```

## Available Backends

### Matplotlib Backend (Default)
Static visualizations with high-quality output for scientific and publication-ready figures.

```python
import fmus_viz as viz
viz.set_backend('matplotlib')
viz.bar(data, x='category', y='value')
```

### Plotly Backend
Interactive visualizations with dynamic features like zoom, pan, and hover tooltips. Ideal for dashboards and web applications.

```python
import fmus_viz as viz
viz.set_backend('plotly')
viz.scatter(data, x='x', y='y', title='Interactive Scatter Plot')
```

### Seaborn Backend
Statistical visualizations with beautiful default styling built on top of Matplotlib.

```python
import fmus_viz as viz
viz.set_backend('seaborn')
viz.boxplot(data, x='category', y='value')
```

## Supported Chart Types

### Basic Charts
- `bar()` - Vertical bar chart
- `barh()` - Horizontal bar chart
- `line()` - Line chart
- `scatter()` - Scatter plot
- `histogram()` - Histogram
- `pie()` - Pie chart
- `area()` - Area chart

### Statistical Charts
- `boxplot()` - Box plot with optional grouping
- `violin()` - Violin plot
- `heatmap()` - 2D heatmap
- `corr()` - Correlation matrix heatmap
- `density()` - Kernel density estimation (1D/2D)
- `regression()` - Linear regression with confidence interval

## Backend Status

| Backend | Status | Charts |
|---------|--------|--------|
| Matplotlib | ✅ Implemented | All basic + statistical |
| Plotly | ✅ Implemented | All basic + statistical |
| Seaborn | ✅ Implemented | All basic + statistical |

## Planned Features

Future releases will include:
- **Geospatial**: map, choropleth
- **Network**: graph, tree
- **3D**: surface, scatter3d
- **Additional Backends**: Bokeh, Altair

## Examples

The `examples/` directory contains scripts demonstrating different features:

```bash
# Run verification to test all features
python examples/verify_implementation.py

# Basic charts example
python examples/basic_charts.py

# Plotly interactive features
python examples/plotly_interactive_features.py

# Plotly example
python examples/plotly_example.py
```

## Documentation

Full documentation is available at [https://fmus-viz.readthedocs.io](https://fmus-viz.readthedocs.io).

## Testing

The project includes a comprehensive test suite with 180+ tests covering all functionality:

```bash
# Run all tests
pytest tests/ -v

# Run specific test modules
pytest tests/test_api/test_statistical.py -v
pytest tests/test_backends/test_matplotlib.py -v

# Run with coverage
pytest tests/ --cov=fmus_viz --cov-report=html
```

## Verification

Run the verification script to test all features:

```bash
python examples/verify_implementation.py
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.
