This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

Replacing Discouraged Syntaxes of estimate

In a future release, the estimate function of the Bayesian linear regression models conjugateblm, semiconjugateblm, diffuseblm, empiricalblm, and customblm will return only an estimated model and an estimation summary table. Specifically, the syntax returning all output arguments will change as indicated in the following code.

[PosteriorMdl,estBeta,EstBetaCov,estSigma2,estSigma2Var,Summary] = estimate(...); % Current and past releases 
[PosteriorMdl,Summary] = estimate(...);                                           % Future release

Starting in release R2018b, if estimate returns more than an estimated model (the output argument in the first position), then it issues this warning:

Warning: Current syntax supports 6 output arguments, and will be removed in a future release. For supported output
arguments, see estimate.

You do not need to change your code at this time. However, to prepare your code for this software change and avoid the warning, you can follow this procedure:

  1. Search your code for instances in which estimate returns any output other than PosteriorMdl.

  2. In the identified instances, determine whether estimate returns marginal or conditional distribution estimates. If the call to estimate uses the 'Beta' or 'Sigma2' name-value pair argument, then it returns conditional distribution estimates. Otherwise, estimate returns marginal distribution estimates.

  3. For instances returning marginal distribution estimates:

    1. Return only PosteriorMdl when you call estimate.

    2. Estimate the marginal posterior statistics using the appropriate code in this table.

      Output Argumentconjugateblm or diffuseblmsemiconjugateblm, empiricalblm, or customblm
      estBeta

      estBeta = PosteriorMdl.Mu;

      estBeta = mean(PosteriorMdl.BetaDraws,2);

      EstBetaCov

      smry = summarize(PosteriorMdl);
      EstBetaCov = smry.Covariances{1:end - 1,1:end - 1};
      or
      EstBetaCov = PosteriorMdl.V/PosteriorMdl.B/(PosteriorMdl.A - 1);

      EstBetaCov = cov(PosteriorMdl.BetaDraws');

      estSigma2

      smry = summarize(PosteriorMdl);
      estSigma2 = smry.MarginalDistributions.Mean(end);
      or
      estSigma2 = 1/PosteriorMdl.B/(PosteriorMdl.A - 1);

      estSigma2 = mean(PosteriorMdl.Sigma2Draws);

      estSigma2Var

      smry = summarize(PosteriorMdl);
      estSigma2Var = smry.Covariances{end,end};
      or
      estSigma2Var = 1/(PosteriorMdl.B^2*(PosteriorMdl.A - 1)^2*(PosteriorMdl.A - 2));

      estSigma2Var = var(PosteriorMdl.Sigma2Draws);

      Summary

      smry = summarize(PosteriorMdl);
      Summary = smry.MarginalDistributions;
      Summary.Covariances = smry.Covariances.Variables

      smry = summarize(PosteriorMdl);
      Summary = smry.MarginalDistributions;
      Summary.Covariances = smry.Covariances.Variables

      For examples, see Replace Discouraged Syntax When Estimating Analytical Marginal Posterior and Replace Discouraged Syntax When Estimating Numerical Marginal Posterior.

  4. For instances returning conditional distribution estimates, there is no simple replacement. You can ignore the warning and you do not need to take any actions now. However, it is best practice to prepare for the change.

    Prepare by updating your code to replace all instances in which estimate returns estBeta, EstBetaCov, estSigma2, and estSigma2Var with code that extracts the estimates from the estimation summary table (which is currently in the sixth output position).

    This table describes how to extract conditional posterior estimates from the estimation summary table Summary returned by estimate.

    Output ArgumentEstimation
    estBeta

    estBeta = Summary.Mean(1:end - 1);

    EstBetaCov

    EstBetaCov = Summary.Covariances{1:end - 1,1:end - 1}

    estSigma2

    estSigma2 = Summary.Mean(end)

    estSigma2Var

    estSigma2Var = Summary.Covariances{end,end}

    In the future release when the syntax change occurs, estimate will store conditional posterior estimates in the estimation summary table returned in the second output position. If you prepared your code, then, when the syntax change occurs, replace all instances of

    [PosteriorMdl,~,~,~,~,Summary] = estimate(...);

    with

    [PosteriorMdl,Summary] = estimate(...);

    If you did not prepare your code, then, when the syntax change occurs, you must update your code as described in the previous table.

    For an example, see Replace Discouraged Syntax When Estimating Conditional Posterior.

Replace Discouraged Syntax When Estimating Analytical Marginal Posterior

This example shows how to replace the discouraged syntax of estimate when it returns an analytical marginal distribution. Although this example uses a conjugateblm prior model, you can use the same code for diffuse prior models.

Consider a multiple linear regression model that predicts US real gross national product (GNPR) using a linear combination of industrial production index (IPI), total employment (E), and real wages (WR). Assume that:

  • The intercept and three regression coefficients are random variables with a multivariate normal prior distribution conditional on the disturbance variance. The prior mean is a 4-D vector of zeros, and the prior covariance matrix is the 4-by-4 identity matrix scaled by 10,000.

  • The disturbance variance is a random variable with an inverse gamma prior distribution. The shape and scale parameter values are 3 and 1, respectively.

Create a normal-inverse-gamma conjugate prior model for the linear regression parameters. Set the number of predictors p. Set the regression coefficient names to the corresponding variable names.

p = 3;
PriorMdl = bayeslm(p,'ModelType','conjugate',...
    'VarNames',["IPI" "E" "WR"]);

Load the Nelson-Plosser data set. Create variables for the response and predictor series.

load Data_NelsonPlosser
X = DataTable{:,PriorMdl.VarNames(2:end)};
y = DataTable{:,'GNPR'};

Estimate the marginal posterior distribution. Return all posterior distribution estimates by using the discouraged syntax. Turn off the estimation display.

[PosteriorMdl,estBeta,estBetaCov,estSigma2,estSigma2Var] = ...
    estimate(PriorMdl,X,y,'Display',false)
Warning: Current syntax supports 6 output arguments, and will be removed in a future release. For supported
output arguments, see estimate. 
> In conjugateblm/estimate (line 205) 

PosteriorMdl = 

  conjugateblm with properties:

    NumPredictors: 3
        Intercept: 1
         VarNames: {4×1 cell}
               Mu: [4×1 double]
                V: [4×4 double]
                A: 34
                B: 6.8660e-04

 
           |   Mean      Std          CI95        Positive       Distribution      
-----------------------------------------------------------------------------------
 Intercept | -24.2494  8.7821  [-41.514, -6.985]    0.003   t (-24.25, 8.65^2, 68) 
 IPI       |   4.3913  0.1414   [ 4.113,  4.669]    1.000   t (4.39, 0.14^2, 68)   
 E         |   0.0011  0.0003   [ 0.000,  0.002]    1.000   t (0.00, 0.00^2, 68)   
 WR        |   2.4683  0.3490   [ 1.782,  3.154]    1.000   t (2.47, 0.34^2, 68)   
 Sigma2    |  44.1347  7.8020   [31.427, 61.855]    1.000   IG(34.00, 0.00069)     
 

estBeta =

  -24.2494
    4.3913
    0.0011
    2.4683


estBetaCov =

   77.1246    0.7713   -0.0024    0.5311
    0.7713    0.0200   -0.0000   -0.0295
   -0.0024   -0.0000    0.0000   -0.0001
    0.5311   -0.0295   -0.0001    0.1218


estSigma2 =

   44.1347


estSigma2Var =

   60.8709

The warning indicates that the syntax returning more than just the posterior model will change in the future.

Compute posterior estimates by using the encouraged procedure.

estBeta = PosteriorMdl.Mu                          % Posterior mean of coefficients

smry = summarize(PosteriorMdl);
EstBetaCov = smry.Covariances{1:end - 1,1:end - 1} % Posterior covariance of coefficients

estSigma2 = smry.MarginalDistributions.Mean(end)   % Posterior mean of disturbance variance

estSigma2Var = smry.Covariances{end,end}           % Posterior variance of disturbance variance
estBeta =

  -24.2494
    4.3913
    0.0011
    2.4683


EstBetaCov =

   77.1246    0.7713   -0.0024    0.5311
    0.7713    0.0200   -0.0000   -0.0295
   -0.0024   -0.0000    0.0000   -0.0001
    0.5311   -0.0295   -0.0001    0.1218


estSigma2 =

   44.1347


estSigma2Var =

   60.8709

The estimates resulting from implementing both the discouraged syntax and the encouraged procedure are equivalent.

Replace Discouraged Syntax When Estimating Numerical Marginal Posterior

This example shows how to replace the discouraged syntax of estimate when it returns a numerical marginal distribution. Although this example uses a semiconjugateblm model, you can use the same code for empirical and custom prior models.

Consider a multiple linear regression model that predicts US real gross national product (GNPR) using a linear combination of industrial production index (IPI), total employment (E), and real wages (WR). Assume that:

  • The intercept and three regression coefficients are random variables with a multivariate normal prior distribution. The prior mean is a 4-D vector of zeros, and the prior covariance matrix is the 4-by-4 identity matrix scaled by 10,000.

  • The disturbance variance is a random variable with an inverse gamma prior distribution. The shape and scale parameter values are 3 and 1, respectively.

  • The four regression coefficients and the disturbance variance are independent.

Create a normal-inverse-gamma semiconjugate prior model for the linear regression parameters. Specify the number of predictors p. Set the regression coefficient names to the corresponding variable names.

p = 3;
PriorMdl = bayeslm(p,'ModelType','semiconjugate',...
    'VarNames',["IPI" "E" "WR"]);

Load the Nelson-Plosser data set. Create variables for the response and predictor series.

load Data_NelsonPlosser
X = DataTable{:,PriorMdl.VarNames(2:end)};
y = DataTable{:,'GNPR'};

Estimate the marginal posterior distribution. Return all posterior distribution estimates by using the discouraged syntax. Turn off the estimation display.

rng(1); % For reproducibility
[PosteriorMdl,estBeta,estBetaCov,estSigma2,estSigma2Var] = ...
    estimate(PriorMdl,X,y,'Display',false)
Warning: Current syntax supports 6 output arguments, and will be removed in a future release. For supported
output arguments, see estimate. 
> In semiconjugateblm/estimate (line 246) 

PosteriorMdl = 

  empiricalblm with properties:

    NumPredictors: 3
        Intercept: 1
         VarNames: {4×1 cell}
        BetaDraws: [4×10000 double]
      Sigma2Draws: [1×10000 double]

 
           |   Mean      Std          CI95        Positive  Distribution 
-------------------------------------------------------------------------
 Intercept | -23.9922  9.0520  [-41.734, -6.198]    0.005     Empirical  
 IPI       |   4.3929  0.1458   [ 4.101,  4.678]    1.000     Empirical  
 E         |   0.0011  0.0003   [ 0.000,  0.002]    0.999     Empirical  
 WR        |   2.4711  0.3576   [ 1.762,  3.178]    1.000     Empirical  
 Sigma2    |  46.7474  8.4550   [33.099, 66.126]    1.000     Empirical  
 

estBeta =

  -23.9922
    4.3929
    0.0011
    2.4711


estBetaCov =

   81.9379    0.8162   -0.0025    0.5893
    0.8162    0.0213   -0.0000   -0.0309
   -0.0025   -0.0000    0.0000   -0.0001
    0.5893   -0.0309   -0.0001    0.1279


estSigma2 =

   46.7474


estSigma2Var =

   71.4868

The warning indicates that the syntax returning more than just the posterior model will change in the future.

Compute posterior estimates by using the encouraged procedure.

estBeta = mean(PosteriorMdl.BetaDraws,2)     % Posterior mean of coefficients

EstBetaCov = cov(PosteriorMdl.BetaDraws')    % Posterior covariance of coefficients

estSigma2 = mean(PosteriorMdl.Sigma2Draws)   % Posterior mean of disturbance variance

estSigma2Var = var(PosteriorMdl.Sigma2Draws) % Posterior variance of disturbance variance
estBeta =

  -23.9922
    4.3929
    0.0011
    2.4711


EstBetaCov =

   81.9379    0.8162   -0.0025    0.5893
    0.8162    0.0213   -0.0000   -0.0309
   -0.0025   -0.0000    0.0000   -0.0001
    0.5893   -0.0309   -0.0001    0.1279


estSigma2 =

   46.7474


estSigma2Var =

   71.4868

The estimates resulting from implementing both the discouraged syntax and the encouraged procedure are equivalent.

Replace Discouraged Syntax When Estimating Conditional Posterior

This example shows how to prepare your code for the removal of the discouraged-syntax estimate when you estimate a conditional posterior distribution. Although this example uses a normal-inverse-gamma conjugate Bayesian linear regression model, you can use the same code for semiconjugate, diffuse, empirical, and custom prior models.

Consider a multiple linear regression model that predicts US real gross national product (GNPR) using a linear combination of industrial production index (IPI), total employment (E), and real wages (WR). Assume that:

  • The intercept and three regression coefficients are random variables with a multivariate normal prior distribution conditional on the disturbance variance. The prior mean is a 4-D vector of zeros, and the prior covariance matrix is the 4-by-4 identity matrix scaled by 10,000.

  • The disturbance variance is a random variable with an inverse gamma prior distribution. The shape and scale parameter values are 3 and 1, respectively.

Create a normal-inverse-gamma conjugate prior model for the linear regression parameters. Specify the number of predictors p. Set the regression coefficient names to the corresponding variable names.

p = 3;
PriorMdl = bayeslm(p,'ModelType','conjugate',...
    'VarNames',["IPI" "E" "WR"]);

Load the Nelson-Plosser data set. Create variables for the response and predictor series.

load Data_NelsonPlosser
X = DataTable{:,PriorMdl.VarNames(2:end)};
y = DataTable{:,'GNPR'};

Estimate the conditional posterior distribution of the regression coefficients given that the disturbance variance is 10. Return all conditional posterior distribution estimates of the regression coefficients and the estimation summary table by using the discouraged syntax. Turn off the estimation display.

[~,estBeta,estBetaCov,~,~,Summary] = ...
    estimate(PriorMdl,X,y,'Sigma2',10,'Display',false)
Warning: Current syntax supports 6 output arguments, and will be removed in a future release. For supported
output arguments, see estimate. 
> In conjugateblm/estimate (line 205) 

estBeta =

  -24.2494
    4.3913
    0.0011
    2.4683


estBetaCov =

   17.4748    0.1748   -0.0005    0.1203
    0.1748    0.0045   -0.0000   -0.0067
   -0.0005   -0.0000    0.0000   -0.0000
    0.1203   -0.0067   -0.0000    0.0276


Summary =

  5×6 table

                   Mean          Std                CI95              Positive         Distribution                                      Covariances                              
                 _________    __________    _____________________    __________    ____________________    _______________________________________________________________________

    Intercept      -24.249        4.1803     -32.443      -16.056    3.2982e-09    'N (-24.25, 4.18^2)'         17.475        0.17477    -0.00053597        0.12034              0
    IPI             4.3913      0.067307      4.2594       4.5233             1    'N (4.39, 0.07^2)'          0.17477      0.0045303    -1.4728e-06     -0.0066796              0
    E            0.0011202    0.00015675    0.000813    0.0014274             1    'N (0.00, 0.00^2)'      -0.00053597    -1.4728e-06     2.4571e-08    -1.8129e-05              0
    WR              2.4683        0.1661      2.1427       2.7938             1    'N (2.47, 0.17^2)'          0.12034     -0.0066796    -1.8129e-05        0.02759              0
    Sigma2              10             0          10           10             1    'Fixed value'                     0              0              0              0              0

The warning indicates that the syntax returning more than just the posterior model will change in the future.

Compute posterior estimates by using the encouraged procedure.

estBeta = Summary.Mean(1:end - 1)                     % Posterior mean of coefficients

EstBetaCov = Summary.Covariances(1:end - 1,1:end - 1) % Posterior covariance of coefficients
estBeta =

  -24.2494
    4.3913
    0.0011
    2.4683


EstBetaCov =

   17.4748    0.1748   -0.0005    0.1203
    0.1748    0.0045   -0.0000   -0.0067
   -0.0005   -0.0000    0.0000   -0.0000
    0.1203   -0.0067   -0.0000    0.0276

The estimates resulting from implementing both the discouraged syntax and the encouraged procedure are equivalent.

See Also

Objects

Functions