Skip to content

Visualization Features Documentation

Version: 1.0
Date: 2025-01-27
Tasks: VIZ-002, VIZ-003, VIZ-004, VIZ-005, VIZ-008

Overview

This document describes the comprehensive Django web visualization interface for the DSTA trading system. The implementation includes portfolio management, performance analytics, strategy comparison, price charts, and trade journal functionality.

Implemented Features

1. Portfolio Overview (TASK-VIZ-002)

Purpose: Real-time portfolio monitoring with position tracking and P&L analysis.

Components: - Views: src/api/views/portfolio/overview.py - Templates: src/api/templates/portfolio/overview.html, positions.html - URLs: - /api/portfolio/ - Portfolio overview dashboard - /api/portfolio/positions/ - Detailed positions view - /api/portfolio/data/ - Real-time data API endpoint

Features: - Real-time portfolio value calculation - Open positions tracking with unrealized P&L - Win rate and performance statistics - Auto-refresh every 30 seconds - Filterable positions by status, exchange, symbol

Usage Example: 

# Access portfolio overview
http://localhost:8000/api/portfolio/

# Get real-time portfolio data via API
import requests
response = requests.get('http://localhost:8000/api/portfolio/data/')
data = response.json()
print(f"Total Value: ${data['total_value']}")
print(f"Total P&L: ${data['total_pnl']}")

2. Performance Charts (TASK-VIZ-003)

Purpose: Comprehensive performance analytics with interactive charts.

Components: - Utilities: src/analytics/charts.py - Views: src/api/views/charts/performance.py - Templates: src/api/templates/charts/performance.html - URL: /api/charts/performance/

Available Charts: 1. Equity Curve - Shows portfolio value over time with drawdown overlay 2. Returns Distribution - Histogram of returns with normal distribution overlay 3. Monthly Returns Heatmap - Color-coded monthly performance 4. Rolling Sharpe Ratio - 252-day rolling Sharpe ratio 5. Drawdown Analysis - Detailed drawdown visualization

Chart Functions: 

from analytics.charts import (
    create_equity_curve_chart,
    create_returns_distribution,
    create_monthly_returns_heatmap,
    create_rolling_sharpe_chart,
    create_drawdown_chart
)

# Create equity curve
import pandas as pd
equity_data = pd.DataFrame({
    'timestamp': pd.date_range('2024-01-01', periods=100),
    'equity': range(100000, 110000, 100)
})
chart_html = create_equity_curve_chart(equity_data, show_drawdown=True)

Statistics Provided: - Total trades - Winning/losing trades - Win rate percentage - Average win/loss - Profit factor - Maximum drawdown - Total P&L

3. Strategy Comparison (TASK-VIZ-004)

Purpose: Side-by-side comparison of multiple trading strategies.

Components: - Views: src/api/views/strategy/comparison.py - Templates: src/api/templates/strategy/comparison.html - URL: /api/comparison/

Features: - Multi-strategy selection - Side-by-side metrics comparison - Overlay equity curves - Export to CSV/JSON

Metrics Compared: - Total trades - Win rate - Total P&L - Average win/loss - Profit factor

Usage Example: 

# Compare strategies via URL
http://localhost:8000/api/comparison/?strategies=Strategy%20A&strategies=Strategy%20B

# Export comparison to CSV
http://localhost:8000/api/comparison/?export=csv&strategies=Strategy%20A

4. Price Charts (TASK-VIZ-005)

Purpose: Interactive candlestick charts with technical indicators.

Components: - Utilities: src/analytics/price_charts.py - Views: src/api/views/charts/price_chart.py - Templates: src/api/templates/charts/price.html - URL: /api/charts/price/

Supported Indicators: - Simple Moving Average (SMA) - Exponential Moving Average (EMA) - Relative Strength Index (RSI) - Bollinger Bands - MACD

