## selection.superpose() — superpose model on selection given alignment

`superpose(mdl2, aln, fit=True, superpose_refine=False, rms_cutoff=3.5, reference_atom='', reference_distance=3.5, refine_local=True, swap_atoms_in_res='')`

Output:
  SuperposeData object

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

> The selection model must be the first sequence in the alignment; mdl2 must be the second sequence in the alignment. The equivalent atoms are the selected atoms that have equivalently named atoms in mdl2; 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 refine_local is `True` the superposition is then refined by considering local similarity. The DRMS profile of the two structures is calculated over a moving window of 11 residues, and a simple heuristic is then used to detect boundaries between local structural fragments. Then each of these fragments is used as the basis for least-squares fitting. The final returned orientation is that which results in the maximum number of equivalent positions, if any is better than the original superposition. (Note that this may result in a higher RMS.)

> 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 the selection model and mdl2 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 mdl2 are then swapped to minimize their RMS deviation relative to the selection model. The labeling 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 SuperposeData 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.initial_rms`; the RMS before superposition
- `r.rms`; the RMS after superposition
- `r.drms`; the distance RMS after superposition
- `r.cutoff_rms`; the RMS after superposition of atoms within rms_cutoff
- `r.cutoff_drms`; the DRMS after superposition of distances within rms_cutoff
- `r.rotation`; the rotation matrix that was used to transform mdl2 (applied first), if fit is `True`
- `r.translation`; the translation that was used to transform mdl2 (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
- `r.num_equiv_cutoff_pos`; the number of equivalent positions within rms_cutoff
- `r.num_equiv_cutoff_dist`; the number of equivalent distances within rms_cutoff

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/pdb1fdn.ent'
      mdl = complete_pdb(env, atfil)
      aln = alignment(env)
      aln.append_model(mdl, align_codes='orig')

      mdl2 = model(env, file='1fdn.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)