common_reports.builders.charts
Finance chart families — waterfall, attribution, underwater, exposure, correlation, risk/return and weights.
Each family takes ONE documented data shape and raises ValueError naming
the expected shape when the data does not fit — a chart never silently draws
the wrong thing. The analytics stay with the caller: attribution effects and
waterfall steps arrive already computed; the only transforms here are the
simple ones a chart needs (returns -> drawdown, returns -> correlation,
returns -> annualised return and volatility).
Colours come from the theme palette; the modern style restyles them to its
brand afterwards. Plotly / pandas load lazily with the [builders] extra.
Functions
build_attribution
def build_attribution(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyATTRIBUTION — contribution by category, one stacked bar per row.
Shape: index = categories (assets, sectors, strategies); each numeric column is one effect (e.g. Allocation / Selection / Interaction, or one column per period). Rows sort by their total; a marker shows each total.
build_correlation
def build_correlation(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyCORRELATION — pairwise correlation of the columns’ returns.
Shape: index = dates; two or more numeric columns of periodic returns.
build_exposure
def build_exposure(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyEXPOSURE — long / short (or per-sector) exposure over time, with net and gross.
Shape: index = dates; each numeric column is a signed exposure as a fraction of NAV (shorts negative). Positive columns stack above zero, negative below.
build_finance_figure
def build_finance_figure(ptype: PlotType, data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyDispatch one of the finance families.
build_risk_return
def build_risk_return(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyRISK_RETURN — annualised return against annualised volatility, one point each.
Shape: periodic returns in strat_cols / bench_cols;
fmt.periods_per_year sets the annualisation (252 trading days, 365 for
crypto, 12 for monthly data).
build_underwater
def build_underwater(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyUNDERWATER — how far below its last peak each series sits over time.
Shape: periodic returns in strat_cols / bench_cols. Strategies are
filled areas, benchmarks lines. Shade chosen periods with fmt.bands.
build_waterfall
def build_waterfall(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyWATERFALL — a bridge from start to end through each contribution.
Shape: ONE numeric column of step values (value_cols picks it), the index
labels the steps. Optional measure column with Plotly’s relative /
absolute / total per row; without it every row is a relative step and
a Total bar closes the bridge.
build_weights
def build_weights(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> AnyWEIGHTS — current position weights, largest on top; shorts in red.
Shape: ONE numeric column of weights (value_cols picks it), index = names.
Types and values
FINANCE_FAMILIES
FINANCE_FAMILIES = {PlotType.WATERFALL: build_waterfall, PlotType.ATTRIBUTION: build_attribution, PlotType.UNDERWATER: build_underwater, PlotType.EXPOSURE: build_exposure, PlotType.CORRELATION: build_correlation, PlotType.RISK_RETURN: build_risk_return, PlotType.WEIGHTS: build_weights}