Frequency and Crosstabulation Analysis Action Set

The following PROC CAS statements use the freqTab action in the freqTab action set to produce frequency and crosstabulation tables:

proc cas;
   action freqTab.freqTab /
      table='Color',
      weight='Count',
      tabulate={'Eyes', 'Hair',
                {vars={'Eyes', 'Hair'}},
                {vars='Region', cross={'Eyes', 'Hair'}}
               };
run;

The tabulate parameter enables you to specify the frequency and crosstabulation tables to produce. This parameter defines a list of terms that are enclosed in braces and separated by commas. Each of these terms contains a list of variables defined by the vars subparameter and optionally a list of variables defined by the cross subparameter. In this example, the terms are {vars={’Eyes’}}, {vars={’Hair’}}, {vars={’Eyes’, ’Hair’}}, and {vars={’Region’}, cross={’Eyes’, ’Hair’}}. These terms define the frequency and crosstabulation tables to produce that correspond to the following syntax that you would use in the FREQ procedure in SAS/STAT:

tables Eyes Hair Eyes*Hair Region*(Eyes Hair);

If a term contains only a vars subparameter and the list that the vars subparameter defines consists of only a single variable, then you can directly specify the variable in the tabulate parameter without the enclosing braces. This type of simplification is a general property of action syntax that is referred to as "coercion." You can exploit coercion to simplify the specification {vars={’Eyes’}} to be simply ’Eyes’. You can also use coercion to simplify the specification of the vars subparameter when the list within braces that it defines consists of a single string. In this case, you can omit the braces and specify the string directly in the vars subparameter. Thus the term {vars={’Region’}, cross={’Eyes’, ’Hair’}} can be specified as {vars=’Region’, cross={’Eyes’, ’Hair’}}.

You define a single variable in the vars subparameter to produce a one-way frequency table. To produce two-way to multiway crosstabulation tables, you define at least two variables in the vars subparameter. The values of the last variable that is defined in the vars subparameter form the crosstabulation table columns. The values of the next-to-last variable form the rows. Each level (or combination of levels) of the other variables forms one stratum. By default, the freqTab action displays two-way and multiway tables in CROSSLIST format, where a separate two-way crosstabulation table is generated for each stratum of a multiway table.

When you specify the cross subparameter along with the vars subparameter, each pair of variables (one from the vars subparameter and the other from the cross subparameter, in this order) defines a two-way crosstabulation table to produce. So the specification of {vars=’Region’, cross={’Eyes’, ’Hair’}} defines two crosstabulation tables to produce: Region by Eyes and Region by Hair.

The default output from this analysis is presented in Output 11.1.1 through Output 11.1.3.

Output 11.1.1 displays the "Number of Observations" and "Variable Level Information" tables. The "Number of Observations" table indicates that there are 30 observations in the input data and 29 of them are used in the analysis. The last observation is not used in the analysis because the value of the weight variable Count is missing. The "Variable Level Information" table shows the level information for all variables that are defined in the tabulate parameter.

Output 11.1.2 displays the two one-way frequency tables that the freqTab action produces: one showing the frequency distribution of eye color and the other showing the frequency distribution of hair color. By default, the variable values are arranged in ascending order based on their internal (unformatted) values. The frequency of observations that have missing values is displayed following each table.

Output 11.1.3 displays the three crosstabulation tables that the freqTab action produces in CROSSLIST format: Eyes by Hair, which is defined by the specification of {vars={’Eyes’, ’Hair’}}; and Region by Eyes and Region by Hair, which are defined by the specification of {vars=’Region’, cross={’Eyes’, ’Hair’}}. In the crosstabulation of Eyes and Hair, the values of Eyes define the table rows, and the values of Hair define the table columns. In the crosstabulation tables of Region by Eyes and Region by Hair, the values of Region define the table rows, and the values of Eyes and Hair define the table columns, respectively.

The freqTab action also supports displaying crosstabulation tables in LIST format, which presents the entire multiway crosstabulation in a single table. The following code shows how you request crosstabulation tables in LIST format by using the tabDisplay parameter in the freqTab action. Because PROC CAS is an interactive procedure, it is not necessary to resubmit the PROC CAS statement.

   action freqTab.freqTab /
      table='Color',
      weight='Count',
      tabDisplay='LIST',
      tabulate={{vars={'Eyes', 'Hair'}},
                {vars={'Region', 'Eyes', 'Hair'}}
               };
run;

In this case, coercion is used to simplify the specification of the tabDisplay parameter when the optional subparameters are not needed. The uncoerced version of the tabDisplay specification is tabDisplay={format=’LIST’}. If you use coercion, this simplifies to tabDisplay=’LIST’.

