Official government website icon

bit	Xplor-NIH	VMD-XPLOR

Pydoc: module torsionDBPotTools

torsionDBPotTools

index

Module to help set up statistical torsion angle, interpolated potentials. Although the provided tools are general and can be used for setting up any such potential (e.g. user-provided), this module is specially suited for setting up the so-called torsionDB potential for protein, RNA, and DNA. A particularly useful function is create_TorsionDBPot, which generates the potential. When using this module, please cite: For protein applications: Bermejo, G.A., Clore, G.M., and Schwieters, C.D. (2012). Smooth statistical torsion angle potential derived from a large conformational database via adaptive kernel density estimation improves the quality of NMR protein structures. Protein Sci. 21, 1824-1836. For RNA applications: Bermejo, G.A., Clore, G.M., and Schwieters, C.D. (2016). Improving NMR structures of RNA. Structure 24, 806-815.

Classes

builtins.object

PotData

potList.PotList(potList.rc_Pot)

TDBPotl

class PotData(builtins.object)

PotData(name, values=[], metaselections=['resid _RESID-1 and name C', 'resid _RESID and name N', 'resid _RESID and name CA', 'resid _RESID and name C', 'resid _RESID and name N', 'resid _RESID and name CA', 'resid _RESID and name C', 'resid _RESID+1 and name N'], info='', elevel=-999)

Simple data structure to collect data that will be associated with an
N-dimensional torsionInterpolPot.TorsionInterpolPotND potential term.

Attribute description:

name (a string) is a name that may be given to the term.

metaselections is a list of strings, each a metaselection for an atom that,
along with the rest, define the torsion angle(s) applicable to the term.

info is a comment string that can be retrieved from the term via the
comment method.

values is a dictionary that contains all the numerical data of the term.
The keys are integers: for example, 1 labels the axis that corresponds to
the first angle defined in the metaselections list. The largest key is used
to identify the energy values. The numbers associated with the axes and
energy are provided by the dict values in the form of a list.

elevel specifies an energy level above which the corresponding torsion
angle(s) in the structure under study will be flagged as "violated" (note
that any scaling on the potential will not affect this functionality;
unscaled energies are considered).

Methods defined here:

__init__(self, name, values=[], metaselections=['resid _RESID-1 and name C', 'resid _RESID and name N', 'resid _RESID and name CA', 'resid _RESID and name C', 'resid _RESID and name N', 'resid _RESID and name CA', 'resid _RESID and name C', 'resid _RESID+1 and name N'], info='', elevel=-999): Initialize self. See help(type(self)) for accurate signature.

Data descriptors defined here:

__dict__: dictionary for instance variables (if defined)

__weakref__: list of weak references to the object (if defined)

class TDBPotl(potList.PotList)

TDBPotl(name, noPotSummary=False)

A special potList.Potlist to hold torsion angle database potential terms.

Methods defined here are intended for violation analysis.

Method resolution order:: TDBPotl; potList.PotList; potList.rc_Pot; builtins.object

Methods defined here:

__init__(self, name, noPotSummary=False): Initialize self. See help(type(self)) for accurate signature.

numRestraints(self): Return the number of restraints of one term in the sequence.

rms(self): Not implemented.

violations(self): Return number of residues outside favored torsion angle regions.

Methods inherited from potList.PotList:

__deref__(self, *args, **kwargs) -> 'PotList *'

__getitem__(self, cnt)

__getslice__(self, *args, **kwargs) -> 'PotList'

__len__(self, *args, **kwargs) -> 'int'

__oldinit__ = __init__(self, *args, **kwargs)

__ref__(self, *args, **kwargs) -> 'PotList &'

__repr__ = _swig_repr(self)

add(self, pot)

addEnergyReport(self, *args, **kwargs) -> 'void'

addEnsWeights(self, *args, **kwargs) -> 'void'

append(self, pot)

byName(self, *args, **kwargs) -> 'rc_Pot'

calcWDerivs(self, *args, **kwargs) -> 'bool const'

clearEnergyReports(self, *args, **kwargs) -> 'void'

clearEnsWeights(self, *args, **kwargs) -> 'void'

