# Temporal Analysis

The `temporal_analyze` command computes grouped statistics (returns, volatility, volume) by time period—day of week, hour of day, or calendar month. Use it to discover session effects, optimal trading windows, and seasonal patterns.

**Related:**
- [CLI.md](CLI.md) — Command usage and output formats
- [GLOSSARY.md](GLOSSARY.md) — Term definitions
- [forecast/VOLATILITY.md](forecast/VOLATILITY.md) — Volatility estimation

---

## Quick Start

```bash
# Average returns by day of week
mtdata-cli temporal_analyze EURUSD --group-by dow --json

# Volatility by hour of day
mtdata-cli temporal_analyze EURUSD --group-by hour --lookback 2000 --json

# Monthly seasonality
mtdata-cli temporal_analyze EURUSD --timeframe D1 --group-by month --lookback 1000 --json
```

---

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `symbol` | (required) | Trading symbol |
| `--timeframe` | `H1` | Candle timeframe |
| `--lookback` | auto | Bars to analyze when `--start`/`--end` are omitted. Auto-derived per timeframe (floor 200, cap 20,000). |
| `--start` | (optional) | Start date (ISO or flexible format) |
| `--end` | (optional) | End date (ISO or flexible format) |
| `--group-by` | `dow` | Grouping: `dow` (day of week), `hour`, `month`, `session` (Asia/London/overlap/NY/off), `all` |
| `--day-of-week` | (optional) | Filter to a specific day (0–6 or name, e.g., `Mon`, `Friday`) |
| `--month` | (optional) | Filter to a specific month (1–12 or name, e.g., `Jan`, `September`) |
| `--time-range` | (optional) | Filter by time window `HH:MM-HH:MM` using a half-open interval `[start, end)` (wraps midnight, e.g., `22:00-02:00`) |
| `--return-mode` | `pct` | Return calculation: `pct` (percentage) or `log` (logarithmic) |

---

## Grouping Modes

### Day of Week (`--group-by dow`)

Shows performance by weekday. Useful for detecting day-of-week effects.

```bash
mtdata-cli temporal_analyze EURUSD --group-by dow --lookback 2000 --json
```

**Example output (simplified):**
```
group  bars  avg_return  volatility  win_rate  avg_volume
Mon     400   -0.012%     0.065%      48.2%     1250
Tue     400    0.008%     0.071%      51.0%     1380
Wed     400    0.015%     0.078%      52.5%     1420
Thu     400   -0.003%     0.074%      49.8%     1350
Fri     400    0.005%     0.062%      50.5%     1100
```

### Hour of Day (`--group-by hour`)

Shows performance by hour. Reveals session activity patterns.

```bash
mtdata-cli temporal_analyze EURUSD --group-by hour --lookback 5000 --json
```

Use `--time-range` to focus on a specific session:
```bash
# London session hours
mtdata-cli temporal_analyze EURUSD --group-by hour --time-range "08:00-16:00" --json

# Asian session (wraps midnight)
mtdata-cli temporal_analyze EURUSD --group-by hour --time-range "22:00-07:00" --json
```

`--time-range` is applied to candle open times. The start time is included and the end time is excluded, so `08:00-16:00` keeps bars stamped `08:00` through `15:59...` and excludes a bar stamped exactly `16:00`.

### Calendar Month (`--group-by month`)

Shows seasonal effects across months. Best with daily data and a long history.

```bash
mtdata-cli temporal_analyze EURUSD --timeframe D1 --group-by month --lookback 2000 --json
```

### Overall Summary (`--group-by all`)

Single aggregate summary across all bars.

```bash
mtdata-cli temporal_analyze EURUSD --group-by all --json
```

---

## Output Fields

Each group includes these statistics:

| Field | Description |
|-------|-------------|
| `group` | Group label (e.g., `Mon`, `14:00`, `Jan`) |
| `group_key` | Numeric group identifier |
| `bars` | Number of bars in group |
| `returns` | Count of return observations |
| `avg_return` | Average return (%) |
| `median_return` | Median return (%) |
| `volatility` | Standard deviation of returns |
| `avg_abs_return` | Average absolute return |
| `win_rate` | Percentage of bars with positive return |
| `avg_range` | Average high-low range |
| `avg_range_pct` | Average range as percentage of close |
| `avg_volume` | Average volume (real or tick) |

Top-level response also includes `overall` (summary statistics) and `volume_source` (whether `real_volume` or `tick_volume` was used).

---

## Filtering

Combine grouping with filters to drill down:

```bash
# Only Mondays, grouped by hour
mtdata-cli temporal_analyze EURUSD --group-by hour --day-of-week Mon --json

# Only January, grouped by day of week
mtdata-cli temporal_analyze EURUSD --timeframe D1 --group-by dow --month Jan --lookback 2000 --json

# London session hours, grouped by day of week
mtdata-cli temporal_analyze EURUSD --group-by dow --time-range "08:00-16:00" --json
```

---

## Practical Applications

### Find Best Trading Days
```bash
mtdata-cli temporal_analyze EURUSD --group-by dow --lookback 5000 --json
# Look for days with highest win_rate and positive avg_return
```

### Find Active Trading Hours
```bash
mtdata-cli temporal_analyze EURUSD --group-by hour --lookback 5000 --json
# Look for hours with highest avg_range_pct and avg_volume
```

### Seasonal Patterns
```bash
mtdata-cli temporal_analyze SPX500 --timeframe D1 --group-by month --lookback 3000 --json
# Compare monthly avg_return and volatility
```

---

## Quick Reference

| Task | Command |
|------|---------|
| Day-of-week stats | `mtdata-cli temporal_analyze EURUSD --group-by dow` |
| Hourly stats | `mtdata-cli temporal_analyze EURUSD --group-by hour` |
| Monthly seasonality | `mtdata-cli temporal_analyze EURUSD --timeframe D1 --group-by month` |
| Filter to Mondays | `mtdata-cli temporal_analyze EURUSD --group-by hour --day-of-week Mon` |
| London session only | `mtdata-cli temporal_analyze EURUSD --group-by hour --time-range "08:00-16:00"` |

---

## See Also

- [CLI.md](CLI.md) — Command usage
- [forecast/VOLATILITY.md](forecast/VOLATILITY.md) — Volatility estimation
- [GLOSSARY.md](GLOSSARY.md) — Term definitions
