The connection Command

The connection command is used to access information about links in generic network objects (see network command). In many respects the behavior of connection objects in networks is comparable to that of bonds in ensembles, and the commands for handling connections are similarly structured. For example, just like bonds can be identified by a list of the participating atoms, connections can be selected by a list of the participating vertices.

Pseudo connection labels first , last and random are special values, which select the first connection in the connection list, the last, or a random connection.

The command edge is an alias for connection , allowing the use of a more standard nomenclature, but without the benefit of a matching prefix on the names of connection properties.

The following connection commands are supported:

connection append

connection append nhandle label ?property value?...
c.append({property:value,...})
c.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:

connection append $nhandle $c C_IDENT “_v2”

connection connection

connection connection nhandle label
Connection.Ref(nref,identifier)

Return the connection label stored in property C_LABEL ( Tcl ) , or a reference ( Python ). This is useful in case the label is not the straightforward connection label or minor object reference, but some other specification type, such as a vertex pair.

Example:

connection connection $nh [list $v1 $v2]

connection create

connection create nhandle vertex_list ?directionality? ?property value?...
Connection(nref,vertexsequence,?directionality=?,?property,value?...)
Connection.Create(nref,vertexsequence,?directionality=?,?property,value?...)

Create a new connection which links the vertices specified in the vertex list argument. In contrast to the handling of bonds in ensembles, there can be multiple connections with the same set of vertices in a network, and self-links (linked the same vertex as source and destination) are allowed. It is also possible to link more than two vertices by a connection. In some contexts the order of the vertices registered in a connection matters, i.e. the connections are interpreted as directional.

By setting the directionality parameter, the presence of a connection duplicate can be detected and in that case the old label (for Tcl ) or reference (for Python ) of the existing connection is returned, instead of creating a new connection. The possible values of the directionality parameter are undefined (or 0, the default, no duplicate checking), undirected (or 1, the vertices are matched regardless of the order in the specified list) and directed (or 2, the vertices are matched in the same order as in the argument list).

The magic vertex label value new can be used in the vertex list to automatically create one or more new vertices with this command instead of referring to existing vertices. The new vertices are added to the vertex list and have the same properties as vertices created explicitly with a vertex create command.

An initial set of property values for the new or re-used connection can be set by the optional property/value arguments.

The command returns the new or old connection label for Tcl , or the corresponding reference for Python .

connection defined

connection defined nhandle label property
c.defined(property)

This command checks whether a property is defined for the connection. 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

connection delete

connection delete nhandle ?label?...
connection delete nhandle all
c.delete()
Connection.Delete(nref,?label?,...)
Connection.Delete(cref,...)
Connection.Delete(nref,“all”)

Delete specific or all connection from the network. The vertices participating in the deleted connections remain in the network.

The command returns the number of deleted connections.

connection dget

connection dget nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The difference between connection get and connection 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, connection get and connection dget are equivalent.

connection network

c.network()

Python -only method to get the network reference from a connection reference.

connection exists

connection exists nhandle label ?filterlist?
c.exists(?filters=?)
Connection.Exists(nref=,label=,?filters=?)

Check whether this connection exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns boolean 0 if the connection does not exist, or fails the filter, and 1 in case of successful testing.

Examples:

connection exists $nhandle 99
connection exists $nhandle [list 1 2]

The second example checks whether a connection between vertices 1 and 2 exists. Instead of using a single label, all connection labels may be substituted by a list of the labels of their vertices.

connection filter

connection filter nhandle label filterlist
c.filter(filters)

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

connection get

connection get nhandle label propertylist ?filterset? ?parameterdict?
c.get(property=,?filters=?,?parameters=?)
c[property]
c.property

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

Example:

connection get $nhandle [list $v1 $v2] C_ONTOLOGY_LINK

yields the ontology link type data of connection 1 as a list. If the information is not yet 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 connection get command are connection new, connection dget, connection nget, connection show, connection sqldget, connection sqlget, connection sqlnew and connection sqlshow .

connection index

connection index nhandle label
c.index()

Get the index of the connection. The index is the position in the connection list of the network. The first position is index 0.

Example:

connection index $nhandle 99

connection jget

connection jget nhandle label propertylist ?filterset? ?parameterdict?
c.jget(property=,?filters=?,?parameters=?)

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

connection jnew

connection jnew nhandle label propertylist ?filterset? ?parameterdict?
c.jnew(property=,?filters=?,?parameters=?)

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

connection jshow

connection jshow nhandle label propertylist ?filterset? ?parameterdict?
c.jshow(property=,?filters=?,?parameters=?)

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

connection network

c.network()
Python
-only method to get the network reference from a connection reference.

connection new

connection new nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The difference between connection get and connection new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

connection nget

connection nget nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The difference between connection get and connection nget is that the latter always returns numeric data, even if symbolic names for the values are available.

connection ref

Connection.Ref(nref,identifier)

Python only method to get a connection reference. See connection connection command.

connection set

connection set nhandle label ?property value?...
c.set(?property,value?,...)
c.set({property:value,...})
c.property = value
c[property] = value

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

Example:

connection set $nhandle 1 C_IDENT “bla”

connection show

connection show nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The difference between connection get and connection 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, connection get and connection show are equivalent.

connection sqldget

connection sqldget nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The differences between connection get and connection sqldget are that the latter does not attempt computation of property data, but initializes the property value to the default and return 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.

connection sqlget

connection sqlget nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The difference between connection get and connection sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

connection sqlnew

connection sqlnew nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The differences between connection get and connection 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.

connection sqlshow

connection sqlshow nhandle label propertylist ?filterset? ?parameterdict?
c.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 connection get command. The differences between connection get and connection 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.

connection subcommands

connection subcommands
dir(Connection)

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

connection vertices

connection vertices nhandle label ?filterset? ?filtermode?
c.vertices(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the vertices which are participating in the connection. This is explained in more detail in the section about object cross-references.

Examples:

connection vertices $nhandle 1