IPython Magic Commands

Dashboard Lego provides IPython magic commands for ultra-fast dashboard creation and Plotly figure export directly from Jupyter notebooks.

Installation

First, load the extension in your Jupyter notebook:

%load_ext dashboard_lego.ipython_magics

Dashboard Creation

Quick Dashboard from DataFrame

Create dashboards from DataFrame variables with minimal code:

# Load data
import pandas as pd
df = pd.read_csv('sales_data.csv')

# Create dashboard with metrics and charts
%dashboard df
  title: "Sales Dashboard"
  theme: lux
  cards:
    - type: metric
      metric_spec:
        column: Sales
        agg: sum
        title: "Total Sales"
        color: success
    - type: metric
      metric_spec:
        column: Profit
        agg: sum
        title: "Total Profit"
        color: info
    - type: chart
      plot_type: bar
      plot_params: {x: Product, y: Sales}
      title: "Sales by Product"
    - type: chart
      plot_type: line
      plot_params: {x: Date, y: Sales}
      title: "Sales Trend"
    - type: text
      content_generator: |
        ## Summary

        Key insights from the data

# Simple single chart dashboard
%dashboard df
  cards:
    - type: chart
      plot_type: scatter
      plot_params: {x: Price, y: Sales}
      title: "Price vs Sales"

Configuration Keys:

• dataframe: Name of DataFrame variable (required)

• title: Dashboard title

• theme: Theme name (uses current preference if not specified)

• port: Server port (default: 8050)

• environment: List of variable names to import from IPython namespace

• cards: List of card specifications with optional controls

Card Types (YAML = kwargs + type): - Metric: type: metric, metric_spec: {column, agg, title, [color], [dtype]} - Chart: type: chart, plot_type: str, plot_params: {x, y, [color], [size]}, title: str, optional controls - Minimal Chart: type: minimal_chart, plot_params: {x, y, ...}, optional plot_type (defaults to scatter), optional controls - Text: type: text, content_generator: callable (returns str or Component) - Control Panel: type: control_panel, title: str, controls: [...]

Note

YAML for magics MUST match block constructor kwargs (plus type). No legacy top-level x/y or column/agg/title. Use metric_spec, plot_params, and content_generator exactly as in the Python API.

Control Types: - Dropdown: name, type: dropdown, options, value, col_props - Slider: name, type: slider, min, max, step, value, marks - Input: name, type: input, input_type, placeholder, value

Environment Variables: - Use $variable_name syntax to reference variables from IPython namespace - Variables must be declared in environment list for security

Available themes: lux, dark, light, cyborg, slate, solar, superhero, minty, flatly, cosmo, cerulean, journal, litera, lumen, pulse, sandstone, simplex, sketchy, spacelab, united, yeti

Cell Magic Dashboard

Create dashboards using YAML configuration in notebook cells with support for controls and environment variables:

%%dashboard_cell
dataframe: df
title: "Sales Dashboard"
theme: lux
environment:
  - metric_options
  - color_palette
cards:
  - type: metric
    metric_spec:
      column: Sales
      agg: sum
      title: "Total Sales"
      color: success
  - type: chart
    plot_type: scatter
    plot_params: {x: Product, y: Sales}
    title: "Sales Analysis"
    controls:
      - name: metric_selector
        type: dropdown
        options: $metric_options
        value: "Sales"
        col_props: {xs: 12, md: 6}
      - name: year_slider
        type: slider
        min: 2020
        max: 2024
        step: 1
        value: 2023
        marks: {2020: "2020", 2024: "2024"}
        col_props: {xs: 12, md: 6}
  - type: text
    content_generator: |
      ## Summary

      Key insights from the data:
      - Sales increased by 15% this quarter
      - Top performing product is Electronics

Understanding Control Bindings

How Controls Wire Together (NEW)

Controls define what gets controlled through state identifiers. Here’s how it works:

1. Control Panel Publishes State

When you define a ControlPanelBlock with controls, each control publishes its value as a state:

