vastorbit.machine_learning.model_selection.statistical_tests.tsa.seasonal_decompose

vastorbit.machine_learning.model_selection.statistical_tests.tsa.seasonal_decompose(input_relation: Annotated[str | VastFrame, ''], columns: Annotated[str | list[str], 'STRING representing one column or a list of columns'], ts: str, by: Annotated[str | list[str], 'STRING representing one column or a list of columns'] | None = None, period: int | tuple | list = -1, polynomial_order: int | tuple | list = 1, estimate_seasonality: bool = True, rule: Annotated[str | timedelta, 'Time Interval'] | None = None, mult: bool = False, two_sided: bool = False, use_row: bool = True, genSQL: bool = False) → VastFrame

Performs a seasonal time series decomposition. Seasonal decomposition plots are graphical representations of the decomposition of time series data into its various components: trend, seasonality, and residual (error). Seasonal decomposition is a technique used to break down a time series into these underlying components to better understand its patterns and behavior.

Seasonal decomposition plots are useful for several purposes:

• Trend Analysis:

  Understanding the long-term direction or behavior of the time series.

• Seasonal Patterns:

  Identifying repeating patterns or cycles within the data.

• Anomaly Detection:

  Spotting unusual behavior or outliers in the residuals.

• Modeling:

  Informing the choice of appropriate models for forecasting or analysis.

Parameters:

• input_relation (SQLRelation) – Input relation.

• columns (SQLColumns) – Input VastColumn to decompose.

• ts (str) – Time series VastColumn used to order the data. It can be of type date or a numerical VastColumn.

• by (SQLColumns, optional) – VastColumn used in the partition.

• period (int | tuple | list, optional) –

  Time series period. It is used to retrieve the seasonality component. If period <= 0, the seasonal component is estimated using ACF. In this case, polynomial_order must be greater than 0.

  It can be an int or a list | tuple of int, each one representing the period of the i-th column.

• polynomial_order (int | tuple | list, optional) –

  If greater than 0, the trend is estimated using a polynomial of degree 'polynomial_order' and the parameter two_sided is ignored. If equal to 0, the trend is estimated using Moving Averages.

  It can be an int or a list | tuple of int, each one representing the polynomial_order of the i-th column.

• estimate_seasonality (bool, optional) – If set to True, the seasonality is estimated using cosine and sine functions.

• rule (TimeInterval, optional) – Interval used to slice the time. For example, '5 minutes' creates records separated by '5 minutes' time interval.

• mult (bool, optional) – If set to True, the decomposition type is ‘multiplicative’. Otherwise, ‘additive’.

• two_sided (bool, optional) – If set to True, a centered moving average is used for the trend isolation. Otherwise, only past values are used.

• use_row (bool, optional) – If set to True, the ROW datatype is used to merge all the different columns time series components together.

• genSQL (bool, optional) – If set to True, the SQL code for creating the final relation is generated but not executed.

Returns:

object containing the different time series components.

Return type:

VastFrame

Examples

Let us use a dataset that has seasonality. The Airline passengers dataset is a good example.

import vastorbit.datasets as vod

data = vod.load_airline_passengers()

	📅 date Date	123 passengers Integer
