Seasonality test based on the coefficient of variation for the variable and lagged component series. A linear trend is removed first (detrend = TRUE), keeping the mean of the variable, so that a trend does not mask the period. For each lag m, the variable is split into its m component series variable[seq(j, n, m)], j = 1, ..., m, and lag m is reported when the length-weighted mean of the component coefficients of variation is below the coefficient of variation of the variable. Dispersion is the Gini mean difference, the degree-1 lower plus upper partial moment about each observation in turn, which is unbiased for any distribution at any component length. The coefficient of variation is used when the (detrended) variable stays on one side of zero; otherwise dispersions are compared directly. Lags are scanned up to max.period, by default n / 5, so every component series has at least 5 observations. Periods added through modulo are kept up to n / 2. On a series without seasonality about half of the lags pass by chance, so treat the result as candidate periods and validate them, for example with NNS.ARMA.optim, or set p.value = TRUE. A result of 1 signifies no seasonality present. A multiple of the true period scores as well in expectation, and its shorter components make its score noisier, so the lowest score often falls on a multiple. best.period is therefore the fundamental period: the smallest period that divides the lowest-scoring lag, or nearly divides it for a non-integer period, and whose score exceeds the lowest by at most two jackknife standard errors of their difference, from paired delete-one scores. It is listed first in all.periods and periods, followed by the other periods in order of score.
Usage
NNS.seas(
variable,
modulo = NULL,
mod.only = TRUE,
plot = TRUE,
detrend = TRUE,
max.period = NULL,
p.value = FALSE,
nperm = 100L,
dispersion = c("auto", "absolute")
)Arguments
- variable
a numeric vector.
- modulo
integer(s); NULL (default) Adds the multiples of
moduloon either side of each detected period (period 7 withmodulo = 5gives 5 and 10).- mod.only
logical;
TRUE(default) Limits the number of seasonal periods returned to the specifiedmodulo.- plot
logical;
TRUE(default) Returns the plot of all periods exhibiting seasonality and the variable level reference.- detrend
logical;
TRUE(default) removes the variable's linear trend, keeping its mean, before the lags are scored; an exactly linear variable is then constant and has no seasonal period.- max.period
integer;
NULL(default) scans lags up ton / 5. A smaller value caps the scan, whose cost grows withntimes the number of lags.- p.value
logical;
FALSE(default). IfTRUE, each period's dispersion ratio is compared with the best ratio over all lags innpermshuffled copies of the (detrended) variable, which remove the original temporal ordering. NNS.ARMA's automatic lag selection does not run this test; for a significance-filtered lag, passNNS.seas(variable, p.value = TRUE)$best.period(or$periods) to itsseasonal.factor.all.periodsgains ap.valuecolumn, andperiodsandbest.periodkeep only the periods withp.value <= 0.05(1if none); each copy contributes its best lag, accounting for scanning multiple lags under an exchangeable null. A serially dependent nonseasonal series need not satisfy that null. Uses the random number generator.- nperm
integer; 100 (default) number of shuffled copies when
p.value = TRUE.- dispersion
"auto"(default) retains relative CV scoring on one-sided data and absolute Gini dispersion otherwise."absolute"always compares Gini dispersions, by centering the series first; use this translation-invariant option for interval-scale data such as temperature.
Value
Returns a matrix of all periods exhibiting less coefficient of variation than the variable with "all.periods"; and the fundamental period with "best.period" (see Description); as well as a vector of "periods" for easy call into NNS.ARMA.optim. If no seasonality is detected, all.periods holds a single row with Period = 1 and a coefficient of variation equal to the variable's (Period = 0 for fewer than 5 observations). The coefficients of variation are those of the detrended variable when detrend = TRUE.
Note
The historical column names Coefficient.of.Variation and Variable.Coefficient.of.Variation are retained in absolute mode; their values then contain absolute Gini dispersions.
best.period need not be the lowest-scoring lag: with(all.periods, Period[which.min(Coefficient.of.Variation)]) returns that lag. The jackknife behind the two-standard-error rule treats observations as exchangeable and does not adjust for serial dependence. The minimum five observations per component is a reliability default; modulo can supply longer domain-informed candidates. Shuffling removes serial dependence as well as seasonality, so the optional permutation comparison is not calibrated against every dependent nonseasonal process.
References
Viole, F. and Nawrocki, D. (2013) "Nonlinear Nonparametric Statistics: Using Partial Moments" (ISBN: 1490523995, 2nd edition: https://ovvo-financial.github.io/NNS/book/)
Examples
if (FALSE) { # \dontrun{
set.seed(123)
x <- rnorm(100)
## To call strongest period based on coefficient of variation:
NNS.seas(x, plot = FALSE)$best.period
## Using modulos for logical seasonal inference:
NNS.seas(x, modulo = c(2,3,5,7), plot = FALSE)
## Keep only periods that beat shuffled copies of the series:
NNS.seas(x, plot = FALSE, p.value = TRUE)$best.period
} # }