Package 'camplet'

Coerce a 'camplet' result to a data frame

Description

Coerce a 'camplet' result to a data frame

Usage

## S3 method for class 'camplet'
as.data.frame(x, ..., diagnostics = TRUE)

Arguments

x	a 'camplet' object, as returned by [camplet()].
...	unused.
diagnostics	if 'TRUE' (default), include the per-period adaptive diagnostic columns (see [camplet()]) alongside 'raw'/'sa'/'seasonal'.

Value

a 'data.frame' with one row per input observation: the columns of 'x$data', plus the diagnostic columns if 'diagnostics = TRUE'.

---

CAMPLET seasonal adjustment

Description

Seasonally adjusts a single time series with the CAMPLET algorithm: a transparent, adaptive method that corrects for seasonality and outliers via arithmetic-progression updates, without model identification or optimisation. See Abeln and Jacobs (2023) for the method.

Usage

camplet(
  x,
  dates = NULL,
  periodicity = NULL,
  ca = 0,
  mu = 50,
  pa = 1,
  le = 0,
  ti = 1
)

Arguments

x	a numeric vector or 'ts' object, without missing values.
dates	optional 'Date' or 'POSIXct' vector, same length as 'x'; required only when 'periodicity = 31' (calendar-aware, variable-month-length mode for daily data). If supplied, it is checked for regular spacing (see Input checks) and used as the 'time' column of the result.
periodicity	periods per year (e.g. '12', '4'), a cycle length in rows (e.g. '7' for day-of-week seasonality), or '31' for calendar-aware daily mode. If 'x' is a 'ts' object this defaults to 'frequency(x)'; otherwise it is required.
ca, mu, pa, le, ti	CAMPLET tuning parameters; see Details. 'ca = 0' and ‘le = 0' mean "derive a default from 'periodicity'" (the algorithm’s own convention).

Details

The five tuning parameters are:

ca

Common Adjustment: weight applied to normal (non-outlier) observations. '0' = derive from periodicity.

mu

Multiplier: scales the correction applied to outliers.

pa

Pattern-shift length in years.

le

Limit-to-Error: the percent threshold separating an outlier from a normal observation. '0' = derive from periodicity.

ti

Times: number of successive same-direction outliers tolerated before a pattern shift is declared.

Value

an object of class '"camplet"', a list with:

data

a 'data.frame' with one row per input observation: 'time' (if available), 'raw', 'sa' (seasonally adjusted) and 'seasonal'.

diagnostics

a 'data.frame', one row per input observation, with the per-period adaptive-parameter trace the original VBA tool wrote to its "Adj_" worksheets: 'n', 'x', 'ca', 'mu', 'pa', 'le', 'ti', 'expo_e', 'abs_pct_e', 'years', 'weight', 'growth'.

accuracy

CAMPLET's own accuracy metric (0-100).

average_extrapolation_error, outlier_percentage

diagnostic summary scalars feeding into 'accuracy'.

parameter_summary

character, the final effective '"ca / mu / pa / le / ti"'.

Input checks

CAMPLET reads observations by position: the k-th value is taken to be the period after the (k-1)-th. 'camplet()' therefore stops with an error when

• 'x' contains 'NA', 'NaN' or infinite values;

• 'dates' contains duplicated or out-of-order timestamps, or is not regularly spaced (e.g. a missing month). Regular means a constant step (daily, weekly, ...), calendar months/quarters/years on a consistent day of the month, or business days (Monday to Friday) without holiday gaps.

It warns when an explicit 'periodicity' contradicts monthly or quarterly data, i.e. 'frequency(x)' or the spacing of 'dates', such as 'periodicity = 4' for a monthly series. A plain numeric 'x' without 'dates' cannot be checked: making sure it has no gaps is up to the caller.

References

Abeln, B. and Jacobs, J. P. A. M. (2023). *Seasonal Adjustment Without Revisions: A Real-Time Approach*. SpringerBriefs in Economics. Springer, Cham. doi:10.1007/978-3-031-22845-2

Examples

x <- AirPassengers
res <- camplet(x)
res$accuracy
head(as.data.frame(res))

---