Dashboard YAML Management¶

Depictio supports managing dashboards as human-readable YAML files using the depictio-cli command-line tool. This enables Infrastructure-as-Code (IaC) workflows, version control integration, and reproducible dashboard deployments.

Implementation Reference

The DashboardDataLite model and CLI dashboard commands were introduced in PR #663. Domain validation (enum constraints, cross-field rules, server schema checks) was added in PR #684.

Overview¶

┌─────────────────┐                        ┌─────────────────┐
│   YAML Files    │  depictio-cli import   │    MongoDB      │
│   (version      │ ─────────────────────▶ │   Dashboard     │
│    controlled)  │                        │                 │
│                 │  depictio-cli export   │                 │
│                 │ ◀───────────────────── │                 │
└─────────────────┘                        └─────────────────┘

Key Benefits:

Version Control: Track dashboard changes in Git with meaningful diffs
Infrastructure-as-Code: Manage dashboards alongside your project configuration
Human-Readable Format: Edit dashboards directly in YAML (60-80 lines vs 500+ in MongoDB)
Reproducible Deployments: Import dashboards to any Depictio instance
Early Validation: Catch invalid field values and incompatible combinations before importing

CLI Commands¶

The depictio-cli dashboard command group provides three commands for YAML management:

Command	Description	Server Required
`validate`	Validate YAML (schema + server schema)	Optional (for Pass 2)
`import`	Import YAML to server	Yes (unless `--dry-run`)
`export`	Export dashboard to YAML	Yes

Validate¶

Validate a dashboard YAML file. Runs in two passes:

Pass 1 — schema + domain (always, no server required): checks required fields, enum values (visu_type, column_type), and cross-field rules (aggregation × column_type, interactive_type × column_type, mode/code_content).
Pass 2 — server schema (default when --config is provided): resolves each component's workflow_tag + data_collection_tag against the live delta table schema, checks that column_name exists, and validates aggregation/interactive type against the inferred column type. Skip with --offline.

depictio-cli dashboard validate <yaml_file> [OPTIONS]

Option	Description
`--config`, `-c`	Path to CLI config file (enables server schema validation — Pass 2)
`--offline`	Skip server schema check (Pass 1 only — useful without server access)
`--verbose`, `-v`	Show detailed validation output
`--api`	API base URL (default: from config)

Examples:

# Schema + domain only (no server needed)
depictio-cli dashboard validate my_dashboard.yaml

# Full validation including server column check
depictio-cli dashboard validate my_dashboard.yaml --config ~/.depictio/admin_config.yaml

# Force offline even when config is provided
depictio-cli dashboard validate my_dashboard.yaml --config ~/.depictio/admin_config.yaml --offline

Example Output (all passes OK):

Validating: my_dashboard.yaml
  Pass 1: schema + domain constraints
  ✓ Schema + domain OK
  Pass 2: server schema validation
  ✓ Server schema OK

✓ Validation passed

Example Output (domain error — invalid visu_type):

Validating: my_dashboard.yaml
  Pass 1: schema + domain constraints
✗ Schema/domain validation failed
                         Validation Errors
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Component     ┃ Field     ┃ Message                                            ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ pie-chart     │ -         │ Invalid visu_type 'pie' for mode='ui'.             │
│               │           │ Valid values: scatter, line, bar, box, histogram   │
│ treemap-chart │ -         │ Invalid visu_type 'treemap' for mode='ui'.         │
│               │           │ Valid values: scatter, line, bar, box, histogram   │
└───────────────┴───────────┴────────────────────────────────────────────────────┘

Import¶

Import a dashboard YAML file to the server. Always runs schema + domain validation first (Pass 1). Also runs server schema validation by default (Pass 2) — skip with --offline.

depictio-cli dashboard import <yaml_file> [OPTIONS]

Option	Description
`--config`, `-c`	Path to CLI config file (required unless `--dry-run`)
`--project`, `-p`	Project ID (overrides `project_tag` in YAML)
`--overwrite`	Update existing dashboard with same title
`--dry-run`	Validate schema + domain only, don't import (no server needed)
`--offline`	Skip server schema check (column names not verified)
`--api`	API base URL (default: from config)

Validation before import

dashboard import always validates your YAML before sending it to the server. A failed validation aborts the import — you never import a dashboard that fails schema or domain checks.

