superpose module

Superimposition of structures by rigid-group / torsion optimization.

usage: superpose.py <moving>.pdb <target>.pdb

Module author: Michael S. Chapman <chapmami@ohsu.edu>

Authors:

Michael S. Chapman <chapmami@ohsu.edu>,

Oregon Health & Science University

Version:

0.5, March 23, 2016

Changed in version 0.1: 10/23/2012

Changed in version 0.5: 05/02/2015 ReStructuredText docs

Changed in version 0.5.5: 10/13/15 Anisotropic Us ride with atom rotations.

Changed in version 0.5.6: 03/23/16 Comparative analysis of anisotropic Us.

Todo

Pairing by sequence alignment.

class superpose.Accumulator

Bases: object

Running total, mean etc.

add(value, weight=1.0)

mean()

std()

class superpose.Arguments(imports=[], main=True, *args, **kwargs)

Bases: argparser.ArgumentParser

Subclass, adding program-specific command-line options.

Parameters:

• imports ((list of) ArgumentParser method(s)) – method(s) adding arguments to ArgumentParser instance. (Alternative to ArgumentParser parents w/ better maintained groups.)
• main (bool) – Parser for main program (i.e. not listed within an ArgumentParser parents argument). Adds default program information.

static export()

Adding options used in both stand-alone and imported modes.

finalize()

Completion of the parser after program sub-class initialized.

class superpose.Objective(target_atoms, target_selection, parameters, moving_selection, reference=None, verbosity=0, answer=None)

Bases: object

Callable methods for function, partials to be optimized.

Variables:

