% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functional_pca.R
\name{functional_pca}
\alias{functional_pca}
\alias{functional_pca.functional_curves}
\alias{functional_pca.functional_dsp}
\title{Functional principal component analysis of disease progress curves}
\usage{
functional_pca(object, ...)

\method{functional_pca}{functional_curves}(
  object,
  n_components = NULL,
  var_explained = 0.95,
  center = TRUE,
  scale = FALSE,
  method = c("pca_on_grid"),
  ...
)

\method{functional_pca}{functional_dsp}(
  object,
  n_components = NULL,
  var_explained = 0.95,
  center = TRUE,
  scale = FALSE,
  method = c("pca_on_grid"),
  ...
)
}
\arguments{
\item{object}{An object returned by \code{\link{functional_curves}}.}

\item{...}{Additional arguments for future extensions.}

\item{n_components}{Optional integer number of functional principal components to retain.}

\item{var_explained}{Cumulative variance threshold used when \code{n_components = NULL}.}

\item{center}{Logical; whether to center curves before PCA. Default TRUE.}

\item{scale}{Logical; whether to scale grid columns before PCA. Default FALSE.}

\item{method}{Character; method for FPCA, currently only \code{"pca_on_grid"} is supported.}
}
\value{
An object of class \code{"r4pde_functional_pca"} containing:
\itemize{
\item \code{scores}: Tibble of curve-level FPC scores.
\item \code{eigenfunctions}: Tibble of eigenfunction values across the time grid.
\item \code{variance}: Tibble of eigenvalues, variance explained, and cumulative variance.
\item \code{mean_curve}: Tibble of the mean curve.
\item \code{reconstructed}: Tibble of reconstructed curves using retained components.
\item \code{input_curves}: Tibble of original fitted curves.
\item \code{pca}: The underlying \code{prcomp} object.
\item \code{settings}: List of settings used.
\item \code{call}: The matched call.
}
}
\description{
Performs functional principal component analysis on fitted disease progress curves
returned by \code{\link{functional_curves}}. The function decomposes variation among epidemic
trajectories into orthogonal temporal components and returns curve-level scores,
eigenfunctions, variance explained, and reconstructed curves.
}
\details{
The function uses the fitted curves from \code{functional_curves()} and does not refit
the disease progress model. The first implementation uses PCA on a common prediction grid.
FPC scores can be analyzed as functional epidemiological traits in downstream models.

Interpretation:
\itemize{
\item FPC1 often captures the largest mode of variation, commonly overall epidemic intensity or speed.
\item Later FPCs may capture timing of disease onset, curve crossing, late acceleration, or other shape-related deviations.
\item Interpretation must be data-driven and should be based on eigenfunction plots and mean +/- perturbation plots.
}
}
\examples{
\dontrun{
curves <- functional_curves(...)
fpca <- functional_pca(curves, var_explained = 0.95)

print(fpca)
plot(fpca, type = "scree")
plot(fpca, type = "components")
plot(fpca, type = "scores", components = c(1, 2))

scores <- get_fpca_scores(fpca)
}
}
