Migrating from QuantStats to jquantstats¶

A heartfelt thank you to Ran Aroussi for creating QuantStats — a brilliant and widely loved library that has helped countless quants and portfolio managers understand their strategies better. This project would simply not exist without that foundation. We have enormous respect for the original work and encourage everyone to check it out.

jquantstats is a modern variation on the theme set by QuantStats — not a copy, not a drop-in replacement, but a different take on the same problem space. Where QuantStats offers a collection of standalone functions each operating on a return series, jquantstats is built around a portfolio-centric entry point: you start from a Portfolio object constructed from prices and positions, and analytics flow naturally from there. This makes multi-asset analysis, cost modelling, and execution-lag studies first-class citizens rather than afterthoughts.

This guide explains the key conceptual and API differences between the two libraries so you know what to expect, and provides concrete code translations to help you move your existing workflows over.

Why migrate¶

Installation¶

pip install jquantstats
pip install jquantstats[plot]   # adds kaleido for static image export

Uninstall QuantStats once you're done:

pip uninstall quantstats

Data format¶

QuantStats expects a pd.Series with a DatetimeIndex. jquantstats expects a pl.DataFrame with a dedicated date column.

import pandas as pd
import polars as pl

# QuantStats — pd.Series with DatetimeIndex
returns_pd: pd.Series = ...

# jquantstats — convert from pandas
returns_pl = pl.from_pandas(returns_pd.rename("MyStrategy").reset_index())
# → DataFrame columns: ["Date", "MyStrategy"]

# jquantstats — build from scratch
from datetime import date
returns_pl = pl.DataFrame({
    "Date":       [date(2020, 1, 2), date(2020, 1, 3), ...],
    "MyStrategy": [0.01, -0.005, ...],
})

The date column is found by type, not by name: whatever you call it — Date, timestamp, dt — the first temporal column is used, and the resulting object exposes it as date (data.index["date"], data.date_col == ["date"]). Pass date_col= only to nominate a specific column, which is required for a non-temporal (e.g. integer) index since there is no temporal column to find.

Benchmarks¶

# QuantStats — benchmark passed to every function call
import quantstats as qs
qs.stats.information_ratio(returns_pd, benchmark=benchmark_pd)

# jquantstats — benchmark provided once at construction time
import jquantstats as jqs
data = jqs.Data.from_returns(
    returns=returns_pl,
    benchmark=benchmark_pl,
)
data.stats.information_ratio()   # benchmark used automatically

Entry points¶

jquantstats has two entry points depending on what data you have.

Data — returns series (drop-in QuantStats replacement)¶

import jquantstats as jqs

data = jqs.Data.from_returns(
    returns=returns_pl,     # pl.DataFrame with date + return columns
    benchmark=benchmark_pl, # optional
)

data.stats.sharpe()
data.plots.snapshot()
data.reports.metrics()

You can also construct from prices:

data = jqs.Data.from_prices(prices=prices_pl)

Portfolio — prices + positions (no QuantStats equivalent)¶

If you have asset prices and position sizes, use Portfolio to get execution-delay analysis, tilt/timing decomposition, turnover analytics, and cost modelling — none of which are available in QuantStats.

pf = jqs.Portfolio.from_cash_position(
    prices=prices_df,        # pl.DataFrame: date + asset columns
    cash_position=pos_df,    # pl.DataFrame: date + asset columns (£ amounts)
    aum=1_000_000,
)

pf.stats.sharpe()            # the full stats API, same as Data
pf.plots.snapshot()          # a portfolio-specific plot set — see note below
pf.report.to_html()          # note: .report (singular), unlike Data.reports

# Drop down to the returns-series API at any time
pf.data.stats.calmar()
pf.data.plots.drawdown()

Portfolio.stats is the same object you get from Data, but Portfolio.plots is not a superset of Data.plots — it is a separate, smaller set aimed at position-level diagnostics:

snapshot                  correlation_heatmap        monthly_returns_heatmap
rolling_sharpe_plot       rolling_volatility_plot    annual_sharpe_plot
lead_lag_ir_plot          lagged_performance_plot
smoothed_holdings_performance_plot                   trading_cost_impact_plot

For any other chart — drawdown(), histogram(), monthly_heatmap(), … — go through pf.data.plots, which is always available.

Other factory methods:

# From share counts
pf = jqs.Portfolio.from_position(prices, position, aum)

# From risk-scaled positions, where vola is an EWMA lookback in periods
# (an int, or a dict[str, int] per asset) — not a volatility frame
pf = jqs.Portfolio.from_risk_position(prices, risk_position, aum, vola=32)

API mapping¶

All jquantstats analytics live on the .stats, .plots, and reports accessors of a Data (or Portfolio) instance — note that the reports accessor is Data.reports but Portfolio.report. Methods return a dict keyed by column name rather than a scalar.

# one-time setup
data = jqs.Data.from_returns(returns=returns_pl, benchmark=benchmark_pl)

Statistics¶

QuantStats functions with no jquantstats equivalent¶

The following QuantStats functions are intentionally not exposed as public methods in jquantstats. Each is either a shorthand alias for a canonical method or a utility that is subsumed by a richer jquantstats API. See the QuantStats Parity Benchmark for full rationale.

jquantstats-only stats methods¶

These methods have no QuantStats equivalent and are unique to jquantstats.

Plots¶

All data.plots.* methods return an interactive Plotly figure instead of a static matplotlib figure.

Reports¶

# QuantStats
qs.reports.full(returns_pd, benchmark=benchmark_pd)
qs.reports.metrics(returns_pd)

