📈 Performance Metrics

When evaluating the success of an investment portfolio, looking only at the total balance or absolute profit is not enough. To truly understand performance, you need standardized metrics that answer different questions: "How did my assets perform?", "How good was my timing?", and "What is the return on this specific trade?".

🎭 The Two Actors in Your Portfolio

To understand why multiple metrics exist, imagine there are two different "actors" managing your wealth:

The Market (The Assets): Causes the prices of the things you own to go up or down.
You (The Investor): Decides when to deposit or withdraw cash from the portfolio.

These two actors can have vastly different performances. You might pick an excellent stock (The Market performs well), but you might buy it at the very top just before a crash (You perform poorly). LibreFolio uses different metrics to isolate these two behaviors.

📚 Topics in this Chapter

LibreFolio's performance metrics are organized around three calculation engines. Each has its own overview page with the full mathematical model.

⚙️ Portfolio Engine

Aggregate, WAC-based accounting for the whole portfolio (or any broker/asset scope).

Metric / Concept	Description
Portfolio Engine Overview	Complete mathematical model: unified price resolver, WAC, aggregation, 3-pool model, contribution, pre-frame/frame architecture.
Price Resolution	Unified resolver tiers: MARKET → TRADE_AVG → CARRIED → MISSING, with native marks and per-date FX.
Net Asset Value (NAV)	Total market valuation of the portfolio (assets + cash + in-transit), using the unified resolver.
Book Value	Historical accounting cost of open positions (WAC × qty) plus cash. Difference from NAV = unrealized P&L.
Period P&L	Cash-flow adjusted monetary profit/loss in a window. Decomposes into: unrealized delta + realized + income − fees. Includes per-asset contribution attribution.
Deposited Capital & Total P&L	Net external capital since inception. Documents the 3-pool event-driven cash decomposition model (K, R, W) with formal transaction-level update rules.
Timing Effect	Difference between Cumulative MWRR and Cumulative TWRR — quantifies the impact of cash flow timing on returns.
Simple ROI	Percentage return relative to net invested capital. Simple but subject to cash flow dilution.
Net Annualized Return	Net CAGR definitions for holdings, period contribution, and FIFO lots, with 30-day minimum window.
Yield on Cost	Trailing-365-day non-negative gross dividend/interest per eligible historical unit, divided by average purchase price (WAC) for each asset/broker pair.
TWRR	Time-Weighted Rate of Return. Pure asset/strategy performance, neutralizing deposit/withdrawal timing.
MWRR (XIRR)	Money-Weighted Rate of Return. Personal investor performance accounting for cash flow timing. Annualized and Cumulative forms.

🔬 FIFO Engine

Per-lot accounting: tracks each acquisition batch through its own lifecycle instead of blending it into one average.

Metric / Concept	Description
FIFO Engine Overview	Lot lifecycle states, chronological event processing, FIFO matching, splits, and transfers between brokers.
FIFO Lot Analysis	Per-lot complement to WAC: tracks each acquisition batch through its own lifecycle, matches sells in FIFO order, and computes open/total return per lot.

📊 Weighted Average Cost

Metric / Concept	Description
Weighted Average Cost	Inventory-aware iterative WAC per position (broker, asset), each acquisition at its own date's exchange rate. Computed once per report, then replayed by the engine's daily loop.

⚖️ Metric Comparison Guide

To help you choose the right metric for your analysis, use this comparison guide:

💼 1. Net Asset Value (NAV) / Net Worth

Core Question: "How much is the portfolio in the selected scope worth right now?"
Formula Concept: \(\text{Market Value} + \text{Cash} + \text{In Transit Assets}\) at end of period.
Best Use Case: Snapshot of absolute wealth on the selected end date (date_to).

📖 2. Book Value

Core Question: "How much did my current portfolio cost to build?"
Formula Concept: \(\text{Open Cost Basis} + \text{Cash} + \text{In Transit Book Value}\) using Weighted Average Cost (WAC).
Best Use Case: Evaluating acquisition costs and comparing with current market value (NAV) to find latent gains.

📊 3. Period P&L

Core Question: "How much money did I actually earn or lose during this period?"
Formula Concept: \(\text{NAV}_{\text{end}} - \text{NAV}_{\text{start}} - \Delta\text{CapitalBaseline}\).
Best Use Case: Measuring period gains in absolute currency, independent of investor cash injections/withdrawals.

⏱️ 4. Timing Effect

Core Question: "How did the timing and size of my cash flows affect my overall return compared to a buy-and-hold strategy?"
Formula Concept: \(\text{MWRR}_{\text{cumulative}} - \text{TWRR}_{\text{cumulative}}\).
Best Use Case: Diagnosing whether deposits and withdrawals added value (\(>0\) pp) or dragged down performance (\(<0\) pp).

