% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/TimescaleDecomposition.R
\name{TimescaleDecomposition}
\alias{TimescaleDecomposition}
\title{Timescale Decomposition}
\usage{
TimescaleDecomposition(
  data,
  ftime_dim = "time",
  fq = 12,
  lambda = 1,
  method = "gcv",
  return_type = "percentages",
  ncores = NULL
)
}
\arguments{
\item{data}{A numeric array containing time-series data. The array must
include at least the named dimension specified in 'ftime_dim'.}

\item{ftime_dim}{A character string indicating the name of forecast time
dimension. The default value is 'time'.}

\item{fq}{An integer indicating the number of observations per year (default
12, for monthly data). The decadal cutoff for the Butterworth filter is 10
times the 'fq' value.}

\item{lambda}{A non-negative integer that controls how close the optimal span
selection in the LOESS smoothing will be to the decadal cutoff. The default
value is 1. Values of lambda close to zero may result in the trend component
capturing more of the decadal component (trend is smooth and less linear),
while higher values may result in the trend component capturing less of the
decadal component (trend is stringent and more linear).}

\item{method}{Character string indicating the method to use for selecting the
optimal span. Must be either \code{"gcv"} (Generalized Correlated
Cross-Validation) (default), \code{"aic"} (Akaike Information Criterion), or
\code{"rsq"} (R Squared).}

\item{return_type}{Character string indicating the output format. Must be
either \code{"percentages"} (default) for variance percentages of each
component or \code{"values"} for actual component time series.}

\item{ncores}{An integer indicating the number of cores to use for parallel
computation. The default value is NULL.}
}
\value{
A named list with the following elements:
\describe{
  \item{pct_trend / comp_trend}{Trend component:
    \itemize{
      \item If \code{return_type = "percentages"}: percentages of each component.
      \item If \code{return_type = "values"}: time series of each component.
    }}
  \item{pct_seasonal / comp_seasonal}{Seasonal component (same dimensional structure as above).}
  \item{pct_decadal / comp_decadal}{Decadal component (same dimensional structure as above).}
  \item{pct_residual / comp_residual}{Residual component (same dimensional structure as above).}
}
}
\description{
This function decomposes grid point time series into trend, 
decadal and residual components using LOESS smoothing and Butterworth filtering.
If the frequency of the given time series object is higher than yearly data 
(e.g daily, monthly data), the seasonal component is also calculated. The 
function returns either variance percentages for each component or their values
across spatial grids.
}
\examples{
# Time-based decomposition
data <- array(rnorm(120 * 3 * 2), dim = c(time = 120, lat = 3, lon = 2))

# Add some variability to the data
data <- data +
  array(rep(seq(1, 120) * 0.05, each = 3 * 2),
        dim = c(time = 120, lat = 3, lon = 2)) + # Trend
  array(rep(sin(seq(1, 120) / 12 * 2 * pi) * 2, each = 3 * 2),
        dim = c(time = 120, lat = 3, lon = 2)) + # Seasonal
  array(rep(sin(seq(1, 120) / 60 * 2 * pi) * 1.5, each = 3 * 2),
        dim = c(time = 120, lat = 3, lon = 2)) # Decadal

result <- TimescaleDecomposition(data)
str(result)

}
\references{
Campos, D. A., Olmo, M. E., Cos, P., Muñoz, Á. G., & Doblas-Reyes,
F. J. (2025). Regional aspects of observed temperature and precipitation trends
in the western Mediterranean: Insights from a timescale decomposition analysis.
Journal of Geophysical Research: Atmospheres, 130, e2024JD042637.
https://doi.org/10.1029/2024JD042637.
}
\author{
Javier Corvillo, \email{javier.corvillo@bsc.es}
}
