The vertex Command

The vertex command is used to access information about vertices in generic network objects (see network command). In many respects the behavior of vertex objects in networks is comparable to that of atoms in ensembles, and the commands for handling vertices are similarly structured.

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

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

The following vertex commands are supported:

vertex append

vertex append nhandle label ?property value?...
v.append({?property:value,?...})
v.append(?property,value,?...)

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

vertex children

vertex children nhandle label ?filterset? ?filtermode? ?sphere? ?allowduplicates?
v.children(?filters=?,?mode=?,?sphere=?,?allowduplicates=?)

This is a variant of the vertex neighbors command, with the additionally applied constraint that all matching vertices must have a value of property V_LEVEL which is exactly higher by one than that of the originating vertex.

The command parameters are explained in the paragraph on command vertex neighbors .

The vertex parents command can be used to find parents instead of children.

vertex connections

vertex connections vhandle label ?filterset? ?filtermode?
v.connections(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the connections the vertex is participating in. This is explained in more detail in the section about object cross-references.

Example:

vertex connections $nh $v

vertex create

vertex create nhandle ?property value?...
Vertex(nref,?property,value?...)
Vertex(nref,dict)
Vertex.Create(nref,?property,value?...)
Vertex.Create(nref,dict)

Create a new vertex in the existing network object. The new vertex is created without any connections or initial data except for its automatically assigned label.

An initial set of vertex properties can be set by the optional property/value arguments.

The commands returns the label or reference of the new vertex.

vertex defined

vertex defined nhandle label property
v.defined(property)

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

vertex delete

vertex delete nhandle ?label?...
vertex delete nhandle all
v.delete()
Vertex.Delete(nref,?label?,...)
Vertex.Delete(vref,...)
Vertex.Delete(nref,“all”)

Delete specific or all vertices and all connections a deleted vertex is participating in.

The command returns the number of deleted vertices.

vertex dget

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

vertex exists

vertex exists nhandle label ?filterlist?
v.exists(?filters=?)
Vertex.Exists(nref=,label=,?filters=?)

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

Example:

vertex exists $nh 99

vertex filter

vertex filter nhandle label filterlist
v.filter(filters)

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

Example:

filter create rootnode property V_LEVEL value 0 operator =
vertex filter $nh $v rootnode

vertex get

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

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

Examples:

vertex get $nhandle 1 {V_LABEL V_IDENT}

yields the label and ID data of vertex 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.

vertex get $nhandle 1 C_ONTOLOGY_LINK 

gets the ontology link types of all connections the vertex participates in.

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

Variants of the vertex get command are vertex new, vertex dget, vertex nget, vertex show, vertex sqldget, vertex sqlget, vertex sqlnew and vertex sqlshow .

Further examples:

vertex get $nhandle 1 V_ONTOLOGY_TERM(structurehash)

vertex index

vertex index nhandle label
v.index()

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

Example:

vertex index $nhandle 99

vertex jget

vertex jget nhandle label propertylist ?filterset? ?parameterdict?
v.jget(property=,?filters=?,?parameters=?)

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

vertex jnew

vertex jnew nhandle label propertylist ?filterset? ?parameterdict?
v.jnew(property=,?filters=?,?parameters=?)

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

vertex jshow

vertex jshow nhandle label propertylist ?filterset? ?parameterdict?
v.jshow(property=,?filters=?,?parameters=?)

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

vertex neighbors

vertex neighbors nhandle label ?filterset? ?filtermode? ?sphere? ?allowduplicates?
v.neighbors(?filters=?,?mode=?,?sphere=?,?allowduplicates=?)

This command (which can also be invoked as subcommand neighbours ) is a cross-referencing command with some extra options and, in some filter modes, slightly different behavior than the standard object cross-reference subcommands.

In the simplest case, it returns the labels or references of the immediate neighbor vertices. A neighbor vertex is a vertex which is linked via a connection to the originating vertex. In case the filter list contains connection filters, the connection leading to the originating vertex must pass the check, not just any connection of the neighbor vertex.

Example:

filter create onto_isa property C_ONTOLOGY_LINK value is_a operator =
vertex neighbors $nhandle 1 onto_isa

returns a list of neighbor vertex labels which are linked via a connection which encodes an ontological “is a” definition. Neighbor vertices which participate in such a link with another vertex, but not the originating vertex, are not returned.

This command supports two special filtermode values in addition to the standard set ( exists, count, exclude, include ). The incoming mode only sees links where the originating or previous vertex is the last vertex in the vertex list of any passed connection. The outgoing mode only sees links where the originating or previous vertex is the first vertex in the vertex list of any passed connection.

Example:

vertex neighbors $nh $vlabel {} outgoing

only returns the links where the originating vertex is the first vertex in the connection linking the originating vertex to its neighbor. In applications where the connections are set up in a directional fashion, or example in networks representing an ontology with “is a” relationships, this mode allows the traversal of the network in the direction of increasingly generic terms.

By default vertices in the immediate neighborhood are examined, but this change be changed by the sphere parameter. The immediate neighbors are in sphere 1 (the default for this parameter), the next group of vertices is in sphere 2, and so on. If the sphere is not 1, the special filtering of connections is no longer active and the normal object substitution mechanism for cross referencing is used. When going beyond the first sphere, it is also possible that a vertex may be reached by multiple paths of the selected length. By default, these vertices are returned only once, but with the last optional parameter this behavior may be changed.

A positive sphere value only selects vertices in that sphere. A negative sphere parameter value returns a list of all neighbors up to and including the sphere identified by the absolute parameter value.

Example:

vertex neighbors $nh $vlabel {} outgoing -5

Above example reports the labels of all vertices of to a distance of 5 steps from the starting point which can be reached via outgoing directional connections.

vertex network

v.network()

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

vertex new

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

vertex nget

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

vertex parents

vertex parents nhandle label ?filterset? ?filtermode? ?sphere? ?allowduplicates?
v.parents(?filters=?,?mode=?,?sphere=?,?allowduplicates=?)

This is a variant of the vertex neighbors command, with the additional automatically applied constraint that all matching vertices must have a value of property V_LEVEL which is exactly one less than that of the originating vertex.

While it would often be expected that there is only a single parent to a vertex, this is not a condition enforced in a generic network, and potentially multiple parents can be found and reported by this command. In any case, the command alias vertex parent in singular is also recognized.

The command parameters are explained in the paragraph on command vertex neighbors.

The vertex children command can be used to find children instead of parents.

vertex paths

vertex paths nhandle label targetlabel ?parameterdict?
v.paths(target=,?parameters=?)

This command finds paths between a pair of vertices, traversing connections.

The return value of the command is a nested list, even it only a single path is found. Every sublist contains all the labels (if this is not overridden in the parameter dictionary) of the vertices in one path, including those of the start and end vertices. Every connection is used only once in any path, and no path crossings through a vertex are allowed. Every vertex, with the possible exception of path end points, appear only once in any single path. Paths from a vertex via some connections back to itself are allowed. The vertex must be a member of a cyclic connection for such paths to exist.

If the destination vertex is specified as an empty string, all possible paths emerging from the source vertex and not violating any other specified constraints are returned. This includes shorter sub-paths which are contained in a longer paths - these are reported as separate result items.

The optional parameter dictionary can be used to further customize the path walking and result reporting. The following dictionary keywords are recognized:

Example:

vertex paths network0 $v1 $v2 \	[dict create property V_ONTOLOGY_TERM(id) flags outgoing]

This example returns all paths from network vertex v1 to v2 in outgoing direction. The reported path data is the value of field id of property V_ONTOLOGY_TERM on every vertex in the paths.

vertex ref

Vertex.Ref(nref,identifier)

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

vertex set

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

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

Example:

vertex set $nhandle 1 V_IDENT “V1294”

vertex show

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

vertex sqldget

vertex sqldget nhandle label propertylist ?filterset? ?parameterdict?
v.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 vertex get command. The differences between v ertex get and vertex 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.

vertex sqlget

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

vertex sqlnew

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

vertex sqlshow

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

vertex subcommands

vertex subcommands
dir(Vertex)

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

vertex vertex

vertex vertex nhandle label
Vertex.Ref(nref,identifier)

Return the vertex label stored in property V_LABEL ( Tcl ) or a minor object reference ( Python ). This is useful in case the label used in the command is not a straightforward numerical label or reference but some other vertex identification format.