Visualization

uncertainty_flow.viz

Interactive visualization dashboard for uncertainty analysis.

launch_dashboard(model, data, target=None, port=8050, title=None)

Launch interactive Streamlit dashboard for uncertainty exploration.

Provides visualizations for calibration, prediction intervals, residual analysis, feature-uncertainty relationships, and more.

Parameters

model : BaseUncertaintyModel Fitted uncertainty model with predict() method data : pl.DataFrame Dataset for analysis (features + target) target : str, optional Target column name. If None, will be inferred from model port : int, default=8050 Port for Streamlit server title : str, optional Dashboard title. If None, uses model name

Examples

import polars as pl from uncertainty_flow.models import QuantileForestForecaster from uncertainty_flow.viz import launch_dashboard

model = QuantileForestForecaster(targets="demand", horizon=7) model.fit(train_data)

Launch dashboard

launch_dashboard(model, test_data, port=8050)

Notes

Requires streamlit as an optional dependency: pip install uncertainty-flow[ml]

The dashboard includes

• Calibration curves (coverage vs. confidence)
• Interval width distribution
• Residual analysis plots
• Feature-uncertainty relationships
• Time series fan charts
• Leverage analysis reports

Source code in uncertainty_flow/viz/dashboard.py

def launch_dashboard(
    model: "BaseUncertaintyModel",
    data: pl.DataFrame,
    target: str | None = None,
    port: int = 8050,
    title: str | None = None,
) -> None:
    """
    Launch interactive Streamlit dashboard for uncertainty exploration.

    Provides visualizations for calibration, prediction intervals,
    residual analysis, feature-uncertainty relationships, and more.

    Parameters
    ----------
    model : BaseUncertaintyModel
        Fitted uncertainty model with predict() method
    data : pl.DataFrame
        Dataset for analysis (features + target)
    target : str, optional
        Target column name. If None, will be inferred from model
    port : int, default=8050
        Port for Streamlit server
    title : str, optional
        Dashboard title. If None, uses model name

    Examples
    --------
    >>> import polars as pl
    >>> from uncertainty_flow.models import QuantileForestForecaster
    >>> from uncertainty_flow.viz import launch_dashboard
    >>>
    >>> model = QuantileForestForecaster(targets="demand", horizon=7)
    >>> model.fit(train_data)
    >>>
    >>> # Launch dashboard
    >>> launch_dashboard(model, test_data, port=8050)

    Notes
    -----
    Requires streamlit as an optional dependency:
        pip install uncertainty-flow[ml]

    The dashboard includes:
        - Calibration curves (coverage vs. confidence)
        - Interval width distribution
        - Residual analysis plots
        - Feature-uncertainty relationships
        - Time series fan charts
        - Leverage analysis reports
    """
    if model is None:
        raise ValueError("model is required")
    if data.is_empty():
        raise ValueError("data must contain at least one row")

    try:
        import streamlit as st
    except ImportError:
        raise ImportError(
            "streamlit is required for the dashboard. Install with: pip install streamlit"
        )

    # Set page config
    if title is None:
        title = f"Uncertainty Analysis Dashboard - {model.__class__.__name__}"

    st.set_page_config(
        page_title="Uncertainty Analysis",
        layout="wide",
        initial_sidebar_state="expanded",
    )

    st.title(title)

    # Sidebar controls
    st.sidebar.header("Configuration")

    # Confidence level slider
    confidence = st.sidebar.slider(
        "Confidence Level",
        min_value=0.5,
        max_value=0.99,
        value=0.9,
        step=0.01,
        help="Confidence level for prediction intervals",
    )

    # Sample size for plots
    max_samples = st.sidebar.slider(
        "Max Samples for Plots",
        min_value=50,
        max_value=5000,
        value=1000,
        step=50,
        help="Maximum number of samples to display in plots",
    )

    # Infer target if not provided
    if target is None and hasattr(model, "_targets"):
        targets = model._targets
        if targets and len(targets) == 1:
            target = targets[0]

    if target is None:
        st.error("Could not infer target column. Please specify 'target' parameter.")
        return

    # Separate features and target
    feature_cols = [col for col in data.columns if col != target]
    features = data.select(feature_cols)
    y_true = data[target]

    # Downsample if needed
    if len(features) > max_samples:
        indices = np.linspace(0, len(features) - 1, max_samples, dtype=int)
        features = features[indices]
        y_true = y_true[indices]

    # Generate predictions
    with st.spinner("Generating predictions..."):
        predictions = model.predict(features)

    # Main content tabs
    tab1, tab2, tab3, tab4, tab5 = st.tabs(
        ["Calibration", "Intervals", "Residuals", "Feature Analysis", "Summary"]
    )

    with tab1:
        _render_calibration_tab(predictions, y_true, confidence)

    with tab2:
        _render_intervals_tab(predictions, y_true, confidence)

    with tab3:
        _render_residuals_tab(predictions, y_true, features, confidence)

    with tab4:
        _render_feature_analysis_tab(predictions, y_true, features, confidence)

    with tab5:
        _render_summary_tab(model, predictions, y_true, confidence)