% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functional_instability.R
\name{functional_instability}
\alias{functional_instability}
\alias{functional_instability.functional_curves}
\alias{functional_instability.functional_dsp}
\title{Normalized functional instability from fitted functional disease curves}
\usage{
functional_instability(x, ...)

\method{functional_instability}{functional_curves}(
  x,
  n_time = 200,
  env_sep = NULL,
  env_names = c("location", "year"),
  return_curves = FALSE,
  ...
)

\method{functional_instability}{functional_dsp}(
  x,
  env_sep = NULL,
  env_names = c("location", "year"),
  return_curves = FALSE,
  ...
)
}
\arguments{
\item{x}{An object returned by \code{\link{functional_curves}} or a \code{functional_dsp} object.}

\item{...}{Additional arguments.}

\item{n_time}{Number of points in the prediction grid over the time domain.}

\item{env_sep}{Optional separator used to split \code{env} into spatial and
temporal components, for example \code{"_"} or \code{"-"}. If \code{NULL}, only the
overall NFI is returned.}

\item{env_names}{A character vector of length 2 giving the names of the
components obtained after splitting \code{env}. Default is
\code{c("location", "year")}.}

\item{return_curves}{Logical. If \code{TRUE}, the predicted genotype-by-environment
curves are also returned.}
}
\value{
If \code{return_curves = FALSE}, a tibble with one row per genotype and
columns:
\describe{
\item{geno}{Treatment or genotype identifier.}
\item{n_env}{Number of environments used in the calculation.}
\item{FI}{Absolute functional instability.}
\item{mean_energy}{Integrated squared mean epidemic curve.}
\item{nFI}{Normalized functional instability. Lower values indicate
greater stability.}
}

If \code{env_sep} is provided, the returned tibble also includes:
\describe{
\item{FI_space, mean_energy_space, nFI_space}{Spatial component of
instability.}
\item{FI_time, mean_energy_time, nFI_time}{Temporal component of
instability.}
}

If \code{return_curves = TRUE}, a list is returned with two elements:
\describe{
\item{metrics}{The tibble described above.}
\item{curves}{A tibble of predicted genotype-by-environment curves with
columns \code{geno}, \code{env}, \code{time}, \code{mu}, and \code{eta}.}
}
}
\description{
Computes normalized functional instability (NFI) for each treatment
based on genotype-by-environment predicted curves extracted from a
\code{\link{functional_curves}} object. Optionally, instability can be decomposed
into spatial and temporal components if the environment identifier can
be split into location and year.
}
\details{
The overall instability metric is defined as the mean integrated squared
deviation of each genotype-by-environment curve from the genotype-specific
mean curve across environments, normalized by the integrated squared mean
curve.

Let \eqn{f_{ge}(t)} denote the predicted epidemic trajectory of genotype
\eqn{g} in environment \eqn{e}, and let \eqn{\bar f_g(t)} denote the mean
trajectory of genotype \eqn{g} across environments. Functional instability
is computed as:

\deqn{
FI_g = \frac{1}{E_g}\sum_{e=1}^{E_g} \int_T \left(f_{ge}(t)-\bar f_g(t)\right)^2 dt
}

and normalized as:

\deqn{
nFI_g = \frac{FI_g}{\int_T \bar f_g(t)^2 dt}
}

Numerical integration is performed with the trapezoidal rule on a regular
prediction grid over the observed time domain.
}
\examples{
\dontrun{
m1 <- r4pde::functional_curves(
  data = dat_ready,
  time = "time",
  response = "y",
  treatment = "geno",
  environment = "env"
)

# Overall instability
res <- functional_instability(m1)
res

# Overall + spatial and temporal components
# Assuming env has values such as "PF_2021"
res2 <- functional_instability(m1, env_sep = "_")
res2

# Return curves used in the calculations
out <- functional_instability(m1, env_sep = "_", return_curves = TRUE)
out$metrics
head(out$curves)
}

}
\seealso{
\code{\link{functional_curves}}
}
