fmus-viz 0.1.0
A human-oriented visualization library with unified interface across multiple backends
License: MIT
Requires Python: >=3.8

# 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.