jebel-quant/jquantstats/portfolio-analysis

Analysing a portfolio

First: get the object, don't invent one

Read ${CLAUDE_PLUGIN_ROOT}/reference/portfolio-context.md and follow it. In short: if .jquantstats/context.json exists, that is the portfolio — rebuild it with load() rather than asking the user to re-specify anything.

import os, sys
sys.path.insert(0, os.path.join(os.environ["CLAUDE_PLUGIN_ROOT"], "scripts"))
from jqs_context import load
pf = load()

If no context exists, build one first — the digest it prints tells you the asset count, span, inferred periodicity and null situation, all of which change which answer is correct.

The call shape

Three rules cover most mistakes:

1. Metrics return a dict keyed by column, never a scalar.

pf.stats.sharpe()  # {'returns': 2.13}   — Portfolio aggregates to one series
data.stats.sharpe()  # {'GOOG': 1.15, 'AAPL': 1.75}

A Portfolio's series is always named returns. Multi-asset lives on Data.

2. Half of `Portfolio` is properties, not methods. Adding () raises.

3. To get stats on a *derived* returns frame, use `pf.as_data(frame)` — never `Data.from_returns(frame)`. The frames returned by pf.returns, cost_adjusted_returns() and deduct_management_fee() also carry profit and NAV_accumulated, which Data.from_returns would silently treat as two more assets (reporting a Sharpe for a cash P&L series and a NAV level). as_data keeps only the returns column and raises MissingReturnsColumnError if there isn't one.

net = pf.deduct_management_fee(annual_fee=0.0085, base=pf.cost_adjusted_returns(cost_bps=5))
pf.as_data(net).stats.sharpe()  # {'returns': ...}

On Data: assets, date_col, all are properties; returns, index, benchmark are fields; head, tail, items, copy, resample, truncate, describe are methods.

4. Periodicity kwargs are not uniformly named. sharpe, sortino, volatility, omega, treynor_ratio take periods; information_ratio, greeks, rolling_greeks, montecarlo_sharpe, montecarlo_cagr take periods_per_year. Both default to None → inferred. Check the digest's periods_per_year before trusting any annualised number.

Which tool for which question

A benchmark must be passed at construction (Data.from_returns(..., benchmark=...)), not per call — so benchmark-relative metrics need a Data context that has one. greeks, information_ratio, rolling_greeks and treynor_ratio take a benchmark= column name; up_capture and down_capture are the odd ones out, taking a pl.Series.

The accessor asymmetry

Portfolio and Data are not symmetric, and this is the most common error:

Note the singular/plural: `Data.reports`, `Portfolio.report`.

PortfolioPlots is not a superset. It offers exactly 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 anything else — drawdown(), histogram(), monthly_heatmap(), drawdowns_periods(), rolling_beta(), distribution() — drop to the returns view, which is always available and shares the same underlying series:

pf.data.plots.drawdown()
pf.data.stats.calmar()

Charts

Plots return a Plotly go.Figure, which a terminal cannot render. Write it out and tell the user the path:

fig = pf.plots.snapshot()
fig.write_html("_analysis/snapshot.html")  # interactive
fig.write_image("_analysis/snapshot.png")  # static; needs kaleido

For a full document: pf.report.to_html(title=..., path=...) returns a Path when path is given, otherwise the HTML string. On the Data side, data.reports.full(title=...) returns a self-contained HTML string.

Reporting numbers

• Say which context produced them when more than one exists.
• State the periodicity actually used when quoting anything annualised.
• information_ratio is raw (non-annualised) by default, matching QuantStats;

pass annualise=True for the √periods-scaled version.

• volatility annualises by default (annualize=True — note the z, unlike

information_ratio's annualise).

• If the digest carried warnings, resolve or repeat them alongside the numbers

rather than quoting past them. Nulls and a misinferred periods_per_year both produce plausible-looking wrong answers.

Before writing an unfamiliar call

Confirm the symbol exists — invented method names are the expensive failure here:

bash "${CLAUDE_PLUGIN_ROOT}/scripts/jqs.sh" jqs_api.py --show sortino
bash "${CLAUDE_PLUGIN_ROOT}/scripts/jqs.sh" jqs_api.py --grep capture