Skip to content

Dashboard Components

Depictio provides a variety of component types for building interactive dashboards. This guide covers each component type, when to use it, and how to configure it.

Component Overview

  • Figure

    Charts and plots (scatter, bar, histogram, line, box, pie, and more)

  • Table

    Interactive data tables with filtering and sorting

  • Card

    Metric display with aggregations

  • Text

    Section headers (H1, H2, H3)

  • Interactive

    User input components for filtering (slider, dropdown, date picker)

  • MultiQC

    Quality control report visualizations

  • Image

    Image galleries with S3/MinIO storage integration

  • Map

    Geospatial map visualization with markers

Figure Components

Figure components display data visualizations using Plotly charts. They support both UI Mode (drag-and-drop configuration) and Code Mode (Python code for custom plots).

Supported Chart Types

UI Mode provides a curated selection of chart types through the visual interface:

Category Chart Types
Basic Charts Scatter, Bar, Line
Statistical Histogram, Box
Matrix ComplexHeatmap (via plotly-complexheatmap)

Unlimited Charts with Code Mode

Code Mode supports the entire Plotly library, giving you access to all chart types including 3D plots, maps, financial charts, and more. See the Plotly Python documentation for the complete reference.

UI Mode

In UI Mode, configure charts through the visual interface:

  1. Select a Data Collection as your data source
  2. Choose the Chart Type (scatter, bar, histogram, etc.)
  3. Map data columns to X-axis, Y-axis, and optional Color dimension
  4. Customize appearance (title, axis labels, colors)

Code Mode

Code Mode allows custom Python code for advanced visualizations:

import plotly.express as px

# df is your data collection as a pandas DataFrame
fig = px.scatter(
    df,
    x="coverage",
    y="quality_score",
    color="sample_type",
    title="Coverage vs Quality by Sample Type"
)

# Return the figure object
fig

Security Note

Code Mode uses RestrictedPython for security. Only approved libraries (pandas, plotly) are available. See Security for details.

Configuration Options

Option Description Default
Title Chart title displayed at top Auto-generated
X-axis label Label for horizontal axis Column name
Y-axis label Label for vertical axis Column name
Color Column for color encoding None
Hover data Additional columns shown on hover None

ComplexHeatmap

ComplexHeatmap figures use the plotly-complexheatmap library to render clustered heatmaps with dendrograms and row/column annotations — similar to R's ComplexHeatmap.

Option Description Default
index_column Column used as row labels First column
value_columns Numeric columns for the matrix All numeric
row_annotations Columns rendered as colored side bars None
cluster_rows / cluster_cols Enable hierarchical clustering true
normalize Row normalization (zscore, minmax, none) none
colorscale Plotly colorscale name RdBu_r
split_rows_by Split heatmap into groups by annotation None
cluster_method Linkage method (ward, average, complete, single) ward
cluster_metric Distance metric (euclidean, correlation, cosine) euclidean

Heatmaps work in both UI Mode (parameter discovery in the stepper) and YAML Mode (see YAML figure reference).

Selection Filtering (Scatter Plots)

Scatter plots can act as interactive filters. Enable selection to let users lasso, box-select, or click points to filter other components.

Option Description
selection_enabled Enable selection filtering (true/false)
selection_column Column to extract from selected points

See Interactive Selection Filtering for details.

Table Components

Table components display data in interactive tables with built-in filtering and sorting.

Features

Feature Description
Server-Side Pagination Efficiently handles large datasets by loading data in pages
Server-Side Scrolling Virtual scrolling for smooth navigation through large tables
Column Sorting Click headers to sort ascending/descending
Column Filtering Filter by column values
Export (v0.6.0+) Download data as CSV

Configuration

Option Description Default
Data Collection Source data for the table Required
Visible Columns Columns to display All columns
Page Size Rows per page 10, 25, 50, or 100
Style Column width, text alignment Auto
Title Header text above the table Auto (from DC tag)
Description Subtitle text below the title None
Title Size Header level: h1, h2, h3, or sm sm
Title Align Text alignment: left, center, or right left

Row Selection Filtering

Tables can act as interactive filters. Enable row selection to let users click rows to filter other components.

Option Description
row_selection_enabled Enable row selection filtering (true/false)
row_selection_column Column to extract from selected rows

See Interactive Selection Filtering for details.

Card Components

Card components display metrics with aggregations. A card shows a hero metric (primary value) and can optionally display secondary metrics below it for at-a-glance summaries.

Aggregation Types

Aggregation Description Example
count Number of rows Total samples
sum Sum of values Total reads
average Average value Average coverage
median Median value Median quality score
min Minimum value Minimum mapping rate
max Maximum value Maximum duplication rate
nunique Count of unique values Unique sample types
std_dev Standard deviation Coverage spread
variance Variance Expression variability
range Max − Min Read length range
skewness Distribution skew Quality score symmetry
kurtosis Distribution tailedness Outlier tendency
percentile 50th percentile Median coverage
mode Most frequent value Dominant sample type

