{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pyaurorax\n",
    "import pprint\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Retrieve metadata schema for ephemeris data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Program:          swarm\n",
      "Platform:         swarma\n",
      "Instrument Type:  footprint\n"
     ]
    }
   ],
   "source": [
    "# set parameters\n",
    "program = \"swarm\"\n",
    "platform = \"swarma\"\n",
    "instrument_type = \"footprint\"\n",
    "print(\"%-18s%s\" % (\"Program:\", program))\n",
    "print(\"%-18s%s\" % (\"Platform:\", platform))\n",
    "print(\"%-18s%s\" % (\"Instrument Type:\", instrument_type))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Identifier: 3\n"
     ]
    }
   ],
   "source": [
    "# get identifier\n",
    "data_source = pyaurorax.sources.get_using_filters(program=program,\n",
    "                                                platform=platform,\n",
    "                                                instrument_type=instrument_type)\n",
    "identifier = data_source[0].identifier\n",
    "print(\"Identifier: %d\" % (identifier))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# get schema\n",
    "schema = pyaurorax.metadata.get_ephemeris_schema(data_source[0].identifier)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# View the schema"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>field_name</th>\n",
       "      <th>description</th>\n",
       "      <th>data_type</th>\n",
       "      <th>allowed_values</th>\n",
       "      <th>searchable</th>\n",
       "      <th>additional_description</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>nbtrace_region</td>\n",
       "      <td>Region based on where the magnetic field line ...</td>\n",
       "      <td>string</td>\n",
       "      <td>[north polar cap, north cusp, north cleft, nor...</td>\n",
       "      <td>True</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>sbtrace_region</td>\n",
       "      <td>Region based on where the magnetic field line ...</td>\n",
       "      <td>string</td>\n",
       "      <td>[south polar cap, south cusp, south cleft, sou...</td>\n",
       "      <td>True</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>radial_distance</td>\n",
       "      <td>Distance spacecraft is from Earth in kilometers</td>\n",
       "      <td>double</td>\n",
       "      <td>[]</td>\n",
       "      <td>True</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>spacecraft_region</td>\n",
       "      <td>Region based on the spacecraft's position with...</td>\n",
       "      <td>string</td>\n",
       "      <td>[interplanetary medium, dayside magnetosheath,...</td>\n",
       "      <td>True</td>\n",
       "      <td>A spacecraft can occupy only one region of thi...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>radial_trace_region</td>\n",
       "      <td>Region based on the location on the Earth's su...</td>\n",
       "      <td>string</td>\n",
       "      <td>[north polar cap, south polar cap, north cusp,...</td>\n",
       "      <td>True</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>state</td>\n",
       "      <td>Data is based on predictive or definitive info...</td>\n",
       "      <td>string</td>\n",
       "      <td>[predictive, definitive]</td>\n",
       "      <td>True</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>tii_on</td>\n",
       "      <td>Indicates that the TII instrument was operatio...</td>\n",
       "      <td>bool</td>\n",
       "      <td>[true, false]</td>\n",
       "      <td>True</td>\n",
       "      <td>Retrieved from TII 2Hz v0301 files. Further in...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>tii_quality_vixh</td>\n",
       "      <td>Quality flag for Vixh data (along-track compon...</td>\n",
       "      <td>int</td>\n",
       "      <td>[]</td>\n",
       "      <td>True</td>\n",
       "      <td>Retrieved from TII 2Hz v0301 files. Further in...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>tii_quality_vixv</td>\n",
       "      <td>Quality flag for Vixv data (along-track compon...</td>\n",
       "      <td>int</td>\n",
       "      <td>[]</td>\n",
       "      <td>True</td>\n",
       "      <td>Retrieved from TII 2Hz v0301 files. Further in...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>9</th>\n",
       "      <td>tii_quality_viy</td>\n",
       "      <td>Quality flag for Viy data (to the right, obser...</td>\n",
       "      <td>int</td>\n",
       "      <td>[]</td>\n",
       "      <td>True</td>\n",
       "      <td>Retrieved from TII 2Hz v0301 files. Further in...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>10</th>\n",
       "      <td>tii_quality_viz</td>\n",
       "      <td>Quality flag for Viz data (downward)</td>\n",
       "      <td>int</td>\n",
       "      <td>[]</td>\n",
       "      <td>True</td>\n",
       "      <td>Retrieved from TII 2Hz v0301 files. Further in...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "             field_name                                        description  \\\n",
       "0        nbtrace_region  Region based on where the magnetic field line ...   \n",
       "1        sbtrace_region  Region based on where the magnetic field line ...   \n",
       "2       radial_distance    Distance spacecraft is from Earth in kilometers   \n",
       "3     spacecraft_region  Region based on the spacecraft's position with...   \n",
       "4   radial_trace_region  Region based on the location on the Earth's su...   \n",
       "5                 state  Data is based on predictive or definitive info...   \n",
       "6                tii_on  Indicates that the TII instrument was operatio...   \n",
       "7      tii_quality_vixh  Quality flag for Vixh data (along-track compon...   \n",
       "8      tii_quality_vixv  Quality flag for Vixv data (along-track compon...   \n",
       "9       tii_quality_viy  Quality flag for Viy data (to the right, obser...   \n",
       "10      tii_quality_viz               Quality flag for Viz data (downward)   \n",
       "\n",
       "   data_type                                     allowed_values  searchable  \\\n",
       "0     string  [north polar cap, north cusp, north cleft, nor...        True   \n",
       "1     string  [south polar cap, south cusp, south cleft, sou...        True   \n",
       "2     double                                                 []        True   \n",
       "3     string  [interplanetary medium, dayside magnetosheath,...        True   \n",
       "4     string  [north polar cap, south polar cap, north cusp,...        True   \n",
       "5     string                           [predictive, definitive]        True   \n",
       "6       bool                                      [true, false]        True   \n",
       "7        int                                                 []        True   \n",
       "8        int                                                 []        True   \n",
       "9        int                                                 []        True   \n",
       "10       int                                                 []        True   \n",
       "\n",
       "                               additional_description  \n",
       "0                                                 NaN  \n",
       "1                                                 NaN  \n",
       "2                                                 NaN  \n",
       "3   A spacecraft can occupy only one region of thi...  \n",
       "4                                                 NaN  \n",
       "5                                                 NaN  \n",
       "6   Retrieved from TII 2Hz v0301 files. Further in...  \n",
       "7   Retrieved from TII 2Hz v0301 files. Further in...  \n",
       "8   Retrieved from TII 2Hz v0301 files. Further in...  \n",
       "9   Retrieved from TII 2Hz v0301 files. Further in...  \n",
       "10  Retrieved from TII 2Hz v0301 files. Further in...  "
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# as a pandas dataframe\n",
    "df = pd.DataFrame(schema)\n",
    "df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[{'allowed_values': ['north polar cap',\n",
      "                     'north cusp',\n",
      "                     'north cleft',\n",
      "                     'north auroral oval',\n",
      "                     'north mid-latitude',\n",
      "                     'low latitude'],\n",
      "  'data_type': 'string',\n",
      "  'description': 'Region based on where the magnetic field line that passes '\n",
      "                 \"through the spacecraft intersects the Earth's surface in the \"\n",
      "                 \"Earth's northern magnetic hemisphere\",\n",
      "  'field_name': 'nbtrace_region',\n",
      "  'searchable': True},\n",
      " {'allowed_values': ['south polar cap',\n",
      "                     'south cusp',\n",
      "                     'south cleft',\n",
      "                     'south auroral oval',\n",
      "                     'south mid-latitude',\n",
      "                     'low latitude'],\n",
      "  'data_type': 'string',\n",
      "  'description': 'Region based on where the magnetic field line that passes '\n",
      "                 \"through the spacecraft intersects the Earth's surface in the \"\n",
      "                 \"Earth's southern magnetic hemisphere\",\n",
      "  'field_name': 'sbtrace_region',\n",
      "  'searchable': True},\n",
      " {'allowed_values': [],\n",
      "  'data_type': 'double',\n",
      "  'description': 'Distance spacecraft is from Earth in kilometers',\n",
      "  'field_name': 'radial_distance',\n",
      "  'searchable': True},\n",
      " {'additional_description': 'A spacecraft can occupy only one region of this '\n",
      "                            'region type at any given time. The North and '\n",
      "                            'South Mid-Latitude regions are defined as the two '\n",
      "                            'bands about the Earth that extend from +30 '\n",
      "                            'degrees latitude to the North Auroral Oval, and '\n",
      "                            '-30 degrees latitude to the South Auroral Oval. '\n",
      "                            'The Low-Latitude is the band that extends from '\n",
      "                            '+30 degrees latitude to -30 degrees latitude.',\n",
      "  'allowed_values': ['interplanetary medium',\n",
      "                     'dayside magnetosheath',\n",
      "                     'nightside magnetosheath',\n",
      "                     'dayside magnetosphere',\n",
      "                     'nightside magnetosphere',\n",
      "                     'dayside plasmasphere',\n",
      "                     'nightside plasmasphere',\n",
      "                     'plasma sheet',\n",
      "                     'tail lobe',\n",
      "                     'low latitude boundary layer',\n",
      "                     'high latitude boundary layer'],\n",
      "  'data_type': 'string',\n",
      "  'description': \"Region based on the spacecraft's position within the \"\n",
      "                 'magnetosphere',\n",
      "  'field_name': 'spacecraft_region',\n",
      "  'searchable': True},\n",
      " {'allowed_values': ['north polar cap',\n",
      "                     'south polar cap',\n",
      "                     'north cusp',\n",
      "                     'south cusp',\n",
      "                     'north cleft',\n",
      "                     'south cleft',\n",
      "                     'north auroral oval',\n",
      "                     'south auroral oval',\n",
      "                     'north mid-latitude',\n",
      "                     'south mid-latitude',\n",
      "                     'low latitude'],\n",
      "  'data_type': 'string',\n",
      "  'description': \"Region based on the location on the Earth's surface where a \"\n",
      "                 'straight line would intersect when connecting the spacecraft '\n",
      "                 \"and the Earth's center\",\n",
      "  'field_name': 'radial_trace_region',\n",
      "  'searchable': True},\n",
      " {'allowed_values': ['predictive', 'definitive'],\n",
      "  'data_type': 'string',\n",
      "  'description': 'Data is based on predictive or definitive information',\n",
      "  'field_name': 'state',\n",
      "  'searchable': True},\n",
      " {'additional_description': 'Retrieved from TII 2Hz v0301 files. Further '\n",
      "                            'information and documentation found at '\n",
      "                            'http://efi.phys.ucalgary.ca/tii-cross-track-ion-flow-dataset-0301-released/',\n",
      "  'allowed_values': ['true', 'false'],\n",
      "  'data_type': 'bool',\n",
      "  'description': 'Indicates that the TII instrument was operational at this '\n",
      "                 'time.',\n",
      "  'field_name': 'tii_on',\n",
      "  'searchable': True},\n",
      " {'additional_description': 'Retrieved from TII 2Hz v0301 files. Further '\n",
      "                            'information and documentation found at '\n",
      "                            'http://efi.phys.ucalgary.ca/tii-cross-track-ion-flow-dataset-0301-released/',\n",
      "  'allowed_values': [],\n",
      "  'data_type': 'int',\n",
      "  'description': 'Quality flag for Vixh data (along-track component from the '\n",
      "                 'horizontal sensor)',\n",
      "  'field_name': 'tii_quality_vixh',\n",
      "  'searchable': True},\n",
      " {'additional_description': 'Retrieved from TII 2Hz v0301 files. Further '\n",
      "                            'information and documentation found at '\n",
      "                            'http://efi.phys.ucalgary.ca/tii-cross-track-ion-flow-dataset-0301-released/',\n",
      "  'allowed_values': [],\n",
      "  'data_type': 'int',\n",
      "  'description': 'Quality flag for Vixv data (along-track component from the '\n",
      "                 'vertical sensor)',\n",
      "  'field_name': 'tii_quality_vixv',\n",
      "  'searchable': True},\n",
      " {'additional_description': 'Retrieved from TII 2Hz v0301 files. Further '\n",
      "                            'information and documentation found at '\n",
      "                            'http://efi.phys.ucalgary.ca/tii-cross-track-ion-flow-dataset-0301-released/',\n",
      "  'allowed_values': [],\n",
      "  'data_type': 'int',\n",
      "  'description': 'Quality flag for Viy data (to the right, observer facing '\n",
      "                 'forward)',\n",
      "  'field_name': 'tii_quality_viy',\n",
      "  'searchable': True},\n",
      " {'additional_description': 'Retrieved from TII 2Hz v0301 files. Further '\n",
      "                            'information and documentation found at '\n",
      "                            'http://efi.phys.ucalgary.ca/tii-cross-track-ion-flow-dataset-0301-released/',\n",
      "  'allowed_values': [],\n",
      "  'data_type': 'int',\n",
      "  'description': 'Quality flag for Viz data (downward)',\n",
      "  'field_name': 'tii_quality_viz',\n",
      "  'searchable': True}]\n"
     ]
    }
   ],
   "source": [
    "# as the raw data returned\n",
    "pprint.pprint(schema)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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",
   "version": "3.8.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}