# `.dashrc` Reference

A `.dashrc` file is a YAML configuration file that controls how experiments and comparisons are displayed in the [Dashboard](/dashboard/overview.md). Its behavior depends on where it is placed.

## File Placement

| Location | Type | Controls |
|----------|------|----------|
| Inside an experiment folder | Experiment `.dashrc` | Charts for that single experiment |
| Inside any other folder | Compare `.dashrc` | Cross-experiment comparison charts |

---

## Experiment `.dashrc` vs Compare `.dashrc`

| Feature | Experiment | Compare |
|---------|-----------|---------|
| `metrics` section | ✓ Used | ✗ Ignored |
| `ctype: line` | ✓ Used | ✓ Used |
| `ctype: image` | ✓ Used | ✗ Ignored |
| `ctype: video` | ✓ Used | ✗ Ignored |
| `series` array | ✗ Ignored | ✓ Used |

---

## Complete Field Reference

### Top-Level Fields

```yaml
metrics:       # Experiment .dashrc only
  fields:
    - "*"

charts:
  - ...
```

| Field | Type | Description |
|-------|------|-------------|
| `metrics` | object | Controls which metrics appear in the experiment header. Experiment `.dashrc` only. |
| `metrics.fields` | `string[]` | Glob patterns for metric names. `"*"` matches all. Supports prefixes like `"train*"`. |
| `charts` | `ChartConfig[]` | Ordered list of charts to display. |

---

### `ChartConfig` — Common Fields

