============================
Molecule : Isotope Labelling
============================


.. |pulldown| image:: ../images/pulldown.png
   :align: bottom


.. |check| image:: ../images/check.png
   :align: bottom


.. |radio| image:: ../images/radio.png
   :align: bottom


.. |float| image:: ../images/float.png
   :align: bottom


.. |int| image:: ../images/int.png
   :align: bottom


.. |entry| image:: ../images/entry.png
   :align: bottom


.. |button| image:: ../images/button.png
   :align: bottom


.. |ramp| image:: ../images/ramp.png
   :align: bottom


.. |selector| image:: ../images/selector.png
   :align: bottom


**Setup Molecule Isotope Labelling Patterns**

This popup is used to specify the isotopic incorporation of molecules in
different samples. This is typically done in the earlier stages of a project,
before the labelling information is required for assignment etc.

Although the user can employ the standard isotope labelling schemes when
performing operations in Analysis, the setup of molecular isotope patterns
allows a greater level of control and allows the isotopic labelling
to be automatically set according to context. The standard labelling schemes,
which are also used as references for molecule specific patterns, may be
created and edited via the `Reference Isotope Schemes`_ popup.

A given molecule can be represented by several different samples, each with
distinct isotope patterns. Each sample is associated with the NMR experiments
(and hence spectra) that were performed on that sample. When assigning a peak,
if the peak's experiment has been linked to a sample with labelling
information then the isotopic proportions hat should be considered are
automatically known.

**Labelled Molecules**

The first tab allows the user to setup the samples (labelled versions) of
each molecule that are available. Each molecule version will appear as a row
in the top table. The user should set the "Experiments" of each sample to
specify which NMR experiments used that labelled version on the molecule.

Each sample of a molecule may refer to only a single labelled version or a
mixture of different labelled forms (of the same molecule), e.g. both fully
labelled and unlabelled. These different forms are referred to as "Patterns"
and can be used in any proportion, to create a sample with a mixed
composition.

The Sample Composition table allows the user to add patterns (labelled
versions of the molecule) to the currently selected mixture. Often  the user
will add a single pattern based on a standard labelling scheme; this is the
simplest setup. However, any number of patterns may be added and their
proportions in a mixed sample may be adjusted by changing the "weight" of
each. It is possible for a given pattern to be re-used in a number of
different samples. For example a natural abundance version of the molecule may
appear on its own in a sample, but as a mixture together with an enriched
pattern in another sample.

**Labelling Patterns**

The second tab allows the user to specify any deviations of a labelling
pattern (version of a molecule) from a standard labelling scheme. An initial
pattern will contain residues that are associated with an initial scheme; the
residues isotopomers are set to be the same as in this scheme. However, the
user may adjust any of the residues in the pattern to use a different scheme.
Here the term "isotopomer" is used to refer to a single isotope pattern of an
individual residue, and there may be several such patterns present for a given
type of residue, so that a polymer molecule will generally be a random mixture
of the different individual forms.

A residue within a pattern may deviate from a standard scheme by adjusting the
proportions of the different isotopomers; this is set via the "Weighting" value
after selecting the required isotopomer in the pulldown menu. Adjusting these
weightings preserves the internal correlations between atoms within
isotopomers; only the relative abundance of separate isotopomer forms is
affected.

The individual atomic incorporations for a residue may be adjusted if
the "Isotopomer" pulldown is set to "Override Scheme", but this looses any
atom pair information that was specified via an isotopomer; only average
incorporations are set. For example there may be no single isotopomer with
both CA and CB labelled at the same time, even though the average shows
incorporation for both sites.

**Examples**

These examples illustrate how to setup various kinds of isotope labelling
"sample", starting from a project with molecule specifications but without
existing labelling information. After creation each sample should be
associated with the required NMR experiments (which were run on that sample),
by double clicking in the "Experiments" column  of the Labelled Samples table
and checking the required options.

*Simple Single Scheme Labelling*

