select

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

Purpose

The select command is used to create a list of relation numbers from a hierarchial database according to a string syntax. Currently, only the molecular system database type is set up with an inherent hierarchy, which is:

system::molecule:monomer:atom

Syntax

select varName spec

Atom Specifications

Simple atom specifications, more complicated atom specifications, and specification operator precedences are tabulated separately in this section.

An ``atom specification'' (spec in the command syntax above) is a general term for a string that specifies a target or list of targets in a hierarchial system database. For the system database the general hierarchy is:

system::molecule:monomer:atom

The syntax of the specification is made up of strings specifying the target at each level. A specification may contain special characters, such as wildcard characters.

A specification may also be a BTCL object handle, e.g.:

    select AL2 $AL1

in which case, all the select command does is to make a copy of an object that was previously defined (AL1) and to assign it to a new object AL2.

Simple Atom Specification Syntax:

Character Description/examples sequence

target Specify a string of characters and wildcards for name matching at the current level. The * wildcard matches any number of characters (including none). The ? wildcard matches any single character. The case-insensitive keywords first and last specify the first and last items in the list of items at the current level. target:: Specify the system database target. This sequence may occur only once in a specification and must be at the start, e.g., rnd::*:*:C. : Move one level down the system hierarchy. For example, *:1 causes a list of molecules (rows) to be generated whose names match the string * (i.e., all of them); the : then changes the level to the monomer level for those monomers that are in the specified molecules; the target 1 is then used to match the items at the new level (monomers). , Concatenate specifications, for example, *:1,*:3 produces a list from all the monomers of names 1 and 3 from all the molecules in the current system. Concatenated lists do not have to be in the same level. ( ) Group lists at a particular level. Usually used in conjunction with the ``,'' character, for example, *:(1,3) produces exactly the same list as *:1,*:3, but the path *: is not re-specified. Note that white space in the specification is ignored. table; The semicolon is used to specify a table name to be considered at the current level rather than the default table at this level in the hierarchy. Currently only Molecule, Monomer, and Atom tables are connected by the system database hierarchy, but at each level it is possible to define a subset. For example, *:Monomer;* specifies all monomers only, and *:* specifies all monomers, subsets, and pseudoatoms defined at the monomer level. type_target Used at the monomer level to specify the monomer type. The monomer names usually have the form type_number, e.g., GLY_3. Thus *:ALA_* might be used to specify all the ALA type monomers in the system. target.. The range operator .. produces a list of rows at the current target level from the first to second targets, for example, *:2..5 specifies a list of monomers in order from 2 to 5, and *:5..2 specifies the same list in reverse order. When the range operator is specified on two lists, e.g., *:(1,3)..(5,4), then the lists are matched from paired elements in each list, i.e., the result here would be the same as for *:(1..5, 3..4). The matching of elements from two lists may be complicated by the lists containing different numbers of items, originating from different tables (levels) or columns, or having different groupings. The parser tries to make the most sensible match it can or it returns an error. !target The complement operator ! is used to generate a list by excluding all items in the following specification. For example, mol:1:!H* specifies all the heavy atoms (non- hydrogens) in monomer 1 of molecule mol. The complement operator is restricted to the table (level) and column (attribute) specified, for example, *:*:!(Subset;p*) specifies all subsets at the atom level whose names do not start with a p and does not refer to any atoms or pseudoatoms defined at this level. \char The backslash is used to quote operators and other special characters. \\ is used to quote a single \ character.

Jump to Background or Examples

More Atom Specification Syntax:


Character       Description/examples
sequence

