subset

Jump to Description or Examples; explanation of how commands are documented.

Purpose

The subset command is used to create or access subsets of objects in a database in the Discover environment.

Syntax

subset operation arg1 ?arg2 ...?

The subset Command Operations:


Operation                 Description
   Arguments

get                       Get the list of items that the subsets contain,
   varName                which are specified by spec, into an object handle 
   spec                   varName. If a subset contains subsets, then these 
                          sub-subsets are also expanded into their component 
                          lists and so on. The command returns a string list 
                          of data types (table names) that spec expands into.

define                    Define a new subset and add it to the specified
   ?allow_empty Bool?     database. path is a string atom specification that 
   Table                  defines the context (level) at which new subsets 
   path:name              with the name name are to be created. If only one 
  (spec |                 argument follows path:name, spec, then this may be 
   objHandle1             a multiple atom specification string, e.g., for an 
   ?objHandle2 ...?)      angle definition spec would be "{spec1} {spec2} 
                          {spec3}". If more than one argument follows 
                          path:name, then these must be object handles to 
                          existing database items. In either case, the 
                          number of objects given to define the subset must 
                          match the number expected for the value of Table, 
                          e.g., for Distance two sets of object items are 
                          expected. A subset is created with the name name 
                          for each valid path in path. When a string spec is 
                          given, the objects are specified by path:spec. 
                          Usually if any empty lists are produced for spec 
                          for particular paths of path, these subsets are not 
                          created. However, if the allow_empty keyword is 
                          included, followed by the Boolean value false, 
                          failure to create any subset produces an error.

Description

Jump to Syntax or Examples

A database subset is a named list of items (row numbers) taken from a particular database in the Discover environment. Unlike BTCL objects, which may also specify a list of items in a database, subsets are actually created within a database and can be accessed through the usual database operations and atom specifications (refer to the select command). A subset may contain a list of any database items, including other subsets.

The subset get command is used to retrieve the contents of subsets that are specified by an atom specification or an object handle.

The subset define command is used to create subsets in a database, which can be accessed through atom specifications and subset get commands. Ordinary subsets are simply defined by a list of object items specified by an atom specification string or an object handle, e.g., $obj. Subsets may also be made up of subsets or objects that are made up of multiple items, such as distances and angles. When a subset of, for instance, distance objects is defined, the subset define command first creates these objects from the supplied arguments, which must be either a multiple atom specification string or a number of object handles, e.g., two for distances. The Table argument is used to specify how many definition objects are required (see the table below).

Further explanations of the subset define and subset get commands are provided in the form of examples.

Tables Available for Subset Definitions:


Table    Number of points

Subset          1
Distance        2
Angle           3
Torsion         4
OutOfPlane      4

Example 1

Jump to Syntax or Description

BTCL > subset define Subset "rna::*:mons" "*"

This example uses the subset command to define subsets from the rna system database at the molecule level with the name mons. Each subset contains a list of all the monomer rows for that molecule. Note that the last two arguments are quoted only for emphasis in this example. Also note that the rna:: part of the path argument is required only if the rna system is not the default system database.

Example 2

BTCL > subset define Subset "rna::*:*:hydrogens" "H*"

This example defines subsets from the rna system database at the monomer level with the name hydrogens. Each subset contains a list of all hydrogen atoms contained in that monomer. There are as many subsets defined at this level as there are valid levels, i.e., if there is only one molecule in the rna system with 30 monomers (residues), then 30 subsets at the monomer level are defined with the name hydrogens.

Example 3

BTCL > subset define allow_empty false Subset "rna::*:(1..5):nitrogens" "N*"
 Error: subset cannot be created for all ATS path specs.
    while executing
 "subset define allow_empty false Subset "rna::*:(1..5):nitrogens" "N*""

This example is similar to the previous one except that the subset level spans only the first five monomers and we are considering nitrogen atoms. If, for example, the third monomer did not contain any nitrogen atoms, only four subsets named nitrogen could be defined at the monomer level. Usually this would be fine, but, since the allow_empty flag is set to false (the default being true), an error is reported.

Example 4

