Note

Notebook name: 02c__viresclient-API.ipynb (download .ipynb)
Alternative view with nbviewer - sometimes the formatting below can be messed up as it is processed by nbsphinx

viresclient API

Author: Luca Mariani

Abstract: Describe the main classes and methods defined in the viresclient package

Introduction

The viresclient Python package allows to connect to the VirES server to download Swarm data and data calculated using magnetic models.

Documentation:

Access token configuration

Before using the client, you need to set the access token. This can be done using the set_token() function:

set_token(url='https://vires.services/ows', token=None, set_default=False)

Parameters:

  • url (str, optional): server URL (default value: https://vires.services/ows).
  • token (str, optional): token string obtained from the VirES access token management page (https://vires.services/accounts/tokens/). If this parameter is not set, the user is prompted to enter its value interactively.
  • set_default (bool, optional): if True, the server identified by url is configured as default server (default False).

Since the url parameter is by default set to the correct value you don’t need to specify it. You can avoid also to specify the token parameter because this value will be asked interactively. Moreover, setting set_default=True you can configure this URL as default in the configuration file and avoid to specify it while sending requests to the server.

First, the function must be imported from the viresclient package:

[1]:
from viresclient import set_token

Now it can be executed:

[2]:
set_token(set_default=True)
Setting access token for https://vires.services/ows...
Generate a token at https://vires.services/accounts/tokens/
Enter token: ································
Token saved for https://vires.services/ows

TOP

Send requests to the server - SwarmRequest

The SwarmRequest object allows to create a request to the server and to download data according to the input parameters.

class SwarmRequest(url=None, username=None, password=None, token=None, config=None, logging_level='NO_LOGGING')

Parameters:

  • url (str, optional): if not provided, the request will be sent to the default URL set in the ~/.viresclient.ini configuration file.
  • username (str, optional): username. The usage of username and password is deprecated and will be removed in future releases.
  • password (str, optional): password. The usage of username and password is deprecated and will be removed in future releases.
  • token (str, optional): token string obtained from the VirES access token management page (https://vires.services/accounts/tokens/). If this parameter is not specified and it is not set in the configuration file, the user is prompted to enter its value interactively.
  • config (str or ClientConfig, optional): viresclient configuration. By default, it is read from ~/.viresclient.ini.
  • logging_level (str, optional): set the logging level. Allowed values are: DEBUG, INFO, WARNING, ERROR, NO_LOGGING (default).

Let’s import the class from the viresclient package:

[3]:
from viresclient import SwarmRequest

After configuring the access token using the set_token() function (see Access token configuration) , the SwarmRequest object can be created as follows:

[4]:
request = SwarmRequest()

The access token for the https://vires.services/ows default URL configured in the ~/.viresclient.ini file is automatically retrieved:

[https://vires.services/ows]
token = <token>

[default]
url = https://vires.services/ows

If the default server URL is not configured (i.e. the “default” section is not present), you must specify the server URL:

[5]:
request = SwarmRequest('https://vires.services/ows')

SwarmRequest object has the following methods:

  • SwarmRequest.available_collections()
  • SwarmRequest.available_measurements()
  • SwarmRequest.available_auxiliaries()
  • SwarmRequest.available_models()
  • SwarmRequest.get_model_info()
  • SwarmRequest.get_orbit_number()
  • SwarmRequest.get_times_for_orbits()
  • SwarmRequest.set_collection()
  • SwarmRequest.set_products()
  • SwarmRequest.set_range_filter()
  • SwarmRequest.clear_range_filter()
  • SwarmRequest.get_between()

TOP

Get the available collections

Swarm data are organized in collections. Each collection is related to a Swarm file type (e.g. collection SW_OPER_MAGA_LR_1B is related to file type MAGA_LR_1B). The list of the available collections are provided invoking the SwarmRequest.available_collections() method.

SwarmRequest.available_collections(details=True)

Parameters:

  • details (bool, optional): if True (default), the method prints the list of all the available collections and the related details. If False, it returns the available collections as a list.

Example: print the list of the available collections and their details:

[6]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Get the available collections
request.available_collections()
General References:
 Swarm Data Handbook, https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook
 The Swarm Satellite Constellation Application and Research Facility (SCARF) and Swarm data products, https://doi.org/10.5047/eps.2013.07.001
 Swarm Science Data Processing and Products (2013), https://link.springer.com/journal/40623/65/11/page/1
 Special issue “Swarm science results after 2 years in space (2016), https://www.springeropen.com/collections/swsr
 Earth's Magnetic Field: Understanding Geomagnetic Sources from the Earth's Interior and its Environment (2017), https://link.springer.com/journal/11214/206/1/page/1

MAG
   SW_OPER_MAGA_LR_1B
   SW_OPER_MAGB_LR_1B
   SW_OPER_MAGC_LR_1B
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-1b-product-definitions#MAGX_LR_1B_Product

EFI
   SW_OPER_EFIA_LP_1B
   SW_OPER_EFIB_LP_1B
   SW_OPER_EFIC_LP_1B
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-1b-product-definitions#EFIX_LP_1B_Product

IBI
   SW_OPER_IBIATMS_2F
   SW_OPER_IBIBTMS_2F
   SW_OPER_IBICTMS_2F
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-2-product-definitions#IBIxTMS_2F
 https://earth.esa.int/documents/10174/1514862/Swarm_L2_IBI_product_description

TEC
   SW_OPER_TECATMS_2F
   SW_OPER_TECBTMS_2F
   SW_OPER_TECCTMS_2F
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-2-product-definitions#TECxTMS_2F
 https://earth.esa.int/documents/10174/1514862/Swarm_Level-2_TEC_Product_Description

FAC
   SW_OPER_FACATMS_2F
   SW_OPER_FACBTMS_2F
   SW_OPER_FACCTMS_2F
   SW_OPER_FAC_TMS_2F
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-2-product-definitions#FAC_TMS_2F
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-2-product-definitions#FACxTMS_2F
 https://earth.esa.int/documents/10174/1514862/Swarm_L2_FAC_single_product_description
 https://earth.esa.int/documents/10174/1514862/Swarm-L2-FAC-Dual-Product-Description

EEF
   SW_OPER_EEFATMS_2F
   SW_OPER_EEFBTMS_2F
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-2-product-definitions#EEFxTMS_2F
 https://earth.esa.int/documents/10174/1514862/Swarm-Level-2-EEF-Product-Description

IPD
   SW_OPER_IPDAIRR_2F
   SW_OPER_IPDBIRR_2F
   SW_OPER_IPDCIRR_2F
 https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/data-handbook/level-2-product-definitions#IPDxIPR_2F

Example: get the list of available collections without the details:

[7]:
request.available_collections(details=False)
[7]:
{'MAG': ['SW_OPER_MAGA_LR_1B', 'SW_OPER_MAGB_LR_1B', 'SW_OPER_MAGC_LR_1B'],
 'EFI': ['SW_OPER_EFIA_LP_1B', 'SW_OPER_EFIB_LP_1B', 'SW_OPER_EFIC_LP_1B'],
 'IBI': ['SW_OPER_IBIATMS_2F', 'SW_OPER_IBIBTMS_2F', 'SW_OPER_IBICTMS_2F'],
 'TEC': ['SW_OPER_TECATMS_2F', 'SW_OPER_TECBTMS_2F', 'SW_OPER_TECCTMS_2F'],
 'FAC': ['SW_OPER_FACATMS_2F',
  'SW_OPER_FACBTMS_2F',
  'SW_OPER_FACCTMS_2F',
  'SW_OPER_FAC_TMS_2F'],
 'EEF': ['SW_OPER_EEFATMS_2F', 'SW_OPER_EEFBTMS_2F'],
 'IPD': ['SW_OPER_IPDAIRR_2F', 'SW_OPER_IPDBIRR_2F', 'SW_OPER_IPDCIRR_2F']}

TOP

Get the available measurements

It is possible to get the available measurements using the SwarmRequest.available_measurements() method:

SwarmRequest.available_measurements(collection=None)

Parameters:

  • collection (str, optional). If indicated, returns the available measurements for this collection as a list. It can be set to: MAG, EFI, IBI, TEC, FAC, EEF, IPD or one of the collections returned by the available_collections method. If not indicated, it returns the available measurements for all the collections as a dict.

Example: get the list of measurements for the MAG collections:

[8]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Get the available measurements
request.available_measurements('MAG')
[8]:
['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']

Setting collection=SW_OPER_MAGA_LR_1B we obtain the same result:

[9]:
request.available_measurements('SW_OPER_MAGA_LR_1B')
[9]:
['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']

Example: get all the available measurements:

[10]:
request.available_measurements()
[10]:
{'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'],
 'EFI': ['U_orbit',
  'Ne',
  'Ne_error',
  'Te',
  'Te_error',
  'Vs',
  'Vs_error',
  'Flags_LP',
  'Flags_Ne',
  'Flags_Te',
  'Flags_Vs'],
 'IBI': ['Bubble_Index',
  'Bubble_Probability',
  'Flags_Bubble',
  'Flags_F',
  'Flags_B',
  'Flags_q'],
 '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', 'RelErr', 'flags'],
 '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']}

TOP

Get the available auxiliaries

It is possible to get the available auxiliaries using the SwarmRequest.available_auxiliaries() method:

SwarmRequest.available_auxiliaries()

This method does not accept input parameters and provides the available auxiliaries as a list.

Example: get the list of the available auxiliaries:

[11]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Get the list of available auxiliaries
request.available_auxiliaries()
[11]:
['Timestamp',
 'Latitude',
 'Longitude',
 'Radius',
 'Spacecraft',
 'OrbitDirection',
 'QDOrbitDirection',
 'SyncStatus',
 'Kp10',
 'Kp',
 'Dst',
 'F107',
 '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']

TOP

Get the available magnetic models

The available magnetic models can be obtained using the SwarmRequest.available_models() method:

SwarmRequest.available_models(param=None, details=True, nice_output=True)

Parameters:

  • param (str, optional): it can be set to one of F, C, D, MCO, MLI, MMA, MIO to filter all the available magnetic models.
  • details (bool, optional): if it is set to True (default), it gets the models and their details. If False, it returns only the models as a list.
  • nice_output (bool, optional): if it is set to True (default), it prints the models and their details. If False, it returns the models as a dictionary (if details=True) or a s a list (if details=False).

Example: get the list of all the available models and their details:

[12]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Get available models
request.available_models()
CHAOS-6-Core = 'CHAOS-6-Core'(max_degree=20,min_degree=1)
  START: 1997-02-07T05:31:12.000003Z
  END:   2020-04-21T02:49:20.639999Z
DESCRIPTION:
CHAOS Core field
 deprecated model identifier, use CHAOS-Core instead
SOURCES:
  SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701

CHAOS-6-MMA-Primary = 'CHAOS-6-MMA-Primary'(max_degree=2,min_degree=1)
  START: 2012-01-01T00:00:00Z
  END:   2020-02-27T23:30:00Z
DESCRIPTION:
CHAOS Primary (external) magnetospheric field
 deprecated model identifier, use CHAOS-MMA-Primary instead
SOURCES:
  SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608
  SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608
  SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608
  SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608
  SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608
  SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608
  SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701
  SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701

CHAOS-6-MMA-Secondary = 'CHAOS-6-MMA-Secondary'(max_degree=2,min_degree=1)
  START: 2012-01-01T00:00:00Z
  END:   2020-02-27T23:30:00Z
DESCRIPTION:
CHAOS-Secondary (internal) magnetospheric field
 deprecated model identifier, use CHAOS-MMA-Secondary instead
SOURCES:
  SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608
  SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608
  SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608
  SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608
  SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608
  SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608
  SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701
  SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701

CHAOS-6-Static = 'CHAOS-6-Static'(max_degree=185,min_degree=21)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
CHAOS crust field
 deprecated model identifier, use CHAOS-Static instead
SOURCES:
  CHAOS-7_static.shc

CHAOS-Core = 'CHAOS-Core'(max_degree=20,min_degree=1)
  START: 1997-02-07T05:31:12.000003Z
  END:   2020-04-21T02:49:20.639999Z
DESCRIPTION:
CHAOS-7 Core field (SH degrees 1-20)
 http://www.spacecenter.dk/files/magnetic-models/CHAOS-7/
SOURCES:
  SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701

CHAOS-MMA-Primary = 'CHAOS-MMA-Primary'(max_degree=2,min_degree=1)
  START: 2012-01-01T00:00:00Z
  END:   2020-02-27T23:30:00Z
DESCRIPTION:
CHAOS-7 Primary (external) magnetospheric field
 hhttp://www.spacecenter.dk/files/magnetic-models/CHAOS-7/
SOURCES:
  SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608
  SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608
  SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608
  SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608
  SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608
  SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608
  SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701
  SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701

CHAOS-MMA-Secondary = 'CHAOS-MMA-Secondary'(max_degree=2,min_degree=1)
  START: 2012-01-01T00:00:00Z
  END:   2020-02-27T23:30:00Z
DESCRIPTION:
CHAOS-7 Secondary (internal) magnetospheric field
 http://www.spacecenter.dk/files/magnetic-models/CHAOS-7/
SOURCES:
  SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608
  SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608
  SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608
  SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608
  SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608
  SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608
  SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701
  SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701

CHAOS-Static = 'CHAOS-Static'(max_degree=185,min_degree=21)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
CHAOS-7 crust field (SH degrees 21-185)
 http://www.spacecenter.dk/files/magnetic-models/CHAOS-7/
SOURCES:
  CHAOS-7_static.shc

IGRF = IGRF(max_degree=13,min_degree=1)
  START: 1900-01-01T00:00:00Z
  END:   2025-01-01T00:00:00Z
DESCRIPTION:
 International Geomagnetic Reference Field: the 13th generation, (waiting for publication)
 https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html
SOURCES:
  SW_OPER_AUX_IGR_2__19000101T000000_20241231T235959_0103

IGRF12 = IGRF12(max_degree=13,min_degree=1)
  START: 1900-01-01T00:00:00Z
  END:   2020-01-01T00:00:00Z
DESCRIPTION:
 International Geomagnetic Reference Field: the 12th generation, https://doi.org/10.1186/s40623-015-0228-9
 https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html  deprecated model identifier, use IGRF instead
SOURCES:
  SW_OPER_AUX_IGR_2__19000101T000000_20191231T235959_0102

LCS-1 = 'LCS-1'(max_degree=185,min_degree=1)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
The LCS-1 high-resolution lithospheric field model, derived from CHAMP and Swarm satellite observations
 http://www.spacecenter.dk/files/magnetic-models/LCS-1/
SOURCES:
  LCS-1.shc

MCO_SHA_2C = MCO_SHA_2C(max_degree=18,min_degree=1)
  START: 2013-11-24T18:28:47.999997Z
  END:   2019-01-01T00:00:00Z
DESCRIPTION:
[Comprehensive Inversion]: Core field of CIY4
 A comprehensive model of Earth’s magnetic field determined from 4 years of Swarm satellite observations, https://doi.org/10.1186/s40623-018-0896-3
Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MCO/SW_OPER_MCO_VAL_2C_20131201T000000_20180101T000000_0401.ZIP
SOURCES:
  SW_OPER_MCO_SHA_2C_20131125T000000_20190101T000000_0501

MCO_SHA_2D = MCO_SHA_2D(max_degree=20,min_degree=1)
  START: 2013-11-25T12:00:00.000003Z
  END:   2018-01-01T00:00:00Z
DESCRIPTION:
[Dedicated Chain]: Core field
An algorithm for deriving core magnetic field models from the Swarm data set, https://doi.org/10.5047/eps.2013.07.005
Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MCO/SW_OPER_MCO_VAL_2D_20131126T000000_20180101T000000_0401.ZIP
SOURCES:
  SW_OPER_MCO_SHA_2D_20131126T000000_20180101T000000_0401

MF7 = MF7(max_degree=133,min_degree=16)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
MF7 crustal field model, derived from CHAMP satellite observations
 http://geomag.org/models/MF7.html
SOURCES:
  MF7.shc

MIO_SHA_2C-Primary = 'MIO_SHA_2C-Primary'(max_degree=60,min_degree=1)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
[Comprehensive Inversion]: Primary (external) ionospheric field of CIY4
Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MIO/SW_OPER_MIO_VAL_2C_00000000T000000_99999999T999999_0401.ZIP
SOURCES:
  SW_OPER_MIO_SHA_2C_00000000T000000_99999999T999999_0501

MIO_SHA_2C-Secondary = 'MIO_SHA_2C-Secondary'(max_degree=60,min_degree=1)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
[Comprehensive Inversion]: Secondary (external/induced) ionospheric field of CIY4
SOURCES:
  SW_OPER_MIO_SHA_2C_00000000T000000_99999999T999999_0501

MIO_SHA_2D-Primary = 'MIO_SHA_2D-Primary'(max_degree=60,min_degree=1)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
[Dedicated Chain]: Primary (external) ionospheric field, DIFI
 Swarm SCARF dedicated ionospheric field inversion chain, https://doi.org/10.5047/eps.2013.08.006
 First results from the Swarm Dedicated Ionospheric Field Inversion chain, https://doi.org/10.1186/s40623-016-0481-6
 http://geomag.colorado.edu/difi-3
Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MIO/SW_OPER_MIO_VAL_2D_20131201T000000_20171231T235959_0402.ZIP
SOURCES:
  SW_OPER_MIO_SHA_2D_20131201T000000_20171231T235959_0402

MIO_SHA_2D-Secondary = 'MIO_SHA_2D-Secondary'(max_degree=60,min_degree=1)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
[Dedicated Chain]: Secondary (external/induced) ionospheric field, DIFI
SOURCES:
  SW_OPER_MIO_SHA_2D_20131201T000000_20171231T235959_0402

MLI_SHA_2C = MLI_SHA_2C(max_degree=120,min_degree=16)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
[Comprehensive Inversion]: Lithospheric field of CIY4
Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MLI/SW_OPER_MLI_VAL_2C_00000000T000000_99999999T999999_0401.ZIP
SOURCES:
  SW_OPER_MLI_SHA_2C_00000000T000000_99999999T999999_0501

MLI_SHA_2D = MLI_SHA_2D(max_degree=133,min_degree=16)
  START: 0001-01-01T00:00:00Z
  END:   4000-01-01T00:00:00Z
DESCRIPTION:
[Dedicated Chain]: Lithospheric field
 Swarm SCARF Dedicated Lithospheric Field Inversion chain, https://doi.org/10.5047/eps.2013.07.008
 Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MLI/SW_OPER_MLI_VAL_2D_00000000T000000_99999999T999999_0401.ZIP
SOURCES:
  SW_OPER_MLI_SHA_2D_00000000T000000_99999999T999999_0501

MMA_SHA_2C-Primary = 'MMA_SHA_2C-Primary'(max_degree=2,min_degree=1)
  START: 2013-11-25T03:00:00Z
  END:   2018-12-31T21:00:00Z
DESCRIPTION:
[Comprehensive Inversion]: Primary (external) magnetospheric field of CIY4
Validation: ftp://swarm-diss.eo.esa.int/Level2longterm/MMA/SW_OPER_MMA_VAL_2C_20131201T000000_20180101T000000_0401.ZIP
SOURCES:
  SW_OPER_MMA_SHA_2C_20131125T000000_20181231T235959_0501

MMA_SHA_2C-Secondary = 'MMA_SHA_2C-Secondary'(max_degree=3,min_degree=1)
  START: 2013-11-25T03:00:00Z
  END:   2018-12-31T21:00:00Z
DESCRIPTION:
[Comprehensive Inversion]: Secondary (internal/induced) magnetospheric field of CIY4
SOURCES:
  SW_OPER_MMA_SHA_2C_20131125T000000_20181231T235959_0501

MMA_SHA_2F-Primary = 'MMA_SHA_2F-Primary'(max_degree=1,min_degree=1)
  START: 2013-11-25T11:15:00Z
  END:   2020-02-24T20:15:00Z
DESCRIPTION:
[Fast-Track Product]: Primary (external) magnetospheric field
 Rapid modelling of the large-scale magnetospheric field from Swarm satellite data, https://doi.org/10.5047/eps.2013.09.003
SOURCES:
  SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108
  SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108
  SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108
  SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108
  SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108
  SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108
  SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108
  SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108

MMA_SHA_2F-Secondary = 'MMA_SHA_2F-Secondary'(max_degree=1,min_degree=1)
  START: 2013-11-25T11:15:00Z
  END:   2020-02-24T20:15:00Z
DESCRIPTION:
[Fast-Track Product]: Secondary (internal/induced) magnetospheric field
SOURCES:
  SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108
  SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108
  SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108
  SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108
  SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108
  SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108
  SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108
  SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108

Example: print the list of the available F (Fast-Track) models and their details:

[13]:
request.available_models('F')
MMA_SHA_2F-Primary = 'MMA_SHA_2F-Primary'(max_degree=1,min_degree=1)
  START: 2013-11-25T11:15:00Z
  END:   2020-02-24T20:15:00Z
DESCRIPTION:
[Fast-Track Product]: Primary (external) magnetospheric field
 Rapid modelling of the large-scale magnetospheric field from Swarm satellite data, https://doi.org/10.5047/eps.2013.09.003
SOURCES:
  SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108
  SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108
  SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108
  SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108
  SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108
  SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108
  SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108
  SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108

MMA_SHA_2F-Secondary = 'MMA_SHA_2F-Secondary'(max_degree=1,min_degree=1)
  START: 2013-11-25T11:15:00Z
  END:   2020-02-24T20:15:00Z
DESCRIPTION:
[Fast-Track Product]: Secondary (internal/induced) magnetospheric field
SOURCES:
  SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108
  SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108
  SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108
  SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108
  SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108
  SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108
  SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108
  SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108

Example: get the If the list of models of type F as a dictionary:

[14]:
request.available_models(param='F', nice_output=False)
[14]:
{'MMA_SHA_2F-Primary': {'description': ('[Fast-Track Product]: Primary (external) magnetospheric field',
   ' Rapid modelling of the large-scale magnetospheric field from Swarm satellite data, https://doi.org/10.5047/eps.2013.09.003 '),
  'details': {'sources': ['SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108'],
   'expression': "'MMA_SHA_2F-Primary'(max_degree=1,min_degree=1)",
   'validity': {'start': '2013-11-25T11:15:00Z',
    'end': '2020-02-24T20:15:00Z'}}},
 'MMA_SHA_2F-Secondary': {'description': ('[Fast-Track Product]: Secondary (internal/induced) magnetospheric field',),
  'details': {'sources': ['SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108',
    'SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108'],
   'expression': "'MMA_SHA_2F-Secondary'(max_degree=1,min_degree=1)",
   'validity': {'start': '2013-11-25T11:15:00Z',
    'end': '2020-02-24T20:15:00Z'}}}}

Example: get the list of all the available models without their details:

[15]:
request.available_models(details=False)
[15]:
['IGRF',
 'IGRF12',
 'LCS-1',
 'MF7',
 'CHAOS-Core',
 'CHAOS-Static',
 'CHAOS-MMA-Primary',
 'CHAOS-MMA-Secondary',
 'CHAOS-6-Core',
 'CHAOS-6-Static',
 'CHAOS-6-MMA-Primary',
 'CHAOS-6-MMA-Secondary',
 'MCO_SHA_2C',
 'MCO_SHA_2D',
 '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']

TOP

Get information about one or more models.

It is possible to get information about one or more specific models using the SwarmRequest.get_model_info() method:

SwarmRequest.get_model_info(models=None, custom_model=None, original_response=False)

Parameters:

  • models (list[str], optional): models as a list of strings. If the list is not provided, returns information about all the available magnetic models.
  • custom_model (str, optional): name of the file containing the spherical harmonics coefficients (custom model).
  • original_response (bool, optional): if set to False (default), returns the result as a dictionary. If set to True, returns the result as a list of dictionaries.

Example: get info about all the available magnetic models:

[16]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Get model info
request.get_model_info()
[16]:
{'MLI_SHA_2D': {'sources': ['SW_OPER_MLI_SHA_2D_00000000T000000_99999999T999999_0501'],
  'expression': 'MLI_SHA_2D(max_degree=133,min_degree=16)',
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'MLI_SHA_2C': {'sources': ['SW_OPER_MLI_SHA_2C_00000000T000000_99999999T999999_0501'],
  'expression': 'MLI_SHA_2C(max_degree=120,min_degree=16)',
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'CHAOS-Core': {'sources': ['SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701'],
  'expression': "'CHAOS-Core'(max_degree=20,min_degree=1)",
  'validity': {'start': '1997-02-07T05:31:12.000003Z',
   'end': '2020-04-21T02:49:20.639999Z'}},
 'MIO_SHA_2C-Primary': {'sources': ['SW_OPER_MIO_SHA_2C_00000000T000000_99999999T999999_0501'],
  'expression': "'MIO_SHA_2C-Primary'(max_degree=60,min_degree=1)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'LCS-1': {'sources': ['LCS-1.shc'],
  'expression': "'LCS-1'(max_degree=185,min_degree=1)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'CHAOS-MMA-Primary': {'sources': ['SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608',
   'SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608',
   'SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608',
   'SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608',
   'SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608',
   'SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608',
   'SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701',
   'SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701'],
  'expression': "'CHAOS-MMA-Primary'(max_degree=2,min_degree=1)",
  'validity': {'start': '2012-01-01T00:00:00Z',
   'end': '2020-02-27T23:30:00Z'}},
 'MIO_SHA_2C-Secondary': {'sources': ['SW_OPER_MIO_SHA_2C_00000000T000000_99999999T999999_0501'],
  'expression': "'MIO_SHA_2C-Secondary'(max_degree=60,min_degree=1)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'CHAOS-MMA-Secondary': {'sources': ['SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608',
   'SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608',
   'SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608',
   'SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608',
   'SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608',
   'SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608',
   'SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701',
   'SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701'],
  'expression': "'CHAOS-MMA-Secondary'(max_degree=2,min_degree=1)",
  'validity': {'start': '2012-01-01T00:00:00Z',
   'end': '2020-02-27T23:30:00Z'}},
 'MIO_SHA_2D-Secondary': {'sources': ['SW_OPER_MIO_SHA_2D_20131201T000000_20171231T235959_0402'],
  'expression': "'MIO_SHA_2D-Secondary'(max_degree=60,min_degree=1)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'MMA_SHA_2F-Primary': {'sources': ['SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108'],
  'expression': "'MMA_SHA_2F-Primary'(max_degree=1,min_degree=1)",
  'validity': {'start': '2013-11-25T11:15:00Z',
   'end': '2020-02-24T20:15:00Z'}},
 'IGRF13': {'sources': ['SW_OPER_AUX_IGR_2__19000101T000000_20241231T235959_0103'],
  'expression': 'IGRF13(max_degree=13,min_degree=1)',
  'validity': {'start': '1900-01-01T00:00:00Z',
   'end': '2025-01-01T00:00:00Z'}},
 'IGRF12': {'sources': ['SW_OPER_AUX_IGR_2__19000101T000000_20191231T235959_0102'],
  'expression': 'IGRF12(max_degree=13,min_degree=1)',
  'validity': {'start': '1900-01-01T00:00:00Z',
   'end': '2020-01-01T00:00:00Z'}},
 'MCO_SHA_2C': {'sources': ['SW_OPER_MCO_SHA_2C_20131125T000000_20190101T000000_0501'],
  'expression': 'MCO_SHA_2C(max_degree=18,min_degree=1)',
  'validity': {'start': '2013-11-24T18:28:47.999997Z',
   'end': '2019-01-01T00:00:00Z'}},
 'MF7': {'sources': ['MF7.shc'],
  'expression': 'MF7(max_degree=133,min_degree=16)',
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'MIO_SHA_2D-Primary': {'sources': ['SW_OPER_MIO_SHA_2D_20131201T000000_20171231T235959_0402'],
  'expression': "'MIO_SHA_2D-Primary'(max_degree=60,min_degree=1)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'MCO_SHA_2D': {'sources': ['SW_OPER_MCO_SHA_2D_20131126T000000_20180101T000000_0401'],
  'expression': 'MCO_SHA_2D(max_degree=20,min_degree=1)',
  'validity': {'start': '2013-11-25T12:00:00.000003Z',
   'end': '2018-01-01T00:00:00Z'}},
 'MMA_SHA_2F-Secondary': {'sources': ['SW_OPER_MMA_SHA_2F_20131125T103000_20140101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20140101T000000_20150101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20150101T000000_20160101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20160101T000000_20170101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20170101T000000_20180101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20180101T000000_20190101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20190101T000000_20200101T000000_0108',
   'SW_OPER_MMA_SHA_2F_20200101T000000_20200224T210000_0108'],
  'expression': "'MMA_SHA_2F-Secondary'(max_degree=1,min_degree=1)",
  'validity': {'start': '2013-11-25T11:15:00Z',
   'end': '2020-02-24T20:15:00Z'}},
 'CHAOS-Static': {'sources': ['CHAOS-7_static.shc'],
  'expression': "'CHAOS-Static'(max_degree=185,min_degree=21)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}},
 'MMA_SHA_2C-Secondary': {'sources': ['SW_OPER_MMA_SHA_2C_20131125T000000_20181231T235959_0501'],
  'expression': "'MMA_SHA_2C-Secondary'(max_degree=3,min_degree=1)",
  'validity': {'start': '2013-11-25T03:00:00Z',
   'end': '2018-12-31T21:00:00Z'}},
 'MMA_SHA_2C-Primary': {'sources': ['SW_OPER_MMA_SHA_2C_20131125T000000_20181231T235959_0501'],
  'expression': "'MMA_SHA_2C-Primary'(max_degree=2,min_degree=1)",
  'validity': {'start': '2013-11-25T03:00:00Z',
   'end': '2018-12-31T21:00:00Z'}},
 'CHAOS-6-MMA-Secondary': {'sources': ['SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608',
   'SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608',
   'SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608',
   'SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608',
   'SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608',
   'SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608',
   'SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701',
   'SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701'],
  'expression': "'CHAOS-6-MMA-Secondary'(max_degree=2,min_degree=1)",
  'validity': {'start': '2012-01-01T00:00:00Z',
   'end': '2020-02-27T23:30:00Z'}},
 'CHAOS-6-Core': {'sources': ['SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701'],
  'expression': "'CHAOS-6-Core'(max_degree=20,min_degree=1)",
  'validity': {'start': '1997-02-07T05:31:12.000003Z',
   'end': '2020-04-21T02:49:20.639999Z'}},
 'MCO_SHA_2X': {'sources': ['SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701'],
  'expression': 'MCO_SHA_2X(max_degree=20,min_degree=1)',
  'validity': {'start': '1997-02-07T05:31:12.000003Z',
   'end': '2020-04-21T02:49:20.639999Z'}},
 'IGRF': {'sources': ['SW_OPER_AUX_IGR_2__19000101T000000_20241231T235959_0103'],
  'expression': 'IGRF(max_degree=13,min_degree=1)',
  'validity': {'start': '1900-01-01T00:00:00Z',
   'end': '2025-01-01T00:00:00Z'}},
 'CHAOS-6-MMA-Primary': {'sources': ['SW_OPER_MMA_CHAOS__20120101T000000_20121231T233000_0608',
   'SW_OPER_MMA_CHAOS__20130101T000000_20131231T233000_0608',
   'SW_OPER_MMA_CHAOS__20140101T000000_20141231T233000_0608',
   'SW_OPER_MMA_CHAOS__20150101T000000_20151231T233000_0608',
   'SW_OPER_MMA_CHAOS__20160101T000000_20161231T233000_0608',
   'SW_OPER_MMA_CHAOS__20170101T000000_20171231T233000_0608',
   'SW_OPER_MMA_CHAOS__20180101T000000_20181231T233000_0701',
   'SW_OPER_MMA_CHAOS__20190101T000000_20200227T233000_0701'],
  'expression': "'CHAOS-6-MMA-Primary'(max_degree=2,min_degree=1)",
  'validity': {'start': '2012-01-01T00:00:00Z',
   'end': '2020-02-27T23:30:00Z'}},
 'CHAOS-6-Static': {'sources': ['CHAOS-7_static.shc'],
  'expression': "'CHAOS-6-Static'(max_degree=185,min_degree=21)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}}}

Example: get info about CHAOS-Core and CHAOS-Static:

[17]:
request.get_model_info(models=['CHAOS-Core', 'CHAOS-Static'])
[17]:
{'CHAOS-Core': {'sources': ['SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701'],
  'expression': "'CHAOS-Core'(max_degree=20,min_degree=1)",
  'validity': {'start': '1997-02-07T05:31:12.000003Z',
   'end': '2020-04-21T02:49:20.639999Z'}},
 'CHAOS-Static': {'sources': ['CHAOS-7_static.shc'],
  'expression': "'CHAOS-Static'(max_degree=185,min_degree=21)",
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}}}

Example: set original_response=True to get the result as a list of dictionaries:

[18]:
request.get_model_info(models=['CHAOS-Core', 'CHAOS-Static'], original_response=True)
[18]:
[{'sources': ['SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701'],
  'expression': "'CHAOS-Core'(max_degree=20,min_degree=1)",
  'name': 'CHAOS-Core',
  'validity': {'start': '1997-02-07T05:31:12.000003Z',
   'end': '2020-04-21T02:49:20.639999Z'}},
 {'sources': ['CHAOS-7_static.shc'],
  'expression': "'CHAOS-Static'(max_degree=185,min_degree=21)",
  'name': 'CHAOS-Static',
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}}]

Example: get info on a custom model by providing the name of the file containing its coefficients:

[19]:
# Download shc file with WGET (command line tool)
!wget "http://www.spacecenter.dk/files/magnetic-models/LCS-1/LCS-1.shc"

# Upload a .shc file and update the file name
request.get_model_info(custom_model='LCS-1.shc')
--2020-02-28 16:49:47--  http://www.spacecenter.dk/files/magnetic-models/LCS-1/LCS-1.shc
Resolving www.spacecenter.dk (www.spacecenter.dk)... 130.226.216.199
Connecting to www.spacecenter.dk (www.spacecenter.dk)|130.226.216.199|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 657666 (642K) [text/plain]
Saving to: ‘LCS-1.shc.1’

LCS-1.shc.1         100%[===================>] 642.25K  --.-KB/s    in 0.1s

2020-02-28 16:49:47 (5.22 MB/s) - ‘LCS-1.shc.1’ saved [657666/657666]

[19]:
{'Custom_Model': {'sources': [],
  'expression': 'Custom_Model(max_degree=185,min_degree=1)',
  'validity': {'start': '0001-01-01T00:00:00Z',
   'end': '4000-01-01T00:00:00Z'}}}
[20]:
# Delete downloaded file(s)
!rm LCS-1.shc*

TOP

Get the orbit number

The SwarmRequest.get_orbit_number() allows to get the orbit number of a given spacecraft providing date and time:

SwarmRequest.get_orbit_number(spacecraft, input_time)

Parameters:

  • spacecraft (str): spacecraft identifier: A, B or C.
  • input_time (datetime.datetime or str): date and time.

Example: get orbit numbers corresponding to date 2020-01-01 00:00:00 for the three spacecrafts:

[21]:
# Create the request object
request = SwarmRequest()

# Get results
for sc in ('A', 'B', 'C'):
    orbit = request.get_orbit_number(sc, '2020-01-01T00:00:00')
    print(f's/c {sc}: {orbit}')
s/c A: 34324
s/c B: 33892
s/c C: 34320

TOP

Get times for orbits

Get the time interval corresponding to a pair of orbit numbers using the SwarmRequest.get_times_for_orbits() method:

SwarmRequest.get_times_for_orbits(spacecraft, start_orbit, end_orbit)

Parameters:

  • spacecraft (str): spacecraft identifier: A, B or C.
  • start_orbit (int): start orbit number
  • end_orbit (int): end orbit number

Example: get time intervals corresponding to start_orbit 1000 and end_orbit 2000 for the three spacecrafts:

[22]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Set start/end orbits
start_orbit = 1000
end_orbit = 2000

# Create the request object
request = SwarmRequest()

# Get results
for sc in ('A', 'B', 'C'):
    start_date, end_date = request.get_times_for_orbits(sc, start_orbit, end_orbit)
    print(f's/c {sc}: {start_date} - {end_date}')
s/c A: 2014-01-27 04:05:04.228591 - 2014-04-02 13:51:01.876037
s/c B: 2014-01-27 04:04:17.158156 - 2014-04-03 00:46:19.552254
s/c C: 2014-01-27 04:08:31.126684 - 2014-04-02 19:45:08.511104

TOP

Set collections

Before sending the request to the server, you need to set the Swarm collection including the measurement(s) of interest. This can be done using the SwarmRequest.set_collection() method:

SwarmRequest.set_collection(*args)

Parameters:

Example: to get data from SW_OPER_MAGA_LR_1B and SW_OPER_EFIA_LP_1B collections:

[23]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Set collections
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
[23]:
<viresclient._client_swarm.SwarmRequest at 0x7f6552398990>

TOP

Set products

After setting the collection, you must set the combination of measurements and/or auxiliaries and/or magnetic model(s) data to retrieve. This can be done using the SwarmRequest.set_products() method:

SwarmRequest.set_products(measurements=None, models=None, custom_model=None, auxiliaries=None, residuals=False, sampling_step=None)

Parameters:

  • measurements (list[str], optional): list of measurements to be downloaded. To get the list of the available measurements see Available measurements (e.g.: ['F', 'B_NEC', 'Ne'].).
  • models (list[str], optional): list of magnetic models. To get the list of the available models see Available models (e.g.: ['CHAOS-Core', 'CHAOS-Static']). In addition to the list, this parameters accepts also expression for the definition of magnetic models (e.g.: 'CHAOS = "CHAOS-Core" + "CHAOS-Static"').
  • custom_model (str, optional): path to the the file containing the spherical harmonics coefficients of the custom model.
  • auxiliaries (list[str], optional): list of auxiliaries to be downloaded. To get the list of the available auxiliaries see Available auxiliaries. Please note that the following parameters are always retrieved (i.e. they don’t need to be specified): Spacecraft, Timestamp, Latitude, Longitude, Radius.
  • residuals (bool, optional): if it is set to True, returns the residuals between measurements (specified with measurements) and models (specified with models). If it is set to False (default), returns measurements and models.
  • sampling_step (str, optional): set the sampling step as an ISO 8601 time interval. If not provided, data is returned with the original sampling.

Example: get measurements: F and B_NEC from SW_OPER_MAGA_LR_1B and Ne from SW_OPER_EFIA_LP_1B, model CHAOS = "CHAOS-Core" + "Chaos-Static" and auxiliary OrbitNumber with a sampling step of 10 seconds:

[24]:
# Import SwarmRequest object (this step can be skipped if SwarmRequest has been already imported)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Set collections
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')

# Set products
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
[24]:
<viresclient._client_swarm.SwarmRequest at 0x7f6552391f90>

TOP

Set/clear filters

Filter(s) can be applied to the requested measurements using the SwarmRequest.set_range_filter() method:

SwarmRequest.set_range_filter(parameter=None, minimum=None, maximum=None)

This method allows to set filter(s) in the form: \(minimum \le parameter \le maximum\).

Parameters:

  • parameter (str, optional): parameter to be used as a filter (e.g. Latitude)
  • minimum (float, optional): allowed minimum value
  • maximum (float, optional): allowed maximum value

It is possible to apply multiple filters with consecutive calls to this method.

Example: to set filter: -20 <= Longitude <= 50 and 30 <= Latitude <= 70:

[25]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Set collection
request.set_collection('SW_OPER_MAGA_LR_1B')

# Set product
request.set_products(measurements=['F', 'B_NEC'])

# Set filters
request.set_range_filter('Longitude', -20.0, 50.0)
request.set_range_filter('Latitude', 30.0, 70.0)
[25]:
<viresclient._client_swarm.SwarmRequest at 0x7f6552398e90>

Filters can be removed using the SwarmRequest.clear_range_filter() method:

SwarmRequest.clear_range_filter()
[26]:
request.clear_range_filter()
[26]:
<viresclient._client_swarm.SwarmRequest at 0x7f6552398e90>

TOP

Send request to the server

After setting collection(s), measurements, auxiliaries and models, we are ready to send the request to the server using the SwarmRequest.get_between() method:

SwarmRequest.get_between(start_time=None, end_time=None, filetype='cdf', asynchronous=True, show_progress=True, nrecords_limit=None, tmpdir=None)

Parameters:

  • start_time (datetime.datetime or str, optional): lower bound of temporal interval. If provided as string, it must be compliant to ISO-8601.
  • end_time (datetime.datetime or str, optional): upper bound of temporal interval. If provided as string, it must be compliant to ISO-8601.
  • filetype (str, optional): file format. Allowed values: csv and cdf (default).
  • asynchronous (bool, optional): if True (default), set the asynchronous processing.
  • show_progress (bool, optional): if True (default), enable the progress bar while processing and downloading data.
  • nrecords_limit (int): overrides the limit of 3456000 records.

Example: download data according to the following inut parameters and get the list of source data files: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T00:00:00] - file format: CDF - filters: none

[27]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Create the request object
request = SwarmRequest()

# Set collections
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')

# Set products
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)

# Get data
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)

