% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ild_kfas.R
\name{ild_kfas}
\alias{ild_kfas}
\title{Fit a Gaussian state-space model via KFAS (single-subject ILD)}
\usage{
ild_kfas(
  data,
  outcome,
  state_spec = "local_level",
  observation_family = "gaussian",
  time_units,
  irregular_time = FALSE,
  smoother = TRUE,
  forecast_horizon = 0L,
  fit_context = c("single_series", "independent_series_per_id"),
  ...
)
}
\arguments{
\item{data}{An object that passes [validate_ild()] (e.g. after [ild_prepare()]).}

\item{outcome}{Character name of the numeric outcome column.}

\item{state_spec}{Character; use \code{"local_level"} in v1. See
\code{inst/dev/KFAS_V1_BACKEND.md} for the full controlled vocabulary.}

\item{observation_family}{Currently only \code{"gaussian"}.}

\item{time_units}{Character describing the time column (e.g. \code{"days"},
\code{"hours"}). Stored in provenance; required for clear reporting.}

\item{irregular_time}{Logical; if \code{TRUE}, skips the irregular-spacing warning.}

\item{smoother}{Logical; passed to \code{KFS()} smoothing (default \code{TRUE}).}

\item{forecast_horizon}{Integer; when \code{> 0}, used by \code{\link{ild_plot_forecast}()}
with \code{\link[stats]{predict}} on the fitted model and stored in \code{mapping$forecast_horizon}.}

\item{fit_context}{\code{"single_series"} (default) or \code{"independent_series_per_id"}
when you have fit the **same** state-space template separately for multiple persons
and must not interpret results as a pooled multilevel latent model. The latter
triggers guardrail \code{GR_KFAS_UNMODELED_BETWEEN_PERSON_HETEROGENEITY}.}

\item{...}{Passed to \code{KFAS::fitSSM()} (e.g. \code{method}, \code{inits}).}
}
\value{
An object of class \code{c("ild_fit_kfas", "ild_fit_model", "ild_analysis")}
  with list slots \code{kfas_model}, \code{kfs}, \code{spec}, \code{state_labels},
  \code{mapping}, \code{schema_version}, \code{preprocessing}. Attributes \code{ild_data} and
  \code{ild_provenance} are set.
}
\description{
Opinionated entry point for **local level** models in v1. Requires the
\pkg{KFAS} package. One distinct \code{.ild_id} per fit; subset your data first.
}
\seealso{
\code{inst/dev/KFAS_V1_BACKEND.md}, [ild_tidy()], [ild_augment()], [ild_diagnose()].

\strong{Conceptual vignettes:}
\itemize{
  \item \href{../doc/kfas-state-space-modeling.html}{\code{vignette("kfas-state-space-modeling", package = "tidyILD")}}
  \item \href{../doc/kfas-irregular-timing-spacing.html}{\code{vignette("kfas-irregular-timing-spacing", package = "tidyILD")}}
  \item \href{../doc/kfas-choosing-backend.html}{\code{vignette("kfas-choosing-backend", package = "tidyILD")}}
}
}