1	1949-01-01	112
2	1949-02-01	118
3	1949-03-01	132
4	1949-04-01	129
5	1949-05-01	121
6	1949-06-01	135
7	1949-07-01	148
8	1949-08-01	148
9	1949-09-01	136
10	1949-10-01	119
11	1949-11-01	104
12	1949-12-01	118
13	1950-01-01	115
14	1950-02-01	126
15	1950-03-01	141
16	1950-04-01	135
17	1950-05-01	125
18	1950-06-01	149
19	1950-07-01	170
20	1950-08-01	170
21	1950-09-01	158
22	1950-10-01	133
23	1950-11-01	114
24	1950-12-01	140
25	1951-01-01	145
26	1951-02-01	150
27	1951-03-01	178
28	1951-04-01	163
29	1951-05-01	172
30	1951-06-01	178
31	1951-07-01	199
32	1951-08-01	199
33	1951-09-01	184
34	1951-10-01	162
35	1951-11-01	146
36	1951-12-01	166
37	1952-01-01	171
38	1952-02-01	180
39	1952-03-01	193
40	1952-04-01	181
41	1952-05-01	183
42	1952-06-01	218
43	1952-07-01	230
44	1952-08-01	242
45	1952-09-01	209
46	1952-10-01	191
47	1952-11-01	172
48	1952-12-01	194
49	1953-01-01	196
50	1953-02-01	196
51	1953-03-01	236
52	1953-04-01	235
53	1953-05-01	229
54	1953-06-01	243
55	1953-07-01	264
56	1953-08-01	272
57	1953-09-01	237
58	1953-10-01	211
59	1953-11-01	180
60	1953-12-01	201
61	1954-01-01	204
62	1954-02-01	188
63	1954-03-01	235
64	1954-04-01	227
65	1954-05-01	234
66	1954-06-01	264
67	1954-07-01	302
68	1954-08-01	293
69	1954-09-01	259
70	1954-10-01	229
71	1954-11-01	203
72	1954-12-01	229
73	1955-01-01	242
74	1955-02-01	233
75	1955-03-01	267
76	1955-04-01	269
77	1955-05-01	270
78	1955-06-01	315
79	1955-07-01	364
80	1955-08-01	347
81	1955-09-01	312
82	1955-10-01	274
83	1955-11-01	237
84	1955-12-01	278
85	1956-01-01	284
86	1956-02-01	277
87	1956-03-01	317
88	1956-04-01	313
89	1956-05-01	318
90	1956-06-01	374
91	1956-07-01	413
92	1956-08-01	405
93	1956-09-01	355
94	1956-10-01	306
95	1956-11-01	271
96	1956-12-01	306
97	1957-01-01	315
98	1957-02-01	301
99	1957-03-01	356
100	1957-04-01	348

Rows: 1-100 | Columns: 2

Note

vastorbit offers a wide range of sample datasets that are ideal for training and testing purposes. You can explore the full list of available datasets in the Datasets, which provides detailed information on each dataset and how to use them effectively. These datasets are invaluable resources for honing your data analysis and machine learning skills within the vastorbit environment.

Data Visualization

Let us first have a look how the data looks like:

data["passengers"].plot(ts = "date")

We can visually observe:

• Overall increasing trend

• A seasonal component

• Some noise

Now we can use the seasonal_decompose to separate these three.

Decomposition

We can directly the function on the dataset:

from vastorbit.machine_learning.model_selection.statistical_tests import seasonal_decompose

decomposition = seasonal_decompose(
    data,
    "passengers",
    "date",
    polynomial_order = 2,
    mult = True,
    use_row = False,
)

	📅 date Date	123 passengers Integer	123 passengers_trend Double	123 passengers_seasonal Double	123 passengers_epsilon Double