BTCL > subset define Subset "rna::mySet" "*:mons, *:*:hydrogens, *:*:N*"

In this example, a subset called mySet is defined at the system level. The subset contains all the mons subsets at the molecule level, all the subsets named hydrogens at the monomer level, and a list of all the nitrogen atoms in the rna system.

Example 5

BTCL > subset define Subset "rna::*:mySet" "mons, *:hydrogens, *:N*"

This example is almost the same as the previous example, but the mySet subsets are defined at the molecule level for all molecules in the rna system. Note that this new definition does not replace the previous one since it is defined for a different level. Also note that a mySet subset could not be defined for a lower level, e.g., at the monomer level, since the mons subsets would exist at a higher level and could not be specified in the spec argument.

Example 6

BTCL > subset define Angle "rna::*:GLY_*:myAng" "{CA} {N} {HN}"

This example of the subset define command shows the definition of subsets named myAng at the monomer level for all the GLY type monomers which refer to rows in the Angle table. These rows are created by this command where, effectively, a set of new ``angles'' is defined between the CA, N, and HN atoms in the specified monomers. Note that the last argument contains 3 separate atom specs, contained between braces. This is because the Angle table contains three point columns to fill in when a new row is added. If the Table argument were Distance, the number of specs would be 2 and for Torsion it would be 4, etc. (refer to table above).

Example 7

BTCL > subset define Angle  "rna::*:myAngAll" "{GLY_*:CA} {GLY_*:N} {GLY_*:HN}"
BTCL > subset define Subset "rna::*:myAngSub" "*:myAng"

These two examples of the subset define continue from the previous example to define new subsets called myAngAll and myAngSub. The definition of myAngAll differs from that of myAng in that, rather than having a subset for each matching monomer level, myAngAll defines one subset for each molecule that spans an identical set of angles. It would be specified by *:myAngAll rather than *:*:myAng and would be more efficient if you always wanted to consider all the specified angles at once.

The definition of myAngSub creates a subset that contains all the myAng subsets. Effectively, this subset would be equivalent to myAngAll in usage and would be specified by *:myAngSub.

An alternative to the subset define Subset command above would be the following:

BTCL > subset define Angle "rna::*:myAngSub" "*:myAng"

The only difference between these commands is that the specified subset "*:myAng" must be an Angle subset. For example, the following would produce an error:

BTCL > subset define Angle "rna::*:myAngSub" "*:myAng, *:*:H*"

whereas the following would not:

BTCL > subset define Subset "rna::*:myAngSub" "*:myAng, *:*:H*"

Example 8

BTCL > subset get dbSub "rna::*:(1..4):hydrogens"
 Object

This example shows the use of the subset get command. Here, the BTCL object dbSub contains a list of all the hydrogen atoms contained in the subsets called hydrogens at the monomer level for the first four monomers. The output from the command is Object, since these subsets refer only to items in the Atom table. (See Example 9.)

Example 9

BTCL > subset get dbSub "rna::(myset, *:*:myAng)"
 Object Angle

This example shows that the subset get command can get lists of row numbers from more than one subset specification at a time. Here, the BTCL object dbSub contains all the rows in the myset subset at the system level, which contains all the rows in the mons and hydrogens sub-subsets, and all the nitrogen row numbers (see Example 4), plus all the angle rows in the myAng subset at the monomer level. Note that the output is Object Angle, since the rows refer to either the Atom or Angle tables. In fact, any item that does not belong to the Distance, Angle, Torsion, or outOfPlane tables is referred to as an Object. The output from the subset get command is very useful for filtering the items in the resulting object and/or for error trapping.

Example 10

BTCL > select objList "*,*:*"
BTCL > subset define Subset mol:1:list $objList

This example shows the definition of a single subset, called list, at the atom level for monomer 1 of molecule mol, using an object handle $objList as the definition of its contents. Note that objList contains a list of all the molecules and all the monomers in the default system database, whereas usually the objects would have to be at the same hierarchy level as the subset being defined, i.e., at the atom level. This feature may be useful at times but should be used with care.

Main access page

Advanced-Use access.

List of BTCL commands select command subStructure command