---
title: "LearningCurve"
description: "Smoothed metric curves comparing training runs over steps."
category: Charts
status: beta
since: 0.8.0
tags: [chart, training, smoothing, seeds]
syncStatus: reviewed
verified: true
---

## Usage

### Runs and Seeds
`seeds` draw as their mean inside a ± std band and `smoothing` sets the strength; wire a legend through `v-model:hidden-runs` and `highlighted-run`.
:::TuffDemoWrapper{demo="LearningCurveBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { TxLearningCurve } from '@talex-touch/tuffex/charts'

  // Each seed is an array of [step, value] in step order
  const runs = [
    { name: 'SAC', seeds: [sac1, sac2, sac3] },
    { name: 'TD3', seeds: [td31, td32, td33] },
    { name: 'PPO', seeds: [ppo1, ppo2, ppo3] },
  ]
  </script>

  <template>
    <TxLearningCurve
      v-model:hidden-runs="hidden"
      :runs="runs"
      :smoothing="smoothing"
      :highlighted-run="highlighted"
      x-axis-name="Environment steps"
      y-axis-name="Episode return"
    />
  </template>
---
:::

### Live Training
The curves grow with the data; a window resting on the last step follows training, and `v-model:window` reads and sets it.
:::TuffDemoWrapper{demo="LearningCurveStreamingDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  const logged = ref(16)
  const runs = computed(() => finished.map(run => ({
    name: run.name,
    seeds: run.seeds.map(seed => seed.slice(0, logged.value)),
  })))
  const view = ref<[number, number] | null>(null)
  </script>

  <template>
    <TxLearningCurve v-model:window="view" :runs="runs" :smoothing="0.8" />
  </template>
---
:::

### Log Step Axis
Pass a single-seed run as `data`; `x-type="log"` spreads out early training and leaves out step 0 and below.
:::TuffDemoWrapper{demo="LearningCurveLogAxisDemo" code-lang="vue"}
---
code: |
  <template>
    <TxLearningCurve
      x-type="log"
      :runs="[
        { name: 'lr 1e-3', data: lossFast },
        { name: 'lr 3e-4', data: lossSlow },
      ]"
      y-axis-name="Training loss"
    />
  </template>
---
:::

### Best Practices

- Compare algorithms with several seeds per run, and judge a gap against the band, not the means alone.
- `smoothing` changes only the drawing; the tooltip lists the smoothed and the raw value.
- Wire `highlightedRun` to legend hover and `v-model:hidden-runs` to legend clicks.
- Localize `labels`: `step` writes the step in the tooltip title and the spoken reading.

## API Reference

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `runs` | `LearningCurveRun[]` | — | Runs to compare. |
| `smoothing` | `number` | `0.6` | Exponential-moving-average weight, 0–0.99; `0` draws the values as logged. |
| `showRaw` | `boolean` | `true` | Draws the raw values faintly under the smoothed line. |
| `showBand` | `boolean` | `true` | Draws a ± one-standard-deviation band for multi-seed runs. |
| `xType` | `'linear' \| 'log'` | `'linear'` | Step axis scale; `log` leaves out step 0 and below. |
| `zoom` | `boolean` | `true` | Zooms and pans the step axis on the chart; `false` keeps the view fixed. |
| `highlightedRun` | `string \| null` | — | Emphasizes one run and dims the rest. |
| `xAxisName` | `string` | — | Step-axis title. |
| `yAxisName` | `string` | — | Value-axis title. |
| `yAxisNameGap` | `number` | `56` | Gap between the value axis and its name, in pixels. |
| `xAxisTickFormat` | `(step: number) => string` | SI prefixes | Step ticks; past a thousand steps they read `200k`, `1.5M`. |
| `yAxisTickFormat` | `(value: number) => string` | — | Value ticks. |
| `stepFormat` | `(step: number) => string` | Grouped digits | The step in the tooltip and spoken reading. |
| `tooltipValueFormat` | `(value: number) => string` | Four significant digits | Values in the tooltip and spoken reading. |
| `height` | `number` | `300` | Height in pixels. |
| `width` | `number` | Measured | Explicit width, for SSR and tests. |
| `ariaDescription` | `string` | — | Accessible description of the chart. |
| `labels` | `Partial<LearningCurveLabels>` | English | Accessible name, key instructions and tooltip wording. |
| `hiddenRuns` | `string[]` | `[]` | Names of runs left out of the chart and tooltip. |
| `window` | `[number, number] \| null` | `null` | Step window shown, bindable with `v-model:window`; `null` shows every step. |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:hiddenRuns` | `hiddenRuns: string[]` | `v-model:hidden-runs` write-back. |
| `update:window` | `window: [number, number] \| null` | After a zoom, a pan, a reset or following new data. |

### Types

:::TuffCodeBlock{lang="typescript"}
---
code: |
  interface LearningCurveRun {
    name: string                           // Tooltip name; hiddenRuns and highlightedRun refer to it
    data?: Array<[number, number]>         // [step, value] pairs of a single seed
    seeds?: Array<Array<[number, number]>> // Several seeds; takes precedence over data
    color?: string                         // Defaults to the categorical palette by position
  }

  interface LearningCurveLabels extends ChartLabels {
    step: (step: string) => string         // Tooltip title and spoken reading from the formatted step
    raw: string                            // Tooltip label in front of the raw value
  }

  // The same smoothing and aggregation, to precompute on a server
  function smoothEma(values: readonly number[], weight: number): number[]
  function aggregateSeeds(seeds: Array<Array<[number, number]>>, weight: number): RunCurve

  interface RunCurve {
    steps: number[]
    raw: number[]                          // Mean of the seeds' raw values
    smoothed: number[]                     // Mean of the seeds' smoothed values
    spread: number[] | null                // Std of the smoothed values; null for a single seed
  }
---
:::

## Interaction

| Input | Result |
|-------|--------|
| Hover, press and drag | Reads each run's smoothed value, band and raw value at the nearest step, and emphasizes the run nearest the pointer. |
| One-finger press and drag | Reads values; a vertical swipe still scrolls the page. |
| Drag across a range | Zooms into those steps. |
| Drag a zoomed chart | Pans, rubberbands past either end and glides on release; Shift-drag still brushes. |
| ⌘/Ctrl + wheel, pinch | Zooms around the pointer. |
| Sideways trackpad swipe | Pans a zoomed view. |
| Double-click | Shows every step. |
| ← / →, Home / End | Reads step by step, jumps to either end. |
| + / −, Shift + ← / →, 0 | Zooms, pans, shows every step. |
| Escape | Clears the reading, or cancels a brush in progress. |

## Overview

- Each seed is smoothed over its own steps, then read at the union of all seeds' steps: the curve is the mean of the smoothed values, the band their population standard deviation.
- At a step only some seeds reach, the mean and band use only those seeds.
- The value axis fits the smoothed lines, raw values and bands drawn in view, and springs to a new fit on a zoom, a pan, a hidden run or new data.
- Readings snap to the nearest logged step; a keyboard reading has no pointer height and treats every run alike.
- A window resting on the last step moves forward with new data; otherwise new data leaves the view alone.
- Under `prefers-reduced-motion: reduce` the entrance, zoom and glide do not animate and the value axis lands at once.

## Technologies

- Smoothing matches TensorBoard's debiased exponential moving average, so the first steps are not dragged towards 0; past four points per plot pixel, each pixel column keeps its first, last, lowest and highest point.
- Composed from the `TxChart` primitives; zoom and pan share one view layer with `TxTimeseriesChart`.
- Source: `packages/tuffex/packages/components/src/charts/src/learning-curve/`.

<TuffDocSourceLink label="View source" path="packages/tuffex/packages/components/src/charts/src/learning-curve/index.ts" />

## Related components

- [TimeseriesChart](/docs/dev/components/timeseries-chart): metrics over time, with the same zoom gestures.
- [Custom Chart](/docs/dev/components/custom-chart): the same primitives, assembled into other charts.
- [Charts](/docs/dev/components/charts): the chart family and how to choose.
