{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Available data and models\n",
    "\n",
    "> Abstract: Different Swarm datasets are available through each \"collection\" on the VirES server. Choosing a collection determines the subset of \"measurement\"-type products available, while \"auxiliary\"-type are always available. Geomagnetic \"model\"-type are available in connection with the MAG collections. These can be seen at https://viresclient.readthedocs.io/en/latest/available_parameters.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext watermark\n",
    "%watermark -i -v -p viresclient,pandas,xarray,matplotlib"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from viresclient import SwarmRequest"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Querying available variables\n",
    "\n",
    "viresclient has some tools to help you find out what data and models are available. First instantiate a request object, then use it to call methods:\n",
    "```\n",
    "request.available_collections()\n",
    "request.available_measurements()\n",
    "request.available_auxiliaries()\n",
    "request.available_models()\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request = SwarmRequest()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Data are organised into \"collections\"\n",
    "\n",
    "To see a list of them with references:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_collections()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just the names of the collections:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_collections(details=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The collections are grouped according to those containing identical variable names, e.g.  \n",
    "`'MAG': ['SW_OPER_MAGA_LR_1B', 'SW_OPER_MAGB_LR_1B', 'SW_OPER_MAGC_LR_1B']`  \n",
    "indicates that these three are all of \"MAG\" type, while the actual collection names such as `SW_OPER_MAGA_LR_1B` point to the specific dataset - in this case, from Swarm Alpha (A), while the others are from Bravo (B) and Charlie (C)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Available \"measurements\"\n",
    "\n",
    "To query the variable names possible from a given collection type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"MAG\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"EFI\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"IBI\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"TEC\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"FAC\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"EEF\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_measurements(\"IPD\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Available \"auxiliaries\"\n",
    "\n",
    "These can be requested together with any collection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_auxiliaries()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Available \"models\"\n",
    "\n",
    "(and custom ones can be supplied as .shc files)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_models(details=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Swarm models are named with a prefix indicating the source field (e.g. MCO for \"Model of the Core field) and suffix indicating the processing chain (e.g. 2D for \"Level 2 product, Comprehensive Inversion chain\").\n",
    "\n",
    "C: Comprehensive; D: Dedicated; F: Fast-track\n",
    "\n",
    "|                     \t| C \t| D \t| F \t|\n",
    "|---------------------\t|---\t|---\t|---\t|\n",
    "| MCO - Core          \t| x \t| x \t| - \t|\n",
    "| MMA - Magnetosphere \t| x \t| - \t| x \t|\n",
    "| MIO - Ionosphere    \t| x \t| x \t| - \t|\n",
    "| MLI - Lithosphere   \t| x \t| x \t| - \t|\n",
    "\n",
    "MIO and MMA are divided into Primary and Secondary parts - primary for the external (to the Earth) ionospheric / magnetospheric field source, and secondary for the internally induced part in the upper mantle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Check models of a certain type\n",
    "\n",
    "e.g. the CI models:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_models(\"C\", details=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "... or MCO (core) models:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.available_models(\"MCO\", details=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Manipulation of models\n",
    "\n",
    "Models can be manipulated: combining different models, limiting spherical harmonic (SH) series summation to a smaller range of SH degree. These composed models can be provided within the `models` kwarg in `request.set_products()`, e.g.\n",
    "\n",
    "```python\n",
    "from viresclient import SwarmRequest\n",
    "request = SwarmRequest()\n",
    "request.set_collection(\"SW_OPER_MAGA_LR_1B\")\n",
    "request.set_products(\n",
    "    measurements=[\"F\"],\n",
    "    models=[\"MCO_MMA = 'MCO_SHA_2C' + 'MMA_SHA_2C-Primary' + 'MMA_SHA_2C-Secondary'\"],\n",
    ")\n",
    "```\n",
    "\n",
    "Model details can be found with `request.get_model_info(models=...)` which handles the same `models` input as `set_products()`. This information is returned as a dictionary.\n",
    "\n",
    "1. The models should be provided as a list of strings, where each string defines a particular model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.get_model_info(\n",
    "    models=[\"MCO_SHA_2D\", \"MCO_SHA_2C\"]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2.. Models can be combined to form a new model like:\n",
    "```\n",
    "\"New_model = 'Model_1' + 'Model_2'\"\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.get_model_info(\n",
    "    models=[\"MCO_MMA = 'MCO_SHA_2C' + 'MMA_SHA_2C-Primary' + 'MMA_SHA_2C-Secondary'\"]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. Limiting the SH degree range can be done with:\n",
    "```\n",
    "Model_name(min_degree=x, max_degree=y)\n",
    "```\n",
    "\n",
    "4. Your own .shc format model can be provided as a file, the model for which is then accessible within VirES under the name `\"Custom_Model\"`. NB: in this case you will also need to provide the `custom_model` kwarg in `request.set_products()` - the model is not persistently stored on the server.\n",
    "\n",
    "5. New models can be defined successively in the list, using names that have been defined earlier in the list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Fetch an example file to use\n",
    "url = \"http://www.spacecenter.dk/files/magnetic-models/LCS-1/LCS-1.shc\"\n",
    "file_name = \"LCS-1.shc\"\n",
    "import urllib.request\n",
    "urllib.request.urlretrieve(url, file_name);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Demonstrates:\n",
    "#  limiting SH degree\n",
    "#  providing your own model file\n",
    "#  referring to defined models\n",
    "request.get_model_info(\n",
    "    models=[\n",
    "        \"MLI_SHA_2D = MLI_SHA_2D(min_degree=1, max_degree=80)\",\n",
    "        \"LCS = Custom_Model(min_degree=1, max_degree=80)\",\n",
    "        \"LCS-SwarmMLI = LCS - MLI_SHA_2D\"\n",
    "    ],\n",
    "    custom_model=file_name,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to provide the models as a dictionary instead of a list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "request.get_model_info(\n",
    "    models={\n",
    "        \"MLI_SHA_2D\": \"MLI_SHA_2D(min_degree=1, max_degree=80)\",\n",
    "        \"LCS\": \"Custom_Model(min_degree=1, max_degree=80)\",\n",
    "        \"LCS-SwarmMLI\": \"LCS - MLI_SHA_2D\"\n",
    "    },\n",
    "    custom_model=\"LCS-1.shc\"\n",
    ")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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"
  },
  "toc-showmarkdowntxt": false
 },
 "nbformat": 4,
 "nbformat_minor": 4
}