The table Command

The table command is the generic command used to manipulate Cactvs table objects. The syntax of this command follows the standard schema of command/subcommand/tablehandle/args. Table objects are major objects just like ensembles, reactions or datasets and have, in addition to object-specific commands, the standard command set for major objects and can possess table-level properties, which start by convention with prefix T_ . Example:

table get $thandle T_XYPLOT

Because tables are pure major objects without an internal set of minor objects, there are no minor object labels. Nevertheless, there are mechanisms to address columns, rows and cells. Commands which address rows or columns use a syntax schema of command/subcommand/tablehandle/address/args .

Depending on the context, column and row arguments to table commands can be either single addresses, or address ranges. Single addresses are identified either by a numerical row or column index starting with zero, the magic names end or last , or a symbolic name which is was assigned to the row or column at some time during its existence. Columns can have additional alias names. Examples:

table getcol $thandle last datatype
table getcol $thandle 0 data

Address ranges are specified by two simple addresses, separated by a dash character. These ranges can also be open, meaning that if there is no name component to the left of the dash, start column or row zero is implied, and if there is no name component to the right of the dash, the rightmost column or bottommost row is the end of the range. When a column or row range without any range dashes is specified, the range only includes that single item. Finally, the magic names all or * select all current columns or rows. Examples:

table delrow $thandle 3-last
table dupcol $thandle E_NAME end

Table objects can store output formatting information in different places - globally, on columns, rows and individual cells. The precedence for these formats is cell>row>column>global. The fonts, font sizes and colors, for which there can only be one value, that are used for the output of a specific cell are determined by the location with the highest precedence where the attribute is set to a definite value (i.e. in the case of fonts, the location where a font name and not an empty string is provided). General formatting flags are bit-ored from all locations. There is currently no method to suppress the use of a formatting flag on output which is set in any checked location. Example:

table setcol $thandle 0 bgcolor white
table setrow $thandle 1 bgcolor red

All cells in row one are output with a red background, provided that there are no cell-level overrides, and that the output format supports cell coloring.

Tables possess an internal utility dataset. Its handle can be retrieved with

table get $thandle dataset

This internal dataset is useful to store objects which are referenced by rows. Normally, these referenced objects which are introduced by command such as table addens or table addreaction are not destroyed when the table is deleted. However, when they are moved into the internal dataset, are will be deleted with the table, just like other objects in a dataset object when that dataset object is destroyed. In case of table file formats which store both table cell data and structure or reaction objects, the associated objects are moved to the internal dataset when such a file is read.

This is the list of officially supported subcommands:

table addcolumn

table addcolumn tablehandle columntype ?property|datatype|expression?	?name? ?position? ?width? ?startvalue?
t.addcolumn(property=,?name=?,?position=?,?width=?,?startvalue=?)

This command adds a new column to the table. All data values for the new column in existing rows are initially set to NULL , with the exception of function columns, which are set to the computed value as far as that is possible from the current table content, and sequences, which are initialized with a number sequence.

table addcol is a shortened alias command name.

The startvalue parameter is only used for sequence type columns.

The column type argument can be one of:

The content of the argument of the column type specification must be appropriate to the previous argument, i.e. a data type for columns of type data , a property name for columns of type property , or a parseable SQL expression for columns of type function .

For data and property type columns, the column type may also be omitted and the property or data type name written immediately. These two lines are equivalent:

table addcol $thandle property E_XLOGP2 xlogp
table addcol $thandle E_XLOGP2 xlogp

In the Python interface, the column type and column detail are rolled into a single argument. It can either be a single item, which is equivalent to the single-argument Tcl form, or a tuple with the type and detail pair corresponding to the two Tcl command arguments. Above example in Python :

t.addcol((“property”,”E_XLOGP2”),”xlogp”)
t.addcol(“E_XLOGP2”)

Columns can be given a user-defined name. If the optional name argument is not given, a synthetic name is automatically supplied. For property columns, it is the name of the property. For other columns, it is the column index appended to the column type, as in data1 for a data column with column index one.

By default, columns are appended to the right. This is also done if the optional position argument is end , an empty string, or a column index beyond the current maximum column index. Otherwise, the column is inserted into the specified position and all other columns behind it are moved one position to the right. No columns are overwritten. Existing cell data is also moved if necessary. It is not possible to add a column to the right beyond the rightmost column in a way that undefined columns result. It is possible to use a column name in addition to a numerical index. In that case, the new column is added to the right of the named column.

The next optional argument defines the column width, which is only used for output formatting. It is the same as the column attribute width and described in the paragraph on the table setcol command. If this argument is omitted, or an empty string, the width is undefined and defaults are used. The optional start value argument is only used for sequence columns.

The return value of the command is the new number of columns in the table.

table addrow

table addrow tablehandle ?name|#auto? ?position? ?celldatalist? ?cellobjlist? 	?rowobject?
t.addrow(?name=?,?position=?,?celldata=?,?cellobjects=?)

Add a row to an existing table. By default, all cell data values of the newly added row are set to NULL .

Table rows can be named. If the name argument is omitted, set to an empty string (or None for Python ), or #auto is used as magic name, the standard automatically generated row name, of the form Row rowcount , is used, with the row count replaced by the integer value. This format can be overridden by setting a table row name template format string ( autorowformat table attribute). Note that this name uses the total row count of the table after adding the new row, not the insert position. This makes it less likely to accidentally generate duplicate row names if multiple rows are inserted into the same position.

By default, the new row is appended to bottom of the table. This also happens if the optional position argument is end , or larger than the current maximum row index, which starts with zero. If any other valid row index is given, the new row is inserted into that position and the rest of the rows behind it are moved. No existing rows are overwritten. It is not possible to add a row beyond the current end of the table in such a fashion that undefined rows result.

Next, it is possible to initialize the cell values of the new row. If that option is chosen, the length of the column data list must smaller then, or the same length, as the number of columns in the table, and every column data value must be decodable according to the respective column data type.

The optional row object argument can be either an ensemble or reaction handle. If it is specified and not an empty string, the object becomes associated with the new row, as by the table addens or table addreaction commands. If an explicit empty string is used, the row is explicitly not associated with an ensemble or reaction, and no attempt is made to find and decode a row object source in the column data when it is requested at a later time.

The same processing applies a a cell object list is used. The cell objects (ensembles or reactions) are transferred to the table and henceforth are under the control of the table and no longer deletable by normal means. They are only destroyed if the associated table cell is deleted. By default the new table cells have no cell object, and this also remains the case if the object list element for a cell is an empty string. Cell objects to be transferred cannot be already undeletable (e.g. a property value or the cell object of another cell). If such objects need to be set, they must be duplicated first.

If data is extracted from chemical objects and stored in a table object, it is usually more convenient to use the table addens and table addreaction commands than to script sequences of table addrow statements.

The table must be editable for this command to be usable.

The return value of the command is the new number of rows in the table.

table adddataset

table adddataset tablehandle datasetlist ?objclass? ?filterlist? ?position? ?mode?
t.adddataset(datasets=,?objclass=?,?filters=?,?position=?,?mode=?)

This command performs a table addens command for each ensemble in the datasets, and a table addreaction command for each reaction. The command arguments are interpreted as described in each specialized command, and have the same defaults if they are not set explicitly.

If a dataset contains other objects besides ensembles and reactions, these objects are ignored in the table data setting operation. If the mode is set to destroy , not only the ensembles or reactions in the dataset are deleted, but the complete dataset with all its content, including other objects which are not reactions or ensembles. With mode move , ensembles and reactions are removed from the source dataset and transferred to the internal table dataset. In this mode, other dataset content objects that are not reactions or ensembles remain in the source dataset, and the source datasets persist. Finally, mode preserve (the default) retain all object memberships, and again the source datasets persist.

The command returns the number of added table rows.

table addens

table addens tablehandle enslist ?objclass? ?filterlist? ?position? ?mode?
t.addens(ens=,?objclass=?,?filters=?,?position=?,?mode=?)

Capture data from a list of ensembles in a table object. One or more new rows are added, and all table columns for these rows which refer to property data present or computable on the ensemble are filled. In addition, references between the new rows and the ensemble are registered.

The object class determines how many rows are added per ensemble. It can be ens , or the type of any ensemble minor object. One row is added for each ensemble minor object (or the ensemble proper, in case the object class is ens ), provided it passes the filters if a filter list is specified. If the object class argument is not specified, or given as an empty string (or None in Python ) or the special value auto or #auto , an attempt is made to determine it automatically. If only data columns of ensemble properties are found, it is then set to ens , but if there are any data columns of properties related to ensemble minor objects except molecules, the object class is that class. If there are only molecule and ensemble properties, the class is mol . For each object of the selected class in the ensemble, one row is added, and the cells filled with the data extracted from the associated ensemble or ensemble minor object.

For example, assume the object class is atom ; let there be table data columns of atom, molecule, and ensemble properties; and let there be four atoms and two molecules in an ensemble to be processed. In that case, total of four rows are added, with the ensemble property data cells holding the same data for all four rows, and the molecule property data cells holding two duplicates for two rows each, and every atom data cell the data of one of the four different atoms. As long as all minor objects for which a row is added (with the exception of molecules) are completely contained in exactly one larger object of the involved classes, property types can be freely combined. For example, atom properties and molecule or ensemble properties mix, because every atom is only a member of one molecule and one ensemble. However, the results from combining atom and bond or ring properties are, while still deterministic, probably not useful for any real application. The same is true for a mismatch of the column properties and an explicit object class, i.e. combining atom properties with a bond object class is not likely to be useful.

If the filter list argument is specified, rows are only added for the objects which pass the filter. Those which do not pass the filter are silently skipped. The type of filters which are suitable are usually determined by the selected object class. For example, if a row is added for each atom, atom filters are certainly useful. However, more exotic combinations are possible - for example, atom filters may be used in combination with a mol object class - in that case only data rows for molecules in which one or more atoms pass the filter are added.

Only cells in property and function columns are populated with values by this command. Any cells in pure-data columns without a property descriptor are set to NULL .

By default, the new row or rows are added at the bottom of the table. If desired, a different row index may be given, with index zero resulting in the insertion of the first new row as the first table row, and any additional new rows immediately behind it. The special position end may be used to explicitly append to the table.

By default, the ensemble objects providing the data are preserved, and they remain in their original dataset membership context. The optional mode argument can be set to change their fate. Its possible values are preserve (the default), delete (the ensembles are destroyed after setting the table row data) and move (the ensembles are moved to the internal dataset object of the table). In mode delete , the relationship between rows and the ensemble is not preserved, because the ensemble is gone after the row addition.

The command returns the number of added table rows.

Example:

table addens $th $eh

table addmolfile

table addmolfile tablehandle molfilelist/filenamelist ?objclass? ?filterlist? 	?position? ?mode?
t.addmolfile(molfiles=,?objclass=?,?filters=?,?position=?,?mode=?)

