Skip to content

Commit

Permalink
Docs: Improve description of available products
Browse files Browse the repository at this point in the history
  • Loading branch information
@smithara
smithara committed Sep 1, 2020
1 parent 8798e8a commit f8323c9
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 67 deletions.
157 changes: 94 additions & 63 deletions docs/available_parameters.rst
View file
Original file line number Diff line number Diff line change
@@ -1,79 +1,104 @@
Available parameters for Swarm data
===================================

| `See also: Jupyter notebook about data and model availability <https://swarm-vre.readthedocs.io/en/latest/Swarm_notebooks/02b__viresclient-Available-Data.html>`_
.. 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.
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()
request = SwarmRequest()
request.available_collections()
request.available_measurements("MAG")
request.available_measurements("SW_OPER_MAGA_LR_1B")
request.available_models()
request.available_auxiliaries()
The available measurements are segregated according to the "collection" (essentially Swarm products): each ``collection`` has a number of ``measurements`` associated with it, and the appropriate collection must be set in order to access the measurements. ``auxiliaries`` are available together with any set ``collection``. ``models`` provide magnetic model evaluation on demand, at the locations of the time series which is being accessed.
The available measurements are segregated according to the "collection" (essentially Swarm products): each ``collection`` has a number of ``measurements`` associated with it, and the appropriate collection must be set in order to access the measurements. ``auxiliaries`` are available together with any set ``collection``. ``models`` provide magnetic model evaluation on demand, at the locations of the time series which is being accessed (when accessing magnetic field data such as ``MAG`` or ``MAG_HR``). Standard positional variables always returned, such as Timestamp, Spacecraft, geocentric Latitude, Longitude, Radius.

----

See the `Swarm Data Handbook`_ for details about the products.
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 Product Demos`: https://swarm-vre.readthedocs.io/en/latest/Swarm_notebooks.html#swarm-product-demos

----

``collections``
---------------

(replace x with A, B, or C for Alpha, Bravo, or Charlie)::

SW_OPER_MAGx_LR_1B
SW_OPER_MAGx_HR_1B
SW_OPER_EFIx_LP_1B
SW_OPER_IBIxTMS_2F
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"``.
Collections are grouped according to a type containing similar measurements (i.e. the same product from different spacecraft). The collection type can be given to :py:meth:`viresclient.SwarmRequest.available_collections` to retrieve the full collection names. These cover the Swarm data products as below (replace x with A, B, or C for Alpha, Bravo, or Charlie):

======================== ================ ==============================================================
Collection full name Collection type Description
======================== ================ ==============================================================
SW_OPER_MAGx_LR_1B MAG Magnetic field (1Hz) from VFM and ASM
SW_OPER_MAGx_HR_1B MAG_HR Magnetic field (50Hz) from VFM
SW_OPER_EFIx_LP_1B EFI Electric field instrument (Langmuir probe measurements at 2Hz)
SW_OPER_IPDxIRR_2F IPD Ionospheric plasma characteristics (derived quantities at 1Hz)
SW_OPER_TECxTMS_2F TEC Total electron content
SW_OPER_FACxTMS_2F FAC Field-aligned currents (single satellite)
SW_OPER_FAC_TMS_2F FAC Field-aligned currents (dual-satellite A-C)
SW_OPER_EEFxTMS_2F EEF Equatorial electric field
SW_OPER_IBIxTMS_2F IBI Ionospheric bubble index
======================== ================ ==============================================================

The AEBS (auroral electrojets and boundaries) products are a bit more complicated:

============================================ ================================= ==============================================================
Collection full name Collection type Description
============================================ ================================= ==============================================================
SW_OPER_AEJxLPL_2F AEJ_LPL Auroral electrojets line profile - Line current method (LC)
SW_OPER_AEJxLPL_2F:Quality AEJ_LPL:Quality -> Quality indicators per orbital section from LC
SW_OPER_AEJxPBL_2F AEJ_PBL -> Peaks and boundaries from LC
SW_OPER_AEJxLPS_2F AEJ_LPS Auroral electrojets line profile - SECS method
SW_OPER_AEJxLPS_2F:Quality AEJ_LPS:Quality -> Quality indicators per orbital section from SECS
SW_OPER_AEJxPBS_2F AEJ_PBS -> Peaks and boundaries from SECS
SW_OPER_AEJxPBS_2F:GroundMagneticDisturbance AEJ_PBS:GroundMagneticDisturbance -> Location and strength of peak ground disturbance per pass
SW_OPER_AOBxFAC_2F AOB_FAC Auroral oval boundaries derived from FACs
============================================ ================================= ==============================================================

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 and ``MAG_HR``::

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::

U_orbit,Ne,Ne_error,Te,Te_error,Vs,Vs_error,Flags_LP,Flags_Ne,Flags_Te,Flags_Vs

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,Elevation_Angle,Absolute_VTEC,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,EEJ,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
----------------

Choose combinations of measurements from one of the following sets, corresponding to the collection chosen above. The collection full name or collection type can be given to :py:meth:`viresclient.SwarmRequest.available_measurements` to retrieve the list of available measurements for a given collection (e.g. ``request.available_measurements("SW_OPER_MAGA_LR_1B")``)

=============== ==============================================================================================================================================================================================================================================================================================
Collection type Available measurement names
=============== ==============================================================================================================================================================================================================================================================================================
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``
MAG_HR ``F,B_VFM,B_NEC,dB_Sun,dB_AOCS,dB_other,B_error,q_NEC_CRF,Att_error,Flags_B,Flags_q,Flags_Platform,ASM_Freq_Dev``
EFI ``U_orbit,Ne,Ne_error,Te,Te_error,Vs,Vs_error,Flags_LP,Flags_Ne,Flags_Te,Flags_Vs``
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``
TEC ``GPS_Position,LEO_Position,PRN,L1,L2,P1,P2,S1,S2,Elevation_Angle,Absolute_VTEC,Absolute_STEC,Relative_STEC,Relative_STEC_RMS,DCB,DCB_Error``
FAC ``IRC,IRC_Error,FAC,FAC_Error,Flags,Flags_F,Flags_B,Flags_q``
EEF ``EEF,EEJ,RelErr,Flags``
IBI ``Bubble_Index,Bubble_Probability,Flags_Bubble,Flags_F,Flags_B,Flags_q``
=============== ==============================================================================================================================================================================================================================================================================================

AEBS products:

================================= ================================================================================
Collection type Available measurement names
================================= ================================================================================
AEJ_LPL ``Latitude_QD,Longitude_QD,MLT_QD,J_NE,J_QD``
AEJ_LPL:Quality ``RMS_misfit,Confidence``
AEJ_PBL ``Latitude_QD,Longitude_QD,MLT_QD,J_QD,Flags,PointType``
AEJ_LPS ``Latitude_QD,Longitude_QD,MLT_QD,J_CF_NE,J_DF_NE,J_CF_SemiQD,J_DF_SemiQD,J_R``
AEJ_LPS:Quality ``RMS_misfit,Confidence``
AEJ_PBS ``Latitude_QD,Longitude_QD,MLT_QD,J_DF_SemiQD,Flags,PointType``
AEJ_PBS:GroundMagneticDisturbance ``B_NE``
AOB_FAC ``Latitude_QD,Longitude_QD,MLT_QD,Boundary_Flag,Quality,Pair_Indicator``
================================= ================================================================================

----

Expand All @@ -90,7 +115,7 @@ Models are evaluated along the satellite track at the positions of the time seri

This composed model can also be accessed by an alias: ``models=["CHAOS"]`` which represents the full CHAOS model

See https://magneticearth.org for an overview introduction to geomagnetic models.
See `Magnetic Earth <https://magneticearth.org/pages/models.html>`_ for an introduction to geomagnetic models.

