Using the Output Delivery System

Paths and Selection

Each output object (tables, graphs, notes, and so on) produced by a SAS procedure has a name and a label. Each name is part of a name path. For example, PROC GLM has a table called ErrorSSCP, and the name path (fully qualified name) is GLM.Repeated.MANOVA.Model.Error.ErrorSSCP. Each level in the name path corresponds to a part of the PROC GLM hierarchy of output. Each piece of output also has a label and a label path. For example, the PROC GLM ErrorSSCP table is labeled 'SSCP Matrix', and the label path is ’The GLM Procedure’.’Repeated Measures Analysis’.’MANOVA’.’Model’.’Error’.’SSCP Matrix’.

You need to know the name or label to select, exclude, or modify a table or graph. You can obtain this information in several ways:

  • You can obtain names from the individual procedure documentation chapter or from the individual procedure section of the SAS online Help system. See the sections "ODS Table Names" and "ODS Graphics" from within the "Details" section of the procedure documentation chapter.

  • You can use the SAS Results window to view the name of each piece of output that is created in your SAS session (see the section The SAS Results Window for more information).

  • You can use the ODS TRACE statement to find the name and label of each piece of output that is created in your SAS session. The ODS TRACE statement writes identifying information to the SAS log or listing for each generated output object.

If you are working interactively with reasonably small data sets, then the ODS TRACE statement is usually the most convenient way to find the names. Specify the ODS TRACE ON statement prior to the procedure statements that create the output for which you want information. For example, the following statements write the trace record for the output created in the REG procedure step:

ods trace on;
ods graphics on;
proc reg data=sashelp.class;
   model weight=height;
   model age=height;
run; quit;
ods trace off;

By default, the trace output is written to the SAS log. Some of the trace output from the previous step is as follows:

Output Added:
-------------
Name:       NObs
Label:      Number of Observations
Template:   Stat.Reg.NObs
Path:       Reg.MODEL1.Fit.Weight.NObs
-------------
Output Added:
-------------
Name:       ANOVA
Label:      Analysis of Variance
Template:   Stat.REG.ANOVA
Path:       Reg.MODEL1.Fit.Weight.ANOVA
-------------

Output Added:
-------------
Name:       FitStatistics
Label:      Fit Statistics
Template:   Stat.REG.FitStatistics
Path:       Reg.MODEL1.Fit.Weight.FitStatistics
-------------

Output Added:
-------------
Name:       ParameterEstimates
Label:      Parameter Estimates
Template:   Stat.REG.ParameterEstimates
Path:       Reg.MODEL1.Fit.Weight.ParameterEstimates
-------------

Output Added:
-------------
Name:       DiagnosticsPanel
Label:      Fit Diagnostics
Template:   Stat.REG.Graphics.DiagnosticsPanel
Path:       Reg.MODEL1.ObswiseStats.Weight.DiagnosticPlots.DiagnosticsPanel
-------------
Output Added:
-------------
Name:       ResidualPlot
Label:      Height
Template:   Stat.REG.Graphics.ResidualPlot
Path:       Reg.MODEL1.ObswiseStats.Weight.ResidualPlots.ResidualPlot
-------------

Output Added:
-------------
Name:       FitPlot
Label:      Fit Plot
Template:   Stat.REG.Graphics.Fit
Path:       Reg.MODEL1.ObswiseStats.Weight.FitPlot
-------------

Output Added:
-------------
Name:       NObs
Label:      Number of Observations
Template:   Stat.Reg.NObs
Path:       Reg.MODEL2.Fit.Age.NObs
-------------

.
.
.

Output Added:
-------------
Name:       FitPlot
Label:      Fit Plot
Template:   Stat.REG.Graphics.Fit
Path:       Reg.MODEL2.ObswiseStats.Age.FitPlot
-------------

Alternatively, you can specify the LISTING option (ods trace on / listing;), which writes the trace record, interleaved with the procedure output, to the LISTING destination (if it is open).

The trace record contains the name of each output object created and its associated label, template, and fully qualified name path. The label provides a description of the table or graph. The fully qualified name path shows the output hierarchy. (An example of the hierarchy is shown in Figure 20.5. The SAS Results window displays the labels, rather than the names of objects, but the hierarchy is the same for both names and labels.) The hierarchy has a level for the REG procedure, a level for the model (MODEL1 or MODEL2), a level for the fit results, a level for the dependent variable (Weight or Age), and a level for the name (for example, NObs, ANOVA, FitStatistics, ParameterEstimates).

