MPAS-Dev · pwolfram · Apr 17, 2018 · Apr 16, 2018 · Apr 16, 2018 · Apr 17, 2018
diff --git a/docs/Makefile b/docs/Makefile
@@ -12,9 +12,16 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+clean:
+	rm -rf *observationstable.rst
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	python parse_table.py -x ../mpas_analysis/obs/observationstable.xml -r landicobservationstable.rst -c landice
+	python parse_table.py -x ../mpas_analysis/obs/observationstable.xml -r oceanobservationstable.rst -c ocean
+	python parse_table.py -x ../mpas_analysis/obs/observationstable.xml -r seaicobservationstable.rst -c seaice
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/authors.rst b/docs/authors.rst
@@ -2,7 +2,7 @@ Main Authors
 ============
 * Xylar Asay-Davis
 * Milena Veniziani
-* Philip Wolfram
+* Phillip J. Wolfram
 
 Contributors
 ============
@@ -16,4 +16,4 @@ Contributors
 * Jeremy Fyke
 
 For a list of all the contributions:
-https://github.com/MPAS-Dev/MPAS-Analysis/graphs/contributors
+https://github.com/MPAS-Dev/MPAS-Analysis/graphs/contributors
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -21,4 +21,6 @@ dependencies:
   - sphinx
   - sphinx_rtd_theme
   - numpydoc
-  - recommonmark
+  - tabulate >= 0.8.2
+  - pip:
+    - recommonmark
diff --git a/docs/index.rst b/docs/index.rst
@@ -14,7 +14,6 @@ Analysis for simulations produced with Model for Prediction Across Scales
 (MPAS) components and the Accelerated Climate Model for Energy (ACME), which
 used those components.
 
-
 Documentation
 =============
 .. toctree::
@@ -33,6 +32,11 @@ MPAS Components and E3SM
    mpasseaice
    e3sm
 
+Observations
+============
+.. toctree::
+
+  observations
 
 Indices and tables
 ==================

