Bump to v0.5.0 and update docs.

Author: smithara

docs/available_parameters.rst

@@ -93,6 +93,7 @@ Models are evaluated along the satellite track at the positions of the time seri
   MCO_SHA_2D,
   MLI_SHA_2D,
   MIO_SHA_2D-Primary, MIO_SHA_2D-Secondary
+  AMPS
 
   # Fast-track models:
   MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
@@ -134,10 +135,7 @@ NB: When using model names containing a hyphen (``-``) then extra single (``'``)
   AscendingNodeLongitude, QDLat, QDLon, QDBasis, MLT, SunDeclination,
   SunHourAngle, SunRightAscension, SunAzimuthAngle, SunZenithAngle,
   SunLongitude, SunVector, DipoleAxisVector, NGPLatitude, NGPLongitude,
-  DipoleTiltAngle,
-
-  UpwardCurrent, TotalCurrent,                        # AMPS
-  DivergenceFreeCurrentFunction, F_AMPS, B_NEC_AMPS   # AMPS
+  DipoleTiltAngle
 
 
 .. note::

docs/conf.py

@@ -14,6 +14,7 @@
 #
 import os
 import sys
+import urllib.request
 sys.path.insert(0, os.path.abspath('..'))
 
 
@@ -109,6 +110,14 @@
 #
 # html_sidebars = {}
 
+# Fetch and use external logo
+logo_filename = 'vre_logo.svg'
+if not os.path.exists(logo_filename):
+    urllib.request.urlretrieve(
+        'https://raw.githubusercontent.com/ESA-VirES/Swarm-VRE/staging/docs/_static/vre_logo.svg',
+        logo_filename)
+html_logo = logo_filename
+
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/index.rst

@@ -1,23 +1,23 @@
 Welcome to VirES-Python-Client's documentation!
 ===============================================
 
+.. toctree::
+  :caption: Virtual Research Environment
+
+  --> [Launch VRE] <https://vre.vires.services/>
+  --> [VRE docs] <https://swarm-vre.readthedocs.io/en/latest/intro.html>
+
 .. toctree::
   :maxdepth: 2
-  :caption: Overview
+  :caption: Information on viresclient
 
   readme
   installation
   config_details
   access_token
   available_parameters
-  release_notes
-
-.. toctree::
-  :maxdepth: 2
-  :caption: Example notebooks
-
   notebook_intro
-  notebooks/simple_example
+  release_notes
 
 .. toctree::
   :maxdepth: 2
@@ -35,8 +35,5 @@ Welcome to VirES-Python-Client's documentation!
   :maxdepth: 2
   :caption: External Links
 
-  Notebook repository <https://nbviewer.jupyter.org/github/smithara/viresclient_examples/>
-  VirES web interface <https://vires.services/>
-  VirES-VRE <https://vre.vires.services/>
-  viresclient GitHub <https://github.com/ESA-VirES/VirES-Python-Client/>
-  Swarm-DISC GitHub <https://github.com/Swarm-DISC/>
+  GitHub: viresclient <https://github.com/ESA-VirES/VirES-Python-Client/>
+  GitHub: Swarm-DISC <https://github.com/Swarm-DISC/>

docs/installation.rst

@@ -61,19 +61,11 @@ Recommended setup if starting without Python already
 
   and follow the instructions.
 
-  [ Below instructions to be updated with new notebook. ]
+  A first usage guide is provided as a Jupyter notebook (`view <https://nbviewer.jupyter.org/github/Swarm-DISC/Swarm_notebooks/blob/master/02a__Intro-Swarm-viresclient.ipynb>`_). To run the notebook on your computer running Jupyter locally, `right click here to download <https://raw.githubusercontent.com/Swarm-DISC/Swarm_notebooks/master/02a__Intro-Swarm-viresclient.ipynb>`_, or use git to get the whole example repository::
 
-  The guide for first time usage are also provided as a Jupyter notebook. Download the notebook to your environment and follow the instructions.
+    git clone https://github.com/Swarm-DISC/Swarm_notebooks.git
 
-  https://github.com/smithara/viresclient_examples/blob/master/0_first_usage.ipynb
-
-  To download the whole example repository, open a terminal and do::
-
-    git clone https://github.com/smithara/viresclient_examples.git
-
-  then launch the notebook, ``viresclient_examples/0_first_usage.ipynb``
-
-Access to the service is through the same user account as on the web interface (https://vires.services/) and is enabled through an access token (essentially a password). To get a token, log in to the website and click on your name on the top right to access the settings. From here, click on "Manage access tokens" and follow the instructions to create a new token.
+Access to the service is through the same user account as on the web interface (https://vires.services/) and is enabled through an access token (essentially a password). To get a token, log in to the website and click on your name on the top right to access the settings (`or follow this link <https://vires.services/accounts/tokens/>`_). From here, click on "Manage access tokens" and follow the instructions to create a new token.
 
 To set your token in the client, use either the Python interface:
 

docs/notebook_intro.rst

@@ -1,26 +1,44 @@
 Introduction to notebooks
 =========================
 
-Jupyter notebooks are a convenient tool for interactive data exploration and are used here to demonstrate usage of ``viresclient``. We encourage users to try out Jupyter for themselves and to consider sharing notebooks with others. If you have a comment about one of the notebooks, or would like a particular demonstration, you can `open a GitHub Issue <https://github.com/smithara/viresclient_examples/issues/new>`_ or get in touch otherwise.
+Jupyter notebooks are a convenient tool for interactive data exploration, rapid prototyping, and producing reports. The Virtual Research Environment provides free JupyterLab instances with persistent storage where you can run notebooks working with Swarm data. For more information, see the `Swarm-VRE docs <https://swarm-vre.readthedocs.io/>`_.
 
-Click `here <https://nbviewer.jupyter.org/github/smithara/viresclient_examples/>`_ (nbviewer) to view viresclient_examples non-interactively. Sometimes notebooks won't render directly on the GitHub website - try `nbviewer <https://nbviewer.jupyter.org/>`_ instead.
 
-Here is a list of related notebook repositories where you are welcome to submit changes or additions. Please get in touch if you would like your own repository to be listed here.
 
- - https://github.com/smithara/viresclient_examples
- - https://github.com/pacesm/jupyter_notebooks
+.. list-table:: Notebook repositories
+   :header-rows: 1
+   :widths: 7 5 5
 
-Other repositories with wider scope:
+   *  -  Name (GitHub Link)
+      -  View (nbviewer)
+      -  Launch/interact (VRE)
+   *  -  `Swarm-DISC/Swarm_notebooks <https://github.com/Swarm-DISC/Swarm_notebooks>`_
+      -  .. image:: https://img.shields.io/badge/render-nbviewer-orange.svg
+            :target: https://nbviewer.jupyter.org/github/Swarm-DISC/Swarm_notebooks
+      -  (to do)
+   *  -  `smithara/viresclient_examples <https://github.com/smithara/viresclient_examples>`_
+      -  .. image:: https://img.shields.io/badge/render-nbviewer-orange.svg
+            :target: https://nbviewer.jupyter.org/github/smithara/viresclient_examples
+      -  (to do)
+   *  -  `pacesm/jupyter_notebooks <https://github.com/pacesm/jupyter_notebooks>`_
+      -  .. image:: https://img.shields.io/badge/render-nbviewer-orange.svg
+            :target: https://nbviewer.jupyter.org/github/pacesm/jupyter_notebooks
+      -  (to do)
 
- - https://github.com/smithara/IAGA_SummerSchool2019
+
+.. note::
+
+  Sometimes notebooks won't render directly on the GitHub website (or are slow). Try `nbviewer <https://nbviewer.jupyter.org/>`_ instead (see the "Render" links above).
+
+Notebooks can be uploaded to JupyterLab using the "Upload" button (which means you must first download the notebooks to your computer from GitHub). To easily access a full repository, open a command line console and use git:
 
 To clone a repository to your working space::
 
-    cd ~
-    git clone https://github.com/smithara/viresclient_examples.git
+    git clone https://github.com/Swarm-DISC/Swarm_notebooks.git
+
+(this will clone it into ``Swarm_notebooks`` within your current directory)
 
-To clear any changes you made and fetch the latest version::
+To clear any changes you made and fetch the latest version, from within ``Swarm_notebooks`` run::
 
-    cd ~/viresclient_examples/
     git fetch
     git reset --hard origin/master

docs/release_notes.rst

@@ -1,17 +1,17 @@
 Release notes
 =============
 
-Changes from 0.4.3 to 0.5.0 (alpha)
------------------------------------
+Changes from 0.4.3 to 0.5.0
+---------------------------
 
 - IGRF model series have changed name: ``IGRF-12`` is dropped in favour of ``IGRF`` which now provides the latest IGRF (currently IGRF-13)
-- ``request.available_collections("MAG")`` can now be called to filter by collection groups, and now returns a dict instead of a list
+- ``request.available_collections("MAG")`` can now be called to filter by collection groups, *and now returns a dict instead of a list*
 - Improvements for ``xarray.Dataset`` support:
 
   - NEC now provided as named coordinates for ``B_NEC``-type variables
+  - Similarly (VFM, quaternion, WGS84) coordinates also provided for the variables ["B_VFM", "dB_Sun", "dB_AOCS", "dB_other", "B_error"], ["q_NEC_CRF"], ["GPS_Position", "LEO_Position"] respectively
   - Metadata (units and description) are now set for each variable
   - (With xarray 0.14+, try ``xarray.set_options(display_style="html")`` for nicer output)
-  - Changed global attributes setting to set as "; "-separated strings instead of lists, to solve https://github.com/pydata/xarray/issues/3647
 
 Changes from 0.4.2 to 0.4.3
 ---------------------------

viresclient/__init__.py

@@ -34,4 +34,4 @@
 from ._data_handling import ReturnedDataFile
 from ._api.upload import DataUpload
 
-__version__ = "0.5.0-alpha"
+__version__ = "0.5.0"

viresclient/_client_swarm.py

@@ -508,7 +508,7 @@ def available_collections(self, groupname=None, details=True):
         """Show details of available collections.
 
         Args:
-            collection_group (str): one of: ("MAG", "EFI", etc.)
+            groupname (str): one of: ("MAG", "EFI", etc.)
             details (bool): If True then print a nice output.
                 If False then return a dict of available collections.
 

viresclient/_config.py

@@ -82,15 +82,15 @@ def set_token(url="https://vires.services/ows", token=None, set_default=False):
         if IN_JUPYTER:
             def _linkify(_url):
                 if _url:
-                    return f'<a href="{_url}">{_url}</a>'
+                    return '<a href="{}">{}</a>'.format(_url, _url)
                 else:
                     return '(link not found)'
             display_html(
-                f'Setting access token for {url}...<br>'
-                f'Generate a token at {_linkify(url4token)}',
+                'Setting access token for {}...<br>'.format(url)
+                + 'Generate a token at {}'.format(_linkify(url4token)),
                 raw=True)
         else:
-            print('Setting access token for', url, '...')
+            print('Setting access token for', url, ' ...')
             url4token = url4token if url4token else '(link not found)'
             print('Generate a token at', url4token)
         token = getpass("Enter token:")

viresclient/_data_handling.py

@@ -181,6 +181,9 @@ def as_pandas_dataframe(self, expand=False):
         return df
 
     def as_xarray_dataset(self):
+        # NB currrently does not set the global metadata (attrs)
+        #  (avoids issues with concatenating them)
+        #  (this is done in ReturnedData)
         # Initialise dataset with time coordinate
         ds = xarray.Dataset(
             coords={"Timestamp":
@@ -620,13 +623,22 @@ def to_file(self, path, overwrite=False):
         Only write to file if it does not yet exist, or if overwrite=True.
         Currently handles CSV and CDF formats.
 
+        .. note::
+
+            This is currently only implemented for smaller data when the
+            request has not been split into multiple requests - the limit is
+            the equivalent of 50 days of 1Hz measurements. In these situations,
+            you can still load the data as pandas/xarray objects (the contents
+            of each file is automatically concatenated) and save them as a
+            different file type. Or use ``.to_files()`` to save the split data
+            directly.
+
         Args:
             path (str): path to the file to save as
             overwrite (bool): Will overwrite existing file if True
 
         """
         if len(self.contents) != 1:
-            raise Exception("Data is split into multiple files. "
-                            "Use .to_files instead"
-                            )
+            raise NotImplementedError(
+                "Data is split into multiple files. Use .to_files instead")
         self.contents[0].to_file(path, overwrite)