All chart types share these fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ctype` | `"line" \| "image" \| "video"` | Yes | Chart type |
| `title` | `string` | No | Title displayed above the chart |

---

### `ChartConfig` — Line Chart Fields

```yaml
- ctype: line
  title: My Chart
  xKey: step
  yKey: train.loss         # or yKeys: [...]
  xLabel: Steps
  yLabel: Loss
  bins: 500
  xFormat: null
  yFormat: null
  xTicks: 10
  yTicks: 5
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `xKey` | `string` | — | X-axis metric name (required). See [xKey values](#xkey-values) below. |
| `yKey` | `string` | — | Single y-axis metric. Mutually exclusive with `yKeys`. |
| `yKeys` | `string[]` | — | Multiple y-axis metrics on the same chart. Mutually exclusive with `yKey`. |
| `series` | `SeriesConfig[]` | — | Per-series config. **Compare `.dashrc` only.** Mutually exclusive with `yKey` and `yKeys`. Each series issues one API request. |
| `xLabel` | `string` | xKey name | X-axis label |
| `yLabel` | `string` | metric name | Y-axis label |
| `bins` | `number` | `1000` | Downsample target point count. Higher = more detail, slower render. |
| `xFormat` | `string \| null` | `null` | Format specifier for x-axis ticks. |
| `yFormat` | `string \| null` | `null` | Format specifier for y-axis ticks. |
| `xTicks` | `number` | auto | Number of x-axis grid lines. |
| `yTicks` | `number` | auto | Number of y-axis grid lines. |

**`yKey`, `yKeys` and `series` are mutually exclusive** — use exactly one. (`series` is available in compare `.dashrc` only.)

---

### `SeriesConfig` — Per-Series Fields

Used inside `series` arrays in compare `.dashrc` files only.

| Field | Type | Description |
|-------|------|-------------|
| `prefix` | `string` | Experiment path prefix. |
| `experimentIds` | `string[]` | Explicit list of experiment IDs to include in this series. |
| `experimentId` | `string` | Single experiment ID. Shorthand for `experimentIds: [id]`. |
| `label` | `string` | Legend label for this series. |
| `color` | `string` | Line color as a hex string (e.g. `"#5470c6"`). Explicit colors are always preserved. |
| `dash` | `string` | SVG stroke-dasharray string. Omit for a solid line. |
| `xKey` | `string` | Overrides the chart-level `xKey` for this series only. |
| `yKey` | `string` | Overrides the chart-level `yKey` for this series only. |

---

### `ChartConfig` — Image Chart Fields

```yaml
- ctype: image
  title: Frames
  glob: "frames/**/*.png"
  nCols: 4
  nRows: 2
  sort: date
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `glob` | `string` | `"**/*.{png,jpg,jpeg,gif,webp}"` | Glob pattern to match files within the experiment folder. |
| `nCols` | `number` | `3` | Number of grid columns. |
| `nRows` | `number` | `2` | Number of grid rows. The grid shows at most `nCols × nRows` files. |
| `sort` | `"name" \| "date" \| "size"` | `"name"` | File sort order. |

---

### `ChartConfig` — Video Chart Fields

```yaml
- ctype: video
  title: Rollouts
  glob: "videos/**/*.mp4"
  nCols: 2
  nRows: 2
  sort: name
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `glob` | `string` | `"**/*.{mp4,webm,mov}"` | Glob pattern to match files within the experiment folder. |
| `nCols` | `number` | `3` | Number of grid columns. |
| `nRows` | `number` | `2` | Number of grid rows. The grid shows at most `nCols × nRows` files. |
| `sort` | `"name" \| "date" \| "size"` | `"name"` | File sort order. |

---

## `xKey` Values

The `xKey` field specifies which metric is used as the x-axis.

| Value | Behavior |
|-------|----------|
| `"default"` | The server picks `step`, then `epoch`, from the metric's own fields. Falls back to the data index if it has neither. |
| `"step"` | Uses the `step` field logged alongside each metric. |
| `"epoch"` | Uses the `epoch` field logged alongside each metric. |
| `"timestamp"` | Uses the Unix timestamp recorded automatically by ML-Dash. |
| Any other string | Uses that metric name as the x-axis value. |

---

## Series Colors and Dash Patterns

When `color` is not specified, series are assigned colors automatically from a fixed palette.

### Default Color Palette

| Index | Swatch | Color | Hex |
|-------|--------|-------|-----|
| 0 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#5470c6', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Blue | `#5470c6` |
| 1 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#91cc75', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Green | `#91cc75` |
| 2 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#fac858', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Yellow | `#fac858` |
| 3 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#ee6666', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Red | `#ee6666` |
| 4 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#73c0de', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Sky | `#73c0de` |
| 5 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#3ba272', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Teal | `#3ba272` |
| 6 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#fc8452', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Orange | `#fc8452` |
| 7 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#9a60b4', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Purple | `#9a60b4` |
| 8 | <span style={{display: 'inline-block', width: '28px', height: '14px', background: '#ea7ccc', borderRadius: '3px', verticalAlign: 'middle'}}></span> | Pink | `#ea7ccc` |

For more than 9 series, colors cycle with a **+40° hue rotation** per round, combined with cycling dash patterns.

### Dash Pattern Examples

| Value | Preview | Appearance |
|-------|---------|-----------|
| *(omitted)* | <svg width="80" height="12" style={{verticalAlign: 'middle'}}><line x1="0" y1="6" x2="80" y2="6" stroke="currentColor" strokeWidth="2"/></svg> | Solid line |
| `2 4` | <svg width="80" height="12" style={{verticalAlign: 'middle'}}><line x1="0" y1="6" x2="80" y2="6" stroke="currentColor" strokeWidth="2" strokeDasharray="2 4"/></svg> | Dotted |
| `4 4` | <svg width="80" height="12" style={{verticalAlign: 'middle'}}><line x1="0" y1="6" x2="80" y2="6" stroke="currentColor" strokeWidth="2" strokeDasharray="4 4"/></svg> | Short dashes |
| `8 4` | <svg width="80" height="12" style={{verticalAlign: 'middle'}}><line x1="0" y1="6" x2="80" y2="6" stroke="currentColor" strokeWidth="2" strokeDasharray="8 4"/></svg> | Long dashes |
| `8 4 2 4` | <svg width="80" height="12" style={{verticalAlign: 'middle'}}><line x1="0" y1="6" x2="80" y2="6" stroke="currentColor" strokeWidth="2" strokeDasharray="8 4 2 4"/></svg> | Dash-dot |

---

## Validation

`.dashrc` files are validated in two stages:

1. **Frontend** — YAML syntax is checked immediately (300ms debounce). Parse errors are shown inline in the editor.
2. **Backend** — Field values are validated when data is fetched. Errors are returned in the API response and displayed below the affected chart.

---

## Quick Reference

```yaml
# Experiment .dashrc — full template
metrics:
  fields:
    - "*"

charts:
  - ctype: line
    title: Chart title
    xKey: default        # or: step, epoch, timestamp, any metric name
    yKey: train.loss     # single metric  ──┐
    # yKeys:             # multiple metrics │-pick one
    #   - train.loss     #                  │
    #   - eval.loss      #                 ─┘
    xLabel: Steps
    yLabel: Loss
    bins: 500
    xTicks: 10
    yTicks: 5

  - ctype: image
    glob: "**/*.png"
    nCols: 4
    nRows: 2
    sort: date

  - ctype: video
    glob: "**/*.mp4"
    nCols: 2
    nRows: 2

# Compare .dashrc — series example
charts:
  - ctype: line
    xKey: default
    yKey: train.loss
    series:
      - prefix: alice/project/run-a
        label: Run A
        color: "#5470c6"
      - prefix: alice/project/run-b
        label: Run B
        color: "#ee6666"
        dash: 4 4
      - experimentIds:
          - exp_abc123
          - exp_def456
        label: Seed Group
        color: "#91cc75"
```