Templating System¶

Templates let you save a plot layout once and reuse it across different data files. Instead of manually dragging series into subplots every time you open a new dataset, a template automatically matches series by name and places them in the right subplots for you.

Templates are useful when you:

Run the same simulation multiple times and want a consistent view
Need standardised plot layouts for reports
Want to share a plotting setup with colleagues

Quick Start¶

Saving Your Current Layout as a Template¶

Set up your plot the way you want it — arrange subplots, add series, set axis labels
Open the Template menu and choose Save Template
Pick a name and save — the template captures your grid layout, series names, axis settings, and any transformations

Applying a Template to New Data¶

Open the Template menu and select Load Template (or pick one from your Favourites or Recent list)
The grid layout and axis settings are applied immediately
Drag a file widget from the sidebar onto the plot area (OR) drag a file from your file explorer into the file area
Series from the file are automatically matched to subplots based on the template's patterns

Note

Drag the file widget (the top-level item), not individual series. The template needs to see all available series to distribute them correctly.

How Pattern Matching Works¶

When you drop a file onto a templated plot, the system tries to match each column name in the file against the patterns defined in each subplot.

Editing templates¶

Templates are YAML files stored in ~/.cuteplot/templates/. You can edit them by hand or let the app generate them from your current plot.

Example¶

name: "Power System Analysis"
description: "Exammple 4-subplot power system analysis layout"
version: "1.0"
created: "2025-09-06T10:30:00"
modified: "2025-09-06T10:30:00"

grid:
  rows: 2
  cols: 2

subplots:
  - position: [0, 0]
    title: "Voltage Measurements"
    series_names:
      - "Voltage*"
      - "*_Voltage_*"
    x_axis:
      label: "Time (s)"
      auto: true
    y_axis:
      label: "Voltage (kV)"
      auto: false
      min: -200
      max: 200
      lock_min: true
      lock_max: true
    transformations:
      - series_pattern: "Voltage*"
        operation: "multiply_y"
        value: 0.001

  - position: [0, 1]
    title: "Current Measurements"
    series_names:
      - "*Current*"
      - "I_*"
    x_axis:
      label: "Time (s)"
      auto: true
    y_axis:
      label: "Current (pu)"
      auto: true

  - position: [1, 0]
    title: "Frequency Response"
    series_names:
      - "Frequency"
      - "Freq*"
    x_axis:
      label: "Time (s)"
      auto: true
    y_axis:
      label: "Frequency (Hz)"
      auto: false
      min: 59
      max: 61
      lock_min: true
      lock_max: true

  - position: [1, 1]
    title: "Power Output"
    series_names:
      - "*Power*"
      - "P_*"
    x_axis:
      label: "Time (s)"
      auto: true
    y_axis:
      label: "Power (MW)"
      auto: true

Wildcards¶

* matches any sequence of characters
? matches any single character

Match Priority¶

The system tries to match in this order:

Exact match — if the pattern has no wildcards and matches a column name exactly
Wildcard match — if the pattern contains * or ?, uses standard glob matching
Substring match — if the pattern has no wildcards and didn't match exactly, it checks if the pattern appears anywhere in the column name (e.g. Voltage matches Bus_1_Voltage_A)

When a series matches patterns in multiple subplots, the first subplot in template order wins.

Case Sensitivity¶

Pattern matching is case-sensitive. Voltage* will match Voltage_A but not voltage_A.

Examples¶

Pattern	Matches	Doesn't Match
`Voltage*`	`Voltage_Bus_1`, `Voltage_Line_A`	`Line_Voltage`
`Current`	`Line_Current`, `Load_Current_A`	`current_phase_a` (wrong case)
`*_Current`	`Line_Current`, `Load_Current`	`Current_Transformer`
`Bus__Voltage_`	`Bus_1_Voltage_A`, `Bus_23_Voltage_B`	`Voltage_Bus_1`
`Frequency`	`Frequency` (exact), `Frequency_Response` (substring)	`Freq`

Field Reference¶

Field	Required	Description
`name`	Yes	Display name for the template
`description`	No	Description shown in template menu
`version`	No	Version string (default: `"1.0"`)
`created` / `modified`	No	Timestamps, auto-generated when saving from the app
`grid.rows`	Yes	Number of subplot rows
`grid.cols`	Yes	Number of subplot columns
`subplots`	Yes	List of subplot configurations

Each subplot supports:

Field	Required	Description
`position`	Yes	Grid position as `[row, col]`, zero-indexed
`title`	No	Subplot title
`series_names`	Yes	List of patterns to match against column names
`x_axis` / `y_axis`	No	Axis configuration (see below)
`transformations`	No	Data transformations to apply on match

Axis options:

Field	Default	Description
`label`	`""`	Axis label text
`auto`	`true`	Auto-scale to fit data
`min` / `max`	none	Fixed axis limits (used when `auto` is `false`)
`lock_min` / `lock_max`	`false`	Prevent auto-fit from changing the min/max

Transformations¶

Templates can automatically scale or offset data when series are matched. This is useful for unit conversions (e.g. V to kV, or kV to per-unit) or time offsets.

transformations:
  - series_pattern: "Voltage*"
    operation: "multiply_y"
    value: 0.001
  - series_pattern: "*"
    operation: "add_x"
    value: -1.0

Operation	What it does
`multiply_x`	Scale time (X) values
`multiply_y`	Scale data (Y) values
`add_x`	Offset time values
`add_y`	Offset data values

Multiply operations are applied before additions. You can adjust transformations afterward using the legend sliders.

Managing Templates¶

Storage¶

Location: ~/.cuteplot/templates/
Format: .yaml files
Filename: Auto-generated from the template name (special characters replaced with _)

Favourites and Recent Templates¶

Favourites (up to 5): Pin your most-used templates for quick access via Template > Modify Favourites
Recent (up to 10): The last 10 templates you loaded or saved appear automatically in the menu

Both lists are stored in ~/.cuteplot/ as JSON files and are cleaned up automatically if a template file is moved or deleted.

Dirty State¶

When you modify a plot after loading a template (add/remove series, change axis settings), the template name shows an asterisk — e.g. Power System Analysis (*) — to indicate unsaved changes.

Template files are fully portable. Copy a .yaml file to another user's ~/.cuteplot/templates/ folder and it will appear in their template menu. The only requirement is that their data files use column names that match the template's patterns.

Tips¶

Start from a real plot: The easiest way to create a template is to set up a plot manually, then save it. The app captures everything including axis limits and transformations.
Use specific patterns: Va_* is better than V* if you only want phase-A voltages. Overly broad patterns lead to series ending up in the wrong subplot.
Order subplots carefully: When a series matches patterns in multiple subplots, the first one wins. Put your most specific subplots first.
Lock axes for comparison: Use lock_min/lock_max to keep axis ranges consistent across different datasets, which makes visual comparison easier.
Use substring matching for simple cases: If your column is literally called Frequency, you don't need a wildcard — the exact name works as a pattern and will also substring-match longer names like Frequency_Response.

Troubleshooting¶

No Series Matched¶

Check that your patterns match the column names in your data file — remember, matching is case-sensitive
Make sure you're dragging the file widget, not individual series
Verify the file loaded correctly by expanding it in the sidebar

Series Ending Up in the Wrong Subplot¶

Make patterns more specific to avoid unintended matches
Reorder your subplots — first match wins when a series matches multiple patterns
Check if broad patterns like *Power* are catching series you didn't intend

Template Won't Load¶

Validate YAML syntax — watch for incorrect indentation, missing colons, or unquoted special characters
Check file permissions on the template file