Updated docs to current behaviour.

README.rst

@@ -6,7 +6,7 @@ viresclient
     :target: https://badge.fury.io/py/viresclient
 
 .. image:: https://readthedocs.org/projects/viresclient/badge/?version=latest
-    :target: http://viresclient.readthedocs.io/en/latest/?badge=latest
+    :target: http://viresclient.readthedocs.io/
     :alt: Documentation Status
 
 .. image:: https://travis-ci.org/ESA-VirES/VirES-Python-Client.svg?branch=master
@@ -22,4 +22,4 @@ Install with::
 
   pip install viresclient
 
-Full documentation: http://viresclient.readthedocs.io/en/latest/
+Full documentation: http://viresclient.readthedocs.io/

docs/api.rst

@@ -1,8 +1,3 @@
-viresclient
-===========
-
-.. automodule:: viresclient
-
 SwarmRequest
 ============
 
@@ -21,7 +16,7 @@ ReturnedData
     :show-inheritance:
     :inherited-members:
 
-.. autoclass:: viresclient.ReturnedDataGroup
+.. autoclass:: viresclient.ReturnedDataFile
     :members:
     :undoc-members:
     :show-inheritance:

docs/available_parameters.rst

@@ -0,0 +1,105 @@
+Available parameters for Swarm data
+===================================
+
+You can check which parameters are available with:
+
+.. code-block:: python
+
+  from viresclient import SwarmRequest
+  req = SwarmRequest()
+  req.available_collections()
+  req.available_measurements("MAG")
+  req.available_models()
+  req.available_auxiliaries()
+
+----
+
+``collections``
+---------------
+
+(replace x with A, B, or C for Alpha, Bravo, or Charlie)::
+
+  SW_OPER_MAGx_LR_1B
+  SW_OPER_EFIx_PL_1B
+  SW_OPER_IBIxTMS_2F
+  SW_OPER_TECxTMS_2F
+  SW_OPER_FACxTMS_2F
+  SW_OPER_EEFxTMS_2F
+
+For Alpha-Charlie FAC: ``collection="SW_OPER_FAC_TMS_2F"``.
+
+The ``measurements``, ``models``, and ``auxiliaries`` chosen will match the cadence of the ``collection`` chosen.
+
+----
+
+``measurements``
+----------------
+
+Choose combinations of measurements from one of the following sets, corresponding to the collection chosen above.
+
+For MAG::
+
+  F,dF_AOCS,dF_other,F_error,B_VFM,B_NEC,dB_Sun,dB_AOCS,dB_other,B_error,q_NEC_CRF,Att_error,Flags_F,Flags_B,Flags_q,Flags_Platform,ASM_Freq_Dev
+
+For EFI::
+
+  v_SC,v_ion,v_ion_error,E,E_error,dt_LP,n,n_error,T_ion,T_ion_error,T_elec,T_elec_error,U_SC,U_SC_error,v_ion_H,v_ion_H_error,v_ion_V,v_ion_V_error,rms_fit_H,rms_fit_V,var_x_H,var_y_H,var_x_V,var_y_V,dv_mtq_H,dv_mtq_V,SAA,Flags_LP,Flags_LP_n,Flags_LP_T_elec,Flags_LP_U_SC,Flags_TII,Flags_Platform,Maneuver_Id
+
+For IBI::
+
+  Bubble_Index,Bubble_Probability,Flags_Bubble,Flags_F,Flags_B,Flags_q
+
+For TEC::
+
+  GPS_Position,LEO_Position,PRN,L1,L2,P1,P2,S1,S2,Absolute_STEC,Relative_STEC,Relative_STEC_RMS,DCB,DCB_Error
+
+For FAC::
+
+  IRC,IRC_Error,FAC,FAC_Error,Flags,Flags_F,Flags_B,Flags_q
+
+For EEF::
+
+  EEF,RelErr,flags
+
+----
+
+``models``
+----------
+
+Models are evaluated along the satellite track at the positions of the measurements.
+
+::
+
+  IGRF12, SIFM, CHAOS-6-Combined, CHAOS-6-Core, CHAOS-6-Static,
+  MCO_SHA_2C, MCO_SHA_2D, MCO_SHA_2F, MLI_SHA_2C, MLI_SHA_2D,
+  MMA_SHA_2C-Primary, MMA_SHA_2C-Secondary,
+  MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
+  MIO_SHA_2C-Primary, MIO_SHA_2C-Secondary,
+  MIO_SHA_2D-Primary, MIO_SHA_2D-Secondary
+
+(``residuals`` available when combined with MAG ``measurements`` ``F`` and/or ``B_NEC``)
+
+----
+
+``auxiliaries``
+---------------
+
+::
+
+  SyncStatus, Kp, Dst, IMF_BY_GSM, IMF_BZ_GSM, IMF_V, F10_INDEX,
+  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
+
+NB: the AMPS model is currently accessible as "auxiliaries" instead of a "model".
+
+----
+
+Standard positional variables always returned::
+
+  Timestamp,Latitude,Longitude,Radius,Spacecraft

docs/index.rst

@@ -6,6 +6,8 @@ Welcome to VirES-Python-Client's documentation!
   :caption: Overview
 
   readme
+  available_parameters
+  release_notes
 
 .. toctree::
   :maxdepth: 2

docs/readme.rst

@@ -1,11 +1,23 @@
 Introduction
-------------
+============
 
 This is the documentation for the ``viresclient`` Python package. This 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.
 
