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