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 HelixTree 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 argument the file chooser will allow multiple files to be selected. If the third argument is omitted or anything but a one is set 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 HelixTree 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:/HelixTree/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 HelixTree 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 Data Sets
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 character to use as the allele delimiter], [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.4.5 Importing Family-Indexed Data
HelixTree can import pedigree and family-indexed data in a number of formats. (Currently, only the FBAT/PBAT pedigree and phenotype formats are supported. In the future, we plan to support other pedigree formats, along with the formats for their supporting data.)
To import an FBAT/PBAT Pedigree file, use the following command. The resulting spreadsheet is returned and may be assigned to a variable.
EXAMPLE
mySS = ghi.importFBATPedigree(’/home/mydata.ped’)
SYNTAX
new spreadsheet object = ghi.importFBATPedigree(path and filename of pedigree file)
To import an FBAT/PBAT Pedigree file, use the following command. The resulting spreadsheet is returned and may be assigned to a variable.
EXAMPLE
mySS = ghi.importFBATPhenotype(’/home/mydata.phe’)
SYNTAX
new spreadsheet object = ghi.importFBATPhenotype(path and filename of phenotype file)
5.6.4.6 Importing PED files
PED files can be imported using the importPED(...) scripting command. This command takes two string parameters for the PED and MAP file paths, as well as two optoinal keyword arguments to specify missing values for genotypes and phenotypes. Note: The missing value for phenotypes defaults to -9, and the missing value for genotypes defaults to "0".
The optional keyword arguments are as follows:
- missingPhenotype – This argument allows you to specify an integer value that should be treated as missing for phenotypes
- missingGenotype – This argument allows you to specify a single character string that should be treated as missing for genotypes
EXAMPLE
mySS = ghi.importPED(’C:/data/myData.ped’, ’C:/data/myData.map’, missingPhenotype=-9, missingGenotype="0")
SYNTAX
new spreadsheet object = ghi.importPED(path and filename of PED file, path and filename of MAP file [, missingPhenotype=missing phenotype value, missingGenotype=missing genotype value])
5.6.4.7 Importing BED files
Use the following command to import BED (binary PED) files. This command takes 3 arguments: the BED file path, the FAM file path, and the BIM file path.
EXAMPLE
mySS = ghi.importBED(’C:/data/myData.bed’, ’C:/data/myData.fam’, ’C:/data/myData.bim’)
SYNTAX
new spreadsheet object = ghi.importBED(path and filename of BED file, path and filename of FAM file, path and file name of BIM file)
5.6.4.8 Extracting Copy Number Values From Affymetrix CEL Files
Using the convertCelToCopyNumberDsf(...) command, you can create a DSF file containing the normalized copy number intensity values contained in the input CEL files. The resulting DSF file will be stored on disk, and may then be included in subsequent operations using HelixTree.
This command requires the following parameters in this order:
- Input file list – This list should contain the paths and names for all CEL files that you want to use. This must be a Python List.
- Output DSF file – Specifies the save location and file name of the output DSF file.
- Ref status spreadsheet – An integer representing the node ID of the spreadsheet object that will contain the reference column.
- Ref status column – An integer that represents the column number of the actual reference status column within the ref status spreadsheet.
- Marker map spreadsheet – An integer representing the node ID for the marker map spreadsheet.
This command also allows you to specify other, optional parameters by using keyword arguments as follows:
- affyLibDir – Allows you to specify the path to a directory containing Affymetrix library files.
- tempDir – Allows you to specify a directory to use for temporary file creation.
- mappingId – NSP/STY mapping spreadsheet.
Note: If you omit the affyLibDir keyword argument, you must have the appropriate .gcdf files in the AffyLibraryFiles directory of your HelixTree directory. This file will be created from the corresponding Affymetrix .cdf file the first time it is used during the import process.
Note: The temporary directory used by the import process must be on a local disk. If your project is on a network drive, be sure to specify tempDir as a directory on your local disk.
Note: If you are using Affymetrix 500k data, and are including both NSP and STY CEL files, you must choose an NSP/STY mapping spreadsheet in order for the import to be successful.
See 4.4.1.1 for more information on the import process, including the requirements for the reference status and mapping spreadsheets.
EXAMPLE
resultVal = ghi.convertCelToCopyNumberDsf([’C:/file1.cel’,’C:/file2.cel’], ’C:/DsfOutput/CopyNumberVals.dsf’, 3, 1, 6, affyLibDir=’C:/GeneChip/Library’, tempDir=’C:/workSpace’, mappingId=9)
SYNTAX
int = ghi.convertCelToCopyNumberDsf(CelFileList, outputDsfFile, CaseControlId, CaseControlColumn, markerMapId [, affyLibDir, tempDir, mappingId])
5.6.4.9 Importing a Marker Map File
To import a Genetic Marker Map, use the following command. The first two arguments are mandatory followed by a third optional argument. The first is the file path to the map file, the second is a format indicator and should be the string “S” for space, “C” for comma and “T” for tab delimited ASCII files. Optionally you can add 1 as the third argument to specify that the first line of the map file should be ignored. These positional parameters are followed by optional “keyword” parameters you can specify in any combination. The values assigned to these parameters should be the column in the import file to associate with each field.
- markerID - The column number of SNP/Marker ID, default=1
- distance - The column number of Distance, default=2
- chromosome - The optional column number of Chromosome
- region - The optional column number of Region
- rsid - The optional column number of RSID
- gene - The optional column number of Gene
The importMarkerMap() command returns a spreadsheet object.
EXAMPLE
mySS = ghi.importMarkerMap(’/home/mydata.txt’,’S’)
EXAMPLE mySS = ghi.importMarkerMap(’/home/mydata.txt’, ’C’, markerID=1, distance=2, chromosome=3, region=5,
rsid=4, gene=6) EXAMPLE mySS = ghi.importMarkerMap(’/home/mydata.txt’, ’T’, 1, distance=2, markerID=1)
SYNTAX
new spreadsheet object = ghi.importMarkerMap(path and filename of map file, the format indicator, [ignore the firest line=0], [markerID column number], [distance column number], [chromosome column number], [region column number], [rsid column number], [gene column number])
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 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 Adding a Column of Genetic Values
The following command adds a column of genetic values.
EXAMPLE
myBuilderObject.addGeneticColumn("myGenetics", ["1_0", "1_1", "1_0", ...])
SYNTAX
ss builder object.addGeneticColumn(column header, list of strings)
5.6.5.8 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.
NOTE: Calling mySS.col("Name") performs a linear search across the columns until a match is found or not. This can be extremely slow with high-dimensional datasets. If you would like to perform look-ups of a columns position by its name, a hash table mapping labels to indexes might be appropriate. For example:
labelDict = {}
for idx, label in enumerate(data.row(0)): labelDict[label] = idx + 1 |
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
- 4 is Genetic
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 Selecting Columns by Chromosome, Region, or Gene Ranges
This method brings up the GUI dialog for selection of columns within one or more desired ranges of chromosome(s), region(s), or gene(s). This method can only be used on a marker mapped spreadsheet, otherwise an error will be returned.
EXAMPLE
mySS.selectGeneticRegion()
SYNTAX
spreadsheet object.selectGeneticRegion()
5.6.6.10 Obtain Marker Map Information from a Spreadsheet
The following method returns a list of dictionaries containing marker map information for all columns or for the column passed in:
EXAMPLE
myMarkerMapDict = mySS.getMarkerMap()
EXAMPLE
myCol5MarkerMap = mySS.getMarkerMap(5)
SYNTAX
list of dictionaries = spreadsheet object.getMarkerMap([optional column number])
The following methods each return a list containing values of the appropriate type for all columns or a list containing the one value of the appropriate type for the column passed in:
EXAMPLE
myDistanceList = mySS.getMarkerMapDistance()
myChromosomeList = mySS.getMarkerMapChromosome()
myRegionList = mySS.getMarkerMapRegion()
myRsidList = mySS.getMarkerMapRsid()
myGeneList = mySS.getMarkerMapGene()
EXAMPLE
myCol2DistanceList = mySS.getMarkerMapDistance(2)
myCol3ChromosomeList = mySS.getMarkerMapChromosome(3)
myCol4RegionList = mySS.getMarkerMapRegion(4)
myCol5RsidList = mySS.getMarkerMapRsid(5)
myCol6GeneList = mySS.getMarkerMapGene(6)
SYNTAX
numeric distance list = spreadsheet object.getMarkerMapDistance([optional column number])
chromosome name list = spreadsheet object.getMarkerMapChromosome([optional column number])
region name list = spreadsheet object.getMarkerMapRegion([optional column number])
rsid (string) list = spreadsheet object.getMarkerMapRsid([optional column number])
gene name list = spreadsheet object.getMarkerMapGene([optional column number])
5.6.6.11 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, HelixTree 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.12 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, HelixTree shows an error message to the user.
EXAMPLE
mySS.exportDSF("results.dsf")
SYNTAX
spreadsheet object.exportDSF(DSF file name)
5.6.6.13 Export a Spreadsheet to FBAT Pedigree File
This method writes the entire contents of the spreadsheet out to the specified FBAT-format pedigree file.
EXAMPLE
mySS.exportAsFBATPedigree("results.ped")
SYNTAX
spreadsheet object.exportAsFBATPedigree(pedigree file name)
5.6.6.14 Export a Spreadsheet to FBAT Phenotype File
This method writes the entire contents of the spreadsheet out to the specified FBAT-format phenotype file.
EXAMPLE
mySS.exportAsFBATPhenotype("results.phe")
SYNTAX
spreadsheet object.exportAsFBATPhenotype(phenotype file name)
5.6.6.15 Export a Spreadsheet PED/MAP File
To export a marker mapped pedigree spreadsheet to a PED file and the corresponding MAP file, use the savePED(...) scripting command. This command takes one string parameter which specifies the save location and name of the PED file. The MAP file name will automatically be created to match the PED file name, and will be exported to the same directory.
EXAMPLE
mySS.savePED("myPedFile.ped")
SYNTAX
spreadsheet object.savePED(PED file name)
5.6.6.16 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.17 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.18 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.19 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.20 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.21 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.22 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.23 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.24 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.25 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.26 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.27 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.28 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.29 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.30 Setting the State of a Defined Set of Rows
This method of setting row state allows you to specify which rows to set to the specified state using a list of row numbers. Rows which correspond to the row numbers contained in the list will have their state changed to the specified state. There are two states: 0=Inactive, 1=Active. Rows with numbers that do not appear in the list will not be affected.
EXAMPLE
mySS.setRowState([1, 2, 4, 6], 0)
SYNTAX
spreadsheet object.setRowState(row number list, state)
5.6.6.31 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.32 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.33 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