define_metric

This feature requires swanlab >= 0.10.0.

define_metric(
    key: str,
    *,
    x_axis: Optional[str] = None,
    section_name: Optional[str] = None,
    hidden: Optional[bool] = None,
    step_sync: Optional[bool] = None,
    overwrite: bool = False,
) -> None

All parameters after key are keyword-only.

Parameter	Description
key	Metric key. Supports an exact key or a glob with a single trailing * (e.g. "train/*"; a bare "*" matches all custom metrics). Patterns like "*loss", "train/*/x" and "train/**" are rejected (an error is reported and the definition does not take effect); system metric keys are never matched.
x_axis	Metric key used as the custom X axis. None uses the system step as the X axis. The step_metric parameter is accepted as an alias.
section_name	Chart section (group) name. None uses the default grouping derived from the key prefix.
hidden	Whether to hide the chart. True places the chart in the HIDDEN section; False explicitly unhides it. Defaults to None (not specified), which keeps the previous setting when merging.
step_sync	When X-axis and Y-axis metrics are logged separately, whether to automatically fill each Y value with the most recent X value. Enabled by default once x_axis is set; usually no need to change.
overwrite	False merges with the existing definition; True resets unspecified fields to their defaults. Defaults to False. Only affects keys that have not been logged yet.

Introduction

swanlab.define_metric defines the chart behavior of metrics before swanlab.log, including:

• Custom X axis: use another metric (e.g. epoch) as the X axis instead of the default step
• Chart grouping: assign metric charts to a custom section
• Hide charts: put rarely used charts into the HIDDEN section

Custom X axis

Set the X axis of train/loss to train/epoch:

import swanlab

swanlab.init(project="my-project")

swanlab.define_metric("train/loss", x_axis="train/epoch")

for epoch in range(num_epochs):
    swanlab.log({"train/epoch": epoch})
    # ... training ...
    swanlab.log({"train/loss": loss})  # automatically syncs the value of train/epoch

X-axis and Y-axis metrics can be logged separately — SwanLab automatically fills each Y value with the most recent X value. We recommend logging the X-axis metric before the Y-axis metric in each round. If the X value is logged after the Y value, the chart keeps the auto-filled X value and a warning is emitted.

x_axis must be a valid metric key (or the system values "_step" / "_relative_time") and must not be a system metric key; if validation fails, the whole definition is aborted with an error.

A custom X axis is assumed to be monotonically non-decreasing: only the first Y point is kept for a given X value. With a non-monotonic X (e.g. 5→6→5), a rolled-back X value is accepted as new, so multiple Y points may appear at the same X value.

Batch definition with glob

key supports a glob with a single trailing *, so you can define a group of metrics at once:

# Put all metrics under val/ into the "Validation" section
swanlab.define_metric("val/*", section_name="Validation")

When a metric matches multiple rules: an exact key match wins first, then the glob with the longest prefix, and finally the default behavior. For example:

swanlab.define_metric("train/stage/acc", x_axis="x1")
swanlab.define_metric("train/*", x_axis="x2")
swanlab.define_metric("train/stage/*", x_axis="x3")

• train/stage/acc uses x1 as its X axis (exact match, most specific)
• Other metrics under train/stage/ use x3 (train/stage/* is more specific than train/*)
• The remaining metrics under train/ use x2

Hiding charts

# The chart goes into the HIDDEN section and is not shown on the dashboard by default
swanlab.define_metric("debug/grad_norm", hidden=True)

Hidden metric data is still recorded and uploaded as usual — the chart is simply folded into the HIDDEN section, and you can unhide it anytime in the WebUI dashboard.

When hidden is not passed, the previous setting is kept; to undo a previous hidden=True, pass hidden=False explicitly (this also works in merge mode).

Merge vs. overwrite

When calling define_metric multiple times for the same key:

• overwrite=False (default): merge on top of the existing definition, updating only the fields specified this time
• overwrite=True: overwrite — every field not specified this time returns to its default value

swanlab.define_metric("train/loss", x_axis="train/epoch")
swanlab.define_metric("train/loss", section_name="Train")  # merge: x_axis kept, section added
swanlab.define_metric("train/loss", section_name="Train", overwrite=True)  # overwrite: x_axis resets to the default step

Merging and overwriting only work for keys that have not been logged yet. Once a metric has been logged and its chart created, further define_metric calls take no effect — adjust the chart in the WebUI instead.

Notes

1. Within the same project, each metric corresponds to only one chart. For example, once the first define_metric("train/loss", x_axis="x1") in run1 takes effect, defining x_axis="x2" in run2 of the same project will not take effect.
2. Media metrics such as images and audio ignore x_axis (they are still displayed by step); only section_name and hidden are applied to them.
3. Chart definitions made via define_metric only take effect in the current default view and copied views. When performing "copy/move experiment", "add comparison experiment", or "create default view", the section grouping is preserved, but custom X-axis associations are lost and the X axis falls back to the default step.