Implementation Code

The extension command mechanism requires that the implementation code reside in a function named Run. For the R Source mode used in this example, the code must reside in a file with the same name as the extension command and with any spaces in the command name replaced by underscores. In addition, the file name must be in uppercase and should have a file type of R.

The implementation code for this example can be found in the file SPSSINC_RASCH_DEMO.R, available in the Samples directory (under the installation directory).

Run<-function(args){
   cmdname = args[[1]]
   args <- args[[2]]
   oobj<-spsspkg.Syntax(templ=list(
          spsspkg.Template(kwd="ITEMS",subc="VARIABLES",ktype="existingvarlist",var="items",islist=TRUE),
          spsspkg.Template(kwd="MISSING",subc="OPTIONS",ktype="str",var="missing")
          ))
   if ("HELP" %in% attr(args,"names"))
       spsspkg.helper(cmdname)
   else
       res <- spsspkg.processcmd(oobj,args,"run_rasch")
        
}

IBM® SPSS® Statistics parses the command syntax entered by the user and passes the specified values to the Run function in a single argument--args in this example. The argument is a list structure whose first element is the command name and whose second element is a set of nested lists containing the values specified by the user.

The spsspkg.Syntax, spsspkg.Template, and spsspkg.processcmd functions are designed to work together.

• spsspkg.Template specifies the details needed to process a specified keyword in the syntax for an extension command.
• spsspkg.Syntax validates the values passed to the Run function according to the templates specified for the keywords.
• spsspkg.processcmd parses the values passed to the Run function and calls the function that will actually implement the command. The implementation function resides in the same code file as the Run function and will be covered later in this tutorial.

You call spsspkg.Template once for each keyword supported by the extension command. In this example, the extension command contains the two keywords ITEMS and MISSING, so spsspkg.Template is called twice. The function returns an object, that we'll refer to as a template object, for use with the spsspkg.Syntax function.

The argument kwd to spsspkg.Template specifies the name of the keyword (in uppercase) for which the template is being defined.

The argument subc to spsspkg.Template specifies the name of the subcommand (in uppercase) that contains the keyword.

The argument ktype to spsspkg.Template specifies the type of keyword, such as whether the keyword specifies a variable name, a string, or a floating point number.

• The value existingvarlist for ktype specifies a list of variable names that are validated against the variables in the active dataset. It is used for the ITEMS keyword that specifies the list of variables for the Rasch analysis.
• The value str for ktype specifies a string or quoted literal, or a list of either. It is used for the MISSING keyword. Values specified as str will be converted to lower case.

The argument var to spsspkg.Template specifies the name of an R variable that will be set to the value specified for the keyword. This variable will be passed to the implementation function by the spsspkg.processcmd function.

The optional argument islist to spsspkg.Template is a boolean (TRUE or FALSE) specifying whether the keyword contains a list of values. The default is FALSE. The keyword ITEMS in this example is a list of variable names, so it should be specified with islist=TRUE.

Once you have specified the templates for each of the keywords, you call spsspkg.Syntax with a list of the associated template objects. The returned value from spsspkg.Syntax is passed to the spsspkg.processcmd function.

This example employs the convention of displaying help for the extension command when the submitted syntax contains the /HELP subcommand. The second element of the argument to the Run function has the attribute names, which is a vector of the subcommands specified in the syntax. If the vector contains the string "HELP", then the spsspkg.helper function is called to display a help file without running the Rasch analysis. The help file is an HTML file and must be provided separately. Information on how to deploy the help file is included with the documentation for the spsspkg.helper function.

The spsspkg.processcmd function has three required arguments.

• The first argument is the value returned from the spsspkg.Syntax function.
• The second argument is the nested list structure containing the values specified by the user in the submitted syntax.
• The third argument is the name of the function that will actually implement the extension command--in this example, the function run_rasch.

run_rasch<-function(items, missing="listwise")
{
    tryCatch(library(ltm), error=function(e){
        stop("The R ltm package is required but could not be loaded.",call.=FALSE)
        }
    )

    if (identical(missing,"listwise")) {missing<-na.exclude} else {missing<-NULL}
    
    dta<-spssdata.GetDataFromSPSS(items,missingValueToNA=TRUE)

    res <- tryCatch(
            summary(fit<-rasch(data=dta,na.action=missing)),
            error=function(e) {return(c("ERROR:",e))}
           )
      
    if (!is.null(res$message)) {print(res$message)} else {
        miss<-ifelse(identical(missing,na.exclude),"na.exclude","NULL")
        spsspkg.StartProcedure("Rasch Model")
        spsspivottable.Display(res$coefficients, 
            title="Coefficients",
            templateName="SPSSINCRasch",
            caption=paste("rasch(data = dta, na.action = ",miss,")",sep=""),
            isSplit=FALSE)
        spsspkg.EndProcedure()
    }

    res <- tryCatch(rm(list=ls()),warning=function(e){return(NULL)})
    
}

The spsspkg.processcmd function calls the specified implementation function with a set of named arguments, one for each template object. The names of the arguments are the values of the var arguments specified for the associated template objects. The values of the arguments are the values of the associated keywords from the syntax.

For example, the user might specify the following syntax for the SPSSINC RASCH DEMO command:

SPSSINC RASCH DEMO
/VARIABLES ITEMS=var1 var2
/OPTIONS MISSING=LISTWISE.

The function run_rasch will be called with the following signature:

run_rasch(
   items=list(var1,var2),
   missing="listwise")

This means that named arguments in the implementation function (such as missing in this example) must match the names specified in the associated template objects.

The IBM SPSS Statistics - Integration Plug-in for R provides functions to read data from the active dataset and write results back to IBM SPSS Statistics. In this example, the spssdata.GetDataFromSPSS function is used to read data for the variables specified on the ITEMS keyword in the submitted syntax. The setting missingValueToNA=TRUE specifies that missing values of numeric variables will be returned as the R NA value (by default, they are returned as the R NaN value).

You group output under a common heading using a spsspkg.StartProcedure-spsspkg.EndProcedure block as shown in this example. The argument to spsspkg.StartProcedure specifies the name that appears in the outline pane of the Viewer associated with the output. In this example, the output is a pivot table created with the spsspivottable.Display function. The first argument to this function is the data to be displayed as a pivot table. It can be a data frame, matrix, table, or any R object that can be converted to a data frame. Here, it is the matrix of coefficients from the R rasch function.