table get $thandle T_XYPLOT

table getcol $thandle last datatype

table getcol $thandle 0 data

table delrow $thandle 3-last

table dupcol $thandle E_NAME end

table setcol $thandle 0 bgcolor white

table setrow $thandle 1 bgcolor red

table get $thandle dataset

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:

• data
  A data column with cells of a specific data type which is not associated with a Cactvs property, or where the property association is unknown. If no data type is supplied in the next argument, the default is double.
• function
  A data column with cells which contain dynamically computed values. The next argument is the SQL-style function expression. If that argument is not provided, the function result for the cell values will always be NULL . formula is an alias column type name for this type.
• image
  Add an structure or reaction image column. This is a special type of property column. The property behind this column is dynamically adapted according to chosen output formats. For example, it is E_GIF for HTML pages, E_EMF_IMAGE for Windows MS Excel , and E_PICT_IMAGE for Mac MS Excel output. For this column type, the next optional argument is immediately the column name, not the detailed type specification.
• none
  An unspecified column. Useful as place holder in case this is defined later, or to add spacer columns. For this column type, the next optional argument is immediately the column name, not the detail type specification.
• property
  A data column with cell values which are linked to a Cactvs property. The fundamental data type, as well as enumeration values, formatting conventions etc. are all inherited from the property definition. If the property name is not supplied in the next argument, the default is property E_NAME . Property-associated columns are especially useful for automatic transfer of chemical object data into a table by means of the table addens and table addreaction commands.
• sequence
  An integer data column automatically filled with sequential numbers starting with one for the first row, or another value if an explicit start value is given. For this column type, the next optional argument is immediately the column name, not the detailed type specification.

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:

• dataset
  A new dataset which contains all the reaction and ensemble objects associated with the table rows, without duplicates. Rows without an ensemble or reaction association generate a new empty ensemble. The property set of the objects in the new dataset is automatically augmented with the data of the associated table row.
• ens
  The ensemble associated with the first table row, or an empty ensemble if no such association exists. The ensemble property set is automatically augmented with the row data.
• reaction
  The reaction associated with the first table row, or an empty reaction if no such association exists. The reaction property set is automatically augmented with the row data.
• table
  Only supported for the sake of completeness, this mode does nothing.

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:

• append
  The data is appended to the current cell data, if the data type of the cell supports the concept of appending. The default is to replace it.
• clear
  Set the cell to a NULL value. The value argument is ignored.
• force
  Override any editing locks on the table, column, row or cell.
• recall
  Return the old value of the cell before the update as command result.
• recallnew
  Return the new value of the cell after the update. Because of the formatting implied by, for example, columns which hold property values and where the property definition contains enumerations, constraints, precision limits, etc., this may not be exactly the value argument which is input.
• settime
  Set the update time stamp on the table. By default, this is not done due to its inherently expensive character because it needs to issue a system call.

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:

• colname
  The name of the newly added result column. If it is not set, or set to an empty string, the default name is cluster.
• epsilon
  The epsilon value, i.e. the minimum total value the cluster centroids need to have moved as result of the last iteration to start another iteration cycle. Only used in fuzzy KMeans clustering, where the default value is 0.001. If the total movement of the centroids is less than that, the iteration is stopped immediately.
• exponent
  The exponent used in the distance law to compute the location of the cluster centroids. Only used in fuzzy KMeans clustering, where the default is 1.5.
• maxncycles
  The maximum number of iteration cycles. Only used in normal and fuzzy KMeans clustering. If the cluster membership does not change during a cycle in normal KMeans clustering, or the total movements of the cluster centroids is less than the epsilon value in fuzzy KMeans clustering, iteration is stopped early even if the maximum number of iterations has not yet been reached.
• ncluster
  The number of clusters to find. Used in normal and fuzzy KMeans clustering and for the Centroid and Ward methods. Jarvis-Patrick clustering determines the number of clusters algorithmically.
• ncommon
  The minimum number of elements needed to be in common among the number of examined closest neighbor points for joint cluster membership. Only used in Jarvis-Patrick clustering. This value must be less than or equal to the nexamine parameter. The default value is one.
• nexamine
  The number of closest neighbor points to examine for being in the joint neighborhood of two points which could potentially be in the same cluster. Only used in Jarvis-Patrick clustering. The default value is two.
• nsteps
  The number of merge steps. Only used in the Centroid and Ward methods. The default value is the minimum of 5 and the number of eligible rows.
• position
  The column position where the result column is inserted. It can be either a numerical index, or the special name end for addition to the right of the current columns. which is the default.

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

• centroid
  The result column is an integer vector with a length equal to the number of merge steps plus one. Initially, and this is recorded in vector element zero, every eligible row is in its own cluster, so all cluster IDs in the range from one to nrows are used. After each merge step, a new vector index is filled for all rows. All values are the same as that of the previous index, except that the cluster ID of the cluster with the higher value of the merged pair is withdrawn and its value replaced by the ID of the other cluster in all rows in the absorbed cluster. If a full merge is performed, all rows will end up as members of cluster one. Rows which are not eligible for clustering retain a cluster number of zero during all merge steps. The merge distances for all steps are stored in a double vector as column header data.
• fuzzykmeans
  The result column is a double vector, with the number of elements equal to the requested cluster number ( ncluster parameter). Every element holds the fractional membership value for that cluster.
• jarvispatrick
  The result column is of type simple integer. It holds the number of the cluster the row is a member of. Cluster numbers begin with one. In case the row data is NULL or otherwise excluded from clustering, it is set to zero.
• kmeans
  The result column is of type simple integer. It holds the number of the cluster the row is a member of. Cluster numbers begin with one. In case the row data is NULL or otherwise excluded from clustering, it is set to zero.
• ward
  The result data format is the same as for the centroid 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

• all Substitute all matches of the regular expression. By default, it applies to the first match. Additional matches are only sought to the right of the last substitution, so this is not processed recursively.
• nocase Ignore case in regular expression matches
• expanded Support expanded regular expression syntax (see regexp man page)

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? ?retrievalcolumn?

t.find(column=,operator=,value=,?mode=?,?retrievalcolumn=?)

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:

• address_city
  The city part of the author contact address.
• address_country
  The country part of the author contact address, following the ISO3166 standard.
• address_state
  The state part of the author contact address. Empty if not applicable.
• address_street
  The street address part of the author contact address. Includes floor, house number, etc.
• address_zip
  The ZIP code or other applicable postal code of the author contact address.
• affiliation
  The institution the table author works for.
• affiliationduns
  The DUNS registration ID of the affiliated institution. This is primarily useful for US government projects.
• affiliationurl
  The URL of the affiliated institution.
• author
  The author of the table, as free-form string data.
• autorowformat
  A string which is used as template for automatically generated table row names if no explicit names are specified. If it is not set, the fallback naming template is Row%ld , where the numeric placeholder is filled by the current value of the autorowid attribute. If a custom template is used, it should also contain a %ld placeholder, and no other C-style formatting instructions except for this one long integer.
• autorowid
  An integer which starts at zero when the table is created and is automatically incremented for every table row added via a table addrow command or internally called equivalents. This number is used in conjunction with the autorowformat attribute to generate unique table row names in case no explicit name is set. The value can be modified if necessary.
• authorurl
  A URL with information on the author, or an empty string if unset.
• bgcolor
  The global table background color. If unset, an the result is an empty string.
• carbondisplaymode
  The default mode for carbon atom rendering of embedded structure or reaction images. It can be either none (no symbols), special (special C atoms have symbols) or all (all carbon atoms are rendered with explicit symbols).
• category
  A category string to be used if the table is stored in a repository.
• class
  A class string to be used in HTML output as attribute of the <table> tag.
• classuuid
  The base class UUID of this table object
• colblocksize
  Set the column block size. If this value is larger than one, the default, the layout of some table output formats is adjusted to use repeated blocks of data instead of a simple matrix. For non-rotated table output, a new row is only started after the set number of entries, each with their normal item column count, have been written, instead of starting a new row after each physical table row. For rotated layout, a new printed set of rows, each set comprising of a number of rows equivalent to the physical table columns, is already forced after the specified number of rows have been printed left to right, instead of printing all selected rows left to right. This formatting option is currently only supported for Excel xls , HTML (table and page) and CDXML layout.
• coldatatypes
  The data type of the columns. If the list is shorter than the column count when used with a set command, only the first column data types are changed.
• coldescriptions
  A list of the column description texts.
