quantlab.api

Frame-in, frame-out functions for callers who hold their own DataFrames.

quantlab.api lets a researcher with market data in a pandas or polars DataFrame use one quantlab capability without adopting the project’s stores and configs (ADR 0011). A function takes a frame, a DataFrame in long form with one row per timestamp and symbol, and returns a frame of the same library; as_xarray=True returns the library’s own xarray panel instead. Nothing is written to disk unless an output_dir is given.

The canonical columns are timestamp, symbol, open, high, low, close and volume, plus amount (traded value) where a function needs it. The columns argument maps differently named columns onto them. The input rules:

• a pandas (timestamp, symbol) MultiIndex is reset automatically;

• a repeated (timestamp, symbol) pair raises, listing the first ones;

• missing (timestamp, symbol) cells become NaN;

• timezone-aware timestamps are converted to UTC and made naive;

• symbols are converted to str.

Underneath, the frame becomes a quantlab.dataset.memory.FrameDataset, a market dataset held in memory, which advanced users can also plug into the full pipeline.

Examples

>>> import pandas as pd
>>> import quantlab.api as qa
>>> frame = pd.DataFrame({
...     "timestamp": pd.to_datetime(["2024-01-02", "2024-01-02", "2024-01-03", "2024-01-03"]),
...     "symbol": ["AAA", "BBB", "AAA", "BBB"],
...     "open": [10.0, 20.0, 10.5, 19.0], "high": [11.0, 21.0, 11.5, 20.5],
...     "low": [9.5, 19.5, 10.0, 18.5], "close": [10.5, 20.5, 11.0, 19.5],
...     "volume": [1e6, 2e6, 1.1e6, 1.8e6],
... })
>>> qa.compute_factors(frame, "alpha158")[["timestamp", "symbol", "KMID"]]
   timestamp symbol      KMID
0 2024-01-02    AAA  0.707107
1 2024-01-02    BBB -0.707107
2 2024-01-03    AAA  0.707107
3 2024-01-03    BBB -0.707107

Functions

analyze_factors	Report how well each factor orders symbols by their forward return.
backtest	Backtest target weights, or the top-N names of a score, on a price frame.
compute_factors	Compute a factor set over every bar of a frame.
forward_returns	Compute the forward return of each bar, the label factors are judged against.