Merge 91bcad3 into cf2bf79

CHANGELOG.md

@@ -3,10 +3,12 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [0.1.0] - 2021-XX-XX
+- Enhancements
+   - Improved definitions of general and GNSS meta data
 - Documentation
-   - Added examples for JRO methods
+   - Added examples for JRO and GNSS data
 - Testing
-   - Added unit tests for JRO methods
+   - Added unit tests for JRO and GNSS methods
 
 ## [0.0.4] - 2021-06-11
 - Made changes to structure to comply with updates in pysat 3.0.0

docs/examples.rst

@@ -6,4 +6,5 @@ tools
 
 .. toctree::
    examples/ex_init.rst
-   examples/ex_jro_isr_beam.rst
+   examples/ex_gnss_tec.rst
+   examples/ex_jro_isr_beam.rst

docs/examples/ex_gnss_tec.rst

@@ -0,0 +1,83 @@
+.. _ex-gnss-tec:
+
+Plot GNSS TEC
+=============
+
+The Global Navigation Satellte System (GNSS) Total Electron Content (TEC) is one
+of the most valuable ionospheric data sets, given its long and continuous
+operational duration and expansive coverage.  :py:mod:`pysatMadrigal` currently
+only supports Vertical TEC (VTEC) data handling through
+:py:mod:`pysatMadrigal.instruments.gnss_tec`.
+
+The VTEC measurements are median filtered to fill 1 degree latitude by 1
+degree longitude bins.  This can be represented with spatially representative
+coverage as shown in the example below.  Start by obtaining the desired data
+and loading it.
+
+.. code::
+
+   import datetime as dt
+   import matplotlib as mpl
+   import matplotlib.pyplot as plt
+   import numpy as np
+   import pysat
+   import pysatMadrigal as pysat_mad
+
+   vtec = pysat.Instrument(inst_module=pysat_mad.instruments.gnss_tec,
+                           tag='vtec')
+   ftime = dt.datetime(2013, 1, 1)
+
+   if not ftime in vtec.files.files.index:
+       vtec.download(start=ftime)
+
+   vtec.load(date=ftime)
+   print(vtec.variables)
+
+
+The result of the above command should be
+``['time', 'gdlat', 'glon', 'dtec', 'gdalt', 'tec']``, where ``'tec'`` is the
+VTEC and ``'dtec'`` is the error in the VTEC.  To plot the data on a grid where
+each value takes up the desired grid size, we need to extend the latitude and
+longitude coordinates, as the data is specified at the lower edge of each
+coordinate bin.
+
+.. code::
+
+   coords = {}
+   for ckey in ['gdlat', 'glon']:
+       coords[ckey] = list(vtec[ckey].values)
+       coords[ckey].append(vtec.meta[ckey, vtec.meta.labels.max_val])
+       coords[ckey] = np.array(coords[ckey])
+
+Now, create a figure using `pcolormesh <https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.pcolormesh.html#matplotlib.pyplot.pcolormesh>`_ to create
+a regular grid with VTEC value indicated by color.
+
+.. code::
+
+
+   fig = plt.figure()
+   ax = fig.add_subplot(111)
+
+   itime = 0
+   vmin = vtec.meta['tec', vtec.meta.labels.min_val]
+   vmax = np.ceil(vtec['tec'][itime].max().values / 10.0) * 10.0
+   con = ax.pcolormesh(coords['glon'], coords['gdlat'],
+                       vtec['tec'].values[itime], vmin=vmin, vmax=vmax)
+
+   ax.set_facecolor('0.9')
+   ax.xaxis.set_major_locator(mpl.ticker.MultipleLocator(60))
+   ax.yaxis.set_major_locator(mpl.ticker.MultipleLocator(30))
+   ax.set_xlabel('Geographic Longitude ($^\circ$)')
+   ax.set_ylabel('Geodedic Latitude ($^\circ$)')
+   plt.colorbar(mappable=con, ax=ax, location='right', fraction=.1, pad=.01,
+                label='VTEC ({:s})'.format(vtec.meta['tec',
+		                                     vtec.meta.labels.units]))
+   fig.suptitle('{:s} {:s} at {:s}'.format(
+       vtec.platform.upper(), vtec.tag.upper(),
+       vtec.index[itime].strftime('%d %b %Y %H:%M:%S UT'), fontsize='medium'))
+
+   
+.. image:: ../figures/ex_gnss_vtec.png
+    :width: 800px
+    :align: center
+    :alt: Mapped median Vertical Total Electron Content over the globe.

