hapiplot() doc references

Author: rweigel

README.rst

@@ -13,17 +13,22 @@ Installation
     # or
     pip install 'git+https://github.com/hapi-server/client-python' --upgrade
 
+    pip install hapiplot --upgrade
+    # or
+    pip install 'git+https://github.com/hapi-server/plot-python' --upgrade
+
 See the `Appendix <#Appendix>`__ for a fail-safe installation method.
 
 Basic Example
 -------------
 
 .. code:: python
 
-    # Get and plot Dst index from CDAWeb HAPI server
+    # Get Dst index from CDAWeb HAPI server
     from hapiclient import hapi
-    from hapiclient import hapiplot
 
+    # See http://hapi-server.org/servers/ for a list of
+    # other HAPI servers and datasets.
     server     = 'https://cdaweb.gsfc.nasa.gov/hapi'
     dataset    = 'OMNI2_H0_MRG1HR'
     start      = '2003-09-01T00:00:00'
@@ -33,21 +38,43 @@ Basic Example
 
     # Get data
     data, meta = hapi(server, dataset, parameters, start, stop, **opts)
-    # Show documentation
-    #help(hapi)
+    print(meta)
+    print(data)
 
     # Plot all parameters
+    from hapiplot import hapi
     hapiplot(data, meta)
-    # Show documentation
-    #help(hapiplot)
+
 
 Documentation
 -------------
 
 Basic usage examples for various HAPI servers are given in `hapi_demo.py <https://github.com/hapi-server/client-python/blob/master/hapi_demo.py>`__
 
+See http://hapi-server.org/servers/ for a list of HAPI servers and datasets.
+
 All of the features are extensively demonstrated in the `hapi_demo.ipynb <https://github.com/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb>`__ Jupyter Notebook.
 