Configuration

  1. Select a Data Collection
  2. Choose a Column to aggregate
  3. Select an Aggregation type (hero metric)
  4. Optionally add Secondary Metrics (aggregations) for a multi-metric summary
  5. Optionally add a Filter Expression (filter_expr) for conditional aggregation
  6. Customize the Title, Icon, and Styling

Multi-Metric Summary Cards

Cards can display multiple aggregation results in a single component. The primary aggregation is shown as the large hero value, and aggregations are displayed as compact secondary rows below it.

┌─────────────────────────────────┐
│ Petal Length              [Icon]│
├─────────────────────────────────┤
│           4.5 cm                │
│          (Average)              │
├─────────────────────────────────┤
│ Median:       4.35              │
│ Std Dev:      0.82              │
│ Min:          1.00              │
│ Max:          6.90              │
└─────────────────────────────────┘

Conditional Aggregation (filter_expr)

Cards support a filter_expr field — a Polars expression that pre-filters the data before computing the aggregation. This enables conditional metrics like "count of samples with coverage > 30x" without creating a separate data collection.

filter_expr works on top of interactive filters (dual-layer filtering): interactive filters narrow the dataset first, then filter_expr applies an additional condition before aggregation.

See Filter Expressions for the complete expression reference.

Styling Options

Option Description Example
Title Metric label "Total Samples"
Description Subtitle text "Across all batches"
Icon Iconify icon name mdi:chart-line
Icon Color Icon accent color #2196F3
Title Color Title text color #333333
Title Font Size Title font size sm
Value Font Size Hero value font size xl

Text Components

Text components display section headers to organize your dashboard.

Supported Header Levels

Level Syntax Description
H1 # Header Main section headers
H2 ## Header Sub-section headers
H3 ### Header Minor section headers

Limited Markdown Support

Currently, only H1, H2, and H3 headers are supported. Full markdown rendering (lists, links, bold, italic, code blocks, etc.) is not available in text components.

Use Cases

  • Dashboard section headers
  • Visual organization of content
  • Labeling groups of related components

Interactive Components

Interactive components let users filter data across the dashboard. These components affect all linked visualization components.

Component Types

Component Input Type Best For
RangeSlider Numeric range Coverage: 0-100x
MultiSelect Multiple choices Sample types
DatePicker Date range Run dates
SegmentedControl Single choice Condition A/B
TextInput Free text Sample ID search

RangeSlider

Filter data by numeric range:

Option Description
Column Numeric column to filter
Min/Max Range bounds
Step Increment value
Default Initial range values

MultiSelect

Filter by selecting multiple values:

Option Description
Column Categorical column to filter
Options Available values (auto-populated)
Default Initially selected values
Placeholder Hint text when empty

DatePicker

Filter by date range:

Option Description
Column Date/datetime column to filter
Format Date display format
Default Initial date range

SegmentedControl

Single-selection toggle:

Option Description
Column Column to filter
Options Available choices
Default Initially selected option

Scoped Filters (filter_expr)

Interactive components support a filter_expr field that pre-filters the underlying data before computing component options. Instead of showing all possible values, the component shows only values that exist in the filtered subset.

Example: A MultiSelect with filter_expr: "col('petal.length') > 4" only shows variety options that appear in rows where petal length exceeds 4 cm.

This is useful for:

  • Cascading filters — show only relevant options based on data conditions
  • Domain-specific scoping — e.g., only show taxa above an abundance threshold
  • Focused analysis — restrict a slider's range to a meaningful subset

See Filter Expressions for the complete expression reference.

MultiQC Components

MultiQC components display quality control reports generated by MultiQC.

Features

Feature Description
Report Embedding Display MultiQC HTML reports inline
Interactive Navigation Navigate between MultiQC sections
Tool Integration Support for various QC tools (FastQC, Samtools, STAR, etc.)

Configuration

Option Description
Report Path Path to MultiQC report HTML file
Display Mode Full report or specific sections

Data Requirements

MultiQC components require pre-generated MultiQC reports. The report HTML files should be accessible via the configured data source.

Image Components

Image components display image galleries from S3/MinIO storage, with metadata filtering and thumbnail previews.

Features

Feature Description
Grid Layout Configurable column layout for image thumbnails
Thumbnail Previews Auto-generated thumbnails with configurable size
Metadata Filtering Filter images using interactive components
S3 Integration Serve images directly from S3/MinIO buckets
Click to Expand View full-size images in a modal

Configuration

Option Description Default
Data Collection Source table with image metadata Required
Image Column Column containing image paths Required
S3 Base Folder S3/MinIO bucket path prefix Required
Thumbnail Size Thumbnail height in pixels 150
Columns Number of columns in grid 4
Max Images Maximum images to display 20

Data Collection Setup

Image components require a Table-type Data Collection with:

  1. A column containing relative image paths (e.g., image_path)
  2. Optional metadata columns for filtering (e.g., category, quality_score)

Example CSV structure:

sample_id,image_path,category,quality_score
sample_001,images/sample_001.png,A,0.95
sample_002,images/sample_002.png,B,0.87
sample_003,images/sample_003.jpg,A,0.92

Project YAML Configuration

Configure the Image data collection in your project.yaml:

