spss.StartProcedure Function (Python)
spss.StartProcedure(procedureName,omsIdentifier). Signals
the beginning of pivot table or text block output. Pivot table
and text block output is typically associated with procedures. Procedures
are user-defined Python functions or custom Python classes that can
read the data, perform computations, add new variables and/or new
cases to the active dataset, create new datasets, 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. You read the data and create
new variables and/or new cases in the active dataset using the Cursor class,
or create new datasets with the Dataset class.
Pivot tables are created using the BasePivotTable class. Text blocks are created
using the TextBlock class.
- The argument procedureName is a string and is the name
that appears in the outline pane of the Viewer associated with the
output. If the optional argument omsIdentifier is omitted,
then procedureName is also the command name associated with
this output when routing it with OMS (Output Management System), as
used in the
COMMANDS
keyword of theOMS
command. - The optional argument omsIdentifier is a string and is
the command name associated with this output when routing it with
OMS (Output Management System), as used in the
COMMANDS
keyword of theOMS
command. If omsIdentifier is omitted, then the value of the procedureName argument is used as the OMS identifier. omsIdentifier is only necessary when creating procedures with localized output so that the procedure name can be localized but not the OMS identifier. See the topic Localizing Output from Python Programs for more information. - In order that names associated with 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.
- Within a
StartProcedure-EndProcedure
block you cannot use thespss.Submit
function. You cannot nestStartProcedure-EndProcedure
blocks. - Within a
StartProcedure-EndProcedure
block, you can create a single cursor instance. - Instances of the
Dataset
class created withinStartProcedure-EndProcedure
blocks cannot be set as the active dataset. - Output from
StartProcedure-EndProcedure
blocks does not support operations involving data in different split groups. When working with splits, each split should be treated as a separate set of data. To cause results from different split groups to display properly in custom pivot tables, use the SplitChange function. Use the IsEndSplit method from theCursor
class to determine a split change. -
spss.StartProcedure
must be followed by spss.EndProcedure.Note: You can use the
spss.Procedure
class to implicitly start and end a procedure without the need to callStartProcedure
andEndProcedure
. See the topic spss.Procedure Class (Python) for more information.
Example
As an example, we will create a procedure 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 with a custom class, see the example for the spss.BaseProcedure class.
def groupMeans(groupVar,sumVar):
#Determine variable indexes from variable names
varCount = spss.GetVariableCount()
groupIndex = 0
sumIndex = 0
for i in range(varCount):
varName = spss.GetVariableName(i)
if varName == groupVar:
groupIndex = i
continue
elif varName == sumVar:
sumIndex = i
continue
varIndex = [groupIndex,sumIndex]
cur = spss.Cursor(varIndex)
Counts={};Statistic={}
#Calculate group sums
for i in range(cur.GetCaseCount()):
row = cur.fetchone()
cat=int(row[0])
Counts[cat]=Counts.get(cat,0) + 1
Statistic[cat]=Statistic.get(cat,0) + row[1]
cur.close()
#Call StartProcedure
spss.StartProcedure("mycompany.com.groupMeans")
#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(Statistic[cat]/Counts[cat])
#Call EndProcedure
spss.EndProcedure()
-
groupMeans
is a Python user-defined function containing the procedure that calculates the group means. - The arguments required by the procedure are the names of the grouping variable (groupVar) and the variable for which group means are desired (sumVar).
- The name associated with output from this procedure is mycompany.com.groupMeans. The output consists of a pivot table populated with the group means.
-
spss.EndProcedure
marks the end of output creation.
Saving and Running Procedures
To use a procedure you have written, you 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 functions 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 described above, you might choose to
save the definition of the groupMeans
function to
a Python module named myprocs.py. And be sure to include an import
spss
statement in the module. Sample command syntax to run
the function is:
import spss, myprocs
spss.Submit("get file='/examples/data/Employee data.sav'.")
myprocs.groupMeans("educ","salary")
- 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). -
myprocs.groupMeans("educ","salary")
runs thegroupMeans
function for the variables educ and salary in /examples/data/Employee data.sav.
Result
