Decompose a time series into trend, seasonal, and residual components

Wrapper around stats::stl() for HMIS monthly data. Extracts trend, seasonal, and remainder components from a time series.

Usage

decompose_series(
  data,
  value_col = "value",
  frequency = 12,
  s.window = "periodic"
)

Arguments

data

Data frame with monyear and value columns.

value_col

Column name for values. Default "value".

frequency

Seasonal frequency. Default 12 (monthly → annual cycle).

s.window

Either "periodic" (default, assumes seasonality is constant across all years) or an odd integer controlling the loess window for seasonal extraction. Use an integer (e.g., 13) to allow seasonality to evolve over time, which may be more appropriate for long HMIS series spanning 17+ years.

Value

A data frame with columns: date, observed, trend, seasonal, remainder.

Examples

if (FALSE) { # \dontrun{
births <- get_hmis("Number of female live births",
  state = "Kerala", category = "Total", sector = "Total"
)
decomp <- decompose_series(births)

# Allow seasonality to evolve over time
decomp2 <- decompose_series(births, s.window = 13)
} # }