copy(self, potList)

decrRefCnt(self, *args, **kwargs) -> 'void'

energyMaybeDerivs0(self, *args, **kwargs) -> 'float_type'

energyMaybeDerivs1(self, *args, **kwargs) -> 'float_type'

energyMaybeDerivs2(self, *args, **kwargs) -> 'float_type'

energyMaybeDerivs3(self, *args, **kwargs) -> 'float_type'

energyMaybeDerivs4(self, *args, **kwargs) -> 'float_type'

energyMaybeDerivsPost(self, *args, **kwargs) -> 'float_type'

energyMaybeDerivsPre(self, *args, **kwargs) -> 'float_type'

energyReports(self, *args, **kwargs) -> 'CDSList< EnergyReport >'

ensWeight(self, *args, **kwargs) -> 'float_type'

ensWeights(self, *args, **kwargs) -> 'CDSList< float_type >'

ensWeightsInfo(self, *args, **kwargs) -> 'String'

getEnsWeights(self, *args, **kwargs) -> 'CDSList< VarEnsWeights > &'

getitem_int(self, *args, **kwargs) -> 'rc_Pot'

getitem_string(self, *args, **kwargs) -> 'rc_Pot'

incrRefCnt(self, *args, **kwargs) -> 'void'

instanceData(self, *args, **kwargs) -> 'PyObject *'

isParallel(self, *args, **kwargs) -> 'bool const'

keys(self)

list(self, *args, **kwargs) -> 'CDSList< rc_Pot >'

makeCopy(self, *args)

pyXplorHelp(self, *args, **kwargs) -> 'String'

refCnt(self, *args, **kwargs) -> 'int'

registerInstanceData(self, *args, **kwargs) -> 'void'

registerTo(self, *args, **kwargs) -> 'void'

remove(self, name)

removeAll(self, *args, **kwargs) -> 'void'

renamed_add(self, *args, **kwargs) -> 'void'

renamed_makeCopy(self, *args, **kwargs) -> 'rc_DerivedPot< PotList >'

renamed_remove(self, *args, **kwargs) -> 'void'

resetInstanceName(self, *args, **kwargs) -> 'void'

resetPotName(self, *args, **kwargs) -> 'void'

setCalcWDerivs(self, *args, **kwargs) -> 'void'

setEnsWeights(self, *args, **kwargs) -> 'void'

setIsParallel(self, *args, **kwargs) -> 'void'

setThreshold(self, *args, **kwargs) -> 'void'

setUseSimEnsWeights(self, *args, **kwargs) -> 'void'

showReport(self, *args, **kwargs) -> 'String'

simulation(self, *args) -> 'EnsembleSimulationBase const *'

size(self, *args, **kwargs) -> 'int'

threshold(self, *args, **kwargs) -> 'float_type const'

unRegister(self, *args, **kwargs) -> 'void'

updateDelta(self, *args, **kwargs) -> 'void'

updateEnsWeights(self, *args, **kwargs) -> 'void'

updateValues(self, *args, **kwargs) -> 'void'

useSimEnsWeights(self, *args, **kwargs) -> 'bool const'

Static methods inherited from potList.PotList:

__swig_destroy__ = delete_PotList(...)

Data descriptors inherited from potList.PotList:

instanceDataCleanup

instanceDataCreate

instanceData_

modified

registeredSimulations

thisown: The membership flag

Data and other attributes inherited from potList.PotList:

noViolationStats = True

Methods inherited from potList.rc_Pot:

calcEnergy(self, *args, **kwargs) -> 'float_type'

calcEnergyAndDerivs(self, *args, **kwargs) -> 'float_type'

instanceName(self, *args, **kwargs) -> 'String'

potName(self, *args, **kwargs) -> 'String'

scale(self, *args, **kwargs) -> 'float_type'

setScale(self, *args, **kwargs) -> 'void'

Data descriptors inherited from potList.rc_Pot:

__dict__: dictionary for instance variables (if defined)

__weakref__: list of weak references to the object (if defined)

Functions

analyze(potlist): Perform analysis of torsionDBPot terms.

