Update docs to prepare for 0.8.0 release

README.rst

@@ -23,12 +23,12 @@
 
   pip install viresclient
 
-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_ 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 about the service and problems with accessing your account, please email info@vires.services. For help with usage, please email ashley.smith@ed.ac.uk 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
+.. _`Swarm mission`: https://earth.esa.int/eogateway/missions/swarm
 .. _EOX: https://eox.at/category/vires/
 .. _`raise an issue on GitHub`: https://github.com/ESA-VirES/VirES-Python-Client/issues
 
@@ -91,9 +91,10 @@ Data and models are processed on demand on the server - a combination of measure
    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.
+*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. See `"Swarm Notebooks"`_ for how-to guides with Swarm data and guidance in using the VRE.
 
-.. _`"Virtual Research Environment" (VRE)`: https://vre.vires.services/
+.. _`"Virtual Research Environment" (VRE)`: https://vre.vires.services
+.. _`"Swarm Notebooks"`: https://swarm.magneticearth.org
 
 .. image:: https://github.com/ESA-VirES/Swarm-VRE/raw/master/docs/images/VRE_shortest_demo.gif
 

docs/api.rst

@@ -6,6 +6,7 @@ SwarmRequest
     :undoc-members:
     :show-inheritance:
     :inherited-members:
+    :exclude-members: AUXILIARY_VARIABLES, COLLECTIONS, COLLECTION_SAMPLING_STEPS, MAGNETIC_MODELS, MAGNETIC_MODEL_VARIABLES, OBS_COLLECTIONS, PRODUCT_VARIABLES
 
 ReturnedData
 ============

docs/available_parameters.rst

@@ -3,7 +3,7 @@ Available parameters for Swarm data
 
 .. note::
 
-  | `See also: Jupyter notebook about data and model availability <https://swarm-vre.readthedocs.io/en/latest/Swarm_notebooks/02b__viresclient-Available-Data.html>`_ - check out the other demo notebooks there too. If you can't see a suitable recipe to help you get started, do `get in touch <https://swarm-vre.readthedocs.io/en/latest/help.html>`_ (email ashley.smith@ed.ac.uk) and I will help you out.
+  | `See also: Jupyter notebook about data and model availability <https://swarm.magneticearth.org/notebooks/02b__viresclient-available-data>`_ - check out the other demo notebooks there too.
 
 You can check which parameters are available with:
 
