---
title: "ASCII Plotting"
description: "Terminal-native chart rendering for CLI tools, Claude Code, and headless environments"
icon: "terminal"
---

Render backtest data as ASCII art directly in the terminal. Works with the frozen dataclasses from the [Plot Data](/plotting) module - no matplotlib, no GUI, no external dependencies.

<CardGroup cols={3}>
  <Card title="Line Charts" icon="chart-line">
    Time-series with Bresenham line drawing
  </Card>
  <Card title="Area Charts" icon="water">
    Filled regions for drawdowns and underwater curves
  </Card>
  <Card title="Histograms" icon="chart-bar">
    Horizontal bar charts from HistogramData
  </Card>
  <Card title="Heatmaps" icon="table-cells">
    Shaded block characters for correlation and monthly returns
  </Card>
  <Card title="Scatter Plots" icon="bullseye">
    Buy/sell markers with triangle glyphs
  </Card>
  <Card title="Dashboard" icon="objects-column">
    Full PlotBundle rendered as a multi-section report
  </Card>
</CardGroup>

## Quick Start

```python
import horizon as hz

result = hz.backtest(strategy, ...)
bundle = hz.from_backtest(result)
print(hz.dashboard(bundle))
```

Output:

```
═══════════════════════════════════════════════════════════════════════
  EQUITY (normalized to 1.0)

    1.49 │                                                 ···
    1.39 │                                           ·····
    1.29 │                                     ·····
    1.19 │                              ······
    1.09 │                       ·····
    0.99 │·····················
         └────────────────────────────────────────────────────

═══════════════════════════════════════════════════════════════════════
  DRAWDOWN (%)

       0 │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
    -2.5 │░░░░░░░░░░░░░░░░░░░░
         └────────────────────────────────────────────────────
```

## Individual Charts

### `line_chart`

```python
print(hz.line_chart(timestamps, values, width=72, height=18, title="Price"))
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `timestamps` | `Sequence[float]` | required | X-axis values |
| `values` | `Sequence[float]` | required | Y-axis values |
| `width` | `int` | `72` | Chart width in characters |
| `height` | `int` | `18` | Chart height in rows |
| `title` | `str` | `""` | Title above chart |
| `marker` | `str` | `"·"` | Character for line drawing |

### `multi_line`

Overlay multiple series with different markers.

```python
print(hz.multi_line([
    (ts, sharpe_vals, "Sharpe", "·"),
    (ts, sortino_vals, "Sortino", "×"),
], title="Rolling Metrics"))
```

### `area_chart`

Filled area from the line down to the bottom axis.

```python
neg_dd = [-d for d in bundle.underwater.drawdown_pct]
print(hz.area_chart(bundle.underwater.timestamps, neg_dd, title="Drawdown"))
```

### `bar_chart`

Horizontal bars with labels.

```python
print(hz.bar_chart(
    ["Strategy A", "Strategy B", "Strategy C"],
    [12.5, -3.2, 8.7],
    title="Returns (%)",
))
```

### `histogram_chart`

Render a `HistogramData` from the plotting module.

```python
h = hz.return_distribution(equity_curve)
print(hz.histogram_chart(h, title="Return Distribution"))
```

### `ascii_heatmap`

Render a `HeatmapData` using shade characters: ` ░ ▒ ▓ █`.

```python
hm = hz.monthly_returns_heatmap(equity_curve)
print(hz.ascii_heatmap(hm))
```

### `ascii_scatter`

Render a `TradeScatterData` with `▲` (buy) and `▼` (sell) markers.

```python
ts = hz.trade_scatter(trades)
print(hz.ascii_scatter(ts))
```

### `ascii_calibration`

Render a `CalibrationPlotData` with perfect line (`·`) and actual points (`●`).

```python
cal = hz.calibration_plot(trades, outcomes)
print(hz.ascii_calibration(cal))
```

### `sparkline`

Compact single-row chart using Unicode block elements.

```python
print(hz.sparkline(values, width=40))
# ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇█▇▅▃▂▁▂▃▅▇█▇▅▃▂▁▂▃▅▇█▇▅▃▂
```

### `dashboard`

Render an entire `PlotBundle` as a multi-section ASCII report.

```python
bundle = hz.from_backtest(result)
print(hz.dashboard(bundle, width=72, height=16))
```

Includes: equity curve, drawdown, return distribution, PnL distribution, rolling metrics, monthly heatmap, trade scatter, and calibration (when available).

## Use Cases

- **Claude Code / AI agents**: Get visual feedback without leaving the terminal
- **CI/CD pipelines**: Embed charts in build logs
- **SSH sessions**: Visualize on remote machines without X forwarding
- **Logging**: Append charts to strategy log files
- **Notebooks**: Quick preview before rendering with matplotlib
