help for scenttest(Roger Newson)

Scenario arithmetic (or geometric) means and their difference (or ratio)

scenttest [if] [in] [weight] , [ atspec(atspec)
atzero(atspec0) subpop(subspec) predict(pred_opt) vce(vcespec) df(#) noesample force
iterate(#) eform level(#) post
]

where atspec and atspec0 are at-specifications recognized by the at() option of margins,
subspec is a subpopulation specification of the form recognized by the subpop() option of margins,
and vcespec is a variance-covariance specification of the form recognized by margins,
and must have one of the values

delta | unconditional

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

Description

scenttest calculates confidence intervals for 2 scenario arithmetic (or geometric) means,
and for their difference (or ratio).
scenttest can be used after an estimation command whose predicted values
are interpreted as conditional arithmetic means of a Y-variable,
such as regress, poisson, or glm.
It estimates two scenario means,
a baseline scenario ("Scenario 0") and an alternative scenario ("Scenario 1"),
in which one or more exposure variables are assumed to be set to particular values (typically zero),
and any other predictor variables in the model are assumed to remain the same.
It also estimates the difference between the Scenario 0 mean and the Scenario 1 mean.
This difference represents the increase in the mean Y-value
attributable to living in Scenario 0 instead of Scenario 1.
If the Y-variable is derived as the log of a positive-valued original outcome variable,
then the scenario means displayed may be the scenario geometric means of the original outcome variable,
and the comparison displayed may be their ratio.

Options for scenttest

atspec(atspec) is an at-specification,
allowed as a value of the at() option of margins.
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 values different from their value in the baseline scenario
(denoted "Scenario 0" and equal to the real-life scenario unless atzero() is specified).
scenttest uses the margins command to estimate the means of outcome values
under Scenarios 0 and 1,
and then uses nlcom to estimate these 2 scenario means,
together with the difference between the Scenario 0 mean and the Scenario 1 mean.
If atspec() is not specified,
then its default value is atspec((asobserved) _all),
implying that Scenario 1 is the real-life baseline scenario,
represented by the predictor values actually present.

atzero(atspec0) is an at-specification,
allowed as a value of the at() option of margins.
This at-specification must specify a single baseline scenario ("Scenario 0"),
defined as an alternative fantasy world in which a subset of predictors in the model
are set to the values specified by atspec0.
Scenario 0 will then be compared to the "Scenario 1" specified by the atspec() option.
If atzero() is not specified,
then its default value is atzero((asobserved) _all),
implying that Scenario 0 is the real-life baseline scenario,
represented by the predictor values actually present.

subpop(subspec), predict(pred_opt) and vce(vcespec)
have the same form and function as the options of the same names for margins.
They specify the subpopulation, the predict option(s),
and the variance-covariance matrix formula, respectively,
used to estimate the scenario means and their difference.

df(#) has the same function as the option of the same name for margins and nlcom.
It specifies the degrees of freedom to be used in calculating confidence intervals.
If absent, it is set to the default used by margins,
which may be missing, implying the use of the standard Normal distribution.

noesample has the same function as the option of the same name for margins.
It specifies that computations will not be restricted to the estimation sample
used by the previous estimation command.

force has the same function as the option of the same name for margins.

iterate(#) has the same form and function as the option of the same name for nlcom.
It specifies the number of iterations used by nlcom
to find the optimal step size to calculate the numerical derivatives
of the scenario means and their difference,
with respect to the original scenario means calculated by margins.

eform specifies that scenttest will display estimates, P-values and confidence limits
for the scenario geometric means of the exponentiated Y-variable and their ratio.
If eform is not specified,
then confidence intervals are displayed for the scenario arithmetic means of the unexponentiated Y-variable
and their difference.

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

post specifies that scenttest will post in e()
the estimation results
for estimating the scenario arithmetic means of the Y-variable
and their difference.
If post is not specified, then any existing estimation results are left in e().

Remarks

scenttest estimates scenario arithmetic means and their difference.
The results of this estimation are stored in e(),
if the option post is specified.
These estimation results may be saved in an output dataset (or resultsset) by the parmest package,
which can be downloaded from SSC.
The general principles behind scenario comparisons
for generalized linear models
were introduced in Lane and Nelder (1982).

scenttest assumes that the most recent estimation command
estimates the parameters of a regression model,
whose fitted values are conditional arithmetic means.
It is the user's responsibility to ensure that this is the case.
However, it will be true if the conditional means are defined using a generalized linear model,
which includes linear regression as a special case.

Other scenario comparisons include population attributable and unattributable risks (PARs and PURs)
and population attributable and unattributable fractions (PAFs and PUFs).
A population attributable risk is a difference between scenario proportions,
a population unattributable risk is a senario proportion,
a population unattributable fraction is a ratio between scenario proportions (or means),
and a population attributable fraction is the result of subtracting a population unattributable fraction from 1.
Users who need to estimate population attributable risks should use regpar.
Users who need to estimate population unattributable or attributable fractions should use either punaf
(for cohort or cross-sectional study data)
or punafcc
(for case-control or survival study data).
Users who need to estimate scenario prevalences (without differences)
should use margprev.
Users who need to estimate log-transformed scenario means (without ratios)
should use marglmean.
Users who need to estimate untransformed scenario means (without differences or ratios)
should use margins.
The packages regpar, punaf, punafcc, margprev and marglmean
are downloadable from SSC.
More about them can be found in
Newson (2012)
and in
Newson (2013)

Examples

The following example uses the auto dataset,
distributed with official Stata.
This dataset has 1 observation for each of a sample of car models.
We fit a regression model, predicting mileage from car weight and non-US origin.
We then use scenttest to estimate the difference in mean mileage
between the real-world sample and a fantasy scenario,
where all cars are from non-US companies,
and their weights are the same as in the real world.
We then compare mean mileage between 2 fantasy scenarios,
one where all cars are from non-US companies and one where all cars are from US companies,
with real-world weights in both scenarios.

Setup

.sysuse auto, clear

.describe

Scenario comparisons

.regress mpg weight i.foreign

.scenttest, at(foreign=1)

.scenttest, at(foreign=1) atzero(foreign=0)

The following examples use Poisson regression in the dollhill3 dataset,
distributed by StataCorp.
This dataset has 1 observation for each of 10 combinations
of age group and smoking status,
and data on deaths and person-years of exposure.

Setup

.webuse dollhill3, clear

.describe

.gene thpyears=pyears/1000

.label variable thpyears "Exposure (thousand person years)"

.list, sepby(smokes)

The following example fits an interactive Poisson regression model
to the data,
predicting deaths per thousand person-years
from age group and smoking exposure.
We then use {cmd:scenttest),
with the option predict(ir) and pweights equal to exposure,
to compare incidence rates in the real world
with those in a dream scenario,
where the whole world stops smoking.
We then compare this dream scenario with a nightmare scenario,
where the whole world starts smoking.
Note that the Poisson model is interactive,
with parameters equal to the death rates in each combination of smoking status and age group.
The estimated difference between scenarios therefore allows the possibility that the increase in death rate due to smoking
may vary between age groups.

.poisson deaths ibn.smokes#ibn.agecat, exposure(thpyears) irr noconst

.scenttest [pweight=thpyears], predict(ir) at(smokes=0)

.scenttest [pweight=thpyears], predict(ir) at(smokes=0) atzero(smokes=1)

The following example demonstrates an alternative method,
using the SSC package parmest.
This time, we use scenttest to estimate the mean number of deaths
expected in the 10 combinations of age group and smoking,
in the real world and in the dream scenario,
and the between-scenario difference.
We then use parmest to save the parameters to a temporary dataset,
where the means, their difference, and their standard errors and confidence limits
are scaled by the number of combinations
to estimate the expected total numbers of deaths in the two scenarios,
and the number of lives saved by eliminating smoking.

.scenttest, at(smokes=0)

.preserve

.parmest, bmatrix(r(b)) vmatrix(r(V)) escal(N) fast

.foreach Y of var estimate stderr min* max* {

. replace `Y'=`Y'*es_1

.}

.list, abbr(32)

.restore

Saved results

scenttest saves the following in r():

Scalars

r(rank) rank of r(V)

r(N) number of observations

r(N_sub) subpopulation observations

r(N_clust) number of clusters

r(N_psu) number of samples PSUs, survey data only

r(N_strata) number of strata, survey data only

r(df_r) variance degrees of freedom, survey data only

r(N_poststrata) number of post strata, survey data only

r(k_margins) number of terms in marginlist

r(k_by) number of subpopulations

r(k_at) number of at() options (always 2)

r(level) confidence level of confidence intervals

Macros

r(atzero) atzero() option

r(atspec) atspec() option

Matrices

r(b) vector of scenario arithmetic means and their difference

r(V) estimated variance-covariance matrix of scenario arithmetic means and their difference

If post is specified, scenttest also saves the following in e():

Scalars

e(rank) rank of e(V)

e(N) number of observations

e(N_sub) subpopulation observations

e(N_clust) number of clusters

e(N_psu) number of samples PSUs, survey data only

e(N_strata) number of strata, survey data only

e(df_r) variance degrees of freedom, survey data only

e(N_poststrata) number of post strata, survey data only

e(k_margins) number of terms in marginlist

e(k_by) number of subpopulations

e(k_at) number of at() options (always 2)

Macros

e(cmd) scenttest

e(predict) program used to implement predict

e(atzero) atzero() option

e(atspec) atspec() option

e(properties) b V

Matrices

e(b) vector of scenario arithmetic means and their difference

e(V) estimated variance-covariance matrix of scenario arithmetic means and their difference

e(V_srs) simple-random-sampling-without-replacement (co)variance
hat V_srswor, if svy

e(V_srswr) simple-random-sampling-with-replacement (co)variance
hat V_srswr, if svy and fpc()

e(V_msp) misspecification (co)variance hat V_msp, if svy
and available

Functions

e(sample) marks estimation sample

Author

Roger Newson, Imperial College London, UK.

Email: r.newson@imperial.ac.uk

References

Lane, P. W., and J. A. Nelder.
1982.
Analysis of covariance and standardization as instances of prediction.
Biometrics 38: 613-621.

Newson, R. B.
2012.
Scenario comparisons: How much good can we do?
Presented at the 18th United Kingdom Stata Users' Group Meeting, 13-14 September, 2012.

Newson, R. B.
2013.
Attributable and unattributable risks and fractions and other scenario comparisons.
The Stata Journal 13(4): 672-698.
Download from
the Stata Journal website.

Also see

Manual: [R] margins, [R] nlcom, [R] regress, [R] poisson, [R] glm

Help: [R] margins, [R] nlcom, [R] regress, [R] poisson, [R] glm

regpar, punaf, punafcc, margprev, marglmean, parmest if installed