examples/00_Basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Basic functionality of octant package"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import the necessary modules"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "from octant.core import TrackRun, OctantTrack, HOUR"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Define the common data directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "sample_dir = Path(\".\") / \"sample_data\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Data are usually organised in hierarchical directory structure. Here, the relevant parameters are defined."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset = \"era5\"\n",
    "period = \"test\"\n",
    "run_id = 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Construct the full path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "track_res_dir = sample_dir / dataset / f\"run{run_id:03d}\" / period"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load the data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The standard loading procedure is done during the initialisation of `TrackRun` by reading text files (output from PMCTRACK) from the given directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "tr = TrackRun(track_res_dir)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<octant.core.TrackRun>\n",
      "[671 tracks]\n",
      "\n",
      "Data columns:\n",
      "lon | lat | vo | time | area | vortex_type\n",
      "\n",
      "Sources:\n",
      "sample_data/era5/run000/test\n"
     ]
    }
   ],
   "source": [
    "print(tr)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `TrackRun` object also has an HTML view available in Jupyter Notebooks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<style>\n",
       "  table.octant {\n",
       "      white-space: pre;\n",
       "      border: 1px solid;\n",
       "      border-color: #f9f9ef;\n",
       "      font-family: monaco, monospace;\n",
       "  }\n",
       "  th.octant {\n",
       "      background: #084469;\n",
       "      color: #fefefe;\n",
       "      border-left: 1px solid;\n",
       "      border-color: #0a507a;\n",
       "      font-size: 1.05em;\n",
       "      min-width: 50px;\n",
       "      max-width: 125px;\n",
       "  }\n",
       "  .octant-la {\n",
       "      text-align: left !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "  .octant-ra {\n",
       "      text-align: right !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "</style>\n",
       "<table class=\"octant\" id=\"140661218006688\">\n",
       "    <tr class=\"octant\">\n",
       "<th class=\"octant octant-la\" colspan=\"7\">Cyclone tracking results</th>\n",
       "</tr>\n",
       "    <tr class=\"octant\">\n",
       "<td class=\"octant octant-la\">Number of tracks</td>\n",
       "<td class=\"octant octant-la\" colspan=\"6\">671</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">Data columns</td>\n",
       "<td class=\"octant octant-la\" colspan=\"6\">lon, lat, vo, time, area, vortex_type</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\"                rowspan=\"2\">Sources</td>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-la\"                             colspan=\"6\">sample_data/era5/run000/test</td>\n",
       "</tr>\n",
       "</tr>\n",
       "</table>\n",
       "        "
      ],
      "text/plain": [
       "<octant.core.TrackRun> [671 tracks]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "octant.core.TrackRun"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(tr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "671"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "len(tr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "671"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.size()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.0"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.tstep_h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Main data container"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The main attribute of `TrackRun` is `.data`, which has all the tracks stored in one DataFrame-like object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "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></th>\n",
       "      <th>lon</th>\n",
       "      <th>lat</th>\n",
       "      <th>vo</th>\n",
       "      <th>time</th>\n",
       "      <th>area</th>\n",
       "      <th>vortex_type</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>track_idx</th>\n",
       "      <th>row_idx</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">0</th>\n",
       "      <th>0</th>\n",
       "      <td>9.3</td>\n",
       "      <td>79.2</td>\n",
       "      <td>0.000345</td>\n",
       "      <td>2011-01-01 00:00:00</td>\n",
       "      <td>10617.93652</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>9.3</td>\n",
       "      <td>79.2</td>\n",
       "      <td>0.000352</td>\n",
       "      <td>2011-01-01 01:00:00</td>\n",
       "      <td>10154.14648</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>9.3</td>\n",
       "      <td>79.2</td>\n",
       "      <td>0.000362</td>\n",
       "      <td>2011-01-01 02:00:00</td>\n",
       "      <td>10136.94629</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"2\" valign=\"top\">1</th>\n",
       "      <th>0</th>\n",
       "      <td>20.4</td>\n",
       "      <td>70.5</td>\n",
       "      <td>0.000317</td>\n",
       "      <td>2011-01-01 00:00:00</td>\n",
       "      <td>34750.66016</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>20.7</td>\n",
       "      <td>70.5</td>\n",
       "      <td>0.000310</td>\n",
       "      <td>2011-01-01 01:00:00</td>\n",
       "      <td>36727.84375</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                    lon   lat        vo                time         area  \\\n",
       "track_idx row_idx                                                          \n",
       "0         0         9.3  79.2  0.000345 2011-01-01 00:00:00  10617.93652   \n",
       "          1         9.3  79.2  0.000352 2011-01-01 01:00:00  10154.14648   \n",
       "          2         9.3  79.2  0.000362 2011-01-01 02:00:00  10136.94629   \n",
       "1         0        20.4  70.5  0.000317 2011-01-01 00:00:00  34750.66016   \n",
       "          1        20.7  70.5  0.000310 2011-01-01 01:00:00  36727.84375   \n",
       "\n",
       "                   vortex_type  \n",
       "track_idx row_idx               \n",
       "0         0                  0  \n",
       "          1                  0  \n",
       "          2                  0  \n",
       "1         0                  1  \n",
       "          1                  1  "
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.data.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It always has `track_idx` level in order to index through individual tracks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tracking run configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If a `.conf` file is present in the same directory, it is loaded to `TrackRun`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<style>\n",
       "  table.octant {\n",
       "      white-space: pre;\n",
       "      border: 1px solid;\n",
       "      border-color: #f9f9ef;\n",
       "      font-family: monaco, monospace;\n",
       "  }\n",
       "  th.octant {\n",
       "      background: #084469;\n",
       "      color: #fefefe;\n",
       "      border-left: 1px solid;\n",
       "      border-color: #0a507a;\n",
       "      font-size: 1.05em;\n",
       "      min-width: 50px;\n",
       "      max-width: 125px;\n",
       "  }\n",
       "  .octant-la {\n",
       "      text-align: left !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "  .octant-ra {\n",
       "      text-align: right !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "</style>\n",
       "<table class=\"octant\" id=\"140661923723696\">\n",
       "    <tr class=\"octant octant-la\">\n",
       "<th class=\"octant\" colspan=\"2\">Tracking algorithm settings (43)</th>\n",
       "</tr>\n",
       "    <tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">dt_start =</td><td class=\"octant octant-la\">201101010000</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">dt_end =</td><td class=\"octant octant-la\">201101312300</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">vor_lvl =</td><td class=\"octant octant-la\">950</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">steer_lvl_btm =</td><td class=\"octant octant-la\">1000</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">steer_lvl_top =</td><td class=\"octant octant-la\">700</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">datadir =</td><td class=\"octant octant-la\">../../reanalysis/era5</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">outdir =</td><td class=\"octant octant-la\">../results/test7</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">vort_name =</td><td class=\"octant octant-la\">vo</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">u_name =</td><td class=\"octant octant-la\">u</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">v_name =</td><td class=\"octant octant-la\">v</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">psea_name =</td><td class=\"octant octant-la\">msl</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">land_name =</td><td class=\"octant octant-la\">lsm</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">prefix_lvl =</td><td class=\"octant octant-la\">era5.an.pl.</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">prefix_sfc =</td><td class=\"octant octant-la\">era5.an.sfc.</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">proj =</td><td class=\"octant octant-la\">1</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">vert_grid =</td><td class=\"octant octant-la\">1</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">lon1 =</td><td class=\"octant octant-la\">-20</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">lon2 =</td><td class=\"octant octant-la\">50</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">lat1 =</td><td class=\"octant octant-la\">65</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">lat2 =</td><td class=\"octant octant-la\">85</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">halo_r =</td><td class=\"octant octant-la\">30.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">smth_type =</td><td class=\"octant octant-la\">0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">nsmth_x =</td><td class=\"octant octant-la\">10</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">nsmth_y =</td><td class=\"octant octant-la\">10</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">r_smth =</td><td class=\"octant octant-la\">60.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">zeta_max0 =</td><td class=\"octant octant-la\">0.0002</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">zeta_min0 =</td><td class=\"octant octant-la\">0.00015</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">int_zeta_min0 =</td><td class=\"octant octant-la\">2e-06</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">gamma =</td><td class=\"octant octant-la\">0.25</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">d_cf_min =</td><td class=\"octant octant-la\">400.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">size_synop =</td><td class=\"octant octant-la\">90000.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">distance_ec =</td><td class=\"octant octant-la\">300.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">del_psea_min =</td><td class=\"octant octant-la\">0.5</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">steering_type =</td><td class=\"octant octant-la\">2</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">n_steering_x =</td><td class=\"octant octant-la\">20</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">n_steering_y =</td><td class=\"octant octant-la\">20</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">r_steering =</td><td class=\"octant octant-la\">200.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">track_type =</td><td class=\"octant octant-la\">2</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">del_lon =</td><td class=\"octant octant-la\">1.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">del_lat =</td><td class=\"octant octant-la\">0.8</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">del_r =</td><td class=\"octant octant-la\">120.0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">merge_opt =</td><td class=\"octant octant-la\">2</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">vor_out_on =</td><td class=\"octant octant-la\">0</td>\n",
       "</tr>\n",
       "</table>\n",
       "        "
      ],
      "text/plain": [
       "Tracking algorithm settings (43)"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.conf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other methods of initialisation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`TrackRun` class can be initialised empty:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "tr_empty = TrackRun()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<style>\n",
       "  table.octant {\n",
       "      white-space: pre;\n",
       "      border: 1px solid;\n",
       "      border-color: #f9f9ef;\n",
       "      font-family: monaco, monospace;\n",
       "  }\n",
       "  th.octant {\n",
       "      background: #084469;\n",
       "      color: #fefefe;\n",
       "      border-left: 1px solid;\n",
       "      border-color: #0a507a;\n",
       "      font-size: 1.05em;\n",
       "      min-width: 50px;\n",
       "      max-width: 125px;\n",
       "  }\n",
       "  .octant-la {\n",
       "      text-align: left !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "  .octant-ra {\n",
       "      text-align: right !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "</style>\n",
       "<table class=\"octant\" id=\"140661217000528\">\n",
       "    <tr class=\"octant\">\n",
       "<th class=\"octant octant-la\" colspan=\"7\">Cyclone tracking results</th>\n",
       "</tr>\n",
       "    <tr class=\"octant\">\n",
       "<td class=\"octant octant-la\">Number of tracks</td>\n",
       "<td class=\"octant octant-la\" colspan=\"6\">0</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">Data columns</td>\n",
       "<td class=\"octant octant-la\" colspan=\"6\">lon, lat, vo, time, area, vortex_type</td>\n",
       "</tr>\n",
       "</table>\n",
       "        "
      ],
      "text/plain": [
       "<octant.core.TrackRun> [0 tracks]"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr_empty"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Concatenate data from several directories"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "TR = TrackRun(one_directory)\n",
    "TR2 = TrackRun(another_directory)\n",
    "TR.extend(TR2)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```python\n",
    "TR += TrackRun(another_directory)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Some attributes of TrackRun"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`TrackRun` object has a few useful properties"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* for example, it is possible to access the list of files that the data were loaded from. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[PosixPath('sample_data/era5/run000/test/vortrack_0001_0001.txt'),\n",
       " PosixPath('sample_data/era5/run000/test/vortrack_0002_0001.txt'),\n",
       " PosixPath('sample_data/era5/run000/test/vortrack_0003_0001.txt'),\n",
       " PosixPath('sample_data/era5/run000/test/vortrack_0004_0001.txt'),\n",
       " PosixPath('sample_data/era5/run000/test/vortrack_0005_0001.txt')]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.filelist[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* there is a shortcut to group tracks by their index"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<pandas.core.groupby.generic.DataFrameGroupBy object at 0x7fee3dd9f390>"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.gb"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is equivalent of doing `tr.data.groupby(\"track_idx\")`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Track with index=0\n",
      "                   lon   lat        vo                time         area  \\\n",
      "track_idx row_idx                                                         \n",
      "0         0        9.3  79.2  0.000345 2011-01-01 00:00:00  10617.93652   \n",
      "          1        9.3  79.2  0.000352 2011-01-01 01:00:00  10154.14648   \n",
      "          2        9.3  79.2  0.000362 2011-01-01 02:00:00  10136.94629   \n",
      "\n",
      "                   vortex_type  \n",
      "track_idx row_idx               \n",
      "0         0                  0  \n",
      "          1                  0  \n",
      "          2                  0  \n"
     ]
    }
   ],
   "source": [
    "for idx, a_track in tr.gb:\n",
    "    print(f\"Track with index={idx}\")\n",
    "    print(a_track)\n",
    "    break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* current `TrackRun` is not categorised yet (see \"Categorisation\" examples), so this attribute is empty:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tr.cat_labels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Serialising TrackRun"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`TrackRun` and all its metadata can be saved to and loaded from an HDF file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "tr.to_archive(\"test.h5\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_tr = TrackRun.from_archive(\"test.h5\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<style>\n",
       "  table.octant {\n",
       "      white-space: pre;\n",
       "      border: 1px solid;\n",
       "      border-color: #f9f9ef;\n",
       "      font-family: monaco, monospace;\n",
       "  }\n",
       "  th.octant {\n",
       "      background: #084469;\n",
       "      color: #fefefe;\n",
       "      border-left: 1px solid;\n",
       "      border-color: #0a507a;\n",
       "      font-size: 1.05em;\n",
       "      min-width: 50px;\n",
       "      max-width: 125px;\n",
       "  }\n",
       "  .octant-la {\n",
       "      text-align: left !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "  .octant-ra {\n",
       "      text-align: right !important;\n",
       "      white-space: pre;\n",
       "  }\n",
       "</style>\n",
       "<table class=\"octant\" id=\"140661217001144\">\n",
       "    <tr class=\"octant\">\n",
       "<th class=\"octant octant-la\" colspan=\"7\">Cyclone tracking results</th>\n",
       "</tr>\n",
       "    <tr class=\"octant\">\n",
       "<td class=\"octant octant-la\">Number of tracks</td>\n",
       "<td class=\"octant octant-la\" colspan=\"6\">671</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\">Data columns</td>\n",
       "<td class=\"octant octant-la\" colspan=\"6\">lon, lat, vo, time, area, vortex_type</td>\n",
       "</tr>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-ra\"                rowspan=\"2\">Sources</td>\n",
       "<tr class=\"octant\">\n",
       "<td class=\"octant octant-la\"                             colspan=\"6\">sample_data/era5/run000/test</td>\n",
       "</tr>\n",
       "</tr>\n",
       "</table>\n",
       "        "
      ],
      "text/plain": [
       "<octant.core.TrackRun> [671 tracks]"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_tr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Units of TrackRun"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each cyclone track stored in lists of `TrackRun` class as a `OctantTrack` instance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [],
   "source": [
    "ot = random.choice([*tr[:].gb])[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is essentially a sub-class of pandas.DataFrame"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "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></th>\n",
       "      <th>lon</th>\n",
       "      <th>lat</th>\n",
       "      <th>vo</th>\n",
       "      <th>time</th>\n",
       "      <th>area</th>\n",
       "      <th>vortex_type</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>track_idx</th>\n",
       "      <th>row_idx</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"4\" valign=\"top\">124</th>\n",
       "      <th>0</th>\n",
       "      <td>12.3</td>\n",
       "      <td>72.0</td>\n",
       "      <td>0.000423</td>\n",
       "      <td>2011-01-05 23:00:00</td>\n",
       "      <td>7615.17285</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>10.8</td>\n",
       "      <td>72.0</td>\n",
       "      <td>0.000393</td>\n",
       "      <td>2011-01-06 00:00:00</td>\n",
       "      <td>19943.68750</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>8.7</td>\n",
       "      <td>72.0</td>\n",
       "      <td>0.000349</td>\n",
       "      <td>2011-01-06 01:00:00</td>\n",
       "      <td>18887.55273</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>-3.6</td>\n",
       "      <td>67.2</td>\n",
       "      <td>0.000666</td>\n",
       "      <td>2011-01-06 02:00:00</td>\n",
       "      <td>95968.20312</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                    lon   lat        vo                time         area  \\\n",
       "track_idx row_idx                                                          \n",
       "124       0        12.3  72.0  0.000423 2011-01-05 23:00:00   7615.17285   \n",
       "          1        10.8  72.0  0.000393 2011-01-06 00:00:00  19943.68750   \n",
       "          2         8.7  72.0  0.000349 2011-01-06 01:00:00  18887.55273   \n",
       "          3        -3.6  67.2  0.000666 2011-01-06 02:00:00  95968.20312   \n",
       "\n",
       "                   vortex_type  \n",
       "track_idx row_idx               \n",
       "124       0                  1  \n",
       "          1                  1  \n",
       "          2                  1  \n",
       "          3                  3  "
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "octant.parts.OctantTrack"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(ot)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It has a few useful properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3.0"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot.lifetime_h"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "836.7043121073503"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot.total_dist_km"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "including maximum vorticity in $ s^{-1}$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.00066578"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot.max_vort"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "810.8722660749592"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot.gen_lys_dist_km"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "278.90143736911676"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot.average_speed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[12.3, 72. ],\n",
       "       [10.8, 72. ],\n",
       "       [ 8.7, 72. ],\n",
       "       [-3.6, 67.2]])"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ot.lonlat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running octant with a progress bar"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Having either the `fastprogress` or `tqdm` module installed allows for running some methods with a bar that shows progress. To enable it, set the attribute of `RUNTIME` variable to `True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "import octant\n",
    "octant.RUNTIME.enable_progress_bar = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "conditions = [\n",
    "    (\"long_lived\", [lambda ot: ot.lifetime_h >= 6]),\n",
    "    (\n",
    "        \"far_travelled_and_very_long_lived\",\n",
    "        [lambda ot: ot.lifetime_h >= 36, lambda ot: ot.gen_lys_dist_km > 300.0],\n",
    "    ),\n",
    "    (\"strong\", [lambda x: x.max_vort > 1e-3]),\n",
    "]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "    <div>\n",
       "        <style>\n",
       "            /* Turns off some styling */\n",
       "            progress {\n",
       "                /* gets rid of default border in Firefox and Opera. */\n",
       "                border: none;\n",
       "                /* Needs to be in here for Safari polyfill so background images work as expected. */\n",
       "                background-size: auto;\n",
       "            }\n",
       "            .progress-bar-interrupted, .progress-bar-interrupted::-webkit-progress-bar {\n",
       "                background: #F44336;\n",
       "            }\n",
       "        </style>\n",
       "      <progress value='671' class='' max='671', style='width:300px; height:20px; vertical-align: middle;'></progress>\n",
       "      100.00% [671/671 00:02<00:00]\n",
       "    </div>\n",
       "    "
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "tr.classify(conditions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More `classify()` [examples](01_Categorisation.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## octant's utilities"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "from octant.utils import great_circle"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "222826.50759451024"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "great_circle(lon1=9.6, lon2=10.2, lat1=76.9, lat2=78.9)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:test_env]",
   "language": "python",
   "name": "conda-env-test_env-py"
  },
  "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": 4
}