mvnrmle

Multivariate normal regression (ignore missing data)

Syntax

[Parameters,Covariance,Resid,Info] = mvnrmle(Data,Design,MaxIterations,TolParam,TolObj,Covar0,CovarFormat)

Arguments

`Data`	`NUMSAMPLES`-by-`NUMSERIES` matrix with `NUMSAMPLES` samples of a `NUMSERIES`-dimensional random vector. If a data sample has missing values, represented as `NaN`s, the sample is ignored. (Use `mvnrmle` to handle missing data.)
`Design`	Matrix or a cell array that handles two model structures: If `NUMSERIES = 1`, `Design` is a `NUMSAMPLES`-by-`NUMPARAMS` matrix with known values. This structure is the standard form for regression on a single series. If `NUMSERIES` ≥ `1`, `Design` is a cell array. The cell array contains either one or `NUMSAMPLES` cells. Each cell contains a `NUMSERIES`-by-`NUMPARAMS` matrix of known values. If `Design` has a single cell, it is assumed to have the same `Design` matrix for each sample. If `Design` has more than one cell, each cell contains a `Design` matrix for each sample.
`MaxIterations`	(Optional) Maximum number of iterations for the estimation algorithm. Default value is `100`.
`TolParam`	(Optional) Convergence tolerance for estimation algorithm based on changes in model parameter estimates. Default value is `sqrt(eps)` which is about 1.0e-8 for double precision. The convergence test for changes in model parameters is
	$‖ P a r a m_{k} - P a r a m_{k - 1} ‖ < T o l P a r a m \times (1 + ‖ P a r a m_{k} ‖)$
	where `Param` represents the output `Parameters`, and iteration k = 2, 3, ... . Convergence is assumed when both the `TolParam` and `TolObj` conditions are satisfied. If both `TolParam` ≤ `0` and `TolObj` ≤ `0`, do the maximum number of iterations (`MaxIterations`), whatever the results of the convergence tests.
`TolObj`	(Optional) Convergence tolerance for estimation algorithm based on changes in the objective function. Default value is eps ∧ 3/4 which is about 1.0e-12 for double precision. The convergence test for changes in the objective function is $\| O b j_{k} - O b j_{k - 1} \| < T o l O b j \times (1 + \| O b j_{k} \|)$ for iteration k = 2, 3, ... . Convergence is assumed when both the `TolParam` and `TolObj` conditions are satisfied. If both `TolParam` ≤ `0` and `TolObj` ≤ `0`, do the maximum number of iterations (`MaxIterations`), whatever the results of the convergence tests.
`Covar0`	(Optional) `NUMSERIES`-by-`NUMSERIES` matrix that contains a user-supplied initial or known estimate for the covariance matrix of the regression residuals.
`CovarFormat`	(Optional) Character vector that specifies the format for the covariance matrix. The choices are: `'full'` — Default method. Compute the full covariance matrix. `'diagonal'` — Force the covariance matrix to be a diagonal matrix.

Description

[Parameters,Covariance,Resid,Info] = mvnrmle(Data,Design,MaxIterations,TolParam,TolObj,Covar0,CovarFormat) estimates a multivariate normal regression model without missing data. The model has the form

$D a t a_{k} \sim N (D e s i g n_{k} \times P a r a m e t e r s, C o v a r i a n c e)$

for samples k = 1, ... , NUMSAMPLES.

mvnrmle estimates a NUMPARAMS-by-1 column vector of model parameters called Parameters, and a NUMSERIES-by-NUMSERIES matrix of covariance parameters called Covariance.

mvnrmle(Data, Design) with no output arguments plots the log-likelihood function for each iteration of the algorithm.

To summarize the outputs of mvnrmle:

Parameters is a NUMPARAMS-by-1 column vector of estimates for the parameters of the regression model.
Covariance is a NUMSERIES-by-NUMSERIES matrix of estimates for the covariance of the regression model's residuals.
Resid is a NUMSAMPLES-by-NUMSERIES matrix of residuals from the regression. For any row with missing values in Data, the corresponding row of residuals is represented as all NaN missing values, since this routine ignores rows with NaN values.

Another output, Info, is a structure that contains additional information from the regression. The structure has these fields:

Info.Obj – A variable-extent column vector, with no more than MaxIterations elements, that contain each value of the objective function at each iteration of the estimation algorithm. The last value in this vector, Obj(end), is the terminal estimate of the objective function. If you do maximum likelihood estimation, the objective function is the log-likelihood function.
Info.PrevParameters – NUMPARAMS-by-1 column vector of estimates for the model parameters from the iteration just before the terminal iteration.
Info.PrevCovariance – NUMSERIES-by-NUMSERIES matrix of estimates for the covariance parameters from the iteration just before the terminal iteration.

Notes

mvnrmle does not accept an initial parameter vector, because the parameters are estimated directly from the first iteration onward.

You can configure Design as a matrix if NUMSERIES = 1 or as a cell array if NUMSERIES ≥ 1.

If Design is a cell array and NUMSERIES = 1, each cell contains a NUMPARAMS row vector.
If Design is a cell array and NUMSERIES > 1, each cell contains a NUMSERIES-by-NUMPARAMS matrix.

These points concern how Design handles missing data:

Although Design should not have NaN values, ignored samples due to NaN values in Data are also ignored in the corresponding Design array.
If Design is a 1-by-1 cell array, which has a single Design matrix for each sample, no NaN values are permitted in the array. A model with this structure must have NUMSERIES ≥ NUMPARAMS with rank(Design{1}) = NUMPARAMS.
Two functions for handling missing data, ecmmvnrmle and ecmlsrmle, are stricter about the presence of NaN values in Design.