network get $nhandle N_CONNECTION_COUNT

network append

network append nhandle ?property value?...

n.append({?property:value,?...})

n.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:

network append $nhandle N_NAME “_new”

network assign

network assign nhandle srcproperty dstproperty

n.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same network. Both properties must be associated with the network object class. This process is more efficient than going through a pair of network get/network 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 network 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.

If the properties are not associated with networks (prefix N_), the operation is performed on all network nodes or vertices if appropriate.

The command returns the object handle for Tcl , or object reference for Python .

Examples

network assign $nh V_IDENT V_NAME

network connections

network connections nhandle ?filterset? ?filtermode?

n.connections(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the connections the network contains as minor objects. This is explained in more detail in the section about object cross-references.

Examples:

network connections $nhandle

filter create isa_link property C_ONTOLOGY_LINK value is_a operator =

network connections $nhandle isa_link

The example simply returns a list of the labels of the connections the network contains as minor objects. The second example restricts these to the subset where property C_ONTOLOGY_LINK has a specific value.

network create

network create ?attribute value?...

network create ?dictionary?

Network(?attribute,value?,...)

Network(attributedict)

Network.Create(?attribute,value?,...)

Network.Create(attributedict)

Create a new network object. All networks are created empty. The optional attribute keyword/value list or single-parameter dictionary is processed just as with a network set command.

The return value of the command is the new network object handle or reference.

network dataset

network dataset nhandle ?filterlist?

n.dataset(?filters=?)

Return the dataset handle or reference of the dataset the network is member of. It the network is not member of a dataset, or does not pass all of the optional filters, an empty string (or None for Python ) is returned.

Example:

network dataset $nhandle

network defined

network defined nhandle property

n.defined(property)

This command checks whether a property is defined for the network. 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 network valid command is used for this purpose.

network delete

network delete ?nhandle/nhandlelist/all?...

n.delete()

Network.Delete(“all”)

Network.Delete(?nref/nrefsequence/nhandle?,...)

Delete network objects and all their associated vertices and connections. The special parameter all may be used to delete all networks currently registered in the application. Alternatively, any number of network handles may be specified for specific object deletions.

The command returns the number of deleted networks.

Example:

network delete all

network delete $nhandle

network dget

network dget nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The difference between network get and network 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, network get and network dget are equivalent.

network dup

network dup nhandle ?dataset? ?position?

n.dup(?target=?,?position=?)

Duplicate a network with all minor objects and all attached data on the network object proper and its minor objects.

The duplicate network is placed into the same dataset as the source, if it is a member of a dataset. Specifying an explicitly empty dataset argument (or None for Python ) places the duplicate outside any dataset, regardless of the dataset membership of the source network.

If the duplicate is moved to a dataset, it is appended to the dataset end by default. This happens also if the position parameter is explicitly specified as end or an empty string. Otherwise, the network is inserted at the given position, starting with 0. If the requested position is larger than the current size of the dataset, the network is appended.

Example:

network dup $nhandle

The command returns a new network handle or reference.

network exists

network exists nhandle ?filterlist?

n.exists(?filters=?)

Network.Exists(nref,?filters=?)

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

Example:

network exists $nhandle

network expr

network expr nhandle expression

n.expr(expression)

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

network filter

network filter nhandle filterlist

n.filter(filters=)

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

network get

network get nhandle propertylist ?filterset? ?parameterdict?

network get nhandle attribute

n.get(property=,?filters=?,?parameters=?)

n.get(attribute)

n[property/attribute]

n.property/attribute

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

Examples:

network get $nhandle {N_VERTEX_COUNT N_NAME}

yields the vertex count and name of the network as a list. If the information is not available, an attempt is made to compute it. If the computation fails, an error results.

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

Variants of the network get command are network new, network dget, network jget, network jnew, network jshow, network nget, network show, network sqldget, network sqlget, network sqlnew, and network sqlshow .

In addition to property data, the network object possesses a few attributes, which can be retrieved with the get command (but not by its related sister subcommands like dget, sqlget, etc.). Some of them are also modifiable via network set. These attributes are:

• 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 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 network, as free-form string data.
• authorurl
  A URL with information on the author, or an empty string if unset.
• category
  A category string to be used if the network is stored in a repository.
• classuuid
  The base class UUID of this network object, as related to its authorship attribute set.
• coords
  If the toolkit was compiled with factory support, these are the coordinates of the object on its workbench, encoded as integer pair. This attribute can be changed.
• deletable
  Flag indicating whether the object can be deleted with a standard network delete command. This attribute is read-only. Networks which are, for example, property data values or a part of a molfile loop command cannot be deleted by standard means.
• date
  The date the network structure was defined.
• doi
  A digital object identifier for the network object content, if defined.
• eolchars
  The default EOL character(s) to use when writing the table to text files. The default is the standard platform EOL character(s).
  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.
• email
  A contact email of the author.
• failures
  A list of properties for which computation failed on this 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.
• footer
  If the toolkit was compiled with factory support, this is the footer of the object icon on a workbench. This attribute can be changed.
• gflags
  If the toolkit was compiled with factory support, this is the currently set object icon rendering flag collection.
• header
  If the toolkit was compiled with factory support, this is the header of the object icon on a workbench. This attribute can be changed.
• 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.
• invisible
  Flag indicating whether the object 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 pointer references. This attribute is read-only.
• infourl
  A URL with information on the network object content, or an empty string if unset.
• 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 network object.
• license
  The license class associated with this network object. Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the network object license.
• literature
  A free-form literature reference.
• modcount
  Object structure modification count. This attribute is read-only.
• mutexcount
  The number of recursive mutex locks held for this object. Only supported on Linux.
• name
  A free-form network name as string.
• orcid
  The ORCID code of the author (see www.orcid.org).
• 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.
• record
  The current iterator record. The pseudo records follow the vertex list, the first vertex 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 network. This attribute is read-only.
• references
  Cross references of the network. This is a nested list of class UUID s and reference type tags.
• regid
  For registered data networks, the registration ID. Zero if this is a private network object.
• 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.
• 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.
• uuid
  An automatically generated UUID globally identifying the object. This attribute is read-only, different for every object, and not dependent on its contents.
• version
  A version number of the network. This is a string in a 1.2.3 (or shortened) style.
• versionuuid
  The version UUID associated with this network object as per its authorship attributes.
• x
  If the toolkit was compiled with factory support, this is the x coordinate of the object on its workbench. This attribute can be changed.
• y
  f the toolkit was compiled with factory support, this is the y coordinate of the object on its workbench.This attribute can be changed.

network getparam

network getparam nhandle property ?key? ?default?

n.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.

network hierarchy

network hierarchy nhandle ?filterlist? ?root?

n.hierarchy(?filters=?,?root=?)

Return the hierarchy handle or reference of the hierarchy the network is part of. If the network 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 network 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:

network hierarchy $nhandle

network index

network index nhandle

n.index()

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

network jget

network jget nhandle propertylist ?filterset? ?parameterdict?

n.jget(property=,?filters=?,?parameters=?)

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

network jnew

network jnew nhandle propertylist ?filterset? ?parameterdict?

n.jnew(property=,?filters=?,?parameters=?)

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

network jshow

network jshow nhandle propertylist ?filterset? ?parameterdict?

n.jshow(property=,?filters=?,?parameters=?)

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

network list

network list ?filterlist?

Network.List(?filters=?)

Without a filter list argument, the command returns a list of the handles or references of all existing network objects.

If a filter list is specified, only those networks which pass all filters are listed. Filters may refer to the minor objects of networks (i.e. vertices and connections). In that case, a filter succeeds if any vertex or connection passes the filter.

Examples:

network list

network lock

network lock nhandle propertylist/objclass/all ?compute?

n.lock(property=,?compute=?)

Lock property data of the network, meaning that it is no longer controlled by the standard data consistency manager. The data consistency manager deletes specific property data if anything is done to the network which would invalidate the information. Blocking the consistency manager can be useful when building networks 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 network or network minor objects 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 network and network minor object properties are locked. The compute flag is ignored.
• vertex , connection , network
  These is are object class identifiers. All property data which is controlled by the network major object and attached to the specified object class is locked.

A lock can be released by a network unlock command.

network max

network max nhandle propertylist ?filterset?

n.max(property=,?filters=?)

Get the maximum values of the properties named in the propertylist parameter. The return value of the command is a list of the maximum property values.

While it is possible to work with network properties, this is pointless since there is only a single instance of a network property per network. Usually, vertex or connection minor object properties are tested. The objects whose property values are used for the determination of the maximum values may optionally be filtered by a standard filter set. If no objects pass the filter, the result is an empty list.

Example:

network max $nhandle V_LEVEL

computes the maximum value of the V_LEVEL property over all vertices.

network metadata

network metadata nhandle property ?field ?value??

n.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 network setparam and network 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 .

network min

network min nhandle propertylist ?filterset?

n.min(property=,?filters=?)

Get the minimum values of the properties named in the propertylist parameter. The return value of the command is a list of the minimum property values.

While it is possible to work with network properties, this is pointless since there is only a single instance of a network property per network. Usually, vertex or connection minor object properties are retrieved. The objects whose property values are used for the determination of the minimum values may optionally be filtered by a standard filter set. If no objects pass the filter, the result is an empty list.

Example:

network min $nhandle V_LEVEL

computes the minimum value of property V_LEVEL over all vertices of the network.

network move

network move nhandle ?datasethandle|remotehandle? ?position?

n.move(?target=?,?position=?)

Make a network a member of a dataset, or remove it from a dataset. If the dataset handle parameter is omitted, or is 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.

By default, datasets do not accept networks as objects. This must be explicitly enabled by modifying the acceptance bits, as for example in

dataset append $dhandle accepts network

The dataset handle cannot be a transient dataset.

The return value of the command is the dataset of the network 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.

This command interacts with the insert control mechanism of size-constrained datasets. More information is provided in the description of the sizecontrol dataset parameter.

Examples:

network move $nhandle $dhandle 0

network move $nhandle

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

This command can be used with a remote dataset descriptor. In that case, the network 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 network is deleted if the transfer succeeds.

Example:

network move $nhandle blockbuster@server2:9998 end

This command moves the network to the dataset which was set up as listener on port 9998 and pass phrase blockbuster on host server2 . The local network is deleted, and its copy is inserted at the end of the remote dataset.

network mutex

network mutex nhandle mode

n.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.

network need

network need nhandle propertylist ?mode? ?parameterdict?

n.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 network handle or reference.

Example:

network need $nhandle V_LEVEL recalc

network new

network new nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The difference between network get and network new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

network nget

network nget nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The difference between network get and network nget is that the latter always returns numeric data, even if symbolic names for the values are available.

network nnew

network nnew nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The difference between network get and network 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.

network pack

network pack nhandle ?maxsize? ?requestprops? ?suppressedprops? ?compressionlib?

n.pack(?maxsize=?,?requestprops=?,?suppressedprops=?,?compressionlib=?)

Pack the network object into a base64-encoded compressed serialized object string. This string does not contain any non-printable characters and is a full dump of the internal state of the object, omitting only property data that was declared to be so easily re-computed that a dump is not worthwhile. The network vertex and connection minor objects and their property data are part of the dump.

The maximum size of the object string (default -1, meaning unlimited) 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.

The two optional parameter lists allow to request a specific property set to be part of the package, even if it normally would not be included, and to explicitly omit properties from the dump. No property computation is performed, and suppressed properties are not purged from the source ensemble.

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 , networks support the standard pickle / unpickle protocol.

network properties

network properties nhandle ?pattern? ?noempty?

n.properties(?pattern=?,?noempty=?)

Get a list of valid properties of the network proper and its vertex and connection minor objects.

The list can be filtered by a string match pattern. If the noempty flag is set, only properties where at least one data element controlled by the network (i.e. a value for an vertex of the network, etc.) is not the property default value are output. By default, the filter pattern is an empty string, and the noempty flag is not set.

Example:

network properties $nhandle N_*

network purge

network purge nhandle propertylist/network/vertex/connection ?emptyonly?

n.purge(?properties=?,?emptyonly=?)

Delete property data from the network. The properties may be network properties (prefix N_ ), or properties of the network minor objects, i.e. vertices (prefix V_ ) and connection (prefix C_ ). If a property marked for deletion is not found on the associated objects, it is silently ignored.

The optional boolean flag emptyonly allows to restrict the deletion to those properties where all the values of a property associated with a network object (such as on all vertices in a network for vertex properties, or just the single network property value for network properties) are set to the default property value.

In addition to property names, the object class names network, vertex or connection may be used. These delete all property data of that class from the network. They do not delete the objects proper, e.g. all vertices are still present after a network purge $nh vertex , though without any data that was not locked.

The return value is the original network handle or reference.

Examples:

network purge $nhandle N_NAME

network purge $nhandle V_ONTOLOGY_TERM 1

network purge $nhandke connection

network read

network read filename ?maxdefinitions?

Network.Read(filename=,?maxdefinitions=?)

Read network data from a file and create a new network object.

The filename argument can either be a disk file name, a pipe to an external generator program which starts with a vertical bar and is followed by the pipe programs and their parameters, the magic file name stdin , or, on Unix-class systems, an existing Tcl or Python file or socket handle.

Currently, there are seven network file formats which can be read. These are automatically identified by peeking into their contents, not by their file name. The recognized formats are:

• the native Cactvs network object dump file (standard suffix .nbin ),
• OBO ontology definition files in version 1.2 (standard suffix .obo ).
• GeneOntology ontology definition files (standard suffix .go )
• SIF network files (standard suffix .sif )
• GML network files (standard suffix .gml )
• XGMML network files (standard suffix .xgmml or .gr )
• KEGG metabolism networks (standard suffix .kgml or .kegg )
• KNIME network data files (standard suffix .knet) . These can only be read from a disk file, not a pipe or other data channel because they are internally a zipped collection of data files.

All of these formats can store only a single top-level network, so there are no record positioning commands for network data input. Nested networks, for example in the GML or XGMML formats, are currently not directly readable. Some additional network file formats can currently be written, but not read (for example, GraphViz . gv and KNIME BEEF ).

The optional definition count argument can be used to stop reading a file after the specified number of vertex definitions have been read. This is basically a debug feature which allows program testing with a smaller network. The option is not supported with native Cactvs network dump files.

The command returns the handle or reference of the new network object.

Example:

set nh [network read “chebi.obo”]

network ref

Network.Ref(identifier)

Python
 only method to get a reaction reference from a handle or another identifier. For networks, other recognized identifiers are network references, integers encoding the numeric part of the handle string, the UUID
 of the network object, or its name.

network rename

network rename nhandle srcproperty dstproperty

n.rename(srcproperty=,dstproperty=)

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

network rewind

network rewind nhandle

n.rewind()

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

network scan

network scan nhandle expression/queryhandle ?mode? ?parameterdict?

n.scan(query=,?mode=?,?parameters=?)

Perform a query on the network. The syntax of the query expression is the same as that of the molfile scan command and explained in more detail in its section about query expressions. In many aspects, this command behaves like an in-memory data file version of the molfile scan or dataset scan commands. The main difference is that the primary objects that are scanned are the vertices of the network, and their property data (or indirectly, the data of the network major object, or the directly attached connection minor objects) is what is checked when determining a match or mismatch.

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 network handle is passed as argument in place of the molfile handle in molfile scan .

The vertices of the network are visited in the order of their index value (see vertex index command). This index value plus one is used also used as a replacement for the record number of a vertex in the dataset.

The return value depends on the mode. The default mode is vertexlist . The following modes are supported for dataset queries:

• array (or alias tclarray, dict, pythondict )
  The mode parameter is a list consisting of the mode selector array and a nested list of properties and pseudo-properties. Each property item can be a list of one to three elements. The first element is a property or pseudo-property, the second element a name, and the third element again a property or pseudo property. The the second property item list element is omitted, the name is the same as the first element. If the third element is missing, it is assumed to be the pseudo-property record .

In this mode, the command returns a list of the names of the created arrays. For each name, a global Tcl array variable or Python dictionary is created, and for each match, a Tcl array element with an element name equal to the value of the first item specification index and an element value equal to the value of the third item specification is created (or a dictionary entry with key and value for Python ). For example, the scan mode specification

{array {V_LABEL id2rec} {record rec2id V_LABEL}}

results in the creation of two global Tcl arrays or Python dictionaries in the current interpreter, called id2rec and rec2id . The first has array elements (for Python , dictionary keys) where the element name is the label of the matching vertex (property V_LABEL ), and the value the pseudo-record number (the default since the third list parameter is omitted). The second array has elements where the record number is the array element name, and the corresponding value the vertex label. The return value of the scan statement is the list (tuple for Python ) “id2rec rec2id” , containing the names of the two variables created.

If array elements for a specific key already exist, the new value is appended as a list object. The registration procedure does not overwrite existing content. Since global arrays are persistent, data is appended over multiple scan statements. If this is not desired. a statement like unset -nocomplain $arrayname should be executed before the scan is started. It is legal to use the same array name to register multiple properties in the array. In that case, any match appends a new list element for every property. The list is however not nested.

• bitvector
  Return a string-encoded bit vector (series of 0s and 1s) indicating the match status for every visited vertex.
• boolean
  Return a boolean value indicating whether the next vertex matches or not.
• booleanvector
  Return a boolean vector (series of 0s and 1s as vector elements) indicating the match status of every visited vertex. The difference to the bitvector mode is that in the scripting interface the vector elements are already isolated elements, for example they appear space-separated in the string form.
• count
  Count the number of hits. The result value is an integer.
• delete
  Delete hit vertices from the network. This is the only scan command which actually changes the network.
• exists
  A boolean check for the existence of a hit. The same as count, except that the scan stops after the first match.
• file
  The mode parameter is a list consisting of the mode selector file and a molfile handle, which must have been opened for writing, appending, or updating. The first matching vertex is written to the file. After that. the scan stops. File attributes determine format, selection of data written, structure encoding conventions such as hydrogen status, etc. If no matching vertex is found, nothing is written. This mode only works with structure files that can accept a vertex or a network object as output target. There are no I/O modules in the standard toolkit package which currently have this capability.
• filelist
  The mode parameter is a list consisting of the mode selector file and a molfile handle, which must have been opened for writing, appending, or updating. Matching vertices are written to that file. File attributes determine format, selection of data written, structure encoding conventions such as hydrogen status, etc. If no matching vertex is found, nothing is written. This mode will only work with structure files that can accept a vertex or a network object as output target. There are no I/O modules in the standard toolkit package which currently have this capability
• index
  This is the same as record , except that the returned value is one less, since indices start with zero.
• indexlist
  This is the same as recordlist , except that the returned value is one less, since indices start with zero
• property
  The mode parameter is a list consisting of the mode selector property and a sequence of properties and pseudo-properties. The selected properties for the first match are returned as a list. After the first match, the scan stops. If there are no hits, an empty string is returned. Properties which can be used in network scans are either of the vertex class (prefix V, the most common case for network queries), class network (prefix N, of limited value since there is only a single network scanned, and the property values are thus the same for all matches), or of the connection class (prefix C). Connection properties are reported as lists which contain the data of all connections the matching vertex participates in.
• propertylist
  The mode parameter is a list consisting of the mode selector propertylist and a sequence of properties and pseudo-properties. The selected properties for all matches are returned as a nested list. If there are no hits, an empty string is returned. This mode is also selected if the mode argument is simply a list of property and pseudo property names without an identifiable mode keyword as first list element.
• record
  Return the sequence number of the first hit. Sequence numbers begin, for the sake of comparability with structure file scan record numbers, with one and are equivalent to the vertex index position plus one. The scan stops after the first match.
• recordlist
  Return sequence numbers of all hits, or an empty list. Sequence numbers begin, for the sake of comparability with structure file scan record numbers, with one and are equivalent to the vertex index position plus one.
• table
  The mode parameter is a list consisting of the mode selector table and a sequence of properties and pseudo-properties. This scan mode returns a table handle. The table is automatically configured with properly typed columns corresponding to the requested properties. For each hit, a row is added. If there are no hits, a table handle is still returned, but the table does not have any rows. This retrieval mode is only available if the toolkit has been compiled with table support. The individual properties may also be specified each as a list consisting of the property name, and an arbitrary string. In that case, the string is used as the column name. By default, the column names are the same as the name of the property they store. Example:

{table V_LABEL N_CONNECTION_COUNT C_LABEL C_ONTOLOGY_LINK}

sets up a table with four columns that store the matching vertex label, the network connection count (the same value for all rows, since all matches are all on the same network), and the labels and link types of the connections attached to the matched vertex. The latter two columns are automatically stored as vector types, since there are potentially multiple values associated with a single matching vertex.

Instead of the keyword table , an existing table handle may also be used. In that case, any existing matching table columns are automatically re-used to store result data. Additionally specified properties are added as new columns to the right of the previously existing columns. New table rows generated by matches are appended to the bottom of the table.

• tablecollection
  Since all objects subject to scans with this command are already in memory, this mode is identical to the table scan mode for network scans. No duplicate table reference objects are created. The result table always refers the network objects directly.
• vrecord
  For network scans, this is the same as record .
• vrecordlist
  For network scans, this is the same as recordlist .
• vertex
  Report the label of the first matching vertex. This is functionally equivalent to the mode property V_LABEL , though internally optimized. The scan stops after the first match.
• vertexlist
  Report a list of the labels of the matching vertices. This is functionally equivalent to the mode propertylist V_LABEL , though internally optimized.

If requested property data is not present on vertices to be tested, an attempt is made to compute it. If this fails, in retrieval mode table NULL cells are generated, and property retrieval as list data produces empty list elements, but no errors.

The following pseudo properties can be retrieved in addition to normal properties:

• avgscore
  The average value of all computed scores, such as Tanimoto, Cosine or Tversky similarity scores, in the matching query for this result.
• conformerindex
  The index of the matching conformer in case of 3D queries with multiple conformations, -1 if no matching conformer index was determined.
• conformer
  A list of the atomic coordinates of the matching conformer, if a 3D query was performed. If this is not the case, an empty vector is the result. The data type of this vector is coorvec (x,y,z-triples as vector elements).
• filename
  This pseudo-property is only provided for compatibility with molfile scan . It is always an empty string.
• image
  A structure GIF image (property E_GIF ) with highlighted matching substructure atoms and bonds. A normal E_GIF retrieval property would just show the structure, but without highlighting. The data type of this property is the same as that of E_GIF (depending on the configuration, a diskfile reference or an in-memory blob).
• index
  This is the same as record , except that the retrieved value is one less, since indices start with zero.
• matchatoms
  An integer vector holding the labels of all atoms matching the substructures used in evaluating the query expression. If no substructure was used for the match, this vector is empty. highlighatoms is an alias for this pseudo property.
• matchbondatoms
  The same as matchbonds , except that each element is a pair of the labels of the matching atoms in the bonds, not the bond label as a single number.
• matchbonds
  An integer vector holding the labels of all bonds matching the substructures used in evaluating the query expression. If no substructure was used for the match, this vector is empty. highlightbonds is an alias for this pseudo property.
• matchcount
  The first element of the matchcounts array, as described below. If the query does not contain any substructure match nodes, the result is empty.
• matchcounts
  An integer vector holding the number of distinct substructure matches for substructure query nodes in the query tree. For normal substructure expressions, this value can only be zero or one because the standard substructure match mode only checks for the presence of any match (match mode first ). Additionally, this value can be minus one if the node was never evaluated, for example because it is part of an or expression. Only if the count modifier is used together with the substructure query operator, or the substructure operator is the range operator, the possibility of multiple matches is evaluated and larger values can be obtained. For these operations the default match mode is distinctinneratoms (see match ss command).
• matchmask
  A bitvector indicating which children of the root query node have matched. The length of the bitvector is the same as the number of children of the root node. A typical application of this retrieval item is in combination with a range node as root node.
• maxscore
  The maximum value of all computed scores, such as Cosine, Tanimoto or Tversky similarity scores, in the matching query for this result.
• merit
  For queries which use a merit/demerit rating scheme (for example, Bruns/Watson queries) this retrieves the accumulated merit/demerit sum of the top-level query node. The query needs to match for this retrieval to work, so in case none of the demerit rules match, you get an empty result, not a default zero merit/demerit value. Internally, there is no distinction between merit and demerit scores. The keyword demerit is an alias for this pseudo-property.
• minscore
  The minimum value of all computed scores, such as Cosine, Tanimoto or Tversky similarity scores, in the matching query for this result.
• parent
  The parent structure of the matching structure as a packed, base64-encoded serialized object string. If the dataset ensemble does not already contain it, it is computed from the structure as property E_PARENT_STRUCTURE .
• productmatchatoms
  The same as the matchatoms pseudo property, but for the ensemble on the right side of a matching reaction, not a simple structure. If no reaction was matched, this is an empty list.
• productmatchbondatoms
  The same as the matchbondatoms pseudo property, but for the ensemble on the right side of a matching reaction, not a simple structure. If no reaction was matched, this is an empty list.
• productmatchbonds
  The same as the matchbonds pseudo property, but for the ensemble on the right side of a matching reaction, not a simple structure. If no reaction was matched, this is an empty list.
• queryid
  The ID of the search tree query item which was responsible for the principal match. Every tree element of a query expression possesses an ID, starting with 1, and then assigned in incremental sequence from left to right in depth-first manner. For simple property or structure match expressions, the query ID is the ID of the matching branch, i.e. one for single-node expressions. For logical expressions with an or , orcontinue or not node, the overall reported query ID is that of the first matching leaf node. For expressions, where all leaves need to be checked, the query ID is the ID of the and or eor node where all leaves matched, not the ID of any individual leaf node.
• reagentmatchatoms
  The same as the matchatoms pseudo property, but for the ensemble on the left side of a matching reaction, not a simple structure. If no reaction was matched, this is an empty list.
• reagentmatchbondatoms
  The same as the matchbondatoms pseudo property, but for the ensemble on the left side of a matching reaction, not a simple structure. If no reaction was matched, this is an empty list.
• reagentmatchbonds
  The same as the matchbonds pseudo property, but for the ensemble on the left side of a matching reaction, not a simple structure. If no reaction was matched, this is an empty list.
• record
  The record number. In the context of in-memory datasets, this is the dataset list index of the matching object plus one. rc is an alias for this pseudo property.
• rgatoms(rg)
  A list of the atom labels in a matching structure which were mapped to an expanded R-group atom in the query. The property index is the name of the R-group of interest defined in the substructure, usually something like R1. If there was no expanded R-group of that name, the result list is empty.
• rgattachments(rg)
  A nested list of the atom label pairs of the bonds in a matching structure which connect between the structure framework and the atoms expanded as the named R-group rg . If there was no expanded R-group of that name, the result list is empty.
• score
  The first element of the scores array, as described below. If the query does not contain any scoring expressions, the result is empty.
• scores
  An integer vector of the results of all query expression branches, in depth-first left-to-right order, which computed a score, such as structure similarity queries with Cosine, Tanimoto or Tversky bitvector comparisons. In case a branch was not executed when the match was determined, a zero value is reported.
• structure
  The matched structure as a packed, base64-encoded serialized object string.
• vrecord
  For network object scans, this is always the same as record.

These pseudo properties are identical to those available for structure file queries. However, structure file queries allow the use of a couple of additional pseudo properties which are not supported for network queries.

network set

network set nhandle ?property value?...

network set nhandle ?dictionary?

n.set(property,value,...)

n.set({property:value,...})

n.property = value

n[property] = value

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

network setparam

network setparam nhandle property ?key value?...

network setparam nhandle property dictionary

n.setparam(property,?key,value?...)

n.setparam(property,dict)

Set or update a property computation parameter in the metadata parameter list of a valid property. This command is described in the section about retrieving property data. The current settings of the computation parameters in the property definition are not changed.

The return value is the updated property computation parameter dictionary.

network show

network show nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The difference between network get and network 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, network get and network show are equivalent.

network sqldget

network sqldget nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The differences between network get and network 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.

network sqlget

network sqlget nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The difference between network get and network sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

network sqlnew

network sqlnew nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The differences between network get and network 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.

network sqlshow

network sqlshow nhandle propertylist ?filterset? ?parameterdict?

n.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 network get command. The differences between network get and network 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.

network subcommands

network subcommands

dir(Network)

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

network transfer

network transfer nhandle propertylist ?targethandle? ?targetpropertylist?

n.transfer(properties=,?target=?,?targetproperties=?)

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

If a target object is specified, the return value is the handle or reference of the target object. The source and target object cannot be the same object. In case a property associated with network minor objects (connections and vertices), the behavior is the same as described for ensemble minor objects in the documentation of ens transfer .

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 network 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 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.

network unlock

network unlock nhandle propertylist/objclass/all

n.unlock(property=)

Unlock property data for the network, 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 or references
  Valid property instances on the network, or network minor objects are unlocked. Non-existent data is silently ignored. It is not possible to unlock individual property fields.
• all
  All valid network or network minor objects properties are unlocked.
• vertex, connection, network
  These are object class identifiers. All property data which is controlled by the network major object and attached to the specified object class is unlocked.

Property data locks are obtained by the network lock command.

The command returns the original network handle or reference.

network unpack

network unpack packstring ?compressionlib?

Network.Unpack(data=,?compressionlib=?)

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

Packed networks may also be unpacked by the network create command.

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

Example:

set packdata [network pack $nhandle]

set nhandle [network unpack $packdata]

network valid

network valid nhandle propertylist

n.valid(property/propertysequence)

Returns a list of boolean values indicating whether values for the named properties are currently set for the network or its minor objects. No attempt at computation is made.

Example:

network valid $nhandle V_ONTOLOGY_TERM

will report whether the network has ontology term definitions attached to its vertices or not.

network has is an alias to this command.

network verify

network verify nhandle property

n.verify(property)

Verify the values of the specified property on the network. The property data must be valid, and a network or network minor sub-object 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.

network vertices

network vertices nhandle ?filterset? ?filtermode?

n.vertices(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the vertices the network contains as minor objects. This is explained in more detail in the section about object cross-references.

Examples:

network vertices $nhandle

filter create rootnode property V_LEVEL value 0 operator =

network vertices $nhandle rootnode

The example simply returns a list of the labels of the vertices the network contains as minor objects. The second example restricts these to the subset where property V_LEVEL has a specific value.

network write

network write nhandle filename ?format?

n.write(filename=,?format=?)

Write the contents of a network object to a file. The output file format is deduced from the suffix of the file name. If it is not recognized, the native toolkit format (default suffix .nbin) is used. This default mechanism can be overridden by giving an explicit format name in the optional argument.

The currently supported network output formats are Cactvs native (. nbin ), SIF (. sif ), GML (. gml ), XGMML (. xgmml , . gr ), KNIME network data (. knet ) , BEEF (. beef )., GraphViz (. gv ), and KEGG metabolic network (. kgml ). OBO and GeneOntology ontology files can only be read, but not written. Predefined format alias names include knime for KNET files, and bisonet for BEEF . Zipped BEEF files cannot be written directly at this time, but can readily be obtained by first writing an unpacked BEEF file and then running an external standard zip-compatible compressor on it.

The file name may be either a disk file name, one of the magic file names stdout or stderr , a pipe construct, or, on Unix-class operating systems, an open Tcl or Python file or socket handle.

The command returns the original network handle or reference.