popov/gogo2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
70e8ede8d366b5e7594a4f1491dfe297c700d11b
gogo2/ANNOTATE/USAGE_GUIDE.md
Dobromir Popov b8f54e61fa remove emojis from console
2025-10-25 16:35:08 +03:00

7.4 KiB
Raw Blame History

ANNOTATE - Usage Guide

🎯 Quick Start

Starting the Application

python ANNOTATE/web/app.py

Access at: http://127.0.0.1:8051

📊 Creating Annotations

Method 1: Click to Mark (Recommended)

  1. Navigate to the time period you want to annotate
  2. Click on the chart at the entry point
    • You'll see "Entry marked" status
    • A temporary marker appears
  3. Click again at the exit point
    • Annotation is saved automatically
    • Visual markers appear: ▲ (entry) and ▼ (exit)
    • P&L percentage is calculated and displayed

What Gets Captured

When you create an annotation, the system captures:

  • Entry timestamp and price
  • Exit timestamp and price
  • Full market state (OHLCV for all 4 timeframes)
  • Direction (LONG/SHORT)
  • P&L percentage
  • Market context at both entry and exit

This ensures the annotation contains exactly the same data your models will see during training!

✏️ Editing Annotations

Method 1: Click on P&L Label

  1. Click the P&L label (the percentage with 🗑️ icon)
  2. Choose action:
    • 1 - Move entry point
    • 2 - Move exit point
    • 3 - Delete annotation

Method 2: From Sidebar

  1. Find annotation in the right sidebar
  2. Click the eye icon (👁️) to view
  3. Click the trash icon (🗑️) to delete

Moving Entry/Exit Points

  1. Click on annotation → Choose "1" or "2"
  2. The current point is removed
  3. The other point stays as reference (grayed out)
  4. Click on chart to set new position
  5. Annotation is updated automatically

🎨 Visual Indicators

On Charts

  • ▲ Green Triangle = LONG entry point
  • ▲ Red Triangle = SHORT entry point
  • ▼ Green Triangle = LONG exit point
  • ▼ Red Triangle = SHORT exit point
  • Dashed Line = Connects entry to exit
  • P&L Label = Shows profit/loss percentage
  • 🗑️ Icon = Click to edit/delete

Color Coding

  • Green = LONG trade (buy low, sell high)
  • Red = SHORT trade (sell high, buy low)
  • Positive P&L = Green text
  • Negative P&L = Red text

🗂️ Managing Annotations

Viewing All Annotations

  • Right sidebar shows all annotations
  • Sorted by creation time
  • Shows: Direction, Timeframe, P&L, Timestamp

Filtering

  • Annotations are grouped by symbol
  • Switch symbols using the dropdown

Exporting

  1. Click download button at top of annotation list
  2. All annotations exported to JSON file
  3. File includes full market context

📦 Generating Test Cases

Automatic Generation

When you save an annotation, the system:

  1. Captures market state at entry time
  2. Captures market state at exit time
  3. Stores OHLCV data for all timeframes
  4. Calculates expected outcome (P&L, direction)

Manual Generation

  1. Find annotation in sidebar
  2. Click file icon (📄)
  3. Test case generated and saved to: 
    ANNOTATE/data/test_cases/annotation_<id>.json

Test Case Format

{
  "test_case_id": "annotation_uuid",
  "symbol": "ETH/USDT",
  "timestamp": "2024-01-15T10:30:00Z",
  "action": "BUY",
  "market_state": {
    "ohlcv_1s": { /* 100 candles */ },
    "ohlcv_1m": { /* 100 candles */ },
    "ohlcv_1h": { /* 100 candles */ },
    "ohlcv_1d": { /* 100 candles */ }
  },
  "expected_outcome": {
    "direction": "LONG",
    "profit_loss_pct": 2.5,
    "entry_price": 2400.50,
    "exit_price": 2460.75
  }
}

