SUPPORT / SAMPLES & SAS NOTES
 

Support

Sample 58775: Estimating nonlinear combinations of model parameters

DetailsResultsDownloadsAboutRate It

Estimating nonlinear combinations of model parameters

Contents: Purpose / History / Requirements / Usage / Details / Limitations / See Also

 

Note: Beginning in SAS® 9.4M6 (TS1M6), a version of this macro is available in the SAS/STAT® Autocall library as the NLEST macro and does not need to be downloaded and defined before use. To access features in more recent versions of the macro (see History), download and run as described in Usage below.

PURPOSE:
The NLEST (or NLEstimate) macro allows you to estimate one or more linear or nonlinear combinations of parameters from any model for which you can save the model parameters and their variance-covariance matrix. Most modeling procedures that offer ESTIMATE, CONTRAST, or LSMEANS statements provide only for estimating or testing linear combinations of model parameters. However, common estimation problems often involve nonlinear combinations, particularly in generalized models with nonidentity link functions such as logistic and Poisson models.
HISTORY:
The version of the NLEST macro that you are using is displayed in the log when you specify anything as the first argument. For example:
    %nlest(v)

The macro always attempts to check for a later version of itself. If it is unable to do this (such as if there is no active internet connection available), the macro will issue the following message in the log:

   NOTE: Unable to check for newer version of the NLEST macro.

The computations performed by the macro are not affected by the appearance of this message. However, this check can be avoided by specifying nochk as the first macro argument. This can be useful if your machine has no connection to the internet.

Version
Update Notes
2.1 Fixed incorrect computation of p-value when df= is specified.
2.0 nochk can be specified as the first (version) parameter. 
1.9 Added optional where= and covdrop=. This version of NLEST is available in the SAS/STAT Autocall Library beginning in SAS 9.4M8 (TS1M8).
1.8 Added optional print= and null=.
1.6 This release of the macro can be called using the preferred name NLEST and is available in the SAS/STAT Autocall Library beginning in SAS 9.4M6 (TS1M6).
1.51 Minor fix to version printing.
1.5 Added optional title= and listnames=.
1.4 When df= is omitted, large-sample Wald statistics are produced. When score= is omitted, results are saved in data set EST in addition to being displayed.
1.3 Fixes error that occurred when input model has only a single parameter such as an intercept-only model.
1.2 SAS/IML® no longer required.
1.1 Added optional score= and outscore=.
1.0 Initial coding
REQUIREMENTS:
Base SAS® and SAS/STAT® software are required. You might also need another SAS product to fit the desired model before using the macro.
USAGE:
Follow the instructions on the Downloads tab of this sample to save the NLEST macro definition. Replace the text within quotation marks in the following statement with the location of the macro definition file on your system. In your SAS program or in the SAS editor window, specify this statement to define the macro and make it available for use:
   %inc "<location of your file containing the NLEST macro>";

Following this statement, you can call the macro. See the Results tab for examples.

There are two basic uses of the macro:

  • Display model parameter names. Specify shownames as the first argument to display a list of the model parameter estimates and their associated names. The model parameter names are needed to write the functions to be estimated in a subsequent run of the macro. f= and fdata= can be omitted when using shownames. For example:
       %nlest(shownames, instore=logmod)
    
  • Estimation of functions. Input the saved model using instore= (preferred) or both inest= and incovb=. Then specify the function or functions to estimate using either f= or fdata= (or both). Do not specify shownames. The macro again displays the parameter names (unless listnames=no is specified) and also displays estimates of the specified functions. For example:
       %nlest(instore=logmod, fdata=funcs)
    

Following are the parameters available with the macro. The necessary model information is provided to the macro by specifying either instore= or both inest= and incovb=. If the modeling procedure provides a STORE statement for saving the fitted model, instore= is generally the better method for providing the model information. Additionally, if shownames is not specified as the first argument, either fdata= or f= (or both) is required.

