Regression Action Set

The following DATA step runs on the CAS server and creates the data table mycas.sample, which contains 20 observations and eight variables. This DATA step assumes that your CAS engine libref is named mycas and your CAS session is named mysess, but you can substitute any appropriately defined CAS engine libref and session name.

The DATA step forms the response y by using a random number generator. The variable x is used as a continuous regressor, and the variable c is used as a classification variable.

data mycas.sample / sessref=mysess single=yes;
    call streamInit(1);
    do byVar=1 to 2;
      do i=1 to 10;
               if byVar=1 then c=rand("Integer",0,3);
         else  if byVar=2 then c=rand("Integer",0,1);
         x=rand("Normal");
         y=1;
         wgt=1;
         if i=5 and byVar=2 then frq  = -1; else frq=1;
         index + 1;
         output;
      end;
    end;
run;

The preceding DATA step generates a data table (sample) that has 20 observations. It contains two continuous variables (x and y) and a single classification variable (c), which can have a maximum of four unique values for 10 observations and a maximum of two unique values for the rest of the observations. Also, a BY variable named byVar is defined that divides the data table into two equally sized BY groups, each of which has 10 observations. Also included are the frq and wgt variables that are used as frequency and weight variables, respectively. For simplicity, all the weight variable values are assigned to 1. The same applies to the frequency variable, with the exception of the observation whose index value is 15, which has an invalid frequency variable value (that is, –1). This invalid frequency variable value demonstrates how the modelMatrix action treats observations that have invalid frequency variable values.

In the following sections, a simple model definition is presented first, followed by more complex statements to highlight the key features of the modelMatrix action. The preceding simulated data table (sample) is used in the use cases that are presented.

The following code shows how you can specify a model definition by using the model parameter in the modelMatrix action:

   regression.modelMatrix  /
      table='sample',
      class={'/c/'},
      model={ depVar='y',
              effects={'/c/','x'}
            },
      outDesign={casOut='designMat',
                 prefix='param'
                };
   run;

The specified model is a linear combination of the main effects, x; all levels of c; and the interaction effect, x*c.

The outDesign parameter is required in the modelMatrix action. The following three subparameters are defined for the outDesign parameter:

The casOut subparameter defines the name of the design matrix and is required. The prefix subparameter accepts a valid SAS prefix (and replaces the default prefix Col) and is optional. The specified prefix, appended to a one-based index, forms the column names of the design matrix. The copyVars subparameter appends some or all of the variables of the input data table to the design matrix. By default, no input variable is appended to the design matrix.

You can use Perl regular expressions to specify sets of variables in all the variable lists that you can specify in the class and model parameters.

Alternatively, the modelMatrix action supports the machine-learning syntax mode for model specification. For examples of this syntax, see Model Selection with Validation.

In the previous code example, the output of the modelMatrix action is immediately displayed. If you assign the results to a named result object, then the output is saved in that result object and is not displayed. The following code shows how you can perform this task:

   regression.modelMatrix  result=myresult /
      table='sample',
      class={'/c/'},
      model={ depVar='y',
              effects={'/c/','x'}
            },
      outDesign={casOut={name='designMat',
                         replace='True'
                        },
                 prefix='param'
                };
   run;

After you run the preceding code, the results of running the modelMatrix action are stored in the result object named myresult, but no output is displayed. You can display the tables that are stored in the myresult object 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 modelMatrix action without assigning the results; it is not shown here. You can also display specific tables that are stored in the myresult object. The following code shows how you can print the "Number of Observations" table:

   print myresult['NObs'];
   run;

The output is shown in Output 20.14.1.

In order to use the PRINT statement to print specific tables in a stored result object, you need to know the paths of those tables in the stored result object. One way you can get this information is to specify the ODS TRACE ON command and then print the entire result. Another way to get the paths is to use the DESCRIBE statement in PROC CAS as follows:

   describe myresult;
   run;

