functional_instability: Normalized functional instability from fitted functional...

In r4pde: Tools for Quantitative Plant Disease Epidemiology

Normalized functional instability from fitted functional disease curves

Description

Computes normalized functional instability (NFI) for each treatment based on genotype-by-environment predicted curves extracted from a functional_curves object. Optionally, instability can be decomposed into spatial and temporal components if the environment identifier can be split into location and year.

Usage

functional_instability(x, ...)

## S3 method for class 'functional_curves'
functional_instability(
  x,
  n_time = 200,
  env_sep = NULL,
  env_names = c("location", "year"),
  return_curves = FALSE,
  ...
)

## S3 method for class 'functional_dsp'
functional_instability(
  x,
  env_sep = NULL,
  env_names = c("location", "year"),
  return_curves = FALSE,
  ...
)

Arguments

x	An object returned by functional_curves or a functional_dsp object.
...	Additional arguments.
n_time	Number of points in the prediction grid over the time domain.
env_sep	Optional separator used to split env into spatial and temporal components, for example "_" or "-". If NULL, only the overall NFI is returned.
env_names	A character vector of length 2 giving the names of the components obtained after splitting env. Default is c("location", "year").
return_curves	Logical. If TRUE, the predicted genotype-by-environment curves are also returned.

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 f_{ge}(t) denote the predicted epidemic trajectory of genotype g in environment e, and let \bar f_g(t) denote the mean trajectory of genotype g across environments. Functional instability is computed as:

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:

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.

Value

If return_curves = FALSE, a tibble with one row per genotype and columns:

geno

Treatment or genotype identifier.

n_env

Number of environments used in the calculation.

FI

Absolute functional instability.

mean_energy

Integrated squared mean epidemic curve.

nFI

Normalized functional instability. Lower values indicate greater stability.

If env_sep is provided, the returned tibble also includes:

FI_space, mean_energy_space, nFI_space

Spatial component of instability.

FI_time, mean_energy_time, nFI_time

Temporal component of instability.

If return_curves = TRUE, a list is returned with two elements:

metrics

The tibble described above.

curves

A tibble of predicted genotype-by-environment curves with columns geno, env, time, mu, and eta.

See Also

functional_curves

Examples

## Not run: 
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)

## End(Not run)

r4pde documentation built on Sept. 8, 2026, 1:10 a.m.