fmus-viz: A Human-Oriented Visualization Library

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

# 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

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.

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.

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.

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:

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

Testing

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

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

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.