This displays a dictionary of the tables in the SAS log and the columns in those tables that are stored in the myresult object. A subset of this dictionary for the "ModelInfo" table follows:

  dictionary ( 5 entries, 5 used);
   [ModelInfo] Table ( [2] Rows [3] columns
  Column Names:
   [1] RowId            [Name            ] (varchar)
   [2] Description      [Description     ] (varchar)
   [3] Value            [Value           ] (varchar)

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

The modelMatrix action supports a display parameter, which provides functionality that corresponds to that of the ODS SELECT, ODS EXCLUDE, and ODS TRACE statements on a SAS client. The major advantage of using the action’s display parameter is that you can use it with Lua, Python, and Java clients, where 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 modelMatrix action produces:

   regression.modelMatrix  result=myresult /
      table='sample',
      class={'/c/'},
      model={ depVar='y',
              effects={'/c/','x'}
            },
      outDesign={casOut={name='designMat',
                         replace='True'
                        },
                 prefix='param'
                },
      display={traceNames=true};
   run;

This code produces the following notes in the SAS log:

   NOTE: Name:'OutDesignInfo' Label:'Design Matrix Column Information'
         Path:'OutDesignInfo'
   NOTE: Name:'ModelInfo' Label:'Model Information' Path:'ModelInfo'
   NOTE: Name:'NObs' Label:'Number of Observations' Path:'NObs'
   NOTE: Name:'Dimensions' Label:'Dimensions' Path:'Dimensions'
   NOTE: Name:'ClassInfo' Label:'Class Level Information' Path:'ClassInfo'

You can also use the display parameter to select which tables the modelMatrix action produces are returned to the client. The following code uses the display parameter to select the "OutDesignInfo" and "NObs" tables:

   regression.modelMatrix /
      table='sample',
      class={'/c/'},
      model={ depVar='y',
              effects={'/c/','x'}
            },
      outDesign={casOut={name='designMat',
                         replace='True'
                        },
                 prefix='param'
                },
      display={names={'OutDesignInfo','NObs'}};
   run;

Specifying full paths is optional—the path-matching rules that the display parameter uses are consistent with the rules that the ODS SELECT statement uses. The tables that you request by using the display parameter match all tables whose pathnames end with the specified path. For example, display={names={"NObs"}} matches all the paths NObs, BYGroup1.SelectedModel.NObs, and so on.

Figure 1 shows the filtered output that contains only the "Design Matrix Column Information" and "Number of Observations" tables.

If you enclose the strings in the names subparameter of the display parameter in 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={’/NObs/’}} selects the paths BYGroup1.NObs and BYGroup2.NObs.

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

   regression.modelMatrix /
      table='sample',
      class={'/c/'},
      model={ depVar='y',
              effects={'/c/','x'}
            },
      outDesign={casOut={name='designMat',
                         replace='True'
                        },
                 prefix='param'
                },
      outputTables={names={'OutDesignInfo', 'NObs'}};
   run;

Output 20.14.2 displays the output CAS tables, which provide information about all the CAS tables that the action produces. You see that the preceding code creates CAS tables named "OutDesignInfo" and "NObs."

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

   proc print data=mycas.NObs;
   run;

Output 20.14.3 shows contents of the "NObs" CAS table.

The CAS tables that you request in the outputTables parameter consist of all the tables whose paths end with the specified name. Grouping variables are added to the CAS table so that you can distinguish between the tables.

You can use the outDesign parameter to create an output CAS table that contains the design matrix of the defined model. The outDesign parameter is required in the modelMatrix action. The variables in the input data table are not included in the output data table in order to avoid data duplication for large data tables; however, variables that you specify in the copyVars subparameter are included. If you specify strings enclosed in forward slashes in the copyVars subparameter, they are interpreted as Perl regular expressions.

The following code demonstrates several features of the modelMatrix action. It shows the use of interaction and spline effects in a model parameter. It also shows how the action performs BY-group processing for a particular model. The same data table (mycas.sample) that is defined at the beginning of this section is used here.

   regression.modelMatrix  /
      table={name='sample', groupBy='byVar'},
      nThreads=1,
      class  = {'c'},
      spline = {{name='spl',vars={'x'}}},
      model ={
             depVar={'y'},
             effects={'x','c','spl',
                      {vars={'x','c'}, interact='CROSS'}
                     }
             },
     freq   = 'frq',
     weight = 'wgt',
     outDesign={casOut={name='designMat',
                        replace='True'
                       },
                prefix  ='param',
                copyVars={'c', 'frq', 'index'}
               };
   run;

