Código de implementación

El mecanismo del comando de extensión requiere que el código de implementación resida en una función llamada Run. En el modo de origen R Source utilizado en este ejemplo, el código debe residir en un archivo con el mismo nombre que el comando de extensión y con espacios en el nombre del comando sustituidos por caracteres de subrayado. Además, el nombre de archivo debe estar en mayúsculas y debe tener un tipo de archivo de R.

El código de implementación de este ejemplo se puede encontrar en el archivo SPSSINC_RASCH_DEMO.R, disponible en el directorio Samples (bajo el directorio de instalación).

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 analiza la sintaxis del mandato especificada por el usuario y pasa los valores especificados a la función Run en un único argumento --args en este ejemplo. El argumento es una estructura de lista cuyo primer elemento es el nombre de mandato y cuyo segundo elemento es un conjunto de listas anidadas que contienen los valores especificados por el usuario.

Las funciones spsspkg.Syntax, spsspkg.Template y spsspkg.processcmd están diseñadas para utilizarse conjuntamente.

• spsspkg.Template especifica los detalles necesarios para procesar una palabra clave especificada en la sintaxis para un comando de extensión.
• spsspkg.Syntax valida los valores pasados a la función Run de acuerdo con las plantillas especificadas por las palabras clave.
• spsspkg.processcmd analiza los valores pasados a la función Run y activa la función que implementará el comando. La función de implementación reside en el mismo archivo de código que la función Run y se tratará posteriormente en este tutorial.

Activará spsspkg.Template por cada palabra clave que admite el comando de extensión. En este ejemplo, el mandato de extensión contiene las dos palabras clave ITEMS y MISSING, por lo que spsspkg.Template se llama dos veces. La función devuelve un objeto, que denominaremos objeto de plantilla, para utilizarlo con la función spsspkg.Syntax.

El argumento kwd de spsspkg.Template especifica el nombre de una palabra clave (en mayúsculas) cuya plantilla se está definiendo.

El argumento subc de spsspkg.Template especifica el nombre del subcomando (en mayúsculas) que contiene la palabra clave.

El argumento ktype de spsspkg.Template especifica el tipo de palabra clave, como si la palabra clave especifica un nombre de variable, una cadena o un número de punto flotante.

• El valor existingvarlist de ktype especifica una lista de nombres de listvariable que se validan con las variables del conjunto de datos activos. Se utiliza para la palabra clave ITEMS que especifica la lista de variables para el análisis Rasch.
• El valor str de ktype especifica un cadena o un literal entre comillas, o una lista de ambos. Se utiliza para la palabra clave MISSING . Los valores especificados como str se convertirán a minúsculas.

El argumento var de spsspkg.Template especifica el nombre de una variable de R que se definirá al valor especificado de la palabra clave. Esta variable se pasará para la función de implementación por la función spsspkg.processcmd.

El argumento opcional islist de spsspkg.Template es un booleano (VERDADERO o FALSO) que especifica si la palabra clave contiene una lista de valores. El valor predeterminado es FALSE. La palabra clave ITEMS en este ejemplo es una lista de nombres de variable, por lo que se debe especificar con islist = TRUE.

Cuando haya especificado las plantillas de cada una de las palabras clave, activará spsspkg.Syntax con una lista de los objetos de plantilla asociada. El valor devuelto de spsspkg.Syntax se pasa a la función spsspkg.processcmd.

Este ejemplo utiliza el convenio de visualización de ayuda para el mandato de extensión cuando la sintaxis enviada contiene el submandato /HELP . El segundo elemento del argumento de la función Run tiene el atributo names, que es un vector de los subcomandos especificados en la sintaxis. Si el vector contiene la cadena "AYUDA", se llama a la función spsspkg.helper para mostrar un archivo de ayudad sin ejecutar el análisis Rasch. El archivo de ayuda es un archivo HTML y se debe proporcionar de forma independiente. La información sobre cómo desplegar el archivo de ayuda se incluye en la documentación de la función spsspkg.helper.

La función spsspkg.processcmd tiene tres argumentos obligatorios.

• El primer argumento es el valor devuelto desde la función spsspkg.Syntax.
• El segundo argumento es la estructura de lista anidada que contiene los valores especificados por el usuario en la sintaxis enviada.
• El tercer argumento es el nombre de la función que implementará el comando de extensión, en este ejemplo, la función 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)})
    
}

La función spsspkg.processcmd activa la función de implementación especificada con un conjunto de argumentos nombrados, uno para cada objeto de plantilla. Los nombres de los argumentos son los valores de los argumentos var especificados para los objetos de plantillas asociados. Los valores de los argumentos son los valores de las palabras clave asociadas a partir de la sintaxis.

Por ejemplo, el usuario puede especificar la siguiente sintaxis para el mandato SPSSINC RASCH DEMO:

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

La función run_rasch se activará con la siguiente firma:

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

Esto significa que los argumentos nombrados en la función de implementación (como por ejemplo missing en este ejemplo) deben coincidir con los nombres especificados en los objetos de plantilla asociados.

IBM SPSS Statistics -Integration Plug-in for R proporciona funciones para leer datos del conjunto de datos activo y volver a escribir los resultados en IBM SPSS Statistics. En este ejemplo, la función spssdata.GetDataFromSPSS se utiliza para leer las variables especificadas en la palabra clave ITEMS en la sintaxis enviada. El ajuste missingValueToNA=TRUE especifica que los valores perdidos de las variables numéricas se devolverán como el valor R NA (de forma predeterminada, se devolverán como el valor R NaN).

Agrupará los resultados en un encabezado común utilizando un bloque spsspkg.StartProcedure-spsspkg.EndProcedure tal y como se muestra en este ejemplo. El argumento de spsspkg.StartProcedure especifica el nombre que aparece en el panel de titulares del Visor asociado con los resultados. En este ejemplo, el resultado es una tabla dinámica creada con la función spsspivottable.Display. El primer argumento de esta función es que los datos se mostrarán como una tabla dinámica. Puede ser un marco de datos, matriz, tabla o cualquier objeto R que se puede convertir a un marco de datos. En este caso, es la matriz de coeficientes de la función rasch de R.