# covarianceParameters

Extract covariance parameters of generalized linear mixed-effects model

## Syntax

``psi = covarianceParameters(glme)``
``````[psi,dispersion] = covarianceParameters(glme)``````
``````[psi,dispersion,stats] = covarianceParameters(glme)``````
``[___] = covarianceParameters(glme,Name,Value)``

## Description

````psi = covarianceParameters(glme)` returns the estimated prior covariance parameters of random-effects predictors in the generalized linear mixed-effects model `glme`.```
``````[psi,dispersion] = covarianceParameters(glme)``` also returns an estimate of the dispersion parameter.```

example

``````[psi,dispersion,stats] = covarianceParameters(glme)``` also returns a cell array `stats` containing the covariance parameter estimates and related statistics.```
````[___] = covarianceParameters(glme,Name,Value)` returns any of the above output arguments using additional options specified by one or more `Name,Value` pair arguments. For example, you can specify the confidence level for the confidence limits of covariance parameters.```

## Input Arguments

expand all

Generalized linear mixed-effects model, specified as a `GeneralizedLinearMixedModel` object. For properties and methods of this object, see `GeneralizedLinearMixedModel`.

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Significance level, specified as the comma-separated pair consisting of `'Alpha'` and a scalar value in the range [0,1]. For a value α, the confidence level is 100 × (1 – α)%.

For example, for 99% confidence intervals, you can specify the confidence level as follows.

Example: `'Alpha',0.01`

Data Types: `single` | `double`

## Output Arguments

expand all

Estimated prior covariance parameters for the random-effects predictors, returned as a cell array of length R, where R is the number of grouping variables used in the model. `psi{r}` contains the covariance matrix of random effects associated with grouping variable gr, where r = 1, 2, ..., R, The order of grouping variables in `psi` is the same as the order entered when fitting the model. For more information on grouping variables, see Grouping Variables.

Dispersion parameter, returned as a scalar value.

Covariance parameter estimates and related statistics, returned as a cell array of length (R + 1), where R is the number of grouping variables used in the model. The first R cells of `stats` each contain a dataset array with the following columns.

Column NameDescription
`Group`Grouping variable name
`Name1`Name of the first predictor variable
`Name2`Name of the second predictor variable
`Type `

If `Name1` and `Name2` are the same, then `Type` is `std` (standard deviation).

If `Name1` and `Name2` are different, then `Type` is `corr` (correlation).

`Estimate`

If `Name1` and `Name2` are the same, then `Estimate` is the standard deviation of the random effect associated with predictor `Name1` or `Name2`.

If `Name1` and `Name2` are different, then `Estimate` is the correlation between the random effects associated with predictors `Name1` and `Name2`.

`Lower`Lower limit of the confidence interval for the covariance parameter
`Upper`Upper limit of the confidence interval for the covariance parameter

Cell R + 1 contains related statistics for the dispersion parameter.

It is recommended that the presence or absence of covariance parameters in `glme` be tested using the `compare` method, which uses a likelihood ratio test.

When fitting a GLME model using `fitglme` and one of the maximum likelihood fit methods (`'Laplace'` or `'ApproximateLaplace'`), `covarianceParameters` derives the confidence intervals in `stats` based on a Laplace approximation to the log likelihood of the generalized linear mixed-effects model.

When fitting a GLME model using `fitglme` and one of the pseudo likelihood fit methods (`'MPL'` or `'REMPL'`), `covarianceParameters` derives the confidence intervals in `stats` based on the fitted linear mixed-effects model from the final pseudo likelihood iteration.

## Examples

expand all

`load mfr`

This simulated data is from a manufacturing company that operates 50 factories across the world, with each factory running a batch process to create a finished product. The company wants to decrease the number of defects in each batch, so it developed a new manufacturing process. To test the effectiveness of the new process, the company selected 20 of its factories at random to participate in an experiment: Ten factories implemented the new process, while the other ten continued to run the old process. In each of the 20 factories, the company ran five batches (for a total of 100 batches) and recorded the following data:

• Flag to indicate whether the batch used the new process (`newprocess`)

