% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functional_curves.R
\name{functional_curves}
\alias{functional_curves}
\title{Fit genotype-specific epidemic trajectories using GAM}
\usage{
functional_curves(
  data,
  time,
  response,
  treatment,
  environment = NULL,
  block = NULL,
  unit = NULL,
  response_scale = c("proportion", "percent"),
  eps = 1e-04,
  min_points = 5,
  grid_n = 140,
  env_ref = NULL,
  k_smooth = 10,
  k_env = 4,
  k_trt = 6,
  gamma = 1.4,
  discrete = TRUE,
  family_try = c("betar", "quasibinomial"),
  show_progress = TRUE,
  covariates = NULL,
  include_covariates = FALSE,
  covariate_smooths = FALSE,
  global_smooth = FALSE,
  ...
)
}
\arguments{
\item{data}{A data.frame containing disease progress observations.}

\item{time}{Character string naming the time variable.}

\item{response}{Character string naming the response variable.}

\item{treatment}{Character string naming the treatment/cultivar factor.}

\item{environment}{Optional character string naming an environment factor.}

\item{block}{Optional character string naming a blocking factor.}

\item{unit}{Optional character string naming a unique experimental unit identifier.}

\item{response_scale}{Character string specifying the response scale: \code{"proportion"} or \code{"percent"}.}

\item{eps}{Numeric small constant retained for API compatibility.}

\item{min_points}{Minimum number of observations required per curve.}

\item{grid_n}{Number of time points for evaluating predicted curves.}

\item{env_ref}{Reference environment level used for adjusted predictions.}

\item{k_smooth}{Basis dimension for the global smooth of time.}

\item{k_env}{Basis dimension for the environment-specific smooth.}

\item{k_trt}{Basis dimension for the treatment-specific smooth.}

\item{gamma}{Penalization parameter passed to \code{mgcv::bam()}.}

\item{discrete}{Logical; whether to use discrete (approximate) fitting.}

\item{family_try}{Character string specifying the GAM family to try.}

\item{show_progress}{Logical; whether to show progress.}

\item{covariates}{Optional character vector of genotype-level covariates (e.g., \code{c("heading_group")}).}

\item{include_covariates}{Logical; whether to include covariates as fixed effects in the model.}

\item{covariate_smooths}{Logical; if TRUE and \code{include_covariates = TRUE}, adds smooth interactions \code{s(time, by=covariate)} for factor covariates.}

\item{global_smooth}{Logical; if \code{TRUE}, fits a shared global curve plus treatment deviations. If \code{FALSE} (default), fits independent smooths per treatment.}

\item{...}{Additional arguments.}
}
\value{
An object of class \code{"functional_curves"} containing:
\itemize{
\item \code{gam}: fitted GAM object and \code{family_used};
\item \code{curves}: environment-adjusted treatment mean curves on the common grid;
\item \code{grid}: the time grid used;
\item \code{observed_data}: the processed input data;
\item \code{genotype_info}: a tibble with one row per genotype containing covariates;
\item \code{vars}: variable names used;
\item \code{settings}: model settings;
\item \code{warnings_betar}: any warnings caught during beta fitting;
\item \code{plot_mean}: ggplot object of the mean curves.
}
}
\description{
Fits a generalized additive model (GAM) to replicated disease progress curves,
returning adjusted treatment mean curves evaluated on a common time grid.
}
\details{
Genotype-level covariates are descriptors that do not vary within a genotype, such as phenological groups.
For example, in wheat blast studies, a cultivar's \code{heading_group} (early, intermediate, late)
can be supplied. This helps distinguish between true genetic resistance and phenological escape, as
cultivars with different heading dates may encounter different infection-risk windows in the same
environment. When \code{include_covariates = TRUE}, the model accounts for these covariates,
yielding heading-adjusted functional resistance.
}
\examples{
\dontrun{
fc <- functional_curves(
  data = my_data,
  time = "time_var",
  response = "severity",
  treatment = "cultivar",
  environment = "env",
  covariates = c("heading_group"),
  include_covariates = TRUE,
  covariate_smooths = TRUE
)
plot(fc)
}
}