Features: - Interactive candlestick charts using Plotly - Multiple timeframes (1m, 5m, 15m, 1h, 4h, 1d) - Trade entry/exit markers - Volume overlay - Customizable date range

Usage Example: 

from analytics.price_charts import (
    create_candlestick_chart,
    calculate_sma,
    calculate_rsi
)

# Load OHLCV data
ohlcv_df = pd.DataFrame({
    'timestamp': pd.date_range('2024-01-01', periods=100),
    'open': np.random.rand(100) * 50000 + 45000,
    'high': np.random.rand(100) * 50000 + 46000,
    'low': np.random.rand(100) * 50000 + 44000,
    'close': np.random.rand(100) * 50000 + 45000,
    'volume': np.random.rand(100) * 1000
})

# Calculate indicators
indicators = {
    'SMA_20': calculate_sma(ohlcv_df['close'], 20),
    'RSI': calculate_rsi(ohlcv_df['close'], 14)
}

# Create chart
chart_html = create_candlestick_chart(
    ohlcv_df,
    symbol='BTCUSDT',
    indicators=indicators
)

URL Parameters: - symbol - Trading pair (e.g., BTCUSDT) - exchange - Exchange name (binance, huobi, gateio) - interval - Timeframe (1m, 5m, 15m, 1h, 4h, 1d) - days - Number of days to display - sma20, sma50, ema12, rsi - Enable/disable indicators - trades - Show trade markers

5. Trade Journal (TASK-VIZ-008)

Purpose: Comprehensive trade logging with notes and analysis.

Components: - Model: TradeJournal in src/api/models.py - Forms: src/api/forms/trade_journal.py - Views: src/api/views/journal/trade_journal.py - Templates: src/api/templates/journal/ - URLs: - /api/journal/ - List all trades - /api/journal/create/ - Create new entry - /api/journal/<id>/ - Trade detail - /api/journal/<id>/edit/ - Edit entry - /api/journal/<id>/delete/ - Delete entry

Database Schema: 

class TradeJournal(models.Model):
    # Identification
    exchange = CharField(max_length=20)
    symbol = CharField(max_length=20)
    direction = CharField(choices=['long', 'short'])
    status = CharField(choices=['open', 'closed', 'cancelled'])

    # Entry details
    entry_timestamp = DateTimeField()
    entry_price = DecimalField()
    quantity = DecimalField()

    # Exit details
    exit_timestamp = DateTimeField(null=True)
    exit_price = DecimalField(null=True)

    # Performance
    pnl = DecimalField(null=True)
    pnl_percent = DecimalField(null=True)
    commission = DecimalField(null=True)

    # Context
    strategy_name = CharField(max_length=100)
    tags = JSONField(default=list)

    # Notes
    entry_notes = TextField()
    exit_notes = TextField()
    post_trade_analysis = TextField()

    # Market conditions
    market_conditions = JSONField(null=True)

Features: - Complete trade lifecycle tracking - Manual notes and analysis - Tagging and categorization - Advanced filtering and search - CSV export - Automatic P&L calculation

Usage Example: 

from api.models import TradeJournal
from decimal import Decimal
from django.utils import timezone

# Create trade entry
trade = TradeJournal.objects.create(
    exchange='binance',
    symbol='BTCUSDT',
    direction='long',
    status='open',
    entry_timestamp=timezone.now(),
    entry_price=Decimal('50000.00'),
    quantity=Decimal('1.0'),
    strategy_name='Momentum Strategy',
    entry_notes='Strong momentum signal on daily chart',
    tags=['momentum', 'breakout']
)

# Close trade
trade.exit_timestamp = timezone.now()
trade.exit_price = Decimal('51000.00')
trade.status = 'closed'
trade.exit_notes = 'Target reached'
trade.commission = Decimal('10.00')
trade.save()

# Calculate P&L
trade.calculate_pnl()
print(f"P&L: ${trade.pnl}")
print(f"P&L %: {trade.pnl_percent}%")

# Export to CSV
http://localhost:8000/api/journal/?export=csv