@@ -23,9 +23,9 @@ The available measurements are segregated according to the "collection" (essenti
 
 See the `Swarm Data Handbook`_ for details about the products and `Swarm Product Demos`_ (Jupyter notebooks) for basic recipes to get started.
 
-.. _`Swarm Data Handbook`: https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/
+.. _`Swarm Data Handbook`: https://earth.esa.int/eogateway/missions/swarm/product-data-handbook
 
-.. _`Swarm Product Demos`: https://swarm-vre.readthedocs.io/en/latest/Swarm_notebooks.html#swarm-product-demos
+.. _`Swarm Product Demos`: https://swarm.magneticearth.org/notebooks/03a1_demo-magx_lr_1b
 
 ----
 
@@ -75,6 +75,23 @@ SW_OPER_AUX_OBSS2\_       AUX_OBSS         Second values from INTERMAGNET
 
 The AUX_OBS collections contain data from all observatories together (distinguishable by the ``IAGA_code`` variable). Data from a single observatory can be accessed with special collection names like ``SW_OPER_AUX_OBSM2_:ABK`` where ``ABK`` can be replaced with the IAGA code of the observatory. Use :py:meth:`viresclient.SwarmRequest.available_observatories` to find these IAGA codes.
 
+The VOBS collections contain derived magnetic measurements from `Geomagnetic Virtual Observatories <https://earth.esa.int/eogateway/activities/gvo>`_ and have a similar interface as the AUX_OBS collections. The data are organised across several collections:
+
+==================================== =========================== ==========================================================================
+Collection full name                 Collection type             Description
+==================================== =========================== ==========================================================================
+SW_OPER_VOBS_1M_2\_                  VOBS_SW_1M                  Swarm (1-monthly cadence)
+SW_OPER_VOBS_4M_2\_                  VOBS_SW_4M                  Swarm (4-monthly)
+OR_OPER_VOBS_4M_2\_                  VOBS_OR_4M                  Ørsted (4-monthly)
+CH_OPER_VOBS_4M_2\_                  VOBS_CH_4M                  CHAMP (4-monthly)
+CR_OPER_VOBS_4M_2\_                  VOBS_CR_4M                  Cryosat-2 (4-monthly)
+CO_OPER_VOBS_4M_2\_                  VOBS_CO_4M                  Composite time series from Ørsted, CHAMP, Cryosat-2, & Swarm (4-monthly)
+SW_OPER_VOBS_1M_2\_:SecularVariation VOBS_SW_1M:SecularVariation Secular variation (``B_SV``) from Swarm 1-monthly
+(ditto for the others)
+==================================== =========================== ==========================================================================
+
+Each VOBS product (e.g. Swarm 1-monthly) is split into two collections (e.g. ``SW_OPER_VOBS_1M_2_`` (containing ``B_OB`` & ``B_CF``) and ``SW_OPER_VOBS_1M_2_:SecularVariation`` (containing ``B_SV``)) because of the different temporal sampling points (i.e. differing ``Timestamp``) of these measurements. Data can also be requested for a specific virtual observatory alone (distinguishable by the ``SiteCode`` variable) with special collection names like ``SW_OPER_VOBS_1M_2_:N65W051`` and ``SW_OPER_VOBS_1M_2_:SecularVariation:N65W051``.
+
 The ``measurements``, ``models``, and ``auxiliaries`` chosen will match the cadence of the ``collection`` chosen.
 
 ----
@@ -117,11 +134,29 @@ AUX_OBS products:
 =============== =========================================
 Collection type Available measurement names
 =============== =========================================
-AUX_OBSH        ``B_NEC,F,IAGA_code,Quality,SensorIndex``
+AUX_OBSH        ``B_NEC,F,IAGA_code,Quality,ObsIndex``
 AUX_OBSM        ``B_NEC,F,IAGA_code,Quality``
 AUX_OBSS        ``B_NEC,F,IAGA_code,Quality``
 =============== =========================================
 
+AUX_OBSH contains a special variable, ``ObsIndex``, which is set to 0, 1, 2 ... to indicate changes to the observatory where the IAGA code has remained the same (e.g. small change of location, change of instrument or calibration procedure).
+
+VOBS products:
+
+==================================== =========================================== 
+Collection full name                 Available measurement names
+==================================== ===========================================
+SW_OPER_VOBS_1M_2\_                  ``SiteCode,B_CF,B_OB,sigma_CF,sigma_OB``
+SW_OPER_VOBS_4M_2\_                  ``SiteCode,B_CF,B_OB,sigma_CF,sigma_OB``
+OR_OPER_VOBS_4M_2\_                  ``SiteCode,B_CF,B_OB,sigma_CF,sigma_OB``
+CH_OPER_VOBS_4M_2\_                  ``SiteCode,B_CF,B_OB,sigma_CF,sigma_OB``
+CR_OPER_VOBS_4M_2\_                  ``SiteCode,B_CF,B_OB,sigma_CF,sigma_OB``
+CO_OPER_VOBS_4M_2\_                  ``SiteCode,B_CF,B_OB,sigma_CF,sigma_OB``
+SW_OPER_VOBS_1M_2\_:SecularVariation ``SiteCode,B_SV,sigma_SV``
+(ditto for the others)
+==================================== ===========================================
+
+
 ----
 
 ``models``
@@ -220,7 +255,7 @@ NB: When using model names containing a hyphen (``-``) then extra single (``'``)
 
 .. note::
 
-  Check other packages such `hapiclient`_ and others from `PyHC`_ for data from other sources.
+  Check other packages such as `hapiclient`_ and others from `PyHC`_ for data from other sources.
 
 .. _`hapiclient`: https://github.com/hapi-server/client-python
 

docs/conf.py

@@ -50,7 +50,8 @@
     'sphinx.ext.napoleon',
     'nbsphinx',
     'sphinx.ext.imgmath',
-    'sphinx.ext.autosectionlabel'
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.viewcode',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -1,11 +1,14 @@
-Welcome to VirES-Python-Client's documentation!
+Welcome to viresclient's documentation!
 ===============================================
 
+Get started `at the introduction <readme.html>`_
+
 .. toctree::
   :caption: Virtual Research Environment
 
-  --> [Launch VRE] JupyterLab <https://vre.vires.services/>
-  --> [VRE docs] Guides and Recipes <https://swarm-vre.readthedocs.io/en/latest/intro.html>
+  🔗 [Launch VRE / JupyterLab] <https://vre.vires.services>
+  🔗 How-To Guides [Swarm Notebooks] <https://swarm.magneticearth.org>
+  🔗 VirES Graphical Interface <https://vires.services>
 
 .. toctree::
   :maxdepth: 2
@@ -35,5 +38,6 @@ Welcome to VirES-Python-Client's documentation!
   :maxdepth: 2
   :caption: External Links
 
-  GitHub: viresclient <https://github.com/ESA-VirES/VirES-Python-Client/>
-  GitHub: Swarm-DISC <https://github.com/Swarm-DISC/>
+  🔗 GitHub: viresclient <https://github.com/ESA-VirES/VirES-Python-Client/>
+  🔗 GitHub: Swarm-DISC <https://github.com/Swarm-DISC/>
+  🔗 Magnetic Earth <https://magneticearth.org>

docs/installation.rst

@@ -1,12 +1,12 @@
-Installation and first usage
+Installation and First Usage
 ============================
 
 1. Installation
 ---------------
 
-.. note:: For VRE (Virtual Research Environment) users (it's free! - `read more <https://swarm-vre.readthedocs.io/>`_):
+.. note:: For VRE (Virtual Research Environment) users (it's free! - `read more <https://swarm.magneticearth.org>`_):
 
-  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/. The access token should be automatically configured so you can jump in with the notebook demos.
+  viresclient is already installed so skip this step. Log in at https://vre.vires.services and refer to `the introduction notebooks <https://swarm.magneticearth.org/notebooks/02a__intro-swarm-viresclient>`_.
 
 Python ≥ 3.6 is required. Testing is primarily on Linux, but macOS and Windows should also work.
 
@@ -24,7 +24,7 @@ Dependencies::
   pandas
   xarray
 
-pip will fetch these automatically - if you are using conda, it may be better to install these first using conda instead::
+pip will fetch these automatically - if you are using conda, it may be better to install these first using conda instead (where available)::
 
     conda install requests jinja2 pytables tqdm pandas xarray
     pip install viresclient
@@ -35,11 +35,11 @@ Recommended setup if starting without Python already
 1. Install Miniconda: https://docs.conda.io/en/latest/miniconda.html
 2. Create a new conda environment with some recommended packages::
 
-    conda create --name py37 scipy matplotlib pandas xarray cartopy jupyter jupyterlab flake8 dask h5py netCDF4 jinja2 pytables tqdm
+    conda create --name myenv scipy matplotlib pandas xarray cartopy jupyter jupyterlab flake8 dask h5py netCDF4 jinja2 pytables tqdm
 
   Activate the new environment (you do this each time you want to use it)::
 
-    conda activate py37
+    conda activate myenv
 
 3. Use pip to install viresclient::
 
@@ -59,7 +59,7 @@ Recommended setup if starting without Python already
 
   and follow the instructions.
 
-  A first usage guide is provided as a Jupyter notebook (`view <https://swarm-vre.readthedocs.io/en/latest/Swarm_notebooks/02a__Intro-Swarm-viresclient.html>`_). 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::
+  A first usage guide is provided as a Jupyter notebook (`view <https://swarm.magneticearth.org/notebooks/02a__intro-swarm-viresclient>`_). To run the notebook on your computer running Jupyter locally, `right click here to download <https://raw.githubusercontent.com/Swarm-DISC/Swarm_notebooks/master/notebooks/02a__Intro-Swarm-viresclient.ipynb>`_, or use git to get the whole example repository::
 
     git clone https://github.com/Swarm-DISC/Swarm_notebooks.git
 

docs/notebook_intro.rst

@@ -1,36 +1,38 @@
 Introduction to notebooks
 =========================
 
-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/>`_.
+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.
 
 
 
 .. list-table:: Notebook repositories
    :header-rows: 1
-   :widths: 7 5 5
 
    *  -  Name (GitHub Link)
-      -  View (nbviewer)
-      -  Launch/interact (VRE)
+      -  View (static/docs)
+      -  Launch/interact
+      -  Description
    *  -  `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)
+      -  .. image:: https://img.shields.io/badge/render-JupyterBook-orange.svg
+            :target: https://swarm.magneticearth.org
+      -  .. image:: https://img.shields.io/badge/nbgitpuller-VRE-blue
+            :target: https://vre.vires.services/hub/user-redirect/git-pull?repo=https://github.com/Swarm-DISC/Swarm_notebooks&urlpath=lab/tree/Swarm_notebooks/notebooks/
+      -  Curated Swarm notebooks for scientists
    *  -  `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)
+      -  .. image:: https://img.shields.io/badge/nbgitpuller-VRE-blue
+            :target: https://vre.vires.services/hub/user-redirect/git-pull?repo=https://github.com/pacesm/jupyter_notebooks&urlpath=lab/tree/jupyter_notebooks/
+      -  Reference mainly during new product registration and configuration
 
 
 .. 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).
+
+  In the case of ``Swarm_notebooks``, the notebooks are stored in the repository *without outputs included*, so are better viewed at `swarm.magneticearth.org <https://swarm.magneticearth.org>`_ (the *Jupyter Book* link 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:
+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 Terminal and use git:
 
 To clone a repository to your working space::
 
@@ -42,3 +44,5 @@ To clear any changes you made and fetch the latest version, from within ``Swarm_
 
     git fetch
     git reset --hard origin/master
+
+The *nbgitpuller* links above perform a ``git clone`` operation for you, and applies updates when you re-click the link using special `automatic merging behaviour <https://jupyterhub.github.io/nbgitpuller/topic/automatic-merging.html>`_. Sometimes it may be necessary to perform the git operations directly instead.