create_RepelPot14(sim, verbose=False): Return a repelPot.RepelPot instance.

The returned potential contains 1-4 interactions between atoms bound to
idi and idj for each (idi, idj) tuple in global torsions list.

create_Terminal14Pot(name, repel=None, selection='not PSEUDO'): Return a repelPot.RepelPot instance with 1-4 interactions of terminal
protonated groups.

Statistical torsion angle potentials are designed to replace parametric
terms like the older XPLOR dihedral potential.
They perform better when the van der Waals interactions between atoms
separated by three bonds (i.e., 1-4 interactions) are turned off, as such
interactions types are already implied in the potential.  However, by
nature, statistical torsion angle potentials only involve torsions defined
by heavy atoms, leaving those involving terminal protons (e.g., methyl
groups) unrestrained.  As a result, if no 1-4 interactions are allowed for
such groups, unrealistic eclipsed conformations may be obtained.  This
function returns a repelPot.RepelPot instance with the 1-4 nonbonded
interactions of such terminal protonated groups.

The argument name is the instanceName assigned to the returned
repelPot.RepelPot.  The optional repel argument (float) is the scale
factor for the atomic radii; its optimal value depends on the version of the
parameter file used.  The selection argument is a string or atomSel.AtomSel
object used to specify a subset of the atoms (or an alternate
simulation.Simulation.)  FIX: improve this paragraph.

In the future this function will be deprecated in favor of a dedicated,
parametric torsion angle potential that complements the statistical torsion
angle term used.

create_TorsionDBPot(name='', selection='all', system='protein', database='default', threshold='99.95', ext='.dat', verbose=False): Return a potList.PotList of statistical torsion angle potential
terms (or a repelPot.RepelPot instance involving selected 1-4
interactions).

Sets up torsion angle potential terms (of the type defined in the
torsionInterpolPot module), based on statistics collected from a
database.  The name argument gives the name to the returned
potList.PotList.  The type of system under consideration ('protein',
'rna', or 'dna') is specified by the system argument (a string).  (An
additional, special value for system, 'repel14', is discussed below.)

The database argument is a string with the name of either a database file or
a directory containing one or more database files (in the latter case, only
files with the extension given by the ext argument are considered).
Alternatively, a sequence with several such filenames can be provided as the
database argument.  If no database files are specified, the default files
for the corresponding system are used (database='default').  The path of a
database file or directory is established (with the getdbfilepath function)
by first searching in the working directory, and then in a system-specific
location within the Xplor-NIH directory; such location can be found as
follows:

    print( torsionDBPotTools.getdblocation('protein') ) # prints location
                                                  # of protein databases in
                                                  # Xplor-NIH directory

For documentation on the format of database files see the README.format
file in the databases/torsions directory within the Xplor-NIH directory.
The selection argument specifies the atoms to subject to the database
potential (all atoms by default); it can be an XPLOR-style selection string
or an atomSel.AtomSel instance.  Note that certain torsion angles, such
as protein phi (and psi), involve atoms from more than one residue.  Thus,
for example, selection='resname PRO' would not enforce a hypothetical 1D PRO
phi potential on prolines not immediately preceeded by a proline because the
C atom from the pre-proline residue, needed to define phi, is not selected.

The threshold argument is a string (possible values: '98' or '99.95') that
specifies a percentage used to flag torsion angle combinations in the
structure under study with associated energy above that of the given
percentage of residues in the database. Specifying threshold=None can be
used to disable threshold reading.

If verbose is True, some information is printed about the setup process.

Each database file (explicitly or implicitly specified by the database
argument) may specify one or more potential terms, which are packed into a
potList.PotList.  The latter is appended to the returned potList, which
thus consists of a potList of potLists.

----------------------------------------------------------------------------

In addition to specifying the system under study ('protein', 'rna', or
'dna'), which configures a statistical torsion angle potential of the
appropriate kind, the system argument may be set to 'repel14'.  In this
special case, the function returns a repelPot.RepelPot instance (i.e.,
a repulsive-only van der Waals-like potential) involving atoms of the type
of A and D, given by:

    A---B---C---D

