vastorbit.machine_learning.vast.tsa.AR

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

Creates a inDB Autoregressor model.

Important

The vastorbit AR model also implements the VAR method; use AR to build a vector autoregressor.

Note

The AR model is much faster than ARIMA(p, 0, 0) because the underlying algorithm of AR is quite different.

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.

• p (int, optional) – Integer in the range [1, 1999], the number of lags to consider in the computation. Larger values for p weaken the correlation.

• method (str, optional) –

  One of the following algorithms for training the model:

  • ols:

    Ordinary Least Squares

  • yule-walker:

    Yule-Walker

• penalty (str, optional) –

  Method of regularization.

  • none:

    No regularization.

  • l2:

    L2 regularization.

• C (PythonNumber, optional) – The regularization parameter value. The value must be zero or non-negative.

• 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.

• subtract_mean (bool, optional) – For Yule Walker, if subtract_mean is True, then the mean of the column will be subtracted before calculating the coefficients. If False (default), then the calculations will be performed directly on the data, this often gives a more accurate model. Note that the means saved in the model will be saved as all 0s if this parameter is set to False. This parameter has no effect for OLS.

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.

• intercept_ (float) – Represents the expected value of the time series when the lagged values are zero. It signifies the baseline or constant term in the model, capturing the average level of the series in the absence of any historical influence.

• 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 generate a dummy time-series dataset.

data = vo.VastFrame(
    {
        "month": [i for i in range(1, 41)],
        "GB": [5, 10, 20, 35, 55, 80, 110, 145, 185, 230,
                280, 330, 380, 430, 480, 530, 580, 630, 680, 730,
                780, 830, 880, 930, 980, 1030, 1080, 1130, 1180, 1230,
                1280, 1330, 1380, 1430, 1480, 1530, 1580, 1630, 1680, 1730],
    }
)

	123 month Integer	123 GB Integer
1	10	230
2	13	380
3	14	430
4	36	1530
5	40	1730
6	29	1180
7	39	1680
8	38	1630
9	37	1580
10	26	1030
11	35	1480
12	24	930
13	25	980
14	34	1430
15	33	1380
16	32	1330
17	31	1280
18	21	780
19	19	680
20	28	1130
21	30	1230
22	16	530
23	27	1080
24	23	880
25	22	830
26	15	480
27	17	580
28	20	730
29	18	630
30	12	330
31	11	280
32	8	145
33	4	35
34	9	185
35	7	110
36	6	80
37	1	5
38	2	10
39	5	55
40	3	20

Rows: 1-40 | 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["GB"].plot(ts = "month")

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 = "GB", ts = "month")

	value
Mann Kendall Test Statistic	9.076155922790461
S	780.0
STDS	85.82928793057764
p_value	1.124771839592972e-19
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 AR model:

from vastorbit.machine_learning.vast.tsa import AR

Then we can create the model:

model = AR(p = 2)

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, "month", "GB")

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()

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(start = 4)

	value
explained_variance	0.999846817422568
max_error	3.333234528631013
median_absolute_error	1.0219673
mean_absolute_error	1.3841424583291402
mean_squared_error	2.834152346382321
root_mean_squared_error	1.6834940886092595
r2	0.9998125715568236
r2_adj	0.9997891430014265
aic	17.274571822007175
bic	15.022599150852411

Rows: 1-10 | Columns: 2

Important

The value for start cannot be less than the p value selected for the AR model.

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 = 4, npredictions = 10)

	value
explained_variance	0.999846817422568
max_error	3.333234528631013
median_absolute_error	1.0219673
mean_absolute_error	1.3841424583291402
mean_squared_error	2.834152346382321
root_mean_squared_error	1.6834940886092595
r2	0.9998125715568236
r2_adj	0.9997891430014265
aic	17.274571822007175
bic	15.022599150852411

Rows: 1-10 | Columns: 2

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(start = 3, 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(30, 16)
1	21.628350583785544
2	36.027285785000764
3	55.42075431756819
4	79.80875618148781
5	109.19129137675964
6	143.56835990338368
7	182.9399617613599
8	227.30609695068836
9	276.666765471369
10	331.02196732340184

Rows: 1-10 | Column: prediction | Type: decimal(30, 16)

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.

model.predict(output_estimated_ts = True)

	123 prediction Decimal(30, 16)
1	21.628350583785544
2	36.027285785000764
3	55.42075431756819
4	79.80875618148781
5	109.19129137675964
6	143.56835990338368
7	182.9399617613599
8	227.30609695068836
9	276.666765471369
10	331.02196732340184

Rows: 1-10 | Column: prediction | Type: decimal(30, 16)

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,
    "month",
    "GB",
    start = 7,
    npredictions = 10,
    output_estimated_ts = True,
)

	123 prediction Decimal(30, 16)
1	143.56835990338368
2	182.9399617613599
3	227.30609695068836
4	276.666765471369
5	331.02196732340184
6	380.9673006369239
7	430.91263395044587
8	480.8579672639679
9	530.80330057749
10	580.748633891012

Rows: 1-10 | Column: prediction | Type: decimal(30, 16)

Plots

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

model.plot(data, "month", "GB", npredictions = 10, start=7)

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 = 4, method = "forecast")

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

	value
explained_variance	0.9879358208743386
max_error	35.34437450736874
median_absolute_error	11.946518
mean_absolute_error	13.61685568591683
mean_squared_error	362.32534282479725
root_mean_squared_error	19.03484548991132
r2	0.9760386646061141
r2_adj	0.9730434976818784
aic	65.78256831002774
bic	63.530595638872974

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 = 4, npredictions = 6, method = "forecast")

Prediction

Prediction is straight-forward:

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

	123 prediction Decimal(17, 13)
1	1779.4366334155407
2	1828.3223415770012
3	1876.668699755828
4	1924.4865067266235
5	1971.7858646075263
6	2018.5762500390047
7	2064.866577645534
8	2110.6652566216035
9	2155.9802411916853
10	2200.819075612039

Rows: 1-10 | Column: prediction | Type: decimal(17, 13)

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,
    "month",
    "GB",
    start = 4,
    npredictions = 20,
    output_estimated_ts = True,
    output_standard_errors = True,
    method = "forecast",
)

	123 prediction Decimal(17, 14)
1	55.42075431756818
2	80.60014471966605
3	109.94899755602552
4	142.9431185439257
5	179.11619661365557
6	218.05348200111723
7	259.3861541180047
8	302.78630394546616
9	347.9624639072398
10	394.65562549263126
11	442.63569141609406
12	491.69831490564303
13	541.6620838844323
14	592.3660124176654
15	643.6673059021359
16	695.4393701329641
17	747.5700376403626
18	799.9599875920616
19	852.5213381431304
20	905.176392418899

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, "month", "GB", npredictions = 10, start = 5, 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