1	1949-01-01	112	114.02804085970713	0.8501353423254534	1.1553625566761538
2	1949-02-01	118	115.69006060661115	0.8821313237414521	1.1562525803339132
3	1949-03-01	132	117.36609675015096	0.9457101217738543	1.1892501982631951
4	1949-04-01	129	119.0561492903266	1.0238358488341364	1.0582969550056072
5	1949-05-01	121	120.76021822713801	1.0955747794484016	0.914575272399499
6	1949-06-01	135	122.47830356058525	1.1417045250926852	0.9654302083460592
7	1949-07-01	148	124.21040529066826	1.1498646576745484	1.0362320267396994
8	1949-08-01	148	125.95652341738709	1.11786867625855	1.0511150718469124
9	1949-09-01	136	127.71665794074173	1.0542898782261476	1.0100231447897343
10	1949-10-01	119	129.49080886073216	0.9761641511658654	0.9414237778004713
11	1949-11-01	104	131.2789761773584	0.9044252205516002	0.8759221197673622
12	1949-12-01	118	133.08115989062046	0.8582954749073165	1.0330672813834307
13	1950-01-01	115	134.8973600005183	0.8501353423254534	1.002781512544378
14	1950-02-01	126	136.72757650705194	0.882131323741452	1.0446749604243644
15	1950-03-01	141	138.57180941022136	0.945710121773854	1.0759353773303926
16	1950-04-01	135	140.4300587100266	1.0238358488341364	0.9389519303129862
17	1950-05-01	125	142.30232440646768	1.0955747794484016	0.8017814291442694
18	1950-06-01	149	144.18860649954453	1.1417045250926852	0.9051104965020854
19	1950-07-01	170	146.08890498925717	1.1498646576745484	1.0120103680448629
20	1950-08-01	170	148.00321987560562	1.1178686762585497	1.0275121610285165
21	1950-09-01	158	149.9315511585899	1.0542898782261476	0.999548831409234
22	1950-10-01	133	151.87389883820995	0.9761641511658655	0.8971098897380081
23	1950-11-01	114	153.8302629144658	0.9044252205516002	0.8193895191545819
24	1950-12-01	140	155.80064338735747	0.8582954749073165	1.0469404170822558
25	1951-01-01	145	157.78504025688494	0.8501353423254535	1.0809711567907094
26	1951-02-01	150	159.78345352304822	0.8821313237414521	1.0642072459337848
27	1951-03-01	178	161.7958831858473	0.9457101217738543	1.1633074196327902
28	1951-04-01	163	163.82232924528216	1.0238358488341364	0.9718162929619643
29	1951-05-01	172	165.86279170135285	1.0955747794484016	0.9465366835517949
30	1951-06-01	178	167.91727055405934	1.141704525092685	0.9284764947462371
31	1951-07-01	199	169.98576580340162	1.1498646576745484	1.0181078700924981
32	1951-08-01	199	172.0682774493797	1.11786867625855	1.034573805749251
33	1951-09-01	184	174.16480549199358	1.0542898782261474	1.0020684458681306
34	1951-10-01	162	176.27534993124326	0.9761641511658653	0.9414571857067755
35	1951-11-01	146	178.39991076712877	0.9044252205516001	0.9048686845208846
36	1951-12-01	166	180.53848799965004	0.8582954749073165	1.0712762190556668
37	1952-01-01	171	182.69108162880715	0.8501353423254535	1.1010085512464793
38	1952-02-01	180	184.85769165460005	0.882131323741452	1.1038288371831717
39	1952-03-01	193	187.03831807702875	0.9457101217738538	1.0911103697915443
40	1952-04-01	181	189.23296089609326	1.0238358488341364	0.9342249424608229
41	1952-05-01	183	191.44162011179355	1.0955747794484012	0.872514599777301
42	1952-06-01	218	193.66429572412966	1.1417045250926852	0.9859461838993289
43	1952-07-01	230	195.90098773310154	1.1498646576745482	1.0210440635384188
44	1952-08-01	242	198.1516961387093	1.11786867625855	1.0925134312332445
45	1952-09-01	209	200.4164209409528	1.0542898782261474	0.9891290269877696
46	1952-10-01	191	202.69516213983212	0.9761641511658659	0.9653107208137566
47	1952-11-01	172	204.98791973534722	0.9044252205516001	0.9277426328027764
48	1952-12-01	194	207.29469372749813	0.8582954749073165	1.09037709971173
49	1953-01-01	196	209.61548411628488	0.8501353423254534	1.0998783148475715
50	1953-02-01	196	211.9502909017074	0.8821313237414522	1.0483077840576724
51	1953-03-01	236	214.29911408376572	0.9457101217738538	1.164484172557511
52	1953-04-01	235	216.66195366245984	1.0238358488341364	1.0593875759208187
53	1953-05-01	229	219.0388096377898	1.0955747794484016	0.9542724495189369
54	1953-06-01	243	221.4296820097555	1.1417045250926852	0.9612065351495415
55	1953-07-01	264	223.83457077835706	1.1498646576745482	1.025722867870263
56	1953-08-01	272	226.25347594359437	1.11786867625855	1.0754317574787666
57	1953-09-01	237	228.6863975054675	1.054289878226148	0.9829874560971159
58	1953-10-01	211	231.1333354639765	0.9761641511658654	0.9351838843425918
59	1953-11-01	180	233.59428981912123	0.9044252205516002	0.8519961226601053
60	1953-12-01	201	236.06926057090175	0.8582954749073167	0.9920185537683209
61	1954-01-01	204	238.5582477193181	0.8501353423254534	1.005883443872492
62	1954-02-01	188	241.06125126437027	0.8821313237414519	0.8840914671548675
63	1954-03-01	235	243.57827120605822	0.9457101217738543	1.0201670241144885
64	1954-04-01	227	246.10930754438198	1.023835848834136	0.900881122791179
65	1954-05-01	234	248.65436027934152	1.0955747794484016	0.8589695174222833
66	1954-06-01	264	251.2134294109369	1.1417045250926854	0.9204651543018308
67	1954-07-01	302	253.78651493916806	1.1498646576745484	1.0348840067489244
68	1954-08-01	293	256.37361686403506	1.1178686762585497	1.0223591847996678
69	1954-09-01	259	258.9747351855378	1.054289878226148	0.9485982723701295
70	1954-10-01	229	261.58986990367634	0.9761641511658654	0.8967919598617543
71	1954-11-01	203	264.21902101845075	0.9044252205515999	0.8494920020889596
72	1954-12-01	229	266.86218852986093	0.8582954749073166	0.999796509368643
73	1955-01-01	242	269.5193724379069	0.8501353423254534	1.056178464429988
74	1955-02-01	233	272.19057274258864	0.8821313237414519	0.970397340910709
75	1955-03-01	267	274.8757894439062	0.9457101217738543	1.0271094723743175
76	1955-04-01	269	277.57502254185965	1.023835848834136	0.9465456506916755
77	1955-05-01	270	280.2882720364488	1.0955747794484016	0.8792589787688203
78	1955-06-01	315	283.0155379276738	1.141704525092685	0.9748696543086384
79	1955-07-01	364	285.7568202155346	1.1498646576745484	1.1077915634574516
80	1955-08-01	347	288.51211890003117	1.1178686762585497	1.0759067383181022
81	1955-09-01	312	291.28143398116356	1.054289878226148	1.0159720326262758
82	1955-10-01	274	294.0647654589318	0.9761641511658665	0.9545193073350206
83	1955-11-01	237	296.86211333333574	0.9044252205515999	0.8827158132086902
84	1955-12-01	278	299.6734776043756	0.8582954749073166	1.0808356610777947
85	1956-01-01	284	302.49885827205117	0.8501353423254535	1.1043494746774531
86	1956-02-01	277	305.3382553363626	0.8821313237414518	1.0284076664752944
87	1956-03-01	317	308.1916687973098	0.9457101217738533	1.087627877134211
88	1956-04-01	313	311.0590986548928	1.023835848834136	0.9828134615287868
89	1956-05-01	318	313.9405449091116	1.0955747794484014	0.9245655050780859
90	1956-06-01	374	316.8360075599662	1.1417045250926852	1.0339114566411551
91	1956-07-01	413	319.74548660745666	1.1498646576745484	1.1233081325473742
92	1956-08-01	405	322.6689820515829	1.1178686762585504	1.1228119270075365
93	1956-09-01	355	325.60649389234493	1.054289878226148	1.0341302880578642
94	1956-10-01	306	328.5580221297427	0.9761641511658654	0.9540837445663306
95	1956-11-01	271	331.52356676377633	0.9044252205515999	0.9038205679728549
96	1956-12-01	306	334.5031277944458	0.8582954749073166	1.0658213623850472
97	1957-01-01	315	337.496705221751	0.8501353423254533	1.0978751246298668
98	1957-02-01	301	340.50429904569205	0.8821313237414518	1.0020990544188302
99	1957-03-01	356	343.52590926626885	0.9457101217738543	1.0958029441106711
100	1957-04-01	348	346.5615358834815	1.0238358488341368	0.9807731147580853

Rows: 1-100 | Columns: 5

We can see that there are now three new columns capturing the three elements of data.

Let’s visualize them.

Seasonality

decomposition["passengers_seasonal"].plot(ts = "date")

Trend

decomposition["passengers_trend"].plot(ts = "date")

Noise

decomposition["passengers_epsilon"].plot(ts = "date")

Note

Thanks to seasonal decomposition, we can effortlessly extract the residual, predict its values, and obtain crucial information necessary for computing the time series. Subsequently, by leveraging all the individual components, we are able to effectively recompose the time series.