Author: bugman
Date: Tue Aug 28 15:32:04 2012
New Revision: 17356
URL: http://svn.gna.org/viewcvs/relax?rev=17356&view=rev
Log:
Created a new chapter for the relax user manual titled 'The relax data model'.
Added:
trunk/docs/latex/data_model.tex
Modified:
trunk/docs/latex/relax.tex
Added: trunk/docs/latex/data_model.tex
URL:
http://svn.gna.org/viewcvs/relax/trunk/docs/latex/data_model.tex?rev=17356&view=auto
==============================================================================
--- trunk/docs/latex/data_model.tex (added)
+++ trunk/docs/latex/data_model.tex Tue Aug 28 15:32:04 2012
@@ -1,0 +1,228 @@
+% The relax data model.
+%%%%%%%%%%%%%%%%%%%%%%%
+
+\chapter{The relax data model}
+
+
+% Introduction.
+%%%%%%%%%%%%%%%
+
+\section{Introduction}
+
+To begin to understand how to use relax, a basic comprehension of the relax
data model is needed. The data model includes the concepts of the relax data
store, the data pipes, the molecule, residue and spin data structures and the
interatomic data containers. These concepts are independent of the specific
analyses presented in the next chapters and are important for setting up
relax.
+
+
+
+% The relax data store.
+%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{The relax data store}
+
+All permanent data handled by relax is kept in a structure known as the
relax data store. This structure is initialised when relax is launched. The
data store is primarily organised into a series of objects known as data
pipes, and all usage of relax revolves around the flow of information in
these data pipes.
+
+
+% Data pipes.
+%~~~~~~~~~~~~
+
+\subsection{Data pipes}
+
+\begin{figure*}[h]
+\includegraphics[width=2cm, bb=0 0 567 567]{graphics/wizards/pipe.eps.gz}
+\end{figure*}
+
+The first thing one must do when relax is launched is to create a data pipe.
When using the GUI, a base data pipe will be created when opening one of the
automatic analyses via the analysis selection window (see figure~\ref{fig:
screenshot: analysis wizard} on page~\pageref{fig: screenshot: analysis
wizard}). This will also create a data pipe bundle for the analysis
(\textit{vide infra}). Alternatively the data pipe editor window can be used
to create data pipes (see figure~\ref{fig: screenshot: pipe editor} on
page~\pageref{fig: screenshot: pipe editor}). For the prompt/scripting
modes, or the \texttt{`User functions $\to$ pipe $\to$ create'} menu entry, a
data pipe can be initialised by specifying the unique name of the data pipe
and the data pipe type:
+
+\example{pipe.create(pipe\_name=`NOE 1200 MHz', pipe\_type=`noe')}
+
+A number of relax operations will also create data pipes by merging a group
of pipes or branching pre-existing pipes. See section~\ref{sect: the data
pipe} on page~\pageref{sect: the data pipe} for additional details.
+
+All data not associated with spin systems will be stored in the base data
pipe. This includes information such as global optimisation statistics,
diffusion tensors, alignment tensors, 3D structural data, the molecule,
residue and spin container data structure and the interatomic data
containers. One data pipe from the set will be defined as being the current
data pipe, and all operations in relax will effect data from this pipe. The
\texttt{`pipe.switch'} user function in all UI modes can be used to change
which pipe is the current data pipe. In the GUI, switching between analysis
tabs will automatically switch the current data pipe to match the analysis
being displayed.
+
+
+
+% Data pipe bundles.
+%~~~~~~~~~~~~~~~~~~~
+
+\subsection{Data pipe bundles}
+
+\begin{figure*}[h]
+\includegraphics[width=2cm, bb=14 14 175
175]{graphics/wizards/pipe_bundle.eps.gz}
+\end{figure*}
+
+Related data pipes can be grouped into a `bundle'. For example if the data
pipes \texttt{`sphere'}, \texttt{`oblate spheroid'}, \texttt{`prolate
spheroid'}, and \texttt{`ellipsoid'} preexist, these can be grouped into a
bundle called \texttt{`diffusion tensors'} with the following series of user
function calls:
+
+\begin{exampleenv}
+pipe.bundle(bundle=`diffusion tensors', pipe=`sphere') \\
+pipe.bundle(bundle=`diffusion tensors', pipe=`oblate spheroid') \\
+pipe.bundle(bundle=`diffusion tensors', pipe=`prolate spheroid') \\
+pipe.bundle(bundle=`diffusion tensors', pipe=`ellipsoid')
+\end{exampleenv}
+
+The data pipe editor window of the GUI can also be used to bundle pipes
together (see figure~\ref{fig: screenshot: pipe editor} on page~\pageref{fig:
screenshot: pipe editor}).
+
+
+
+% Molecule, residue, and spin containers.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Molecule, residue, and spin containers}
+
+Within a data pipe is the molecule, residue, and spin container data
structure. Data which is specific to a given nucleus is stored in a special
spin container structure. This includes relaxation data, model-free
parameters, reduced spectral density mapping values, spin specific
optimisation parameters, chemical shift tensor information, pseudo-contact
shift values, etc. The spin containers can be created from 3D structural
data or a sequence file, as described in the next two sections, or manually
built.
+
+
+
+% Molecule containers.
+%~~~~~~~~~~~~~~~~~~~~~
+
+\newpage
+\subsection{Molecule containers}
+
+\begin{figure*}[h]
+\includegraphics[width=2cm, bb=0 0 567 567]{graphics/wizards/molecule.eps.gz}
+\end{figure*}
+
+The spin containers are part of a nested set of containers, and are
graphically depicted in the spin viewer window of the GUI in figure~\ref{fig:
screenshot: spin viewer} on page~\pageref{fig: screenshot: spin viewer}. As
can be seen from the figure, the top level holds a single molecular
container. Multiple molecular containers can be present if the study is of a
molecular complex. Using the GUI menus or the prompt/scripting mode,
molecule containers can be manually created with the user function:
+
+\example{molecule.create(mol\_name=`glycerol', mol\_type=`organic molecule')}
+
+In the spin viewer window of the GUI, right clicking on the `Spin system
information' will pop up a menu with an entry for adding molecule containers.
Right clicking on molecule containers will show a pop up menu with an entry
for permanently deleting the container.
+
+
+
+% Residue containers.
+%~~~~~~~~~~~~~~~~~~~~
+
+\subsection{Residue containers}
+
+\begin{figure*}[h]
+\includegraphics[width=2cm, bb=0 0 567 567]{graphics/wizards/residue.eps.gz}
+\end{figure*}
+
+Nested within the molecule containers are residue containers. These are
graphically depicted in the spin viewer window (see figure~\ref{fig:
screenshot: spin viewer} on page~\pageref{fig: screenshot: spin viewer}).
Each molecule container can possess multiple residues. These require either
a unique residue number or unique residue name. For organic molecules where
the residue concept is meaningless, all spin containers can be held within a
single unnamed and unnumbered residue container. Using the GUI menus or the
prompt/scripting mode, residue containers can be manually created with the
user function:
+
+\example{residue.create(res\_num=`-5', res\_name=`ASP')}
+
+Alternatively residues can be added in the spin viewer window from the pop
up menu when right clicking on molecule containers, and can be deleted via
the pop up menu when right clicking on the residue to delete.
+
+
+
+% Spin containers.
+%~~~~~~~~~~~~~~~~~
+
+\subsection{Spin containers}
+
+\begin{figure*}[h]
+\includegraphics[width=2cm, bb=0 0 567 567]{graphics/wizards/spin.eps.gz}
+\end{figure*}
+
+Spin containers are nested within a residue container (again graphically
depicted in the spin viewer window in figure~\ref{fig: screenshot: spin
viewer} on page~\pageref{fig: screenshot: spin viewer}). Multiple spin
containers can exist per residue. This allows, for example, a single
model-free analysis simultaneously on the backbone nitrogen spins, side-chain
tryptophan indole nitrogen spins and alpha carbon spins. Or, for example,
studying the pseudocontact shifts for all nitrogen, carbon and proton spins
in the molecule simultaneously.
+
+Spin containers can be manually added via the \texttt{`spin.create'} user
function in the GUI or prompt/scripting mode:
+
+\example{spin.create(spin\_num=`200', spin\_name=`NE1')}
+
+The spin viewer window can also be used by right clicking on residue
containers.
+
+
+
+% Spin ID strings.
+%~~~~~~~~~~~~~~~~~
+
+\subsection{Spin ID strings}
+
+Spins are often identified in relax using their ID strings. The spin ID
strings follow the basic construct found in a number of other NMR softwares
such as MOLMOL. The identification string is composed of three components:
+
+\begin{itemize}
+\item The molecule ID token beginning with the \texttt{`\#'} character,
+\item The residue ID token beginning with the \texttt{`:'} character,
+\item The atom or spin system ID token beginning with the \texttt{`@'}
character.
+\end{itemize}
+
+Each token can be composed of multiple elements -- one per spin -- separated
by the \texttt{`,'} 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 \texttt{`-'} character. Negative numbers are
supported. The full ID string specification is \texttt{`\#<mol\_name>
:<res\_id>[, <res\_id>[, <res\_id>, ...]] @<atom\_id>[, <atom\_id>[,
<atom\_id>, ...]]'}, where the token elements are \texttt{`<mol\_name>'}, the
name of the molecule, \texttt{`<res\_id>'}, the residue identifier which can
be a number, name, or range of numbers, \texttt{`<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 \texttt{`\#'} character then
all molecules will match the string. If only the molecule ID component is
specified, then all spins of the molecule will match.
+
+Regular expression can, in some instances, be used to select spins. For
example the string \texttt{`@H*'} will select the protons `H', `H2' and `H98'.
+
+
+
+% Interatomic data containers.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newpage
+\section{Interatomic data containers}
+
+\begin{figure*}[h]
+\includegraphics[width=3cm, bb=14 14 95
148]{graphics/wizards/dipole_pair/NH_dipole_pair.eps.gz}
+\end{figure*}
+
+Separate from the spin containers, yet strongly linked to them, are the
interatomic data containers. These containers are grouped together within
the same data pipe as the spins they point to. These define interactions
between two spins located anywhere within the molecule, residue and spin
nested data structure. These are automatically created when reading in data
defined between two spins such as RDCs and NOE distance constraints. They
can also be created using the \texttt{`dipole\_pair.define'} user function:
+
+\example{dipole\_pair.define(spin\_id1=`:2@N', spin\_id2=`:2@H')}
+
+As the interatomic data container concept is relatively new, how they are
created and handled is likely to evolve and change in the future.
+
+
+% Structural data.
+%%%%%%%%%%%%%%%%%%
+
+\section{Structural data}
+
+\begin{figure*}[h]
+\includegraphics[width=3cm, bb=14 14 215
293]{graphics/wizards/n_state_model.eps.gz}
+\end{figure*}
+
+3D structural data is stored at the level of the current data pipe. This
data is completely separate from the molecule, residue and spin data
structure. However the structural data can be used to generate the spin
containers. For example, assuming a data pipe is already present:
+
+\begin{exampleenv}
+\# Load the PDB file. \\
+structure.read\_pdb(`1f3y.pdb') \\
+ \\
+\# Set up the 15N and 1H spins. \\
+structure.load\_spins(`@N', ave\_pos=True) \\
+structure.load\_spins(`@H', ave\_pos=True) \\
+spin.isotope(`15N', spin\_id=`@N') \\
+spin.isotope(`1H', spin\_id=`@H')
+\end{exampleenv}
+
+The \texttt{`structure.read\_pdb'} user function will load the structural
data into the current data pipe, and the \texttt{`structure.load\_spins'}
user function will create the molecule, residue, and spin containers as
needed. This will also load atomic position information into the matching
spin containers. The \texttt{`spin.isotope'} user function is required for
certain analysis types.
+
+These operations are also available in the GUI via the spin viewer window.
Clicking on the `Load spins' button or the `Load spins' menu entry from the
right click pop up menu (see figure~\ref{fig: screenshot: spin viewer} on
page~\pageref{fig: screenshot: spin viewer}) will launch a wizard which
consists of the above user functions (excluding the \texttt{`spin.isotope'}
user function).
+
+Note that if structural data from the PDB is used to generate the spin
containers, then all subsequent data loaded into relax must follow the exact
naming convention from the PDB file. Automatic residue name matching (i.e.
`GLY' = `Gly' = `gly' = `G') is currently not supported.
+
+
+
+% Sequence file.
+%%%%%%%%%%%%%%%%
+
+\section{Sequence file}
+
+\begin{figure*}[h]
+\includegraphics[width=2cm, bb=0 0 567 567]{graphics/wizards/sequence.eps.gz}
+\end{figure*}
+
+Alternatively to setting up the molecule, residue, and spin containers via
3D structural data, a plain text columnar formatted file can be used. This
is useful for when no 3D structure exists for the molecule. For example:
+
+\begin{exampleenv}
+\# Set up the 15N spins. \\
+sequence.read(file=`noe.500.out', mol\_name\_col=None, res\_num\_col=1,
res\_name\_col=2, spin\_num\_col=None, spin\_name\_col=None) \\
+spin.name(`N') \\
+spin.element(element=`N', spin\_id=`@N') \\
+spin.isotope(`15N', spin\_id=`@N')
+\end{exampleenv}
+
+Here the molecule, residue, and spin information is extracted from the
\texttt{`noe.500.out'} file. The \texttt{`sequence.read'} user function call
assumes that only residue information is present in the file, with the
residue number and name in the first and second columns respectively. The
file can contain columns for the molecule name, the residue name and number,
and the spin name and number in any order. The subsequent user functions in
the above example are used to set up the spin containers appropriately for a
model-free analysis. These are not required in the automatic analysis of GUI
as these user functions will be presented to you when adding relaxation data,
or when clicking on the heteronucleus and proton buttons (`X isotope' and `H
isotope').
+
+If 3D structures are to be used later on in the analysis, then the residue
and spin names and numbers must either be blank or match the notation used in
the 3D structure file.
+
+In the GUI, the creation of molecule, residue, and spin containers from a
sequence file is also available via the `Load spins' wizard within the spin
viewer window (\textit{vide supra}).
+
+
+
+% The next steps.
+%%%%%%%%%%%%%%%%%
+
+\section{The next steps}
+
+This chapter presented the basics of setting up the relax data store,
concepts which are needed for all analysis types built into relax. The next
chapters will introduce specific analyses types -- the steady-state NOE,
$\Rone$ and $\Rtwo$ relaxation curve-fitting, and the automated full
model-free analysis protocol of \citet{dAuvergneGooley07,dAuvergneGooley08b}
-- which build on the ideas introduced here.
Modified: trunk/docs/latex/relax.tex
URL:
http://svn.gna.org/viewcvs/relax/trunk/docs/latex/relax.tex?rev=17356&r1=17355&r2=17356&view=diff
==============================================================================
--- trunk/docs/latex/relax.tex (original)
+++ trunk/docs/latex/relax.tex Tue Aug 28 15:32:04 2012
@@ -201,6 +201,7 @@
\include{intro}
\include{install}
\include{infrastruct}
+\include{data_model}
\include{noe}
\include{curvefit}
\include{model-free}
r17356 - in /trunk/docs/latex: data_model.tex relax.tex