ControlPanelBlock(
    block_id="filters",  # ← This becomes part of state ID
    title="Filters",
    controls={
        "category": Control(...),  # ← State ID: "filters-category"
        "price": Control(...)      # ← State ID: "filters-price"
    }
)

State ID formula: {block_id}-{control_name}

Examples: - filters-category - filters-price - session_controls-duration

2. Chart/Metric Subscribes to State

Other blocks subscribe to these state IDs using subscribes_to:

TypedChartBlock(
    block_id="sales_chart",
    plot_type="bar",
    plot_params={"x": "Product", "y": "Sales"},
    subscribes_to="filters-category"  # ← Subscribe to control panel state
)

3. State Changes Trigger Updates

When user changes control value → state updates → all subscribers re-render

YAML Example: Control Panel with Chart

Here’s a complete example showing how controls bind to charts:

%%dashboard_cell
dataframe: df
title: "Interactive Dashboard"
cards:
  # STEP 1: Define control panel
  - type: control_panel
    title: "Filters"
    controls:
      - name: category
        type: dropdown
        options:
          - {label: "Electronics", value: "Electronics"}
          - {label: "Furniture", value: "Furniture"}
          - {label: "Office Supplies", value: "Supplies"}
        value: "Electronics"
      - name: min_price
        type: slider
        min: 0
        max: 1000
        value: 100

  # STEP 2: Chart subscribes to control panel states
  - type: chart
    plot_type: scatter
    plot_params: {x: Product, y: Sales}
    title: "Sales by Category"
    # Subscribe to BOTH controls
    subscribes_to:
      - "control_panel-category"    # Listens to category dropdown
      - "control_panel-min_price"   # Listens to price slider

What Happens:

1. Control panel block_id is automatically control_panel in cell magic

2. Control names become state suffixes: control_panel-category, control_panel-min_price

3. Chart subscribes to these states

4. When dropdown changes → state control_panel-category updates → chart re-renders

5. When slider changes → state control_panel-min_price updates → chart re-renders

Multiple Charts from One Control Panel

%%dashboard_cell
dataframe: df
cards:
  # Single control panel
  - type: control_panel
    title: "Filters"
    controls:
      - name: region
        type: dropdown
        options: $region_list
        value: "North America"

  # Chart 1 subscribes
  - type: chart
    plot_type: bar
    plot_params: {x: Product, y: Revenue}
    subscribes_to: "control_panel-region"

  # Chart 2 subscribes to SAME control
  - type: chart
    plot_type: line
    plot_params: {x: Month, y: Profit}
    subscribes_to: "control_panel-region"

Result: Changing region filter updates both charts

Advanced: Chart with Embedded Controls

Charts can have their own internal controls that don’t affect other blocks:

- type: chart
  plot_type: histogram
  plot_params: {x: Price}
  title: "Price Distribution"
  # These are chart-local controls (don't publish state)
  controls:
    - name: x_col
      type: dropdown
      options:
        - {label: "Price", value: "Price"}
        - {label: "Quantity", value: "Quantity"}
      value: "Price"

Key Difference: - Control Panel controls → publish state → can control other blocks - Chart embedded controls → private to chart → don’t affect other blocks

Dynamic Marker Size Configuration

For scatter plots with variable marker sizes, you can configure consistent pixel-based sizing that adapts to your data range:

- type: chart
  plot_type: scatter_minimal
  plot_params: {x: session_length, y: max_idle, size: "{{metric_selector_2}}"}
  plot_kwargs:
    marker_size_max_px: 42
    marker_size_min_px: 8

Configuration: - marker_size_max_px: Maximum marker size in pixels (largest data point) - marker_size_min_px: Minimum marker size in pixels (smallest data point)

How it works: - Uses Plotly’s sizeref formula to normalize marker sizes relative to current data range - Automatically adapts when filters change the underlying data - Ensures consistent visual scaling regardless of data distribution - No modification of underlying DataFrame values

State ID Anatomy

Understanding state ID structure is key:

State ID: "my_filters-category"
          └────┬────┘  └──┬──┘
          block_id    control_name

