model.pick_atoms() -- select atoms in MODEL

aln = <alignment>		Used for detecting loop regions
pick_atoms_set = <int:1>	1	index of the selected atoms set: 1 | 2 | 3
selection_search = <str:1>	'SEGMENT'	search method: 'SPHERE' | 'SEGMENT' | 'SPHERE_SEGMENT'
res_types = <str:1>	'ALL'	residue type selection: 'ALL' | 'HET' | 'BLK' | 'STD' | CHARMM 4-letter codes
atom_types = <str:1>	'ALL'	atom type selection: 'ALL' | 'SDCH' | 'MNCH' | IUPAC atom names
selection_from = <str:1>	'ALL'	selecting from: 'ALL' | 'SELECTED'
selection_mode = <str:1>	'ATOM'	selecting what: 'ATOM' | 'RESIDUE'
selection_status = <str:1>	'INITIALIZE'	what to do with selected atoms: 'ADD' | 'REMOVE' | 'INITIALIZE'
$\bullet$ For selection_search = 'SEGMENT':
selection_segment = <str:2>	'' ''	'RES:CHN' ids for the first and last residues in a chain/segment; or 'LOOPS'
gap_extension = <int:2>	2 1	extend insertions/deletions for that many residues, in PICK_ATOMS
minmax_loop_length = <int:2>	5 15	minimal/maximal length of a loop in PICK_ATOMS
$\bullet$ For selection_search = 'SPHERE':
sphere_center = <str:2>	'undefined' 'undefined'	'#RES1:C' 'ATOM_NAME'
sphere_radius = <float:1>	10.0	sphere radius for atoms selection
selection_slab = <float:5>	9999 9999 0 0 0	slab for atoms selection: 'dz1' 'dz2' 'xtrans' 'ytrans' 'ztrans'
$\bullet$ For selection_search = 'SPHERE_SEGMENT':
selection_segment = <str:2>	'' ''	'RES:CHN' ids for the first and last residues in a chain/segment; or 'LOOPS'
gap_extension = <int:2>	2 1	extend insertions/deletions for that many residues, in PICK_ATOMS
sphere_radius = <float:1>	10.0	sphere radius for atoms selection

Description:

This command adds atoms to, removes atoms from, or initializes any one of the three independent sets of selected atoms of MODEL. There are three selection sets because it is convenient to have different sets used by different MODELLER commands.

pick_atoms_set specifies the set of selected atoms. Set 1 is used in the model.restraints.pick(), model.rotate_dihedrals(), model.randomize_xyz() and model.mutate() commands. Sets 2 and 3 are used in the model.restraints.make() command.

selection_status determines whether the selected atoms are added ('ADD'), removed ('REMOVE'), or a set is initialized and then the selected atoms are added ('INITIALIZE').

The selection of atoms is a hierarchical two level process. The first level of selection consists of specifying how the atoms will be scanned. The second level consists of selecting by the specified atom and residue names.

How the atoms are scanned is specified by setting the selection_search variable to either 'SEGMENT', 'SPHERE', or 'SPHERE_SEGMENT':

1. 'SEGMENT' mode: Only a single stretch of residues specified by the beginning and ending residue identifiers in selection_segment (Section 3.9.1) is scanned. Alternatively, if selection_segment[1] has the special value 'LOOPS' only residues in loops are scanned. Loops are defined as those residues in the MODEL that are aligned with only gap positions in the templates (MODEL has to be the last sequence in the current alignment), are within gap_extension[1] of an insertion in MODEL, or are within gap_extension[2] positions of a deletion in MODEL, and are not in a loop segment shorter than minmax_loop_length[1] or longer than minmax_loop_length[2]. This selection mode is useful for automatic selection of loops to be refined by the loop modeling procedure.

2. 'SPHERE' mode: Only those atoms that are closer than sphere_radius angstroms to the sphere_center atom, after the center atom was translated by $(xtrans, ytrans, ztrans)$ angstroms specified in selection_slab[3:5], are scanned. If the first element of sphere_center is string 'INDEX', the second element is an integer atom index of the center atom; otherwise, the first and second element are the residue identifier (Section 3.9.1) and the IUPAC atom name, respectively. selection_slab[1:2] specifies the interval on the $Z$-axis relative to the $Z$ coordinate of the translated central atom that imposes another condition on the selected atoms: $Zcen+dz1 < Z+ztrans < Zcen+dz2$. Larger $Z$ values are in front, so $dz1$ specifies the plane that is further away than the $dz2$ plane. To pick any atoms, $dz1 < dz2$.

3. 'SPHERE_SEGMENT' mode: Only atoms within a sphere around the atoms in the specified segment of residues are scanned. This is useful, for example, when a neighborhood of a loop needs to be selected. As for the 'SEGMENT' mode, if selection_segment[1] has the special value 'LOOPS', only loop atoms are scanned for their neighbors.

