tutorial.rst

Tutorial
========

So, you are planning to use the Earth Diagnostics? You don't know how to use them? This is the place to go.
From now on this tutorial will guide you through all the process from installation to running.

.. Hint::
    If you have any problem with this tutorial, please report it to <javier.vegas@bsc.es> so it can be corrected.
    A lof of people will benefit from it.

Installation
------------

For now, you only have one option: download the diagnostics directly from BSC-ES's Gitlab:

.. code-block:: sh

    git clone https://earth.bsc.es/gitlab/es/ocean_diagnostics.git

You will also need

* CDO version 1.6.9 (other versions could work, but this is the one we use)
* NCO version 4.5.4 or newer
* Python 2.7 or newer (but no 3.x) with Autosubmit, CDO and NCO packages, among others. A virtual environment with all requisites fullfilled is available at /shared/earth/ClimatePrediction/EarthDiagnostics
* Access to CDFTOOLS_3.0 executables for BSC-ES. At this point, those are located at /shared/earth/ClimatePrediction/CDFTOOLS_CMOR/bin.

Creating a config file
----------------------

Go to the folder where you installed the EarthDiagnostics. You will see a folder called earthdiagnostics,
and, inside it, a diags.conf file that can be used as a model for your config file. Create a copy of it wherever it
suites you.

Now open your brand new copy with your preferred text editor. The file contains commentaries explaining each
one of its options, so read it carefully and edit whatever you need. Don't worry about DIAGS option, we will
talk about it next.

After this, you need to choose the diagnostics you want to run. For a simple test, it's recommended to use the monmean
diagnostic to compute monthly means from daily data. We recommend it because it can be used with any variable, the user
has to provide parameters but they are quite intuitive and it's relatively fast to compute. If your experiment does not
have daily data, you can use any other diagnostic. Check next section for a list of available diagnostics and choose
whichever suits you better. From now on, we will assume that you are going to run the monmean diagnostic.

.. hint::

    For old Ocean Diagnostics users: you can use most of the old names as aliases to launch one or multiple diagnostics.
    Check the ALIAS section on the diags.conf to see which ones are available.

First, choose a variable that has daily data. Then replace the DIAGS option with the next one where $VARIABLE represents the
variable's name and $DOMAIN its domain (atmos, ocean, seaice, landice...)

.. code-block:: sh

    DIAGS = monmean,$VARIABLE,$DOMAIN

Prepare the run script
----------------------

Once you have configured your experiment you can execute any diagnostic with the provided launch_diags.sh script.
Create a copy and change the variables PATH_TO_CONF_FILE and PATH_TO_DIAGNOSTICS so they point to your conf file and
installation folder.

Now, execute the script (or submit it to bsceslogin01, it has the correct header) and... that's it!
You will find your results directly on the storage and a folder for the temp files in the scratch named after the EXPID.