Charts
Charts need the builders extra. .plot(df, type=..., fmt=...) takes a DataFrame and a
PlotType. Every chart is built with Plotly. The email view embeds a PNG of it, and the
interactive page keeps it live.
from common_reports.contracts.builders import PlotFormat, PlotType, Transform
b.plot( daily_returns, # index = dates, 0.01 = 1% type=PlotType.CUMULATIVE, fmt=PlotFormat(strat_cols=("Genesis",), bench_cols=("SPY",), transform=Transform.CUM), caption="Cumulative return since launch",)Finance families
Each finance family takes one documented data shape. When the data does not fit, the
family raises ValueError naming the shape it expected; it never draws the wrong
thing. The analytics stay with you: attribution effects and waterfall steps arrive
already computed.
PlotType | Data | Draws |
|---|---|---|
WATERFALL | one numeric column of step values (value_cols picks it); the index labels the steps; an optional measure column holds relative / absolute / total | a bridge from start to end; without measure a Total bar closes it |
ATTRIBUTION | index = categories (assets, sectors, strategies); each numeric column is one effect or period | stacked bars per category, sorted by total, with a marker for each total |
UNDERWATER | periodic returns in strat_cols / bench_cols | distance below the running peak; strategies as areas, benchmarks as lines |
EXPOSURE | index = dates; each column is a signed exposure as a fraction of NAV (shorts negative) | long above zero, short below, with net and gross lines |
CORRELATION | index = dates; two or more columns of periodic returns | the correlation matrix |
RISK_RETURN | periodic returns in strat_cols / bench_cols | annualised return against annualised volatility, one point each |
WEIGHTS | one numeric column of weights, index = names | horizontal bars, largest on top, shorts in red |
RISK_RETURN annualises with fmt.periods_per_year: 252 for trading days, 365 for
crypto and 12 for monthly data.
b.plot(weights_df, type=PlotType.WEIGHTS, fmt=PlotFormat(value_cols=("Weight",)))b.plot(effects_df, type=PlotType.ATTRIBUTION, caption="Brinson attribution, September")b.plot( returns_df, type=PlotType.RISK_RETURN, fmt=PlotFormat(strat_cols=("Genesis",), bench_cols=("SPY", "QQQ"), periods_per_year=252),)Performance families
These plot the columns named in strat_cols and bench_cols. Strategies take the
strategy colours; benchmarks take the benchmark colours.
PlotType | Data and behaviour |
|---|---|
CUMULATIVE, CUMULATIVE_LOG, CUMULATIVE_VOLMATCHED | lines over dates; transform turns periodic returns into a curve (CUM, LOG1P_CUMSUM, LOG, VOL_MATCHED) |
CUMULATIVE_PERIODIC | cumulative lines with period buttons (period_buttons, rebase_per_period) |
PORTFOLIO, ROLLING | portfolio value; rolling metrics over rolling_windows |
PERIOD_BAR | one bar per period, with a dashed average line |
DRAWDOWN | the given series as lines; shade periods with bands |
DISTRIBUTION | histograms of returns, with a dashed line at each mean |
HEATMAP | a returns grid: index = years, columns = months (and EOY), on a red-to-green scale centred at 0 |
PlotFormat settings
| Group | Fields |
|---|---|
| Columns | strat_cols, bench_cols, value_cols, name_map (display names) |
| Data | transform, rebase, date_range, periods_per_year, na_fill |
| Axes | yaxis_tickformat (default .0%), xaxis_tickformat, tickprefix, yaxis_type, secondary_axis, primary_axis_title |
| Marks | hlines (HLine), vlines (VLine), bands (Band) |
| Look | title, height, width, margins, font_size, legend_orientation, color_overrides |
| Interactive page | hover (hover labels), zoom (drag-to-zoom and the toolbar) |
| Escape hatches | traces (extra Plotly traces), raw_layout (merged into the layout) |
A chart’s caption goes under it rather than into the Plotly title, so it reads the same
in every view. To use a figure you built yourself, call b.figure(fig, caption=...).
Colours
- Classic style: colours come from the theme palette. The palette is deterministic: the same series name always gets the same colour.
- Modern style: charts are restyled to the brand’s
seriescolours and font.- With
chart_card=False(the Null Capital brand), the chart background is see-through. Its text useschart_text, which reads on light and dark mail. - With
chart_mark=True, the crest sits in the chart’s corner.
- With
Chart images
The email PNGs are drawn by kaleido.
- One shared browser, in its own process. A helper process starts once per program and keeps one headless browser for every chart, so a chart takes about 0.1 s after the first one. A stalled, crashed or memory-starved browser costs only that helper.
- Timeout. Each export has a 120-second deadline (
PNG_TIMEOUT_SECONDS). When it passes, the helper is killed with its browser, that chart and every later one in the program are left out, and afigure_png_timeoutwarning is logged. The email still renders, and the program exits normally. - Chrome. kaleido 1.x needs a Chrome or Chromium it can find. Container images that send charts must include one.