‹‹ Back to SVS Home
5.6 Scripting Reference
5.6 Scripting Reference
5.6.1 Project Related Commands
5.6.1.1 Creating a New Project
To create a new project that can later be viewed in GUI mode, use the following command. Once you create a project, all new Optimus RP objects will be added to the project as if you were doing the same operations in GUI mode.
EXAMPLE
ghi.newProject(’Discovery’, ’/projects’ )
SYNTAX
ghi.newProject(project name, project path)
Note that the ’project path’ must be an existing folder on your file system and ’project name’ will be a new folder in the ’project path’ directory.
5.6.1.2 Creating a Temporary Project
To create a temporary project, use the following command. Projects created with this command will not be saved to disk, and will not be available once the script has completed. This command cannot be used in GUI mode.
Note: Projects created with this command cannot be saved using the saveProject() command.
EXAMPLE
ghi.newTempProject()
SYNTAX
ghi.newTempProject()
5.6.1.3 Open an Existing Project
To open a project previously created in either GUI mode or script mode use this command.
EXAMPLE
ghi.openProject(’/projects/Discovery/Discovery.ghp’)
SYNTAX
ghi.openProject(path and name of project)
5.6.1.4 Saving a Project
When you are at a point in your workflow where you want to save the state of the current project use this command.
EXAMPLE
ghi.saveProject()
SYNTAX
ghi.saveProject()
5.6.1.5 Closing a Project
The following command will close the current project without saving the state of the project first. If you want to save the project state first use the saveProject() command.
EXAMPLE
ghi.closeProject()
SYNTAX
ghi.closeProject()
5.6.2 General GHI Commands
5.6.2.1 Allowing Viewers to Display
There may be times when you are running a script and you do not want to see viewers, such as progress dialogs, during the running of script commands. The following command will either suppress or allow the display of GUI viewers while executing scripts. Note that you can turn viewers on and off at any time while running a script, and this command only affects scripts that are run from the Scripts menu of a viewer. If viewers are turned off in a script, they will be turned on again upon completion of the script so that new scripts will always start with viewers turned on.
There are two possible settings: 0 = false, 1 = true.
EXAMPLE
ghi.enableNewViewers(1)
SYNTAX
ghi.enableNewViewers(viewer setting)
5.6.2.2 Allowing Log Messages to Be Created
There might be times when you do not want to have logging take place during the execution of script commands, but other times when you do want logging. The following command will either suppress or allow the logging of actions while executing scripts. Note that you can turn logging on and off at any time while running a script.
There are two possible settings: 0 = false, 1 = true.
EXAMPLE
ghi.enableLogging(1)
SYNTAX
ghi.enableLogging(logging setting)
5.6.2.3 Display a GUI Message
Sometimes you may want to pop up a GUI based message to report status or other information. This command will take the text parameter and display it in a standard message dialog.
EXAMPLE
ghi.message("my important message")
SYNTAX
ghi.message(message string)
5.6.2.4 Display a GUI Error Message
When you create a script that uses try/except syntax, you can put this command in the except clause and any exception message will be displayed in a GUI error dialog.
EXAMPLE
ghi.error()
SYNTAX
ghi.error()
5.6.2.5 Getting a Specific Navigator Node
When you know a navigator node display name or a navigator node ID, you can retrieve an object representing that navigator node. The following command takes either an integer for the node ID or a string for the node name. When asking for a navigator node by ID a single object is returned. When asking for a navigator node by name a list of objects is returned because names are not guaranteed to be unique.
EXAMPLE
myList = ghi.getObject(’name’)
SYNTAX
object list = ghi.getObject(navigator node display name)
EXAMPLE
myObject = ghi.getObject(ID)
SYNTAX
object variable = ghi.getObject(navigator node ID)
5.6.2.6 Getting the Current Navigator Node
Another way to get access to navigator nodes is to ask for the currently highlighted node. If no node is highlighted an error will be displayed. Otherwise, an object representing the current node will be returned.
EXAMPLE
myObject = ghi.getCurrentObject()
SYNTAX
object variable = ghi.getCurrentObject()
5.6.2.7 Choosing a File
This method will display a dialog window for browsing and selecting a file(s). If a file(s) is selected then a tuple with the complete path to the file(s) is returned. If the dialog is canceled then an empty tuple is returned. There are two required parameters. The first parameter defines a file extension mask. For example, if you pass in "*.txt" the dialog will only display files that have the .txt extension. The second parameter is the title to be displayed in the dialog’s title bar. The third argument is optional. If you put 1 for the third arguement the the file chooser will allow multiple files to be selected. If the third argument is omitted or anything but a one is set the the chooser will default to selecting only a single file. This command returns the file path(s) as a list.
EXAMPLE
myFilePaths = ghi.chooseFile("*.txt", "Choose A File Please", 1)
SYNTAX
file path list = ghi.chooseFile(file extension mask, dialog title, [allow multiple selection])
5.6.2.8 Choosing a Directory
The following method can be used to create a file browser for browsing to and selecting directories. This method has one required parameter and one optional parameter. The first parameter is the title to be displayed in the dialog’s title bar. The second parameter is optional and specifies the initial working directory of the browser. If this parameter is omitted, then the Optimus RP application directory will be used as the initial working directory. If the dialog is cancelled, an empty string will be returned. Otherwise, the path of the selected directory will be returned.
EXAMPLE
myDirectory = ghi.chooseDirectory("Choose a Directory Please", "C:/Optimus RP/example" )
SYNTAX
directory path = ghi.chooseDirectory(dialog title, [initial working directory])
5.6.2.9 Creating a Progress Bar
This method will create a progress bar which can be used to display the progress of a certain task and to signal the cancellation of a process. There are two required arguments for this method. The first argument specifies the text to be displayed on the progress bar. The second argument defines the number of progress increments for the progress bar. An object for the progress bar will be returned.
EXAMPLE
myProgressBar = ghi.progressBar(“Please Wait”, 100)
SYNTAX
progress bar object = ghi.progressBar(dialog caption, total number of progress increments )
5.6.2.10 Setting the Progress Bar’s Progress
The following method allows you to set the progress displayed by the progress bar to the value passed in. This value will be displayed on the progress bar as a percentage based on the proportion of the specified progress to the total number or progress increments. For example, if a progress bar is defined as having 50 progress increments, setting the progress to 10 will cause the progress bar to display 20 percent completion.
EXAMPLE
myProgressBar.setProgress(10)
SYNTAX
progress bar object.setProgress(progress value)
5.6.2.11 Checking if the Progress Bar Has Been Cancelled
The following method allows you to check if a user has pressed the cancel button on the progress bar. This information may prove useful when trying to determine whether to stop a process prior to it’s completion. If the progress bar has been cancelled the method returns 1. Otherwise, the method returns 0.
EXAMPLE
myProgressBar.wasCancelled()
SYNTAX
integer variable = progress bar object.wasCancelled()
5.6.2.12 Disposing of a Progress Bar When Done
It is good practice to make sure that a progress bar is disposed of when the task is complete. After this method is called, the progress bar will no longer show itself and calling methods on the script object will have no effect.
EXAMPLE
myProgressBar.finish()
SYNTAX
progress bar object.finish()
5.6.2.13 Creating a Status Dialog
This method will create a status dialog which can display messages for a task that can not incrementally update a progress bar. This method is also useful for brief tasks that do not require the full weight of a progress bar. There is one argument for this method: the message to be displayed by the status dialog.
EXAMPLE
myStatusDialog = ghi.statusDialog(“Doing something brief”)
SYNTAX
status dialog object = ghi.statusDialog(dialog message )
5.6.2.14 Setting the Status Dialog’s Message
The following method allows you to change the message displayed by the status dialog. This may be useful when you have a series of tasks and you would like to inform the user which task is currently being worked on. The only argument is the message to update the dialog with.
EXAMPLE
myStatusDialog.setMessage(“Now working on a very hard problem.”)
SYNTAX
status dialog object.setMessage(new message )
5.6.2.15 Closing the Status Dialog When Done
To close the status dialog, simply call this method. You should always remember to finish the status dialog that you start and only use one at a time.
EXAMPLE
myStatusDialog.finish()
SYNTAX
status dialog object.finish()
5.6.3 Commands Common to All Objects
Some commands are available for all the Optimus RP objects that you can access from the Python shell. These commands allow you to control GUI aspects of objects you create in scripting.
5.6.3.1 Change a Navigator Node Name
During the course of a script you could be creating navigator node objects that will appear in the Navigator Window next time you open the project in GUI mode. If the generic names assigned to new navigator nodes are not the desired behavior you can change the name of the object with this command.
EXAMPLE
myNodeObject.setName(’my node name’)
SYNTAX
node object.setName(new navigator node name)
5.6.3.2 Getting a Navigator Node Name
If you need to know the name of a navigator node use this command with any Python object that corresponds to a navigator node.
EXAMPLE
myNodeName = myNodeObject.getName()
SYNTAX
navigator node name = node object.getName()
5.6.3.3 Getting a Navigator Node Type
If needed, you can get the navigator node type from an object with this command. The command returns a string displaying the object’s type.
EXAMPLE
myNodeType = myNodeObject.getType()
SYNTAX
navigator node type = node object.getType()
5.6.3.4 Getting a Navigator Node ID
If needed, you can get the navigator node ID from an object with this command. The command returns an integer representing a node’s ID.
EXAMPLE
myNodeID = myNodeObject.getID()
SYNTAX
navigator node ID = node object.getID()
5.6.3.5 Deleting a Navigator Node
To delete a navigator node enter this command in the Python Shell window. If a node can not be deleted, such as the project node or a node that is used to create another node, then a message will be displayed and the node will not be deleted. After entering this command in the Python Shell, the variable that represented the node will no longer be valid and any attempt to use it will display a message saying it is no longer valid.
EXAMPLE
myNodeObject.deleteObject()
SYNTAX
node object.deleteObject()
5.6.3.6 Closing a Navigator Viewer
To cause the viewer for a navigator node to be shut down you can enter this command in the Python Shell window.
EXAMPLE
myNodeObject.close()
SYNTAX
node object.close()
5.6.3.7 Showing a Navigator Viewer
To cause the viewer for a navigator node to be displayed you can enter this command in the Python Shell window.
EXAMPLE
myNodeObject.show()
SYNTAX
node object.show()
5.6.3.8 Finding a Node’s Parent
To get an object that represents a node’s parent enter this command in the Python Shell window and it will return an object representing the parent node. You can use the getType() command to test what type of object is returned.
EXAMPLE
newObject = myNodeObject.getParent()
SYNTAX
new node object = node object.getParent()
5.6.3.9 Finding a Node’s Secondary Parent
This command returns an object representing the secondary parent of a node. A secondary parent is another node that was used in combination with the current node’s parent to create the current node. If there is no secondary parent then nothing is returned. You can check the type of secondary parent returned by using the getType() command.
EXAMPLE
newObject = myNodeObject.getParentSecondary()
SYNTAX
new node object = node object.getParentSecondary()
5.6.3.10 Getting a Node’s Annotations
This command will returned a string with the current contents of the annotations window.
EXAMPLE
myAnnotations = myNodeObject.getAnnotations()
SYNTAX
annotations string = node object.getAnnotations()
5.6.3.11 Appending to a Node’s Annotations
This command will append a string to the end of the current contents of the annotations window.
EXAMPLE
myNodeObject.appendAnnotations("some text")
SYNTAX
node object.appendAnnotations(new annotations text)
5.6.4 Importing and Loading Data
The following commands allow you to import datasets into your open project.
5.6.4.1 Importing GHD-format DataSets
This command can be used to import a (“Legacy”) GHD format dataset. The resulting spreadsheet is returned and may be assigned to a variable.
EXAMPLE
mySS = ghi.importGHD(’/home/mydata.ghd’)
SYNTAX
new spreadsheet object = ghi.importGHD(path and filename of GHD file)
5.6.4.2 Importing DSF Files
This command can be used to import a Dataset Storage Format (DSF) dataset. The resulting spreadsheet is returned and may be assigned to a variable.
EXAMPLE
mySS = ghi.importDSF(’/home/mydata.dsf’)
SYNTAX
new spreadsheet object = ghi.importDSF(path and filename of DSF file)
5.6.4.3 Importing Various File Formats
Correlating to the Import Wizard (4.3.1), this command allows the importing of various file types into the project.
EXAMPLE
mySS = ghi.importData(’/home/mydata.txt’)
EXAMPLE
mySS = ghi.importData(’/home/mydata.txt’, 1, 1, 2)
SYNTAX
new spreadsheet object = ghi.importData(path and filename of file, [optional column number to be used as spreadsheet row labels], [optional row to use as column headers], [the worksheet to use when applicable] )
5.6.4.4 Importing ASCII files
To specifically import a text based file you may use one of the following commands. For either case, the resulting spreadsheet is returned and may be assigned to a variable.
To import a space-separated text file, use
EXAMPLE
mySS = ghi.importASCII(’/home/mydata.txt’)
EXAMPLE
mySS = ghi.importASCII(’/home/mydata.txt’, 1)
SYNTAX
new spreadsheet object = ghi.importASCII(path and filename of text file, [optional column number to be used as spreadsheet row labels])
To import a comma-separated-variable (CSV) text file, use
EXAMPLE
mySS = ghi.importCSV(’/home/mydata.txt’)
EXAMPLE
mySS = ghi.importCSV(’/home/mydata.txt’, 1)
SYNTAX
new spreadsheet object = ghi.importCSV(path and filename of CSV file, [optional column number to be used as spreadsheet row header])
In either case, the resulting spreadsheet is returned, and may be assigned to a variable.
5.6.5 Creating a New Data Set with Scripting
As you manipulate data in scripting there may be times when you would like to add a new dataset and its corresponding spreadsheet to a project. The following set of commands allows you to construct a dataset from Python lists and add the dataset to a project.
5.6.5.1 Getting a Dataset Builder Object
This command returns an object for use in building new datasets. The first parameter is the display name for the dataset when it is added to the Navigator Window. The next two parameters are the number of rows and columns respectively. The last column indicates whether or not you want to add a column of row labels. Note that if you want a column of row labels you must use the addRowLabels() command before adding any of you data columns.
EXAMPLE
myBuilderObject = ghi.startSpreadsheetBuilder("datasetName", 10, 10, 1)
SYNTAX
ss builder object = ghi.startSpreadsheetBuilder(dataset name, number of rows, number of columns, add a row labels 1=yes 0=no)
5.6.5.2 Adding Row Labels
If you specified that your dataset will have row labels you must use the following command to add the row label column before you add the data columns. There are two parameters for this command the first is the column header and the second is a list of strings that are the row labels.
EXAMPLE
myBuilderObject.addRowLabels("myLabels", [label1, label2, label3, ...])
SYNTAX
ss builder object.addRowLabels(column header, list of strings)
5.6.5.3 Adding a Column of Boolean Values
The following command adds a column of boolean values to the new data set. Note the the values should be either 0’s or 1’s.
EXAMPLE
myBuilderObject.addBoolColumn("myBools", [1, 1, 0, ...])
SYNTAX
ss builder object.addBoolColumn(column header, list of 0’s and 1’s)
5.6.5.4 Adding a Column of Integer Values
The following command adds a column of integer values to the new data set.
EXAMPLE
myBuilderObject.addIntColumn("myInts", [10, 12, 20, ...])
SYNTAX
ss builder object.addIntColumn(column header, list of integers)
5.6.5.5 Adding a Column of Double Values
The following command adds a column of double values to the new data set.
EXAMPLE
myBuilderObject.addDoubleColumn("myDoubles", [1.14, 2.5, 1.8, ...])
SYNTAX
ss builder object.addDoubleColumn(column header, list of doubles)
5.6.5.6 Adding a Column of Nominal Values
The following command adds a column of nominal values.
EXAMPLE
myBuilderObject.addNominalColumn("myNominals", ["green", "blue", "brown", ...])
SYNTAX
ss builder object.addNominalColumn(column header, list of strings)
5.6.5.7 Creating the Data Set
After you have added all the columns you desire to the spreadsheet builder object, you are ready to add the data set to the current project. This command will add the data set as a child of the node ID you pass in as a parameter and return a spreadsheet object representing the new data set. Note if no parameter is passed in the builder will default to placing the data set under the project root node.
EXAMPLE
myNewSpreadsheet = myBuilderObject.finishSpreadsheet(5)
SYNTAX
new spreadsheet object = ss builder object.finishSpreadsheet(node ID)
5.6.6 Spreadsheet Access and Manipulation
Once you have created a scripting spreadsheet object you can use the following commands to manipulate the spreadsheet.
5.6.6.1 Getting the Spreadsheet as a Dictionary
This function returns the entire spreadsheet as a dictionary of key value pairs, where the key is a string containing the spreadsheet column label, and the value is a list containing the contents of the spreadsheet column. If there a label column, it is also incorporated as a dictionary entry with its associated column label as its key.
EXAMPLE
myDict = mySS.asDict()
SYNTAX
new dictionary = spreadsheet object.asDict()
5.6.6.2 Getting the Spreadsheet as a List of Lists
This function returns the entire spreadsheet as a list of column lists. The columns will be listed in spreadsheet column number order. If there is a label column it will be the first column.
EXAMPLE
myList = mySS.asList()
SYNTAX
new list of lists = spreadsheet object.asList()
5.6.6.3 Getting a Spreadsheet Cell
This function returns the spreadsheet entry found at the intersection of the specified row and column. Row 0 is the row headers and column 0 is the column headers (if they exist). An invalid row or column index throws a RunTimeError exception.
EXAMPLE
myVariable = mySS.cell(1, 4)
SYNTAX
new variable = spreadsheet object.cell(row number, column number)
5.6.6.4 Getting a Spreadsheet Column by Column Number
This function returns the spreadsheet column values for the selected column. Column 0 is the column headers (if they exist). An invalid column index throws an exception.
EXAMPLE
myList = mySS.col(3)
SYNTAX
new list = spreadsheet object.col(column number)
5.6.6.5 Getting a Spreadsheet Column by Column Name
This function returns the spreadsheet column values for the column with the specified name. An invalid name throws an exception.
EXAMPLE
myList = mySS.col("Name")
SYNTAX
new list = spreadsheet object.col(column name)
5.6.6.6 Determining if a Spreadsheet is a Marker Map
This function returns 1 if a spreadsheet is a marker map spreadsheet or 0 if it is not.
EXAMPLE
mySS.isMarkerMap()
SYNTAX
new variable = spreadsheet object.isMarkerMap()
5.6.6.7 Get a Spreadsheet Column Type
This function returns the column type as one of the following values.
- 0 is Binary
- 1 is Integer
- 2 is Double
- 3 is Categorical
EXAMPLE
myVariable = mySS.getColType(3)
SYNTAX
new variable = spreadsheet object.getColType(column number)
5.6.6.8 Get a Spreadsheet Column State
This function returns the column state as one of the following values.
- 0 is Inactive
- 1 is Independent
- 2 is Dependent
EXAMPLE
myVariable = mySS.getColState(4)
SYNTAX
new variable = spreadsheet object.getColState(column number)
5.6.6.9 Export a Spreadsheet to CSV File
This method writes the entire contents of the spreadsheet out to the specified comma-separated file. If an empty string is passed in, then the user is prompted for a file. If an error occurs in writing to the file in GUI mode, Optimus RP shows an error message to the user.
EXAMPLE
mySS.exportCSV("results.csv")
SYNTAX
spreadsheet object.exportCSV(comma separated value can be set to either 0 = use even spacing or 1 = use marker map spacing.file name)
5.6.6.10 Export a Spreadsheet to a DSF File
This method writes the entire contents of the spreadsheet out to the specified Dataset Storage Format (DSF) file. If an empty string is passed in, then the user is prompted for a file. If an error occurs in writing to the file in GUI mode, Optimus RP shows an error message to the user.
EXAMPLE
mySS.exportDSF("results.dsf")
SYNTAX
spreadsheet object.exportDSF(DSF file name)
5.6.6.11 Finding a Column by Name
This method searches for a column in the spreadsheet whose column label is specified. It returns the index of that column, or throws an exception if no such column is found.
EXAMPLE
myColNum = mySS.findCol("name")
SYNTAX
column number = spreadsheet object.findCol(column name)
5.6.6.12 Finding a Row by Name
This method searches for a row in the spreadsheet whose row label is specified. It returns the index of that row, or throws an exception if no such row is found. The spreadsheet must have row labels otherwise this routine will throw an exception.
EXAMPLE
myRowNum = mySS.findRow("name")
SYNTAX
row number = spreadsheet object.findRow(row name)
5.6.6.13 Invert Row States
Calling this function causes state of all rows to be inverted. That is, rows that were formerly active are made inactive, and rows that were formerly inactive are made active. This routine is useful in creating training and test sets.
EXAMPLE
mySS.invertRowState()
SYNTAX
spreadsheet object.invertRowState()
5.6.6.14 Getting the Number of Spreadsheet Columns
This method returns the number of columns in the spreadsheet (not including the label column).
EXAMPLE
myNum = mySS.numCols()
SYNTAX
number of columns = spreadsheet object.numCols()
5.6.6.15 Get the Number of Columns in a State
This method returns the number of columns in the given state. There are three states: 0=Inactive, 1=Independent, 2=Dependent.
EXAMPLE
myNumIndependant = mySS.numColsState(1)
SYNTAX
number of columns in state = spreadsheet object.numColsState(state)
5.6.6.16 Get the Number of Spreadsheet Rows
This method returns the number of rows in the spreadsheet (not including the column header row).
EXAMPLE
myNumRows = mySS.numRows()
SYNTAX
number of rows = spreadsheet object.numRows()
5.6.6.17 Get the Number of Rows in a State
This method returns the number of rows in the given state. There are two states: 0=Inactive, 1=Active.
EXAMPLE
myNumActive = mySS.numRowsState(1)
SYNTAX
number of rows in state = spreadsheet object.numRowsState(state)
5.6.6.18 Randomly Shuffle Rows
This method randomly permutes the rows in the spreadsheet by modifying the sort order at random. Subsequent calls to this method will give new permutations, based on the current random seed.
EXAMPLE
mySS.permuteRows()
SYNTAX
spreadsheet object.permuteRows()
5.6.6.19 Getting a Row of Data
This method returns a list of elements in a row given by the specified row number. Row 0 is the header row. All other rows contain the data elements of the spreadsheet. Note that row access is generally slower than column access. An exception is thrown if an invalid row number is specified.
EXAMPLE
myRowData = mySS.row(3)
SYNTAX
list of row elements = spreadsheet object.row(row number)
5.6.6.20 Change the State of a Single Column
This method sets the specified column to the specified state. There are three states: 0=Inactive, 1=Independent, 2=Dependent. Other column states remain unchanged.
EXAMPLE
mySS.setColState(1, 2)
SYNTAX
spreadsheet object.setColState(column number, state)
5.6.6.21 Change the State of a Range of Columns
This method sets a range of columns (inclusively) to the specified state. There are three states: 0=Inactive, 1=Independent, 2=Dependent. The states of other columns remain unchanged.
EXAMPLE
mySS.setColState(1, 50, 1)
SYNTAX
spreadsheet object.setColState(first column, last column, state)
5.6.6.22 Setting the State of a Single Row
This method sets a row to the specified state. There are two states: 0=Inactive, 1=Active. The states of other rows remain unchanged.
EXAMPLE
mySS.setRowState(3, 0)
SYNTAX
spreadsheet object.setRowState(row number, state)
5.6.6.23 Getting the State of a Single Row
This method returns the state of a row. There are two states: 0=Inactive, 1=Active.
EXAMPLE
mySS.getRowState(3)
SYNTAX
spreadsheet object.getRowState(row number)
5.6.6.24 Setting the State of a Range of Rows
This method sets a range of rows (inclusively) to the specified state. There are two states: 0=Inactive, 1=Active. Other row states remain unchanged.
EXAMPLE
mySS.setRowState(1, 50, 0)
SYNTAX
spreadsheet object.setRowState(first row number, last row number, state)
5.6.6.25 Randomly set a Number of Rows to a State
This method will set a number of randomly selected rows to the specified state. There are two states: 0=Inactive, 1=Active. The other rows will be set to the opposite state.
EXAMPLE
mySS.setRowStateRandom(25, 0)
SYNTAX
spreadsheet object.setRowStateRandom(number of rows, state)
5.6.6.26 Randomly Set a Percentage of Rows to a State
This method will at random set a fraction of the total number of rows to be to the specified state. This is useful for selecting a certain percentage of the data irregardless of its size. There are two states: 0=Inactive, 1=Active. The other rows will be set to the opposite state.
EXAMPLE
mySS.setRowStateRandom(.5,0)
SYNTAX
spreadsheet object.setRowStateRandom(fraction of total rows, state)
5.6.6.27 Sort a Column in Ascending Order
This method sorts the spreadsheet by arranging the specified column in ascending order.
EXAMPLE
mySS.sortByColAscending(3)
SYNTAX
spreadsheet object.sortByColAscending(column number)
5.6.6.28 Sort a Column in Descending Order
This method sorts the spreadsheet by arranging the specified column in descending order.
EXAMPLE
mySS.sortByColDescending(3)
SYNTAX
spreadsheet object.sortByColDescending(column number)
5.6.6.29 Remembering a Spreadsheet Page
When you make a change to a spreadsheet which has another viewer dependent on it, such as a tree model, the spreadsheet will be copied to a new sheet first. The change will then be made on the copy, rather than the original. For convenience’s sake, your spreadsheet variable will always catch up with the spreadsheet change. However, there are times when, after making such a change, you will want to reference the original spreadsheet page.
To be able to recall the original spreadsheet, use the following command before making the spreadsheet change (to “mySS” in this example):
EXAMPLE
myOriginalSS = mySS.thisPage()
SYNTAX
new spreadsheet object = spreadsheet object.thisPage()
Alternatively, you may wish to make the changes using the new spreadsheet variable (“myNewSS” in the following example) after executing this command the following way:
EXAMPLE
myNewSS = mySS.thisPage()
5.6.6.30 Joining Two Spreadsheets
Spreadsheets can be joined as long as some of the rows match in each spreadsheet. This is useful for adding additional columns to a spreadsheet. To join spreadsheets you get a spreadsheet object in the Python shell. Then specify the node ID of the second spreadsheet as the parameter of the join spreadsheet command. The spreadsheet object command can be a useful aid in specifying the second spreadsheet. A new spreadsheet object will be returned that represents the joined spreadsheets. The joined spreadsheet will be added to the navigator window as a child of the spreadsheet object that was used to issue the join command.
EXAMPLE
myNewSS = mySS.joinSpreadsheet(7)
SYNTAX
new spreadsheet object = spreadsheet object.joinSpreadsheet(node ID of second spreadsheet)
5.6.7 Using the P-Value plot
Once you have created a P-Value plot object, there are a number of functions which can be run with that object.
5.6.7.1 Getting P-Values
Use this command to get a Python dictionary containing P, aP, and bP values. The dictionary contains the following keys:
- P
- aP
- bP
EXAMPLE
myPValues = myPVPlot.pValue(9)
SYNTAX
new dictionary = P-Value object.pValue(column number)
5.6.7.2 Getting Simes P-Values
Use this command to get a Python dictionary containing Simes P, and Simes aP values from a P-Value plot which is ordered by variable number. The dictionary contains the following keys:
- Simes P
- Simes aP
EXAMPLE
mySimesPValues = myPVPlot.simesValue(9)
SYNTAX
new dictionary = P-Value object.simesValue(column number)
5.6.7.3 Setting the Simes Window
The following command can be used to change the window size used in calculating Simes P-Values. The new window size must be greater than 0, odd, and less than or equal to the number of plot columns.
EXAMPLE
myPVPlot.setSimes(3)
SYNTAX
P-Value object.setSimes(new window size)
5.6.7.4 Getting FDR (aP)
To find the false discovery rate for a specific column in a P-Value plot ordered by aP, use the following command.
EXAMPLE
myVariable = myPVPlot.FDRValue(9)
SYNTAX
new variable = P-Value object.FDRValue(column number)
5.6.7.5 Getting all P-Values as a Spreadsheet
Use this command to get a spreadsheet object which contains P, aP, bP, Simes P, and Simes aP for all columns represented in the current P-Value plot.
EXAMPLE
mySpreadsheet = myPVPlot.pvalueSpreadsheet()
SYNTAX
new spreadsheet object = P-Value object.pvalueSpreadsheet()
5.6.8 Getting and Setting Tree Options
In order to set parameters that affect how trees are built and what values are shown in GUI mode, you must first get a tree options object. This object works like a Python dictionary. Each setting is accessed using subscript notation where the name of the setting is put inside the subscript brackets. Each setting is described below with an example showing the subscript notation. To get a tree options object use the following command.
EXAMPLE
myOptionsObject = ghi.getTreeOptions()
SYNTAX
tree options object = ghi.getTreeOptions()
5.6.8.1 Setting the Minimum Elements for Splitting
Using the following command, you can get or change the minimum split size used when creating trees. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new split size must be greater than or equal to 1.
EXAMPLE
myMinElements = myOptionsObject[’minelements’]
SYNTAX
new variable = tree options object[’minelements’]
EXAMPLE
myOptionsObject[’minelements’] = 2
SYNTAX
tree options object[’minelements’] = desired split size
5.6.8.2 Setting the Number of Threads
Using the following command, you can get or change the number of threads used when creating trees. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new number of threads must be greater than or equal to 1.
EXAMPLE
myNumThreads = myOptionsObject[’numthreads’]
SYNTAX
new variable = tree options object[’numthreads’]
EXAMPLE
myOptionsObject[’numthreads’] = 2
SYNTAX
tree options object[’numthreads’] = desired number of threads
5.6.8.3 Setting the P Value Threshold
Using the following command, you can get or change the P value threshold. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new P threshold must be greater than or equal to 0.
EXAMPLE
myPThreshold = myOptionsObject[’pthreshold’]
SYNTAX
new variable = tree options object[’pthreshold’]
EXAMPLE
myOptionsObject[’pthreshold’] = 0.01
SYNTAX
tree options object[’pthreshold’] = desired threshold
5.6.8.4 Setting the Pairwise Threshold
Using the following command, you can get or change the pairwise threshold. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new pairwise threshold must be greater than or equal to 0.
EXAMPLE
myOptionsObject[’pairwisepthreshold’]
SYNTAX
new variable = tree options object[’pairwisepthreshold’]
EXAMPLE
myOptionsObject[’pairwisepthreshold’] = 0.01
SYNTAX
tree options object[’pairwisepthreshold’] = desired pairwise threshold
5.6.8.5 Setting the P Threshold Type
Using the following command, you can get or change the P threshold type. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new P threshold type must be one of three types: 0 = Raw P, 1 = Adjusted P, 2 = Bonferonni Adjusted P.
EXAMPLE
myOptionsObject[’pthresholdtype’]
SYNTAX
new variable = tree options object[’pthresholdtype’]
EXAMPLE
myOptionsObject[’pthresholdtype’] = 2
SYNTAX
tree options object[’pthresholdtype’] = desired threshold type
5.6.8.6 Setting the Segmenting Algorithm
Using the following command, you can get or change the segmenting algorithm. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new segmenting algorithm must be one of two types: 0 = exact, 1 = approximate.
EXAMPLE
myOptionsObject[’segalgorithm’]
SYNTAX
new variable = tree options object[’segalgorithm’]
EXAMPLE
myOptionsObject[’segalgorithm’] = 0
SYNTAX
tree options object[’segalgorithm’] = desired algorithm
5.6.8.7 Setting the Maximum Segments
Using the following command, you can get or change the maximum segments. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new maximum segments must be greater than or equal to 2.
EXAMPLE
myOptionsObject[’maxsegments’]
SYNTAX
new variable = tree options object[’maxsegments’]
EXAMPLE
myOptionsObject[’maxsegments’] = 3
SYNTAX
tree options object[’maxsegments’] = desired setting
5.6.8.8 Setting Resample Iterations
Using the following command, you can get or change the number of resample iterations. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting.
EXAMPLE
myOptionsObject[’resample_iterations’]
SYNTAX
new variable = tree options object[’resample_iterations’]
EXAMPLE
myOptionsObject[’resample_iterations’] = 0
SYNTAX
tree options object[’resample_iterations’] = desired setting
5.6.8.9 Setting Linear Regression
Using the following command, you can get or change the Linear Regression setting. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new linear regression setting must be one of two settings: 0 = off, 1 = on.
EXAMPLE
myOptionsObject[’linearregression’]
SYNTAX
new variable = tree options object[’linearregression’]
EXAMPLE
myOptionsObject[’linearregression’] = 0
SYNTAX
tree options object[’linearregression’] = desired setting
5.6.8.10 Setting RP Splits
Using the following command, you can get or change the RP Splits setting. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new RP Splits setting must be one of two settings: 0 = off, 1 = on.
EXAMPLE
myOptionsObject[’rpsplits’]
SYNTAX
new variable = tree options object[’rpsplits’]
EXAMPLE
myOptionsObject[’rpsplits’] = 0
SYNTAX
tree options object[’rpsplits’] = desired setting
5.6.8.11 Setting Use Missing Values Option
Using the following command, you can get or change the Use Missing Values setting. The first example demonstrates getting the current setting, and the second example demonstrates changing the setting. The new missing values setting must be one of two settings: 0 = off, 1 = on.
EXAMPLE
myOptionsObject[’usemissing’]
SYNTAX
new variable = tree options object[’usemissing’]
EXAMPLE
myOptionsObject[’usemissing’] = 0
SYNTAX
tree options object[’usemissing’] = desired setting
5.6.9 Creating a Tree Model
To build tree model you must first set the options you want by using the getTreeOptions() command and then setting the options to desired values. See(5.6.8). The options object is then passed as the first parameter to the buildTreeModel() command. In addition to the options object there are three optional parameters you can specify in any combination.
The buildTreeModel() command will return a tree model object.
EXAMPLE
myTreeModel = mySS. buildTreeModel(ghi.getTreeOptions(), numtrees=50, randseed=7839743, numsplitters=6)
SYNTAX
tree model object = spreadsheet object. buildTreeModel(tree options object [, numtrees=val, randseed=val, numsplitters=val])
5.6.10 Importing a Legacy Tree Model
You can import an existing tree model using the following command. The tree model will be imported into the project as a child node of the current spreadsheet.
EXAMPLE
myTreeModel = mySS.importLegacyTreeModel(”C:/HelixTree/myProject/trees/myTree.ght”)
SYNTAX
tree model object = spreadsheet object. importLegacyTreeModel(path and filename of tree model)
5.6.11 Tree Model Commands
5.6.11.1 Get Variable Frequencies
This command creates a new spreadsheet with the variable frequencies of a multi-tree model. The new spreadsheet is added to the project as a child of the tree model and is returned as a spreadsheet object in the Python shell.
EXAMPLE
mySpreadsheetVariable = myTreeModel.variableFrequencies()
SYNTAX
new spreadsheet object = tree model object.variableFrequencies()
5.6.11.2 Get Tree Predictions
This command creates a new spreadsheet with the tree predictions. The spreadsheet is added to the project as a child of the tree model and is returned as a spreadsheet object in the Python shell.
EXAMPLE
mySpreadsheetVariable = myTreeModel.averageTreePredictions()
SYNTAX
new spreadsheet object = tree model object.averageTreePredictions()
5.6.11.3 Get Tree Variables
This command returns a list of variables used as splitters in creating the trees in a multi-tree model.
EXAMPLE
myVariable = myTreeModel.getTreeVariables()
SYNTAX
new list = tree model object.getTreeVariables()
5.6.11.4 Get Correlation Table
This command builds a spreadsheet of correlation interactions for a given tree model’s variables. The spreadsheet is added to the project as a child of the tree model and is returned as a spreadsheet object in the Python shell.
EXAMPLE
mySpreadsheetVariable = myTreeModel.correlationTable()
SYNTAX
new spreadsheet object = tree model object.correlationTable()
5.6.11.5 Get Correlation Plot
This command creates a new correlation interaction plot using the variables of a given tree model. The plot is added to the project as a child of the tree model, and a correlation plot object is returned in the Python shell.
EXAMPLE
myCorrelationPlot = myTreeModel.correlationPlot()
SYNTAX
new plot object = tree model object.correlationPlot()
5.6.11.6 Get Observation Distance Matrix Unsorted
This command creates an unsorted observation distance matrix plot using the tree model. The plot is added to the navigator window as a child of the tree model, and a distance matrix object is returned in the Python shell.
EXAMPLE
myDMPlot = myTreeModel.distMatrixUnsorted()
SYNTAX
new plot object = tree model object.distMatrixUnsorted()
5.6.11.7 Get Observation Distance Matrix Sorted by First Principal Component
This command creates an observation distance matrix plot, sorted by the first principal component, using the tree model. The plot is added to the navigator window as a child of the tree model and a distance matrix object is returned in the Python shell.
EXAMPLE
myDMPlot = myTreeModel.distMatrixSorted()
SYNTAX
new plot object = tree model object.distMatrixSorted()
5.6.11.8 Get Observation Distance Sorted by Similarity to One Observation
This command creates an observation distance matrix plot of observations most similar to selected observations, sorted by the distance to those observations, using the tree model. The plot is added to the navigator window as a child of the tree model and a distance matrix object is returned in the Python shell.
EXAMPLE
myDMPlot = myTreeModel.distMatrixSimSorted(37, 5)
SYNTAX
new plot object = tree model object.distMatrixSimSorted(number of similar observations, row (observation) number)
5.6.12 Using the Distance Matrix Object
Once you have created a distance matrix object, there are a number of functions available which use that object.
The functions translate between the ranking, or position, within the distance matrix plot, and the spreadsheet row name or number.
NOTE: For distance matrices sorted by first principal component, the earliest ranking (number one) corresponds to the eigenvector component with the greatest magnitude, the second ranking corresponds with the eigenvector component with the second-greatest magnitude, and so forth. For unsorted distance matrices, the ranking will be the same as the row number. For distance matrices sorted by similarity to a given observation, that observation will be number one, the closest observation to that one will be number two, and so forth.
5.6.12.1 Get the Observation Label for a Distance Matrix Plot
This command returns the observation label for a desired rank in an observation distance matrix plot. This command takes one parameter, the desired rank index.
EXAMPLE
myLabel = myDM.getObsLabel(1)
SYNTAX
new label string = distance matrix object.getObsLabel(rank index)
5.6.12.2 Get the Observation Number for a Distance Matrix Plot
This command returns the spreadsheet row number for a desired rank in an observation distance matrix plot. This command takes one parameter, the desired rank index.
EXAMPLE
myObsNumber = myDM.getObsNumber(2)
SYNTAX
row number variable = distance matrix object.getObsNumber(rank index)
5.6.12.3 Get the Rank Index for a Distance Matrix Plot
This command returns the rank index for a specified spreadsheet row used in an observation distance matrix plot. This command takes one parameter, the desired row number.
EXAMPLE
myRankIndex = myDM.getRankIndex(5)
SYNTAX
rank index variable = distance matrix object.getRankIndex(row number)
5.6.12.4 Get the Distance Values by Row Number for a Distance Matrix Plot
The following function can be used with two parameters or two ranges to output the computed distance value between two observations, input by spreadsheet row number. If two parameters are specified a single distance value is returned. If a range of parameters are specified then a matrix of distance values is returned.
EXAMPLE
myDistance = myDM.distance(5, 7)
SYNTAX
distance variable = distance matrix object.distance(first row number, second row number)
EXAMPLE
myMatrix = myDM.distance(5, 7, 8, 9)
SYNTAX
distance matrix = distance matrix object.distance(first range start row, first range end row, second range start row, second range end row)
5.6.12.5 Get the Distance Values by Rank Index for a Distance Matrix Plot
The following function can be used with two parameters or two ranges to output the computed distance value between two observations, input by rank index. If two parameters are specified a single distance value is returned. If a range of parameters are specified then a matrix of distance values is returned.
EXAMPLE
myDistance = myDM.distanceByRank(1, 3)
SYNTAX
distance variable = distance matrix object.distanceByRank(rank index of first observation, rank index of second observation)
EXAMPLE
myMatrix = myDM.distanceByRank(1, 3, 4, 6)
SYNTAX
distance matrix = distance matrix object.distanceByRank(first range start rank index, first range end rank index, second range start rank index, second range end rank index)
5.6.13 Applying a Tree Model
Use this command to apply a previously built tree model to a spreadsheet. This command takes one parameter, an existing tree model object, and returns the new tree model.
EXAMPLE
myAppliedTreeModel = mySS.applyTreeModel(treeModelObject)
SYNTAX
new tree model object = spreadsheet object. applyTreeModel(existing tree model object)
5.6.14 Performing Regression
There are two scripting commands which allow you to perform various regressions. These commands are:
- performRegression(...) - to perform linear or logistic regression.
- performStepwiseRegression(...) - to perform stepwise linear or logistic regression
In order to be able to use these commands, the spreadsheet object must have exactly one non-categorical column set as dependent.
These commands will return a tuple of result objects which will vary based on the options used. The results tuple will contain:
- A text viewer object at the first index, and ’None’ at the second index if the parameter for whether or not to create a residual spreadsheet is set to 0.
- A text viewer at the first index, and a residual spreadsheet at the second index if the parameter for whether or not to create a residual spreadsheet is set to 1.
The performRegression command has no required parameters, but does require that either covariates or first order interactions be specified.
The performStepwiseRegression command requires 1 parameter: a p-value cutoff for the stepwise procedure.
Additionally, these commands can take a number of keyword arguments, each of which may be required or prohibited based on the other options used. These keywords, and the parameters they represent are as follows:
- numPermutations - represents the number of permutations to perform for permutation tests. To omit permutation testing, set this value to 0. Default value = 0
- covariates - This parameter represents the covariates that should be included in the regeression. This parameter must be specified as a python list of spreadsheet column numbers, i.e. covariates = [3, 4, 6] would include columns 3, 4 and 6 in the regression. All column numbers must represent active columns.
- firstOrderInteractions - defines the first-order interactions between covariates which will be used in the regression. These interactions must be specified in the form of a python list of tuples which contain spreadsheet column numbers, i.e. firstOrderInteractions = [(3, 4), (4, 4), (2, 3)]. All column numbers must represent active columns.
- createResidualSpreadsheet - if set to 1, a residual spreadsheet will be created. Default value = 0.
The performRegression command should be used in the following manner:
EXAMPLE
myTuple = mySpreadsheet.performRegression( covariates=[3,5,6], firstOrderInteractions=[(3, 6),(5, 5)])
SYNTAX
new tuple = spreadsheet object.performRegression( keyword1=value1, keyword2=value2...)
The performStepwiseRegression command can be used as follows:
EXAMPLE
myTuple = mySpreadsheet.performStepwiseRegression( 0.01, covariates=[3,5,6], firstOrderInteractions=[(3, 6),(5, 5)])
SYNTAX
new tuple = spreadsheet object.performStepwiseRegression( pvalueCutoff, keyword1=value1, keyword2=value2...)
For further description of the parameters used in these commands please see 16.2.
5.6.15 Output a C File
To create a C program with the prediction rules of a tree model, use this command.
EXAMPLE
myTreeModel.outputCFile(’/tmp/mycfile’)
SYNTAX
tree model object.outputCFile(path and filename of C file)
5.6.16 Prompting the User for Input
In interactive scripts, it is often useful to prompt the user for data or parameters to be used in the analysis. We have provided an interface to create a simple modal dialog that prompts the user for a number of values, and provides error checking on the input. The main ghi object provides a convenient python function for this purpose. The function takes a set of dictionaries as the arguement and returns a list of user inputs.
EXAMPLE
myUserInput = ghi.promptUser([{"label":"Enter string:", "type":"string", "tooltip":"Any string will
do"},
{"label":"Enter integer:", "type":"integer","min":0, "max":100},
{"label":"Enter double:", "type":"double","min":-1},
{"label":"Select method:", "type":"combobox",
"list":["method 1", "method 2", "method 3"]}])
SYNTAX
new list = ghi.promptUser(list of dictionaries)
This example would construct the following dialog:
![[Picture]](promptUserPT.png)
|
The promptUser() function takes a list of Python dictionary objects, with each object defining one data entry field. The fields are included in list order from top to bottom within the dialog. When the user hits the OK button, if the entries are valid, they are returned in a list.
There are a number of data entry methods available. Each entry method is defined using a dictionary. Every entry must have a "label" attribute and a "type" attribute. Each entry may have an optional tooltip attribute, which is a message that appears when the user hovers the mouse over the field. Labels are listed at the left of the data field. The "type" attribute defines which type of data entry field is to be constructed. The available types are as follows:
- integer: prompts user for an integer. Does error checking to see that a valid integer has been entered.
Optional attributes:
- "min":<integer> specifies that integer must be greater than or equal to the specified minimum value.
- "max":<integer> specifies that integer must be less than or equal to the specified maximum value.
- double: prompts user for a double precision (64-bit) number. Does error checking to see that a valid double has been
entered.
Optional attributes:
- "min":<double> specifies that user-entered double must be greater than or equal to the specified minimum value.
- "max":<double> specifies that user-entered double must be less than or equal to the specified maximum value.
- float: same as double, provided for convenience.
- real: same as double, provided for convenience.
- string: prompts user for a string. Does error checking to see that the string entered is not blank.
- combobox: Takes an additional non-optional attribute, "list", which contains a list of strings to form a list of choices for the user to choose from. For example, the dictionary entry "list":["item1", "item2"] specifies a combobox with two possible values to choose from, "item1" and "item2". The first item is specified by default.
If the user cancels, a Python exception is returned. If there is an error in syntax, a Python exception is returned with a description of the error. If the user hits OK, and there is any error in the input, the user is told by the dialog what the problem is, which may be remedied from within the dialog. If there are no errors, a list of the user inputs is returned in the same order as the dictionaries that are passed in.
5.6.17 Text Viewer
5.6.17.1 Getting the text
This function will return a Python string with the contents of the text viewer.
EXAMPLE
myVeiwerContents = myTextViewer.getText()
SYNTAX
new string = text viewer object.getText()
5.6.17.2 Saving text to a file
This function will save the contents of the text viewer to a .txt file. “.txt” will be appended to the end of the file name if it is not already there.
EXAMPLE
myTextViewer.saveToFile("filename.txt")
SYNTAX
text viewer object.saveToFile( file name string )
5.6.18 Regression Results
5.6.18.1 Getting the text
This function will return a Python string with the contents of the regression results.
EXAMPLE
myResultsString = myRegressionResults.getText()
SYNTAX
new string = regression results object.getText()
5.6.18.2 Saving text to a file
This function will save the contents of the Regression Results to a .txt file. “.txt” will be appended to the end of the file name if it is not already there.
EXAMPLE
myRegressionResults.saveToFile("filename.txt")
SYNTAX
regression results object.saveToFile( file name string )
5.6.18.3 Getting the covariates
This function will return the covariates which were used in the regression as a Python list of spreadsheet column numbers.
EXAMPLE
myCovariates = myRegressionResults.covariates()
SYNTAX
new list = regression results object.covariates()
5.6.18.4 Getting the interactions
This function will return the interactions which were used in the regression as a Python list of tuples, which contain a column number for each of the regression terms.
EXAMPLE
myInteractions = myRegressionResults.interactionTerms()
SYNTAX
new list of tuples = regression results object.interactionTerms()
5.6.19 Navigator Object Selection
5.6.19.1 Selecting a Spreadsheet
This function constructs a dialog that lists all of the navigator nodes, with all the spreadsheet nodes highlighted in white. The navigator node ID is returned for the spreadsheet that the user selects. Nothing is returned if the user cancels.
EXAMPLE
mySSID = ghi.promptSpreadsheet()
SYNTAX
new variable = ghi.promptSpreadsheet()
5.6.19.2 Selecting a Tree model
This function constructs a dialog that lists all of the navigator nodes, with all the tree model nodes highlighted in white. The navigator node ID is returned for the tree model that the user selects. Nothing is returned if the user cancels.
EXAMPLE
myTreeID = ghi.promptTree()
SYNTAX
new variable = ghi.promptTree()