A number of methods are defined for AtomGroup objects. These methods are applied to an AtomGroup object using the dot operator. Some methods can only be applied to Atom nodes, other methods can be applied only to Group nodes and a few methods can be applied to any kind of node. The methods are listed in this table with the target object names A, G or AG. A stands for an Atom object, G for a Group object and AG for an object that can be either an Atom or a Group. The atom() and group() methods are documented in their own pages; the links below will take you to these pages. G.atom() Add an atom to the Group G G.clear() Remove the contents of G AG.contents() List the contents of AG AG.delete() Remove the contents of G, then remove G AG.findnode() Find the atom with the given label (name), index or reference number G.group() Add a group to G AG.index() Renumber the atoms in the entire hierarchy A.modify() Modify the properties of the atom A AG.setmask() Set the selection mask of all the atoms in AG to the given value G.transfer() Transfer the contents of G to the empty destination Group specified in the argument. G.unpack() Decode the string representation of a hierarchy specified in the argument into the empty target Group G. The clear() method clears out the content of a Group node. If the contents include Group nodes, the contents of these nodes are first cleared. This method cannot be applied to an Atom node. Method Name Applicable Number of Arguments Return Value clear Group 0 - Return to Index The contents() method lists the contents of an Atom or Group node. If an Atom node, the return value is None. If a Group node, the return value is a tuple of AtomMaps. This tuple is empty if the group is empty. Method Name Applicable Number of Arguments Return Value contents Atom and Group 0 None or tuple of AtomMaps The returned tuple contains AtomMaps in the same order in which they had been inserted. Return to Index The delete() method operates like the clear() method, then the target node is also removed. This method can be applied to any type of node. Method Name Applicable Number of Arguments Return Value delete Atom and Group 0 - From the concrete example, note that the Group node named "f2" is contained in the Group node named "e1" as shown when we first print out the latter node. After the delete method is applied to the "f2" node a listing of the parent node shows no sign of this node. Note also the renumbering of atoms: >>> Ge1 +e1: /14:16\ -+f2: /14:16\ --+e3 14:14 1:0 -1:-1 0 --+f3 15:15 1:0 -1:-1 0 -+g2: /16:16\ >>> Gf2.delete() >>> Ge1 +e1: /14:14\ -+g2: /14:14\ >>> Return to Index The findnode() method locates a node in one of three ways: by a label (name), the index (atom) number or by the reference number. The search for the label will be confined to the target node. For the other two searches, the entire hierarchy is searched. Only one of the keywords can be specified in one search. When a node is found, the pointer to that node is returned. Method Name Applicable Argument Keywords Return Value findnode Atom and Group "label", "index", "reference" The found node Keyword Argument Purpose Preset Value label one and only one argument can be specified find the node with this label or name - index find the atom with this atom or index number - reference find the atom with this reference number - A label search includes the target node; but an expression like R.findnode( label = "" ) where R is the root node will cause an exception although strictly speaking it should return R. The label search will return the first node found in a depth first search that matches the given label, starting from the target. Note that both the index and the reference numbers start from 0. Thus, the specified index or reference number must be positive or zero. They must also be within range. A reference number may be within permissible range but may be that of a deleted atom. The search will fail in this case and an error message is printed. Since label is the first keyword an expression like G.findnode( "xyz" ) means to find a node labeled "xyz". Return to Index The index() method is used to force all the atoms to be renumbered or reindexed. The renumbering starts from the top of the hierarchy regardless of the level of the target. Hence the target node can be an Atom or a Group node and it can be a node at any level of the hierarchy. Method Name Applicable Number of Arguments Return Value index Atom and Group 0 - Most methods that affect atom numbering such as atom(), clear() and delete() automatically renumber the atoms. Atoms are numbered depth-first, and within each Group from the oldest to the newest Atoms. This has the property that any sub-hierarchy will have a contiguous range of atom numbers. Return to Index The modify() method is used to modify the properties of an atom. Method Name Applicable Argument Keywords Return Value modify Atom "name", "mass", "charge", "atomitype", "atomxtype", "mask" - Keyword Argument Purpose Preset Value name optional atom name - mass optional atomic mass - charge optional atomic charge - atomitype optional inclusion atom type - atomxtype optional exclusion atom type - mask optional selection mask - All arguments are optional and there are no preset values. There is no return value. Return to Index The setmask() method is applicable to any AtomGroup object and it requires one argument: the value of the selection mask. If the target is an Atom node, that mask value is set for that atom. If the target is a Group node, the mask value is set for all the atoms in that Group and in its descendant Groups. The mask value is a small integer value that is positive or zero. Method Name Applicable Number of Arguments Return Value setmask Atom and Group 1 - Keyword Argument Purpose Preset Value - required value of the selection mask - From the concrete example, set the mask for three pairs of atoms to 123, in the Groups "d1", "f2" and "a3". Then print the top of the hierarchy to confirm: >>> Gd1.setmask( 123 ) >>> Gf2.setmask( 123 ) >>> Ga3.setmask( 123 ) >>> Top : /0:16\ +a1 0:0 1:0 -1:-1 0 +b1: /1:11\ -+a2 1:2 1:0 -1:-1 0 -+b2: /2:10\ --+a3: /2:4\ ---+a4 2:10 1:0 -1:-1 123 ---+b4 3:11 1:0 -1:-1 123 --+b3 4:6 1:0 -1:-1 0 --+c3 5:7 1:0 -1:-1 0 --+d3: /6:10\ ---+c4 6:12 1:0 -1:-1 0 ---+d4: /7:7\ ---+e4 7:13 1:0 -1:-1 0 ---+f4 8:14 1:0 -1:-1 0 ---+g4 9:15 1:0 -1:-1 0 -+c2 10:3 1:0 -1:-1 0 +c1 11:1 1:0 -1:-1 0 +d1: /12:14\ -+d2 12:4 1:0 -1:-1 123 -+e2 13:5 1:0 -1:-1 123 +e1: /14:16\ -+f2: /14:16\ --+e3 14:8 1:0 -1:-1 123 --+f3 15:9 1:0 -1:-1 123 -+g2: /16:16\ >>> Return to Index The transfer() method is used to transfer the contents of the target Group to the destination Group specified in the argument. The destination Group must be empty (use clear() to empty a Group). The target Group and the destination Group must be in the same hierarchy and a Group cannot be transferred to a descendent Group. Method Name Applicable Number of Arguments Return Value transfer Group 1 - Keyword Argument Purpose Preset Value - required the destination Group node - From the concrete example, we first print the contents of the Groups ":e1:g2" (held in the variable Gg2) and ":b1:b2:a3" (in the variable Ga3). Then we apply the transfer() method to move the contents of Ga3 to Gg2. We then print these Groups again to see the result of the transfer: >>> print Gg2, Ga3 -+g2: /16:16\ --+a3: /2:4\ ---+a4 2:10 1:0 -1:-1 0 ---+b4 3:11 1:0 -1:-1 0 >>> Ga3.transfer( Gg2 ) >>> print Gg2, Ga3 -+g2: /14:16\ --+a4 14:10 1:0 -1:-1 0 --+b4 15:11 1:0 -1:-1 0 --+a3: /2:2\ >>> Notice that the transferred atoms get new atom numbers (2 and 3 become 14 and 15 respectively) but retain their reference numbers (10 and 11). Although this is not clear from the example, atom properties are also preserved. Return to Index The unpack() method decodes the string representation of a hierarchy specified in the argument and recreates the hierarchy under the target Group, which must be empty. The unpacking may create new Atoms but no properties will be defined for them. The new Atoms must be provided with properties separately. The string representation may be crafted by hand but it is more usual and less error-prone, to use a string generated by the repr() function or from a file. Method Name Applicable Number of Arguments Return Value unpack Group 1 - Keyword Argument Purpose Preset Value - required the string representation of a hierarchy - See the String page for the format of the string representation of a hierarchy. From the concrete example, we encode the hierarchy at the Group ":b1:b2:a3" and save the string into a variable Sa3. Next, we print the two object variables Gg2 and Ga3. We then unpack the string variable Sa3 into the empty Group Gg2. Finally, we print the two Groups again to see the effect of the unpacking. The encoded string is also printed: >>> Sa3 = `Ga3` >>> print Gg2, Ga3 -+g2: /16:16\ --+a3: /2:4\ ---+a4 2:10 1:0 -1:-1 0 ---+b4 3:11 1:0 -1:-1 0 >>> Gg2.unpack( Sa3 ) >>> print Gg2, Ga3 -+g2: /16:18\ --+a4 16:16 1:0 -1:-1 0 --+b4 17:17 1:0 -1:-1 0 --+a3: /2:4\ ---+a4 2:10 1:0 -1:-1 0 ---+b4 3:11 1:0 -1:-1 0 >>> print Sa3 /2:a4:b4\ >>> Notice that the Group that we encoded retained its atoms. The target Group was empty at the start and after the encoded string was unpacked into it, it has two new atoms. The new atoms have the same names as the original atoms (but properties are not copied). The new atoms are assigned new index and reference numbers. Return to Index Intro Top Group Atom Data Print String Compare Methods Mapping Example