Output 11.1.4 shows the two crosstabulation tables in LIST format. Unlike the default CROSSLIST format, in LIST format the crosstabulation tables do not display row percentages and column percentages.

If an observation has a missing value for a variable contained in a term that is defined by the tabulate parameter, by default that observation is not included in the frequency or crosstabulation table. Also by default, observations that have missing values are not included in the computation of percentages and statistics. The freqTab action displays the frequency of observations that have missing values following each frequency or crosstabulation table.

If you want to include in the analysis the observations that have missing values for variables defined in the tabulate parameter, you can specify either the includeMissing parameter or the missingFreq subparameter in the tabDisplay parameter. When you specify the includeMissing parameter, missing values are treated as a valid level for all variables defined in the tabulate parameter and are included in computations of percentages and statistics. When you specify the missingFreq subparameter in the tabDisplay parameter, missing values are presented in one-way frequency tables or crosstabulation tables in LIST format but are not included in computations of percentages or statistics. The following code shows how you can include observations that have missing values in the analysis:

   action freqTab.freqTab /
      table='Color',
      weight='Count',
      tabDisplay='LIST',
      includeMissing=true,
      tabulate={'Eyes', {vars={'Eyes', 'Hair'}}};
run;

   action freqTab.freqTab /
      table='Color',
      weight='Count',
      tabDisplay={format='LIST', missingFreq=true},
      tabulate={'Eyes', {vars={'Eyes', 'Hair'}}};
run;

Output 11.1.5 shows the one-way frequency table and the two-way table in LIST format when you specify the includeMissing parameter. The table displays the missing level, and the freqTab action includes this level when computing frequencies and percentages.

Output 11.1.6 shows the one-way frequency table and the two-way table in LIST format when you specify the missingFreq subparameter in the tabDisplay parameter. The table displays the missing level, but the freqTab action does not include its frequency when computing the total frequency and percentages.

The freqTab action groups a variable’s values according to its formatted values, except for numeric variables for which no explicit format is provided. These numeric variables are grouped by their internal value. As with the LABEL and FORMAT statements that you can use with SAS procedures, you can use the attributes parameter to specify formats and labels for variables in the input CAS table. The freqTab action formats the variable values before grouping observations into the levels of a frequency or crosstabulation table. The following code shows how you can do this:

   action freqTab.freqTab /
      table='Color',
      attributes={{name='Region', format='roman4.', label='European Region'}},
      weight='Count',
      tabulate='Region';
run;

The "Variable Level Information" table and the "One-Way Frequencies" table in Output 11.1.7 show that the freqTab action applies the specified format for the variable Region. The "One-Way Frequencies" table displays both the formatted and unformatted values of the variable Region. By default, the frequency or crosstabulation table lists the values of both character and numeric variables in ascending order based on internal (unformatted) variable values. To list the values in ascending order by formatted values, specify order=’FORMATTED’ in the freqTab action.

Attributes that you specify for a variable in the attributes parameter override those same attributes for that variable in the input data. However, the input data attributes are unchanged after the action completes.

The freqTab action supports a display parameter, which provides functionality that corresponds to that of ODS SELECT, ODS EXCLUDE, and ODS TRACE statements on a SAS client. The major advantage of the action’s display parameter is that you can use it with Lua, Python, and Java clients, for which the ODS system is not available. The following code shows how you can use the traceNames subparameter of the display parameter to obtain the paths of the tables that the freqTab action produces:

   action freqTab.freqTab /
      table='Color',
      weight='Count',
      display={traceNames=true},
      tabulate={'Eyes', 'Hair', {vars={'Region', 'Eyes', 'Hair'}}};
run;

This code produces the following notes in the SAS log:

   NOTE: Name:'NObs' Label:'Number of Observations' Path:'NObs'
   NOTE: Name:'LevelInfo' Label:'Variable Level Information' Path:'LevelInfo'
   NOTE: Name:'OneWayFreqs' Label:'Eye Color' Path:'Table1.OneWayFreqs'
   NOTE: Name:'OneWayFreqs' Label:'Hair Color' Path:'Table2.OneWayFreqs'
   NOTE: Name:'CrossList' Label:'Table of Eyes by Hair Controlling for Region=1'
         Path:'Table1of3.CrossList'
   NOTE: Name:'CrossList' Label:'Table of Eyes by Hair Controlling for Region=2'
         Path:'Table2of3.CrossList'
   NOTE: Name:'Timing' Label:'Task Timing' Path:'Timing'

