VizzBreeze

A lightweight, high-performance transactional web-dashboard designed for advanced data flow analytics, multi-stage routing visualization, and statistical risk audit. Built natively on top of Streamlit, Pandas, and Plotly.

Key Features

• Flat Transaction Processing Engine: Optimized for fast processing of un-aggregated logs (e.g., Client ➔ Fund ➔ Asset).
• Global Session Synchronization: Seamlessly locks metric column selections, typography sizes, and alignments across all workspace views.
• Auto-Scroll Suppression: Enhanced layout architecture prevents viewport jumps during widget updates and data updates.
• Advanced Graph Matrix Analytics: Includes high-fidelity stacked charts, multi-dimensional Parcats layouts, Density Matrices, and automated IQR risk audit profiling tools.

Build With

1 - Plotly - Core interactive charting engine. 2 - Streamlit - Cloud infrastructure and web UI framework. 3 - Pandas - High-performance data structures and data analysis engine.

Quick Start

1. Standard Python / Jupyter Notebook Usage

VizzBreeze functions process un-aggregated raw DataFrames and return native Plotly figures, making them fully compatible with Jupyter views and pipeline automation:

import vizzbreeze as vb
import pandas as pd

# Load raw transaction logs
df = pd.read_csv("transactions.csv")

# Generate advanced Parcats flow directly in your notebook
fig = vb.generate_parcats(
    df=df, 
    stage_nodes=['client', 'fund'], 
    target_node='asset', 
    value_col='amount'
)
fig.show()

2. Standalone Web Control Room Execution

If you prefer a full-scale interactive UI with global layout sync, just open your local terminal and run:

vizzbreeze-run

Cloud Execution

If you explicitly need to run VizzBreeze in cloud environments like Google Colab, please use a secure SSH/Port-forwarding tunnel to bypass iframe infrastructure limits.

Test Dataset

To explore the dashboard features instantly, you can use the pre-configured spreadsheet sample_data_unaggregated.xlsx located in the root folder of this repository. Just drag and drop it into the sidebar upload zone!

Accessing Built-in Color Palettes

You don't need to hardcode HEX styles. Access the corporate design system directly from the package configuration:

import vizzbreeze as vb

# View all available palette names
print(vb.COLOR_PALETTES.keys())

# Extract a specific synchronized list of colors
chosen_colors = vb.COLOR_PALETTES["Warm Amber"]

Core Analytical Tabs

1. Flows: Explore multi-stage multi-dimensional category paths with thin, light axis labels and custom high-contrast hover tooltips.
2. Funnel: Track progressive conversion drops along specific workflow layers.
3. Structural Breakdown: Classic stacked column bar charts configured with responsive axis titles that update on the fly based on active filters.
4. Bento: An asymmetrical modular tile framework designed to compress complex multi-level dimensions into a clean, prioritized grid dashboard.
5. Density Matrix: High-density dashboard to scan cluster intersections instantly.
6. Anomaly & Risk Audit: Automated statistical anomaly profiling that detects process outliers without freezing the browser engine.

Core Functions API Reference & Parameter Mapping

All visualization engines are fully modular, accept un-aggregated raw pandas.DataFrame inputs, and return native plotly.graph_objects.Figure interactive objects.

1. Flows

fig = vb.generate_parcats(
    df=df,                          # pandas.DataFrame: Source transaction logs (un-aggregated)
    stage_nodes=['col1', 'col2'],   # list: Ordered column names defining the routing stages
    target_node='col3',             # str: The terminal endpoint column name
    value_col='amount',             # str: Volume metric column name (or "Number of rows (Sample size)")
    selected_palette=chosen_colors, # list/str: List of HEX codes or a built-in palette name string
    unit_divider=1.0,               # float: Optional division scaling factor (e.g., 1000 for Thousands)
    force_shuffle=False,            # bool/int: Seed integer to randomize color distribution maps
    chart_title="Flow Canvas",      # str: Custom graph header text
    title_size=20,                  # int: Font size of the chart title
    width_px=1050,                  # int: Holster canvas width (1050 fits Jupyter viewports perfectly)
    height_px=500,                  # int: Holster canvas height
    title_x=0.5                     # float: Header Alighnment
)
fig.update_layout(
    margin=dict(l=100, r=100, t=100, b=50)
    )
