The biologics command

Biologics objects are a high-level representation of biological macromolecules. Internally, they are a network of items, connected by links. Items usually are superatoms, and links a more intricate type of bond which do not just link the superatom items, but additionally contain information about where and how the links connect to the superatoms in expanded form. Biologics can usually be expanded into normal structure ensembles with standard atoms and bonds.

Biologics are major objects. Associated properties start with a Q_ prefix.

biologics append

biologics append bhandle ?property value?...
b.append({?property:value,?...})
b.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.

biologics assign

biologics assign bhandle srcproperty dstproperty
b.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same biologics object. Both properties must be associated with the biologics object class. This process is more efficient than going through a pair of biologics get/biologics 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 biolgics 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 biologics (prefix Q_), the operation is performed on all bioitem nodes or biolinks if appropriate.

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

Examples

biologics assign $bh I_IDENT I_NAME

biologics create

biologics create ?data?
biologics create attribute value...
Biologics(?data?)
Biologics(dict)
Biologics(attribute,value,...)
Biologics.Create(?data?)
Biologics.Create(dict)
Biologics.Create(attribute,value,...)

Create a new biologics object. There are three basic styles.

Biologics items can be created as empty shells if no arguments are used. Alternatively, if a single argument is used, they can be initialized by decoding a line notation. Supported notations currently include pack strings (see biologics pack ), and 1- or 3-letter amino acid codes. The third option is to use an attribute dictionary - either as a single argument, or as a series or key-value pairs.

The command returns the new object handle or reference.

biologics dataset

biologics dataset bhandle ?filterlist?
b.dataset(?filters=?)

Return the dataset handle or reference of the dataset the biologics item is a member of. It the biologics item 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:

biologics dataset $bhandle

biologics defined

biologics defined bhandle property
b.defined(property)

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

biologics delete

biologics delete ?bhandle/bhandlelist/all?...
b.delete()
Biologics.Delete(“all”)
Biologics.Delete(?bref/brefsequence/bhandle?,...)

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

The command returns the number of deleted biologics.

Example:

biologics delete all
biologics delete $bhandle

biologics dget

biologics dget bhandle propertylist ?filterset? ?parameterdict?
b.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 biologics get command. The difference between biologics get and biologics 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, biologics get and bioologics dget are equivalent.

biologics dup

biologics dup bhandle ?dataset? ?position?
b.dup(?target=?,?position=?)

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

The duplicate biologics object 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 biologics object.

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 biologics object is inserted at the given position, starting with 0. If the requested position is larger than the current size of the dataset, the biologics item is appended.

Example:

biologics dup $bhandle

The command returns a new biologics handle or reference.

biologics exists

biologics exists bhandle ?filterlist?
b.exists(?filters=?)
Biologics.Exists(bref,?filters=?)

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

Example:

biologics exists $bhandle

biologics expr

biologics expr bhandle expression
b.expr(expression)

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

biologics fill

biologics fill bhandle ?property value?...
b.fill({?property:value,...})
b.fill(?property,value?,...)

Standard data manipulation command for setting data, ignoring possible mismatches between the lengths of the lists of objects associated with the property and the value list. It is explained in more detail in the section about setting property data.

biologics filter

biologics filter bhandle filterlist
n.filter(filters=)

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

biologics get

biologics get bhandle propertylist ?filterset? ?parameterdict?
biologics get bhandle attribute
b.get(property=,?filters=?,?parameters=?)
b.get(attribute)
b[property/attribute]
b.property/attribute

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

Examples:

biologics get $hhandle {B_IDENT B_NAME}

yields the ID and name of the biologics object 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 biologics get command are biologics new, biologics dget, biologics jget, biologics jnew, biologics jshow, biologics nget, biologics show, biologics sqldget, biolgics sqlget, biologics sqlnew, and biologics sqlshow .

In addition to property data, a biologics 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 biologics set. These attributes are:

biologics getparam

biologics getparam hhandle property ?key? ?default?
b.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.

biologics hierarchy

biologics hierarchy bhandle ?filterlist? ?root?
b.hierarchy(?filters=?,?root=?)

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

biologics hierarchy $ehandle

biologics index