Subscribe: subscribes_to: "my_filters-category"
Result: Block listens to that control panel's category control

Explicit Parameter Naming with dep_param_name

By default, when a chart subscribes to external controls, the parameter name sent to the datasource is auto-parsed from the control name. For example, subscribing to "quick_card_1-window_step_selector" would send parameter window_step_selector to the datasource.

To explicitly control the parameter name sent to the datasource, use dep_param_name:

%%dashboard_cell
datasource: my_datasource
cards:
  # Control panel with slider
  - type: control_panel
    title: "Select Step"
    controls:
      - name: window_step_selector
        type: slider
        min: 1
        max: 5
        value: 1

  # Chart with explicit dep_param_name
  - type: chart
    plot_type: scatter  # YAML x/y are adapted to plot_params internally
    x: session_length
    y: max_idle
    title: "Session Analysis"
    subscribes_to:
      - state_id: "quick_card_1-window_step_selector"
        dep_param_name: "window_step"  # ← Explicit datasource param name

What happens:

1. User changes slider → state quick_card_1-window_step_selector = 3

2. Chart receives update with {"quick_card_1-window_step_selector": 3}

3. dep_param_name remaps this to {"window_step": 3} for datasource

4. Datasource receives datasource.get_processed_data({"window_step": 3})

Without dep_param_name (legacy):

subscribes_to:
  - "quick_card_1-window_step_selector"  # Auto-parses to "window_step_selector"

With dep_param_name (explicit):

subscribes_to:
  - state_id: "quick_card_1-window_step_selector"
    dep_param_name: "window_step"  # Explicitly "window_step"

Use Cases:

• Your datasource expects window_step but control is named window_step_selector

• Multiple controls map to same datasource parameter

• Legacy datasources with specific parameter names

• Cleaner API when control names don’t match datasource parameters

Practical Workflow

Step 1: Define control panel with block_id

- type: control_panel
  block_id: "filters"          # Optional, auto-generated if omitted
  title: "Dashboard Filters"
  controls:
    - name: category
      type: dropdown
      options: ["A", "B", "C"]

Step 2: Note the state IDs produced

• filters-category ← This is what other blocks subscribe to

Step 3: Charts subscribe

- type: chart
  plot_type: bar
  plot_params: {x: Product, y: Sales}
  subscribes_to: "filters-category"  # Now this chart listens to control changes

Result: User changes dropdown → chart updates automatically

Theme Management

Set default theme for future dashboards:

# Set theme
%dashboard_theme cyborg

# View current theme and available options
%dashboard_theme

Plotly Export

Export Figures to Files

Export Plotly figures from dashboard blocks:

# Export as HTML with custom title
%plotly_export chart_block
  format: html
  output: sales_chart.html
  title: "Sales Analysis"

# Export as PNG image with custom dimensions
%plotly_export chart_block
  format: png
  output: chart.png
  width: 1000
  height: 800

# Export as JSON
%plotly_export chart_block
  format: json
  output: data.json

# Export with parameters for interactive controls
%plotly_export histogram
  format: html
  output: distribution.html
  params:
    x_col: "Price"
    group_by: "Category"

Configuration Keys:

• block: Name of dashboard block variable (required)

• format: Export format (html, png, json, svg)

• output: Output file path (required)

• title: Figure title (for HTML)

• width: Figure width (for images)

• height: Figure height (for images)

• params: JSON parameters for block.get_figure()

Display in Notebook

Display figures inline in Jupyter notebooks:

# Show figure with custom size and title
%plotly_show chart_block
  title: "Interactive Chart"
  width: 900
  height: 600

# Show with parameters for interactive controls
%plotly_show histogram
  params:
    x_col: "Price"
    group_by: "Category"

Batch Export

Export multiple figures using cell magic:

%%plotly_export
exports:
  - block: sales_chart
    format: html
    output: sales_report.html
    title: "Sales Analysis"
  - block: profit_chart
    format: png
    output: profit_analysis.png
    width: 1200
    height: 800