As an example of specifying a molecule with a single pattern from the standard
"1,3 13C Glycerol" scheme, the user would first select the required molecule
(to the right of "For molecule") and press [New Sample].  In the lower right
pulldown menu the user then selects "13Glycerol" and then presses [New Pattern
From Scheme]. The molecule in this sample will have the labelling specified by
one pattern made according to the selected scheme.

*Mixture of Labelled and Unlabelled*

As an example of a mixture, say that a sample of a molecule was composed of a
1:3 ratio of fully labelled and unlabelled molecules (two different patterns
in a mixture). The user would make one sample for the molecule using [New
Sample], then setup the Sample Composition to have two patterns, one based on a
uniform labelling scheme (e.g. "uni_15N13C2H") and one for the "NatAbun"
scheme; select each scheme in the lower right pulldown menu and for each make
[New Pattern From Scheme]. Labelling patterns "A" and "B" will be created. For
the pattern that corresponds to the "NatAbun" basis scheme set the  weight to
3 (the weight for the other pattern will remain at 1.0). This labelled sample
specification is nor ready to used because the individual residues do not need
any further adjustment.

*Labelling a Specific Residue*

As an example of a molecule that is unlabelled except at one specific sequence
position, where the residue has 15N, the user would first make a New Sample
for the required molecule and add a New Pattern from the "NatAbun" scheme;
this will make Pattern "A".

The user should then go to the second "Labelling Patterns" tab (at the top) and
ensure that the correct molecule and Pattern "A" are selected in the upper
pulldown menus. The sequence of the molecule will be displayed in the upper
table. To set the labelling for the only labelled residue, the user scrolls
down until the residue is visible, then selects the row for the residue in the
table (highlighting the row). Next, in the pulldown menu to the bottom right
of the residue table, the user selects the scheme "uni_15N" and then presses
the adjacent [Set Residue Composition From Scheme:]. The residue will now be listed in
the table as using the "uni_15N", and not "NatAbun" like all the others.

.. _`Reference Isotope Schemes`: IsotopeSchemeEditor.html



Main Panel
==========

|button| **Clone**: Clone popup window

|button| **Help**: Show popup help document

|button| **Close**: Close popup

Labelled Molecules
==================

Setup isotope labelling at the molecule level; the versions of a present molecule in different samples

Labelled Samples
~~~~~~~~~~~~~~~~


====================  ===========================================================================================================================
**Table 1**
-------------------------------------------------------------------------------------------------------------------------------------------------
          *Molecule*  The name of the molecule (sequence template) that the isotope labelled sample refers to 
            *Sample*  The serial number of the sample (mixture of labelling patterns) in the CCPN project 
       *Sample Name*  A user editable name for the isotope labelled sample  *(Editable)*
       *Experiments*  The NMR experiments that are asscociated with the isotope labelling sample; can be set at any time by the user  *(Editable)*
*Labelling Patterns*  One or more labelling patterns (versions of a molecyle), in diifferent proportions, constiture the sample 
            *Chains*  The molecular system chains (assignable entities in a complex) that are associated with the labelled molecule 
          *Sequence*  Part of the residue sequence of the labelled molecule 
          *Mol Mass*  The estimated average molecular mass of the molecule (albeit a mixture of different patterns) 
====================  ===========================================================================================================================



|button| **Delete Sample**: Delete the selected isotope labelling molecule specification

|button| **New Sample**: Make a new, intially bank, isotope labelled sample, to which molecule labelling patterns may be added

|pulldown| **For molecule**: Selects which molecular sequence template to use when making a new specifcation of an isotope labelled sample

Sample Composition
~~~~~~~~~~~~~~~~~~


===================  ==================================================================================================================================================
**Table 2**
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
*Labelling Pattern*  A code letter for a specific labelling pattern version of the molecule sample 
     *Basis Scheme*  The standard isotope labelling scheme on which the labelling pattern is primarily based (for mosed residue) 
           *Weight*  The relative weighting of this labelling patterns compated to other patterns in the sample sample; for a mixture of molecule versions  *(Editable)*
    *% Composition*  The relative composition of this pattern compated to others in the sample 
         *Mol Mass*  The estimated molecular masss of the version of the isotopic molecule represented by the pattern 
