clean up + update docs and README.md (#7)

* split up eccov4.rst into three files: overview.rst, downloads.rst, and runs.rst
* update commands to rely solely on github + various cosmetic changes
* homogenize treatment of ` and `` quotes: ` for proper nouns; `` for code, file names, directory names.
* revise front page paragraph (reathedocs) and README.md accordingly (github)
* re-organize slightly the tools section

README.md

@@ -2,7 +2,8 @@
 
 **Content:**
 
-This repository contains model settings ([code/](code/), [input/](input/)) and guidelines ([readthedocs](http://eccov4.readthedocs.io/en/latest/)) which allow users to re-run the ECCO v4 r2 ocean state estimate using the [MITgcm](http://mitgcm.org/) using on-premise cluster or using [Amazon Web Services' cfncluster][] via shell scripts provided in [example_scripts/](example_scripts/). If user support is needed, please contact <mitgcm-support@mit.edu> or <ecco-support@mit.edu>
+This repository contains model settings ([code/](code/), [input/](input/)) and documentation ([readthedocs](http://eccov4.readthedocs.io/en/latest/)) that allow users to download, analyze, rerun, or modify the ECCO v4 r2 ocean state estimate using the [MITgcm](http://mitgcm.org/) via on-premise cluster or [Amazon Web Services' cfncluster][] (see [example_scripts/](example_scripts/)). If user support is needed, please contact <mitgcm-support@mit.edu> or <ecco-support@mit.edu>.
+
 
 **Citation for this repository:**
 

docs/downloads.rst

@@ -0,0 +1,91 @@
+
+.. _downloads:
+
+Downloading ECCO Version 4
+**************************
+
+This section provides directions to download the ECCO v4 r2 output 
+(:numref:`download-solution`), the underlying model setup 
+(:numref:`download-setup`) that can be used to re-run ECCO v4 r2 
+(:numref:`eccov4-baseline`), `Matlab` tools to analyze ECCO v4 r2 and
+other model output (:numref:`download-analysis`), and a list of
+additional resources (:numref:`other-resources`).
+
+.. _download-solution:
+
+The Release 2 Solution
+----------------------
+
+The ECCO v4 r2 state estimate output is permanently archived within the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2>`__ that provides citable identifiers for the various datasets as reported in this `README.pdf <https://dataverse.harvard.edu/api/access/datafile/2863409>`__. For download purposes, the ECCO v4 r2 output is also made available via this `ftp
+server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ by the `ECCO Consortium <http://ecco-group.org>`__. The various directory contents are summarized in this `README <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/README>`__ and specific details are provided in each subdirectory’s README. Under Linux or macOS for instance, a simple download method consists in using ``wget`` at the command line by typing
+
+::
+
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_grid
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_climatology
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/nctiles_monthly
+
+and similarly for the other directories. The ``nctiles_`` directory prefix indicates that contents are provided on the native LLC90 grid in the nctiles format :cite:`for-eta:15` which can be read in `Matlab` using the `gcmfaces` toolbox (see :numref:`download-analysis`). Alternatively users can download interpolated fields, on a :math:`1/2\times1/2^\circ` grid in the netcdf format, from the ``interp_*`` directories. The ``input_*`` directories contain binary and netcdf input files that can be read by `MITgcm` (:numref:`download-setup` and :numref:`eccov4-baseline`). The ``profiles/`` directory (`see ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/profiles/>`_) additionally contains the MITprof collections of collocated in situ and state estimate profiles in `netcdf` format :cite:`for-eta:15`.
+
+.. _download-setup:
+
+The Release 2 Setup
+-------------------
+
+To :ref:`baseline` the solution and :ref:`testreportecco` in :numref:`eccov4-baseline`, user wants to install the following components. First, install the `MITgcm` either by downloading a copy from `this github repository <https://github.com/MITgcm/MITgcm/>`__. Second, create a subdirectory called ``MITgcm/mysetups/`` and download the model setup there from `this github
+repository <https://github.com/gaelforget/ECCO_v4_r2/>`__ by typing:
+
+::
+
+    git clone https://github.com/MITgcm/MITgcm
+    mkdir MITgcm/mysetups
+    mv ECCO_v4_r2 MITgcm/mysetups/.
+    cd MITgcm/mysetups
+    git clone https://github.com/gaelforget/ECCO_v4_r2    
+
+Third, download the model input forcing fields (96G of 6-hourly fields in ECCO v4 r2), initial condition, grid, etc. input (610M), and observational input data (25G) either from the `Harvard Dataverse <https://dataverse.harvard.edu/dataverse/ECCOv4r2inputs>`__ permanent archive or from the `ECCO ftp server <ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/>`__ as follows:
+
+::
+
+    cd MITgcm/mysetups/ECCO_v4_r2
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_forcing/
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_init/
+    wget --recursive ftp://mit.ecco-group.org/ecco_for_las/version_4/release2/input_ecco/
+    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_forcing forcing_baseline2
+    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_ecco inputs_baseline2
+    mv mit.ecco-group.org/ecco_for_las/version_4/release2/input_init inputs_baseline2/.
+
+Downloaded directories should be organized as shown under :ref:`mitgcmdirs` for use in :numref:`eccov4-baseline`. Experienced users should feel free to re-organize directories assuming that they are comfortable with modifying the :numref:`eccov4-baseline` instructions accordingly.
+
+.. _download-analysis:
+
+Matlab Analysis Tools
+---------------------
+
+`Matlab` tools are provided to analyze model output one it has been downloaded (:numref:`download-solution`) or generated by user (:numref:`eccov4-baseline`) include the `gcmfaces <https://github.com/gaelforget/gcmfaces>`__ toolbox :cite:`for-eta:15`. It is typically installed by typing 
+::
+
+    git clone https://github.com/gaelforget/gcmfaces
+
+and can be used, for example, to re-generate the ECCO v4 standard analysis (i.e., the plots included in :cite:`dspace-eccov4r2` for ECCO v4 r2) from the released model output (:numref:`download-solution`) or from the plain, binary, model output (:numref:`eccov4-baseline`). Documentation for `gcmfaces` is provided in the `github repository <https://github.com/gaelforget/gcmfaces>`__.
+
+
+.. _other-resources:
+
+Other Resources
+---------------
+
+-  The ECCO v4 r2 state estimate can also be downloaded and analyzed via the `NASA` `Sea Level Change Portal <https://sealevel.nasa.gov>`__ tools (interpolated fields) and the `Harvard Dataverse <https://dataverse.harvard.edu>`__ APIs (native grid input and output).
+
+-  A series of three presentations offered in May 2016 during the `ECCO` meeting at `MIT` provide an overview of the ECCO v4 r2 data sets and applications are available via researchgate.net
+   (`Overview <http://doi.org/10.13140/RG.2.2.33361.12647>`__;
+   `Processes <http://doi.org/10.13140/RG.2.2.26650.24001>`__;
+   `Tracers <http://doi.org/10.13140/RG.2.2.36716.56967>`__).
+
+-  `netcdf` enabled software such as `Panoply <http://www.giss.nasa.gov/tools/panoply/>`__ can be used to read the interpolated output (``interp_*`` directories) under `MS-Windows`, `Linux`, or `macOS`.
+
+-  `xmitgcm <https://github.com/xgcm/xmitgcm>`__ provides a `python` alternative to using `Matlab` and `gcmfaces <https://github.com/gaelforget/gcmfaces>`__.
+
+-  ``MITgcm/utils/`` provides basic `Matlab` and `python` functionalities.
+
+-  The stand-alone `eccov4_lonlat.m <http://mit.ecco-group.org/opendap/ecco_for_las/version_4/release2/doc/eccov4_lonlat.m>`__ `Matlab` script can be used to extract the lat-lon sector (i.e., array) of the gridded output that spans the 69S to 56N latitude range.