Examples

Complete Workflow Example with Controls:

# Load extension
%load_ext dashboard_lego.ipython_magics

# Load data and prepare variables
import pandas as pd
df = pd.read_csv('data.csv')

# Prepare environment variables
metric_options = [
    {"label": "Sales", "value": "sales"},
    {"label": "Profit", "value": "profit"},
    {"label": "Revenue", "value": "revenue"}
]

color_palette = ["#1f77b4", "#ff7f0e", "#2ca02c", "#d62728"]

# Create dashboard with controls
%%dashboard_cell
dataframe: df
title: "Interactive Sales Dashboard"
theme: lux
environment:
  - metric_options
  - color_palette
cards:
  - type: metric
    metric_spec:
      column: Sales
      agg: sum
      title: "Total Sales"
      color: success
  - type: chart
    plot_type: scatter
    plot_params: {x: Product, y: Sales}
    title: "Sales Analysis"
    controls:
      - name: metric_selector
        type: dropdown
        options: $metric_options
        value: "sales"
        col_props: {xs: 12, md: 6}
      - name: year_slider
        type: slider
        min: 2020
        max: 2024
        step: 1
        value: 2023
        marks: {2020: "2020", 2024: "2024"}
        col_props: {xs: 12, md: 6}

# Export charts
%plotly_export sales_chart
  format: html
  output: dashboard_export.html
  title: "Sales Dashboard Export"

# Display in notebook
%plotly_show sales_chart
  title: "Interactive Sales Chart"

Common Patterns

Quick Analysis with Controls:

# Prepare environment
metric_options = [{"label": "Sales", "value": "sales"}, {"label": "Profit", "value": "profit"}]

%%dashboard_cell
dataframe: df
environment:
  - metric_options
cards:
  - type: metric
    metric_spec:
      column: col1
      agg: mean
      title: "Average"
  - type: chart
    plot_type: histogram
    plot_params: {x: col1}
    title: "Distribution"
    controls:
      - name: metric_selector
        type: dropdown
        options: $metric_options
        value: "sales"

Interactive Parameter Exploration:

# Hyperparameter playground example
session_params = {
    'session_length': [10, 15, 20, 25, 30],
    'max_idle': [600, 900, 1800, 3600, 7200],
    'window_step': [3, 5, 7, 10]
}

%%dashboard_cell
dataframe: session_hp_datasource
title: "Session Hyperparameters Playground"
environment:
  - session_params
  - metric_options
cards:
  - type: chart
    plot_type: scatter
    plot_params: {x: session_length, y: max_idle}
    title: "Session Length vs Max Idle"
    controls:
      - name: metric_selector
        type: dropdown
        options: $metric_options
        value: "n_sessions"
      - name: window_step_slider
        type: slider
        min: 3
        max: 10
        step: 1
        value: 5

Report Generation:

%plotly_export analysis_chart
  format: html
  output: report.html
  title: "Analysis Results"

%plotly_export summary_chart
  format: png
  output: summary.png
  width: 800
  height: 400

Interactive Exploration:

%plotly_show chart
  title: "Interactive View"
# Now you can interact with the chart in the notebook

Troubleshooting

Block not found: Ensure the block variable exists in the notebook namespace

Export fails: Check file permissions and disk space

Display issues: Ensure plotly is properly installed and configured for Jupyter

Theme not applied: Use %dashboard_theme to set default theme before creating dashboards

Error Messages

• ❌ Error: Block variable 'X' not found - Variable doesn’t exist in namespace

• ❌ Error: Block 'X' does not support figure export - Block doesn’t have get_figure() method

• ❌ Error: --output/-o is required - Output file path not specified

• ❌ Error: Environment variable 'X' not found - Variable not declared in environment list

• ❌ Error: Invalid YAML format - YAML syntax error in cell configuration

• ❌ Error: Control 'X': unknown type 'Y' - Unsupported control type (use dropdown, slider, input)

• ❌ Error: Variable '$X' not found in environment - Referenced variable not in environment list