atomselect

Atom selection is the primary method to access information about the atoms in a molecule. It works in two steps. The first step is to create a selection given the selection text, molecule id, and optional frame number. This is done by a function called atomselect, which returns the name of the new atom selection. the second step is to use the created selection to access the information about the atoms in the selections.

• list: Return a list of all undeleted atom selections.

• keywords: Return a list of all recognized keywords in an atom selection text.

• macro name selection: Create a new singleword atom selection out of existing atom selections. name must be a single word starting with a non-numeric character and contain no spaces or special characters. selection can be any valid atom selection, and can even contain other macros. You should ensure that your macros do not contain themselves, either directly or through a chain of other macros. If VMD detects this situation, it will abort the evaluation of the atom selection.

  If no selection is given, the macro for the given name is returned.

  If no name is given, a list of all macro names is returned.

  If a macro already exists for the given name, the old selection will be replaced with the new selection. Singlewords that are not defined as macros, like protein and water, cannot be redefined with the macro command.

• delmacro name: Delete the macro corresponding to name. Singlewords that are not defined as macros cannot be deleted.

• molecule_id selection_text [frame frame_number] Creates a new atom selection and returns its name. The returned name can be used as a Tcl proc in order to access the atom selection. The selection text is the same language used in the Graphics form and described in Chapter 6.3. It is used to pick a given subset of the atom. The text cannot be changed once a selection is made. Some of the terms in the selection depend on data that change during a trajectory (so far only the keywords 'x', 'y', and 'z' can change over time). For these, the optional 'frame value' is used to determine which specific frame to use. The frame number can be a non-negative integer, the word now (the current frame), the word first (for frame 0) and last (for the last frame).

  Some examples are:

  vmd> atomselect top "name CA"
  atomselect0
  vmd> atomselect 3 "resid 25" frame last
  atomselect1
  vmd> atomselect top "within 5 of resname LYR" frame 23
  atomselect2
  

  The newly created atom selection is a Tcl proc, which takes the following options:

  • num: Return the number of atoms in the selection.
  • list: Return a list of the atom indices in the selection (BTW, this is the same as get index).
  • text: Return the text used to create this selection.
  • molid: Returns the molecule id used to create this selection.
  • frame: Returns the animation frame associated with this selection. The result will be either now, last, or an integer corresponding to the frame. When the frame is now, the atom selection will use atomic coordinates from the current frame for its associated molecule. If the frame is last, the atom selection will always use coordinates from the last frame. If the frame is a specific integer, the selection will always use coordinates from that frame, even if the current animation frame changes. Note that if a nonexistent frame is specified, the atomic coordinates will reference the last frame.
  • frame frame: Set the frame for the selection. frame should be either now, last, or an integer.
  • delete: Delete this object (removes the function).
  • global: Moves the object into the global namespace. Atom selections created within a Tcl proc that are not made global are deleted when the proc exits.
  • uplevel level: Moves the object to a new level in the namespace stack. Works the same as the Tcl function uplevel.
  • get attribute_list: Given an attribute or a list of attributes, returns the attribute values. If only a single attribute is given, a list of corresponding attributes values will be returned. If a list of attributes is given, then a list of sublists will be returned; each sublist will contain the values for the corresponding attributes. See Tables 6.5, 6.6, and 6.8 for the recognized attribute keywords.

  • set attribute_list values_lists: Set the attributes in the attribute list with the values gven in the values lists. If there is only one attribute, then values_lists can be either a single value or a list of values, one for each selected atom. If there is more than one attribute, then values_lists must be a list of sublists; the number of sublists must equal the number of selected atoms, and the number of items in each sublist must equal the number of attributes.

    Example:

      set sel [atomselect top all]
      set mass [$sel get mass]
      set xyz [$sel get {x y z}]
      $sel set beta 0      # all values are set to zero
      $sel set beta $mass  # copy mass to beta
      # set occupancy to x, mass to y, beta to z
      $sel set {occupancy mass beta} $xyz
    

    It is an error to set integer or floating point keywords using non-numeric values. If floating point values are passed to integer keywords, they will be converted to integers, and vice versa.

    The set command immediately updates all representations of the selected molecule. If speed is an issue, delete all representations of the molecule before setting the values.

  • getbonds: returns a list of bondlists; each bondlist contains the id's of the atoms bonded to the corresponding atom in the selection.
  • setbonds: Set the bonds for the atoms in the selection; the second argument should be a list of bondlists, one bondlist for each selected atom.
  • move 4x4 matrix: Applies the given transformation matrix to the coordinates of each atom in the selection.
  • moveby offset: move all the atoms by a given offset.
  • lmoveby offset_list: move each atom by an offset given in the list.
  • moveto position: move all the atoms to a given location.
  • lmoveto position_list: move each atom to a point given by the appropriate list element.
  • writeXXX filename: write the selected atoms to a file of type XXX; e.g., pdb, dcd. New in VMD 1.8: writepdb requires a filename; omitting the filename no longer returns the PDB data as a string. To get the PDB data as a string, first write to a file, then enter the following commands: set fd [open filename r]; set s [read $fd]; close $fd. The text will be contained in the variable s.
  • update: Update the atom selection based on the frame for the selection (the frame can be specified using the frame option as described above).

  See section 12.2 for more on using atom selections for fun and profit, as well as issues relating to speed of analysis scripts.