
===============================================================================

          ARIA -- Ambiguous Restraints for Iterative Assignment

                 A software for automated NOE assignment

                               Version 2.1

===============================================================================

Copyright (C) Benjamin Bardiaux, Michael Habeck, Therese Malliavin,
              Wolfgang Rieping, and Michael Nilges

All rights reserved.

NO WARRANTY. This software package is provided 'as is' without warranty of
any kind, expressed or implied, including, but not limited to the implied
warranties of merchantability and fitness for a particular purpose or
a warranty of non-infringement.

Distribution of substantively modified versions of this module is
prohibited without the explicit permission of the copyright holders.

===============================================================================

You may also want to have a look at the ARIA mailing list
which can be found here:

http://groups.yahoo.com/group/aria-discuss

===============================================================================

This file contains brief instructions for how to setup an ARIA 2
calculation for the HRDC domain, both using data in ARIA XML format
and stored within a CCPN project.

======================================================================

Ready-to-use XML files (conversion, data and a project file in
ARIA XML format can be found in the sub-directory "ready-to-use"

=======================================================================

Table of Contents:

0. Available data
1. Converting the data to ARIA XML
2. Project setup
3. Running ARIA
4. Running ARIA using data stored in a CCPN project

0. Available data
-----------------

The original data are in XEasy and XPLOR/CNS format and are located in the
directory $ARIA2/examples/werner/data.

a.) Molecule definition            hrdc.seq

b.) 13C NOESY spectrum             hmqcnoe_partially_assigned.peaks
    Chemical shift list            hmqcnoe.prot

    Proton1 dimension: 2           XEasy format
    Hetero1 dimension: 1
    Proton2 dimension: 3

c.) 15N NOESY spectrum             noehsqc_partially_assigned.peaks
    Chemical shift list            noehsqc.prot

    Proton1 dimension: 3           XEsay format
    Hetero1 dimension: 1
    Proton2 dimension: 2

d.) Hydrogen bond restraints       hbonds.tbl
    in XPLOR/CNS .tbl format

1. Converting the data to ARIA XML.
-----------------------------------

1.1 ARIA provides routines for data conversion in the following way: the
    sequence and all data sources need to be specified in a simple XML file,
    "conversion.xml" in case of this example.

    To create a template conversion file use the following command:

        aria2 --convert -t conversion.xml

1.2 The next step is to edit the file "conversion.xml" and to fill in
    the relevant fields. Check the comments in "conversion.xml"
    for further instructions.

    A conversion file that is already filled in can be found in the directory
    $ARIA2/examples/werner. The attribute filename in <project><output>
    section of the XML file has been set to "./run1.xml", i.e. the data
    conversion routine will also create an appropriate project XML file with 
    the same name.

1.3 Start the data conversion:

        aria2 --convert conversion.xml

    This command first loads and parses the conversion file. It then reads in
    your data files (i.e spectra, shifts-lists, sequence-file) and converts
    them into XML. ARIA has created 6 new files:

    ./xml/hrdc.xml                        Molecule definition

    ./xml/13C_noe.xml                     13C NOESY spectrum
    ./xml/13C_ppm.xml                     Chemical shift list for 13C
 	 
    ./xml/15N_ppm.xml                     15N NOESY spectrum
    ./xml/15N_noe.xml                     Chemical shift list for 15N

    ./run1.xml                            Project XML file


2. Project setup
----------------

2.1 In order to setup an ARIA project it is necessary to provide
    some additional information: 

      - working directory               The root directory of the project.

      - file_root                       The "nickname" of the project.
                                        It serves, for instance, as
                                        basename for all PDB files: In case
                                        of this example, it is set to "hrdc".
					PDB files will be called hrdc_1.pdb etc

      - temporary path                  

      - list of available machines      In particular if you want to run the
                                        structure calculation on several
                                        machines simultaneously, you need
                                        to specify a list of those machines

                                        If the list is empty, ARIA uses the
                                        machine from which you started ARIA.

      - Path of local CNS binary                                   


    Use the GUI to fill in the 5 fields ("Project" panel):

        aria2 -g run1.xml  

    The fields "working directory", "file_root", "temporary path" are 
    located in panel "Project". The machine-list can be found at 
    "Structure Generation->Job Manager" and the CNS binary can be edited
    at "Structure Generation->CNS"

    Alternatively, you can edit the project file by hand using a text- or 
    XML editor. In our example the project XML file "run1.xml" the fields above
    have been already set to the following values:

        working_directory:         ./
        file_root:                 hrdc
        temporary_path:            ./
        list of avail. machines:   <empty>