Examples:

# Schema + domain validation only (no config, no import)
depictio-cli dashboard import dashboard.yaml --dry-run

# Full validation + import (server schema check runs by default)
depictio-cli dashboard import dashboard.yaml --config ~/.depictio/admin_config.yaml

# Import without server schema check
depictio-cli dashboard import dashboard.yaml --config ~/.depictio/admin_config.yaml --offline

# Update existing dashboard with same title
depictio-cli dashboard import dashboard.yaml --config ~/.depictio/admin_config.yaml --overwrite

# Override project from YAML
depictio-cli dashboard import dashboard.yaml --config ~/.depictio/admin_config.yaml --project 646b0f3c1e4a2d7f8e5b8c9a

Example Output:

Validating: dashboard.yaml
✓ Validation passed
  Title: Iris Dashboard Demo
  Components: 7
  Project: Iris_Dataset_Project (from YAML project_tag)

Loading CLI configuration...
✓ Configuration loaded
  API URL: localhost:8058

Importing dashboard (project: Iris_Dataset_Project)...
✓ Dashboard imported successfully!
  Dashboard ID: 6824cb3b89d2b72169309737
  Title: Iris Dashboard Demo
  Project ID: 650a1b2c3d4e5f6a7b8c9d0e

View at: localhost:8058/dashboard/6824cb3b89d2b72169309737

Export¶

Export a dashboard from the server to a YAML file.

depictio-cli dashboard export <dashboard_id> [OPTIONS]

Option	Description
`--config`, `-c`	Path to CLI config file (required)
`--output`, `-o`	Output file path (default: `dashboard.yaml`)
`--api`	API base URL (default: from config)

Examples:

# Export to default file
depictio-cli dashboard export 6824cb3b89d2b72169309737 --config ~/.depictio/admin_config.yaml

# Export to specific file
depictio-cli dashboard export 6824cb3b89d2b72169309737 --config ~/.depictio/admin_config.yaml -o iris_dashboard.yaml

YAML Format¶

DashboardDataLite Structure¶

The lite format is designed for human readability:

title: Dashboard Title
subtitle: Optional subtitle
project_tag: Project_Name

components:
  - tag: component-identifier
    component_type: figure|card|interactive|table|image|multiqc
    workflow_tag: engine/workflow_name
    data_collection_tag: dc_tag
    # Component-specific fields...

Complete Example¶

title: Iris Dashboard Demo
subtitle: Sample analysis dashboard
project_tag: Iris_Dataset_Project

components:
  # Figure: Box plot
  - tag: box-variety-sepal-length
    component_type: figure
    workflow_tag: python/iris_workflow
    data_collection_tag: iris_table
    visu_type: box
    dict_kwargs:
      x: variety
      y: sepal.length
      color: variety
      title: Sepal Length by Variety

  # Figure: Scatter plot
  - tag: scatter-sepal-petal
    component_type: figure
    workflow_tag: python/iris_workflow
    data_collection_tag: iris_table
    visu_type: scatter
    dict_kwargs:
      x: sepal.length
      y: petal.length
      color: variety

  # Card: Metric with aggregation
  - tag: sepal-length-average
    component_type: card
    workflow_tag: python/iris_workflow
    data_collection_tag: iris_table
    aggregation: average
    column_name: sepal.length
    icon_name: mdi:leaf
    icon_color: "#8BC34A"

  # Interactive: MultiSelect filter
  - tag: variety-filter
    component_type: interactive
    workflow_tag: python/iris_workflow
    data_collection_tag: iris_table
    interactive_component_type: MultiSelect
    column_name: variety
    custom_color: "#858585"

  # Interactive: RangeSlider filter
  - tag: sepal-length-filter
    component_type: interactive
    workflow_tag: python/iris_workflow
    data_collection_tag: iris_table
    interactive_component_type: RangeSlider
    column_name: sepal.length

  # Table: Data display
  - tag: data-table
    component_type: table
    workflow_tag: python/iris_workflow
    data_collection_tag: iris_table

  # Image: Gallery component
  - tag: sample-gallery
    component_type: image
    workflow_tag: python/image_workflow
    data_collection_tag: sample_images
    image_column: image_path
    thumbnail_size: 150
    columns: 3
    max_images: 9

  # MultiQC: Quality control report
  - tag: fastqc-quality
    component_type: multiqc
    workflow_tag: python/nf_workflow
    data_collection_tag: multiqc_report
    selected_module: fastqc
    selected_plot: per_base_sequence_quality

