model.superpose() -- superpose MODEL2 on MODEL 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_cutoffs = <float:11>	3.5 3.5 60 60 15 60 60 60 60 60 60	only the first element is used for calculating the cutoff 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')

Description:

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

MODEL must be the first sequence in the alignment; mdl must be the second sequence in the alignment. The equivalent atoms are those selected atoms (set 1) of the MODEL that have equivalently named atoms in mdl; the atom equivalences are defined in library $ATMEQV_LIB. Use the model.pick_atoms() command to select the desired atoms for superposition. By default, all atoms are selected.

No fitting is done if fit = False.

The rms_cutoffs[1] element 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_cutoffs[1] angstroms away from each other (as superposed using all aligned positions) and those equivalent distances which are less than rms_cutoffs[1] 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_cutoffs[1] 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

Example: examples/commands/superpose.py

# Example for: model.superpose()

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

env = environ()

mdl  = model(env, file='1fas')
mdl2 = model(env, file='2ctx')
aln = alignment(env, file='toxin.ali', align_codes=('1fas', '2ctx'))
mdl.pick_atoms(aln, pick_atoms_set=1, atom_types='CA')
mdl.superpose(mdl2, aln)
mdl2.write(file='2ctx.fit')

Example: examples/commands/align3d.py

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

# This will align 3D structures of two proteins:

log.verbose()
env = environ()

# 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')
mdl.pick_atoms(aln, atom_types='CA')
mdl2 = model(env, file='2ctx')
mdl.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 model.superpose() command:

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

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 = model(env, file=atfil)
aln = alignment(env)
aln.append_model(mdl, align_codes='1fdx', atom_files=atfil)
aln.append_model(mdl, align_codes='1fdx', atom_files=atfil)
mdl.generate_topology(aln, sequence='1fdx')
mdl.transfer_xyz(aln)
mdl.build(initialize_xyz=False, build_method='INTERNAL_COORDINATES')

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