vastorbit.machine_learning.vast.tsa.ARIMA

class vastorbit.machine_learning.vast.tsa.ARIMA(name: str = None, overwrite_model: bool = False, **kwargs)

Creates a inDB ARIMA model.

Parameters:

• name (str, optional) – Name of the model. The model is stored in the database.

• overwrite_model (bool, optional) – If set to True, training a model with the same name as an existing model overwrites the existing model.

• order (tuple, optional) – The (p,d,q) order of the model for the autoregressive, differences, and moving average components.

• tol (float, optional) – Determines whether the algorithm has reached the specified accuracy result.

• max_iter (int, optional) – Determines the maximum number of iterations the algorithm performs before achieving the specified accuracy result.

• init (str, optional) –

  Initialization method, one of the following:

  • ’zero’:

    Coefficients are initialized to zero.

  • ’hr’:

    Coefficients are initialized using the Hannan-Rissanen algorithm.

• missing (str, optional) –

  Method for handling missing values, one of the following strings:

  • ’drop’:

    Missing values are ignored.

  • ’error’:

    Missing values raise an error.

  • ’zero’:

    Missing values are set to zero.

  • ’linear_interpolation’:

    Missing values are replaced by a linearly interpolated value based on the nearest valid entries before and after the missing value. In cases where the first or last values in a dataset are missing, the function errors.

Variables:

• created (Many attributes are)

• phase. (during the fitting)

• phi_ (numpy.array) – The coefficient of the AutoRegressive process. It represents the strength and direction of the relationship between a variable and its past values.

• theta_ (numpy.array) – The theta coefficient of the Moving Average process. It signifies the impact and contribution of the lagged error terms in determining the current value within the time series model.

• mean_ (float) – The mean of the time series values.

• feature_importances_ (numpy.array) – The importance of features is computed through the AutoRegressive part coefficients, which are normalized based on their range. Subsequently, an activation function calculates the final score. It is necessary to use the features_importance() method to compute it initially, and the computed values will be subsequently utilized for subsequent calls.

• mse_ (float) – The mean squared error (MSE) of the model, based on one-step forward forecasting, may not always be relevant. Utilizing a full forecasting approach is recommended to compute a more meaningful and comprehensive metric.

• n_ (int) – The number of rows used to fit the model.

• note:: (..) – All attributes can be accessed using the get_attributes() method.

Examples

The following examples provide a basic understanding of usage. For more detailed examples, please refer to the Machine Learning or the Examples section on the website.

Initialization

We import vastorbit:

import vastorbit as vo

Hint

By assigning an alias to vastorbit, we mitigate the risk of code collisions with other libraries. This precaution is necessary because vastorbit uses commonly known function names like “average” and “median”, which can potentially lead to naming conflicts. The use of an alias ensures that the functions from vastorbit are used as intended without interfering with functions from other libraries.

For this example, we will use the airline passengers dataset.

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.

We can plot the data to visually inspect it for the presence of any trends:

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

Though the increasing trend is obvious in our example, we can confirm it by the mkt() (Mann Kendall test) test:

from vastorbit.machine_learning.model_selection.statistical_tests import mkt

mkt(data, column = "passengers", ts = "date")

	value
Mann Kendall Test Statistic	14.381116595949713
S	8327.0
STDS	578.9536538730886
p_value	6.798871500366548e-47
Monotonic Trend	✓
Trend	increasing

Rows: 1-6 | Columns: 2

The above tests gives us some more insights into the data such as that the data is monotonic, and is increasing. Furthermore, the low p-value confirms the presence of a trend with respect to time. Now we are sure of the trend so we can apply the appropriate time-series model to fit it.

Model Initialization

First we import the ARIMA model:

from vastorbit.machine_learning.vast.tsa import ARIMA

Then we can create the model:

model = ARIMA(order = (12, 0, 0))

Important

The model name is crucial for the model management system and versioning. It’s highly recommended to provide a name if you plan to reuse the model later.

Model Fitting

We can now fit the model:

model.fit(data, "date", "passengers")

Important

To train a model, you can directly use the VastFrame or the name of the relation stored in the database. The test set is optional and is only used to compute the test metrics. In vastorbit, we don’t work using X matrices and y vectors. Instead, we work directly with lists of predictors and the response name.

Features Importance

We can conveniently get the features importance:

model.features_importance()

Important

Feature importance is determined by using the coefficients of the auto-regressive (AR) process and normalizing them. This method tends to be precise when your time series primarily consists of an auto-regressive component. However, its accuracy may be a topic of discussion if the time series contains other components as well._____

One important thing in time-series forecasting is that it has two types of forecasting:

• One-step ahead forecasting

• Full forecasting

Important

The default method is one-step ahead forecasting. To use full forecasting, use method = "forecast".

One-step ahead

In this type of forecasting, the algorithm utilizes the true value of the previous timestamp (t-1) to predict the immediate next timestamp (t). Subsequently, to forecast additional steps into the future (t+1), it relies on the actual value of the immediately preceding timestamp (t).

