SwarmRequest

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

Bases: viresclient._client.ClientRequest

Handles the requests to and downloads from the server.

Steps to download data:

  1. Set up a connection to the server with: request = SwarmRequest()
  2. Set collections to use with: request.set_collections()
  3. Set parameters to get with: request.set_products()
  4. Set filters to apply with: request.set_range_filter()
  5. Get the data in a chosen time window: request.get_between()
Parameters:
  • url (str) –
  • username (str) –
  • password (str) –
  • token (str) –
  • config (str or ClientConfig) –
  • logging_level (str) –
available_auxiliaries()

Returns a list of the available auxiliary parameters.

available_collections(details=True)

Show details of available collections.

Parameters:details (bool) – If True then print a nice output. If False then return a list of available collections.
available_measurements(collection=None)

Returns a list of the available measurements for the chosen collection.

Parameters:collection (str) – one of: (“MAG”, “EFI”, “IBI”, “TEC”, “FAC”, “EEF”)
available_models(param=None, details=True, nice_output=True)

Show details of avalable models.

If details is True, return a dictionary of model names and details. If nice_output is True, the dictionary is printed nicely. If details is False, return a list of model names. If param is set, filter to only return entries including this

Note

F = Fast-Track Products
C = Comprehensive Inversion
D = Dedicated Chain
MCO = Core / main
MLI = Lithosphere
MMA = Magnetosphere
MIO = Ionosphere
Parameters:
  • param (str) – one of “F C D MCO MLI MMA MIO”
  • details (bool) – True for a dict of details, False for a brief list
  • nice_output (bool) – If True, just print the dict nicely
clear_range_filter()

Remove all applied filters.

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

Make the server request and download the data.

Parameters:
  • start_time (datetime) –
  • end_time (datetime) –
  • filetype (str) – one of (‘csv’, ‘cdf’)
  • asynchronous (bool) – True for asynchronous processing, False for synchronous
  • show_progress (bool) – Set to False to remove progress bars
  • nrecords_limit (int) – Override the default limit per request (e.g. nrecords_limit=3456000)
  • tmpdir (str) – Override the default temporary file directory
Returns:

Return type:

ReturnedData

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

Get model info from server.

Handles the same models input as .set_products(), and returns a dict like:

{‘IGRF12’: { ‘expression’: ‘IGRF12(max_degree=13,min_degree=0)’, ‘validity’: {‘start’: ‘1900-01-01T00:00:00Z’, ‘end’: ‘2020-01-01T00:00:00Z’ }, …}

If original_response=True, return the list of dicts like:

{‘expression’: ‘MCO_SHA_2C(max_degree=16,min_degree=0)’, ‘name’: ‘MCO_SHA_2C’, ‘validity’: {‘start’: ‘2013-11-30T14:38:24Z’, ‘end’: ‘2018-01-01T00:00:00Z’}}, …

Parameters:
  • models (list/dict) – as with set_products
  • custom_model (str) – as with set_products
  • original_response (bool) –
Returns:

dict or list

get_orbit_number(spacecraft, input_time)

Translate a time to an orbit number.

Parameters:
  • spacecraft (str) – one of (‘A’,’B’,’C’) or (“Alpha”, “Bravo”, “Charlie”)
  • input_time (datetime) – a point in time
Returns:

The current orbit number at the input_time

Return type:

int

get_times_for_orbits(spacecraft, start_orbit, end_orbit)

Translate a pair of orbit numbers to a time interval.

Parameters:
  • spacecraft (str) – one of (‘A’,’B’,’C’) or (“Alpha”, “Bravo”, “Charlie”)
  • start_orbit (int) – a starting orbit number
  • end_orbit (int) – a later orbit number
Returns:

(start_time, end_time) The start time of the start_orbit and the ending time of the end_orbit. (Based on ascending nodes of the orbits)

Return type:

tuple (datetime)

set_collection(collection)

Set the collection to use (sets satellite implicitly).

Note

Currently limited to one collection, one satellite.

Parameters:collection (str) – one of .available_collections()
set_products(measurements=None, models=None, custom_model=None, auxiliaries=None, residuals=False, sampling_step=None)

Set the combination of products to retrieve.

If residuals=True then just get the measurement-model residuals, otherwise get both measurement and model values.

Parameters:
  • measurements (list(str)) – from .available_measurements(collection_key)
  • models (list(str)/dict) – from .available_models() or defineable with custom expressions
  • custom_model (str) – path to a custom model in .shc format
  • auxiliaries (list(str)) – from .available_auxiliaries()
  • residuals (bool) – True if only returning measurement-model residual
  • sampling_step (str) – ISO_8601 duration, e.g. 10 seconds: PT10S, 1 minute: PT1M
set_range_filter(parameter=None, minimum=None, maximum=None)

Set a filter to apply.

Filters data for minimum ≤ parameter ≤ maximum

Note

Apply multiple filters with successive calls to set_range_filter()

Parameters:
  • parameter (str) –
  • minimum (float) –
  • maximum (float) –

ReturnedData

class viresclient.ReturnedData(filetype=None, N=1, tmpdir=None)

Bases: object

Flexible object for working with data returned from the server

Holds a list of ReturnedDataFile objects. The number of them, N, is set upon initialisation. Access the ReturnedDataFile objects directly via the list in ReturnedData.contents.

as_dataframe()

Convert the data to a pandas DataFrame.

Returns:pandas.DataFrame
as_xarray()

Convert the data to an xarray Dataset.

Returns:xarray.Dataset
contents

List of ReturnedDataFile objects

filetype

Filetype string

to_file(path, overwrite=False)

Saves the data to the specified file, when data is only in one file.

Only write to file if it does not yet exist, or if overwrite=True. Currently handles CSV and CDF formats.

Parameters:
  • path (str) – path to the file to save as
  • overwrite (bool) – Will overwrite existing file if True
to_files(paths, overwrite=False)

Saves the data to the specified files.

Only write to file if it does not yet exist, or if overwrite=True. Currently handles CSV and CDF formats.

Parameters:
  • paths (list of str) – paths to the files to save as
  • overwrite (bool) – Will overwrite existing file if True
class viresclient.ReturnedDataFile(filetype=None, tmpdir=None)

Bases: object

For handling individual files returned from the server.

Holds the data returned from the server and the data type. Data is held in a NamedTemporaryFile, which is automatically closed and destroyed when it goes out of scope. Provides output to different file types and data objects.

as_dataframe()

Convert the data to a pandas DataFrame.

Returns:pandas.DataFrame
as_xarray(group=None)

Convert the data to an xarray Dataset.

Note

Does not support csv

Only supports scalar and 3D vectors (currently)

Returns:xarray.Dataset
file

Points to the actual file object

filetype

Filetype is one of (“csv”, “cdf”, “nc”)

open_cdf()

Returns the opened file as cdflib.CDF

to_file(path, overwrite=False)

Saves the data to the specified file.

Only write to file if it does not yet exist, or if overwrite=True. Currently handles CSV and CDF formats.

Parameters:
  • path (str) – path to the file to save as
  • overwrite (bool) – Will overwrite existing file if True
to_netcdf(path, overwrite=False)

Saves the data as a netCDF4 file (this is compatible with HDF5)

Extension should be .nc