cagr refactor

Author: rbeeli

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 
 - `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.
 
 ### Changed
 

README.md

@@ -20,7 +20,7 @@ log_returns(prices::AbstractMatrix; drop_first=false, first_value=NaN)
 total_return(returns::AbstractVector; method=:simple)
 total_return(returns::AbstractVector; method=:log)
 
-cagr(returns::AbstractVector; periods_per_year::Real, method=:simple)
+cagr(returns::AbstractVector, periods_per_year::Real; method=:simple)
 
 volatility(returns::AbstractVector; multiplier=1.0)
 

src/returns.jl

@@ -449,7 +449,7 @@ function total_return(returns::AbstractVector; method::Symbol=:simple)
 end
 
 """
-    cagr(returns::AbstractVector; periods_per_year, method=:simple)
+    cagr(returns::AbstractVector, periods_per_year; method=:simple)
 
 Compute the Compound Annual Growth Rate (CAGR) from a series of periodic returns.
 Supports either simple returns (`method = :simple`) or log returns (`method = :log`).
@@ -484,16 +484,16 @@ julia> using RiskPerf
 
 julia> monthly_r = fill((1.5)^(1/36) - 1, 36);  # 3 years of monthly returns growing total 50%
 
-julia> cagr(monthly_r; periods_per_year=12)
+julia> cagr(monthly_r, 12)
 0.1447146268169922  # ≈ (1.5)^(1/3) - 1
 
 julia> log_monthly = log.(1 .+ monthly_r);
 
-julia> cagr(log_monthly; periods_per_year=12, method=:log) ≈ cagr(monthly_r; periods_per_year=12)
+julia> cagr(log_monthly, 12; method=:log) ≈ cagr(monthly_r, 12)
 true
 ```
 """
-function cagr(returns::AbstractVector; periods_per_year::Real, method::Symbol=:simple)
+function cagr(returns::AbstractVector, periods_per_year::Real; method::Symbol=:simple)
     n = length(returns)
     n == 0 && return 0.0
     ppy = float(periods_per_year)

test/returns.jl

@@ -90,11 +90,11 @@ end
     monthly_r = fill(monthly_growth^(1 / n) - 1, n)
     # Direct formula
     expected = monthly_growth^(1 / n_years) - 1
-    @test cagr(monthly_r; periods_per_year=periods_per_year) ≈ expected atol = 1e-12
+    @test cagr(monthly_r, periods_per_year) ≈ expected atol = 1e-12
 
     # Log returns variant
     log_r = log.(1 .+ monthly_r)
-    @test cagr(log_r; periods_per_year=periods_per_year, method=:log) ≈ expected atol = 1e-12
+    @test cagr(log_r, periods_per_year; method=:log) ≈ expected atol = 1e-12
 
     # Weekly example using simple returns
     weekly_growth = 2.0  # total double
@@ -103,16 +103,16 @@ end
     n2 = weeks_per_year * years
     weekly_r = fill(weekly_growth^(1 / n2) - 1, n2)
     expected2 = weekly_growth^(1 / years) - 1
-    @test cagr(weekly_r; periods_per_year=weeks_per_year) ≈ expected2 atol = 1e-12
+    @test cagr(weekly_r, weeks_per_year) ≈ expected2 atol = 1e-12
 
     # Empty input
-    @test cagr(Float64[]; periods_per_year=12) == 0.0
+    @test cagr(Float64[], 12) == 0.0
 
     # Invalid method
-    @test_throws ArgumentError cagr(monthly_r; periods_per_year=12, method=:foo)
+    @test_throws ArgumentError cagr(monthly_r, 12; method=:foo)
 
     # Invalid periods_per_year values
-    @test_throws ArgumentError cagr(monthly_r; periods_per_year=0)
-    @test_throws ArgumentError cagr(monthly_r; periods_per_year=-12)
-    @test_throws ArgumentError cagr(monthly_r; periods_per_year=Inf)
+    @test_throws ArgumentError cagr(monthly_r, 0)
+    @test_throws ArgumentError cagr(monthly_r, -12)
+    @test_throws ArgumentError cagr(monthly_r, Inf)
 end