A notable drawback of this forecasting method is its tendency to exhibit exaggerated accuracy, particularly when predicting more than one step into the future.

Metrics

We can get the entire report using:

model.report()

	value
explained_variance	0.7968735700002738
max_error	28.235556067114082
median_absolute_error	7.782895
mean_absolute_error	9.246920621817747
mean_squared_error	168.3521776055204
root_mean_squared_error	12.975059830517948
r2	0.7092363081079095
r2_adj	0.6728908466213982
aic	58.11772366227439
bic	55.86575099111963

Rows: 1-10 | Columns: 2

You can also choose the number of predictions and where to start the forecast. For example, the following code will allow you to generate a report with 30 predictions, starting the forecasting process at index 40.

model.report(start = 40, npredictions = 30)

	value
explained_variance	0.7329944262123258
max_error	42.40391018451546
median_absolute_error	13.395048
mean_absolute_error	14.247677486941015
mean_squared_error	312.2669458874625
root_mean_squared_error	17.671076534480363
r2	0.7020808408187085
r2_adj	0.691440870847948
aic	177.05649327441657
bic	179.11814729700015

Rows: 1-10 | Columns: 2

Note

No matter what value you give for npredictons, in the report, the comparison will only be until the extent of the availability of true value. For exaxmple, even if we give n_predictions = 300, the report result will be the same as n_predictions = 104 starting from 40. This is because there are only 104 values beyond 40 in the dataset.

Important

Most metrics are computed using a single SQL query, but some of them might require multiple SQL queries. Selecting only the necessary metrics in the report can help optimize performance. E.g. model.report(metrics = ["mse", "r2"]).

You can utilize the score() function to calculate various regression metrics, with the explained variance being the default.

model.score()

The same applies to the score. You can choose where to start and the number of predictions to use.

model.score(start = 40, npredictions = 30)

Important

If you do not specify a starting point and the number of predictions, the forecast will begin at one-fourth of the dataset, which can result in an inaccurate score, especially for large datasets. It’s important to choose these parameters carefully.

Prediction

Prediction is straight-forward:

model.predict()

	123 prediction Decimal(38, 18)
1	122.34789051920173
2	119.97270878863017
3	130.40511857650353
4	135.03356898479817
5	137.523254048988
6	129.04989433328802
7	161.0599479833417
8	168.63663958343994
9	158.84924127220378
10	136.35686983685878

Rows: 1-10 | Column: prediction | Type: decimal(38, 18)

Hint

You can control the number of prediction steps by changing the npredictions parameter: model.predict(npredictions = 30).

Note

Predictions can be made automatically by using the training set, in which case you don’t need to specify the predictors. Alternatively, you can pass only the VastFrame to the predict() function, but in this case, it’s essential that the column names of the VastFrame match the predictors and response name in the model.

If you would like to have the ‘time-stamps’ (ts) in the output then you can switch the output_estimated_ts the parameter. And if you also would like to see the standard error then you can switch the output_standard_errors parameter:

model.predict(output_estimated_ts = True, output_standard_errors = True)

	123 prediction Decimal(38, 18)
1	122.34789051920173
2	119.97270878863017
3	130.40511857650353
4	135.03356898479817
5	137.523254048988
6	129.04989433328802
7	161.0599479833417
8	168.63663958343994
9	158.84924127220378
10	136.35686983685878

Rows: 1-10 | Column: prediction | Type: decimal(38, 18)

Important

The output_estimated_ts parameter provides an estimation of ‘ts’ assuming that ‘ts’ is regularly spaced.

If you don’t provide any input, the function will begin forecasting after the last known value. If you want to forecast starting from a specific value within the input dataset or another dataset, you can use the following syntax.

model.predict(
    data,
    "date",
    "passengers",
    start = 40,
    npredictions = 20,
    output_estimated_ts = True,
    output_standard_errors = True,
)

	123 prediction Decimal(38, 18)
1	179.3054162957827
2	189.7644439328859
3	227.41829985639995
4	223.7650566670624
5	223.45126830994622
6	180.1391715915681
7	185.3950484887631
8	166.43552143932914
9	200.44379321117344
10	191.3952577629153
11	193.59608981548453
12	220.6932515210783
13	238.82145713737486
14	225.9409935157178
15	253.68959883060876
16	259.2084026630325
17	251.96504984439684
18	208.4777226990456
19	200.68770927526185
20	179.57978119031512

Rows: 1-20 | Column: prediction | Type: decimal(38, 18)

Plots

We can conveniently plot the predictions on a line plot to observe the efficacy of our model:

model.plot(data, "date", "passengers", npredictions = 20, start = 140)

Note

You can control the number of prediction steps by changing the npredictions parameter: model.plot(npredictions = 30).

Please refer to Machine Learning - Time Series Plots for more examples.

Full forecasting

In this forecasting approach, the algorithm relies solely on a chosen true value for initiation. Subsequently, all predictions are established based on a series of previously predicted values.

