Research Workflow

Cell 1: import packages

import matplotlib.pyplot as plt
import pandas as pd

These imports come from the Python environment selected when mlab notebook started.

Cell 2: choose a historical range

history = mlab.history(
    start="2026-08-01",
    end="2026-08-20",
)

start and end accept UTC dates or UTC date-times:

history = mlab.history(
    start="2026-08-01 09:30:00",
    end="2026-08-01 16:00:00",
)

The range is validated immediately. No market data is fetched until a cell requests a source.

Cell 3: fetch a source

CANDLES = "btc@candles@hyperliquidf:timeframe=3600"
candles = history.source(CANDLES)

Notebook history accepts the same exact selectors as Python V2. The first call fetches and normalizes the requested range. Repeated calls for the same selector use the history object's memory cache.

The result is a normal Python list of dictionaries ordered from oldest to newest.

Read individual records with the same indexing convention as Python V2:

latest = history.source(CANDLES, 0)
previous = history.source(CANDLES, 1)

Index 0 is the newest record. An unavailable index returns None.

Cell 4: analyze with pandas

df = pd.DataFrame(candles)
df["return"] = df["c"].pct_change()
df["sma_20"] = df["c"].rolling(20).mean()
df.tail()

Notebook history returns the complete requested range. It does not use the rolling lookback limit applied to Python strategy files.

Cell 5: use Market Lab studies

Notebook studies use mlab.study:

sma = mlab.study.sma(candles, {"field": "c", "window": 20})
sma["latest"]

Available helpers:

sma
ema
cvd
spread
depth
imbalance
slippage
vamp

They run the same Rust calculations used by Python V2 and the Market Lab CLI. See Built-In Functions for their input and return shapes; use mlab.study where those plain-file examples use ctx.study.

Cell 6: plot the result

fig, ax = plt.subplots(figsize=(12, 5))
ax.plot(df["t"], df["c"], label="BTC close")
ax.plot(df["t"], df["sma_20"], label="20-period SMA")
ax.legend()
plt.show()

Refresh cached data

Clear one selector and fetch it again:

history.clear(CANDLES)
candles = history.source(CANDLES)

Clear every selector cached by the history object:

history.clear()

Each new mlab.history(...) object has its own range and cache.

Read How It Works for the kernel bridge and current notebook boundaries.