Main Content

CompactDirectForecaster

Compact direct forecasting model

Since R2023b

    Description

    CompactDirectForecaster is a compact version of a DirectForecaster model object for direct forecasting. The compact model does not include the time series data (X and Y) used for training the full model. Therefore, you cannot perform some tasks, such as a cross-validation, using the compact model.

    Creation

    Create a CompactDirectForecaster object from a full DirectForecaster model object by using compact.

    Properties

    expand all

    Data Properties

    This property is read-only.

    Indices of categorical exogenous predictors, specified as a positive integer vector. Each index value in CategoricalPredictors indicates that the corresponding exogenous predictor listed in PredictorNames is categorical. If none of the exogenous predictors are categorical, then this property is empty ([]).

    Data Types: double

    This property is read-only.

    Names of the exogenous predictors, specified as a cell array of character vectors. The order of the elements in PredictorNames corresponds to the order of the exogenous predictors in the data argument used to train the model.

    Data Types: cell

    This property is read-only.

    Name of the response variable, specified as a character vector.

    Data Types: char

    Forecasting Properties

    This property is read-only.

    Future time steps at which to forecast, specified as a positive integer vector. Learners contains a trained regression model for each horizon step. For example, if the Horizon value of a direct forecasting model Mdl is [1 3], then Mdl.Learners contains two regression models: one that forecasts at horizon step 1, and one that forecasts at horizon step 3.

    Data Types: double

    This property is read-only.

    Leading predictor lags used for preparing leading exogenous predictors, specified as a nonnegative integer vector or cell array of nonnegative integer vectors.

    • If LeadingPredictorLags is a vector, then for each element i in the vector, the software shifts the leading exogenous predictors backward in time by i steps, relative to the horizon time step. The software uses the resulting features as predictors. When the LeadingPredictorLags value is 0, the software uses the unshifted leading predictors.

      For example, if the Horizon value of a direct forecasting model is 3 and the LeadingPredictorLags value is 0, then the software uses the unshifted leading predictor values at horizon step 3 as predictor values.

    • If LeadingPredictorLags is a cell array, then the numeric values in element i of the cell array indicate the lags for leading exogenous predictor i.

    If no leading predictor lags are used, then this property is empty ([]).

    Data Types: double | cell

    This property is read-only.

    Indices of the leading exogenous predictors, specified as a positive integer vector. Leading predictors are predictors for which future values are known. Each index value in LeadingPredictors indicates that the corresponding exogenous predictor listed in PredictorNames is leading. If no exogenous predictors are leading predictors, then this property is empty ([]).

    Data Types: double

    This property is read-only.

    Compact regression models trained at different horizon steps, specified as a cell array of regression model objects. That is, for a direct forecasting model Mdl, the software trains the regression model Mdl.Learners{1} at horizon step Mdl.Horizon(1).

    This table lists the possible compact regression models.

    Regression Model TypeModel Object
    Bagged or boosted ensemble of treesCompactRegressionEnsemble
    General additive model (GAM)CompactRegressionGAM
    Gaussian process regression (GPR)CompactRegressionGP
    Kernel modelRegressionKernel
    Linear modelRegressionLinear
    Support vector machine (SVM)CompactRegressionSVM
    Decision treeCompactRegressionTree

    Data Types: cell

    This property is read-only.

    Maximum lag value, specified as a nonnegative integer scalar. The MaxLag value depends on the values in ResponseLags, PredictorLags, and LeadingPredictorLags. Specifically, the software computes the maximum lag as follows:

    MaxLag = max([0,ResponseLags,PredictorLags, ...
        LeadingPredictorLags - min(Horizon) + 1])
    Unlike response lags and nonleading predictor lags, leading predictor lags are relative to horizon time steps instead of the current time step.

    Data Types: double

    This property is read-only.

    Predictor lags used for preparing nonleading exogenous predictors, specified as a positive integer vector or cell array of positive integer vectors.

    • If PredictorLags is a vector, then for each element i in the vector, the software shifts the nonleading exogenous predictors backward in time by i steps and uses the resulting features as predictors.

    • If PredictorLags is a cell array, then the numeric values in element i of the cell array indicate the lags for nonleading exogenous predictor i.

    If no predictor lags are used, then this property is empty ([]).

    Data Types: double | cell

    This property is read-only.

    Response lags used for preparing predictors, specified as a positive integer vector. Each element in ResponseLags indicates the number of time steps by which to shift the response backward in time. The resulting feature is used as a predictor. If no response lags are used, then this property is empty ([]).

    Data Types: double

    Prepared Data Properties

    This property is read-only.

    Indices of the prepared categorical predictors, specified as a positive integer vector. Each index value in PreparedCategoricalPredictors indicates that the corresponding predictor listed in PreparedPredictorNames is categorical. If no prepared predictors are categorical predictors, then this property is empty ([]).

    Data Types: double

    This property is read-only.

    Names of the prepared predictors, specified as a cell array of character vectors. These prepared predictors include variables created from both the exogenous predictor variables and the response variable used to train the direct forecasting model. Not every predictor is used at every horizon step. To see which predictors are used at a specific horizon step, consult the PreparedPredictorsPerHorizon table.

    Data Types: cell

    This property is read-only.

    Prepared predictors at each horizon step, specified as a table of logical values. Each row of the table corresponds to a horizon step, and each column of the table corresponds to a prepared predictor as listed in PreparedPredictorNames.

    For a direct forecasting model Mdl, the logical value in row i and column j indicates whether the software uses prepared predictor Mdl.PreparedPredictorNames(j) at horizon step Mdl.Horizon(i). If the value is 1 (true), then the software uses the predictor. If the value is 0 (false), then the software does not use the predictor.

    Data Types: table

    This property is read-only.

    Names of the prepared responses at each horizon step, specified as a cell array of character vectors. That is, element i of PreparedResponseNames is the name of the response variable at the horizon step specified by element i of Horizon.

    For example, given a direct forecasting model Mdl, the name of the response variable at horizon step Mdl.Horizon(1), Mdl.PreparedResponseNames{1}, matches the response variable name used in the first regression model in Learners (Mdl.Learners{1}.ResponseName).

    Data Types: cell

    Object Functions

    lossLoss at each horizon step
    predictPredict response at time steps in observed test data
    forecastForecast response at time steps beyond available data
    preparedPredictorsObtain prepared data used for training or testing in direct forecasting

    Examples

    collapse all

    Reduce the size of a full direct forecasting model by removing the training data from the model. You can use a compact model to improve memory efficiency.

    Load the sample file TemperatureData.csv, which contains average daily temperatures from January 2015 through July 2016. Read the file into a table. Observe the first eight observations in the table.

    temperatures = readtable("TemperatureData.csv");
    head(temperatures)
        Year       Month       Day    TemperatureF
        ____    ___________    ___    ____________
    
        2015    {'January'}     1          23     
        2015    {'January'}     2          31     
        2015    {'January'}     3          25     
        2015    {'January'}     4          39     
        2015    {'January'}     5          29     
        2015    {'January'}     6          12     
        2015    {'January'}     7          10     
        2015    {'January'}     8           4     
    

    For this example, use a subset of the temperature data that omits the first 100 observations.

    Tbl = temperatures(101:end,:);

    Create a datetime variable t that contains the year, month, and day information for each observation in Tbl. Then, use t to convert Tbl into a timetable.

    numericMonth = month(datetime(Tbl.Month, ...
        InputFormat="MMMM",Locale="en_US"));
    t = datetime(Tbl.Year,numericMonth,Tbl.Day);
    Tbl.Time = t;
    Tbl = table2timetable(Tbl);

    Plot the temperature values in Tbl over time.

    plot(Tbl.Time,Tbl.TemperatureF)
    xlabel("Date")
    ylabel("Temperature in Fahrenheit")

    Figure contains an axes object. The axes object with xlabel Date, ylabel Temperature in Fahrenheit contains an object of type line.

    Create a full direct forecasting model by using the data in Tbl. Train the model using a decision tree learner. All three of the predictors (Year, Month, and Day) are leading predictors because their future values are known. To create new predictors by shifting the leading predictor and response variables backward in time, specify the leading predictor lags and the response variable lags.

    Mdl = directforecaster(Tbl,"TemperatureF", ...
        Learner="tree", ...
        LeadingPredictors="all",LeadingPredictorLags={0:1,0:1,0:7}, ...
        ResponseLags=1:7)
    Mdl = 
      DirectForecaster
    
                      Horizon: 1
                 ResponseLags: [1 2 3 4 5 6 7]
            LeadingPredictors: [1 2 3]
         LeadingPredictorLags: {[0 1]  [0 1]  [0 1 2 3 4 5 6 7]}
                 ResponseName: 'TemperatureF'
               PredictorNames: {'Year'  'Month'  'Day'}
        CategoricalPredictors: 2
                     Learners: {[1x1 classreg.learning.regr.CompactRegressionTree]}
                       MaxLag: 7
              NumObservations: 465
    
    
    

    Mdl is a DirectForecaster object. By default, the horizon is one step ahead. That is, Mdl predicts a value that is one step into the future.

    Reduce the size of the model by using the compact object function.

    compactMdl = compact(Mdl)
    compactMdl = 
      CompactDirectForecaster
    
                      Horizon: 1
                 ResponseLags: [1 2 3 4 5 6 7]
            LeadingPredictors: [1 2 3]
         LeadingPredictorLags: {[0 1]  [0 1]  [0 1 2 3 4 5 6 7]}
                 ResponseName: 'TemperatureF'
               PredictorNames: {'Year'  'Month'  'Day'}
        CategoricalPredictors: 2
                     Learners: {[1x1 classreg.learning.regr.CompactRegressionTree]}
                       MaxLag: 7
    
    
    

    compactMdl is a CompactDirectForecaster model object. compactMdl contains fewer properties than the full model Mdl.

    Display the amount of memory used by each direct forecasting model.

    whos("Mdl","compactMdl")
      Name            Size             Bytes  Class                                            Attributes
    
      Mdl             1x1             119523  timeseries.forecaster.DirectForecaster                     
      compactMdl      1x1              43983  timeseries.forecaster.CompactDirectForecaster              
    

    The full model is larger than the compact model.

    More About

    expand all

    Version History

    Introduced in R2023b