Filtering Options: - Exchange - Symbol - Direction (long/short) - Status (open/closed/cancelled) - Strategy name - Date range - Text search in notes

Installation & Setup

1. Database Migration

cd /home/minhdqdev/Projects/dsta
python src/manage.py migrate

2. Dependencies

All required dependencies are already in requirements.txt: - Django 4.0 - djangorestframework 3.13.1 - pandas 1.3.5 - numpy 1.21.4 - plotly (via CDN in templates)

3. Static Files

Charts use CDN-hosted libraries: - Plotly.js 2.27.0 - Chart.js 4.4.0 - Bootstrap 5.3.0 - Font Awesome 6.4.0

API Endpoints

Portfolio API

GET /api/portfolio/data/
Response: {
    "timestamp": "2025-01-27T12:00:00Z",
    "total_value": 150000.00,
    "total_pnl": 5000.00,
    "positions_count": 3,
    "positions": [
        {
            "id": 1,
            "symbol": "BTCUSDT",
            "direction": "long",
            "entry_price": 50000.00,
            "current_price": 51000.00,
            "quantity": 1.0,
            "unrealized_pnl": 1000.00,
            "unrealized_pnl_percent": 2.0
        }
    ],
    "equity_curve": [...]
}

Strategy Comparison Export

GET /api/comparison/?export=csv&strategies=Strategy1&strategies=Strategy2
Response: CSV file with comparison metrics

Trade Journal Export

GET /api/journal/?export=csv
Response: CSV file with all trades

Testing

Run the comprehensive test suite:

# Run all visualization tests
pytest tests/api/views/test_visualization.py -v

# Run specific test classes
pytest tests/api/views/test_visualization.py::TradeJournalModelTests -v
pytest tests/api/views/test_visualization.py::ChartUtilityTests -v
pytest tests/api/views/test_visualization.py::PortfolioViewTests -v

Test Coverage: - TradeJournal model tests (10 tests) - Form validation tests (2 tests) - Portfolio view tests (3 tests) - Chart utility tests (4 tests) - Price chart utility tests (5 tests) - Strategy comparison tests (2 tests) - Trade journal view tests (4 tests) - Integration tests (1 test)

Total: 31 comprehensive tests

Performance Considerations

Chart Rendering

  • Charts use Plotly's CDN for fast loading
  • HTML-only rendering (no Python-side rendering)
  • Client-side interactivity

Database Queries

  • Indexed fields for fast lookups
  • Pagination for large datasets (50 items per page)
  • Efficient aggregations using Django ORM

Real-time Updates

  • Portfolio data auto-refreshes every 30 seconds
  • AJAX calls to minimize page reloads
  • Lightweight JSON responses

Future Enhancements

  1. WebSocket Integration - Real-time portfolio updates
  2. Advanced Filtering - More complex trade journal queries
  3. Custom Chart Configurations - User-defined chart preferences
  4. Performance Benchmarking - Compare against market indices
  5. Mobile Responsiveness - Optimized mobile views
  6. Export to Excel - Enhanced export with formatting
  7. Automated Trade Import - Import trades from exchanges

Troubleshooting

No Data in Charts

  • Ensure you have closed trades with P&L calculated
  • Check that trade timestamps are valid
  • Verify database contains candlestick data for price charts

Charts Not Rendering

  • Check browser console for JavaScript errors
  • Verify CDN links are accessible
  • Ensure Plotly.js is loaded

Migration Issues

# If migration fails, check existing migrations
python src/manage.py showmigrations

# Reset if needed (development only)
python src/manage.py migrate api zero
python src/manage.py migrate

Contact & Support

For issues or questions: - GitHub Issues: https://github.com/minhdqdev/dsta/issues - Project Documentation: /docs/

Status: ✅ All 5 visualization tasks completed
Lines of Code: ~15,000
Test Coverage: 31 comprehensive tests
Documentation: Complete