data_collections:
  - id: "650a1b2c3d4e5f6a7b8c9d10"
    data_collection_tag: "sample_images"
    description: "Sample images with metadata"
    config:
      type: "Image"
      metatype: "Images"
      scan:
        mode: single
        scan_parameters:
          filename: images_data.csv
      dc_specific_properties:
        # Table fields (required for delta table)
        format: "csv"
        columns_description:
          sample_id: "Unique sample identifier"
          image_path: "Relative path to image file"
          category: "Sample category"
          quality_score: "Quality score 0-1"
        # Image-specific fields (mandatory)
        image_column: "image_path"
        # Image display properties (optional)
        s3_base_folder: "s3://bucket-name/images/"
        local_images_path: ./images
        supported_formats: [".png", ".jpg", ".jpeg"]
        thumbnail_size: 150

Dashboard YAML Configuration

Add an image component in your dashboard_lite.yaml:

components:
  - tag: sample-gallery
    component_type: image
    workflow_tag: python/image_workflow
    data_collection_tag: sample_images
    image_column: image_path
    s3_base_folder: "s3://bucket-name/images/"
    thumbnail_size: 150
    columns: 3
    max_images: 9

Image Storage

Images can be stored and accessed in two ways:

Option 1: Images already on S3/MinIO

If your images are already uploaded to S3/MinIO, specify the location in your project configuration:

# In project.yaml - dc_specific_properties
s3_base_folder: "s3://bucket-name/images/"

Option 2: Upload local images with depictio-cli (Recommended)

Use the depictio-cli run command to automatically upload images from a local directory to S3:

# In project.yaml - dc_specific_properties
local_images_path: ./images  # Local path relative to project directory

# Run depictio-cli to sync project and upload images
depictio-cli run --project-dir /path/to/project

The CLI will:

  1. Read the local_images_path from your project configuration
  2. Upload images to the configured S3 bucket
  3. Set the correct s3_base_folder automatically

Cross-DC Filtering

Image components support filtering via interactive components on the same Data Collection. Select samples using a MultiSelect filter, and the image gallery updates automatically.

Map Components

Map components display geospatial data on interactive tile-based maps using Plotly Express (no API key required).

Map Types

Type Function Best For
scatter_map Point markers at lat/lon coordinates Sample locations, site maps
density_map Heatmap overlay from point density Concentration hotspots
choropleth_map Colored polygon regions from GeoJSON Per-country/region statistics

Configuration Options

Option Applies To Description
lat_column / lon_column scatter, density Columns with GPS coordinates (required)
color_column scatter, choropleth Column for color encoding
size_column scatter Column for marker size encoding
hover_columns scatter, choropleth Columns shown on hover tooltip
map_style all Tile style: open-street-map, carto-positron, carto-darkmatter
opacity all Marker/region opacity (0.0–1.0)
default_zoom / default_center all Override auto-computed viewport

Choropleth GeoJSON Sources

Choropleth maps require a GeoJSON FeatureCollection to define region boundaries. Three sources are supported:

Source Field Description
URL geojson_url Public URL to a GeoJSON file
Data Collection geojson_dc_tag Tag of a geojson-type Data Collection in the same project
Inline geojson_data Embedded GeoJSON dict (large — prefer URL or DC)

Selection Filtering

Scatter maps support the same lasso/box/click selection as scatter plots. Enable with selection_enabled: true and selection_column. See Interactive Selection Filtering for details.

Choropleth Limitation

Choropleth maps do not support selection filtering (Plotly does not expose click/lasso on choropleth traces).

YAML Examples

Scatter map:

- tag: sampling-map
  component_type: map
  workflow_tag: python/my_workflow
  data_collection_tag: sample_metadata
  lat_column: latitude
  lon_column: longitude
  color_column: biome
  size_column: read_count
  hover_columns: [sample_id, site_name, country]
  map_style: carto-positron
  selection_enabled: true
  selection_column: sample_id

Choropleth map:

- tag: country-choropleth
  component_type: map
  workflow_tag: python/my_workflow
  data_collection_tag: sample_metadata
  map_type: choropleth_map
  locations_column: country_name
  featureidkey: properties.NAME
  color_column: sample_id
  choropleth_aggregation: count
  color_continuous_scale: Viridis
  geojson_url: "https://raw.githubusercontent.com/nvkelso/natural-earth-vector/master/geojson/ne_110m_admin_0_countries.geojson"

Cross-DC Filtering

Interactive components can filter across linked Data Collections using the Links system. See Cross-DC Filtering for details.

┌─────────────────┐         ┌─────────────────┐
│  Filter: Status │  link   │  Table: Samples │
│  [MultiSelect]  │────────▶│  [auto-filters] │
└─────────────────┘         └─────────────────┘

Component Creation

Using the Stepper Wizard

The component builder guides you through creation:

  1. Select Data Collection - Choose your data source
  2. Choose Component Type - Figure, Table, Card, Interactive, Text, MultiQC, or Map
  3. Configure Settings - Type-specific options
  4. Preview - See the component before adding
  5. Add to Dashboard - Place on the canvas

Positioning Components

  • Drag and drop components in Edit Mode
  • Components snap to a grid layout
  • Resize by dragging corner handles