The preceding statements create a model that contains the continuous variable x and the classification variable c. The model includes the variable x, individual levels of the variable c, a spline effect on the variable x, and the cross interaction of the variables x and c (x*c). BY-group processing is performed on the basis of the variable byVar in the data table.

The preceding lines of code use the following additional parameters:

Several output tables are displayed consecutively. They are shown in Output 20.14.4 through Output 20.14.6.

The "Column Names of the Design Matrix" table in Output 20.14.4 shows that the defined model creates a total of 17 parameters across the two BY groups. Therefore, the design matrix has 17+3 columns (the additional columns are reserved for the variables c, frq, and index that are appended to the design matrix by using the copyVars keyword).

Apart from the intercept, x as a continuous variable is considered directly in the model. However, because c is defined as a classification variable, all of its unique values (0–3) are considered as separate parameters (a total of four). You can see that the included spline effect adds seven more parameters to the model. Finally, the interaction of x and c () adds four more parameters to the model because of the interaction of the continuous x with all four levels of c.

Also displayed in Output 20.14.4 is the "Model Information" table, which shows a brief summary of the response variable and the frequency and weight variables.

The rest of the output tables are dependent on the BY group and hence are produced separately. They are shown in Output 20.14.5 and Output 20.14.6.

For each BY group, the modelMatrix action displays the number of observations that are read and used. Because the frequency and weight variables are defined, the action displays the number of frequency variables that are read and used and the sum of the weight variables. You can see that BY group 2 (Output 20.14.5) has one invalid observation (the observation whose index value is 15). Therefore, the number of used frequency variables is nine; this is different from BY group 1, in which all frequency variables have a value of 1.

The "Dimensions" table shows the number of effects and parameters that are considered within each BY group. Notice that the number of considered effects for both BY groups is five. However, neither BY group includes all the parameters listed in the OutDesignInfo table; so, for all BY groups, the number of parameters is less than 17.

This fact can be seen in the "Class Level Information" tables shown in Output 20.14.5 and Output 20.14.6. These tables show the levelization of the classification variables within each BY group (in this case only c is defined as a classification variable). You can see that none of the BY groups include all levels of the c (that is, 0, 1, 2 and 3) which is why the number of parameters is less than 17 for all BY groups.

The modelMatrix action constructs a global design matrix. Therefore, it constructs a table that includes the union of all parameters in each BY group. To inspect the design matrix that resides on the CAS server as a CAS table, you can transfer the constructed table with 20 rows to the client by using the following statements:

data designMat;
  set mycas.designMat;
run;

proc print data=designMat;
  format BEST 5. param1-param17;
  var index c frq param1-param7 param17;
  where
    (index < 11) or
    (index = 15);
run;

Output 20.14.7 displays rows of the design matrix whose index value is 1–10 and the row whose index is 15. Only the index, c, frq, param1–param7, and param17 variables are shown. As expected, the generated data table contains 20 rows associated with each observation and 20 columns (17 parameters plus three columns for input variable c, frq, and index). You can see that the column names are param1 through param17, based on the specified prefix subparameter in the outDesign parameter.

The OutDesignInfo table lists the model parameters along with their corresponding column names in the design matrix. Columns param3 through param6 contain all levels of the c variable. The rows in the design matrix whose index value is less than 11 belong to the first BY group (byVar value of 1), and according to the ClassInfo table, level does not exist in either BY group. This observation can be confirmed by the fact that the param6 and param17 columns of the design matrix (which are associated with the and parameters, respectively) are empty.

You can also see that the row of the design matrix whose index value is 15 is all blanks. This is because the defined frequency variable value for this observation is invalid and equal to –1 (see the frq column in the design matrix), and therefore this observation is not considered when the design matrix is created.