% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/suggest_k.R
\name{suggest_k}
\alias{suggest_k}
\title{Suggest GAM smoothing parameters for epidemic curve models}
\usage{
suggest_k(
  data = NULL,
  time = NULL,
  treatment = NULL,
  environment = NULL,
  n_time = NULL,
  n_env = NULL,
  rule = c("minimum", "median"),
  smoothness = c("conservative", "moderate", "flexible")
)
}
\arguments{
\item{data}{Optional data frame.  If supplied, \code{time}, \code{treatment},
and optionally \code{environment} are used to compute summaries of the
number of unique time points and environments per treatment.}

\item{time}{Unquoted column name for the time variable, or a character
string naming the column.}

\item{treatment}{Unquoted column name for the treatment / cultivar variable,
or a character string naming the column.}

\item{environment}{Optional unquoted column name for the environment
variable, or a character string naming the column.}

\item{n_time}{Integer.  Number of unique time points to use directly
(ignored when \code{data} is supplied).}

\item{n_env}{Integer.  Number of unique environments to use directly
(ignored when \code{data} is supplied, or when there is no environment
variable).}

\item{rule}{Character string. How to summarise the distribution of
replication counts across treatment-by-environment combinations:
\code{"minimum"} (default, conservative) or \code{"median"}.}

\item{smoothness}{Character string controlling how liberal the
recommendations are: \code{"conservative"} (default), \code{"moderate"},
or \code{"flexible"}.}
}
\value{
A named list with the following elements:
\describe{
\item{\code{time_summary}}{Named numeric vector with minimum, median, and
maximum unique time points per treatment-by-environment combination.}
\item{\code{environment_summary}}{Named numeric vector with minimum, median,
and maximum unique environments per treatment (or \code{NULL} when no
environment variable is given).}
\item{\code{effective_n_time}}{The effective number of time points chosen
by \code{rule}.}
\item{\code{effective_n_env}}{The effective number of environments chosen
by \code{rule}, or \code{NULL}.}
\item{\code{k_smooth}}{Recommended basis dimension for the global time smooth.}
\item{\code{k_trt}}{Recommended basis dimension for the treatment-specific smooth.}
\item{\code{k_env}}{Recommended basis dimension for the environment random effect.}
\item{\code{gamma}}{Recommended penalisation multiplier.}
\item{\code{message}}{A short interpretation message.}
}
}
\description{
A helper function to guide selection of the \code{k_smooth}, \code{k_trt},
\code{k_env}, and \code{gamma} parameters used by \code{\link{functional_curves}}.
Can infer the effective replication from a data frame or accept scalar values
directly when the data are not yet available.

For sparse epidemic data it is strongly recommended to use
\code{rule = "minimum"} so that k values are based on the least-replicated
treatment-by-environment combination, guarding against over-fitting.
}
\details{
The function computes, for every treatment-by-environment combination, the
number of unique time points at which observations are available.  It then
summarises these counts using the chosen \code{rule} to obtain
\code{effective_n_time}.  Similarly it computes, per treatment, the number
of unique environments, and summarises using the same \code{rule} to obtain
\code{effective_n_env}.

Recommended k values follow these heuristics:
\itemize{
\item \code{k_smooth}: global smooth over time; capped below
\code{effective_n_time - 1}.
\item \code{k_trt}: treatment-specific smooth; capped below
\code{k_smooth}.
\item \code{k_env}: environment random effect; capped below
\code{effective_n_env}.
\item \code{gamma}: penalty multiplier; higher values encourage
smoother fits.
}
}
\examples{
# Using explicit values
suggest_k(n_time = 5, n_env = 8)

# Inferring from a data frame (unquoted column names)
df <- data.frame(
  time      = rep(1:6, times = 6),
  cultivar  = rep(c("A", "B", "C"), each = 12),
  env       = rep(rep(c("E1", "E2"), each = 6), times = 3),
  severity  = runif(36, 0, 0.5)
)
suggest_k(
  data        = df,
  time        = time,
  treatment   = cultivar,
  environment = env,
  rule        = "minimum",
  smoothness  = "conservative"
)

}
