candle-annotator/span-annotation-prompt.md

Span Annotation Feature for Candlestick Pattern Labeling Tool

What is Span Annotation?

Span annotation means selecting a range of consecutive candles on a candlestick chart that together form a recognizable pattern (e.g., bull flag, head and shoulders, double bottom). The user clicks a start candle and an end candle, assigns a pattern label, and optionally adds metadata. This is the standard approach for labeling multi-candle patterns in time series data.

User Interaction Flow

1. User enters annotation mode (toggle or hotkey)
2. User clicks a candle → that candle is highlighted as the span start
3. User clicks a second candle → that becomes the span end
4. A label selector appears (dropdown or palette) with the user's predefined pattern categories
5. Optionally, user can add:
   • Sub-spans (e.g., mark the "pole" and "flag" portions within a bull flag)
   • Outcome (win/loss/breakeven, or the price move after the pattern)
   • Confidence (how clear the pattern is, 1-5 scale)
   • Free-text notes
6. The annotation is saved and visually rendered on the chart as a highlighted region with a label tag
7. User can click an existing annotation to edit or delete it
8. Annotations persist and are exportable

Visual Rendering of Annotations

• Draw a semi-transparent colored rectangle behind the candles in the span range (color per label category)
• Show the label name as a small tag above or below the highlighted region
• Sub-spans get a slightly different shade or a thin divider line within the main span
• Overlapping annotations should be visually distinguishable (offset vertically or use border styles)

Annotation Data Model

Each annotation is a JSON object:

{
  "id": "uuid-v4",
  "pair": "EURUSD",
  "timeframe": "1H",
  "start_time": "2024-03-15T09:00:00Z",
  "end_time": "2024-03-15T16:00:00Z",
  "start_index": 142,
  "end_index": 149,
  "label": "bull_flag",
  "sub_spans": [
    {
      "label": "pole",
      "start_time": "2024-03-15T09:00:00Z",
      "end_time": "2024-03-15T12:00:00Z"
    },
    {
      "label": "consolidation",
      "start_time": "2024-03-15T12:00:00Z",
      "end_time": "2024-03-15T16:00:00Z"
    }
  ],
  "outcome": "win",
  "confidence": 4,
  "notes": "clean breakout on volume",
  "created_at": "2024-03-16T10:30:00Z"
}

Export Formats for ML Training

The tool must export annotations in multiple formats to support different model types. All exports should be triggered from a single "Export" button with format selection.

---

Format 1: Windowed Classification (CSV)

One row per annotation. Used for training classifiers (XGBoost, CNN, LSTM) where each row is a labeled window of OHLC data.

pair,timeframe,start_time,end_time,label,outcome,confidence,window_length,open_0,high_0,low_0,close_0,volume_0,open_1,high_1,low_1,close_1,volume_1,...
EURUSD,1H,2024-03-15T09:00:00Z,2024-03-15T16:00:00Z,bull_flag,win,4,8,1.0921,1.0935,1.0918,1.0933,1200,1.0933,1.0948,1.0930,1.0945,1500,...

The OHLCV columns are flattened: open_0 through close_N where N is the number of candles in the span. Pad shorter spans with NaN or truncate/resample to a fixed window size (user-configurable, e.g., 20 candles).

---

Format 2: Sequence Labels / BIO Tags (CSV)

One row per candle across the entire dataset. Used for sequence labeling models (BiLSTM-CRF, Transformer encoder). Uses BIO tagging scheme:

• B-{label} = first candle of a pattern
• I-{label} = inside a pattern (continuation)
• O = outside any pattern (no pattern)

time,open,high,low,close,volume,bio_tag
2024-03-15T08:00:00Z,1.0915,1.0922,1.0910,1.0918,980,O
2024-03-15T09:00:00Z,1.0921,1.0935,1.0918,1.0933,1200,B-bull_flag
2024-03-15T10:00:00Z,1.0933,1.0948,1.0930,1.0945,1500,I-bull_flag
2024-03-15T11:00:00Z,1.0944,1.0950,1.0938,1.0941,1100,I-bull_flag
...
2024-03-15T16:00:00Z,1.0939,1.0960,1.0937,1.0958,1800,I-bull_flag
2024-03-15T17:00:00Z,1.0958,1.0965,1.0950,1.0962,900,O

For overlapping annotations, use multi-label columns: bio_tag_1, bio_tag_2, etc.

---

Format 3: Raw Annotations JSON

The complete annotation list as-is, for custom pipelines or re-import.

{
  "metadata": {
    "pair": "EURUSD",
    "timeframe": "1H",
    "export_date": "2024-03-20T12:00:00Z",
    "total_annotations": 47,
    "label_counts": {
      "bull_flag": 12,
      "head_and_shoulders": 8,
      "double_bottom": 15,
      "wedge": 12
    }
  },
  "annotations": [
    { ... annotation objects as defined above ... }
  ]
}

---

Notes

Format 2 (BIO tags) is probably the most versatile starting point — it works directly with sequence models and you can always derive Format 1 (windowed) from it by slicing. Format 1 (windowed CSV) is what you'd feed directly into XGBoost or a CNN. If you start with just one export format, go with the raw JSON (Format 3) since you can always transform it into the others with a script.

Make sure the export includes context candles — e.g., 10-20 candles before and after each pattern span. Models need to see the trend leading into the pattern, not just the pattern itself. You might want a configurable context_padding parameter on export.

Label Configuration

The user should be able to define their own pattern categories in a config, e.g.:

{
  "labels": [
    { "name": "bull_flag", "color": "#4CAF50", "hotkey": "1" },
    { "name": "bear_flag", "color": "#F44336", "hotkey": "2" },
    { "name": "head_and_shoulders", "color": "#FF9800", "hotkey": "3" },
    { "name": "double_bottom", "color": "#2196F3", "hotkey": "4" },
    { "name": "wedge_up", "color": "#9C27B0", "hotkey": "5" },
    { "name": "wedge_down", "color": "#795548", "hotkey": "6" },
    { "name": "custom", "color": "#607D8B", "hotkey": "0" }
  ]
}

Summary of Requirements

• Click-to-select span annotation on a TradingView Lightweight Charts candlestick chart
• Label assignment via dropdown or hotkey
• Optional sub-spans, outcome, confidence, notes
• Visual overlay of annotations on the chart
• Edit/delete existing annotations
• Export to: Windowed CSV, BIO-tagged CSV, Raw JSON, and optionally image crops
• User-configurable label categories with colors and hotkeys