Component Types Reference¶

Type	Description	Required Fields
`figure`	Plotly charts (scatter, box, histogram, etc.)	`visu_type` (ui mode) or `code_content` (code mode)
`card`	Metric cards with aggregations	`aggregation`, `column_name`
`interactive`	Filters (RangeSlider, MultiSelect, etc.)	`interactive_component_type`, `column_name`
`table`	Data tables	(none beyond base fields)
`image`	Image galleries from S3/MinIO	`image_column`
`multiqc`	MultiQC quality control report viewer	`selected_module`, `selected_plot`

Figure Component¶

Two rendering modes are supported:

UI Mode (default) — select a chart type and pass Plotly Express parameters:

- tag: scatter-plot
  component_type: figure
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  visu_type: scatter       # see valid values below
  dict_kwargs:
    x: column_x
    y: column_y
    color: category_column
    title: Chart Title

Valid visu_type values (UI mode): scatter, line, bar, box, histogram

Code Mode — write arbitrary Python/Plotly code for full flexibility:

- tag: custom-plot
  component_type: figure
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  mode: code
  code_content: |
    import plotly.express as px
    fig = px.scatter_matrix(df, dimensions=["sepal.length", "sepal.width", "petal.length"])

Code mode and visu_type

visu_type is not validated when mode: code. Any Plotly chart can be built in code mode. code_content must be non-empty when mode: code.

Selection filtering — enable lasso/box selection to filter linked components:

- tag: scatter-with-selection
  component_type: figure
  visu_type: scatter
  selection_enabled: true
  selection_column: sample_id   # required when selection_enabled=true
  # ...

Card Component¶

- tag: metric-card
  component_type: card
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  aggregation: average
  column_name: numeric_column
  column_type: float64     # optional — enables offline aggregation validation
  icon_name: mdi:chart-line
  icon_color: "#2196F3"

Aggregation × column_type compatibility:

column_type	Valid aggregations
`int64`	`count`, `sum`, `average`, `median`, `min`, `max`, `range`, `variance`, `std_dev`, `skewness`, `kurtosis`
`float64`	`count`, `sum`, `average`, `median`, `min`, `max`, `range`, `variance`, `std_dev`, `percentile`, `skewness`, `kurtosis`
`bool`	`count`, `sum`, `min`, `max`
`datetime`	`count`, `min`, `max`
`timedelta`	`count`, `sum`, `min`, `max`
`category`	`count`, `mode`
`object`	`count`, `mode`, `nunique`

column_type is optional

If you omit column_type, validation against the compatibility table is skipped offline. When --config is provided, the column type is inferred from the server schema and used for validation automatically.

Interactive Component¶

# MultiSelect — for categorical/text columns
- tag: category-filter
  component_type: interactive
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  interactive_component_type: MultiSelect
  column_name: category

# RangeSlider — for numeric columns
- tag: numeric-filter
  component_type: interactive
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  interactive_component_type: RangeSlider
  column_name: value
  column_type: float64     # optional — enables offline type compatibility check

# DateRangePicker — for datetime columns
- tag: date-filter
  component_type: interactive
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  interactive_component_type: DateRangePicker
  column_name: sample_date

Interactive type × column_type compatibility:

column_type	Valid interactive_component_type
`int64`	`Slider`, `RangeSlider`
`float64`	`Slider`, `RangeSlider`
`datetime`	`DateRangePicker`
`category`	`Select`, `MultiSelect`, `SegmentedControl`
`object`	`Select`, `MultiSelect`, `SegmentedControl`
`bool`	(not yet supported)
`timedelta`	(not supported)

Table Component¶

- tag: data-table
  component_type: table
  workflow_tag: python/workflow_name
  data_collection_tag: table_dc
  page_size: 25          # rows per page (default: 10)
  columns: [col1, col2]  # optional: restrict visible columns

Image Component¶

