Add doc to fast_R_to_r_approx and possibly variable interval

EpiAware/src/utilities.jl

@@ -130,8 +130,39 @@ function dneg_MGF_dr(r, w::AbstractVector)
     return -sum([w[i] * i * exp(-r * i) for i = 1:length(w)])
 end
 
-function fast_R_to_r_approx(R₀, w::Vector{T}; newton_steps = 1) where {T<:AbstractFloat}
-    mean_gen_time = dot(w, 1:length(w))
+"""
+    fast_R_to_r_approx(R₀, w::Vector{T}; newton_steps = 2, Δd = 1.0)
+
+This function computes an approximation to the exponential growth rate `r`
+given the reproductive ratio `R₀` and the discretized generation interval `w` with
+discretized interval width `Δd`. This is based on the implicit solution of
+
+```math
+G(r) - {1 \over R_0} = 0.
+```
+
+where
+
+```math
+G(r) = \sum_{i=1}^n w_i e^{-r i}.
+```
+
+is the negative moment generating function (MGF) of the generation interval distribution.
+
+The two step approximation is based on:
+    1. Direct solution of implicit equation for a small `r` approximation.
+    2. Improving the approximation using Newton's method for a fixed number of steps `newton_steps`.
+
+Returns:
+- The approximate value of `r`.
+"""
+function fast_R_to_r_approx(
+    R₀,
+    w::Vector{T};
+    newton_steps = 2,
+    Δd = 1.0,
+) where {T<:AbstractFloat}
+    mean_gen_time = dot(w, 1:length(w)) * Δd
     # Small r approximation as initial guess
     r_approx = (R₀ - 1) / (R₀ * mean_gen_time)
     # Newton's method
@@ -141,12 +172,11 @@ function fast_R_to_r_approx(R₀, w::Vector{T}; newton_steps = 1) where {T<:Abst
     return r_approx
 end
 
-function fast_R_to_r_approx(R₀, epimodel::AbstractEpiModel; newton_steps = 4)
-    fast_R_to_r_approx(R₀, epimodel.data.gen_int; newton_steps = newton_steps)
+function fast_R_to_r_approx(R₀, epimodel::AbstractEpiModel; newton_steps = 2, Δd = 1.0)
+    fast_R_to_r_approx(R₀, epimodel.data.gen_int; newton_steps = newton_steps, Δd = Δd)
 end
 
 
-
 """
     growth_rate_to_reproductive_ratio(r, w)