===================  ==================================================================================================================================================



|button| **Remove Pattern**: Remove the selected molecule labelling pattern from the sample/mixture; the pattern is deleted if it is no longer used in any sample

|button| **Edit Pattern**: Edit the selected molecule labelling pattern (isotopic version), in terms of residue and atom incorporations

|button| **Add Existing Pattern**: Add a molecule labelling pattern to the current sample specification, using a pre-constructed pattern

|pulldown| ***None***: Selects which extsing molecule labelling pattern to add to the selecte sample

|button| **New Pattern From Scheme**: make a complete new isotope labelling pattern for the molecule using the selected isitope labelling scheme

|pulldown| ***None***: Selects which standard isotope labelling scheme to use as a template to make a new molecule specific labelling pattern

Labelling Patterns
==================

Setup the specific residue and atom labelling patterns in a given molecule version

|pulldown| **Molecule**: Selects which molecule to view the residue labelling patterns for

|pulldown| **Pattern**: Selects which residue labelling to view from those available for the selected molecule

|button| **New Pattern From Scheme**: make a new labelling pattern (isotope version of the molecule) using the selected standard labelling scheme

|pulldown| ***None***: Selects which standardised isotope labelling scheme to use as a template for creating a to make a new molecule specific labelling pattern

Residue Pattern
~~~~~~~~~~~~~~~


==============  ======================================================================================================================================
**Table 3**
------------------------------------------------------------------------------------------------------------------------------------------------------
      *Seq Id*  The sequence ID number of the labelled residue in the molecule; a separate numbering system to the numbering in chains 
*Residue Code*  The code of the residue identifying which type it is 
     *Schemes*  The names of the standard isotope labelling schemes on which the residues labelling is based within this specific pattern 
 *Isotopomers*  Tne numbers of the isotopomer versions of this residue that specify labelling; from the standard scheme 
==============  ======================================================================================================================================



|button| **Set Natural Abundance**: Set the selected residue labelling to have natural abundance isotopic incorporation labels.

|button| **Set Residue Composition From Scheme**: Set the selected residue to have labelling based upon isotopomers from the selected standard scheme

|pulldown| ***None***: Selects which standardised isotope labelling scheme to base the residues isotopomer labelling upon

Residue Composition
~~~~~~~~~~~~~~~~~~~


|pulldown| **Chem Element**: Selects which chemical element to display atomic isotope incorporation levels for

|check| **Show Exchangeable**: Sets whether to display water exchangeable atoms in the atom isotope table

|pulldown| **Isotopomer**: Selects which isotopomer version, from those set for the residue to show atom istopes for; can be set to override the schem istopomers

|float| **1.0**: Specifies what relative weighing the selected residue isotopomer has compared to others for the same residue

===============  ===================================================================================================================================================
**Table 4**
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
         *Atom*  The name of the atom within its residue, for which to set isotopic abundances, within the selected labelling pattern 
*Weighting ¹²C*  The amount of ¹²C isotope incorporation; can be a ratio, percentage or fraction (the value used is relative to the sum of all weights)  *(Editable)*
*Weighting ¹³C*  The amount of ¹³C isotope incorporation; can be a ratio, percentage or fraction (the value used is relative to the sum of all weights)  *(Editable)*
        *% ¹²C*  The percentage ¹²C isotope incorporation for this atom, calculated using stated weights 
        *% ¹³C*  The percentage ¹³C isotope incorporation for this atom, calculated using stated weights 
===============  ===================================================================================================================================================



|button| **Reset Residue To Orig Scheme**: Resets the selected residue to use atom isotope incorporation levels from the isotopomers of the set scheme; removes any atom level edits

|button| **Propagate Abundances**: Spread the istotope incorporation levels from the last selected atom (in the table) to all selected atomes; overrides isotopomer levels

|button| **Set Natural Abundance**: Set the selected atoms to have natural abundance isotope incorporation levels

