307 lines
7.4 KiB
Markdown
307 lines
7.4 KiB
Markdown
# ANNOTATE - Usage Guide
|
|
|
|
## 🎯 Quick Start
|
|
|
|
### Starting the Application
|
|
```bash
|
|
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
|
|
```json
|
|
{
|
|
"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!** 🎉
|