You can also use the display parameter to select which tables the freqTab action needs to produce and return to the client. The following code uses the display parameter to select the crosstabulation tables:

   action freqTab.freqTab /
      table='Color',
      weight='Count',
      display='CrossList',
      tabulate={'Eyes', 'Hair', {vars={'Region', 'Eyes', 'Hair'}}};
run;

In this case, coercion is used to simplify the specification of the display parameter. The uncoerced version of the display specification is display={names={’CrossList’}}. Specifying full paths is optional—the path-matching rules that the display parameter uses are consistent with rules that the ODS SELECT statement uses. The tables that you request by using the display parameter match all tables whose paths end with the specified path. For example, display={names={’CrossList’}} matches all the following paths: Table1of3.CrossList, Table2of3.CrossList, and ByGroup1.Table1.CrossList.

Output 11.1.8 shows the filtered output that contains only the crosstabulation tables.

If you enclose the strings in the names subparameter of the display parameter within forward slashes, then those strings are treated as Perl regular expressions that are matched against the full paths of the tables that the action produces. For example, display={names={’/Table1/’}} selects the paths Table1.OneWayFreqs and Table1of3.CrossList.

The freqTab action supports a displayOut (outputTables) parameter, which you can use to save any displayed table as a CAS table in the active caslib. This functionality is analogous to the ODS OUTPUT functionality, which saves ODS output as SAS data sets. The following code provides an example of using this parameter:

   action freqTab.freqTab /
      table='Color',
      weight='Count',
      displayOut={names={'NObs', 'OneWayFreqs'}},
      tabulate={'Region', 'Eyes', 'Hair'};
run;

Output 11.1.9 displays the "Output CAS Tables," which provide information about all the CAS tables that the action produces. You see that the preceding code created CAS tables named NObs and OneWayFreqs.

The following PROC PRINT code displays the OneWayFreqs CAS table on the SAS client by using the CAS engine to bring the table back to the SAS client:

 proc print data=mycas.OneWayFreqs;
 run;

Output 11.1.10 shows the contents of the OneWayFreqs CAS table.

Notice that the CAS tables that you request in the displayOut parameter consist of all the tables whose paths end with the specified name, and also notice that grouping variables are added to the CAS table so that you can distinguish among the tables. This behavior matches the behavior of ODS OUTPUT. If you want to see a specific table, you can specify the complete path to the table. Furthermore, you can optionally supply your own name for the CAS table that is created, as illustrated in the following code:

proc cas;
   action freqTab.freqTab /
      table='Color',
      weight='Count',
      displayOut={names={'Table2.OneWayFreqs'='myTable2'}},
      tabulate={'Region', 'Eyes', 'Hair'};
run;

The following PROC PRINT code displays the myTable2 CAS table on the SAS client by using the CAS engine to bring the table back to the SAS client:

  proc print data=mycas.myTable2;
  run;

Output 11.1.11 shows the second one-way frequency table that is saved in the myTable2 CAS table.

You can use the groupBy subparameter of the table parameter to specify BY processing in the freqTab action. Unlike BY processing in SAS procedures, BY processing in the freqTab action does not require the input table to be sorted by the variable or variables that you name in the groupBy subparameter. In the preceding code snippets in this example, the table parameter is specified simply as table=’Color’. This form is the coerced simplification of the general specification of the table parameter when only the name subparameter is needed. You can use a partially coerced form to specify BY processing with a single BY variable, as shown in the following code:

proc cas;
   action freqTab.freqTab /
      table={name='Color', groupBy='Region'},
      weight='Count',
      display={names={'NObs', 'OneWayFreqs'}, traceNames=true},
      tabulate={'Eyes', 'Hair'};
run;

Output 11.1.12 shows the output. You see that the output of the BY group is identified by a title that contains the name and value of the BY variable.

Furthermore, the following notes in the SAS log (which you request by specifying the traceNames subparameter in the display parameter) show that the table paths contain a prefix that identifies the BY-group index:

   NOTE: Name:'NObs' Label:'Number of Observations' Path:'ByGroup1.NObs'
   NOTE: Name:'OneWayFreqs' Label:'Eye Color' Path:'ByGroup1.Table1.OneWayFreqs'
   NOTE: Name:'OneWayFreqs' Label:'Hair Color' Path:'ByGroup1.Table2.OneWayFreqs'
   NOTE: Name:'NObs' Label:'Number of Observations' Path:'ByGroup2.NObs'
   NOTE: Name:'OneWayFreqs' Label:'Eye Color' Path:'ByGroup2.Table1.OneWayFreqs'
   NOTE: Name:'OneWayFreqs' Label:'Hair Color' Path:'ByGroup2.Table2.OneWayFreqs'