biologics index bhandle
b.index()

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

biologics items

biologics items bhandle ?filterset? ?filtermode?
b.items(?filters=?,?mode=?)

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

biologics bioitems is an alias for this command.

Example:

biologics items $bhandle

biologics jget

biologics jget bhandle propertylist ?filterset? ?parameterdict?
b.jget(property=,?filters=?,?parameters=?)

This is a variant of biologics get which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects. The command is usable only for property data, not attribute retrieval.

biologics jnew

biologics jnew bhandle propertylist ?filterset? ?parameterdict?
b.jnew(property=,?filters=?,?parameters=?)

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

biologics jshow

biologics jshow bhandle propertylist ?filterset? ?parameterdict?
b.jshow(property=,?filters=?,?parameters=?)

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

biologics links

biologics links bhandle ?filterset? ?filtermode?
b.links(?filters=?,?mode=?)

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

biologics biolinks is an alias for this command.

Example:

biologics links $bhandle

biologics list

biologics list ?filterlist?
Biologics.List(?filters=?)

This command returns a list of the biologics object handles currently registered in the application. This list may optionally be filtered by a standard filter list.

biologics lock

biologics lock bhandle propertylist/biologics/bioitem/biolink/all ?compute?
b.lock(property=,?compute=?)

Lock property data of the biologics object, meaning that it is no longer subject to the standard data consistency manager control. The data consistency manager deletes specific property data if anything is done to the biologics object or its minor object components which would invalidate the information. 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:

The lock can be released by a biologics unlock command.

The return value is the original biologics handle or reference.

biologics max

biologics max bhandle propertylist ?filterset?
b.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 biologics object properties, this is pointless since there is only a single instance of a biologics property per biologics object. Usually, bioitem or biolink 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.

biologics metadata

biologics metadata bhandle property ?field ?value??
b.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 biologics setparam and biologics 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.

biologics min

biologics min bhandle propertylist ?filterset?
b.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 maximum property values.

While it is possible to work with biologics object properties, this is pointless since there is only a single instance of a biologics property per biologics object. Usually, bioitem or biolink minor object properties are tested. 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.

biologics move

biologics move bhandle ?datasethandle|remotehandle? ?position?
b.move(?target=?,?position=?)

Make the biologics object a member of a dataset, or remove it from a dataset. If the dataset handle or reference parameter is omitted, or is an empty string, or None for Python , the object is removed from its current dataset. The dataset handle or reference 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 or rnd . This value moves to the object to a random position in the dataset. Using this mode with remote datasets is currently not supported.

The dataset handle cannot be a transient dataset.

The return value of the command is the dataset of the object prior to the move operation. It is either a dataset handle/reference, or an empty string ( Tcl ) or None ( Python ) if it was not member of a dataset.

biologics mutex

biologics mutex bhandle mode
b.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:

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.

biologics need

biologics need bhandle propertylist ?mode? ?parameterdict?
b.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 biologics object handle or reference.

biologics new

