The network Command

The network command is the major object command for network objects. These are a high-level abstraction for any kind of data relationship which can be expressed as a network of vertices and connections. Network objects do not have a direct relationship with ensemble or reaction objects, but of course network nodes or connections can store ensemble or reaction data. However, these are then stored as vertex or connection properties of the respective type and not as direct memberships, like ensembles or reactions which are a member of a dataset object.

The syntax of this command follows the standard schema of command/subcommand/majorhandle . Networks are major objects and thus do not need any minor object labels for identification.

There are currently no transient network objects.

Examples:

network get $nhandle N_CONNECTION_COUNT

This is the list of currently officially supported subcommands:

network append

network append nhandle property value ?property value?

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

Example:

network append $nhandle N_NAME “_new”

network assign

network assign nhandle srcprop dstprop

Copy data from one property to another. Both properties must be associated with the same object class. The source property (but currently not the destination property) may be specified as an indexed property subfield. There must exist a conversion path between the data types of the two properties or property subfields involved for the operation to succeed. For example, assigning a string property to a numeric property succeeds only if the string data items contain convertible numbers.

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 reactions (prefix N_), the operation is performed on all network nodes or vertices if appropriate.

Examples

network assign $nh V_IDENT V_NAME

network connections

network connections nhandle ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels 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?

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.

network dataset

network dataset nhandle =filterlist?

Return the dataset handle 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 is returned.

Example:

network dataset $nhandle

network defined

network defined nhandle 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 all
network delete ?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? ?parameterlist?

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?

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

network exists

network exists nhandle ?filterlist?

Check whether a network handle is valid. The command returns 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 dnandle 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

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

network get

network get nhandle propertylist ?filterset? ?parameterlist?
network get nhandle 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:

network getparam

network getparam nhandle 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. 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 key/value format.

network index

network index nhandle

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 list

network list ?filterlist?

Without a filter list argument, the command returns a list of the handles 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?

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:

A lock can be released by a network unlock command.

network max

network max nhandle propertylist ?filterset?

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?

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.

network min

network min nhandle propertylist ?filterset?

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?

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, the network is removed from its current dataset. If it was not a dataset member, this command does nothing. The dataset handle may be the name of a remote dataset for moving networks over a network connection.

If a dataset handle is specified, the network 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 network is added to the end of the dataset object list, but he final optional parameter allows the specification of an 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 network is appended as per the default. It is legal to use this command for moving networks within the same dataset.

Another special position value is random . This value moves to the network 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 membership of the network prior to the move. It is either a dataset handle, or an empty string if it was not member of a dataset.

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.

network mutex

network mutex nhandle mode

Manipulate the object mutex. During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing.

This command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes:

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

network need

network need nhandle propertylist ?mode?

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

Example:

network need $nhandle V_LEVEL recalc

network new

network new nhandle propertylist ?filterset? ?parameterlist?

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

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 pack

network pack nhandle ?maxsize? ?request_propertylist? ?suppress_propertylist?

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 other two optional parameters 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 ensemble.

The command returns the pack string.

network properties

network properties nhandle ?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?

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.

Examples:

network purge $nhandle N_NAME
network purge $nhandle V_ONTOLOGY_TERM 1
network purge $nhandke connection

network read

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

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 of the new network object.

Example:

set nh [network read “chebi.obo”]

network rename

network rename nhandle srcproperty dstproperty

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

network rewind

network rewind nhandle

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

network scan

network scan nhandle expression ?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:

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:

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?

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 ?key value?...

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.

network show

network show nhandle propertylist ?filterset? ?parameterlist?

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

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 script processing.

network sqlget

network sqlget nhandle propertylist ?filterset? ?parameterlist?

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 script processing.

network sqlnew

network sqlnew nhandle propertylist ?filterset? ?parameterlist?

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 script processing.

network sqlshow

network sqlshow nhandle propertylist ?filterset? ?parameterlist?

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 script processing.

network subcommands

network subcommands

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

network transfer

network transfer nhandle propertylist ?target_nhandle?

Copy property data from one network to another, 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 of the target network. The source and target networks 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 no target object is specified, 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

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 data locks are obtained by the network lock command.

network unpack

network unpack packstring

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

Example:

set packdata [network pack $nhandle]

set nhandle [network unpack $packdata]

network valid

network valid nhandle propertylist

Returns a list of boolean values indicating whether values for the named properties are currently set for the network. 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 ehandle 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 1, 0 if the data could be found but fails the tests, and an error condition otherwise.

network vertices

network vertices nhandle ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels 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?

Write the contents of a network object to a file. The output file format is deducted 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 file or socket handle.

The command returns the network handle.