spss.BaseProcedure Class (Python)

The spss.BaseProcedure class is used to create classes that encapsulate procedures. Procedures can read the data, perform computations, add new variables and/or new cases to the active dataset, and produce pivot table output and text blocks in the IBM® SPSS® Statistics Viewer. Procedures have almost the same capabilities as built-in IBM SPSS Statistics procedures, such as DESCRIPTIVES and REGRESSION, but they are written in Python by users. Use of the spss.BaseProcedure class provides an alternative to encapsulating procedure code within a Python function and explicitly using an spss.StartProcedure-spss.EndProcedure block for the procedure output. All classes that encapsulate procedures must inherit from the BaseProcedure class.

The spss.BaseProcedure class has three methods: __init__, execProcedure, and execUserProcedure. When creating procedure classes you always override the execUserProcedure method, replacing it with the body of your procedure. You override the __init__ method if you need to provide arguments other than the procedure name and the optional OMS identifier. You never override the execProcedure method. It is responsible for calling execUserProcedure to run your procedure as well as automatically making the necessary calls to spss.StartProcedure and spss.EndProcedure.

The rules governing procedure code contained within the execUserProcedure method are the same as those for StartProcedure-EndProcedure blocks. See the topic spss.StartProcedure Function (Python) for more information.

Example

As an example, we will create a procedure class that calculates group means for a selected variable using a specified categorical variable to define the groups. The output of the procedure is a pivot table displaying the group means. For an alternative approach to creating the same procedure, but making explicit use of spss.StartProcedure-spss.EndProcedure and without the use of the BaseProcedure class, see the example for the spss.StartProcedure function.

class groupMeans(spss.BaseProcedure):

    #Overrides __init__ method to pass arguments
    def __init__(self, procName, groupVar, sumVar):
        self.procName = procName
        self.omsIdentifier = ""
        self.groupVar = groupVar
        self.sumVar = sumVar

    #Overrides execUserProcedure method of BaseProcedure
    def execUserProcedure(self):
        #Determine variable indexes from variable names
        varCount = spss.GetVariableCount()
        groupIndex = 0
        sumIndex = 0
        for i in range(varCount):
            varName = spss.GetVariableName(i)
            if varName == self.groupVar:
                groupIndex = i
                continue
            elif varName == self.sumVar:
                sumIndex = i
                continue
                
        varIndex = [groupIndex,sumIndex]
        cur = spss.Cursor(varIndex)
        Counts={};Totals={}
    
        #Calculate group sums
        for i in range(cur.GetCaseCount()):
            row = cur.fetchone()
            cat=int(row[0])
            Counts[cat]=Counts.get(cat,0) + 1
            Totals[cat]=Totals.get(cat,0) + row[1]

        cur.close()
    
        #Create a pivot table
        table = spss.BasePivotTable("Group Means",
                                    "OMS table subtype")
        table.Append(spss.Dimension.Place.row,
                     spss.GetVariableLabel(groupIndex))
        table.Append(spss.Dimension.Place.column,
                     spss.GetVariableLabel(sumIndex))

        category2 = spss.CellText.String("Mean")
        for cat in sorted(Counts):
            category1 = spss.CellText.Number(cat)
            table[(category1,category2)] = \
                   spss.CellText.Number(Totals[cat]/Counts[cat])

• groupMeans is a class based on the spss.BaseProcedure class.
• The procedure defined by the class requires two arguments, the name of the grouping variable (groupVar) and the name of the variable for which group means are desired (sumVar). Passing these values requires overriding the __init__ method of spss.BaseProcedure. The values of the parameters are stored to the properties groupVar and sumVar of the class instance.
• The value passed in as the procedure name is stored to the procName property. The spss.BaseProcedure class allows for an optional omsIdentifier property that specifies the command name associated with output from this procedure when routing the output with OMS (Output Management System), as used in the COMMANDS keyword of the OMS command. If omsIdentifier is an empty string then the value of procName is used as the OMS identifier. Although specifying a non-blank value of the omsIdentifier property is optional, the property itself must be included.

  Note:

• The body of the procedure is contained within the execUserProcedure method, which overrides that method in spss.BaseProcedure. The procedure reads the data to calculate group sums and group case counts and creates a pivot table populated with the group means.
• The necessary calls to spss.StartProcedure and spss.EndProcedure are handled by spss.BaseProcedure.

Saving and Running Procedure Classes

Once you have written a procedure class, you will want to save it in a Python module on the Python search path so that you can call it. A Python module is simply a text file containing Python definitions and statements. You can create a module with a Python IDE, or with any text editor, by saving a file with an extension of .py. The name of the file, without the .py extension, is then the name of the module. You can have many classes in a single module. To be sure that Python can find your new module, you may want to save it to your Python "site-packages" directory, typically /Python310/Lib/site-packages.

For the example procedure class described above, you might choose to save the class definition to a Python module named myprocs.py. And be sure to include an import spss statement in the module. Sample command syntax to instantiate this class and run the procedure is:

import spss, myprocs
spss.Submit("GET FILE='/examples/data/Employee data.sav'.")
proc = myprocs.groupMeans("mycompany.com.groupMeans","educ","salary")
proc.execProcedure()

• The import statement containing myprocs makes the contents of the Python module myprocs.py available to the current session (assuming that the module is on the Python search path).
• The call to myprocs.groupMeans creates an instance of the groupMeans class. The variables educ and salary in /examples/data/Employee data.sav are used as the grouping variable and the variable for which means are calculated.
• Output from the procedure is associated with the name mycompany.com.groupMeans. This is the name that appears in the outline pane of the Viewer associated with output produced by the procedure. It is also the command name associated with this procedure when routing output from this procedure with OMS (Output Management System). In order that names associated with procedure output not conflict with names of existing IBM SPSS Statistics commands (when working with OMS), it is recommended that they have the form yourcompanyname.com.procedurename. See the topic spss.StartProcedure Function (Python) for more information.

Result