% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functional_suppression_profiles.R
\name{functional_suppression_profiles}
\alias{functional_suppression_profiles}
\title{Functional suppression profiles of disease control treatments}
\usage{
functional_suppression_profiles(
  data,
  reference,
  time = "time",
  response = "severity",
  treatment = "treatment",
  environment = NULL,
  by_environment = FALSE,
  env_ref = NULL,
  threshold = 5,
  metrics = c("protected_area", "max_suppression", "persistence", "centroid"),
  dist_method = "euclidean",
  hclust_method = "average",
  k = "auto",
  cut_height = NULL,
  ...
)
}
\arguments{
\item{data}{A data frame or tibble containing the disease progress data.}

\item{reference}{Character string specifying the reference treatment name.}

\item{time}{Character string specifying the time column. Default is \code{"time"}.}

\item{response}{Character string specifying the response column. Default is \code{"severity"}.}

\item{treatment}{Character string specifying the treatment column. Default is \code{"treatment"}.}

\item{environment}{Character string specifying the environment column (optional).}

\item{by_environment}{Logical; if \code{TRUE}, the analysis is run separately for each environment. Default is \code{FALSE}.}

\item{env_ref}{Character string specifying the reference environment for joint analysis (optional).}

\item{threshold}{Numeric threshold for the persistence metric. Default is \code{5}.}

\item{metrics}{Character vector of metrics to include in the ranking. Default is \code{c("protected_area", "max_suppression", "persistence", "centroid")}.}

\item{dist_method}{Character string specifying the distance method. Default is \code{"euclidean"}.}

\item{hclust_method}{Character string specifying the hierarchical clustering method. Default is \code{"average"}.}

\item{k}{Integer specifying the number of functional profiles to create, or \code{"auto"} (default). When \code{"auto"}, the optimal number of profiles is estimated by maximizing the average silhouette width.}

\item{cut_height}{Numeric specifying the cut height for clustering. If provided, overrides \code{k}.}

\item{...}{Additional arguments passed to \code{\link{functional_contrast}}.}
}
\value{
A list of class \code{"functional_suppression_profiles"} containing:
\itemize{
\item \code{call}: The matched call.
\item \code{reference}: The reference treatment name.
\item \code{contrast}: The contrast data from \code{functional_contrast}.
\item \code{dsp_curves}: The fitted curves from \code{functional_curves}.
\item \code{distances}: The distances object from \code{functional_distances}.
\item \code{hclust}: The hierarchical clustering object.
\item \code{clusters}: A tibble with treatment cluster assignments (internal).
\item \code{profiles}: A lightweight tibble mapping treatments to profiles.
\item \code{classification}: A tibble with the final classification combining profiles, mean rank, and functional metrics, ordered by mean rank.
\item \code{summary}: A tibble with functional summary metrics.
\item \code{ranking}: A tibble with metric rankings.
\item \code{cluster_summary}: A tibble combining metrics, ranks, and cluster assignments.
\item \code{parameters}: A list of input parameters.
}
}
\description{
Computes disease suppression trajectories relative to a reference treatment, estimates functional distances among suppression curves, clusters treatments according to their temporal suppression profiles, and summarizes each profile using functional suppression metrics.
}
\details{
A Functional Suppression Profile (FSP) is the temporal trajectory of disease
suppression produced by a treatment relative to an untreated or reference control.
Functional distances and hierarchical clustering are computed from smoothed disease
suppression trajectories rather than raw observed suppression values. Functional
summary metrics are subsequently used to interpret the resulting suppression profiles.

The workflow includes contrasting treatments against a reference, fitting functional
curves, calculating distances, clustering, and summarizing the suppression using
metrics like protected area, maximum suppression, and persistence.

Treatments belonging to the same functional suppression profile are displayed using
the same colour throughout all graphical summaries. This visual consistency facilitates
interpretation of the relationship between suppression trajectories, functional clustering,
and suppression metrics.

The \code{classification} table combines functional profile membership, suppression metrics,
and mean functional rank. Functional profiles are defined from distances among smoothed
suppression trajectories, whereas mean rank summarizes the overall performance across
functional suppression metrics.
}
\examples{
\dontrun{
sim_dat <- tibble::tibble(
  treatment = rep(c("Control", "A", "B", "C"), each = 6),
  time = rep(seq(0, 25, by = 5), times = 4),
  severity = c(
    c(5, 10, 20, 35, 50, 65),
    c(3, 5, 10, 18, 30, 40),
    c(4, 6, 12, 22, 35, 45),
    c(2, 4, 8, 14, 22, 32)
  )
)
fsp <- functional_suppression_profiles(
  data = sim_dat,
  reference = "Control",
  time = "time",
  response = "severity",
  treatment = "treatment",
  threshold = 5,
  k = 2
)

fsp
summary(fsp)
plot(fsp, type = "dendrogram")
plot(fsp, type = "profiles")
plot(fsp, type = "heatmap")
plot(fsp, type = "rank")
}
}
\seealso{
\code{\link{functional_contrast}}, \code{\link{functional_curves}}, \code{\link{functional_distances}}, \code{\link{functional_summary}}, \code{\link{rank_dsp}}, \code{\link{plot_dendrogram}}
}