📉 5. Simple ROI

Core Question: "How much did I gain relative to the net capital I invested?"
Formula Denominator: Capital baseline, including priced in-kind capital.
Limitations: Does not account for when cash flows occurred, leading to cash flow dilution when subsequently buying more of an asset.

⏱️ 6. TWRR (Time-Weighted Rate of Return)

Core Question: "How did my chosen asset allocation/strategy perform, ignoring my cash timing?"
Formula Concept: Breaks the timeline at each cash flow, calculates sub-period returns, and multiplies them.
Best Use Case: Comparing your performance with external benchmarks (like the S&P 500) or evaluating the pure performance of the assets.

📈 7. Annualized MWRR (Money-Weighted Rate of Return)

Core Question: "At what compound annual rate did my actual capital grow, considering my deposits and withdrawals?"
Formula Concept: Solves for the internal rate of return (\(r\)) that brings the net present value of all cash flows to zero.
Best Use Case: Comparing your personal performance against long-term interest rates or evaluating compound growth over long horizons. Can be highly volatile on short windows.

📊 8. Cumulative MWRR

Core Question: "What is the equivalent money-weighted cumulative return over this selected time window?"
Formula Concept: Compounds the annualized MWRR for the actual number of days elapsed.
Best Use Case: Serial charts and dashboard widgets to compare visual performance trends side-by-side with TWRR and ROI.

💸 9. Yield on Cost

Core Question: "How much gross dividend and interest income did each current unit produce over the last 365 calendar dates relative to its average purchase price?"
Formula Concept: Sums non-negative, transaction-date-FX income per eligible prior-day long unit, adjusts for linked splits, then divides by average purchase price (WAC) at the report end date.
Best Use Case: Comparing the recorded income productivity of open asset/broker positions without confusing it with market dividend yield, CAGR, or bond YTM.

💡 The Practical Example (TWRR vs MWRR vs ROI)

Let's look at an extreme example to see how TWRR, MWRR, and Simple ROI tell different, but mathematically correct, stories.

Month 1: You buy €1,000 of a stock. The next month, the stock doubles (+100%). You now have €2,000.
Month 2: You deposit another €100,000 into the exact same stock. You now have €102,000 invested.
Month 3: The stock drops by -10%. Your total capital drops to €91,800.

Here is what LibreFolio will calculate for this scenario:

📊 Cumulative TWRR: +80.00%

The assets you picked went up +100%, and then dropped -10%. Mathematically:

\[ (1 + 1.00) \times (1 - 0.10) - 1 = +80.00\% \]

This isolates the pure performance of the stock. Your asset picking was excellent. If you had invested all your money on day 1, you would have made an 80% return.

📉 Simple ROI: -9.11%

You deposited a total of €101,000 out of your own pocket (€1,000 + €100,000), but you currently hold €91,800:

\[ ROI = \frac{91,800 - 101,000}{101,000} = -9.11\% \]

This represents your actual, raw wallet gain/loss relative to your net invested capital.

💵 Cumulative MWRR: -16.99%

Because you deposited €100,000 right at the peak before a drop, your timing dragged down your return significantly:

\[ \text{MWRR}_{\text{cumulative}} \approx -16.99\% \]

This money-weighted cumulative return represents the performance of a "theoretical euro" under your actual cash flow timing.

📈 Annualized MWRR: -67.19%

Since the substantial drop occurred over a very short time window (31 days) on a massive capital base (€100,000), the annualized compound rate of loss is very high:

\[ \text{MWRR}_{\text{annualized}} \approx -67.19\% \]

This represents the annualized speed of capital loss over this specific window.

⚖️ Why LibreFolio shows both side-by-side

By placing TWRR and MWRR next to each other on your Dashboard, LibreFolio gives you an immediate behavioral diagnosis:

TWRR > MWRR: "You are picking good investments, but your timing is bad. You are likely buying at the top (FOMO) and dragging your personal returns down."
MWRR > TWRR: "You have excellent timing! You are buying assets at a discount when the market drops, boosting your personal returns above the market average."

🔗 UI Integration & Dashboard Help Links

To aid navigation, the three KPI cards on the LibreFolio dashboard — Period P&L, Returns, and Net Worth — each carry a help icon. The path to these theory chapters is two steps:

The help icon opens the matching section of the user guide's KPI Cards page (Card 1, Card 2, Card 3).
From there, each metric links to its financial theory chapter: Period P&L, Book Value, ROI, TWRR, MWRR, Timing Effect, NAV / Net Worth, Deposited Capital & Total P&L.

Elsewhere in the app, the WAC preview in the transaction form links directly to the Weighted Average Cost chapter, the Holdings table links its YOC column to Yield on Cost, and each chart signal/indicator links to its own theory page.