• collengths
  The width of all columns as a list. Columns with undefined widths report minus one. This is a read-only attribute. Note that this attribute defines an object length (for example, a character count), not a formatting width, which is defined by the widths attribute.
• colnames
  The names of all columns as a list. If the list is shorter than the column count when used with a set command, only the first names are changed.
• colproperties
  A list of the properties of all table columns. If a column is not a property column, an empty string element is inserted. This is a read-only attribute. This attribute can also be addressed via its alias names colprops, props or properties .
• coltypes
  The column types of all columns as a list. This is a read-only attribute.
• comment
  A free-form comment string.
• coords
  If the toolkit was compiled with factory support, these are the coordinates of the object icon on its workbench, encoded as integer pair. This attribute can be changed.
• dataset
  A deprecated alternative name for the internaldataset attribute.
• datatypes
  A list of all the data types of the table columns. This is a read-only attribute. This attribute can also be addressed via its alias coldatatypes .
• dataframe
  This attribute is only available in the Python interface and only if the numpy module is loaded or can be auto-imported. The complete table is exported as a numpy dataframe object. For column typing and special issues concerning these, please refer to the nparray and nptype column attributes.
• date
  The date the table configuration was defined.
• deletable
  Flag indicating whether the object can be deleted with a standard table delete command. This attribute is read-only. Objects which are, for example, property data values or a part of a molfile loop command cannot be deleted by standard means.
• displaywidths
  A list of the widths of all table columns. This is a read-only attribute. Table columns which have no explicit width contribute an empty string, not a negative or zero value. This is for compatibility with Tk widget configuration. Note that this is the formatting width, for example defined as pixel count or points, not an object length, such as a character count. The latter attribute can be queried by the collengths attribute. widths is an alias name for this attribute.
• doi
  A digital object identifier for the table object content, if defined.
• downloadfilename
  The save name of the file when it is transmitted via HTTP . If is is also specified as part of the transient output options in table write , that specification has precedence.
• editable
  Boolean flag reporting whether the table is editable.
• email
  A contact email of the author.
• embedfileformat
  The output file format of embedded objects in the table. This applies for example to tables which are written as Excel or Excel XML , where associated structures may be written as CDX or SKC OLE objects. For table output in formats which do not support this kind of embedding, the attribute is ignored. If the attribute is set to an empty string, or none , embedding is disabled where applicable, i.e. embedded Excel XML structure images are plain WMF/EMF drawings, not OLE objects. Otherwise, the attribute must be resolvable to a I/O module name for molfile objects (see filex command).
• emptyrows
  Get a list of row numbers which are empty, i.e. only contain NULL data values. This is a read-only attribute.
• ens
  A list of all ensembles associated with the table rows. This is a read-only attribute. If a structure data column is associated with the table, an attempt is made to automatically instantiate the ensembles.
• ensrowcount
  The number of rows which are associated with any ensemble. This is a read-only attribute. If a structure data column is associated with the table, an attempt is made to automatically instantiate the ensembles.
• ensrows
  A list of the row indices of those rows which are associated with an ensemble. This is a read-only attribute. If a structure data column is associated with the table, an attempt is made to automatically instantiate the ensembles.
• eod
  The value of the end-of-data marker. This attribute is typically used in multi-threaded applications to indicate that feeder threads have exhausted their data supplies and that no further table rows are expected to arrive. This attribute is internally used by the table pop and table wait commands to determine whether they should continue to wait or exit with an empty result. The initial value of this attribute is zero.
• eodcheck
  Perform a check whether at least one row is in the table, or is expected to arrive later. If rows are currently in the table, or the eod attribute value is less than the targeteod attribute value, the command returns zero, otherwise one. This attribute is read-only.
• eolchars
  The end-of-line chars for text-based table output. The default is platform-dependent ( NL on Linux/Unix, CR on Mac, CR/NL on Windows).
  The magic strings windows , mac (both checked for the first three characters only) as well as unix and linux are automatically translated to the standard platform line terminators and not copied verbatim. Alternative names for these standard system encodings are crlf , cr and lf . The special value default resets the attribute to the platform-dependent default.
• failures
  A list of properties for which computation failed on this table object. This is a read-only attribute. Depending on configuration settings, this information may be used to block pointless attempts at re-computation of incomputable data.
• fgcolor
  The global table foreground color. If unset, an the result is an empty string.
• fileformat
  The format of the file the table was read from. none is returned if the table was not read from a file.
• filename
  The full path name of the file the table was read from. If the table was not read from a file, an empty string is returned. This attribute can also be set, and is then used when the table is written and no explicit filename given.
• font
  The global output font name, or an empty string if it is not set.
• fontsize
  The global font size in points. If not set, zero is reported.
• footer
  A free-form table footer text.
• footercolor
  The table footer color, or an empty string if not set.
• footerfont
  The table footer font name, or an empty string if not set.
• footerfontsize
  The table footer font size, or zero if not set.
• footerformat
  The table footer format flag set. The set is the same as for the format attribute.
• format
  The current set of global format flags. This is a keyword list which can contain the flags

none -no flags, equivalent to empty string