continuation (bool) – True (only) if additional cycles w/o changes to model or map calculation parameters. (Continues w/ prior numbering and skips first function evaluation.

Parameters:

• target_atoms (Atoms) – on which moving structure to be superposed
• target_selection (atoms.Selection) – which atoms are to be used.
• parameters (Parameters) – refinement parameters
• moving_selection (atoms.Selection) – atoms from moving_structure to be superposed on target_selection (must correspond 1-to-1)
• reference (Atoms or NoneType) – if torsion angle changes are to be restrained (option.torsion_weight), an optional reference state of the moving structure (same atoms, order etc.) can be provided (eg. input structure); else any restraint will apply from the start of each refinement batch.
• verbosity (int) – increase for greater diagnostic output
• answer (Atoms) – known correct structure (for testing)

Prone to large initial shift on 1st cycle when model is ~perfect with bfgs. Should be used with l_bgfs_b.

add_torsion_restraint()

Begin applying restraint on changes if torsion angle refinement.

callback(param, parameters_only=False)

Function to be called by optimizer at the end of each iteration.

Optionally calculates the correlation between the latest shifts and the gradients from the last evaluation of the previous cycle. (Empirically, get higher correlations with the final gradient estimate rather then the first.)

Parameters:

• param (1D ndarray) – refining parameters, x_k; Note not yet updated to x_k+1 as one might expect at the end of a cycle.
• parameters_only – Only the parameters have been updated from x_k to x_k+1, as occurs between the last callback and the end of refinement. Use True after end of refinement.

depends_on_anisou = False

If False, Objective independent of anisotropic U which are “riding” and can be ignored until final update.

f(param, preAlign=False)

Objective function callable for optimizer, with diagnostic output.

Parameters:

• param (1D ndarray) – refining parameters
• preAlign (bool) – Overall rigid-group superposition prior to function calculation. Should only use in diagnostics, not refinement, as incompatible with fprime which must be able to calculate derivatives for rigid-group refinement.

fprime(param)

Partials callable for optimizer, with diagnostic output.

Partial derivatives are mostly calculated by methods called and documented therein. Exceptions are some of the group and overall partial derivatives calculated from atomic partials.

Parameters:param (1D ndarray) – refining parameters

function_detail = 3

progress = 1

step_detail = 2

class superpose.PairItem(atoms)

Bases: object

One of the structures in a Pairing.

Variables:

• atoms – coordinates
• selection – atoms with which pairing to be tried
• paired – atoms successfully paired.
• equiv (dict) – indices of another structure paired to this one (see also matched_to)
• matched_to (ndarray) – indices of atoms of paired structure (only where self.paired)

One of the two structures in a pair.

Parameters:atoms (Atoms, Group or Selection) – coordinates, Group or Selection

copy(atoms, *attributes)

In-place copy of attributes from Atoms.

Does not re-pair atoms. It is unlikely, but conceivable that a user might want re-pairing if the pairing were based on xyz, b or o, or o as implicit through conformer.

Parameters:

• atoms (atoms.Atoms) – Coordinate set.
• attributes (str [, str...]) – names of attributes to be copied.

Returns:

updated Pairing coordinate set.

Return type:

Pairing.Item

from_pair(array)

Copy by index of paired atoms into an array, masked where unpaired.

Parameters:array (ndarray) – shape[0] must equal number of atoms in paired structure. Return mapped:values copied according to order in self.atoms Rtype numpy.MaskedArray:  

index

ndarray of indices of atoms matched.

matched_to = None

Indices for paired atoms where self.paired, calculated by Pairing.

reordered

Subset of atoms matched, in order of other structure.

reordered_paired

Trivial ‘all’ Selection for self.reordered when needed.

(As reordered contains only atoms paired with the other structure, Selection is, by definition ‘all’.)

class superpose.PairSubCommands(parent, prompt='sub-command')

Bases: cmd2nest.SubCmd, cmd2nest.ProgCmd

Sub-commands for pairing.

Parameters:

• parent (TopCmd instance) – Cmd object whence this call was made, usually self.
• prompt (str) – concatonated with the parent’s prompt.

do_match(instance, arg)

Pair atoms by attribute value (-v) and/or position (-p; order).

ATTR is specified as in “select –attr”, white-space replaced with “_”. Default: –value atom_name –value=residue_num -v conformer –position chain, (-v None (or -p None) avoids default, disabling value (position) matching.) Through the overall (pair -m/-t) and current (within -m/-t) selections and use of sufficient paired attributes, the specified match must be unambiguous 1:1.

Usage: match [options] arg

Options:

-h, --help	show this help message and exit
-v ATTR, --value=ATTR
	Match attribute by value (repeatable).
-p ATTR, --position=ATTR
	Match attribute by position (order; repeatable).

do_print(rest)

Pairing statistics.

do_within(instance, arg)

Limit atom matching to moving and/or target selection until redefined.

Selections are remembered between pair commands. These selections are combined (logical AND) with those of the parent pair command. Limits need only be defined for one of the structures, but both can be used if more convenient.

Usage: within [options] SELECTION_EXPR | SELECTION:

SELECTION_EXPR: boolean expr; see help SELECTION_EXPR.

SELECTION: COLLECTION[‘ITEM’] previously designated with a select command. SELECTION is usually defined only for –moving atoms and will usually be invalid if applied to –target atoms. COLLECTION or [‘ITEM’] can be omitted if defaults were used in the select command.

Options:

-h, --help	show this help message and exit
-m, --moving	Selection is for moving atoms.
-t, --target	Selection is for target atoms.

help_SELECTION_EXPR()

class superpose.Pairing(atomsA, atomsB)

Bases: object

Equivalences between two Atoms() coordinate sets, a & b.

Instantiate an empty Pairing.

Parameters:

• atomsA (Atoms, Group or Selection) – atomic coordinates, Group or Selection
• atomsB (Atoms, Group or Selection) – atomic coordinates, Group or Selection

See also

Pairing.add to fill it with atoms.

add(value=['atnam', 'resnum', 'conformer'], position=['chain'], selectionA=None, selectionB=None, verbose=True)

Add pairs of atoms with matching attributes.

Finds pairs of atoms in the selections that can be matched unambiguously by attribute value or order (position). Attributes are matched in a progression from chain-level to atomic. Those in ‘value’ require an exact match. Those in ‘position’ are matched by order of appearance at the current state, i.e. ignoring atoms that have already been excluded with a higher level attribute. (Thus for example, residues might be matched by position in each chain as long as the chains contain the same number of selected residues.) One could pair homologous proteins by selecting residues of each structure that are not in gaps, and then aligning residue-number by position.

May be called repeatedly to expand a pairing.

Time is proportional to the product of the selection sizes, so large structures can be paired faster by repeated calls with different chains selected.

Parameters:

• value (list of strings) – attributes that must match exactly. Synonyms in Selection._attributes are recognized.
• position (list of strings) – attributes that will be matched by order, providing that the selections contain the same numbers of each. Synonyms in Selection._attributes are recognized.
• selectionA (Selection or Group) – optional subset selection.
• selectionB (Selection or Group) – optional subset selection.

Raises LookupError:  

if any ambiguity remains in pairing.

attributeOrder = ['segid', 'chain', 'resnum', 'resnam', 'insert', 'atnam', 'atype', 'element', 'charge', 'conformer', 'altloc', 'o', 'b']

Order in which attributes will be paired.

bfactors(selection=None, name='User_selection', scaling=None, verbose=False, quiet=False, plot_screen=True, plot_files=None, color=None, residue_ttest=False, a_wt=True, b_wt=True, delta_wt=False, plot_hetatms=False)

Comparison of atomic displacement parameters of “a” (moving) to “b” (target).

Parameters:

• selection (Selection or Group or NoneType) – subset(s) of atoms (from self.a) to analyze
• name (str) – python-valid dict key name to be used for an unnamed selection.
• scaling (str or NoneType) – how the U values are to be scaled (atoms resized) to best match target atoms: “individual”, “group” or None. (The group(s) is/are defined by selection; selection=None for all-atom uniform).
• verbose (bool) – statistics by atom and residue
• quiet (bool) – statistics totaled by selection (only)
• plot_screen (bool) – comparative analysis of anisotropic Bs and coordinate differences graphed to screen. Requires user to close window, so use False for batch jobs.
• plot_files (str-2-uple) – file names for same graphical analysis, one comparing anisotropic Us, other comparing Us of moving structure to coordinate differences. Extension indicates file format: .emf, eps, jpeg, jpg, pdf, png, ps, raw, rgba, svg, svgz, tif, tiff. Can be used with plot_screen or independently.
• color (str-tuple) – names for pdb output of moving structure in which B-factors will be replaced by anisotropy of moving structure, 100 x |cos(U mis-alignment between paired atoms)|, and 100 x |cos(moving structure U mis-alignment vs. coordinate difference vectors)|, and (if names are provided), 100 x (1 - Kulback-Liebler divergence), and (if not already scaled), 100 x (1 - scaled Kulback- Liebler divergence). So the tuple should contain 0 or 3 to 5 file names, the 5th optionally None.
• residue_ttest (bool) – compare to randomized (shuffled atoms) using Welch’s t-test for unequal means. This is usually overkill, per-residue, as P(random) is usually tiny.
• a_wt (bool) – Weight weighted means by (1-Anisotropy) (i.e. asymmetry). (Can be used with other weights.)
• b_wt (bool) – Weight weighted means by B_iso (size of atom). (Can be used with other weights.)
• delta_wt (bool) – Weight weighted means by size of coordinate difference. (Use with care, because effects on U vs. U alignment might be different from U vs. delta xyz.) (Can be used with other weights.)
• plot_hetatms (bool) – include ligands and solvent in plots, else just polymers.

Return None:

Warning

Averages do not weight by occupancy of multiconformer parts.

Warning

Statistics calculated only for atoms input with anisotropic U tensors, not those input with only an ATOM (isotropic) record.

connectivity

Covalent connectivity of paired atoms.

Changed in version ?: For generality, don’t think that can restrict moving selection to self.a.paired, but this may have multiple consequences???

continuable = None

Superposition refinement just completed and can be extended.

deprecated_3ax = True

difference(verbose=False)

Difference between coordinate sets: rmsd(xyz), <|O1-O2|>, <|B1-B2|>

Returns:RMS deviation in coordinates, mean absolute difference in coordinates, occupancy & B-factor Return type:4 floats

See also

Atoms.difference provides similar functionality for coordinates that are not yet paired and will be paired by attribute value.

differences(quiet=False)

Print differences between coordinates by residue: each atom, rms.

Parameters:quiet (bool) – return vectors without printed output Returns:difference vector (a - b) for each paired atom Return type:numpy.MaskedArray of same (3, N) shape as self.a.atoms.xyz

See also

Atoms.differences provides similar functionality for coordinates that are not yet paired and will be paired by attribute value.

differences_vs_bs(scale=False, individual=False, map_to_a=True, intermediate=(0.0, 1.0), diagnostics=[0, 50.0])

Compare coordinate differences to B-factors.

Parameters:

• scale (Group|Selection|bool) – normalize for average b_iso atom size within group(s) of atoms in self (if specified), treating all non-selected atoms as an additional group.
• individual (bool) – scaling by individual atom, else by average isotropic B
• intermediate ((float, float)) – beyond these prolateness limits, the ellipsoid will be considered pure oblate and prolate respectively, transitioning between the two with a linear ramp between the limits.
• map_to_a (bool) – statistics for structure b will be mapped to the paired atoms of structure a; else will reordered as in structure a, but a contiguous array only for the b atoms that are paired.
• diagnostics ([int, float]) – print diagnostics for 1st n cases where alignment stats differ by more than threshold.

Returns:

difference magnitudes, then misalignments between diffence vectors and anisotropic Bs for both a and b structures

Return type:

(MaskedArray,) x 3, shapes len(self.a.atoms) (but 3rd shape is count(self.a.paired) if map_to_a=False).

Misalignment is the average (cosine) deviation.

equivs = None

Array[N, 2] with the paired indices from structures a & b.

info(verbose=False)

Difference statistics on matched atoms: rmsd(xyz), <|O1-O2|>, <|B1-B2|>

Returns:matched atoms, atoms in structure A, structure B Return type:3 int

loquacious = False

objective = None

Methods for refinement objective function, derivatives.

overlay(selection=None)

Rigidly transform selected atoms of “a” to superimpose on target “b”.

Initial alignment: faster/quicker convergence than superpose for overall superimposition, but less control. Uses Kabsch’s eigenvector method.

Parameters:selection (boolean Selection or Group) – atoms to be transformed, noting that all paired atoms are used for the alignment irrespective of which atoms are selected to be transformed. Returns:reference to the in-place updated Pairing. Return type:Pairing

parameters = None

Last refinement’s parameters, gradients, history etc..

residueTable = None

Changes, impact per residue.

superpose(continuation=False, refine=None, max_cycles=10, min_improvement=0.0, min_grad=0.0, reference=None, verbosity=0)

Superpose selected atoms of “a” onto target “b” by changing parameters.

With torsion optimization, the tuple phipsi supports definition of a subset of phi, psi angles within a moving atom selection. Within the moving atom selection, the dependence on each torsion angle is determined by a graph of atom connectivity determined automatically, and then optionally edited through the link and unlink parameters.

Parameters:

• continuation (bool) – resume a prior refinement, ignoring any new model parameterization arguments (individual atoms, groups, overall, phipsi).
• refine (optimize.AtomicParameterization or subclass) – definition of what is to be refined, how atomic parameters are to be collectivized.
• min_improvement (float) – refinement (l_bfgs_b) is stopped when relative change in function < min_improvement, i.e. precision of 1.e-2 stops when change < 1% of current residual value.
• max_cycles (int) – maximum number of max_cycles (hard limit for bfgs; approx. for l-bfgs, as have to guess a corresponding limit on function calculations).
• min_grad (float) – refinement stopped when the largest derivative magnitude falls below this value (internal parameter units as reported by analyze).
• reference (Atoms or NoneType) – if torsion angle changes are to be restrained (option.torsion_weight), an optional reference state of the moving structure (same atoms, order etc.) can be provided (eg. input structure); else any restraint will apply from the start of each refinement batch. This structure is also used if residue tables and plots use overall options.
• verbosity (int) – -1 for silent, 0 for terse, 1 for verbose, > 1 for (debugging) information on each function or gradient evaluation.

Returns:

new object of moved atoms

Return type:

Atoms

class superpose.Parameters(atoms, parameter_selection={'position': {'overall': True, 'indiv': False, 'group': True, 'torsion': True}, 'occ': {'overall': False, 'indiv': False, 'group': False}, 'B': {'overall': False, 'indiv': False, 'group': False}, 'magnification': False}, defaults=None, link=None, unlink=None)

Bases: optimize.Parameters

grouping = 'group'

param = 'magnification'

partials = "{\n 'position':{'indiv':dxyz, 'group':drigid, \n 'overall':dxyzoverall, 'torsion': dtorsion},\n 'B': {'indiv':False, 'group':False, 'overall':False},\n 'occ':{'indiv':False, 'group':False, 'overall':False},\n 'magnification': False\n }"

supported_modes = "{\n 'position':{'indiv':False, 'group':True, 'overall':True, \n 'torsion': True},\n 'B': {'indiv':False, 'group':False, 'overall':False},\n 'occ':{'indiv':False, 'group':False, 'overall':False},\n 'magnification': False\n }"

value = False

class superpose.Tasks

Bases: atoms.Tasks, optimize.Tasks

Program-specific tasks, supporting just-in-time execution.

Methods with names ending _prereq define tasks whose prerequisites will be met, if possible, prior to execution.

atoms_being_evaluated

atoms_refined

backup(jar)

Pickle current refinement state for future restoration.

Saves the current coordinates, ResidueTable and refinement History, but not the parameterization, options etc..

Parameters:jar (str) – file name

backup_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

bfactors(*args, **kwargs)

Analysis of atomic displacement parameters.

bfactors_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

default_group

evaluate(quiet=False, verbose=False, color=None, scale=1.0)

Current model statistics.

Parameters:

• color (str|NoneType) – name of a new PDB file in which B will be replaced by the coordinate difference.
• scale (float) – for the differences in the PDB file.

evaluate_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

flip(glu=True, gln=True, asp=True, asn=True, his=True, phe=True, tyr=True, arg=True, **kwargs)

Side-chain flipping of moving coordinates, invokes rotamer.flip().

Tests residue type specified as True.

flip_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

overlay(moving=None)

Overalay selected atoms of moving structure onto target.

Parameters:moving (Selection) – atoms to be transformed, noting that the least-squares transformation is calculated using all paired atoms, not just those selected.

overlay_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

pair(value=None, position=None, moving=None, target=None)

Pair atoms between structure A (moving) & B (target).

Requires self.pairing as a Pairing instance.

Parameters:

• value (list of strings) – attributes that must match exactly. Synonyms in atoms.Selection._attributes are recognized.
• position (list of strings) – attributes that will be matched by order, providing that the selections contain the same numbers of each. Synonyms in atoms.Selection._attributes are recognized.
• moving (atoms.Selection or str criteria) – atoms within A used for this pairing command.
• target (atoms.Selection or str criteria) – atoms within B used for this pairing command.

Returns:

updated self.pairing

Return type:

atoms.Pairing

Changed in version 02/13: Reimplemented to use Pairing, supporting selections on both structures and matching by flexible criteria.

pair_init(moving=None, target=None)

Prepare to pair atoms between structure A (moving) & B (target).

Parameters:

• moving (Atoms, Selection or str (criterion for Selection)) – atoms [def. self.atoms] or master selection thereof for subsequent pairing commands. Future selections will be combined with the optional master selection through logical AND.)
• target (Atoms, Selection or str (criterion for Selection)) – atoms [def. self.target_in] or master selection thereof for subsequent pairing commands. Future selections will be combined with the optional master selection through logical AND.)

