Update docs.

smithara · smithara · commit 63713e8ee965 · 2019-12-17T19:02:28.000Z
diff --git a/README.rst b/README.rst
@@ -1,6 +1,3 @@
-===========
-viresclient
-===========
 
 .. image:: https://badge.fury.io/py/viresclient.svg
     :target: https://badge.fury.io/py/viresclient
@@ -22,10 +19,85 @@ viresclient
 .. image:: https://zenodo.org/badge/138034133.svg
    :target: https://zenodo.org/badge/latestdoi/138034133
 
-``viresclient`` is a tool which connects to a VirES server through the `WPS <http://www.opengeospatial.org/standards/wps>`_ interface and handles product requests and downloads.
-
-Install with::
+::
 
   pip install viresclient
 
-Full documentation: http://viresclient.readthedocs.io/
+viresclient_ is a Python package which connects to a VirES_ server through the WPS_ interface and handles product requests and downloads. This enables easy access to ESA's `Swarm mission`_ data and models. This service is provided for ESA by EOX_. For enquiries or help, please email info@vires.services or `raise an issue on GitHub`_.
+
+.. _viresclient: https://github.com/ESA-VirES/VirES-Python-Client
+.. _VirES: https://vires.services
+.. _WPS: http://www.opengeospatial.org/standards/wps
+.. _`Swarm mission`: https://earth.esa.int/web/guest/missions/esa-operational-eo-missions/swarm
+.. _EOX: https://eox.at/category/vires/
+.. _`raise an issue on GitHub`: https://github.com/ESA-VirES/VirES-Python-Client/issues
+
+Data and models are processed on demand on the server - a combination of measurements from any time interval can be accessed. These are the same data that can be accessed by the `VirES GUI`_. *viresclient* handles the returned data to allow direct loading as a single pandas.DataFrame_, or xarray.Dataset_.
+
+.. _pandas.DataFrame: https://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe
+.. _xarray.Dataset: http://xarray.pydata.org/en/stable/data-structures.html#dataset
+.. _`VirES GUI`: https://vires.services
+
+.. code-block:: python
+
+ from viresclient import SwarmRequest
+
+ # Set up connection with server
+ request = SwarmRequest()
+ # Set collection to use
+ request.set_collection("SW_OPER_MAGA_LR_1B")
+ # Set mix of products to fetch:
+ #  measurements (variables from the given collection)
+ #  models (magnetic model predictions at spacecraft sampling points)
+ #  auxiliaries (variables available with any collection)
+ request.set_products(
+     measurements=["F", "B_NEC"],
+     models=["CHAOS-Core"],
+     auxiliaries=["QDLat", "QDLon"],
+     sampling_step="PT10S"
+ )
+ # Fetch data from a given time interval
+ data = request.get_between(
+     start_time="2014-01-01T00:00",
+     end_time="2014-01-01T01:00"
+ )
+ # Load the data as an xarray.Dataset
+ ds = data.as_xarray()
+
+.. code-block::
+
+ <xarray.Dataset>
+ Dimensions:           (NEC: 3, Timestamp: 360)
+ Coordinates:
+ * Timestamp         (Timestamp) datetime64[ns] 2014-01-01 ... 2014-01-01T00:59:50
+ Dimensions without coordinates: NEC
+ Data variables:
+   Spacecraft        (Timestamp) <U1 'A' 'A' 'A' 'A' 'A' ... 'A' 'A' 'A' 'A'
+   Latitude          (Timestamp) float64 -1.229 -1.863 -2.496 ... 48.14 48.77
+   Longitude         (Timestamp) float64 -14.12 -14.13 -14.15 ... 153.6 153.6
+   Radius            (Timestamp) float64 6.878e+06 6.878e+06 ... 6.868e+06
+   F                 (Timestamp) float64 2.287e+04 2.281e+04 ... 4.021e+04
+   F_CHAOS-Core      (Timestamp) float64 2.287e+04 2.282e+04 ... 4.02e+04
+   B_NEC             (Timestamp, NEC) float64 2.01e+04 -4.126e+03 ... 3.558e+04
+   B_NEC_CHAOS-Core  (Timestamp, NEC) float64 2.011e+04 ... 3.557e+04
+   QDLat             (Timestamp) float64 -11.99 -12.6 -13.2 ... 41.59 42.25
+   QDLon             (Timestamp) float64 58.02 57.86 57.71 ... -135.9 -136.0
+ Attributes:
+   Sources:         ['SW_OPER_MAGA_LR_1B_20140101T000000_20140101T235959_050...
+   MagneticModels:  ["CHAOS-Core = 'CHAOS-Core'(max_degree=20,min_degree=1)"]
+   RangeFilters:    []
+
+
+*viresclient* is installed on the `"Virtual Research Environment" (VRE)`_, which is a managed Jupyter-based system provided for ESA by EOX. The service is free and open to all.
+
+.. _`"Virtual Research Environment" (VRE)`: https://vre.vires.services/
+
+.. image:: https://github.com/ESA-VirES/Swarm-VRE/raw/master/docs/images/VRE_shortest_demo.gif
+
+
+How to acknowledge VirES
+------------------------
+
+You can reference *viresclient* directly using the DOI of our zenodo_ record. VirES uses data from a number of different sources so please also acknowledge these appropriately.
+
+.. _zenodo: https://doi.org/10.5281/zenodo.2554162
diff --git a/docs/available_parameters.rst b/docs/available_parameters.rst
@@ -98,9 +98,9 @@ Models are evaluated along the satellite track at the positions of the time seri
   MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
 
   # CHAOS models:
-  CHAOS-6-Core,
-  CHAOS-6-Static,
-  CHAOS-6-MMA-Primary, CHAOS-6-MMA-Secondary
+  CHAOS-Core,
+  CHAOS-Static,
+  CHAOS-MMA-Primary, CHAOS-MMA-Secondary
 
   # Other lithospheric models:
   MF7, LCS-1
@@ -111,7 +111,15 @@ Flexible evaluation of models and defining new derived models is possible with t
 
 .. code-block:: python
 
-  "Combined_model = 'MMA_SHA_2F-Primary'(min_degree=1,max_degree=1) + 'MMA_SHA_2F-Secondary'(min_degree=1,max_degree=1)"
+  request.set_products(
+    ...
+    models=["Combined_model = 'MMA_SHA_2F-Primary'(min_degree=1,max_degree=1) + 'MMA_SHA_2F-Secondary'(min_degree=1,max_degree=1)"],
+    ...
+  )
+
+In this case, model evaluations will then be available in the returned data under the name "Combined_model", but you can name it however you like.
+
+NB: When using model names containing a hyphen (``-``) then extra single (``'``) or double (``"``) quotes must be used around the model name. This is to distinguish from arithmetic minus (``-``).
 
 ----
 
@@ -134,7 +142,7 @@ Flexible evaluation of models and defining new derived models is possible with t
 
 .. note::
 
-  - The AMPS model is currently accessible as "auxiliaries" instead of a "model"
+  - The AMPS model is currently accessible as "auxiliaries" instead of a "model" (On the DISC server it is now accessible as a regular model)
   - ``Kp`` provides the Kp values in fractional form (e.g 2.2), and ``Kp10`` is multiplied by 10 (as integers)
   - ``F107`` is the hourly 10.7 cm solar radio flux value, and ``F10_INDEX`` is the daily average
   - ``QDLat`` and ``QDLon`` are quasi-dipole coordinates
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -8,7 +8,7 @@ Installation and first usage
 
   viresclient is already installed so skip this step. Log in at https://vre.vires.services/ and refer to documentation at https://swarm-vre.readthedocs.io/
 
-  You will still need to configure viresclient (see step 2)
+  You may still need to configure viresclient (see step 2)
 
 Python ≥ 3.5 is required. Tested primarily on Linux, but macOS and Windows should also work (on v0.4+).
 
@@ -54,6 +54,15 @@ Recommended setup if starting without Python already
 
 .. note:: For Jupyter notebook users:
 
+  On creation of a SwarmRequest object, you will automatically be prompted to set a token. Just try::
+
+    from viresclient import SwarmRequest
+    request = SwarmRequest()
+
+  and follow the instructions.
+
+  [ Below instructions to be updated with new notebook. ]
+
   The guide for first time usage are also provided as a Jupyter notebook. Download the notebook to your environment and follow the instructions.
 
   https://github.com/smithara/viresclient_examples/blob/master/0_first_usage.ipynb
diff --git a/docs/readme.rst b/docs/readme.rst
@@ -1,47 +1,4 @@
 Introduction
 ============
 
-This is the documentation for the ``viresclient`` Python package. This is a tool which connects to a VirES_ server through the WPS_ interface and handles product requests and downloads. This enables easy access to ESA's Swarm mission data and models. For enquiries or help, please email info@vires.services or `raise an issue on GitHub`_
-
-.. _VirES: https://vires.services
-.. _WPS: http://www.opengeospatial.org/standards/wps
-.. _`raise an issue on GitHub`: https://github.com/ESA-VirES/VirES-Python-Client/issues
-
-Some links where you can read more about VirES:
-
- - `VirES web service`_
- - `Swarm DQW slides about viresclient`_
- - `EOX blog posts`_
- - `Swarm mission`_
-
- .. _`VirES web service`: https://vires.services/
- .. _`Swarm DQW slides about viresclient`: https://github.com/smithara/viresclient_examples/blob/master/viresclient_SwarmDQW8.pdf
- .. _`EOX blog posts`: https://eox.at/category/vires/
- .. _`Swarm mission`: https://earth.esa.int/web/guest/missions/esa-operational-eo-missions/swarm
-
-``viresclient`` is installed on the "Virtual Research Environment" (VRE), which is a managed Jupyter-based system provided by ESA:
-
- - `VRE documentation`_
-
- .. _`VRE documentation`: https://swarm-vre.readthedocs.io/
-
-Data can be accessed from the server as CSV or CDF files and saved to disk, or loaded directly into Python objects pandas.DataFrame_, or xarray.Dataset_.
-
-.. _pandas.DataFrame: https://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe
-
-.. _xarray.Dataset: http://xarray.pydata.org/en/stable/data-structures.html#dataset
-
-cdflib_ is used to read CDF files.
-
-.. _cdflib: https://github.com/MAVENSDC/cdflib
-
-The project is on GitHub at https://github.com/ESA-VirES/VirES-Python-Client - please feel free to contribute with any code/suggestions/comments.
-
-A repository of example notebooks can be found at https://github.com/smithara/viresclient_examples. We welcome contribution of notebooks to this repository that show some short analyses or generating useful figures. It can be hard to remember or figure how do things (e.g. remembering Swarm product names; understanding the VirES "language" and what is possible; making certain kinds of figures with various libraries) so these notebooks are meant to act as recipes we can follow, to demonstrate code that can be copied and adapted for other purposes.
-
-How to acknowledge VirES
-------------------------
-
-You can reference ``viresclient`` directly using the DOI of our zenodo_ record. VirES uses data from a number of different sources so please also acknowledge these appropriately.
-
- .. _zenodo: https://doi.org/10.5281/zenodo.2554163
+.. include:: ../README.rst
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
@@ -1,6 +1,20 @@
 Release notes
 =============
 
+Changes from 0.4.2 to 0.4.3
+---------------------------
+
+- AMPS is now accessible as a regular model on the DISC server, see::
+
+    request = SwarmRequest("https://staging.viresdisc.vires.services/ows")
+    request.get_model_info(["AMPS"])
+
+- xarray.Dataset objects now contain dimension names for all variables. Variables containing "B_NEC" get the "NEC" dimension name.
+- CHAOS model series have changed name: "CHAOS-6-Core" etc. is dropped for "CHAOS-Core" etc. which provides the latest version of the CHAOS models (currently CHAOS-7)
+- Better error message when authentication with server fails.
+- When in notebooks: Detect empty or invalid credentials (e.g. on first usage), direct user to the token generation page, and prompt for token input.
+- Added ``request.list_jobs()`` to give info on previous two jobs on the server (failed/running/succeeded).
+
 Changes from 0.4.1 to 0.4.2
 ---------------------------
 
diff --git a/viresclient/_client.py b/viresclient/_client.py
@@ -560,7 +560,11 @@ def get_between(self, start_time=None, end_time=None,
         return retdatagroup
 
     def list_jobs(self):
-        """ Return job information from the server """
+        """ Return job information from the server.
+
+        Returns:
+            dict
+        """
         templatefile = TEMPLATE_FILES['list_jobs']
         template = JINJA2_ENVIRONMENT.get_template(templatefile)
         request = template.render().encode('UTF-8')
diff --git a/viresclient/_client_swarm.py b/viresclient/_client_swarm.py
@@ -296,17 +296,37 @@ def custom_shc(self, custom_shc):
 class SwarmRequest(ClientRequest):
     """Handles the requests to and downloads from the server.
 
-    Steps to download data:
-
-    1. Set up a connection to the server with: request = SwarmRequest()
-
-    2. Set collections to use with: request.set_collections()
-
-    3. Set parameters to get with: request.set_products()
+    Example usage::
+
+        from viresclient import SwarmRequest
+        # Set up connection with server
+        request = SwarmRequest()
+        # Set collection to use
+        request.set_collection("SW_OPER_MAGA_LR_1B")
+        # Set mix of products to fetch:
+        #  measurements (variables from the given collection)
+        #  models (magnetic model predictions at spacecraft sampling points)
+        #  auxiliaries (variables available with any collection)
+        request.set_products(
+            measurements=["F", "B_NEC"],
+            models=["CHAOS-Core"],
+            auxiliaries=["QDLat", "QDLon"],
+            sampling_step="PT10S"
+        )
+        # Fetch data from a given time interval
+        data = request.get_between(
+            start_time="2014-01-01T00:00",
+            end_time="2014-01-01T01:00"
+        )
+        # Load the data as an xarray.Dataset
+        ds = data.as_xarray()
 
-    4. Set filters to apply with: request.set_range_filter()
+    Check what data are available with::
 
-    5. Get the data in a chosen time window: request.get_between()
+        request.available_collections(details=False)
+        request.available_measurements("MAG")
+        request.available_auxiliaries()
+        request.available_models(details=False)
 
     Args:
         url (str):
@@ -623,6 +643,7 @@ def set_collection(self, *args):
                     )
         self._collection_list = collections
         self._request_inputs.set_collections(collections)
+        return self
 
     def set_products(self, measurements=None, models=None, custom_model=None,
                      auxiliaries=None, residuals=False, sampling_step=None
@@ -717,6 +738,7 @@ def set_products(self, measurements=None, models=None, custom_model=None,
         self._request_inputs.variables = variables
         self._request_inputs.sampling_step = sampling_step
         self._request_inputs.custom_shc = custom_shc
+        return self
 
     def set_range_filter(self, parameter=None, minimum=None, maximum=None):
         """Set a filter to apply.
@@ -743,11 +765,13 @@ def set_range_filter(self, parameter=None, minimum=None, maximum=None):
             filters = ';'.join(self._filterlist)
         # Update the SwarmWPSInputs object
         self._request_inputs.filters = filters
+        return self
 
     def clear_range_filter(self):
         """Remove all applied filters."""
         self._filterlist = []
         self._request_inputs.filters = None
+        return self
 
     def get_times_for_orbits(self, spacecraft, start_orbit, end_orbit):
         """Translate a pair of orbit numbers to a time interval.
diff --git a/viresclient/_data_handling.py b/viresclient/_data_handling.py
@@ -398,6 +398,14 @@ class ReturnedData(object):
     The number of them, N, is set upon initialisation.
     Access the ReturnedDataFile objects directly via the list in ReturnedData.contents.
 
+    Example usage::
+
+        ...
+        data = request.get_between(..., ...)
+        data.as_xarray()
+        data.as_dataframe(expand=True)
+        data.to_file()
+
     """
 
     def __init__(self, filetype=None, N=1, tmpdir=None):
