| rdcPot |
index |
residual dipolar coupling potential
One normally creates RDCPot objects using the create_RDCPot function within
the rdcPotTools module.
constructor:
RDCPot1(instanceName,
oTensor
restraints,
simulation)
instanceName is a user-specified identifier. oTensor specifies an
orientational varTensor.VarTensor object. restraints is an optional
XPLOR-style sani or dipo restraint table. simulation is an optional
simulation.Simulation specification.
This potential term is described in G.M. Clore and C.D. Schwieters,
J. Am. Chem. Soc. 126, 2923-2938 (2004).
members:
oTensor - the VarTensor orientational tensor object.
methods:
addRestraints(restraintList,,
warnOnEmpty=False,
selectionFilter="") -add the specified XPLOR sani- or
dipo-style restraints. Note that
this is a string, and not a
filename. If the optional warnOnEmpty
argument is True, the warning given
for an empty restraintList will
be suppressed. selectionFilter is
an optional additional selection
string which can be used to specify
that restraints apply to only a
subset of the atoms matched by the
strings in the ASSIgnment statements
in the restraintList.
removeRestraint(num) - remove the specified restraint. Restraints
are numbered from zero. Note that
after a restraint is removed, all
restraints with larger indices will be
renumbered.
calcEnergy() - calc energy, returns the energy value.
calcEnergyAndDerivs(derivs) - calc energy, derivs, returns the energy value.
rms() - return the rms of the restriants' diff() values.
deviation() - return average of deviation of ensemble members
numRestraints() - return the number of restraints defined for this term.
violations() - return number of violations
info() - current info about the state of this instance
showViolations() - return a string listing violated restraints.
showRestraints(violated) - return info on restraints. Argument violated is
boolean specifying whether to return only
violated restraints.
restraints() - return the list of restraints. See the description of the
Restraint class below. Restraint properties can thus be
modified.
rawRestraints() - return a list of restraints, without calling calcEnergy
to update calculated values. See the description of the
Restraint class below.
simulation() - return the associated simulation.Simulation.
setLocalTensors(list) - Specify atoms to use to define a local reference
frame used to specify the alignment tensor. The
list is a sequence of tuples containing three atoms,
the first of which must appear in the first selection
of one or more restraints' selPairs. If one is
specified, then all atoms in all first selections of
all restraints must be present in list. If the
specified atoms of a tuple are A,B,C, which
positions qA,qB,qC, then the local frame for the
alignment tensor of all interactions involving
atom A is given by the rotation matrix RA
/ \
RA = | c1 , c2 , c3 |
\ /
where c1, c2, c3 are the column vectors:
c1 = unitVec(qBA X (qBA X qCA))
c2 = unitVec(qBA)
c3 = unitVec(qBA X qCA)
with qBA=qB-qA and X denoting cross product.
The principal components of the alignment tensor
associated with center A become
ux -> RA ux
uy -> RA uy
uz -> RA uz
This local tensor representation is appropriate for
pseudo-contact shifts caused by one or more
paramagnetic tags attached to a molecule of interest.
getLocalTensors() - return a dictionary of LocalTensors indexed by the atom
index of center atoms. See below for a description of
the contents of a LocalTensor
ensWeight(index) - return the ensemble weight associated with the
specified member.
The following parameters can be set [defaults in square brackets]
allowBadRestraints - By default, restraint definitions given to
addRestraints which select no atoms cause an
exception to be raised. If this flag is set to
True, only a warning message will be written. [False]
deltaDFS - constant offset in dipolar couplings [0]
verbose - if true, sporadically spit out info [False]
useDistance- if True, include the 1/r^3 dependence in the calcedShift
calculation. Note that this feature changes the meaning
and units of Da [False].
useSign - default value for useSign of each restraint (see restraint
description below) [True]. When set with setUseSign(), the
default value, and values of all restraints are set.
gyroA
gyroB - linear scaling factors for the calculated dipolar coupling.
scale - energy scale factor (force constant) [1]
threshold - threshold in violation calculation [0]
potType - type of potential: "harmonic" or "square" ["harmonic"]
aveType - type of averaging to use for indistinguishable atoms:
"sum" , "average" , or "pairwise". Pairwise is appropriate for
symmetric multimers for which the segid is not specified in
the restraint atom selection. ["sum"]
showAllRestraints - boolean which changes the behavior of showViolations. If
this parameter is set to True, the behavior of
showViolations is modified such that all restraints are
printed. Violated restraints are indicated by an
asterisk in the first column. [0]
useLocalTensor - whether or not to use the local tensor interpretation of
of the alignment tensor. It is set to True if
setLocalTensors() is called with non-null argument.
Otherwise, it is False.
useSimEnsWeight - whether to use the ensemble wieghts set with setEnsWeights
or to use those of the underlying EnsembleSimulation.
ensWeights - a sequence of ensemble weights to use when calculating
the ensemble- averaged value of each dipolar coupling. By
default, the weights of the underlying EnsembleSimulation
are used. If these are overridden by calling the
setEnsWeights method, and useSimEnsWeight is set to False.
use the specified ensemble weights instead of those
in the underlying EnsembleSimulation.
setEnsWeights(vals) - use the specified ensemble weights instead of those
in the underlying EnsembleSimulation.
the above quantities may be retrieved using the member function form
quantity(), while they are set using the form setQuantity(value).
assignment table:
entries in the restraint list have the following form
assign ( sel OO ) ( sel Z ) ( sel X ) ( sel Y )
( sel m ) ( sel n ) obsShift error1 [error2]
[or ( sel m1 ) ( sel n1) ...]
where the first four selections are present for compatibility with
XPLOR assignment tables- they can be any string with properly nested
parentheses. The m and n selections specify the atoms involved in
the interaction. The observed dipolar shift is given by the obsShift
argument, and the error bounds are given by error1 and error2. If
error2 is absent, it defaults to error1. One or more optional OR
statements can be used to add additional pairs of atom
selections. For instance, is residue 4 is a phenylalanine, the
following assign..or statement will correctly allow averaging of the
CE1-HE1 CE2-HE2 contributions:
assign ( resid 500 and name OO )
( resid 500 and name Z )
( resid 500 and name X )
( resid 500 and name Y )
( resid 4 and name CE1 )
( resid 4 and name HE1 ) -4.62 4.62 0.1000
or ( resid 4 and name CE2 )
( resid 4 and name HE2 )
[ If a single pair of wildcard atom selections is used, four
contributions are computed. For these cases, the RDCPot assignment
statement is not compatible with XPLOR DIPO ASSIgnment
statements. ]
The dipolar shift is given by the equation
calcedShift = DFS + Da (3 vz^2 -1) + 3/2 Da*R ( vx^2 - vy^2 )
where R is the rhombic tensor component, and vx,vy,vz are the
projections of the unit vector in the direction mn onto the
corresponding coordinate axis representing tensor orientation. Da is scaled
by gyroA and gyroB. Typically, these are set to one, or are set to scale
factors such that a single Da value can be used with experiments
involving different nuclei. These scale factors are usually set
using the helper function rdcPotTools.scale_toNH.
If useDistance is True, the Da is scaled by 1 / |q_m - q_n|^3. Note that
this changes the units of Da. This feature is frequently used in
proton-proton experiments. If the Da is fixed, one will need an
additional experiment to obtain a value for Da, and the value scaled
appropriately. For example, if Da(NH) is available from a 15N-1H
experiment in the same medium, the H-H Da would be set as Da(NH) *
r(NH)^3 * gamma(N) gamma(N) = 10.47*Da(NH), where r(NH) is the NH
bond distance, and gamma(N) and gamma(H) are the gyromagnetic ratio
of 15N and 1H, respectively.
The energy function is defined as
1/2 * scale * (calcedShift - effShift)^2 [for useSign==True]
or
1/2 * scale * (|calcedShift| - |effShift|)^2 [for useSign==False]
where for potType=harmonic, effShift = obsShift. For potType=square,
effShift = calcedShift, if
obsShift-error1 < calcedShift < obsShift+error2
= calcedShift+error1, if calcedShift < obsShift-error1
= calcedShift-error2, if calcedShift > obsShift+error2
Restraint class
methods:
energy() - energy due to this restraint
calcd() - calculated value of dipolar coupling (ensemble average).
obs() - observed value of dipolar coupling.
diff() - difference between calcd and obs, adjusted for the useSign setting.
For square and linearsquare potential types, the plus/minus
bounds are subtracted (so that restraints with zero energy have
zero diff).
plusErr(), minusErr() - bounds for the square well potential
setObs(val) - set the observed value.
setErr(val) - set both plus and minus errors to the given value.
selPairs() - pairs of atom selections. Each pair is an object with
atomSel.AtomSel members named a and b,
corresponding to the first and second selections in the
ASSIgn or OR statements
comment() - return the (optional) comment string supplied in the
assignment table.
selectionFilter() - return the (optional) selectrionFilter string
specified in addRestraints()
scale(), setScale() - get, set per-restraint energy scale factor
(force constant) [1]
aSelection() - deprecated - synonym for selPairs()[0].a
bSelection() - deprecated - synonym for selPairs()[0].b
calced_contrib() - list of contributions due to each ensemble member.
deviation() - measure of spread between different ensemble members
useSign() - if false, ignore the sign of the calculated and observed
dipolar coupling; this if the sign of the shift is
unknown [True]. Set this using the setUseSign accessor.
aveSize(mem=-1) - return the number of atom pairs averaged over in
ambiguous assignments. The optional mem argument
specifies which ensemble member to report on.
LocalTensor class
atom1, atom2, atom3 - atoms A, B and C as speicified above in the
documentation of setLocalTensors.
uMat - the current definition of the rotation matrix RA.
U - a sequence of the local values of the alignment tensor
principal components: ux, uy, uz.
# This file was automatically generated by SWIG (http://www.swig.org).
# Version 4.0.2
#
# Do not make changes to this file unless you know what you are doing--modify
# the SWIG interface file instead.
| Classes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Functions | ||
| ||