- tag: image-gallery
  component_type: image
  workflow_tag: python/workflow_name
  data_collection_tag: images_dc
  image_column: image_path   # required: column with image paths
  thumbnail_size: 150        # pixels (default: 150)
  columns: 4                 # grid columns (default: 4)
  max_images: 20             # max images shown (default: 20)

s3_base_folder is optional

If omitted, the image base folder is resolved automatically from the data collection's S3 configuration at runtime.

MultiQC Component¶

Embeds a specific plot from a MultiQC quality control report. Both selected_module and selected_plot are required — they uniquely identify which plot to render.

- tag: fastqc-quality
  component_type: multiqc
  workflow_tag: python/nf_workflow
  data_collection_tag: multiqc_report
  selected_module: fastqc
  selected_plot: per_base_sequence_quality

Both fields are required

Omitting either selected_module or selected_plot will fail validation. Unlike the Dash runtime (which can auto-select), YAML-defined components must be explicit about which plot to display.

Validation¶

The CLI validates YAML files in two passes:

┌──────────────────────────────────────────────────────────────┐
│  Pass 1 — Schema + Domain  (always, no server needed)        │
│                                                              │
│  ✓ YAML syntax parsing                                       │
│  ✓ Required fields (title, component required fields)        │
│  ✓ visu_type enum (scatter, line, bar, box, histogram)       │
│  ✓ mode/code_content cross-field rule                        │
│  ✓ selection_enabled/selection_column cross-field rule       │
│  ✓ aggregation × column_type compatibility (if provided)     │
│  ✓ interactive_type × column_type compatibility (if provided)│
│  ✓ MultiQC: selected_module + selected_plot both required    │
│  ✓ Image: image_column required                              │
├──────────────────────────────────────────────────────────────┤
│  Pass 2 — Server Schema  (with --config, skip: --offline)    │
│                                                              │
│  ✓ Resolves workflow_tag + data_collection_tag → DC schema   │
│  ✓ Checks column_name exists in delta table schema           │
│  ✓ Infers column_type from schema → validates aggregation    │
│    and interactive_component_type against inferred type      │
└──────────────────────────────────────────────────────────────┘

Error output is a clean per-component table — each invalid field gets its own row:

                     Validation Errors
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Component              ┃ Field           ┃ Message        ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ image-missing-column   │ image_column    │ Field required │
│ multiqc-missing-module │ selected_module │ Field required │
│ multiqc-missing-plot   │ selected_plot   │ Field required │
└────────────────────────┴─────────────────┴────────────────┘

Best Practices¶

File Organization¶

project/
├── project.yaml              # Project configuration
├── dashboards/
│   ├── overview.yaml         # Main overview dashboard
│   ├── qc_metrics.yaml       # QC-specific dashboard
│   └── samples.yaml          # Sample analysis dashboard
└── README.md

Component Naming¶

Use descriptive tags that indicate purpose:

# Good: Descriptive tags
- tag: box-variety-sepal-length   # Chart type + data
- tag: sepal-length-average       # Metric + aggregation
- tag: variety-filter             # Column + purpose

# Avoid: Generic tags
- tag: figure-1
- tag: card-2

Incremental Validation Workflow¶

# Step 1 — check schema and domain constraints (no server needed)
depictio-cli dashboard validate my.yaml

# Step 2 — full validation including column names
depictio-cli dashboard validate my.yaml --config ~/.depictio/admin_config.yaml

# Step 3 — dry import (schema check only, no write)
depictio-cli dashboard import my.yaml --dry-run

# Step 4 — actual import
depictio-cli dashboard import my.yaml --config ~/.depictio/admin_config.yaml

# Step 5 — roundtrip check (export back and diff)
depictio-cli dashboard export <id> -o out.yaml
diff my.yaml out.yaml

Version Control¶

Do version control dashboard YAML files
Use meaningful commit messages describing dashboard changes
Review diffs before merging dashboard changes
Tag releases when deploying to production

Dashboard YAML Management¶

Overview¶

CLI Commands¶

Validate¶

Import¶

Export¶

YAML Format¶

DashboardDataLite Structure¶

Complete Example¶

Component Types Reference¶

Figure Component¶

Card Component¶

Interactive Component¶

Table Component¶

Image Component¶

MultiQC Component¶

Validation¶

Best Practices¶

File Organization¶

Component Naming¶

Incremental Validation Workflow¶

Version Control¶

See Also¶