If selection_from is 'SELECTED', scanning specified above is restricted only to the atoms that were already selected before calling model.pick_atoms().

Once the method for scanning the atoms is specified, each of the scanned atoms is checked against the specified atom name(s) (atom_types) and residue name(s) (res_types). If selection_mode is 'RESIDUE', all atoms in a residue with at least one atom that matches both the residue and atom name criteria are selected. Otherwise, only those atoms that have both the specified residue and atom names are selected. The res_types and atom_types keywords can contain several residue and atom names in one quoted string or in several quoted strings. For example, both 'CA' 'N' and 'CA N' are valid specifications selecting the CA and N atoms. The following groups of residues and atoms are defined:

• If res_types contains word 'ALL', all residues will be selected.

• If res_types contains word 'HET', all `HETATM' residues will be selected (e.g., all residue types with the MODELLER residue code larger than 27; see library $RESTYP_LIB).

• If res_types contains word 'BLK', all `BLK' residue types will be selected (Section 3.5.1).

• If res_types contains word 'STD', all standard residue types will be selected. Standard residue types are all residue types but `HETATM' and `BLK' types.

• If atom_types contains word 'ALL', all atoms will be selected.

• If atom_types contains word 'MNCH', all mainchain atoms will be selected. Mainchain atoms are N, C, CA, O, and OXT.

• If atom_types contains word 'SDCH', all sidechain atoms will be selected. Sidechain atoms are all non-mainchain atoms, including non-mainchain atoms in `HETATM' and `BLK' residues.

Example: examples/commands/pick_atoms.py

# Example for: model.pick_atoms()

# This will pick various subsets of atoms in the MODEL and compare them 
# with MODEL2.

env = environ()
log.level(1, 1, 1, 1, 0)

# Set some defaults (the same as in top.ini):
env.selection_mode = 'ATOM' # only the selected atoms, not whole residues
env.selection_from = 'ALL'  # scanning of all atoms, not selected atoms
env.selection_search = 'SEGMENT'  # scan over a segment
env.selection_segment = ('FIRST:', 'LAST:')   # the whole chain as a segment
env.res_types = 'ALL'               # all residue types
env.pick_atoms_set = 1              # put the selected atoms in set 1
env.selection_status = 'INITIALIZE' # select only the selected atoms

# Read the models and the alignment:
mdl  = model(env, file='1fas')
mdl2 = model(env, file='2ctx')
aln = alignment(env, file='toxin.ali', align_codes=('1fas', '2ctx'))
aln.write(file='toxin.pap', alignment_format='PAP')

# Pick and superpose mainchain atoms:
mdl.pick_atoms(aln, atom_types='MNCH')
mdl.superpose(mdl2, aln)

# Pick and superpose sidechain atoms:
mdl.pick_atoms(aln, atom_types='SDCH')
mdl.superpose(mdl2, aln)

# Pick and superpose CA and CB atoms:
mdl.pick_atoms(aln, atom_types='CA CB')
mdl.superpose(mdl2, aln)

# Pick and superpose all atoms:
mdl.pick_atoms(aln, atom_types='ALL')
mdl.superpose(mdl2, aln)

# Pick and superpose CA and CB atoms in one segment only:
mdl.pick_atoms(aln, atom_types='CA CB', selection_segment=('2:', '10:'))
mdl.superpose(mdl2, aln)

# Pick and superpose all atoms within 6 angstroms of the 'CA' atom in residue '10:':
mdl.pick_atoms(aln, atom_types='ALL', sphere_radius=6.0,
               selection_search='SPHERE', sphere_center=('10:', 'CA'))
mdl.superpose(mdl2, aln)

# Pick and superpose all atoms within 6 angstroms of any atom in 
# segment 2: to 10:
mdl.pick_atoms(aln, atom_types='ALL', selection_segment=('2:', '10:'),
               selection_search='SPHERE_SEGMENT', sphere_radius=6.0)
mdl.superpose(mdl2, aln)

# Pick and superpose all atoms in all loops (ie residues within 2 positions 
# of any gap in the alignment):
mdl.pick_atoms(aln, atom_types='ALL', selection_segment=('LOOPS', ''),
               selection_search='SEGMENT', gap_extension=(2, 2))
mdl.superpose(mdl2, aln)

# Pick and superpose all atoms within 6 angstroms of all loops (ie residues
# within 2 positions of any gap in the alignment):
mdl.pick_atoms(aln, atom_types='ALL', selection_segment=('LOOPS', ''),
               selection_search='SPHERE_SEGMENT', sphere_radius=6.0,
               gap_extension=(2, 2))
mdl.superpose(mdl2, aln)