< column >      Specify a column (attribute) that is used to match target in 
  target        the hierarchy level at which the last list was specified, 
                for example, *:*<Type>GLY and *:*:<Type>GLY both specify all 
                the monomers in the system of type GLY, i.e., all rows in 
                the Monomer table for which the Type column value matches 
                the string GLY. The latter of these examples does not work 
                at the atom level, despite the extra `:', since no atom 
                target is specified, and this operation is performed as a 
                filter on the last list specified. This feature is useful 
                only when the path to this level is independently specified, 
                as with the subset command.

@ step          Used after a range operator to specify a step, for example,
                mol:3..LAST@2 specifies every other monomer in molecule mol 
                between 3 and the last one listed. The step value step is 
                always positive, even for ranges that run in reverse order.

+shift          Specify objects that are shift rows along in the same table 
                from those in last list specified, for example, *:*:C+2 
                specifies all the atoms in the current system that occur 2 
                after each C atom in the Atom table. The shift is always 
                made in the context of the individual items in the specified 
                list, for example, (mol:1,mol:*:C)+1 specifies a list 
                containing the monomer listed after 1 and all atoms 
                listed after C atoms in the database for molecule mol. If a 
                shift causes the object specification to go out of range, 
                then that specification is ignored, e.g., mol:(1,last)+1 is 
                an equivalent specification to mol:2, since mol:last+1 
                produces an empty list. The + operator is similar to the < > 
                operator in that it is performed on the last list specified, 
                for example, both mol:LAST+-1 and mol:LAST:+-1 specify the 
                last-but-one monomer defined in molecule mol. Note the use 
                of +-1. There is no complementary ``-'' operator, since 
                this character is often used in monomer types, etc.

#symmetry       Used to find the symmetry image of an atom for a system
                containing symmetry atoms. For example, *:*:Si*#2 specifies
                the set of atoms generated by applying the second symmetry
                operator (#2) to all matches to Si* (silicon) atoms.
                Currently, the symmetry operator may not be applied to
                pseudoatoms, ghost (offset) atoms, e.g., *:*:Si*%111#2, or
                other symmetry atoms, e.g., *:*:Si*#2#3.

%offset         Used to find the cell offset of an atom for a system
                containing periodic atoms, such as a crystal structure. 
                The offset may be specified in one of two ways:
                by %(x,y,z), where x,y,z are integer unit cell offsets
                along the unit cell vectors a,b,c, e.g., *:*:Si*%(1,-5,13);
                or by %xyz, where the unit cell offsets xyz are in the
                range -9 to 9, e.g., *:*:Si1%100, *:*:Si1%1-10.
                With the offset operator, a new ghost (offset) atom is
                created if the specified image atom does not already exist,
                e.g., *:*:Si*%120 would create the (1,2,0) unit cell image
                atoms for those atoms matching *:*:Si* the first time these
                atoms are specified. Unlike the symmetry operator, the
                offset operator may be applied to pseudoatoms, ghost
                (offset) atoms, e.g., *:*:Si*%111%202, or symmetry atoms,
                e.g.. *:*:Si*#2%202.

"" ''           Used (in matching pairs) to quote literal strings inside 
                specifications, for example, 'molecule 3:2':*:* specifies
                all the atoms in molecule molecule 3:2. Since strings pass 
                through the TCL interpretor, it may be necessary to quote 
                the " characters, e.g., *:*:\"Cu_2+\".

{ }             Used for multiple specifications, for example, {*}{*:2:H}
                specifies two separate lists, * and *:2:H; and (*),(*:2:H) 
                specifies only a single list. Multiple specifications are 
                allowed only for certain commands, e.g., subset, and are 
                not allowed to span systems, as would occur for 
                {sys1::*} {sys2::*:2:H}. The select command does not allow 
                multiple specifications.

Specification Operator Precedence:


Precedence   Operators

    |           {  }
    |           ::
    |           ,
    |           :
    |           ;
    |           _
    |           <  > #  %
    |           !
    |           ..
    |           @
    |           +
    V           (  )

Background

Jump to Syntax or Examples

The select command and object specification syntax are used to quickly access a molecular system database to select lists of molecules, monomers (residues or sidechains), and atoms. These lists are very useful in the Discover program for defining geometric properties of molecules and residues, like distances and angles, so that they may be monitored, analyzed, or altered. They are also very useful for defining constraints or restraints on parts of molecules, etc., to reduce the amount of work in, for example, a minimization or dynamics simulation.

Example 1

Jump to Syntax or Background

BTCL > select ats (CRN:2,PRI:3):CA

In this example, a BTCL object variable called ats is created, which is the list of alpha-carbon atoms (CA) in the ``2'' monomer of the CRN molecule and in the ``3'' monomer of the PRI molecule.

Example 2

BTCL > select ats MYSYS::CRN:!(GLY_*)

In this example, a list of all the monomers in the molecule CRN in system MYSYS that are not of type GLY is returned in the object variable ats.

Example 3

BTCL > select ats CRN:(1..4,6,8..11)

In this example, the specification generates all the monomers of the CRN molecule with names 1, 2, 3, 4, 6, 8, 9, 10, and 11. This gives the desired list because of the operator precedence rules shown above.

Example 4

BTCL > select ats crn:!3..15@3:CA..(CA+5)

This last example again relies on the precedence rules to generate a specific list. Since ``..'' has higher precedence than ``!'' and ``+'', the specification string is the simplest form of (crn):(!(3..15@3)):(CA..(CA+5)). The example produces a list of all the atoms from CA to CA+5, i.e., six in all, for all monomers in molecule crn except 3, 6, 9, 12, and 15.

Example 5

BTCL > select ats "mysys::*:*:nonbond_group;c3"

In this example, a list is made of all the c3 nonbond groups in system database mysys. Every character in the specification is lower-case, since table names, column names, and target strings are case-insensitive. However, system, table, and column names are not allowed to contain wildcards, since it is not possible to create objects that span databases; and table columns may only be accessed individually. In this example, the resulting object ats is empty, since the table nonbond_group is not accessible through the system database hierarchy, even though it is part of the system database. Note that the spec argument is quoted in this example because of the ``;'' character.

Example 6

BTCL > select ats1 "Xtal::*:*:Si1#(1,2)"
BTCL > select ats2 "Xtal::*:*:Si1#2..LAST"

In this example two atom lists, ats1 and ats2, are defined from a system called Xtal, which contains symmetry atoms.

Assuming that this system contains one molecule and one monomer, then ats1 contains 2 atoms which are the images of the Si1 atom when operated on by symmetry operators 1 (the identity) and 2.

Atom list ats2 specifies all symmetry images of the atom named Si1 other than the identity.

Note: the specification Si1#1 is equivalent to Si1.

Example 7

BTCL > select ats1 "Xtal::*:*:Si1#2%101"
BTCL > select ats2 "Xtal::*:*:Si1%(1..3,0,(1,3))"

In this example, two atom lists, ats1 and ats2, are defined from a periodic (infinite) system called Xtal, which also contains symmetry atoms.

Assuming that this system contains one molecule and one monomer, then ats1 contains one atom, which is the 101 unit cell offset image (ghost atom) of the second symmetry image of atom Si1.

Atom list ats2 specifies a number of periodic images of the atom Si1 using the range, grouping ((...)) and concatenation (,) operators. In fact, the expanded list is equivalent to the following specification: Xtal::*:*:Si1(#101,#201,#301,#103,#203,#303).

Note: the specification Si1%000, or Si1%(0,0,0), is equivalent to Si1.

Main access page

Advanced-Use access.

List of BTCL commands restraint command subset command