+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
+
+The cdflib_ library is used to read CDF files.
+
+.. _cdflib: https://github.com/MAVENSDC/cdflib
+
 Installation
 ------------
 
+Python ≥ 3.5 is required. (Partial?) support for 2.7 and 3.4 could be added in the future, but their usage is not recommended (https://python3statement.org/).
+
 It can currently be installed with::
 
   pip install viresclient
@@ -21,6 +33,7 @@ Dependencies::
 
 Example usage
 -------------
+
 Import the package and set up the connection to the server:
 
 .. code-block:: python
@@ -67,89 +80,23 @@ Specify the time range from which to retrieve data, make the request to the serv
                              filetype="cdf",
                              asynchronous=True)
 
-Transfer your data to a (``pandas``) dataframe or save it:
+Transfer your data to a pandas.DataFrame_, or a xarray.Dataset_, or just save it as is:
+
+.. _pandas.DataFrame: https://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe
+
+.. _xarray.Dataset: http://xarray.pydata.org/en/stable/data-structures.html#dataset
 
 .. code-block:: python
 
   df = data.as_dataframe()
+  ds = data.as_xarray()
   data.to_file('outfile.cdf', overwrite=False)
 
 The returned data has columns for:
  - ``Spacecraft, Timestamp, Latitude, Longitude, Radius``
- - those specified in ``measurements`` and ``auxiliaries`` above
+ - 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>``)
    - ``B_NEC_res_<model_id>``   -- vector field residual (``B_NEC - B_NEC_<model_id>``)
-
-Available parameters for Swarm data
------------------------------------
-
-``collections`` (replace x with A, B, or C for Alpha, Bravo, or Charlie)::
-
-  SW_OPER_MAGx_LR_1B
-  SW_OPER_EFIx_PL_1B
-  SW_OPER_IBIxTMS_2F
-  SW_OPER_TECxTMS_2F
-  SW_OPER_FACxTMS_2F
-  SW_OPER_EEFxTMS_2F
-
-For Alpha-Charlie FAC: ``collection="SW_OPER_FAC_TMS_2F"``.
-
-The ``measurements``, ``models``, and ``auxiliaries`` chosen will match the cadence of the ``collection`` chosen.
-
-``measurements``:
-
-Choose from one of the following sets, corresponding to the collection chosen above.
-
-For MAG::
-
-  F,dF_AOCS,dF_other,F_error,B_VFM,B_NEC,dB_Sun,dB_AOCS,dB_other,B_error,q_NEC_CRF,Att_error,Flags_F,Flags_B,Flags_q,Flags_Platform,ASM_Freq_Dev
-
-For EFI::
-
-  v_SC,v_ion,v_ion_error,E,E_error,dt_LP,n,n_error,T_ion,T_ion_error,T_elec,T_elec_error,U_SC,U_SC_error,v_ion_H,v_ion_H_error,v_ion_V,v_ion_V_error,rms_fit_H,rms_fit_V,var_x_H,var_y_H,var_x_V,var_y_V,dv_mtq_H,dv_mtq_V,SAA,Flags_LP,Flags_LP_n,Flags_LP_T_elec,Flags_LP_U_SC,Flags_TII,Flags_Platform,Maneuver_Id
-
-For IBI::
-
-  Bubble_Index,Bubble_Probability,Flags_Bubble,Flags_F,Flags_B,Flags_q
-
-For TEC::
-
-  GPS_Position,LEO_Position,PRN,L1,L2,P1,P2,S1,S2,Absolute_STEC,Relative_STEC,Relative_STEC_RMS,DCB,DCB_Error
-
-For FAC::
-
-  IRC,IRC_Error,FAC,FAC_Error,Flags,Flags_F,Flags_B,Flags_q
-
-For EEF::
-
-  EEF,RelErr,flags
-
-``models`` (``residuals`` available when combined with MAG ``measurements``)::
-
-  IGRF12, SIFM, CHAOS-6-Combined, CHAOS-6-Core, CHAOS-6-Static,
-  MCO_SHA_2C, MCO_SHA_2D, MCO_SHA_2F, MLI_SHA_2C, MLI_SHA_2D,
-  MMA_SHA_2C-Primary, MMA_SHA_2C-Secondary,
-  MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
-  MIO_SHA_2C-Primary, MIO_SHA_2C-Secondary,
-  MIO_SHA_2D-Primary, MIO_SHA_2D-Secondary
-
-``auxiliaries``::
-
-  SyncStatus, Kp, Dst, IMF_BY_GSM, IMF_BZ_GSM, IMF_V, F10_INDEX,
-  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
-
-Standard positional variables always returned::
-
-  Timestamp,Latitude,Longitude,Radius,Spacecraft
-
-NB: the AMPS model is currently accessible as "auxiliaries" instead of a "model".

docs/release_notes.rst

@@ -0,0 +1,14 @@
+Release notes
+=============
+
+Changes from v0.1.0 to v0.2.0
+-----------------------------
+
+ - Now use ``SwarmRequest`` instead of ``ClientRequest``.
+ - kwarg ``subsample`` changed to ``sampling_step``.
+ - Added references to .available_collections() and .available_models().
+ - User credentials are automatically stored in a configuration file ``~/.viresclient.ini``.
+ - Downloads are streamed to temporary files instead of being held in memory.
+ - Any size request is now supported. Large requests are automatically chunked up.
+ - Added download progress bar indicating size in MB.
+ - xarray added as a dependency and ``.as_xarray()`` method added.