Update docs for VARIMA identification

Ref #421

R/VARIMA.R

@@ -90,8 +90,10 @@ specials_varima <- new_specials(
 #' @aliases report.VARIMA
 #'
 #' @param formula Model specification (see "Specials" section).
-#' @param identification The identification technique used to estimate the model.
+#' @param identification The identification technique used to estimate the model. Possible options include NULL (automatic selection), "kronecker_indices" (Kronecker index identification), and "scalar_components" (scalar component identification). More details can be found in the "Identification" section below.
 #' @param ... Further arguments for arima
+#' 
+#' @return A model specification.
 #'
 #' @section Specials:
 #'
@@ -107,7 +109,7 @@ specials_varima <- new_specials(
 #'   `q`      \tab The order of the non-seasonal moving average (MA) terms. If multiple values are provided, the one which minimises `ic` will be chosen. \cr
 #' }
 #' }
-
+#'
 #' \subsection{xreg}{
 #' Exogenous regressors can be included in an VARIMA model without explicitly using the `xreg()` special. Common exogenous regressor specials as specified in [`common_xregs`] can also be used. These regressors are handled using [stats::model.frame()], and so interactions and other functionality behaves similarly to [stats::lm()].
 #'
@@ -122,10 +124,49 @@ specials_varima <- new_specials(
 #' }
 #' }
 #'
-#' @return A model specification.
+#' @section Identification:
+#' 
+#' \subsection{Kronecker indices (`"kronecker_indices"`, the default)}{
+#' Determines the structural complexity and degrees of freedom in a VARIMA model
+#' by analysing the singularities in the polynomial matrices.
+#' 
+#' Kronecker indices represent the structural properties of the VARIMA system, 
+#' focusing on the relationship between system inputs and outputs. These indices
+#' define the minimal realisation of the model, helping to determine the order 
+#' and complexity of each equation in the system. They are particularly suited 
+#' for capturing dynamic dependencies in multivariate systems with cointegrated 
+#' processes. This is particularly useful for understanding system-wide 
+#' dependencies and cointegrating relationships, however it is computationally
+#' intensive for models with many variables.
+#' }
+#' \subsection{Scalar components (`"scalar_components"`)}{
+#' Simplifies VARIMA models by identifying univariate "scalar components" that
+#' combine linear combinations of variables into simpler sub-models. This uses
+#' canonical correlation analysis (CCA) to find linear combinations of variables
+#' with minimal lag orders. These combinations are then modeled as simpler 
+#' ARIMA processes reducing the complexity and dimensionality of the full
+#' VARIMA model. This is particularly useful for identifying models with many
+#' variables, however it assumes good separability of the components.
+#' }
+#' \subsection{No identification (`"none"`)}{
+#' Directly estimates the model as specified by `p`, `d`, and `q`. This allows
+#' all coefficients up to lag `p` and `q` (for the AR and MA components) to be
+#' freely estimated. This can be problematic as the estimation of parameters 
+#' without identification is not unique.
+#' 
+#' Identification is necessary for VARIMA models to ensure that the model is 
+#' parsimonious, unique, and interpretable. Without proper identification, the
+#' model can become overly complex, redundant, or ambiguous, making estimation
+#' and interpretation challenging.
+#' }
+#' 
+#' For a more detailed comparison of identification methods, refer to 
+#' Athanasopoulos et al (2012).
 #'
 #' @seealso
 #' [`MTS::VARMA()`], [`MTS::Kronfit()`].
+#' 
+#' @references Athanasopoulos, George, D. S. Poskitt, and Farshid Vahid. "Two Canonical VARMA Forms: Scalar Component Models Vis-à-Vis the Echelon Form." Econometric Reviews 31, no. 1 (January 2012): 60–83. https://doi.org/10.1080/07474938.2011.607088.
 #'
 #' @examplesIf requireNamespace("tsibbledata", quietly = TRUE)
 #' library(tsibbledata)