--> You need to specify the path of your CNS binary. If you edit the
    "run1.xml" by hand, the following line has to be changed:

    <cns local_executable="<your_binary>" ....

    To save your project file, use the menu item "File", "Save as..."

2.2 To setup the project, use the following command:

        aria2 -s run1.xml

    This commands reads and checks the project file and 
    creates a new directory, "run1", copies your XML data files, 
    copies CNS protocols etc.


3. Run ARIA
-----------

After the project has been successfully set up, run ARIA2:

        aria2 run1.xml


4. Running ARIA using data stored in a CCPN project
---------------------------------------------------

A CCPN project that contains the input data, i.e. the molecular
system, shift lists, and peak lists, can be found in the 
directory $ARIA2/examples/werner/ccpn. A project XML file that is ready
to use is stored in $ARIA/examples/werner/ccpn/hrdc_ccpn_project.xml

Before you start: 

A CCPN project consists of an XML file, which is similar to an ARIA project
file. The CCPN project file references other storages (which are, in case of
the example, XML files too). In order to use the example CCPN project provided
with the ARIA distribution, you first need to update the references within the
CCPN project file (basically, this is because a CCPN project references 
storages using absolute path names. These path names are not necessarily
compatible with the name of the directory that contains your ARIA example
files). However, this is only necessary for the example CCPN project. It is
not required if you use ARIA with your own CCPN project files.

Updating the example CCPN project is simple. It can either be done by using
the FormatConverter or Analysis:

1. Start the FormatConverter or Analysis
2. Open the example project hrdc_ccpn_project.xml using the Menu
   "Project->Open"
3. The program will then tell you that the project moved from some
   directory to another one. Press OK. 
4. Save the project using the Menu "Project->Save".

That is it.

4.1 Name and location of your CCPN project

In order to setup a run, you first need to specfiy the filename
of the CCPN project that contains your data. The GUI provides the most
convenient way of doing this. To start the GUI, use the following command:

        aria2 -g

Go to panel "CCPN data model" and specify the name of your CCPN project,
hrdc_ccpn_project.xml in case of this example. If you want ARIA to export
restraint lists, the coordinates of the calculated structures, or 
NOE assignments, use the options provided by the panel.

4.2 Specification of the molecular system

In order to specify the name of the molecular system, click the
node Data->Molecular system. Choose "CCPN" as format, and press the button
"Select...". This will open the CCPN project specified in the step above to
give you a list of available molecular systems contained in the CCPN project. 
In case of the present example, the CCPN project contains only one system,
"hrdc". After selecting the molecular system, the GUI will show an associated
id, "hrdc|A", which ARIA uses to unambiguously retrieve the molecular system
from a CCPN project.

4.3 Adding shift and peak lists

Choose the menu "Add" "Spectrum" to add a new spectrum. The newly created
spectrum will appear under node Data->Spectra. Analogous to the molecular
systen, in section "Chemical Shift List", choose "CCPN" as format and press
the button "Select...". Select the shift list "13C_hmqcnoe". Do the same for
the peak list; choose list "13C_hmqcnoe_partially_assigned". The field
"CCPN name" shows the unique ids associated to the shift and peak list,
respectively.

In order to add another spectrum, simply repeat the step above. The name of
the second shift and peak list, respectively, is "15N_noehsqc" and 
"15N_noehsqc_partially_assigned".

4.4 Miscellaneous information

To complete the project setup, you need to provide a working directory, 
temporary directory, etc. In order to do so, please follow the instructions
given in section 2.1.

4.5 Setting up and running the project.

After saving your project XML file, you need to setup the project. This 
creates the directory tree, and copies all relevant files to the respective
target directories. To setup your project, run ARIA with the option -s:

         aria2 -s your_project.xml

To launch ARIA:

         aria2 your_project.xml