shownames
When specified as the first argument in the macro call and score= is not specified, displays a list of the model parameter estimates and their associated names as mentioned above. No analysis results are displayed. shownames is ignored if score= or listnames=no is specified. 
instore=item-store
Specifies the fitted model that was saved using the STORE statement in the modeling procedure. The OUT= option in the STORE statement saves the model in a file known as an item store. This is the preferred method for providing the required model information. However, if the modeling procedure does not offer the STORE statement, then you might be able to use inest= and incovb=. See "Limitations" below.
inest=data-set-name
Specifies the data set of parameter estimates saved using an ODS OUTPUT statement in the modeling procedure. The parameter estimates of the model should be stored in a variable named ESTIMATE in this data set. An error is issued if the ESTIMATE variable is not found. When inest= is specified, incovb= must also be specified. The parameter vector in the inest= data set must be compatible with the covariance matrix in the incovb= data set. See "Compatibility error when using inest= and incovb=" below.
incovb=data-set-name
Specifies the data set containing the variance-covariance matrix of model parameters saved using an ODS OUTPUT statement in the modeling procedure. Typically, an option such as COVB is required in the modeling procedure to make this matrix available for saving. When incovb= is specified, inest= must also be specified. The parameter vector in the inest= data set must be compatible with the covariance matrix in the incovb= data set. See "Compatibility error when using inest= and incovb=" below.
where=condition
Requires version 1.9 or later of the macro. Specifies an optional condition to subset the inest= and incovb= data sets. Condition is a valid expression for the WHERE statement and is useful when the input data sets were created using a BY statement or, in survey analysis, when the DOMAIN statement was used.
covdrop=variable(s)
Requires version 1.9 or later of the macro. Specifies one or more variables to be dropped from the incovb= data set. This can be helpful when an error occurs indicating that the covariance matrix is incompatible with the parameter vector. That error is often caused by the presence of numeric variables in the incovb= data set that do not contain columns of the covariance matrix.
fdata=data-set-name
Specifies a data set containing the functions to be estimated (estimands). fdata= can be used when you have more than one function to estimate. This data set must contain two character variables with names LABEL and F. In each observation of the data set, F contains a function to be estimated involving the parameter names of the model. In this function, the model parameters are referred to using names of the form B_P1, B_P2, and so on in the order as displayed by the modeling procedure. LABEL contains a text string used to label the estimate of the function in the results. The label does not need to be enclosed in quotation marks. Do not use double quotation marks (") in either the F or LABEL variable. Use single quotation marks (') instead if needed. The results are also saved in data set EST.
f=expression
Specifies an expression representing a single function to be estimated (the estimand) involving the parameter names. In this function, the model parameters are referred to using names of the form B_P1, B_P2, and so on in the order as displayed by the modeling procedure. These names and associated values can be displayed by specifying shownames as described above. f= can be used when only one function is to be estimated. Do not use double quotation marks (") in the expression. Use single quotation marks (') instead if needed. Any quotation marks must appear in pairs. For estimands that involve values from data set variables, specify score=. When score= is not specified, the results are also saved in data set EST.
label=text-string
Optionally, can be used to label the single function specified in f=. Ignored if f= is not specified. Do not use quotation marks surrounding or within text-string.
null=value
Requires version 1.8 or later of the macro. Specifies value in the null hypothesis H0: f(β)=value, where f(β) is the function of model parameters specified in f= or fdata= and value is a numeric value. Scientific notation, such as 1E4, is not allowed. Requires version 1.8 or later of the macro. The default is null=0.
df=value
Specifies the degrees of freedom to be used in the test and confidence interval computed for the estimated functions. value must be a non-zero, positive value. Scientific notation, such as 1E4 is not allowed. If omitted or null, large-sample Wald statistics are given. The degrees of freedom for testing a linear combination of parameters in a linear model would typically be the number of observations used in fitting the model minus the number of parameters estimated in the model – essentially, the error degrees of freedom.
alpha=value
Specifies the alpha level to be used in computing confidence limits. If omitted, alpha=0.05.
score=data-set-name
Specifies a data set for which the function in f= is evaluated for each observation. Use score= together with f= when the estimand involves values of variables in the input data set. score= cannot be used with fdata=.
outscore=data-set-name
Names a data set to be created that is a copy of the score= data set and has additional variables for the estimated function, its standard error, test statistic, p-value, and confidence limits in each observation. If not specified, the data set is named NLEST.
listnames=yes|no
Display parameter names or not before the results table. listnames=no suppresses the table of names. The default is listnames=yes.
print=yes|no
Display or suppress the results table. The default is print=yes. Note that print= has no effect on displaying the table of parameter names, which is controlled by listnames=. To suppress all printed output, specify print=no and listnames=no. Requires version 1.8 or later of the macro. The default is print=yes.
title=title-text
Specifies a title for the results table. The title-text must not contain quotation marks (" or '), ampersands(&), commas(,), or parentheses. If omitted, title=Nonlinear Function Estimate.
DETAILS:
The NLEST (or NLEstimate) macro takes advantage of the ESTIMATE statement in PROC NLMIXED, which can estimate and test nonlinear (or linear) functions of model parameters, f(β). It uses NLMIXED to fit a multivariate normal distribution with mean equal to the input model parameter estimates and variance equal to the input model covariance matrix. This creates a log likelihood that is zero and NLMIXED is able to converge immediately to a model with the specified parameter estimates and covariance matrix. It is then possible to use the ESTIMATE statement to estimate and test the function(s) specified in f= or fdata=. The test provided is a test of the null hypothesis H0: f(β)=value, where value is specified in null= (zero by default).

Compatibility error when using inest= and incovb=

The incovb= data set should have the same number of observations (rows) and variables (columns) as the number of rows in the inest= data set in order to be compatible. Otherwise, an error message is issued that indicates the relevant numbers of rows and columns. If the incovb= data set contains numeric variables other than those containing the covariance matrix, they should be removed in order to avoid a compatibility error. This can be done either by preprocessing the data set to remove the extraneous variables or by specifying them in covdrop= (requires version 1.9 or later of the macro).

When the modeling procedure uses GLM parameterization of CLASS variables (PARAM=GLM in the CLASS statement, which is the default in many procedures), the NLEST macro will typically display the following Warning message in this log. This Warning can be ignored.

WARNING: The final Hessian matrix is not positive definite, and therefore the estimated
         covariance matrix is not full rank and may be unreliable.  The variance of some
         parameter estimates is zero or some parameters are linearly related to other
         parameters.

BY group or domain processing

The NLEST macro does not directly support BY group processing (such as for the analysis of multiply imputed data) or processing of domains from a survey analysis. That is, it cannot directly be used to process all results from a modeling procedure that was run using a BY or DOMAIN statement. However, this capability can be provided by the RunBY macro, which can run the NLEST macro repeatedly for each of the BY groups in your data. Version 1.9 or later of the NLEST macro and version 1.1 or later of the RunBY macro are required. See the RunBY macro documentation (SAS Note 66249) for details about its use. Additionally, you can use where= to allow NLEST to process the results of one BY group or domain by specifying an appropriate condition to select that BY group or domain. See Example 2 in the Results tab above.

Output data set

When score= is not specified, the results from the macro are automatically saved in data set EST. When score= is specified, the f= function is evaluated for each observation in the score= data set and saved in a data set named NLEST, by default, or as named in outscore=.

LIMITATIONS:
Some modeling procedures cannot provide the necessary covariance matrix for some models or estimands. For example, since PROC GLIMMIX cannot provide a covariance matrix that includes the scale parameter, an estimand involving the scale parameter cannot be estimated. Some procedures either do not have a STORE statement (such as PROC FMM) or do not save the necessary model information (such as PROC COUNTREG). In such cases, use inest= and incovb= instead of instore=.
SEE ALSO:
The NLMeans macro (SAS Note 62362) can be used to do multiple comparisons among the levels of a model effect on the mean scale. The macro forms the expressions that must be evaluated and then calls the NLEST macro to do the computations. See the NLMeans macro description for details. The Margins macro (SAS Note 63038) can also be used to estimate and test differences or contrasts of means. Unlike the NLMeans macro, the Margins macro can be used when one or more predictors in the model is not fixed.



These sample files and code examples are provided by SAS Institute Inc. "as is" without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Recipients acknowledge and agree that SAS Institute shall not be liable for any damages whatsoever arising out of their use of this material. In addition, SAS Institute will provide no support for the materials contained herein.