# jquantstats
data.reports.metrics()                  # pl.DataFrame; mode="full" for the extended set
data.reports.full(title="My Strategy")  # str — self-contained HTML document

# The Portfolio route spells it differently: .report (singular), and the
# HTML entry point is to_html(), which returns a str or writes to `path`.
pf.report.to_html(title="My Portfolio", path="report.html")

There is no data.reports.summary(). The composite stats table lives on the stats accessor instead, as data.stats.summary() → pl.DataFrame.

Accessing results¶

QuantStats functions return scalars. jquantstats methods return a dict keyed by column name.

# QuantStats — scalar
sharpe = qs.stats.sharpe(returns_pd)   # 1.23

# jquantstats — dict
result = data.stats.sharpe()            # {"MyStrategy": 1.23}
sharpe = result["MyStrategy"]           # 1.23

Multi-asset results come back in the same call:

returns_multi = pl.DataFrame({
    "Date": dates,
    "AAPL": aapl_rets,
    "MSFT": msft_rets,
})
data = jqs.Data.from_returns(returns=returns_multi)
data.stats.sharpe()
# → {"AAPL": 1.34, "MSFT": 0.91}

Behavioural differences¶

NaN / null handling¶

pandas (and QuantStats) silently drop NaN values in most calculations. Polars propagates null by default — if any value in a column is null, most statistics will return null instead of a numeric result.

Note: in Polars, null (a missing entry, equivalent to pandas NaN) and NaN (IEEE-754 "Not a Number") are distinct. jquantstats treats null as missing; NaN is a numeric value that propagates through calculations.

You can clean data manually before constructing Data:

returns_pl = returns_pl.drop_nulls()
# or fill forward
returns_pl = returns_pl.with_columns(pl.all().forward_fill())

Or use the null_strategy parameter on Data.from_returns / Data.from_prices:

# Mirrors pandas / QuantStats behaviour: silently drop rows with nulls
data = jqs.Data.from_returns(returns=returns_pl, null_strategy="drop")

# Forward-fill nulls before computing statistics
data = jqs.Data.from_returns(returns=returns_pl, null_strategy="forward_fill")

# Raise an informative error if any null is found (useful during development)
data = jqs.Data.from_returns(returns=returns_pl, null_strategy="raise")

The default (null_strategy=None) passes nulls through unchanged.

conditional_value_at_risk — alpha vs confidence¶

The tail can be named either way round. confidence is the QuantStats spelling; alpha = 1 − confidence is the tail probability, matching value_at_risk on the same object. Passing both in one call raises ValueError, and omitting both gives alpha=0.05 (95% confidence).

# QuantStats — confidence level
qs.stats.conditional_value_at_risk(r, confidence=0.95)

# jquantstats — either spelling, same result
data.stats.conditional_value_at_risk(confidence=0.95)
data.stats.conditional_value_at_risk(alpha=0.05)

Note the asymmetry with value_at_risk, which takes alpha only and has no confidence parameter.

information_ratio — annualisation¶

Both libraries return a raw, non-annualised information ratio by default, so the ported number matches QuantStats as-is. jquantstats can additionally annualise on request, scaling by √periods_per_year:

# QuantStats — raw
qs.stats.information_ratio(r, benchmark=b)

# jquantstats — raw (default), matching the above
data.stats.information_ratio()

# jquantstats — annualised
data.stats.information_ratio(annualise=True)

No top-level functions¶

QuantStats exposes bare module-level functions. jquantstats has none.

# ❌ does not exist
jqs.stats.sharpe(returns)

# ✅ correct
data = jqs.Data.from_returns(returns=returns_pl)
data.stats.sharpe()

Portfolio-only features¶

These capabilities have no QuantStats equivalent and are only available through the Portfolio entry point.

pf = jqs.Portfolio.from_cash_position(prices, positions, aum=1_000_000)

# Execution-delay analysis
pf_lagged = pf.lag(1)                    # shift positions forward by 1 day
pf.plots.lead_lag_ir_plot(start=-5, end=5)   # information ratio across a lag range

# Tilt / timing decomposition
pf.tilt                                  # constant-weight (allocation skill)
pf.timing                                # weight deviations (timing skill)
pf.tilt_timing_decomp                    # side-by-side NAV comparison

# Turnover analytics
pf.turnover                              # daily one-way turnover (fraction of AUM)
pf.turnover_weekly()                     # weekly aggregate
pf.turnover_summary()                    # pl.DataFrame: metric/value rows for
                                         # mean_daily_turnover, mean_weekly_turnover,
                                         # turnover_std

# Cost modelling
from jquantstats import CostModel

pf_a = jqs.Portfolio.from_cash_position(
    prices, positions, aum,
    cost_model=CostModel.per_unit(0.01),    # £0.01 per share traded
)
pf_b = jqs.Portfolio.from_cash_position(
    prices, positions, aum,
    cost_model=CostModel.turnover_bps(5),   # 5 bps per unit of AUM turnover
)

pf.trading_cost_impact(max_bps=20)          # sweep cost sensitivity 0 → 20 bps

Minimal migration checklist¶

1. Install jquantstats (pip install jquantstats).
2. Convert your pd.Series to a pl.DataFrame with a date column.
3. Construct a Data object once with Data.from_returns(...).
4. Replace every qs.stats.foo(r) call with data.stats.foo()["col"].
5. Drop any NaN-filled rows before passing data in, or use null_strategy.

Further reading¶

• API Reference — complete method signatures
• API Stability — versioning and deprecation policy