::

Expand All @@ -103,18 +128,18 @@ Models are evaluated along the satellite track at the positions of the time seri
MIO_SHA_2C-Primary, MIO_SHA_2C-Secondary, # Ionosphere

# Dedicated inversion models:
MCO_SHA_2D,
MLI_SHA_2D,
MIO_SHA_2D-Primary, MIO_SHA_2D-Secondary
AMPS
MCO_SHA_2D, # Core
MLI_SHA_2D, MLI_SHA_2E # Lithosphere
MIO_SHA_2D-Primary, MIO_SHA_2D-Secondary # Ionosphere
AMPS # High-latitude ionosphere

# Fast-track models:
MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary,
MMA_SHA_2F-Primary, MMA_SHA_2F-Secondary, # Magnetosphere

# CHAOS models:
CHAOS-Core,
CHAOS-Static,
CHAOS-MMA-Primary, CHAOS-MMA-Secondary
CHAOS-Core, # Core
CHAOS-Static, # Lithosphere
CHAOS-MMA-Primary, CHAOS-MMA-Secondary # Magnetosphere

# Other lithospheric models:
MF7, LCS-1
Expand Down Expand Up @@ -163,14 +188,20 @@ NB: When using model names containing a hyphen (``-``) then extra single (``'``)

.. note::

- 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
- ``MLT`` is calculated from the QDLon and the subsolar position
- ``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.

----

Standard positional variables always returned::
.. note::

Check other packages such `hapiclient`_ and others from `PyHC`_ for data from other sources.

.. _`hapiclient`: https://github.com/hapi-server/client-python

.. _`PyHC`: http://heliopython.org/projects/

Timestamp,Latitude,Longitude,Radius,Spacecraft
----
4 changes: 2 additions & 2 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ 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>
--> [Launch VRE] JupyterLab <https://vre.vires.services/>
--> [VRE docs] Guides and Recipes <https://swarm-vre.readthedocs.io/en/latest/intro.html>

.. toctree::
:maxdepth: 2
Expand Down
4 changes: 2 additions & 2 deletions docs/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/. The access token should be automatically configured so you can jump in with the notebook demos.

Python ≥ 3.5 is required. Tested primarily on Linux, but macOS and Windows should also work (on v0.4+).
Python ≥ 3.6 is required. Testing is primarily on Linux, but macOS and Windows should also work.

It can currently be installed with::

Expand Down Expand Up @@ -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://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::
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::

git clone https://github.com/Swarm-DISC/Swarm_notebooks.git

Expand Down
8 changes: 8 additions & 0 deletions docs/release_notes.rst
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,14 @@
Release notes
=============

Changes from 0.6.2 to 0.6.3
---------------------------

- Added support for:

- AEBS products
- MLI_SHA_2E

Changes from 0.6.1 to 0.6.2
---------------------------

Expand Down

0 comments on commit f8323c9

Please sign in to comment.