When you specify ODS objects in an ODS statement, you can often omit the first few levels and instead use a partially qualified name path. A partially qualified name path consists of any part of the fully qualified name path that begins immediately after a period and continues to the end of the fully qualified name path. For example, the table Reg.Model1.Fit.Weight.ParameterEstimates can be referenced in any of the following ways:

$\; \; \; $ ParameterEstimates

name

Weight.ParameterEstimates

partially qualified name path

Fit.Weight.ParameterEstimates

partially qualified name path

Model1.Fit.Weight.ParameterEstimates

partially qualified name path

Reg.Model1.Fit.Weight.ParameterEstimates

fully qualified name path

When a procedure creates multiple output objects that have the same name, as shown in the preceding trace output, you have several selection options for referring to the object. You can specify the name, a fully qualified name path, or a partially qualified name path in ODS statements such as ODS SELECT, ODS EXCLUDE, or ODS OUTPUT. You can also specify a WHERE clause. For example, you can specify any of the following statements (in addition to other possibilities) to display both tables of parameter estimates:

ods select ParameterEstimates;

ods select Weight.ParameterEstimates Age.ParameterEstimates;

ods select Reg.Model1.Fit.Weight.ParameterEstimates
           Reg.Model2.Fit.Age.ParameterEstimates;

ods select where = (_path_ ? 'Parameter');

The first ODS SELECT statement specifies the object name, which is shared by both tables. The second statement specifies a partially qualified name path for both tables. The third statement specifies the fully qualified name path for each table. The fourth statement selects every object that contains the string 'Parameter' anywhere in its path.

In the first three statements, selection is case insensitive. Any combination of uppercase and lowercase letters works. This is not true in the fourth statement, which uses an ordinary SAS comparison of character strings. For case insensitivity in WHERE clause selection, use the LOWCASE function as in the following example:

ods select where = (lowcase(_path_) ? 'parameter');

You can also select objects based on a WHERE clause and the label path. The following statements turn on the trace record, display a label path in addition to the name path, and select all objects that have the string 'var' in the label:

ods trace on / label;
ods select where = (lowcase(_label_) ? 'var');

A subset of the trace record for PROC REG with this ODS SELECT list, showing just the name path and label path, is as follows:

   Path:       Reg.MODEL1.Fit.Weight.ANOVA
   Label Path: 'The Reg Procedure'.'MODEL1'.'Fit'.Weight.'Analysis of Variance'
   Path:       Reg.MODEL2.Fit.Age.ANOVA
   Label Path: 'The Reg Procedure'.'MODEL2'.'Fit'.Age.'Analysis of Variance'

The ODS SELECT statement selects the ANOVA tables, because they have the string 'Analysis of Variance' (which when lowercased contains 'var') in their labels. WHERE clause selection is also useful for selecting all of the objects within a group or level of the path hierarchy (the group 'MODEL2' or 'Fit'). You can specify any part of the name path or label path—for example, '.Age.' matches the variable Age and ignores any 'Age' that might be in the middle of a word, '2.F' matches Model 2 fit tables and any other object that has the string '2.F' in its path, and so on.

ODS records the specified object names in its internal selection or exclusion list, and then it processes the output it receives. ODS maintains an overall selection or exclusion list that pertains to all ODS destinations, and it maintains a separate selection or exclusion list for each ODS destination. The list for a specific destination provides the primary filtering step. The restrictions that you specify in the overall list are added to the destination-specific lists.

Suppose, for example, that your LISTING exclusion list (that is, the list of objects you want to exclude from the LISTING destination) contains the FitStatistics table, which you specify with the following statement:

ods listing exclude FitStatistics;

Suppose also that your overall selection list (that is, the list of objects you want to select for all destinations) contains the tables ParameterEstimates and FitStatistics, which you specify with the following statement:

ods select ParameterEstimates FitStatistics;

ODS then sends only the ParameterEstimates and FitStatistics tables to all open destinations except the LISTING destination. It sends only the ParameterEstimates table to the LISTING destination because the table FitStatistics is excluded from that destination.