Returns:

self.pairing

Return type:

Pairing

pair_init_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

pair_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

parameterization_init()

Initialize parameterization - directives on what/how to refine.

parameterization_init_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

parameterize()

Pass-back after checking prerequisites for parameterize sub-comds.

parameterize_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

phipsi_copy(**arguments)

Copy phi, psi from target into current structure.

Parameters:sigma (float) – copy only dihedrals whose difference exceeds this sigma-level.

phipsi_copy_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

phipsi_diff(color=None, pseudo=False, normalized=True, **arguments)

Difference in phi, psi between current structure & target.

Parameters:

• color (str or NoneType) – PDB filename is which Bs will reflect phi-psi differences.
• pseudo (bool) – φ_{i’ is to be combined with |psgr|:sub:`i-1} in above PDB.
• normalized (bool) – use relative magnitudes instead of actual torsion angle differences.

phipsi_diff_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

read_coords(*args, **kwargs)

read_target(new_file=None)

New coordinates for target, but does not recalculate statistics.

Parameters:new_file (str) – PDB file to be read.

read_target_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

refine(continuation=False, restart=False, method='l_bfgs_b', max_cycles=0, min_improvement=0.0, min_grad=0.0, verbosity=0)

Superpose wrapper: align moving molecule to target.

Parameters:

• continuation (bool) – If not restart, treat as a continuation of a prior batch if no change in parameterization and atoms since last refinement. False - force a new batch.
• restart (bool) – from start of prior refinement.
• min_improvement (float) – refinement (l_bfgs_b) is stopped when relative change in function < min_improvement, i.e. precision of 1.e-2 stops when change < 1% of current residual value.
• max_cycles (int) – maximum number of max_cycles (hard limit for bfgs; approx. for l-bfgs, as have to guess the corresponding limit on function calculations).
• min_grad (float) – refinement stopped when the largest derivative magnitude falls below this value (internal parameter units as reported by analyze).
• verbosity (int) – -1 for silent, 0 for terse, 1 for verbose, > 1 for (debugging) information on each function or gradient evaluation.

Returns:

new object of moved atoms

Return type:

Atoms

refine_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

restore(jar)

Restores a previously pickled refinement end-point.

Restores the current coordinates, ResidueTable, History and selected refinement and parameter attributes.

Parameters:jar (str) – file name

Warning

options and parameterization must be made compatible with jar-file before it is loaded.

Warning

FRAGILE - because refinement and parameter instances contain methods, they cannot be pickled. They must exist and have been instantiated with the same parameterization mapping with which the objects in the jar file were created. Then instances with the methods can have selected attributes rebound to jar objects.

See also

restore_prereq for creation of a new refinement instance if needed.

See also

comments in code for backup for explanation.

restore_prereq(*args, **kwargs)

Pass-through, trying to meet the prerequisites.

If refinement has not previously been run, it will be implicitly through the prerequisite defined for self._restore.

Warning

No matter how created, the refinement instance must have been created with the same parameterization (and program options) as when the jar file was saved. There is no error checking, and unpredictable results are expected, because otherwise the mapping of structural parameters to the optimization parameter array will be garbled.

restrain_to_reference = True

run_test(name, arguments=None)

Program development testing.

verbose = False

class superpose.Test(name)

Bases: object

set_options(options)

class superpose.TopCommands(tasks, initial_commands=None, py_locals={}, parser=None)

Bases: atoms.Commands, optimize.Commands, cmd2nest.TopCmd, cmd2nest.ProgCmd

Top-level commands for Program Prog.

Parameters:

• tasks (Control) – class instance that defines methods to be called.
• initial_commands (str or list of str) – file(s) of commands to run before interactive loop at the top level, and before any command-line commands.
• py_locals (dict) – objects added to the local namespace in the python interpreter invoked by ‘py’ commands.
• parser (ArgumentParser (argparse) or OptionParser (optparse)) – to which -t / –test option will be added for cmd2 regression testing. Should only be used once / program.

do_backup(arg)

do_bfactors(instance, arg)

B-factor statistics comparing current model to target. Usage: bfactors [options] SELECTION_EXPR | SELECTION | COLLECTION:

Group(s) of atoms over which average statistics are to be output.

SELECTION_EXPR: boolean expr; see help SELECTION_EXPR.

COLLECTION: a dictionary-like Group of SELECTIONs (defined by prior select command) over which statistics are iterated.

SELECTION: COLLECTION[‘ITEM’] previously defined with a select command.

COLLECTION or [‘ITEM’] can be omitted if defaults were used in the select command.

Options:

-h, --help	show this help message and exit
-v, --verbose	Including per-residue information.
-p OUTPUT_type, --plot=OUTPUT_type
	Plot to “screen” or “file” an analysis of anisotropic Bs and coordinate differences. Repeat for both.
-f FILE, --file=FILE
	base of the file name (for –plot=file) into which “_cmp_U” and “_U_vs_xyz” will be inserted for 2 plots. The extension designates the file-type: .emf, eps, jpeg, jpg, pdf, png, ps, raw, rgba, svg, svgz, tif, tiff.
-c PDB_out, --color=PDB_out
	Output pdb files with B-factors replaced for molecular graphic illustration of the following statistics. The argument gives the base file name, which is modified to indicate the contents of the B-factor column: “_A”- 100 x Anisotropy of moving structure; “_U_vs_U”- 100 x |cos(deviation U_moving vs. U_target)|; “_U_vs_xyz”- 100 x |cos(deviation U_moving vs. coordinate difference vector)|; “_div”- Kullback-Liebler divergence for U_moving vs. U_target; “_div_scaled”- like “_div” except scaled by B_iso for each atom (like Merritt, 2011) - this is only output if SCALING is not “individual”. [“_div” and “_div_scaled” are provided for comparison and may be deprecated.] Use -c None to disable output of all files.
-s SCALING, --scaling=SCALING
	Scaling of anisotropic Us for atom size (B_iso) by individual (atom) or group or overall (by means of all paired atoms).

do_evaluate(instance, arg)

Statistics for current model compared to target. Usage: evaluate [options] arg

Options:

-h, --help	show this help message and exit
-v, --verbose	Including per-residue information.
-c PDB_file, --color=PDB_file
	Output superimposed stucture, B replaced by |coordinate difference|.
-s float, --scale=float
	Scale by which differences in PDB_file will be multiplied.

do_flip(instance, arg)

Chi rotation of pseudo-symmetrical side chains to match target.

180 degree rotations about sp3-sp2 bonds.

Usage: flip [options] arg

Options:

-h, --help	show this help message and exit
-R, --arg	Include arginines.
-N, --asn	Include asparagines.
-D, --asp	Include aspartates.
-Q, --gln	Include glutamines.
-E, --glu	Include glutamates.
-H, --his	Include histidines.
-F, --phe	Include phenylalinines.
-Y, --tyr	Include tysosines.
-a, --all	All amino acids, default if none specified.
-v VERBOSITY, --verbosity=VERBOSITY
	-1 (quiet) to +1 (verbose)

do_overlay(instance, arg)

Apply the rigid transformation that LSQ overlays moving atoms on paired targets.

For a single rigid group, this is prefered over iterative refinement, using the Kabsch method to give the least-squares solution in a single step.

overlay transforms selected coordinates by the rigid group operator

that least-squares aligns previously paired refining and target atoms. (Note that the selection here (default is ‘all’) can be different from the selections used in pairing.) The operator is determined by Kabsch’s eigenvector method [Kabsch-1976], [Kabsch-1978]. This is a direct (linear) method that can circumvent slow and narrow convergence of the non-linear methods in refine. However, it cannot be combined with torsion angle parameterization or external restraints. It is best used as a preliminary such that refine can start well within its convergence radius.

[Kabsch-1976]

Kabsch, W., 1976. A solution for the best rotation to relate two sets of vectors. Acta Crystallographica A32, 922-3.

[Kabsch-1978]

Kabsch, W., 1978. A discussion of the solution for the best rotation to relate two sets of vectors. Acta Crystallographica A34, 827-8.

Usage: overlay [options] arg

Options:

-h, --help

show this help message and exit

-m SELECTION_EXPR|SELECTION, –moving=SELECTION_EXPR|SELECTION

Selection of atoms to move; default: all. SELECTION_EXPR: boolean expr; see help SELECTION_EXPR. SELECTION: COLLECTION[‘ITEM’] previously designated with a select command. COLLECTION or [‘ITEM’] can be omitted if defaults used in select command. This option does not change the pairing or the transformation operator.

do_pair(instance, arg)

Pair atoms between moving & target structures. Required before flip, refine etc..

Option –moving and –target selections limit the atoms that are available for matching in (just) this pair session (defaults are all atoms). These selections are combined (logical AND) with those of the pair>within subcommand. Limits need only be defined for one structure, but either/both can be specified for convenience.

Usage: pair [options] arg

Options:

-h, --help	show this help message and exit
-e, --extend	Extend prior pairing, else start anew.

-m SELECTION|SELECTION_EXPR, –moving=SELECTION|SELECTION_EXPR

Moving atoms for this pair session. SELECTION_EXPR: boolean expr; see help SELECTION_EXPR. SELECTION: COLLECTION[‘ITEM’] previously designated with a select command. COLLECTION or [‘ITEM’] can be omitted if defaults used in select command.

-t SELECTION_EXPR, --target=SELECTION_EXPR
	Target atoms for this pair session.

do_parameterize(instance, arg)

For designated parameter type(s) (default positions), select atoms to be refined & how. Usage: parameterize [options] arg

Options:

-h, --help	show this help message and exit
-p, --position	Designate which atomic positions (xyz, default) to be refined.

do_phipsi_copy(instance, arg)

Difference in phi, psi between current structure & target. Usage: phipsi_copy [options] arg

Options:

-h, --help	show this help message and exit
-s FLOAT, --sigma=FLOAT
	Copy only dihedrals above these standard deviations.
-p, --pseudo	Sigma threshold applies to pseudo-dihedrals (phi_i + psi_i-1) rather than individual torsion angles.
-c, --confirm	Confirm each change interactively before applying.

do_phipsi_diff(instance, arg)

Difference in phi, psi between current structure & target. Usage: phipsi_diff [options] [Header inserted into top of PDB file]

Options:

-h, --help	show this help message and exit
-c PDB-FILE, --color=PDB-FILE
	Output coordinates for display - B-factors set to differences.
-H, --hinge	hinge analysis using THRESHOLD & GAP
-g INT, --gap=INT
	# residues w/o dihedral changes that can be bridged in a hinge
-t FLOAT, --threshold=FLOAT
	above which dihedral rotations considered hinges. Degrees if > 1.0, else fraction of total change.
-s START, --start=START
	start of an explicitly defined hinge: chain-residue, requires –end, repeatable.
-e END, --end=END
	end of an explicitly defined hinge: chain-residue, requires –end, repeatable.
-n, --normalized
	Color by relative absolute differences not actual signed values, and plot absolute values.
-p, --pseudo	quasi pseudo-torsion angles, combining phi_i w/ psi_i-1
-P, --plot	graph the differences.

do_refine(instance, arg)

Refine atomic model. Usage: refine [options] arg

Options:

-h, --help	show this help message and exit
-C INT, --max_cycles=INT
	Maximum number of cycles.
-i FLOAT, --min_improvement=FLOAT
	End when per-cycle improvement falls below this value.
-g FLOAT, --min_grad=FLOAT
	End when gradient norm falls below this value.
-n, --new_batch
	New batch (losing prior history), else continue prior (default) if exists/possible.
-r, --restart	From original coordinates (implies -n).
-v INT, --verbosity=INT
	Per-cycle logging: -1 (terse) to 3 (verbose) [def. 0].

do_restore(arg)

do_test(rest)

Run a program developer’s test.

help_backup()

help_restore()

help_test()

superpose.dissect(obj, doc)

Recusrively type the attributes of an object, printing documentation..

A diagnostic used to gopher out forgotten burried ndarrays that hopefully will never be needed again.

Parameters:

• obj – object (and its attributes) to be typed.
• doc (str) – printed label, often the attribute name.

superpose.findS0(obj, doc, exception=False, verbose=True)

Recusively gopher out string ndarrays.

Documents string ndarrays which will cause pickle.load() errors. Scans attributes, but not items if object is a sequence.

Parameters:

• obj – object and its attributes to be analyzed.
• doc (str) – label to be printed, often attribute name.
• exception (bool) – raise exception if zero-length numpy.string encountered, noting that ndarray initialization to [‘’, ‘’] gives length-1. It might be only those instantiated to None or numpy.nan that raise exception.
• verbose (bool) – print (some of) array contents if numpy.string

superpose.startup()

Program initialization, reading options etc..

Returns:parser Return type:Arguments.ArgumentParser

superpose.std_err_mu(var_a, a_size, var_b, b_size)

Standard error between sample means.

BMJ introduction

This is the same as the standard error between small-sized sample and population mean (unequal variances). (BMJ explanation)

superpose.t1_Welch_gt(data, comparison)

Welch’s unequal variances 1-tailed t-test for mean(data)>mean(comparison)

Parameters:

• data (ndarray) –
• comparison (ndarray) –

(Like a student t-test for unequal variances; Wiki)

superpose.t1_Welch_lt(data, comparison)

Welch’s unequal variances 1-tailed t-test for mean(data)<mean(comparison)

Parameters:

• data (ndarray) –
• comparison (ndarray) –

(Like a student t-test for unequal variances; Wiki)

superpose.z_d(mean_a, var_a, a_size, mean_b, var_b, b_size)

Difference between means in standard error units (z-score).

BMJ introduction

This is the same as Sattherwaite’s approach for an analogous d-score:

BMJ t-test explanation

Also same as Welch’s unequal variances t-test, for calculation of a Student-t like difference in means (t-statistic).

So we also calculate degrees of freedom for a t-test .. deprecated:: use scipy.stats.ttest_ind(equal_var=False)

or scipy.stats.mstats.ttest_ind(equal_var=False)