/performance-reporting

name: performance-reporting
description: "Generate clear, accurate performance reports for investment portfolios with benchmarks, attribution, and risk dashboards. Use when the user asks about portfolio performance reports, return summaries, benchmark comparison, risk dashboards, goal progress tracking, or GIPS-compliant reporting. Also trigger when users mention 'quarterly report', 'how did my portfolio do', 'time-weighted vs money-weighted return', 'annualized returns', 'net-of-fee performance', 'rolling Sharpe', or ask how to present investment results to clients."

Performance Reporting — Reporting & Communication

Core Concepts

Return Reporting

Accurate and consistent return calculation is the foundation of all performance reporting.

**Period returns:** Report standard time periods — MTD (month-to-date), QTD (quarter-to-date), YTD (year-to-date), 1Y, 3Y, 5Y, 10Y, and since inception. Always state the exact inception date.

**Cumulative vs annualized:** Annualize returns only for periods greater than 1 year. Annualizing a 3-month return is misleading because it implies the rate is sustainable for a full year. For periods under 1 year, report cumulative (total) returns only.

• Annualized return formula: `(1 + cumulative_return)^(1/years) - 1`
• For multi-year periods, always present both cumulative and annualized figures so the reader can see total wealth growth and the rate of compounding.

**Gross vs net of fees:** Always specify whether returns are gross or net of management fees, advisory fees, and transaction costs. Net-of-fee returns are what the investor actually experiences and should be the primary presentation. If showing gross returns, also show the fee drag.

**GIPS (Global Investment Performance Standards):** For institutional reporting, follow GIPS requirements — composite construction, full disclosure, verified calculations, and standardized presentation. Even for non-GIPS reports, the principles of fair representation and full disclosure apply.

**Time-weighted vs money-weighted returns:**

• Time-weighted return (TWR) removes the impact of cash flows — use for evaluating the investment manager's skill.
• Money-weighted return (MWR / IRR) reflects the investor's actual experience including timing of contributions and withdrawals — use for evaluating the investor's outcome.

Calculation Engines

`scripts/performance_reporting.py` implements the return calculations behind these reports:

• **Modified Dietz (`ModifiedDietz`):** approximates TWR by weighting each external cash flow by the fraction of the period it was invested: R = (V_end - V_start - sum(CF)) / (V_start + sum(w_i * CF_i)), with w_i = (D - d_i)/D. A GIPS-acceptable approximation when daily valuations are unavailable.
• **True TWR (`TimeWeightedReturn`):** chain-links sub-period returns, prod(1 + r_t) - 1, with an annualization helper that refuses periods under 1 year.
• **IRR / MWR (`MoneyWeightedReturn`):** solves NPV(rate) = 0 numerically using Brent's root-finding method (`scipy.optimize.brentq`) over a bracketing interval, returning the annual money-weighted return.
• **GIPS composites (`CompositeReturn`):** asset-weighted composite return using beginning-of-period values as weights, plus equal-weighted return and the asset-weighted internal dispersion GIPS requires for composites with 6+ portfolios.
• **Standard periods (`PeriodReturns`):** MTD/QTD/YTD-style trailing windows (1M through 10Y) and inception-to-date from a daily return series, annualizing only periods of 1 year or more.

Benchmark Comparison

A return number in isolation is meaningless. Context requires a benchmark.

**Appropriate benchmark selection:** The benchmark must match the portfolio's investment style, geography, capitalization, and asset class mix. A US large-cap equity portfolio should be compared to the S&P 500 or Russell 1000, not the MSCI Emerging Markets Index.

• For multi-asset portfolios, use a blended benchmark (e.g., 60% S&P 500 / 40% Bloomberg Aggregate).
• The benchmark should be investable — the investor could have held it as a passive alternative.
• Document the benchmark rationale and keep it consistent over time to avoid cherry-picking.

**Active return (alpha):** Portfolio return minus benchmark return. Positive alpha indicates outperformance; negative alpha indicates underperformance.

**Tracking error and information ratio:** For definitions and computation, see performance-metrics. In reports, present these alongside active return so the reader can judge how consistently outperformance was achieved.

Risk Dashboard

Complement return reporting with risk metrics to give a complete picture. For definitions and computation of these metrics (volatility, VaR, drawdown, etc.), see historical-risk.

**Current snapshot metrics:**

• Annualized volatility
• Maximum drawdown and current drawdown
• Value at Risk (VaR) at 95% and 99% confidence levels
• Beta relative to the benchmark

**Rolling metrics:** Show how risk evolves over time, not just a point-in-time estimate.

• 12-month rolling Sharpe ratio
• 12-month rolling volatility
• 36-month rolling beta
• Rolling drawdown chart

**Risk exposure breakdown:**

• Sector concentration and weights vs benchmark
• Factor exposures (value, growth, momentum, quality, size)
• Geographic allocation
• Duration and credit quality (for fixed income)

Attribution Summary

Explain *why* the portfolio outperformed or underperformed.

**Brinson attribution (allocation, selection, interaction) and factor decomposition:** For methodology and formulas, see performance-attribution. In a report, summarize each effect in one plain-language sentence (e.g., "sector weighting added 0.2%, stock selection added 0.4%").

**Top/bottom contributors (holdings-level):**

• List the 5-10 holdings that contributed most positively and most negatively to portfolio returns.
• Show both the return of the holding and its contribution to total portfolio return (weight x return).

-