Return Annualization and Deannualization
Install and import#
npm install fintech-algorithmsimport { returnAnnualizationAndDeannualization } from "fintech-algorithms/foundations/financial-arithmetic-time-value-and-returns/annualization-deannualization";Signature#
returnAnnualizationAndDeannualization(input)Scales a single-period return up to an annual figure by compounding it frequency times, then scales that annual figure back down to confirm the two conversions are inverses.
Parameters#
| Name | Type | Notes |
|---|---|---|
input | D00Input | A plain object. Every F02 topic first reads principal, rate and periods and validates them before any per-topic branch runs. This branch sits at the end of the chain, so the engine also rejects a startValue or endValue that is zero or negative (omitting them entirely is not caught, because Number(undefined) is NaN) and requires returns to be a non-empty array of finite numbers none of which is at or below -1, even though none of them affect the answer. The result depends only on periodicReturn, the return over one period, and frequency, the number of such periods in a year. |
Returns#
{ annualizedReturn: number; deannualizedReturn: number }
annualizedReturn is (1 + periodicReturn) ** frequency - 1. deannualizedReturn takes that result back down by the frequency root, recovering periodicReturn.
Errors#
- When input is not a plain object — throws TypeError
- When principal is negative, periods is negative, or rate is at or below -1 — throws RangeError
- When startValue or endValue is zero or negative — throws RangeError
- When returns is missing, empty, not an array, or contains a non-finite number — throws RangeError
- When any entry of returns is at or below -1, a loss of 100% or worse — throws RangeError
Complexity: time O(n),
space O(n).
Worked example#
verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.
Input#
{
"principal": 1000,
"rate": 0.05,
"periods": 3,
"compoundsPerPeriod": 12,
"futureValue": 1200,
"cashFlows": [-1000, 400, 400, 400],
"startValue": 100,
"endValue": 110,
"returns": [0.1, -0.05, 0.08],
"frequency": 12,
"periodicReturn": 0.01
}Call#
returnAnnualizationAndDeannualization(input)Returns#
object with 2 fields: annualizedReturn, deannualizedReturn
{
"annualizedReturn": 0.12682503013196977,
"deannualizedReturn": 0.010000000000000009
}Diagrams#
Calculation flow#
Return Annualization and Deannualization — four-part map
flowchart LR
A["Name the input"] --> B["Apply: annualized = (1 + HPR)^(1/years) - 1; target period = (1 + annual rate)^(years) - 1"]
B --> C["Check units and boundary"]
C --> D["Explain the output"]
How it works#
This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.
References#
- INVESTOR_RETURN - Annual Return — U.S. Securities and Exchange Commission
- CFA_QM - CFA Institute Quantitative Methods Study Session — CFA Institute
- CFA_TVM - Time Value of Money in Finance — CFA Institute
- Author-derived and synthetic boundary