------------------------------------------------------------------------------- help formarglmean(Roger Newson) -------------------------------------------------------------------------------

Marginal log means from regression models

marglmean[if] [in] [weight] , [atspec(atspec)subpop(subspec)predict(pred_opt)vce(vcespec)noesampleforceiterate(#)eformlevel(#)post]where

atspecis an at-specification recognized by theat()option ofmargins,subspecis a subpopulation specification of the form recognized by thesubpop()option ofmargins, andvcespecis a variance-covariance specification of the form recognized bymargins, and must have one of the values

delta|unconditional

fweights,aweights,iweights,pweights are allowed; see weight.

Description

marglmeancalculates symmetric confidence intervals for log marginal means (also known as log scenario means), and asymmetric confidence intervals for the marginal means themselves.marglmeancan be used after an estimation command whose predicted values are interpreted as positive conditional arithmetic means of non-negative-valued outcome variables, such aslogit,logistic,probit,poisson, orglmwith most non-Normal distributional families. It can estimate a marginal mean for a scenario ("Scenario 1"), in which one or more predictor variables may be assumed to be set to particular values, and any other predictor variables in the model are assumed to remain the same.

Options formarglmean

atspec(atspec)is an at-specification, allowed as a value of theat()option ofmargins. This at-specification must specify a single scenario ("Scenario 1"), defined as a fantasy world in which a subset of the predictor variables in the model are set to specified values.marglmeanuses themarginscommand to estimate the marginal arithmetic mean under Scenario 1, and then usesnlcomto estimate the log of this scenario mean, known as the marginal log mean. Ifatspec()is not specified, then its default value isatspec((asobserved) _all), implying that Scenario 1 is the real-life baseline scenario, represented by the predictor values actually present.

subpop(subspec),predict(pred_opt)andvce(vcespec)have the same form and function as the options of the same names formargins. They specify the subpopulation, the predict option(s), and the variance-covariance matrix formula, respectively, used to estimate the log of the marginal mean.

noesamplehas the same function as the option of the same name formargins. It specifies that computations will not be restricted to the estimation sample used by the previous estimation command.

forcehas the same function as the option of the same name formargins.

iterate(#)has the same form and function as the option of the same name fornlcom. It specifies the number of iterations used bynlcomto find the optimal step size to calculate the numerical derivative of the log of the marginal mean, with respect to the original marginal mean calculated bymargins.

eformspecifies thatmarglmeanwill display an estimate,P-value and confidence limits for the marginal mean, instead of for the log marginal mean. Ifeformis not specified, then a confidence interval for the log marginal mean is displayed. Whether or noteformis specified, the saved results will contain an estimate vector and variance matrix for the log marginal mean.

level(#)specifies the percentage confidence level to be used in calculating the confidence interval. If it is not specified, then it is taken from the current value of the c-class valuec(level), which is usually 95.

postspecifies thatmarglmeanwill post ine()the estimation results for estimating the log of the marginal mean. Ifpostis not specified, then any existing estimation results are left ine(). Note that the estimation results posted are for the log of the marginal mean, and not for the marginal mean itself. This is done because the estimation results are intended to define a symmetric confidence interval for the log-transformed marginal mean, which can be back-transformed to define an asymmetric confidence interval for the untransformed marginal mean.

Remarks

marglmeanestimates the marginal mean, which is a scenario mean. The general principles behind scenario means for generalized linear models were introduced in Lane and Nelder (1982).

marglmeanstarts by estimating the log of the scenario mean, usingmarginsandnlcom. The results of this estimation are stored ine(), if the optionpostis specified. These estimation results may be saved in an output dataset (or resultsset) by theparmestpackage, which can be downloaded from SSC.

marglmeanassumes that the most recent estimation command estimates the parameters of a regression model, whose fitted values are conditional arithmetic means, which must be positive. It is the user's responsibility to ensure that this is the case. However, it will be true if the conditional proportions are defined using a generalized linear model with a binomial, negative binomial, Poisson, gamma or inverse Gaussian distributional family, and a link function with a positive domain, such as a power, the log, the logit, the probit, or the complementary log-log.Note that

marglmeanestimates a single marginal mean, and does not compare 2 marginal means from the same estimation using differences or ratios. Users who need to estimate differences between marginal means should usemarginsfollowed bycontrast. Users who need to estimate ratios between scenario means (population unattributable fractions) should use eitherpunaf(for cohort or cross-sectional study data) orpunafcc(for case-control or survival study data). Users who need to estimate marginal prevalences or proportions (a special case of scenario means) should probably usemargprev. Users who need to estimate differences between scenario proportions (population attributable risks) should useregpar. The packagespunaf,punafcc,margprevandregparare downloadable from SSC.

ExamplesThe following examples use the

autodataset, distributed with Stata.Setup

. sysuse auto, clear. describeThe following examples estimate marginal means of mileage, or their logs, either in the real world or in a fantasy scenario, where all car models are US-made but have the same weight as in the real world.

. glm mpg weight foreign, fam(gamma) link(log) robust eform. marglmean, eform. marglmean, at(foreign=0) eform. marglmean. marglmean, at(foreign=0)The following example demonstrates the use of

marglmeanwith theparmestpackage, downloadable from SSC. The marginal mean of mileage is estimated usingmarglmean(with thepostoption), and saved, usingparmest, in a dataset in memory, overwriting the original dataset, with 1 observation for the untransformed parameter, named"Scenario_1", and data on the estimate, confidence limits,P-value, and other parameter attributes. We thendescribeandlistthe new dataset.

. glm mpg weight foreign, fam(gamma) link(log) robust eform. marglmean, eform post. parmest, eform norestore. describe. list

Saved results

marglmeansaves the following inr():Scalars

r(rank)rank ofr(V)r(N)number of observationsr(N_sub)subpopulation observationsr(N_clust)number of clustersr(N_psu)number of samples PSUs, survey data onlyr(N_strata)number of strata, survey data onlyr(df_r)variance degrees of freedom, survey data onlyr(N_poststrata)number of post strata, survey data onlyr(k_margins)number of terms inmarginlistr(k_by)number of subpopulationsr(k_at)number ofat()options (always 1)r(level)confidence level of confidence intervalsMacros

r(atspec)atspec()optionMatrices

r(b)vector of the log of the marginal meanr(V)estimated variance-covariance matrix of the log of the marginal meanIf

postis specified,marglmeanalso saves the following ine():Scalars

e(rank)rank ofe(V)e(N)number of observationse(N_sub)subpopulation observationse(N_clust)number of clusterse(N_psu)number of samples PSUs, survey data onlye(N_strata)number of strata, survey data onlye(df_r)variance degrees of freedom, survey data onlye(N_poststrata)number of post strata, survey data onlye(k_margins)number of terms inmarginliste(k_by)number of subpopulationse(k_at)number ofat()options (always 1)Macros

e(cmd)marglmeane(predict)program used to implementpredicte(atspec)atspec()optione(properties)b VMatrices

e(b)vector of the log of the marginal meane(V)estimated variance-covariance matrix of the log of the marginal meane(V_srs)simple-random-sampling-without-replacement (co)variance hat V_srswor, ifsvye(V_srswr)simple-random-sampling-with-replacement (co)variance hat V_srswr, ifsvyandfpc()e(V_msp)misspecification (co)variance hat V_msp, ifsvyand availableFunctions

e(sample)marks estimation sample

AuthorRoger Newson, National Heart and Lung Institute, Imperial College London, UK. Email: r.newson@imperial.ac.uk

ReferencesLane, P. W., and J. A. Nelder. 1982. Analysis of covariance and standardization as instances of prediction.

Biometrics38: 613–621.

Also seeManual:

[R] margins,[R] nlcom,[R] logistic,[R] logit,[R] probit,[R]glmHelp:

[R] margins,[R] nlcom,[R] logistic,[R] logit,[R] probit,[R]glmmargprev,regpar,punaf,punafcc,parmestif installed