feat: rolling aggregations, and reject irregular period grids

DESCRIPTION

@@ -5,7 +5,9 @@ Version: 1.4.0
 Description: Provides a unified interface to extract trends, cycles, and
     seasonal components from monthly and quarterly time series using
     established econometric filters and smoothing methods, with
-    frequency-aware defaults for common economic frequencies.
+    frequency-aware defaults for common economic frequencies. Rolling and
+    year-to-date aggregations are also available, including the compounded
+    accumulation of rates of change.
 License: MIT + file LICENSE
 Encoding: UTF-8
 Language: en-US

NAMESPACE

@@ -1,13 +1,20 @@
 # Generated by roxygen2: do not edit by hand
 
+export(augment_rolling)
 export(augment_trends)
 export(decompose_series)
 export(deseason_series)
 export(detrend_series)
 export(df_to_ts)
 export(extract_trends)
+export(roll_series)
 export(ts_to_df)
+importFrom(RcppRoll,roll_max)
 importFrom(RcppRoll,roll_mean)
+importFrom(RcppRoll,roll_min)
+importFrom(RcppRoll,roll_prod)
+importFrom(RcppRoll,roll_sd)
+importFrom(RcppRoll,roll_sum)
 importFrom(cli,cli_abort)
 importFrom(cli,cli_inform)
 importFrom(cli,cli_warn)
@@ -32,6 +39,7 @@ importFrom(stats,loess)
 importFrom(stats,poly)
 importFrom(stats,predict)
 importFrom(stats,residuals)
+importFrom(stats,sd)
 importFrom(stats,setNames)
 importFrom(stats,smooth.spline)
 importFrom(stats,start)

NEWS.md

@@ -1,3 +1,68 @@
+# trendseries (development version)
+
+## New Features
+
+* New `augment_rolling()` and `roll_series()` add rolling and year-to-date
+  aggregations, mirroring the `augment_trends()` / `extract_trends()` pair.
+  `augment_rolling()` takes a data frame and adds `roll_{stat}_{window}`
+  columns (e.g. `roll_sum_12`); `roll_series()` takes a `ts`, `xts`, or `zoo`
+  object and returns `ts` results. Six statistics are available: `"sum"`,
+  `"chain"`, `"mean"`, `"sd"`, `"min"`, and `"max"`.
+
+  These are aggregations rather than trend estimators, and are deliberately
+  kept out of the trend method registry so they are never passed to
+  `detrend_series()`, which would subtract them from the series. Notable
+  points:
+  - `stats = "chain"` compounds rates of change as `prod(1 + r) - 1`, which is
+    the correct 12-month accumulation for a series that is already a rate
+    (monthly inflation, monthly returns). Summing such a series only
+    approximates it. Use `percent = TRUE` when rates are in percentage points;
+    a warning is issued when the values look mis-scaled for the declared
+    setting.
+  - `window = "ytd"` computes an expanding year-to-date accumulation that
+    resets each January (or Q1), for any of the six statistics.
+  - `window` accepts a vector (e.g. `c(3, 6, 12)`), adding one column per
+    value, and `stats` accepts a vector, so several statistics and windows can
+    be requested in one call.
+  - `align` defaults to `"right"` (causal), the convention for accumulated
+    economic indicators, rather than the centred default used for trends.
+  - Grouped series are supported via `group_cols`, and multiple `value_col`
+    entries are suffixed with the column name.
+  - Rows with missing values keep their calendar position, so windows stay
+    aligned with the dates; `na_rm` controls whether an affected window yields
+    `NA` or is computed from the observations present.
+
+* `roll_series(x, "mean", window = k, align = "right")` is equivalent to
+  `extract_trends(x, "ma", window = k, align = "right")`, and the rolling sum
+  is `k` times that value. The rolling family is the one to reach for when the
+  accumulated quantity is itself the number of interest.
+
+## Bug Fixes
+
+* `augment_trends()`, `decompose_series()`, `deseason_series()`, and
+  `detrend_series()` no longer return silently misdated results for series with
+  a gap in the middle. Observations are placed at consecutive positions in a
+  `ts`, so a missing period shifted every later observation one period earlier;
+  results were then merged back by date and landed on the wrong rows, and the
+  series lost its final period. In a 36-month example with one missing month,
+  23 of the 24 rows after the gap were wrong, and `decompose_series()`'s
+  documented `value = trend + seasonal + remainder` identity held on only 19 of
+  59 rows.
+
+  Two situations triggered this and neither produced a warning: a row whose
+  value was `NA` (dropped before conversion), and a period absent from the data
+  altogether. Both now raise an error naming the missing periods and
+  distinguishing the two causes. Duplicated periods, which corrupt the series
+  in the same way, are rejected as well.
+
+  Leading and trailing missing values are unaffected and continue to work, as
+  they cannot open an interior gap. Series whose frequency has no exact
+  calendar period (weekly, daily) are not checked.
+
+  A future release may fit through interior gaps instead of rejecting them;
+  that requires a per-method policy for missing values, since 6 of the 20 trend
+  methods cannot produce a result from a series containing `NA`.
+
 # trendseries 1.4.0
 
 This release combines the 1.3.0 development series, which was never published