Virata manual

tsdecomp

Splits a series into its trend, its seasonal pattern and what is left.

What we have

  • additive and multiplicative decomposition, with generate()
  • checked against R's decompose()

Coming later

  • arima, dfuller and forecasting, which are not built
  • it is not a Stata command, so there is no Stata output to compare with

You may shorten it to tsdeco.

How you write it

tsdecomp var, period(#) [multiplicative] [generate(stub)]

Square brackets mean optional. A vertical bar means choose one.

What it does

Sales rise every December. Is this December good? tsdecomp sales, period(12) separates the long movement (trend), the repeating within-year shape (seasonal) and the leftover (remainder), each as its own column, so you can answer that.

multiplicative is for series whose swings grow with their level — if the December bump is "20% up" rather than "5,000 up", use it.

Watch out. It needs every period present and at least two full cycles. It is not a Stata command — Stata has no tsdecomp — so nothing here corresponds to Stata output. The numbers match R's decompose().

Try it

Every example below was run after sysuse vira.sample04, clear.

. tsset month
 Time variable: month, 1 to 96
         Delta: 1 unit
The same thing in pandas and in R

pandas

# tsset: sorted by the time variable; L. and D. count in time, not rows

R

# no R form for `tsset` yet -- see docs/r-equivalents.md
. tsdecomp revenue, period(12)
Classical additive decomposition of revenue, period 12

  season |        index
---------+--------------
       1 |    -335.9028
       2 |    -282.1778
       3 |    -244.9290
       4 |     -61.2034
       5 |     123.3740
       6 |     267.2853
       7 |     328.6198
       8 |     290.7656
       9 |     251.1531
      10 |      35.0293
      11 |     -96.2475
      12 |    -275.7665

created: revenue_trend, revenue_seasonal, revenue_resid
(the trend and residual are missing for the first and last 6 periods)
The same thing in pandas and in R

pandas

from statsmodels.tsa.seasonal import seasonal_decompose
parts = seasonal_decompose(df["revenue"], model="additive", period=12, two_sided=True)
df["revenue_trend"] = parts.trend
df["revenue_seasonal"] = parts.seasonal
df["revenue_resid"] = parts.resid

R

series <- ts(df$revenue, frequency = 12)
decomposed <- decompose(series, type = "additive")

# This R was run in a real R (4.6.1) and gave the same numbers.
. summarize revenue_trend revenue_seasonal revenue_resid
    Variable |         Obs        Mean   Std. dev.         Min         Max
-------------+------------------------------------------------------------
revenue_tre~ |          84    1151.523    178.1546    879.4167    1481.312
revenue_sea~ |          96  1.7171e-14    240.1762   -335.9028    328.6198
revenue_res~ |          84   -3.141815    122.9338   -400.5531    273.1552
The same thing in pandas and in R

pandas

df[['revenue_trend', 'revenue_seasonal', 'revenue_resid']].describe()

R

library(dplyr)
df %>% summarise(revenue_trend_n = sum(!is.na(revenue_trend)),
    revenue_trend_mean = mean(revenue_trend, na.rm = TRUE),
    revenue_trend_sd = sd(revenue_trend, na.rm = TRUE),
    revenue_trend_min = min(revenue_trend, na.rm = TRUE),
    revenue_trend_max = max(revenue_trend, na.rm = TRUE),
    revenue_seasonal_n = sum(!is.na(revenue_seasonal)),
    revenue_seasonal_mean = mean(revenue_seasonal, na.rm = TRUE),
    revenue_seasonal_sd = sd(revenue_seasonal, na.rm = TRUE),
    revenue_seasonal_min = min(revenue_seasonal, na.rm = TRUE),
    revenue_seasonal_max = max(revenue_seasonal, na.rm = TRUE),
    revenue_resid_n = sum(!is.na(revenue_resid)),
    revenue_resid_mean = mean(revenue_resid, na.rm = TRUE),
    revenue_resid_sd = sd(revenue_resid, na.rm = TRUE),
    revenue_resid_min = min(revenue_resid, na.rm = TRUE),
    revenue_resid_max = max(revenue_resid, na.rm = TRUE))

# This R was run in a real R (4.6.1) and gave the same numbers.
The full built-in help (help tsdecomp)
tsset timevar [, delta(#)]  |  tsset panelvar timevar
L.x  L2.x  F.x  D.x  D2.x  S12.x          in any expression
tsline var [var ...]
tssmooth ma newvar = var, window(#l #c #f)
tsdecomp var, period(#) [multiplicative] [generate(stub)]

    . tsset month
    . generate growth = D.sales / L.sales
    . generate yoy    = S12.sales / L12.sales
    . tsdecomp sales, period(12)
    . tsline sales sales_trend

The operators count in units of the time variable, NOT in rows.  L.x at
month 5 is x at month 4, and it is missing if there is no month 4 -- even
when the row above is month 3.  A plain row shift gets that wrong quietly,
and most real series have a missing month somewhere.  In a panel each unit
is lagged on its own.

  L. / F.    a lag / a lead;   L2. is two periods
  D.         a difference: x - L.x;   D2. is a difference of differences
  S12.       a seasonal difference: x - L12.x

  tssmooth ma   window(2 1 2) is a 5-term centred average.  The edges, where
                the window does not fit, are missing
  tsdecomp      classical decomposition into trend, seasonal and remainder
                (created as var_trend, var_seasonal, var_resid).  Needs every
                period present and two full cycles.  Not a Stata command

Not built: date formats (the time variable is a plain number: 1, 2, 3 or
2019, 2020), arima, Holt-Winters, exponential smoothing, dfuller, forecasting.
The decomposition and moving average are checked against R's decompose() and
stats::filter(); the moving average's edge handling has not been compared
with Stata.

Nearby

tsset tsline tssmooth