% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functional_rate.R
\name{functional_rate}
\alias{functional_rate}
\title{Instantaneous Disease Progress Rates from Functional Curves}
\usage{
functional_rate(
  object,
  scale = c("response", "link"),
  method = c("central"),
  n_grid = 200,
  eps = NULL,
  interval = 0.95,
  threshold = 0,
  positive_only = TRUE,
  uncertainty = TRUE,
  growth_criterion = c("rate", "significant"),
  newdata = NULL,
  ...
)
}
\arguments{
\item{object}{An object of class \code{"functional_curves"}.}

\item{scale}{Character specifying the derivative scale: \code{"response"}
(default; e.g., severity change per unit time) or \code{"link"} (linear predictor scale).}

\item{method}{Character specifying the finite difference method. Currently \code{"central"}
(central difference in the interior with one-sided differences at temporal boundaries).}

\item{n_grid}{Integer; number of points in the regular temporal evaluation grid per group.
Default is 200.}

\item{eps}{Numeric step size used in finite differences. If \code{NULL} (default),
automatically chosen as \eqn{10^{-4} \times (t_{max} - t_{min})}.}

\item{interval}{Numeric confidence level for intervals. Default is 0.95.}

\item{threshold}{Numeric minimum rate threshold considered biologically relevant.
Default is 0.}

\item{positive_only}{Logical; whether to restrict summarized growth descriptors
to positive rates. Default is \code{TRUE}. Note that negative rates are always
preserved in the detailed rate table (\code{data}).}

\item{uncertainty}{Logical; whether to compute standard errors and confidence
intervals using the GAM covariance matrix. Default is \code{TRUE}.}

\item{growth_criterion}{Character specifying how active epidemic growth is defined:
\code{"rate"} (default; \code{rate > threshold}) or \code{"significant"}
(\code{rate_lower > threshold}, requiring \code{uncertainty = TRUE}).}

\item{newdata}{Optional user-supplied data frame with custom evaluation points.
Must contain the time and treatment variables.}

\item{...}{Additional arguments passed to methods.}
}
\value{
An object of class \code{"functional_rate"} containing:
\describe{
\item{\code{data}}{A tibble of full evaluation grid with columns including
treatment, time, \code{fitted}, \code{fitted_se}, \code{fitted_lower}, \code{fitted_upper},
\code{rate}, \code{rate_se}, \code{rate_lower}, \code{rate_upper},
\code{significant_increase}, \code{above_threshold}, and \code{significant_above_threshold}.}
\item{\code{summary}}{A tibble of curve-level rate phenotypes:
\code{r_max}, \code{t_r_max}, \code{r_mean}, \code{r_mean_positive},
\code{t_growth_start}, \code{t_growth_end}, \code{growth_duration},
\code{cumulative_positive_growth}, and \code{n_growth_windows}.}
\item{\code{model}}{The underlying GAM model object.}
\item{\code{call}}{The matched call.}
\item{\code{settings}}{List of analysis settings used.}
\item{\code{vars}}{List of variable names identified in the model.}
\item{\code{family}}{Character string naming the GAM family.}
}
}
\description{
Estimates instantaneous rates of plant disease progress (\eqn{S'(t) = dS(t)/dt})
and associated uncertainty from epidemic trajectories fitted by
\code{\link{functional_curves}}. Derivatives are computed using the GAM linear
predictor matrix (\code{lpmatrix}) with finite differences, supporting both
the original response scale (e.g., severity proportion/percentage points per day)
and the link (linear predictor) scale. Also computes epidemic rate phenotypes
including maximum rate (\eqn{r_{max}}), time of maximum rate (\eqn{t_{r_{max}}}),
growth duration, cumulative positive growth, and distinct growth windows.
}
\details{
\strong{Mathematical Formulation:}
Let \eqn{S(t)} denote the fitted disease trajectory and \eqn{\eta(t) = X(t)\beta}
the linear predictor from the GAM model, with \eqn{\mu(t) = g^{-1}(\eta(t))}.

The derivative on the link scale is estimated by:
\deqn{D = \frac{X(t + \epsilon) - X(t - \epsilon)}{2\epsilon}}
\deqn{\eta'(t) = D \beta}
with variance \eqn{\operatorname{Var}(\eta'(t)) = \operatorname{diag}(D V_p D^T)},
where \eqn{V_p} is the Bayesian posterior covariance matrix of the GAM parameters.

On the response scale (\code{scale = "response"}), the derivative of the mean trajectory is:
\deqn{S'(t) = \frac{\mu(\eta(t + \epsilon)) - \mu(\eta(t - \epsilon))}{2\epsilon}}
The approximate gradient vector \eqn{G} with respect to \eqn{\beta} is:
\deqn{G = \frac{\mu'(\eta(t + \epsilon)) X(t + \epsilon) - \mu'(\eta(t - \epsilon)) X(t - \epsilon)}{2\epsilon}}
where \eqn{\mu'(\eta) = d\mu/d\eta} is given by \code{family$mu.eta()}.
The uncertainty is then:
\deqn{\operatorname{Var}(S'(t)) = \operatorname{diag}(G V_p G^T)}

\strong{Boundary Handling:}
At the observed boundaries \eqn{t_{min}} and \eqn{t_{max}}, one-sided forward and backward
differences are used to prevent unintended extrapolation beyond the observed domain.

\strong{Time-Invariant Terms and Random Effects:}
Intercepts, main treatment effects, and terms constant with respect to time cancel
analytically in \eqn{X(t + \epsilon) - X(t - \epsilon)}. Environmental and experimental
unit random effects are excluded by default to yield population-adjusted treatment rates,
consistent with \code{\link{functional_curves}}.

\strong{No-Epidemic and Flat Curves:}
Curves with all observed response values equal to zero (or estimated rates below
numerical tolerance \eqn{10^{-6}}) explicitly return \eqn{r_{max} = 0}, \eqn{t_{r_{max}} = \text{NA}},
\eqn{\text{growth\_duration} = 0}, and \eqn{\text{cumulative\_positive\_growth} = 0}.
}
\examples{
\dontrun{
set.seed(123)
df <- data.frame(
  time = rep(1:30, 3),
  treatment = rep(c("Early", "Late", "None"), each = 30),
  y = c(
    1 / (1 + exp(-(1:30 - 10) * 0.4)),  # Early
    1 / (1 + exp(-(1:30 - 20) * 0.4)),  # Late
    rep(0, 30)                          # None
  )
)

curves <- functional_curves(
  data = df, time = "time", response = "y", treatment = "treatment",
  min_points = 3, show_progress = FALSE, family_try = "quasibinomial"
)

rates <- functional_rate(curves)
print(rates)
summary(rates)
plot(rates)
}

}
\references{
Madden, L. V., Hughes, G., & van den Bosch, F. (2007).
The Study of Plant Disease Epidemics. APS Press, St. Paul, MN.

Wood, S. N. (2017). Generalized Additive Models: An Introduction with R (2nd ed.).
Chapman and Hall/CRC.

Simpson, G. L. (2018). Modelling Palaeoecological Time Series Using Generalized Additive Models.
Frontiers in Ecology and Evolution, 6, 149.
}
