Welcome to amdapy’s documentation!

amdapy is a python package for accessing data in AMDA. It is intended for anyone interested in manipulating heliophysics data. AMDA provides a vast collection of plasma physics datasets and analysis tools via its web platform AMDA. The amdapy package provides an interface for those wishing to manipulate AMDA datasets in their python scripts.

Github : https://github.com/cdppirap/amdapy.

AMDA home page

AMDA home page

Indices and tables

What is amdapy ?

AMDA is a collection of tools and datasets destined for research in the field to heliophysics. Through the web plateform AMDA user can download datasets from a multitude of missions, retrieve information about instrumentation used during these missions and view the measurements.

AMDA also provides access to simulation models and advanced vizualisation tools. For specific application users often have to download the data and perform the desired operations themselves.

Python is an open-source development language with a large and very active community. Reasearchers have developed a number of packages usefull in the field of astrophysics and amdapy aims to fill this gap in functionality. Users familiar with datasets in AMDA can now easily download data as a simple python object and do with it as they please.

amdapy makes use of AMDA’s internal REST/SOAP web service protocol to deliver data to the user.

Warning

This package is still under active developement and could undergo changes at any point.

Getting started

The following is an introduction to using amdapy. We present the hierachy under which AMDA stores its data structures and how we propose to navigate it.

Installation

The current packaged version of amdapy can be downloaded amdapy tar. This package requires Python3.5 (or a later version).

Install by executing the following

pip3 install amdapy

To install the package with pip from the source archive use the following:

pip3 install amdapy.tar.gz

On windows if you have Anaconda installed then use:

conda install amdapy

The collection

Datasets belong to a mission and an instrument and contain parameters (which we will refer to indistinctively. As each instrument makes measurements over time all parameters are timeseries. When refering to a parameters size we refer to any dimension other than time, for instance a position is of size (or dimension) 3.

Datasets and parameters have a unique identifier in AMDA by which they can be retrived. The amdapy.amda.Collection.find() searches the collection for an item with the corresponding id and returns a description of that object as presented below.

>>>dataset_desc
Dataset (id:tao-ura-sw, start:2010-01-01 00:00:00, stop:2021-02-19 00:00:00, n_param:7)
     Parameter (id:ura_sw_n, name:density, units:cm⁻³, shape: (24,))
     Parameter (id:ura_sw_v, name:velocity, units:km/s, nodata)
     Parameter (id:ura_sw_t, name:temperature, units:eV, shape: (24,))
     Parameter (id:ura_sw_pdyn, name:dynamic pressure, units:nPa, shape: (24,))
     Parameter (id:ura_sw_b, name:b tangential, units:nT, shape: (24,))
     Parameter (id:ura_sw_bx, name:b radial, units:nT, shape: (24,))
     Parameter (id:ura_sw_da, name:angle Uranus-Sun-Earth, units:deg, shape: (24,))

AMDA’s web service provides the user with a XML collection that is parsed by the amdapy.amda.Collection class. This object returns descriptions of the items belonging to the collection. Dataset descriptions are accessed via the amdapy.amda.Collection.Dataset class and parameters through amdapy.amda.Collection.Parameter.

Parameter ID in AMDA

You can find a parameters ID in the information popup when hovering a parameter in the AMDA dataset navigation tree

Getting data

Let’s see how to retrieve some data with a simple example by downloading the tao-ura-sw dataset.

Interacting with AMDA is done through the connector object amdapy.amda.AMDA :

>>> from amdapy.amda import AMDA
>>> amda = AMDA()

The user must retrieve the dataset description object (amdapy.amda.Collection.Dataset) using the amdapy.amda.Collection.find() method.

>>> dataset_description = amda.collection.find("tao-ura-sw")
>>> dataset_description
Dataset item (id:tao-ura-sw, name:SW / Input OMNI, start:2010-01-01 00:00:00, stop:2021-02-19 00:00:00, n_param:7)
     Parameter item (id:ura_sw_n, name:density, units:cm⁻³, disp:None, dataset:tao-ura-sw, n:1)
     Parameter item (id:ura_sw_v, name:velocity, units:km/s, disp:None, dataset:tao-ura-sw, n:2)
     Parameter item (id:ura_sw_t, name:temperature, units:eV, disp:None, dataset:tao-ura-sw, n:1)
     Parameter item (id:ura_sw_pdyn, name:dynamic pressure, units:nPa, disp:None, dataset:tao-ura-sw, n:1)
     Parameter item (id:ura_sw_b, name:b tangential, units:nT, disp:None, dataset:tao-ura-sw, n:1)
     Parameter item (id:ura_sw_bx, name:b radial, units:nT, disp:None, dataset:tao-ura-sw, n:1)
     Parameter item (id:ura_sw_da, name:angle Uranus-Sun-Earth, units:deg, disp:None, dataset:tao-ura-sw, n:1)

You may now download the data :

>>> dataset = amda.get(dataset_description)
>>> dataset
Dataset (id:tao-ura-sw, start:2010-01-01 00:00:00, stop:2021-02-19 00:00:00, n_param:7)
     Parameter (id:ura_sw_n, name:density, units:cm⁻³, shape: (24,))
     Parameter (id:ura_sw_v, name:velocity, units:km/s, nodata)
     Parameter (id:ura_sw_t, name:temperature, units:eV, shape: (24,))
     Parameter (id:ura_sw_pdyn, name:dynamic pressure, units:nPa, shape: (24,))
     Parameter (id:ura_sw_b, name:b tangential, units:nT, shape: (24,))
     Parameter (id:ura_sw_bx, name:b radial, units:nT, shape: (24,))
     Parameter (id:ura_sw_da, name:angle Uranus-Sun-Earth, units:deg, shape: (24,))

The contents of the dataset are availble through the data attribute :

>>> type(dataset.data)
<class 'pandas.core.frame.DataFrame'>

You can get individual parameters either through the bracket operator by passing the name or id of the desired parameter or by using the amdapy.amda.Dataset.iter_parameter() method.

>>> dataset["density"]
Parameter (id:ura_sw_n, name:density, units:cm⁻³, shape: (24,))

By default when calling amdapy.amda.AMDA.get() without the t_interval argument, only the first day of data is returned. If more data is required you can specify the time interval like in the following example :

>>> from amdapy.amda import Timespan
>>> import datetime
>>> time_interval = Timespan(dataset_description.starttime, dataset_description.starttime+datetime.timedelta(days=10))
>>> dataset = amda.get(dataset_description, time_interval)
>>> dataset.data.shape
(240,8)

A simple plot example :

>>> import matplotlib.pyplot as plt
>>> fig = dataset["density"].plot(dataset_id="tao-ura-sw")
>>> plt.show()
Simple plot of *density* for *tao-ura-sw* dataset

Plot density from tao-ura-sw dataset