This methodology aligns the accuracy of predictions more closely with reality. In practical forecasting scenarios, the goal is to predict all future steps, and this technique ensures a progressive sequence of predictions.

Metrics

We can get the report using:

model.report(start = 40, method = "forecast")

By selecting start = 40, we will measure the accuracy from 40th time-stamp and continue the assessment until the last available time-stamp.

	value
explained_variance	0.6731441121563337
max_error	42.45215308811038
median_absolute_error	23.365067
mean_absolute_error	21.45994039189248
mean_squared_error	597.6418180151178
root_mean_squared_error	24.44671384900469
r2	-0.42468668625025074
r2_adj	-0.6027725220315321
aic	70.78705893682901
bic	68.53508626567424

Rows: 1-10 | Columns: 2

Notice that the accuracy using method = forecast is poorer than the one-step ahead forecasting.

You can utilize the score() function to calculate various regression metrics, with the explained variance being the default.

model.score(start = 40, npredictions = 30, method = "forecast")

Prediction

Prediction is straight-forward:

model.predict(start = 50, npredictions = 40, method = "forecast")

	123 prediction Decimal(17, 14)
1	193.5960898154845
2	179.0679443090135
3	194.81945740698478
4	205.56402022135435
5	227.52161820942064
6	226.89943595636495
7	216.7023634979596
8	201.35766095439442
9	196.32241558307217
10	201.2486966063865
11	199.63782093326114
12	200.9144583687937
13	189.28441631125628
14	188.27398671872254
15	191.8786747715333
16	204.69931779689432
17	217.40774073106303
18	219.80899945781456
19	216.7577632381002
20	209.08231043629414
21	208.72140886687794
22	207.56842350436645
23	208.30530063303055
24	203.01759964248367
25	196.2372761050883
26	193.00926508422626
27	194.5971885428085
28	203.495205547232
29	210.48218612558918
30	215.10173795730086
31	214.18963417280375
32	213.39672348851468
33	213.35960978372268
34	213.98673612984902
35	213.26798710918212
36	208.4984202351696
37	203.34571079133818
38	198.93190471855524
39	199.68422182790826
40	203.39111510032632

Rows: 1-40 | Column: prediction | Type: decimal(17, 14)

If you want to forecast starting from a specific value within the input dataset or another dataset, you can use the following syntax.

model.predict(
    data,
    "date",
    "passengers",
    start = 40,
    npredictions = 20,
    output_estimated_ts = True,
    output_standard_errors = True,
    method = "forecast"
)

	123 prediction Decimal(17, 14)
1	179.3054162957827
2	186.13769863888962
3	197.09100625447027
4	199.54784691188962
5	189.6291499815959
6	172.80740811618108
7	167.63812810498695
8	169.59450368779417
9	172.63493396747546
10	182.01450412200944
11	181.85087247527034
12	180.4339054984652
13	181.67752933033785
14	188.14389492897527
15	196.85828658374413
16	198.92244286889195
17	193.0121194340164
18	184.25404329132496
19	179.52248803697313
20	177.1789259890237

Rows: 1-20 | Column: prediction | Type: decimal(17, 14)

Plots

We can conveniently plot the predictions on a line plot to observe the efficacy of our model:

model.plot(data, "date", "passengers", npredictions = 40, start = 120, method = "forecast")

__init__(name: str = None, overwrite_model: bool = False, **kwargs) → None

Methods

__init__([name, overwrite_model])
contour([nbins, chart])	Draws the model's contour plot.
deploySQL([ts, y, start, npredictions, ...])	Returns the SQL code needed to deploy the model.
drop()	Drops the model from the VAST DataBase.
export_models(name, path[, kind])	Exports machine learning models.
features_importance([idx, show, chart])	Computes the model's features importance.
fit(input_relation, ts, y[, test_relation, ...])	Trains the model using pure SQL.
get_attributes([attr_name])	Returns the model attributes.
get_match_index(x, col_list[, str_check])	Returns the matching index.
get_params()	Returns the parameters of the model.
get_plotting_lib([class_name, chart, ...])	Returns the first available library (Plotly, Matplotlib) to draw a specific graphic.
import_models(path[, schema, kind])	Imports machine learning models.
plot([vdf, ts, y, start, npredictions, ...])	Draws the model.
predict([vdf, ts, y, start, npredictions, ...])	Predicts using the input relation.
regression_report([metrics, start, ...])	Computes a regression report using multiple metrics to evaluate the model (r2, mse, max error...).
report([metrics, start, npredictions, method])	Computes a regression report using multiple metrics to evaluate the model (r2, mse, max error...).
score([metric, start, npredictions, method])	Computes the model score.
set_params([parameters])	Sets the parameters of the model.
summarize()	Summarizes the model.
to_binary(path)	Exports the model to the VAST Binary format.
to_python([return_proba, ...])	Returns the Python function needed for in-memory scoring without using built-in VAST functions.
to_sql([X, return_proba, ...])	Returns the SQL code needed to deploy the model without using built-in VAST functions.

Attributes

object_type