\n",
"\n",
"VirES is a platform for data access, analysis, and visualisation for ESA's magnetic mission, *Swarm*\n",
"\n",
"This tutorial introduces the Python interface to VirES, `viresclient`\n",
"\n",
"For more information see:\n",
"- https://vires.services/\n",
"- https://viresclient.readthedocs.io\n",
"- https://earth.esa.int/web/guest/missions/esa-eo-missions/swarm/mission-overview"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 0. Configuration\n",
"\n",
"To access VirES through Python code, you first need to generate an authentication token from your VirES account:\n",
"\n",
"1. Create a user account at https://vires.services/ if you haven't already done so\n",
"2. Login there and go to settings (top right: the button with your user name)\n",
"3. Select \"Manage access tokens\" and follow the instructions to create a token (see first part of video)\n",
"5. Paste the token into the code below and run it once.\n",
"6. The default has now been configured and you won't need to provide the token again.\n",
"\n",
"This can also be done via the command line. For more info, see https://viresclient.readthedocs.io/en/latest/installation.html"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"%%HTML\n",
""
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from viresclient import ClientConfig\n",
"\n",
"cc = ClientConfig()\n",
"cc.set_site_config(\"https://vires.services/ows\", token=\"...\")\n",
"cc.default_url = \"https://vires.services/ows\"\n",
"cc.save()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 1. Fetching some data\n",
"\n",
"Import the `SwarmRequest` object which provides the VirES interface, and `datetime` which gives convenient time objects which can be used by `SwarmRequest.get_between()`"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from viresclient import SwarmRequest\n",
"import datetime as dt\n",
"%matplotlib inline"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following code will fetch one day (i.e. around 15 orbits) of the scalar (`F`) measurements from Swarm Alpha. The data are then loaded as a `pandas` dataframe. `sampling_step=\"PT10S\"` donwsamples the data to 10 seconds, from the `MAGx_LR` default of 1 second."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"request = SwarmRequest()\n",
"request.set_collection(\"SW_OPER_MAGA_LR_1B\")\n",
"request.set_products(\n",
" measurements=[\"F\"],\n",
" sampling_step=\"PT10S\"\n",
")\n",
"\n",
"data = request.get_between(\n",
" start_time=dt.datetime(2016,1,1),\n",
" end_time=dt.datetime(2016,1,2)\n",
")\n",
"\n",
"df = data.as_dataframe()\n",
"df.head()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Try plotting some things to visualise the data. The following shows the variation in field strength measured by the satellite as it passes between high and low latitudes, varying from one orbit to the next as it samples a different longitude."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"df.plot(y=\"F\")\n",
"df.plot(y=\"F\", x=\"Latitude\")\n",
"df.plot(y=\"Latitude\", x=\"Longitude\")\n",
"df.plot(y=\"Latitude\", x=\"Longitude\", c=\"F\", kind=\"scatter\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 2. Fetching model evaluations at the same time\n",
"\n",
"Various (mostly spherical harmonic) models of the magnetic field are produced as Swarm mission products and these are available through VirES. They are evaluated on demand at the same points and times as the data sample points. Here we ask for the `MCO_SHA_2D` model, a dedicated core field model produced from Swarm data. By supplying `residuals=True` we will get the data-model residuals, named in the dataframe as `F_res_MCO_SHA_2D`."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"request = SwarmRequest()\n",
"request.set_collection(\"SW_OPER_MAGA_LR_1B\")\n",
"request.set_products(\n",
" measurements=[\"F\"],\n",
" models=[\"MCO_SHA_2D\"],\n",
" residuals=True,\n",
" sampling_step=\"PT10S\"\n",
")\n",
"\n",
"data = request.get_between(\n",
" start_time=dt.datetime(2016,1,1),\n",
" end_time=dt.datetime(2016,1,2)\n",
")\n",
"\n",
"df = data.as_dataframe()\n",
"df.head()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The core field has been removed from the data so the amplitudes are much smaller. Can you interprete the new signals in terms of external fields, i.e. from the ionosphere and magnetosphere?"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"df.plot(y=\"F_res_MCO_SHA_2D\")\n",
"df.plot(y=\"F_res_MCO_SHA_2D\", x=\"Latitude\")\n",
"df.plot(y=\"Latitude\", x=\"Longitude\", c=\"F_res_MCO_SHA_2D\", kind=\"scatter\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 3. Explore the other possibilites through VirES\n",
"\n",
"To find out what other data and models are available, see https://viresclient.readthedocs.io/en/latest/available_parameters.html\n",
"\n",
"For examples see https://github.com/smithara/viresclient_examples (sorry they are a bit messy now and undocumented!)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.3"
}
},
"nbformat": 4,
"nbformat_minor": 2
}