---
name: analytics
description: "Performance attribution, trade analytics, and strategy optimization"
emoji: "📊"
---

# Analytics - Complete API Reference

Analyze trading performance with attribution by edge source, time-of-day analysis, and optimization insights.

---

## Chat Commands

### Performance Overview

```
/analytics                          Performance summary
/analytics today                    Today's performance
/analytics week                     Weekly breakdown
/analytics month                    Monthly breakdown
```

### Attribution

```
/analytics attribution              P&L by edge source
/analytics by-platform              P&L by platform
/analytics by-category              P&L by market category
/analytics by-strategy              P&L by strategy
```

### Time Analysis

```
/analytics best-times               Best trading hours
/analytics by-hour                  Hourly performance
/analytics by-day                   Day of week analysis
```

### Edge Analysis

```
/analytics edge-decay               How edge decays over time
/analytics edge-buckets             Performance by edge size
/analytics liquidity                Performance by liquidity
```

---

## TypeScript API Reference

### Create Analytics Service

```typescript
import { createAnalyticsService } from 'clodds/analytics';

const analytics = createAnalyticsService({
  // Data source
  tradesDb: './trades.db',

  // Time zone
  timezone: 'America/New_York',
});
```

### Performance Summary

```typescript
const summary = await analytics.getSummary({
  period: 'month',
  // or: from: '2024-01-01', to: '2024-01-31'
});

console.log('=== Performance ===');
console.log(`Total P&L: $${summary.totalPnl}`);
console.log(`Win Rate: ${summary.winRate}%`);
console.log(`Profit Factor: ${summary.profitFactor}`);
console.log(`Sharpe Ratio: ${summary.sharpeRatio}`);
console.log(`Total Trades: ${summary.totalTrades}`);
console.log(`Avg Trade: $${summary.avgTrade}`);
console.log(`Best Trade: $${summary.bestTrade}`);
console.log(`Worst Trade: $${summary.worstTrade}`);
```

### Attribution by Edge Source

```typescript
const attribution = await analytics.getAttribution('edgeSource');

for (const source of attribution) {
  console.log(`${source.name}:`);
  console.log(`  P&L: $${source.pnl}`);
  console.log(`  Trades: ${source.trades}`);
  console.log(`  Win Rate: ${source.winRate}%`);
  console.log(`  Contribution: ${source.contribution}%`);
}

// Example sources:
// - price_lag (stale prices)
// - liquidity_gap (thin orderbooks)
// - information (news/events)
// - model_edge (external models)
// - combinatorial (arbitrage)
```

### Time-of-Day Analysis

```typescript
const hourly = await analytics.getHourlyPerformance();

console.log('Best Hours:');
for (const hour of hourly.slice(0, 3)) {
  console.log(`  ${hour.hour}:00 - Win: ${hour.winRate}%, Avg: $${hour.avgPnl}`);
}

console.log('Worst Hours:');
for (const hour of hourly.slice(-3)) {
  console.log(`  ${hour.hour}:00 - Win: ${hour.winRate}%, Avg: $${hour.avgPnl}`);
}
```

### Day-of-Week Analysis

```typescript
const daily = await analytics.getDayOfWeekPerformance();

for (const day of daily) {
  console.log(`${day.name}: $${day.pnl} (${day.trades} trades, ${day.winRate}% win)`);
}
```

### Edge Decay Analysis

```typescript
const decay = await analytics.getEdgeDecay();

console.log('Edge Decay (how fast edge disappears):');
for (const bucket of decay) {
  console.log(`  ${bucket.holdTime}: ${bucket.avgReturn}% return`);
}
// Shows optimal hold time before edge decays
```

### Edge Size Buckets

```typescript
const edgeBuckets = await analytics.getEdgeBuckets();

for (const bucket of edgeBuckets) {
  console.log(`Edge ${bucket.min}-${bucket.max}%:`);
  console.log(`  Trades: ${bucket.trades}`);
  console.log(`  Win Rate: ${bucket.winRate}%`);
  console.log(`  Avg P&L: $${bucket.avgPnl}`);
  console.log(`  Realized Edge: ${bucket.realizedEdge}%`);
}
```

### Liquidity Analysis

```typescript
const liquidity = await analytics.getLiquidityAnalysis();

for (const bucket of liquidity) {
  console.log(`${bucket.name} liquidity:`);
  console.log(`  Trades: ${bucket.trades}`);
  console.log(`  Avg Slippage: ${bucket.avgSlippage}%`);
  console.log(`  Fill Rate: ${bucket.fillRate}%`);
  console.log(`  Avg P&L: $${bucket.avgPnl}`);
}
```

### Execution Quality

```typescript
const execution = await analytics.getExecutionQuality();

console.log('=== Execution Quality ===');
console.log(`Avg Slippage: ${execution.avgSlippage}%`);
console.log(`Fill Rate: ${execution.fillRate}%`);
console.log(`Avg Fill Time: ${execution.avgFillTimeMs}ms`);
console.log(`Partial Fills: ${execution.partialFillRate}%`);
console.log(`Rejected Orders: ${execution.rejectionRate}%`);
```

### Platform Comparison

```typescript
const platforms = await analytics.getPlatformComparison();

for (const platform of platforms) {
  console.log(`${platform.name}:`);
  console.log(`  P&L: $${platform.pnl}`);
  console.log(`  Win Rate: ${platform.winRate}%`);
  console.log(`  Avg Slippage: ${platform.avgSlippage}%`);
  console.log(`  Best For: ${platform.strengths.join(', ')}`);
}
```

### Export Report

```typescript
// Generate PDF report
await analytics.exportReport({
  format: 'pdf',
  period: 'month',
  include: ['summary', 'attribution', 'charts'],
  outputPath: './reports/january-2024.pdf',
});

// Export raw data
await analytics.exportData({
  format: 'csv',
  period: 'month',
  outputPath: './data/january-trades.csv',
});
```

---

## Attribution Categories

| Category | Description |
|----------|-------------|
| **Edge Source** | Where the edge came from |
| **Platform** | Which platform traded on |
| **Category** | Market category (politics, crypto) |
| **Strategy** | Which strategy generated trade |
| **Time** | Hour/day of trade |
| **Size** | Trade size bucket |

---

## Key Metrics

| Metric | Good Value | Description |
|--------|------------|-------------|
| **Win Rate** | > 50% | Percent of winning trades |
| **Profit Factor** | > 1.5 | Gross profit / gross loss |
| **Sharpe Ratio** | > 1.0 | Risk-adjusted returns |
| **Realized Edge** | > 0 | Actual vs expected edge |
| **Fill Rate** | > 95% | Orders fully filled |

---

## Best Practices

1. **Review weekly** — Catch problems early
2. **Track attribution** — Know where profits come from
3. **Optimize timing** — Trade your best hours
4. **Monitor edge decay** — Don't hold too long
5. **Check execution** — Slippage kills edge