Skip to content

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) -> Any

ATTRIBUTION — 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) -> Any

CORRELATION — 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) -> Any

EXPOSURE — 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) -> Any

Dispatch one of the finance families.

build_risk_return

def build_risk_return(data: Any, fmt: PlotFormat, palette: Palette, go: Any, apply_layout: Any) -> Any

RISK_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) -> Any

UNDERWATER — 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) -> Any

WATERFALL — 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) -> Any

WEIGHTS — 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}