fig.show()

2. Funnel

fig = vb.generate_funnel_chart(
    df=df,
    stage_nodes=['col1', 'col2'],   # list: Sequence of progressive funnel workflow steps
    target_node='col3',             # str: Terminal checkpoint layer name
    value_col='amount',             # str: Volume metric target column
    selected_route_dict=route_dict, # dict: Active routing coordinate filters (e.g., {'col1': 'Client_1'})
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=False,
    chart_title="Pipeline Drops",
    width_px=1050,
    height_px=500,
    title_x=0.5                     
)
fig.update_layout(
    margin=dict(l=250, r=20, t=100, b=50)
    )
fig.show()

3. Structural Breakdown

fig = vb.generate_stacked_bar_chart(
    df=df,
    stage_nodes=['col1', 'col2'],   # list: Categories to aggregate and display on the horizontal X-axis
    target_node='col3',             # str: Legend segment categorical target breakdown
    value_col='amount',             # str: Numeric target volume metric
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=False,
    chart_title="Composition",
    width_px=1050,
    height_px=500,
    title_x=0.5 
)
fig.update_layout(
    margin=dict(l=100, r=20, t=50, b=50) 
)
fig.update_layout(
    yaxis=dict(
        title="", 
    )
fig.show()

4. Bento

fig = vb.generate_bento_treemap(
    df=df,
    id_col='target_dimension',      # str: Unique column name to rank and partition into tiles
    value_col='amount',             # str: Target numeric metric column name
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=False,
    chart_title="Bento Allocation Top-15", # Automatically truncates grid layout to Top 15 nodes
    width_px=1050,
    height_px=500,
    title_x=0.5 
)
fig.update_layout(
    margin=dict(l=50, r=20, t=50, b=50)
    )
fig.show()

5. Density Matrix

fig = vb.generate_heatmap(
    df=df,
    x_col='category_x',             # str: Categorical split column for horizontal partitions (X-Axis)
    y_col='category_y',             # str: Categorical split column for vertical partitions (Y-Axis)
    value_col='amount',             # str: Numeric target volume or "Number of rows (Sample size)"
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=False,
    chart_title="Density Matrix",
    show_annot=True,                # bool: Inject clean, non-zero numeric labels inside active cells
    width_px=1050,
    height_px=500,
    title_x=0.5 
)
fig.update_layout(
    margin=dict(l=100, r=20, t=50, b=50)
    )
fig.show()

6. Anomaly & Risk Audit

fig = vb.generate_outliers_chart(
    df=df,
    stage_col='origin_node',         # str: Operational source checkpoint step
    target_col='destination_node',   # str: Operational destination checkpoint step
    value_col='amount',              # str: Numeric target weight column to compute strict IQR bounds
    selected_palette=chosen_colors,
    unit_divider=1.0,
    force_shuffle=False,
    chart_title="Statistical Anomaly Profile", # Automatically plots a dashed line at Q3 + 1.5*IQR upper boundary
    width_px=1050,
    height_px=500,
    title_x=0.5 
)
fig.update_layout(
    margin=dict(l=170, r=20, t=50, b=70)
    )
fig.update_layout(
    yaxis=dict(
        title="", 
    )
)
fig.show()

Requirements

• Python >= 3.9
• Streamlit >= 1.35.0
• Pandas >= 2.1.0
• Plotly >= 5.18.0

Roadmap

• Advanced Data Preprocessing Pipeline: Implementing automated anomaly tracking and missing value imputation optimized for multi-source financial and operational data arrays.
• Interactive Risk Metrics: Adding features for deep data analysis, including volatility tracking, anomaly detection, and custom structural breakdown widgets.
• Large-Scale Data Engineering: Adding chunks-based data loading and optimization widgets to seamlessly process unaggregated corporate and industrial datasets exceeding 500MB.
• Enterprise Stability & Testing: Expanding code verification with an extensive pytest suite to achieve 85%+ test coverage for secure local CLI execution.

License

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