Update docs.

docs/available_parameters.rst

@@ -25,6 +25,7 @@ You can check which parameters are available with:
   SW_OPER_TECxTMS_2F
   SW_OPER_FACxTMS_2F
   SW_OPER_EEFxTMS_2F
+  SW_OPER_IPDxIRR_2F
 
 For Alpha-Charlie FAC: ``collection="SW_OPER_FAC_TMS_2F"``.
 
@@ -61,6 +62,10 @@ For EEF::
 
   EEF,RelErr,flags
 
+For IPD::
+
+  Ne,Te,Background_Ne,Foreground_Ne,PCP_flag,Grad_Ne_at_100km,Grad_Ne_at_50km,Grad_Ne_at_20km,Grad_Ne_at_PCP_edge,ROD,RODI10s,RODI20s,delta_Ne10s,delta_Ne20s,delta_Ne40s,Num_GPS_satellites,mVTEC,mROT,mROTI10s,mROTI20s,IBI_flag,Ionosphere_region_flag,IPIR_index,Ne_quality_flag,TEC_STD
+
 ----
 
 ``models``
@@ -90,18 +95,25 @@ Flexible evaluation of models and defining new derived models is possible with t
 
 ::
 
-  SyncStatus, Kp10, Kp, Dst, IMF_BY_GSM, IMF_BZ_GSM, IMF_V, F10_INDEX,
+  SyncStatus, Kp10, Kp, Dst, IMF_BY_GSM, IMF_BZ_GSM, IMF_V, F107, F10_INDEX,
   OrbitDirection, QDOrbitDirection,
   OrbitSource, OrbitNumber, AscendingNodeTime,
   AscendingNodeLongitude, QDLat, QDLon, QDBasis, MLT, SunDeclination,
   SunHourAngle, SunRightAscension, SunAzimuthAngle, SunZenithAngle,
   SunLongitude, SunVector, DipoleAxisVector, NGPLatitude, NGPLongitude,
   DipoleTiltAngle,
 
-  UpwardCurrent, TotalCurrent,
-  DivergenceFreeCurrentFunction, F_AMPS, B_NEC_AMPS
+  UpwardCurrent, TotalCurrent,                        # AMPS
+  DivergenceFreeCurrentFunction, F_AMPS, B_NEC_AMPS   # AMPS
+
+
+.. note::
 
-NB: the AMPS model is currently accessible as "auxiliaries" instead of a "model".
+  - The AMPS model is currently accessible as "auxiliaries" instead of a "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
+  - ``OrbitDirection`` and ``QDOrbitDirection`` flags indicate if the satellite is moving towards or away from each pole, respectively for geographic and quasi-dipole magnetic poles. +1 for ascending, and -1 for descending (in latitude); 0 for no data.
 
 ----
 

docs/conf.py

@@ -96,7 +96,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/installation.rst

@@ -1,12 +1,16 @@
 Installation and first usage
 ============================
 
-Installation
-------------
+1. Installation
+---------------
 
-Linux/Unix and Python ≥ 3.5 is required for full support (since cdflib requires ≥ 3.5).
+.. note:: For VRE (Virtual Research Environment) users:
 
-Python 3.4 can also be used, but conversion from CDF to pandas/xarray is not supported - you can still download and save CDF files - :meth:`viresclient.ReturnedData.to_file`, or download as CSV files and convert to pandas - :meth:`viresclient.ReturnedData.as_dataframe`.
+  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)
+
+Python ≥ 3.5 is required. Tested primarily on Linux, but macOS and Windows should also work (on v0.4+).
 
 It can currently be installed with::
 
@@ -15,20 +19,49 @@ It can currently be installed with::
 Dependencies::
 
   Jinja2 ≥ 2.10.0
-  pandas ≥ 0.18.0
-  cdflib = 0.3.9
   tables ≥ 3.4.4
   tqdm   ≥ 4.23.0
-  xarray ≥ 0.10.0
+  cdflib ≥ 0.3.9
+  pandas ≥ 0.18.0
+  xarray ≥ 0.11.0
+
+(pip will fetch these automatically - if you are using conda, it may be better to install these first using conda instead::
+
+    conda install jinja2 pytables tqdm pandas xarray
+    pip install viresclient
+
+Recommended setup if starting without Python already
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Install Miniconda for Python 3.7: 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
+
+  Activate the new environment (you do this each time you want to use it)::
+
+    conda activate py37
+
+3. Use pip to install viresclient::
 
-(pip will fetch these automatically - if you are using conda, it may be better to install these first using conda instead)
+    pip install viresclient
 
-There is an unresolved bug with Windows support - see here_.
 
-.. _here: https://github.com/ESA-VirES/VirES-Python-Client/issues/1
 
-First usage / Configuration
----------------------------
+2. First usage / Configuration
+------------------------------
+
+.. note:: For Jupyter notebook users:
+
+  The instructions for first time usage are also provided as a Jupyter notebook which you might find easier to use. Download the notebook to your environment and follow the instructions.
+
+  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 a token. 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.
 
@@ -124,8 +157,12 @@ When creating the configuration file manually make sure the file is readable by
     request = SwarmRequest(url="https://staging.viresdisc.vires.services/ows")
 
 
-Example use
------------
+3. Example use
+--------------
+
+.. note::
+
+  A brief introduction is given here. For more possibilities, see :doc:`notebook_intro`
 
 Choose which collection to access (see :doc:`available_parameters` for more options):
 
@@ -162,14 +199,12 @@ Set a parameter range filter to apply. You can add multiple filters in sequence
 
   request.set_range_filter("Longitude", 0, 90)
 
-Specify the time range from which to retrieve data, make the request to the server (specifying the output file format, currently either csv or cdf):
+Specify the time range from which to retrieve data, make the request to the server:
 
 .. code-block:: python
 
   data = request.get_between(start_time=dt.datetime(2016,1,1),
-                             end_time=dt.datetime(2016,1,2),
-                             filetype="cdf",
-                             asynchronous=True)
+                             end_time=dt.datetime(2016,1,2))
 
 Transfer your data to a pandas.DataFrame_, or a xarray.Dataset_, or just save it as is:
 
@@ -184,9 +219,12 @@ Transfer your data to a pandas.DataFrame_, or a xarray.Dataset_, or just save it
   data.to_file('outfile.cdf', overwrite=False)
 
 The returned data has columns for:
+
  - ``Spacecraft, Timestamp, Latitude, Longitude, Radius``
  - those specified by ``measurements`` and ``auxiliaries``
+
 ... and model values and residuals, named as:
+
    - ``F_<model_id>``           -- scalar field
    - ``B_NEC_<model_id>``       -- vector field
    - ``F_res_<model_id>``       -- scalar field residual (``F - F_<model_id>``)

docs/notebook_intro.rst

@@ -3,7 +3,24 @@ 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.
 
+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
+
+Other repositories with wider scope:
+
+ - https://github.com/smithara/IAGA_SummerSchool2019
+
+To clone a repository to your working space::
+
+    cd ~
+    git clone https://github.com/smithara/viresclient_examples.git
+
+To clear any changes you made and fetch the latest version::
+
+    cd ~/viresclient_examples/
+    git fetch
+    git reset --hard origin/master