This command performs the equivalent of a table addens or table addreaction command for every ensemble or reaction which can be read from the argument structure file handles. The type of object read from the file, in case there are multiple possibilities, is determined by the configuration of the file handle. Please refer to the section on the table addens and addreaction commands for additional explanations. The command arguments after the file handles are interpreted as in these commands.

Input starts from the current file position of every specified file handle. The command fails if any file cannot be read to the end. The files are positioned at EOF after a successful operation.

If a file handle list argument is not a molfile object handle, an attempt is made to interpret it as the name of a structure or reaction data file. If such a file exists, is readable, and of a recognized file format, it is transiently opened in read-only mode with default settings and automatically closed when the command completes. This is equivalent to the handling of transient files in the molfile command.

Different from the table adddataset/addens/addreaction commands, the default object addition mode of this command is delete . In this mode, the read ensemble or reaction objects are deleted after the table cells have been filled from the current object, so there is no persistent table row association with a structure object. In mode preserve , the ensembles remain in memory, and in mode move , they are also kept, but additionally moved to the internal table dataset. The latter two modes can of course greatly increase the memory requirements, so these modes should not be used indiscriminately.

table addfile is a command alias.

The command returns the total number of added table rows.

table addreaction

table addreaction tablehandle reactionlist ?objclass? ?filterlist? ?position? 	?mode?
t.addreaction(reactions=,?obvjclass=?,?filters=?,?position=?,?mode=?)

Capture data from one or more reactions in a table object. One or more new rows are added, and all table columns for these rows which refer to property data present or computable on the reactions are filled. In addition, a reference is created between the new table rows and the reactions, or, with an ens object class, the reaction ensembles.

If the object class is reaction , a single row is added per reaction and reaction-level property data is copied. Alternatively, it may be specified as ens , which is equivalent to the execution of one table addens command for every reaction ensemble. If this argument is not specified explicitly, or given as an empty string or the special value auto or #auto, it is automatically determined from the column types present. If any data columns are reaction properties, the object class is set to reaction , otherwise ens.

If the filter list argument is specified, only reactions or ensembles which pass the filter are added. Those which do not pass the filter are silently skipped.

By default, the new row or rows are added at the bottom of the table. If desired, a different row index may be specified, with index zero resulting in the insertion of the first new row as the first table row, and any additional new rows immediately behind it. The special position end may be used to explicitly append to the table.

By default, the ensemble objects providing the data are preserved, and they remain in their original dataset membership context. The optional mode argument can be set to change their fates. Its possible values are preserve (the default), delete (the reactions and all their ensembles are destroyed after setting the table row data) and move (the reactions are moved to the internal dataset object of the table). In mode delete , the relationship between rows and the reaction or reaction ensembles is not preserved, since the reaction is gone after the command.

The command returns the number of added table rows.

table addretrieval

table addretrieval tablehandle ?field?...
t.addretrieval(?field?,...)

Add columns to the table, using the syntax of the result retrieval argument of commands such as molfile scan or dataset scan . The modification of the table column set is the same as using a scan command in the to-table result output mode with an existing table as output target. Please refer to the documentation of molfile scan for details on the syntax.

Example:

table addretrieval $th {*}[knode param $kh customretrieval]

This is an example for the preparation of an output table for a Cactvs KNIME node in the configuration function. In the KNIME context, an output table must be fully configured by the configuration script, so this cannot be delegated to the molfile scan command run in the execution script of the node.

table append

table append tablehandle ?property value?...
t.append({?property:value,?...})
t.append(?property,value,?...)

Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.

The command returns the first data value.

Example:

table append $ehandle T_COMMENT “\nI still do not think this data makes sense!”

table assign

table assign tablehandle srcprop dstprop
t.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same table. Both properties must be associated with the table object class. This process is more efficient than going through a pair of table get/table set commands, because in most cases no string or Tcl/Python script object representations of the property data need to be created.

Both source and destination properties may be addressed with field specifications. A data conversion path must exist between the data types of the involved properties. If any data conversion fails, the command fails. For example, it is possible to assign a string property to a numeric property - but only if all property values can be successfully converted to that numeric type. The reverse example case always succeeds, out-of-memory errors and similar global events excluded.

The original property data remains valid. The command variant table rename directly exchanges the property name without any data duplication or conversion, if that is possible. In any case, the original property data is no longer present after the execution of this command variant.

Examples

table assign $th T_IDENT T_NAME

table blockloop

table blockloop tablehandle column rowvariable ?maxblocks? ?offset? body
t.blockloop(column=,function=,?maxblocks=?,?offset=?,?variable=?)

This command is a convenience function for looping over the contents of a table. It is a more complex version of the table loop command. It works on blocks of rows which have the same value in a column instead of a single row.

