

\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.copy} \label{uf: align_tensor.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} alignment tensor data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]copy}(\linebreak[0]tensor\_from=\linebreak[0]None, pipe\_from=\linebreak[0]None, tensor\_to=\linebreak[0]None, pipe\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{tensor\_from:}  The identification string of the alignment tensor to copy\index{copy} the data from.

\hspace{3 mm}\keyword{pipe\_from:}  The name of the data pipe to copy\index{copy} the alignment tensor data from.

\hspace{3 mm}\keyword{tensor\_to:}  The identification string of the alignment tensor to copy\index{copy} the data to.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the data pipe to copy\index{copy} the alignment tensor data to.


\subsubsection{Description}

This will copy\index{copy} the alignment tensor data to a new tensor or a new data pipe.  The destination data pipe must not contain any alignment tensor data corresponding to the tensor\_to label.  If the source or destination data pipes are not supplied, then both will default to the current data pipe.  Both the source and destination tensor IDs must be supplied.

\subsubsection{Prompt examples}

To copy\index{copy} the alignment tensor data corresponding to \quotecmd{Pf1} from the data pipe \quotecmd{old} to the current data pipe, type one of:

\begin{lstlisting}[numbers=none]
relax> align_tensor.copy('Pf1', 'old')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> align_tensor.copy(tensor_from='Pf1', pipe_from='old')
\end{lstlisting}


To copy\index{copy} the alignment tensor data corresponding to \quotecmd{Otting} from the current data pipe to the data pipe new, type one of:

\begin{lstlisting}[numbers=none]
relax> align_tensor.copy('Otting', pipe_to='new')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> align_tensor.copy(tensor_from='Otting', pipe_to='new')
\end{lstlisting}


To copy\index{copy} the alignment tensor data of \quotecmd{Otting} to that of \quotecmd{Otting new}, type one of:

\begin{lstlisting}[numbers=none]
relax> align_tensor.copy('Otting', tensor_to='Otting new')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> align_tensor.copy(tensor_from='Pf1', tensor_to='Otting new')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.delete} \label{uf: align_tensor.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} alignment tensor data from the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]delete}(\linebreak[0]tensor=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{tensor:}  The alignment tensor identification string.


\subsubsection{Description}

This will delete\index{delete} the specified alignment tensor data from the current data pipe.  If no tensor is specified, all tensors will be deleted.\index{delete}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.display} \label{uf: align_tensor.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the alignment tensor information in full detail.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]display}(\linebreak[0]tensor=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{tensor:}  The alignment tensor identification string.


\subsubsection{Description}

This will show all information relating to the alignment tensor, including the different tensor forms:

\begin{itemize}
  \item[]Probability tensor.
  \item[]Saupe order matrix.
  \item[]Alignment tensor.
  \item[]Magnetic susceptibility tensor.
\end{itemize}

All possible tensor parameters and information will also be shown (Eigensystem, GDO, Aa, Ar, $\mathfrak{R}$, eta, chi\_ax, chi\_rh, etc).  The printout will be extensive.

If no tensor is specified, all tensors will be displayed.\index{display}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.fix} \label{uf: align_tensor.fix}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/status/object-locked}

\subsubsection{Synopsis}

Fix all alignment tensors so that they do not change during optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]fix}(\linebreak[0]id=\linebreak[0]None, fixed=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{id:}  The alignment tensor identification string.

\hspace{3 mm}\keyword{fixed:}  The flag specifying if the tensors should be fixed or variable.


\subsubsection{Description}

If the ID string is left unset, then all alignment tensors will be fixed.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.init} \label{uf: align_tensor.init}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor}

\subsubsection{Synopsis}

Initialise an alignment tensor.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]init}(\linebreak[0]tensor=\linebreak[0]None, align\_id=\linebreak[0]None, domain=\linebreak[0]None, params=\linebreak[0]None, scale=\linebreak[0]1.0, angle\_units=\linebreak[0]`deg', param\_types=\linebreak[0]2, errors=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{tensor:}  The optional alignment tensor ID string, required if multiple tensors exist per alignment.

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string that the tensor corresponds to.

\hspace{3 mm}\keyword{domain:}  The optional domain ID string that the tensor corresponds to.

\hspace{3 mm}\keyword{params:}  The alignment tensor data.

\hspace{3 mm}\keyword{scale:}  The alignment tensor eigenvalue\index{eigenvalues} scaling value.

\hspace{3 mm}\keyword{angle\_units:}  The units for the angle\index{angles} parameters.

\hspace{3 mm}\keyword{param\_types:}  A flag to select different parameter combinations.

\hspace{3 mm}\keyword{errors:}  A flag which determines if the alignment tensor data or its errors are being input.


\subsubsection{Description}

The tensor ID is only required if there are multiple unique tensors per alignment.  An example is if internal domain motions cause multiple parts of the molecule\index{molecule} to align differently.  The tensor ID is optional and in the case of only a single tensor per alignment, the tensor can be identified using the alignment ID instead.

The alignment tensor parameters should be a tuple of floating\index{floating point number} point numbers (a list surrounded by round brakets).  These correspond to the parameters of the tensor which can be specified by the parameter types whereby the values correspond to:

\begin{description}
  \item[0 --] \{Sxx, Syy, Sxy, Sxz, Syz\}  (unitless),
  \item[1 --] \{Szz, Sxx-yy, Sxy, Sxz, Syz\}  (Pales default format),
  \item[2 --] \{Axx, Ayy, Axy, Axz, Ayz\}  (unitless),
  \item[3 --] \{Azz, Axx-yy, Axy, Axz, Ayz\}  (unitless),
  \item[4 --] \{Axx, Ayy, Axy, Axz, Ayz\}  (units of Hertz),
  \item[5 --] \{Azz, Axx-yy, Axy, Axz, Ayz\}  (units of Hertz),
  \item[6 --] \{Pxx, Pyy, Pxy, Pxz, Pyz\}  (unitless),
  \item[7 --] \{Pzz, Pxx-yy, Pxy, Pxz, Pyz\}  (unitless).
\end{description}

Other formats may be added later.  The relationship between the Saupe order matrix S and the alignment tensor A is

\begin{itemize}
  \item[]S = 3/2 A.
\end{itemize}

The probability matrix P is related to the alignment tensor A by

\begin{itemize}
  \item[]A = P - 1/3 I,
\end{itemize}

where I is the identity matrix.  For the alignment tensor to be supplied in Hertz, the bond vectors must all be of equal length.

\subsubsection{Prompt examples}

To set a rhombic tensor for the domain labelled \quotecmd{domain 1} with the alignment named \quotecmd{super media}, type one of:

\begin{lstlisting}[numbers=none]
relax> align_tensor.init('domain 1', 'super media', (-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=1)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> align_tensor.init(tensor='domain 1', align_id='super media', params=(-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=1)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.matrix\-\_angles} \label{uf: align_tensor.matrix_angles}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the angles\index{angles} between all alignment tensors.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]matrix\_angles}(\linebreak[0]basis\_set=\linebreak[0]`matrix', tensors=\linebreak[0]None, angle\_units=\linebreak[0]`deg', precision=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{basis\_set:}  The basis set to operate with.

\hspace{3 mm}\keyword{tensors:}  A list of the tensors to apply the calculation to.  If None, all tensors are used.

\hspace{3 mm}\keyword{angle\_units:}  The units for the angle\index{angles} parameters, either \quotecmd{deg} or \quotecmd{rad}.

\hspace{3 mm}\keyword{precision:}  The precision of the printed out angles.\index{angles}  The number corresponds to the number of figures to print after the decimal point.


\subsubsection{Description}

This will calculate the inter-matrix angles\index{angles} between all loaded alignment tensors for the current data pipe.  For the vector basis sets, the matrices are first mapped\index{map} to vector form and then then the inter-vector angles\index{angles} rather than inter-matrix angles\index{angles} are calculated.  The angles\index{angles} are dependent upon the basis set - linear maps\index{map} produce identical results whereas non-linear maps\index{map} result in different angles.\index{angles}  The basis set can be one of:

\begin{description}
  \item[\quotecmd{matrix} --] The standard inter-matrix angles.\index{angles}  This default option is a linear map,\index{map} hence angles\index{angles} are preserved.  The angle\index{angles} is calculated via the arccos of the Euclidean inner product of the alignment matrices in rank-2, 3D form divided by the Frobenius norm ||A||\_F of the matrices.
  \item[\quotecmd{irreducible 5D} --] The inter-tensor vector angles\index{angles} for the irreducible spherical tensor 5D basis set \{A-2, A-1, A0, A1, A2\}.  This is a linear map,\index{map} hence angles\index{angles} are preserved.  These are the spherical harmonic decomposition coefficients.
  \item[\quotecmd{unitary 9D} --] The inter-tensor vector angles\index{angles} for the unitary 9D basis set \{Sxx, Sxy, Sxz, Syx, Syy, Syz, Szx, Szy, Szz\}.  This is a linear map,\index{map} hence angles\index{angles} are preserved.
  \item[\quotecmd{unitary 5D} --] The inter-tensor vector angles\index{angles} for the unitary 5D basis set \{Sxx, Syy, Sxy, Sxz, Syz\}.  This is a non-linear map,\index{map} hence angles\index{angles} are not preserved.
  \item[\quotecmd{geometric 5D} --] The inter-tensor vector angles\index{angles} for the geometric 5D basis set \{Szz, Sxxyy, Sxy, Sxz, Syz\}.  This is a non-linear map,\index{map} hence angles\index{angles} are not preserved.  This is also the Pales standard notation.
\end{description}

The full matrix angle\index{angles} via the Euclidean inner product is defined as

{\footnotesize \begin{verbatim}
                   /   <A1 , A2>   \ 
    theta = arccos | ------------- | ,
                   \ ||A1||.||A2|| / 
\end{verbatim}}

where <a,b> is the Euclidean inner product and ||a|| is the Frobenius norm of the matrix.  For the irreducible spherical tensor 5D basis set, the Am components are defined as

{\footnotesize \begin{verbatim}
            / 4pi \ 1/2
       A0 = | --- |     Szz ,
            \  5  /

                / 8pi \ 1/2
    A+/-1 = +/- | --- |     (Sxz +/- iSyz) ,
                \ 15  /

            / 2pi \ 1/2
    A+/-2 = | --- |     (Sxx - Syy +/- 2iSxy) ,
            \ 15  / 
\end{verbatim}}

and, for this complex notation, the angle\index{angles} is

{\footnotesize \begin{verbatim}
                   / Re(<A1|A2>) \ 
    theta = arccos | ----------- | ,
                   \  |A1|.|A2|  / 
\end{verbatim}}

where the inner product is defined as

{\footnotesize \begin{verbatim}
               ___
               \      1    2*
    <A1|A2> =   >   Am . Am   ,
               /__
              m=-2,2 
\end{verbatim}}

and where Am* = (-1)\^{}m A-m, and the norm is defined as |A1| = Re(sqrt(<A1|A1>)).  For all other basis sets whereby the map\index{map} is real matrix -> real vector, the inter-tensor angle\index{angles} is defined as

{\footnotesize \begin{verbatim}
                   /  <A1|A2>  \ 
    theta = arccos | --------- | ,
                   \ |A1|.|A2| / 
\end{verbatim}}

where the inner product <A1|A2> is simply the vector dot product and |A1| is the vector length.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.reduction} \label{uf: align_tensor.reduction}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill 

\subsubsection{Synopsis}

Specify that one tensor is a reduction of another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]reduction}(\linebreak[0]full\_tensor=\linebreak[0]None, red\_tensor=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{full\_tensor:}  The full alignment tensor.

\hspace{3 mm}\keyword{red\_tensor:}  The reduced alignment tensor.


\subsubsection{Description}

Prior to optimisation of the N-state model and Frame Order theories using alignment tensors, which tensor is a reduction of which other tensor must be specified through this user function.

\subsubsection{Prompt examples}

To state that the alignment tensor loaded as \quotecmd{chi3 C-dom} is a reduction of \quotecmd{chi3 N-dom}, type:

\begin{lstlisting}[numbers=none]
relax> align_tensor.reduction(full_tensor='chi3 N-dom', red_tensor='chi3 C-dom')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.set\-\_domain} \label{uf: align_tensor.set_domain}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-select}

\subsubsection{Synopsis}

Set the domain label for the alignment tensor.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]set\_domain}(\linebreak[0]tensor=\linebreak[0]None, domain=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{tensor:}  The alignment tensor to assign the domain label to.

\hspace{3 mm}\keyword{domain:}  The domain label.


\subsubsection{Description}

Prior to optimisation of the N-state model or Frame Order theories, the domain to which each alignment tensor belongs must be specified.

\subsubsection{Prompt examples}

To link the alignment tensor loaded as \quotecmd{chi3 C-dom} to the C-terminal domain \quotecmd{C}, type:

\begin{lstlisting}[numbers=none]
relax> align_tensor.set_domain(tensor='chi3 C-dom', domain='C')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{align\-\_tensor\-.svd} \label{uf: align_tensor.svd}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the singular values and condition number for all alignment tensors.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{align\_tensor.\linebreak[0]svd}(\linebreak[0]basis\_set=\linebreak[0]`irreducible 5D', tensors=\linebreak[0]None, precision=\linebreak[0]4)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{basis\_set:}  The basis set to operate with.

\hspace{3 mm}\keyword{tensors:}  A list of the tensors to apply the calculation to.  If None, all tensors are used.

\hspace{3 mm}\keyword{precision:}  The precision of the printed out singular values and condition numbers.  The number corresponds to the number of figures to print after the decimal point.


\subsubsection{Description}

This will perform a singular value decomposition for all alignment tensors and calculate the condition number.  The singular values and condition number are dependent on the basis set - linear maps\index{map} produce identical results whereas non-linear maps\index{map} result in different values.  The basis set can be one of:

\begin{description}
  \item[\quotecmd{irreducible 5D} --] The irreducible spherical tensor 5D basis set \{A-2, A-1, A0, A1, A2\}.  This is a linear map,\index{map} hence angles,\index{angles} singular values, and condition number are preserved.  These are the spherical harmonic decomposition coefficients.
  \item[\quotecmd{unitary 9D} --] The unitary 9D basis set \{Sxx, Sxy, Sxz, Syx, Syy, Syz, Szx, Szy, Szz\}.  This is a linear map,\index{map} hence angles,\index{angles} singular values, and condition number are preserved.
  \item[\quotecmd{unitary 5D} --] The unitary 5D basis set \{Sxx, Syy, Sxy, Sxz, Syz\}.  This is a non-linear map,\index{map} hence angles,\index{angles} singular values, and condition number are not preserved.
  \item[\quotecmd{geometric 5D} --] The geometric 5D basis set \{Szz, Sxxyy, Sxy, Sxz, Syz\}.  This is a non-linear map,\index{map} hence angles,\index{angles} singular values, and condition number are not preserved.  This is also the Pales standard notation.
\end{description}

If the selected basis set is the default of \quotecmd{irreducible 5D}, the matrix on which SVD will be performed will be:

{\footnotesize \begin{verbatim}
    | A-2(1) A-1(1) A0(1)  A1(1)  A2(1) |
    | A-2(2) A-1(2) A0(2)  A1(2)  A2(2) |
    | A-2(3) A-1(3) A0(3)  A1(3)  A2(3) |
    |   .      .     .      .      .    |
    |   .      .     .      .      .    |
    |   .      .     .      .      .    |
    | A-2(N) A-1(N) A0(N)  A1(N)  A2(N) |
\end{verbatim}}

If the selected basis set is \quotecmd{unitary 9D}, the matrix on which SVD will be performed will be:

{\footnotesize \begin{verbatim}
    | Sxx1 Sxy1 Sxz1 Syx1 Syy1 Syz1 Szx1 Szy1 Szz1 |
    | Sxx2 Sxy2 Sxz2 Syx2 Syy2 Syz2 Szx2 Szy2 Szz2 |
    | Sxx3 Sxy3 Sxz3 Syx3 Syy3 Syz3 Szx3 Szy3 Szz3 |
    |  .    .    .    .    .    .    .    .    .   |
    |  .    .    .    .    .    .    .    .    .   |
    |  .    .    .    .    .    .    .    .    .   |
    | SxxN SxyN SxzN SyxN SyyN SyzN SzxN SzyN SzzN |
\end{verbatim}}

Otherwise if the selected basis set is \quotecmd{unitary 5D}, the matrix for SVD is:

{\footnotesize \begin{verbatim}
    | Sxx1 Syy1 Sxy1 Sxz1 Syz1 |
    | Sxx2 Syy2 Sxy2 Sxz2 Syz2 |
    | Sxx3 Syy3 Sxy3 Sxz3 Syz3 |
    |  .    .    .    .    .   |
    |  .    .    .    .    .   |
    |  .    .    .    .    .   |
    | SxxN SyyN SxyN SxzN SyzN |
\end{verbatim}}

Or if the selected basis set is \quotecmd{geometric 5D}, the stretching and skewing parameters Szz and Sxx-yy will be used instead and the matrix is:

{\footnotesize \begin{verbatim}
    | Szz1 Sxxyy1 Sxy1 Sxz1 Syz1 |
    | Szz2 Sxxyy2 Sxy2 Sxz2 Syz2 |
    | Szz3 Sxxyy3 Sxy3 Sxz3 Syz3 |
    |  .     .     .    .    .   |
    |  .     .     .    .    .   |
    |  .     .     .    .    .   |
    | SzzN SxxyyN SxyN SxzN SyzN |
\end{verbatim}}

For the irreducible spherical tensor basis set, the Am components are defined as

{\footnotesize \begin{verbatim}
            / 4pi \ 1/2
       A0 = | --- |     Szz ,
            \  5  /

                / 8pi \ 1/2
    A+/-1 = +/- | --- |     (Sxz +/- iSyz) ,
                \ 15  /

            / 2pi \ 1/2
    A+/-2 = | --- |     (Sxx - Syy +/- 2iSxy) .
            \ 15  / 
\end{verbatim}}

The relationships between the geometric and unitary basis sets are

{\footnotesize \begin{verbatim}
    Szz = - Sxx - Syy,
    Sxxyy = Sxx - Syy.
\end{verbatim}}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{angles\-.diff\-\_frame\index{angles|textbf}} \label{uf: angles.diff_frame}
\hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the angles\index{angles} defining the XH bond vector within the diffusion frame.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{angles.\linebreak[0]diff\_frame}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

If the diffusion\index{diffusion!tensor} tensor is isotropic,\index{diffusion!sphere (isotropic)} then nothing will be done.

If the diffusion\index{diffusion!tensor} tensor is axially\index{diffusion!spheroid (axially symmetric)} symmetric, then the angle\index{angles} $\alpha$ will be calculated for each XH bond vector.

If the diffusion\index{diffusion!tensor} tensor is asymmetric,\index{diffusion!ellipsoid (asymmetric)} then the three angles\index{angles} will be calculated.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.citation} \label{uf: bmrb.citation}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/documentation}

\subsubsection{Synopsis}

Specify a citation to be added the BMRB data file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]citation}(\linebreak[0]cite\_id=\linebreak[0]None, authors=\linebreak[0]None, doi=\linebreak[0]None, pubmed\_id=\linebreak[0]None, full\_citation=\linebreak[0]None, title=\linebreak[0]None, status=\linebreak[0]`published', type=\linebreak[0]`journal', journal\_abbrev=\linebreak[0]None, journal\_full=\linebreak[0]None, volume=\linebreak[0]None, issue=\linebreak[0]None, page\_first=\linebreak[0]None, page\_last=\linebreak[0]None, year=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{cite\_id:}  The citation ID string.

\hspace{3 mm}\keyword{authors:}  The list of authors.  Each author element is a list of four elements (the first name, last name, first initial, and middle initials).

\hspace{3 mm}\keyword{doi:}  The DOI number, e.g. \quotecmd{10.1000/182}.

\hspace{3 mm}\keyword{pubmed\_id:}  The identification code assigned to the publication by PubMed.

\hspace{3 mm}\keyword{full\_citation:}  The full citation as given in a reference list.

\hspace{3 mm}\keyword{title:}  The title of the publication.

\hspace{3 mm}\keyword{status:}  The status of the publication.  This can be a value such as \quotecmd{published}, \quotecmd{submitted}, etc.

\hspace{3 mm}\keyword{type:}  The type of publication, for example \quotecmd{journal}.

\hspace{3 mm}\keyword{journal\_abbrev:}  The standard journal abbreviation.

\hspace{3 mm}\keyword{journal\_full:}  The full journal name.

\hspace{3 mm}\keyword{volume:}  The volume number.

\hspace{3 mm}\keyword{issue:}  The issue number.

\hspace{3 mm}\keyword{page\_first:}  The first page number.

\hspace{3 mm}\keyword{page\_last:}  The last page number.

\hspace{3 mm}\keyword{year:}  The publication year.


\subsubsection{Description}

The full\_citation should be in a format similar to that used in a journal article by either cutting and pasting from another document or by typing. Please include author names, title, journal, page numbers, and year or equivalent information for the type of publication given.

The journal status can only be one of:

\begin{itemize}
  \item[]\quotecmd{preparation},
  \item[]\quotecmd{in press},
  \item[]\quotecmd{published},
  \item[]\quotecmd{retracted},
  \item[]\quotecmd{submitted}.
\end{itemize}

The citation type can only be one of:

\begin{itemize}
  \item[]\quotecmd{abstract},
  \item[]\quotecmd{BMRB only},
  \item[]\quotecmd{book},
  \item[]\quotecmd{book chapter},
  \item[]\quotecmd{internet},
  \item[]\quotecmd{journal},
  \item[]\quotecmd{personal communication},
  \item[]\quotecmd{thesis}.
\end{itemize}

The standard journal abbreviation is that defined by the Chemical Abstract Services for the journal where the data are or will be published.  If the data in the deposition are related to a J. Biomol. NMR\index{NMR} paper, the value must be \quotecmd{J. Biomol. NMR}\index{NMR} to alert the BMRB annotators so that the deposition is properly processed.  If the depositor truly does not know the journal, a value of \quotecmd{not known} or \quotecmd{na} is acceptable.

\subsubsection{Prompt examples}

To add the citation "d'Auvergne E. J., Gooley P. $\mathfrak{R}$. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494.", type:

\begin{lstlisting}[numbers=none]
relax> bmrb.citation(authors=[["Edward", "d'Auvergne", "E.", "J."], ["Paul", "Gooley", "P.", "R."]], doi="10.1039/b702202f", pubmed_id="17579774", full_citation="d'Auvergne E. J., Gooley P. R. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494.", title="Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm.", status="published", type="journal", journal_abbrev="Mol. Biosyst.", journal_full="Molecular Biosystems", volume=3, issue=7, page_first=483, page_last=498, year=2007)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.display} \label{uf: bmrb.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the BMRB data in NMR-STAR\index{NMR} format.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]display}(\linebreak[0]version=\linebreak[0]`3.1')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{version:}  The version of the BMRB NMR-STAR\index{NMR} format to display.\index{display}


\subsubsection{Description}

This will print the BMRB NMR-STAR\index{NMR} formatted data to STDOUT.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.read} \label{uf: bmrb.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} BMRB files in the NMR-STAR\index{NMR} format.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, version=\linebreak[0]None, sample\_conditions=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the BMRB NMR-STAR\index{NMR} formatted file to read.\index{read}

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{version:}  The version of the BMRB NMR-STAR\index{NMR} format to read.\index{read}  This is not necessary as the version is normally auto-detected.

\hspace{3 mm}\keyword{sample\_conditions:}  The sample conditions label in the NMR-STAR\index{NMR} file to restrict loading to.


\subsubsection{Description}

This will allow most of the data from a BMRB NMR-STAR\index{NMR} formatted file to be loaded into the relax data store.  Note that an empty data pipe should be created for storing the data, and that currently only model-free data pipes can be used.  Also, only one sample condition can be read\index{read} per relax data pipe.  Therefore if one of the sample conditions is not specified and multiple conditions exist in the NMR-STAR\index{NMR} file, an error will be raised.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.script} \label{uf: bmrb.script}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/mimetypes/application-x-desktop}

\subsubsection{Synopsis}

Specify the scripts\index{scripting!script file} used in the analysis.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]script}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, analysis\_type=\linebreak[0]None, model\_selection=\linebreak[0]None, engine=\linebreak[0]`relax', model\_elim=\linebreak[0]False, universal\_solution=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the script\index{scripting!script file} file.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{analysis\_type:}  The type of analysis performed.

\hspace{3 mm}\keyword{model\_selection:}  The model selection technique used, if relevant.  For example \quotecmd{AIC} model selection.

\hspace{3 mm}\keyword{engine:}  The software engine used in the analysis.

\hspace{3 mm}\keyword{model\_elim:}  A model-free specific flag specifying if model\index{model elimination} elimination\index{model elimination} was performed.

\hspace{3 mm}\keyword{universal\_solution:}  A model-free specific flag specifying if the universal solution was sought after.


\subsubsection{Description}

This user function allows scripts\index{scripting!script file} used in the analysis to be included in the BMRB deposition.  The following addition information may need to be specified with the script.\index{scripting!script file}

The analysis type must be set.  Allowable values include all the data pipe types used in relax, ie:

\begin{description}
  \item[\quotecmd{frame order} --] The Frame Order theories,
  \item[\quotecmd{jw} --] Reduced spectral density mapping,\index{map}
  \item[\quotecmd{mf} --] Model-free analysis,
  \item[\quotecmd{N-state} --] N-state model of domain motions,
  \item[\quotecmd{noe} --] Steady state NOE calculation,
  \item[\quotecmd{relax\_fit} --] Relaxation\index{relaxation} curve fitting,
\end{description}

The model selection technique only needs to be set if the script\index{scripting!script file} selects between different mathematical models.  This can be anything, but the following are recommended:

\begin{description}
  \item[\quotecmd{AIC} --] Akaike's Information Criteria.
  \item[\quotecmd{AICc} --] Small sample size corrected AIC.\index{model selection!AIC}
  \item[\quotecmd{BIC} --] Bayesian or Schwarz Information Criteria.
  \item[\quotecmd{Bootstrap} --] Bootstrap\index{model selection!bootstrap} model selection.
  \item[\quotecmd{CV} --] Single-item-out cross-validation.\index{model selection!cross-validation}
  \item[\quotecmd{Expect} --] The expected overall discrepancy (the true values of the parameters are required).
  \item[\quotecmd{Farrow} --] Old model-free method by Farrow et al., 1994.
  \item[\quotecmd{Palmer} --] Old model-free method by Mandel et al., 1995.
  \item[\quotecmd{Overall} --] The realised overall discrepancy (the true values of the parameters are required).
\end{description}

The engine is the software used in the calculation, optimisation, etc.  This can be anything, but those recognised by relax (automatic program info, citations, etc. added) include:

\begin{description}
  \item[\quotecmd{relax} --] hence relax was used for the full analysis.
  \item[\quotecmd{modelfree4} --] Art Palmer's Modelfree4\index{software!Modelfree}\index{software!Modelfree} program was used for optimising the model-free parameter values.
  \item[\quotecmd{dasha} --] The Dasha\index{software!Dasha}\index{software!Dasha} program was used for optimising the model-free parameter values.
  \item[\quotecmd{curvefit} --] Art Palmer's curvefit program was used to determine the R$_1$ or R$_2$ values.
\end{description}

The model\_elim flag is model-free specific and should be set if the methods from "d'Auvergne, E. J. and Gooley, P. $\mathfrak{R}$. (2006). Model-free model\index{model elimination} elimination:\index{model elimination} A new step in the model-free dynamic analysis of NMR\index{NMR} relaxation\index{relaxation} data. J. Biomol. NMR,\index{NMR} 35(2), 117-135." were used.  This should be set to True for the full\_analysis.py script.\index{scripting!script file}

The universal\_solution flag is model-free specific and should be set if the methods from "d'Auvergne E. J., Gooley P. $\mathfrak{R}$. (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494." were used.  This should be set to True for the full\_analysis.py script.\index{scripting!script file}

\subsubsection{Prompt examples}

For BMRB deposition, to specify that the full\_analysis.py script\index{scripting!script file} was used, type one of:

\begin{lstlisting}[numbers=none]
relax> bmrb.script('full_analysis.py', 'model-free', 'AIC', 'relax', True, True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> bmrb.script(file='full_analysis.py', dir=None, analysis_type='model-free', model_selection='AIC', engine='relax', model_elim=True, universal_solution=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.software} \label{uf: bmrb.software}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/apps/utilities-terminal}

\subsubsection{Synopsis}

Specify the software used in the analysis.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]software}(\linebreak[0]name=\linebreak[0]None, version=\linebreak[0]None, url=\linebreak[0]None, vendor\_name=\linebreak[0]None, cite\_ids=\linebreak[0]None, tasks=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{name:}  The name of the software program utilised.

\hspace{3 mm}\keyword{version:}  The version of the software, if applicable.

\hspace{3 mm}\keyword{url:}  The web address of the software.

\hspace{3 mm}\keyword{vendor\_name:}  The name of the company or person behind the program.

\hspace{3 mm}\keyword{cite\_ids:}  A list of the BMRB citation ID numbers.

\hspace{3 mm}\keyword{tasks:}  A list of all the tasks performed by the software.


\subsubsection{Description}

This user function allows the software used in the analysis to be specified in full detail.

For the tasks list, this should be a python\index{Python} list of strings (e.g. [\quotecmd{spectral processing}]).  Although not restricted to these, the values suggested by the BMRB are:

\begin{itemize}
  \item[]\quotecmd{chemical shift assignment},
  \item[]\quotecmd{chemical shift calculation},
  \item[]\quotecmd{collection},
  \item[]\quotecmd{data analysis},
  \item[]\quotecmd{geometry optimization},
  \item[]\quotecmd{peak picking},
  \item[]\quotecmd{processing},
  \item[]\quotecmd{refinement},
  \item[]\quotecmd{structure solution}
\end{itemize}

\subsubsection{Prompt examples}

For BMRB deposition, to say that Sparky\index{software!Sparky}\index{software!Sparky} was used in the analysis, type:

\begin{lstlisting}[numbers=none]
relax> cite_id = bmrb.citation(authors=[["Tom", "Goddard", "T.", "D."], ["D", "Kneller", "D.", "G."]], title="Goddard, T. D. and Kneller, D. G., SPARKY 3, University of California, San Francisco."
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> bmrb.software("Sparky", version="3.110", url="http://www.cgl.ucsf.edu/home/sparky/", vendor_name="Goddard, T. D.", cite_ids=[cite_id], tasks=["spectral analysis"])
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.software\-\_select} \label{uf: bmrb.software_select}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/apps/utilities-terminal}

\subsubsection{Synopsis}

Select the software used in the analysis.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]software\_select}(\linebreak[0]name=\linebreak[0]None, version=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{name:}  The name of the software program utilised.

\hspace{3 mm}\keyword{version:}  The version of the software, if applicable.


\subsubsection{Description}

Rather than specifying all the information directly, this user function allows the software packaged used in the analysis to be selected by name.  The programs currently supported are:

\begin{description}
  \item[\quotecmd{NMRPipe} --] http://spin.niddk.nih.gov/NMRPipe/
  \item[\quotecmd{Sparky} --] http://www.cgl.ucsf.edu/home/sparky/
\end{description}

More can be added if all relevant information (program name, description, website, original citation, purpose, etc.) is emailed to relax-users@gna.org.

Note that relax is automatically added to the BMRB file.

\subsubsection{Prompt examples}

For BMRB deposition, to say that both NMRPipe\index{NMR} and Sparky\index{software!Sparky}\index{software!Sparky} were used prior to relax, type:

\begin{lstlisting}[numbers=none]
relax> bmrb.software_select('NMRPipe')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> bmrb.software_select('Sparky', version='3.113')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.thiol\-\_state} \label{uf: bmrb.thiol_state}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill 

\subsubsection{Synopsis}

Select the thiol state of the system.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]thiol\_state}(\linebreak[0]state=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{state:}  The thiol state.


\subsubsection{Description}

The thiol state can be any text, thought the BMRB suggests the following:

\begin{itemize}
  \item[]\quotecmd{all disulfide bound},\index{parameter!bounds}
  \item[]\quotecmd{all free},
  \item[]\quotecmd{all other bound},\index{parameter!bounds}
  \item[]\quotecmd{disulfide and other bound},\index{parameter!bounds}
  \item[]\quotecmd{free and disulfide bound},\index{parameter!bounds}
  \item[]\quotecmd{free and other bound},\index{parameter!bounds}
  \item[]\quotecmd{free disulfide and other bound},\index{parameter!bounds}
  \item[]\quotecmd{not available},
  \item[]\quotecmd{not present},
  \item[]\quotecmd{not reported},
  \item[]\quotecmd{unknown}.
\end{itemize}

Alternatively the pure states \quotecmd{reduced} or \quotecmd{oxidised} could be specified.

\subsubsection{Prompt examples}

For BMRB deposition, to say that the protein studied is in the oxidised state, tyype one of:

\begin{lstlisting}[numbers=none]
relax> bmrb.thiol_state('oxidised')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> bmrb.thiol_state(state='oxidised')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bmrb\-.write} \label{uf: bmrb.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bmrb} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} the results to a BMRB NMR-STAR\index{NMR} formatted file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bmrb.\linebreak[0]write}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]`pipe\_name', version=\linebreak[0]`3.1', force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the BMRB file to output results to.  Optionally this can be a file object, or any object with a write()\index{write} method.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{version:}  The NMR-STAR\index{NMR} dictionary format version to create.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the any pre-existing file to be overwritten.


\subsubsection{Description}

This will create a NMR-STAR\index{NMR} formatted file of the data in the current data pipe for BMRB deposition.

In the prompt/script UI modes, to place the BMRB file in the current working directory, set dir to None.  If dir is set to the special name \quotecmd{pipe\_name}, then the results file will be placed into a directory with the same name as the current data pipe.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{bruker\-.read} \label{uf: bruker.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/bruker} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} a Bruker Dynamics Center (DC) relaxation\index{relaxation} data file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{bruker.\linebreak[0]read}(\linebreak[0]ri\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.  This must be a unique identifier.

\hspace{3 mm}\keyword{file:}  The name of the Bruker Dynamics Center file containing the relaxation\index{relaxation} data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.


\subsubsection{Description}

This user function is used to load all of the data out of a Bruker Dynamics Center (DC) relaxation\index{relaxation} data file for subsequent analysis within relax.  Currently the R$_1$ and R$_2$ relaxation\index{relaxation} rates and steady-state NOE data is supported.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{chemical\-\_shift\-.read} \label{uf: chemical_shift.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/chemical_shift} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} chemical shifts from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{chemical\_shift.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the peak list of generic formatted file containing the chemical shifts.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column used by the generic file format (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{sep:}  The column separator used by the generic format (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string used to restrict the loading of data to certain spin subsets.


\subsubsection{Description}

This will read\index{read} chemical shifts from a peak list or a generic column formatted file.

\subsubsection{Prompt examples}

The following commands will read\index{read} the chemical shifts out of the Sparky\index{software!Sparky}\index{software!Sparky} peak list \quotecmd{10$m$s.list}:

\begin{lstlisting}[numbers=none]
relax> chemical_shift.read('10ms.list')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{consistency\-\_tests\-.set\-\_frq} \label{uf: consistency_tests.set_frq}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/consistency_testing} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frq}

\subsubsection{Synopsis}

Select which relaxation\index{relaxation} data to use in the consistency tests by NMR\index{NMR} spectrometer frequency.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{consistency\_tests.\linebreak[0]set\_frq}(\linebreak[0]frq=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{frq:}  The spectrometer frequency in Hz.  This must match the currently loaded data to the last decimal point.  See the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file.


\subsubsection{Description}

This will select the relaxation\index{relaxation} data to use in the consistency tests corresponding to the given frequencies.  The data is selected by the spectrometer frequency in Hertz, which should be set to the exact value (see the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file).  Note thought that the R$_1$, R$_2$ and NOE are all expected to have the exact same frequency in the $J(\omega)$ mapping\index{map} analysis (to the last decimal point).

\subsubsection{Prompt examples}

\begin{lstlisting}[numbers=none]
relax> consistency_tests.set_frq(600.0 * 1e6)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> consistency_tests.set_frq(frq=600.0 * 1e6)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{dasha\-.create\index{software!Dasha|textbf}} \label{uf: dasha.create}
\hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create the Dasha\index{software!Dasha}\index{software!Dasha} script.\index{scripting!script file}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{dasha.\linebreak[0]create}(\linebreak[0]algor=\linebreak[0]`LM', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{algor:}  The minimisation\index{optimisation} algorithm.

\hspace{3 mm}\keyword{dir:}  The directory to place the files.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the results file to be overwritten if it already exists.


\subsubsection{Description}

The script\index{scripting!script file} file created is called \quotecmd{dir/dasha\_script}.

\subsubsection{Optimisation algorithms}

The two minimisation\index{optimisation} algorithms within Dasha\index{software!Dasha}\index{software!Dasha} are accessible through the algorithm which can be set to:

\begin{description}
  \item[\quotecmd{LM} --] The Levenberg-Marquardt\index{optimisation!algorithm!Levenberg-Marquardt} algorithm,
  \item[\quotecmd{NR} --] Newton-Raphson\index{optimisation!algorithm!Newton} algorithm.
\end{description}

For Levenberg-Marquardt\index{optimisation!algorithm!Levenberg-Marquardt} minimisation,\index{optimisation} the function \quotecmd{lmin} will be called, while for Newton-Raphson,\index{optimisation!algorithm!Newton} the function \quotecmd{min} will be executed.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{dasha\-.execute\index{software!Dasha|textbf}} \label{uf: dasha.execute}
\hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Perform a model-free optimisation using Dasha.\index{software!Dasha}\index{software!Dasha}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{dasha.\linebreak[0]execute}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False, binary=\linebreak[0]`dasha')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory to place the files.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the results file to be overwritten if it already exists.

\hspace{3 mm}\keyword{binary:}  The name of the executable Dasha\index{software!Dasha}\index{software!Dasha} program file.


\subsubsection{Description}

Dasha\index{software!Dasha}\index{software!Dasha} will be executed as

\begin{lstlisting}[numbers=none]
$ dasha < dasha_script | tee dasha_results
\end{lstlisting}


If you would like to use a different Dasha\index{software!Dasha}\index{software!Dasha} executable file, change the binary name to the appropriate file name.  If the file is not located within the environment's path, include the full path in front of the binary file name.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{dasha\-.extract\index{software!Dasha|textbf}} \label{uf: dasha.extract}
\hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/archive-extract}

\subsubsection{Synopsis}

Extract data from the Dasha\index{software!Dasha}\index{software!Dasha} results file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{dasha.\linebreak[0]extract}(\linebreak[0]dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory where the file \quotecmd{dasha\_results} is found.


\subsubsection{Description}

The model-free results will be extracted from the Dasha\index{software!Dasha}\index{software!Dasha} results file \quotecmd{dasha\_results} located in the given directory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{deselect\-.all} \label{uf: deselect.all}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey} \hfill 

\subsubsection{Synopsis}

Deselect all spins in the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{deselect.\linebreak[0]all}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will deselect all spins, irregardless of their current state.

\subsubsection{Prompt examples}

To deselect all spins, simply type:

\begin{lstlisting}[numbers=none]
relax> deselect.all()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{deselect\-.interatom} \label{uf: deselect.interatom}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey} \hfill 

\subsubsection{Synopsis}

Deselect specific interatomic data containers.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{deselect.\linebreak[0]interatom}(\linebreak[0]spin\_id1=\linebreak[0]None, spin\_id2=\linebreak[0]None, boolean=\linebreak[0]`AND', change\_all=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id1:}  The spin ID string of the first spin of the interatomic data container.

\hspace{3 mm}\keyword{spin\_id2:}  The spin ID string of the second spin of the interatomic data container.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how interatomic data containers should be selected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all other interatomic data containers should be changed.


\subsubsection{Description}

This is used to deselect specific interatomic data containers which store information about spin pairs such as RDCs, NOEs, dipole-dipole pairs involved in relaxation,\index{relaxation} etc.  The \quotecmd{change all} flag default is False meaning that all interatomic data containers currently either selected or deselected will remain that way.  Setting this to True will cause all interatomic data containers not specified by the spin ID strings to be deselected.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Boolean operators and their effects on selections]{Boolean operators and their effects on selections}
\begin{tabular}{llllllllll}
\\[-5pt]
\toprule
Spin system or interatomic data container & 1 & 2 & 3 & 4 & 5 & 6 & 7 & 8 & 9 \\
\midrule
Original selection & 0 & 1 & 1 & 1 & 1 & 0 & 1 & 0 & 1 \\
New selection & 0 & 1 & 1 & 1 & 1 & 1 & 0 & 0 & 0 \\
OR & 0 & 1 & 1 & 1 & 1 & 1 & 1 & 0 & 1 \\
NOR & 1 & 0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
AND & 0 & 1 & 1 & 1 & 1 & 0 & 0 & 0 & 0 \\
NAND & 1 & 0 & 0 & 0 & 0 & 1 & 1 & 1 & 1 \\
XOR & 0 & 0 & 0 & 0 & 0 & 1 & 1 & 0 & 1 \\
XNOR & 1 & 1 & 1 & 1 & 1 & 0 & 0 & 1 & 0 \\
\bottomrule
\\[-5pt]
\label{table: bool operators}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Prompt examples}

To deselect all N-H backbone bond vectors of a protein, assuming these interatomic data containers have been already set up, type one of:

\begin{lstlisting}[numbers=none]
relax> deselect.interatom('@N', '@H')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.interatom(spin_id1='@N', spin_id2='@H')
\end{lstlisting}


To deselect all H-H interatomic vectors of a small organic molecule,\index{molecule} type one of:

\begin{lstlisting}[numbers=none]
relax> deselect.interatom('@H*', '@H*')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.interatom(spin_id1='@H*', spin_id2='@H*')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{deselect\-.read} \label{uf: deselect.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Deselect the spins contained in a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{deselect.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None, boolean=\linebreak[0]`AND', change\_all=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the list of spins to deselect.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict the loading of data to certain spin subsets.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how spins should be selected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all other spins should be changed.


\subsubsection{Description}

The spin system can be identified in the file using two different formats.  The first is the spin ID string column which can include the molecule\index{molecule} name, the residue name and number, and the spin name and number.  Alternatively the molecule\index{molecule} name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns.  Note that the numbering of columns starts at one.  The spin ID string can be used to restrict the reading\index{read} to certain spin types, for example only 15N spins when only residue information is in the file.

Empty lines and lines beginning with a hash are ignored.

The \quotecmd{change all} flag default is False meaning that all spins currently either selected or deselected will remain that way.  Setting this to True will cause all spins not specified in the file to be selected.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\subsubsection{Prompt examples}

To deselect all overlapped residues listed with residue numbers in the first column of the file \quotecmd{unresolved}, type one of:

\begin{lstlisting}[numbers=none]
relax> deselect.read('unresolved', res_num_col=1)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.read(file='unresolved', res_num_col=1)
\end{lstlisting}


To deselect the spins in the second column of the relaxation\index{relaxation} data file \quotecmd{r1.600} while selecting all other spins, for example type:

\begin{lstlisting}[numbers=none]
relax> deselect.read('r1.600', spin_num_col=2, change_all=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.read(file='r1.600', spin_num_col=2, change_all=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{deselect\-.reverse} \label{uf: deselect.reverse}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/system-switch-user}

\subsubsection{Synopsis}

Reversal of the spin selection for the given spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{deselect.\linebreak[0]reverse}(\linebreak[0]spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.


\subsubsection{Description}

By supplying the spin ID string, a subset of spins can have their selection status reversed.

\subsubsection{Description}

To deselect all currently selected spins and select those which are deselected type:

\begin{lstlisting}[numbers=none]
relax> deselect.reverse()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{deselect\-.sn\-\_ratio} \label{uf: deselect.sn_ratio}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid}

\subsubsection{Synopsis}

Deselect spins with signal to noise ratio higher or lower than the given ratio.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{deselect.\linebreak[0]sn\_ratio}(\linebreak[0]ratio=\linebreak[0]10.0, operation=\linebreak[0]`<', all\_sn=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ratio:}  The signal to noise ratio to compare to.

\hspace{3 mm}\keyword{operation:}  The comparison operation by which to deselect the spins.

\hspace{3 mm}\keyword{all\_sn:}  A flag specifying if all the signal to noise ratios per spin should match the comparison operator, of if just a single comparison match is enough.


\subsubsection{Description}

The comparison operation is the method which to deselect spins according to: operation(sn\_ratio, ratio).

The possible operations are: \quotecmd{<}:strictly less than, \quotecmd{<=}:less than or equal, \quotecmd{>}:strictly greater than, \quotecmd{>=}:greater than or equal, \quotecmd{==}:equal, \quotecmd{!=}:not equal.

The \quotecmd{all\_sn} flag default is False, meaning that if any of the spin's signal to noise levels evaluates to True in the comparison, the spin is deselected.

\subsubsection{Prompt examples}

To deselect all spins with a signal to noise ratio lower than 10.0:

\begin{lstlisting}[numbers=none]
relax> deselect.sn_ratio(ratio=10.0, operation='<')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.sn_ratio(ratio=10.0, operation='<', all_sn=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{deselect\-.spin} \label{uf: deselect.spin}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey}

\subsubsection{Synopsis}

Deselect specific spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{deselect.\linebreak[0]spin}(\linebreak[0]spin\_id=\linebreak[0]None, boolean=\linebreak[0]`AND', change\_all=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how spins should be deselected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all other spins should be changed.


\subsubsection{Description}

The \quotecmd{change all} flag default is False meaning that all spins currently either selected or deselected will remain that way.  Setting this to True will cause all spins not specified by the spin ID string to be deselected.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\subsubsection{Prompt examples}

To deselect all glycines and alanines, type:

\begin{lstlisting}[numbers=none]
relax> deselect.spin(spin_id=':GLY|:ALA')
\end{lstlisting}


To deselect residue 12 MET type:

\begin{lstlisting}[numbers=none]
relax> deselect.spin(':12')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.spin(spin_id=':12')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> deselect.spin(spin_id=':12&:MET')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{diffusion\-\_tensor\-.copy} \label{uf: diffusion_tensor.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/diff_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} diffusion\index{diffusion!tensor} tensor data from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{diffusion\_tensor.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the data pipe to copy\index{copy} the diffusion\index{diffusion!tensor} tensor data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the data pipe to copy\index{copy} the diffusion\index{diffusion!tensor} tensor data to.


\subsubsection{Description}

This will copy\index{copy} the diffusion\index{diffusion!tensor} tensor data between data pipes.  The destination data pipe must not contain any diffusion\index{diffusion!tensor} tensor data.  If the source or destination data pipes are not supplied, then both will default to the current data pipe (hence specifying at least one is essential).

\subsubsection{Prompt examples}

To copy\index{copy} the diffusion\index{diffusion!tensor} tensor from the data pipe \quotecmd{m1} to the current data pipe, type:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.copy('m1')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.copy(pipe_from='m1')
\end{lstlisting}


To copy\index{copy} the diffusion\index{diffusion!tensor} tensor from the current data pipe to the data pipe \quotecmd{m9}, type:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.copy(pipe_to='m9')
\end{lstlisting}


To copy\index{copy} the diffusion\index{diffusion!tensor} tensor from the data pipe \quotecmd{m1} to \quotecmd{m2}, type:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.copy('m1', 'm2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.copy(pipe_from='m1', pipe_to='m2')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{diffusion\-\_tensor\-.delete} \label{uf: diffusion_tensor.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/diff_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} the diffusion\index{diffusion!tensor} tensor data from the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{diffusion\_tensor.\linebreak[0]delete}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will delete\index{delete} all diffusion\index{diffusion!tensor} tensor data from the current data pipe.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{diffusion\-\_tensor\-.display} \label{uf: diffusion_tensor.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/diff_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the diffusion\index{diffusion!tensor} tensor information.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{diffusion\_tensor.\linebreak[0]display}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will display\index{display} all of the diffusion\index{diffusion!tensor} tensor information of the current data pipe.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{diffusion\-\_tensor\-.init} \label{uf: diffusion_tensor.init}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/diff_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/diff_tensor}

\subsubsection{Synopsis}

Initialise the diffusion\index{diffusion!tensor} tensor.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{diffusion\_tensor.\linebreak[0]init}(\linebreak[0]params=\linebreak[0]None, time\_scale=\linebreak[0]1.0, d\_scale=\linebreak[0]1.0, angle\_units=\linebreak[0]`deg', param\_types=\linebreak[0]0, spheroid\_type=\linebreak[0]None, fixed=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{params:}  The diffusion\index{diffusion!tensor} tensor data.

\hspace{3 mm}\keyword{time\_scale:}  The correlation\index{correlation time} time scaling value.

\hspace{3 mm}\keyword{d\_scale:}  The diffusion\index{diffusion!tensor} tensor eigenvalue\index{eigenvalues} scaling value.

\hspace{3 mm}\keyword{angle\_units:}  The units for the angle\index{angles} parameters.

\hspace{3 mm}\keyword{param\_types:}  A flag to select different parameter combinations.

\hspace{3 mm}\keyword{spheroid\_type:}  A string which, if supplied together with spheroid\index{diffusion!spheroid (axially symmetric)} parameters, will restrict the tensor to either being \quotecmd{oblate} or \quotecmd{prolate}.

\hspace{3 mm}\keyword{fixed:}  A flag specifying whether the diffusion\index{diffusion!tensor} tensor is fixed or can be optimised.\index{optimise}


\subsubsection{The sphere (isotropic diffusion)}

When the molecule\index{molecule} diffuses as a sphere,\index{diffusion!sphere (isotropic)} all three eigenvalues\index{eigenvalues} of the diffusion\index{diffusion!tensor} tensor are equal, $\Diff_x$ = $\Diff_y$ = $\Diff_z$.  In this case, the orientation of the XH bond vector within the diffusion frame is inconsequential to relaxation,\index{relaxation} hence, the spherical or Euler\index{Euler angles} angles\index{angles} are undefined.  Therefore solely a single geometric parameter, either $\tau_m$ or $\Diff_{iso}$, can fully and sufficiently parameterise the diffusion\index{diffusion!tensor} tensor.  The correlation function for the global rotational\index{rotation} diffusion is

{\footnotesize \begin{verbatim}

             1   - tau / tm
    C(tau) = - e            ,
             5

\end{verbatim}}

To select isotropic\index{diffusion!sphere (isotropic)} diffusion, the parameter should be a single floating\index{floating point number} point number.  The number is the value of the isotropic\index{diffusion!sphere (isotropic)} global correlation\index{correlation time} time, $\tau_m$, in seconds. To specify the time in nanoseconds, set the time scale to 1e-9.  Alternative parameters can be used by changing the \quotecmd{param\_types} flag to the following integers

\begin{description}
  \item[0 --] \{tm\}   (Default),
  \item[1 --] \{Diso\},
\end{description}

where

\begin{itemize}
  \item[]1 / $\tau_m$ = 6$\Diff_{iso}$.
\end{itemize}

\subsubsection{The spheroid (axially symmetric diffusion)}

When two of the three eigenvalues\index{eigenvalues} of the diffusion\index{diffusion!tensor} tensor are equal, the molecule\index{molecule} diffuses as a spheroid.\index{diffusion!spheroid (axially symmetric)}  Four pieces of information are required to specify this tensor, the two geometric parameters, $\Diff_{iso}$ and $\Diff_a$, and the two orientational parameters, the polar angle\index{angles} $\theta$ and the azimuthal angle\index{angles} $\phi$ describing the orientation of the axis of symmetry.  The correlation function of the global diffusion is

{\footnotesize \begin{verbatim}

               _1_
             1 \          - tau / tau_i
    C(tau) = -  >  ci . e              ,
             5 /__
               i=-1

\end{verbatim}}

where

\begin{itemize}
  \item[]c-1 = 1/4 (3 $\delta_z$\^{}2 - 1)\^{}2,
  \item[]c0  = 3 $\delta_z$\^{}2 (1 - $\delta_z$\^{}2),
  \item[]c1  = 3/4 ($\delta_z$\^{}2 - 1)\^{}2,
\end{itemize}

and

\begin{itemize}
  \item[]1 / $\tau$ -1 = 6$\Diff_{iso}$ - 2$\Diff_a$,
  \item[]1 / $\tau$ 0  = 6$\Diff_{iso}$ - $\Diff_a$,
  \item[]1 / $\tau$ 1  = 6$\Diff_{iso}$ + 2$\Diff_a$.
\end{itemize}

The direction cosine $\delta_z$ is defined as the cosine of the angle\index{angles} $\alpha$ between the XH bond vector and the unique axis of the diffusion\index{diffusion!tensor} tensor.

To select axially\index{diffusion!spheroid (axially symmetric)} symmetric anisotropic\index{diffusion!anisotropic} diffusion, the parameters should be a tuple of floating\index{floating point number} point numbers of length four.  A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas.  Alternative sets of parameters, \quotecmd{param\_types}, are

\begin{description}
  \item[0 --] \{$\tau_m$, $\Diff_a$, $\theta$, $\phi$\}   (Default),
  \item[1 --] \{$\Diff_{iso}$, $\Diff_a$, $\theta$, $\phi$\},
  \item[2 --] \{$\tau_m$, $\Diff_{ratio}$, $\theta$, $\phi$\},
  \item[3 --] \{$\Diff_\Par$, $\Diff_\Per$, $\theta$, $\phi$\},
  \item[4 --] \{$\Diff_{iso}$, $\Diff_{ratio}$, $\theta$, $\phi$\},
\end{description}

where

\begin{itemize}
  \item[]$\tau_m$ = 1 / 6$\Diff_{iso}$,
  \item[]$\Diff_{iso}$ = 1/3 ($\Diff_\Par$ + 2$\Diff_\Per$),
  \item[]$\Diff_a$ = $\Diff_\Par$ - $\Diff_\Per$,
  \item[]$\Diff_{ratio}$ = $\Diff_\Par$ / $\Diff_\Per$.
\end{itemize}

The spherical angles\index{angles} \{$\theta$, $\phi$\} orienting the unique axis of the diffusion\index{diffusion!tensor} tensor within the PDB\index{PDB} frame are defined between

\begin{itemize}
  \item[]0 $\le$ $\theta$ $\le$ $\pi$,
  \item[]0 $\le$ $\phi$ $\le$ 2$\pi$,
\end{itemize}

while the angle\index{angles} $\alpha$ which is the angle\index{angles} between this axis and the given XH bond vector is defined between

\begin{itemize}
  \item[]0 $\le$ $\alpha$ $\le$ 2$\pi$.
\end{itemize}

The spheroid\index{diffusion!spheroid (axially symmetric)} type should be \quotecmd{oblate}, \quotecmd{prolate}, or None.  This will be ignored if the diffusion\index{diffusion!tensor} tensor is not axially\index{diffusion!spheroid (axially symmetric)} symmetric.  If \quotecmd{oblate} is given, then the constraint\index{constraint} $\Diff_a$ $\le$ 0 is used while if \quotecmd{prolate} is given, then the constraint\index{constraint} $\Diff_a$ $\ge$ 0 is used.  If nothing is supplied, then $\Diff_a$ will be allowed to have any values.  To prevent minimisation\index{optimisation} of diffusion\index{diffusion!tensor} tensor parameters in a space with two minima, it is recommended to specify which tensor is to be minimised,\index{optimisation} thereby partitioning the two minima into the two subspaces along the boundary\index{parameter!bounds} $\Diff_a$ = 0.

\subsubsection{The ellipsoid (rhombic diffusion)}

When all three eigenvalues\index{eigenvalues} of the diffusion\index{diffusion!tensor} tensor are different, the molecule\index{molecule} diffuses as an ellipsoid.\index{diffusion!ellipsoid (asymmetric)}  This diffusion is also known as fully anisotropic,\index{diffusion!anisotropic} asymmetric,\index{diffusion!ellipsoid (asymmetric)} or rhombic. The full tensor is specified by six pieces of information, the three geometric parameters $\Diff_{iso}$, $\Diff_a$, and $\Diff_r$ representing the isotropic,\index{diffusion!sphere (isotropic)} anisotropic,\index{diffusion!anisotropic} and rhombic components of the tensor, and the three Euler\index{Euler angles} angles\index{angles} $\alpha$, $\beta$, and $\gamma$ orienting the tensor within the PDB\index{PDB} frame.  The correlation function is

{\footnotesize \begin{verbatim}

               _2_
             1 \          - tau / tau_i
    C(tau) = -  >  ci . e              ,
             5 /__
               i=-2

\end{verbatim}}

where the weights on the exponentials are

\begin{itemize}
  \item[]c-2 = 1/4 (d + e),
  \item[]c-1 = 3 $\delta_y$\^{}2 $\delta_z$\^{}2,
  \item[]c0  = 3 $\delta_x$\^{}2 $\delta_z$\^{}2,
  \item[]c1  = 3 $\delta_x$\^{}2 $\delta_y$\^{}2,
  \item[]c2  = 1/4 (d + e).
\end{itemize}

Let

\begin{itemize}
  \item[]$\mathfrak{R}$ = sqrt(1 + 3$\Diff_r$),
\end{itemize}

then

\begin{itemize}
  \item[]d = 3 ($\delta_x$\^{}4 + $\delta_y$\^{}4 + $\delta_z$\^{}4) - 1,
  \item[]e = - 1 / $\mathfrak{R}$ ((1 + 3$\Diff_r$)($\delta_x$\^{}4 + 2$\delta_y$\^{}2 $\delta_z$\^{}2) + (1 - 3$\Diff_r$)($\delta_y$\^{}4 + 2$\delta_x$\^{}2 $\delta_z$\^{}2) - 2($\delta_z$\^{}4 + 2$\delta_x$\^{}2 $\delta_y$\^{}2)).
\end{itemize}

The correlation\index{correlation time} times are

\begin{itemize}
  \item[]1 / $\tau$ -2 = 6$\Diff_{iso}$ - 2$\Diff_a$ . $\mathfrak{R}$,
  \item[]1 / $\tau$ -1 = 6$\Diff_{iso}$ - $\Diff_a$ (1 + 3$\Diff_r$),
  \item[]1 / $\tau$ 0  = 6$\Diff_{iso}$ - $\Diff_a$ (1 - 3$\Diff_r$),
  \item[]1 / $\tau$ 1  = 6$\Diff_{iso}$ + 2$\Diff_a$,
  \item[]1 / $\tau$ 1  = 6$\Diff_{iso}$ + 2$\Diff_a$ . $\mathfrak{R}$.
\end{itemize}

The three direction cosines $\delta_x$, $\delta_y$, and $\delta_z$ are the coordinates of a unit vector parallel to the XH bond vector.  Hence the unit vector is [$\delta_x$, $\delta_y$, $\delta_z$].

To select fully anisotropic\index{diffusion!anisotropic} diffusion, the parameters should be a tuple of length six.  A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas.  Alternative sets of parameters, \quotecmd{param\_types}, are

\begin{description}
  \item[0 --] \{$\tau_m$, $\Diff_a$, $\Diff_r$, $\alpha$, $\beta$, $\gamma$\}   (Default),
  \item[1 --] \{$\Diff_{iso}$, $\Diff_a$, $\Diff_r$, $\alpha$, $\beta$, $\gamma$\},
  \item[2 --] \{$\Diff_x$, $\Diff_y$, $\Diff_z$, $\alpha$, $\beta$, $\gamma$\},
  \item[3 --] \{Dxx, Dyy, Dzz, Dxy, Dxz, Dyz\},
\end{description}

where

\begin{itemize}
  \item[]$\tau_m$ = 1 / 6$\Diff_{iso}$,
  \item[]$\Diff_{iso}$ = 1/3 ($\Diff_x$ + $\Diff_y$ + $\Diff_z$),
  \item[]$\Diff_a$ = $\Diff_z$ - ($\Diff_x$ + $\Diff_y$)/2,
  \item[]$\Diff_r$ = ($\Diff_y$ - $\Diff_x$)/2$\Diff_a$.
\end{itemize}

The angles\index{angles} $\alpha$, $\beta$, and $\gamma$ are the Euler\index{Euler angles} angles\index{angles} describing the diffusion\index{diffusion!tensor} tensor within the PDB\index{PDB} frame.  These angles\index{angles} are defined using the z-y-z axis rotation\index{rotation} notation where $\alpha$ is the initial rotation\index{rotation} angle\index{angles} around the z-axis, $\beta$ is the rotation\index{rotation} angle\index{angles} around the y-axis, and $\gamma$ is the final rotation\index{rotation} around the z-axis again.  The angles\index{angles} are defined between

\begin{itemize}
  \item[]0 $\le$ $\alpha$ $\le$ 2$\pi$,
  \item[]0 $\le$ $\beta$ $\le$ $\pi$,
  \item[]0 $\le$ $\gamma$ $\le$ 2$\pi$.
\end{itemize}

Within the PDB\index{PDB} frame, the XH bond vector is described using the spherical angles\index{angles} $\theta$ and $\phi$ where $\theta$ is the polar angle\index{angles} and $\phi$ is the azimuthal angle\index{angles} defined between

\begin{itemize}
  \item[]0 $\le$ $\theta$ $\le$ $\pi$,
  \item[]0 $\le$ $\phi$ $\le$ 2$\pi$.
\end{itemize}

When param\_types is set to 3, then the elements of the diffusion\index{diffusion!tensor} tensor matrix defined within the PDB\index{PDB} frame can be supplied.

\subsubsection{Units}

The correlation\index{correlation time} time scaling value should be a floating\index{floating point number} point number.  The only parameter affected by this value is $\tau_m$.

The diffusion\index{diffusion!tensor} tensor eigenvalue\index{eigenvalues} scaling value should also be a floating\index{floating point number} point number.  Parameters affected by this value are $\Diff_{iso}$, $\Diff_\Par$, $\Diff_\Per$, $\Diff_a$, $\Diff_x$, $\Diff_y$, and $\Diff_z$.  Significantly, $\Diff_r$ is not affected.

The  units for the angle\index{angles} parameters should be either \quotecmd{deg} or \quotecmd{rad}.  Parameters affected are $\theta$, $\phi$, $\alpha$, $\beta$, and $\gamma$.

\subsubsection{Prompt examples}

To set an isotropic\index{diffusion!sphere (isotropic)} diffusion\index{diffusion!tensor} tensor with a correlation\index{correlation time} time of 10 ns, type:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(10e-9)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(params=10e-9)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(10.0, 1e-9)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(params=10.0, time_scale=1e-9, fixed=True)
\end{lstlisting}


To select axially\index{diffusion!spheroid (axially symmetric)} symmetric diffusion with a $\tau_m$ value of 8.5 ns, $\Diff_{ratio}$ of 1.1, $\theta$ value of 20 degrees, and $\phi$ value of 20 degrees, type:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init((8.5e-9, 1.1, 20.0, 20.0), param_types=2)
\end{lstlisting}


To select a spheroid\index{diffusion!spheroid (axially symmetric)} diffusion\index{diffusion!tensor} tensor with a $\Diff_\Par$ value of 1.698e7, $\Diff_\Per$ value of 1.417e7, $\theta$ value of 67.174 degrees, and $\phi$ value of -83.718 degrees, type one of:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init((1.698e7, 1.417e7, 67.174, -83.718), param_types=3)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(params=(1.698e7, 1.417e7, 67.174, -83.718), param_types=3)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, d_scale=1e8)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, d_scale=1e8)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, d_scale=1e8, angle_units='rad')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, d_scale=1e8, angle_units='rad', fixed=True)
\end{lstlisting}


To select ellipsoidal\index{diffusion!ellipsoid (asymmetric)} diffusion, type:

\begin{lstlisting}[numbers=none]
relax> diffusion_tensor.init((1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=2)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{domain} \label{uf: domain}


\subsubsection{Synopsis}

Definition of structural domains.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{domain}(\linebreak[0]id=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{id:}  The ID string used to identify molecular domains.

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string of all atomic members of the domain.


\subsubsection{Description}

This is used to define structural domains.  Multiple domains can be defined, and these can overlap.  Rather than labelling the currently loaded spins with the ID string, the spin ID string is stored for later use.  This allows new spins to be loaded later and still be included within the same domain.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{dx\-.execute} \label{uf: dx.execute}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/opendx} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Execute an OpenDX\index{software!OpenDX} program.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{dx.\linebreak[0]execute}(\linebreak[0]file\_prefix=\linebreak[0]`map', dir=\linebreak[0]`dx', dx\_exe=\linebreak[0]`dx', vp\_exec=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file\_prefix:}  The file name prefix.  For example if file is set to \quotecmd{temp}, then the OpenDX\index{software!OpenDX} program temp.net will be loaded.

\hspace{3 mm}\keyword{dir:}  The directory to change to for running OpenDX.\index{software!OpenDX}  If this is set to None, OpenDX\index{software!OpenDX} will be run in the current directory.

\hspace{3 mm}\keyword{dx\_exe:}  The OpenDX\index{software!OpenDX} executable file.

\hspace{3 mm}\keyword{vp\_exec:}  A flag specifying whether to execute the visual program automatically at start-up.  The default of True causes the program to be executed.


\subsubsection{Description}

This will execute OpenDX\index{software!OpenDX} to display\index{display} the space maps\index{map} created previously by the $\delta_x$.map user function.  This will work for any type of OpenDX\index{software!OpenDX} map.\index{map}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{dx\-.map} \label{uf: dx.map}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/opendx} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grid_search}

\subsubsection{Synopsis}

Create a map\index{map} of the given space in OpenDX\index{software!OpenDX} format.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{dx.\linebreak[0]map}(\linebreak[0]params=\linebreak[0]None, map\_type=\linebreak[0]`Iso3D', spin\_id=\linebreak[0]None, inc=\linebreak[0]20, lower=\linebreak[0]None, upper=\linebreak[0]None, axis\_incs=\linebreak[0]5, file\_prefix=\linebreak[0]`map', dir=\linebreak[0]`dx', point=\linebreak[0]None, point\_file=\linebreak[0]`point', chi\_surface=\linebreak[0]None, create\_par\_file=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{params:}  The parameters to be mapped.\index{map}  This should be an array of strings, the meanings of which are described below.

\hspace{3 mm}\keyword{map\_type:}  The type of map\index{map} to create.  For example the default, a 3D isosurface, the type is \quotecmd{Iso3D}.  See below for more details.

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.

\hspace{3 mm}\keyword{inc:}  The number of increments to map\index{map} in each dimension.  This value controls the resolution of the map.\index{map}

\hspace{3 mm}\keyword{lower:}  The lower bounds\index{parameter!bounds} of the space.  If you wish to change the lower bounds\index{parameter!bounds} of the map\index{map} then supply an array of length equal to the number of parameters in the model.  A lower bound\index{parameter!bounds} for each parameter must be supplied.  If nothing is supplied then the defaults will be used.

\hspace{3 mm}\keyword{upper:}  The upper bounds\index{parameter!bounds} of the space.  If you wish to change the upper bounds\index{parameter!bounds} of the map\index{map} then supply an array of length equal to the number of parameters in the model.  A upper bound\index{parameter!bounds} for each parameter must be supplied.  If nothing is supplied then the defaults will be used.

\hspace{3 mm}\keyword{axis\_incs:}  The number of increments or ticks displaying\index{display} parameter values along the axes of the OpenDX\index{software!OpenDX} plot.\index{plot}

\hspace{3 mm}\keyword{file\_prefix:}  The file name.  All the output files are prefixed with this name.  The main file containing the data points will be called the value of \quotecmd{file}.  The OpenDX\index{software!OpenDX} program will be called \quotecmd{file.net} and the OpenDX\index{software!OpenDX} import file will be called \quotecmd{file.general}.

\hspace{3 mm}\keyword{dir:}  The directory to output files to.  Set this to \quotecmd{None} if you do not want the files to be placed in subdirectory.  If the directory does not exist, it will be created.

\hspace{3 mm}\keyword{point:}  This argument allows specific points in the optimisation space to be displayed\index{display} as coloured spheres.\index{diffusion!sphere (isotropic)}  This can be used to highlight a minimum or other any other feature of the space.  Either a single point or a list of points can be supplied.  Each point is a list of floating\index{floating point number} point numbers in the form [$x$, $y$, $z$]

\hspace{3 mm}\keyword{point\_file:}  The name of that the point output files will be prefixed with.

\hspace{3 mm}\keyword{chi\_surface:}  A list of 4 numbers, setting the level for the 4 isosurfaces. Useful in scripting\index{scripting!script file}\index{scripting} if you create a set of OpenDX\index{software!OpenDX} maps\index{map} with all the same contour levels.  Ideal for comparisons.

\hspace{3 mm}\keyword{create\_par\_file:}  A flag specifying whether to create a file with parameters and associated chi2 value.  The default of False causes the file not to be created.


\subsubsection{Description}

This will map\index{map} the space corresponding to the spin identifier and create the OpenDX\index{software!OpenDX} files.  The map\index{map} type can be changed to one of the following supported map\index{map} types:

Please see Table~\ref{table: opendx map} on page~\pageref{table: opendx map}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[OpenDx mapping types.]{OpenDx mapping types.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Surface type & Name \\
\midrule
3D isosurface & 'Iso3D' \\
\bottomrule
\\[-5pt]
\label{table: opendx map}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Model-free parameters}

Please see Table~\ref{table: all model-free parameters} on page~\pageref{table: all model-free parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Model-free parameters.]{Model-free parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
tm & Global correlation time \\
Diso & Isotropic component of the diffusion tensor \\
Dx & Eigenvalue associated with the x-axis of the diffusion tensor \\
Dy & Eigenvalue associated with the y-axis of the diffusion tensor \\
Dz & Eigenvalue associated with the z-axis of the diffusion tensor \\
Dpar & Diffusion coefficient parallel to the major axis of the spheroid diffusion tensor \\
Dper & Diffusion coefficient perpendicular to the major axis of the spheroid diffusion tensor \\
Da & Anisotropic component of the diffusion tensor \\
Dr & Rhombic component of the diffusion tensor \\
Dratio & Ratio of the parallel and perpendicular components of the spheroid diffusion tensor \\
alpha & The first Euler angle of the ellipsoid diffusion tensor \\
beta & The second Euler angle of the ellipsoid diffusion tensor \\
gamma & The third Euler angle of the ellipsoid diffusion tensor \\
theta & The polar angle defining the major axis of the spheroid diffusion tensor \\
phi & The azimuthal angle defining the major axis of the spheroid diffusion tensor \\
s2 & $S^2$, the model-free generalised order parameter ($S^2$ = $S^2_f$.S2s) \\
s2f & $S^2_f$, the faster motion model-free generalised order parameter \\
s2s & $S^2_s$, the slower motion model-free generalised order parameter \\
local\_tm & The spin specific global correlation time (seconds) \\
te & Single motion effective internal correlation time (seconds) \\
tf & Faster motion effective internal correlation time (seconds) \\
ts & Slower motion effective internal correlation time (seconds) \\
rex & Chemical exchange relaxation (sigma\_ex = $R_{ex}$ / omega**2) \\
csa & Chemical shift anisotropy (unitless) \\
\bottomrule
\\[-5pt]
\label{table: all model-free parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{N-state model parameters}

Please see Table~\ref{table: N-state parameters} on page~\pageref{table: N-state parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[N-state model parameters.]{N-state model parameters.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Type \\
\midrule
Axx & The Axx component of the alignment tensor & float \\
Ayy & The Ayy component of the alignment tensor & float \\
Axy & The Axy component of the alignment tensor & float \\
Axz & The Axz component of the alignment tensor & float \\
Ayz & The Ayz component of the alignment tensor & float \\
probs & The probabilities of each state & list \\
alpha & The $\alpha$ Euler angles (for the rotation of each state) & list \\
beta & The $\beta$ Euler angles (for the rotation of each state) & list \\
gamma & The $\gamma$ Euler angles (for the rotation of each state) & list \\
paramagnetic\_centre & The paramagnetic centre & list \\
\bottomrule
\\[-5pt]
\label{table: N-state parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameters} on page~\pageref{table: dispersion parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation dispersion parameters.]{Relaxation dispersion parameters.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Type \\
\midrule
r2eff & The effective transversal relaxation rate & dict \\
i0 & The initial intensity & dict \\
r1 & The longitudinal relaxation rate & dict \\
r2 & The transversal relaxation rate & dict \\
r2a & The transversal relaxation rate for state A in the absence of exchange & dict \\
r2$b$ & The transversal relaxation rate for state B in the absence of exchange & dict \\
pA & The population for state A & float \\
pB & The population for state B & float \\
pC & The population for state C & float \\
phi\_ex & The $\phi$\_ex = pA.pB.dw**2 value (ppm\^{}2) & float \\
phi\_ex\_B & The fast exchange factor between sites A and B (ppm\^{}2) & float \\
phi\_ex\_C & The fast exchange factor between sites A and C (ppm\^{}2) & float \\
padw2 & The pA.dw**2 value (ppm\^{}2) & float \\
dw & The chemical shift difference between states A and B (in ppm) & float \\
dw\_AB & The chemical shift difference between states A and B for 3-site exchange (in ppm) & float \\
dw\_AC & The chemical shift difference between states A and C for 3-site exchange (in ppm) & float \\
dw\_BC & The chemical shift difference between states B and C for 3-site exchange (in ppm) & float \\
dwH & The proton chemical shift difference between states A and B (in ppm) & float \\
dwH\_AB & The proton chemical shift difference between states A and B for 3-site exchange (in ppm) & float \\
dwH\_AC & The proton chemical shift difference between states A and C for 3-site exchange (in ppm) & float \\
dwH\_BC & The proton chemical shift difference between states B and C for 3-site exchange (in ppm) & float \\
kex & The exchange rate & float \\
kex\_AB & The exchange rate between sites A and B for 3-site exchange with kex\_AB = $k$\_AB + $k$\_BA (rad.s\^{}-1) & float \\
kex\_AC & The exchange rate between sites A and C for 3-site exchange with kex\_AC = $k$\_AC + $k$\_CA (rad.s\^{}-1) & float \\
kex\_BC & The exchange rate between sites B and C for 3-site exchange with kex\_BC = $k$\_BC + $k$\_CB (rad.s\^{}-1) & float \\
kB & Approximate chemical exchange rate constant between sites A and B (rad.s\^{}-1) & float \\
kC & Approximate chemical exchange rate constant between sites A and C (rad.s\^{}-1) & float \\
tex & The time of exchange (tex = 1/kex) & float \\
k\_AB & The exchange rate from state A to state B & float \\
k\_BA & The exchange rate from state B to state A & float \\
\bottomrule
\\[-5pt]
\label{table: dispersion parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Frame order parameters}

Please see Table~\ref{table: frame order parameters} on page~\pageref{table: frame order parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Frame order parameters.]{Frame order parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
pivot\_x & The pivot point position $x$ coordinate \\
pivot\_y & The pivot point position $y$ coordinate \\
pivot\_z & The pivot point position $z$ coordinate \\
ave\_pos\_x & The average position $x$ translation \\
ave\_pos\_y & The average position $y$ translation \\
ave\_pos\_z & The average position $z$ translation \\
ave\_pos\_alpha & The average position $\alpha$ Euler angle \\
ave\_pos\_beta & The average position $\beta$ Euler angle \\
ave\_pos\_gamma & The average position $\gamma$ Euler angle \\
eigen\_alpha & The Eigenframe $\alpha$ Euler angle \\
eigen\_beta & The Eigenframe $\beta$ Euler angle \\
eigen\_gamma & The Eigenframe $\gamma$ Euler angle \\
axis\_theta & The cone axis polar angle (for the isotropic cone model) \\
axis\_phi & The cone axis azimuthal angle (for the isotropic cone model) \\
axis\_alpha & The rotor axis $\alpha$ angle (the rotation angle out of the xy plane) \\
cone\_theta\_x & The pseudo-ellipse cone opening half-angle for the x-axis \\
cone\_theta\_y & The pseudo-ellipse cone opening half-angle for the y-axis \\
cone\_theta & The isotropic cone opening half-angle \\
cone\_s1 & The isotropic cone order parameter \\
cone\_sigma\_max & The torsion angle \\
\bottomrule
\\[-5pt]
\label{table: frame order parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Prompt examples}

The following commands will generate a map\index{map} of the extended model-free space for model \quotecmd{m5} consisting of the parameters \{$S^2$, $S^2_f$, $\tau_s$\}.  Files will be output into the directory \quotecmd{dx} and will be prefixed by \quotecmd{map}.  In this case, the system is a protein and residue number 6 will be mapped.\index{map}

\begin{lstlisting}[numbers=none]
relax> dx.map(['s2', 's2f', 'ts'], spin_id=':6')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> dx.map(['s2', 's2f', 'ts'], spin_id=':6', file_prefix='map', dir='dx')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> dx.map(params=['s2', 's2f', 'ts'], spin_id=':6', inc=20, file_prefix='map', dir='dx')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> dx.map(params=['s2', 's2f', 'ts'], spin_id=':6', map_type='Iso3D', inc=20, file_prefix='map', dir='dx')
\end{lstlisting}


To map\index{map} the model-free space \quotecmd{m4} for residue 2, spin N6 defined by the parameters \{$S^2$, $\tau_e$, $R_{ex}$\}, name the results \quotecmd{test}, and to place the files in the current directory, use one of the following commands:

\begin{lstlisting}[numbers=none]
relax> dx.map(['s2', 'te', 'rex'], spin_id=':2@N6', file_prefix='test', dir=None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> dx.map(params=['s2', 'te', 'rex'], spin_id=':2@N6', inc=100, file_prefix='test', dir=None)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{eliminate} \label{uf: eliminate}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-delete}

\subsubsection{Synopsis}

Elimination\index{model elimination} or rejection of models.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{eliminate}(\linebreak[0]function=\linebreak[0]None, args=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{function:}  An optional user supplied function for model\index{model elimination} elimination.\index{model elimination}

\hspace{3 mm}\keyword{args:}  A tuple of arguments used by the optional function for model\index{model elimination} elimination.\index{model elimination}


\subsubsection{Description}

This is used for model validation to eliminate or reject models prior to model selection.  Model validation is a part of mathematical modelling\index{modelling} whereby models are either accepted or rejected.

Empirical rules are used for model rejection and are listed below.  However these can be overridden by supplying a function in the prompt and scripting\index{scripting!script file}\index{scripting} modes.  The function should accept five arguments, a string defining a certain parameter, the value of the parameter, the minimisation\index{optimisation} instance (ie the residue index if the model is residue specific), and the function arguments.  If the model is rejected, the function should return True, otherwise it should return False.  The function will be executed multiple times, once for each parameter of the model.

The function arguments should be a tuple, a list enclosed in round brackets, and will be passed to the user supplied function or the inbuilt function.  For a description of the arguments accepted by the inbuilt functions, see below.

Once a model is rejected, the select flag corresponding to that model will be set to False so that model selection, or any other function, will then skip the model.

\subsubsection{Local tm model elimination rule}

The local $\tau_m$, in some cases, may exceed the value expected for a global correlation\index{correlation time} time. Generally the $\tau_m$ value will be stuck at the upper limit\index{parameter!limit} defined for the parameter.  These models are eliminated using the rule:

{\footnotesize \begin{verbatim}
    tm >= c
\end{verbatim}}

The default value of c is 50 ns, although this can be overridden by supplying the value (in seconds) as the first element of the args tuple.

\subsubsection{Internal correlation times {te, tf, ts} model elimination rules}

These parameters may experience the same problem as the local $\tau_m$ in that the model fails and the parameter value is stuck at the upper limit.\index{parameter!limit}  These parameters are constrained using the formula ($\tau_e$, $\tau_f$, $\tau_s$ $\le$ 2$\tau_m$).  These failed models are eliminated using the rule:

{\footnotesize \begin{verbatim}
    te, tf, ts >= c . tm.
\end{verbatim}}

The default value of c is 1.5.  Because of round-off errors and the constraint\index{constraint} algorithm, setting c to 2 will result in no models being eliminated as the minimised\index{optimisation} parameters will always be less than 2$\tau_m$.  The value can be changed by supplying the value as the second element of the tuple.

\subsubsection{Arguments}

The \quotecmd{args} argument must be a tuple of length 2, the elements of which must be numbers.  For example, to eliminate models which have a local $\tau_m$ value greater than 25 ns and models with internal correlation\index{correlation time} times greater than 1.5 times $\tau_m$, set \quotecmd{args} to (25 * 1e-9, 1.5).



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{error\-\_analysis\-.covariance\-\_matrix} \label{uf: error_analysis.covariance_matrix}
\hfill 

\subsubsection{Synopsis}

Parameter error estimation via the covariance matrix.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{error\_analysis.\linebreak[0]covariance\_matrix}(\linebreak[0]epsrel=\linebreak[0]0.0, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{epsrel:}  The parameter to remove linear-dependent columns when J is rank deficient.

\hspace{3 mm}\keyword{verbosity:}  The higher the value, the greater the verbosity.


\subsubsection{Description}

This is a new experimental feature from version 3.3.

This will estimate parameter errors by using the exponential decay Jacobian matrix \quotecmd{J} to compute the covariance matrix of the best-fit parameters.

This can be used to for comparison to Monte-Carlo simulations.

This method is inspired from the GNU Scientific Library (GSL).

The covariance matrix is given by: covar = Qxx = (J\^{}T.W.J)\^{}-1, where the weight matrix W is constructed by the multiplication of an Identity matrix I and a weight array w.  The weight array is 1/errors\^{}2, which then gives W = I.w = I $x$ 1/errors\^{}2.

Qxx is computed by QR decomposition, J\^{}T.W.J=QR, Qxx=R\^{}-1. Q\^{}T.  The columns of $\mathfrak{R}$ which satisfy: |R\_\{kk\}| $\le$ epsrel |R\_\{11\}| are considered linearly-dependent and are excluded from the covariance matrix (the corresponding rows and columns of the covariance matrix are set to zero).

The parameter \quotecmd{epsrel} is used to remove linear-dependent columns when J is rank deficient.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{fix} \label{uf: fix}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/status/object-locked}

\subsubsection{Synopsis}

Fix or allow parameter values to change during optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{fix}(\linebreak[0]element=\linebreak[0]None, fixed=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{element:}  Which element to fix.

\hspace{3 mm}\keyword{fixed:}  A flag specifying if the parameters should be fixed or allowed to change.


\subsubsection{Description}

The element can be any of the following:

\begin{description}
  \item[\quotecmd{diff} --] The diffusion\index{diffusion!tensor} tensor parameters.  This will allow all diffusion\index{diffusion!tensor} tensor parameters to be toggled.
  \item[\quotecmd{all\_spins} --] Using this keyword, all parameters from all spins will be toggled.
  \item[\quotecmd{all} --] All parameters will be toggled.  This is equivalent to combining both \quotecmd{diff} and \quotecmd{all\_spins}.
\end{description}

The flag \quotecmd{fixed}, if set to True, will fix parameters during optimisation whereas a value of False will allow parameters to vary.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.average\-\_position} \label{uf: frame_order.average_position}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill 

\subsubsection{Synopsis}

Define the mechanics of the average domain position.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]average\_position}(\linebreak[0]pivot=\linebreak[0]`com', translation=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pivot:}  The type of pivot to use for the rotation\index{rotation} to the average domain position.  This can be one of \quotecmd{com} or \quotecmd{motional}.

\hspace{3 mm}\keyword{translation:}  A flag specifying if the average domain position should be allowed to translate during optimisation.  If False, then translation can be disabled.


\subsubsection{Description}

Prior to optimisation, the mechanics of the average moving domain position must be specified.  Having the domain shifted to the correct average position is essential for understanding the dynamics as this information is the major contributor to the RDC and PCS.  The motional eigenframe (spherical or Euler\index{Euler angles} angles)\index{angles} and ordering (via order\index{order parameter} parameters, cone angles\index{angles} or torsion angles)\index{angles} come second, and are therefore severely distorted by an incorrect average domain position.

There are two pieces of information affecting this average position - a rotation\index{rotation} and translation.  For the rotation,\index{rotation} a pivot point is required.  Note that this pivot is not related to the pivot of the motions.  However if you believe that your starting structure lies within the uniform distribution of positions of the domain motions, then the two pivots can be linked by setting the average position pivot to the motional pivot.  The default however is to set the pivot to the centre of mass (CoM) of the moving domain.

The second option allows the average domain position to translate during optimisation.  By default, only a rotation\index{rotation} of the initial structure of the domain is rotated to the average position.  But if the rotation\index{rotation} is not sufficient to shift the domain to the average position, then a translation will be required.  This option will be ignored if no PDC data is present, as RDCs do not contain information about the translation of the domain.

\subsubsection{Prompt examples}

To use the centre of mass as the rotational\index{rotation} pivot and to allow translation of the average domain position during optimisation, type one of:

\begin{lstlisting}[numbers=none]
relax> frame_order.translate('com', True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> frame_order.translate(translation=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> frame_order.translate(pivot='com', translation=True)
\end{lstlisting}


To use the motional pivot as the average domain rotational\index{rotation} pivot while disallowing translation of, type one of:

\begin{lstlisting}[numbers=none]
relax> frame_order.translate('motional')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> frame_order.translate('motional', False)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> frame_order.translate(pivot='motional', translation=False)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.num\-\_int\-\_pts} \label{uf: frame_order.num_int_pts}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the number of integration points used in the quasi-random Sobol' sequence\index{sequence} during optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]num\_int\_pts}(\linebreak[0]num=\linebreak[0]200000)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{num:}  The number of integration points to use in the Sobol' sequence\index{sequence} during optimisation.


\subsubsection{Description}

This allows the number of integration points used during the Frame Order target\index{tar} function optimisation to be changed from the default.  This is used in the quasi-random Sobol' sequence\index{sequence} for the numerical integration.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.pdb\-\_model} \label{uf: frame_order.pdb_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create a PDB\index{PDB} file representation of the frame order dynamics.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]pdb\_model}(\linebreak[0]ave\_pos\_file=\linebreak[0]`ave\_pos.\linebreak[0]pdb', rep\_file=\linebreak[0]`frame\_order.\linebreak[0]pdb', dist\_file=\linebreak[0]`domain\_distribution.\linebreak[0]pdb', dir=\linebreak[0]None, size=\linebreak[0]30.0, inc=\linebreak[0]36, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ave\_pos\_file:}  The name of the 3D structure PDB\index{PDB} file for the molecular structure with the moving domains shifted to the average position.

\hspace{3 mm}\keyword{rep\_file:}  The name of the PDB\index{PDB} file for the geometric object representation of the frame order dynamics.

\hspace{3 mm}\keyword{dist\_file:}  The name of the file which will contain multiple models spanning the full dynamics distribution of the frame order model.

\hspace{3 mm}\keyword{dir:}  The directory where the file is to be located.

\hspace{3 mm}\keyword{size:}  The size of the geometric object in \AA.

\hspace{3 mm}\keyword{inc:}  The number of increments used to create the geometric object.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will overwrite the any pre-existing files.


\subsubsection{Description}

This function creates a PDB\index{PDB} file containing an artificial geometric structure representing the Frame Order cone models.

There are four different types of residue within the PDB.\index{PDB}  The pivot point is represented as as a single carbon atom of the residue \quotecmd{PIV}.  The cone consists of numerous H atoms of the residue \quotecmd{CON}.  The cone axis vector is presented as the residue \quotecmd{AXE} with one carbon atom positioned at the pivot and the other $x$ \AA away on the cone axis (set by the geometric object size).  Finally, if Monte Carlo have been performed, there will be multiple \quotecmd{MCC} residues representing the cone for each simulation, and multiple \quotecmd{MCA} residues representing the multiple cone axes.

To create the diffusion in a cone PDB\index{PDB} representation, a uniform distribution of vectors on a sphere\index{diffusion!sphere (isotropic)} is generated using spherical coordinates with the polar angle\index{angles} defined by the cone axis.  By incrementing the polar angle\index{angles} using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle\index{angles} evenly creates the longitudinal vectors.  These are all placed into the PDB\index{PDB} file as H atoms and are all connected using PDB\index{PDB} CONECT records.  Each H atom is connected to its two neighbours on the both the longitude and latitude.  This creates a geometric PDB\index{PDB} object with longitudinal and latitudinal lines representing the filled cone.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.pivot} \label{uf: frame_order.pivot}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill 

\subsubsection{Synopsis}

Set the pivot points for the two body motion in the structural coordinate system.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]pivot}(\linebreak[0]pivot=\linebreak[0]None, order=\linebreak[0]1, fix=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pivot:}  The pivot point for the motion (e.g. the position between the 2 domains in PDB\index{PDB} coordinates).

\hspace{3 mm}\keyword{order:}  The ordinal number of the pivot point.  The value of 1 is for the first pivot point, the value of 2 for the second pivot point, and so on.

\hspace{3 mm}\keyword{fix:}  A flag specifying if the pivot point should be fixed during optimisation.


\subsubsection{Description}

This will set the pivot points for the two domain system within the PDB\index{PDB} coordinate system.  This is required for interpreting PCS data as well as for the generation of cone or other PDB\index{PDB} representations of the domain motions.

This user function can also be used to change the optimisation status of an already set pivot point.  By simply providing the fixed flag and not the pivot point values, the pivot can be changed to be either fixed during optimisation or that it will be optimised.\index{optimise}

\subsubsection{Prompt examples}

To set the pivot point, type one of:

\begin{lstlisting}[numbers=none]
relax> frame_order.pivot([12.067, 14.313, -3.2675])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> frame_order.pivot(pivot=[12.067, 14.313, -3.2675])
\end{lstlisting}


To change an already set and fixed pivot point so that it can now be optimised,\index{optimise} type:

\begin{lstlisting}[numbers=none]
relax> frame_order.pivot(fix=False)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.quad\-\_int} \label{uf: frame_order.quad_int}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Turn the high precision quadratic integration on or off.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]quad\_int}(\linebreak[0]flag=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{flag:}  The flag with if True  will perform high precision numerical integration via the scipy.integrate quad(), dblquad() and tplquad() integration methods rather than the rough quasi-random numerical integration.


\subsubsection{Description}

This allows the high precision numerical integration of the Scipy quad() and related functions to be used instead of the lower precision quasi-random Sobol' sequence\index{sequence} integration.  This is for the optimisation of the Frame Order target\index{tar} functions.  The quadratic integration is orders of magnitude slower than the Sobol' sequence\index{sequence} integration, but the precision is much higher.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.ref\-\_domain} \label{uf: frame_order.ref_domain}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the reference domain for the \quotecmd{2-domain} Frame Order theories.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]ref\_domain}(\linebreak[0]ref=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ref:}  The domain which will act as the frame of reference.  This is only valid for the \quotecmd{2-domain} Frame Order theories.


\subsubsection{Description}

Prior to optimisation of the \quotecmd{2-domain} Frame Order theories, which of the two domains will act as the frame of reference must be specified.  This is important for the attachment of cones to domains, etc.

\subsubsection{Prompt examples}

To set up the isotropic\index{diffusion!sphere (isotropic)} cone frame order model with \quotecmd{centre} domain being the frame of reference, type:

\begin{lstlisting}[numbers=none]
relax> frame_order.ref_domain(ref='centre')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{frame\-\_order\-.select\-\_model} \label{uf: frame_order.select_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Select and set up the Frame Order model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{frame\_order.\linebreak[0]select\_model}(\linebreak[0]model=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The name of the preset Frame Order model.


\subsubsection{Description}

Prior to optimisation, the Frame Order model should be selected.  These models consist of three parameter categories:

\begin{itemize}
  \item[]The average domain position.  This includes the parameters ave\_pos\_alpha, ave\_pos\_beta, and ave\_pos\_gamma.  These Euler\index{Euler angles} angles\index{angles} rotate the tensors from the arbitrary PDB\index{PDB} frame of the moving domain to the average domain position.
  \item[]The frame order eigenframe.  This includes the parameters eigen\_alpha, eigen\_beta, and eigen\_gamma.  These Euler\index{Euler angles} angles\index{angles} define the major modes of motion.  The cone central axis is defined as the z-axis.  The pseudo-elliptic cone $x$ and y-axes are defined as the $x$ and y-axes of the eigenframe.
  \item[]The cone parameters.  These are defined as the tilt-torsion angles\index{angles} cone\_theta\_x, cone\_theta\_y, and cone\_sigma\_max.  The cone\_theta\_x and cone\_theta\_y parameters define the two cone opening angles\index{angles} of the pseudo-ellipse.  The amount of domain torsion is defined as the average domain position, plus and minus cone\_sigma\_max.  The isotropic\index{diffusion!sphere (isotropic)} cones are defined by setting cone\_theta\_x = cone\_theta\_y and converting the single parameter into a 2$^{\mathrm{nd}}$ rank order\index{order parameter} parameter.
\end{itemize}

The list of available models are:

\begin{description}
  \item[\quotecmd{pseudo-ellipse} --] The pseudo-elliptic cone model.  This is the full model consisting of the parameters ave\_pos\_alpha, ave\_pos\_beta, ave\_pos\_gamma, eigen\_alpha, eigen\_beta, eigen\_gamma, cone\_theta\_x, cone\_theta\_y, and cone\_sigma\_max.
  \item[\quotecmd{pseudo-ellipse, torsionless} --] The pseudo-elliptic cone with the torsion angle\index{angles} cone\_sigma\_max set to zero.
  \item[\quotecmd{pseudo-ellipse, free rotor} --] The pseudo-elliptic cone with no torsion angle\index{angles} restriction.
  \item[\quotecmd{iso cone} --] The isotropic\index{diffusion!sphere (isotropic)} cone model.  The cone is defined by a single order\index{order parameter} parameter s1 which is related to the single cone opening angle\index{angles} cone\_theta\_x = cone\_theta\_y.  Due to rotational\index{rotation} symmetry about the cone axis, the average position $\alpha$ Euler\index{Euler angles} angle\index{angles} ave\_pos\_alpha is dropped from the model.  The symmetry also collapses the eigenframe to a single z-axis defined by the parameters axis\_theta and axis\_phi.
  \item[\quotecmd{iso cone, torsionless} --] The isotropic\index{diffusion!sphere (isotropic)} cone model with the torsion angle\index{angles} cone\_sigma\_max set to zero.
  \item[\quotecmd{iso cone, free rotor} --] The isotropic\index{diffusion!sphere (isotropic)} cone model with no torsion angle\index{angles} restriction.
  \item[\quotecmd{line} --] The line cone model.  This is the pseudo-elliptic cone with one of the cone angles,\index{angles} cone\_theta\_y, assumed to be statistically negligible.  I.e. the cone angle\index{angles} is so small that it cannot be distinguished from noise.
  \item[\quotecmd{line, torsionless} --] The line cone model with the torsion angle\index{angles} cone\_sigma\_max set to zero.
  \item[\quotecmd{line, free rotor} --] The line cone model with no torsion angle\index{angles} restriction.
  \item[\quotecmd{rotor} --] The only motion is a rotation\index{rotation} about the cone axis restricted by the torsion angle\index{angles} cone\_sigma\_max.
  \item[\quotecmd{rigid} --] No domain motions.
  \item[\quotecmd{free rotor} --] The only motion is free rotation\index{rotation} about the cone axis.
  \item[\quotecmd{double rotor} --] Restricted motions about two independent rotor axes.
\end{description}

\subsubsection{Prompt examples}

To select the isotropic\index{diffusion!sphere (isotropic)} cone model, type:

\begin{lstlisting}[numbers=none]
relax> frame_order.select_model(model='iso cone')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{grace\-.view\index{software!Grace|textbf}} \label{uf: grace.view}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grace_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grace_icon}

\subsubsection{Synopsis}

Visualise the file within Grace.\index{software!Grace}\index{software!Grace}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{grace.\linebreak[0]view}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]`grace', grace\_exe=\linebreak[0]`xmgrace')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{grace\_exe:}  The Grace\index{software!Grace}\index{software!Grace} executable file.


\subsubsection{Description}

This can be used to view the specified Grace\index{software!Grace}\index{software!Grace} \quotecmd{*.agr} file by opening it with the Grace\index{software!Grace}\index{software!Grace} program.

\subsubsection{Prompt examples}

To view the file \quotecmd{s2.agr} in the directory \quotecmd{grace}, type:

\begin{lstlisting}[numbers=none]
relax> grace.view(file='s2.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.view(file='s2.agr', dir='grace')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{grace\-.write\index{software!Grace|textbf}} \label{uf: grace.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grace_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create a grace\index{software!Grace} \quotecmd{.agr} file to visualise the 2D data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{grace.\linebreak[0]write}(\linebreak[0]x\_data\_type=\linebreak[0]`res\_num', y\_data\_type=\linebreak[0]None, spin\_id=\linebreak[0]None, plot\_data=\linebreak[0]`value', norm\_type=\linebreak[0]`first', file=\linebreak[0]None, dir=\linebreak[0]`grace', force=\linebreak[0]False, norm=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{x\_data\_type:}  The data type for the X-axis (no regular\index{regular expression} expression is allowed).

\hspace{3 mm}\keyword{y\_data\_type:}  The data type for the Y-axis (no regular\index{regular expression} expression is allowed).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.

\hspace{3 mm}\keyword{plot\_data:}  The data to use for the plot.\index{plot}

\hspace{3 mm}\keyword{norm\_type:}  How the graph should be normalised, if the norm flag is set.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the file to be overwritten.

\hspace{3 mm}\keyword{norm:}  A flag which, if set to True, will cause all graphs to be normalised to 1.  This is for the normalisation of series type data.  The point for normalisation is set with the norm\_type argument.


\subsubsection{Description}

This is designed to be as flexible as possible so that any combination of data can be plotted.\index{plot}  The output is in the format of a Grace\index{software!Grace}\index{software!Grace} plot\index{plot} (also known as ACE/gr, Xmgr, and xmgrace) which only supports two dimensional plots.\index{plot}  Three types of information can be used to create various types of plot.\index{plot}  These include the x-axis and y-axis data types, the spin ID string, and the type of data plot.\index{plot}

The x-axis and y-axis data types should be plain strings, regular\index{regular expression} expression is not allowed.  The two axes of the Grace\index{software!Grace}\index{software!Grace} plot\index{plot} can be any of the data types listed in the tables below.  The only limitation\index{parameter!limit} is that the data must belong to the same data pipe.

If the x-axis data type is not given, the plot\index{plot} will default to having the residue numbering along the x-axis.Two special data types for the axes are:

\begin{description}
  \item[\quotecmd{res\_num} --] The axis will consist of the residue numbering.
  \item[\quotecmd{spin\_num} --] The axis will consist of the spin numbering.
\end{description}

The spin ID string can be used to limit\index{parameter!limit} which spins are used in the plot.\index{plot}  The default is that all spins will be used, however, the ID string can be used to select a subset of all spins, or a single spin for plots\index{plot} of Monte Carlo simulations, etc.

The property which is actually plotted\index{plot} can be controlled by the plot\index{plot} data setting.  This can be one of the following:

\begin{description}
  \item[\quotecmd{value} --] Plot\index{plot} values (with errors if they exist).
  \item[\quotecmd{error} --] Plot\index{plot} errors.
  \item[\quotecmd{sims} --] Plot\index{plot} the simulation values.
\end{description}

Normalisation is only allowed for series type data, for example the R$_2$ exponential curves, and will be ignored for all other data types.  If the norm flag is set to True then the y-value of the first point of the series will be set to 1.  This normalisation is useful for highlighting errors in the data sets.

\subsubsection{Relaxation curve fitting parameters}

Please see Table~\ref{table: curve-fit parameters and min stats} on page~\pageref{table: curve-fit parameters and min stats}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation curve fitting parameters and minimisation statistics.]{Relaxation curve fitting parameters and minimisation statistics.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
rx & Either the R$_1$ or R$_2$ relaxation rate \\
i0 & The initial intensity \\
iinf & The intensity at infinity \\
chi2 & Chi-squared value \\
iter & Optimisation iterations \\
f\_count & Number of function calls \\
g\_count & Number of gradient calls \\
h\_count & Number of Hessian calls \\
warning & Optimisation warning \\
\bottomrule
\\[-5pt]
\label{table: curve-fit parameters and min stats}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Steady-state NOE parameters}

Please see Table~\ref{table: NOE parameters} on page~\pageref{table: NOE parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Steady-state NOE parameters.]{Steady-state NOE parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
noe & The steady-state NOE value \\
\bottomrule
\\[-5pt]
\label{table: NOE parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Model-free parameters}

Please see Table~\ref{table: model-free parameters and min stats} on page~\pageref{table: model-free parameters and min stats}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Model-free parameters and minimisation statistics.]{Model-free parameters and minimisation statistics.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
s2 & $S^2$, the model-free generalised order parameter ($S^2$ = $S^2_f$.S2s) \\
s2f & $S^2_f$, the faster motion model-free generalised order parameter \\
s2s & $S^2_s$, the slower motion model-free generalised order parameter \\
local\_tm & The spin specific global correlation time (seconds) \\
te & Single motion effective internal correlation time (seconds) \\
tf & Faster motion effective internal correlation time (seconds) \\
ts & Slower motion effective internal correlation time (seconds) \\
rex & Chemical exchange relaxation (sigma\_ex = $R_{ex}$ / omega**2) \\
csa & Chemical shift anisotropy (unitless) \\
\bottomrule
\\[-5pt]
\label{table: model-free parameters and min stats}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Reduced spectral density mapping parameters}

Please see Table~\ref{table: J(w) parameters} on page~\pageref{table: J(w) parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Reduced spectral density mapping parameters.]{Reduced spectral density mapping parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
j0 & Spectral density value at 0 MHz - $J(0)$ \\
jwx & Spectral density value at the frequency of the heteronucleus - $J(\omega_X)$ \\
jwh & Spectral density value at the frequency of the proton - $J(\omega_H)$ \\
csa & Chemical shift anisotropy (unitless) \\
\bottomrule
\\[-5pt]
\label{table: J(w) parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Consistency testing parameters}

Please see Table~\ref{table: consistency testing parameters} on page~\pageref{table: consistency testing parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Consistency testing parameters.]{Consistency testing parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
j0 & Spectral density value at 0 MHz (from Farrow et al. (1995) JBNMR, 6: 153-162) \\
f\_eta & Eta-test (from Fushman et al. (1998) JACS, 120: 10947-10952) \\
f\_r2 & R2-test (from Fushman et al. (1998) JACS, 120: 10947-10952) \\
csa & Chemical shift anisotropy (unitless) \\
orientation & Angle between the 15N-1H vector and the principal axis of the 15N chemical shift tensor \\
tc & The single global correlation time estimate/approximation \\
\bottomrule
\\[-5pt]
\label{table: consistency testing parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameters and min stats} on page~\pageref{table: dispersion parameters and min stats}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation dispersion parameters and minimisation statistics.]{Relaxation dispersion parameters and minimisation statistics.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
r2eff & The effective transversal relaxation rate \\
i0 & The initial intensity \\
r1 & The longitudinal relaxation rate \\
r2 & The transversal relaxation rate \\
r2a & The transversal relaxation rate for state A in the absence of exchange \\
r2$b$ & The transversal relaxation rate for state B in the absence of exchange \\
pA & The population for state A \\
pB & The population for state B \\
pC & The population for state C \\
phi\_ex & The $\phi$\_ex = pA.pB.dw**2 value (ppm\^{}2) \\
phi\_ex\_B & The fast exchange factor between sites A and B (ppm\^{}2) \\
phi\_ex\_C & The fast exchange factor between sites A and C (ppm\^{}2) \\
padw2 & The pA.dw**2 value (ppm\^{}2) \\
dw & The chemical shift difference between states A and B (in ppm) \\
dw\_AB & The chemical shift difference between states A and B for 3-site exchange (in ppm) \\
dw\_AC & The chemical shift difference between states A and C for 3-site exchange (in ppm) \\
dw\_BC & The chemical shift difference between states B and C for 3-site exchange (in ppm) \\
dwH & The proton chemical shift difference between states A and B (in ppm) \\
dwH\_AB & The proton chemical shift difference between states A and B for 3-site exchange (in ppm) \\
dwH\_AC & The proton chemical shift difference between states A and C for 3-site exchange (in ppm) \\
dwH\_BC & The proton chemical shift difference between states B and C for 3-site exchange (in ppm) \\
kex & The exchange rate \\
kex\_AB & The exchange rate between sites A and B for 3-site exchange with kex\_AB = $k$\_AB + $k$\_BA (rad.s\^{}-1) \\
kex\_AC & The exchange rate between sites A and C for 3-site exchange with kex\_AC = $k$\_AC + $k$\_CA (rad.s\^{}-1) \\
kex\_BC & The exchange rate between sites B and C for 3-site exchange with kex\_BC = $k$\_BC + $k$\_CB (rad.s\^{}-1) \\
kB & Approximate chemical exchange rate constant between sites A and B (rad.s\^{}-1) \\
kC & Approximate chemical exchange rate constant between sites A and C (rad.s\^{}-1) \\
tex & The time of exchange (tex = 1/kex) \\
k\_AB & The exchange rate from state A to state B \\
k\_BA & The exchange rate from state B to state A \\
chi2 & Chi-squared value \\
iter & Optimisation iterations \\
f\_count & Number of function calls \\
g\_count & Number of gradient calls \\
h\_count & Number of Hessian calls \\
warning & Optimisation warning \\
\bottomrule
\\[-5pt]
\label{table: dispersion parameters and min stats}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Prompt examples}

To write\index{write} the NOE values for all spins to the Grace\index{software!Grace}\index{software!Grace} file \quotecmd{noe.agr}, type one of:

\begin{lstlisting}[numbers=none]
relax> grace.write('res_num', 'noe', file='noe.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.write(y_data_type='noe', file='noe.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.write(x_data_type='res_num', y_data_type='noe', file='noe.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.write(y_data_type='noe', file='noe.agr', force=True)
\end{lstlisting}


To create a Grace\index{software!Grace}\index{software!Grace} file of \quotecmd{s2} vs. \quotecmd{te} for all spins, type one of:

\begin{lstlisting}[numbers=none]
relax> grace.write('s2', 'te', file='s2_te.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.write(x_data_type='s2', y_data_type='te', file='s2_te.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.write(x_data_type='s2', y_data_type='te', file='s2_te.agr', force=True)
\end{lstlisting}


To create a Grace\index{software!Grace}\index{software!Grace} file of the Monte Carlo simulation values of \quotecmd{rex} vs. \quotecmd{te} for residue 123, type one of:

\begin{lstlisting}[numbers=none]
relax> grace.write('rex', 'te', spin_id=':123', plot_data='sims', file='s2_te.agr')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> grace.write(x_data_type='rex', y_data_type='te', spin_id=':123', plot_data='sims', file='s2_te.agr')
\end{lstlisting}


By plotting\index{plot} the peak intensities, the integrity of exponential relaxation\index{relaxation} curves can be checked and anomalies searched for prior to model-free analysis or reduced spectral density mapping.\index{map}  For example the normalised average peak intensities can be plotted\index{plot} verses the relaxation\index{relaxation} time periods for the relaxation\index{relaxation} curves of all residues of a protein.  The normalisation, whereby the initial peak intensity of each residue I(0) is set to 1, emphasises any problems.  To produce this Grace\index{software!Grace}\index{software!Grace} file, type:

\begin{lstlisting}[numbers=none]
relax> grace.write(x_data_type='relax_times', y_data_type='ave_int', file='intensities_norm.agr', force=True, norm=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{interatom\-.copy} \label{uf: interatom.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/dipole_pair} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} all data associated with a interatomic data container.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{interatom.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, spin\_id1=\linebreak[0]None, spin\_id2=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The data pipe containing the interatomic data container from which the data will be copied.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{pipe\_to:}  The data pipe to copy\index{copy} the interatomic data container to.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{spin\_id1:}  The spin ID of the first spin.

\hspace{3 mm}\keyword{spin\_id2:}  The spin ID of the first spin.


\subsubsection{Description}

This will copy\index{copy} all the data associated with the identified interatomic data container to a different data pipe.  The new interatomic data container must not already exist.

\subsubsection{Prompt examples}

To copy\index{copy} the interatomic data container between \quotecmd{:2@C} and \quotecmd{:2@H}, from the \quotecmd{orig} data pipe to the current data pipe, type one of:

\begin{lstlisting}[numbers=none]
relax> interatom.copy('orig', spin_id1=':2@C', spin_id2=':2@H')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.copy(pipe_from='orig', spin_id1=':2@C', spin_id2=':2@H')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{interatom\-.define} \label{uf: interatom.define}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/dipole_pair} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Define interatomic interactions between pairs of spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{interatom.\linebreak[0]define}(\linebreak[0]spin\_id1=\linebreak[0]`@N', spin\_id2=\linebreak[0]`@H', direct\_bond=\linebreak[0]True, spin\_selection=\linebreak[0]True, pipe=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id1:}  The spin ID string for the first spin of the interatomic interaction.

\hspace{3 mm}\keyword{spin\_id2:}  The spin ID string for the second spin of the interatomic interaction.

\hspace{3 mm}\keyword{direct\_bond:}  This is a flag which if True means that the two spins are directly bonded.  This flag is useful to simplify the set up of the main heteronuclear relaxation\index{relaxation} mechanism or one-bond residual dipolar couplings.

\hspace{3 mm}\keyword{spin\_selection:}  Define the interatomic data container selection based on the spin selection.  If either spin is deselected, the interatomic container will also be deselected.  Otherwise the container will be selected.

\hspace{3 mm}\keyword{pipe:}  The data pipe to create the interatomic data container for.  This defaults to the current data pipe if not supplied.


\subsubsection{Description}

To analyse relaxation\index{relaxation} or residual dipolar coupling (RDC) data, for example, pairs of spins which are coupled need to be defined.  This can be via the magnetic dipole-dipole interaction or scalar coupling interaction.  This function will create an interatomic data object connecting two existing spins.  This data container will be used to store all information about the interactomic interaction including interatomic vectors and distances.

For analyses which use relaxation\index{relaxation} data, simply defining the interatomic interaction will indicate that there is a dipolar relaxation\index{relaxation} mechanism operating between the two spins.  Note that for model-free analyses or reduced spectral density mapping,\index{map} only a single relaxation\index{relaxation} mechanism can be handled.  For RDC dependent analyses, the presence of the interatomic interaction indicates that dipolar coupling is expected between the two spins.

If the spin selection flag is set, then the newly created interatomic data container will be selected based on the current selection status of the two spins defining the interaction.  If either of the spins are deselected, then the new interatomic data container will also be deselected.  If both spins are selected, then the interatomic data container will also be selected.

\subsubsection{Prompt examples}

To connect the spins \quotecmd{:1@N} to \quotecmd{:1@H}, type one of:

\begin{lstlisting}[numbers=none]
relax> interatom.define(':1@N', ':1@H')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.define(spin_id1=':1@N', spin_id2=':1@H')
\end{lstlisting}


To define the protein 15N heteronuclear relaxation\index{relaxation} mechanism for a model-free analysis, type one of the following:

\begin{lstlisting}[numbers=none]
relax> interatom.define('@N', '@H', True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.define(spin_id1='@N', spin_id2='@H', direct_bond=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{interatom\-.read\-\_dist} \label{uf: interatom.read_dist}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/dipole_pair} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} inter-spin distances from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{interatom.\linebreak[0]read\_dist}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, unit=\linebreak[0]`meter', spin\_id1\_col=\linebreak[0]1, spin\_id2\_col=\linebreak[0]2, data\_col=\linebreak[0]3, sep=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the averaged distance data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{unit:}  The unit of distance.  The default is meter, but \AA can also be specified.

\hspace{3 mm}\keyword{spin\_id1\_col:}  The spin ID string column for the first spin.

\hspace{3 mm}\keyword{spin\_id2\_col:}  The spin ID string column for the second spin.

\hspace{3 mm}\keyword{data\_col:}  The distance data column.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).


\subsubsection{Description}

This allows interatomic distances to be read\index{read} from a file.  This is useful in the case when the distances vary, avoiding having to tediously use the interatom.set\_dist user function for each spin-pair separately.  The format of the file should be columnar, with the two spin ID strings in two separate columns and the distances in any other.  The default measurement unit is meter but this can be changed to \AA.

For RDC and relaxation\index{relaxation} based analyses, as the magnetic dipole-dipole interaction is averaged in NMR\index{NMR} over the interatomic distance to the inverse third power, the interatomic distances within a 3D structural file are of no use for defining the interaction.  Therefore these $r$\^{}-3 average distances must be explicitly defined.

\subsubsection{Prompt examples}

To load the distances in meters from the fifth column of the \quotecmd{distances} file, and where the spin IDs are in the first and second columns, type one of the following:

\begin{lstlisting}[numbers=none]
relax> interatom.read_dist('distances', 1, 2, 5)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.read_dist(file='distances', unit='meter', spin_id1_col=1, spin_id2_col=2, data_col=5)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{interatom\-.set\-\_dist} \label{uf: interatom.set_dist}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/dipole_pair} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the inter-spin distances.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{interatom.\linebreak[0]set\_dist}(\linebreak[0]spin\_id1=\linebreak[0]`@N', spin\_id2=\linebreak[0]`@H', ave\_dist=\linebreak[0]1.0200000000000001e-10, unit=\linebreak[0]`meter')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id1:}  The spin identification string for the first spin of the dipole pair.

\hspace{3 mm}\keyword{spin\_id2:}  The spin identification string for the second spin of the dipole pair.

\hspace{3 mm}\keyword{ave\_dist:}  The $r$\^{}-3 averaged distance between the two spins to be used in the magnetic dipole constant, defaulting to meters.

\hspace{3 mm}\keyword{unit:}  The unit of distance (the default is \quotecmd{meter}).


\subsubsection{Description}

For many NMR\index{NMR} interactions, the distance between the spin of interest and another spin or atom must be defined.  This information can be extracted from a 3D structure but, in many cases, these distances are not of interest.  For example the empirical or fixed distance calculation of proton positions in X-ray crystallographic structures will often not correspond to the real interatomic distances.

Another example is the magnetic dipole-dipole interaction which is averaged over the interatomic distance to the inverse third power.  In this case, the interatomic distances from any 3D structural file can be of no use for defining the interaction.  The average distances must be explicitly supplied.  This user function allows these distances to be set up.  The default measurement unit is meter but this can be changed to \AA.  Alternatively the distances can be read\index{read} from a file using other user functions in this class.

\subsubsection{Prompt examples}

To set the N-H distance for protein the 15N heteronuclear relaxation\index{relaxation} mechanism to 1.02 \AA, type one of the following:

\begin{lstlisting}[numbers=none]
relax> interatom.set_dist('@N', '@H', 1.02 * 1e-10)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.set_dist(spin_id1='@N', spin_id2='@H', ave_dist=1.02 * 1e-10, unit='meter')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.set_dist(spin_id1='@N', spin_id2='@H', ave_dist=1.02, unit='Angstrom')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{interatom\-.unit\-\_vectors} \label{uf: interatom.unit_vectors}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/dipole_pair} \hfill 

\subsubsection{Synopsis}

Calculate the unit vectors for all interatomic interactions.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{interatom.\linebreak[0]unit\_vectors}(\linebreak[0]ave=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ave:}  A flag which if True will cause the bond vectors from all models to be averaged.  If vectors from only one model is extracted, this will have no effect.


\subsubsection{Description}

For an orientational dependent analysis, such as model-free analysis with the spheroidal\index{diffusion!spheroid (axially symmetric)} and ellipsoidal\index{diffusion!ellipsoid (asymmetric)} global diffusion\index{diffusion!tensor} tensors or any analysis using RDCs, the unit vectors between the two dipoles must be calculated prior to starting the analysis.  For the unit vector extraction, the two interacting spins should already possess positional information and the dipole-dipole interaction should already be defined via the interatom.define user function.  This information will be used to calculate unit vectors between the two spins.  Without positional information from a 3D structure, no vectors can be calculated and an orientational dependent analysis will not be possible.

The number of unit vectors per interaction will be defined by the number of positions each spin possesses together with the averaging flag.  If both spins have N and M positions loaded, the number of positions for both must match (N=M).  In this case, as well as when one spin has N positions and the other a single position, then N unit vectors will be calculated.  This is unless the averaging flag is set in which case an averaged vector of unit length will be calculated.

\subsubsection{Prompt examples}

To calculate the unit vectors prior to a model-free analysis, type one of the following:

\begin{lstlisting}[numbers=none]
relax> interatom.unit_vectors(True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> interatom.unit_vectors(ave=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{j\-\_coupling\-.copy} \label{uf: j_coupling.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/j_coupling} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} J coupling data from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{j\_coupling.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the pipe to copy\index{copy} the J coupling data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the pipe to copy\index{copy} the J coupling data to.


\subsubsection{Description}

This function will copy\index{copy} J coupling data from one pipe to another.

\subsubsection{Prompt examples}

To copy\index{copy} all J coupling data from pipe \quotecmd{DMSO} to pipe \quotecmd{CDCl3}, type one of:

\begin{lstlisting}[numbers=none]
relax> j_coupling.copy('DMSO', 'CDCl3')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> j_coupling.copy(pipe_from='DMSO', pipe_to='CDCl3')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{j\-\_coupling\-.delete} \label{uf: j_coupling.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/j_coupling} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} the J coupling values.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{j\_coupling.\linebreak[0]delete}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will delete\index{delete} all J coupling data in the current data pipe.

\subsubsection{Prompt examples}

To delete\index{delete} all J coupling data, type:

\begin{lstlisting}[numbers=none]
relax> j_coupling.delete()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{j\-\_coupling\-.display} \label{uf: j_coupling.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/j_coupling} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the J coupling data in the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{j\_coupling.\linebreak[0]display}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will display\index{display} all of the J coupling data in the current data pipe.

\subsubsection{Prompt examples}

To display\index{display} all J coupling data, type:

\begin{lstlisting}[numbers=none]
relax> j_coupling.display()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{j\-\_coupling\-.read} \label{uf: j_coupling.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/j_coupling} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} the J coupling data from file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{j\_coupling.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id1\_col=\linebreak[0]1, spin\_id2\_col=\linebreak[0]2, data\_col=\linebreak[0]None, error\_col=\linebreak[0]None, sign\_col=\linebreak[0]None, sep=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the J coupling data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id1\_col:}  The spin ID string column for the first spin.

\hspace{3 mm}\keyword{spin\_id2\_col:}  The spin ID string column for the second spin.

\hspace{3 mm}\keyword{data\_col:}  The J coupling data column.

\hspace{3 mm}\keyword{error\_col:}  The experimental error column.

\hspace{3 mm}\keyword{sign\_col:}  A special column holding the sign of the J coupling, being either 1 or -1, in case this data is obtained separately.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).


\subsubsection{Description}

This will read\index{read} J coupling data from a file.  If the sign of the J coupling has been determined by a different experiment, this information can be present in a different column having either the value of 1 or -1.

\subsubsection{Prompt examples}

The following commands will read\index{read} the J coupling data out of the file \quotecmd{J.txt} where the columns are separated by the symbol \quotecmd{,}:

\begin{lstlisting}[numbers=none]
relax> j_coupling.read('J.txt', sep=',')
\end{lstlisting}


If the individual spin J coupling errors are located in the file \quotecmd{j\_err.txt} in column number 5 then, to read\index{read} these values into relax, type one of:

\begin{lstlisting}[numbers=none]
relax> j_coupling.read('j_err.txt', error_col=5)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> j_coupling.read(file='j_err.txt', error_col=5)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{j\-\_coupling\-.write} \label{uf: j_coupling.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/j_coupling} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} the J coupling data to file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{j\_coupling.\linebreak[0]write}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

This will write\index{write} the J coupling values to file.  If no directory name is given, the file will be placed in the current working directory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{jw\-\_mapping\-.set\-\_frq} \label{uf: jw_mapping.set_frq}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/jw_mapping} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frq}

\subsubsection{Synopsis}

Select which relaxation\index{relaxation} data to use in the $J(\omega)$ mapping\index{map} by NMR\index{NMR} spectrometer frequency.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{jw\_mapping.\linebreak[0]set\_frq}(\linebreak[0]frq=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{frq:}  The spectrometer frequency in Hz.  This must match the currently loaded data to the last decimal point.  See the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file.


\subsubsection{Description}

This will select the relaxation\index{relaxation} data to use in the reduced spectral density mapping\index{map} corresponding to the given frequency.  The data is selected by the spectrometer frequency in Hertz, which should be set to the exact value (see the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file).  Note thought that the R$_1$, R$_2$ and NOE are all expected to have the exact same frequency in the $J(\omega)$ mapping\index{map} analysis (to the last decimal point).

\subsubsection{Prompt examples}

\begin{lstlisting}[numbers=none]
relax> jw_mapping.set_frq(600.0 * 1e6)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> jw_mapping.set_frq(frq=600.0 * 1e6)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{minimise\-.calculate\index{optimisation|textbf}} \label{uf: minimise.calculate}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/rosenbrock} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the model parameters or the current target\index{tar} function value.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{minimise.\linebreak[0]calculate}(\linebreak[0]verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print to screen.  Zero corresponds to minimal output while higher values increase the amount of output.  The default value is 1.


\subsubsection{Description}

The operation of this user function is two-fold and depends on whether the solution for the models of the current analysis are found by direct calculation or by optimisation.  The dual operations are:

\begin{description}
  \item[Direct calculation models --] For these models, the parameters will be directly calculated from the base data.  This will be the exact solution and the user function will store the parameter values.  The grid search and optimisation user functions are not implemented for this analysis type.
  \item[Optimised\index{optimise} models --] This will call the target\index{tar} function normally used for optimisation for each model using the current parameter values.  This can be used to manually find the chi-squared\index{chi-squared} value for different parameter values.  The parameter values will not be affected.
\end{description}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{minimise\-.execute\index{optimisation|textbf}} \label{uf: minimise.execute}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/rosenbrock} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/rosenbrock}

\subsubsection{Synopsis}

Perform an optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{minimise.\linebreak[0]execute}(\linebreak[0]min\_algor=\linebreak[0]`newton', line\_search=\linebreak[0]None, hessian\_mod=\linebreak[0]None, hessian\_type=\linebreak[0]None, func\_tol=\linebreak[0]1e-25, grad\_tol=\linebreak[0]None, max\_iter=\linebreak[0]10000000, constraints=\linebreak[0]True, scaling=\linebreak[0]True, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{min\_algor:}  The optimisation algorithm to use.

\hspace{3 mm}\keyword{line\_search:}  The line search algorithm which will only be used in combination with the line search and conjugate\index{optimisation!algorithm!conjugate gradient} gradient methods.  This will default to the More and Thuente line search.

\hspace{3 mm}\keyword{hessian\_mod:}  The Hessian modification.  This will only be used in the algorithms which use the Hessian, and defaults to Gill, Murray, and Wright modified Cholesky algorithm.

\hspace{3 mm}\keyword{hessian\_type:}  The Hessian type.  This will only be used in a few trust region algorithms, and defaults to BFGS.\index{optimisation!algorithm!BFGS}

\hspace{3 mm}\keyword{func\_tol:}  The function tolerance.  This is used to terminate minimisation\index{optimisation} once the function value between iterations is less than the tolerance.  The default value is 1e-25.

\hspace{3 mm}\keyword{grad\_tol:}  The gradient tolerance.  Minimisation\index{optimisation} is terminated if the current gradient value is less than the tolerance.  The default value is None.

\hspace{3 mm}\keyword{max\_iter:}  The maximum number of iterations.  The default value is 1e7.

\hspace{3 mm}\keyword{constraints:}  A boolean flag specifying whether the parameters should be constrained.  The default is to turn constraints\index{constraint} on (constraints=True).

\hspace{3 mm}\keyword{scaling:}  The diagonal scaling boolean flag.  The default that scaling is on (scaling=True).

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print to screen.  Zero corresponds to minimal output while higher values increase the amount of output.  The default value is 1.


\subsubsection{Description}

This will perform an optimisation starting from the current parameter values.  This is only suitable for data pipe types which have target\index{tar} functions and hence support optimisation.

\subsubsection{Diagonal scaling}

Diagonal scaling is the transformation of parameter values such that each value has a similar order of magnitude.  Certain minimisation\index{optimisation} techniques, for example the trust region methods, perform extremely poorly with badly scaled problems.  In addition, methods which are insensitive to scaling such as Newton\index{optimisation!algorithm!Newton} minimisation\index{optimisation} may still benefit due to the minimisation\index{optimisation} of round off errors.

In Model-free analysis for example, if $S^2$ = 0.5, $\tau_e$ = 200 ps, and $R_{ex}$ = 15 1/s at 600 MHz, the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18].  $R_{ex}$ is divided by (2 * $\pi$ * 600,000,000)**2 to make it field strength independent.  The scaling vector for this model may be something like [1.0, 1e-9, 1/(2 * $\pi$ * 6e8)**2].  By dividing the unscaled parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0].  To revert to the original unscaled parameter vector, the scaled parameter vector and scaling vector are multiplied.

\subsubsection{Minimisation algorithms}

A minimisation\index{optimisation} function is selected if the minimisation\index{optimisation} algorithm matches a certain pattern.  Because the python\index{Python} regular\index{regular expression} expression \quotecmd{match} statement is used, various strings can be supplied to select the same minimisation\index{optimisation} algorithm.  Below is a list of the minimisation\index{optimisation} algorithms available together with the corresponding patterns.

This is a short description of python\index{Python} regular\index{regular expression} expression, for more information, see the regular\index{regular expression} expression syntax section of the Python\index{Python} Library Reference.  Some of the regular\index{regular expression} expression syntax used in this function is:

\begin{description}
  \item[\quotecmd{[]} --] A sequence\index{sequence} or set of characters to match to a single character.  For example, \quotecmd{[Nn]ewton} will match both \quotecmd{Newton} and \quotecmd{newton}.
  \item[\quotecmd{\^{}} --] Match the start of the string.
  \item[\quotecmd{\$} --] Match the end of the string.  For example, \quotecmd{\^{}[Ll][Mm]\$} will match \quotecmd{lm} and \quotecmd{LM} but will not match if characters are placed either before or after these strings.
\end{description}

To select a minimisation\index{optimisation} algorithm, use a string which matches one of the following patterns given in the tables.

Unconstrained line search methods:

Please see Table~\ref{table: min - line search} on page~\pageref{table: min - line search}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation algorithms -- unconstrained line search methods.]{Minimisation algorithms -- unconstrained line search methods.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Minimisation algorithm & Patterns \\
\midrule
Back-and-forth coordinate descent & '\^{}[Cc][Dd]\$' or '\^{}[Cc]oordinate[ \_-][Dd]escent\$' \\
Steepest descent & '\^{}[Ss][Dd]\$' or '\^{}[Ss]teepest[ \_-][Dd]escent\$' \\
Quasi-Newton BFGS & '\^{}[Bb][Ff][Gg][Ss]\$' \\
Newton & '\^{}[Nn]ewton\$' \\
Newton-CG & '\^{}[Nn]ewton[ \_-][Cc][Gg]\$' or '\^{}[Nn][Cc][Gg]\$' \\
\bottomrule
\\[-5pt]
\label{table: min - line search}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Unconstrained trust-region methods:

Please see Table~\ref{table: min - trust-region} on page~\pageref{table: min - trust-region}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation algorithms -- unconstrained trust-region methods.]{Minimisation algorithms -- unconstrained trust-region methods.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Minimisation algorithm & Patterns \\
\midrule
Cauchy point & '\^{}[Cc]auchy' \\
Dogleg & '\^{}[Dd]ogleg' \\
CG-Steihaug & '\^{}[Cc][Gg][-\_ ][Ss]teihaug' or '\^{}[Ss]teihaug' \\
Exact trust region & '\^{}[Ee]xact' \\
\bottomrule
\\[-5pt]
\label{table: min - trust-region}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Unconstrained conjugate\index{optimisation!algorithm!conjugate gradient} gradient methods:

Please see Table~\ref{table: min - conjugate gradient} on page~\pageref{table: min - conjugate gradient}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation algorithms -- unconstrained conjugate gradient methods.]{Minimisation algorithms -- unconstrained conjugate gradient methods.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Minimisation algorithm & Patterns \\
\midrule
Fletcher-Reeves & '\^{}[Ff][Rr]\$' or '\^{}[Ff]letcher[-\_ ][Rr]eeves\$' \\
Polak-Ribiere & '\^{}[Pp][Rr]\$' or '\^{}[Pp]olak[-\_ ][Rr]ibiere\$' \\
Polak-Ribi\`ere + & '\^{}[Pp][Rr]$\backslash$+\$' or '\^{}[Pp]olak[-\_ ][Rr]ibiere$\backslash$+\$' \\
Hestenes-Stiefel & '\^{}[Hh][Ss]\$' or '\^{}[Hh]estenes[-\_ ][Ss]tiefel\$' \\
\bottomrule
\\[-5pt]
\label{table: min - conjugate gradient}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Miscellaneous unconstrained methods:

Please see Table~\ref{table: min - misc} on page~\pageref{table: min - misc}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation algorithms -- miscellaneous unconstrained methods.]{Minimisation algorithms -- miscellaneous unconstrained methods.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Minimisation algorithm & Patterns \\
\midrule
Simplex & '\^{}[Ss]implex\$' \\
Levenberg-Marquardt & '\^{}[Ll][Mm]\$' or '\^{}[Ll]evenburg-[Mm]arquardt\$' \\
\bottomrule
\\[-5pt]
\label{table: min - misc}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Global minimisation\index{optimisation} methods:

Please see Table~\ref{table: min - global} on page~\pageref{table: min - global}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation algorithms -- global minimisation methods.]{Minimisation algorithms -- global minimisation methods.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Minimisation algorithm & Patterns \\
\midrule
Simulated Annealing & '\^{}[Ss][Aa]\$' or '\^{}[Ss]imulated [Aa]nnealing\$' \\
\bottomrule
\\[-5pt]
\label{table: min - global}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Minimisation options}

The minimisation\index{optimisation} options can be given in any order.

Line search algorithms.  These are used in the line search methods and the conjugate\index{optimisation!algorithm!conjugate gradient} gradient methods.  The default is the Backtracking line search.  The algorithms are:

Please see Table~\ref{table: min sub-algor - line search} on page~\pageref{table: min sub-algor - line search}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation sub-algorithms -- line search algorithms.]{Minimisation sub-algorithms -- line search algorithms.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Line search algorithm & Patterns \\
\midrule
Backtracking line search & '\^{}[Bb]ack' \\
Nocedal and Wright interpolation based line search & '\^{}[Nn][Ww][Ii]' or '\^{}[Nn]ocedal[ \_][Ww]right[ \_][Ii]nt' \\
Nocedal and Wright line search for the Wolfe conditions & '\^{}[Nn][Ww][Ww]' or '\^{}[Nn]ocedal[ \_][Ww]right[ \_][Ww]olfe' \\
More and Thuente line search & '\^{}[Mm][Tt]' or '\^{}[Mm]ore[ \_][Tt]huente\$' \\
No line search & '\^{}[Nn]o [Ll]ine [Ss]earch\$' \\
\bottomrule
\\[-5pt]
\label{table: min sub-algor - line search}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Hessian modifications.  These are used in the Newton,\index{optimisation!algorithm!Newton} Dogleg,\index{optimisation!algorithm!dogleg} and Exact\index{optimisation!algorithm!exact trust region} trust region algorithms:

Please see Table~\ref{table: min sub-algor - Hessian mod} on page~\pageref{table: min sub-algor - Hessian mod}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation sub-algorithms -- Hessian modifications.]{Minimisation sub-algorithms -- Hessian modifications.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Hessian modification & Patterns \\
\midrule
Unmodified Hessian & '\^{}[Nn]o [Hh]essian [Mm]od' \\
Eigenvalue modification & '\^{}[Ee]igen' \\
Cholesky with added multiple of the identity & '\^{}[Cc]hol' \\
The Gill, Murray, and Wright modified Cholesky algorithm & '\^{}[Gg][Mm][Ww]\$' \\
The Schnabel and Eskow 1999 algorithm & '\^{}[Ss][Ee]99' \\
\bottomrule
\\[-5pt]
\label{table: min sub-algor - Hessian mod}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Hessian type, these are used in a few of the trust region methods including the Dogleg\index{optimisation!algorithm!dogleg} and Exact\index{optimisation!algorithm!exact trust region} trust region algorithms.  In these cases, when the Hessian type is set to Newton,\index{optimisation!algorithm!Newton} a Hessian modification can also be supplied as above.  The default Hessian type is Newton,\index{optimisation!algorithm!Newton} and the default Hessian modification when Newton\index{optimisation!algorithm!Newton} is selected is the GMW algorithm:

Please see Table~\ref{table: min sub-algor - Hessian type} on page~\pageref{table: min sub-algor - Hessian type}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Minimisation sub-algorithms -- Hessian type.]{Minimisation sub-algorithms -- Hessian type.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Hessian type & Patterns \\
\midrule
Quasi-Newton BFGS & '\^{}[Bb][Ff][Gg][Ss]\$' \\
Newton & '\^{}[Nn]ewton\$' \\
\bottomrule
\\[-5pt]
\label{table: min sub-algor - Hessian type}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


For Newton\index{optimisation!algorithm!Newton} minimisation,\index{optimisation} the default line search algorithm is the More and Thuente line search, while the default Hessian modification is the GMW algorithm.

\subsubsection{Prompt examples}

To apply Newton\index{optimisation!algorithm!Newton} minimisation\index{optimisation} together with the GMW81 Hessian modification algorithm, the More and Thuente line search algorithm, a function tolerance of 1e-25, no gradient tolerance, a maximum of 10,000,000 iterations, constraints\index{constraint} turned on to limit\index{parameter!limit} parameter values, and have normal printout, type any combination of:

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('Newton')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', 'gmw')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', 'mt')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', 'gmw', 'mt')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', 'mt', 'gmw')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', func_tol=1e-25)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', func_tol=1e-25, grad_tol=None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', max_iter=1e7)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', constraints=True, max_iter=1e7)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton', verbosity=1)
\end{lstlisting}


To use constrained Simplex\index{optimisation!algorithm!Nelder-Mead simplex} minimisation\index{optimisation} with a maximum of 5000 iterations, type:

\begin{lstlisting}[numbers=none]
relax> minimise.execute('simplex', constraints=True, max_iter=5000)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{minimise\-.grid\-\_search\index{optimisation|textbf}} \label{uf: minimise.grid_search}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/rosenbrock} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grid_search}

\subsubsection{Synopsis}

Perform a grid search to find an initial non-biased parameter set for optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{minimise.\linebreak[0]grid\_search}(\linebreak[0]lower=\linebreak[0]None, upper=\linebreak[0]None, inc=\linebreak[0]21, verbosity=\linebreak[0]1, constraints=\linebreak[0]True, skip\_preset=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{lower:}  An array of the lower bound\index{parameter!bounds} parameter values for the grid search.  The length of the array should be equal to the number of parameters in the model.

\hspace{3 mm}\keyword{upper:}  An array of the upper bound\index{parameter!bounds} parameter values for the grid search.  The length of the array should be equal to the number of parameters in the model.

\hspace{3 mm}\keyword{inc:}  The number of increments to search over.  If a single integer is given then the number of increments will be equal in all dimensions.  Different numbers of increments in each direction can be set if \quotecmd{inc} is set to an array of integers of length equal to the number of parameters.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print to screen.  Zero corresponds to minimal output while higher values increase the amount of output.  The default value is 1.

\hspace{3 mm}\keyword{constraints:}  A boolean flag specifying whether the parameters should be constrained.  The default is to turn constraints\index{constraint} on (constraints=True).

\hspace{3 mm}\keyword{skip\_preset:}  This argument, when True, allows any parameter which already has a value set to be skipped in the grid search.  This value will be overridden and turned off when a zooming grid search is active.


\subsubsection{Description}

The optimisation of a mathematical model normally consists of two parts - a coarse grid search across the parameter space to find an initial set of parameter values followed by the use of a high precision optimisation algorithm to exactly find the local or global solution.  The grid search is an essential tool as it allows a non-biased initial optimisation position to be found.  It avoids the statistical bias and preconditioning introduced by using a self chosen initial parameter set.  The high computational cost of the grid search is almost always favourable to the statistical bias of a user defined starting position.

The region of the parameter space that the grid search covers is defined by the lower and upper grid bounds.\index{parameter!bounds}  These will generally default to the entire parameter space except for when the parameter is non-bounded, for example a 3D position in the PDB\index{PDB} space.  This user function will print out the grid bounds\index{parameter!bounds} used and, if the default bounds\index{parameter!bounds} are deemed to be insufficient, then the lower, upper or both bounds\index{parameter!bounds} can supplied.  This only works if all active models have the same parameters.  The coarseness or fineness of the grid is defined by the number of increments to search across between the bounds.\index{parameter!bounds}  For an alternative to using large numbers of increments, see the zooming grid search.

It is possible to decrease the dimensionality of the grid search, and hence drop the computational cost by orders of magnitude, if certain parameter values are know a priori.  For example if the values are determined via a different experiment.  Such parameters can be set with the value setting user function.  Then, when the skip preset flag is set, these parameters will be skipped in the grid search.  This feature should not be abused and statistical bias should be avoided at all cost.

The parameter skipping logic is as follows.  Firstly setting the increments argument to a list with None elements causes the corresponding parameters to be skipped in the grid search, or an error to be raised if no preset parameter is present.  This overrides all other settings.  Secondly the preset skipping flag only allows parameters to be skipped if the zooming grid search is non-active and a value is preset.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{minimise\-.grid\-\_zoom\index{optimisation|textbf}} \label{uf: minimise.grid_zoom}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/rosenbrock} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/zoom-in}

\subsubsection{Synopsis}

Activate the zooming grid search by setting the zoom level.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{minimise.\linebreak[0]grid\_zoom}(\linebreak[0]level=\linebreak[0]0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{level:}  The zooming grid search level.  This can be any number, positive or negative.


\subsubsection{Description}

The optimisation of a mathematical model normally consists of two parts - a coarse grid search to find an initial set of parameter values followed by the use of a high precision optimisation algorithm to exactly find the local or global solution.  But in certain situations, for example where a parallelised grid search is advantageous, a finer grid may be desired.  The zooming grid search provides a more efficient alternative to simply increasing the number of increments used in the initial grid search.  Note that in most situations, standard optimisation algorithms will be by far computationally less expensive.

The zooming grid search can be activated via this user function.  After setting the desired zoom level, the original grid search user function should be called again.  The zoom level is used to decrease the total area of the grid search.  The grid width for each dimension of the parameter space will be divided by 2**zoom\_level.  So a level of 1 will halve all dimensions, a level of 2 will quarter the widths, a level of 3 will be an eighth of the widths, etc.

The zooming algorithm proceeds as follows.  The new zoomed grid will be centred at the current parameter values.  However if the new grid is outside of the bounds\index{parameter!bounds} of the original grid, the entire grid will be translated so that it lies entirely within the original bounds.\index{parameter!bounds}  This is to avoid grid points lying within undefined regions of the space.  An exception is when the zoom factor is negative, hence the new grid will be larger than the original.

An example of using the zooming grid search is to first perform a standard initial grid search, then set the zoom level to 1 and perform a second grid search.  Continue for zoom levels 2, 3, etc. until the desired fineness is obtained.  Note that convergence is not guaranteed - as the zoom level is increased to infinity, the parameter values do not necessarily converge to the local minimum.  Therefore performing standard optimisation is recommended after completing a zooming grid search. 



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{model\-\_free\-.create\-\_model} \label{uf: model_free.create_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/model-free} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a model-free model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{model\_free.\linebreak[0]create\_model}(\linebreak[0]model=\linebreak[0]None, equation=\linebreak[0]None, params=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The new name of the model-free model.

\hspace{3 mm}\keyword{equation:}  The model-free equation.

\hspace{3 mm}\keyword{params:}  The array of parameter names of the model.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

This user function should almost never be used.  It is provided for academic reasons for the study of old analyses and published results.  If you are looking for a normal model-free model, use the model\_free.select\_model user function instead.

\subsubsection{Model-free equation}

The model-free equation can be one of the following:

\begin{itemize}
  \item[]\quotecmd{mf\_orig} selects the original model-free equations with parameters \{$S^2$, $\tau_e$\}.
  \item[]\quotecmd{mf\_ext} selects the extended model-free equations with parameters \{$S^2_f$, $\tau_f$, $S^2$, $\tau_s$\}.
  \item[]\quotecmd{mf\_ext2} selects the extended model-free equations with parameters \{$S^2_f$, $\tau_f$, $S^2_s$, $\tau_s$\}.
\end{itemize}

\subsubsection{Model-free parameters}

The following parameters are accepted for the original model-free equation:

\begin{description}
  \item[\quotecmd{s2} --]  The square of the generalised order\index{order parameter} parameter.
  \item[\quotecmd{te} --]  The effective correlation\index{correlation time} time.
\end{description}

The following parameters are accepted for the extended model-free equation:

\begin{description}
  \item[\quotecmd{s2f} --] The square of the generalised order\index{order parameter} parameter of the faster motion.
  \item[\quotecmd{tf} --]  The effective correlation\index{correlation time} time of the faster motion.
  \item[\quotecmd{s2} --]  The square of the generalised order\index{order parameter} parameter $S^2$ = $S^2_f$ * $S^2_s$.
  \item[\quotecmd{ts} --]  The effective correlation\index{correlation time} time of the slower motion.
\end{description}

The following parameters are accepted for the extended 2 model-free equation:

\begin{description}
  \item[\quotecmd{s2f} --] The square of the generalised order\index{order parameter} parameter of the faster motion.
  \item[\quotecmd{tf} --]  The effective correlation\index{correlation time} time of the faster motion.
  \item[\quotecmd{s2s} --] The square of the generalised order\index{order parameter} parameter of the slower motion.
  \item[\quotecmd{ts} --]  The effective correlation\index{correlation time} time of the slower motion.
\end{description}

The following parameters are accepted for all equations:

\begin{description}
  \item[\quotecmd{rex} --] The chemical\index{chemical exchange} exchange relaxation.\index{relaxation}
  \item[\quotecmd{r} --]   The average bond\index{bond length} length $<$$r$$>$.
  \item[\quotecmd{csa} --] The chemical shift anisotropy.
\end{description}

\subsubsection{Spin identification string}

If \quotecmd{spin\_id} is supplied then the model will only be created for the corresponding spins.  Otherwise the model will be created for all spins.

\subsubsection{Prompt examples}

The following commands will create the model-free model \quotecmd{m1} which is based on the original model-free equation and contains the single parameter \quotecmd{s2}.

\begin{lstlisting}[numbers=none]
relax> model_free.create_model('m1', 'mf_orig', ['s2'])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> model_free.create_model(model='m1', params=['s2'], equation='mf_orig')
\end{lstlisting}


The following commands will create the model-free model \quotecmd{large\_model} which is based on the extended model-free equation and contains the seven parameters \quotecmd{s2f}, \quotecmd{tf}, \quotecmd{s2}, \quotecmd{ts}, \quotecmd{rex}, \quotecmd{csa}, \quotecmd{r}.

\begin{lstlisting}[numbers=none]
relax> model_free.create_model('large_model', 'mf_ext', ['s2f', 'tf', 's2', 'ts', 'rex', 'csa', 'r'])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> model_free.create_model(model='large_model', params=['s2f', 'tf', 's2', 'ts', 'rex', 'csa', 'r'], equation='mf_ext')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{model\-\_free\-.delete} \label{uf: model_free.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/model-free} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} all model-free data from the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{model\_free.\linebreak[0]delete}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will delete\index{delete} all of the model-free data - parameters, model, etc. - from the current data pipe.

\subsubsection{Prompt examples}

To delete\index{delete} all model-free data, type:

\begin{lstlisting}[numbers=none]
relax> model_free.delete()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{model\-\_free\-.remove\-\_tm} \label{uf: model_free.remove_tm}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/model-free} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Remove the local $\tau_m$ parameter from a model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{model\_free.\linebreak[0]remove\_tm}(\linebreak[0]spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

This function will remove the local $\tau_m$ parameter from the model-free parameter set.  If there is no local $\tau_m$ parameter within the set nothing will happen.

If no spin identification string is given, then the function will apply to all spins.

\subsubsection{Prompt examples}

The following command will remove the parameter \quotecmd{tm}:

\begin{lstlisting}[numbers=none]
relax> model_free.remove_tm()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{model\-\_free\-.select\-\_model} \label{uf: model_free.select_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/model-free} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Select a preset model-free model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{model\_free.\linebreak[0]select\_model}(\linebreak[0]model=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The name of the preset model.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

This allows a standard model-free model to be selected from a long list of models.

\subsubsection{The preset models}

The standard preset model-free models are

\begin{description}
  \item[\quotecmd{m0} --] \{\},
  \item[\quotecmd{m1} --] \{S2\},
  \item[\quotecmd{m2} --] \{$S^2$, $\tau_e$\},
  \item[\quotecmd{m3} --] \{$S^2$, $R_{ex}$\},
  \item[\quotecmd{m4} --] \{$S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{m5} --] \{$S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m6} --] \{$S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m7} --] \{$S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m8} --] \{$S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m9} --] \{Rex\}.
\end{description}

The preset model-free models with optimisation of the CSA value are

\begin{description}
  \item[\quotecmd{m10} --] \{CSA\},
  \item[\quotecmd{m11} --] \{CSA, $S^2$\},
  \item[\quotecmd{m12} --] \{CSA, $S^2$, $\tau_e$\},
  \item[\quotecmd{m13} --] \{CSA, $S^2$, $R_{ex}$\},
  \item[\quotecmd{m14} --] \{CSA, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{m15} --] \{CSA, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m16} --] \{CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m17} --] \{CSA, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m18} --] \{CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m19} --] \{CSA, $R_{ex}$\}.
\end{description}

The preset model-free models with optimisation of the bond\index{bond length} length are

\begin{description}
  \item[\quotecmd{m20} --] \{r\},
  \item[\quotecmd{m21} --] \{$r$, $S^2$\},
  \item[\quotecmd{m22} --] \{$r$, $S^2$, $\tau_e$\},
  \item[\quotecmd{m23} --] \{$r$, $S^2$, $R_{ex}$\},
  \item[\quotecmd{m24} --] \{$r$, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{m25} --] \{$r$, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m26} --] \{$r$, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m27} --] \{$r$, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m28} --] \{$r$, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m29} --] \{$r$, CSA, $R_{ex}$\}.
\end{description}

The preset model-free models with both optimisation of the bond\index{bond length} length and CSA are

\begin{description}
  \item[\quotecmd{m30} --] \{$r$, CSA\},
  \item[\quotecmd{m31} --] \{$r$, CSA, $S^2$\},
  \item[\quotecmd{m32} --] \{$r$, CSA, $S^2$, $\tau_e$\},
  \item[\quotecmd{m33} --] \{$r$, CSA, $S^2$, $R_{ex}$\},
  \item[\quotecmd{m34} --] \{$r$, CSA, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{m35} --] \{$r$, CSA, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m36} --] \{$r$, CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{m37} --] \{$r$, CSA, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m38} --] \{$r$, CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{m39} --] \{$r$, CSA, $R_{ex}$\}.
\end{description}

Warning:  The models in the thirties range fail when using standard R$_1$, R$_2$, and NOE relaxation\index{relaxation} data.  This is due to the extreme flexibly of these models where a change in the parameter \quotecmd{r} is compensated by a corresponding change in the parameter \quotecmd{csa} and vice versa.

\subsubsection{The preset local tm models}

Additional preset model-free models, which are simply extensions of the above models with the addition of a local $\tau_m$ parameter are:

\begin{description}
  \item[\quotecmd{tm0} --] \{tm\},
  \item[\quotecmd{tm1} --] \{$\tau_m$, $S^2$\},
  \item[\quotecmd{tm2} --] \{$\tau_m$, $S^2$, $\tau_e$\},
  \item[\quotecmd{tm3} --] \{$\tau_m$, $S^2$, $R_{ex}$\},
  \item[\quotecmd{tm4} --] \{$\tau_m$, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{tm5} --] \{$\tau_m$, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm6} --] \{$\tau_m$, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm7} --] \{$\tau_m$, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm8} --] \{$\tau_m$, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm9} --] \{$\tau_m$, $R_{ex}$\}.
\end{description}

The preset model-free models with optimisation of the CSA value are

\begin{description}
  \item[\quotecmd{tm10} --] \{$\tau_m$, CSA\},
  \item[\quotecmd{tm11} --] \{$\tau_m$, CSA, $S^2$\},
  \item[\quotecmd{tm12} --] \{$\tau_m$, CSA, $S^2$, $\tau_e$\},
  \item[\quotecmd{tm13} --] \{$\tau_m$, CSA, $S^2$, $R_{ex}$\},
  \item[\quotecmd{tm14} --] \{$\tau_m$, CSA, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{tm15} --] \{$\tau_m$, CSA, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm16} --] \{$\tau_m$, CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm17} --] \{$\tau_m$, CSA, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm18} --] \{$\tau_m$, CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm19} --] \{$\tau_m$, CSA, $R_{ex}$\}.
\end{description}

The preset model-free models with optimisation of the bond\index{bond length} length are

\begin{description}
  \item[\quotecmd{tm20} --] \{$\tau_m$, $r$\},
  \item[\quotecmd{tm21} --] \{$\tau_m$, $r$, $S^2$\},
  \item[\quotecmd{tm22} --] \{$\tau_m$, $r$, $S^2$, $\tau_e$\},
  \item[\quotecmd{tm23} --] \{$\tau_m$, $r$, $S^2$, $R_{ex}$\},
  \item[\quotecmd{tm24} --] \{$\tau_m$, $r$, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{tm25} --] \{$\tau_m$, $r$, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm26} --] \{$\tau_m$, $r$, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm27} --] \{$\tau_m$, $r$, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm28} --] \{$\tau_m$, $r$, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm29} --] \{$\tau_m$, $r$, CSA, $R_{ex}$\}.
\end{description}

The preset model-free models with both optimisation of the bond\index{bond length} length and CSA are

\begin{description}
  \item[\quotecmd{tm30} --] \{$\tau_m$, $r$, CSA\},
  \item[\quotecmd{tm31} --] \{$\tau_m$, $r$, CSA, $S^2$\},
  \item[\quotecmd{tm32} --] \{$\tau_m$, $r$, CSA, $S^2$, $\tau_e$\},
  \item[\quotecmd{tm33} --] \{$\tau_m$, $r$, CSA, $S^2$, $R_{ex}$\},
  \item[\quotecmd{tm34} --] \{$\tau_m$, $r$, CSA, $S^2$, $\tau_e$, $R_{ex}$\},
  \item[\quotecmd{tm35} --] \{$\tau_m$, $r$, CSA, $S^2_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm36} --] \{$\tau_m$, $r$, CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$\},
  \item[\quotecmd{tm37} --] \{$\tau_m$, $r$, CSA, $S^2_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm38} --] \{$\tau_m$, $r$, CSA, $S^2_f$, $\tau_f$, $S^2$, $\tau_s$, $R_{ex}$\},
  \item[\quotecmd{tm39} --] \{$\tau_m$, $r$, CSA, $R_{ex}$\}.
\end{description}

\subsubsection{Spin identification string}

If \quotecmd{spin\_id} is supplied then the model will only be selected for the corresponding spins.  Otherwise the model will be selected for all spins.

\subsubsection{Prompt examples}

To pick model \quotecmd{m1} for all selected spins, type:

\begin{lstlisting}[numbers=none]
relax> model_free.select_model('m1')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> model_free.select_model(model='m1')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{model\-\_selection} \label{uf: model_selection}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/discrepancy_curve}

\subsubsection{Synopsis}

Select the best model from a set of optimised\index{optimise} models.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{model\_selection}(\linebreak[0]method=\linebreak[0]`AIC', modsel\_pipe=\linebreak[0]None, bundle=\linebreak[0]None, pipes=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{method:}  The model selection technique (see below).

\hspace{3 mm}\keyword{modsel\_pipe:}  The name of the new data pipe which will be created by this user function by the copying\index{copy} of the selected data pipe.

\hspace{3 mm}\keyword{bundle:}  The optional pipe bundle is a special grouping or clustering of data pipes.  If this is specified, the newly created data pipe will be added to this bundle.

\hspace{3 mm}\keyword{pipes:}  An array containing the names of all data pipes to include in model selection.


\subsubsection{Description}

The following model selection methods are supported:

\begin{description}
  \item[AIC\index{model selection!AIC} --] Akaike's Information Criteria.
  \item[AICc\index{model selection!AICc}\index{model selection!AIC} --] Small sample size corrected AIC.\index{model selection!AIC}
  \item[BIC\index{model selection!BIC} --] Bayesian or Schwarz Information Criteria.
  \item[Bootstrap\index{model selection!bootstrap} --] Bootstrap\index{model selection!bootstrap} model selection.
  \item[CV --] Single-item-out cross-validation.\index{model selection!cross-validation}
  \item[Expect --] The expected overall discrepancy (the true values of the parameters are required).
  \item[Farrow --] Old model-free method by Farrow et al., 1994.
  \item[Palmer --] Old model-free method by Mandel et al., 1995.
  \item[Overall --] The realised overall discrepancy (the true values of the parameters are required).
\end{description}

For the methods \quotecmd{Bootstrap}, \quotecmd{Expect}, and \quotecmd{Overall}, the Monte Carlo simulations should have previously been executed with the monte\_carlo.create\_data method set to Bootstrapping\index{model selection!bootstrap} to modify its behaviour.

If the data pipes have not been specified, then all data pipes will be used for model selection.

\subsubsection{Prompt examples}

For model-free analysis, if the preset models 1 to 5 are minimised\index{optimisation} and loaded into the program, the following commands will carry out AIC\index{model selection!AIC} model selection and to place the selected results into the \quotecmd{mixed} data pipe, type one of:

\begin{lstlisting}[numbers=none]
relax> model_selection('AIC', 'mixed')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> model_selection(method='AIC', modsel_pipe='mixed')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> model_selection('AIC', 'mixed', ['m1', 'm2', 'm3', 'm4', 'm5'])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> model_selection(method='AIC', modsel_pipe='mixed', pipes=['m1', 'm2', 'm3', 'm4', 'm5'])
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molecule\-.copy\index{molecule|textbf}} \label{uf: molecule.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molecule} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} all data associated with a molecule.\index{molecule}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molecule.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, mol\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, mol\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The data pipe containing the molecule\index{molecule} from which the data will be copied.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{mol\_from:}  The name of the molecule\index{molecule} from which to copy\index{copy} data from.

\hspace{3 mm}\keyword{pipe\_to:}  The data pipe to copy\index{copy} the data to.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{mol\_to:}  The name of the new molecule.\index{molecule}  If left blank, the new molecule\index{molecule} will have the same name as the old.  This needs to be a molecule\index{molecule} ID string, starting with \quotecmd{\#}.


\subsubsection{Description}

This will copy\index{copy} all the data associated with a molecule\index{molecule} to a second molecule.\index{molecule}  This includes all residue and spin system information.  The new molecule\index{molecule} name must be unique in the destination data pipe.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

To copy\index{copy} the molecule\index{molecule} data from the molecule\index{molecule} \quotecmd{GST} to the new molecule\index{molecule} \quotecmd{wt-GST}, type:

\begin{lstlisting}[numbers=none]
relax> molecule.copy('#GST', '#wt-GST')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molecule.copy(mol_from='#GST', mol_to='#wt-GST')
\end{lstlisting}


To copy\index{copy} the molecule\index{molecule} data of the molecule\index{molecule} \quotecmd{Ap4Aase} from the data pipe \quotecmd{m1} to \quotecmd{m2}, assuming the current data pipe is \quotecmd{m1}, type:

\begin{lstlisting}[numbers=none]
relax> molecule.copy(mol_from='#ApAase', pipe_to='m2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molecule.copy(pipe_from='m1', mol_from='#ApAase', pipe_to='m2', mol_to='#ApAase')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molecule\-.create\index{molecule|textbf}} \label{uf: molecule.create}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molecule} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a new molecule.\index{molecule}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molecule.\linebreak[0]create}(\linebreak[0]mol\_name=\linebreak[0]None, mol\_type=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{mol\_name:}  The name of the new molecule.\index{molecule}

\hspace{3 mm}\keyword{mol\_type:}  The type of molecule.\index{molecule}


\subsubsection{Description}

This adds a new molecule\index{molecule} data container to the relax data storage object.  The same molecule\index{molecule} name cannot be used more than once.  The molecule\index{molecule} type need not be specified.  However, if given, it should be one of \quotecmd{protein}, \quotecmd{DNA}, \quotecmd{RNA}, \quotecmd{organic molecule},\index{molecule} or \quotecmd{inorganic molecule}.\index{molecule}

\subsubsection{Prompt examples}

To create the molecules\index{molecule} \quotecmd{Ap4Aase}, \quotecmd{ATP}, and \quotecmd{MgF4}, type:

\begin{lstlisting}[numbers=none]
relax> molecule.create('Ap4Aase')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molecule.create('ATP')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molecule.create('MgF4')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molecule\-.delete\index{molecule|textbf}} \label{uf: molecule.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molecule} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Deleting molecules\index{molecule} from the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molecule.\linebreak[0]delete}(\linebreak[0]mol\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{mol\_id:}  The molecule\index{molecule} ID string.


\subsubsection{Description}

This can be used to delete\index{delete} a single or sets of molecules\index{molecule} from the relax data store.  The molecule\index{molecule} will be deleted\index{delete} from the current data pipe.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molecule\-.display\index{molecule|textbf}} \label{uf: molecule.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molecule} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the molecule\index{molecule} information.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molecule.\linebreak[0]display}(\linebreak[0]mol\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{mol\_id:}  The molecule\index{molecule} ID string.


\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molecule\-.name\index{molecule|textbf}} \label{uf: molecule.name}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molecule} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Name a molecule.\index{molecule}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molecule.\linebreak[0]name}(\linebreak[0]mol\_id=\linebreak[0]None, name=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{mol\_id:}  The molecule\index{molecule} ID string corresponding to one or more molecules.\index{molecule}

\hspace{3 mm}\keyword{name:}  The new molecule\index{molecule} name.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the molecule\index{molecule} to be renamed.


\subsubsection{Description}

This simply allows molecules\index{molecule} to be named (or renamed).

\subsubsection{Prompt examples}

To rename the molecule\index{molecule} \quotecmd{Ap4Aase} to \quotecmd{Inhib Ap4Aase}, type one of:

\begin{lstlisting}[numbers=none]
relax> molecule.name('#Ap4Aase', 'Inhib Ap4Aase', True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molecule.name(mol_id='#Ap4Aase', name='Inhib Ap4Aase', force=True)
\end{lstlisting}


This assumes the molecule\index{molecule} \quotecmd{Ap4Aase} already exists.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molecule\-.type\index{molecule|textbf}} \label{uf: molecule.type}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molecule} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the molecule\index{molecule} type.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molecule.\linebreak[0]type}(\linebreak[0]mol\_id=\linebreak[0]None, type=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{mol\_id:}  The molecule\index{molecule} ID string corresponding to one or more molecules.\index{molecule}

\hspace{3 mm}\keyword{type:}  The molecule\index{molecule} type.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the molecule\index{molecule} to type to be overwritten.


\subsubsection{Description}

This allows the type of the molecule\index{molecule} to be specified.  It can be one of:

\begin{itemize}
  \item[]\quotecmd{protein},
  \item[]\quotecmd{DNA},
  \item[]\quotecmd{RNA},
  \item[]\quotecmd{organic molecule},\index{molecule}
  \item[]\quotecmd{inorganic molecule}.\index{molecule}
\end{itemize}

\subsubsection{Prompt examples}

To set the molecule\index{molecule} \quotecmd{Ap4Aase} to the \quotecmd{protein} type, type one of:

\begin{lstlisting}[numbers=none]
relax> molecule.type('#Ap4Aase', 'protein', True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molecule.type(mol_id='#Ap4Aase', type='protein', force=True)
\end{lstlisting}


\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.clear\-\_history\index{software!MOLMOL|textbf}} \label{uf: molmol.clear_history}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill 

\subsubsection{Synopsis}

Clear the Molmol\index{software!MOLMOL}\index{software!MOLMOL} command history.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]clear\_history}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will clear the Molmol\index{software!MOLMOL}\index{software!MOLMOL} history from memory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.command\index{software!MOLMOL|textbf}} \label{uf: molmol.command}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Execute a user supplied Molmol\index{software!MOLMOL}\index{software!MOLMOL} command.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]command}(\linebreak[0]command=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{command:}  The Molmol\index{software!MOLMOL}\index{software!MOLMOL} command to execute.


\subsubsection{Description}

This allows Molmol\index{software!MOLMOL}\index{software!MOLMOL} commands to be passed to the program.  This can be useful for automation or scripting.\index{scripting!script file}\index{scripting}

\subsubsection{Prompt examples}

To reinitialise the Molmol\index{software!MOLMOL}\index{software!MOLMOL} instance, type:

\begin{lstlisting}[numbers=none]
relax> molmol.command("InitAll yes")
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.macro\-\_apply\index{software!MOLMOL|textbf}} \label{uf: molmol.macro_apply}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol}

\subsubsection{Synopsis}

Execute Molmol\index{software!MOLMOL}\index{software!MOLMOL} macros.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]macro\_apply}(\linebreak[0]data\_type=\linebreak[0]None, style=\linebreak[0]`classic', colour\_start\_name=\linebreak[0]None, colour\_start\_rgb=\linebreak[0]None, colour\_end\_name=\linebreak[0]None, colour\_end\_rgb=\linebreak[0]None, colour\_list=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{data\_type:}  The data type to map\index{map} to the structure.

\hspace{3 mm}\keyword{style:}  The style of the macro.

\hspace{3 mm}\keyword{colour\_start\_name:}  The name of the starting colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the starting colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_start\_rgb:}  The starting colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the starting colour name cannot be given.

\hspace{3 mm}\keyword{colour\_end\_name:}  The name of the ending colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the ending colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_end\_rgb:}  The ending colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the ending colour name cannot be given.

\hspace{3 mm}\keyword{colour\_list:}  The colour list to search for the colour names.  This can be either \quotecmd{molmol} or \quotecmd{x11}.


\subsubsection{Description}

This allows spin specific values to be mapped\index{map} to a structure through Molmol\index{software!MOLMOL}\index{software!MOLMOL} macros.  Currently only the \quotecmd{classic} style, which is described below, is available.

\subsubsection{Colour}

The values are coloured based on a linear colour gradient which is specified through starting and ending colours.  These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself.  For example, \quotecmd{white} and [1.0, 1.0, 1.0] both select the same colour.  Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings.  These are the default Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour list and the X11 colour list, both of which are described in the tables below.  The default behaviour is to first search the Molmol\index{software!MOLMOL}\index{software!MOLMOL} list and then the X11 colour list, raising an error if neither contain the name.  To explicitly select these lists, set the colour list to either \quotecmd{molmol} or \quotecmd{x11}.

\subsubsection{Model-free classic style}

Creator:  Edward d'Auvergne

Argument string:  "classic"

Description:  The classic style draws the backbone of a protein in a cylindrical bond style.  Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured.  Deselected residues are shown as black lines.

Supported data types:

Please see Table~\ref{table: model-free macro classic style} on page~\pageref{table: model-free macro classic style}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[The model-free classic style for PyMOL and Molmol data mapping.]{The model-free classic style for mapping model spin specific data onto 3D molecular structures using either PyMOL or Molmol.}
\begin{tabularx}{\textwidth}{llX}
\\[-5pt]
\toprule
Data type & String & Description \\
\midrule
$S^2$. & 's2' & The standard model-free order parameter, equal to $S^2_f$.S2s for the two timescale models.  The default colour gradient starts at 'yellow' and ends at 'red'. \\
$S^2_f$. & 's2f' & The order parameter of the faster of two internal motions.  Residues which are described by model-free models m1 to m4, the single timescale models, are illustrated as white neon bonds.  The default colour gradient is the same as that for the $S^2$ data type. \\
$S^2_s$. & 's2s' & The order parameter of the slower of two internal motions.  This functions exactly as $S^2_f$ except that $S^2_s$ is plotted instead. \\
Amplitude of fast motions. & 'amp\_fast' & Model independent display of the amplite of fast motions.  For residues described by model-free models m5 to m8, the value plotted is that of $S^2_f$.  However, for residues described by models m1 to m4, what is shown is dependent on the timescale of the motions.  This is because these single timescale models can, at times, be perfect approximations to the more complex two timescale models.  Hence if $\tau_e$ is less than 200 ps, $S^2$ is plotted.  Otherwise the peptide bond is coloured white.  The default colour gradient  is the same as that for $S^2$. \\
Amplitude of slow motions. & 'amp\_slow' & Model independent display of the amplite of slow motions, arbitrarily defined as motions slower than 200 ps.  For residues described by model-free models m5 to m8, the order parameter $S^2$ is plotted if $\tau_s$ $>$ 200 ps.  For models m1 to m4, $S^2$ is plotted if $\tau_e$ $>$ 200 ps.  The default colour gradient is the same as that for $S^2$. \\
$\tau_e$. & 'te' & The correlation time, $\tau_e$.  The default colour gradient starts at 'turquoise' and ends at 'blue'. \\
$\tau_f$. & 'tf' & The correlation time, $\tau_f$.  The default colour gradient is the same as that of $\tau_e$. \\
$\tau_s$. & 'ts' & The correlation time, $\tau_s$.  The default colour gradient starts at 'blue' and ends at 'black'. \\
Timescale of fast motions & 'time\_fast' & Model independent display of the timescale of fast motions.  For models m5 to m8, only the parameter $\tau_f$ is plotted.  For models m2 and m4, the parameter $\tau_e$ is plotted only if it is less than 200 ps.  All other residues are assumed to have a correlation time of zero.  The default colour gradient is the same as that of $\tau_e$. \\
Timescale of slow motions & 'time\_slow' & Model independent display of the timescale of slow motions.  For models m5 to m8, only the parameter $\tau_s$ is plotted.  For models m2 and m4, the parameter $\tau_e$ is plotted only if it is greater than 200 ps.  All other residues are coloured white.  The default colour gradient is the same as that of $\tau_s$. \\
Chemical exchange & 'rex' & The chemical exchange, $R_{ex}$.  Residues which experience no chemical exchange are coloured white.  The default colour gradient starts at 'yellow' and finishes at 'red'. \\
\bottomrule
\\[-5pt]
\label{table: model-free macro classic style}
\end{tabularx}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Molmol RGB colour arrays}

The following table is a list of colours used in Molmol\index{software!MOLMOL}\index{software!MOLMOL} and their corresponding RGB colour values ranging from 0 to 1.

Please see Table~\ref{table: Molmol colours} on page~\pageref{table: Molmol colours}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Molmol colour names and corresponding RGB colour values (from 0 to 1)]{Molmol colour names and corresponding RGB colour values (from 0 to 1)}
\begin{tabular}{llll}
\\[-5pt]
\toprule
Name & Red & Green & Blue \\
\midrule
'black' & 0.000 & 0.000 & 0.000 \\
'navy' & 0.000 & 0.000 & 0.502 \\
'blue' & 0.000 & 0.000 & 1.000 \\
'dark green' & 0.000 & 0.392 & 0.000 \\
'green' & 0.000 & 1.000 & 0.000 \\
'cyan' & 0.000 & 1.000 & 1.000 \\
'turquoise' & 0.251 & 0.878 & 0.816 \\
'royal blue' & 0.255 & 0.412 & 0.882 \\
'aquamarine' & 0.498 & 1.000 & 0.831 \\
'sky green' & 0.529 & 0.808 & 0.922 \\
'dark violet' & 0.580 & 0.000 & 0.827 \\
'pale green' & 0.596 & 0.984 & 0.596 \\
'purple' & 0.627 & 0.125 & 0.941 \\
'brown' & 0.647 & 0.165 & 0.165 \\
'light blue' & 0.678 & 0.847 & 0.902 \\
'grey' & 0.745 & 0.745 & 0.745 \\
'light grey' & 0.827 & 0.827 & 0.827 \\
'violet' & 0.933 & 0.510 & 0.933 \\
'light coral' & 0.941 & 0.502 & 0.502 \\
'khaki' & 0.941 & 0.902 & 0.549 \\
'beige' & 0.961 & 0.961 & 0.863 \\
'red' & 1.000 & 0.000 & 0.000 \\
'magenta' & 1.000 & 0.000 & 1.000 \\
'deep pink' & 1.000 & 0.078 & 0.576 \\
'orange red' & 1.000 & 0.271 & 0.000 \\
'hot pink' & 1.000 & 0.412 & 0.706 \\
'coral' & 1.000 & 0.498 & 0.314 \\
'dark orange' & 1.000 & 0.549 & 0.000 \\
'orange' & 1.000 & 0.647 & 0.000 \\
'pink' & 1.000 & 0.753 & 0.796 \\
'gold' & 1.000 & 0.843 & 0.000 \\
'yellow' & 1.000 & 1.000 & 0.000 \\
'light yellow' & 1.000 & 1.000 & 0.878 \\
'ivory' & 1.000 & 1.000 & 0.941 \\
'white' & 1.000 & 1.000 & 1.000 \\
\bottomrule
\\[-5pt]
\label{table: Molmol colours}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{X11 RGB colour arrays}

The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.

Please see Table~\ref{table: X11 colours} on page~\pageref{table: X11 colours}.

\onecolumn
\begin{scriptsize}
\begin{center}
\begin{longtable}{llll}
\caption[X11 colour names and corresponding RGB colour values]{X11 colour names and corresponding RGB colour values}
\\
\toprule
Name & Red & Green & Blue \\
\midrule
\endhead

\bottomrule
\endfoot
\label{table: X11 colours}
snow & 255 & 250 & 250 \\
ghost white & 248 & 248 & 255 \\
white smoke & 245 & 245 & 245 \\
gainsboro & 220 & 220 & 220 \\
floral white & 255 & 250 & 240 \\
old lace & 253 & 245 & 230 \\
linen & 250 & 240 & 230 \\
antique white & 250 & 235 & 215 \\
papaya whip & 255 & 239 & 213 \\
blanched almond & 255 & 235 & 205 \\
bisque & 255 & 228 & 196 \\
peach puff & 255 & 218 & 185 \\
navajo white & 255 & 222 & 173 \\
moccasin & 255 & 228 & 181 \\
cornsilk & 255 & 248 & 220 \\
ivory & 255 & 255 & 240 \\
lemon chiffon & 255 & 250 & 205 \\
seashell & 255 & 245 & 238 \\
honeydew & 240 & 255 & 240 \\
mint cream & 245 & 255 & 250 \\
azure & 240 & 255 & 255 \\
alice blue & 240 & 248 & 255 \\
lavender & 230 & 230 & 250 \\
lavender blush & 255 & 240 & 245 \\
misty rose & 255 & 228 & 225 \\
white & 255 & 255 & 255 \\
black & 0 & 0 & 0 \\
dark slate grey & 47 & 79 & 79 \\
dim grey & 105 & 105 & 105 \\
slate grey & 112 & 128 & 144 \\
light slate grey & 119 & 136 & 153 \\
grey & 190 & 190 & 190 \\
light grey & 211 & 211 & 211 \\
midnight blue & 25 & 25 & 112 \\
navy & 0 & 0 & 128 \\
cornflower blue & 100 & 149 & 237 \\
dark slate blue & 72 & 61 & 139 \\
slate blue & 106 & 90 & 205 \\
medium slate blue & 123 & 104 & 238 \\
light slate blue & 132 & 112 & 255 \\
medium blue & 0 & 0 & 205 \\
royal blue & 65 & 105 & 225 \\
blue & 0 & 0 & 255 \\
dodger blue & 30 & 144 & 255 \\
deep sky blue & 0 & 191 & 255 \\
sky blue & 135 & 206 & 235 \\
light sky blue & 135 & 206 & 250 \\
steel blue & 70 & 130 & 180 \\
light steel blue & 176 & 196 & 222 \\
light blue & 173 & 216 & 230 \\
powder blue & 176 & 224 & 230 \\
pale turquoise & 175 & 238 & 238 \\
dark turquoise & 0 & 206 & 209 \\
medium turquoise & 72 & 209 & 204 \\
turquoise & 64 & 224 & 208 \\
cyan & 0 & 255 & 255 \\
light cyan & 224 & 255 & 255 \\
cadet blue & 95 & 158 & 160 \\
medium aquamarine & 102 & 205 & 170 \\
aquamarine & 127 & 255 & 212 \\
dark green & 0 & 100 & 0 \\
dark olive green & 85 & 107 & 47 \\
dark sea green & 143 & 188 & 143 \\
sea green & 46 & 139 & 87 \\
medium sea green & 60 & 179 & 113 \\
light sea green & 32 & 178 & 170 \\
pale green & 152 & 251 & 152 \\
spring green & 0 & 255 & 127 \\
lawn green & 124 & 252 & 0 \\
green & 0 & 255 & 0 \\
chartreuse & 127 & 255 & 0 \\
medium spring green & 0 & 250 & 154 \\
green yellow & 173 & 255 & 47 \\
lime green & 50 & 205 & 50 \\
yellow green & 154 & 205 & 50 \\
forest green & 34 & 139 & 34 \\
olive drab & 107 & 142 & 35 \\
dark khaki & 189 & 183 & 107 \\
khaki & 240 & 230 & 140 \\
pale goldenrod & 238 & 232 & 170 \\
light goldenrod yellow & 250 & 250 & 210 \\
light yellow & 255 & 255 & 224 \\
yellow & 255 & 255 & 0 \\
gold & 255 & 215 & 0 \\
light goldenrod & 238 & 221 & 130 \\
goldenrod & 218 & 165 & 32 \\
dark goldenrod & 184 & 134 & 11 \\
rosy brown & 188 & 143 & 143 \\
indian red & 205 & 92 & 92 \\
saddle brown & 139 & 69 & 19 \\
sienna & 160 & 82 & 45 \\
peru & 205 & 133 & 63 \\
burlywood & 222 & 184 & 135 \\
beige & 245 & 245 & 220 \\
wheat & 245 & 222 & 179 \\
sandy brown & 244 & 164 & 96 \\
tan & 210 & 180 & 140 \\
chocolate & 210 & 105 & 30 \\
firebrick & 178 & 34 & 34 \\
brown & 165 & 42 & 42 \\
dark salmon & 233 & 150 & 122 \\
salmon & 250 & 128 & 114 \\
light salmon & 255 & 160 & 122 \\
orange & 255 & 165 & 0 \\
dark orange & 255 & 140 & 0 \\
coral & 255 & 127 & 80 \\
light coral & 240 & 128 & 128 \\
tomato & 255 & 99 & 71 \\
orange red & 255 & 69 & 0 \\
red & 255 & 0 & 0 \\
hot pink & 255 & 105 & 180 \\
deep pink & 255 & 20 & 147 \\
pink & 255 & 192 & 203 \\
light pink & 255 & 182 & 193 \\
pale violet red & 219 & 112 & 147 \\
maroon & 176 & 48 & 96 \\
medium violet red & 199 & 21 & 133 \\
violet red & 208 & 32 & 144 \\
magenta & 255 & 0 & 255 \\
violet & 238 & 130 & 238 \\
plum & 221 & 160 & 221 \\
orchid & 218 & 112 & 214 \\
medium orchid & 186 & 85 & 211 \\
dark orchid & 153 & 50 & 204 \\
dark violet & 148 & 0 & 211 \\
blue violet & 138 & 43 & 226 \\
purple & 160 & 32 & 240 \\
medium purple & 147 & 112 & 219 \\
thistle & 216 & 191 & 216 \\
snow 1 & 255 & 250 & 250 \\
snow 2 & 238 & 233 & 233 \\
snow 3 & 205 & 201 & 201 \\
snow 4 & 139 & 137 & 137 \\
seashell 1 & 255 & 245 & 238 \\
seashell 2 & 238 & 229 & 222 \\
seashell 3 & 205 & 197 & 191 \\
seashell 4 & 139 & 134 & 130 \\
antique white 1 & 255 & 239 & 219 \\
antique white 2 & 238 & 223 & 204 \\
antique white 3 & 205 & 192 & 176 \\
antique white 4 & 139 & 131 & 120 \\
bisque 1 & 255 & 228 & 196 \\
bisque 2 & 238 & 213 & 183 \\
bisque 3 & 205 & 183 & 158 \\
bisque 4 & 139 & 125 & 107 \\
peach puff 1 & 255 & 218 & 185 \\
peach puff 2 & 238 & 203 & 173 \\
peach puff 3 & 205 & 175 & 149 \\
peach puff 4 & 139 & 119 & 101 \\
navajo white 1 & 255 & 222 & 173 \\
navajo white 2 & 238 & 207 & 161 \\
navajo white 3 & 205 & 179 & 139 \\
navajo white 4 & 139 & 121 & 94 \\
lemon chiffon 1 & 255 & 250 & 205 \\
lemon chiffon 2 & 238 & 233 & 191 \\
lemon chiffon 3 & 205 & 201 & 165 \\
lemon chiffon 4 & 139 & 137 & 112 \\
cornsilk 1 & 255 & 248 & 220 \\
cornsilk 2 & 238 & 232 & 205 \\
cornsilk 3 & 205 & 200 & 177 \\
cornsilk 4 & 139 & 136 & 120 \\
ivory 1 & 255 & 255 & 240 \\
ivory 2 & 238 & 238 & 224 \\
ivory 3 & 205 & 205 & 193 \\
ivory 4 & 139 & 139 & 131 \\
honeydew 1 & 240 & 255 & 240 \\
honeydew 2 & 224 & 238 & 224 \\
honeydew 3 & 193 & 205 & 193 \\
honeydew 4 & 131 & 139 & 131 \\
lavender blush 1 & 255 & 240 & 245 \\
lavender blush 2 & 238 & 224 & 229 \\
lavender blush 3 & 205 & 193 & 197 \\
lavender blush 4 & 139 & 131 & 134 \\
misty rose 1 & 255 & 228 & 225 \\
misty rose 2 & 238 & 213 & 210 \\
misty rose 3 & 205 & 183 & 181 \\
misty rose 4 & 139 & 125 & 123 \\
azure 1 & 240 & 255 & 255 \\
azure 2 & 224 & 238 & 238 \\
azure 3 & 193 & 205 & 205 \\
azure 4 & 131 & 139 & 139 \\
slate blue 1 & 131 & 111 & 255 \\
slate blue 2 & 122 & 103 & 238 \\
slate blue 3 & 105 & 89 & 205 \\
slate blue 4 & 71 & 60 & 139 \\
royal blue 1 & 72 & 118 & 255 \\
royal blue 2 & 67 & 110 & 238 \\
royal blue 3 & 58 & 95 & 205 \\
royal blue 4 & 39 & 64 & 139 \\
blue 1 & 0 & 0 & 255 \\
blue 2 & 0 & 0 & 238 \\
blue 3 & 0 & 0 & 205 \\
blue 4 & 0 & 0 & 139 \\
dodger blue 1 & 30 & 144 & 255 \\
dodger blue 2 & 28 & 134 & 238 \\
dodger blue 3 & 24 & 116 & 205 \\
dodger blue 4 & 16 & 78 & 139 \\
steel blue 1 & 99 & 184 & 255 \\
steel blue 2 & 92 & 172 & 238 \\
steel blue 3 & 79 & 148 & 205 \\
steel blue 4 & 54 & 100 & 139 \\
deep sky blue 1 & 0 & 191 & 255 \\
deep sky blue 2 & 0 & 178 & 238 \\
deep sky blue 3 & 0 & 154 & 205 \\
deep sky blue 4 & 0 & 104 & 139 \\
sky blue 1 & 135 & 206 & 255 \\
sky blue 2 & 126 & 192 & 238 \\
sky blue 3 & 108 & 166 & 205 \\
sky blue 4 & 74 & 112 & 139 \\
light sky blue 1 & 176 & 226 & 255 \\
light sky blue 2 & 164 & 211 & 238 \\
light sky blue 3 & 141 & 182 & 205 \\
light sky blue 4 & 96 & 123 & 139 \\
slate grey 1 & 198 & 226 & 255 \\
slate grey 2 & 185 & 211 & 238 \\
slate grey 3 & 159 & 182 & 205 \\
slate grey 4 & 108 & 123 & 139 \\
light steel blue 1 & 202 & 225 & 255 \\
light steel blue 2 & 188 & 210 & 238 \\
light steel blue 3 & 162 & 181 & 205 \\
light steel blue 4 & 110 & 123 & 139 \\
light blue 1 & 191 & 239 & 255 \\
light blue 2 & 178 & 223 & 238 \\
light blue 3 & 154 & 192 & 205 \\
light blue 4 & 104 & 131 & 139 \\
light cyan 1 & 224 & 255 & 255 \\
light cyan 2 & 209 & 238 & 238 \\
light cyan 3 & 180 & 205 & 205 \\
light cyan 4 & 122 & 139 & 139 \\
pale turquoise 1 & 187 & 255 & 255 \\
pale turquoise 2 & 174 & 238 & 238 \\
pale turquoise 3 & 150 & 205 & 205 \\
pale turquoise 4 & 102 & 139 & 139 \\
cadet blue 1 & 152 & 245 & 255 \\
cadet blue 2 & 142 & 229 & 238 \\
cadet blue 3 & 122 & 197 & 205 \\
cadet blue 4 & 83 & 134 & 139 \\
turquoise 1 & 0 & 245 & 255 \\
turquoise 2 & 0 & 229 & 238 \\
turquoise 3 & 0 & 197 & 205 \\
turquoise 4 & 0 & 134 & 139 \\
cyan 1 & 0 & 255 & 255 \\
cyan 2 & 0 & 238 & 238 \\
cyan 3 & 0 & 205 & 205 \\
cyan 4 & 0 & 139 & 139 \\
dark slate grey 1 & 151 & 255 & 255 \\
dark slate grey 2 & 141 & 238 & 238 \\
dark slate grey 3 & 121 & 205 & 205 \\
dark slate grey 4 & 82 & 139 & 139 \\
aquamarine 1 & 127 & 255 & 212 \\
aquamarine 2 & 118 & 238 & 198 \\
aquamarine 3 & 102 & 205 & 170 \\
aquamarine 4 & 69 & 139 & 116 \\
dark sea green 1 & 193 & 255 & 193 \\
dark sea green 2 & 180 & 238 & 180 \\
dark sea green 3 & 155 & 205 & 155 \\
dark sea green 4 & 105 & 139 & 105 \\
sea green 1 & 84 & 255 & 159 \\
sea green 2 & 78 & 238 & 148 \\
sea green 3 & 67 & 205 & 128 \\
sea green 4 & 46 & 139 & 87 \\
pale green 1 & 154 & 255 & 154 \\
pale green 2 & 144 & 238 & 144 \\
pale green 3 & 124 & 205 & 124 \\
pale green 4 & 84 & 139 & 84 \\
spring green 1 & 0 & 255 & 127 \\
spring green 2 & 0 & 238 & 118 \\
spring green 3 & 0 & 205 & 102 \\
spring green 4 & 0 & 139 & 69 \\
green 1 & 0 & 255 & 0 \\
green 2 & 0 & 238 & 0 \\
green 3 & 0 & 205 & 0 \\
green 4 & 0 & 139 & 0 \\
chartreuse 1 & 127 & 255 & 0 \\
chartreuse 2 & 118 & 238 & 0 \\
chartreuse 3 & 102 & 205 & 0 \\
chartreuse 4 & 69 & 139 & 0 \\
olive drab 1 & 192 & 255 & 62 \\
olive drab 2 & 179 & 238 & 58 \\
olive drab 3 & 154 & 205 & 50 \\
olive drab 4 & 105 & 139 & 34 \\
dark olive green 1 & 202 & 255 & 112 \\
dark olive green 2 & 188 & 238 & 104 \\
dark olive green 3 & 162 & 205 & 90 \\
dark olive green 4 & 110 & 139 & 61 \\
khaki 1 & 255 & 246 & 143 \\
khaki 2 & 238 & 230 & 133 \\
khaki 3 & 205 & 198 & 115 \\
khaki 4 & 139 & 134 & 78 \\
light goldenrod 1 & 255 & 236 & 139 \\
light goldenrod 2 & 238 & 220 & 130 \\
light goldenrod 3 & 205 & 190 & 112 \\
light goldenrod 4 & 139 & 129 & 76 \\
light yellow 1 & 255 & 255 & 224 \\
light yellow 2 & 238 & 238 & 209 \\
light yellow 3 & 205 & 205 & 180 \\
light yellow 4 & 139 & 139 & 122 \\
yellow 1 & 255 & 255 & 0 \\
yellow 2 & 238 & 238 & 0 \\
yellow 3 & 205 & 205 & 0 \\
yellow 4 & 139 & 139 & 0 \\
gold 1 & 255 & 215 & 0 \\
gold 2 & 238 & 201 & 0 \\
gold 3 & 205 & 173 & 0 \\
gold 4 & 139 & 117 & 0 \\
goldenrod 1 & 255 & 193 & 37 \\
goldenrod 2 & 238 & 180 & 34 \\
goldenrod 3 & 205 & 155 & 29 \\
goldenrod 4 & 139 & 105 & 20 \\
dark goldenrod 1 & 255 & 185 & 15 \\
dark goldenrod 2 & 238 & 173 & 14 \\
dark goldenrod 3 & 205 & 149 & 12 \\
dark goldenrod 4 & 139 & 101 & 8 \\
rosy brown 1 & 255 & 193 & 193 \\
rosy brown 2 & 238 & 180 & 180 \\
rosy brown 3 & 205 & 155 & 155 \\
rosy brown 4 & 139 & 105 & 105 \\
indian red 1 & 255 & 106 & 106 \\
indian red 2 & 238 & 99 & 99 \\
indian red 3 & 205 & 85 & 85 \\
indian red 4 & 139 & 58 & 58 \\
sienna 1 & 255 & 130 & 71 \\
sienna 2 & 238 & 121 & 66 \\
sienna 3 & 205 & 104 & 57 \\
sienna 4 & 139 & 71 & 38 \\
burlywood 1 & 255 & 211 & 155 \\
burlywood 2 & 238 & 197 & 145 \\
burlywood 3 & 205 & 170 & 125 \\
burlywood 4 & 139 & 115 & 85 \\
wheat 1 & 255 & 231 & 186 \\
wheat 2 & 238 & 216 & 174 \\
wheat 3 & 205 & 186 & 150 \\
wheat 4 & 139 & 126 & 102 \\
tan 1 & 255 & 165 & 79 \\
tan 2 & 238 & 154 & 73 \\
tan 3 & 205 & 133 & 63 \\
tan 4 & 139 & 90 & 43 \\
chocolate 1 & 255 & 127 & 36 \\
chocolate 2 & 238 & 118 & 33 \\
chocolate 3 & 205 & 102 & 29 \\
chocolate 4 & 139 & 69 & 19 \\
firebrick 1 & 255 & 48 & 48 \\
firebrick 2 & 238 & 44 & 44 \\
firebrick 3 & 205 & 38 & 38 \\
firebrick 4 & 139 & 26 & 26 \\
brown 1 & 255 & 64 & 64 \\
brown 2 & 238 & 59 & 59 \\
brown 3 & 205 & 51 & 51 \\
brown 4 & 139 & 35 & 35 \\
salmon 1 & 255 & 140 & 105 \\
salmon 2 & 238 & 130 & 98 \\
salmon 3 & 205 & 112 & 84 \\
salmon 4 & 139 & 76 & 57 \\
light salmon 1 & 255 & 160 & 122 \\
light salmon 2 & 238 & 149 & 114 \\
light salmon 3 & 205 & 129 & 98 \\
light salmon 4 & 139 & 87 & 66 \\
orange 1 & 255 & 165 & 0 \\
orange 2 & 238 & 154 & 0 \\
orange 3 & 205 & 133 & 0 \\
orange 4 & 139 & 90 & 0 \\
dark orange 1 & 255 & 127 & 0 \\
dark orange 2 & 238 & 118 & 0 \\
dark orange 3 & 205 & 102 & 0 \\
dark orange 4 & 139 & 69 & 0 \\
coral 1 & 255 & 114 & 86 \\
coral 2 & 238 & 106 & 80 \\
coral 3 & 205 & 91 & 69 \\
coral 4 & 139 & 62 & 47 \\
tomato 1 & 255 & 99 & 71 \\
tomato 2 & 238 & 92 & 66 \\
tomato 3 & 205 & 79 & 57 \\
tomato 4 & 139 & 54 & 38 \\
orange red 1 & 255 & 69 & 0 \\
orange red 2 & 238 & 64 & 0 \\
orange red 3 & 205 & 55 & 0 \\
orange red 4 & 139 & 37 & 0 \\
red 1 & 255 & 0 & 0 \\
red 2 & 238 & 0 & 0 \\
red 3 & 205 & 0 & 0 \\
red 4 & 139 & 0 & 0 \\
deep pink 1 & 255 & 20 & 147 \\
deep pink 2 & 238 & 18 & 137 \\
deep pink 3 & 205 & 16 & 118 \\
deep pink 4 & 139 & 10 & 80 \\
hot pink 1 & 255 & 110 & 180 \\
hot pink 2 & 238 & 106 & 167 \\
hot pink 3 & 205 & 96 & 144 \\
hot pink 4 & 139 & 58 & 98 \\
pink 1 & 255 & 181 & 197 \\
pink 2 & 238 & 169 & 184 \\
pink 3 & 205 & 145 & 158 \\
pink 4 & 139 & 99 & 108 \\
light pink 1 & 255 & 174 & 185 \\
light pink 2 & 238 & 162 & 173 \\
light pink 3 & 205 & 140 & 149 \\
light pink 4 & 139 & 95 & 101 \\
pale violet red 1 & 255 & 130 & 171 \\
pale violet red 2 & 238 & 121 & 159 \\
pale violet red 3 & 205 & 104 & 137 \\
pale violet red 4 & 139 & 71 & 93 \\
maroon 1 & 255 & 52 & 179 \\
maroon 2 & 238 & 48 & 167 \\
maroon 3 & 205 & 41 & 144 \\
maroon 4 & 139 & 28 & 98 \\
violet red 1 & 255 & 62 & 150 \\
violet red 2 & 238 & 58 & 140 \\
violet red 3 & 205 & 50 & 120 \\
violet red 4 & 139 & 34 & 82 \\
magenta 1 & 255 & 0 & 255 \\
magenta 2 & 238 & 0 & 238 \\
magenta 3 & 205 & 0 & 205 \\
magenta 4 & 139 & 0 & 139 \\
orchid 1 & 255 & 131 & 250 \\
orchid 2 & 238 & 122 & 233 \\
orchid 3 & 205 & 105 & 201 \\
orchid 4 & 139 & 71 & 137 \\
plum 1 & 255 & 187 & 255 \\
plum 2 & 238 & 174 & 238 \\
plum 3 & 205 & 150 & 205 \\
plum 4 & 139 & 102 & 139 \\
medium orchid 1 & 224 & 102 & 255 \\
medium orchid 2 & 209 & 95 & 238 \\
medium orchid 3 & 180 & 82 & 205 \\
medium orchid 4 & 122 & 55 & 139 \\
dark orchid 1 & 191 & 62 & 255 \\
dark orchid 2 & 178 & 58 & 238 \\
dark orchid 3 & 154 & 50 & 205 \\
dark orchid 4 & 104 & 34 & 139 \\
purple 1 & 155 & 48 & 255 \\
purple 2 & 145 & 44 & 238 \\
purple 3 & 125 & 38 & 205 \\
purple 4 & 85 & 26 & 139 \\
medium purple 1 & 171 & 130 & 255 \\
medium purple 2 & 159 & 121 & 238 \\
medium purple 3 & 137 & 104 & 205 \\
medium purple 4 & 93 & 71 & 139 \\
thistle 1 & 255 & 225 & 255 \\
thistle 2 & 238 & 210 & 238 \\
thistle 3 & 205 & 181 & 205 \\
thistle 4 & 139 & 123 & 139 \\
grey 0 & 0 & 0 & 0 \\
grey 1 & 3 & 3 & 3 \\
grey 2 & 5 & 5 & 5 \\
grey 3 & 8 & 8 & 8 \\
grey 4 & 10 & 10 & 10 \\
grey 5 & 13 & 13 & 13 \\
grey 6 & 15 & 15 & 15 \\
grey 7 & 18 & 18 & 18 \\
grey 8 & 20 & 20 & 20 \\
grey 9 & 23 & 23 & 23 \\
grey 10 & 26 & 26 & 26 \\
grey 11 & 28 & 28 & 28 \\
grey 12 & 31 & 31 & 31 \\
grey 13 & 33 & 33 & 33 \\
grey 14 & 36 & 36 & 36 \\
grey 15 & 38 & 38 & 38 \\
grey 16 & 41 & 41 & 41 \\
grey 17 & 43 & 43 & 43 \\
grey 18 & 46 & 46 & 46 \\
grey 19 & 48 & 48 & 48 \\
grey 20 & 51 & 51 & 51 \\
grey 21 & 54 & 54 & 54 \\
grey 22 & 56 & 56 & 56 \\
grey 23 & 59 & 59 & 59 \\
grey 24 & 61 & 61 & 61 \\
grey 25 & 64 & 64 & 64 \\
grey 26 & 66 & 66 & 66 \\
grey 27 & 69 & 69 & 69 \\
grey 28 & 71 & 71 & 71 \\
grey 29 & 74 & 74 & 74 \\
grey 30 & 77 & 77 & 77 \\
grey 31 & 79 & 79 & 79 \\
grey 32 & 82 & 82 & 82 \\
grey 33 & 84 & 84 & 84 \\
grey 34 & 87 & 87 & 87 \\
grey 35 & 89 & 89 & 89 \\
grey 36 & 92 & 92 & 92 \\
grey 37 & 94 & 94 & 94 \\
grey 38 & 97 & 97 & 97 \\
grey 39 & 99 & 99 & 99 \\
grey 40 & 102 & 102 & 102 \\
grey 41 & 105 & 105 & 105 \\
grey 42 & 107 & 107 & 107 \\
grey 43 & 110 & 110 & 110 \\
grey 44 & 112 & 112 & 112 \\
grey 45 & 115 & 115 & 115 \\
grey 46 & 117 & 117 & 117 \\
grey 47 & 120 & 120 & 120 \\
grey 48 & 122 & 122 & 122 \\
grey 49 & 125 & 125 & 125 \\
grey 50 & 127 & 127 & 127 \\
grey 51 & 130 & 130 & 130 \\
grey 52 & 133 & 133 & 133 \\
grey 53 & 135 & 135 & 135 \\
grey 54 & 138 & 138 & 138 \\
grey 55 & 140 & 140 & 140 \\
grey 56 & 143 & 143 & 143 \\
grey 57 & 145 & 145 & 145 \\
grey 58 & 148 & 148 & 148 \\
grey 59 & 150 & 150 & 150 \\
grey 60 & 153 & 153 & 153 \\
grey 61 & 156 & 156 & 156 \\
grey 62 & 158 & 158 & 158 \\
grey 63 & 161 & 161 & 161 \\
grey 64 & 163 & 163 & 163 \\
grey 65 & 166 & 166 & 166 \\
grey 66 & 168 & 168 & 168 \\
grey 67 & 171 & 171 & 171 \\
grey 68 & 173 & 173 & 173 \\
grey 69 & 176 & 176 & 176 \\
grey 70 & 179 & 179 & 179 \\
grey 71 & 181 & 181 & 181 \\
grey 72 & 184 & 184 & 184 \\
grey 73 & 186 & 186 & 186 \\
grey 74 & 189 & 189 & 189 \\
grey 75 & 191 & 191 & 191 \\
grey 76 & 194 & 194 & 194 \\
grey 77 & 196 & 196 & 196 \\
grey 78 & 199 & 199 & 199 \\
grey 79 & 201 & 201 & 201 \\
grey 80 & 204 & 204 & 204 \\
grey 81 & 207 & 207 & 207 \\
grey 82 & 209 & 209 & 209 \\
grey 83 & 212 & 212 & 212 \\
grey 84 & 214 & 214 & 214 \\
grey 85 & 217 & 217 & 217 \\
grey 86 & 219 & 219 & 219 \\
grey 87 & 222 & 222 & 222 \\
grey 88 & 224 & 224 & 224 \\
grey 89 & 227 & 227 & 227 \\
grey 90 & 229 & 229 & 229 \\
grey 91 & 232 & 232 & 232 \\
grey 92 & 235 & 235 & 235 \\
grey 93 & 237 & 237 & 237 \\
grey 94 & 240 & 240 & 240 \\
grey 95 & 242 & 242 & 242 \\
grey 96 & 245 & 245 & 245 \\
grey 97 & 247 & 247 & 247 \\
grey 98 & 250 & 250 & 250 \\
grey 99 & 252 & 252 & 252 \\
grey 100 & 255 & 255 & 255 \\
dark grey & 169 & 169 & 169 \\
dark blue & 0 & 0 & 139 \\
dark cyan & 0 & 139 & 139 \\
dark magenta & 139 & 0 & 139 \\
dark red & 139 & 0 & 0 \\
light green & 144 & 238 & 144 \\
\end{longtable}
\end{center}
\end{scriptsize}
\twocolumn


\subsubsection{Prompt examples}

To map\index{map} the order\index{order parameter} parameter values, $S^2$, onto the structure using the classic style, type:

\begin{lstlisting}[numbers=none]
relax> molmol.macro_apply('s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molmol.macro_apply(data_type='s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molmol.macro_apply(data_type='s2', style="classic")
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.macro\-\_run\index{software!MOLMOL|textbf}} \label{uf: molmol.macro_run}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Open and execute the Molmol\index{software!MOLMOL}\index{software!MOLMOL} macro file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]macro\_run}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]`molmol')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} macro file.

\hspace{3 mm}\keyword{dir:}  The directory name.


\subsubsection{Description}

This user function is for opening and running a Molmol\index{software!MOLMOL}\index{software!MOLMOL} macro located within a text file.

\subsubsection{Prompt examples}

To execute the macro file \quotecmd{s2.mac} located in the directory \quotecmd{molmol}, type:

\begin{lstlisting}[numbers=none]
relax> molmol.macro_run(file='s2.mac')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molmol.macro_run(file='s2.mac', dir='molmol')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.macro\-\_write\index{software!MOLMOL|textbf}} \label{uf: molmol.macro_write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create Molmol\index{software!MOLMOL}\index{software!MOLMOL} macros.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]macro\_write}(\linebreak[0]data\_type=\linebreak[0]None, style=\linebreak[0]`classic', colour\_start\_name=\linebreak[0]None, colour\_start\_rgb=\linebreak[0]None, colour\_end\_name=\linebreak[0]None, colour\_end\_rgb=\linebreak[0]None, colour\_list=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]`molmol', force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{data\_type:}  The data type to map\index{map} to the structure.

\hspace{3 mm}\keyword{style:}  The style of the macro.

\hspace{3 mm}\keyword{colour\_start\_name:}  The name of the starting colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the starting colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_start\_rgb:}  The starting colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the starting colour name cannot be given.

\hspace{3 mm}\keyword{colour\_end\_name:}  The name of the ending colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the ending colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_end\_rgb:}  The ending colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the ending colour name cannot be given.

\hspace{3 mm}\keyword{colour\_list:}  The colour list to search for the colour names.  This can be either \quotecmd{molmol} or \quotecmd{x11}.

\hspace{3 mm}\keyword{file:}  The optional name of the file.

\hspace{3 mm}\keyword{dir:}  The optional directory to save the file to.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the file to be overwritten.


\subsubsection{Description}

This allows residues specific values to be mapped\index{map} to a structure through the creation of a Molmol\index{software!MOLMOL}\index{software!MOLMOL} \quotecmd{*.mac} macro which can be executed in Molmol\index{software!MOLMOL}\index{software!MOLMOL} by clicking on \quotecmd{File, Macro, Execute User...}.  Currently only the \quotecmd{classic} style, which is described below, is available.

\subsubsection{Colour}

The values are coloured based on a linear colour gradient which is specified through starting and ending colours.  These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself.  For example, \quotecmd{white} and [1.0, 1.0, 1.0] both select the same colour.  Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings.  These are the default Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour list and the X11 colour list, both of which are described in the tables below.  The default behaviour is to first search the Molmol\index{software!MOLMOL}\index{software!MOLMOL} list and then the X11 colour list, raising an error if neither contain the name.  To explicitly select these lists, set the colour list to either \quotecmd{molmol} or \quotecmd{x11}.

\subsubsection{Model-free classic style}

Creator:  Edward d'Auvergne

Argument string:  "classic"

Description:  The classic style draws the backbone of a protein in a cylindrical bond style.  Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured.  Deselected residues are shown as black lines.

Supported data types:

Please see Table~\ref{table: model-free macro classic style} on page~\pageref{table: model-free macro classic style}.

\subsubsection{Molmol RGB colour arrays}

The following table is a list of colours used in Molmol\index{software!MOLMOL}\index{software!MOLMOL} and their corresponding RGB colour values ranging from 0 to 1.

Please see Table~\ref{table: Molmol colours} on page~\pageref{table: Molmol colours}.

\subsubsection{X11 RGB colour arrays}

The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.

Please see Table~\ref{table: X11 colours} on page~\pageref{table: X11 colours}.

\subsubsection{Prompt examples}

To create a Molmol\index{software!MOLMOL}\index{software!MOLMOL} macro mapping\index{map} the order\index{order parameter} parameter values, $S^2$, onto the structure using the classic style, type:

\begin{lstlisting}[numbers=none]
relax> molmol.macro_write('s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molmol.macro_write(data_type='s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> molmol.macro_write(data_type='s2', style="classic", file='s2.mac', dir='molmol')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.ribbon\index{software!MOLMOL|textbf}} \label{uf: molmol.ribbon}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill 

\subsubsection{Synopsis}

Apply the Molmol\index{software!MOLMOL}\index{software!MOLMOL} ribbon style.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]ribbon}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This applies the Molmol\index{software!MOLMOL}\index{software!MOLMOL} ribbon style which is equivalent to clicking on \quotecmd{ribbon} in the Molmol\index{software!MOLMOL}\index{software!MOLMOL} side menu.  To do this, the following commands are executed:

\begin{itemize}
  \item[]CalcAtom \quotecmd{H}
  \item[]CalcAtom \quotecmd{HN}
  \item[]CalcSecondary
  \item[]XMacStand ribbon.mac
\end{itemize}

\subsubsection{Prompt examples}

To apply the ribbon style to the PDB\index{PDB} file loaded, type:

\begin{lstlisting}[numbers=none]
relax> molmol.ribbon()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.tensor\-\_pdb\index{software!MOLMOL|textbf}} \label{uf: molmol.tensor_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill 

\subsubsection{Synopsis}

Display\index{display} the diffusion\index{diffusion!tensor} tensor PDB\index{PDB} geometric object over the loaded PDB.\index{PDB}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]tensor\_pdb}(\linebreak[0]file=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file containing the tensor geometric object.


\subsubsection{Description}

In executing this user function, a PDB\index{PDB} file must have previously been loaded , a geometric object or polygon representing the Brownian\index{diffusion!Brownian} rotational\index{rotation} diffusion\index{diffusion!tensor} tensor will be overlain with the loaded PDB\index{PDB} file and displayed\index{display} within Molmol.\index{software!MOLMOL}\index{software!MOLMOL}  The PDB\index{PDB} file containing the geometric object must be created using the complementary structure.create\_diff\_tensor\_pdb user function.

To display\index{display} the diffusion\index{diffusion!tensor} tensor, the multiple commands will be executed.  To overlay the structure with the diffusion\index{diffusion!tensor} tensor, everything will be selected and reoriented and moved to their original PDB\index{PDB} frame positions:

\begin{itemize}
  \item[]SelectAtom \quotecmd{}
  \item[]SelectBond \quotecmd{}
  \item[]SelectAngle \quotecmd{}
  \item[]SelectDist \quotecmd{}
  \item[]SelectPrim \quotecmd{}
  \item[]RotateInit
  \item[]MoveInit
\end{itemize}

Next the tensor PDB\index{PDB} file is read\index{read} in, selected, and the covalent bonds of the PDB\index{PDB} CONECT records calculated:

\begin{itemize}
  \item[]ReadPdb\index{read} file
  \item[]SelectMol \quotecmd{@file}
  \item[]CalcBond 1 1 1
\end{itemize}

Then only the atoms and bonds of the geometric object are selected and the \quotecmd{ball/stick} style applied:

\begin{itemize}
  \item[]SelectAtom \quotecmd{0}
  \item[]SelectBond \quotecmd{0}
  \item[]SelectAtom \quotecmd{:TNS}
  \item[]SelectBond \quotecmd{:TNS}
  \item[]XMacStand ball\_stick.mac
\end{itemize}

The appearance is finally touched up:

\begin{itemize}
  \item[]RadiusAtom 1
  \item[]SelectAtom \quotecmd{:TNS@C*}
  \item[]RadiusAtom 1.5
\end{itemize}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{molmol\-.view\index{software!MOLMOL|textbf}} \label{uf: molmol.view}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/molmol} \hfill 

\subsubsection{Synopsis}

View the collection of molecules\index{molecule} from the loaded PDB\index{PDB} file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{molmol.\linebreak[0]view}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will simply launch Molmol.\index{software!MOLMOL}\index{software!MOLMOL}

\subsubsection{Prompt examples}

\begin{lstlisting}[numbers=none]
relax> molmol.view()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{monte\-\_carlo\-.create\-\_data} \label{uf: monte_carlo.create_data}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create the Monte Carlo simulation data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{monte\_carlo.\linebreak[0]create\_data}(\linebreak[0]method=\linebreak[0]`back\_calc', distribution=\linebreak[0]`measured', fixed\_error=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{method:}  The simulation method.

\hspace{3 mm}\keyword{distribution:}  The error distribution method.

\hspace{3 mm}\keyword{fixed\_error:}  The fixed value to use when distribution is set to \quotecmd{fixed}.


\subsubsection{Description}

The method can either be set to back calculation (Monte Carlo) or direct (bootstrapping), the choice of which determines the simulation type.  If the values or parameters are calculated rather than minimised,\index{optimisation} this option will have no effect.  Errors should only be propagated via Monte Carlo simulations if errors have been measured. 

For error analysis, the method should be set to back calculation which will result in proper Monte Carlo simulations.  The data used for each simulation is back calculated from the minimised\index{optimisation} model parameters and is randomised using Gaussian noise where the standard deviation is from the original error set.  When the method is set to back calculation, this function should only be called after the model is fully minimised.\index{optimisation}

The simulation type can be changed by setting the method to direct.  This will result in bootstrapping\index{model selection!bootstrap} simulations which cannot be used in error analysis (and which are no longer Monte Carlo simulations).  However, these simulations are required for certain model selection techniques (see the documentation for the model selection user function for details), and can be used for other purposes.  Rather than the data being back calculated from the fitted model parameters, the data is generated by taking the original data and randomising using Gaussian noise with the standard deviations set to the original error set.

The errors generated per simulation can either be generated indidual per datapoint and drawn from a gauss distrubtion described by the standard deviation of the indidual point, or it can be generated from a overall gauss distribution described by the standard deviation of the goodness of fit, where SD\_fit = sqrt(chi2/(N-p)).  The last possibility is to supply a fixed value of the standard deviation, from which gauss distribution to draw errors from.

\subsubsection{Monte Carlo Simulation Overview}

For proper error analysis using Monte Carlo simulations, a sequence\index{sequence} of function calls is required for running the various simulation components.  The steps necessary for implementing Monte Carlo simulations are:

\begin{description}
  \item[1 --] The measured data set together with the corresponding error set should be loaded into relax.
  \item[2 --] Either minimisation\index{optimisation} is used to optimise\index{optimise} the parameters of the chosen model, or a calculation is run.
  \item[3 --] To initialise and turn on Monte Carlo simulations, the number of simulations, $n$, needs to be set.
  \item[4 --] The simulation data needs to be created either by back calculation from the fully minimised\index{optimisation} model parameters from step 2 or by direct calculation when values are calculated rather than minimised.\index{optimisation}  The error set is used to randomise each simulation data set by assuming Gaussian errors.  This creates a synthetic data set for each Monte Carlo simulation.
  \item[5 --] Prior to minimisation\index{optimisation} of the parameters of each simulation, initial parameter estimates are required.  These are taken as the optimised\index{optimise} model parameters.  An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive.  For the case where values are calculated rather than minimised,\index{optimisation} this step should be skipped (although the results will be unaffected if this is accidentally run).
  \item[6 --] Each simulation requires minimisation\index{optimisation} or calculation.  The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
  \item[7 --] Failed simulations are removed using the techniques of model\index{model elimination} elimination.\index{model elimination}
  \item[8 --] The model parameter errors are calculated from the distribution of simulation parameters.
\end{description}

Monte Carlo simulations can be turned on or off using functions within this class.  Once the function for setting up simulations has been called, simulations will be turned on.  The effect of having simulations turned on is that the functions used for minimisation\index{optimisation} (grid search, minimise,\index{optimisation} etc) or calculation will only affect the simulation parameters and not the model parameters.  By subsequently turning simulations off using the appropriate function, the functions used in minimisation\index{optimisation} will affect the model parameters and not the simulation parameters.

An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:

\begin{lstlisting}[numbers=none]
relax> minimise.grid_search(inc=11)                              # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.initial_values()                              # Step 5.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> eliminate()                                               # Step 7.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}


An example for reduced spectral density mapping\index{map} is:

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{monte\-\_carlo\-.error\-\_analysis} \label{uf: monte_carlo.error_analysis}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue}

\subsubsection{Synopsis}

Calculate parameter errors from the Monte Carlo simulations.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{monte\_carlo.\linebreak[0]error\_analysis}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

Parameter errors are calculated as the standard deviation of the distribution of parameter values.  This function should never be used if parameter values are obtained by minimisation\index{optimisation} and the simulation data are generated using the method \quotecmd{direct}.  The reason is because only true Monte Carlo simulations can give the true parameter errors.

\subsubsection{Monte Carlo Simulation Overview}

For proper error analysis using Monte Carlo simulations, a sequence\index{sequence} of function calls is required for running the various simulation components.  The steps necessary for implementing Monte Carlo simulations are:

\begin{description}
  \item[1 --] The measured data set together with the corresponding error set should be loaded into relax.
  \item[2 --] Either minimisation\index{optimisation} is used to optimise\index{optimise} the parameters of the chosen model, or a calculation is run.
  \item[3 --] To initialise and turn on Monte Carlo simulations, the number of simulations, $n$, needs to be set.
  \item[4 --] The simulation data needs to be created either by back calculation from the fully minimised\index{optimisation} model parameters from step 2 or by direct calculation when values are calculated rather than minimised.\index{optimisation}  The error set is used to randomise each simulation data set by assuming Gaussian errors.  This creates a synthetic data set for each Monte Carlo simulation.
  \item[5 --] Prior to minimisation\index{optimisation} of the parameters of each simulation, initial parameter estimates are required.  These are taken as the optimised\index{optimise} model parameters.  An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive.  For the case where values are calculated rather than minimised,\index{optimisation} this step should be skipped (although the results will be unaffected if this is accidentally run).
  \item[6 --] Each simulation requires minimisation\index{optimisation} or calculation.  The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
  \item[7 --] Failed simulations are removed using the techniques of model\index{model elimination} elimination.\index{model elimination}
  \item[8 --] The model parameter errors are calculated from the distribution of simulation parameters.
\end{description}

Monte Carlo simulations can be turned on or off using functions within this class.  Once the function for setting up simulations has been called, simulations will be turned on.  The effect of having simulations turned on is that the functions used for minimisation\index{optimisation} (grid search, minimise,\index{optimisation} etc) or calculation will only affect the simulation parameters and not the model parameters.  By subsequently turning simulations off using the appropriate function, the functions used in minimisation\index{optimisation} will affect the model parameters and not the simulation parameters.

An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:

\begin{lstlisting}[numbers=none]
relax> minimise.grid_search(inc=11)                              # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.initial_values()                              # Step 5.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> eliminate()                                               # Step 7.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}


An example for reduced spectral density mapping\index{map} is:

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{monte\-\_carlo\-.initial\-\_values} \label{uf: monte_carlo.initial_values}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Set the initial simulation parameter values.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{monte\_carlo.\linebreak[0]initial\_values}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This only effects where minimisation\index{optimisation} occurs and can therefore be skipped if the values or parameters are calculated rather than minimised.\index{optimisation}  However, if accidentally run in this case, the results will be unaffected.  It should only be called after the model or run is fully minimised.\index{optimisation}  Once called, the user functions minimise.grid\_search\index{optimisation} and minimise.execute\index{optimisation} will only effect the simulations and not the model parameters.

The initial values of the parameters for each simulation is set to the minimised\index{optimisation} parameters of the model.  A grid search can be undertaken for each simulation instead, although this is computationally expensive and unnecessary.  The minimisation\index{optimisation} function should be executed for a second time after running this function.

\subsubsection{Monte Carlo Simulation Overview}

For proper error analysis using Monte Carlo simulations, a sequence\index{sequence} of function calls is required for running the various simulation components.  The steps necessary for implementing Monte Carlo simulations are:

\begin{description}
  \item[1 --] The measured data set together with the corresponding error set should be loaded into relax.
  \item[2 --] Either minimisation\index{optimisation} is used to optimise\index{optimise} the parameters of the chosen model, or a calculation is run.
  \item[3 --] To initialise and turn on Monte Carlo simulations, the number of simulations, $n$, needs to be set.
  \item[4 --] The simulation data needs to be created either by back calculation from the fully minimised\index{optimisation} model parameters from step 2 or by direct calculation when values are calculated rather than minimised.\index{optimisation}  The error set is used to randomise each simulation data set by assuming Gaussian errors.  This creates a synthetic data set for each Monte Carlo simulation.
  \item[5 --] Prior to minimisation\index{optimisation} of the parameters of each simulation, initial parameter estimates are required.  These are taken as the optimised\index{optimise} model parameters.  An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive.  For the case where values are calculated rather than minimised,\index{optimisation} this step should be skipped (although the results will be unaffected if this is accidentally run).
  \item[6 --] Each simulation requires minimisation\index{optimisation} or calculation.  The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
  \item[7 --] Failed simulations are removed using the techniques of model\index{model elimination} elimination.\index{model elimination}
  \item[8 --] The model parameter errors are calculated from the distribution of simulation parameters.
\end{description}

Monte Carlo simulations can be turned on or off using functions within this class.  Once the function for setting up simulations has been called, simulations will be turned on.  The effect of having simulations turned on is that the functions used for minimisation\index{optimisation} (grid search, minimise,\index{optimisation} etc) or calculation will only affect the simulation parameters and not the model parameters.  By subsequently turning simulations off using the appropriate function, the functions used in minimisation\index{optimisation} will affect the model parameters and not the simulation parameters.

An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:

\begin{lstlisting}[numbers=none]
relax> minimise.grid_search(inc=11)                              # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.initial_values()                              # Step 5.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> eliminate()                                               # Step 7.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}


An example for reduced spectral density mapping\index{map} is:

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{monte\-\_carlo\-.off} \label{uf: monte_carlo.off}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/dialog-cancel}

\subsubsection{Synopsis}

Turn the Monte Carlo simulations off.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{monte\_carlo.\linebreak[0]off}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will turn off the Monte Carlo simulations so that subsequent optimisation will operate directly on the model parameters and not on the simulations.

\subsubsection{Monte Carlo Simulation Overview}

For proper error analysis using Monte Carlo simulations, a sequence\index{sequence} of function calls is required for running the various simulation components.  The steps necessary for implementing Monte Carlo simulations are:

\begin{description}
  \item[1 --] The measured data set together with the corresponding error set should be loaded into relax.
  \item[2 --] Either minimisation\index{optimisation} is used to optimise\index{optimise} the parameters of the chosen model, or a calculation is run.
  \item[3 --] To initialise and turn on Monte Carlo simulations, the number of simulations, $n$, needs to be set.
  \item[4 --] The simulation data needs to be created either by back calculation from the fully minimised\index{optimisation} model parameters from step 2 or by direct calculation when values are calculated rather than minimised.\index{optimisation}  The error set is used to randomise each simulation data set by assuming Gaussian errors.  This creates a synthetic data set for each Monte Carlo simulation.
  \item[5 --] Prior to minimisation\index{optimisation} of the parameters of each simulation, initial parameter estimates are required.  These are taken as the optimised\index{optimise} model parameters.  An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive.  For the case where values are calculated rather than minimised,\index{optimisation} this step should be skipped (although the results will be unaffected if this is accidentally run).
  \item[6 --] Each simulation requires minimisation\index{optimisation} or calculation.  The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
  \item[7 --] Failed simulations are removed using the techniques of model\index{model elimination} elimination.\index{model elimination}
  \item[8 --] The model parameter errors are calculated from the distribution of simulation parameters.
\end{description}

Monte Carlo simulations can be turned on or off using functions within this class.  Once the function for setting up simulations has been called, simulations will be turned on.  The effect of having simulations turned on is that the functions used for minimisation\index{optimisation} (grid search, minimise,\index{optimisation} etc) or calculation will only affect the simulation parameters and not the model parameters.  By subsequently turning simulations off using the appropriate function, the functions used in minimisation\index{optimisation} will affect the model parameters and not the simulation parameters.

An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:

\begin{lstlisting}[numbers=none]
relax> minimise.grid_search(inc=11)                              # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.initial_values()                              # Step 5.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> eliminate()                                               # Step 7.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}


An example for reduced spectral density mapping\index{map} is:

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{monte\-\_carlo\-.on} \label{uf: monte_carlo.on}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/dialog-ok}

\subsubsection{Synopsis}

Turn the Monte Carlo simulations on.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{monte\_carlo.\linebreak[0]on}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will turn on the Monte Carlo simulations so that subsequent optimisation will operate on the simulations rather than on the real model parameters.

\subsubsection{Monte Carlo Simulation Overview}

For proper error analysis using Monte Carlo simulations, a sequence\index{sequence} of function calls is required for running the various simulation components.  The steps necessary for implementing Monte Carlo simulations are:

\begin{description}
  \item[1 --] The measured data set together with the corresponding error set should be loaded into relax.
  \item[2 --] Either minimisation\index{optimisation} is used to optimise\index{optimise} the parameters of the chosen model, or a calculation is run.
  \item[3 --] To initialise and turn on Monte Carlo simulations, the number of simulations, $n$, needs to be set.
  \item[4 --] The simulation data needs to be created either by back calculation from the fully minimised\index{optimisation} model parameters from step 2 or by direct calculation when values are calculated rather than minimised.\index{optimisation}  The error set is used to randomise each simulation data set by assuming Gaussian errors.  This creates a synthetic data set for each Monte Carlo simulation.
  \item[5 --] Prior to minimisation\index{optimisation} of the parameters of each simulation, initial parameter estimates are required.  These are taken as the optimised\index{optimise} model parameters.  An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive.  For the case where values are calculated rather than minimised,\index{optimisation} this step should be skipped (although the results will be unaffected if this is accidentally run).
  \item[6 --] Each simulation requires minimisation\index{optimisation} or calculation.  The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
  \item[7 --] Failed simulations are removed using the techniques of model\index{model elimination} elimination.\index{model elimination}
  \item[8 --] The model parameter errors are calculated from the distribution of simulation parameters.
\end{description}

Monte Carlo simulations can be turned on or off using functions within this class.  Once the function for setting up simulations has been called, simulations will be turned on.  The effect of having simulations turned on is that the functions used for minimisation\index{optimisation} (grid search, minimise,\index{optimisation} etc) or calculation will only affect the simulation parameters and not the model parameters.  By subsequently turning simulations off using the appropriate function, the functions used in minimisation\index{optimisation} will affect the model parameters and not the simulation parameters.

An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:

\begin{lstlisting}[numbers=none]
relax> minimise.grid_search(inc=11)                              # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.initial_values()                              # Step 5.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> eliminate()                                               # Step 7.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}


An example for reduced spectral density mapping\index{map} is:

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{monte\-\_carlo\-.setup} \label{uf: monte_carlo.setup}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/roll-relax-blue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-edit}

\subsubsection{Synopsis}

Set up the Monte Carlo simulations.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{monte\_carlo.\linebreak[0]setup}(\linebreak[0]number=\linebreak[0]500)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{number:}  The number of Monte Carlo simulations.


\subsubsection{Description}

This must be called prior to any of the other Monte Carlo functions.  The effect is that the number of simulations will be set and that simulations will be turned on.

\subsubsection{Monte Carlo Simulation Overview}

For proper error analysis using Monte Carlo simulations, a sequence\index{sequence} of function calls is required for running the various simulation components.  The steps necessary for implementing Monte Carlo simulations are:

\begin{description}
  \item[1 --] The measured data set together with the corresponding error set should be loaded into relax.
  \item[2 --] Either minimisation\index{optimisation} is used to optimise\index{optimise} the parameters of the chosen model, or a calculation is run.
  \item[3 --] To initialise and turn on Monte Carlo simulations, the number of simulations, $n$, needs to be set.
  \item[4 --] The simulation data needs to be created either by back calculation from the fully minimised\index{optimisation} model parameters from step 2 or by direct calculation when values are calculated rather than minimised.\index{optimisation}  The error set is used to randomise each simulation data set by assuming Gaussian errors.  This creates a synthetic data set for each Monte Carlo simulation.
  \item[5 --] Prior to minimisation\index{optimisation} of the parameters of each simulation, initial parameter estimates are required.  These are taken as the optimised\index{optimise} model parameters.  An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive.  For the case where values are calculated rather than minimised,\index{optimisation} this step should be skipped (although the results will be unaffected if this is accidentally run).
  \item[6 --] Each simulation requires minimisation\index{optimisation} or calculation.  The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.
  \item[7 --] Failed simulations are removed using the techniques of model\index{model elimination} elimination.\index{model elimination}
  \item[8 --] The model parameter errors are calculated from the distribution of simulation parameters.
\end{description}

Monte Carlo simulations can be turned on or off using functions within this class.  Once the function for setting up simulations has been called, simulations will be turned on.  The effect of having simulations turned on is that the functions used for minimisation\index{optimisation} (grid search, minimise,\index{optimisation} etc) or calculation will only affect the simulation parameters and not the model parameters.  By subsequently turning simulations off using the appropriate function, the functions used in minimisation\index{optimisation} will affect the model parameters and not the simulation parameters.

An example for model-free analysis using the prompt UI mode which includes only the functions required for implementing the above steps is:

\begin{lstlisting}[numbers=none]
relax> minimise.grid_search(inc=11)                              # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.initial_values()                              # Step 5.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.execute('newton')                                # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> eliminate()                                               # Step 7.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}


An example for reduced spectral density mapping\index{map} is:

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 2.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.setup(number=500)                             # Step 3.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.create_data(method='back_calc')               # Step 4.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> minimise.calculate()                                      # Step 6.
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> monte_carlo.error_analysis()                              # Step 8.
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{n\-\_state\-\_model\-.CoM} \label{uf: n_state_model.CoM}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/n_state_model} \hfill 

\subsubsection{Synopsis}

The defunct centre of mass (CoM) analysis.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{n\_state\_model.\linebreak[0]CoM}(\linebreak[0]pivot\_point=\linebreak[0][0.0, 0.0, 0.0], centre=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pivot\_point:}  The pivot point of the motions between the two domains.

\hspace{3 mm}\keyword{centre:}  Manually specify the CoM of the initial position prior to the N rotations\index{rotation} to the positions of the N states.  This is optional.


\subsubsection{Description}

WARNING:  This analysis is now defunct!

This is used for analysing the domain motion information content of the N states from the N-state model.  The states do not correspond to physical states, hence nothing can be extracted from the individual states.  This analysis involves the calculation of the pivot to centre of mass (pivot-CoM) order\index{order parameter} parameter and subsequent cone of motions.

For the analysis, both the pivot point and centre of mass must be specified.  The supplied pivot point must be a vector of floating\index{floating point number} point numbers of length 3.  If the centre of mass is supplied, it must also be a vector of floating\index{floating point number} point numbers (of length 3).  If the centre of mass is not supplied, then the CoM will be calculated from the selected parts of a previously loaded structure.

\subsubsection{Prompt examples}

To perform an analysis where the pivot is at the origin and the CoM is set to the N-terminal domain of a previously loaded PDB\index{PDB} file (the C-terminal domain has been deselected), type:

\begin{lstlisting}[numbers=none]
relax> n_state_model.CoM()
\end{lstlisting}


To perform an analysis where the pivot is at the origin (because the real pivot has been shifted to this position) and the CoM is at the position [0, 0, 1], type one of:

\begin{lstlisting}[numbers=none]
relax> n_state_model.CoM(centre=[0, 0, 1])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> n_state_model.CoM(centre=[0.0, 0.0, 1.0])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> n_state_model.CoM(pivot_point=[0.0, 0.0, 0.0], centre=[0.0, 0.0, 1.0])
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{n\-\_state\-\_model\-.cone\-\_pdb} \label{uf: n_state_model.cone_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/n_state_model} \hfill 

\subsubsection{Synopsis}

Create a PDB\index{PDB} file representing the cone models from the centre of mass (CoM) analysis.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{n\_state\_model.\linebreak[0]cone\_pdb}(\linebreak[0]cone\_type=\linebreak[0]None, scale=\linebreak[0]1.0, file=\linebreak[0]`cone.\linebreak[0]pdb', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{cone\_type:}  The type of cone model to represent.

\hspace{3 mm}\keyword{scale:}  Value for scaling the pivot-CoM distance which the size of the cone defaults to.

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will overwrite the any pre-existing file.


\subsubsection{Description}

WARNING:  This analysis is now defunct!

This creates a PDB\index{PDB} file containing an artificial geometric structure to represent the various cone models.  These models include:

\begin{itemize}
  \item[]\quotecmd{diff in cone}
  \item[]\quotecmd{diff on cone}
\end{itemize}

The model can be selected by setting the cone type to one of these values.  The cone is represented as an isotropic\index{diffusion!sphere (isotropic)} cone with its axis parallel to the average pivot-CoM vector, the vertex placed at the pivot point of the domain motions, and the length of the edge of the cone equal to the pivot-CoM distance multiplied by the scaling factor.  The resultant PDB\index{PDB} file can subsequently read\index{read} into any molecular viewer.

There are four different types of residue within the PDB.\index{PDB}  The pivot point is represented as as a single carbon atom of the residue \quotecmd{PIV}.  The cone consists of numerous H atoms of the residue \quotecmd{CON}.  The average pivot-CoM vector is presented as the residue \quotecmd{AVE} with one carbon atom positioned at the pivot and the other at the head of the vector (after scaling by the scaling factor).  Finally, if Monte Carlo have been performed, there will be multiple \quotecmd{MCC} residues representing the cone for each simulation, and multiple \quotecmd{MCA} residues representing the varying average pivot-CoM vector for each simulation.

To create the diffusion in a cone PDB\index{PDB} representation, a uniform distribution of vectors on a sphere\index{diffusion!sphere (isotropic)} is generated using spherical coordinates with the polar angle\index{angles} defined from the average pivot-CoM vector.  By incrementing the polar angle\index{angles} using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle\index{angles} evenly creates the longitudinal vectors.  These are all placed into the PDB\index{PDB} file as H atoms and are all connected using PDB\index{PDB} CONECT records.  Each H atom is connected to its two neighbours on the both the longitude and latitude.  This creates a geometric PDB\index{PDB} object with longitudinal and latitudinal lines representing the filled cone.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{n\-\_state\-\_model\-.elim\-\_no\-\_prob} \label{uf: n_state_model.elim_no_prob}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/n_state_model} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Eliminate the structures or states with no probability.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{n\_state\_model.\linebreak[0]elim\_no\_prob}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will simply remove the structures from the N-state analysis which have an optimised\index{optimise} probability of zero.

\subsubsection{Prompt examples}

Simply type:

\begin{lstlisting}[numbers=none]
relax> n_state_model.elim_no_prob(N=8)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{n\-\_state\-\_model\-.number\-\_of\-\_states} \label{uf: n_state_model.number_of_states}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/n_state_model} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the number of states in the N-state model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{n\_state\_model.\linebreak[0]number\_of\_states}(\linebreak[0]N=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{N:}  The number of states.


\subsubsection{Description}

Prior to optimisation, the number of states in the N-state model can be specified.  If the number of states is not set, then this parameter will be equal to the number of loaded structures - the ensemble size.

\subsubsection{Prompt examples}

To set up an 8-state model, type:

\begin{lstlisting}[numbers=none]
relax> n_state_model.number_of_states(N=8)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{n\-\_state\-\_model\-.ref\-\_domain} \label{uf: n_state_model.ref_domain}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/n_state_model} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the reference domain for the \quotecmd{2-domain} N-state model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{n\_state\_model.\linebreak[0]ref\_domain}(\linebreak[0]ref=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ref:}  The domain which will act as the frame of reference.  This is only valid for the \quotecmd{2-domain} N-state model.


\subsubsection{Description}

Prior to optimisation of the \quotecmd{2-domain} N-state model, which of the two domains will act as the frame of reference must be specified.  The N-states will be rotations\index{rotation} of the other domain, so to switch the frame of reference to the other domain simply transpose the rotation\index{rotation} matrices.

\subsubsection{Prompt examples}

To set up a 5-state model with \quotecmd{C} domain being the frame of reference, type:

\begin{lstlisting}[numbers=none]
relax> n_state_model.ref_domain(ref='C')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{n\-\_state\-\_model\-.select\-\_model} \label{uf: n_state_model.select_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/n_state_model} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Select the N-state model type and set up the model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{n\_state\_model.\linebreak[0]select\_model}(\linebreak[0]model=\linebreak[0]`population')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The name of the preset N-state model.


\subsubsection{Description}

Prior to optimisation, the N-state model type should be selected.  The preset models are:

\begin{description}
  \item[\quotecmd{population} --] The N-state model whereby only populations are optimised.\index{optimise}  The structures loaded into relax are assumed to be fixed, $i$.e. the orientations are not optimised,\index{optimise} or if two domains are present the Euler\index{Euler angles} angles\index{angles} for each state are fixed.  The parameters of the model include the weight or probability for each state and the alignment tensors - \{p0, p1, ..., pN, Axx, Ayy, Axy, Axz, Ayz, ...\}.
  \item[\quotecmd{fixed} --] The N-state model whereby all motions are fixed and all populations are fixed to the set probabilities.  The parameters of the model are simply the parameters of each alignment tensor \{Axx, Ayy, Axy, Axz, Ayz, ...\}.
  \item[\quotecmd{2-domain} --] The N-state model for a system of two domains, where one domain experiences a reduced tensor.
\end{description}

\subsubsection{Prompt examples}

To analyse populations of states, type:

\begin{lstlisting}[numbers=none]
relax> n_state_model.select_model(model='populations')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{noe\-.read\-\_restraints} \label{uf: noe.read_restraints}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/noe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} NOESY or ROESY restraints from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{noe.\linebreak[0]read\_restraints}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, proton1\_col=\linebreak[0]None, proton2\_col=\linebreak[0]None, lower\_col=\linebreak[0]None, upper\_col=\linebreak[0]None, sep=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the restraint data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{proton1\_col:}  The column containing the first proton of the NOE or ROE cross peak.

\hspace{3 mm}\keyword{proton2\_col:}  The column containing the second proton of the NOE or ROE cross peak.

\hspace{3 mm}\keyword{lower\_col:}  The column containing the lower NOE bound.\index{parameter!bounds}

\hspace{3 mm}\keyword{upper\_col:}  The column containing the upper NOE bound.\index{parameter!bounds}

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).


\subsubsection{Description}

The format of the file will be automatically determined, for example Xplor formatted restraint files.  A generically formatted file is also supported if it contains minimally four columns with the two proton names and the upper and lower bounds,\index{parameter!bounds} as specified by the column numbers.  The proton names need to be in the spin ID string format.

\subsubsection{Prompt examples}

To read\index{read} the Xplor formatted restraint file \quotecmd{NOE.xpl}, type one of:

\begin{lstlisting}[numbers=none]
relax> noe.read_restraints('NOE.xpl')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> noe.read_restraints(file='NOE.xpl')
\end{lstlisting}


To read\index{read} the generic formatted file \quotecmd{noes}, type one of:

\begin{lstlisting}[numbers=none]
relax> noe.read_restraints(file='NOE.xpl', proton1_col=0, proton2_col=1, lower_col=2, upper_col=3)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{noe\-.spectrum\-\_type} \label{uf: noe.spectrum_type}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/noe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the steady-state NOE spectrum type for pre-loaded peak intensities.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{noe.\linebreak[0]spectrum\_type}(\linebreak[0]spectrum\_type=\linebreak[0]None, spectrum\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_type:}  The type of steady-state NOE spectrum, one of \quotecmd{ref} for the reference spectrum or \quotecmd{sat} for the saturated spectrum.

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string.


\subsubsection{Description}

The spectrum type can be one of the following:

\begin{itemize}
  \item[]The steady-state NOE reference spectrum.
  \item[]The steady-state NOE spectrum with proton saturation turned on.
\end{itemize}

Peak intensities should be loaded before this user function via the spectrum.read\_intensities user function.  The intensity values will then be associated with a spectrum ID string which can be used here.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{palmer\-.create} \label{uf: palmer.create}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/modelfree4} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create the Modelfree4\index{software!Modelfree}\index{software!Modelfree} input files.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{palmer.\linebreak[0]create}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False, binary=\linebreak[0]`modelfree4', diff\_search=\linebreak[0]`none', sims=\linebreak[0]0, sim\_type=\linebreak[0]`pred', trim=\linebreak[0]0, steps=\linebreak[0]20, constraints=\linebreak[0]True, heteronuc\_type=\linebreak[0]`15N', atom1=\linebreak[0]`N', atom2=\linebreak[0]`H', spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory to place the files.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the results file to be overwritten if it already exists.

\hspace{3 mm}\keyword{binary:}  The name of the executable Modelfree program file.

\hspace{3 mm}\keyword{diff\_search:}  See the Modelfree4\index{software!Modelfree}\index{software!Modelfree} manual for \quotecmd{diffusion\_search}.

\hspace{3 mm}\keyword{sims:}  The number of Monte Carlo simulations.

\hspace{3 mm}\keyword{sim\_type:}  See the Modelfree4\index{software!Modelfree}\index{software!Modelfree} manual.

\hspace{3 mm}\keyword{trim:}  See the Modelfree4\index{software!Modelfree}\index{software!Modelfree} manual.

\hspace{3 mm}\keyword{steps:}  See the Modelfree4\index{software!Modelfree}\index{software!Modelfree} manual.

\hspace{3 mm}\keyword{constraints:}  A flag specifying whether the parameters should be constrained.  The default is to turn constraints\index{constraint} on (constraints=True).

\hspace{3 mm}\keyword{heteronuc\_type:}  A three letter string describing the heteronucleus type, ie \quotecmd{15N}, \quotecmd{13C}, etc.

\hspace{3 mm}\keyword{atom1:}  The symbol of the X heteronucleus in the PDB\index{PDB} file.

\hspace{3 mm}\keyword{atom2:}  The symbol of the H nucleus in the PDB\index{PDB} file.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

The following files are created

\begin{itemize}
  \item[]\quotecmd{dir/mfin}
  \item[]\quotecmd{dir/mfdata}
  \item[]\quotecmd{dir/mfpar}
  \item[]\quotecmd{dir/mfmodel}
  \item[]\quotecmd{dir/run.sh}
\end{itemize}

The file \quotecmd{dir/run.sh} contains the single command,

\begin{itemize}
  \item[]\quotecmd{modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out},
\end{itemize}

which can be used to execute modelfree4.\index{software!Modelfree}

If you would like to use a different Modelfree executable file, change the binary name to the appropriate file name.  If the file is not located within the environment's path, include the full path in front of the binary file name.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{palmer\-.execute} \label{uf: palmer.execute}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/modelfree4} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Perform a model-free optimisation using Modelfree4.\index{software!Modelfree}\index{software!Modelfree}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{palmer.\linebreak[0]execute}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False, binary=\linebreak[0]`modelfree4')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory to place the files.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the results file to be overwritten if it already exists.

\hspace{3 mm}\keyword{binary:}  The name of the executable Modelfree program file.


\subsubsection{Description}

Modelfree 4 will be executed as

\begin{lstlisting}[numbers=none]
$ modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out
\end{lstlisting}


If a PDB\index{PDB} file is loaded and non-isotropic diffusion is selected, then the file name will be placed on the command line as \quotecmd{-s pdb\_file\_name}.

If you would like to use a different Modelfree executable file, change the binary name to the appropriate file name.  If the file is not located within the environment's path, include the full path in front of the binary file name.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{palmer\-.extract} \label{uf: palmer.extract}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/modelfree4} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/archive-extract}

\subsubsection{Synopsis}

Extract data from the Modelfree4\index{software!Modelfree}\index{software!Modelfree} \quotecmd{mfout} star formatted file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{palmer.\linebreak[0]extract}(\linebreak[0]dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory where the file \quotecmd{mfout} is found.


\subsubsection{Description}

The model-free results will be extracted from the Modelfree4\index{software!Modelfree}\index{software!Modelfree} results file \quotecmd{mfout} located in the given directory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{paramag\-.centre} \label{uf: paramag.centre}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill 

\subsubsection{Synopsis}

Specify which atom is the paramagnetic centre.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{paramag.\linebreak[0]centre}(\linebreak[0]pos=\linebreak[0]None, atom\_id=\linebreak[0]None, pipe=\linebreak[0]None, verbosity=\linebreak[0]1, fix=\linebreak[0]True, ave\_pos=\linebreak[0]True, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pos:}  The atomic position of the paramagnetic centre.

\hspace{3 mm}\keyword{atom\_id:}  The atom ID string.

\hspace{3 mm}\keyword{pipe:}  The data pipe containing the structures to extract the centre from.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.

\hspace{3 mm}\keyword{fix:}  A flag specifying if the paramagnetic centre should be fixed during optimisation.

\hspace{3 mm}\keyword{ave\_pos:}  A flag specifying if the position of the atom is to be averaged across all models.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the current paramagnetic centre to be overwritten.


\subsubsection{Description}

This is required for specifying where the paramagnetic centre is located in the loaded structure file.  If no structure number is given, then the average atom position will be calculated if multiple structures are loaded.

A different set of structures than those loaded into the current data pipe can also be used to determine the position, or its average.  This can be achieved by loading the alternative structures into another data pipe, and then specifying that pipe.

If the average position flag is set to True, the average position from all models will be used as the position of the paramagnetic centre.  If False, then the positions from all structures will be used.  If multiple positions are used, then a fast paramagnetic centre motion will be assumed so that PCSs for a single tensor will be calculated for each position, and the PCS values linearly averaged.

\subsubsection{Prompt examples}

If the paramagnetic centre is the lanthanide Dysprosium which is labelled as $\Diff_y$ in a loaded PDB\index{PDB} file, then type one of:

\begin{lstlisting}[numbers=none]
relax> paramag.centre('Dy')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> paramag.centre(atom_id='Dy')
\end{lstlisting}


If the carbon atom \quotecmd{C1} of residue \quotecmd{4} in the PDB\index{PDB} file is to be used as the paramagnetic centre, then type:

\begin{lstlisting}[numbers=none]
relax> paramag.centre(':4@C1')
\end{lstlisting}


To state that the Dy3+ atomic position is [0.136, 12.543, 4.356], type one of:

\begin{lstlisting}[numbers=none]
relax> paramag.centre([0.136, 12.543, 4.356])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> paramag.centre(pos=[0.136, 12.543, 4.356])
\end{lstlisting}


To find an unknown paramagnetic centre, type:

\begin{lstlisting}[numbers=none]
relax> paramag.centre(fix=False)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.back\-\_calc} \label{uf: pcs.back_calc}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Back calculate the pseudo-contact shifts.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]back\_calc}(\linebreak[0]align\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.


\subsubsection{Description}

This will back calculate the pseudo-contact shifts if the paramagnetic centre, temperature and magnetic field strength has been specified, an alignment tensor is present, and atomic positions have been loaded into the relax data store.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.calc\-\_q\-\_factors} \label{uf: pcs.calc_q_factors}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the PCS Q factor for the selected spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]calc\_q\_factors}(\linebreak[0]spin\_id=\linebreak[0]None, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string for restricting to subset of all selected spins.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.  Set to zero to silence the user function, or one to see all messages.


\subsubsection{Description}

For this to work, the back-calculated PCS data must first be generated by the analysis specific code.  Otherwise a warning will be given.

\subsubsection{Prompt examples}

To calculate the PCS Q factor for only the spins \quotecmd{@H26}, \quotecmd{@H27}, and \quotecmd{@H28}, type one of:

\begin{lstlisting}[numbers=none]
relax> pcs.calc_q_factors('@H26 & @H27 & @H28')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.calc_q_factors(spin_id='@H26 & @H27 & @H28')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.copy} \label{uf: pcs.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} PCS data from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, align\_id=\linebreak[0]None, back\_calc=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the pipe to copy\index{copy} the PCS data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the pipe to copy\index{copy} the PCS data to.

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{back\_calc:}  A flag which if True will cause any back-calculated PCSs present to also be copied with the real values and errors.


\subsubsection{Description}

This function will copy\index{copy} PCS data from \quotecmd{pipe\_from} to \quotecmd{pipe\_to}.  If align\_id is not given then all PCS data will be copied, otherwise only a specific data set will be.

\subsubsection{Prompt examples}

To copy\index{copy} all PCS data from pipe \quotecmd{m1} to pipe \quotecmd{m9}, type one of:

\begin{lstlisting}[numbers=none]
relax> pcs.copy('m1', 'm9')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.copy(pipe_from='m1', pipe_to='m9')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.copy('m1', 'm9', None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.copy(pipe_from='m1', pipe_to='m9', align_id=None)
\end{lstlisting}


To copy\index{copy} only the \quotecmd{Th} PCS data from \quotecmd{m3} to \quotecmd{m6}, type one of:

\begin{lstlisting}[numbers=none]
relax> pcs.copy('m3', 'm6', 'Th')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.copy(pipe_from='m3', pipe_to='m6', align_id='Th')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.corr\-\_plot} \label{uf: pcs.corr_plot}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grace_icon}

\subsubsection{Synopsis}

Generate a correlation plot\index{plot} of the measured vs. the back-calculated PCSs.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]corr\_plot}(\linebreak[0]format=\linebreak[0]`grace', title=\linebreak[0]None, subtitle=\linebreak[0]None, file=\linebreak[0]`pcs\_corr\_plot.\linebreak[0]agr', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{format:}  The format of the plot\index{plot} data.

\hspace{3 mm}\keyword{title:}  The title for the plot,\index{plot} overriding the default.

\hspace{3 mm}\keyword{subtitle:}  The subtitle for the plot,\index{plot} overriding the default.

\hspace{3 mm}\keyword{file:}  The name of the Grace\index{software!Grace}\index{software!Grace} file to create.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

Two formats are currently supported.  If format is set to \quotecmd{grace}, then a Grace\index{software!Grace}\index{software!Grace} plot\index{plot} file will be created.  If the format is not set then a plain text list of the measured and back-calculated data will be created.

\subsubsection{Prompt examples}

To create a Grace\index{software!Grace}\index{software!Grace} plot\index{plot} of the data, type:

\begin{lstlisting}[numbers=none]
relax> pcs.corr_plot()
\end{lstlisting}


To create a plain text list of the measured and back-calculated data, type one of:

\begin{lstlisting}[numbers=none]
relax> pcs.corr_plot(None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.corr_plot(format=None)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.delete} \label{uf: pcs.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} the PCS data corresponding to the alignment ID.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]delete}(\linebreak[0]align\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string of the data to delete.\index{delete}


\subsubsection{Description}

This will delete\index{delete} all PCS data associated with the alignment ID in the current data pipe.

\subsubsection{Prompt examples}

To delete\index{delete} the PCS data corresponding to align\_id=\quotecmd{PH\_gel}, type:

\begin{lstlisting}[numbers=none]
relax> pcs.delete('PH_gel')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.display} \label{uf: pcs.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the PCS data corresponding to the alignment ID.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]display}(\linebreak[0]align\_id=\linebreak[0]None, bc=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{bc:}  A flag which if set will display\index{display} the back-calculated rather than measured RDCs.


\subsubsection{Description}

This will display\index{display} all of the PCS data associated with the alignment ID in the current data pipe.

\subsubsection{Prompt examples}

To display\index{display} the \quotecmd{phage} PCS data, type:

\begin{lstlisting}[numbers=none]
relax> pcs.display('phage')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.read} \label{uf: pcs.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} the PCS data from file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]read}(\linebreak[0]align\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, data\_col=\linebreak[0]None, error\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{file:}  The name of the file containing the PCS data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{data\_col:}  The PCS data column.

\hspace{3 mm}\keyword{error\_col:}  The experimental error column.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict the loading of data to certain spin subsets.


\subsubsection{Description}

This will read\index{read} PCS data from a file and associate it with an alignment ID, either a new ID or a preexisting one with no PCS data.

The spin system can be identified in the file using two different formats.  The first is the spin ID string column which can include the molecule\index{molecule} name, the residue name and number, and the spin name and number.  Alternatively the molecule\index{molecule} name, residue number and name, and spin number and name columns can be supplied allowing this information to be in separate columns.  Note that the numbering of columns starts at one.  The spin ID can be used to restrict the reading\index{read} to certain spin types, for example only 15N spins when only residue information is in the file.

\subsubsection{Prompt examples}

The following commands will read\index{read} the PCS data out of the file \quotecmd{Tb.txt} where the columns are separated by the symbol \quotecmd{,}, and store the PCSs under the ID \quotecmd{Tb}.

\begin{lstlisting}[numbers=none]
relax> pcs.read('Tb', 'Tb.txt', sep=',')
\end{lstlisting}


To read\index{read} the 15N and 1H PCSs from the file \quotecmd{Eu.txt}, where the 15N values are in the 4$^{\mathrm{th}}$ column and the 1H in the 9$^{\mathrm{th}}$, type both the following:

\begin{lstlisting}[numbers=none]
relax> pcs.read('Tb', 'Tb.txt', spin_id='@N', res_num_col=1, data_col=4)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pcs.read('Tb', 'Tb.txt', spin_id='@H', res_num_col=1, data_col=9)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.set\-\_errors} \label{uf: pcs.set_errors}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the errors for the PCSs.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]set\_errors}(\linebreak[0]align\_id=\linebreak[0]None, spin\_id=\linebreak[0]None, sd=\linebreak[0]0.1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The optional alignment ID string.

\hspace{3 mm}\keyword{spin\_id:}  The optional spin ID string.

\hspace{3 mm}\keyword{sd:}  The PCS standard deviation value in ppm.


\subsubsection{Description}

If the PCS errors have not already been read\index{read} from a PCS data file or if they need to be changed, then the errors can be set via this user function.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.structural\-\_noise} \label{uf: pcs.structural_noise}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill 

\subsubsection{Synopsis}

Determine the PCS error due to structural noise via simulation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]structural\_noise}(\linebreak[0]align\_id=\linebreak[0]None, rmsd=\linebreak[0]0.2, sim\_num=\linebreak[0]1000, file=\linebreak[0]None, dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The optional alignment ID string.

\hspace{3 mm}\keyword{rmsd:}  The atomic position RMSD, in \AA, to randomise the spin positions with for the simulations.

\hspace{3 mm}\keyword{sim\_num:}  The number of simulations, N, to perform to determine the structural noise component of the PCS errors.

\hspace{3 mm}\keyword{file:}  The optional name of the Grace\index{software!Grace}\index{software!Grace} file to plot\index{plot} the structural errors verses the paramagnetic centre to spin distances.

\hspace{3 mm}\keyword{dir:}  The directory name to place the Grace\index{software!Grace}\index{software!Grace} file into.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

The analysis of the pseudo-contact shift is influenced by two significant sources of noise - that of the NMR\index{NMR} experiment and structural noise from the 3D molecular structure used.  The closer the spin to the paramagnetic centre, the greater the influence of structural noise.  This distance dependence is governed by the equation:

{\footnotesize \begin{verbatim}

                 sqrt(3) * abs(delta) * RMSD
    sigma_dist = --------------------------- ,
                            r

\end{verbatim}}

where sigma\_dist is the distance component of the structural noise as a standard deviation, delta is the PCS value, RMSD is the atomic position root-mean-square deviation, and $r$ is the paramagnetic centre to spin distance.  When close to the paramagnetic centre, this error source can exceed that of the NMR\index{NMR} experiment.  The equation for the angular component of the structural noise is more complicated.  The PCS error is influenced by distance, angle\index{angles} in the alignment frame, and the magnetic susceptibility tensor.

For the simulation the following must already be set up in the current data pipe:

\begin{itemize}
  \item[]The position of the paramagnetic centre.
  \item[]The alignment and magnetic susceptibility tensor.
\end{itemize}

The protocol for the simulation is as follows:

\begin{itemize}
  \item[]The lanthanide or paramagnetic centre position will be fixed.  Its motion is assumed to be on the femto- to pico- and nanosecond timescales.  Hence the motion is averaged over the evolution of the PCS and can be ignored.
  \item[]The positions of the nuclear spins will be randomised N times.  For each simulation a random unit vector will be generated.  Then a random distance along the unit vector will be generated by sampling from a Gaussian distribution centered at zero, the original spin position, with a standard deviation set to the given RMSD.  Both positive and negative displacements will be used.
  \item[]The PCS for the randomised position will be back calculated.
  \item[]The PCS standard deviation will be calculated from the N randomised PCS values.
\end{itemize}

The standard deviation will both be stored in the spin container data structure in the relax data store as well as being added to the already present PCS error (using variance addition).  This will then be used in any optimisations involving the PCS.

If the alignment ID string is not supplied, the procedure will be applied to the PCS data from all alignments.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.weight} \label{uf: pcs.weight}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill 

\subsubsection{Synopsis}

Set optimisation weights on the PCS data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]weight}(\linebreak[0]align\_id=\linebreak[0]None, spin\_id=\linebreak[0]None, weight=\linebreak[0]1.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.

\hspace{3 mm}\keyword{weight:}  The weighting value.


\subsubsection{Description}

This can be used to force the PCS to contribute more or less to the chi-squared\index{chi-squared} optimisation statistic.  The higher the value, the more importance the PCS will have.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pcs\-.write} \label{uf: pcs.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} the PCS data to file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pcs.\linebreak[0]write}(\linebreak[0]align\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, bc=\linebreak[0]False, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{bc:}  A flag which if set will write\index{write} out the back-calculated rather than measured RDCs.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

If no directory name is given, the file will be placed in the current working directory.  The alignment ID is required for selecting which PCS data set will be written to file.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.bundle} \label{uf: pipe.bundle}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe_bundle}

\subsubsection{Synopsis}

The grouping of data pipes into a bundle.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]bundle}(\linebreak[0]bundle=\linebreak[0]None, pipe=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{bundle:}  The pipe bundle is a special grouping or clustering of data pipes.

\hspace{3 mm}\keyword{pipe:}  The name of the data pipe to add to the bundle.


\subsubsection{Description}

Data pipes can be grouped or clustered together through special structures known as pipe bundles.  If the specified data pipe bundle does not currently exist, it will be created.

\subsubsection{Prompt examples}

To add the data pipes \quotecmd{test 1}, \quotecmd{test 2}, and \quotecmd{test 3} to the bundle \quotecmd{first analysis}, type the following:

\begin{lstlisting}[numbers=none]
relax> pipe.bundle('first analysis 1', 'test 1')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pipe.bundle('first analysis 1', 'test 2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pipe.bundle('first analysis 1', 'test 3')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.change\-\_type} \label{uf: pipe.change_type}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill 

\subsubsection{Synopsis}

Change the type of the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]change\_type}(\linebreak[0]pipe\_type=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_type:}  The type of data pipe.


\subsubsection{Description}

The data pipe type must be one of the following:

\begin{description}
  \item[\quotecmd{ct} --] Consistency testing.
  \item[\quotecmd{frame order} --] Frame Order theories.
  \item[\quotecmd{jw} --] Reduced spectral density mapping.\index{map}
  \item[\quotecmd{hybrid} --] Special hybrid pipe.
  \item[\quotecmd{mf} --] Model-free analysis.
  \item[\quotecmd{N-state} --] N-state model or ensemble analysis.
  \item[\quotecmd{noe} --] Steady state NOE calculation.
  \item[\quotecmd{relax\_disp} --] Relaxation\index{relaxation} dispersion.
  \item[\quotecmd{relax\_fit} --] Relaxation\index{relaxation} curve fitting.
\end{description}

\subsubsection{Prompt examples}

To change the type of the current \quotecmd{frame order} data pipe to the N-state model, type one of:

\begin{lstlisting}[numbers=none]
relax> pipe.change_type('N-state')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pipe.change_type(pipe_type='N-state')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.copy} \label{uf: pipe.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} a data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, bundle\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the source data pipe to copy\index{copy} the data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the target\index{tar} data pipe to copy\index{copy} the data to.

\hspace{3 mm}\keyword{bundle\_to:}  If given, the new data pipe will be grouped into this bundle.


\subsubsection{Description}

This allows the contents of a data pipe to be copied.  If the source data pipe is not set, the current data pipe will be assumed.  The target\index{tar} data pipe must not yet exist.

The optional bundling allows the newly created data pipe to be placed into either a new or existing data pipe bundle.  If not specified, then the copied data pipe will not be associated with a bundle.

\subsubsection{Prompt examples}

To copy\index{copy} the contents of the \quotecmd{m1} data pipe to the \quotecmd{m2} data pipe, type:

\begin{lstlisting}[numbers=none]
relax> pipe.copy('m1', 'm2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pipe.copy(pipe_from='m1', pipe_to='m2')
\end{lstlisting}


If the current data pipe is \quotecmd{m1}, then the following command can be used:

\begin{lstlisting}[numbers=none]
relax> pipe.copy(pipe_to='m2')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.create} \label{uf: pipe.create}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Add a new data pipe to the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]create}(\linebreak[0]pipe\_name=\linebreak[0]None, pipe\_type=\linebreak[0]None, bundle=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_name:}  The name of the data pipe.

\hspace{3 mm}\keyword{pipe\_type:}  The type of data pipe.

\hspace{3 mm}\keyword{bundle:}  The optional pipe bundle is a special grouping or clustering of data pipes.  If this is specified, the newly created data pipe will be added to this bundle.


\subsubsection{Description}

The data pipe name can be any string however the data pipe type can only be one of the following:

\begin{description}
  \item[\quotecmd{ct} --] Consistency testing,
  \item[\quotecmd{frame order} --] The Frame Order theories,
  \item[\quotecmd{jw} --] Reduced spectral density mapping,\index{map}
  \item[\quotecmd{hybrid} --] A special hybrid pipe,
  \item[\quotecmd{mf} --] Model-free analysis,
  \item[\quotecmd{N-state} --] N-state model or ensemble analysis,
  \item[\quotecmd{noe} --] Steady state NOE calculation,
  \item[\quotecmd{relax\_disp} --] Relaxation\index{relaxation} dispersion curve fitting,
  \item[\quotecmd{relax\_fit} --] Relaxation\index{relaxation} curve fitting,
\end{description}

The pipe bundling concept is simply a way of grouping data pipes together.  This is useful for a number of purposes:

\begin{itemize}
  \item[]The grouping or categorisation of data pipes, for example when multiple related analyses are performed.
  \item[]In the auto-analyses, as all the data pipes that they spawn are bound\index{parameter!bounds} together within the original bundle.
  \item[]In the graphical user interface mode as analysis tabs are linked to specific pipe bundles.
\end{itemize}

\subsubsection{Prompt examples}

To set up a model-free analysis data pipe with the name \quotecmd{m5}, type:

\begin{lstlisting}[numbers=none]
relax> pipe.create('m5', 'mf')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.current} \label{uf: pipe.current}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Print the name of the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]current}(\linebreak[0])}
\end{flushleft}


\subsubsection{Prompt examples}

To run the user function, type:

\begin{lstlisting}[numbers=none]
relax> pipe.current()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.delete} \label{uf: pipe.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} a data pipe from the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]delete}(\linebreak[0]pipe\_name=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_name:}  The name of the data pipe to delete.\index{delete}


\subsubsection{Description}

This will permanently remove the data pipe and all of its contents from the relax data store.  If the pipe name is not given, then all data pipes will be deleted.\index{delete}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.display} \label{uf: pipe.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Print a list of all the data pipes.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]display}(\linebreak[0])}
\end{flushleft}


\subsubsection{Prompt examples}

To run the user function, type:

\begin{lstlisting}[numbers=none]
relax> pipe.display()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.hybridise} \label{uf: pipe.hybridise}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe_hybrid}

\subsubsection{Synopsis}

Create a hybrid data pipe by fusing a number of other data pipes.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]hybridise}(\linebreak[0]hybrid=\linebreak[0]None, pipes=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{hybrid:}  The name of the hybrid data pipe to create.

\hspace{3 mm}\keyword{pipes:}  An array containing the names of all data pipes to hybridise.


\subsubsection{Description}

This user function can be used to construct hybrid models.  An example of the use of a hybrid model could be if the protein consists of two independent domains.  These two domains could be analysed separately, each having their own optimised\index{optimise} diffusion\index{diffusion!tensor} tensors.  The N-terminal domain data pipe could be called \quotecmd{N\_sphere} while the C-terminal domain could be called \quotecmd{C\_ellipsoid}.  These two data pipes could then be hybridised into a single data pipe.  This hybrid data pipe can then be compared via model selection to a data pipe whereby the entire protein is assumed to have a single diffusion\index{diffusion!tensor} tensor.

The requirements for data pipes to be hybridised is that the molecules,\index{molecule} sequences,\index{sequence} and spin systems for all the data pipes is the same, and that no spin system is allowed to be selected in two or more data pipes.  The selections must not overlap to allow for rigorous statistical comparisons.

\subsubsection{Prompt examples}

The two data pipes \quotecmd{N\_sphere} and \quotecmd{C\_ellipsoid} could be hybridised into a single data pipe called \quotecmd{mixed model} by typing:

\begin{lstlisting}[numbers=none]
relax> pipe.hybridise('mixed model', ['N_sphere', 'C_ellipsoid'])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pipe.hybridise(hybrid='mixed model', pipes=['N_sphere', 'C_ellipsoid'])
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pipe\-.switch} \label{uf: pipe.switch}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pipe} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/system-switch-user}

\subsubsection{Synopsis}

Switch between the data pipes of the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pipe.\linebreak[0]switch}(\linebreak[0]pipe\_name=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_name:}  The name of the data pipe.


\subsubsection{Description}

This will switch between the various data pipes within the relax data store.

\subsubsection{Prompt examples}

To switch to the \quotecmd{ellipsoid} data pipe, type:

\begin{lstlisting}[numbers=none]
relax> pipe.switch('ellipsoid')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pipe.switch(pipe_name='ellipsoid')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.cartoon} \label{uf: pymol.cartoon}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill 

\subsubsection{Synopsis}

Apply the PyMOL cartoon style and colour by secondary structure.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]cartoon}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This applies the PyMOL cartoon style which is equivalent to hiding everything and clicking on show cartoon.  It also colours the cartoon with red helices, yellow strands, and green loops.  The following commands are executed:

\begin{itemize}
  \item[]cmd.hide(\quotecmd{everything}, file)
  \item[]cmd.show(\quotecmd{cartoon}, file)
  \item[]util.cbss(file, \quotecmd{red}, \quotecmd{yellow}, \quotecmd{green})
\end{itemize}

where file is the file name without the \quotecmd{.pdb} extension.

\subsubsection{Prompt examples}

To apply this user function, type:

\begin{lstlisting}[numbers=none]
relax> pymol.cartoon()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.clear\-\_history} \label{uf: pymol.clear_history}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill 

\subsubsection{Synopsis}

Clear the PyMOL command history.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]clear\_history}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will clear the Pymol history from memory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.command} \label{uf: pymol.command}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Execute a user supplied PyMOL command.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]command}(\linebreak[0]command=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{command:}  The PyMOL command to execute.


\subsubsection{Description}

This allows PyMOL commands to be passed to the program.  This can be useful for automation or scripting.\index{scripting!script file}\index{scripting}

\subsubsection{Prompt examples}

To reinitialise the PyMOL instance, type:

\begin{lstlisting}[numbers=none]
relax> pymol.command("reinitialise")
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.cone\-\_pdb} \label{uf: pymol.cone_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill 

\subsubsection{Synopsis}

Display\index{display} the cone PDB\index{PDB} geometric object.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]cone\_pdb}(\linebreak[0]file=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file containing the cone geometric object.


\subsubsection{Description}

The PDB\index{PDB} file containing the geometric object must be created using the complementary $n$\_state\_model.cone\_pdb user function.

The cone PDB\index{PDB} file is read\index{read} in using the command:

\begin{itemize}
  \item[]load file
\end{itemize}

The average CoM-pivot point vector, the residue \quotecmd{AVE} is displayed\index{display} using the commands:

\begin{itemize}
  \item[]select resn AVE
  \item[]show sticks, \quotecmd{sele}
  \item[]color blue, \quotecmd{sele}
\end{itemize}

The cone object, the residue \quotecmd{CON}, is displayed\index{display} using the commands:

\begin{itemize}
  \item[]select resn CON
  \item[]hide (\quotecmd{sele})
  \item[]show sticks, \quotecmd{sele}
  \item[]color white, \quotecmd{sele}
\end{itemize}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.frame\-\_order} \label{uf: pymol.frame_order}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frame_order}

\subsubsection{Synopsis}

Display\index{display} the frame order results from the frame\_order.pdb\_model user function.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]frame\_order}(\linebreak[0]ave\_pos\_file=\linebreak[0]`ave\_pos.\linebreak[0]pdb', rep\_file=\linebreak[0]`frame\_order.\linebreak[0]pdb', dist\_file=\linebreak[0]`domain\_distribution.\linebreak[0]pdb', dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ave\_pos\_file:}  The name of the 3D structure PDB\index{PDB} file for the molecular structure with the moving domains shifted to the average position.

\hspace{3 mm}\keyword{rep\_file:}  The name of the PDB\index{PDB} file for the geometric object representation of the frame order dynamics.

\hspace{3 mm}\keyword{dist\_file:}  The name of the file which will contain multiple models spanning the full dynamics distribution of the frame order model.

\hspace{3 mm}\keyword{dir:}  The directory where the file is to be located.


\subsubsection{Description}

This user function is designed to be combined with the frame\_order.pdb\_model user function.  It will take the three PDB\index{PDB} files created by frame\_order.pdb\_model - the molecular structure with the averaged domain positions, the frame order dynamics representation file, and the moving domain distribution file - and display\index{display} them in PyMOL.  Rather than loading the three files into PyMOL manually, this user function will change the representation to significantly improve the visualisation.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.macro\-\_apply} \label{uf: pymol.macro_apply}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon}

\subsubsection{Synopsis}

Execute PyMOL macros.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]macro\_apply}(\linebreak[0]data\_type=\linebreak[0]None, style=\linebreak[0]`classic', colour\_start\_name=\linebreak[0]None, colour\_start\_rgb=\linebreak[0]None, colour\_end\_name=\linebreak[0]None, colour\_end\_rgb=\linebreak[0]None, colour\_list=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{data\_type:}  The data type to map\index{map} to the structure.

\hspace{3 mm}\keyword{style:}  The style of the macro.

\hspace{3 mm}\keyword{colour\_start\_name:}  The name of the starting colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the starting colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_start\_rgb:}  The starting colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the starting colour name cannot be given.

\hspace{3 mm}\keyword{colour\_end\_name:}  The name of the ending colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the ending colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_end\_rgb:}  The ending colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the ending colour name cannot be given.

\hspace{3 mm}\keyword{colour\_list:}  The colour list to search for the colour names.  This can be either \quotecmd{molmol} or \quotecmd{x11}.


\subsubsection{Description}

This allows spin specific values to be mapped\index{map} to a structure through PyMOL macros.  Currently only the \quotecmd{classic} style, which is described below, is available.

\subsubsection{Colour}

The values are coloured based on a linear colour gradient which is specified through starting and ending colours.  These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself.  For example, \quotecmd{white} and [1.0, 1.0, 1.0] both select the same colour.  Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings.  These are the default Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour list and the X11 colour list, both of which are described in the tables below.  The default behaviour is to first search the Molmol\index{software!MOLMOL}\index{software!MOLMOL} list and then the X11 colour list, raising an error if neither contain the name.  To explicitly select these lists, set the colour list to either \quotecmd{molmol} or \quotecmd{x11}.

\subsubsection{Model-free classic style}

Creator:  Edward d'Auvergne

Argument string:  "classic"

Description:  The classic style draws the backbone of a protein in a cylindrical bond style.  Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured.  Deselected residues are shown as black lines.

Supported data types:

Please see Table~\ref{table: model-free macro classic style} on page~\pageref{table: model-free macro classic style}.

\subsubsection{Molmol RGB colour arrays}

The following table is a list of colours used in Molmol\index{software!MOLMOL}\index{software!MOLMOL} and their corresponding RGB colour values ranging from 0 to 1.

Please see Table~\ref{table: Molmol colours} on page~\pageref{table: Molmol colours}.

\subsubsection{X11 RGB colour arrays}

The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.

Please see Table~\ref{table: X11 colours} on page~\pageref{table: X11 colours}.

\subsubsection{Prompt examples}

To map\index{map} the order\index{order parameter} parameter values, $S^2$, onto the structure using the classic style, type:

\begin{lstlisting}[numbers=none]
relax> pymol.macro_apply('s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pymol.macro_apply(data_type='s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pymol.macro_apply(data_type='s2', style="classic")
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.macro\-\_run} \label{uf: pymol.macro_run}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Open and execute the PyMOL macro file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]macro\_run}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]`pymol')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PyMOL macro file.

\hspace{3 mm}\keyword{dir:}  The directory name.


\subsubsection{Description}

This user function is for opening and running a PyMOL macro located within a text file.

\subsubsection{Prompt examples}

To execute the macro file \quotecmd{s2.pml} located in the directory \quotecmd{pymol}, type:

\begin{lstlisting}[numbers=none]
relax> pymol.macro_run(file='s2.pml')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pymol.macro_run(file='s2.pml', dir='pymol')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.macro\-\_write} \label{uf: pymol.macro_write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create PyMOL macros.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]macro\_write}(\linebreak[0]data\_type=\linebreak[0]None, style=\linebreak[0]`classic', colour\_start\_name=\linebreak[0]None, colour\_start\_rgb=\linebreak[0]None, colour\_end\_name=\linebreak[0]None, colour\_end\_rgb=\linebreak[0]None, colour\_list=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]`pymol', force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{data\_type:}  The data type to map\index{map} to the structure.

\hspace{3 mm}\keyword{style:}  The style of the macro.

\hspace{3 mm}\keyword{colour\_start\_name:}  The name of the starting colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the starting colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_start\_rgb:}  The starting colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the starting colour name cannot be given.

\hspace{3 mm}\keyword{colour\_end\_name:}  The name of the ending colour of the linear colour gradient.  This can be either one of the X11 or one of the Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour names listed in the description.  If this is set, then the ending colour RGB colour array cannot be given.

\hspace{3 mm}\keyword{colour\_end\_rgb:}  The ending colour of the linear colour gradient.  This is an RGB colour array with values ranging from 0 to 1.  If this is set, then the ending colour name cannot be given.

\hspace{3 mm}\keyword{colour\_list:}  The colour list to search for the colour names.  This can be either \quotecmd{molmol} or \quotecmd{x11}.

\hspace{3 mm}\keyword{file:}  The optional name of the file.

\hspace{3 mm}\keyword{dir:}  The optional directory to save the file to.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the file to be overwritten.


\subsubsection{Description}

This allows residues specific values to be mapped\index{map} to a structure through the creation of a PyMOL macro which can be executed in PyMOL by clicking on \quotecmd{File, Macro, Execute User...}.  Currently only the \quotecmd{classic} style, which is described below, is available.

\subsubsection{Colour}

The values are coloured based on a linear colour gradient which is specified through starting and ending colours.  These can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself.  For example, \quotecmd{white} and [1.0, 1.0, 1.0] both select the same colour.  Leaving both colours unset will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings.  These are the default Molmol\index{software!MOLMOL}\index{software!MOLMOL} colour list and the X11 colour list, both of which are described in the tables below.  The default behaviour is to first search the Molmol\index{software!MOLMOL}\index{software!MOLMOL} list and then the X11 colour list, raising an error if neither contain the name.  To explicitly select these lists, set the colour list to either \quotecmd{molmol} or \quotecmd{x11}.

\subsubsection{Model-free classic style}

Creator:  Edward d'Auvergne

Argument string:  "classic"

Description:  The classic style draws the backbone of a protein in a cylindrical bond style.  Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured.  Deselected residues are shown as black lines.

Supported data types:

Please see Table~\ref{table: model-free macro classic style} on page~\pageref{table: model-free macro classic style}.

\subsubsection{Molmol RGB colour arrays}

The following table is a list of colours used in Molmol\index{software!MOLMOL}\index{software!MOLMOL} and their corresponding RGB colour values ranging from 0 to 1.

Please see Table~\ref{table: Molmol colours} on page~\pageref{table: Molmol colours}.

\subsubsection{X11 RGB colour arrays}

The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.

Please see Table~\ref{table: X11 colours} on page~\pageref{table: X11 colours}.

\subsubsection{Prompt examples}

To create a PyMOL macro mapping\index{map} the order\index{order parameter} parameter values, $S^2$, onto the structure using the classic style, type:

\begin{lstlisting}[numbers=none]
relax> pymol.macro_write('s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pymol.macro_write(data_type='s2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> pymol.macro_write(data_type='s2', style="classic", file='s2.pml', dir='pymol')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.tensor\-\_pdb} \label{uf: pymol.tensor_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill 

\subsubsection{Synopsis}

Display\index{display} the diffusion\index{diffusion!tensor} tensor PDB\index{PDB} geometric object over the loaded PDB.\index{PDB}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]tensor\_pdb}(\linebreak[0]file=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file containing the tensor geometric object.


\subsubsection{Description}

In executing this user function, a PDB\index{PDB} file must have previously been loaded into this data pipe a geometric object or polygon representing the Brownian\index{diffusion!Brownian} rotational\index{rotation} diffusion\index{diffusion!tensor} tensor will be overlain with the loaded PDB\index{PDB} file and displayed\index{display} within PyMOL.  The PDB\index{PDB} file containing the geometric object must be created using the complementary structure.create\_diff\_tensor\_pdb user function.

The tensor PDB\index{PDB} file is read\index{read} in using the command:

\begin{itemize}
  \item[]load file
\end{itemize}

The centre of mass residue \quotecmd{COM} is displayed\index{display} using the commands:

\begin{itemize}
  \item[]select resn COM
  \item[]show dots, \quotecmd{sele}
  \item[]color blue, \quotecmd{sele}
\end{itemize}

The axes of the diffusion\index{diffusion!tensor} tensor, the residue \quotecmd{AXS}, is displayed\index{display} using the commands:

\begin{itemize}
  \item[]select resn AXS
  \item[]hide (\quotecmd{sele})
  \item[]show sticks, \quotecmd{sele}
  \item[]color cyan, \quotecmd{sele}
  \item[]label \quotecmd{sele}, name
\end{itemize}

The simulation axes, the residues \quotecmd{SIM}, are displayed\index{display} using the commands:

\begin{itemize}
  \item[]select resn SIM
  \item[]colour cyan, \quotecmd{sele}
\end{itemize}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.vector\-\_dist} \label{uf: pymol.vector_dist}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill 

\subsubsection{Synopsis}

Display\index{display} the PDB\index{PDB} file representation of the XH vector distribution.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]vector\_dist}(\linebreak[0]file=\linebreak[0]`XH\_dist.\linebreak[0]pdb')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file containing the vector distribution.


\subsubsection{Description}

A PDB\index{PDB} file of the macromolecule must have previously been loaded as the vector distribution will be overlain with the macromolecule within PyMOL.  The PDB\index{PDB} file containing the vector distribution must be created using the complementary structure.create\_vector\_dist user function.

The vector distribution PDB\index{PDB} file is read\index{read} in using the command:

\begin{itemize}
  \item[]load file
\end{itemize}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{pymol\-.view} \label{uf: pymol.view}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/pymol_icon} \hfill 

\subsubsection{Synopsis}

View the collection of molecules\index{molecule} from the loaded PDB\index{PDB} file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{pymol.\linebreak[0]view}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will simply launch Pymol.

\subsubsection{Prompt examples}

\begin{lstlisting}[numbers=none]
relax> pymol.view()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.back\-\_calc} \label{uf: rdc.back_calc}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Back calculate the residual dipolar couplings.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]back\_calc}(\linebreak[0]align\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.


\subsubsection{Description}

This will back calculate the residual dipolar couplings (RDCs) if an alignment tensor is present and inter-dipole vectors have been loaded into the relax data store.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.calc\-\_q\-\_factors} \label{uf: rdc.calc_q_factors}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the RDC Q factor for the selected spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]calc\_q\_factors}(\linebreak[0]spin\_id=\linebreak[0]None, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string for restricting to subset of all selected spins.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.  Set to zero to silence the user function, or one to see all messages.


\subsubsection{Description}

For this to work, the back-calculated RDC data must first be generated by the analysis specific code.  Otherwise a warning will be given.

\subsubsection{Prompt examples}

To calculate the RDC Q factor for only the spins \quotecmd{@H26}, \quotecmd{@H27}, and \quotecmd{@H28}, type one of:

\begin{lstlisting}[numbers=none]
relax> rdc.calc_q_factors('@H26 & @H27 & @H28')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.calc_q_factors(spin_id='@H26 & @H27 & @H28')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.copy} \label{uf: rdc.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} RDC data from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, align\_id=\linebreak[0]None, back\_calc=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the pipe to copy\index{copy} the RDC data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the pipe to copy\index{copy} the RDC data to.

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{back\_calc:}  A flag which if True will cause any back-calculated RDCs present to also be copied with the real values and errors.


\subsubsection{Description}

This function will copy\index{copy} RDC data from \quotecmd{pipe\_from} to \quotecmd{pipe\_to}.  If align\_id is not given then all RDC data will be copied, otherwise only a specific data set will be.

\subsubsection{Prompt examples}

To copy\index{copy} all RDC data from pipe \quotecmd{m1} to pipe \quotecmd{m9}, type one of:

\begin{lstlisting}[numbers=none]
relax> rdc.copy('m1', 'm9')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.copy(pipe_from='m1', pipe_to='m9')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.copy('m1', 'm9', None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.copy(pipe_from='m1', pipe_to='m9', align_id=None)
\end{lstlisting}


To copy\index{copy} only the \quotecmd{Th} RDC data from \quotecmd{m3} to \quotecmd{m6}, type one of:

\begin{lstlisting}[numbers=none]
relax> rdc.copy('m3', 'm6', 'Th')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.copy(pipe_from='m3', pipe_to='m6', align_id='Th')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.corr\-\_plot} \label{uf: rdc.corr_plot}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grace_icon}

\subsubsection{Synopsis}

Generate a correlation plot\index{plot} of the measured vs. the back-calculated RDCs.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]corr\_plot}(\linebreak[0]format=\linebreak[0]`grace', title=\linebreak[0]None, subtitle=\linebreak[0]None, file=\linebreak[0]`rdc\_corr\_plot.\linebreak[0]agr', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{format:}  The format of the plot\index{plot} data.

\hspace{3 mm}\keyword{title:}  The title for the plot,\index{plot} overriding the default.

\hspace{3 mm}\keyword{subtitle:}  The subtitle for the plot,\index{plot} overriding the default.

\hspace{3 mm}\keyword{file:}  The name of the Grace\index{software!Grace}\index{software!Grace} file to create.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

Two formats are currently supported.  If format is set to \quotecmd{grace}, then a Grace\index{software!Grace}\index{software!Grace} plot\index{plot} file will be created.  If the format is not set then a plain text list of the measured and back-calculated data will be created.

\subsubsection{Prompt examples}

To create a Grace\index{software!Grace}\index{software!Grace} plot\index{plot} of the data, type:

\begin{lstlisting}[numbers=none]
relax> rdc.corr_plot()
\end{lstlisting}


To create a plain text list of the measured and back-calculated data, type one of:

\begin{lstlisting}[numbers=none]
relax> rdc.corr_plot(None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.corr_plot(format=None)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.delete} \label{uf: rdc.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} the RDC data corresponding to the alignment ID.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]delete}(\linebreak[0]align\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string of the data to delete.\index{delete}


\subsubsection{Description}

This will delete\index{delete} all RDC data associated with the alignment ID in the current data pipe.

\subsubsection{Prompt examples}

To delete\index{delete} the RDC data corresponding to align\_id=\quotecmd{PH\_gel}, type:

\begin{lstlisting}[numbers=none]
relax> rdc.delete('PH_gel')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.display} \label{uf: rdc.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the RDC data corresponding to the alignment ID.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]display}(\linebreak[0]align\_id=\linebreak[0]None, bc=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{bc:}  A flag which if set will display\index{display} the back-calculated rather than measured RDCs.


\subsubsection{Description}

This will display\index{display} all of the RDC data associated with the alignment ID in the current data pipe.

\subsubsection{Prompt examples}

To display\index{display} the \quotecmd{phage} RDC data, type:

\begin{lstlisting}[numbers=none]
relax> rdc.display('phage')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.read} \label{uf: rdc.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} the RDC data from file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]read}(\linebreak[0]align\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, data\_type=\linebreak[0]`D', spin\_id1\_col=\linebreak[0]1, spin\_id2\_col=\linebreak[0]2, data\_col=\linebreak[0]None, error\_col=\linebreak[0]None, sep=\linebreak[0]None, neg\_g\_corr=\linebreak[0]False, absolute=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{file:}  The name of the file containing the RDC data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{data\_type:}  Specify if the RDC data is in the D or 2D format, or the T = J + D format.

\hspace{3 mm}\keyword{spin\_id1\_col:}  The spin ID string column for the first spin.

\hspace{3 mm}\keyword{spin\_id2\_col:}  The spin ID string column for the second spin.

\hspace{3 mm}\keyword{data\_col:}  The RDC data column.

\hspace{3 mm}\keyword{error\_col:}  The experimental error column.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{neg\_g\_corr:}  A flag which is used to correct for the negative gyromagnetic ratio of 15N.  If set to True, all RDC values will be inverted prior to being stored in the relax data store.

\hspace{3 mm}\keyword{absolute:}  A flag which indicates that the loaded RDCs are are signless.


\subsubsection{Description}

This will read\index{read} RDC data from a file and associate it with an alignment ID, either a new ID or a preexisting one with no RDC data.

The data type is used to specify how the RDC is defined.  It can be set to a number of values:

\begin{itemize}
  \item[]\quotecmd{D} means that the splitting in the aligned sample was taken as J + D.
  \item[]\quotecmd{2D} means that the splitting in the aligned sample was assumed to be J + 2D.
  \item[]\quotecmd{T} means that the file contains T = J + D values.
\end{itemize}

Internally, relax uses the D notation.  Therefore if set to \quotecmd{2D}, the values will be doubled when read\index{read} in.  If the \quotecmd{T} data type is specified, then J couplings must be present for this data to be of any use.

If the negative gyromagnetic ratio correction flag is set, a sign inversion will be applied to all RDC values to be loaded.  This is sometimes needed for 15N if the data is not compensated for the negative gyromagnetic ratio.

The absolute RDCs flag is used for RDCs in which the sign is unknown.  All absolute RDCs loaded will be converted to positive values.

\subsubsection{Prompt examples}

The following commands will read\index{read} the RDC data out of the file \quotecmd{Tb.txt} where the columns are separated by the symbol \quotecmd{,}, and store the RDCs under the ID \quotecmd{Tb}:

\begin{lstlisting}[numbers=none]
relax> rdc.read('Tb', 'Tb.txt', sep=',')
\end{lstlisting}


If the individual spin RDC errors are located in the file \quotecmd{rdc\_err.txt} in column number 5, then to read\index{read} these values into relax, assuming J + D was measured, type one of:

\begin{lstlisting}[numbers=none]
relax> rdc.read('phage', 'rdc_err.txt', data_type='D', error_col=5)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> rdc.read(align_id='phage', file='rdc_err.txt', data_type='D', error_col=5)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.set\-\_errors} \label{uf: rdc.set_errors}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the errors for the RDCs.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]set\_errors}(\linebreak[0]align\_id=\linebreak[0]None, spin\_id1=\linebreak[0]None, spin\_id2=\linebreak[0]None, sd=\linebreak[0]1.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The optional alignment ID string.

\hspace{3 mm}\keyword{spin\_id1:}  The optional spin ID string of the first spin.

\hspace{3 mm}\keyword{spin\_id2:}  The optional spin ID string of the second spin.

\hspace{3 mm}\keyword{sd:}  The RDC standard deviation value in Hertz.


\subsubsection{Description}

If the RDC errors have not already been read\index{read} from a RDC data file or if they need to be changed, then the errors can be set via this user function.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.weight} \label{uf: rdc.weight}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill 

\subsubsection{Synopsis}

Set optimisation weights on the RDC data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]weight}(\linebreak[0]align\_id=\linebreak[0]None, spin\_id=\linebreak[0]None, weight=\linebreak[0]1.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.

\hspace{3 mm}\keyword{weight:}  The weighting value.


\subsubsection{Description}

This can be used to force the RDC to contribute more or less to the chi-squared\index{chi-squared} optimisation statistic.  The higher the value, the more importance the RDC will have.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{rdc\-.write} \label{uf: rdc.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/align_tensor} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} the RDC data to file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{rdc.\linebreak[0]write}(\linebreak[0]align\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, bc=\linebreak[0]False, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{align\_id:}  The alignment ID string.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{bc:}  A flag which if set will write\index{write} out the back-calculated rather than measured RDCs.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

If no directory name is given, the file will be placed in the current working directory.  The alignment ID is required for selecting which RDC data set will be written to file.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.back\-\_calc} \label{uf: relax_data.back_calc}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Back calculate the relaxation\index{relaxation} data at the given frequency.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]back\_calc}(\linebreak[0]ri\_id=\linebreak[0]None, ri\_type=\linebreak[0]None, frq=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.

\hspace{3 mm}\keyword{ri\_type:}  The relaxation\index{relaxation} data type, ie \quotecmd{R1}, \quotecmd{R2}, or \quotecmd{NOE}.

\hspace{3 mm}\keyword{frq:}  The spectrometer frequency in Hz.


\subsubsection{Description}

This allows relaxation\index{relaxation} data of the given type and frequency to be back calculated from the model parameter values.  If the relaxation\index{relaxation} data ID, type and frequency are not given, then relaxation\index{relaxation} data matching that currently loaded in the relax data store will be back-calculated.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.copy} \label{uf: relax_data.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} relaxation\index{relaxation} data from one pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, ri\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the pipe to copy\index{copy} the relaxation\index{relaxation} data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the pipe to copy\index{copy} the relaxation\index{relaxation} data to.

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.


\subsubsection{Description}

This will copy\index{copy} relaxation\index{relaxation} data from one data pipe to another.  If the relaxation\index{relaxation} ID data string is not given then all relaxation\index{relaxation} data will be copied, otherwise only a specific data set will be copied.

\subsubsection{Prompt examples}

To copy\index{copy} all relaxation\index{relaxation} data from pipe \quotecmd{m1} to pipe \quotecmd{m9}, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_data.copy('m1', 'm9')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_data.copy(pipe_from='m1', pipe_to='m9')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_data.copy('m1', 'm9', None)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_data.copy(pipe_from='m1', pipe_to='m9', ri_id=None)
\end{lstlisting}


To copy\index{copy} only the NOE relaxation\index{relaxation} data with the ID string of \quotecmd{NOE\_800} from \quotecmd{m3} to \quotecmd{m6}, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_data.copy('m3', 'm6', 'NOE_800')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_data.copy(pipe_from='m3', pipe_to='m6', ri_id='NOE_800')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.delete} \label{uf: relax_data.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} the data corresponding to the relaxation\index{relaxation} data ID string.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]delete}(\linebreak[0]ri\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.


\subsubsection{Description}

The relaxation\index{relaxation} data corresponding to the given relaxation\index{relaxation} data ID string will be removed from the current data pipe.

\subsubsection{Prompt examples}

To delete\index{delete} the relaxation\index{relaxation} data corresponding to the ID \quotecmd{NOE\_600}, type:

\begin{lstlisting}[numbers=none]
relax> relax_data.delete('NOE_600')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.display} \label{uf: relax_data.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the data corresponding to the relaxation\index{relaxation} data ID string.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]display}(\linebreak[0]ri\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.


\subsubsection{Description}

This will display\index{display} the relaxation\index{relaxation} data corresponding to the given ID.

\subsubsection{Prompt examples}

To display\index{display} the NOE relaxation\index{relaxation} data at 600 MHz with the ID string \quotecmd{NOE\_600}, type:

\begin{lstlisting}[numbers=none]
relax> relax_data.display('NOE_600')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.peak\-\_intensity\-\_type} \label{uf: relax_data.peak_intensity_type}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Specify if heights or volumes were used to measure the peak intensities.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]peak\_intensity\_type}(\linebreak[0]ri\_id=\linebreak[0]None, type=\linebreak[0]`height')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.

\hspace{3 mm}\keyword{type:}  The peak intensity type.


\subsubsection{Description}

This is essential for BMRB data deposition.  It is used to specify whether peak heights or peak volumes were measured.  The two currently allowed values for the peak intensity type are \quotecmd{height} and \quotecmd{volume}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.read} \label{uf: relax_data.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} R$_1$, R$_2$, NOE, or R2eff relaxation\index{relaxation} data from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]read}(\linebreak[0]ri\_id=\linebreak[0]None, ri\_type=\linebreak[0]None, frq=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, data\_col=\linebreak[0]None, error\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.  This must be a unique identifier.

\hspace{3 mm}\keyword{ri\_type:}  The relaxation\index{relaxation} data type, $i$.e. \quotecmd{R1}, \quotecmd{R2}, \quotecmd{NOE}, or \quotecmd{R2eff}.

\hspace{3 mm}\keyword{frq:}  The exact proton frequency of the spectrometer in Hertz.  See the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file.

\hspace{3 mm}\keyword{file:}  The name of the file containing the relaxation\index{relaxation} data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{data\_col:}  The relaxation\index{relaxation} data column.

\hspace{3 mm}\keyword{error\_col:}  The experimental error column.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict the loading of data to certain spin subsets.


\subsubsection{Description}

This will load the relaxation\index{relaxation} data into the relax data store.  The data is associated with the spectrometer frequency in Hertz.  For subsequent analysis, this frequency must be set to the exact field strength.  This value is stored in the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file.

The spin system can be identified in the file using two different formats.  The first is the spin ID string column which can include the molecule\index{molecule} name, the residue name and number, and the spin name and number.  Alternatively the molecule\index{molecule} name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns.  Note that the numbering of columns starts at one.  The spin ID string can be used to restrict the reading\index{read} to certain spin types, for example only 15N spins when only residue information is in the file.

\subsubsection{Prompt examples}

The following commands will read\index{read} the protein NOE relaxation\index{relaxation} data collected at 600 MHz out of a file called \quotecmd{noe.600.out} where the residue numbers, residue names, data, errors are in the first, second, third, and forth columns respectively.

\begin{lstlisting}[numbers=none]
relax> relax_data.read('NOE_600', 'NOE', 599.7 * 1e6, 'noe.600.out', res_num_col=1, res_name_col=2, data_col=3, error_col=4)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_data.read(ri_id='NOE_600', ri_type='NOE', frq=600.0 * 1e6, file='noe.600.out', res_num_col=1, res_name_col=2, data_col=3, error_col=4)
\end{lstlisting}


The following commands will read\index{read} the R$_2$ data out of the file \quotecmd{r2.out} where the residue numbers, residue names, data, errors are in the second, third, fifth, and sixth columns respectively.  The columns are separated by commas.

\begin{lstlisting}[numbers=none]
relax> relax_data.read('R2_800', 'R2', 8.0 * 1e8, 'r2.out', res_num_col=2, res_name_col=3, data_col=5, error_col=6, sep=',')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_data.read(ri_id='R2_800', ri_type='R2', frq=8.0*1e8, file='r2.out', res_num_col=2, res_name_col=3, data_col=5, error_col=6, sep=',')
\end{lstlisting}


The following commands will read\index{read} the R$_1$ data out of the file \quotecmd{r1.out} where the columns are separated by the symbol \quotecmd{\%}

\begin{lstlisting}[numbers=none]
relax> relax_data.read('R1_300', 'R1', 300.1 * 1e6, 'r1.out', sep='%')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.temp\-\_calibration} \label{uf: relax_data.temp_calibration}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/status/weather-clear}

\subsubsection{Synopsis}

Specify the per-experiment temperature calibration method used.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]temp\_calibration}(\linebreak[0]ri\_id=\linebreak[0]None, method=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.

\hspace{3 mm}\keyword{method:}  The per-experiment temperature calibration method.


\subsubsection{Description}

For the proper measurement of relaxation\index{relaxation} data, per-experiment temperature calibration is essential.  This user function is not for inputting standard MeOH/ethylene glycol/etc. calibration of a spectrometer - this temperature setting is of no use when you are running experiments which pump in large amounts of power into the probe head.

The R$_1$ experiment should be about the same temperature as a HSQC and hence be close to the standard MeOH/ethylene glycol spectrometer calibration.  However the R$_2$ CPMG or spin lock and, to a lesser extent, the NOE pre-saturation pump a lot more power into the probe head.  The power differences can either cause the temperature in the sample to be too high or too low.  This is unpredictable as the thermometer used by the VT unit is next to the coils in the probe head and not inside the NMR\index{NMR} sample.  So the VT unit tries to control the temperature inside the probe head rather than in the NMR\index{NMR} sample.  However between the thermometer and the sample is the water of the sample, the glass of the NMR\index{NMR} tube, the air gap where the VT unit controls air flow and the outside components of the probe head protecting the electronics.  If the sample, the probe head or the VT unit is changed, this will have a different affect on the per-experiment temperature.  The VT unit responds differently under different conditions and may sometimes over or under compensate by a couple of degrees.  Therefore each relaxation\index{relaxation} data set from each spectrometer requires a per-experiment calibration.

Specifying the per-experiment calibration method is needed for BMRB data deposition.  The currently allowed methods are:

\begin{itemize}
  \item[]\quotecmd{methanol},
  \item[]\quotecmd{monoethylene glycol},
  \item[]\quotecmd{no calibration applied}.
\end{itemize}

Other methods will be accepted if supplied.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.temp\-\_control} \label{uf: relax_data.temp_control}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/status/weather-clear}

\subsubsection{Synopsis}

Specify the temperature control method used.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]temp\_control}(\linebreak[0]ri\_id=\linebreak[0]None, method=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.

\hspace{3 mm}\keyword{method:}  The control method.


\subsubsection{Description}

For the proper measurement of relaxation\index{relaxation} data, explicit temperature control techniques are essential.  A number of factors can cause significant temperature fluctuations between individual relaxation\index{relaxation} experiments.  This includes the daily temperature cycle of the room housing the spectrometer, different amounts of power for the individual experiments, etc.

The best methods for eliminating such problems are single scan interleaving and temperature compensation block.  Single scan interleaving is the most powerful technique for averaging the temperature fluctuations not only across different experiments, but also across the entire measurement time.  The application of off-resonance temperature compensation blocks at the start of the experiment is useful for the R$_2$ and will normalise the temperature between the individual experiments, but single scan or single fid interleaving is nevertheless required for normalising the temperature across the entire measurement.

Specifying the temperature control method is needed for BMRB data deposition.  The currently allowed methods are:

\begin{itemize}
  \item[]\quotecmd{single scan interleaving},
  \item[]\quotecmd{temperature compensation block},
  \item[]\quotecmd{single scan interleaving and temperature compensation block},
  \item[]\quotecmd{single fid interleaving},
  \item[]\quotecmd{single experiment interleaving},
  \item[]\quotecmd{no temperature control applied}.
\end{itemize}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.type} \label{uf: relax_data.type}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the type of relaxation\index{relaxation} data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]type}(\linebreak[0]ri\_id=\linebreak[0]None, ri\_type=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string of the data to set the frequency of.

\hspace{3 mm}\keyword{ri\_type:}  The relaxation\index{relaxation} data type, $i$.e. \quotecmd{R1}, \quotecmd{R2}, or \quotecmd{NOE}.


\subsubsection{Description}

This allows the type associated with the relaxation\index{relaxation} data to be either set or reset.  This type must be one of \quotecmd{R1}, \quotecmd{R2}, or \quotecmd{NOE}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_data\-.write} \label{uf: relax_data.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} relaxation\index{relaxation} data to a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_data.\linebreak[0]write}(\linebreak[0]ri\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, bc=\linebreak[0]False, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ri\_id:}  The relaxation\index{relaxation} data ID string.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{bc:}  A flag which if True will cause the back-calculated data to be written to the file.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

If no directory name is given, the file will be placed in the current working directory.  The relaxation\index{relaxation} data ID string is required for selecting which relaxation\index{relaxation} data to write\index{write} to file.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.catia\-\_execute} \label{uf: relax_disp.catia_execute}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Perform a relaxation\index{relaxation} dispersion optimisation using Flemming Hansen's CATIA.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]catia\_execute}(\linebreak[0]dir=\linebreak[0]None, binary=\linebreak[0]`catia')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory containing all of the CATIA input files.

\hspace{3 mm}\keyword{binary:}  The name of the executable CATIA program file.


\subsubsection{Description}

CATIA will be executed as

\begin{lstlisting}[numbers=none]
$ catia < Fit.catia
\end{lstlisting}


If you would like to use a different CATIA executable file, change the binary name to the appropriate file name.  If the file is not located within the environment's path, include the full path in front of the binary file name.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.catia\-\_input} \label{uf: relax_disp.catia_input}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create the input files for Flemming Hansen's CATIA program.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]catia\_input}(\linebreak[0]dir=\linebreak[0]`catia', force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory to place the CATIA input files, output directory, etc.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the files to be overwritten if they already exist.


\subsubsection{Description}

This will create all of the input file required for CATIA as well as the CATIA results output directory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.cluster} \label{uf: relax_disp.cluster}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/cluster}

\subsubsection{Synopsis}

Define clusters of spins for joint optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]cluster}(\linebreak[0]cluster\_id=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{cluster\_id:}  The cluster identification string.

\hspace{3 mm}\keyword{spin\_id:}  The spin identifier string for the spin or group of spins to add to the cluster.


\subsubsection{Description}

In a relaxation\index{relaxation} dispersion analysis, the parameters of the model of dispersion can either be optimised\index{optimise} for each spin system separately or a number of spins can be grouped or clustered and the dispersion model parameters optimised\index{optimise} for all spins in the cluster together.  Clusters are identified by unique ID strings.  Any spins not within a cluster will be optimised\index{optimise} separately and individually.

If the cluster ID string already exists, the spins will be added to that pre-existing cluster.  If no spin ID is given, then all spins will be added to the cluster.

The special cluster ID string \quotecmd{free spins} is reserved for the pool of non-clustered spins.  This can be used to remove a spin system from an already existing cluster by specifying this cluster ID and the desired spin ID.

\subsubsection{Prompt examples}

To add the spins \quotecmd{:1@N} and \quotecmd{:3@N} to a new cluster called \quotecmd{cluster}, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_disp.cluster('cluster', ':1,3@N')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_disp.cluster(cluster_id='cluster', spin_id=':1,3@N')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.cpmg\-\_setup} \label{uf: relax_disp.cpmg_setup}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill 

\subsubsection{Synopsis}

Set the CPMG pulse sequence\index{sequence} information associated with a given spectrum.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]cpmg\_setup}(\linebreak[0]spectrum\_id=\linebreak[0]None, cpmg\_frq=\linebreak[0]None, ncyc\_even=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string to associate the CPMG pulse sequence\index{sequence} information to.

\hspace{3 mm}\keyword{cpmg\_frq:}  The frequency, in Hz, of the CPMG pulse train.

\hspace{3 mm}\keyword{ncyc\_even:}  A flag which if True means that the number of CPMG blocks must be even.  This is pulse sequence\index{sequence} dependant.


\subsubsection{Description}

This allows all information about CPMG pulse sequence\index{sequence} required for a relaxation\index{relaxation} dispersion analysis to be specified.  This includes:

\begin{itemize}
  \item[]\quotecmd{cpmg\_frq} allows the CPMG pulse train frequency of a given spectrum to be set.  If None is given for frequency, then the spectrum will be treated as a reference spectrum.
  \item[]\quotecmd{ncyc\_even} specifies if an even number of CPMG blocks are required for the pulse sequence.\index{sequence}
\end{itemize}

\subsubsection{Prompt examples}

To identify the reference spectrum called \quotecmd{reference\_spectrum}, type:

\begin{lstlisting}[numbers=none]
relax> relax_disp.cpmg_setup(spectrum_id='reference_spectrum', cpmg_frq=None)
\end{lstlisting}


To set a frequency of 200 Hz for the spectrum \quotecmd{200\_Hz\_spectrum}, type:

\begin{lstlisting}[numbers=none]
relax> relax_disp.cpmg_setup(spectrum_id='200_Hz_spectrum', cpmg_frq=200)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.cpmgfit\-\_execute} \label{uf: relax_disp.cpmgfit_execute}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Optimisation of the CPMG data using Art Palmer's CPMGFit program.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]cpmgfit\_execute}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False, binary=\linebreak[0]`cpmgfit')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory containing all of the CPMGFit input files.  If not given, this defaults to the model name in lower case.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the results files to be overwritten if they already exist.

\hspace{3 mm}\keyword{binary:}  The name of the executable CPMGFit program file.


\subsubsection{Description}

CPMGFit will be executed once per spin as:

\begin{lstlisting}[numbers=none]
$ cpmgfit -grid -xmgr -f dir/spin_x.in | tee dir/spin_x.out
\end{lstlisting}


where $x$ is replaced by each spin ID string.  If you would like to use a different CPMGFit executable file, change the binary name to the appropriate file name.  If the file is not located within the environment's path, be sure to include the full path in front of the binary file name so it can be found.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.cpmgfit\-\_input} \label{uf: relax_disp.cpmgfit_input}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create the input files for Art Palmer's CPMGFit program.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]cpmgfit\_input}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False, binary=\linebreak[0]`cpmgfit', spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory to place the files.  If not given, this defaults to the model name in lower case.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the files to be overwritten if they already exist.

\hspace{3 mm}\keyword{binary:}  The name of the executable CPMGFit program file.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

The following files are created:

\begin{itemize}
  \item[]\quotecmd{dir/spin\_x.in},
  \item[]\quotecmd{dir/run.sh}.
\end{itemize}

One CPMGFit input file is created per spin and named \quotecmd{dir/spin\_x.in}, where $x$ is the spin ID string.  The file \quotecmd{dir/run.sh} is a batch file for executing CPMGFit for all of the spin input files.  If you would like to use a different CPMGFit executable file, change the binary name to the appropriate file name.  If the file is not located within the environment's path, be sure to include the full path in front of the binary name so it can be found.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.exp\-\_type} \label{uf: relax_disp.exp_type}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill 

\subsubsection{Synopsis}

Select the relaxation\index{relaxation} dispersion experiment type.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]exp\_type}(\linebreak[0]spectrum\_id=\linebreak[0]None, exp\_type=\linebreak[0]`SQ CPMG')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string to associate the spin-lock field strength to.

\hspace{3 mm}\keyword{exp\_type:}  The type of relaxation\index{relaxation} dispersion experiment performed.


\subsubsection{Description}

For each peak intensity set loaded into relax, the type of experiment it comes from needs to be specified.  By specifying this for each spectrum ID, multiple experiment types can be analysed simultaneously.  This is assuming that an appropriate dispersion model exists for the experiment combination.

The currently supported experiments include:

\begin{description}
  \item[\quotecmd{SQ CPMG} --] The single quantum (SQ) CPMG-type experiments,
  \item[\quotecmd{ZQ CPMG} --] The zero quantum (ZQ) CPMG-type experiments,
  \item[\quotecmd{DQ CPMG} --] The double quantum (DQ) CPMG-type experiments,
  \item[\quotecmd{MQ CPMG} --] The multiple quantum (MQ) CPMG-type experiments,
  \item[\quotecmd{1H SQ CPMG} --] The 1H single quantum (SQ) CPMG-type experiments,
  \item[\quotecmd{1H MQ CPMG} --] The 1H multiple quantum (MQ) CPMG-type experiments,
  \item[\quotecmd{R1$r$ho} --] The R1$r$ho-type experiments.
\end{description}

\subsubsection{Prompt examples}

To set the experiment type to \quotecmd{SQ CPMG} for the spectrum ID \quotecmd{nu\_4500.0\_800MHz}, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_disp.exp_type('nu_4500.0_800MHz', 'SQ CPMG')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_disp.exp_type(spectrum_id='nu_4500.0_800MHz', exp_type='SQ CPMG')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.insignificance} \label{uf: relax_disp.insignificance}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin_grey}

\subsubsection{Synopsis}

Deselect all spins with insignificant dispersion.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]insignificance}(\linebreak[0]level=\linebreak[0]2.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{level:}  The R2eff/R1$r$ho value in rad/s by which to judge insignificance.  If the maximum difference between two points on all dispersion curves for a spin is less than this value, that spin will be deselected.


\subsubsection{Description}

This can be used to deselect all spins which have insignificant dispersion profiles.  The insignificance value is the R2eff/R1$r$ho value in rad/s by which to judge the dispersion curves by.  If the maximum difference between two points on all dispersion curves for a spin is less than this value, that spin will be deselected.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.nessy\-\_input} \label{uf: relax_disp.nessy_input}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/nessy}

\subsubsection{Synopsis}

Create the input files for Michael Bieri's NESSY program.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]nessy\_input}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory to place the file and to use as the NESSY project directory.  If not given, this defaults to the current directory.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the files to be overwritten if they already exist.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

This will create a single NESSY save file called \quotecmd{save.NESSY}.  This will contain all of the dispersion data currently loaded in the relax data store.  If the directory name is not supplied, this will default to the current directory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.parameter\-\_copy} \label{uf: relax_disp.parameter_copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} dispersion specific parameters values from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]parameter\_copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the pipe to copy\index{copy} from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the pipe to copy\index{copy} to.


\subsubsection{Description}

This is a special function for copying\index{copy} relaxation\index{relaxation} dispersion parameters from one data pipe to another.  It is much more advanced than the value.copy user function, in that clustering is taken into account.  When the destination data pipe has spin clusters defined, then the new parameter values, when required, will be taken as the median value.

For the cluster specific parameters, $i$.e. the populations of the states and the exchange parameters, a median value will be used as the starting point.  For all other parameters, the R20 values for each spin and magnetic field, as well as the parameters related to the chemical shift difference dw, the optimised\index{optimise} values of the previous run will be directly copied.

\subsubsection{Prompt examples}

To copy\index{copy} the CSA values from the data pipe \quotecmd{m1} to \quotecmd{m2}, type:

\begin{lstlisting}[numbers=none]
relax> value.parameter_copy('m1', 'm2', 'csa')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.plot\-\_disp\-\_curves} \label{uf: relax_disp.plot_disp_curves}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create 2D Grace\index{software!Grace}\index{software!Grace} plots\index{plot} of the dispersion curves for each spin system.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]plot\_disp\_curves}(\linebreak[0]dir=\linebreak[0]`grace', y\_axis=\linebreak[0]`r2\_eff', x\_axis=\linebreak[0]`disp', num\_points=\linebreak[0]1000, extend\_hz=\linebreak[0]500.0, extend\_ppm=\linebreak[0]500.0, interpolate=\linebreak[0]`disp', force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory name to place all of the spin system files into.

\hspace{3 mm}\keyword{y\_axis:}  Option can be either \quotecmd{r2\_eff} which plot\index{plot} \quotecmd{r2eff} for CPMG experiments or \quotecmd{r1$r$ho} for R1$r$ho experiments or option can be \quotecmd{r2\_r1$r$ho}, which for R1$r$ho experiments plot\index{plot} R$_2$.

\hspace{3 mm}\keyword{x\_axis:}  Option can be either \quotecmd{disp} which plot\index{plot} \quotecmd{CPMG frequency (Hz)} for CPMG experiments or \quotecmd{Spin-lock field strength (Hz)} for R1$r$ho experiments or option can be either \quotecmd{w\_eff} or \quotecmd{theta} for R1$r$ho experiments, which plot\index{plot} \quotecmd{Effective field in rotating frame (rad/s)} or \quotecmd{Rotating frame tilt angle\index{angles} $\theta$ (rad)}

\hspace{3 mm}\keyword{num\_points:}  The total number of points to generate the interpolated dispersion curves with.  This value has no effect for the numeric CPMG-based models.

\hspace{3 mm}\keyword{extend\_hz:}  How far to extend the interpolated dispersion curves beyond the last dispersion point, $i$.e. the nu\_CPMG frequency or spin-lock field strength value, in Hertz.

\hspace{3 mm}\keyword{extend\_ppm:}  How far to extend the interpolated dispersion curves beyond the last dispersion point, $i$.e. the spin-lock offset value, in ppm.

\hspace{3 mm}\keyword{interpolate:}  Either by option \quotecmd{disp} which interpolate CPMG frequency or spin-lock field strength, or by option \quotecmd{offset} which interpole over spin-lock offset.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the files to be overwritten.


\subsubsection{Description}

This is used to create 2D Grace\index{software!Grace}\index{software!Grace} plots\index{plot} of the dispersion curves of the nu\_CPMG frequencies or spin-lock field strength verses the R2eff/R1$r$ho values.  One file will be created per spin system with the name \quotecmd{disp\_x.agr}, where $x$ is related to the spin ID string.  For each file, one Grace\index{software!Grace}\index{software!Grace} graph will be produced for each experiment.

Four sets of curves of R2eff/R1$r$ho values will be produced per experiment and per magnetic field strength.  These are the experimental values, the fitted values, the interpolated dispersion curves for the fitted solution, and the residuals.  Different dispersion models result in different interpolated dispersion curves.  For the numeric models which use CPMG-type data, the maximum interpolation resolution is constrained by the frequency of a single CPMG block for the entire relaxation\index{relaxation} period.  For all other models, the interpolation resolution is not constrained and can be as fine as desired by setting the total number of interpolation points.  Interpolated curves are not produced for the \quotecmd{R2eff} model as they are not necessary.

For R1$r$ho models, graphs can be interpolated against Spin-lock offset, but this feature is not available for CPMG experiment types.  It is also possible to select values on X-axis of \quotecmd{Effective field in rotating frame w\_eff (rad/s)} or \quotecmd{Rotating frame tilt angle\index{angles} $\theta$ (rad)}.

For R1$r$ho models, special Y-value R$_2$ R1$r$ho can for example be plotted\index{plot} as function of w\_eff.  R$_2$ is calculated as: R2=(R1$r$ho - R$_1$ cos\^{}2($\theta$)) / sin\^{}2($\theta$).



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.plot\-\_exp\-\_curves} \label{uf: relax_disp.plot_exp_curves}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create 2D Grace\index{software!Grace}\index{software!Grace} plots\index{plot} of the exponential curves.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]plot\_exp\_curves}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]`grace', force=\linebreak[0]False, norm=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the file to be overwritten.

\hspace{3 mm}\keyword{norm:}  A flag which, if set to True, will cause all graphs to be normalised to a starting value of 1.  This is for the normalisation of series type data.


\subsubsection{Description}

This is used to create 2D Grace\index{software!Grace}\index{software!Grace} plots\index{plot} of the individual exponential curves used to find the R2eff or R1$r$ho values.  This supplements the grace.write\index{software!Grace} user function which is not capable of generating these curves in a reasonable format.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.r1\-\_fit} \label{uf: relax_disp.r1_fit}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/status/object-locked}

\subsubsection{Synopsis}

Switch between fixed or fitted R$_1$ values for optimisation.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]r1\_fit}(\linebreak[0]fit=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{fit:}  The flag specifying if R$_1$ values should be optimised\index{optimise} or if loaded R$_1$ values should be fixed during optimisation.


\subsubsection{Description}

This user function allows the optimisation of R$_1$ values to be turned on an off for the relaxation\index{relaxation} dispersion dispersion models.  If turned off, the current values of R$_1$ will be fixed.  Otherwise the R$_1$ values will be added to the model parameter set.  For models which do not support the R$_1$ parameter for off-resonance effects, this setting will have no effect.  Only the models [\quotecmd{No $R_{ex}$}, \quotecmd{DPL94}, \quotecmd{TP02}, \quotecmd{TAP03}, \quotecmd{MP05}, \quotecmd{NS R1$r$ho 2-site}] support R$_1$ optimisation.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.r20\-\_from\-\_min\-\_r2eff} \label{uf: relax_disp.r20_from_min_r2eff}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/grid_search}

\subsubsection{Synopsis}

Set the R20 parameter values to that of the minimum R2eff value.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]r20\_from\_min\_r2eff}(\linebreak[0]force=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the R20 values to be overwritten if they already exist.


\subsubsection{Description}

Set the R20 parameter values to that of the minimum R2eff value.  This user function will look through all R2eff values per magnetic field strength, find the minimum value, and set the R20, R20A, R20B, and R1$r$ho' parameters of the model to this value.  This can serve a number of purposes including using the values for the chi-squared\index{chi-squared} space mapping\index{map} via the $\delta_x$.map user function, speeding up optimisation by avoiding the grid search for these parameters, and as initial parameter values for other dispersion software.

Instead of finding the initial values for the R20 parameter using the grid search, the minimum for the R2eff points can be used instead.  This is often a good initial position for minimisation.\index{optimisation}  For example for a two field CPMG experiment with model CR72, that would drop the number of uniform grid search points from 5D to 3D, $i$.e. two orders of magnitude faster.  When using the standard 21 grid increments per dimension, it would allow the grid search to be 441 times faster.  Note that the relaxation\index{relaxation} dispersion auto-analysis will take all pre-set parameter values into account and will automatically exclude these from the grid search.

Note that for optimisation, that this is an experimental and unpublished feature of the dispersion analysis.  If R20 $<<$ min(R2eff), the grid search will be performed in a region of the optimisation space quite distant from the true minimum.  If unsure, do not activate this option, and let the grid search find a better starting value.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.r2eff\-\_err\-\_estimate} \label{uf: relax_disp.r2eff_err_estimate}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_fit}

\subsubsection{Synopsis}

Estimate R2eff errors by the Jacobian matrix.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]r2eff\_err\_estimate}(\linebreak[0]spin\_id=\linebreak[0]None, epsrel=\linebreak[0]0.0, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict value setting to.

\hspace{3 mm}\keyword{epsrel:}  The parameter to remove linear-dependent columns when J is rank deficient.

\hspace{3 mm}\keyword{verbosity:}  The higher the value, the greater the verbosity.


\subsubsection{Description}

This is a new experimental feature from version 3.3.

This will estimate R2eff errors by using the exponential decay Jacobian matrix \quotecmd{J} to compute the covariance matrix of the best-fit parameters.

This can be an huge time saving step, when performing model fitting in R1$r$ho.  Errors of R2eff values, are normally estimated by time-consuming Monte-Carlo simulations.

This method is inspired from the GNU Scientific Library (GSL).

The covariance matrix is given by: covar = Qxx = (J\^{}T.W.J)\^{}-1, where the weight matrix W is constructed by the multiplication of an Identity matrix I and a weight array w.  The weight array is 1/errors\^{}2, which then gives W = I.w = I $x$ 1/errors\^{}2.

Qxx is computed by QR decomposition, J\^{}T.W.J=QR, Qxx=R\^{}-1. Q\^{}T.  The columns of $\mathfrak{R}$ which satisfy: |R\_\{kk\}| $\le$ epsrel |R\_\{11\}| are considered linearly-dependent and are excluded from the covariance matrix (the corresponding rows and columns of the covariance matrix are set to zero).

The parameter \quotecmd{epsrel} is used to remove linear-dependent columns when J is rank deficient.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.r2eff\-\_read} \label{uf: relax_disp.r2eff_read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} R2eff/R1$r$ho values and errors from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]r2eff\_read}(\linebreak[0]id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, disp\_frq=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, data\_col=\linebreak[0]None, error\_col=\linebreak[0]None, sep=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{id:}  The partial experiment ID string to identify this data with.  The full ID string will be constructed as this ID followed by an underscore and then the dispersion point value from the file.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{disp\_frq:}  For CPMG-type data, the frequency of the CPMG pulse train.  For R1$r$ho-type data, the spin-lock field strength nu1.  The units must be Hertz

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column used by the generic file format (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column used by the generic file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{data\_col:}  The RDC data column.

\hspace{3 mm}\keyword{error\_col:}  The experimental error column.

\hspace{3 mm}\keyword{sep:}  The column separator used by the generic format (the default is white space).


\subsubsection{Description}

This will read\index{read} R2eff/R1$r$ho data directly from a file.  The data will be associated with an experiment ID string.  A partial ID is to be supplied and then the full ID string will be constructed as this ID followed by an underscore and then the dispersion point value from the file (as \quotecmd{\%s\_\%s} \% (id, disp\_point)).  The full IDs must already exist and have been used to set the type of dispersion experiment the data is from, spectrometer proton frequency of the data, and if needed the time of the relaxation\index{relaxation} period.

The format of this text file must be that each row corresponds to a unique spin system and that there is one file per dispersion point (i.e. per CPMG frequency nu\_CPMG or per spin-lock field strength nu1).  The file must be in columnar format and information to identify the spin must be in columns of the file.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.r2eff\-\_read\-\_spin} \label{uf: relax_disp.r2eff_read_spin}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} R2eff/R1$r$ho values and errors for a single spin from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]r2eff\_read\_spin}(\linebreak[0]id=\linebreak[0]None, spin\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, disp\_point\_col=\linebreak[0]None, offset\_col=\linebreak[0]None, data\_col=\linebreak[0]2, error\_col=\linebreak[0]3, sep=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{id:}  The experiment ID string to identify this data with.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{disp\_point\_col:}  The column containing the CPMG frequency or spin-lock field strength (Hz).

\hspace{3 mm}\keyword{offset\_col:}  The column containing the offset information for R1$r$ho-type data.

\hspace{3 mm}\keyword{data\_col:}  The column containing the R2eff or R1$r$ho data.

\hspace{3 mm}\keyword{error\_col:}  The column containing the R2eff or R1$r$ho error.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).


\subsubsection{Description}

This will read\index{read} R2eff/R1$r$ho data for a single spin directly from a file.  The data will be associated with an experiment ID string.  This ID can be used for setting the type of dispersion experiment the data is from, spectrometer proton frequency of the data, and the time of the relaxation\index{relaxation} period.

The format of this text file must be that each row corresponds to a dispersion point (i.e. per CPMG frequency nu\_CPMG or per spin-lock field strength nu1) and that there is one file per unique spin system.  The file must be in columnar format.  For R1$r$ho data, the dispersion point column can be substituted for the offset values in Hertz.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.relax\-\_time} \label{uf: relax_disp.relax_time}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/chronometer}

\subsubsection{Synopsis}

Set the relaxation\index{relaxation} delay time associated with each spectrum.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]relax\_time}(\linebreak[0]spectrum\_id=\linebreak[0]None, time=\linebreak[0]0.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string.

\hspace{3 mm}\keyword{time:}  The time, in seconds, of the relaxation\index{relaxation} period.


\subsubsection{Description}

Peak intensities should be loaded before calling this user function via the spectrum.read\_intensities user function.  The intensity values will then be associated with a spectrum identifier.  To associate each spectrum identifier with a time point in the relaxation\index{relaxation} curve prior to optimisation, this user function should be called.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.select\-\_model} \label{uf: relax_disp.select_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Select the relaxation\index{relaxation} dispersion model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]select\_model}(\linebreak[0]model=\linebreak[0]`R2eff')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The type of relaxation\index{relaxation} dispersion model to fit.


\subsubsection{Description}

A number of different dispersion models are supported.  This includes both analytic models and numerical models.  Models which are independent of the experimental data type are:

\begin{description}
  \item[\quotecmd{R2eff} --] This is the model used to determine the R2eff/R1$r$ho values and errors required as the base data for all other models,
\end{description}

\subsubsection{The no chemical exchange models}

\begin{description}
  \item[\quotecmd{No $R_{ex}$} --] This is the model for no chemical\index{chemical exchange} exchange being present.
\end{description}

\subsubsection{The SQ CPMG-type experiments}

The currently supported analytic models are:

\begin{description}
  \item[\quotecmd{LM63} --] The original Luz and Meiboom (1963) 2-site fast exchange equation with parameters \{R20, ..., $\phi$\_ex, kex\},
  \item[\quotecmd{LM63 3-site} --] The original Luz and Meiboom (1963) 3-site fast exchange equation with parameters \{R20, ..., $\phi$\_ex, kex, $\phi$\_ex2, kex2\},
  \item[\quotecmd{CR72} --] The reduced Carver and Richards (1972) 2-site equation for most time scales whereby the simplification R20A = R20B is assumed.  The parameters are \{R20, ..., pA, dw, kex\},
  \item[\quotecmd{CR72 full} --] The full Carver and Richards (1972) 2-site equation for most time scales with parameters \{R20A, R20B, ..., pA, dw, kex\},
  \item[\quotecmd{IT99} --] The Ishima and Torchia (1999) 2-site model for all time scales with pA $>>$ pB and with parameters \{R20, ..., pA, dw, kex\},
  \item[\quotecmd{TSMFK01} --] The Tollinger, Kay et al. (2001) 2-site very-slow exchange model, range of microsecond to second time scale.  Applicable in the limit\index{parameter!limit} of slow exchange, when |R20A-R20B| $<<$ $k$\_AB,kB $<<$ 1/tau\_CP.  R20A is the transverse relaxation\index{relaxation} rate of site A in the absence of exchange.  2*tau\_CP is is the time between successive 180 deg. pulses.  The parameters are \{R20A, ..., dw, $k$\_AB\}.
  \item[\quotecmd{B14} --] The Baldwin (2014) 2-site exact solution model for all time scales, whereby the simplification R20A = R20B is assumed. The parameters are \{R20, ..., pA, dw, kex\},
  \item[\quotecmd{B14 full} --] The Baldwin (2014) 2-site exact solution model for all time scales with parameters \{R20A, R20B, ..., pA, dw, kex\},
\end{description}

The currently supported numeric models are:

\begin{description}
  \item[\quotecmd{NS CPMG 2-site 3D} --] The reduced numerical solution for the 2-site Bloch-McConnell equations using 3D magnetisation vectors whereby the simplification R20A = R20B is assumed.  Its parameters are \{R20, ..., pA, dw, kex\},
  \item[\quotecmd{NS CPMG 2-site 3D full} --] The full numerical solution for the 2-site Bloch-McConnell equations using 3D magnetisation vectors.  Its parameters are \{R20A, R20B, ..., pA, dw, kex\},
  \item[\quotecmd{NS CPMG 2-site star} --] The reduced numerical solution for the 2-site Bloch-McConnell equations using complex conjugate matrices whereby the simplification R20A = R20B is assumed.  It has the parameters \{R20, ..., pA, dw, kex\},
  \item[\quotecmd{NS CPMG 2-site star full} --] The full numerical solution for the 2-site Bloch-McConnell equations using complex conjugate matrices with parameters \{R20A, R20B, ..., pA, dw, kex\},
  \item[\quotecmd{NS CPMG 2-site expanded} --] The numerical solution for the 2-site Bloch-McConnell equations expanded using Maple\index{map} by Nikolai Skrynnikov.  It has the parameters \{R20, ..., pA, dw, kex\}.
\end{description}

\subsubsection{The MMQ CPMG-type experiments}

The currently supported models are:

\begin{description}
  \item[\quotecmd{MMQ CR72} --] The the Carver and Richards (1972) 2-site model for most time scales expanded for MMQ CPMG data by Korzhnev et al., 2004, whereby the simplification R20A = R20B is assumed.  Its parameters are \{R20, ..., pA, dw, dwH, kex\}.
  \item[\quotecmd{NS MMQ 2-site} --] The numerical solution for the 2-site Bloch-McConnell equations for combined proton-heteronuclear SQ, ZQ, DQ, and MQ CPMG data whereby the simplification R20A = R20B is assumed.  Its parameters are \{R20, ..., pA, dw, dwH, kex\}.
  \item[\quotecmd{NS MMQ 3-site linear} --] The numerical solution for the 3-site Bloch-McConnell equations linearised with kAC = kCA = 0 for combined proton-heteronuclear SQ, ZQ, DQ, and MQ CPMG data whereby the simplification R20A = R20B = R20C is assumed.  Its parameters are \{R20, ..., pA, dw(AB), dwH(AB), kex(AB), pB, dw(BC), dwH(BC), kex(BC)\}.
  \item[\quotecmd{NS MMQ 3-site} --] The numerical solution for the 3-site Bloch-McConnell equations for combined proton-heteronuclear SQ, ZQ, DQ, and MQ CPMG data whereby the simplification R20A = R20B = R20C is assumed.  Its parameters are \{R20, ..., pA, dw(AB), dwH(AB), kex(AB), pB, dw(BC), dwH(BC), kex(BC), kex(AC)\}.
\end{description}

\subsubsection{The R1rho-type experiments}

The currently supported analytic models are:

On-resonance models are:

\begin{description}
  \item[\quotecmd{M61} --] The Meiboom (1961) 2-site fast exchange equation with parameters \{R1$r$ho', ..., $\phi$\_ex, kex\},
  \item[\quotecmd{M61 skew} --] The Meiboom (1961) 2-site equation for all time scales with pA $>>$ pB and with parameters \{R1$r$ho', ..., pA, dw, kex\},
\end{description}

Off-resonance models are:

\begin{description}
  \item[\quotecmd{DPL94} --] The Davis, Perlman and London (1994) 2-site fast exchange equation with parameters \{R1$r$ho', ..., $\phi$\_ex, kex\},
  \item[\quotecmd{TP02} --] The Trott and Palmer (2002) 2-site equation for all time scales with parameters \{R1$r$ho', ..., pA, dw, kex\}.
  \item[\quotecmd{TAP03} --] The Trott, Abergel and Palmer (2003) off-resonance 2-site equation for all time scales with parameters \{R1$r$ho', ..., pA, dw, kex\}.
  \item[\quotecmd{MP05} --] The Miloushev and Palmer (2005) 2-site off-resonance equation for all time scales with parameters \{R1$r$ho', ..., pA, dw, kex\}.
\end{description}

The currently supported numeric models are:

\begin{description}
  \item[\quotecmd{NS R1$r$ho 2-site} --] The numerical solution for the 2-site Bloch-McConnell equations using 3D magnetisation vectors whereby the simplification R20A = R20B.  Its parameters are \{R1$r$ho', ..., pA, dw, kex\}.
  \item[\quotecmd{NS R1$r$ho 3-site linear} --] The numerical solution for the 3-site Bloch-McConnell equations using 3D magnetisation vectors whereby the simplification R20A = R20B = R20C is assumed and linearised with kAC = kCA = 0.  Its parameters are \{R1$r$ho', ..., pA, dw(AB), kex(AB), pB, dw(BC), kex(BC)\}.
  \item[\quotecmd{NS R1$r$ho 3-site} --] The numerical solution for the 3-site Bloch-McConnell equations using 3D magnetisation vectors.  Its parameters are \{R1$r$ho', ..., pA, dw(AB), kex(AB), pB, dw(BC), kex(BC), kex(AC)\}.
\end{description}

\subsubsection{Prompt examples}

To pick the 2-site fast exchange model for all selected spins, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_disp.select_model('LM63')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_disp.select_model(model='LM63')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.sherekhan\-\_input} \label{uf: relax_disp.sherekhan_input}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/sherekhan}

\subsubsection{Synopsis}

Create the input files for Adam Mazur's ShereKhan program.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]sherekhan\_input}(\linebreak[0]force=\linebreak[0]False, spin\_id=\linebreak[0]None, dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause the files to be overwritten if they already exist.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.

\hspace{3 mm}\keyword{dir:}  The directory name to place ShereKhan cluster folders into.


\subsubsection{Description}

This creates the files required for the ShereKhan server located at http://sherekhan.bionmr.org/.  One file per spin cluster per field strength will be created.  These will be placed in the directory \quotecmd{clusterx} and named \quotecmd{sherekhan\_frqy.in}, where $x$ is the cluster index starting from 1 and $y$ is the magnetic field strength index starting from 1.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.spin\-\_lock\-\_field} \label{uf: relax_disp.spin_lock_field}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill 

\subsubsection{Synopsis}

Set the relaxation\index{relaxation} dispersion spin-lock field strength (nu1).


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]spin\_lock\_field}(\linebreak[0]spectrum\_id=\linebreak[0]None, field=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string to associate the spin-lock field strength to.

\hspace{3 mm}\keyword{field:}  The spin-lock field strength, nu1, in Hz.


\subsubsection{Description}

This sets the spin-lock field strength, nu1, for the specified R1$r$ho spectrum in Hertz.

\subsubsection{Prompt examples}

To set a spin-lock field strength of 2.1 kHz for the spectrum \quotecmd{nu1\_2.1$k$Hz\_relaxT\_0.010}, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_disp.spin_lock_field(2100, 'nu1_2.1kHz_relaxT_0.010')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_disp.spin_lock_field(field=2100, spectrum_id='nu1_2.1kHz_relaxT_0.010')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.spin\-\_lock\-\_offset} \label{uf: relax_disp.spin_lock_offset}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill 

\subsubsection{Synopsis}

Set the relaxation\index{relaxation} dispersion spin-lock offset (omega\_rf).


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]spin\_lock\_offset}(\linebreak[0]spectrum\_id=\linebreak[0]None, offset=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string to associate the spin-lock offset to.

\hspace{3 mm}\keyword{offset:}  The spin-lock offset, omega\_rf, in ppm.


\subsubsection{Description}

This sets the spin-lock offset, omega\_rf, for the specified R1$r$ho spectrum in ppm.

\subsubsection{Prompt examples}

To set a spin-lock offset of 110.0 ppm for the spectrum \quotecmd{nu1\_2.1$k$Hz\_relaxT\_0.010}, type one of:

\begin{lstlisting}[numbers=none]
relax> relax_disp.spin_lock_offset('nu1_2.1kHz_relaxT_0.010', 110.0)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> relax_disp.spin_lock_offset(spectrum_id='nu1_2.1kHz_relaxT_0.010', offset=110.0)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_disp\-.write\-\_disp\-\_curves} \label{uf: relax_disp.write_disp_curves}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_disp} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Create text files of the dispersion curves for each spin system.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_disp.\linebreak[0]write\_disp\_curves}(\linebreak[0]dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{dir:}  The directory name to place all of the spin system files into.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the files to be overwritten.


\subsubsection{Description}

This is used to created text files of the dispersion curves of R2eff/R1$r$ho values, both measured and back calculated from the optimised\index{optimise} dispersion model.  The columns of the text file will be the experiment name, the magnetic field strength (as the proton frequency in MHz), dispersion point (nu\_CPMG or the spin-lock field strength), the experimental R2eff value, the back-calculated R2eff value, and the experimental R2eff error.  One file will be created per spin system with the name \quotecmd{disp\_x.out}, where $x$ is the spin ID string.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_fit\-.relax\-\_time} \label{uf: relax_fit.relax_time}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_fit} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/chronometer}

\subsubsection{Synopsis}

Set the relaxation\index{relaxation} delay time associated with each spectrum.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_fit.\linebreak[0]relax\_time}(\linebreak[0]time=\linebreak[0]0.0, spectrum\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{time:}  The time, in seconds, of the relaxation\index{relaxation} period.

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum identification string.


\subsubsection{Description}

Peak intensities should be loaded before calling this user function via the spectrum.read\_intensities user function.  The intensity values will then be associated with a spectrum identifier.  To associate each spectrum identifier with a time point in the relaxation\index{relaxation} curve prior to optimisation, this user function should be called.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{relax\-\_fit\-.select\-\_model} \label{uf: relax_fit.select_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax_fit} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Select the relaxation\index{relaxation} curve type.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{relax\_fit.\linebreak[0]select\_model}(\linebreak[0]model=\linebreak[0]`exp')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The type of relaxation\index{relaxation} curve to fit.


\subsubsection{Description}

A number of relaxation\index{relaxation} experiments are supported and include:

The \quotecmd{exp} model.  This is the default two parameter exponential fit.  The magnetisation starts at I0 and decays to zero.  The parameters are [Rx, I0] and the equation is I(t) = I0*exp(-Rx*t).

The \quotecmd{inv} model.  This is the inversion recovery experiment (IR).  The magnetisation starts at a negative value at -I0 and relaxes to a positive Iinf value.  The parameters are [Rx, I0, Iinf] and the equation is I(t) = Iinf - I0*exp(-Rx*t).

The \quotecmd{sat} model.  This is the saturation recovery experiment (SR).  The magnetisation starts at zero and relaxes to a positive Iinf value.  The parameters are [Rx, Iinf] and the equation is I(t) = Iinf*(1 - exp(-Rx*t)).



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{reset} \label{uf: reset}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/dialog-close}

\subsubsection{Synopsis}

Reinitialise the relax data storage object.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{reset}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

All of the data of the relax data storage object will be erased and hence relax will return to its initial state.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{residue\-.copy} \label{uf: residue.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/residue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} all data associated with a residue.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{residue.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, res\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, res\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The data pipe containing the residue from which the data will be copied.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{res\_from:}  The residue ID string of the residue to copy\index{copy} the data from.

\hspace{3 mm}\keyword{pipe\_to:}  The data pipe to copy\index{copy} the data to.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{res\_to:}  The residue ID string of the residue to copy\index{copy} the data to.  If left blank, the new residue will have the same name as the old.


\subsubsection{Description}

This will copy\index{copy} all the data associated with the identified residue to the new, non-existent residue.  The new residue cannot currently exist.

\subsubsection{Prompt examples}

To copy\index{copy} the residue data from residue 1 to the new residue 2, type:

\begin{lstlisting}[numbers=none]
relax> residue.copy(res_from=':1', res_to=':2')
\end{lstlisting}


To copy\index{copy} residue 1 of the molecule\index{molecule} \quotecmd{Old mol} to residue 5 of the molecule\index{molecule} \quotecmd{New mol}, type:

\begin{lstlisting}[numbers=none]
relax> residue.copy(res_from='#Old mol:1', res_to='#New mol:5')
\end{lstlisting}


To copy\index{copy} the residue data of residue 1 from the data pipe \quotecmd{m1} to \quotecmd{m2}, assuming the current data pipe is \quotecmd{m1}, type:

\begin{lstlisting}[numbers=none]
relax> residue.copy(res_from=':1', pipe_to='m2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.copy(pipe_from='m1', res_from=':1', pipe_to='m2', res_to=':1')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{residue\-.create} \label{uf: residue.create}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/residue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a new residue.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{residue.\linebreak[0]create}(\linebreak[0]res\_num=\linebreak[0]None, res\_name=\linebreak[0]None, mol\_name=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{res\_num:}  The residue number.

\hspace{3 mm}\keyword{res\_name:}  The name of the residue.

\hspace{3 mm}\keyword{mol\_name:}  The name of the molecule\index{molecule} to add the residue to.


\subsubsection{Description}

Using this, a new sequence\index{sequence} can be generated without using the sequence\index{sequence} user functions.  However if the sequence\index{sequence} already exists, the new residue will be added to the end of the residue list (the residue numbers of this list need not be sequential).  The same residue number cannot be used more than once.  A corresponding single spin system will be created for this residue.  The spin system number and name or additional spin systems can be added later if desired.

\subsubsection{Prompt examples}

The following sequence\index{sequence} of commands will generate the sequence\index{sequence} 1 ALA, 2 GLY, 3 LYS:

\begin{lstlisting}[numbers=none]
relax> residue.create(1, 'ALA')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.create(2, 'GLY')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.create(3, 'LYS')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{residue\-.delete} \label{uf: residue.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/residue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} residues from the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{residue.\linebreak[0]delete}(\linebreak[0]res\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{res\_id:}  The residue ID string.


\subsubsection{Description}

This can be used to delete\index{delete} a single or sets of residues.  See the ID string documentation for more information.  If spin system/atom ids are included a RelaxError will be raised.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{residue\-.display} \label{uf: residue.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/residue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} information about the residue(s).


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{residue.\linebreak[0]display}(\linebreak[0]res\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{res\_id:}  The residue ID string.


\subsubsection{Description}

This will display\index{display} the residue data loaded into the current data pipe.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{residue\-.name} \label{uf: residue.name}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/residue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Name the residues.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{residue.\linebreak[0]name}(\linebreak[0]res\_id=\linebreak[0]None, name=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{res\_id:}  The residue ID string corresponding to one or more residues.

\hspace{3 mm}\keyword{name:}  The new name.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the residue to be renamed.


\subsubsection{Description}

This simply allows residues to be named (or renamed).

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The following sequence\index{sequence} of commands will rename the sequence\index{sequence} \{1 ALA, 2 GLY, 3 LYS\} to \{1 XXX, 2 XXX, 3 XXX\}:

\begin{lstlisting}[numbers=none]
relax> residue.name(':1', 'XXX', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.name(':2', 'XXX', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.name(':3', 'XXX', force=True)
\end{lstlisting}


Alternatively:

\begin{lstlisting}[numbers=none]
relax> residue.name(':1,2,3', 'XXX', force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{residue\-.number} \label{uf: residue.number}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/residue} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Number the residues.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{residue.\linebreak[0]number}(\linebreak[0]res\_id=\linebreak[0]None, number=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{res\_id:}  The residue ID string corresponding to a single residue.

\hspace{3 mm}\keyword{number:}  The new residue number.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the residue to be renumbered.


\subsubsection{Description}

This simply allows residues to be numbered.  The new number cannot correspond to an existing residue.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The following sequence\index{sequence} of commands will renumber the sequence\index{sequence} \{1 ALA, 2 GLY, 3 LYS\} to \{101 ALA, 102 GLY, 103 LYS\}:

\begin{lstlisting}[numbers=none]
relax> residue.number(':1', 101, force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.number(':2', 102, force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> residue.number(':3', 103, force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{results\-.display} \label{uf: results.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the results.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{results.\linebreak[0]display}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will print to screen (STDOUT) the results contained within the current data pipe.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{results\-.read} \label{uf: results.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} the contents of a relax results file into the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{results.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]`results', dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file to read\index{read} results from.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.


\subsubsection{Description}

This is able to handle uncompressed,\index{compression!uncompressed} bzip2\index{compression!bzip2} compressed files, or gzip\index{compression!gzip} compressed files automatically.  The full file name including extension can be supplied, however, if the file cannot be found the file with \quotecmd{.bz2} appended followed by the file name with \quotecmd{.gz} appended will be searched for.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{results\-.write} \label{uf: results.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} the results to a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{results.\linebreak[0]write}(\linebreak[0]file=\linebreak[0]`results', dir=\linebreak[0]`pipe\_name', compress\_type=\linebreak[0]1, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file to output results to.  The default is \quotecmd{results}.  Optionally this can be a file object, or any object with a write()\index{write} method.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{compress\_type:}  The type of compression\index{compression} to use when creating the file.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the results file to be overwritten.


\subsubsection{Description}

This will write\index{write} the entire contents of the current data pipe into an XML formatted file.  This results file can then be read\index{read} back into relax at a later point in time, or transfered to another machine.  This is in contrast to the state.save user function whereby the entire data store, including all data pipes, are saved into a similarly XML formatted file.

To place the results file in the current working directory in the prompt and scripting\index{scripting!script file}\index{scripting} modes, leave the directory unset.  If the directory is set to the special name \quotecmd{pipe\_name}, then the results file will be placed into a directory with the same name as the current data pipe.

The default behaviour of this function is to compress the file using bzip2\index{compression!bzip2} compression.\index{compression}  If the extension \quotecmd{.bz2} is not included in the file name, it will be added.  The compression\index{compression} can, however, be changed to either no compression\index{compression} or gzip\index{compression!gzip} compression.\index{compression}  This is controlled by the compression\index{compression} type which can be set to

\begin{description}
  \item[0 --] No compression\index{compression} (no file extension),
  \item[1 --] bzip2\index{compression!bzip2} compression\index{compression} (\quotecmd{.bz2} file extension),
  \item[2 --] gzip\index{compression!gzip} compression\index{compression} (\quotecmd{.gz} file extension).
\end{description}

The complementary read\index{read} function will automatically handle the compressed files.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{script\index{scripting!script file|textbf}} \label{uf: script}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/mimetypes/application-x-desktop}

\subsubsection{Synopsis}

Execute a relax script.\index{scripting!script file}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{script}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the relaxation\index{relaxation} data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.


\subsubsection{Description}

This will execute a relax or any ordinary Python\index{Python} script.\index{scripting!script file}



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.all} \label{uf: select.all}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill 

\subsubsection{Synopsis}

Select all spins in the current data pipe.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]all}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will select all spins, irregardless of their current state.

\subsubsection{Prompt examples}

To select all spins, simply type:

\begin{lstlisting}[numbers=none]
relax> select.all()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.display} \label{uf: select.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} the current spin selection status.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]display}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This simply prints out the current spin selections.

\subsubsection{Prompt examples}

To show the current selections, type:

\begin{lstlisting}[numbers=none]
relax> select.display()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.domain} \label{uf: select.domain}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill 

\subsubsection{Synopsis}

Select all spins and interatomic data containers of a domain.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]domain}(\linebreak[0]domain\_id=\linebreak[0]None, boolean=\linebreak[0]`AND', change\_all=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{domain\_id:}  The domain ID string of the domain to select.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how interatomic data containers should be selected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all non-matching spin and interatomic data containers should be deselected.


\subsubsection{Description}

This will select all spins and interatomic data containers of a given domain.  This is defined by the domain ID string as specified by the previously executed domain-related user functions.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\subsubsection{Prompt examples}

To select all spins of the domain \quotecmd{N-dom}, simply type one of:

\begin{lstlisting}[numbers=none]
relax> select.domain('N-dom', change_all=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.domain(domain_id='N-dom', change_all=True)
\end{lstlisting}


To select all spins of the domain \quotecmd{N-dom}, preserving the current selections, simply type one of:

\begin{lstlisting}[numbers=none]
relax> select.domain('N-dom', 'AND', True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.domain(domain_id='N-dom', boolean='AND', change_all=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.interatom} \label{uf: select.interatom}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill 

\subsubsection{Synopsis}

Select specific interatomic data containers.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]interatom}(\linebreak[0]spin\_id1=\linebreak[0]None, spin\_id2=\linebreak[0]None, boolean=\linebreak[0]`OR', change\_all=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id1:}  The spin ID string of the first spin of the interatomic data container.

\hspace{3 mm}\keyword{spin\_id2:}  The spin ID string of the second spin of the interatomic data container.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how interatomic data containers should be selected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all other interatomic data containers should be changed.


\subsubsection{Description}

This is used to select specific interatomic data containers which store information about spin pairs such as RDCs, NOEs, dipole-dipole pairs involved in relaxation,\index{relaxation} etc.  The \quotecmd{change all} flag default is False meaning that all interatomic data containers currently either selected or deselected will remain that way.  Setting this to True will cause all interatomic data containers not specified by the spin ID strings to be selected.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\subsubsection{Prompt examples}

To select all N-H backbone bond vectors of a protein, assuming these interatomic data containers have been already set up, type one of:

\begin{lstlisting}[numbers=none]
relax> select.interatom('@N', '@H')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.interatom(spin_id1='@N', spin_id2='@H')
\end{lstlisting}


To select all H-H interatomic vectors of a small organic molecule,\index{molecule} type one of:

\begin{lstlisting}[numbers=none]
relax> select.interatom('@H*', '@H*')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.interatom(spin_id1='@H*', spin_id2='@H*')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.read} \label{uf: select.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Select the spins contained in a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None, boolean=\linebreak[0]`OR', change\_all=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the list of spins to select.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict the loading of data to certain spin subsets.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how spins should be selected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all other spins should be changed.


\subsubsection{Description}

The spin system can be identified in the file using two different formats.  The first is the spin ID string column which can include the molecule\index{molecule} name, the residue name and number, and the spin name and number.  Alternatively the molecule\index{molecule} name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns.  Note that the numbering of columns starts at one.  The spin ID string can be used to restrict the reading\index{read} to certain spin types, for example only 15N spins when only residue information is in the file.

Empty lines and lines beginning with a hash are ignored.

The \quotecmd{change all} flag default is False meaning that all spins currently either selected or deselected will remain that way.  Setting this to True will cause all spins not specified in the file to be deselected.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\subsubsection{Prompt examples}

To select all residues listed with residue numbers in the first column of the file \quotecmd{isolated\_peaks}, type one of:

\begin{lstlisting}[numbers=none]
relax> select.read('isolated_peaks', res_num_col=1)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.read(file='isolated_peaks', res_num_col=1)
\end{lstlisting}


To select the spins in the second column of the relaxation\index{relaxation} data file \quotecmd{r1.600} while deselecting all other spins, for example type:

\begin{lstlisting}[numbers=none]
relax> select.read('r1.600', spin_num_col=2, change_all=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.read(file='r1.600', spin_num_col=2, change_all=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.reverse} \label{uf: select.reverse}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/system-switch-user}

\subsubsection{Synopsis}

Reversal of the spin selection for the given spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]reverse}(\linebreak[0]spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.


\subsubsection{Description}

By supplying the spin ID string, a subset of spins can have their selection status reversed.

\subsubsection{Prompt examples}

To select all currently deselected spins and deselect those which are selected type:

\begin{lstlisting}[numbers=none]
relax> select.reverse()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.sn\-\_ratio} \label{uf: select.sn_ratio}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid}

\subsubsection{Synopsis}

Select spins with signal to noise ratio higher or lower than the given ratio.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]sn\_ratio}(\linebreak[0]ratio=\linebreak[0]10.0, operation=\linebreak[0]`>', all\_sn=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{ratio:}  The signal to noise ratio to compare to.

\hspace{3 mm}\keyword{operation:}  The comparison operation by which to select the spins.

\hspace{3 mm}\keyword{all\_sn:}  A flag specifying if all the signal to noise ratios per spin should match the comparison operator, of if just a single comparison match is enough.


\subsubsection{Description}

The comparison operation is the method which to select spins according to: operation(sn\_ratio, ratio).

The possible operations are: \quotecmd{<}:strictly less than, \quotecmd{<=}:less than or equal, \quotecmd{>}:strictly greater than, \quotecmd{>=}:greater than or equal, \quotecmd{==}:equal, \quotecmd{!=}:not equal.

The \quotecmd{all\_sn} flag default is True, meaning that if all of the spin's signal to noise levels evaluates to True in the comparison, the spin is selected.

\subsubsection{Prompt examples}

To select all spins with a signal to noise ratio higher than 10.0:

\begin{lstlisting}[numbers=none]
relax> select.sn_ratio(ratio=10.0, operation='>')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.sn_ratio(ratio=10.0, operation='>', all_sn=False)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{select\-.spin} \label{uf: select.spin}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin}

\subsubsection{Synopsis}

Select specific spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{select.\linebreak[0]spin}(\linebreak[0]spin\_id=\linebreak[0]None, boolean=\linebreak[0]`OR', change\_all=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.

\hspace{3 mm}\keyword{boolean:}  The boolean operator specifying how spins should be selected.

\hspace{3 mm}\keyword{change\_all:}  A flag specifying if all other spins should be changed.


\subsubsection{Description}

The \quotecmd{change all} flag default is False meaning that all spins currently either selected or deselected will remain that way.  Setting this to True will cause all spins not specified by the spin ID string to be selected.

\subsubsection{Boolean operators}

The boolean operator can be used to change how spin systems or interatomic data containers are selected.  The allowed values are: \quotecmd{OR}, \quotecmd{NOR}, \quotecmd{AND}, \quotecmd{NAND}, \quotecmd{XOR}, \quotecmd{XNOR}.  The following table details how the selections will occur for the different boolean operators.

Please see Table~\ref{table: bool operators} on page~\pageref{table: bool operators}.

\subsubsection{Prompt examples}

To select only glycines and alanines, assuming they have been loaded with the names GLY and ALA, type one of:

\begin{lstlisting}[numbers=none]
relax> select.spin(spin_id=':GLY|:ALA')
\end{lstlisting}


To select residue 5 CYS in addition to the currently selected residues, type one of:

\begin{lstlisting}[numbers=none]
relax> select.spin(':5')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.spin(':5&:CYS')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> select.spin(spin_id=':5&:CYS')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{sequence\-.attach\-\_protons\index{sequence|textbf}} \label{uf: sequence.attach_protons}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/sequence} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Attach protons to all heteronuclei.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{sequence.\linebreak[0]attach\_protons}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This can be used to attach protons to all the heteronuclei in the current data pipe.  For each proton, a spin container will be created.

\subsubsection{Prompt examples}

To attach protons, simply type:

\begin{lstlisting}[numbers=none]
relax> sequence.attach_protons()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{sequence\-.copy\index{sequence|textbf}} \label{uf: sequence.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/sequence} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} the molecule,\index{molecule} residue, and spin sequence\index{sequence} data from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{sequence.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, empty=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the data pipe to copy\index{copy} the sequence\index{sequence} data from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the data pipe to copy\index{copy} the sequence\index{sequence} data to.

\hspace{3 mm}\keyword{empty:}  A flag which if True will create a molecule,\index{molecule} residue, and spin sequence\index{sequence} in the target\index{tar} pipe lacking all of the spin data of the source pipe.  If False, then the spin data will also be copied.


\subsubsection{Description}

This will copy\index{copy} the sequence\index{sequence} data between data pipes.  The destination data pipe must not contain any sequence\index{sequence} data.  If the source and destination pipes are not specified, then both will default to the current data pipe (hence providing one is essential).

\subsubsection{Prompt examples}

To copy\index{copy} the sequence\index{sequence} from the data pipe \quotecmd{m1} to the current data pipe, type:

\begin{lstlisting}[numbers=none]
relax> sequence.copy('m1')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.copy(pipe_from='m1')
\end{lstlisting}


To copy\index{copy} the sequence\index{sequence} from the current data pipe to the data pipe \quotecmd{m9}, type:

\begin{lstlisting}[numbers=none]
relax> sequence.copy(pipe_to='m9')
\end{lstlisting}


To copy\index{copy} the sequence\index{sequence} from the data pipe \quotecmd{m1} to \quotecmd{m2}, type:

\begin{lstlisting}[numbers=none]
relax> sequence.copy('m1', 'm2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.copy(pipe_from='m1', pipe_to='m2')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{sequence\-.display\index{sequence|textbf}} \label{uf: sequence.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/sequence} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} sequences\index{sequence} of molecules,\index{molecule} residues, and/or spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{sequence.\linebreak[0]display}(\linebreak[0]sep=\linebreak[0]None, mol\_name\_flag=\linebreak[0]True, res\_num\_flag=\linebreak[0]True, res\_name\_flag=\linebreak[0]True, spin\_num\_flag=\linebreak[0]True, spin\_name\_flag=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{sep:}  The column separator (the default of None corresponds to white space).

\hspace{3 mm}\keyword{mol\_name\_flag:}  A flag which if True will cause the molecule\index{molecule} name column to be shown.

\hspace{3 mm}\keyword{res\_num\_flag:}  A flag which if True will cause the residue number column to be shown.

\hspace{3 mm}\keyword{res\_name\_flag:}  A flag which if True will cause the residue name column to be shown.

\hspace{3 mm}\keyword{spin\_num\_flag:}  A flag which if True will cause the spin number column to be shown.

\hspace{3 mm}\keyword{spin\_name\_flag:}  A flag which if True will cause the spin name column to be shown.


\subsubsection{Description}

This will print out the sequence\index{sequence} information of all loaded spins in the current data pipe.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{sequence\-.read\index{sequence|textbf}} \label{uf: sequence.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/sequence} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} the molecule,\index{molecule} residue, and spin sequence\index{sequence} from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{sequence.\linebreak[0]read}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the sequence\index{sequence} data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict the loading of data to certain spin subsets.


\subsubsection{Description}

The spin system can be identified in the file using two different formats.  The first is the spin ID string column which can include the molecule\index{molecule} name, the residue name and number, and the spin name and number.  Alternatively the molecule\index{molecule} name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns.  Note that the numbering of columns starts at one.  The spin ID string can be used to restrict the reading\index{read} to certain spin types, for example only 15N spins when only residue information is in the file.

\subsubsection{Prompt examples}

The following commands will read\index{read} protein backbone 15N sequence\index{sequence} data out of a file called \quotecmd{seq} where the residue numbers and names are in the first and second columns respectively:

\begin{lstlisting}[numbers=none]
relax> sequence.read('seq')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.read('seq', res_num_col=1, res_name_col=2)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.read(file='seq', res_num_col=1, res_name_col=2, sep=None)
\end{lstlisting}


The following commands will read\index{read} the residue sequence\index{sequence} out of the file \quotecmd{noe.out} which also contains the NOE values:

\begin{lstlisting}[numbers=none]
relax> sequence.read('noe.out')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.read('noe.out', res_num_col=1, res_name_col=2)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.read(file='noe.out', res_num_col=1, res_name_col=2)
\end{lstlisting}


The following commands will read\index{read} the sequence\index{sequence} out of the file \quotecmd{noe.600.out} where the residue numbers are in the second column, the names are in the sixth column and the columns are separated by commas:

\begin{lstlisting}[numbers=none]
relax> sequence.read('noe.600.out', res_num_col=2, res_name_col=6, sep=',')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.read(file='noe.600.out', res_num_col=2, res_name_col=6, sep=',')
\end{lstlisting}


The following commands will read\index{read} the RNA residues and atoms (including C2, C5, C6, C8, N1, and N3) from the file \quotecmd{500.NOE}, where the residue number, residue name, spin number, and spin name are in the first to fourth columns respectively:

\begin{lstlisting}[numbers=none]
relax> sequence.read('500.NOE', res_num_col=1, res_name_col=2, spin_num_col=3, spin_name_col=4)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> sequence.read(file='500.NOE', res_num_col=1, res_name_col=2, spin_num_col=3, spin_name_col=4)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{sequence\-.write\index{sequence|textbf}} \label{uf: sequence.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/sequence} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} the molecule,\index{molecule} residue, and spin sequence\index{sequence} to a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{sequence.\linebreak[0]write}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, sep=\linebreak[0]None, mol\_name\_flag=\linebreak[0]True, res\_num\_flag=\linebreak[0]True, res\_name\_flag=\linebreak[0]True, spin\_num\_flag=\linebreak[0]True, spin\_name\_flag=\linebreak[0]True, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{sep:}  The column separator (the default of None corresponds to white space).

\hspace{3 mm}\keyword{mol\_name\_flag:}  A flag which if True will cause the molecule\index{molecule} name column to be shown.

\hspace{3 mm}\keyword{res\_num\_flag:}  A flag which if True will cause the residue number column to be shown.

\hspace{3 mm}\keyword{res\_name\_flag:}  A flag which if True will cause the residue name column to be shown.

\hspace{3 mm}\keyword{spin\_num\_flag:}  A flag which if True will cause the spin number column to be shown.

\hspace{3 mm}\keyword{spin\_name\_flag:}  A flag which if True will cause the spin name column to be shown.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the file to be overwritten.


\subsubsection{Description}

Write\index{write} the sequence\index{sequence} data to file.  If no directory name is given, the file will be placed in the current working directory.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrometer\-.frequency} \label{uf: spectrometer.frequency}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spectrometer} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/frq}

\subsubsection{Synopsis}

Set the spectrometer proton frequency of the experiment.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrometer.\linebreak[0]frequency}(\linebreak[0]id=\linebreak[0]None, frq=\linebreak[0]None, units=\linebreak[0]`Hz')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{id:}  The experiment identification string to set the frequency of.

\hspace{3 mm}\keyword{frq:}  The spectrometer frequency.  See the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file.

\hspace{3 mm}\keyword{units:}  The units of frequency.


\subsubsection{Description}

This allows the spectrometer frequency of a given experiment to be set.  The expected units are that of the proton resonance frequency in Hertz.  See the \quotecmd{sfrq} parameter in the Varian procpar file or the \quotecmd{SFO1} parameter in the Bruker acqus file for the exact value.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrometer\-.temperature} \label{uf: spectrometer.temperature}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spectrometer} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/status/weather-clear}

\subsubsection{Synopsis}

Specify the temperature of an experiment.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrometer.\linebreak[0]temperature}(\linebreak[0]id=\linebreak[0]None, temp=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{id:}  The experiment identification string.

\hspace{3 mm}\keyword{temp:}  The temperature of the experiment in Kalvin.


\subsubsection{Description}

This allows the temperature of an experiment to be set.  This value should be in Kalvin.  In certain analyses, for example those which use pseudocontact shift data, knowledge of the temperature is essential.  For the pseudocontact shift, the experiment ID string should match one of the alignment IDs.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.baseplane\-\_rmsd} \label{uf: spectrum.baseplane_rmsd}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the baseplane RMSD of a given spin in a spectrum for error analysis.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]baseplane\_rmsd}(\linebreak[0]error=\linebreak[0]0.0, spectrum\_id=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{error:}  The baseplane RMSD error value.

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string.

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string.


\subsubsection{Description}

The spectrum ID identifies the spectrum associated with the error and must correspond to a previously loaded set of intensities.  If the spin ID is unset, then the error value for all spins will be set to the supplied value.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.delete} \label{uf: spectrum.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} the spectral data corresponding to the spectrum ID string.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]delete}(\linebreak[0]spectrum\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_id:}  The unique spectrum ID string.


\subsubsection{Description}

The spectral data corresponding to the given spectrum ID string will be removed from the current data pipe.

\subsubsection{Prompt examples}

To delete\index{delete} the peak height data corresponding to the ID \quotecmd{R1 ncyc5}, type:

\begin{lstlisting}[numbers=none]
relax> spectrum.delete('R1 ncyc5')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.error\-\_analysis} \label{uf: spectrum.error_analysis}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Perform an error analysis for peak intensities.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]error\_analysis}(\linebreak[0]subset=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{subset:}  The list of spectrum ID strings to restrict the error analysis to.


\subsubsection{Description}

This user function must only be called after all peak intensities have been loaded and all other necessary spectral information set.  This includes the baseplane RMSD and the number of points used in volume integration, both of which are only used if spectra have not been replicated.

The error analysis can be restricted to a subset of the loaded spectral data.  This is useful, for example, if half the spectra have been collected on one spectrometer and the other half on a different spectrometer.

Six different types of error analysis are supported depending on whether peak heights or volumes are supplied, whether noise is determined from replicated spectra or the RMSD of the baseplane noise, and whether all spectra or only a subset have been duplicated.  These are:

Please see Table~\ref{table: peak intensity error analysis} on page~\pageref{table: peak intensity error analysis}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[The six peak intensity error analysis types.]{The six peak intensity error analysis types.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Int type & Noise source & Error scope \\
\midrule
Heights & RMSD baseplane & One sigma per peak per spectrum \\
Heights & Partial duplicate + variance averaging & One sigma for all peaks, all spectra \\
Heights & All replicated + variance averaging & One sigma per replicated spectra set \\
Volumes & RMSD baseplane & One sigma per peak per spectrum \\
Volumes & Partial duplicate + variance averaging & One sigma for all peaks, all spectra \\
Volumes & All replicated + variance averaging & One sigma per replicated spectra set \\
\bottomrule
\\[-5pt]
\label{table: peak intensity error analysis}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Peak heights with baseplane noise RMSD}

When none of the spectra have been replicated, then the peak height errors are calculated using the RMSD of the baseplane noise, the value of which is set by the spectrum.baseplane\_rmsd user function.  This results in a different error per peak per spectrum.  The standard deviation error measure for the peak height, sigma\_I, is set to the RMSD value.

\subsubsection{Peak heights with partially replicated spectra}

When spectra are replicated, the variance for a single spin at a single replicated spectra set is calculated by the formula

\begin{itemize}
  \item[]sigma\^{}2 =  sum(\{Ii - Iav\}\^{}2) / ($n$ - 1),
\end{itemize}

where sigma\^{}2 is the variance, sigma is the standard deviation, $n$ is the size of the replicated spectra set with $i$ being the corresponding index, Ii is the peak intensity for spectrum $i$, and Iav is the mean over all spectra $i$.e. the sum of all peak intensities divided by $n$.

As the value of $n$ in the above equation is always very low since normally only a couple of spectra are collected per replicated spectra set, the variance of all spins is averaged for a single replicated spectra set.  Although this results in all spins having the same error, the accuracy of the error estimate is significantly improved.

If there are in addition to the replicated spectra loaded peak intensities which only consist of a single spectrum, $i$.e. not all spectra are replicated, then the variances of replicated replicated spectra sets will be averaged.  This will be used for the entire experiment so that there will be only a single error value for all spins and for all spectra.

\subsubsection{Peak heights with all spectra replicated}

If all spectra are collected in duplicate (triplicate or higher number of spectra are supported), the each replicated spectra set will have its own error estimate.  The error for a single peak is calculated as when partially replicated spectra are collected, and these are again averaged to give a single error per replicated spectra set.  However as all replicated spectra sets will have their own error estimate, variance averaging across all spectra sets will not be performed.

\subsubsection{Peak volumes with baseplane noise RMSD}

The method of error analysis when no spectra have been replicated and peak volumes are used is highly dependent on the integration method.  Many methods simply sum the number of points within a fixed region, either a box or oval object.  The number of points used, N, must be specified by another user function in this class.  Then the error is simply given by the sum of variances:

\begin{itemize}
  \item[]sigma\_vol\^{}2 = sigma\_i\^{}2 * N,
\end{itemize}

where sigma\_vol is the standard deviation of the volume, sigma\_i is the standard deviation of a single point assumed to be equal to the RMSD of the baseplane noise, and N is the total number of points used in the summation integration method.  For a box integration method, this converts to the Nicholson, Kay, Baldisseri, Arango, Young, Bax, and Torchia (1992) Biochemistry, 31: 5253-5263 equation:

\begin{itemize}
  \item[]sigma\_vol = sigma\_i * sqrt(n*m),
\end{itemize}

where $n$ and $m$ are the dimensions of the box.  Note that a number of programs, for example peakint (http://hugin.ethz.ch/wuthrich/software/xeasy/xeasy\_m15.html) does not use all points within the box.  And if the number N can not be determined, this category of error analysis is not possible.

Also note that non-point summation methods, for example when line shape fitting is used to determine peak volumes, the equations above cannot be used.  Hence again this category of error analysis cannot be used.  This is the case for one of the three integration methods used by Sparky\index{software!Sparky}\index{software!Sparky} (http://www.cgl.ucsf.edu/home/sparky/manual/peaks.html\#Integration).  And if fancy techniques are used, for example as Cara does to deconvolute overlapping peaks (http://www.cara.ethz.ch/Wiki/Integration), this again makes this error analysis impossible.

\subsubsection{Peak volumes with partially replicated spectra}

When peak volumes are measured by any integration method and a few of the spectra are replicated, then the intensity errors are calculated identically as described in the \quotecmd{Peak heights with partially replicated spectra} section above.

\subsubsection{Peak volumes with all spectra replicated}

With all spectra replicated and again using any integration methodology, the intensity errors can be calculated as described in the \quotecmd{Peak heights with all spectra replicated} section above.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.error\-\_analysis\-\_per\-\_field} \label{uf: spectrum.error_analysis_per_field}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Use spectrum IDs per each field strength for an error analysis for peak intensities.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]error\_analysis\_per\_field}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

Please see the spectrum.error\_analysis user function documentation.

This user function will collect all spectrum IDs for each field strength separately, and call the spectrum.error\_analysis with these.

This function is meant as a short-cut for the spectrum.error\_analysis function.

\subsubsection{Prompt examples}

To collect all spectrum IDs per field strength, and perform peak intensity error analysis:

\begin{lstlisting}[numbers=none]
relax> spectrum.error_analysis_per_field()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.integration\-\_points} \label{uf: spectrum.integration_points}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the number of summed points used in volume integration of a given spin in a spectrum.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]integration\_points}(\linebreak[0]N=\linebreak[0]None, spectrum\_id=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{N:}  The number of points used by the summation volume integration method.

\hspace{3 mm}\keyword{spectrum\_id:}  The spectrum ID string.

\hspace{3 mm}\keyword{spin\_id:}  Restrict setting the number to certain spins.


\subsubsection{Description}

For a complete description of which integration methods and how many points N are used for different integration techniques, please see the spectrum.error\_analysis user function documentation.

The spectrum ID identifies the spectrum associated with the value of N and must correspond to a previously loaded set of intensities.  If the spin ID is unset, then the number of summed points for all spins will be set to the supplied value.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.read\-\_intensities} \label{uf: spectrum.read_intensities}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} peak intensities from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]read\_intensities}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, spectrum\_id=\linebreak[0]None, dim=\linebreak[0]1, int\_method=\linebreak[0]`height', int\_col=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None, ncproc=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file or the list of files containing the intensity data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spectrum\_id:}  The unique spectrum ID string or list of strings to associate with the peak intensity values.  If multiple files are given, then each file should have a corresponding spectrum ID string.  If \quotecmd{auto} is provided for a NMRPipe\index{NMR} seriesTab formatted file, the IDs are auto generated in form of Z\_A\{i\}.

\hspace{3 mm}\keyword{dim:}  Associate the data with the spins of any dimension in the peak list.  This defaults to w1, the heteronucleus in HSQC type experiments.

\hspace{3 mm}\keyword{int\_method:}  The method by which peaks were integrated.

\hspace{3 mm}\keyword{int\_col:}  The optional column containing the peak intensity data (used by the generic intensity file format, or if the intensities are in a non-standard column).

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column used by the generic intensity file format (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{sep:}  The column separator used by the generic intensity format (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string used to restrict the loading of data to certain spin subsets.

\hspace{3 mm}\keyword{ncproc:}  The Bruker specific FID intensity scaling factor.


\subsubsection{Description}

The peak intensity can either be from peak heights or peak volumes.

The spectrum ID is a label which is subsequently utilised by other user functions.  If this identifier matches that of a previously loaded set of intensities, then this indicates a replicated spectrum.

The spectral dimension is used to specify if the intensity data should be loaded into the spins identified by the first dimension w1, second dimension w2, etc.

The integration method is required for the subsequent error analysis.  When peak heights are measured, this should be set to \quotecmd{height}.  Volume integration methods are a bit varied and hence two values are accepted.  If the volume integration involves pure point summation, with no deconvolution algorithms or other methods affecting peak heights, then the value should be set to \quotecmd{point sum}.  All other volume integration methods, e.g. line shape fitting, the value should be set to \quotecmd{other}.

If a series of intensities extracted from Bruker FID files processed in Topspin or XWinNMR are to be compared, the ncproc parameter may need to be supplied.  This is because this FID is stored using integer representation and is scaled using ncproc to avoid numerical truncation artifacts.  If two spectra have significantly different maximal intensities, then ncproc will be different for both.  The intensity scaling is binary, $i$.e. 2**ncproc. Therefore if spectrum A has an ncproc of 6 and and spectrum B a value of 7, then a reference intensity in B will be double that of A.  Internally, relax stores the intensities scaled by 2**ncproc.

\subsubsection{File formats}

The peak list or intensity file will be automatically determined.

Sparky\index{software!Sparky}\index{software!Sparky} peak list:  The file should be a Sparky\index{software!Sparky}\index{software!Sparky} peak list saved after typing the command \quotecmd{lt}.  The default is to assume that columns 0, 1, 2, and 3 (1$^{\mathrm{st}}$, 2$^{\mathrm{nd}}$, 3$^{\mathrm{rd}}$, and 4$^{\mathrm{th}}$) contain the Sparky\index{software!Sparky}\index{software!Sparky} assignment, w1, w2, and peak intensity data respectively.  The frequency data w1 and w2 are ignored while the peak intensity data can either be the peak height or volume displayed\index{display} by changing the window options.  If the peak intensity data is not within column 3, set the integration column to the appropriate number (column numbering starts from 0 rather than 1).

XEasy\index{software!XEasy} peak list:  The file should be the saved XEasy\index{software!XEasy} text window output of the list peak entries command, \quotecmd{tw} followed by \quotecmd{le}.  As the columns are fixed, the peak intensity column is hardwired to number 10 (the 11$^{\mathrm{th}}$ column) which contains either the peak height or peak volume data.  Because the columns are fixed, the integration column number will be ignored.

NMRView:\index{NMR}  The file should be a NMRView\index{NMR} peak list. The default is to use column 16 (which contains peak heights) for peak intensities. To use use peak volumes (or evolumes), int\_col must be set to 15.

NMRPipe\index{NMR} seriesTab:  The file should be a NMRPipe-format\index{NMR} Spectral Series list.  If the spectrum\_id=\quotecmd{auto}, the IDs are auto generated in form of Z\_A\{i\}.

Generic intensity file:  This is a generic format which can be created by scripting\index{scripting!script file}\index{scripting} to support non-supported peak lists.  It should contain in the first few columns enough information to identify the spin.  This can include columns for the molecule\index{molecule} name, residue number, residue name, spin number, and spin name.  Alternatively a spin ID string column can be used. The peak intensities can be placed in another column specified by the integration column number.  Intensities from multiple spectra can be placed into different columns, and these can then be specified simultaneously by setting the integration column value to a list of columns.  This list must be matched by setting the spectrum ID to a list of the same length.  If columns are delimited by a character other than whitespace, this can be specified with the column separator.  The spin ID can be used to restrict the loading to specific spin subsets.

\subsubsection{Multiple files}

The data from multiple files can be loaded simultaneously if a list of files is supplied.  In this case, a list of spectrum ID strings of equal length must be supplied.

\subsubsection{Prompt examples}

To read\index{read} the reference and saturated spectra peak heights from the Sparky\index{software!Sparky}\index{software!Sparky} formatted files \quotecmd{ref.list} and \quotecmd{sat.list}, type:

\begin{lstlisting}[numbers=none]
relax> spectrum.read_intensities(file='ref.list', spectrum_id='ref')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spectrum.read_intensities(file='sat.list', spectrum_id='sat')
\end{lstlisting}


To read\index{read} the reference and saturated spectra peak heights from the XEasy\index{software!XEasy} formatted files \quotecmd{ref.text} and \quotecmd{sat.text}, type:

\begin{lstlisting}[numbers=none]
relax> spectrum.read_intensities(file='ref.text', spectrum_id='ref')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spectrum.read_intensities(file='sat.text', spectrum_id='sat')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.read\-\_spins} \label{uf: spectrum.read_spins}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} peak assignments from a file and create spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]read\_spins}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, dim=\linebreak[0]1, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the file containing the intensity data.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{dim:}  Associate the data with the spins of any dimension in the peak list.  This defaults to w1, the heteronucleus in HSQC type experiments.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column used by the generic intensity file format (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column used by the generic intensity file format (alternative to the spin ID column).

\hspace{3 mm}\keyword{sep:}  The column separator used by the generic intensity format (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string used to restrict the loading of data to certain spin subsets.


\subsubsection{Description}

The spectral dimension is used to specify if the intensity data should be loaded into the spins identified by the first dimension w1, second dimension w2, etc.

\subsubsection{File formats}

The peak list or intensity file will be automatically determined.

Sparky\index{software!Sparky}\index{software!Sparky} peak list:  The file should be a Sparky\index{software!Sparky}\index{software!Sparky} peak list saved after typing the command \quotecmd{lt}.  The default is to assume that columns 0, 1, 2, and 3 (1$^{\mathrm{st}}$, 2$^{\mathrm{nd}}$, 3$^{\mathrm{rd}}$, and 4$^{\mathrm{th}}$) contain the Sparky\index{software!Sparky}\index{software!Sparky} assignment, w1, w2, and peak intensity data respectively.  The frequency data w1 and w2 are ignored while the peak intensity data can either be the peak height or volume displayed\index{display} by changing the window options.  If the peak intensity data is not within column 3, set the integration column to the appropriate number (column numbering starts from 0 rather than 1).

XEasy\index{software!XEasy} peak list:  The file should be the saved XEasy\index{software!XEasy} text window output of the list peak entries command, \quotecmd{tw} followed by \quotecmd{le}.  As the columns are fixed, the peak intensity column is hardwired to number 10 (the 11$^{\mathrm{th}}$ column) which contains either the peak height or peak volume data.  Because the columns are fixed, the integration column number will be ignored.

NMRView:\index{NMR}  The file should be a NMRView\index{NMR} peak list. The default is to use column 16 (which contains peak heights) for peak intensities. To use use peak volumes (or evolumes), int\_col must be set to 15.

NMRPipe\index{NMR} seriesTab:  The file should be a NMRPipe-format\index{NMR} Spectral Series list.  If the spectrum\_id=\quotecmd{auto}, the IDs are auto generated in form of Z\_A\{i\}.

Generic intensity file:  This is a generic format which can be created by scripting\index{scripting!script file}\index{scripting} to support non-supported peak lists.  It should contain in the first few columns enough information to identify the spin.  This can include columns for the molecule\index{molecule} name, residue number, residue name, spin number, and spin name.  Alternatively a spin ID string column can be used. The peak intensities can be placed in another column specified by the integration column number.  Intensities from multiple spectra can be placed into different columns, and these can then be specified simultaneously by setting the integration column value to a list of columns.  This list must be matched by setting the spectrum ID to a list of the same length.  If columns are delimited by a character other than whitespace, this can be specified with the column separator.  The spin ID can be used to restrict the loading to specific spin subsets.

\subsubsection{Prompt examples}

To read\index{read} the spin assignments from the Sparky\index{software!Sparky}\index{software!Sparky} formatted files \quotecmd{ref.list} and \quotecmd{sat.list}, type:

\begin{lstlisting}[numbers=none]
relax> spectrum.read_spins(file='ref.list')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spectrum.read_spins(file='sat.list')
\end{lstlisting}


To read\index{read} the spin assignments from the XEasy\index{software!XEasy} formatted files \quotecmd{ref.text} and \quotecmd{sat.text}, type:

\begin{lstlisting}[numbers=none]
relax> spectrum.read_spins(file='ref.text')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spectrum.read_spins(file='sat.text')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.replicated} \label{uf: spectrum.replicated}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Specify which spectra are replicates of each other.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]replicated}(\linebreak[0]spectrum\_ids=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spectrum\_ids:}  The list of replicated spectra ID strings.


\subsubsection{Description}

This is used to identify which of the loaded spectra are replicates of each other.  Specifying the replicates is essential for error analysis if the baseplane RMSD has not been supplied.

\subsubsection{Prompt examples}

To specify that the NOE spectra labelled \quotecmd{ref1}, \quotecmd{ref2}, and \quotecmd{ref3} are the same spectrum replicated, type one of:

\begin{lstlisting}[numbers=none]
relax> spectrum.replicated(['ref1', 'ref2', 'ref3'])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spectrum.replicated(spectrum_ids=['ref1', 'ref2', 'ref3'])
\end{lstlisting}


To specify that the two R$_2$ spectra \quotecmd{ncyc2} and \quotecmd{ncyc2$b$} are the same time point, type:

\begin{lstlisting}[numbers=none]
relax> spectrum.replicated(['ncyc2', 'ncyc2b'])
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spectrum\-.sn\-\_ratio} \label{uf: spectrum.sn_ratio}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/fid}

\subsubsection{Synopsis}

Calculate the signal to noise ratio for all selected spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spectrum.\linebreak[0]sn\_ratio}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This user function will per spin calculate the signal to noise ratio: S/N.

\subsubsection{Prompt examples}

To calculate the Signal to Noise ratio per spin.

\begin{lstlisting}[numbers=none]
relax> spectrum.sn_ratio()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.copy} \label{uf: spin.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} all data associated with a spin.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, spin\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, spin\_to=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The data pipe containing the spin from which the data will be copied.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{spin\_from:}  The spin identifier string of the spin to copy\index{copy} the data from.

\hspace{3 mm}\keyword{pipe\_to:}  The data pipe to copy\index{copy} the data to.  This defaults to the current data pipe.

\hspace{3 mm}\keyword{spin\_to:}  The spin identifier string of the spin to copy\index{copy} the data to.  If left blank, the new spin will have the same name as the old.


\subsubsection{Description}

This will copy\index{copy} all the data associated with the identified spin to the new, non-existent spin.  The new spin must not already exist.

\subsubsection{Prompt examples}

To copy\index{copy} the spin data from spin 1 to the new spin 2, type:

\begin{lstlisting}[numbers=none]
relax> spin.copy(spin_from='@1', spin_to='@2')
\end{lstlisting}


To copy\index{copy} spin 1 of the molecule\index{molecule} \quotecmd{Old mol} to spin 5 of the molecule\index{molecule} \quotecmd{New mol}, type:

\begin{lstlisting}[numbers=none]
relax> spin.copy(spin_from='#Old mol@1', spin_to='#New mol@5')
\end{lstlisting}


To copy\index{copy} the spin data of spin 1 from the data pipe \quotecmd{m1} to \quotecmd{m2}, assuming the current data pipe is \quotecmd{m1}, type:

\begin{lstlisting}[numbers=none]
relax> spin.copy(spin_from='@1', pipe_to='m2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.copy(pipe_from='m1', spin_from='@1', pipe_to='m2', spin_to='@1')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.create} \label{uf: spin.create}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a new spin.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]create}(\linebreak[0]spin\_name=\linebreak[0]None, spin\_num=\linebreak[0]None, res\_name=\linebreak[0]None, res\_num=\linebreak[0]None, mol\_name=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_name:}  The name of the spin.

\hspace{3 mm}\keyword{spin\_num:}  The spin number.

\hspace{3 mm}\keyword{res\_name:}  The name of the residue to add the spin to.

\hspace{3 mm}\keyword{res\_num:}  The number of the residue to add the spin to.

\hspace{3 mm}\keyword{mol\_name:}  The name of the molecule\index{molecule} to add the spin to.


\subsubsection{Description}

This will add a new spin data container to the relax data storage object.  The same spin number cannot be used more than once.

\subsubsection{Prompt examples}

The following sequence\index{sequence} of commands will add the spins 1 C4, 2 C9, 3 C15 to residue number 10:

\begin{lstlisting}[numbers=none]
relax> spin.create('C4',  1, res_num=10)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.create('C9',  2, res_num=10)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.create('C15', 3, res_num=10)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.create\-\_pseudo} \label{uf: spin.create_pseudo}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a spin system representing a pseudo-atom.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]create\_pseudo}(\linebreak[0]spin\_name=\linebreak[0]None, spin\_num=\linebreak[0]None, res\_id=\linebreak[0]None, members=\linebreak[0]None, averaging=\linebreak[0]`linear')}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_name:}  The name of the pseudo-atom spin.

\hspace{3 mm}\keyword{spin\_num:}  The spin number.

\hspace{3 mm}\keyword{res\_id:}  The molecule\index{molecule} and residue ID string identifying the position to add the pseudo-spin to.

\hspace{3 mm}\keyword{members:}  A list of the atoms (as spin ID strings) that the pseudo-atom is composed of.

\hspace{3 mm}\keyword{averaging:}  The positional averaging technique.


\subsubsection{Description}

This will create a spin data container representing a number of pre-existing spin containers as a pseudo-atom.  The optional spin number must not already exist.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The following will create the pseudo-atom named \quotecmd{Q9} consisting of the protons \quotecmd{@H16}, \quotecmd{@H17}, \quotecmd{@H18}:

\begin{lstlisting}[numbers=none]
relax> spin.create_pseudo('Q9', members=['@H16', '@H17', '@H18'])
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.delete} \label{uf: spin.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]delete}(\linebreak[0]spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin identifier string.


\subsubsection{Description}

This can be used to delete\index{delete} a single or sets of spins.  See the identification string documentation below for more information.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.display} \label{uf: spin.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} information about the spin(s).


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]display}(\linebreak[0]spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.


\subsubsection{Description}

This will display\index{display} the spin data loaded into the current data pipe.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.element} \label{uf: spin.element}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Set the element type of the spin.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]element}(\linebreak[0]element=\linebreak[0]None, spin\_id=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{element:}  The IUPAC element name.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string corresponding to one or more spins.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the element to be changed.


\subsubsection{Description}

This allows the element type of the spins to be set.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The set all spins of residue 1 to be carbons, type one of:

\begin{lstlisting}[numbers=none]
relax> spin.element('@1', 'C', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.element(spin_id='@1', element='C', force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.isotope} \label{uf: spin.isotope}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/nuclear_symbol}

\subsubsection{Synopsis}

Set the spins' nuclear isotope type.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]isotope}(\linebreak[0]isotope=\linebreak[0]None, spin\_id=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{isotope:}  The nuclear isotope name in the AE notation - the atomic mass number followed by the element symbol.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string corresponding to one or more spins.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the nuclear isotope to be changed.


\subsubsection{Description}

This allows the nuclear isotope type of the spins to be set.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The set all spins of residue 1 to the \quotecmd{13C} nuclear isotope, type one of:

\begin{lstlisting}[numbers=none]
relax> spin.isotope('@1', '13C', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.isotope(spin_id='@1', isotope='13C', force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.name} \label{uf: spin.name}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Name the spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]name}(\linebreak[0]name=\linebreak[0]None, spin\_id=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{name:}  The new name.

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string corresponding to one or more spins.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the spin to be renamed.


\subsubsection{Description}

This simply allows spins to be named (or renamed).  Spin naming often essential.  For example when reading\index{read} Sparky\index{software!Sparky}\index{software!Sparky} peak list files, then the spin name must match that in the file.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The following sequence\index{sequence} of commands will rename the sequence\index{sequence} \{1 C1, 2 C2, 3 C3\} to \{1 C11, 2 C12, 3 C13\}:

\begin{lstlisting}[numbers=none]
relax> spin.name('@1', 'C11', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.name('@2', 'C12', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.name('@3', 'C13', force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{spin\-.number} \label{uf: spin.number}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/edit-rename}

\subsubsection{Synopsis}

Number the spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{spin.\linebreak[0]number}(\linebreak[0]spin\_id=\linebreak[0]None, number=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string corresponding to a single spin.

\hspace{3 mm}\keyword{number:}  The new spin number.

\hspace{3 mm}\keyword{force:}  A flag which if True will cause the spin to be renumbered.


\subsubsection{Description}

This simply allows spins to be numbered.  The new number cannot correspond to an existing spin number.

\subsubsection{Spin ID string documentation}

The identification string is composed of three components: the molecule\index{molecule} ID token beginning with the \quotecmd{\#} character, the residue ID token beginning with the \quotecmd{:} character, and the atom or spin system ID token beginning with the \quotecmd{@} character.  Each token can be composed of multiple elements - one per spin - separated by the \quotecmd{,} character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the \quotecmd{-} character.  Negative numbers are supported.  The full ID string specification is \quotecmd{\#<mol\_name> :<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[, <atom\_id>, ...]]}, where the token elements are \quotecmd{<mol\_name>}, the name of the molecule,\index{molecule} \quotecmd{<res\_id>}, the residue identifier which can be a number, name, or range of numbers, \quotecmd{<atom\_id>}, the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match.  For example if the string does not contain the \quotecmd{\#} character then all molecules\index{molecule} will match the string.  If only the molecule\index{molecule} ID component is specified, then all spins of the molecule\index{molecule} will match.

Regular\index{regular expression} expression can be used to select spins.  For example the string \quotecmd{@H*} will select the protons \quotecmd{H}, \quotecmd{H2}, \quotecmd{H98}.

\subsubsection{Prompt examples}

The following sequence\index{sequence} of commands will renumber the sequence\index{sequence} \{1 C1, 2 C2, 3 C3\} to \{-1 C1, -2 C2, -3 C3\}:

\begin{lstlisting}[numbers=none]
relax> spin.number('@1', -1, force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.number('@2', -2, force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> spin.number('@3', -3, force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{state\-.load} \label{uf: state.load}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Load a saved program state.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{state.\linebreak[0]load}(\linebreak[0]state=\linebreak[0]`state.\linebreak[0]bz2', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{state:}  The file name, which can be a string or a file descriptor object, of a saved program state.

\hspace{3 mm}\keyword{dir:}  The name of the directory in which the file is found.

\hspace{3 mm}\keyword{force:}  A boolean flag which if True will cause the current program state to be overwritten.


\subsubsection{Description}

This is able to handle uncompressed,\index{compression!uncompressed} bzip2\index{compression!bzip2} compressed files, or gzip\index{compression!gzip} compressed files automatically.  The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with \quotecmd{.bz2} appended followed by the file name with \quotecmd{.gz} appended.

For more advanced users, file descriptor objects are supported.  If the force flag is set to True, then the relax data store will be reset prior to the loading of the saved state.

\subsubsection{Prompt examples}

The following commands will load the state saved in the file \quotecmd{save}.

\begin{lstlisting}[numbers=none]
relax> state.load('save')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.load(state='save')
\end{lstlisting}


Use one of the following commands to load the state saved in the bzip2\index{compression!bzip2} compressed file \quotecmd{save.bz2}:

\begin{lstlisting}[numbers=none]
relax> state.load('save')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.load(state='save')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.load('save.bz2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.load(state='save.bz2', force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{state\-.save} \label{uf: state.save}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/relax} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Save the program state.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{state.\linebreak[0]save}(\linebreak[0]state=\linebreak[0]`state.\linebreak[0]bz2', dir=\linebreak[0]None, compress\_type=\linebreak[0]1, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{state:}  The file name, which can be a string or a file descriptor object, to save the current program state in.

\hspace{3 mm}\keyword{dir:}  The name of the directory in which to place the file.

\hspace{3 mm}\keyword{compress\_type:}  The type of compression\index{compression} to use when creating the file.

\hspace{3 mm}\keyword{force:}  A boolean flag which if set to True will cause the file to be overwritten.


\subsubsection{Description}

This will place the program state - the relax data store - into a file for later reloading or reference.  The default format is an XML formatted file.

The default behaviour of this function is to compress the file using bzip2\index{compression!bzip2} compression.\index{compression}  If the extension \quotecmd{.bz2} is not included in the file name, it will be added.  The compression\index{compression} can, however, be changed to either no compression\index{compression} or gzip\index{compression!gzip} compression.\index{compression}  This is controlled by the compression\index{compression} type which can be set to

\begin{description}
  \item[0 --] No compression\index{compression} (no file extension).
  \item[1 --] bzip2\index{compression!bzip2} compression\index{compression} (\quotecmd{.bz2} file extension).
  \item[2 --] gzip\index{compression!gzip} compression\index{compression} (\quotecmd{.gz} file extension).
\end{description}

\subsubsection{Prompt examples}

The following commands will save the current program state, uncompressed,\index{compression!uncompressed} into the file \quotecmd{save}:

\begin{lstlisting}[numbers=none]
relax> state.save('save', compress_type=0)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.save(state='save', compress_type=0)
\end{lstlisting}


The following commands will save the current program state into the bzip2\index{compression!bzip2} compressed file \quotecmd{save.bz2}:

\begin{lstlisting}[numbers=none]
relax> state.save('save')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.save(state='save')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.save('save.bz2')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.save(state='save.bz2')
\end{lstlisting}


If the file \quotecmd{save} already exists, the following commands will save the current program state by overwriting the file.

\begin{lstlisting}[numbers=none]
relax> state.save('save', force=True)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> state.save(state='save', force=True)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{statistics\-.aic} \label{uf: statistics.aic}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/office-chart-pie} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/discrepancy_curve}

\subsubsection{Synopsis}

Calculate and store Akaike's Information Criterion (AIC) for each model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{statistics.\linebreak[0]aic}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will perform a calculation to obtain the chi-squared\index{chi-squared} statistic for the current parameter values for each model, count the number of parameters per model and calculate Akaike's Information Criterion (AIC) using the formula AIC\index{model selection!AIC} = chi2 + 2$k$.  The AIC\index{model selection!AIC} values, chi-squared\index{chi-squared} values, and number of parameters will be stored in the appropriate location for the model in the relax data store.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{statistics\-.model} \label{uf: statistics.model}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/office-chart-pie} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate and store the model statistics.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{statistics.\linebreak[0]model}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will perform a back-calculation to obtain the chi-squared\index{chi-squared} statistic for the current parameter values, count the number of parameters and data points per model, and place all the values in the relax data store.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.add\-\_atom} \label{uf: structure.add_atom}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Add an atom.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]add\_atom}(\linebreak[0]mol\_name=\linebreak[0]None, atom\_name=\linebreak[0]None, res\_name=\linebreak[0]None, res\_num=\linebreak[0]None, pos=\linebreak[0]None, element=\linebreak[0]None, atom\_num=\linebreak[0]None, chain\_id=\linebreak[0]None, segment\_id=\linebreak[0]None, pdb\_record=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{mol\_name:}  The name of molecule\index{molecule} container to create or add the atom to.

\hspace{3 mm}\keyword{atom\_name:}  The atom name.

\hspace{3 mm}\keyword{res\_name:}  The residue name.

\hspace{3 mm}\keyword{res\_num:}  The residue number.

\hspace{3 mm}\keyword{pos:}  The atomic coordinates.  For specifying different coordinates for each model of the ensemble, a list of lists can be supplied.

\hspace{3 mm}\keyword{element:}  The element name.

\hspace{3 mm}\keyword{atom\_num:}  The optional atom number.

\hspace{3 mm}\keyword{chain\_id:}  The optional chain ID string.

\hspace{3 mm}\keyword{segment\_id:}  The optional segment ID string.

\hspace{3 mm}\keyword{pdb\_record:}  The optional PDB\index{PDB} record name, e.g. \quotecmd{ATOM} or \quotecmd{HETATM}.


\subsubsection{Description}

This allows atoms to be added to the internal structural object.  To use the same atomic coordinates for all models, the atomic position can be an array of 3 values.  Alternatively different coordinates can be used for each model if the atomic position is a rank-2 array where the first dimension matches the number of models currently present.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.add\-\_model} \label{uf: structure.add_model}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Add a new model.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]add\_model}(\linebreak[0]model\_num=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model\_num:}  The number of the new model.


\subsubsection{Description}

This allows new models to be added to the internal structural object.  Note that no structural information is allowed to be present.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.atomic\-\_fluctuations} \label{uf: structure.atomic_fluctuations}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Create an interatomic distance fluctuation correlation matrix.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]atomic\_fluctuations}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None, measure=\linebreak[0]`distance', file=\linebreak[0]None, format=\linebreak[0]`text', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to generate the interatomic distance fluctuation correlation matrix for.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to generate the interatomic distance fluctuation correlation matrix for.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to generate the interatomic distance fluctuation correlation matrix for.  This allows differently named molecules\index{molecule} in the same or different data pipes to be superimposed.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.  This can be used to restrict the correlation matrix to one atom per residue, for example.

\hspace{3 mm}\keyword{measure:}  The type of fluctuation to investigate.  This allows for both interatomic distance and vector angle\index{angles} fluctuations to be calculated.

\hspace{3 mm}\keyword{file:}  The name of the text file to create.

\hspace{3 mm}\keyword{format:}  The output format.  For all formats other than the text file, a second file will be created with the same name as the text file but with the appropriate file extension added.

\hspace{3 mm}\keyword{dir:}  The directory to save the file to.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause any pre-existing files to be overwritten.


\subsubsection{Description}

This is used to visualise the interatomic fluctuations between different structures.  By setting the measure argument, different categories of fluctuations can seen:

\begin{description}
  \item[\quotecmd{distance} --] The interatomic distance fluctuations is the default option.  The corrected sample standard deviation (SD) is calculated for the distances between all atom pairs, resulting in a pairwise matrix of SD values.  This is frame independent and hence is superimposition independent.
  \item[\quotecmd{angle} --] The interatomic vector angle\index{angles} fluctuations.  The corrected sample standard deviation (SD) is calculated for the angles\index{angles} between the inter atom vectors all atom pairs to an average vector.  This also produces a pairwise matrix of SD values.
  \item[\quotecmd{parallax shift} --] The interatomic parallax shift fluctuations.  The corrected sample standard deviation (SD) is calculated for the parallax shift between the inter atom vectors all atom pairs to an average vector.  This also produces a pairwise matrix of SD values.  The parallax shift is calculated as the dot product of the interatomic vector and the unit average vector, times the unit average vector.  It is a frame and superimposition dependent measure close to orthogonal to the interatomic distance fluctuations.  It is similar to the angle\index{angles} measure however, importantly, it is independent of the distance between the two atoms.
\end{description}

For the output file, the currently supported formats are:

\begin{description}
  \item[\quotecmd{text} --] This is the default value and will result in a single text file being created.
  \item[\quotecmd{gnuplot} --] This will create a both a text file with the data and a script\index{scripting!script file} for visualising the correlation matrix using gnuplot.  The script\index{scripting!script file} will have the same name as the text file, however the file extension will be changed to *.gnu.
\end{description}

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

The atom ID string, which uses the same notation as the spin ID, can be used to restrict the coordinates compared to a subset of molecules,\index{molecule} residues, or atoms.  For example to only use backbone heavy atoms in a protein, set the atom ID to \quotecmd{@N,C,CA,O}, assuming those are the names of the atoms in the 3D structural file.

\subsubsection{Prompt examples}

To create the interatomic distance fluctuation correlation matrix for the models 1, 3, and 5, type:

\begin{lstlisting}[numbers=none]
relax> structure.atomic_fluctuations(models=[[1, 3, 5]], file='atomic_fluctuation_matrix')
\end{lstlisting}


To create the interatomic distance fluctuation correlation matrix for the molecules\index{molecule} \quotecmd{A}, \quotecmd{B}, \quotecmd{C}, and \quotecmd{D}, type:

\begin{lstlisting}[numbers=none]
relax> structure.atomic_fluctuations(molecules=[['A', 'B', 'C', 'D']], file='atomic_fluctuation_matrix')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.com} \label{uf: structure.com}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Calculate the centre of mass (CoM) for all structures.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]com}(\linebreak[0]model=\linebreak[0]None, atom\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{model:}  The optional structural model number to restrict the calculation of the centre of mass to.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string to restrict the CoM calculation to.


\subsubsection{Description}

This user function will calculate the centre of mass (CoM) for all loaded structures, printing out the position and storing it in the current data pipe.

\subsubsection{Prompt examples}

To determine the centre of mass of all structure, simply type:

\begin{lstlisting}[numbers=none]
relax> structure.com()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.connect\-\_atom} \label{uf: structure.connect_atom}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Connect two atoms.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]connect\_atom}(\linebreak[0]index1=\linebreak[0]None, index2=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{index1:}  The global index of the first atom.

\hspace{3 mm}\keyword{index2:}  The global index of the second atom.


\subsubsection{Description}

This allows atoms to be connected in the internal structural object.  The global index is normally equal to the PDB\index{PDB} atom number minus 1.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.create\-\_diff\-\_tensor\-\_pdb} \label{uf: structure.create_diff_tensor_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a PDB\index{PDB} file to represent the diffusion\index{diffusion!tensor} tensor.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]create\_diff\_tensor\_pdb}(\linebreak[0]scale=\linebreak[0]1.8e-06, file=\linebreak[0]`tensor.\linebreak[0]pdb', dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{scale:}  Value for scaling the diffusion rates.

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory to place the file into.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will overwrite the any pre-existing file.


\subsubsection{Description}

This creates a PDB\index{PDB} file containing an artificial geometric structure to represent the diffusion\index{diffusion!tensor} tensor.  A structure must have previously been read\index{read} into relax.  The diffusion\index{diffusion!tensor} tensor is represented by an ellipsoidal,\index{diffusion!ellipsoid (asymmetric)} spheroidal,\index{diffusion!spheroid (axially symmetric)} or spherical geometric object with its origin located at the centre of mass (of the selected residues).  This diffusion\index{diffusion!tensor} tensor PDB\index{PDB} file can subsequently read\index{read} into any molecular viewer.

There are four different types of residue within the PDB.\index{PDB}  The centre of mass of the selected residues is represented as a single carbon atom of the residue \quotecmd{COM}.  The ellipsoidal\index{diffusion!ellipsoid (asymmetric)} geometric shape consists of numerous H atoms of the residue \quotecmd{TNS}.  The axes of the tensor, when defined, are presented as the residue \quotecmd{AXS} and consist of carbon atoms: one at the centre of mass and one at the end of each eigenvector.  Finally, if Monte Carlo simulations were run and the diffusion\index{diffusion!tensor} tensor parameters were allowed to vary then there will be multiple \quotecmd{SIM} residues, one for each simulation.  These are essentially the same as the \quotecmd{AXS} residue, representing the axes of the simulated tensors, and they will appear as a distribution.

As the Brownian\index{diffusion!Brownian} rotational\index{rotation} diffusion\index{diffusion!tensor} tensor is a measure of the rate of rotation\index{rotation} about different axes - the larger the geometric object, the faster the diffusion of a molecule.\index{molecule}  For example the diffusion\index{diffusion!tensor} tensor of a water molecule\index{molecule} is much larger than that of a macromolecule.

The effective global correlation\index{correlation time} time experienced by an XH bond vector, not to be confused with the Lipari and Szabo parameter $\tau$\_e, will be approximately proportional to the component of the diffusion\index{diffusion!tensor} tensor parallel to it.  The approximation is not exact due to the multiexponential form of the correlation function of Brownian\index{diffusion!Brownian} rotational\index{rotation} diffusion.  If an XH bond vector is parallel to the longest axis of the tensor, it will be unaffected by rotations\index{rotation} about that axis, which are the fastest rotations\index{rotation} of the molecule,\index{molecule} and therefore its effective global correlation\index{correlation time} time will be maximal.

To set the size of the diffusion\index{diffusion!tensor} tensor within the PDB\index{PDB} frame the unit vectors used to generate the geometric object are first multiplied by the diffusion\index{diffusion!tensor} tensor (which has the units of inverse seconds) then by the scaling factor (which has the units of second \AA and has the default value of 1.8e-6 s.Angstrom).  Therefore the rotational\index{rotation} diffusion rate per \AA is equal the inverse of the scale value (which defaults to 5.56e5 s\^{}-1.Angstrom\^{}-1).  Using the default scaling value for spherical diffusion, the correspondence between global correlation\index{correlation time} time, $\Diff_{iso}$ diffusion rate, and the radius of the sphere\index{diffusion!sphere (isotropic)} for a number of discrete cases will be:

Please see Table~\ref{table: diff tensor PDB scaling} on page~\pageref{table: diff tensor PDB scaling}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Diffusion tensor PDB scaling.]{Diffusion tensor PDB representation sizes using the default scaling for different diffusion tensors}
\begin{tabular}{lll}
\\[-5pt]
\toprule
$\tau_m$ (ns) & $\Diff_{iso}$ (s\^{}-1) & Radius (\AA) \\
\midrule
1 & 1.67e8 & 300 \\
3 & 5.56e7 & 100 \\
10 & 1.67e7 & 30 \\
30 & 5.56e6 & 10 \\
\bottomrule
\\[-5pt]
\label{table: diff tensor PDB scaling}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


The scaling value has been fixed to facilitate comparisons within or between publications, but can be changed to vary the size of the tensor geometric object if necessary.  Reporting the rotational\index{rotation} diffusion rate per \AA within figure legends would be useful.

To create the tensor PDB\index{PDB} representation, a number of algorithms are utilised.  Firstly the centre of mass is calculated for the selected residues and is represented in the PDB\index{PDB} by a C atom.  Then the axes of the diffusion are calculated, as unit vectors scaled to the appropriate length (multiplied by the eigenvalue\index{eigenvalues} $\Diff_x$, $\Diff_y$, $\Diff_z$, $\Diff_\Par$, $\Diff_\Per$, or $\Diff_{iso}$ as well as the scale value), and a C atom placed at the position of this vector plus the centre of mass.  Finally a uniform distribution of vectors on a sphere\index{diffusion!sphere (isotropic)} is generated using spherical coordinates.  By incrementing the polar angle\index{angles} using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle\index{angles} evenly creates the longitudinal vectors.  These unit vectors, which are distributed within the PDB\index{PDB} frame and are of 1 \AA in length, are first rotated into the diffusion frame using a rotation\index{rotation} matrix (the spherical diffusion\index{diffusion!tensor} tensor is not rotated).  Then they are multiplied by the diffusion\index{diffusion!tensor} tensor matrix to extend the vector out to the correct length, and finally multiplied by the scale value so that the vectors reasonably superimpose onto the macromolecular structure.  The last set of algorithms place all this information into a PDB\index{PDB} file.  The distribution of vectors are represented by H atoms and are all connected using PDB\index{PDB} CONECT records.  Each H atom is connected to its two neighbours on the both the longitude and latitude.  This creates a geometric PDB\index{PDB} object with longitudinal and latitudinal lines.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.create\-\_rotor\-\_pdb} \label{uf: structure.create_rotor_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a PDB\index{PDB} file representation of a rotor.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]create\_rotor\_pdb}(\linebreak[0]file=\linebreak[0]`rotor.\linebreak[0]pdb', dir=\linebreak[0]None, rotor\_angle=\linebreak[0]0.0, axis=\linebreak[0]None, axis\_pt=\linebreak[0]None, centre=\linebreak[0]None, span=\linebreak[0]2e-09, blade\_length=\linebreak[0]5e-10, force=\linebreak[0]False, staggered=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory to place the file into.

\hspace{3 mm}\keyword{rotor\_angle:}  The angle\index{angles} of the rotor motion in degrees.

\hspace{3 mm}\keyword{axis:}  The vector defining the rotor axis.

\hspace{3 mm}\keyword{axis\_pt:}  A point lying anywhere on the rotor axis.  This is used to define the position of the axis in 3D space.

\hspace{3 mm}\keyword{centre:}  The central point of the representation.  If this point is not on the rotor axis, then the closest point on the axis will be used for the centre.

\hspace{3 mm}\keyword{span:}  The distance from the central point to the rotor blades (meters).

\hspace{3 mm}\keyword{blade\_length:}  The length of the representative rotor blades.

\hspace{3 mm}\keyword{force:}  A flag which if True will overwrite the file if it already exists.

\hspace{3 mm}\keyword{staggered:}  A flag which if True will cause the rotor blades to be staggered.  This is used to avoid blade overlap.


\subsubsection{Description}

This creates a PDB\index{PDB} file representation of a rotor motional model.  The model axis is defined by a vector and a single point on the axis.  The centre of the representation will be taken as the point on the rotor axis closest to the given centre position.  The size of the representation is defined by the span, which is the distance from the central point to the rotors, and the length of the blades.

\subsubsection{Prompt examples}

The following is a synthetic example:

\begin{lstlisting}[numbers=none]
relax> structure.create_rotor_pdb(file='rotor.pdb', rotor_angle=20.0, axis=[0., 0., 1.], axis_pt=[1., 1., 0.], centre=[0., 0., 2.], span=2e-9, blade_length=1e-9)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.create\-\_vector\-\_dist} \label{uf: structure.create_vector_dist}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add-relax-blue}

\subsubsection{Synopsis}

Create a PDB\index{PDB} file representation of the distribution of XH bond vectors.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]create\_vector\_dist}(\linebreak[0]length=\linebreak[0]2e-09, file=\linebreak[0]`XH\_dist.\linebreak[0]pdb', dir=\linebreak[0]None, symmetry=\linebreak[0]True, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{length:}  The length of the vectors in the PDB\index{PDB} representation (meters).

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory to place the file into.

\hspace{3 mm}\keyword{symmetry:}  A flag which if True will create a second chain with reversed XH bond orientations.

\hspace{3 mm}\keyword{force:}  A flag which if True will overwrite the file if it already exists.


\subsubsection{Description}

This creates a PDB\index{PDB} file containing an artificial vectors, the length of which default to 20 \AA.  A structure must have previously been read\index{read} into relax.  The origin of the vector distribution is located at the centre of mass (of the selected residues).  This vector distribution PDB\index{PDB} file can subsequently be read\index{read} into any molecular viewer.

Because of the symmetry of the diffusion\index{diffusion!tensor} tensor reversing the orientation of the XH bond vector has no effect.  Therefore by setting the symmetry flag two chains \quotecmd{A} and \quotecmd{B} will be added to the PDB\index{PDB} file whereby chain \quotecmd{B} is chain \quotecmd{A} with the XH bonds reversed.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.delete} \label{uf: structure.delete}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-remove}

\subsubsection{Synopsis}

Delete\index{delete} structural information.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]delete}(\linebreak[0]atom\_id=\linebreak[0]None, model=\linebreak[0]None, verbosity=\linebreak[0]1, spin\_info=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string.

\hspace{3 mm}\keyword{model:}  Individual structural models from a loaded ensemble can be deleted\index{delete} by specifying the model number.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.  Set to zero to silence the user function, or one to see all messages.

\hspace{3 mm}\keyword{spin\_info:}  A flag which if True will cause all structural information in the spin containers and interatomic data containers to be deleted\index{delete} as well.  If False, then only the 3D structural data will be deleted.\index{delete}


\subsubsection{Description}

This will delete\index{delete} structural information from the current data pipe.  All spin and sequence\index{sequence} information loaded from these structures will be preserved - this only affects the structural data.  The atom ID argument can be used to restrict deletion to parts of the loaded molecules,\index{molecule} or the model argument can be used to delete\index{delete} individual structural models from an ensemble.

\subsubsection{Prompt examples}

To delete\index{delete} everything, simply type:

\begin{lstlisting}[numbers=none]
relax> structure.delete()
\end{lstlisting}


To delete\index{delete} residues 50 to 100 of the molecule\index{molecule} called \quotecmd{Ap4Aase}, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.delete(':50-100')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.delete(atom_id=':50-100')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.displacement} \label{uf: structure.displacement}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Determine the rotational\index{rotation} and translational displacement between a set of models or molecules.\index{molecule}


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]displacement}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None, centroid=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to determine the displacements for.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to determine the displacements for.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to determine the displacements for.  This allows differently named molecules\index{molecule} in the same or different data pipes to be superimposed.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.

\hspace{3 mm}\keyword{centroid:}  The alternative position of the centroid.


\subsubsection{Description}

This user function allows the rotational\index{rotation} and translational displacement between different models or molecules\index{molecule} to be calculated.  The information will be printed out in various formats and held in the relax data store.  This is directional, so there is a starting and ending position for each displacement.  Therefore the displacements in all directions between all models and molecules\index{molecule} will be calculated.

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

The atom ID string, which uses the same notation as the spin ID, can be used to restrict the coordinates compared to a subset of molecules,\index{molecule} residues, or atoms.  For example to only use backbone heavy atoms in a protein, set the atom ID to \quotecmd{@N,C,CA,O}, assuming those are the names of the atoms in the 3D structural file.

By supplying the position of the centroid, an alternative position than the standard rigid body centre is used as the focal point of the motion.  The allows, for example, a pivot of a rotational\index{rotation} domain motion to be specified.  This is not a formally correct algorithm, all translations will be zero, but does give an indication to the amplitude of the pivoting angle.\index{angles}

\subsubsection{Prompt examples}

To determine the rotational\index{rotation} and translational displacements between all sets of models, type:

\begin{lstlisting}[numbers=none]
relax> structure.displacement()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.find\-\_pivot} \label{uf: structure.find_pivot}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Find the pivot point of the motion of a set of structures.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]find\_pivot}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None, init\_pos=\linebreak[0]None, func\_tol=\linebreak[0]1e-05, box\_limit=\linebreak[0]200)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to use in the motional pivot algorithm.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to use in the motional pivot algorithm.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to use in the motional pivot algorithm.  This allows differently named molecules\index{molecule} in the same or different data pipes to be used.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.

\hspace{3 mm}\keyword{init\_pos:}  The initial position of the pivot.

\hspace{3 mm}\keyword{func\_tol:}  The function tolerance.  This is used to terminate minimisation\index{optimisation} once the function value between iterations is less than the tolerance.  The default value is 1e-5.

\hspace{3 mm}\keyword{box\_limit:}  The pivot point is constrained withing a box of +/- $x$ \AA the using the logarithmic barrier function together with simplex\index{optimisation!algorithm!Nelder-Mead simplex} optimisation.  This argument is the value of $x$.


\subsubsection{Description}

This is used to find pivot point of motion between a set of structural models.  If the list of models is not supplied, then all models will be used.

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

The atom ID string, which uses the same notation as the spin ID, can be used to restrict the coordinates compared to a subset of molecules,\index{molecule} residues, or atoms.  For example to only use backbone heavy atoms in a protein, set the atom ID to \quotecmd{@N,C,CA,O}, assuming those are the names of the atoms in the 3D structural file.

By supplying the position of the centroid, an alternative position than the standard rigid body centre is used as the focal point of the superimposition.  The allows, for example, the superimposition about a pivot point.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.get\-\_pos} \label{uf: structure.get_pos}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Extract the atomic positions from the loaded structures for the given spins.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]get\_pos}(\linebreak[0]spin\_id=\linebreak[0]None, ave\_pos=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string.

\hspace{3 mm}\keyword{ave\_pos:}  A flag specifying if the position of the atom is to be averaged across models.


\subsubsection{Description}

This allows the atomic positions of the spins to be extracted from the loaded structures.  This is automatically performed by the structure.load\_spins user function, but if the sequence\index{sequence} information is generated in other ways, this user function allows the structural information to be obtained.

If averaging the atomic positions, then average position of all models will be loaded into the spin container.  Otherwise the positions from all models will be loaded separately.

\subsubsection{Prompt examples}

For a model-free backbone amide nitrogen analysis whereby the N spins have already been created, to obtain the backbone N positions from the file \quotecmd{1F3Y.pdb} (which is a single protein), type the following two user functions:

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('1F3Y.pdb')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.get_pos(spin_id='@N')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.load\-\_spins} \label{uf: structure.load_spins}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/spin}

\subsubsection{Synopsis}

Load spins from the structure into the relax data store.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]load\_spins}(\linebreak[0]spin\_id=\linebreak[0]None, from\_mols=\linebreak[0]None, mol\_name\_target=\linebreak[0]None, ave\_pos=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{spin\_id:}  The spin identification string for the selective loading of certain spins into the relax data store.

\hspace{3 mm}\keyword{from\_mols:}  The list of similar, but not necessarily identical molecules\index{molecule} to load spin information from.

\hspace{3 mm}\keyword{mol\_name\_target:}  The name of target\index{tar} molecule\index{molecule} container, overriding the name of the loaded structures.

\hspace{3 mm}\keyword{ave\_pos:}  A flag specifying if the position of the atom is to be averaged across models.


\subsubsection{Description}

This allows a sequence\index{sequence} to be generated within the relax data store using the atomic information from the structure already associated with this data pipe.  The spin ID string is used to select which molecules,\index{molecule} which residues, and which atoms will be recognised as spin systems within relax.  If the spin ID is left unspecified, then all molecules,\index{molecule} residues, and atoms will be placed within the data store (and all atoms will be treated as spins).

As an alternative to using structural models, by specifying the list of molecules\index{molecule} to load spins from similar though not necessarily identical molecules\index{molecule} will be combined.  In this case, the target\index{tar} molecule\index{molecule} name must be supplied to create a single combined molecule.\index{molecule}  And only a single model can be loaded in the current data pipe.  The spin numbering will be dropped to allow for sequential atom numbering in the PDB\index{PDB} and other formats.  Therefore only the residue number and name and atom name will be preserved for creating the spin containers.  If the spin is only present in a subset of the structures, then the positional information will only be taken from that subset and hence the number of positions might be different for different spins.

If averaging the atomic positions, then average position of all models or molecules\index{molecule} will be loaded into the spin container.  Otherwise the positions from all models or molecules\index{molecule} will be loaded separately.

\subsubsection{Prompt examples}

For a model-free backbone amide nitrogen analysis, to load just the backbone N sequence\index{sequence} from the file \quotecmd{1F3Y.pdb} (which is a single protein), type the following two user functions:

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('1F3Y.pdb')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id='@N')
\end{lstlisting}


For an RNA analysis of adenine C8 and C2, guanine C8 and N1, cytidine C5 and C6, and uracil N3, C5, and C6, type the following series of commands (assuming that the PDB\index{PDB} file with this atom naming has already been read):\index{read}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":A@C8")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":A@C2")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":G@C8")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":G@N1")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":C@C5")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":C@C6")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":U@N3")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":U@C5")
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.load_spins(spin_id=":U@C6")
\end{lstlisting}


Alternatively using some Python\index{Python} programming:

\begin{lstlisting}[numbers=none]
relax> for id in [":A@C8", ":A@C2", ":G@C8", ":G@N1", ":C@C5", ":C@C6", ":U@N3", ":U@C5", ":U@C6"]:
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax>     structure.load_spins(spin_id=id)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.mean} \label{uf: structure.mean}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/categories/applications-education}

\subsubsection{Synopsis}

Calculate the mean structure from all loaded models.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]mean}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None, set\_mol\_name=\linebreak[0]None, set\_model\_num=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes containing structures to average.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe containing structures to average.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to average.  This allows differently named molecules\index{molecule} in the same or different data pipes to be averaged.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.  This can be used to restrict the averaged structure to one atom per residue, for example.

\hspace{3 mm}\keyword{set\_mol\_name:}  Set the optional name of the averaged molecule.\index{molecule}

\hspace{3 mm}\keyword{set\_model\_num:}  Set the optional model number of the averaged molecule.\index{molecule}


\subsubsection{Description}

This will calculate and store the mean structure from a collection of related molecules.\index{molecule}  If a new molecule\index{molecule} name or model number is not supplied, the mean structure will replace all the models in the internal structural object.  This is provided as a structural aid, specifically for superimposition purposes.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.read\-\_gaussian} \label{uf: structure.read_gaussian}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Reading\index{read} structures from Gaussian log files.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]read\_gaussian}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, set\_mol\_name=\linebreak[0]None, set\_model\_num=\linebreak[0]None, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the Gaussian log file.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{set\_mol\_name:}  Set the names of the read\index{read} molecules.\index{molecule}  If unset, then the molecules\index{molecule} will be automatically labelled based on the file name or other information.  This can either be a single name or a list of names.

\hspace{3 mm}\keyword{set\_model\_num:}  Set the model numbers of the loaded molecules.\index{molecule}  This can be a single number or list of numbers.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.  Set to zero to silence the user function, or one to see all messages.


\subsubsection{Description}

The atomic positions from a Gaussian log file can be read\index{read} into relax.  If optimisation has been preformed, the last set of atomic coordinates from the log will be read\index{read} to obtain the final structure.  The log file can be Gzip\index{compression!gzip} or Bzip2\index{compression!bzip2} compressed.

The setting of molecule\index{molecule} names is used to name the molecules\index{molecule} within the Gaussian file.  If not set, then the molecules\index{molecule} will be named after the file name, with the molecule\index{molecule} number appended if more than one exists.  By setting the molecule\index{molecule} name or setting the model number, the loaded structure can be stored as a specific model or as a different molecule.\index{molecule}

\subsubsection{Prompt examples}

To load all structures from the Gaussian file \quotecmd{taxol.log} in the directory \quotecmd{\~{}/logs}, including all models and all molecules,\index{molecule} type one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_gaussian('taxol.log', '~/logs')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_gaussian(file='taxol.log', dir=logs')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.read\-\_pdb} \label{uf: structure.read_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Reading\index{read} structures from PDB\index{PDB} files.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]read\_pdb}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, read\_mol=\linebreak[0]None, set\_mol\_name=\linebreak[0]None, read\_model=\linebreak[0]None, set\_model\_num=\linebreak[0]None, alt\_loc=\linebreak[0]None, verbosity=\linebreak[0]1, merge=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{read\_mol:}  If set, only the given molecule(s)\index{molecule} will be read.\index{read}  The molecules\index{molecule} are numbered consecutively from 1.  If unset, then all molecules\index{molecule} will be loaded.  By providing a list of numbers such as [1, 2], multiple molecules\index{molecule} will be read.\index{read}

\hspace{3 mm}\keyword{set\_mol\_name:}  Set the names of the read\index{read} molecules.\index{molecule}  If unset, then the molecules\index{molecule} will be automatically labelled based on the file name or other information.  This can either be a single name or a list of names.

\hspace{3 mm}\keyword{read\_model:}  If set, only the given model number(s) from the PDB\index{PDB} file will be read.\index{read}  Otherwise all models will be read.\index{read}  This can be a single number or list of numbers.

\hspace{3 mm}\keyword{set\_model\_num:}  Set the model numbers of the loaded molecules.\index{molecule}  If unset, then the PDB\index{PDB} model numbers will be preserved if they exist.  This can be a single number or list of numbers.

\hspace{3 mm}\keyword{alt\_loc:}  The PDB\index{PDB} ATOM record \quotecmd{Alternate location indicator} field value.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.  Set to zero to silence the user function, or one to see all messages.

\hspace{3 mm}\keyword{merge:}  A flag which if set to True will try to merge the PDB\index{PDB} structure into the currently loaded structures.


\subsubsection{Description}

The reading\index{read} of PDB\index{PDB} files into relax is quite a flexible procedure allowing for both models, defined as an ensemble of the same molecule\index{molecule} but with different atomic positions, and different molecules\index{molecule} within the same model.  One of more molecules\index{molecule} can exist in one or more models.  The flexibility allows PDB\index{PDB} models to be converted into different molecules\index{molecule} and different PDB\index{PDB} files loaded as the same molecule\index{molecule} but as different models.

In a PDB\index{PDB} file, the models are specified by the MODEL PDB\index{PDB} record.  All the supported PDB\index{PDB} readers\index{read} in relax recognise this.  The internal reader\index{read} defines molecules\index{molecule} using the TER PDB\index{PDB} record.  In both cases, the molecules\index{molecule} will be numbered consecutively from 1.

Setting the molecule\index{molecule} name allows the molecule\index{molecule} within the PDB\index{PDB} (within one model) to have a custom name.  If not set, then the molecules\index{molecule} will be named after the file name, with the molecule\index{molecule} number appended if more than one exists.

Note that relax will complain if it cannot work out what to do.

This is able to handle uncompressed,\index{compression!uncompressed} bzip2\index{compression!bzip2} compressed files, or gzip\index{compression!gzip} compressed files automatically.  The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with \quotecmd{.bz2} appended followed by the file name with \quotecmd{.gz} appended.

If a PDB\index{PDB} file contains alternative atomic locations, then the alternate location indicator must be specified to allow one of the multiple coordinate sets to be selected.

\subsubsection{Prompt examples}

To load all structures from the PDB\index{PDB} file \quotecmd{test.pdb} in the directory \quotecmd{\~{}/pdb}, including all models and all molecules,\index{molecule} type one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('test.pdb', '~/pdb')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb(file='test.pdb', dir='pdb')
\end{lstlisting}


To load the 10$^{\mathrm{th}}$ model from the file \quotecmd{test.pdb} and naming it \quotecmd{CaM}, use one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('test.pdb', read_model=10, set_mol_name='CaM')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb(file='test.pdb', read_model=10, set_mol_name='CaM')
\end{lstlisting}


To load models 1 and 5 from the file \quotecmd{test.pdb} as two different structures of the same model, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('test.pdb', read_model=[1, 5], set_model_num=[1, 1])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('test.pdb', set_mol_name=['CaM_1', 'CaM_2'], read_model=[1, 5], set_model_num=[1, 1])
\end{lstlisting}


To load the files \quotecmd{lactose\_MCMM4\_S1\_1.pdb}, \quotecmd{lactose\_MCMM4\_S1\_2.pdb}, \quotecmd{lactose\_MCMM4\_S1\_3.pdb} and \quotecmd{lactose\_MCMM4\_S1\_4.pdb} as models, type the following sequence\index{sequence} of commands:

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('lactose_MCMM4_S1_1.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=1)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('lactose_MCMM4_S1_2.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=2)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('lactose_MCMM4_S1_3.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=3)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_pdb('lactose_MCMM4_S1_4.pdb', set_mol_name='lactose_MCMM4_S1', set_model_num=4)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.read\-\_xyz} \label{uf: structure.read_xyz}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Reading\index{read} structures from XYZ files.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]read\_xyz}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, read\_mol=\linebreak[0]None, set\_mol\_name=\linebreak[0]None, read\_model=\linebreak[0]None, set\_model\_num=\linebreak[0]None, verbosity=\linebreak[0]1)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the XYZ file.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{read\_mol:}  If set, only the given molecule(s)\index{molecule} will be read.\index{read}  The molecules\index{molecule} are numbered consecutively from 1.  If unset, then all molecules\index{molecule} will be loaded.  By providing a list of numbers such as [1, 2], multiple molecules\index{molecule} will be read.\index{read}

\hspace{3 mm}\keyword{set\_mol\_name:}  Set the names of the read\index{read} molecules.\index{molecule}  If unset, then the molecules\index{molecule} will be automatically labelled based on the file name or other information.  This can either be a single name or a list of names.

\hspace{3 mm}\keyword{read\_model:}  If set, only the given model number(s) from the PDB\index{PDB} file will be read.\index{read}  Otherwise all models will be read.\index{read}  This can be a single number or list of numbers.

\hspace{3 mm}\keyword{set\_model\_num:}  Set the model numbers of the loaded molecules.\index{molecule}  If unset, then the PDB\index{PDB} model numbers will be preserved if they exist.  This can be a single number or list of numbers.

\hspace{3 mm}\keyword{verbosity:}  The amount of information to print out.  Set to zero to silence the user function, or one to see all messages.


\subsubsection{Description}

The XYZ files with different models, which defined as an ensemble of the same molecule\index{molecule} but with different atomic positions, can be read\index{read} into relax.  If there are several molecules\index{molecule} in one xyz file, please separate them into different files and then load them individually.  Loading different models and different molecules\index{molecule} is controlled by specifying the molecule\index{molecule} number read,\index{read} setting the molecule\index{molecule} names, specifying which model to read,\index{read} and setting the model numbers.

The setting of molecule\index{molecule} names is used to name the molecules\index{molecule} within the XYZ (within one model).  If not set, then the molecules\index{molecule} will be named after the file name, with the molecule\index{molecule} number appended if more than one exists.

Note that relax will complain if it cannot work out what to do.

\subsubsection{Prompt examples}

To load all structures from the XYZ file \quotecmd{test.xyz} in the directory \quotecmd{\~{}/xyz}, including all models and all molecules,\index{molecule} type one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test.xyz', '~/xyz')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz(file='test.xyz', dir='xyz')
\end{lstlisting}


To load the 10$^{\mathrm{th}}$ model from the file \quotecmd{test.xyz} and naming it \quotecmd{CaM}, use one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test.xyz', read_model=10, set_mol_name='CaM')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz(file='test.xyz', read_model=10, set_mol_name='CaM')
\end{lstlisting}


To load models 1 and 5 from the file \quotecmd{test.xyz} as two different structures of the same model, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test.xyz', read_model=[1, 5], set_model_num=[1, 1])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test.xyz', set_mol_name=['CaM_1', 'CaM_2'], read_model=[1, 5], set_model_num=[1, 1])
\end{lstlisting}


To load the files \quotecmd{test\_1.xyz}, \quotecmd{test\_2.xyz}, \quotecmd{test\_3.xyz} and \quotecmd{test\_4.xyz} as models, type the  following sequence\index{sequence} of commands:

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test_1.xyz', set_mol_name='test_1', set_model_num=1)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test_2.xyz', set_mol_name='test_2', set_model_num=2)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test_3.xyz', set_mol_name='test_3', set_model_num=3)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.read_xyz('test_4.xyz', set_mol_name='test_4', set_model_num=4)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.rmsd} \label{uf: structure.rmsd}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Determine the RMSD between structures.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]rmsd}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to determine the RMSD for.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to determine the RMSD for.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to determine the RMSD for.  The RMSD will only be calculated for atoms with identical residue name and number and atom name.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.


\subsubsection{Description}

This allows the root mean squared deviation (RMSD) between all structures to be calculated.  The RMSDs for individual structures to the mean structure will be calculated and reported, and then these values averaged for the global RMSD.  This will be stored in the structural object of the current data pipe.

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

The atom ID string, which uses the same notation as the spin ID, can be used to restrict the coordinates compared to a subset of molecules,\index{molecule} residues, or atoms.  For example to only use backbone heavy atoms in a protein, set the atom ID to \quotecmd{@N,C,CA,O}, assuming those are the names of the atoms in the 3D structural file.

\subsubsection{Prompt examples}

To determine the RMSD of all models in the current data pipe, simply type:

\begin{lstlisting}[numbers=none]
relax> structure.rmsd()
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.rotate} \label{uf: structure.rotate}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Rotate the internal structural object about the given origin by the rotation\index{rotation} matrix.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]rotate}(\linebreak[0]R=\linebreak[0]array(\linebreak[0][[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]]), origin=\linebreak[0]None, model=\linebreak[0]None, atom\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{R:}  The rotation\index{rotation} matrix in forwards rotation\index{rotation} notation.

\hspace{3 mm}\keyword{origin:}  The origin or pivot of the rotation.\index{rotation}

\hspace{3 mm}\keyword{model:}  The model to rotate (which if not set will cause all models to be rotated).

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string.


\subsubsection{Description}

This is used to rotate the internal structural data by the given rotation\index{rotation} matrix.  If the origin is supplied, then this will act as the pivot of the rotation.\index{rotation}  Otherwise, all structural data will be rotated about the point [0, 0, 0].  The rotation\index{rotation} can be restricted to one specific model.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.sequence\-\_alignment} \label{uf: structure.sequence_alignment}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Multiple sequence\index{sequence} alignment (MSA) of structural data.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]sequence\_alignment}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, msa\_algorithm=\linebreak[0]`Central Star', pairwise\_algorithm=\linebreak[0]None, matrix=\linebreak[0]None, gap\_open\_penalty=\linebreak[0]10.0, gap\_extend\_penalty=\linebreak[0]1.0, end\_gap\_open\_penalty=\linebreak[0]0.0, end\_gap\_extend\_penalty=\linebreak[0]0.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to use in the sequence\index{sequence} alignment.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to use in the sequence\index{sequence} alignment.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to use in the sequence\index{sequence} alignment.  This allows differently named molecules\index{molecule} in the same or different data pipes to be superimposed.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{msa\_algorithm:}  The multiple sequence\index{sequence} alignment (MSA) algorithm used to align all the primary sequence\index{sequence} of all structures of interest.

\hspace{3 mm}\keyword{pairwise\_algorithm:}  The pairwise alignment algorithm to align each pair of sequences.\index{sequence}

\hspace{3 mm}\keyword{matrix:}  The substitution matrix to use in the pairwise sequence\index{sequence} alignment algorithm.

\hspace{3 mm}\keyword{gap\_open\_penalty:}  The penalty for introducing gaps, as a positive number.

\hspace{3 mm}\keyword{gap\_extend\_penalty:}  The penalty for extending a gap, as a positive number.

\hspace{3 mm}\keyword{end\_gap\_open\_penalty:}  The optional penalty for opening a gap at the end of a sequence.\index{sequence}

\hspace{3 mm}\keyword{end\_gap\_extend\_penalty:}  The optional penalty for extending a gap at the end of a sequence.\index{sequence}


\subsubsection{Description}

To find the atoms in common between different molecules,\index{molecule} a MSA of the primary sequence\index{sequence} of the molecules\index{molecule} is required.  This sequence\index{sequence} alignment will then subsequently be used by any other user function which operates on multiple molecules.\index{molecule}  The following MSA algorithms can be selected:

\begin{description}
  \item[\quotecmd{Central Star} --] This is a heuristic, progressive alignment method using pairwise alignments to construct a MSA.  It consists of four major steps - pairwise alignment between all sequence\index{sequence} pairs, finding the central sequence,\index{sequence} iteratively aligning the sequences\index{sequence} to the gapped central sequence,\index{sequence} and introducing gaps in previous alignments during the iterative alignment.
  \item[\quotecmd{residue number} --] This will simply align the molecules\index{molecule} based on residue number.
\end{description}

For the MSA algorithms which require pairwise alignments, the following subalgorithms can be used:

\begin{description}
  \item[\quotecmd{NW70} --] The Needleman-Wunsch alignment algorithm.  This has been modified to use the logic of the EMBOSS software for handling gap opening and extension penalties, as well as end penalties.
\end{description}

For the MSAs or pairwise alignments which require a substitution matrix, one of the following can be used:

\begin{description}
  \item[\quotecmd{BLOSUM62} --] The BLOcks SUbstitution Matrix for proteins with a cluster percentage $\ge$ 62\%.
  \item[\quotecmd{PAM250} --] The point accepted mutation matrix for proteins with $n$ = 250 evolutionary distance.
  \item[\quotecmd{NUC 4.4} --] The nucleotide 4.4 matrix for DNA/RNA.
\end{description}

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

\subsubsection{Prompt examples}

To superimpose the structures in the \quotecmd{A} data pipe onto the structures of the \quotecmd{B} data pipe using backbone heavy atoms, type:

\begin{lstlisting}[numbers=none]
relax> structure.sequence_alignment(pipes=['B', 'A'], atom_id='@N,C,CA,O')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.superimpose} \label{uf: structure.superimpose}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Superimpose a set of structures.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]superimpose}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None, displace\_id=\linebreak[0]None, method=\linebreak[0]`fit to mean', centre\_type=\linebreak[0]`centroid', centroid=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to use in the superimposition.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to use in the superimposition.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to use in the superimposition.  This allows differently named molecules\index{molecule} in the same or different data pipes to be superimposed.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.  This allows a subset of all residues or atoms to be used in the superimposition.  For example for protein backbone heavy atoms, this can be set to \quotecmd{@N,C,CA,O}.

\hspace{3 mm}\keyword{displace\_id:}  The atom identification string for restricting the displacement to a subset of all atoms.  If not set, then all atoms will be translated and rotated.  If supplied as a list of IDs, then the number of items must match the number of structures.

\hspace{3 mm}\keyword{method:}  The superimposition method.

\hspace{3 mm}\keyword{centre\_type:}  The type of centre to user for the superimposition, $i$.e. either the standard centroid superimposition or a superimposition using the centre of mass (CoM).

\hspace{3 mm}\keyword{centroid:}  The alternative position of the centroid.


\subsubsection{Description}

This allows a set of related structures to be superimposed to each other.  If a multiple sequence\index{sequence} alignment (MSA) of the molecules\index{molecule} has already been performed with the structure.sequence\_alignment user function, this will allow residues with different numbering to be superimposed.  Otherwise only residues with the same numbering will be used in the superimposition.  Two superimposition methods are currently supported:

\begin{description}
  \item[\quotecmd{fit to mean} --] All models are fit to the mean structure.  This is the default and most accurate method for an ensemble description.  It is an iterative method which first calculates a mean structure and then fits each model to the mean structure using the Kabsch algorithm.  This is repeated until convergence.
  \item[\quotecmd{fit to first} --] This is quicker but is not as accurate for an ensemble description.  The Kabsch algorithm is used to rotate and translate each model to be superimposed onto the first model of the first data pipe.
\end{description}

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

The atom ID string, which uses the same notation as the spin ID, can be used to restrict the coordinates compared to a subset of molecules,\index{molecule} residues, or atoms.  For example to only use backbone heavy atoms in a protein, set the atom ID to \quotecmd{@N,C,CA,O}, assuming those are the names of the atoms in the 3D structural file.

The displacement ID string, which is similar to the atom ID, gives finer control over which atoms are translated and rotated by the algorithm.  When not set this allows, for example, to align structures based on a set of backbone heavy atoms and the backbone protons and side-chains are displaced by default.  Or if set to the same as the atom ID, if a single domain is aligned, then just that domain will be displaced.

By supplying the position of the centroid, an alternative position than the standard rigid body centre is used as the focal point of the superimposition.  The allows, for example, the superimposition about a pivot point.

\subsubsection{Prompt examples}

To superimpose all sets of models, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.superimpose()
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.superimpose(method='fit to mean')
\end{lstlisting}


To superimpose the models 1, 2, 3, 5 onto model 4, type:

\begin{lstlisting}[numbers=none]
relax> structure.superimpose(models=[[4, 1, 2, 3, 5]], method='fit to first')
\end{lstlisting}


To superimpose an ensemble of protein structures using only the backbone heavy atoms, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.superimpose(atom_id='@N,C,CA,O')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.superimpose(method='fit to mean', atom_id='@N,C,CA,O')
\end{lstlisting}


To superimpose the structures in the \quotecmd{A} data pipe onto the structures of the \quotecmd{B} data pipe using backbone heavy atoms, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.superimpose(['B', 'A'], None, 'fit to first', '@N,C,CA,O')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.superimpose(pipes=['B', 'A'], method='fit to first', atom_id='@N,C,CA,O')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.translate} \label{uf: structure.translate}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Laterally displace the internal structural object by the translation vector.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]translate}(\linebreak[0]T=\linebreak[0]None, model=\linebreak[0]None, atom\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{T:}  The translation vector.

\hspace{3 mm}\keyword{model:}  The model to translate (which if not set will cause all models to be translate).

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string.


\subsubsection{Description}

This is used to translate the internal structural data by the given translation vector.  The translation can be restricted to one specific model.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.web\-\_of\-\_motion} \label{uf: structure.web_of_motion}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill 

\subsubsection{Synopsis}

Create a PDB\index{PDB} representation of motion between structures using a web of interconnecting lines.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]web\_of\_motion}(\linebreak[0]pipes=\linebreak[0]None, models=\linebreak[0]None, molecules=\linebreak[0]None, atom\_id=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipes:}  The data pipes to generate the web between.

\hspace{3 mm}\keyword{models:}  The list of models for each data pipe to generate the web between.  The number of elements must match the pipes argument.  If no models are given, then all will be used.

\hspace{3 mm}\keyword{molecules:}  The list of molecules\index{molecule} for each data pipe to generate the web between.  This allows differently named molecules\index{molecule} in the same or different data pipes to be superimposed.  The number of elements must match the pipes argument.  If no molecules\index{molecule} are given, then all will be used.

\hspace{3 mm}\keyword{atom\_id:}  The atom identification string of the coordinates of interest.

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory to save the file to.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause any pre-existing files to be overwritten.


\subsubsection{Description}

This will create a PDB\index{PDB} representation of the motion between the atoms of a given set of structures.  Identical atoms of the structures are concatenated into one model, within a temporary internal structural object, linked together using PDB\index{PDB} CONECT records, and then written to the PDB\index{PDB} file.

Support for multiple structures is provided by the data pipes, model numbers and molecule\index{molecule} names arguments.  Each data pipe, model and molecule\index{molecule} combination will be treated as a separate structure.  As only atomic coordinates with the same residue name and number and atom name will be assembled, structures with slightly different atomic structures can be compared.  If the list of models is not supplied, then all models of all data pipes will be used.  If the optional molecules\index{molecule} list is supplied, each molecule\index{molecule} in the list will be considered as a separate structure for comparison between each other.

The atom ID string, which uses the same notation as the spin ID, can be used to restrict the coordinates compared to a subset of molecules,\index{molecule} residues, or atoms.  For example to only use backbone heavy atoms in a protein, set the atom ID to \quotecmd{@N,C,CA,O}, assuming those are the names of the atoms in the 3D structural file.

\subsubsection{Prompt examples}

To create a web of motion for the models 1, 3, and 5, type:

\begin{lstlisting}[numbers=none]
relax> structure.web_of_motion(models=[[1, 3, 5]], file='web.pdb')
\end{lstlisting}


To create a web of motion for the molecules\index{molecule} \quotecmd{A}, \quotecmd{B}, \quotecmd{C}, and \quotecmd{D}, type:

\begin{lstlisting}[numbers=none]
relax> structure.web_of_motion(molecules=[['A', 'B', 'C', 'D']], file='web.pdb')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{structure\-.write\-\_pdb} \label{uf: structure.write_pdb}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/structure} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Writing structures to a PDB\index{PDB} file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{structure.\linebreak[0]write\_pdb}(\linebreak[0]file=\linebreak[0]None, dir=\linebreak[0]None, model\_num=\linebreak[0]None, compress\_type=\linebreak[0]0, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{file:}  The name of the PDB\index{PDB} file.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{model\_num:}  Restrict the writing of structural data to a single model in the PDB\index{PDB} file.

\hspace{3 mm}\keyword{compress\_type:}  The type of compression\index{compression} to use when creating the file.

\hspace{3 mm}\keyword{force:}  A flag which if set to True will cause any pre-existing files to be overwritten.


\subsubsection{Description}

This will write\index{write} all of the structural data loaded in the current data pipe to be converted to the PDB\index{PDB} format and written to file.  Specifying the model number allows single models to be output.

The default behaviour of this function is to not compress the file.  The compression\index{compression} can, however, be changed to either bzip2\index{compression!bzip2} or gzip\index{compression!gzip} compression.\index{compression}  If the \quotecmd{.bz2} or \quotecmd{.gz} extension is not included in the file name, it will be added.  This behaviour is controlled by the compression\index{compression} type which can be set to

\begin{description}
  \item[0 --] No compression\index{compression} (no file extension).
  \item[1 --] bzip2\index{compression!bzip2} compression\index{compression} (\quotecmd{.bz2} file extension).
  \item[2 --] gzip\index{compression!gzip} compression\index{compression} (\quotecmd{.gz} file extension).
\end{description}

\subsubsection{Prompt examples}

To write\index{write} all models and molecules\index{molecule} to the PDB\index{PDB} file \quotecmd{ensemble.pdb} within the directory \quotecmd{\~{}/pdb}, type one of:

\begin{lstlisting}[numbers=none]
relax> structure.write_pdb('ensemble.pdb', '~/pdb')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.write_pdb(file='ensemble.pdb', dir='pdb')
\end{lstlisting}


To write\index{write} model number 3 into the new file \quotecmd{test.pdb}, use one of:

\begin{lstlisting}[numbers=none]
relax> structure.write_pdb('test.pdb', model_num=3)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> structure.write_pdb(file='test.pdb', model_num=3)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{sys\-\_info} \label{uf: sys_info}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/help-about}

\subsubsection{Synopsis}

Display\index{display} all system information relating to this version of relax.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{sys\_info}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will display\index{display} all of the relax, Python,\index{Python} python\index{Python} package and hardware information currently being used by relax.  This is useful for seeing if all packages are up to date and if the correct software versions are being used.  It is also very useful information for reporting relax bugs.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{time} \label{uf: time}
\includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/chronometer}

\subsubsection{Synopsis}

Display\index{display} the current time.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{time}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This user function will display\index{display} the current time which can be useful for timing long calculations by having time information in any saved log files.



\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{value\-.copy} \label{uf: value.copy}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/value} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/list-add}

\subsubsection{Synopsis}

Copy\index{copy} parameters from one data pipe to another.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{value.\linebreak[0]copy}(\linebreak[0]pipe\_from=\linebreak[0]None, pipe\_to=\linebreak[0]None, param=\linebreak[0]None, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{pipe\_from:}  The name of the pipe to copy\index{copy} from.

\hspace{3 mm}\keyword{pipe\_to:}  The name of the pipe to copy\index{copy} to.

\hspace{3 mm}\keyword{param:}  The parameter to copy.\index{copy}  Only one parameter may be selected.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the destination parameter to be overwritten.


\subsubsection{Description}

If this is used to change values of previously minimised\index{optimisation} parameters, then the minimisation\index{optimisation} statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.

\subsubsection{Relaxation curve fitting parameters}

Please see Table~\ref{table: curve-fit parameter value setting} on page~\pageref{table: curve-fit parameter value setting}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation curve fitting parameters.]{Relaxation curve fitting parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
rx & Either the R$_1$ or R$_2$ relaxation rate \\
i0 & The initial intensity \\
iinf & The intensity at infinity \\
\bottomrule
\\[-5pt]
\label{table: curve-fit parameter value setting}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Model-free parameters}

Please see Table~\ref{table: model-free parameter value setting} on page~\pageref{table: model-free parameter value setting}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Model-free parameters.]{Model-free parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
s2 & $S^2$, the model-free generalised order parameter ($S^2$ = $S^2_f$.S2s) \\
s2f & $S^2_f$, the faster motion model-free generalised order parameter \\
s2s & $S^2_s$, the slower motion model-free generalised order parameter \\
local\_tm & The spin specific global correlation time (seconds) \\
te & Single motion effective internal correlation time (seconds) \\
tf & Faster motion effective internal correlation time (seconds) \\
ts & Slower motion effective internal correlation time (seconds) \\
rex & Chemical exchange relaxation (sigma\_ex = $R_{ex}$ / omega**2) \\
csa & Chemical shift anisotropy (unitless) \\
\bottomrule
\\[-5pt]
\label{table: model-free parameter value setting}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Setting a parameter value may have no effect depending on which model-free model is chosen.  For example if $S^2_f$ values and $S^2_s$ values are set but the data pipe corresponds to the model-free model \quotecmd{m4} then because these data values are not parameters of the model they will have no effect.

Note that the $R_{ex}$ values are scaled quadratically with field strength and should be supplied as a field strength independent value.  Use the following formula to obtain the correct value:

{\footnotesize \begin{verbatim}
    value = rex / (2.0 * pi * frequency) ** 2
\end{verbatim}}

where:

\begin{itemize}
  \item[]rex is the chemical\index{chemical exchange} exchange value for the current frequency.
  \item[]frequency is the proton frequency corresponding to the data.
\end{itemize}

\subsubsection{Reduced spectral density mapping parameters}

Please see Table~\ref{table: J(w) parameter value setting} on page~\pageref{table: J(w) parameter value setting}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Reduced spectral density mapping parameters.]{Reduced spectral density mapping parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
j0 & Spectral density value at 0 MHz - $J(0)$ \\
jwx & Spectral density value at the frequency of the heteronucleus - $J(\omega_X)$ \\
jwh & Spectral density value at the frequency of the proton - $J(\omega_H)$ \\
csa & Chemical shift anisotropy (unitless) \\
\bottomrule
\\[-5pt]
\label{table: J(w) parameter value setting}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


In reduced spectral density mapping,\index{map} the CSA value must be set prior to the calculation of spectral density values.

\subsubsection{Consistency testing parameters}

Please see Table~\ref{table: consistency testing parameter value setting} on page~\pageref{table: consistency testing parameter value setting}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Consistency testing parameters.]{Consistency testing parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
j0 & Spectral density value at 0 MHz (from Farrow et al. (1995) JBNMR, 6: 153-162) \\
f\_eta & Eta-test (from Fushman et al. (1998) JACS, 120: 10947-10952) \\
f\_r2 & R2-test (from Fushman et al. (1998) JACS, 120: 10947-10952) \\
csa & Chemical shift anisotropy (unitless) \\
orientation & Angle between the 15N-1H vector and the principal axis of the 15N chemical shift tensor \\
tc & The single global correlation time estimate/approximation \\
\bottomrule
\\[-5pt]
\label{table: consistency testing parameter value setting}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


In consistency testing, the CSA value, angle\index{angles} Theta (\quotecmd{orientation}) and global correlation\index{correlation time} time must be set prior to the calculation of consistency functions.

\subsubsection{N-state model parameters}

Please see Table~\ref{table: N-state parameter value setting} on page~\pageref{table: N-state parameter value setting}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[N-state model parameters.]{N-state model parameters.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Type \\
\midrule
Axx & The Axx component of the alignment tensor & float \\
Ayy & The Ayy component of the alignment tensor & float \\
Axy & The Axy component of the alignment tensor & float \\
Axz & The Axz component of the alignment tensor & float \\
Ayz & The Ayz component of the alignment tensor & float \\
probs & The probabilities of each state & list \\
alpha & The $\alpha$ Euler angles (for the rotation of each state) & list \\
beta & The $\beta$ Euler angles (for the rotation of each state) & list \\
gamma & The $\gamma$ Euler angles (for the rotation of each state) & list \\
paramagnetic\_centre & The paramagnetic centre & list \\
\bottomrule
\\[-5pt]
\label{table: N-state parameter value setting}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states.  To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be given as the index argument.  So the Euler\index{Euler angles} angle\index{angles} $\gamma$ of the third state is specified using the parameter name \quotecmd{gamma} and index of 2.

\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameter value setting} on page~\pageref{table: dispersion parameter value setting}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation dispersion parameters.]{Relaxation dispersion parameters.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Type \\
\midrule
r2eff & The effective transversal relaxation rate & dict \\
i0 & The initial intensity & dict \\
r1 & The longitudinal relaxation rate & dict \\
r2 & The transversal relaxation rate & dict \\
r2a & The transversal relaxation rate for state A in the absence of exchange & dict \\
r2$b$ & The transversal relaxation rate for state B in the absence of exchange & dict \\
pA & The population for state A & float \\
pB & The population for state B & float \\
pC & The population for state C & float \\
phi\_ex & The $\phi$\_ex = pA.pB.dw**2 value (ppm\^{}2) & float \\
phi\_ex\_B & The fast exchange factor between sites A and B (ppm\^{}2) & float \\
phi\_ex\_C & The fast exchange factor between sites A and C (ppm\^{}2) & float \\
padw2 & The pA.dw**2 value (ppm\^{}2) & float \\
dw & The chemical shift difference between states A and B (in ppm) & float \\
dw\_AB & The chemical shift difference between states A and B for 3-site exchange (in ppm) & float \\
dw\_AC & The chemical shift difference between states A and C for 3-site exchange (in ppm) & float \\
dw\_BC & The chemical shift difference between states B and C for 3-site exchange (in ppm) & float \\
dwH & The proton chemical shift difference between states A and B (in ppm) & float \\
dwH\_AB & The proton chemical shift difference between states A and B for 3-site exchange (in ppm) & float \\
dwH\_AC & The proton chemical shift difference between states A and C for 3-site exchange (in ppm) & float \\
dwH\_BC & The proton chemical shift difference between states B and C for 3-site exchange (in ppm) & float \\
kex & The exchange rate & float \\
kex\_AB & The exchange rate between sites A and B for 3-site exchange with kex\_AB = $k$\_AB + $k$\_BA (rad.s\^{}-1) & float \\
kex\_AC & The exchange rate between sites A and C for 3-site exchange with kex\_AC = $k$\_AC + $k$\_CA (rad.s\^{}-1) & float \\
kex\_BC & The exchange rate between sites B and C for 3-site exchange with kex\_BC = $k$\_BC + $k$\_CB (rad.s\^{}-1) & float \\
kB & Approximate chemical exchange rate constant between sites A and B (rad.s\^{}-1) & float \\
kC & Approximate chemical exchange rate constant between sites A and C (rad.s\^{}-1) & float \\
tex & The time of exchange (tex = 1/kex) & float \\
k\_AB & The exchange rate from state A to state B & float \\
k\_BA & The exchange rate from state B to state A & float \\
\bottomrule
\\[-5pt]
\label{table: dispersion parameter value setting}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Any of the relaxation\index{relaxation} dispersion parameters which are of the \quotecmd{float} type can be set.  Note that setting values for parameters which are not part of the model will have no effect.

\subsubsection{Frame order parameters}

Please see Table~\ref{table: frame order parameters} on page~\pageref{table: frame order parameters}.

\subsubsection{Prompt examples}

To copy\index{copy} the CSA values from the data pipe \quotecmd{m1} to \quotecmd{m2}, type:

\begin{lstlisting}[numbers=none]
relax> value.copy('m1', 'm2', 'csa')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{value\-.display} \label{uf: value.display}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/value} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-preview}

\subsubsection{Synopsis}

Display\index{display} spin specific parameter values.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{value.\linebreak[0]display}(\linebreak[0]param=\linebreak[0]None, scaling=\linebreak[0]1.0)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{param:}  The parameter to display.\index{display}  Only one parameter may be selected.

\hspace{3 mm}\keyword{scaling:}  The factor to scale parameters by.


\subsubsection{Description}

The values corresponding to the given parameter will be displayed.\index{display}  The scaling argument can be used to scale the parameter values.  This can be useful for example in the case of the model-free $R_{ex}$ parameter to obtain the spectrometer dependent value from the omega\_ex field strength independent internal value.  Or to scale correlation\index{correlation time} times from seconds down to nanosecond or picosecond timescales.

\subsubsection{Relaxation curve fitting parameters}

Please see Table~\ref{table: curve-fit parameters} on page~\pageref{table: curve-fit parameters}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation curve fitting parameters.]{Relaxation curve fitting parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
rx & Either the R$_1$ or R$_2$ relaxation rate \\
i0 & The initial intensity \\
iinf & The intensity at infinity \\
\bottomrule
\\[-5pt]
\label{table: curve-fit parameters}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Steady-state NOE parameters}

Please see Table~\ref{table: NOE parameters} on page~\pageref{table: NOE parameters}.

\subsubsection{Model-free parameters}

Please see Table~\ref{table: model-free parameter writing} on page~\pageref{table: model-free parameter writing}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Model-free parameters.]{Model-free parameters.}
\begin{tabular}{ll}
\\[-5pt]
\toprule
Name & Description \\
\midrule
s2 & $S^2$, the model-free generalised order parameter ($S^2$ = $S^2_f$.S2s) \\
s2f & $S^2_f$, the faster motion model-free generalised order parameter \\
s2s & $S^2_s$, the slower motion model-free generalised order parameter \\
local\_tm & The spin specific global correlation time (seconds) \\
te & Single motion effective internal correlation time (seconds) \\
tf & Faster motion effective internal correlation time (seconds) \\
ts & Slower motion effective internal correlation time (seconds) \\
rex & Chemical exchange relaxation (sigma\_ex = $R_{ex}$ / omega**2) \\
csa & Chemical shift anisotropy (unitless) \\
\bottomrule
\\[-5pt]
\label{table: model-free parameter writing}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


For model-free theory it is assumed that $R_{ex}$ values are scaled quadratically with field strength.  The values will be very small as they will be written out as a field strength independent value.  Hence use the following formula to convert the value to that expected for a given magnetic field strength:

{\footnotesize \begin{verbatim}
    Rex = value * (2.0 * pi * frequency) ** 2
\end{verbatim}}

The frequency is that of the proton in Hertz.

\subsubsection{Reduced spectral density mapping parameters}

Please see Table~\ref{table: J(w) parameters} on page~\pageref{table: J(w) parameters}.

\subsubsection{Consistency testing parameters}

Please see Table~\ref{table: consistency testing parameters} on page~\pageref{table: consistency testing parameters}.

\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameters} on page~\pageref{table: dispersion parameters}.

\subsubsection{Prompt examples}

To show all CSA values, type:

\begin{lstlisting}[numbers=none]
relax> value.display('csa')
\end{lstlisting}


To display\index{display} the model-free $R_{ex}$ values scaled to 600 MHz, type one of:

\begin{lstlisting}[numbers=none]
relax> value.display('rex', scaling=(2.0*pi*600e6)**2)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.display(param='rex', scaling=(2.0*pi*600e6)**2)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{value\-.read} \label{uf: value.read}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/value} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-open}

\subsubsection{Synopsis}

Read\index{read} spin specific parameter values from a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{value.\linebreak[0]read}(\linebreak[0]param=\linebreak[0]None, scaling=\linebreak[0]1.0, file=\linebreak[0]None, dir=\linebreak[0]None, spin\_id\_col=\linebreak[0]None, mol\_name\_col=\linebreak[0]None, res\_num\_col=\linebreak[0]None, res\_name\_col=\linebreak[0]None, spin\_num\_col=\linebreak[0]None, spin\_name\_col=\linebreak[0]None, data\_col=\linebreak[0]None, error\_col=\linebreak[0]None, sep=\linebreak[0]None, spin\_id=\linebreak[0]None)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{param:}  The parameter.  Only one parameter may be selected.

\hspace{3 mm}\keyword{scaling:}  The factor to scale parameters by.

\hspace{3 mm}\keyword{file:}  The name of the file containing the values.

\hspace{3 mm}\keyword{dir:}  The directory where the file is located.

\hspace{3 mm}\keyword{spin\_id\_col:}  The spin ID string column (an alternative to the mol, res, and spin name and number columns).

\hspace{3 mm}\keyword{mol\_name\_col:}  The molecule\index{molecule} name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_num\_col:}  The residue number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{res\_name\_col:}  The residue name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_num\_col:}  The spin number column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{spin\_name\_col:}  The spin name column (alternative to the spin\_id\_col).

\hspace{3 mm}\keyword{data\_col:}  The RDC data column.

\hspace{3 mm}\keyword{error\_col:}  The experimental error column.

\hspace{3 mm}\keyword{sep:}  The column separator (the default is white space).

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict the loading of data to certain spin subsets.


\subsubsection{Description}

The spin system can be identified in the file using two different formats.  The first is the spin ID string column which can include the molecule\index{molecule} name, the residue name and number, and the spin name and number.  Alternatively the molecule\index{molecule} name, residue number, residue name, spin number and/or spin name columns can be supplied allowing this information to be in separate columns.  Note that the numbering of columns starts at one.  The spin ID string can be used to restrict the reading\index{read} to certain spin types, for example only 15N spins when only residue information is in the file.

If this is used to change values of previously minimised\index{optimisation} parameters, then the minimisation\index{optimisation} statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.

\subsubsection{Relaxation curve fitting parameters}

Please see Table~\ref{table: curve-fit parameter value setting} on page~\pageref{table: curve-fit parameter value setting}.

\subsubsection{Model-free parameters}

Please see Table~\ref{table: model-free parameter value setting} on page~\pageref{table: model-free parameter value setting}.

Setting a parameter value may have no effect depending on which model-free model is chosen.  For example if $S^2_f$ values and $S^2_s$ values are set but the data pipe corresponds to the model-free model \quotecmd{m4} then because these data values are not parameters of the model they will have no effect.

Note that the $R_{ex}$ values are scaled quadratically with field strength and should be supplied as a field strength independent value.  Use the following formula to obtain the correct value:

{\footnotesize \begin{verbatim}
    value = rex / (2.0 * pi * frequency) ** 2
\end{verbatim}}

where:

\begin{itemize}
  \item[]rex is the chemical\index{chemical exchange} exchange value for the current frequency.
  \item[]frequency is the proton frequency corresponding to the data.
\end{itemize}

\subsubsection{Reduced spectral density mapping parameters}

Please see Table~\ref{table: J(w) parameter value setting} on page~\pageref{table: J(w) parameter value setting}.

In reduced spectral density mapping,\index{map} the CSA value must be set prior to the calculation of spectral density values.

\subsubsection{Consistency testing parameters}

Please see Table~\ref{table: consistency testing parameter value setting} on page~\pageref{table: consistency testing parameter value setting}.

In consistency testing, the CSA value, angle\index{angles} Theta (\quotecmd{orientation}) and global correlation\index{correlation time} time must be set prior to the calculation of consistency functions.

\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameter value setting} on page~\pageref{table: dispersion parameter value setting}.

Any of the relaxation\index{relaxation} dispersion parameters which are of the \quotecmd{float} type can be set.  Note that setting values for parameters which are not part of the model will have no effect.

\subsubsection{Prompt examples}

To load 15N CSA values from the file \quotecmd{csa\_values} in the directory \quotecmd{data}, where spins are only identified by residue name and number, type one of the following:

\begin{lstlisting}[numbers=none]
relax> value.read('csa', 'data/csa_value', spin_id='@N')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.read('csa', 'csa_value', dir='data', spin_id='@N')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.read(param='csa', file='csa_value', dir='data', res_num_col=1, res_name_col=2, data_col=3, error_col=4, spin_id='@N')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{value\-.set} \label{uf: value.set}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/value} \hfill 

\subsubsection{Synopsis}

Set parameter values.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{value.\linebreak[0]set}(\linebreak[0]val=\linebreak[0]None, param=\linebreak[0]None, index=\linebreak[0]0, spin\_id=\linebreak[0]None, error=\linebreak[0]False, force=\linebreak[0]True)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{val:}  The value(s).

\hspace{3 mm}\keyword{param:}  The parameter(s).

\hspace{3 mm}\keyword{index:}  The list index for when the parameter is a list of values.  This is ignored in all other cases.

\hspace{3 mm}\keyword{spin\_id:}  The spin ID string to restrict value setting to.

\hspace{3 mm}\keyword{error:}  A flag which if True will cause the error rather than parameter to be set.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the destination parameter to be overwritten.


\subsubsection{Description}

If this function is used to change values of previously minimised\index{optimisation} results, then the minimisation\index{optimisation} statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.

The value can be None, a single value, or an array of values while the parameter can be None, a string, or array of strings.  The choice of which combination determines the behaviour of this function.  The following table describes what occurs in each instance.  In these columns, \quotecmd{None} corresponds to None, \quotecmd{1} corresponds to either a single value or single string, and \quotecmd{n} corresponds to either an array of values or an array of strings.

Please see Table~\ref{table: value.set combinations} on page~\pageref{table: value.set combinations}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[The value and parameter combinations for the value.set user function.]{The value and parameter combination options for the value.set user function.}
\begin{tabularx}{\textwidth}{llX}
\\[-5pt]
\toprule
Value & Param & Description \\
\midrule
None & None & This case is used to set the model parameters prior to minimisation or calculation.  The model parameters are set to the default values. \\
1 & None & Invalid combination. \\
n & None & This case is used to set the model parameters prior to minimisation or calculation.  The length of the val array must be equal to the number of model parameters.  The parameters will be set to the corresponding number. \\
None & 1 & The parameter matching the string will be set to the default value. \\
1 & 1 & The parameter matching the string will be set to the supplied number. \\
n & 1 & Invalid combination. \\
None & n & Each parameter matching the strings will be set to the default values. \\
1 & n & Each parameter matching the strings will be set to the supplied number. \\
n & n & Each parameter matching the strings will be set to the corresponding number.  Both arrays must be of equal length. \\
\bottomrule
\\[-5pt]
\label{table: value.set combinations}
\end{tabularx}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Spin ID string}

For spin-specific parameters, the spin ID string can be used to restrict the value setting to a specific spin system or group of spins.  It has no effect for global parameters such as in the N-state model and frame order analyses.

\subsubsection{Relaxation curve fitting parameters}

Please see Table~\ref{table: curve-fit parameter value setting with defaults} on page~\pageref{table: curve-fit parameter value setting with defaults}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation curve fitting parameter value setting.]{Relaxation curve fitting parameter value setting.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Default \\
\midrule
rx & Either the R$_1$ or R$_2$ relaxation rate & 8.0 \\
i0 & The initial intensity & 10000.0 \\
iinf & The intensity at infinity & 0.0 \\
\bottomrule
\\[-5pt]
\label{table: curve-fit parameter value setting with defaults}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


\subsubsection{Model-free parameters}

Please see Table~\ref{table: model-free parameter value setting with defaults} on page~\pageref{table: model-free parameter value setting with defaults}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Model-free parameter value setting.]{Model-free parameter value setting.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Default \\
\midrule
s2 & $S^2$, the model-free generalised order parameter ($S^2$ = $S^2_f$.S2s) & 0.8 \\
s2f & $S^2_f$, the faster motion model-free generalised order parameter & 0.8 \\
s2s & $S^2_s$, the slower motion model-free generalised order parameter & 0.8 \\
local\_tm & The spin specific global correlation time (seconds) & 1e-08 \\
te & Single motion effective internal correlation time (seconds) & 1e-10 \\
tf & Faster motion effective internal correlation time (seconds) & 1e-11 \\
ts & Slower motion effective internal correlation time (seconds) & 1e-09 \\
rex & Chemical exchange relaxation (sigma\_ex = $R_{ex}$ / omega**2) & 0.0 \\
csa & Chemical shift anisotropy (unitless) & -0.000172 \\
\bottomrule
\\[-5pt]
\label{table: model-free parameter value setting with defaults}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Setting a parameter value may have no effect depending on which model-free model is chosen.  For example if $S^2_f$ values and $S^2_s$ values are set but the data pipe corresponds to the model-free model \quotecmd{m4} then because these data values are not parameters of the model they will have no effect.

Note that the $R_{ex}$ values are scaled quadratically with field strength and should be supplied as a field strength independent value.  Use the following formula to obtain the correct value:

{\footnotesize \begin{verbatim}
    value = rex / (2.0 * pi * frequency) ** 2
\end{verbatim}}

where:

\begin{itemize}
  \item[]rex is the chemical\index{chemical exchange} exchange value for the current frequency.
  \item[]frequency is the proton frequency corresponding to the data.
\end{itemize}

\subsubsection{Reduced spectral density mapping parameters}

Please see Table~\ref{table: J(w) parameter value setting with defaults} on page~\pageref{table: J(w) parameter value setting with defaults}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Reduced spectral density mapping parameter value setting.]{Reduced spectral density mapping parameter value setting.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Default \\
\midrule
j0 & Spectral density value at 0 MHz - $J(0)$ & None \\
jwx & Spectral density value at the frequency of the heteronucleus - $J(\omega_X)$ & None \\
jwh & Spectral density value at the frequency of the proton - $J(\omega_H)$ & None \\
csa & Chemical shift anisotropy (unitless) & -0.000172 \\
\bottomrule
\\[-5pt]
\label{table: J(w) parameter value setting with defaults}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


In reduced spectral density mapping,\index{map} the CSA value must be set prior to the calculation of spectral density values.

\subsubsection{Consistency testing parameters}

Please see Table~\ref{table: consistency testing parameter value setting with defaults} on page~\pageref{table: consistency testing parameter value setting with defaults}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Consistency testing parameter value setting.]{Consistency testing parameter value setting.}
\begin{tabular}{lll}
\\[-5pt]
\toprule
Name & Description & Default \\
\midrule
j0 & Spectral density value at 0 MHz (from Farrow et al. (1995) JBNMR, 6: 153-162) & None \\
f\_eta & Eta-test (from Fushman et al. (1998) JACS, 120: 10947-10952) & None \\
f\_r2 & R2-test (from Fushman et al. (1998) JACS, 120: 10947-10952) & None \\
csa & Chemical shift anisotropy (unitless) & -0.000172 \\
orientation & Angle between the 15N-1H vector and the principal axis of the 15N chemical shift tensor & 15.7 \\
tc & The single global correlation time estimate/approximation & 1.3e-08 \\
\bottomrule
\\[-5pt]
\label{table: consistency testing parameter value setting with defaults}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


In consistency testing, the CSA value, angle\index{angles} Theta (\quotecmd{orientation}) and global correlation\index{correlation time} time must be set prior to the calculation of consistency functions.

\subsubsection{N-state model parameters}

Please see Table~\ref{table: N-state parameter value setting with defaults} on page~\pageref{table: N-state parameter value setting with defaults}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[N-state model parameter value setting.]{N-state model parameter value setting.}
\begin{tabular}{llll}
\\[-5pt]
\toprule
Name & Description & Default & Type \\
\midrule
Axx & The Axx component of the alignment tensor & None & float \\
Ayy & The Ayy component of the alignment tensor & None & float \\
Axy & The Axy component of the alignment tensor & None & float \\
Axz & The Axz component of the alignment tensor & None & float \\
Ayz & The Ayz component of the alignment tensor & None & float \\
probs & The probabilities of each state & 0.0 & list \\
alpha & The $\alpha$ Euler angles (for the rotation of each state) & 0.0 & list \\
beta & The $\beta$ Euler angles (for the rotation of each state) & 0.0 & list \\
gamma & The $\gamma$ Euler angles (for the rotation of each state) & 0.0 & list \\
paramagnetic\_centre & The paramagnetic centre & None & list \\
\bottomrule
\\[-5pt]
\label{table: N-state parameter value setting with defaults}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states.  To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be given as the index argument.  So the Euler\index{Euler angles} angle\index{angles} $\gamma$ of the third state is specified using the parameter name \quotecmd{gamma} and index of 2.

\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameter value setting with defaults} on page~\pageref{table: dispersion parameter value setting with defaults}.

\begin{table*}
\begin{scriptsize}
\begin{center}
\caption[Relaxation dispersion parameter value setting.]{Relaxation dispersion parameter value setting.}
\begin{tabular}{llll}
\\[-5pt]
\toprule
Name & Description & Default & Type \\
\midrule
r2eff & The effective transversal relaxation rate & 10.0 & dict \\
i0 & The initial intensity & 10000.0 & dict \\
r1 & The longitudinal relaxation rate & 2.0 & dict \\
r2 & The transversal relaxation rate & 10.0 & dict \\
r2a & The transversal relaxation rate for state A in the absence of exchange & 10.0 & dict \\
r2$b$ & The transversal relaxation rate for state B in the absence of exchange & 10.0 & dict \\
pA & The population for state A & 0.9 & float \\
pB & The population for state B & 0.5 & float \\
pC & The population for state C & 0.5 & float \\
phi\_ex & The $\phi$\_ex = pA.pB.dw**2 value (ppm\^{}2) & 5.0 & float \\
phi\_ex\_B & The fast exchange factor between sites A and B (ppm\^{}2) & 5.0 & float \\
phi\_ex\_C & The fast exchange factor between sites A and C (ppm\^{}2) & 5.0 & float \\
padw2 & The pA.dw**2 value (ppm\^{}2) & 1.0 & float \\
dw & The chemical shift difference between states A and B (in ppm) & 1.0 & float \\
dw\_AB & The chemical shift difference between states A and B for 3-site exchange (in ppm) & 1.0 & float \\
dw\_AC & The chemical shift difference between states A and C for 3-site exchange (in ppm) & 1.0 & float \\
dw\_BC & The chemical shift difference between states B and C for 3-site exchange (in ppm) & 1.0 & float \\
dwH & The proton chemical shift difference between states A and B (in ppm) & 1.0 & float \\
dwH\_AB & The proton chemical shift difference between states A and B for 3-site exchange (in ppm) & 1.0 & float \\
dwH\_AC & The proton chemical shift difference between states A and C for 3-site exchange (in ppm) & 1.0 & float \\
dwH\_BC & The proton chemical shift difference between states B and C for 3-site exchange (in ppm) & 1.0 & float \\
kex & The exchange rate & 1000.0 & float \\
kex\_AB & The exchange rate between sites A and B for 3-site exchange with kex\_AB = $k$\_AB + $k$\_BA (rad.s\^{}-1) & 1000.0 & float \\
kex\_AC & The exchange rate between sites A and C for 3-site exchange with kex\_AC = $k$\_AC + $k$\_CA (rad.s\^{}-1) & 1000.0 & float \\
kex\_BC & The exchange rate between sites B and C for 3-site exchange with kex\_BC = $k$\_BC + $k$\_CB (rad.s\^{}-1) & 1000.0 & float \\
kB & Approximate chemical exchange rate constant between sites A and B (rad.s\^{}-1) & 1000.0 & float \\
kC & Approximate chemical exchange rate constant between sites A and C (rad.s\^{}-1) & 1000.0 & float \\
tex & The time of exchange (tex = 1/kex) & 0.001 & float \\
k\_AB & The exchange rate from state A to state B & 2.0 & float \\
k\_BA & The exchange rate from state B to state A & 1000.0 & float \\
\bottomrule
\\[-5pt]
\label{table: dispersion parameter value setting with defaults}
\end{tabular}
\end{center}
\end{scriptsize}
\end{table*}


Any of the relaxation\index{relaxation} dispersion parameters which are of the \quotecmd{float} type can be set.  Note that setting values for parameters which are not part of the model will have no effect.

\subsubsection{Frame order parameters}

Please see Table~\ref{table: frame order parameters} on page~\pageref{table: frame order parameters}.

\subsubsection{Prompt examples}

To set the parameter values for the current data pipe to the default values, for all spins, type:

\begin{lstlisting}[numbers=none]
relax> value.set()
\end{lstlisting}


To set the parameter values of residue 10, which is in the current model-free data pipe \quotecmd{m4} and has the parameters \{$S^2$, $\tau_e$, $R_{ex}$\}, the following can be used.  $R_{ex}$ term is the value for the first given field strength.

\begin{lstlisting}[numbers=none]
relax> value.set([0.97, 2.048*1e-9, 0.149], spin_id=':10')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.set(val=[0.97, 2.048*1e-9, 0.149], spin_id=':10')
\end{lstlisting}


To set the CSA value of all spins to the default value, type:

\begin{lstlisting}[numbers=none]
relax> value.set(param='csa')
\end{lstlisting}


To set the CSA value of all spins to -172 ppm, type:

\begin{lstlisting}[numbers=none]
relax> value.set(-172 * 1e-6, 'csa')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.set(val=-172 * 1e-6, param='csa')
\end{lstlisting}


To set the NH bond\index{bond length} length of all spins to 1.02 \AA, type:

\begin{lstlisting}[numbers=none]
relax> value.set(1.02 * 1e-10, 'r')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.set(val=1.02 * 1e-10, param='r')
\end{lstlisting}


To set both the bond\index{bond length} length and the CSA value to the default values, type:

\begin{lstlisting}[numbers=none]
relax> value.set(param=['r', 'csa'])
\end{lstlisting}


To set both $\tau_f$ and $\tau_s$ to 100 ps, type:

\begin{lstlisting}[numbers=none]
relax> value.set(100e-12, ['tf', 'ts'])
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.set(val=100e-12, param=['tf', 'ts'])
\end{lstlisting}


To set the $S^2$ and $\tau_e$ parameter values of residue 126, Ca spins to 0.56 and 13 ps, type:

\begin{lstlisting}[numbers=none]
relax> value.set([0.56, 13e-12], ['s2', 'te'], ':126@Ca')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.set(val=[0.56, 13e-12], param=['s2', 'te'], spin_id=':126@Ca')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.set(val=[0.56, 13e-12], param=['s2', 'te'], spin_id=':126@Ca')
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{value\-.write} \label{uf: value.write}
\includegraphics[bb=0 0 18 18]{graphics/relax_icons/128x128/value} \hfill \includegraphics[bb=0 0 18 18]{graphics/oxygen_icons/128x128/actions/document-save}

\subsubsection{Synopsis}

Write\index{write} spin specific parameter values to a file.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{value.\linebreak[0]write}(\linebreak[0]param=\linebreak[0]None, file=\linebreak[0]None, dir=\linebreak[0]None, scaling=\linebreak[0]1.0, comment=\linebreak[0]None, bc=\linebreak[0]False, force=\linebreak[0]False)}
\end{flushleft}


\subsubsection{Keyword arguments}

\hspace{3 mm}\keyword{param:}  The parameter.

\hspace{3 mm}\keyword{file:}  The name of the file.

\hspace{3 mm}\keyword{dir:}  The directory name.

\hspace{3 mm}\keyword{scaling:}  The factor to scale parameters by.

\hspace{3 mm}\keyword{comment:}  Text which will be added to the start of the file as comments.  All lines will be prefixed by \quotecmd{\# }.

\hspace{3 mm}\keyword{bc:}  A flag which if True will cause the back calculated values to be written to file rather than the actual data.

\hspace{3 mm}\keyword{force:}  A flag which, if set to True, will cause the file to be overwritten.


\subsubsection{Description}

The values corresponding to the given parameter will be written to file.  The scaling argument can be used to scale the parameter values.  This can be useful for example in the case of the model-free $R_{ex}$ parameter to obtain the spectrometer dependent value from the omega\_ex field strength independent internal value.  Or to scale correlation\index{correlation time} times from seconds down to nanosecond or picosecond timescales.

\subsubsection{Relaxation curve fitting parameters}

Please see Table~\ref{table: curve-fit parameters} on page~\pageref{table: curve-fit parameters}.

\subsubsection{Steady-state NOE parameters}

Please see Table~\ref{table: NOE parameters} on page~\pageref{table: NOE parameters}.

\subsubsection{Model-free parameters}

Please see Table~\ref{table: model-free parameter writing} on page~\pageref{table: model-free parameter writing}.

For model-free theory it is assumed that $R_{ex}$ values are scaled quadratically with field strength.  The values will be very small as they will be written out as a field strength independent value.  Hence use the following formula to convert the value to that expected for a given magnetic field strength:

{\footnotesize \begin{verbatim}
    Rex = value * (2.0 * pi * frequency) ** 2
\end{verbatim}}

The frequency is that of the proton in Hertz.

\subsubsection{Reduced spectral density mapping parameters}

Please see Table~\ref{table: J(w) parameters} on page~\pageref{table: J(w) parameters}.

\subsubsection{Consistency testing parameters}

Please see Table~\ref{table: consistency testing parameters} on page~\pageref{table: consistency testing parameters}.

\subsubsection{Relaxation dispersion parameters}

Please see Table~\ref{table: dispersion parameters} on page~\pageref{table: dispersion parameters}.

\subsubsection{Prompt examples}

To write\index{write} the CSA values to the file \quotecmd{csa.txt}, type one of:

\begin{lstlisting}[numbers=none]
relax> value.write('csa', 'csa.txt')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.write(param='csa', file='csa.txt')
\end{lstlisting}


To write\index{write} the NOE values to the file \quotecmd{noe}, type one of:

\begin{lstlisting}[numbers=none]
relax> value.write('noe', 'noe.out')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.write(param='noe', file='noe.out')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.write(param='noe', file='noe.out')
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.write(param='noe', file='noe.out', force=True)
\end{lstlisting}


To write\index{write} the model-free $R_{ex}$ values scaled to 600 MHz to the file \quotecmd{rex\_600}, type one of:

\begin{lstlisting}[numbers=none]
relax> value.write('rex', 'rex_600', scaling=(2.0*pi*600e6)**2)
\end{lstlisting}

\begin{lstlisting}[numbers=none]
relax> value.write(param='rex', file='rex_600', scaling=(2.0*pi*600e6)**2)
\end{lstlisting}




\pagebreak[4]
\rule{\columnwidth}{1pt}
\vspace{-20pt}
\subsection{vmd\-.view} \label{uf: vmd.view}
\hfill 

\subsubsection{Synopsis}

View the structures loaded into the relax data store using VMD.


\subsubsection{Defaults}

\begin{flushleft}
\textsf{\textbf{vmd.\linebreak[0]view}(\linebreak[0])}
\end{flushleft}


\subsubsection{Description}

This will launch VMD with all of the structures loaded into the relax data store.

\subsubsection{Prompt examples}

\begin{lstlisting}[numbers=none]
relax> vmd.view()
\end{lstlisting}


