selection.superpose() -- superpose MODEL2 on selection given alignment

mdl = <model>		Input model for superposition
aln = <alignment>		Alignment between the two models
fit = <bool:1>	True	whether to superpose
superpose_refine = <bool:1>	False	whether to refine the superposition
rms_cutoff = <float:1>		cutoff for RMS and DRMS measures
reference_atom = <str:1>	''	reference atom name in SUPERPOSE
reference_distance = <float:1>	3.5	cutoff for selecting reference positions in SUPERPOSE
refine_local = <bool:1>	True	whether to refine superposition using locally similar substructures
swap_atoms_in_res = <str:1>	''	minimize RMS by swapping atoms in these residues (1 char code: 'DEFHLNQRVY')

Output:

superpose_data object

This command superposes mdl on the selection, without changing the alignment, aln.

The selection model must be the first sequence in the alignment; mdl must be the second sequence in the alignment. The equivalent atoms are the selected atoms that have equivalently named atoms in mdl; the atom equivalences are defined in library $ATMEQV_LIB.

No fitting is done if fit = False.

rms_cutoff is the cutoff used in calculating the cutoff RMS deviations; i.e., those position and distance RMS deviations that are defined on the equivalent atoms which are less than rms_cutoff angstroms away from each other (as superposed using all aligned positions) and those equivalent distances which are less than rms_cutoff angstroms different from each other, respectively.

If superpose_refine is True the refinement of the superposition is done by repeating the fitting with only those aligned pairs of atoms that are within rms_cutoff of each other until there is no change in the number of equivalent positions. This refinement can only remove compared positions, not add them like alignment.align3d() can do. This is useful for comparing equivalent parts of two structures with a fixed alignment but omitting divergent parts from the superposition and RMS deviation calculation; e.g., comparing a model with the X-ray structure.

If superpose_refine is False and reference_atom is non-blank, only those pairs of equivalently named selected atoms from aligned residues are superposed that come from residues whose reference_atom atoms are closer than reference_distance to each other.

When MODEL and mdl have exactly the same atoms in the same order, one can set swap_atoms_in_res to any combination of single character amino acid residue codes in DEFHLNQRVY. Certain atoms (see below) in the specified sidechains of mdl are then swapped to minimize their RMS deviation relative to MODEL. The labelling resulting in the lowest RMS deviation is retained. The following swaps are attempted:

Residue	Swap(s)
D	OD1, OD2
E	OE1, OE2
F	CD1, CD2
	CE1, CE2
H	ND1, CD2
	NE2, CE1
N	OD1, ND2
Q	OE1, NE2
R	NH1, NH2
V	CG1, CG2
Y	CD1, CD2
	CE1, CE2

On successful completion, a superpose_data object is returned, which contains all of the calculated data. For instance, if you save this in a variable 'r', the following data are available:

• r.rms; the RMS after superposition
• r.drms; the distance RMS after superposition
• r.rotation; the rotation matrix that was used to transform mdl (applied first), if fit is True
• r.translation; the translation that was used to transform mdl (applied after rotation), if fit is True
• r.num_equiv_pos; the number of equivalent positions
• r.num_equiv_dist; the number of equivalent distances

Example: examples/commands/superpose.py

# Example for: selection.superpose()

# This will use a given alignment to superpose Calpha atoms of 
# one structure (2ctx) on the other (1fas).

from modeller import *

env = environ()
env.io.atom_files_directory = '../atom_files'

mdl  = model(env, file='1fas')
mdl2 = model(env, file='2ctx')
aln = alignment(env, file='toxin.ali', align_codes=('1fas', '2ctx'))

atmsel = selection(mdl).only_atom_types('CA')
r = atmsel.superpose(mdl2, aln)

# We can now use the calculated RMS, DRMS, etc. from the returned 'r' object:
rms = r.rms
drms = r.drms
print "%d equivalent positions" % r.num_equiv_pos

mdl2.write(file='2ctx.fit')

Example: examples/commands/align3d.py

# Example for: alignment.align3d(), selection.superpose()

# This will align 3D structures of two proteins:

from modeller import *
log.verbose()
env = environ()
env.io.atom_files_directory = '../atom_files'

# First example: read sequences from a sequence file:
aln = alignment(env)
aln.append(file='toxin.ali', align_codes=['1fas', '2ctx'])
aln.align(gap_penalties_1d=[-600, -400])
aln.align3d(gap_penalties_3d=[0, 4.0])
aln.write(file='toxin-str.ali')

# Second example: read sequences from PDB files to eliminate the
# need for the toxin.ali sequence file:
mdl = model(env)
aln = alignment(env)
for code in ['1fas', '2ctx']:
    mdl.read(file=code)
    aln.append_model(mdl, align_codes=code, atom_files=code)
aln.align(gap_penalties_1d=(-600, -400))
aln.align3d(gap_penalties_3d=(0, 2.0))
aln.write(file='toxin-str.ali')

# And now superpose the two structures using current alignment to get
# various RMS's:
mdl = model(env, file='1fas')
atmsel = selection(mdl).only_atom_types('CA')
mdl2 = model(env, file='2ctx')
atmsel.superpose(mdl2, aln)

Example: examples/commands/swap_atoms_in_res.py

# This script illustrates the use of the swap_atoms_in_res
# argument to the selection.superpose() command:

# Need to make sure that the topologies of the two molecules
# superposed are exactly the same:

from modeller import *
from modeller.scripts import complete_pdb

env = environ()
env.libs.topology.read(file='$(LIB)/top_heav.lib')
env.libs.parameters.read(file='$(LIB)/par.lib')

atfil = '../atom_files/1fdx.atm'
mdl = complete_pdb(env, atfil)
aln = alignment(env)
aln.append_model(mdl, align_codes='orig')

mdl2 = model(env, file='./1fdx.swap.atm')
aln.append_model(mdl2, align_codes='swap')
atmsel = selection(mdl)
atmsel.superpose(mdl2, aln, swap_atoms_in_res='')
atmsel.superpose(mdl2, aln, swap_atoms_in_res='DEFHLNQRVY', fit=False)
atmsel.superpose(mdl2, aln, swap_atoms_in_res='', fit=True)