biologics new bhandle propertylist ?filterset? ?parameterdict?
b.new(property=,?mode=?,?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 biologics get command. The difference between biologics get and biologics new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

biologics nget

biologics nget bhandle propertylist ?filterset? ?parameterdict?
b.nget(property=,?mode=?,?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 biologics get command. The difference between biologics get and biologics nget is that the latter always returns numeric data, even if symbolic names for the values are available.

biologics nnew

biologics nnew bhandle propertylist ?filterset? ?parameterdict?
b.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 biologics get command. The difference between biologics get and biologics 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.

biologics pack

biologics pack bhandle ?maxsize? ?requestprops? ?suppressedprops? ?compressionlib?
b.pack(?maxsize=?,?requestprops=?,?suppressedprops=?,?compressionlib=?)

Pack the biologics object and all its bioitem and biolink components 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. Further object relationships, such as datasets the object might be a member in are not saved.

The maximum size of the object string (default -1, meaning unlimited size) can be configured by the optional maxsize parameter. The size is specified in bytes. If the pack string would be longer than the maximum size, an error results.

The other optional property 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 biologics object.

Hierarchies can be restored from a packed object string by the biologics unpack or biologics create commands.

The biologics object and its minor objects remain in existence after using this command.

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 return value of this command is the packed string.

In Python , biologics objects support the standard pickle / unpickle protocol.

Example:

set dbstring [biologics pack $hhandle]

biologics properties

biologics properties filehandle ?pattern? ?noempty?
b.properties(?pattern=?,?noempty=?)

Generate a list of the names of all properties attached to the biologics object. This includes properties of bioitem and biolink minor objects which are part of the biologics object. Optionally, the list may be filtered by a string match pattern.

If the noempty flag is set, only properties where at least one data element is not the property default value are output. By default, the filter pattern is an empty string, and the noempty flag is not set.

The command may be abbreviated to props instead of the full name properties .

biologics purge

biologics purge bhandle propertylist/biologics/bioitem/biolink ?emptyonly?
b.purge(?properties=?,?emptyonly=?)

Delete property data from the biologics object. The properties may be biologics properties (prefix Q_ ), or properties of the biologics minor objects, i.e. bioitems (prefix I_ ) and biolinks (prefix J_ ). 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 biologics object (such as on all bioitems in a network for bioitem properties, or just the single biologics property value for biologics properties) are set to the default property value.

In addition to property names, the object class names biologics, bioitem or biolink may be used. These delete all property data of that class from the biologics item. They do not delete the objects proper, e.g. all bioitems are still present after a biologics purge $bh bioitem , though without any data that was not locked.

The return value is the original object handle or reference.

biologics ref

Biologics.Ref(identifier)

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

biologics rename

biologics rename bhandle srcproperty dstproperty
b.rename(srcproperty=,dstproperty=)

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

biologics set

biologics set bhandle ?property value?...
b.set(property,value,...)
b.set({property:value,...})
b.property = value
b[property] = value

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

biologics setparam

biologics setparam bhandle property ?key value?...
biologics setparam bhandle property dictionary
b.setparam(property,?key,value?...)
b.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.

 

biologics show

biologics show bhandle propertylist ?filterset? ?parameterdict?
b.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 biologics get command. The difference between biologics get and biologics 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, biologics get and biologics show are equivalent.

biologics sqldget

biologics sqldget bhandle propertylist ?filterset? ?parameterdict?
b.sqldget(property=,?mode=?,?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 biologics get command. The differences between biologics get and biologics 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.

biologics sqlget

biologics sqlget bhandle propertylist ?filterset? ?parameterdict?
b.sqldget(property=,?mode=?,?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 biologics get command. The difference between biologics get and biologics sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

biologics sqlnew

biologics sqlnew bhandle propertylist ?filterset? ?parameterdict?
b.sqlnew(property=,?mode=?,?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 biologics get command. The differences between biologics get and biologics 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.

biologics sqlshow

biologics sqlshow bhandle propertylist ?filterset? ?parameterdict?
b.sqlshow(property=,?mode=?,?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 biologics get command. The differences between biologics get and biologics 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.

biologics subcommands

biologics subcommands
dir(Biologics)

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

biologics transfer

biologics transfer bhandle propertylist ?targethandle? ?targetpropertylist?
b.transfer(properties=,?target=?,?targetproperties=?)

Copy property data from one biologics object to another biologics object 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 biologics minor objects (bioitems and biolinks), 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 biologics 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.

biologics unlock

biologics unlock bhandle propertylist/biologics/bioitem/biolink/all
b.unlock(property=)

Unlock property data for the biologics item, 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 biologics lock command.

The return value is the original biologics object handle or reference.

biologics unpack

biologics unpack packstring ?compressionlib?
Biologics.Unpack(data=,?compressionlib=?)

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

Biologics objects may also be unpacked by a biologics create command.

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

Example:

set packdata [biologics pack $bhandle]

set bhandle [biologics unpack $packdata]

biologics valid

biologics valid bhandle propertylist
b.valid(property/propertysequence)

Returns a list of boolean values indicating whether values for the named properties are currently set for the biologics object or its minor objects. No attempt at computation is made. For Python , where single-item lists are syntactically not the same as a single value, the return value is a single boolean if the argument was a string or a property reference, and only a single property was decoded.

biologics verify

biologics verify bhandle property
b.verify(property)

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