pysatMadrigal/instruments/gnss_tec.py

@@ -214,7 +214,19 @@ def load(fnames, tag=None, inst_id=None):
 
     # Fix the units for tec and dtec
     if tag == 'vtec':
-        meta['tec'] = {meta.labels.units: 'TECU'}
-        meta['dtec'] = {meta.labels.units: 'TECU'}
+        meta['tec'] = {meta.labels.units: 'TECU', meta.labels.min_val: 0.0,
+                       meta.labels.max_val: np.nan}
+        meta['dtec'] = {meta.labels.units: 'TECU', meta.labels.min_val: 0.0,
+                        meta.labels.max_val: np.nan}
+
+    # Get the maximum and minimum values for time, latitude, longitude,
+    # and altitude
+    meta['time'] = {meta.labels.notes: data['time'].values.dtype.__doc__,
+                    meta.labels.min_val: np.nan, meta.labels.max_val: np.nan}
+    meta['gdalt'] = {meta.labels.min_val: 0.0, meta.labels.max_val: np.nan}
+    meta['gdlat'] = {meta.labels.min_val: -90.0, meta.labels.max_val: 90.0}
+    min_lon = 0.0 if data['glon'].values.min() >= 0.0 else -180.0
+    meta['glon'] = {meta.labels.min_val: min_lon,
+                    meta.labels.max_val: min_lon + 360.0}
 
     return data, meta

pysatMadrigal/instruments/methods/general.py

@@ -104,13 +104,20 @@ def load(fnames, tag=None, inst_id=None, xarray_coords=None):
     if len(load_file_types["netCDF4"]) > 0:
         # Currently not saving file header data, as all metadata is at
         # the data variable level
+        if 'catalog_text' in file_data.attrs:
+            notes = file_data.attrs['catalog_text']
+        else:
+            notes = "No catalog text"
+
         for item in file_data.data_vars.keys():
             name_string = item
             unit_string = file_data[item].attrs['units']
             desc_string = file_data[item].attrs['description']
             meta[name_string.lower()] = {meta.labels.name: name_string,
+                                         meta.labels.notes: notes,
                                          meta.labels.units: unit_string,
-                                         meta.labels.desc: desc_string}
+                                         meta.labels.desc: desc_string,
+                                         meta.labels.fill_val: np.nan}
 
             # Remove any metadata from xarray
             file_data[item].attrs = {}

pysatMadrigal/tests/test_methods_gnss.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+# Full license can be found in License.md
+# Full author list can be found in .zenodo.json file
+# DOI:10.5281/zenodo.3824979
+# ----------------------------------------------------------------------------
+"""Test methods for `pysatMadrigal.instruments.methods.gnss`."""
+
+import pytest
+
+from pysatMadrigal.instruments.methods import gnss
+
+
+class TestGNSSRefs(object):
+    """Test the acknowledgements and references for the JRO instruments."""
+
+    def setup(self):
+        """Run before every method to create a clean testing setup."""
+        self.out = None
+        return
+
+    def teardown(self):
+        """Run after every method to clean up previous testing."""
+        del self.out
+        return
+
+    @pytest.mark.parametrize("func, comp_str, in_args", [
+        ('acknowledgements', 'GPS TEC data products', ['tec']),
+        ('references', 'Rideout and Coster', ['tec', 'vtec'])])
+    def test_ref_output(self, func, comp_str, in_args):
+        """Test the GNSS acknowledgements and references."""
+        self.out = getattr(gnss, func)(*in_args)
+        assert self.out.find(comp_str) >= 0
+        return