Data is returned as a ReturnedData object:

[28]:
type(data)
[28]:
viresclient._data_handling.ReturnedData

TOP

Handle downloaded data - ReturnedData

Once the server receives the user’s request, it creates the product, than this product is automatically downloaded and returned to the client as a ReturnedData object. Thus you don’t need to create it by yourself. It is now possible to convert this data to a pandas.DataFrame object or to a xarray.Dataset object or to save it to one or more files.

ReturnedData object has the following attributes:

  • ReturnedData.sources
  • ReturnedData.contents
  • ReturnedData.file_types
  • ReturnedData.magnetic_models
  • ReturnedData.range_filters

and the following methods:

  • ReturnedData.as_dataframe()
  • ReturnedData.as_xarray()
  • ReturnedData.to_file()
  • ReturnedData.to_files()

TOP

Get the list of source data

This attribute contains the list of source data files from which the values have been extracted.

Example: download data according to the following inut parameters and get the list of source data files: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T00:00:00] - file format: CDF - filters: none

[29]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[30]:
# Get list of sources
data.sources
[30]:
['CHAOS-7_static.shc',
 'SW_OPER_AUXAORBCNT_20131122T000000_20200228T000000_0001',
 'SW_OPER_EFIA_LP_1B_20190930T000000_20190930T235959_0501_MDR_EFI_LP',
 'SW_OPER_EFIA_LP_1B_20191001T000000_20191001T235959_0501_MDR_EFI_LP',
 'SW_OPER_MAGA_LR_1B_20191001T000000_20191001T235959_0505_MDR_MAG_LR',
 'SW_OPER_MCO_SHA_2X_19970101T000000_20200419T235959_0701']