left - left-aligned text), center (centered text

right - right-aligned text), bold (bold text

highlight - cell highlight), texthighlight (text highlight

histogram - plot histogram instead of data if supported by output format

border - use extra cell border

padding - use extra interior cell padding

expand - format as auto-expand item

top - text aligned vertically to top

middle - text centered vertically in middle of cell

bottom - text aligned vertically to bottom

multiline - format cell data in multiple lines if possible

gcolor - has explicit foreground color

bgcolor - has explicit background color

italic - use cursive text), underline (use underlined text

embedded - embed content of data which are external references, such as linked files into the output, instead of passing the reference

mdlnote - augment call data with MDL Molfile note text of associated ensemble or reaction

smilesnote - augment cell data with SMILES note text of associated ensemble or reaction

vertical - use vertical text if supported

precision - use property precision data for formatting

html - data is expected to be already HTML-encoded, no additional formatting for HTML table output

merge - merge column with column on the left to multi-row column if supported

The flag set is the same in all contexts. However, not all make sense everywhere (i.e. the merge flag is only useful in column formats, not globally or on individual cells), and other require additional data (the fgcolor / bgcolor flags).

• framecolor
  The color of frames around objects in certain output contexts, for example around embedded images or OLE objects. This attribute is evaluated only if the rendering is executed implicitly, for example during an output operation. If, for example, an explicit E_GIF or E_EMF_IMAGE image is set as cell data, the parameters that were in effect when these images were generated are not checked. The default frame color is black. It is sometimes useful to set it to the background color or the rendering, i.e. white, or to suppress frame output altogether (see table write ).
• gflags
  If the toolkit was compiled with factory support, this is the currently set object icon rendering flag collection.
• header
  A free-form header text.
• headercolor
  The table header color, or an empty string if not set.
• headerdata
  A list of the values of the header data for all columns. This is a read-only attribute.
• headerfont
  The table header font name, or an empty string if not set.
• headerfontsize
  The table header font size, or zero if not set.
• headerformat
  The table header format flag set. The flag set is the same as for the format attribute.
• heights
  A list of all row heights. This is a read-only attribute. Rows for which a height has not been set contribute an empty string.
• hidden
  Flag indicating whether the object is hidden. This is not the same as the invisible state. This attribute is intended to be used for rendering selections. This attribute can be changed.
• highlightcolor
  The default color for highlighting. It is set by default to red.
• highlightfont
  The default font for highlighted text output, or an empty string if not set.
• highlightfontsize
  The font size of the highlight font, or zero if not set.
• highlightformat
  The format flags used by default for highlighting. The set of flags is the same as for the format attribute. The default flag set is bold and underline (plus fgcolor , because the foreground color is set, see highlightcolor attribute).
• httpheader
  The type of MIME header to add to table output. It can be 0 (no header, the default), 1 (basic MIME header) or 2 (full header with status code).
• hydrogendisplaymode
  The default mode for hydrogen atom rendering of embedded structure or reaction images. It can be either none (no symbols), special (special H atoms have symbols) or all (all hydrogen atoms are rendered with explicit symbols).
• imagedirectory
  The name of a directory to store images and other external files in which, depending on the output format, cannot be stored directly in the table file.
• imagemenuoptions
  A keyword list to select the inclusion of specific image menu options in table file formats which support such a feature (currently, only HTML ).
• imageurl
  The base URL component used for linking images in the image directory (attribute imagedirectory ). In HTML output, this component and the name of image files were once combined to add working image links to the output file. Since in current toolkit versions, HTML output employs data URI encoding of the images as replacement for external linking, this attribute is deprecated.
• infourl
  A URL with information on the object content, or an empty string if unset.
• internaldataset
  The handle of the internal table dataset object which is part of every table. It is not the handle of a dataset the table may be a member of, as retrieved by the table dataset command. The attribute name may be shortened to simply dataset . It is a read-only value - it is not possible to change an internal table dataset since it is an integral part of the data structure.
• invisible
  Flag indicating whether the table is invisible. This is not the same as the hidden state. An invisible object is no longer accessible via its handle. This is usually the case for objects which are scheduled for deletion, but still have lingering referring pointers. This attribute is read-only.
• iteratorstyle
  The default style of row data stored in the loop variable of the table loop command. It can either be list (or tuple, for Python compatibility) or dictionary. In list mode, the row data is presented as a simple list and elements are accessed via the list index. In dictionary mode, the data is presented as a dictionary, with the column names as keys. The default iterator style is list. More information can be found in the command description of table loop.
• linktarget
  If the table output is HTML or a similar format with hyperlinks, this parameter controls the link target specification, if it is not an empty string. For HTML , a value like _blank to open the link in a new window or the name of an existing window in an application can be set.
• javaobject
  If the toolkit was compiled with JNI support, this attribute reports the memory address of the JNI wrapper class instance, if it exists.
• keywords
  A list of keywords associated with the table object.
• license
  The license class associated with this table object. Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the table object license.
• literature
  A free-form literature reference for the data content of the table.
• markcolor
  The color of markings and annotations in certain output contexts, for example in embedded images or OLE objects. This attribute is evaluated only if the rendering is executed implicitly, for example during an output operation. If, for example, an explicit E_GIF or E_EMF_IMAGE image is set as cell data, the parameters that were in effect when these images were generated are not checked. The default mark color is pure blue.
• maxrows
  A maximum number of rows allowed in the table. Attempts to add more rows fail, or, if the table has an active background export thread, block. Setting it to a negative value, the default, disables this limit.
• modcount
  The object data and content modification count.
• mutexcount
  The number of recursive mutex locks held for this object. Only supported on Linux.
• name
  A free-form table name as string
• ncols
  The number of columns in the table. This attribute may be used in a table set command to reduce the number of columns, but not to enlarge the table.
• note
  Arbitrary data added as note data. This is usually only used on a lower level to added notes to individual cells.
• notesize
  The size of the table-level note data. This is a read-only attribute.
• nrows
  The number of rows in the table. This attribute may be used in a table set command to reduce the number of rows. Adding table rows is also possible by manipulating this attribute. In that case, all new data cells are set to NULL .
• nulldatarows
  A list of the row indices of those rows where all columns are NULL values.
• nullensrows
  A list of the row indices of those rows which are not associated with an ensemble. This is a read-only attribute. If a structure data column is associated with the table, an attempt is made to automatically instantiate the ensembles.
• nullreactionrows
  A list of the row indices of those rows which are not associated with a reaction. This is a read-only attribute. If a reaction data column is associated with the table, an attempt is made to automatically instantiate the reactions.
• offset
  This attribute can be either zero or one. It influences the naming of flattened columns (see table flatten command)
• onclick
  For HTML output, the name of a JavaScript function to be called when a table cell is clicked. The function is called with three arguments: The automatically generated DOM ID of the table cell, and the row and column indices, starting with zero.
• onmouseover
  For HTML output, the name of a JavaScript function to be called when a the mouse is moved over a table cell. The function is called with three arguments: The automatically generated DOM ID of the table cell, and the row and column indices, starting with zero.
• onmouseout
  For HTML output, the name of a JavaScript function to be called when a the mouse is moved away from a table cell. The function is called with three arguments: The automatically generated DOM ID of the table cell, and the row and column indices, starting with zero.
• orcid
  The ORCID code of the author of the table (see www.orcid.org).
• orientation
  This value can be none (the default), landscape or portrait . It describes the orientation of a drawing area specified via the paper attribute. Few I/O modules use this information. The most important formats which implement this is are CDX and CDXML .
• paper
  An attribute describing the size of the drawing areas for formats such as CDX or CDXML , which can encode this type of information. Possible values are none (the default), a3 , a4 , a5, a6, a7, b3, b4, b5, b6, letter, legal and executive . The associated orientation of the drawing orientation can be set via the orientation attribute
• parameters
  A keyword/value dictionary of format-specific output options which are not represented by a general table object attribute. I/O modules may possess individual additional control parameters (see tablex get/set commands). The default values for these are automatically added to the parameters table attribute when a table file is written, and may be examined afterwards, but key/value pairs which have been explicitly configured via this attribute are not overwritten and take precedence.
• path
  The repository path for displaying hierarchical repository trees. This attribute is independent of any file system paths.
• phone
  A contact phone number of the author.
• progress
  A user-defined progress value intended to track the state of lengthy operations on the table. It is an integer between zero and one hundred and is initially set to zero. When the argument is set, it accepts a floating point value, but the stored value is automatically rounded to the next integer and forced into the 0..100 range.
• pyobject
  If the toolkit was compiled with Python support, this attribute reports the memory address of the Python wrapper class instance, if it exists. This attribute is read-only.
• pyrefcount
  If the toolkit was compiled with Python support, this attribute reports the reference count of the Python wrapper class instance, if it exists. This attribute is read-only.
• reactioncolumn
  The index of the first column which has the reactionsource attribute set. If no such column can be found, the result is minus one. This attribute is read-only.
• reactioncolumnfileformat
  The file format associated with columns which contain decodable reaction data. By default, this attribute is unset, which means that an attempt is made to automatically detect the format, as with a reaction create command.
• reactionimageproperty
  The name of a property to use for rendering reaction images in formats which allow the inclusion of images in multiple formats, such as HTML . In that case, supported properties include X_GIF , X_SVG_IMAGE and X_PDF_IMAGE . In table file formats which cannot include images, or support only a single image format, this attribute is ignored.
• reactions
  A list of all the reactions associated with the table rows. This is a read-only attribute.
• reactionrowcount
  The number of rows which are associated with a reaction. This is a read-only attribute. If a reaction data column is associated with the table, an attempt is made to automatically instantiate the reactions.
• reactionrows
  A list of the row indices of those rows which are associated with a reaction. This is a read-only attribute. If a reaction data column is associated with the table, an attempt is made to automatically instantiate the reactions.
• record
  The current table row iterator record. The first row is record one.
• refcount
  If the Tcl interpreter is using native Cactvs objects instead of string-based major object handles and integer-based minor object labels to identify toolkit objects, this returns the number of Tcl object references active for this table. This attribute is read-only.
• references
  Cross references of the table. This is a nested list of class UUID s and reference type tags.
• regid
  For registered data tables, the registration ID. Zero if this is a private table.
• rownames
  A list of the names of all rows. This is a read-only attribute.
• rownametype
  This can be either string , or numeric , and has an effect on how row names are compared during sorting and other operations. The names are nevertheless always stored as strings.
• rowobjectassociations
  This is a boolean attribute. On querying, it indicates whether this table has any rows which are associated with existing ensemble or reaction objects. When setting, it has an effect only if the boolean argument value is false . This operation then removes any existing associations between structures or reactions and rows on this table (see table addens/addreaction ). Deleting structures or reactions while they are associated with a table can be slow if multiple or large tables exist in the application, since they all need to be searched for associations with the object to be deleted. This is because currently structures or reactions only maintain a table reference count, but not any information with which table(s) and row(s) they are associated with.
• scoped
  A boolean object visibility control flag. If set, and global control flag ::cactvs(object_scope) is also set, the object is visible only in the Tcl interpreter which set the scope flag and thus claimed it. Object list commands executed in other interpreters omit this object, and attempts to decode its handle in other interpreters will fail. The most common use of this feature is the hiding of persistent chemistry objects in scripted property computation functions.
• selected
  Flag indicating whether the object is selected. This attribute can be changed. This flag is unrelated to row or column selections - it is a standard major object flag.
• selectedcolumns
  The currently selected set of columns, as a numerical list of column indices.
• selectedrows
  The currently selected set of rows, as a numerical list of row indices.
• separator
  The current separator character. This is updated if table data is read from a text file with automatic detection of the separator character or with an explicitly named separator (see table read command). It also has an effect on formatting of ASCII table output. The default separator is a tab character. If you set it to a string which has more than one character, only the first character is actually recorded.
• sizehint
  An integer indicating the expected maximum row count of the table. This is used for internal optimizations. A value of minus one indicates that no size hint is in effect.
• soapmethod
  The name of a method which is used for SOAP data exchange involving this table.
• soapschema
  The name of a schema which is used for SOAP data exchange involving this table.
• sqlddl
  Compose an SQL statement which can be used to define a compatible database table. The precise syntax used depends on the configured SQL dialect in ::cactvs(sql_dialect) .
• structurecolumn
  The index of the first column which has the structuresource attribute set. If no such column can be found, the result is minus one. This attribute is read-only. The attribute name enscolumn is an alias.
• structurecolumnfileformat
  The file format associated with columns which contain decodable structure data. By default, this attribute is unset, which means that an attempt is made to automatically detect the format, as with a ens create command. The attribute name enscolumnfileformat is an alias.
• structureimageproperty
  The name of a property to use for rendering structure (ensemble) images in formats which allow the inclusion of images in multiple formats, such as HTML . In that case, supported properties include E_GIF , E_SVG_IMAGE and E_PDF_IMAGE . In table file formats which cannot include images, or support only a single image format, this attribute is ignored.
• style
  The name of a predefined output style. This is currently only used by the CDX and CDXML table output formats, which support both the ChemDraw default style and the ACS journal style ( acs ).
• stylesheet
  This is only used in htmltable output. It is the outputfile-relative path name of a CSS file which is linked to the primary output file via a <link> tag.
• symboldisplaymode
  The default mode for atom rendering of embedded structure or reaction images. It can be either none (no symbols), symbol (element symbols), label (atom labels), index (atom list index), box (colored square marker), compact (symbols with contracted atoms) or residue ( A_RESIDUE label)
• targeteod
  The target value of the eod attribute. Once it matches or exceeds this value, the table is not expected to receive any more rows. The initial value of this attribute is one. This attribute is for example checked by processing threads.
• title
  A free-form table title text.
• titlecolor
  The table title color, or an empty string if not set.
• titlefont
  The table title font name, or an empty string if not set.
• titlefontsize
  The table title font size, or zero if not set.
• titleformat
  The table title format flag set. The set is the same as for the format attribute.
• tooltip
  If the toolkit was compiled with factory support, this is the tooltip of the object icon on a workbench. This attribute can be changed.
• undefined
  This attribute controls the I/O of undefined cell data. It is a string consisting of one or more words, separated by commas. The first word is used for string-based output of NULL cell values. All words are recognized when decoding cell data from strings. Any input matching any of the words are stored as a NULL value. The default value is „ NULL,N/A,UNDEF,UNDEFINED,UNSET,NOTSET“. With this string, NULL cells are printed as “NULL”, and a total of six magic words for the input of NULL data are recognized.
• uuid
  An automatically generated UUID globally identifying the object. This attribute is read-only, different for every object, and not dependent on its contents.
• variable
  The name of a global Tcl array variable in the base interpreter which is linked to the table. Table updates are reflected in the variable contents, and changes of the variable elements will change the table object contents. The 2-dimensional Tcl array variable uses numerical row and column indices. If there is no linked variable, which is the default, the result is an empty string.
• version
  The version number of the table. This is a string in a 1.2.3 (or shortened) style,
• versionuuid
  The UUID associated with this table object version.
• x
  If the toolkit was compiled with factory support, this is the x coordinate of the object icon on its workbench. This attribute can be changed.
• y
  If the toolkit was compiled with factory support, this is the y coordinate of the object icon on its workbench.This attribute can be changed.

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:

• bgcolor
  The background cell color, if it is set on the cell level.
• comment
  A free-form text comment
• exists
  Check whether the addressed cell exists in the table. The return value is a boolean result. No error is raised if the cell address cannot be resolved.
• fgcolor
  The foreground cell color, if it is set on the cell level.
• format
  Cell-level format flags. This is the same set as for the global table attribute of the same name, which is explained in the section describing the table get command.
• isnull
  A boolean check whether the data value of the cell is NULL .
• mergedbgcolor
  The effective cell background color, merged from cell>row>column>table format specifications.
• mergedfgcolor
  The effective cell foreground color, merged from cell>row>column>table format specifications.
• mergedformat
  The effective format flags for the cell, merged from cell>row>column>table format specifications.
• image
  A Tk image handle when the table object is linked to a Tk table widget.
• note
  A free-form cell note. In output formats such as MS Excel this is displayed as a tool tip. Note that this data can be binary.
• notesize
  The size of the note, in bytes.
• object
  The table cell object (the handle of an ensemble or reaction), or an empty string if no such object exists.
• tag
  The cell tag in a linked Tk table widget.
• value
  The cell data value.
• window
  The name of a linked Tk window displaying cell contents.

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:

• avg
  The computed average value of the column data cells. Null cells are ignored. This operation only succeeds on numerical table columns. average is an alias.
• count
  The number of non-null data values under this column.
• data
  A list of all the values of the column data cells, in row order. The size of the returned list is the same as the row count. values is an alias.
• data(fieldname)
  This form is a variant of above command. It is used to access a specific data field of the column data, or perform datatype-specific conversion operations. The allowed field names are determined by the specification of the column property, if it exists, and/or the column datatype. If the column data is already a property field, the field name signifies further indexing from that property data subset onwards. At this time, not all indexing operations possible in other index-driven commands are available, especially index accesses where individual data items determine success or failure (such as key-indexed dictionary values) are not possible.
• distinct
  Get the number of distinct cell values in this column. Implicitly, this sets up a column index.
• exists
  A boolean pseudo-attribute indicating whether the column with the specified identifier exists in the current table or not.
• hasnull
  A boolean flag indicating whether any of the cells in the column is a NULL cell.
• index
  The numerical column index of the specified column identifier. If the identifier cannot be resolved, minus one is reported.
• isnull
  A boolean value indicating whether all rows under the column exclusively contain NULL values.
• max
  The computed maximum value of the column data cells. Null cells are ignored. This operation only succeeds on numerical table columns.
• min
  The computed minimum value of the column data cells. Null cells are ignored. This operation only succeeds on numerical table columns.
• maxsize
  The the maximum size (as per the size pseudo-element in property retrieval commands) of all non-null rows of the column. This is especially useful for string-class columns (returning the maximum string length) and vector-class columns (maximum vector size). If there are no non-null cells, in the column, the return value is an empty string.
• minsize
  The the minimum size (as per the size pseudo-element in property retrieval commands) of all non-null rows of the column. This is especially useful for string-class columns (returning the minimum string length) and vector-class columns (minimum vector size). If there are no non-null cells in the column, the return value is an empty string.
• nparray
  This attribute is only available in the Python interface and only if the numpy module is loaded or can be auto-imported. The return value is a numpy array of the column data. Vector data is either represented as 2-dimensional arrays (if the vector length is constant over all column values), or object_ if it varies. Not all Cactvs data types can be translated to numpy , and the command can thus fail for more complex column data types. For an export of a full table as a numpy dataframe, see the dataframe attribute on the table object.
• nptype
  This attribute is only available in the Python interface, and only if the numpy module is loaded or can be auto-imported. It returns the numpy item datatype for elements of this column as numpy object, or none if the column data cannot be represented as numpy data. For vectors the type is the element type if all vector lengths in the table column are identical, otherwise object_, due to limitations in the numpy data model.
• nullrows
  Get a list of all rows which have NULL values in this column.
• notesize
  The byte length of the note attribute. If no note is attached, the result is zero.
• objects
  A list of the handles of all table cell objects set in that column, in row order. Cells for which no object has been set report an empty string list element.
• propertyfield
  The property field index of the column. If the column is not a property column, or the column is specified to contain data of a complete property record, not just a field, the value minus one is returned.
• sqlname
  The name of the column, reformatted to be easily usable in the context of SQL statements. These column names are automatically used when the table is exported in one of the SQL database dialects.
• stddev
  The computed standard deviati8on of the column data cells. Null cells are ignored. This operation only succeeds on numerical table columns.
• sum
  The computed sum of the column data cells. Null cells are ignored. This operation only succeeds on numerical table columns.
• unique
  Test whether the row values under this column are unique. The command returns a list of three values. The first is a boolean value telling whether all values are unique, followed by a pair of row indices of a duplicate value pair if it exists. If the column values are unique, the reported row indices are both minus one. The uniqueness test is performed by temporarily creating a column index and thus scales better than n2, but is also means only columns where an index can be built can be tested.

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:

• data
  A nested list of all the values of the data cells of the row set. The size of the returned inner list is the same as the column count, and the size of the outer list the row count between the first and last specified rows. values is an alias.
• dictdata
  The same as data, except that the row information is returned as a dictionary, with the column names as keys. dictvalues is an alias.
• exists
  Report as a boolean value whether the specified row range could be resolved.
• index
  The list of numerical row indices of the specified row identifiers. If the row range cannot be resolved, a single minus one value is reported.
• isnull
  A boolean value indicating whether all columns in the specified row range consist exclusively of NULL values.
• objclass
  The class of objects, such as ens, reaction or atom, associated with each row in the retrieval range. The default attachment, even for rows which are not connected to a chemistry object, is ens.
• objects
  A nested list of the cell objects in that row set. Cells for which no cell object has been set report an empty string.
• notesize
  A list of the he byte lengths of the note attributes in the row set. If no note is attached, the result is zero for that row.

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:

• Property names
  Valid property instances on the table are locked. If the boolean compute flag is set, an attempt is made to compute the property if it is not yet present. Otherwise, a request to lock non-existent data is silently ignored. It is not possible to lock individual property fields.
• all
  All valid table properties are locked. The compute flag is ignored.
• table
  This is an object class identifier. All property data which is controlled by the table major object and attached to the specified object class is locked. Because a table currently does not have minor objects, this command does the same as the all variant.

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:

• append
  All rows from the second table are appended to the first, without checking for duplicates.
• exclusive
  Any rows which are present in both tables are deleted from the first table. In addition, rows from the second table which do not match rows in the first table are appended. This is the opposite of the intersect mode.
• intersect
  Rows from the first table which have no equivalent in the second table are deleted from the first table. Matching rows remain unchanged in the first table, and no data is ever appended to the first table.
• join
  This mode is a combination of the transfer and union modes.
• replace
  The data of rows which have a duplicate in the first table overwrites all data cells in the matching row in the first table. This can be used, depending on the column mode, to add or update column data which is not present or NULL in the first table. The difference to the transfer mode is that even non- NULL cells in the first table are overwritten by data from the second table. Rows from the second table which do not match a row in the first table are ignored.
• second
  Rows in the second table which do not match any rows in the first table are appended to the first table. All original rows in the first table are deleted. This is similar to the subtract mode, with the order of the tables reversed.
• subtract
  Only rows from the first table which do not match rows from the second table are retained in the first table. Matching rows are deleted. No data is appended.
• transfer
  The data of rows which have a duplicate in the first table overwrites NULL data cells in the matching row in the first table. This can be used, depending on the column mode, to add or update column data which is not present in the first table. The difference to the replace mode is that non- NULL cells in the first table are not overwritten by data from the second table. Rows from the second table which do not match a row in the first table are ignored.
• union
  Rows from the second table for which there is no duplicate in the first table are appended to the first table. This is the default row mode. Rows which are duplicates are skipped.

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:

• append
  All columns of the second table are appended to the right of the current table. This can lead to duplicate column names and is not a frequently used mode. Old row data on the first table becomes NULL for these new columns.
• left
  The columns on the first table are not changed.
• intersect
  All columns on the first table for which no equivalent column exists in the second table are deleted in the first table. Columns in the second table without an equivalent in the first table are ignored and their cell data will not be copied from the second table. This is the default column merge mode.
• right
  The second table determines the column set. Any column on the first table for which there is no equivalent in the second table are deleted, and any column definitions in the second table for which there is no equivalent in the first table are added to the first table. Old row data on the first table becomes NULL for these new columns.
• union
  Any columns on the second table for which no equivalent column exists are recreated on the first table. Old row data on the first table becomes NULL for these new columns.

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:

• lock
  Increase the recursive mutex lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock.
• reset
  Release all persistent locks on the object, if they exist.
• test
  Return the current persistent lock count on the object. This excludes the transient per-command lock.
• unlock
  Decrease the recursive lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock. Unlocking an object which has not been persistently locked results in an error.

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:

• list
  This is the default. The row data is returned as a standard Tcl list.
• dict
  The row data is returned as a Tcl dictionary. The primary column names are the dictionary keys. For columns without a name, a synthetic name in the form col%d is generated.
• ens
  Return an ensemble object. The source of the ensemble is, in this order, either an existing association of the row with an ensemble, the first column marked as structure source (see description of column flags), or an empty ensemble constructed on the fly. Column data which is not already present on the result structure is attached as ensemble properties if possible. If a column is already a property column, and the column property is an ensemble property, it is directly attached to the ensemble. For other column data, with the exception of explicit property data of incompatible objects, synthetic property definitions are automatically created. NULL data is skipped.
• object
  The return value is an automatically chosen major object, either an ensemble or a reaction, depending on the type of existing row associations, source columns, or present property types. This mode can also be selected as auto or #auto .
• reaction
  As above, but the result is a reaction object. The source is either an existing row association with a reaction, a reaction source column, or a newly constructed empty reaction.
• rownamedict
  The same as the dict mode, except that the dictionary also contains a rowname key with the name of the current row as value.
• rownamelist
  The same as the list mode, except that the first list element is the row name, not the value of the leftmost column.

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:

• centered
  If there are multiple rows of the same superiority, their rank is the average position in the result list. For example, if there are two entries which would occupy both second place, their rank is both 2.5, the average of position 2 and 3 in the list. The next rank assigned is fourth place.
• olympic
  If there are multiple rows of the same superiority, they all get assigned the highest unclaimed rank. The next tier receives ranks which skip those which would have been assigned had the ranks of the superior positions been all different. For example, if there are two rows with first rank, the next assigned rank is third. This is the default method.
• sequence
  If there are multiple rows of the same superiority, they all get assigned the highest open rank. The next tier get ranks in immediate sequence, without correcting for ties. For example, if there are two tied top rows, they both get first rank, and the next rank assigned is second.

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.

• colnames
  In some cases it may not be possible to automatically detect whether the table file contains column names or not in the first data line. The boolean colnames parameter allows the programmer to provide this information explicitly. If the title reader hint is also used, the column names are expected to come after the title line.
• debug
  A boolean flag indicating that, if set, debug information should be printed while reading the file. This is primarily a developer option.
• firstrecord
  The first row record (starting with one) to read. By default, table input starts at the first row. Not all table file format I/O modules support this.
• format
  By default, the file format is identified automatically. However, in order to enforce reading the input source as a specific format, for example in case of an ASCII table file with confusing separator characters, it is possible to explicitly state the format with the format parameter. If the handler for that format is not yet loaded, an attempt at auto-loading it is made.
• headeronly
  A set boolean parameter instructs the table I/O format handler to only read the table column definitions and table-level properties. This is not supported on all table formats. If a table I/O module does not support this input mode, the full table is read instead, as by the default operation. This includes all the information which would be read in header-only mode, but also all row and cell data, which requires more memory and takes longer to read. If header-only mode is supported, the result table has no rows and no cells after input, and also no associated row chemistry objects.
• maxrows
  If set to a non-negative integer value, this parameter limits the maximum number of rows to read from the table. By default, the maximum row count is not limited.
• rownames
  In some cases it may not be possible to automatically detect whether the table file contains row names or not. The boolean rownames parameter allows the programmer to provide this information explicitly.
• scoped
  If set, directly set the scoped attribute, which makes the table invisible from Tcl interpreters other than the one performing the read.
• separator
  This parameter provides a way to explicitly define a separator character for ASCII-style text tables. By default, an attempt is made to determine the separator character automatically if the table file format is identified as an ASCII-based format with a variable separator. This option is ignored for file formats with a more advanced internal structure.
• sheetname
  Cactvs table objects can represent only a single table, not multiple tables forming a sheet collection, notebook or similar construct in the input file. In case files are read which contain multiple tables, for example sqlite, xlsx or fits files, the desired table can be selected via the sheetname string option. The alternative parameter name table is an alias for sheetname. If a multi-table file is read, and no such sheet name provided, the first table from the file is the one extracted. There is currently no way to read multiple tables from such a file with a single command, nor a method to query the number or names of sheets or tables present.
• skiperrors
  If this boolean parameter is set, rows which cannot be decoded are ignored. This is useful for example in case there are trailing blank or comment lines in the file. However, the read command will then also remain silent in case all rows fail, for example because of a mis-identification of the file format, so this option should be used with care.
• table
  An alias for sheetname, for a more familiar naming if, for example, a specific table from a database file is read.
• target
  If set to a table handle, the data is read into this existing table, which is fully reset before input commences. By default, a new table object is allocated.
• title
  A boolean flag indicating whether the table reader should interpret the first line as title string. If column names are also read, these follow the title line. The title string is stored in the title table object attribute.

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. For tables, other recognized identifiers are table references, integers encoding the numeric part of the handle string, the UUID of the network object, or its name.

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/queryhandle 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? ?retrievalcolumn?

t.select(column=,operator=,value=,?mode=?,?retrievalcolumn=?)

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 by default 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. If the name of a retrieval column is set, the return value is a list of the cell data of matching rows of that column. The special column name #name for access to row names is also supported. The manipulation of the row selection flag is not changed if this retrieval type is used instead of the default index retrieval.

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:

• bgcolor
  The background cell color, for output in formats which support this.
• class
  The class attribute of <td> tags when writing html output.
• comment
  A free-form text comment.
• fgcolor
  The foreground cell color, for output in formats which support this
• font
  The name of a font to use in rendering. This overrides fonts set on the cell column or top-level table object.
• fontsize
  The size of the font to use in rendering. This overrides font sizes set on the cell column or top-level table object.
• format
  Cell-level data format flags. This is the same set as for the global table attribute of the same name, which is explained in the section describing the table get command.
• image
  A Tk image handle if the table object is linked to a Tk table widget.
• linktext
  A text overlaying a link to use when formatting URL s in formats like HTML . An empty string results in the link value to be printed verbatim.
• note
  A cell note, which can be a block of arbitrary bytes, not just a string. In output formats such as MS Excel this is displayed as a tool tip.
• object
  A per-cell chemistry object. Currently, these must be ensembles or reactions (specified by their handles), or an empty string in order to remove an existing cell object. A cell object has precedence when computing cell data over a row object, if one is simultaneously present. An ensemble or reaction cell object cannot be deleted by ens/reaction delete commands. It is deleted by another table setcell command, or when the row, column or complete table is destroyed. Cell objects are stored in retrieved in the native Cactvs table format, even in output modes where row objects are not. Other table file formats do not preserve these. Setting a cell object duplicates the source object, just like setting an ensemble or reaction property value.
• objectref
  This is the same operation as the object command, except that the cell object is not copied. At the time the command is executed, the new cell object must be deletable (i.e. not a property value, and not a cell object anywhere else). After it has been set, is is managed by the table and cannot be deleted by normal means. When the table cell is deleted, or another cell object is set, this object is destroyed.
• shape
  Set a KNIME -compatible graph rendering shape for the cell. Valid shape names are default, rectangle, circle, triangle, revtriangle, diamond, asterisk, cross, xshape, hline and vline .
• shapesize
  Set a KNIME -compatible graph rendering shape size multiplier for the cell. This is a floating-point attribute, and 1.0 is the default.
• tag
  The cell tag in a linked Tk table widget.
• value
  The cell data value. It must be encoded in a format which can be decoded as the data type specified in the column definition.
• window
  The name of a Tk window displaying cell contents.

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:

• alias
  An alias name for the column which can be used to identify it in addition to its numerical index or primary column name.
• bgcolor
  The background column color, for output in formats which support this.
• bgcolorfunction
  An SQL -style function to compute the background color. If this is set, it has precedence over direct color specification via the bgcolor attribute, but has lower precedence that a background color specified directly on a cell.
• celldata
  Set the cell values of the column starting with the first row. The attribute argument is expected to be a list, which is split into per-cell values. If there are fewer list elements than rows, the remaining rows of the current column are not touched. If there are more list elements than rows, additional rows are added, which have NULL values in all columns except the current one. data , value or cellvalue are alias names for this attribute. To set all cells of the column to the same value, use the coldata attribute.
• class
  The class attribute of table cells in HTML output, if not overridden by an explicit table cell class.
• coldata
  Set the cell values of the column to a common value. Use the celldata attribute to set column cells to different values via a value list. colvalue is an alias attribute name.
• comment
  A free-form text comment.
• dataformat
  A formatting string which is used in text-oriented formats (i.e. HTML , Excel ) to reformat the data cell value on file output. Every instance of ‘%s’ in the formatting string is replaced by the cell value string, and that result be written to the file. The original cell content remains unchanged. With an empty formatting string (the default) the normal raw data formatting is used.
• datatype
  The column data type, which can be any data type a property definition can use. If there are already rows in the table when the command is executed, an attempt is made to cast the column values from their original data type to the new one. If this does not succeed, failing cells are set to NULL values. If the column is associated with a property, and the new data type is not storage-compatible with the native property datatype, the column connection with the property is lost.
• dbdefault
  This attribute is only used in SQL output. If it is not empty, its value is used to specify a column default value as per the SQL standard in the written table definition. The value is used verbatim in output, so depending on the column type, it may have to be properly quoted in SQL fashion.

The special value auto or #auto can only be used when there are already data rows in the table. With this command argument, and if the current data type is string , and the columns are not associated with a property and its native data type, the string contents of the data cells are analyzed across all rows, an optimally matching numerical data type (boolean, color, integer, double, date, uint64, intvector, doublevector) is determined and the column data type as well as the cell data contents are updated. This variant is usually used after reading some table data from a file in a format without explicit column data type information. For these inputs, the data is initially stored as string columns in the table object.

• dbflags
  This attribute encodes a set of hint flags for setting up SQL database columns for storing data of this table column. It format is the same of the dbflags attribute of property definitions (see prop set command). This column flag overrides the corresponding flag of a property linked to the column.
• dbforeignkey
  This attribute is only used in SQL output. If it is not empty, its value is used to specify a foreign key relationship as per the SQL standard in the written table definition. The format is foreigntable(foreigncolumn). The value is used verbatim in output, so if the foreign table or column contains unusual characters or whitespace, they must be properly quoted in SQL fashion. The allowed syntax of this attribute in the context of more exotic table or column names is dependent on the target SQL dialect and not checked when the attribute is set.
• dbindex
  Specify the type of index to be used on SQL database tables which are derived from this Cactvs table column. Possible values are none (the default, no index), generic (simple index with support for multiple identical values) and unique (primary index with no duplicate column data values).
• description
  A free-form textual description of the column.
• displaywidth
  A field output formatting width, usually defined in characters. This attribute is different from the fieldlength attribute, which defines an inherent data size. If the width is negative, the attribute is considered unset.
• editable
  A boolean flag indicating whether this column is editable or not. The default is editable.
• fgcolor
  The foreground column color, for output in formats which support this.
• fgcolorfunction
  A SQL -style function to compute the foreground color. If this is set, it has precedence over direct color specification via the fgcolor attribute, but has lower precedence that a foreground color specified directly on a cell.
• fieldlength
  The inherent field length, in characters or significant digits. This is attribute is different from the displaywidth attribute, which is only used for output formatting. A negative value defines the attribute as unset.
• flattening
  A boolean flag indicating if the column data should automatically be temporarily flattened (see table flatten command) on output.
• font
  The column-level output font name, or an empty string if it is not set.
• fontsize
  The column-level font size in points. If not set, zero is reported.
• format
  Column-level data format flags. This is the same set as for the global table attribute of the same name, which is explained in the section describing the table get command.
• function
  A SQL -style generator expression for the data in the column cells. This attribute has an effect only if the column type if type function . Cell data values are automatically recomputed when the function definition changes, or any of the data in the column the function references.
• headerbgcolor
  The background color of column headers. If not set, use an empty string.
• headerdata
  A data value for the column header data field. When set, it must be decodable by the input function for the column header data type. Note that this is data for the independent header data field, not for the main column cells.
• headerfgcolor
  The foreground color of column headers. If not set, use an empty string.
• headerfont
  The font to use for column headers, or an empty string if not set.
• headerfontsize
  The size of the font for column headers. If not set, zero is reported.
• headerformat
  Column header data format flags. This is the same set as for the global table attribute format, which is explained in the section describing the table get command.
• headerproperty
  The name of a property to associate the header data field with. If it is changed, existing column header data is discarded. Note that this is property which is independent of the main column cell property (attribute property ).
• imageparameters
  A keyword/value parameter set to be used for the computation of images. This attribute has an effect only on columns of type image . Any parameter defined here overrides the parameter of the same name in the global parameter settings on the image property (i.e. E_GIF , E_EMF_IMAGE , etc.). The parameter override is only temporary while the image data is computed. The global parameter set is not changed permanently.
• imageborder
  An integer image border value to be used when images are embedded in some output formats. For example, in HTML output this is used for the border attribute in the <img> tag.
• indexed
  A boolean flag indicating whether the data of the table column is currently indexed or not. Index creation or re-creation can be forced by setting it to true , and the index can be torn down by setting it to false . Note that this is not the same as the database index attribute dbindex . This index is an in-memory index on the column data which is used to accelerate simple look-ups via the table find command group. The read-only attribute index (see table getcol) is again not the attribute as this one.
• isname
  A boolean flag indicating that the column data contains names of persons. If set, table sort and comparison functions use a special string comparison algorithm to deal with titles and other personal name prefixes properly. This flag is ignored for columns which do not hold string data.
• linktext
  A text overlaying a link to use when formatting URL s in formats like HTML . An empty string results in the link value to be printed verbatim.
• mimetype
  An indication of the format of data held in blob or disk files. If the table column is linked to a property, the value of the property is copied when the column is created. This attribute is used for example when mapping blob columns to different KNIME image column types.
• name
  The primary name of the column. Columns should avoid duplicate names, though this is not illegal. In case multiple identical column names are desired, a suitable set of unique and different alias names should be configured, and columns only be identified by these alias names.
• note
  An arbitrary sequence of bytes attached as a column-level note.
• precision
  The precision of numerical column data values, in significant digits. This attribute overrides any precision defined for properties linked to the column. Negative precisions (presumably meaning that the numeric value is only precise to tens, hundreds etc. range) are currently not supported. Setting this attribute also sets the precision column format flag as a side effect.
• property
  The name of the property the column data is associated with. If this attribute is set, it also automatically defines the column data type, precision and unit by copying those values from the property definition record. If the property is changed, any current data values on this column are deleted. If the table rows are still associated with chemical objects, an attempt is made to re-fill the column data cells.

It is possible to define table columns which only refer to a specific field of a property. In that case, the name of the property is specified with standard field access syntax:

table setcol $thandle $col property E_IRSPECTRUM(source)

• reactionproperty
  A boolean flag indicating that the data in this table column is a reaction identifier, but not a direct structure encoding like a Reaction SMILES string or an RXN blob. This information can be used to restore structure information for tables where the rows have no references to external ensemble objects.
• reactionsource
  A boolean flag indicating that the data in this table column is a string-based reaction encoding in a format which could, for example, be decoded with a reaction create command. This information can be used to restore reaction information for tables where the rows have no references to external reaction objects.
• resetcellformat
  This is a pseudo attribute which can only be set. It takes a boolean argument. If it is true, all cell-level cell formats, which override the column/row/table-level formatting, are reset for this column.
• shape
  Set a KNIME -compatible graph rendering shape for the column. Valid shape names are default, rectangle, circle, triangle, revtriangle, diamond, asterisk, cross, xshape, hline and vline .
• shapesize
  Set a KNIME -compatible graph-rendering shape size multiplier for the column. This is a floating-point attribute, and 1.0 is the default.
• structureproperty
  A boolean flag indicating that the data in this table column is a structure identifier, but not a direct structure encoding like a SMILES string or an SD blob. This information can be used to restore structure information for tables where the rows have no references to external ensemble objects.
• structuresource
  A boolean flag indicating that the data in this table column is a string-based structure encoding in a format which could, for example, be decoded with an ens create command. This information can be used to restore structure information for tables where the rows have no references to external ensemble objects.
• transform
  A transformation function for numerical table data values. The currently supported types are linear (the default), inv (negated), abs (use absolute value), log or ln (natural logarithm), log10 (decadic logarithm), log2 (logarithm base 2), -log (negative natural logarithm), -log10 or p (negative decadic logarithm), -log2 (negative logarithm base 2), percent (multiplied by 100) and score (divided by 100). This attribute is for documentation only. The column data values are not updated by changing this attribute.
• type
  The table column type. Possible values are none , data (data defined via a property or at least a data type), image (an image of the structure or reaction associated with a data row, with the image property automatically chosen to be suitable for a specific output format) and function for data columns which are dynamically computed and updated from the contents of other columns by means of SQL -style expressions (see function attribute). If the column type is changed, any previous cell data for that column is deleted. If the table rows are still associated with chemical objects, and attempt is made to re-fill the column cells.
• unit
  A free-form string describing the unit of the data.
• urn
  A URN associated with the column.
• vectorsize
  If the data type of the column is a vector type, set the size of the individual cell data vectors in the column to a specified common size. If vectors get enlarged beyond their original size, they add 0 or NULL element values. If the size is smaller than that of an existing vector, it is truncated. If the column data type is not a vector, the command is ignored.

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:

• alias
  An alias name for the row which can be used to identify it in addition to its numerical index or primary row name.
• anchor
  A string as navigation aid pointing to this row. This attribute is only used in HTML output, where it is output as a <a name=“...“> tag.
• bgcolor
  The background row color, for output in formats which support this.
• class
  The class attribute of the <tr> tag. Only used in html output.
• data
  A list of the cell values for the row. The length of the list must be the same as the number of table columns. If more than one row is selected, the same values are entered for all these rows. values is an alias for this attribute.
• editable
  A boolean flag indicating whether this row is editable or not. The default is editable.
• ens
  Associate an ensemble with the table row. If this ensemble is not the same as the one currently associated, the old row data is invalidated, and an attempt is made to re-fill the row with data from the new ensemble. If the argument is an empty string, the row is explicitly set to be not associated with an ensemble. On retrieval, if no explicit or null ensemble association is set, but a column of the table is marked as structure source (see table setcol command), an attempt is made to create the ensemble from the data in the columns marked with this flag. These are scanned from left to right. If the data conversion from any of those succeeds, the new ensemble is automatically and permanently associated with the row, and the scan is stopped. An automatically created ensemble exists independently of the table in the normal chemical objects set, and must be explicitly deleted when no longer needed. structure is an alias for this attribute.
• fgcolor
  The foreground row color, for output in formats which support this.
• font
  The row-level output font name, or an empty string if it is not set.
• fontsize
  The row-level font size in points. Setting is to zero disables the attribute for this row.
• format
  Row-level data format flags. This is the same set as for the global table attribute of the same name, which is explained in the section describing the table get command.
• height
  An integer attribute to set the row height in various output formats, for example Excel or HTML . The unit depends on the output formats - usually these are pixels.
• label
  Associate the row with a minor object label. This makes only sense if the table row is also associated with an ensemble, and holds minor object data, such as atom or bond properties. If the value is set to minus one, the label is undefined.
• linktext
  A text overlaying a link to use when formatting URL s in formats like HTML . An empty string results in the link value to be printed verbatim.
• name
  Set the name of the row as arbitrarily formatted string. By default, and if row names were not read from file, rows do not have names and are addressed by their numerical indices. If an empty string is passed, this is interpreted as no name. It is not illegal to have multiple rows with the same name, but in that case care should be taken to identify them by their row index, or a suitably set unique alias.
• note
  An arbitrary sequence of bytes attached as a row-level note.
• reaction
  Associate a reaction with the table row. If this reaction is not the same as the one currently associated, the old row data is invalidated, and an attempt is made to re-fill the row with data from the new reaction. If the argument is an empty string, the row is explicitly set to be not associated with a reaction. On retrieval, if no explicit reaction or null association is set, but a column of the table is marked as reaction source (see table setcol command), an attempt is made to create the reaction from the data in the columns marked with this flag. These are scanned from left to right. If the data conversion from any of those succeeds, the new reaction is automatically and permanently associated with the row, and the scan is stopped. An automatically created reaction exists independently of the table in the normal chemical objects set, and must be explicitly deleted when no longer needed.
• shape
  Set a KNIME -compatible graph rendering shape for the row. Valid shape names are default, rectangle, circle, triangle, revtriangle, diamond, asterisk, cross, xshape, hline and vline .
• shapesize
  Set a KNIME -compatible graph rendering shape size multiplier for the row. This is a floating-point attribute, and 1.0 is the default.
• selected
  Mark the rows as selected or deselected, depending on the value argument.

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 names
  Valid property instances on the table are unlocked. Non-existent data is silently ignored. It is not possible to unlock individual property fields.
• all
  All valid table properties are unlocked.
• table
  This is an object class identifier. All property data which is controlled by the table major object and attached to the specified object class is unlocked. Since tables currently do not have minor objects, this command does the same as the all variant.

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:

• eod
  The end-of-data condition has been reached (see the eod, targeteod and checkeod table attributes)
• hasrows
  The table has one or more rows of data.
• norows
  The table contains no (more) rows
• script
  A script embedded in an RPC input stream was received. This flag is reset when an RPC transfer for the table begins, and set when either the script was received, or a status flag that no script will me sent in the transmission. In the latter case, the importscript attribute of the table is set to an empty string. Scripts are always transmitted after the table column definition and other structure information has been sent, but usually before all cell data has been transmitted.

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:

• append
  A boolean value of 1 as attribute value instructs the table I/O module to append the data, not to rewrite the file or database table. This is currently supported only for a few table formats, such as database table I/O modules which do not delete and recreate the destination table in this mode.
• compression
  Select the compression method of the table file format if it supports different types of compression. For example, ORC table files can use compression methods none, zlib or snappy. The allowed compression schemes depend on the format, and most formats do not use compression, or utilize a fixed method. In these cases, the value is ignored.
• colblocksize
  The column block size. specified as an integer of 1 (the default, no column blocking) or more. Not many table formats support the combination of columns into blocks. This is the same attribute as can be set or retrieved for the table as a table-level attribute, but if used in this context, it is not permanently changed. After the command completes, the old value is restored.
• colnames
  A boolean flag indicating whether the column names shall be included in the output or not. This flag is only honored when the file format allows a choice whether to include these or not.
• columns
  The argument is a column range list. Only the selected columns are output. By default, all columns are written. The alias cols is also recognized.
• compact
  A boolean attribute. If set, the output is formatted in a compact style, if the format supports distinct compact/compressed and expanded/beautified/human-readable representations. For most formats, this flag is ignored.
• corsdomain
  If specified, and the httpheader attribute is also set to a value larger than zero, the output HTTP header contains a CORS domain header line ( Access-Control-Allow-Origin: ). Useful values for this parameter are either * (for free access), a host name, or a domain name. If this parameter is not specified, HTTP headers do not contain information, which usually is equivalent to allowing access for AJAX queries only from the same server as the requesting page.
• debug
  A boolean flag indicating that, if set, debugging information should be printed while writing the file. This is primarily a developer option.
• downloadfilename
  If a HTTP header is configured (see httpheader attribute), a download target file name is included in the HTTP header if the attribute is not set to an empty string. By default, the value of this attribute is copied from the persistent downloadfilename table attribute. If it is neither set there, nor as transient write attribute, no save file name is transmitted.
• embedfileformat
  The format of embedded objects in the table. This is equivalent to setting the same attribute with a table set command. It is explained in the paragraph about the table get command.
• extsjsstatus
  This flag only applies to the extjs table file format. If set, the content is wrapped in an XML dictionary with keys success set to true, and the table data under key data . This format is expected by the ExtJS Web toolkit in response to AJAX submissions.
• firstrow
  The first row (in zero-based index notation) to output. By default, output starts at row zero.
• flatten
  A boolean flag indicating whether the data of columns of complex data types such as vectors and compound properties should be temporarily expanded into columns of simpler data types. Please refer to the table flatten command for more details. In any case, this variant of the flattening operation is transient and the table is restored to the same column set after the write as it had when the command was started. The default value for this option is dependent on the selected output format. If output is in a format which does not support vector data in cells, flattening is performed by default. For output in vector-capable formats, column flattening is disabled by default.
• formatbits
  A collection of additional formatting bits to be applied to the output besides the format-dependent standard set. This is not a commonly used attribute, and not every format bit is compatible with every output format. Example:

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 .

• frame
  A boolean value indicating whether certain graphical representations of structures or reactions should be wrapped in a frame or not. Examples are embedded OLE objects in XLSX and RTF output. By default, a frame is drawn around the structure or reaction rendering in these formats, ensuring, for example, uniform size and centering of the images in the output file. This option has only an effect if the rendering is produced implicitly at output time. If cell data has been explicitly set to, for example, an E_GIF or E_EMF_IMAGE , the presence or absence of a frame in the drawing is not checked and must have been configured by suitable property computation parameters when the image was computed. It is also possible to retain an invisible frame by setting its color to the background color, see framecolor table object attribute.
• httpheader
  Configure whether the table data content output should be prefixed by a HTTP header. This can be useful when scripting CGI or FCGI applications. The value can be 0 (no HTTP header prefix, the default), 1 (standard HTTP header prefix, without status code) or 2 ( HTTP header including 200 status code). String values none , default and status are also recognized. Not all table I/O modules support this feature.
• maxrows
  An integer indicating the maximum number of rows to write. A negative value (the default) indicates that there is no set limit.
• mode
  The output mode for the table, interpreted like the standard text file output modes. The value can be either w or a , and is ignored for most table file formats. The only exception are those formats which can store more than one table in the file. For these files, the current table may either be added or replaced in mode a (depending on the sheet name), or a new file is written with the current table as only data in mode w . The default value of this option is w , and it is not supported for direct string output ( table string command), where the implied value is always w .
• monochrome
  If this boolean value is set, the output of structure and reaction drawings is configured to be monochrome, i.e. use only black and white rendering colors. This applies only to renderings which are created at the moment the file is written (e.g. OLE objects or generic image class columns), but not if, for example, a GIF or EMF image has been set as explicit cell data - these are not re-computed. Cell property data formatting colors are not modified by this flag. The values of the framecolor and markcolor table attributes are ignored when the flag is set.
• oleautoupdate
  This boolean value only applies to output formats which include Microsoft OLE objects. Such files can be written in two styles: With the pre-rendered display (a WMF image) and the silent OLE data backing it, so that it is only updated when the OLE application supporting the embedded data format is started by a double click, or auto-updating, which means that the OLE application is automatically started when the document is opened and the image is re-rendered immediately. Generally, the pre-rendered images are of inferior quality than the native Windows re-rendered images, but re-rendering a lot of OLE objects in a document can take significant time. This option, which is by default off, lets you control the update style.
• overspill
  A boolean flag which can be set to prevent distributing tables onto multiple pages if the rendering of the table is larger than the configured paper size. This option has an effect only for output formats which use the concept of a paper as drawing area, such as RTF or CDXML and generally provide means to manually reformat the table in the native editing program (e.g. MS Word for RTF or ChemDraw for CDXML , but not PDF ).
• pagebreaks
  A boolean attribute which influences the placement of page breaks in some output formats, for example CDXML tables. If set, a new page is started at the end of a column block in rotated mode. By default, the current page is filled until no additional row or column can be placed.
• paperorientation
  The orientation of the paper for print output, specified as portrait or landscape . The default is portrait . This is not the same as the rotate attribute, which controls the layout of the table data, not the dimensions of the output medium. Only output formats which use paper-based formatting (currently this is jut PDF ) use this attribute. The parameter may also be abbreviated to orientation .
• papersize
  The size of the paper, specified as a standard name such as A4 or letter , to be used for formatting. This attribute is currently only used for PDF output and has no effect for other formats. This parameter may be abbreviated to simply paper . If this parameter is not set, the default paper size, which is configurable via the ::cactvs(paper_size) control variable, is used.
• recodebitvectors
  A boolean value indicating whether a bit vector should be recoded on output to an integer vector with zero bit padding for bits filling up a full integer value instead of writing a true bitvector. This is only supported on a few output formats, most notably SQL database formats.
• rotate
  A boolean flag which will, if set, virtually rotate the table by 90 degrees counterclockwise for output, thus swapping rows and columns. This is supported only for a few formats, such as HTML and Excel . The table object in memory does not change by this operation. The attribute controls the layout of the table output, not the dimensions of the output medium (see paperorientation parameter).
• rownames
  A boolean flag indicating whether the row names shall be included in the output or not. This flag is only honored when the file format allows a choice whether to include these or not.
• rows
  The argument is a row range list. Only the selected rows are output. By default, all rows are written.
• sheetname
  The name of the sheet the current table is stored in, if the selected output file format supports this concept. The default sheet name is dependent on the output format.
• structures
  A boolean flag indicating whether structures (ensembles and reactions) associated with the table rows should be included in the file. This option has an effect only for a few formats where this is supported, for example the native binary Cactvs table format. Only the primary row object is written - if cell data has been set from other structure objects, their association is not remembered and they are not included in the output.

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.