update documentation

doc/EGADS Documentation - SPHINX/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 
+tags: 

doc/EGADS Documentation - SPHINX/build/html/_sources/alg_development.rst.txt

@@ -0,0 +1,134 @@
+=====================
+Algorithm Development
+=====================
+
+Introduction
+*******************
+
+The EGADS framework is designed to facilitate integration of third-party algorithms. This is accomplished
+through creation of Python modules containing the algorithm code, and corresponding LaTeX files which 
+contain the algorithm methodology documentation. This section will explain the elements
+necessary to create these files, and how to incorporate them into the broader package.
+
+Python module creation
+************************
+
+To guide creation of Python modules containing algorithms in EGADS, an algorithm template has been included
+in the distribution. It can be found in ./egads/algorithms/algorithm_template.py and is shown below:
+
+.. literalinclude:: algorithm_template.py
+
+The best practice before starting an algorithm is to copy this file and name it following the EGADS algorithm
+file naming conventions, which is all lowercase with words separated by underscores. As an example, the file
+name for an algorithm calculating the wet bulb temperature contributed by DLR would be called
+'temperature_wet_bulb_dlr.py'.
+
+Within the file itself, there are several elements in this template that will need to be modified before this
+can be usable as an EGADS algorithm:
+
+1. Class name
+   The class name is currently 'AlgorithmTemplate', but this must be changed to the actual name of the
+   algorithm. The conventions here are the same name as the filename (see above), but using MixedCase. So,
+   following the example above, the class name would be TemperatureWetBulbDlr
+
+2. Algorithm docstring
+   The docstring is everything following the three quote marks just after the class definition. This 
+   section describes several essential aspects of the algorithm for easy reference directly from Python. 
+   Each field following the word in ALLCAPS should be changed to reflect the properties of the algorithm
+   (with the exception of VERSION, which will be changed automatically by Subversion when the file is 
+   committed to the server).
+
+3. Algorithm and output metadata
+   In the __init__ method of the module, two important parameters are defined. The first is the
+   'output_metadata', which defines the metadata elements that will be assigned to the variable 
+   output by the algorithm. A few recommended elements are included, but a broader list of variable
+   metadata parameters can be found in the NetCDF standards document on the EUFAR website (http://www.eufar.net/documents/4412, Annexe III).
+   In the case that there are multiple parameters output by the algorithm, the output_metadata parameter
+   can be defined as a list VariableMetadata instances.
+
+   Next, the 'metadata' parameter defines metadata concerning the algorithm itself. These information
+   include the names, types, descriptions and units of inputs; names and descriptions of outputs; name, 
+   description, purpose, date and version of the algorithm; date processed; and a reference to the output 
+   parameters. Of these parameters, only the names, types, descriptions and units of the inputs, names and 
+   descriptions of the outputs and description and purpose of the algorithm need to be altered. The other 
+   parameters (name, date and version of the processor; date processed) are populated automatically.
+
+.. NOTE::
+   For algorithms in which the output units depend on the input units (i.e. a purely mathematical
+   transform, derivative, etc), there is a specific methodology to tell EGADS how to set the output units.
+   To do this, set the appropriate 'units' parameter of output_metadata to 'inputn' where *n* is the
+   number of the input parameter from which to get units (starting at 0). The units on the input parameter 
+   from which the output is to be derived should be set to 'None'.
+
+4. Definition of parameters
+   In both the run and _algorithm methods, the local names intended for inputs need to be included. There
+   are three locations where the same list must be added (marked in bold):
+
+   * def run(self, **inputs**)
+   * return egads_core.EgadsAlgorithm.run(self, **inputs**)
+   * def _algorithm(self, **inputs**)
+
+5. Implementation of algorithm
+   The algorithm itself gets written in the _algorithm method and uses variables passed in by the user.
+   The variables which arrive here are simply scalar or arrays, and if the source is an instance of 
+   EgadsData, the variables will be converted to the units you specified in the InputUnits of the 
+   algorithm metadata. 
+
+
+Documentation creation
+***********************
+
+Within the EGADS structure, each algorithm has accompanying documentation in the EGADS Algorithm Handbook.
+These descriptions are contained in LaTeX files, organized in a structure similar to the toolbox itself,
+with one algorithm per file. These files can be found in the doc/EGADS Algorithm Handbook directory on 
+GitHub repository: https://github.com/eufarn7sp/egads/tree/master/doc.
+
+A template is provided to guide creation of the documentation files. This can be found at 
+doc/EGADS Algorithm Handbook/algorithms/algorithm_template.tex. The template is divided into 8 sections, enclosed 
+in curly braces. These sections are explained below:
+
+* Algorithm name
+   Simply the name of the Python file where the algorithm can be found.
+
+* Algorithm summary
+   This is a short description of what the algorithm is designed to calculate, and should contain
+   any usage caveats, constraints or limitations.
+
+* Category
+   The name of the algorithm category (e.g. Thermodynamics, Microphysics, Radiation, Turbulence, etc).
+
+* Inputs
+   At the minimum, this section should contain a table containing the symbol, data type (vector
+   or coefficient), full name and units of the input parameters. An example of the expected 
+   table layout is given in the template.
+
+* Outputs
+   This section describes the parameters output from the algorithm, using the same fields as the 
+   input table (symbol, data type, full name and units). An example of the expected table layout is
+   given in the template.
+
+* Formula
+   The mathematical formula for the algorithm is given in this section, if possible, along with a
+   description of the techniques employed by the algorithm.
+
+* Author
+   Any information about the algorithm author (e.g. name, institution, etc) should be given here.
+
+* References
+   The references section should contain citations to publications which describe the algorithm.
+
+In addition to these sections, the ``index`` and ``algdesc`` fields at the top of the file 
+need to be filled in. The value of the ``index`` field should be the same as the algorithm name.
+The ``algdesc`` field should be the full English name of the algorithm. 
+
+.. NOTE::
+    Any "_" character in plain text in LaTeX needs to be offset by a "\". Thus if the algorithm 
+    name is ``temp_static_cnrm``, in LaTex, it should be input as ``temp\_static\_cnrm``.
+
+
+Example
+--------
+
+An example algorithm is shown below with all fields completed.
+
+.. literalinclude:: temp_static_cnrm.tex

doc/EGADS Documentation - SPHINX/build/html/_sources/egadsapi.rst.txt

@@ -0,0 +1,39 @@
+==========
+EGADS API
+==========
+
+Core Classes
+************
+
+.. automodule:: egads.core.egads_core
+	:members:
+	:show-inheritance:
+
+
+Metadata Classes
+*****************
+
+.. automodule:: egads.core.metadata
+	:members:
+	:show-inheritance:
+
+File Classes
+*************
+
+.. automodule:: egads.input.input_core
+	:members:
+
+.. automodule:: egads.input.nasa_ames_io
+	:members:
+
+.. automodule:: egads.input.netcdf_io
+	:members:
+	:show-inheritance:
+
+.. automodule:: egads.input.text_file_io
+	:members:
+	:show-inheritance:
+
+
+
+

doc/EGADS Documentation - SPHINX/build/html/_sources/index.rst.txt

@@ -0,0 +1,18 @@
+.. EGADS documentation master file, created by
+   sphinx-quickstart on Tue May 24 15:43:01 2011.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to EGADS's documentation!
+=================================
+
+.. toctree::
+   :maxdepth: 3
+
+   intro
+   install
+   tutorial
+   alg_development
+   egadsapi
+
+

doc/EGADS Documentation - SPHINX/build/html/_sources/install.rst.txt

@@ -0,0 +1,54 @@
+=============
+Installation
+=============
+The latest version of EGADS can be obtained from https://github.com/eufarn7sp/egads
+
+
+Prerequisites
+*************
+Use of EGADS requires the following packages:
+
+* Python 2.7.10 or newer. Available at http://www.python.org/
+* numpy 1.10.1 or newer. Available at http://numpy.scipy.org/
+* scipy 0.15.0 or newer. Available at http://www.scipy.org/
+* Python netCDF4 libraries 1.1.9. Available at https://pypi.python.org/pypi/netCDF4
+
+
+Optional Packages
+*****************
+The following are useful when using or compiling EGADS:
+
+* IPython - An optional package which simplifies Python command line usage (http://ipython.scipy.org). IPython is an enhanced interactive Python shell which supports tab-completion, debugging, command history, etc. 
+* setuptools - An optional package which allows easier installation of Python packages (http://pypi.python.org/pypi/setuptools). It gives access to the ``easy_install`` command which allows packages to be downloaded and installed in one step from the command line. 
+
+
+Installation
+************
+Since EGADS is a pure Python distribution, it does not need to be built. However, to use it, it must 
+be installed to a location on the Python path. To install EGADS, first download and decompress the file. From the directory
+containing the file ``setup.py``, type ``python setup.py install`` 
+from the command line. To install to a user-specified location, type ``python setup.py install --prefix=$MYDIR``.
+
+
+Testing
+*******
+To test EGADS after it is installed, run the run_tests.py Python script, or from Python, run the following commands:
+
+   >>> import egads
+   >>> egads.test()
+
+
+Log
+***
+A logging system has been introduced in EGADS since the version 0.7.0. By default, the output file is available in the 'Python local site-packages/EGADS x.x.x/egads' directory and the logging level has been set to INFO. Both options can be changed through EGADS using the ``egads.set_log_options()`` function, by passing a dictionary of option keys and values:
+
+   >>> import egads
+   >>> config_dict = {'level': 'INFO', 'path': '/path/to/log/directory/'}
+   >>> egads.set_log_options(config_dict)
+   >>> exit()
+
+New logging options will be loaded at the next import of EGADS. Logging levels are the standard Python ones (``DEBUG``, ``INFO``, ``WARNING``, ``CRITICAL``, ``ERROR``). It is also possible to change dynamically the logging level in a script:
+
+   >>> egads.change_log_level('DEBUG')
+
+That possibility is not permanent and will last until the script run is over.

doc/EGADS Documentation - SPHINX/build/html/_sources/intro.rst.txt

@@ -0,0 +1,20 @@
+=============
+Introduction
+=============
+The EGADS (EUFAR General Airborne Data-processing Software) core is a Python-based 
+library of processing and file I/O routines designed to help analyze a wide range of 
+airborne atmospheric science data. EGADS purpose is to provide a benchmark for airborne 
+data-processing through its community-provided algorithms, and to act as a reference 
+by providing guidance to researchers with an open-source design and well-documented 
+processing routines.
+
+Python is used in development of EGADS due to its straightforward syntax and  
+portability between systems. Users interact with data processing 
+algorithms using the Python command-line, by creating Python scripts for 
+more complex tasks, or by using the EGADS GUI for a simplified interaction. The 
+core of EGADS is built upon a data structure that 
+encapsulates data and metadata into a single object. This simplifies the housekeeping 
+of data and metadata and allows these data to be easily passed 
+between algorithms and data files. Algorithms in EGADS also contain metadata 
+elements that allow data and their sources to be tracked through processing chains.
+