This is the list of the files from which the measurement and auxiliaries values and the magnetic models values have been retrieved.

TOP

ReturnedData contents

Downloaded data is saved to one or more temporary files represente as ReturnedDataFile objects. The ReturnedData.contents attribute contains the list of these objects.

Example: download data according to the following inut parameters and get the ReturnedData contents: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T00:00:00] - file format: CDF - filters: none

[31]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[32]:
# Get the ReturnedData contents
data.contents
[32]:
[<viresclient._data_handling.ReturnedDataFile at 0x7f6551d01790>]

TOP

Get type of downloaded data files

This attribute contains the type of downloaded files (i.e. cdf or csv).

Example: download data according to the following inut parameters and get the ReturnedData file type: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T00:00:00] - file format: CDF - filters: none

[33]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')

# Get ReturnedData file type
data.filetype
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[33]:
'cdf'

TOP

Get list of magnetic models used during calculations

This attribute contains the list of the magnetic models used during calculations.

Example: get F and B_NEC from SW_OPER_MAGA_LR_1B, Ne from SW_OPER_EFIA_LP_1B, model CHAOS = “CHAOS-Core” + “Chaos-Static” and auxiliary OrbitNumber with a sampling step of 10 seconds, between 2019-10-01T00:00:00 and 2019-10-01T01:00:00 in CDF format and get the list of magnetic models used during calculations:

Example: download data according to the following inut parameters and get the list of magnetic models: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[34]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[35]:
# Get magnetic models
data.magnetic_models
[35]:
["CHAOS = 'CHAOS-Core'(max_degree=20,min_degree=1) + 'CHAOS-Static'(max_degree=185,min_degree=21)"]

TOP

Get list of filters applied to the request

This attribute contains the list of applied filters

Example: download data according to the following inut parameters and get the list of the applied filters: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-02T00:00:00] - file format: CDF - filters: - Longitude: \([-20.0, 50.0]\) - Latitude: \([30.0, 70.0]\)

[36]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
request.set_range_filter('Longitude', -20.0, 50.0)
request.set_range_filter('Latitude', 30.0, 70.0)
data = request.get_between('2019-10-01T00:00:00', '2019-10-02T00:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.099MB)
[37]:
# Get list of applied filters
data.range_filters
[37]:
['Latitude:30,70', 'Longitude:-20,50']

TOP

Convert ReturnedData to Pandas DataFrame

Data downloaded from the server can be converted to a pandas.DataFrame object. This is a general 2D labeled, size-mutable tabular structure with potentially heterogeneously-typed column allowing the user to directly access data. For more information:

This conversion can be obtained with the ReturnedData.as_dataframe() method:

ReturnedData.as_dataframe(expand=False)

Parameters:

  • expand (bool, optional): If set to False (default), the vector parameters are represented as arrays (i.e. all the vector components in the same column). If this parameter is stet to True, the vector parameters are expanded (i.e. each component in a separate column).

Example: download data according to the following inut parameters and convert the ReturnedData object to a pandas DataFrame: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[38]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[39]:
# Convert ReturnedData to pandas DataFrame
df = data.as_dataframe()

You can visualize the first 5 records using the DataFrame.head() method:

[40]:
df.head()
[40]:
OrbitNumber Ne Longitude Spacecraft F B_NEC F_CHAOS Radius Latitude B_NEC_CHAOS
2019-10-01 00:00:00 32904 108830.9 37.641386 A 26246.0328 [11030.816, -6222.3955000000005, -22988.693300... 26240.985891 6820061.65 -33.130184 [11046.424869499242, -6221.021024854402, -2297...
2019-10-01 00:00:10 32904 116231.7 37.642219 A 26281.9878 [10910.8961, -6345.64, -23053.250200000002] 26276.579667 6820113.72 -33.771114 [10925.955568855303, -6344.535396315394, -2303...
2019-10-01 00:00:20 32904 116226.5 37.643695 A 26322.3415 [10798.207900000001, -6468.446800000001, -2311... 26316.580822 6820164.78 -34.412011 [10812.911047129362, -6467.100084355649, -2310...
2019-10-01 00:00:30 32904 120598.5 37.645838 A 26367.2575 [10692.824700000001, -6590.2154, -23183.793700... 26361.164222 6820214.83 -35.052873 [10707.112068975179, -6588.730009330973, -2317...
2019-10-01 00:00:40 32904 129792.6 37.648675 A 26416.9227 [10594.3256, -6710.861, -23250.8852] 26410.501735 6820263.88 -35.693700 [10608.360249796353, -6709.418192882664, -2323...

Setting expand=True:

[41]:
df = data.as_dataframe(expand=True)

each vector component is in a separate column:

[42]:
df.head()
[42]:
OrbitNumber Ne Longitude Spacecraft F F_CHAOS Radius Latitude B_NEC_N B_NEC_E B_NEC_C B_NEC_CHAOS_N B_NEC_CHAOS_E B_NEC_CHAOS_C
2019-10-01 00:00:00 32904 108830.9 37.641386 A 26246.0328 26240.985891 6820061.65 -33.130184 11030.8160 -6222.3955 -22988.6933 11046.424869 -6221.021025 -22975.307083
2019-10-01 00:00:10 32904 116231.7 37.642219 A 26281.9878 26276.579667 6820113.72 -33.771114 10910.8961 -6345.6400 -23053.2502 10925.955569 -6344.535396 -23039.726659
2019-10-01 00:00:20 32904 116226.5 37.643695 A 26322.3415 26316.580822 6820164.78 -34.412011 10798.2079 -6468.4468 -23118.1299 10812.911047 -6467.100084 -23104.544950
2019-10-01 00:00:30 32904 120598.5 37.645838 A 26367.2575 26361.164222 6820214.83 -35.052873 10692.8247 -6590.2154 -23183.7937 10707.112069 -6588.730009 -23170.182717
2019-10-01 00:00:40 32904 129792.6 37.648675 A 26416.9227 26410.501735 6820263.88 -35.693700 10594.3256 -6710.8610 -23250.8852 10608.360250 -6709.418193 -23237.060964

TOP

Convert ReturnedData to xarray Dataset

Data downloaded from the server can be converted to a xarray.Dataset object. This is a multi-dimentional array allowing the user to directly access data. For more information:

This conversion can be obtained with the ReturnedData.as_xarray().

Example: download data according to the following inut parameters and convert the ReturnedData object to an xarray Dataset: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[43]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[44]:
# Convert ReturnedData to pandas DataFrame
ds = data.as_xarray()

You can se how the xarray Dataset is represented:

[45]:
ds
[45]:
<xarray.Dataset>
Dimensions:      (NEC: 3, Timestamp: 360)
Coordinates:
  * Timestamp    (Timestamp) datetime64[ns] 2019-10-01 ... 2019-10-01T00:59:50
  * NEC          (NEC) <U1 'N' 'E' 'C'
Data variables:
    Spacecraft   (Timestamp) object 'A' 'A' 'A' 'A' 'A' ... 'A' 'A' 'A' 'A' 'A'
    OrbitNumber  (Timestamp) int32 32904 32904 32904 32904 ... 32905 32905 32905
    F_CHAOS      (Timestamp) float64 2.624e+04 2.628e+04 ... 4.748e+04 4.745e+04
    Ne           (Timestamp) float64 1.088e+05 1.162e+05 ... 4.102e+04 3.138e+04
    Longitude    (Timestamp) float64 37.64 37.64 37.64 ... -139.6 -137.9 -135.9
    F            (Timestamp) float64 2.625e+04 2.628e+04 ... 4.749e+04 4.746e+04
    B_NEC        (Timestamp, NEC) float64 1.103e+04 -6.222e+03 ... 4.744e+04
    Radius       (Timestamp) float64 6.82e+06 6.82e+06 ... 6.803e+06 6.803e+06
    Latitude     (Timestamp) float64 -33.13 -33.77 -34.41 ... 82.09 82.69 83.29
    B_NEC_CHAOS  (Timestamp, NEC) float64 1.105e+04 -6.221e+03 ... 4.744e+04
Attributes:
    Sources:         ['CHAOS-7_static.shc', 'SW_OPER_AUXAORBCNT_20131122T0000...
    MagneticModels:  ["CHAOS = 'CHAOS-Core'(max_degree=20,min_degree=1) + 'CH...
    RangeFilters:    []

TOP

Save downloaded data to a file

Data downloaded from the server can be saved to a file using the ReturnedData.to_file() method:

ReturnedData.to_file(path, overwrite=False)

Parameters:

  • path (str): output file path.
  • overwrite (bool, optional):if True allows to overwrite the file if already present at path.

Example: download data according to the following inut parameters and save the ReturnedData object to a file: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[46]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[47]:
# Save ReturnedData to a file
data.to_file('out.cdf', overwrite=True)
Data written to out.cdf

Note: this method can be used only if the amount of downloaded data is small (i.e. if the request is not split between multiple requests).

Example: download data according to the following inut parameters and save the ReturnedData object to a file: - measurements: U_orbit, Ne, Te, Vs - magnetic models: none - auxiliaries: none - sampling step: default - time interval: [2019-10-01T00:00:00, 2019-11-01T00:00:00] - file format: CDF - filters: none

[48]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['U_orbit', 'Ne', 'Te', 'Vs'],
)
data = request.get_between('2019-10-01T00:00:00', '2019-11-01T00:00:00')
[1/2] Processing:  100%|██████████|  [ Elapsed: 00:04, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:02, Remaining: 00:00 ] (279.743MB)
[2/2] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (67.389MB)

The request is split between multiple requests. Try to execute the cell below:

[49]:
data.to_file('huge.cdf', True)
---------------------------------------------------------------------------
NotImplementedError                       Traceback (most recent call last)
<ipython-input-49-589a24500271> in <module>
----> 1 data.to_file('huge.cdf', True)

/opt/conda/lib/python3.7/site-packages/viresclient/_data_handling.py in to_file(self, path, overwrite)
    641         if len(self.contents) != 1:
    642             raise NotImplementedError(
--> 643                 "Data is split into multiple files. Use .to_files instead")
    644         self.contents[0].to_file(path, overwrite)

NotImplementedError: Data is split into multiple files. Use .to_files instead
[50]:
# Remove saved files (if any)
!rm *.cdf

TOP

Save downloaded data to multiple files

Data downloaded from the server can be saved to one or more files using the ReturnedData.to_files() method:

ReturnedData.to_files(paths, overwrite=False)

Parameters:

  • paths (list[str]): output files path as a list of strings.
  • overwrite (bool, optional):if True allows to overwrite the file if already present at path.

Example: download data according to the following inut parameters and save the ReturnedData object a file using the ReturnedData.to_files() method: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[51]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[52]:
# Save ReturnedData to a file
data.to_files(['out.cdf'], overwrite=True)
Data written to out.cdf

This method is very useful in case the request has been split between multiple requests

Example: download data according to the following inut parameters and save the ReturnedData object to a files: - measurements: U_orbit, Ne, Te, Vs - magnetic models: none - auxiliaries: none - sampling step: default - time interval: [2019-10-01T00:00:00, 2019-11-01T00:00:00] - file format: CDF - filters: none

[53]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['U_orbit', 'Ne', 'Te', 'Vs'],
)
data = request.get_between('2019-10-01T00:00:00', '2019-11-01T00:00:00')
[1/2] Processing:  100%|██████████|  [ Elapsed: 00:03, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:02, Remaining: 00:00 ] (279.743MB)
[2/2] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (67.389MB)
[54]:
# Save ReturnedData to files
data.to_files(['first.cdf', 'second.cdf'], overwrite=True)
Data written to first.cdf
Data written to second.cdf

Note: the number of files to be specified must be equal to the number of files indicated by the ReturnedData.contents attribute. In the above case:

[55]:
data.contents
[55]:
[<viresclient._data_handling.ReturnedDataFile at 0x7f65504c8ed0>,
 <viresclient._data_handling.ReturnedDataFile at 0x7f6550d9d450>]
[56]:
# Remove saved files (if any)
!rm *.cdf

TOP

Handle downloaded temporary data file - ReturnedDataFile

This object holds the file downloaded from the server. Even if data has not ben saved to a file with the ReturnedData.to_files(), it is stored in a temporary file and automatically deleted when not needed anymore. As indicated in the “ReturnedData contents” section, you can get the list of the returned data files using the ReturnedData.contents attribute. Thus, you don’t need to create this object by yourself.

Note: the description of this object has been included for completeness only. You won’t need to use this object and its methods directly. To handle the downloaded data is preferable to use the ReturnedData object.

ReturnedDataFile object has the following attributes:

  • ReturnedDataFile._file
  • ReturnedDataFile.filetype

and the following methods:

  • ReturnedDataFile.as_dataframe()
  • ReturnedDataFile.as_xarray()
  • ReturnedDataFile.to_file()

TOP

Get the NamedTemporaryFile associated to a ReturnedDataFile

The NamedTemporaryFile corresponding to the ReturnedDataFile is contained in the ReturnedDataFile._file attribute.

Example: download data according to the following inut parameters and get the NamedTemporaryFiles objects associated to ReturnedDataFiles: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[57]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[58]:
# Get ReturnedData contents
data.contents
[58]:
[<viresclient._data_handling.ReturnedDataFile at 0x7f6550431750>]

ReturnedData contains only one ReturnedDataFile. Let’s get the associated NamedTemporaryFile:

[59]:
data.contents[0]._file
[59]:
<tempfile._TemporaryFileWrapper at 0x7f6550431110>

tempfile.NamedTemporaryFile is part of the Python standard library. For more information see: https://docs.python.org/3/library/tempfile.html#tempfile.NamedTemporaryFile

TOP

Get type of the downloaded data file

This attribute contains the type of downloaded files (i.e. cdf, csv or nc)

Example: download data according to the following inut parameters and get the file type of the ReturnedDataFile: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[60]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[61]:
# Get ReturnedData contents
data.contents
[61]:
[<viresclient._data_handling.ReturnedDataFile at 0x7f6550443bd0>]
[62]:
# Get file type
data.contents[0].filetype
[62]:
'cdf'

TOP

Convert ReturnedDataFile to Pandas Dataframe

As for the ReturnedData object (see Convert ReturnedData to Pandas DataFrame), the ReturnedDataFile object can be converted to a Pandas DataFrame using the ReturnedDataFile.as_dataframe() method:

ReturnedDataFile.as_dataframe(expand=False)

Parameters:

  • expand (bool, optional): If set to False (default), the vector parameters are represented as arrays (i.e. all the vector components in the same column). If this parameter is stet to True, the vector parameters are expanded (i.e. each component in a separate column).

TOP

Convert ReturnedDataFile to xarray Dataset

As for the ReturnedData object (see Convert ReturnedData to xarray Dataset), the ReturnedDataFile object can be converted to an xarray Dataset using the ReturnedDataFile.as_xarray() method:

ReturnedDataFile.as_xarray()

TOP

Save ReturnedDataFile object to a file

Data stored in the ReturnedDataFile object can be saved to a file with the ReturnedDataFile.to_file() method:

ReturnedDataFile.to_file(path, overwrite=False)

Parameters:

  • path (str): output file path.
  • overwrite (bool, optional):if True allows to overwrite the file if already present at path.

Example: download data according to the following inut parameters and get the file type of the ReturnedDataFile: - measurements: F, B_NEC, Ne - magnetic models: CHAOS = “CHAOS-Core” + “Chaos-Static” - auxiliaries: OrbitNumber - sampling step: 10 seconds - time interval: [2019-10-01T00:00:00, 2019-10-01T01:00:00] - file format: CDF - filters: none

[63]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B', 'SW_OPER_EFIA_LP_1B')
request.set_products(
    measurements=['F', 'B_NEC', 'Ne'],
    models=['CHAOS = "CHAOS-Core" + "CHAOS-Static"'],
    auxiliaries=['OrbitNumber'],
    residuals=False,
    sampling_step='PT10S'
)
data = request.get_between('2019-10-01T00:00:00', '2019-10-01T01:00:00')
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.098MB)
[64]:
# Save the ReturnedDataFile to a file
data.contents[0].to_file('out.cdf', overwrite=True)
Data written to out.cdf
[65]:
# Remove saved files (if any)
!rm out.cdf

TOP

Handle viresclient configuration - ClientConfig

You can acces the viresclient configuration using the ClientConfig class:

class viresclient.ClientConfig(path=None)

Parameters: - path (str, optional): path of the configuration file. If not specified, the default configuration file is assumed: ~/.viresclient.ini.

Example: create the ClientConfig object associated to the default configuration file:

[66]:
# Import the ClientConfig
from viresclient import ClientConfig

# Create the ClientConfig object
default = ClientConfig()

ClientConfig object has the following attributes:

  • ClientConfig.path
  • ClientConfig.default_url

and the following methods:

  • ClientConfig.set_site_config()
  • ClientConfig.get_site_config()
  • ClientConfig.save()

TOP

Get path of the configuration file

The ClientConfig.path read-only attribute contains the path of the configuration file.

Example: create the ClientConfig object associated to the default configuration file and check its path:

[67]:
# Import the ClientConfig (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig

# Create the ClientConfig object
default = ClientConfig()

default.path
[67]:
'/home/jovyan/.viresclient.ini'

TOP

Get or set the default URL

The ClientConfig.default_url attribute contains server’s default URL (i.e. the one used when SwarmClient class is invoked without URL).

Example: create the ClientConfig object associated to the default configuration file and check the default URL:

[68]:
# Import the ClientConfig (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig

# Create the ClientConfig object
default = ClientConfig()

default.default_url
[68]:
'https://vires.services/ows'

If the default URL is not set, the attribute returns None.

Example: create a new configuration:

[69]:
# Import the ClientConfig (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig

# Create new configuration
newcfg = ClientConfig('newfile.ini')

# Print default URL
print(newcfg.default_url)
None

Set default URL to: https://vires.services/ows:

[70]:
newcfg.default_url = 'https://vires.services/ows'

Get the updated result:

[71]:
# Print default URL
print(newcfg.default_url)
https://vires.services/ows

TOP

Set site configuration

It is possible to set the configuration for a server identified by an URL with the Client.Config.set_site_config() method:

ClientConfig.set_site_config(url, **options)

Parameters:

  • url (str): server URL
  • ****options** (str): configuration options in the form: key=value (e.g.: token=’…’)

Example: create a new configuration, set default URL to: https://vires.services/ows and set the access token for this URL:

[72]:
# Import the ClientConfig (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig

# Create new configuration
newcfg = ClientConfig('newfile.ini')

# Set default URL
newcfg.default_url = 'https://vires.services/ows'

# Set the access token
newcfg.set_site_config(newcfg.default_url, token='mytokenstring')

TOP

Get site configuration

It is possible to get the configuration for a server identified by an URL with the ClientConfig.get_site_config() method:

ClientConfig.get_site_config(url)

Parameters:

  • url (str): server URL

Example: create a new configuration, set default URL to: https://vires.services/ows, set the access token for this URL and get the configuration for https://vires.services/ows:

[73]:
# Import the ClientConfig (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig

# Create new configuration
newcfg = ClientConfig('newfile.ini')

# Set default URL
newcfg.default_url = 'https://vires.services/ows'

# Set the access token
newcfg.set_site_config(newcfg.default_url, token='mytokenstring')

# Get the configuration
newcfg.get_site_config('https://vires.services/ows')
[73]:
{'token': 'mytokenstring'}

TOP

Save configuration

The configuration stored in the ClientConfig object can be saved using the ClientConfig.save() method:

ClientConfig.save()

This method saves the configuration to the path specified during the ClientConfig creation. You can check this value via the ClientConfig.path attribute.

Example: create a new configuration, set default URL to: https://vires.services/ows, set the access token for this URL and save the configuration to file:

[74]:
# Import the ClientConfig (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig

# Create new configuration
newcfg = ClientConfig('newfile.ini')

# Set default URL
newcfg.default_url = 'https://vires.services/ows'

# Set the access token
newcfg.set_site_config(newcfg.default_url, token='mytokenstring')

# Save the configuration
newcfg.save()

Let’s have a look to the new configuration file:

[75]:
!cat newfile.ini
[default]
url = https://vires.services/ows

[https://vires.services/ows]
token = mytokenstring

[76]:
# delete newfile.ini
!rm newfile.ini

TOP

Upload data to the server - DataUpload

You can upload your data to the server to view it in the VirES web interface. File format can be CDF or CSV and must be compliant to: https://github.com/ESA-VirES/VirES-Server/blob/master/vires/custom_data_format_description.md.

Data can be uploaded using the DataUpload object:

class DataUpload(url, token, **kwargs)

Parameters:

  • url (str): server URL
  • token (str): access token
  • ****kwargs** (str): additional parameters (currently not used)

DataUpload object has the following attributes:

  • DataUpload.ids

and the following methods:

  • DataUpload.post()
  • DataUpload.get()
  • DataUpload.set_constant_parameters()
  • DataUpload.get_constant_parameters()

Example: create a DataUpload object for data upload to the default server. You can retrieve the default URL and the access token from the configuration, using the ClientConfig object:

[77]:
# Import DataUpload object
from viresclient import DataUpload

# Import ClientConfig object (this step can be avoided if ClientConfig has been already imported)
from viresclient import ClientConfig

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

TOP

Upload a file to the server

You can upload a file to the server using the DataUpload.post() method:

DataUpload.post(file, filename=None)

Parameters:

  • file (str): file to be uploaded

The method returns the info about the uploaded file as a dictionary.

Example: upload a product to the server:

[78]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf

[79]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Check info about the uploaded file:

[80]:
info
[80]:
{'missing_fields': {},
 'source_fields': ['F',
  'Timestamp',
  'Longitude',
  'B_NEC',
  'Radius',
  'Latitude'],
 'content_type': 'application/x-cdf',
 'owner': 'ashleysmith',
 'size': 243326,
 'end': '2020-01-01T00:59:59Z',
 'constant_fields': {},
 'data_file': 'out.cdf',
 'fields': {'F': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'Timestamp': {'shape': [], 'cdf_type': 31, 'data_type': 'CDF_EPOCH'},
  'Longitude': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'Latitude': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'Radius': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'B_NEC': {'shape': [3], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'}},
 'created': '2020-02-28T16:52:33.673116Z',
 'filename': 'out.cdf',
 'start': '2020-01-01T00:00:00Z',
 'is_valid': True,
 'checksum': 'bef12db0b7be7da745bb304c2645143a',
 'identifier': 'cc444746-ea21-4241-bdbd-689d2be634cf'}
[81]:
# Delete test file (if any)
!rm out.cdf

TOP

Get the identifier(s) of the uploaded file(s)

You can obtain the identifiers of the uploaded files via the DataUpload.ids attribute as a list. Please note that currently the server accepts only one file at a time, thus the returned list will have length 1.

Example: upload a product to the server and get its identifier:

[82]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf
[83]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Get id of the uploaded file:

[84]:
du.ids
[84]:
['c1069d28-27a3-490d-ad84-47a481a80f18']
[85]:
# Delete test file (if any)
!rm out.cdf

TOP

Get info about the uploaded file

You can get the info of the uploaded file using the DataUpload.get() method:

DataUpload.get(identifier=None)

Parameters:

Example: upload a product to the server and get product’s info with DataUpload.get():

[86]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf

[87]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Get info about the uploaded file:

[88]:
du.get(du.ids[0])
[88]:
{'missing_fields': {},
 'source_fields': ['F',
  'Timestamp',
  'Longitude',
  'B_NEC',
  'Radius',
  'Latitude'],
 'content_type': 'application/x-cdf',
 'owner': 'ashleysmith',
 'size': 243326,
 'end': '2020-01-01T00:59:59Z',
 'constant_fields': {},
 'data_file': 'out.cdf',
 'fields': {'F': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'Timestamp': {'shape': [], 'cdf_type': 31, 'data_type': 'CDF_EPOCH'},
  'Longitude': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'Latitude': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'Radius': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
  'B_NEC': {'shape': [3], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'}},
 'created': '2020-02-28T16:52:53.895027Z',
 'filename': 'out.cdf',
 'start': '2020-01-01T00:00:00Z',
 'is_valid': True,
 'checksum': 'f363730f087b390eb401bbbb06d64cd1',
 'identifier': 'e9f61595-49d7-4f37-a5f2-e27e9ce7129a'}

If the identifier is not provided, you will get info about all the files as a list:

[89]:
du.get()
[89]:
[{'missing_fields': {},
  'source_fields': ['F',
   'Timestamp',
   'Longitude',
   'B_NEC',
   'Radius',
   'Latitude'],
  'content_type': 'application/x-cdf',
  'owner': 'ashleysmith',
  'size': 243326,
  'end': '2020-01-01T00:59:59Z',
  'constant_fields': {},
  'data_file': 'out.cdf',
  'fields': {'F': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
   'Timestamp': {'shape': [], 'cdf_type': 31, 'data_type': 'CDF_EPOCH'},
   'Longitude': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
   'Latitude': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
   'Radius': {'shape': [], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'},
   'B_NEC': {'shape': [3], 'cdf_type': 45, 'data_type': 'CDF_DOUBLE'}},
  'created': '2020-02-28T16:52:53.895027Z',
  'filename': 'out.cdf',
  'start': '2020-01-01T00:00:00Z',
  'is_valid': True,
  'checksum': 'f363730f087b390eb401bbbb06d64cd1',
  'identifier': 'e9f61595-49d7-4f37-a5f2-e27e9ce7129a'}]
[90]:
# Delete test file (if any)
!rm out.cdf

TOP

Set constant parameters to the uploaded file

It is possible to set constant parameters to the uploaded file using the DataUpload.set_constant_parameters() method:

DataUpload.set_constant_parameters(identifier, parameters, replace=False)

Parameters:

  • identifier (str): file identifier.
  • parameters (dict): constant parameters provided as a dictionary
  • replace (bool, optional): if set to True, all the parameters will be replaced by the new parameters, otherwise the new parameters will update the existing ones (default behaviour).

Example: upload a product to the server and set constant parameters to the uploaded file:

[91]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf

[92]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Assign constant parameters: \(param1 = 12345\) and \(param2 = 34567\):

[93]:
du.set_constant_parameters(du.ids[0], {'param1': 12345, 'param2': 34567})
[93]:
{'param2': 34567, 'param1': 12345}

If you want to set param1 to a new value you can update the existing set of parameters:

[94]:
du.set_constant_parameters(du.ids[0], {'param1': 1})
[94]:
{'param2': 34567, 'param1': 1}

or replace the entire set of parameters:

[95]:
du.set_constant_parameters(du.ids[0], {'param1': 1}, replace=True)
[95]:
{'param1': 1}

Note that param2 has been removed.

[96]:
# Delete test file (if any)
!rm out.cdf

TOP

Get constant parameters applied to the uploaded file

It is possible to get the list of constant parameters applied to the uploaded file using the DataUpload.get_constant_parameters() method:

DataUpload.get_constant_parameters(identifier)

Parameters:

  • identifier (str): file identifier.

Example: upload a product to the server and get constant parameters applied to the uploaded file:

[97]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf

[98]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Assign constant parameters: \(param1 = 12345\) and \(param2 = 34567\):

[99]:
du.set_constant_parameters(du.ids[0], {'param1': 12345, 'param2': 34567})
[99]:
{'param2': 34567, 'param1': 12345}

Get the list of constant parameters:

[100]:
du.get_constant_parameters(du.ids[0])
[100]:
{'param2': 34567, 'param1': 12345}
[101]:
# Delete test file (if any)
!rm out.cdf

TOP

Delete a specific uploaded file

You can delete a specific uploaded file using the DataUpload.delete() method:

DataUpload.delete(identifier)

Parameters:

Example: upload a product to the server and delete it with DataUpload.delete():

[102]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf

[103]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Delete the uploaded product:

[104]:
du.delete(du.ids[0])

du.ids
[104]:
[]
[105]:
# Delete test file (if any)
!rm out.cdf

TOP

Delete the uploaded files

You can delete all the uploaded files using the DataUpload.clear() method:

DataUpload.clear()

Example: upload a product to the server and delete it with DataUpload.clear():

[106]:
# Import SwarmClient (this step can be omitted if already executed in the previous examples)
from viresclient import SwarmRequest

# Download 1 hour of MAGA_LR_1B data
request = SwarmRequest()
request.set_collection('SW_OPER_MAGA_LR_1B')
request.set_products(measurements=['F', 'B_NEC'])
data = request.get_between('2020-01-01T00:00:00', '2020-01-01T01:00:00')
data.to_file('out.cdf', overwrite=True)
[1/1] Processing:  100%|██████████|  [ Elapsed: 00:01, Remaining: 00:00 ]
      Downloading: 100%|██████████|  [ Elapsed: 00:00, Remaining: 00:00 ] (0.243MB)
Data written to out.cdf

[107]:
# Import ClientConfig and DataUpload (this step can be omitted if already executed in the previous examples)
from viresclient import ClientConfig, DataUpload

# Create ClientConfig object associated to the default configuration file: ~/.viresclient.ini
default = ClientConfig()

# Get default URL and access token from the configuration
url = default.default_url
token = default.get_site_config(url)['token']

# Create the DataUpload object:
du = DataUpload(url, token)

# Upload the file to the server to be visualized in the web client
info = du.post('out.cdf')

Delete the uploaded product(s):

[108]:
du.clear()

du.ids
[108]:
[]