In the previous examples, the output of the freqTab action is immediately displayed. If you route the results to a named result, then the output is saved in the named result and is not displayed. The following code shows how you can do this:

   action freqTab.freqTab result=myResult /
      table='Color',
      weight='Count',
      tabulate={'Eyes', 'Hair', {vars={'Region', 'Eyes', 'Hair'}}};
run;

After you run the preceding code, the results of running the freqTab action are stored in the variable named myResult, but no output is displayed. You can display the tables that are stored in myResult by using the PRINT statement in PROC CAS as follows:

   print myResult;
run;

The output of running this PRINT statement is the same as when you run the freqTab action without assigning the results; it is not produced here. You can also display specific tables that are stored in myResult. The following code shows how you can print the crosstabulation tables:

   print myResult['Table1of3.CrossList']
         myResult['Table2of3.CrossList'];
run;

The requested output is not reproduced here but is shown in Output 11.1.8.

For every one-way frequency or crosstabulation table that the freqTab action produces, it saves the frequency of observations that have missing values in the attributes of the result table. The following code shows how you can display the frequency of observations that have missing values for specific one-way frequency or crosstabulation tables:

print myResult['Table1.OneWayFreqs'].attrs['Frequency Missing']
      myResult['Table2.OneWayFreqs'].attrs['Frequency Missing']
      myResult['Table1of3.CrossList'].attrs['Frequency Missing']
      myResult['Table2of3.CrossList'].attrs['Frequency Missing'];
run;

To be able to use the PRINT statement to print specific tables in a stored result, you need to know the paths of those tables in the stored result. One way to get this information is to specify display={traceNames=true} in the freqTab action and obtain the paths of the tables that it produces. Another way to get the paths is to use the DESCRIBE statement in PROC CAS as follows:

    describe myResult;
run;

This displays in the SAS log a dictionary of the tables and the columns in those tables that are stored in myResult. A subset of this dictionary for the "LevelInfo" and "CrossList" tables follows:

   dictionary ( 7 entries, 7 used);
    [LevelInfo] Table ( [3] Rows [4] columns
   Column Names:
    [1] Variable         [Variable        ] (string)
    [2] Label            [Label           ] (string)
    [3] Levels           [Levels          ] (double)
    [4] Values           [Values          ] (string)
    [Table1of3.CrossList] Table[CrossList] ( [22] Rows [9] columns
   Column Names:
    [1] F_Eyes           [Eyes            ] (string)
    [2] Eyes             [Eye Color       ] (string)
    [3] F_Hair           [Hair            ] (string)
    [4] Hair             [Hair Color      ] (string)
    [5] Frequency        [Frequency Count ] (double)
    [6] TotalPercent     [Percent of Total Frequency] (double)
    [7] Percent          [Percent of Two-Way Table Frequency] (double)
    [8] RowPercent       [Percent of Row Frequency] (double)
    [9] ColPercent       [Percent of Column Frequency] (double)

This dictionary contains the paths (such as Table1of3.CrossList) of all tables in myResult. You must use the complete path to request specific tables in the PRINT statement.

The status of each action submission is available in the _status variable, which contains several fields that you can access programmatically. You can display the contents of _status by using the PRINT statement as follows:

   print _status;
run;

For an action that runs without error, this PRINT statement displays the following line in the SAS log:

   {severity=0,reason=0,,statusCode=0}

You can access and print individual fields in the status by using dot notation as follows:

   print _status.severity;
run;

This PRINT statement displays the number 0 (the contents of _status.severity) in the SAS log.

The following code submits the freqTab action but specifies a weight variable that does not exist in the input table (which is an error). It also illustrates how you can assign the status of the action to a variable that you name.

   action freqTab.freqTab status=myStatus /
      table='Color',
      weight='TotalCount',
      tabulate={'Eyes', 'Hair', {vars={'Region', 'Eyes', 'Hair'}}};
run;
   print myStatus;
run;

This code produces the following errors in the SAS log:

   ERROR: The variable TotalCount does not exist in table COLOR.
   ERROR: The action stopped due to errors.

The nature of the error is also saved in the status variable myStatus, which you can display as follows:

    print myStatus;
 run;

This PRINT statement produces the following line in the SAS log:

   {severity=2,reason=6,status=
   The variable TotalCount does not exist in table COLOR.,statusCode=5890022}

For more information about severity and reason codes, see the section "Programming with Severity and Reason Codes" in SAS Viya: System Programming Guide.