⌨️ Keyboard Shortcuts

  • ← Left Arrow = Navigate backward in time
  • → Right Arrow = Navigate forward in time
  • Space = Mark point (when chart focused)
  • Esc = Cancel pending annotation

🎯 Best Practices

1. Be Selective

  • Only mark clear, high-confidence trades
  • Quality > Quantity
  • Look for obvious patterns

2. Use Multiple Timeframes

  • Check all 4 timeframes before marking
  • Confirm pattern across timeframes
  • Look for confluence

3. Document Your Reasoning

  • Add notes to annotations (future feature)
  • Explain why you marked the trade
  • Note key indicators or patterns

4. Review Before Generating

  • Verify entry/exit points are correct
  • Check P&L calculation makes sense
  • Ensure market context is complete

5. Organize by Strategy

  • Group similar trade types
  • Use consistent marking criteria
  • Build a library of patterns

🔧 Troubleshooting

Clicks Not Working

  • Issue: Chart clicks don't register
  • Solution:
    • Make sure you're clicking on the candlestick (not volume bars)
    • Click on the body or wick of a candle
    • Avoid clicking on empty space

Annotations Not Appearing

  • Issue: Saved annotations don't show on charts
  • Solution:
    • Refresh the page
    • Check the correct symbol is selected
    • Verify annotation is for the visible timeframe

Can't Edit Annotation

  • Issue: Edit mode not working
  • Solution:
    • Click directly on the P&L label (percentage text)
    • Or use the sidebar icons
    • Make sure annotation mode is enabled

Market Context Missing

  • Issue: Test case has empty market_state
  • Solution:
    • Ensure DataProvider has cached data
    • Check timestamp is within available data range
    • Verify all timeframes have data

💡 Tips & Tricks

Tip 1: Quick Navigation

Use the quick range buttons (1h, 4h, 1d, 1w) to jump to different time periods quickly.

Tip 2: Zoom for Precision

  • Scroll wheel to zoom in/out
  • Drag to pan
  • Get precise entry/exit points

Tip 3: Check All Timeframes

Before marking, scroll through all 4 charts to confirm the pattern is valid across timeframes.

Tip 4: Start with Recent Data

Begin annotating recent data where you remember the market conditions clearly.

Tip 5: Batch Export

Export annotations regularly to backup your work.

📊 Data Consistency

Why It Matters

The annotation system uses the same DataProvider as your training and inference systems. This means:

Same data source
Same data quality
Same data structure
Same timeframes
Same caching

What This Guarantees

When you train a model on annotated data:

  • The model sees exactly what you saw
  • No data discrepancies
  • No format mismatches
  • Perfect consistency

🎓 Example Workflow

Scenario: Mark a Breakout Trade

  1. Navigate to ETH/USDT on 2024-01-15
  2. Identify a breakout pattern on 1m chart
  3. Confirm on 1h chart (uptrend)
  4. Click at breakout point: $2400.50 (10:30:00)
  5. Click at target: $2460.75 (10:35:00)
  6. Result: LONG trade, +2.51% P&L
  7. Verify: Check all timeframes show the pattern
  8. Generate: Click file icon to create test case
  9. Train: Use test case to train model

📝 Storage Locations

Annotations

ANNOTATE/data/annotations/annotations_db.json

Test Cases

ANNOTATE/data/test_cases/annotation_<id>.json

Exports

ANNOTATE/data/annotations/export_<timestamp>.json

Next Steps

After creating annotations:

  1. Generate test cases for all annotations
  2. Review test cases to verify market context
  3. Train models using the test cases
  4. Evaluate performance with inference simulation
  5. Iterate - mark more trades, refine patterns

📞 Support

For issues or questions:

  • Check ANNOTATE/README.md for technical details
  • Review ANNOTATE/IMPLEMENTATION_SUMMARY.md for architecture
  • See ANNOTATE/STATUS.md for current status

Happy Annotating! 🎉