======================
Command Line Interface
======================

The ESM Analysis software provides a command line interface for common
operations you may want to perform on model output. To see which operators are
available::

	$ esm_analysis —-help

This will print a list of currently implemented subcommands. For suggestions,
improvements, or feature requests, please open an issue.

Effectively, the command line interface provides “syntax sugar” around several
``CDO`` commands to take away some of the overhead, including:

* Automatic awareness of file and directory locations
* Avoids reprocessing already existing analysis
* Uniform, semantic output file names in organized subdirectories

This eases some of the problems commonly experiences when sharing data with
colleagues, such as:

* Different preferences in filenames (``esm_analysis`` does this for you)
* No ambiguity in what sort of analysis you are getting (``esm_analysis``
  clearly marks what it does)

You can execute ``esm_analysis`` from anywhere within an experiment tree. It
doesn’t matter if you are in ``outdata``, ``analysis``, ``work``, ``restart``,
the top of the experiment, or an arbitrarily deep subfolder. The only
pre-requisite here is that a file ``.top_of_experiment`` is in the top level
directory. If this is not found, and ``esm_analysis`` finds the root of the
filesystem, it will ask you for assistance.

Example
-------

Let’s say you want to make a globally spatial average of ``temp2``, the 2 meter
near surface air temperature. From anywhere in the experiment, just say::

	$ esm_analysis fldmean temp2

``esm_analysis`` will figure out that:

* ``temp2`` is an echam variable
* which files in echam have ``temp2`` information (if more than one, it will ask
  which files you want to use)
* Make an analysis directory for you
* Generate a file ``${EXP_ID}_echam6_temp2_fldmean.nc``

=============
Library Usage
=============

To use ESM Analysis in a project::

    import esm_analysis

The ESM Analysis module allows for creation of several common analyis from
Python objects.

The main object you probably want to use is: ``EsmAnalysis``. You can create one
like this, if you are currently working within an experiment directory::

    from esm_analysis import EsmAnalysis
    analyser = EsmAnalysis()

Optionally, you can give it a path where to start from::

    analyser = EsmAnalysis(exp_base="/work/ba0989/a270077/AWICM_PISM/LGM_011")

You can also tell it where to store analysis::

    analyser = EsmAnalysis(preferred_analysis_dir="/work/ba0989/a270077/store_analysis_here")

Once you have created the ``analyzer`` object, you can use the attached methods
to quickly get some typical analyses. The methods always return an
``xarray.Dataset`` object. Typically, the only required argument is the variable
name::

    t2m_fldmean = analyser.fldmean("temp2")