where dashes specify covalent bonds, and the torsion angle defined around
the B---C bond is not already affected by a statistical torsion angle
potential returned by this function (i.e., by using 'protein', 'rna', or
'dna' system values).

define_cispro_impropers(psfstring, prePRO_residues): Return a list with improper definitions for each PRO assuming
cis peptide.

The specific molecular system is specified via a string with the
contents of a PSF file (psfstring).  prePRO_residues is a list of
(segment id, residue number) tuples (string, int types) indicating
the preproline residues in the system.

For each proline in the input system a list is made of the form (all such
lists are packed into a list and returned):

[(segid, resid), improper1, improper2, improper3]

where segid (string) and resid (int) specify the segment ID and the residue
number, respectively, and improperk (k = 1, 2, 3) defines a unique improper
that the residue would have if it were in the cis conformation.  The
definition of impropers is done in terms of atom IDs (see docstring of
get_impropers function for more details).  For example,

improper1 = [-C, -CA, +N, +CA]

where "+" indicates the proline and "-" the residue preceeding it (e.g.,
"+CA" is the ID of the CA of the proline.  The impropers are those "added"
by the CIPP patch in file protein.top.

del_resid_from_metasel(metaselection, word=''): Return a proper XPLOR selection string.

Remove the 'resid word' specification from the input metaselection so that
the remaining, returned string is a proper XPLOR selection string.

find_minima(sequence, resid=2, cispeptide=[], database=[], system='protein', exclude='omega', npoint=30, tolerance=1.0, flag=0, nmin=3, numSteps=500, dEPred=0.001, printInterval=0): Return a list with (energy, minimum) tuples sorted by energy value.

Each tuple in the returned list contains the energy value of a local minimum
and a cdsVector.CDSVector_double with the corresponding coordinates in
torsion angle space.  The sequence argument is a string with the residue
sequence (e.g., 'GLY ALA GLY'), and resid is a residue number in it.  Cis
peptide bonds can be specified by via cispeptide, a sequence of one or more
residue numbers (int), each indicating the residue N-terminal to the cis
peptide bond; here a blank segment ID (segid) is assumed (if non-blank
segids are required, the elements of cispeptide may consist of (resiue#,
segid) pairs, segid a string).

The minima are found by minimization of all torsion angles in resid,
subjected to the torsion angle database potential specified by the database
and system arguments (see create_TorsionDBPot function for their
description).  exclude is either a string with a torsion name or a list of
such names (for all applicable names see torsionDBTools module); the
associated torsion angles are assumed to have no effect on the overall
energy, and are thus disregarded.  Several minimizations are performed,
starting from torsion coordinates in a grid; the number of points in each
dimension are specified by the npoint argument.  Two multidimensional
torsion angle points, minimum1 and minimum2, are considered to represent
different minima if the short angle between them is greater than tolerance;
if such angle is between tolerance and the flag argument, one of the torsion
angle points is flagged in the returned list as follows:

(energy1, minimum1, [minimum2, small-angle]).

The above is only done if flag!=0.  nmin is the number of consecutive
minimizations to perform from a given starting point; the rest of the
arguments are those described in function protocol.initMinimize.

find_minima_parallel(sequence, resid=2, cispeptide=[], database=[], system='protein', exclude='omega', npoint=30, tolerance=1.0, flag=0, nmin=3, numSteps=500, dEPred=0.001, printInterval=0): Return a list with (energy, minimum) tuples sorted by energy value.

(Note: this function is the same as find_minima, except that it has to be
run in parallel.)

Each tuple in the returned list contains the energy value of a local minimum
and a cdsVector.CDSVector_double with the corresponding coordinates in
torsion angle space.  The sequence argument is a string with the residue
sequence (e.g., 'GLY ALA GLY'), and resid is a residue number in it.  Cis
peptide bonds can be specified by via cispeptide, a sequence of one or more
residue numbers (int), each indicating the residue N-terminal to the cis
peptide bond; here a blank segment ID (segid) is assumed (if non-blank
segids are required, the elements of cispeptide may consist of (resiue#,
segid) pairs, segid a string).

The minima are found by minimization of all torsion angles in resid,
subjected to the torsion angle database potential specified by the database
and system arguments (see create_TorsionDBPot function for their
description).  exclude is either a string with a torsion name or a list of
such names (for all applicable names see torsionDBTools module); the
associated torsion angles are assumed to have no effect on the overall
energy, and are thus disregarded.  Several minimizations are performed,
starting from torsion coordinates in a grid; the number of points in each
dimension are specified by the npoint argument.  Two multidimensional
torsion angle points, minimum1 and minimum2, are considered to represent
different minima if the short angle between them is greater than tolerance;
if such angle is between tolerance and the flag argument, one of the torsion
angle points is flagged in the returned list as follows:

(energy1, minimum1, [minimum2, small-angle]).

The above is only done if flag!=0.  nmin is the number of consecutive
minimizations to perform from a given starting point; the rest of the
arguments are those described in function protocol.initMinimize.

get_cispro_residues(prePRO_residues, simulation): Return a list with (segid, resid) for cis prolines.

segid and resid are the segment id (string) and the residue number (int),
respectively, of a cis proline in the currently loaded coordinates.
Input prePRO_residues is a list similar to the returned one, except that it
corresponds to the preproline residues. If no cis prolines are found an
empty list is returned.

get_impropers(psfstring): Return a list with lists of impropers from the input PSF file.

The PSF file is input as the string psfstring. Each improper in the
returned list is a list with the four atom IDs which define the improper.
Each ID is a string with the ID number given in the PSF file.

get_torsions(sim): Populate the global torsions list with all torsion angles in the PSF.

A torsion angle is denoted by a tuple (idy, idz), where idy and idz are the
indices of two atoms bonded to each other via the bond around which the
torsion is defined.

As a side effect, the global neighbors dictionary is populated, which
contains idi:[idj, ..., idn] key:value pairs, where idx is the index of atom
x, and the listed indices represent atoms covalently bound to idi (i.e.,
idi's "neighbors"). All atoms in the PSF appear as keys.

getdbfilepath(system, database='default', ext='.dat'): Return a list with the path(s) to database file(s).

database is a string with the name of either a database file or a directory
containing one or more database files.  Alternatively, a sequence with
several such names can be provided as the database argument.  The system is
that to which the database applies to (e.g., 'protein'), and is specified by
the system argument; its possible values can be found as follows:

    import torsionDBPotTools
    print( torsionDBPotTools.getsystems() )  # prints valid systems

If database is not provided, a list with the path(s) of default database
file(s) for the system is returned.

The path of a name (file or directory name) in database is established by
first searching for the name in the working directory, and then in a system-
specific location within the Xplor-NIH directory; such location can be found
as follows:

    print( torsionDBPotTools.getdblocation('protein') ) # prints location
                                                  # of protein databases in
                                                  # Xplor-NIH directory

If the searched name is that of a file, its path is appended to the returned
list.  If the searched name is that of a directory, the paths of all files
within such directory are appended to the returned list, as long as their
file extensions are that of the ext argument.

getdblocation(system)

getsystems()

metasels_atoms_offsets(metaselections, sim): For each metaselection in metaselections, generically written
'sel and resid _RESID+/-X', return (atomSel.AtomSel(sel, sim), +/-X).

metasels_central_residue_selstring(metaselections): Find first metaselection in metaselections that is of the kind
'sel and resid _RESID', and return sel.

setup_pot(name, data, selection, verbose): Return potList.PotList with instances of N-dimensional
torsionInterpolPot.TorsionInterpolPotND potential terms.

The name argument (a string) is the name given to the returned
potList.PotList.  data is a sequence of PotData instances with the
information required to create and set up the terms.  The selection argument
is an atomSel.AtomSel instance specifying the atoms subjected to the
terms.  If verbose is True, some information is printed about the setup
process.

As a side effect, each torsion angle affected by the terms is removed from
the global torsions list.

Data
		databases = {'dna': '/home/schwitrs/xplor/databases/torsions/dna', 'protein': '/home/schwitrs/xplor/databases/torsions/protein', 'rna': '/home/schwitrs/xplor/databases/torsions/rna'} neighbors = {} torsions = []