• Processing time for each batch, in hours (`time`)

• Temperature of the batch, in degrees Celsius (`temp`)

• Categorical variable indicating the supplier (`A`, `B`, or `C`) of the chemical used in the batch (`supplier`)

• Number of defects in the batch (`defects`)

The data also includes `time_dev` and `temp_dev`, which represent the absolute deviation of time and temperature, respectively, from the process standard of 3 hours at 20 degrees Celsius.

Fit a generalized linear mixed-effects model using `newprocess`, `time_dev`, `temp_dev`, and `supplier` as fixed-effects predictors. Include a random-effects term for intercept grouped by `factory`, to account for quality differences that might exist due to factory-specific variations. The response variable `defects` has a Poisson distribution, and the appropriate link function for this model is log. Use the Laplace fit method to estimate the coefficients. Specify the dummy variable encoding as `'effects'`, so the dummy variable coefficients sum to 0.

The number of defects can be modeled using a Poisson distribution

`${\text{defects}}_{ij}\sim \text{Poisson}\left({\mu }_{ij}\right)$`

This corresponds to the generalized linear mixed-effects model

`$\mathrm{log}\left({\mu }_{ij}\right)={\beta }_{0}+{\beta }_{1}{\text{newprocess}}_{ij}+{\beta }_{2}{\text{time}\text{_}\text{dev}}_{ij}+{\beta }_{3}{\text{temp}\text{_}\text{dev}}_{ij}+{\beta }_{4}{\text{supplier}\text{_}\text{C}}_{ij}+{\beta }_{5}{\text{supplier}\text{_}\text{B}}_{ij}+{b}_{i},$`

where

• ${\text{defects}}_{ij}$ is the number of defects observed in the batch produced by factory $i$ during batch $j$.

• ${\mu }_{ij}$ is the mean number of defects corresponding to factory $i$ (where $i=1,2,...,20$) during batch $j$ (where $j=1,2,...,5$).

• ${\text{newprocess}}_{ij}$, ${\text{time}\text{_}\text{dev}}_{ij}$, and ${\text{temp}\text{_}\text{dev}}_{ij}$ are the measurements for each variable that correspond to factory $i$ during batch $j$. For example, ${\text{newprocess}}_{ij}$ indicates whether the batch produced by factory $i$ during batch $j$ used the new process.

• ${\text{supplier}\text{_}\text{C}}_{ij}$ and ${\text{supplier}\text{_}\text{B}}_{ij}$ are dummy variables that use effects (sum-to-zero) coding to indicate whether company `C` or `B`, respectively, supplied the process chemicals for the batch produced by factory $i$ during batch $j$.

• ${b}_{i}\sim N\left(0,{\sigma }_{b}^{2}\right)$ is a random-effects intercept for each factory $i$ that accounts for factory-specific variation in quality.

`glme = fitglme(mfr,'defects ~ 1 + newprocess + time_dev + temp_dev + supplier + (1|factory)','Distribution','Poisson','Link','log','FitMethod','Laplace','DummyVarCoding','effects');`

Compute and display the estimate of the prior covariance parameter for the random-effects predictor.

```[psi,dispersion,stats] = covarianceParameters(glme); psi{1}```
```ans = 0.0985 ```

`psi{1}` is an estimate of the prior covariance matrix of the first grouping variable. In this example, there is only one grouping variable (`factory`), so `psi{1}` is an estimate of ${\sigma }_{b}^{2}$.

Display the dispersion parameter.

`dispersion`
```dispersion = 1 ```

Display the estimated standard deviation of the random effect associated with the predictor. The first cell of `stats` contains statistics for `factory`, while the second cell contains statistics for the dispersion parameter.

`stats{1}`
```ans = Covariance Type: Isotropic Group Name1 Name2 Type factory {'(Intercept)'} {'(Intercept)'} {'std'} Estimate Lower Upper 0.31381 0.19253 0.51148 ```

The estimated standard deviation of the random effect associated with the predictor is 0.31381. The 95% confidence interval is [0.19253 , 0.51148]. Because the confidence interval does not contain 0, the random intercept is significant at the 5% significance level.