diff --git a/docs/observations.rst b/docs/observations.rst
@@ -0,0 +1,18 @@
+Observations
+============
+
+A variety of observational datasets are used within MPAS-Analysis:
+
+Land Ice metrics
+----------------
+.. include::  landicobservationstable.rst
+
+Ocean metrics
+-------------
+
+.. include::  oceanobservationstable.rst
+
+Sea Ice metrics
+---------------
+.. include::  seaicobservationstable.rst
+
diff --git a/docs/parse_table.py b/docs/parse_table.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python
+"""
+This script is used to convert an xml-based table into an rst table for
+python documentation and pythonic parsing.
+
+Phillip J. Wolfram
+04/16/2018
+"""
+
+import xml.etree.ElementTree as ET
+import tabulate
+import argparse
+import re
+
+
+def markdown_links(data, footer):
+    urlscmd = re.findall(r"\[.*?\]\n*\(.*?\)", data)
+    urls = re.findall(r"\[.*?\]\n*\((.*?)\)", data)
+    linknames = re.findall(r"\[(.*?)\]\n*\(.*?\)", data)
+
+    for alinkname, aurl, aurlscmd in zip(linknames, urls, urlscmd):
+        data = data.replace(aurlscmd, '`' + alinkname + '`_')
+        footer += ".. _`" + alinkname + "`: " + aurl + "\n"
+
+    return data, footer
+
+
+def spurious_newline_whitespace(data, _):
+    whitespace = re.findall('\n\s*', data)
+    if len(whitespace) > 0:
+        astr = min(whitespace)
+        data = data.replace(astr, "\n")
+    return data, _
+
+
+def cleanup(linedata, footer):
+    cleanups = [spurious_newline_whitespace, markdown_links]
+    for acleanup in cleanups:
+        linedata, footer = acleanup(linedata, footer)
+    return linedata, footer
+
+
+def build_rst_table_from_xml(xmlfile, rstfile, component):
+
+    # open xml file for reading
+    xml = ET.parse(xmlfile)
+
+    # open rst file for writing
+    rst = open(rstfile, 'w')
+
+    # get headers and build list to write entries
+    headers = xml.getroot().attrib['headers'].replace(' ', '').split(',')
+    headernames = [aname.strip() for aname in
+                   xml.getroot().attrib['headernames'].split(',')]
+    data = []
+    footer = ''
+    for entry in xml.findall('observation'):
+        if (component != 'all' and
+                entry.findall('component')[0].text.strip() != component):
+            continue
+        line = []
+        for aheader in headers:
+            linedata = entry.findall(aheader)[0].text.strip()
+            linedata, footer = cleanup(linedata, footer)
+            line.append(linedata)
+        data.append(line)
+
+    rst.writelines(tabulate.tabulate(data, headernames, tablefmt='rst') + '\n')
+    rst.write('\n')
+    rst.write(footer)
+    rst.write('\n')
+
+    rst.close()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+            description=__doc__, formatter_class=argparse.RawTextHelpFormatter)
+    parser.add_argument("-x", "--xml_table", dest="xml_table",
+                        help="Path to file containing "
+                             "xml description of table",
+                        metavar="FILE", required=True)
+    parser.add_argument("-r", "--rst_table", dest="rst_table",
+                        help="Path to file containing rst description "
+                             "of table for output",
+                        metavar="FILE", required=True)
+    parser.add_argument("-c", "--component", dest="component",
+                        help="Component for parsing of table: "
+                             "'landice', 'ocean', 'seaice', or 'all'",
+                        metavar="STRING", default="all")
+
+    args = parser.parse_args()
+
+    build_rst_table_from_xml(args.xml_table, args.rst_table, args.component)
diff --git a/mpas_analysis/obs/observationstable.xml b/mpas_analysis/obs/observationstable.xml
@@ -0,0 +1,153 @@
+<?xml version="1.0"?>
+<observations 
+  headers="shortdesc, obsDataSet, references"
+  headernames="Dataset, Observational Dataset, References">
+  <!-- OCEAN -->
+  <observation>
+    <name>
+      sst Hadley-NOAA
+    </name>
+    <component>
+      ocean
+    </component>
+    <shortdesc>
+      SST global annual climatology and trend
+    </shortdesc>
+    <detaileddesc>
+      - Global latitude/longitude plot on ocean native grid. Annual climatologies computed over 5-10 year periods at regular intervals throughout the run.
+      - Time series of area-weighted (AW) global mean (1-year running average).
+    </detaileddesc>
+    <obsDataSet>
+      [Merged Hadley Center-NOAA/OI data set from Hurrell et al. 2008](https://climatedataguide.ucar.edu/climate-data/merged-hadley-noaaoi-sea-surface-temperature-sea-ice-concentration-hurrell-et-al-2008)
+      <releasePolicy>
+        Update 4/11/18: emailed UCAR to ask about their release policy.
+      </releasePolicy>
+    </obsDataSet>
+    <references>
+      - CESM Atm diagnostic package 
+      - Gent et al. (2011, Fig.1)
+    </references>
+    <purpose>
+    </purpose>
+    <inMPASAnalysis value="true" />
+    <testedStandAlone value="true" />
+    <testedCoupled value="true" />
+  </observation>
+  <observation>
+    <name>
+      SSS NASA Aquarius
+    </name>
+    <component>
+      ocean
+    </component>
+    <shortdesc>
+      SSS global annual climatology
+    </shortdesc>
+    <detaileddesc>
+    - Global latitude/longitude plot on ocean native grid . Annual climatologies computed over 5-10 year periods at regular intervals throughout the run.
+    </detaileddesc>
+    <obsDataSet>
+      [NASA Aquarius satellite data ~4 years until Jun 2015](ftp://podaac-ftp.jpl.nasa.gov/allData/aquarius/L3/mapped/V4/7day_running/SCI/)
+      <releasePolicy>
+      This statement is from the NASA daac (Distributed
+      Active Archive Center) website: "NASA data are not copyrighted; however,
+      when you publish our data or results derived therefrom, we request that
+      you include an acknowledgment within the text of the publication and
+      reference list." This should apply to all NASA data sets.
+      </releasePolicy>
+    </obsDataSet>
+    <otherDataSets>
+      [PHC](http://psc.apl.washington.edu/nonwp_projects/PHC/Climatology.html)
+        or [WOA13 climatology](https://www.nodc.noaa.gov/OC5/woa13/).
+    </otherDataSets>
+    <references>
+      - Large and Danabasoglu (2006, Fig.1)
+      - Griffies et al. (2009, Fig. 8)
+    </references>
+    <purpose>
+    </purpose>
+    <inMPASAnalysis value="true"/>
+    <testedStandAlone value="true"/>
+    <testedCoupled value="true"/>
+  </observation>
+  <!-- SEA ICE -->
+  <observation>
+    <name>
+      Ice area/extent annual climatology, and annual and seasonal trends
+    </name>
+    <component>
+      seaice
+    </component>
+    <shortdesc>
+      Sea ice concentration
+    </shortdesc>
+    <detaileddesc>
+      - Arctic and Antarctic seasonal and annual climatologies (maps) of ice area and extent. Annual climatologies computed over 5-10 year periods at regular intervals throughout the run.
+     - Daily, monthly and 1-year average time series of area-weighted ice area and extent.
+    </detaileddesc>
+    <obsDataSet>
+      - [Ice concentration: SSM/I, NASATeam algorithm(both NH and SH)](http://nsidc.org/data/NSIDC-0051)
+      - [Ice concentration: SSM/I, Bootstrap algorithm (both NH and SH)](http://nsidc.org/data/NSIDC-0079)
+      - [Ice area time series: SSM/I derived (both NH and SH)](http://neptune.gsfc.nasa.gov/csb/index.php?section=59)
+      <releasePolicy>
+        Same as all NASA data.
+      </releasePolicy>
+    </obsDataSet>
+    <otherDataSets>
+      - [Antarctic ship-based data](http://aspect.antarctica.gov.au/data)
+      - [Ice type, and drift](http://marine.copernicus.eu/services-portfolio/access-to-products/?option=com_csw&amp;view=details&amp;product_id=SEAICE_GLO_SEAICE_L4_NRT_OBSERVATIONS_011_001)
+      - [MANY data sets available for both ocean and sea ice, both global and regional](high-reshttp://marine.copernicus.edu)
+    </otherDataSets>
+    <references>
+      - CESM CICE diagnostics
+      - Ivanova et al. (2012)
+      - Worby et al. (2008)
+    </references>
+    <purpose>
+      See CESM sea ice diagnostic package
+    </purpose>
+    <inMPASAnalysis value="NA"/>
+    <testedStandAlone value="NA"/>
+    <testedCoupled value="NA"/>
+  </observation>
+  <!-- LAND ICE -->
+  <observation>
+    <name>
+      Present-day ice sheet area and volume (scalar)
+    </name>
+    <component>
+      landice
+    </component>
+    <shortdesc>
+      Land ice area / volume
+    </shortdesc>
+    <detaileddesc>
+      - Difference between modeled and observed values.
+    </detaileddesc>
+    <obsDataSet>
+      Greenland ice thickness at bed topography at 1 km posting
+        - [Bedmap2 paper](http://www.the-cryosphere.net/7/375/2013/), [Bedmap2 data](https://www.bas.ac.uk/project/bedmap-2/)
+        - [R-Topo2 paper](http://www.earth-syst-sci-data-discuss.net/essd-2016-3/), [R-Topo2 data](https://www.pangaea.de/PHP/hs.php?s=Maps&amp;d=RTopo-2.0&amp;ID=856844)
+      Antarctic ice thickness and bed topography at 1 km posting
+      <releasePolicy>
+        Same as all NASA data.
+      </releasePolicy>
+    </obsDataSet>
+    <otherDataSets>
+      - [Antarctic ship-based data](http://aspect.antarctica.gov.au/data)
+      - [Ice type, and drift](http://marine.copernicus.eu/services-portfolio/access-to-products/?option=com_csw&amp;view=details&amp;product_id=SEAICE_GLO_SEAICE_L4_NRT_OBSERVATIONS_011_001)
+      - [MANY data sets available for both ocean and sea ice, both global and regional](high-reshttp://marine.copernicus.edu)
+    </otherDataSets>
+    <references>
+      - Bamber et al. (2013)
+      - Fretwell et al. (2013)
+    </references>
+    <purpose>
+      validate initial conditions
+    </purpose>
+    <inMPASAnalysis value="on landice/develop"/>
+    <testedStandAlone value="True"/>
+    <testedCoupled value="False"/>
+  </observation>
+
+</observations>