# covarianceParameters

**Class: **GeneralizedLinearMixedModel

Extract covariance parameters of generalized linear mixed-effects model

## Syntax

## Description

`[`

also
returns an estimate of the dispersion parameter.`psi`

,`dispersion`

]
= covarianceParameters(`glme`

)

`[`

also
returns a cell array `psi`

,`dispersion`

,`stats`

]
= covarianceParameters(`glme`

)`stats`

containing the covariance
parameter estimates and related statistics.

`[___] = covarianceParameters(`

returns
any of the above output arguments using additional options specified
by one or more `glme`

,`Name,Value`

)`Name,Value`

pair arguments. For
example, you can specify the confidence level for the confidence limits
of covariance parameters.

## Input Arguments

`glme`

— Generalized linear mixed-effects model

`GeneralizedLinearMixedModel`

object

Generalized linear mixed-effects model, specified as a `GeneralizedLinearMixedModel`

object.
For properties and methods of this object, see `GeneralizedLinearMixedModel`

.

### Name-Value Arguments

Specify optional pairs of arguments as
`Name1=Value1,...,NameN=ValueN`

, where `Name`

is
the argument name and `Value`

is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.

*
Before R2021a, use commas to separate each name and value, and enclose*
`Name`

*in quotes.*

`Alpha`

— Significance level

0.05 (default) | scalar value in the range [0,1]

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

`psi`

— Estimated prior covariance parameters

cell array

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 g_{r},
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`

— Dispersion parameter

scalar value

Dispersion parameter, returned as a scalar value.

`stats`

— Covariance parameter estimates and related statistics

cell array

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 Name | Description |
---|---|

`Group` | Grouping variable name |

`Name1` | Name of the first predictor variable |

`Name2` | Name of the second predictor variable |

`Type ` |
If If |

`Estimate` |
If If |

`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

### Obtain Estimated Covariance Parameters

Load the sample data.

`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}({\mu}_{ij})$$

This corresponds to the generalized linear mixed-effects model

$$\mathrm{log}({\mu}_{ij})={\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(0,{\sigma}_{b}^{2})$$ 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.

## See Also

`GeneralizedLinearMixedModel`

| `fitglme`

| `compare`

| `fixedEffects`

| `randomEffects`

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)