In the Tcl variant, the contents of one or more rows are stored as a nested list in the global Tcl row variable. The inner objects are either lists that contain one cell data element per table column (with a list table iterator) or dictionaries with column names as keys. In each iteration, after the variable has been updated, the Tcl code in the body argument is executed. The standard Tcl loop control constructs break and continue work as expected within the loop. The iteratorstyle table attribute controls the formatting of the elements of the outer list (i.e. whether this are lists, or dictionaries. The default iterator mode is list.

The length of the nested iteration argument list is determined by the number of consecutive rows which have the same value in the data cell of the block column as the current row. The next iteration of the loop continues with the first row which has a value in the block column data cell that is different from the current value. Note that this command does not sort the table. If the same block column cell value appears in rows which are not consecutive, multiple blocks are processed with the same value. If the block column is an empty string, or the special row name #name , the block membership is determined by the row name.

By default, the iteration continues until the end of the table, but an upper limit may be specified in the optional maxblocks parameter. If this parameter is explicitly set to a negative value, the loop runs to the end of the table. The default starting point of the loop is the first row. This can be changed by giving an explicit offset in the second optional parameter.

The Python version of the loop method does intentionally have a different argument sequence for convenience. The function argument may either be a multi-line string (similar to the Tcl construct), or a function reference. Functions are called with the table reference and a list of current block data rows as two arguments, and have their own context frame, so that the specification of a reference variable is not generally useful in that call style, though is is allowed. For string function blocks the code is executed in the local call frame, and the variable with the current object reference is visible locally. Script code blocks must be written with an initial indentation level of zero. Within the Python functions, the normal break and continue loop control commands cannot be used to to scope limitations. Instead, the custom exceptions BreakLoop and ContinueLoop can be raised. These are automatically caught and processed in the loop body handler code.

Example:

table cluster $thandle E_SCREENING_RESULT jarvispatrick {colname clusters}
table sort $thandle clusters
table blockloop $thandle clusters rowvar {
	foreach row $rowvar {
		lassign $row cpdname clusterid
		...
	}
}

The loop is executed once per cluster with the variable set to the row data block of all structures in that cluster.

The return value of the command is the number of loop iterations processed. The last value of the loop variable remains accessible outside the loop.

The commands table dictblockloop and table listblockloop are variants of this command which ignore the configured iterator style attribute of the table.

table cast

table cast tablehandle dataset/ens/reaction/table ?propertylist?
t.cast(objectclass=,?properties=?)

Transform the table into a different object. With the exception of the table target object class, which does nothing, the table is destroyed in the process. Depending on the target object class, the result is as follows:

If the optional property list is specified, an attempt is made to compute the listed properties before the cast operation, so that they may become a part of the new object. No error is raised if a computation fails.

The command returns the handle or reference of the new object, or the original input object in case of mode table.

table celldata

table celldata tablehandle row column ?value? ?flags?
t.celldata(row=,column=,?value=?,?flags=?)

In the simple form without the optional flags argument, this command is essentially a shortcut for the table setcell and table getcell commands with the value attribute.

If the flags argument is used, setting of the cell data can be modified. The flags argument can be one or more of the following words:

table clear

table clear tablehandle
t.clear()

Reset a table. All rows and columns as well as table-level property data are removed, and user-configurable attributes are reset to default values. However, the table handle remains valid and can be re-used to set up a new table.

The table needs to be editable to allow this command to succeed.

The command returns the table handle.

table clone

table clone srctablehandle ?dsttablehandle? ?columnrangelist?
t.clone(?target=?,?columnranges=?)

Copy the table definition from the source to another table. If a destination table is specified, all cells, rows and columns of the destination table are deleted before the information is copied from the source.

If the destination table handle or reference is omitted, or specified as an empty string (or None for Python ), or the special names new or #auto are used, a new table is created and the command has a similar effect as table dup .

The optional column range list argument can be used to copy only some of the columns. By default, all columns are copied.

This command is similar to table copy, except that no row and cell data is copied. The destination table has the same column layout and other global attributes of the source table, but now rows or cells.

The command returns the handle or reference of the destination table, which may just have been newly created.

table clonecolumns

table clonecolumns srctablehandle columnrangelist dstablehandle ?position?
t.clonecols(?columnranges=?,?target=?,?position=?)

Transfer the definitions of columns in the source table to the destination table.

If the destination table handle or reference is omitted, or specified as an empty string (or None for Python ), or the special names new or #auto are used, a new table is created and the command has a similar effect as table dup .

Different from the table clone command with a column range list argument, the destination table is not reset when this command is run. The transferred column definitions are added to the existing set. In case of column name collisions, the names of the added columns are automatically modified. If the destination table already contained rows, the cells of the new columns are all NULL values. No cell data is copied by this command.

If no position is set, the new columns are appended to the right. Otherwise, they are inserted at the specified position, or, if the position is defined by a column name, to the right of this column.

The short form table clonecols is an alias to this command.

The command returns the handle or reference of the destination table.

table cluster

table cluster tablehandle columnrangelist ?method? ?parameterdict?
t.cluster(columnranges=,?method=?,?parameters=?)

Perform clustering on table data and add the clustering results as an additional table column. The currently supported methods are kmeans, fuzzykmeans, centroid, ward and jarvispatrick . kmeans is the default method. The optional parameter dictionary argument is a standard keyword/value dictionary. Currently the following parameters are recognized:

The data type of the result column depends on the selected clustering method:

Data columns which are used as input data must be convertible into floating-point values. Multiple columns may be used in parallel, but it is the responsibility of the script writer to perform any scaling and other data preparation steps.

The return value is the number of clusters found, after the last iteration or merge step, if applicable.

table compare

table compare tablehandle1 tablehandle2 ?rowmode? ?comparisoncolumn?
t.compare(table2=,?rowmode=?,?comparisoncolumn=?)

This command is a dry-run version of the table merge command. Instead of actually modifying the first table, this command sets the selected row attribute on both tables to indicate which rows from both tables would be present in a new combined table.

The meaning of the parameters are the same as in the table merge command.

table copy

table copy srctablehandle ?dsttablehandle? ?columnrangelist? ?rowmode?
t.copy(?target=?,?columnranges=?,?rowmode=?)

Copy the table definition and table cell data to another table. If a destination table is specified, all cells, rows and columns of the destination table are deleted before the information is copied from the source.

If the destination handle is omitted, or specified as an empty string (or None for Python ), or the special names new or #auto are used, a new table is created and the command has a similar effect as table dup .

The optional column range list argument can be used to copy only some of the columns. By default, all columns are copied.

The default row mode is all, where all source table rows are copied. Other supported modes are selected (only rows for which the selection flag is set are copied) and unselected (only rows for which the selection flag is not set are copied).

A related command is table clone , which also adjusts the column definitions and other attributes of the destination table to match that of the source, but does not transfer row and cell data.

The command returns the handle or reference of the destination table, which may just have been newly created.

table copycolumns

table copycolumns srctablehandle columnrangelist dstablehandle ?position?
t.copycolumns(columnranges=,target=,?position=?)

Transfer the definitions of columns in the source table to the destination table, and also copy the cell content.

The copied column definitions are added to the destination table, which is not reset. In case of column name collisions, the names of the added columns are automatically modified. The number of rows in the destination table is not changed. Existing cell data from the source table is copied to the same row in the destination table. If there are more rows in the source table, the extra source cells are ignored. If there are more rows in the destination table, the extra destination cells have NULL values.

If no position is set, the new columns are appended to the right. Otherwise, they are inserted at the specified position, or, if the position is defined by a column name, to the right of this column.

table copycols is a shortened alias to this command.

The command returns the handle or reference of the destination table.

table copyrows

table copyrows srctablehandle rowrange dsttablehandle ?position?
t.copyrows(rowrange=,target=,?position=?)

Copy a range of rows from one table to another. If no explicit position is given, the new rows are appended to the destination table. The source table retains the copied rows. It is allowed to use this command to duplicate table rows within a single table. The destination table is not required to have the same column layout, just the same column names for matching columns. Columns not present in the destination table are added (with NULL data for existing rows), and the cell order is adapted while copying if necessary. If a pair of columns has no compatible datatype, an attempt at data conversion to the destination column type is made. If that fails, the destination cell is silently set to NULL .

The command returns the handle or reference of the source table.

table create

table create packstring|aid
table create ?property|image|none|enshandle|reactionhandle|datasethandle| 		molfilehandle|tablehandle?...
Table(packstring/aid)
Table.Create(packstring/aid)
Table(?property/image/none/eref/xref/dref/fref/tref?,...)
Table.Create(?property/image/none/eref/xref/dref/fref/tref?,...)

Create a new table. The return value of the command is the new table handle or reference.

The first variant of the command generates a fully initialized table with row and column specifications, cell data and potentially table properties. The single argument can either be a serialized packed table string (see table pack command), or a PubChem assay identifier ( AID ). AID s are simple integers, or integers prefixed with AID or TID . For these, the full assay content is downloaded from PubChem . Depending on the size of the assay, this can take a minute or more. The magic table name pse creates a table with atom information from the periodic system of elements.

Example:

set th [table create 67]

The second variant initially creates an empty table. By supplying additional arguments, one or more columns can be specified in a single statement, and/or ensemble and reaction data added to the specified columns. These are shorthand notations for table addcol or table addens/addreaction/adddataset/addfile commands. Optional arguments that are a property name, or the special names image or none are equivalent to

table addcol $thandle $arg

(one such statement per additional argument) and the chemistry object handle arguments are handled the same way as writing one or more of

table addens $thandle $arg

or

table addreaction $thandle $arg

If a table handle is used as an argument, its column structure and global table properties and attributes, but not its rows and cell data, are copied as with the table clone command.

The Python version accepts both names or handles and references for properties or data source objects.

The full command equivalents of the shortcuts offer more options for control of the row or column addition modes, so this abbreviated command variant can only be only used in simple cases. Ensemble or reaction handles as row data sources should be supplied after column type or table handle arguments, otherwise the cell data of these columns rows already existing when a column is added is set to NULL .

Example:

set th [table create E_NAME E_SMILES E_XLOGP2 E_WEIGHT image $eh1 $eh2]

table data

table data tablehandle ?rowrangelist? ?columnrangelist? ?nullvalue?
t.data(?rowrange=?,?columnrange=?,?nullvalue=?)

Extract cell data from a table as a nested list. By default, the full table content is returned. The optional parameters allow the selection of a specific subset of the rows and/or columns. The final optional parameter can be used to control the output format of Null data. If that parameter is omitted, the global style defined by the undefined table attribute (see table get/set ) is used.

For historical reasons, the variant table print is an alternative name for this command.

Example:

set elements [lsort [table data table0 all symbol]]

This command retrieves an alphabetically sorted list of the atom symbols of the PSE .

table dataset

table dataset tablehandle ?filterlist?
t.dataset(?filters=?)

If the table is a member of a dataset, report the handle or reference of the dataset object. If the table is not a member of a dataset, or does not pass all of the optional filters, an empty string ( None for Python ) is the result.

This command is different from table get $thandle dataset . The latter retrieves the handle of the internal dataset which is an integral part of the table data structure.

table defined

table defined tablehandle property
t.defined(property)

This command checks whether a property is defined for the table. This is explained in more detail in the section about property validity checking. Note that this is not a check for the presence of property data! The table valid command is used for this purpose.

table delcolumns

table delcolumns tablehandle ?columnrange?..
t.delcolumns(?columnrange?,...)

Delete a set of column ranges, including cell data under these columns, from the table. All selected columns are deleted in a single operation, so all column numbers used in the arguments refer to the original table, not those after deletion of column sets defined in arguments to the left in the same command.

The command may also be written as table delcols or table delcol .

The return value is the number of deleted columns.

table delete

table delete ?tablehandle?...
table delete all
t.delete()
Table.Delete(“all”)
Table.Delete(?tref/trefsequence/thandle?,...)

Destroy one or more table objects. The special handle all can be used to remove all deletable tables. Tables with the undeletable status flag (see table set ) are not affected. It is also not possible to delete the three system tables (element data, expansion fragments and SMILES macros). Finally, tables with a reference count of two or more, as they are produced by the definition of table slices, are also not deleted by this command. The referring slice tables need to be removed first before the underlying base table can be deleted.

Objects referenced by table rows, as introduced by table addens or table addreaction commands, are usually not deleted, except when they were put into the internal table dataset object.

The return value is the number of successfully deleted tables.

table delrows

table delrows tablehandle ?rowrange?..
t.delrows(?rowrange?,...)

Delete a set of row ranges, including cell data in these rows, from the table. All selected rows are deleted in a single operation, so all row numbers used in the argument refer to the original table, not those after deletion of rows sets defined in arguments to the left in the same command.

The all range is internally optimized to delete all current rows in one step, and to ignore all other specifications.

The return value is the number of deleted rows.

Example:

table delrows $thandle all

table dget

table dget tablehandle propertylist ?filterset? ?parameterdict?
t.dget(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The difference between table get and table dget is that the latter does not attempt computation of property data, but rather initializes the property values to the default and return that default if the data is not yet available. For data already present, table get and table dget are equivalent.

table dictblockloop

table dictblockloop tablehandle column rowvariable ?maxrows? ?offset? body
t.dictblockloop(column=,function=,?maxblocks=?,?offset=?,?variable=?)

This command is a variant of the table blockloop command. It stores the row data as a dictionary in the loop variable, with the column names as keys. The value of the iterator style table attribute is ignored.

Please refer to the table blockloop command description for more information.

table dictloop

table dictloop tablehandle rowvariable ?rowobjectsvariable? ?maxrows? ?offset? 	body
t.dictloop(function=,?maxrows=?,?offset=?,?variable=?,?objectvariable=?)

This command is a variant of the table loop command. It stores the row data as a dictionary in the loop variable, with the column names as keys. The value of the iterator style table attribute is ignored.

Please refer to the table loop command description for more information.

table dup

table dup tablehandle ?rowrangelist? ?columnrangelist?
t.dup(?rows=?,?columns=?)

Duplicate a table. The return value is the handle or reference of the duplicate. Only the table data content is duplicated, not any table slices which refer to the original, or any ensembles or reactions which hold a reference to the original table. However, such references to ensembles or reactions are copied to the new table, so that the objects refer to both tables simultaneously after the copying. System tables can be duplicated just as any other table.

By default, the full table content is duplicated. The optional parameters can be used to restrict duplication to a row and/or column subset.

This command does not follow the standard dup command syntax of other major objects. It is not possible to move the duplicate table directly into a dataset.

Example:

set thnew [table dup $th]

table dupcolumns

table dupcolumns tablehandle columnrange ?position?
t.dupcolumns(columns=,?position=?)

Duplicate one or more columns, including their cell data, within a table. If the destination, a simple column address, is not specified, the duplicated columns are inserted on the right of the table. The destination cannot be in the range of the source columns.

The command may also be written as table dupcol or table dupcols .

The return value is the new number of columns.

table editcolumn

table editcolumn tablehandle column regexp ?substitution? ?flags?
t.editcolumn(column=,regexp=,?substitution?,?flags=?)

Edit the contents of a table column by performing regular expression matches and substitutions on cells which are not NULL . This also changes the data type of the column to string, which may have indirect consequences (see table setcol .. datatype ).

If the substitution parameter is not supplied, the substitution value is an empty string, i.e. the matched part is removed from the cell data string.

The flags parameter may be a combination of the words

table editcol is an alias of this command.

The command returns the original table handle or reference.

table ens

table ens tablehandle
t.ens()

Return a list of the handles or references of all ensembles which are referenced by the table. Every ensemble is reported only once, even if it is referenced by multiple rows. Rows with ensemble references are usually added to tables my means of the table addens command. In case a row has no ensemble reference, it is ignored, and no output is produced.

table exists

table exists tablehandle ?filterlist?
t.exists(?filters=?)
Table.Exists(tref=,?filters=?)

Check whether a table handle or reference is valid. The command returns boolean 0 or 1. Optionally, the table may be filtered by a standard filter list, and if it does not pass the filter, it is reported as not valid.

table expr

table expr tablehandle expression
t.expr(expression)

Compute a standard SQL -style property expression for the table. This is explained in detail in the chapter on property expressions.

table fill

table fill tablehandle rowrangelist ?columnrangelist? ?unsetonly? ?enshandle? 	?reactionhandle?
t.fill(rows=,?columns=?,?unsetonly=?,?ens=?,?reaction=?)

Set the values of table data cells in the specified row range with data from an ensemble or reaction, for columns that are associated with a property or have another mechanism to compute or retrieve data from a chemistry object. If no column range is specified, the command visits all columns.

If the unsetonly flag is set, only NULL cells are modified and cells where valid data exists are skipped.

If an ensemble or reaction handle or reference is specified as argument, this object takes precedence over a potentially present cell object, or present row object. Otherwise, if there is a suitable cell object, it becomes the data source, and if there is none, the row object assumes this role. If there is also no row object, the command cannot perform any work and all selected cells remain unchanged.

The command can only modify cells in property columns, not pure data or formula columns. The property definition of the column is used to retrieve or compute the new cell data from the data source object. For reaction property columns, an explicit reaction object in the object priority sequence has precedence, and likewise for ensemble or ensemble minor object property columns, an explicit ensemble is preferred. If no directly matching source object is found, a reaction linked to the priority ensemble, or the first reaction ensemble from the priority reaction are used.

The command returns the original table handle or reference.

Note that for tables, there is no (it is rarely used, anyway) standard major object data manipulation command of the same name.

table filter

table filter tablehandle filterlist
t.filter(filters)

Check whether the filter passes a filter list. The return value is 1 for success and 0 for failure.

table find

table find tablehandle column|all operator value ?mode?
t.find(column=,operator=,value=,?mode=?)

The command is very similar to the table select command. The difference is that this command stops the scan after the first matching row was found. Please refer to the section on that command for an explanation of the command arguments.

The command uses index information if the search operation allows it and a column index has been prepared. For large tables, this can make a big difference in search speed.

Example:

set r [table find $thandle E_CID = 5]

The result is the row index of the matching row, or minus one if no such row was found.

table flatten

table flatten tablehandle ?columnrange?
t.flatten(columns=)

This operation simplifies the data types represented in the table. Cactvs table columns can hold any data type the toolkit knows to manage via its data handler modules, including for example vector types, which are generally beyond the scope of traditional table formats.

This command attempts to simplify column types to elementary types, such as strings and numerics. In order to do that, columns with complex data types are split up. For example, a float vector column is replaced by a group of simple float columns, which are inserted immediately to the right of the original column. The number of these columns is determined by the longest vector found in the data cells under the original column, but it is at least one. The names of the new columns are either set to the names of the property fields (for example, for column data of type compound ), or use the original column name with a bracketed suffix, for example E_XYEXTENT(0) . The first suffix is either zero or one, depending on the setting of the offset table attribute (see table get ). The original column with the complex data is deleted. For columns which are already of a simple type, or of a type which is not handled by the current implementation, the command does nothing.

Currently, this function is only implemented for standard vectors (integer and float type vectors, bitvectors, plain and Unicode string vectors) and the special data types compound, choice, intpair, floatpair and intquad . Other complex data types are not processed.

If no column range is specified, all table columns are processed. Table columns which are of an elementary data type are skipped.

The return value is the number of columns after the flattening operation.

table get

table get tablehandle propertylist ?filterset? ?parameterdict?
table get tablehandle attribute
t.get(property=,?filters=?,?parameters=?)
t.get(attribute)
t[property/attribute]
t.property/attribute

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For the use of the optional property parameter list and filter arguments, refer to the documentation of the ens get command.

In addition to retrieving property data, this command is also used to retrieve a large set of attribute values from the table object. Many of these attributes can also be set. Table objects have the following public attributes:

Table attributes which are not marked read-only can be set by the table set command.

Variants of the table get command are table new, table dget, table jget, table jnew, table jshow, table nget, table show, table sqldget, table sqlget, table sqlnew, and table sqlshow . These commands only work on property data and cannot be used to access attributes.

table getcell

table getcell tablehandle row column ?attribute?
t.getcell(row=,column=,?attribute=?)

Get the cell data value, or a cell attribute. The following cell-level attributes are supported:

The attributes image, tag and window are only useful for developers who want to display a Cactvs table in a GUI tool developed with the Tk toolkit and its table widget.

If the last optional command argument is omitted, it is assumed to be value .

table cellget is an alias for this command.

table getcolumn

table getcolumn tablehandle column ?attribute?
t.getcolumn(column=,?attribute=?)

Get data from a specific column. All attributes which can be set (see table setcolumn command), can also be read. In addition, the following attributes can only be read, but not set:

The exists and index attributes allow the specification of non-existing column identifiers. In all other cases, an error is raised if the column cannot be identified.

If the last optional command argument is omitted, it is assumed to be data.

table colget and table getcol are aliases for this command.

Example:

table colget $th mycol
table colget $th mycol data(CHF)

The first form retrieves all column data values in standard format. The second form assumes that the column supports index CHF , which is for example the case if the column data type is currency . In that case, the returned values are automatically converted from whatever original currency it is in.

table getparam

table getparam tablehandle property ?key? ?default?
t.getparam(property=,?key=?,?default=?)

Retrieve a named computation parameter from valid property data. If the key is not present in the parameter list, an empty string is returned ( None for Python ). If the default argument is supplied, that value is returned in case the key is not found.

If the key parameter is omitted, a complete set of the parameters used for computation of the property value is returned in dictionary format.

This command does not attempt to compute property data. If the specified property is not present, an error results.

table getrows

table getrows tablehandle rowrange ?attribute?
t.getrows(rows=,?attribute=?)

Get data from a specific row range. All attributes which can be set (see table setrow command), can also be read. In addition, the following attributes can only be read, but not set:

If the last optional command argument is omitted, it is assumed to be data.

table rowget and table getrow are aliases for this command.

A common error when using this command is to forget that it can return data on multiple rows, and therefore the return value is always nested list. If only a single row needs to be accessed in a statement, and list unwrapping is tedious, the table getrow1 command can be used instead.

table getrow1

table getrow1 tablehandle row ?attribute?
t.getrow1(row=,?attribute=?)

This command is essentially the same as table getrows , but it only accepts a simple single-row identifier, not a row range.

The return value is a simple list for the column values, not a nested list as with table getrows , which can be convenient.

Important: For reasons of backward compatibility, table getrow is an alias for table getrows , not t able getrow1 !

table getparam

table getparam tablehandle property ?key? ?default?
t.getparam(property=,?key=?,?default=?

Retrieve a named computation parameter from valid property data. If the key is not present in the parameter list, an empty string is returned ( None for Python ). If the default argument is supplied, that value is returned in case the key is not found.

If the key parameter is omitted, a complete set of the parameters used for computation of the property value is returned in dictionary format.

This command does not attempt to compute property data. If the specified property is not present, an error results.

table hierarchy

table hierarchy thandle ?filterlist? ?root?
t.hierarchy(?filters=?,?root=?)

Return the hierarchy handle or reference of the hierarchy the table is part of. If the table is not member of a hierarchy, or does not pass all of the optional filters, an empty string or None for Python is returned. By default, the hierarchy object which directly contains the table is returned. If the root flag is set, the root hierarchy object is reported instead, which is the same only if the hierarchy has only a single level.

Example:

table hierarchy $thandle

table index

table index tablehandle
t.index()

Get the position of the table in the object list of its dataset. If the table is not member of a dataset, -1 is returned.

table innerjoin

table innerjoin tablehandle1 tablehandle2 ?column1? ?column2? ?cmpflags?
table join tablehandle1 tablehandle2 ?column1? ?column2? ?cmpflags?
t.innerjoin(table2=,?column1=?,?column2=?,?comparisonflags=?)
t.join(table2=,?column1=?,?column2=?,?comparisonflags=?)

Perform a relational inner join on two tables and return the handle or reference of a newly created join table. The two command variants are aliases.

The source tables remain unchanged. If no explicit table columns are specified, in both tables the first column is used. If only one column name or index is specified, it applies to both tables. With two column names or indices, the first is used to select the join column on the first input table, and the second on the other table.

This command explanation is also referenced by the table object subcommands leftjoin , rightjoin , and outerjoin . This is the reason why the explanation of some command features goes beyond describing exclusively the innerjoin subcommand.

The result table always contains, in this order, the columns of the first table, followed by those of the second table, with the exception of the omitted join column of the second table. The names of columns originating from the second table are adjusted if necessary to avoid duplication of column names in the result table. Data attached to rows on either input table outside of cell values, such as structure or reaction references, are not copied to the output table.

By default, the join condition is a simple equality check on the data of a single column from each table. The data value comparison method may be modified by the last optional argument, for example to use case-insensitive or punctuation-ignorant comparison. The recognized values in this flag set are dependent on the column data types and the same as in the prop compare command. At this time, the fundamental comparison operator is always an equality check - other operators such as less than etc. are not supported. The row values of the join columns are not required to be sorted in either input table. NULL data values in the comparison column never match another data value, even if it also is NULL , following the standard rules of relational algebra. Parallel joining on multiple columns is not yet supported.

The column data types are not required to be identical. If they disagree, an attempt is made to cast the data values of the first table to the datatype of the column of the second table. If that fails, the input row of the first table is skipped and never included in the result table, even in left, right or outer joins.

In an inner join, rows from the first able are omitted in the output if there is no matching column value in the second table. This is always the case if the column value is NULL - a NULL value is never equivalent to another NULL . If either table has more than one matching row for a column value, multiple combined output rows result from that pairing, with all possible combinations of row data blocks (but not individual join column values - these are by definition identical) from either table result.

The table leftjoin , table rightjoin and table outerjoin commands are extensions of the fundamental inner join operation. These generate selected additional rows in the output for rows from the tables which do not match a counterpart in the join column, following the normal relational algebra rules.

table jget

table jget tablehandle propertylist ?filterset? ?parameterdict?
t.jget(property=,?filters=?,?parameters=?)

This is a variant of table get which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects. The command is usable only for property data, not attribute retrieval.

table jnew

table jnew tablehandle propertylist ?filterset? ?parameterdict?
t.jnew(property=,?filters=?,?parameters=?)

This is a variant of table new which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

table jshow

table jshow tablehandle propertylist ?filterset? ?parameterdict?
t.jshow(property=,?filters=?,?parameters=?)

This is a variant of table show which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

table leftjoin

table leftjoin tablehandle1 tablehandle2 ?column1? ?column2? ?cmpflags?
t.leftjoin(table2=,?column1=?,?column2=?,?comparisonflags=?)

Perform a relational left join on two tables and return the handle or reference of a newly created join table. The command arguments and result value are explained in the table innerjoin command.

The difference between a standard inner join and a left join is that rows from the first input table which do not match any values of the join column in the second table are still output, with all column data originating from the second table set to NULL values.

table list

table list ?filterlist?
Table.List(?filters=?)

Without a filter list argument, the command returns a list of the handles of all tables currently existing in the application, including those of the system tables.

If a filter list is specified, only those tables which pass all filters are listed.

Examples:

table list

table listblockloop

table listblockloop tablehandle rowvariable ?maxrows? ?offset? body
t.listblockloop(column=,function=,?maxblocks=?,?offset=?,?variable=?)

This command is a variant of the table blockloop command. It stores the row data as a simple nested list in the loop variable, without column names. The value of the iterator style table attribute is ignored.

Please refer to the table blockloop command description for more information.

For the sake of compatibility with the Python interface syntax, the command may also be invoked as table tupleblockloop .

table listloop

table listloop tablehandle rowvariable ?rowobjectsvariable? ?maxrows? ?offset? 	body
t.listloop(function=,?maxrows=?,?offset=?,?variable=?,?objectvariable=?)

This command is a variant of the table loop command. It stores the row data as a simple list in the loop variable. The value of the iterator style table attribute is ignored.

Please refer to the table loop command description for more information.

For the sake of compatibility with the Python interface syntax, the command may also be invoked as table tupleloop .

table lock

table lock tablehandle propertylist/table/all ?compute?
t.lock(property=,?compute=?)

Lock property data of the table, meaning that it is no longer subject to the standard data consistency manager control. The data consistency manager deletes specific property data if anything is done to the table which would invalidate the information. Blocking the consistency manager can be useful when building tables from components in a script. Property data remains locked until is it explicitly unlocked.

The property data to lock can be selected by providing a list of the following identifiers:

The lock can be released by an table unlock command.

The return value is the table handle.

table loop

table loop tablehandle rowvariable ?rowobjectsvariable? ?maxrows? ?offset? body
t.loop(function=,?maxrows=?,?offset=?,?rowvariable=?,?objectsvariable=?)
for r in t:

This command executes a loop over the rows of a table. On each iteration, the variable rowvariable is set to a list of the cell values of the current row, and then the body argument is executed as script.

For Tcl scripts, within the loop, the standard Tcl break and continue commands work as expected. If the body script generates an error, the loop is exited.

By default, the loop runs from the first row to the end of the table. The optional arguments can be used to set a maximum iteration count, and to change the starting point of the loop. If the maximum iteration count is explicitly set to a negative value, the loop runs to the end of the table.

The content of the row variable is dependent on the configured table iterator style (see iteratorstyle table attribute). It can either be a list, with simple cell values, or a dictionary with column name and cell values. The default is the list style.

If a row objects variable is specified, it contains the handles of the cell objects in the current row, and empty strings ( None for Python ) for those cells without a cell object. The object variable cannot be a string looking like an integer, otherwise the argument will be interpreted as maxrows argument. It is also possible to explicitly skip the argument by using an empty variable name. The reported cell objects are direct references to the cell content and remain locked to the table. They cannot and do not need to be discarded in the loop.

During the execution of the loop, the record table attribute is continuously updated to the current 1-based row number.

The Python version of the loop method does intentionally have a different argument sequence for convenience. The function argument may either be a multi-line string (similar to the Tcl construct), or a function reference. Functions are called with the table handle, 0-based row number, row data tuple or dictionary and the row objects tuple or dictionary as four arguments.

Normal Python functions have their own context frame, and are passed arguments, so that the specification of a loop variables is not generally useful in that call style, though is is allowed. For string function blocks the code is executed in the local call frame, and the variable with the current object reference is visible locally. Script code blocks must be written with an initial indentation level of zero. Within the Python functions, the normal break and continue loop control commands cannot be used to to scope limitations. Instead, the custom exceptions BreakLoop and ContinueLoop can be raised. These are automatically caught and processed in the loop body handler code.

In Python , there is also an object iterator so that simple loops over table rows, with the row data as iterator value, can be written with a for statement. The table object iterator is of the self style (i.e. there is one per table, these are not independent objects), so nesting them is not possible on the same table.

Python object loop constructs and their peculiarities are discussed in more detail in the general chapter on Python scripting.

Example:

table loop $th rowvar {
	echo “Col0: [lindex $rowvar 0] Col1: [lindex $rowvar 1]”
}

The table blockloop command is a more complex variant of this command. It operates on blocks of rows with a common cell value in a column instead of simply stepping from one row to the next.

The table listloop variant of this command always stores the row data as a list in the loop variable. The value of the iterator style table attribute is ignored.

The table dictloop variant of this command always stores the row data as a dictionary in the loop variable, with the column names as keys. The value of the iterator style table attribute is ignored.

There are also rownamedictloop and rownamelistloop variants, which additionally report the name of the current table row.

The return value of the command is the number of loop iterations processed. The last value of the loop variables remain accessible outside the loop, if loop variables were used.

table merge

table merge tablehandle1 tablehandle2 ?rowmode? ?columnmode? ?comparisoncolumn?
t.merge(table2=,?rowmode=?,?columnmode=?,?comparisoncolumn=?)

Merge two tables into one. The first table is updated. The second table remains valid and retains all its data. It is not possible to merge a table with itself.

The first table will usually be subject to row and column updates. What kind of updates are performed is determined by the row and column modes. The row mode can be one of:

The comparisoncolumn parameter determines which column is used to check for duplicate rows. By default, it is #name , i.e. the row name is used instead of real column data. For tables without explicit row names, this is equivalent to the row index. For tables which were generated by direct output from the molfile scan command, it has been automatically set to the matched file record number. Query result tables from the same file can therefore be merged easily. Instead of the row name, any cell data of a real column in the first table may be used for identity checks. However, this column must have an equivalent in the second table, or an error results.

The column mode determines which column definitions from the second table are added to the first table, and whether any columns on the first table are deleted if there is no corresponding column in the second table. The supported column modes are:

The order of the columns on the two merged tables is not important for property columns. Column matching uses property definitions and field indices to find equivalent columns regardless of their name. Pure data columns without property definitions require a matching name and data type in order to be perceived as equivalent. The column modes left , intersect and union are most often used. If the two tables have identical column sets, the merge result are the same in all these modes.

If property T_QUERY is valid on both tables, and it describes a query on the same data source, it is updated on the first table to represent a single query which would yield the results of the merged table. This is done by manipulating the query tree in that property by combining the old two trees under a suitable logical operator such as and or or . This is intended to facilitate convenient management of query results in tables, as they are, for example, produced by a molfile scan command with direct table output.

table metadata

table metadata tablehandle property ?field ?value??
t.metadata(property=,?field=?,?value=?)

Obtain property metadata information, or set it. The handling of property metadata is explained in more detail in its own introductory section. The related commands table setparam and table getparam can be used for convenient manipulation of specific keys in the computation parameter field. Metadata can only be read from or set on valid property data.

Valid field names are bounds , comment , info , flags , parameters and unit .

table move

table move tablehandle ?datasethandle|remotehandle? ?position?
t.move(?target=?,?position=?)

Make a table a member of a dataset, or remove it from a dataset. If the dataset handle parameter is omitted, or an empty string (or None for Python ), the object is removed from its current dataset. If it was not a dataset member, this command variant does nothing. The dataset handle may be the name of a remote dataset for moving objects over a network connection.

If a target dataset handle or reference is specified, the object is added to the dataset, if allowed by the acceptance bits of the dataset, and removed from any dataset it was member of before the execution of the command. By default the object is added to the end of the dataset object list, but the final optional parameter allows the specification of a dataset object list index. The first position is index zero. If the parameter value end is used, or the index is bigger than the current number of dataset objects minus one, the object is appended as per the default. It is legal to use this command for moving objects within the same dataset.

Another special position value is random . This value moves to the object to a random position in the dataset. Using this mode with remote datasets is currently not supported.

The dataset handle cannot be a transient dataset. It is not possible to move a table into its own built-in dataset.

The return value of the command is the dataset of the object prior to the move operation. It is either a dataset handle/reference, or an empty string ( Tcl ) or None ( Python ) if it was not member of a dataset

Examples:

table move $thandle $dhandle 0
table move $thandle

In the first sample line, the table is inserted as the first element in a dataset. The second line reverts this operation and removes the table from the dataset.

This command can be used with a remote dataset descriptor. In that case, the table is packed into a serialized object representation, transmitted over the network and restored as member of the remote dataset at the specified position. The local table is deleted if the transfer succeeds.

table movecolumns

table movecolumns tablehandle columnrange ?destination?
t.movecolumns(columnrange=,?destination=?)

Move one or more columns including their cell data within a table. If the destination, a simple column address, is not specified, the selected columns are moved to the right of the table. The destination cannot be in the range of the source columns.

The command may also be written as table movecol or table movecols .

The command returns the original table handle or reference.

table moverows

table moverows tablehandle rowrange ?destination?
t.moverows(rowrange=,?destination=?)

Move one or more rows, including their cell data within a table. If the destination, a simple row address, is not specified, the selected rows are moved to the bottom of the table. The destination cannot be in the range of the source rows.

The command may also be written as table moverow .

The command returns the original table handle or reference.

table mutex

table mutex tablehandle mode
t.mutex(mode)

Manipulate the object mutex. During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing. This command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes:

There is no trylock command variant because the command already needs to be able to acquire a transient object mutex lock for its execution.

The command returns the current lock count.

table need

table need tablehandle propertylist ?mode? ?parameterdict?
t.need(property=,?mode=?,?parameters=?)

Standard command for the computation of property data, without immediate retrieval of results. This command is explained in more detail in the section about retrieving property data.

The return value is the original table handle or reference.

Example:

table need $th T_XYPLOT recalc

table new

table new tablehandle propertylist ?filterset? ?parameterdict?
t.new(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The difference between table get and table new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

table nget

table nget tablehandle propertylist ?filterset? ?parameterdict?
t.nget(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The difference between table get and table nget is that the latter always returns numeric data, even if symbolic names for the values are available.

table nnew

table nnew tablehandle propertylist ?filterset? ?parameterdict?
t.nnew(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data and attributes. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The difference between table get and table nnew is that the latter always returns numeric data, even if symbolic names for the values are available, and that property data re-computation is enforced.

table normalize

table normalize tablehandle column ?singlerow?
t.normalize(column=,?singlerow=?)

Normalize a table column with numerical data to an average value of zero and a standard deviation of one.

If the data type of the column is a floating-point vector type (vectors of floats or doubles), and the singlerow flag is set, the normalization is performed individually on each vector in the cells of the selected column and not over all rows together.

The return value of the command is a list of the offset and scaling factors used to normalize the data column, in that order. In case the singlerow command variant was used, the return value is a list of these number pairs with one list element per row.

If the command is used on float or double vector columns in normal mode, all vector elements are treated as independent data values.

It is possible to normalize integer-type columns. However, since this command does not change the data types of the columns, only the offset and scaling values are reported but the column data is not changed because this cannot be done in a reasonable fashion.

Any attempt to normalize non-numeric columns results in an error.

table outerjoin

table outerjoin tablehandle1 tablehandle2 ?column1? ?column2? ?cmpflags?
t.outerjoin(table2=,?column1=?,?column2=?,?comparisonflags=?)

Perform a relational outer join on two tables and return the handle or reference of a newly created join table. The command arguments and result value are explained in the table innerjoin command.

The difference between a standard inner join and an outer join is that rows from either the first input table which do not match any values of the join column in the second table, or from the second input table which do not match any values of the join column in the first table, are still output, with all column data originating from the respective other table set to NULL values. The outer join is a fusion of a left and right join.

table pack

table pack tablehandle ?rowrangelist? ?columnrangelist? ?maxsize? 	?compressionlib?
t.pack(?maxsize=?,?rows=?,?columns=?,?compressionlib=?)

Pack the table into a compressed, base64-encoded, serialized object string. This string can be used with a table unpack command to restore the table.

By default the full table is packed, but the optional range parameters, which are both range lists, can be used to pack a subset of the table.

The maximum size of the object string (default -1, meaning unlimited size) can be configured by the optional maxsize parameter. The size is specified in bytes. If the pack string would be longer than the maximum size, an error results.

Note that this command does not pack ensembles or reactions which are associated with a table. If a table is restored, this linkage is lost.

The default compression library is zlib . Other useful variants include lzo and gzip (and there are other internal types), but these may not be available on all builds due to license issues, and you need to specify the compression library when a dataset is unpacked. It is generally recommended to stay with zlib .

The command returns the pack string.

In Python , tables support the standard pickle / unpickle protocol.

Example:

set ts [table pack table0 {F Cl Br I} {vdwradius covradius}]

This command copies the Van der Waals and covalent radii of the halogens from the PSE table into a pack string. The string can be restored to a subset table with a

set thnew [table unpack $ts]

table poploop

table poploop tablehandle ?mode? varname ?objvarname? body
t.poploop(function=,?mode=?,?rowvariable=?,?objectsvariable=?)

Perform the table poprow command (see below) in a loop. The loop is repeated until no more rows can be extracted from the table. In each iteration, the extracted table data is stored in the specified variable, the row is deleted, and the code in the body executed. If execution of the body code results in an error, the loop is stopped immediately.

If an object variable name is specified, it contains a list or dictionary of the handles of the cell objects in the current row, with empty strings ( None for Python ) as elements for cells which do not possess a cell object. These objects are unlinked from the current row and are no longer associated with the table. It may be necessary to dispose them in the loop if they are not linked to other controlling objects or moved to, for example, a target dataset.

In the Tcl interface, the loop can be left early without raising an error by executing a standard Tcl break or return loop control command in the body.

The Python version of the loop method does intentionally have a different argument sequence for convenience. The function argument may either be a multi-line string (similar to the Tcl construct), or a function reference. Functions are called with the table object reference, the row data tuple or dictionary and the row objects tuple or dictionary as three arguments.

Normal Python functions have their own context frame, and are passed arguments, so that the specification of loop variables is not generally useful in that call style, though is is allowed. For string function blocks the code is executed in the local call frame, and the variable with the current object reference is visible locally. Script code blocks must be written with an initial indentation level of zero. Within the Python functions, the normal break and continue loop control commands cannot be used to to scope limitations. Instead, the custom exceptions BreakLoop and ContinueLoop can be raised. These are automatically caught and processed in the loop body handler code.

There is no Python iterator for this loop style.

The possible values of the optional mode argument are the same as in the table poprow command, as is the default mode list .

The command is thread-aware and will enter a wait loop until the EOR condition on the table has been met, so that other threads may fill the table.

The return value is the number of rows processed. The last value of the loop variables remain accessible outside the loop, if loop variables were used.

table poprow

table poprow tablehandle ?mode?
t.poprow(?mode=?)

Remove the first row of the table and return its content as result. The form of the result can be modified by the optional mode parameter. Its possible values are:

For this command to work, the table needs to be editable. If there are no more table rows, an empty result is returned. If the table has an active background import thread, the command blocks until the import thread has added another row, or has terminated.

The command may be abbreviated as table pop .

table properties

table properties tablehandle ?pattern? ?noempty?
t.properties(?pattern=?,?noempty=?)

Return a list of the valid properties on the table object. If desired, the property list can be filtered by the optional string match pattern. Since tables incorporate no minor objects, only true table properties (standard prefix T_ ) are listed. Properties of ensembles or reactions associated with the table are not output because these are not component objects, just cross-references.

If the noempty flag is set, only properties where at least one data element is not the property default value are output. By default, the filter pattern is an empty string, and the noempty flag is not set.

The command may also be written as short form table props .

Example:

set plotproplist [table props $th T_*PLOT*]

table purge

table purge tablehandle propertylist/table ?emptyonly?
t.purge(?properties=?,?emptyonly=?)

Delete property data from the table. In contrast to performing property deletions on, for example, ensembles this operation does not branch out to properties which are stored on objects linked to the table. Ensemble or reaction references are not traversed because they are not true container object memberships.

This command only deletes proper table properties (usually starting with T_). If the object class name table is used instead of a property name, the data of all table properties is deleted.

The optional boolean flag emptyonly restricts the deletion to those properties where the value of a property is identical to the default.

table randomize

table randomize tablehandle ?seed?
t.randomize(?seed=?)

Shuffle the rows of the table in a pseudo-random fashion. If the seed argument, an integer, is provided, it is used to seed the random generator. If the command is called the first time without a seed, the current time stamp is automatically provided as seed and the random number sequence becomes unpredictable. Subsequent calls of the command without a seed parameter continue with the random number sequence defined by the seed, until the command is again called with a seed argument. The random generator is then re-seeded and the number sequence specific to the seed is re-started.

This command is useful for testing the robustness of algorithms with respect to data ordering.

The command returns the original table handle or reference.

table rank

table rank tablehandle ?method? ?{column ?direction ?cmpflags??}?..
t.rank(?method?,?(column,?direction,?cmpflags)???,...)

Rank the table rows according to data in specific columns. The command returns a list of the individual ranks of the rows, with one numeric list item per row and in order of the rows. It does not sort the table.

There are three different ranking schemes:

The rest of the optional arguments select the columns to use for ranking, and the comparison operations used to determine the rank. Each argument is a list of one to three elements. The first list element, the column name, is mandatory. The special column name #name can be used to use the row name as criterion, #row or #record for the row number, and #random or #rnd as tiebreaker.

If the second element of a rank specification is not supplied, the sort direction for rank comparisons is up , meaning that lower values imply a higher (numerically lower) rank. The sort order can also be specified as down , which inverts this.

Finally, the comparison operation can be influenced by providing a list of comparison flags. These the same as used with the prop compare command.

In case multiple comparison columns are given, columns to the left have precedence over columns to the right.

Not specifying any comparison column is syntactically allowed, but reports all rows as of the same rank.

table reactions

table reactions tablehandle
t.reactions()

Return a list of the handles or references of all reactions which are referenced by the table. Every reaction is reported only once, even if it is referenced by multiple rows. Rows with reaction references are usually added to tables my means of the table addreaction command. In case a row has no reaction reference, it is ignored, and no output is produced.

table read

table read filename ?parameter value?...
table read filename ?dictionary?
Table.Read(filename,?parameter,value?,...)
Table.Read(filename,?dictionary?)

Read a table file into a newly allocated Cactvs table object and return the handle or reference of the new table if the operation succeeded. The column data types and other attributes of the new table are set appropriately according to the data found in the file. This is even true for pure ASCII text tables, because an attempt is made to promote the column formats to integers, floats or booleans after the data has been read initially as strings, if the data content allows the conversion.

Besides a normal file name, it is also possible to specify stdin as magic file name to read from standard input, or a pipe by starting the file name argument with the “|” character. If a normal file is used, and the suffix cannot be identified by the currently loaded table file format I/O handlers, an attempt is made to auto-load a handler by constructing a standard module name from the suffix (see tablex command for more information about table file format handlers). Additionally, some URL formats, such as http(s):// , (s)ftp:// and gs:// ( Google storage) are also recognized as file names. For these formats, the file is automatically temporarily downloaded, read, and again deleted from local disk space. Access credentials can be embedded in the URL in standard fashion.

For normal disk files, but not when reading from stdin , pipes or URL s, the file format is automatically detected by looking into the file content, independently of the file suffix. This is done by invoking in reverse load order the detection function of all currently loaded table I/O modules and the built-in handlers. For build-in table handlers, but only for those, such as the simple separator-controlled text table dumps, the table file may be gzip -compressed (but not bz2 , etc.), and the format is still auto-detected. For other table disk files, the presence of gzip or bz2 compression is detected, but no automatic format detection takes place behind the compression layer. These files can still be read without prior decompression by explicitly stating the format in the argument dictionary.

Additional optional parameters to control the input can be specified either as a number of keyword/value argument pairs, or a single dictionary argument. The recognized control keywords are the same for both variants.

If a read table file contains, besides the cell data, structure or reaction object data, as it is possible for example with native Cactvs or KNIME table files, these objects are automatically read and moved into the internal table dataset object. Proper row references to these objects are also established.

table load is an alternative command name.

Example:

set th [table read $file colnames 1 separator “!”]

This reads a slightly unusual ASCII table with exclamation marks as separators, and column names in the first row.

table readblob

table readblob data ?parameter value?...
table readblob data ?dictionary?
Table.Readblob(data,?parameter,value?,...)
Table.Readblob(data,?dictionary?)

This command is the same as the table read command, except that is reads from an in-memory blob instead from a file. If the responsible table I/O module for the table file format does not support in-memory decoding, a temporary file is automatically created and removed after reading.

Currently, automatic format detection of in-memory table data does not work in some cases, or forces the inefficient use of a temporary file. It is advisable to specify an explicit file format in the optional arguments to avoid this problem.

table loadblob is an alternative command name.

table recalc

table recalc tablehandle ?rowrangelist? ?columnrangelist?
t.recalc(?rows=?,?columns=?)

Recompute the values of all cells which are linked to column computation functions in the specified block. The default re-computation block is the complete set of rows and columns. This command does not affect cell data which is not linked to a function.

The return value is a boolean status code indicating whether all requested values could be computed.

table ref

Table.Ref(identifier)

Python only method to get a table reference from a handle or another identifier.

table rename

table rename tablehandle srcproperty dstproperty
t.rename(srcproperty=,dstproperty=)

This is a variant of the table assign command. Please refer the command description in that paragraph.

table replot

table replot tablehandle ?rowrange? ?columnrange?
t.replot(?rows=?,?columns=?)

Replot structure and reaction images embedded in the table. The default replot block is the complete set of rows and columns. The command only affects data cells of columns of type image .

The command returns the original table handle or reference.

table rewind

table rewind tablehandle
t.rewind()

Reset the table iterator record. This is equivalent to setting the record table attribute to one.

The command returns the original table handle or reference.

table rightjoin

table rightjoin tablehandle1 tablehandle2 ?column1? ?column2? ?cmpflags?
t.righjoin(table2=,?column1=?,?column2=?,?comparisonflags=?)

Perform a relational right join on two tables and return the handle or reference of a newly created join table. The command arguments and result value are explained in the table innerjoin command.

The difference between a standard inner join and a right join is that rows from the second input table which do not match any values of the join column in the first table are still output, with all column data originating from the first table set to NULL values.

table rownamedictloop

table rownamedictloop tablehandle rowvariable ?rowobjectsvariable? ?maxrows? 	?offset? body
t.rownamedictloop(function=,?maxrows=?,?offset=?,?rowvariable=?,	?objectsvariable=?)

This command is a variant of the table loop command. It stores the row data as a dictionary in the loop variable, with the column names as keys. In addition, the dictionary key rowname holds the name of the current table row. The value of the iterator style table attribute is ignored.

Please refer to the table loop command description for more information.

table rownamelistloop

table rownamelistloop tablehandle rowvariable ?rowobjectsvariable? ?maxrows? 	?offset? body
t.rownamelistloop(function=,?maxrows=?,?offset=?,?rowvariable=?,	?objectsvariable=?)

This command is a variant of the table loop command. It stores the row data as a simple list in the loop variable. The first list element is the name of the current row. The value of the iterator style table attribute is ignored.

Please refer to the table loop command description for more information.

For the sake of compatibility with the Python interface syntax, the command may also be invoked as table rownametupleloop .

table scan

table scan tablehandle expression ?mode? ?parameterdict?
t.scan(query=,?mode=?,?parameters=?)

This command is a variation of the dataset scan or molfile scan commands. The query expression is matched, in row order, on all ensemble or reaction objects associated with the table rows, i.e. the same objects as reported by the table ens and table reactions commands. An attempt is made to automatically instantiate these objects if a row currently has no association, but a structure source column has been configured via the structuresource or reactionsource attribute. Rows which do not possess a structure or reaction reference even after this attempts are skipped and can never return a match.

The default retrieval mode for this scan command variant is rowlist , which is an alias of the indexlist mode of dataset scans. In this mode, matching row indices are returned as a list. If an ensemble or reaction is associated with multiple rows, it is tested repeatedly for every row it is associated with.

For further information on the operation of this command and the use of the various arguments, refer to the paragraph on dataset scan .

The optional parameter dictionary is the same as for molfile scan , but not all parameters are actually used. At this time, only the matchcallback, maxhits, maxscan, order, progresscallback, progresscallbackfrequency, sscheckcallback, startposition and target parameters have an effect. In case a progress callback function is used, the table handle is passed as argument in place of the molfile handle in molfile scan .

This command does not operate on table cell data, but exclusively on the associated structures, reactions, and their present or computable data. For queries on table cell data, use the table find command. However, the delete query mode of this command does indeed remove matching table rows, not delete the associated objects.

table select

table select tablehandle column|all operator value ?mode?
t.select(column=,operator=,value=,?mode=?)

Perform a scan over the table and mark all rows which match a value. This command processes multiple matches. For a simple version of the command which stops after the first match, see table find.

The default mode is new , which resets all current select flags on the rows before running the command. The alternative modes are or , which just sets additional flags, and , which resets the selection flag for rows which are currently selected but not pass the new expression, and eor or xor , which invert the selection flag on all rows which are matched.

The column argument is either the name or index of an existing table column, or the magic word all , which runs the scan on all columns. There is currently no support for scans which use more than one, but not all columns. The special column name #name to test the row names is also supported.

For single-column scans, the value argument needs to be a string which can be decoded as the data type of the scanned column. For all scans, the argument is parsed separately for each column. Only columns where the data successfully decodes according to their data type are searched. Other columns where the value argument cannot be parsed are silently skipped.

The operator argument is a standard arithmetic operator, optionally modified by either single-character modifier flags, or specified as a list with the symbolic names of these modifier flags. The syntax of this argument is compatible to that of property query leaf expressions of the molfile scan command. The operators in and notin are also supported. In that case, the value argument must be a valid list. The list is split, and each element parsed and matched separately. For the in operator, rows where any of the multiple elements match with an equality comparison are selected. For a notin match, none of the elements must match in an equality comparison.

Examples:

table select $thandle E_NAME *= “*chloro*”
table select $thandle E_NAME {= shell} “*chloro*”
table select $thandle E_WEIGHT <= 200
table select $thandle SID in [ens get $eh E_SIDSET]

The first two sample statements are equivalent and both perform a shell-syntax string match on the column E_NAME , matching any data which contains the substring chloro . The third example performs a simple numeric comparison, and the last example tests whether the SID column data value is one of a list of alternatives.

The result is a list of the row indices of all selected rows after the operation. In addition, the selection attribute on matched rows is set and can be queried by attribute retrieval commands.

This command has limited power in the types of comparison operations it supports. For a more extensive search capability please refer to the table sqlselect command. However, in many cases this simpler command is much faster than the SQL version, especially if it operates on columns with indices and uses a search operator which can make use of the index information.

This command does not support data access via linked ensembles or reactions. It can only test cell data directly stored in the table.

table set

table set tablehandle ?property/attribute value?...
table set tablehandle ?dictionary?
t.set(property/attribute,value,...)
t.set({property/attribute:value,...})
t.property/attribute = value
t[property/attribute] = value

Standard data manipulation command. It is explained in more detail in the section about setting property data.

Examples:

table set $thandle T_COMMENT “This data, if leaked in an appropriate fashion, will lead to the waste of years of research by our competitors”

The command can also be used to set a rich set of table attributes. The list of attributes is documented in the section on the table get command.

Example:

table set $thandle bgcolor “grey80” imagedirectory “/www/images” imageurl “.”

table setcell

table setcell tablehandle row column ?attribute value?...
table setcell tablehandle row column value
t.setcell(row,column,?attribute,value?,...)
t.setcell(row,column,value)
t.setcell(row,column,{attribute:value,...})
t.setcell(row,column,(attribute,value,...))

Set the cell data value, or a cell attribute. The second form is a shortcut for setting the cell data value and equivalent to using an explicit value attribute name. In the Python variant, the attribute set can also be specified as a dictionary.

The following cell-level attributes are supported:

The attributes image , tag and window are only useful for developers who want to display a Cactvs table in a GUI tool developed with the Tk toolkit and its table widget.

The command returns the original table handle or reference.

table setcolumn

table setcolumn tablehandle column ?attribute value?...
t.setcolumn(column,?attribute,value?,...)
t.setcolumn(column,{attribute:value})
t.setcolumn(column,(attribute,value,...))

Set column attributes. The following column-level attributes can be set:

The command returns the original table handle or reference.

table setcol and table colset are command aliases.

table setparam

table setparam tablehandle property ?keyword value?...
table setparam tablehandle property dictionary
t.setparam(property,?key,value?...)
t.setparam(property,dict)

Set parameter values in the metadata section of existing property data attached to the table. This command does not change the parameters for computations in the property definition (see prop setparam command for this function). It only stores its data in the parameter set which was copied into the metadata when the property was computed for the table.

This command does not attempt to compute property data. If the specified property is not present, an error results.

table setrow

table setrow tablehandle rowrange ?attribute value?...
t.setrow(rowrange,?attribute,value?,...)
t.setrow(rowrange,{attribute:value,...})
t.setrow(rowrange,(attribute,value,...))

Set row attributes for one or more table rows. The following row-level attributes can be set:

The command returns the original table handle or reference.

table rowset is an alias.

table show

table show tablehandle propertylist ?filterset? ?parameterdict?
t.show(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The difference between table get and table show is that the latter does not attempt computation of property data, but raises an error if the data is not present and valid. For data already present, table get and table show are equivalent.

table sort

table sort tablehandle ?{column ?direction ?cmpflags ?cmpvalue???}?...
t.sort(?(column,?direction,?cmpflags,?cmpvalue)????,...)

Sort the rows of a table according to the cell values in one or more columns. Every sort criterion argument after the table handle argument is a list or tuple of between one and four elements. In the simplest case, it is just the name of a single column. Additionally, a sort direction ( up or down , the default is up) can be specified, plus comparison flags. The comparison flags argument supports the same set of flags as in the prop compare command and is explained there in detail.

If a comparison value is supplied as fourth argument, the sort utilizes the comparison results of cell values against this value for ranking, not the direct comparison result between the cell values. This is for example useful when sorting according to a bitvector similarity value to an external structure.

Sort columns to the left in the column specification list have precedence over those on the right. The special column name #name or #rowname can be used to sort on the row names, #row (or #record ) to sort on the row number, and #random to sort on a random value assigned to every row, effectively duplicating the table randomize command. The row number criterion is also always added implicitly as an additional rightmost sort column to yield a stable sort. If an unstable sort is required, add a final explicit #random sort column, which has precedence over the implicit row number sort.

The command returns the original table handle or reference.

table split

table split tablehandle row
t.split(row)

Split a table into two. The original table retains all data rows up to, but not including, the split row. A new table with the same basic attributes, properties and column layout is created and gets the rest of the original data.

The command returns the handle or reference of the new table.

table splitcolumn

table splitcolumn tablehandle column ?separators? ?separatormerge?
t.splicolumn(column=,?separators=?,?separatormerge=?)

Split a table column into multiple result columns. This also changes the table column data type to string, which can have indirect consequences (see table setcol .. datatype ).

The default split characters are whitespace. If the separator argument is set, every character in the separator string is an equivalent split character. It is also possible to set the separator to an empty string, which performs splits of cell data into individual characters. By default, every encountered separator character defines a new split position. The the merge flag is set to true, every sequence of separator characters is a split position instead. For example, a series multiple white spaces in the input then defines only a single word split, not multiple splits producing some empty result words.

The original split column retains the first result word after the split. Additional columns are inserted to the right of the source column, with the cell which contains the largest number of words defining the total number of columns added. NULL cells are not split, and result cells in added columns for which no split word was found because there are less words in the source cell than in the cells with the largest number of words, or the source cell is NULL , are also set to NULL .

The return value is the number of columns added, which is one less than the largest number of words found in a cell, if there were any non- NULL cells.

table splitcol and table colsplit are command aliases.

table sqldget

table sqldget tablehandle propertylist ?filterset? ?parameterdict?
t.sqldget(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The differences between table get and table sqldget are that the latter does not attempt computation of property data, but initializes the property value to the default and returns that default, if the data is not present and valid; and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

table sqlfind

table sqlfind tablehandle query ?maxrows? ?offset? ?mode?
t.sqlfind(query=,?nmax=?,?offset=?,?mode=?)

This command is very similar to the table sqlselect command, except that the query execution stops after the first matched row.

The result is the index of the matched row, or minus one in case no row matches.

table sqlget

table sqlget tablehandle propertylist ?filterset? ?parameterdict?
t.sqlget(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The difference between table get and table sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

table sqlnew

table sqlnew tablehandle propertylist ?filterset? ?parameterdict?
t.sqlnew(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The differences between table get and table sqlnew are that the latter forces re-computation of the property data, and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

table sqlselect

table sqlselect tablehandle query ?maxrows? ?offset? ?mode?
t.sqlselect(query,?nmax=?,?offset=?,?mode=?)

Perform a SQL -style select operation on the table and set the selected row flags depending on whether the row was selected by the query. This command yields multiple matches. For a simple version of the command which stops after the first match, see table sqlfind.

The default mode is new , which resets all current select flags on the rows before running the command. The alternative modes are or , which just sets additional flags, and , which resets the selection flag for rows which are currently selected but not pass the new expression, and eor or xor , which invert the selection flag on all rows which are matched.

By default the number of selected rows is unlimited. This can be explicitly requested by setting the first optional parameter to a negative value. Any positive value stops the execution of the command after the specified number of matched rows have been processed. The second optional parameter is the index of the first row where processing starts. The default is zero, meaning that the table scan is started at the top.

The expression argument is an SQL expression which checks cell values. The syntax of this expression is that of the where clause of an SQL statement. The syntax is compatible to the SQL dialect used in the MySQL database. Almost all SQL functions that database provides in the 4.1 release can be used here, including aggregate functions and function columns which are dynamically computed. However, only columns in the local table can be used. Cross-referencing to other tables is not supported.

Example:

table sqlselect $thandle “E_WEIGHT>avg(E_WEIGHT) and E_NROTBONDS<5”

where E_WEIGHT and E_NROTBONDS are either the names of existing table columns, or the table has retained active row references to ensembles. In case a reference is used, the data is obtained indirectly by reading existing property data from the linked ensemble, or even by computing it on the fly. This type of ensemble- or reaction-linked computation is only possible for column names which can be identified as properties. Existing table columns which are used in the expression can be property columns, function columns, or simple data columns. The use of existing columns has precedence over references, even if the cell data is, for example, NULL and not identical to what would be obtained from the structure object.

Ensemble or reaction references in rows are conveniently introduced by using table addens or table addreaction commands to fill the rows. They are silently lost if the ensembles or reactions which provided the data are deleted from memory. It is possible to save tables in the native Cactvs format with all reference objects, so that they could be restored from a file, but this is not the default. Normally, tables lose object references when written to file and re-read.

The result is a list of the row indices of all selected rows after the operation.

This command is very powerful, but can be overkill in many circumstances. For a simpler, and in many cases faster, alternative refer to the table select command.

table sqlshow

table sqlshow tablehandle propertylist ?filterset? ?parameterlist?
t.sqlshow(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the table get command. The differences between table get and table sqlshow are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

table string

table string tablehandle ?format? ?parameter value?...
table string tablehandle ?format? ?dictionary?
t.string(?format?,?parameter,value?,...)
t.string(?format?,?dict?)

Encode the contents of the table as a blob image of an file of the specified format. Except that the output goes to a blob instead of a file, this command is the same as table write .

The result value is a byte vector, not a string, so this command can be used with binary table formats.

table subcommands

table subcommands
dir(Table)

Lists all subcommands of the table command. Note that this command does not require a table handle.

table transfer

table transfer tablehandle propertylist ?targethandle? ?targetpropertylist?
t.transfer(properties=,?target=?,?targetproperties=?)

Copy property data from one table to another table or other major object, without going through an intermediate scripting language object representation, or dissociate property data from the table. If a property in the argument property list is not already valid on the source table, an attempt is made to compute it.

If a target object is specified, the return value is the handle or reference of the target table. The source table and the target object cannot be the same object.

If a target property list is given, the data from the source is stored as content of a different property on the target. For this, the data types of the properties must be compatible, and the object class of the target property that of the target object. No attempt is made to convert data of mismatched types. In case of multiple properties, the source property list and the target property list are stepped through in parallel. If there is no target property list, or it is shorter than the source list, unmatched entries are stored as original property values, and this implies that the object class of the source and target objects are the same.

If no target object is specified, or it is spelled as an empty string or Python None , the visible effect of the command is the same as a simple table get , i.e. the result is the property data value or value list. The property data is then deleted from the source object. In case the data type of the deleted property was a major object (i.e. an ensemble, reaction, table, dataset or network), it is only unlinked from the source object, but not destroyed. This means that the object handles or references returned by the command can henceforth the used as independent objects. They can be deleted by a normal object deletion command, and are no longer managed by the source object.

table transfercolumn

table transfercolum tablehandle srcolumn dstcolumn ?target?
t.transfercolumn(srccolumn=,dstcolumn=,?target=?)

Transfer column data to another data column, or auxiliary cell data field. The data transfer operation attempts casting of the source value to the datatype of the destination - either the column datatype, or a string for the auxiliary cell values. If a cast fails, the cell data is a NULL value without an error message. The original data remains unchanged. The source and destination column may be identical, and this can be useful if the target is not the cell value. When casting to a string for the auxiliary cell fields, the string is formatted according to the format set on the table, column, row and cell level.

The transfer target can either be data (the column data, which is the default), comment (cell comment) or linktext (the text output instead of the actual underlying link destination when writing table files which support links, such as HTML , MS Word or PDF .

The return value is the table handle or reference.

table trim

table trim tablehandle ?positions?
t.trim(?positions=?)

Remove leading or trailing table rows or columns where all cells have NULL values. If no position argument is specified, both rows and columns are processed. This is equivalent to the positions argument all. Alternatively, location values columns (only columns are processed), rows (only rows are processed), or a list of left (leading columns), right (trailing columns), top (leading rows) and bottom (trailing rows) are recognized.

This command only processed leading or trailing rows or columns. Empty rows or columns which are embedded in the middle of the table are not removed.

This command is useful for quickly cleaning up tables with spurious extra empty rows or columns, as they are often found in Excel spread sheets and similar sources.

The command returns the original table handle or reference.

table unlock

table unlock tablehandle propertylist/table/all
t.unlock(property=)

Unlock property data for the table, meaning that they are again under the control of the standard data consistency manager.

The property data to unlock can be selected by providing a list of the following identifiers:

Property data locks are obtained by the table lock command.

The return value is the original table handle or reference.

table unpack

table unpack datastring ?compressionlib?
Table.Unpack(data=,?compressionlib=?)

Unpack a base64-encoded serialized object string which was created by a table pack command. The return value of this function is the handle or reference of the newly created table object, which is an exact duplicate of the packed original table.

Packed tables may also be unpacked by the table create command.

The default compression library is zlib . For more options, see table pack .

table valid

table valid tablehandle propertylist
t.valid(property/propertysequence)

Returns a list of boolean values indicating whether values for the named properties are currently set for the table. No attempt at computation is made.

Example:

table valid $thandle T_COMMENT

reports whether the table has a comment property attached or not.

table has is an alias to this command.

table varexport

table varexport tablehandle ?varname? ?reset?
t.varexpor(?variable=?,?reset=?)

Export the table contents into a global Tcl array or Python dictionary variable in the current thread-local main interpreter. If the boolean reset flag is given as true , any previous variable contents are erased. If the variable name is not specified, the variable name set via the variable table attribute (see table get command) is used. If the variable name is unset or an empty string, the command does nothing. The variable table attribute is updated if a variable name is supplied.

The rows and columns of the table are translated into a comma-separated numerical index in the array variable, i.e. the cell at the first row and column in the table has the array index or dictionary key “0,0”. The addressing is scheme is row-first.

Within the Tcl interface, this command establishes a variable trace link between the variable and the table. Any data updates in either the table or the Tcl variable is automatically reflected in the other object.

The command returns the original table handle or reference.

table varimport

table varimport tablehandle ?varname?
t.varimport(?variable=?)

Import cell data from a global Tcl array variable or Python dictionary in the current thread-local main interpreter. The array variable is expected to use row and column addressing with row-first numerical, comma-separated indices (see table varexport ), and to contain element data which is compatible with the column data types of the table.

If the variable name is not specified, it is taken from the variable table attribute (see table get command). If the variable name is not set, or an empty string, the command does nothing. In any case, the variable table attribute is not changed, and, for Tcl , no automatic update link between the Tcl variable and the table is established. Existing table cells for which no array variable element exists remain unchanged. Array variable elements which do not correspond to existing table cells are ignored.

Example:

set tvar(0,0) “data_for_row0_col0”
set tvar(0,1) “data_for_row0_col1”
table varimport $thandle tvar

If the tvar variable did not exist before, and the table has at least one row and two columns, and these cells can accept string data, the first two table cells in row zero are updated.

The use of this command with variables which are linked to the table object (via table varexport or table set commands) is not required, since data changed a linked variable is automatically propagated.

The command returns the original table handle or reference.

table verify

table verify tablehandle property
t.verify(property)

Verify the values of the specified property on the table. The property data must be valid, and a table property. If the data can be found, it is checked against all constraints defined for the property, and, if such a function has been defined, is tested with the value verification function of the property.

If all tests are passed, the return value is boolean 1, 0 if the data could be found but fails the tests, and an error condition otherwise.

table wait

table wait tablehandle conditionflags
t.wait(conditionflags)

Suspend execution of the current thread until one or more conditions on the table have been met. While waiting, the mutex lock on the table is released, so that other threads can manipulate it. While a wait operation is in progress, the table cannot be deleted.

The flags may be a list of one or more of the following flags, plus none or an empty string (and None for Python ) if no flags should be set:

table write

table write tablehandle ?filename? ?format? ?parameter value?..
table write tablehandle ?filename? ?format? ?dictionary?
t.write(?filename?,?format?,?parameter,value?,...)
t.write(?filename?,?format?,?dict?)

Save the contents of the table to a file. If no filename is specified, or an empty string, #auto or None for Python , the same filename as that the table was originally read from, or configured via a table set command, is used. If this name is not set, a name with a standard suffix located in the temporary directory is generated, but this requires that the format argument is set. Besides a normal file name, standard output and standard error ( stdout , stderr ) as well as, except on Windows, an open Tcl or Python file or socket handle may be specified. If the file name begins with a vertical bar, a pipe channel is opened. If the file name is specified, it is remembered as future default.

If no explicit table file format is specified, an attempt is made to infer the format from the file name suffix. If necessary, table I/O modules are loaded automatically. If none of these measures are able to automatically choose an format, the original table format is used if it is defined. If still no table file format can be identified, an error is reported. Otherwise, the selected file format is remembered as future default.

The rest of the optional arguments are either keyword/value pairs (an even number of additional command arguments) or a single dictionary argument with the same possible set of keyword/value pairs. The following keywords are recognized:

table write $th1 kinome_export.xlsx xlsx {formatbits unit|rescale}

In this example, the Excel cells in the output do not only contain the cell values, but additionally (for those columns which are associated with a property, which then also needs to possess a specified unit) the unit name as a string, and an attempt is made to adjust the Excel cell value to lie between 1 and 1000 with automatic adjustment of the unit within a known unit series, for example by switching between the unit names pMol , nMol , uMol , mMol and Mol .

table save is a command alias.

table yield

table yield tablehandle ?waitusecs?
t.yield(?waitusecs=?)

This command is primarily useful in multi-threaded application. It temporarily sets the table undeletable, releases all mutex locks, instructs the thread scheduler to yield the current thread, and them either immediately or after the specified number of microseconds re-acquires the mutex locks and restores the original object deletability.

The return value of the command is the original table handle or reference.

A typical application is within a table loop or table poploop command where the processing of a row by the loop command is faster than the delivery of new table rows by a separate thread. Using this command can lead to a better distribution of table access time between the loop command and the data provision thread and an overall speed-up of the computation.