Templating System¶

The Cute Plot templating system enables rapid plot setup by automatically distributing data series across subplots based on predefined patterns and configurations.

Template Concept¶

Templates solve the problem of repeatedly setting up the same plot layout for different datasets. Instead of manually dragging series to subplots every time, templates automate this process.

Use Cases¶

Repetitive analysis: Same measurements across multiple simulation runs
Standard reports: Consistent plot layouts for reports
Team workflows: Share standardized analysis approaches
Batch processing: Apply same layout to multiple files simultaneously

Template Components¶

Grid Configuration¶

Defines the subplot layout:

grid:
  rows: 2
  cols: 2

Subplot Configuration¶

Each subplot can specify: - Position: Grid location (row, col) - Title: Subplot title - Series patterns: Which series to include - Axis labels: X and Y axis labels - Transformations: Data transformations to apply

Series Patterns¶

Flexible pattern matching for automatic series selection:

series_names:
  - "Voltage*"        # Matches "Voltage_Bus_1", "Voltage_Line_A"
  - "*Current*"       # Matches "Line_Current", "Load_Current" 
  - "Frequency"       # Exact match
  - "*Power*Output*"  # Complex wildcard patterns

Creating Templates¶

Template Creation Workflow¶

Set up plot manually: Create desired subplot layout and add series
Save as template: Capture current configuration
Name and describe: Provide meaningful name and description
Test template: Apply to different datasets to verify

Template File Format¶

Templates are stored as YAML files:

name: "Power System Analysis"
description: "Standard 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 (pu)"
      auto: true

  - 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: 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

Template Management¶

Template Storage¶

Templates are stored in: - Location: ~/.cuteplot/templates/ (user directory) - Format: YAML files with .yaml extension - Naming: Automatic filename generation from template name

Recent Templates¶

The system tracks recently used templates: - File: ~/.cuteplot/recent_templates.json - Capacity: Last 10 used templates - Quick access: Available in dropdown menu

Template Operations¶

Save Template¶

Configure plot: Set up desired subplot layout
Template menu: Access template creation (implementation pending)
Name template: Provide descriptive name
Add description: Document template purpose

Load Template¶

Template dropdown: Select from available templates
Preview: See template description
Apply: Template becomes active for file drops

Template Files¶

Edit: Manually edit YAML files for advanced customization
Share: Copy template files between users/systems
Version control: Track template changes over time

Pattern Matching System¶

Wildcard Support¶

The template system supports flexible pattern matching:

Basic Wildcards¶

* - Matches any sequence of characters
? - Matches any single character

Pattern Examples¶

# Exact matching
"Frequency"           # Matches only "Frequency"

# Prefix matching  
"Voltage*"           # Matches "Voltage_Bus_1", "Voltage_Line_A"

# Suffix matching
"*_Current"          # Matches "Line_Current", "Load_Current"

# Contains matching
"*Power*"            # Matches "Real_Power_Out", "Reactive_Power"

# Complex patterns
"Bus_*_Voltage_*"    # Matches "Bus_1_Voltage_A", "Bus_23_Voltage_B"

Matching Priority¶

When multiple patterns could match the same series: 1. Exact matches: Highest priority 2. Specific patterns: More specific patterns preferred 3. First match: First matching pattern in template order

Case Sensitivity¶

Case insensitive: Pattern matching ignores case differences
Flexible: "voltage" matches "Voltage", "VOLTAGE", "VoLtAgE"

Using Templates¶

Template Application¶

Select template: Choose template from dropdown
Load files: Load data files normally
Drag files: Drag file widgets to subplot area (not individual subplots)
Auto-distribution: Series automatically distributed based on template patterns

Manual Template Application¶

For files already loaded: 1. Select template: Choose template from dropdown 2. Drag file widget: Drag entire file widget to subplot area 3. Pattern matching: System matches series to template patterns 4. Distribution: Series placed in appropriate subplots

Template Feedback¶

The system provides feedback during template application: - Success notifications: "Template Applied" with match count - No matches: "No Matches" if no series match patterns - Error handling: Clear error messages for template issues

Advanced Template Features¶

Data Transformations¶

Templates can include automatic data transformations:

subplots:
  - position: [0, 0]
    series_names:
      - "Voltage*"
    transformations:
      - series_pattern: "Voltage*"
        operation: "multiply_y"
        value: 100.0        # Convert pu to percentage
      - series_pattern: "Time*"
        operation: "multiply_x"  
        value: 1000.0       # Convert seconds to milliseconds

Transformation Types¶

multiply_x: Multiply X (time) values
multiply_y: Multiply Y (data) values
add_x: Add offset to X values
add_y: Add offset to Y values

Template Inheritance¶

Future enhancement possibilities: - Base templates: Common configurations shared across templates - Template variants: Slight modifications of base templates - Template libraries: Collections of related templates

Template Best Practices¶

Pattern Design¶

Specific patterns: Use specific patterns to avoid unintended matches
Consistent naming: Maintain consistent data series naming conventions
Test patterns: Verify patterns match expected series

Template Organization¶

Descriptive names: Use clear, descriptive template names
Document purpose: Include meaningful descriptions
Version control: Track template versions for important workflows

File Naming Conventions¶

To maximize template effectiveness: - Consistent structure: Use consistent column naming across files - Logical grouping: Group related measurements with common patterns - Avoid special characters: Stick to letters, numbers, underscores

Template Development Workflow¶

1. Analysis Design¶

Define objectives: What analysis do you want to perform?
Identify patterns: What measurements are common across datasets?
Plan layout: How should subplots be arranged?

2. Manual Setup¶

Create layout: Manually set up the desired subplot grid
Add sample data: Use representative data files
Refine layout: Adjust titles, labels, and organization

3. Pattern Extraction¶

Identify patterns: Look for common naming patterns in your data
Design wildcards: Create patterns that match related series
Test matching: Verify patterns match expected series

4. Template Creation¶

Capture configuration: Save the manual setup as template
Document template: Add clear name and description
Version template: Track template versions for important workflows

5. Template Validation¶

Test with multiple files: Apply template to different datasets
Verify matches: Ensure patterns match intended series
Refine patterns: Adjust patterns based on testing results

Troubleshooting Templates¶

Common Issues¶

No Series Matched¶

Problem: Template applied but no series were placed Solutions: 1. Check patterns: Verify wildcard patterns match your data 2. Case sensitivity: Patterns are case-insensitive 3. File expansion: Ensure files are expanded in sidebar 4. Data format: Verify files loaded correctly

Wrong Series Placement¶

Problem: Series placed in unexpected subplots Solutions: 1. Pattern specificity: Make patterns more specific 2. Pattern order: Reorder patterns in template 3. Multiple matches: Check if series matches multiple patterns

Template Load Failures¶

Problem: Template won't load or apply Solutions: 1. YAML syntax: Validate YAML file syntax 2. File permissions: Check template file permissions 3. Template format: Verify template follows expected format

Debugging Templates¶

Pattern testing: Test patterns on sample data first
Console output: Check console for template matching debug info
Template validation: Manually review YAML files for syntax errors

Next Steps¶

Master the templating system and then explore: 1. Annotations & Markup 2. Data Transformations 3. Advanced Configuration

Template tip: Start simple with basic patterns and gradually add complexity as you understand your data naming conventions