added annualized_return

Author: rbeeli

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - `mean_excess` and `std_excess` helpers for allocation‑free mean and standard deviation of differences.
 - `cagr` function for calculating the compound annual growth rate of a series of returns, with support for simple and log returns.
+- `annualized_return` function for calculating the annualized return of a series of returns, with support for simple and log returns.
 
 ### Changed
 

README.md

@@ -22,6 +22,8 @@ total_return(returns::AbstractVector; method=:log)
 
 cagr(returns::AbstractVector, periods_per_year::Real; method=:simple)
 
+annualized_return(returns::AbstractVector, periods_per_year::Real)
+
 volatility(returns::AbstractVector; multiplier=1.0)
 
 information_ratio(asset_returns::AbstractVector, benchmark_returns::Real; multiplier=1.0)

src/RiskPerf.jl

@@ -19,6 +19,7 @@ export adjusted_sharpe_ratio,
     simple_returns,
     total_return,
     cagr,
+    annualized_return,
     mean_excess,
     std_excess,
     lower_partial_moment,

src/returns.jl

@@ -498,9 +498,7 @@ function cagr(returns::AbstractVector, periods_per_year::Real; method::Symbol=:s
     n == 0 && return 0.0
     ppy = float(periods_per_year)
     (!isfinite(ppy) || ppy <= 0) && throw(
-        ArgumentError(
-            "periods_per_year must be positive and finite (got $(periods_per_year)).",
-        ),
+        ArgumentError("periods_per_year must be positive and finite (got $(periods_per_year)).")
     )
     years = n / ppy
     T = promote_type(eltype(returns), Float64)
@@ -522,3 +520,40 @@ function cagr(returns::AbstractVector, periods_per_year::Real; method::Symbol=:s
 
     throw(ArgumentError("Invalid method $(method). Use :simple or :log."))
 end
+
+"""
+    annualized_return(returns::AbstractVector, periods_per_year::Real)
+
+Compute the arithmetic annualized return by scaling the average periodic return.
+This matches the common "expected annual return" metric on fact sheets where the
+per-period arithmetic mean is multiplied by the observation frequency.
+
+# Arguments
+- `returns`: Vector of periodic simple (arithmetic) returns.
+- `periods_per_year`: Number of periods per calendar year (e.g. 252, 12, 52).
+
+# Formula
+
+Let `μ = mean(returns)` and `k = periods_per_year`. Then
+
+``AnnualizedReturn = μ × k``
+
+# Edge Cases
+- Returns `0.0` if `returns` is empty.
+- Throws `ArgumentError` when `periods_per_year` is non-positive or non-finite.
+"""
+function annualized_return(returns::AbstractVector, periods_per_year::Real)
+    n = length(returns)
+    n == 0 && return 0.0
+    ppy = float(periods_per_year)
+    (!isfinite(ppy) || ppy <= 0) && throw(
+        ArgumentError("periods_per_year must be positive and finite (got $(periods_per_year)).")
+    )
+    T = promote_type(eltype(returns), Float64)
+    s = zero(T)
+    @inbounds for r in returns
+        s += T(r)
+    end
+    μ = s / T(n)
+    μ * T(ppy)
+end

test/returns.jl

@@ -116,3 +116,19 @@ end
     @test_throws ArgumentError cagr(monthly_r, -12)
     @test_throws ArgumentError cagr(monthly_r, Inf)
 end
+
+@testitem "annualized_return" begin
+    using Test
+    using RiskPerf
+
+    monthly = fill(0.01, 12)
+    @test annualized_return(monthly, 12) ≈ 0.12 atol = 1e-12
+
+    mixed = [0.01, -0.02, 0.03]
+    expected = sum(mixed) / length(mixed) * 12
+    @test annualized_return(mixed, 12) ≈ expected atol = 1e-12
+
+    @test annualized_return(Float64[], 12) == 0.0
+    @test_throws ArgumentError annualized_return(mixed, 0)
+    @test_throws ArgumentError annualized_return(mixed, Inf)
+end