+
+Data Model and Time Format
+--------------------------
+
+A request for data of the form
+```
+data, meta = hapi(server, dataset, parameters, start, stop)
+```
+
+returns the [Numpy N-D array](https://docs.scipy.org/doc/numpy-1.15.1/user/quickstart.html) `data` and a Python dictionary `meta` from a HAPI-compliant data server `server`. The structure of `data` and `meta` mirrors the structure of a response from a HAPI server.
+
+The HAPI client data model is intentionally basic. There is an ongoing discussion of a data model for Heliophysics data among the `PyHC community <https://heliopython.org/>`_. When this data model is complete, a function that converts `data` and `meta` to that data model will be included in the `hapiclient` package.
+
+Examples of transforming and manipulating `data` is given in a `Jupyter Notebook <https://colab.research.google.com/drive/11Zy99koiE90JKJ4u_KPTaEBMQFzbfU3P#scrollTo=aI_7DxnZtQZ3>`_. The examples include 
+
+# Fast and well-tested conversion from ISO 8601 timestamp strings to Python `datetime` objects
+# Putting the content of `data` in a Pandas `DataFrame` object
+# Creating an Astropy NDArray
+
+
 Development
 -----------
 

TODO.md

@@ -9,8 +9,8 @@
 #    %matplotlib inline
 # to revert.
 
-# For a more extensive demo, see
-# https://github.com/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb
+# For more extensive demos and examples, see
+# https://colab.research.google.com/drive/11Zy99koiE90JKJ4u_KPTaEBMQFzbfU3P?usp=sharing
 
 def main():
 
@@ -23,9 +23,9 @@ def main():
             print("\033[0;31mError:\033[0m " + str(e))
 
 def omniweb():
-    
+
     from hapiclient import hapi
-    from hapiclient import hapiplot
+    from hapiplot import hapiplot
 
     server     = 'https://cdaweb.gsfc.nasa.gov/hapi'
     dataset    = 'OMNI2_H0_MRG1HR'
@@ -36,14 +36,14 @@ def omniweb():
 
     # Get data
     data, meta = hapi(server, dataset, parameters, start, stop, **opts)
-    
+
     # Plot all parameters
     hapiplot(data, meta)
 
 def sscweb():
 
     from hapiclient import hapi
-    from hapiclient import hapiplot
+    from hapiplot import hapiplot
 
     # SSCWeb data
     server     = 'http://hapi-server.org/servers/SSCWeb/hapi'
@@ -58,7 +58,7 @@ def sscweb():
 def cdaweb():    
 
     from hapiclient import hapi
-    from hapiclient import hapiplot
+    from hapiplot import hapiplot
 
     # CDAWeb data - Magnitude and BGSEc from dataset AC_H0_MFI
     server     = 'https://cdaweb.gsfc.nasa.gov/hapi'
@@ -69,7 +69,7 @@ def cdaweb():
     opts       = {'logging': True, 'usecache': True}    
     data, meta = hapi(server, dataset, parameters, start, stop, **opts)
     hapiplot(data, meta, **opts)
-    
+
     # CDAWeb metadata for AC_H0_MFI
     server     = 'https://cdaweb.gsfc.nasa.gov/hapi'
     dataset    = 'AC_H0_MFI'
@@ -78,7 +78,7 @@ def cdaweb():
     for i in range(0, len(meta['parameters'])):
         print('  %s' % meta['parameters'][i]['name'])
     print('')
-    
+
     # CDAWeb metadata for all datasets
     server = 'https://cdaweb.gsfc.nasa.gov/hapi'
     meta = hapi(server, **opts)
@@ -88,31 +88,32 @@ def cdaweb():
     print('  ...')    
     print('  %d. %s' % (len(meta['catalog']), meta['catalog'][-1]['id']))
     print('')
-    
+
     # List all servers
     servers = hapi(logging=True)  # servers is an array of URLs
     print('')
-    
+
 def cassini():
 
     from hapiclient import hapi
-    from hapiclient import hapiplot
-    
+    from hapiplot import hapiplot
+
     server     = 'http://datashop.elasticbeanstalk.com/hapi';
     dataset    = 'CHEMS_PHA_BOX_FLUXES_FULL_TIME_RES';
     parameters = 'HPlus_BEST_T1';
     start      = '2004-07-01T04:00:00Z';
     stop       = '2004-07-01T06:00:00Z';
     opts       = {'usecache': True, 'logging': True}
-    
+
     data, meta = hapi(server, dataset, parameters, start, stop, **opts)
 
     popts = {'logging': False, 'logy': True, 'logz': True}
     hapiplot(data, meta, **popts)
 
 def lisird():
 
-    from hapiclient import hapi, hapiplot
+    from hapiclient import hapi
+    from hapiplot import hapiplot
 
     server     = 'http://lasp.colorado.edu/lisird/hapi';
     dataset    = 'sme_ssi';
@@ -125,4 +126,8 @@ def lisird():
     hapiplot(data, meta)    
 
 if __name__ == '__main__':
+    try:
+        from hapiplot import hapiplot
+    except:
+        print('Package hapiplot is not installed. Will not plot results.')
     main()

hapi_demo.py

@@ -110,7 +110,7 @@ def request2path(*args):
 
 
 def hapiopts():
-    """Return allowed options for hapi().
+    """Return dict of default options for hapi()
 
     Used by hapiplot() and hapi().
 
@@ -144,11 +144,12 @@ def hapiopts():
 def hapi(*args, **kwargs):
     """Request data from a HAPI server.
 
-    For additional documentation and demonstration, see
-    https://github.com/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb
+    Version: 0.1.9
 
-    Version: 0.1.9b0
 
+    Examples
+    ----------
+    `Jupyter Notebook <https://colab.research.google.com/drive/11Zy99koiE90JKJ4u_KPTaEBMQFzbfU3P?usp=sharing>_`
 
     Parameters
     ----------
@@ -272,9 +273,6 @@ def hapi(*args, **kwargs):
     ----------
         * `HAPI Server Definition <https://github.com/hapi-server/data-specification>`_
 
-    Examples
-    ----------
-        See https://github.com/hapi-server/client-python-notebooks
     """
 
     nin = len(args)