docs/user_guide/tutorial.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial\n",
    "\n",
    "## Preprocessing of daily observations\n",
    "\n",
    "First, we need to obtain some daily weather observations that we will use to detect heat wave events.\n",
    "\n",
    "We will use a [CSV file](https://data.climpact.gr/dataset/e2ae9f71-048f-4565-b24b-f8f15e4c2cf5/resource/6994e5a9-a5b2-457d-9a60-f47462d13824/download/hcd_noa_4.csv)\n",
    "with daily historical climatic data (1901 - 2020) from the [Thissio station](https://data.climpact.gr/dataset/2f5bbe2a-7e27-40e7-9ff6-1dcc08c507fa)\n",
    "(Athens, Greece) of the National Observatory of Athens ([Founda, 2011](https://doi.org/10.1080/17512549.2011.582338), [Founda et al., 2013](https://doi.org/10.1002/asl2.419)).\n",
    "The dataset is puclic under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After downloading our file, we should inspect its data and preprocess it so that\n",
    "it can be used with hotspell."
   ]
  },
  {
   "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>YEAR</th>\n",
       "      <th>MONTH</th>\n",
       "      <th>DAY</th>\n",
       "      <th>T (oC)</th>\n",
       "      <th>Tmax (oC)</th>\n",
       "      <th>Tmin (oC)</th>\n",
       "      <th>RH (%)</th>\n",
       "      <th>Precipitation (mm)</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>12.8</td>\n",
       "      <td>14.3</td>\n",
       "      <td>5.9</td>\n",
       "      <td>67.0</td>\n",
       "      <td>0.2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>2</td>\n",
       "      <td>10.5</td>\n",
       "      <td>15.0</td>\n",
       "      <td>8.9</td>\n",
       "      <td>80.0</td>\n",
       "      <td>5.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>6.5</td>\n",
       "      <td>10.3</td>\n",
       "      <td>4.8</td>\n",
       "      <td>76.0</td>\n",
       "      <td>5.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>4</td>\n",
       "      <td>6.0</td>\n",
       "      <td>7.1</td>\n",
       "      <td>4.8</td>\n",
       "      <td>78.0</td>\n",
       "      <td>3.2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>5</td>\n",
       "      <td>7.3</td>\n",
       "      <td>10.4</td>\n",
       "      <td>5.2</td>\n",
       "      <td>83.0</td>\n",
       "      <td>6.6</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   YEAR  MONTH  DAY  T (oC)  Tmax (oC)  Tmin (oC)  RH (%)  Precipitation (mm)\n",
       "0  1901      1    1    12.8       14.3        5.9    67.0                 0.2\n",
       "1  1901      1    2    10.5       15.0        8.9    80.0                 5.8\n",
       "2  1901      1    3     6.5       10.3        4.8    76.0                 5.0\n",
       "3  1901      1    4     6.0        7.1        4.8    78.0                 3.2\n",
       "4  1901      1    5     7.3       10.4        5.2    83.0                 6.6"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "\n",
    "raw_data = \"hcd_noa_4.csv\"  # Replace with your path\n",
    "\n",
    "df = pd.read_csv(raw_data)\n",
    "df.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, the dataset includes 7 columns. \n",
    "\n",
    "The first 3 columns correspond to the year, month and day of the observations,\n",
    "columns 4 and 5 to the daily maximum (Tmax) and daily minimum (Tmin) air\n",
    "temperature (in °C), column 6 to to relative humidity (RH, expressed as percent)\n",
    "and the last column to precipitation (Rain, in mm).\n",
    "\n",
    "We need to drop humidity and rain and rearrange Tmax and Tmin:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "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>YEAR</th>\n",
       "      <th>MONTH</th>\n",
       "      <th>DAY</th>\n",
       "      <th>Tmin (oC)</th>\n",
       "      <th>Tmax (oC)</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>1</td>\n",
       "      <td>5.9</td>\n",
       "      <td>14.3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>2</td>\n",
       "      <td>8.9</td>\n",
       "      <td>15.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>4.8</td>\n",
       "      <td>10.3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>4</td>\n",
       "      <td>4.8</td>\n",
       "      <td>7.1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>1901</td>\n",
       "      <td>1</td>\n",
       "      <td>5</td>\n",
       "      <td>5.2</td>\n",
       "      <td>10.4</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   YEAR  MONTH  DAY  Tmin (oC)  Tmax (oC)\n",
       "0  1901      1    1        5.9       14.3\n",
       "1  1901      1    2        8.9       15.0\n",
       "2  1901      1    3        4.8       10.3\n",
       "3  1901      1    4        4.8        7.1\n",
       "4  1901      1    5        5.2       10.4"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = df[[\"YEAR\", \"MONTH\", \"DAY\", \"Tmin (oC)\", \"Tmax (oC)\"]]\n",
    "df.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Suppose that there are nodata values included in the timeseries which have been set as -9999.\n",
    "\n",
    "We should delete these measurements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "nodata_value = -9999\n",
    "df = df.loc[\n",
    "    (df[\"Tmin (oC)\"] != nodata_value ) & (df[\"Tmax (oC)\"] != nodata_value)\n",
    "]"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we are ready to save our processed file; we must not write out the header\n",
    "and the index of the DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "processed_data = \"hcd_noa_4_processed.csv\"  # Replace with your path\n",
    "\n",
    "df.to_csv(processed_data, header=False, index=False)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Detect heat waves\n",
    "\n",
    "We have finished the preprocessing of our data and we are now ready to use hotspell.\n",
    "\n",
    "### Create a heat index\n",
    "First we must initialize the heat wave index we want to use.\n",
    "For this first example we are going to use the index [CTX90PCT](https://doi.org/10.1175/JCLI-D-12-00383.1). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hotspell\n",
    "\n",
    "index_name = \"ctx90pct\"\n",
    "ctx90pct = hotspell.index(name=index_name)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This index uses as a threshold the calendar day 90th percentile value of the\n",
    "maximum temperature based on a 15-day moving window. A heat wave occurs when\n",
    "the threshold is exceeded for at least 3 consecutive days.\n",
    "\n",
    "For the complete list of the available heat wave indices to use see [here](./heatwave_indices.rst)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Find heat wave events and compute annual metrics\n",
    "\n",
    "Using our heat wave index and the output CSV from the first part of the tutorial\n",
    "we will find the heat wave events for the Thissio station."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "hw = hotspell.get_heatwaves(filename=processed_data, hw_index=ctx90pct)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above we used the default arguments for the parameters of get_heatwaves:\n",
    "\n",
    "- the base period, used to calculate the percentile values, was 1961 to 1990\n",
    "- we limited our interest only to months June to August\n",
    "- we chose to compute the annual metrics and to export our results in csv files\n",
    "\n",
    "For a list of available choises see the documentation for [hotspell.get_heatwaves](../hotspell.heatwaves.rst#hotspell.heatwaves.get_heatwaves)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's examine our results.\n",
    "\n",
    "The `hw.events` attribute is a DataFrame that contains the dates of detected heat wave events, as well as their basic characteristics (duration and temperature statistics)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "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>begin_date</th>\n",
       "      <th>end_date</th>\n",
       "      <th>duration</th>\n",
       "      <th>avg_tmax</th>\n",
       "      <th>std_tmax</th>\n",
       "      <th>max_tmax</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>index</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>1901-08-01</th>\n",
       "      <td>1901-08-01</td>\n",
       "      <td>1901-08-03</td>\n",
       "      <td>3</td>\n",
       "      <td>37.9</td>\n",
       "      <td>0.8</td>\n",
       "      <td>38.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1902-07-22</th>\n",
       "      <td>1902-07-22</td>\n",
       "      <td>1902-07-24</td>\n",
       "      <td>3</td>\n",
       "      <td>38.2</td>\n",
       "      <td>1.8</td>\n",
       "      <td>40.3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1903-08-14</th>\n",
       "      <td>1903-08-14</td>\n",
       "      <td>1903-08-16</td>\n",
       "      <td>3</td>\n",
       "      <td>36.0</td>\n",
       "      <td>0.2</td>\n",
       "      <td>36.2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1904-08-09</th>\n",
       "      <td>1904-08-09</td>\n",
       "      <td>1904-08-12</td>\n",
       "      <td>4</td>\n",
       "      <td>36.5</td>\n",
       "      <td>0.3</td>\n",
       "      <td>36.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1905-08-26</th>\n",
       "      <td>1905-08-26</td>\n",
       "      <td>1905-09-01</td>\n",
       "      <td>7</td>\n",
       "      <td>36.4</td>\n",
       "      <td>0.9</td>\n",
       "      <td>38.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           begin_date   end_date  duration  avg_tmax  std_tmax  max_tmax\n",
       "index                                                                   \n",
       "1901-08-01 1901-08-01 1901-08-03         3      37.9       0.8      38.8\n",
       "1902-07-22 1902-07-22 1902-07-24         3      38.2       1.8      40.3\n",
       "1903-08-14 1903-08-14 1903-08-16         3      36.0       0.2      36.2\n",
       "1904-08-09 1904-08-09 1904-08-12         4      36.5       0.3      36.8\n",
       "1905-08-26 1905-08-26 1905-09-01         7      36.4       0.9      38.0"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hw.events.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "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>duration</th>\n",
       "      <th>avg_tmax</th>\n",
       "      <th>std_tmax</th>\n",
       "      <th>max_tmax</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>count</th>\n",
       "      <td>205.000000</td>\n",
       "      <td>205.000000</td>\n",
       "      <td>205.000000</td>\n",
       "      <td>205.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>mean</th>\n",
       "      <td>4.804878</td>\n",
       "      <td>36.794634</td>\n",
       "      <td>1.122439</td>\n",
       "      <td>38.210244</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>std</th>\n",
       "      <td>2.255924</td>\n",
       "      <td>1.494867</td>\n",
       "      <td>0.627775</td>\n",
       "      <td>2.021464</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>min</th>\n",
       "      <td>3.000000</td>\n",
       "      <td>32.500000</td>\n",
       "      <td>0.100000</td>\n",
       "      <td>32.800000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>25%</th>\n",
       "      <td>3.000000</td>\n",
       "      <td>36.000000</td>\n",
       "      <td>0.700000</td>\n",
       "      <td>36.900000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>50%</th>\n",
       "      <td>4.000000</td>\n",
       "      <td>37.000000</td>\n",
       "      <td>1.000000</td>\n",
       "      <td>38.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>75%</th>\n",
       "      <td>6.000000</td>\n",
       "      <td>37.600000</td>\n",
       "      <td>1.400000</td>\n",
       "      <td>39.300000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>max</th>\n",
       "      <td>13.000000</td>\n",
       "      <td>41.000000</td>\n",
       "      <td>3.600000</td>\n",
       "      <td>44.800000</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         duration    avg_tmax    std_tmax    max_tmax\n",
       "count  205.000000  205.000000  205.000000  205.000000\n",
       "mean     4.804878   36.794634    1.122439   38.210244\n",
       "std      2.255924    1.494867    0.627775    2.021464\n",
       "min      3.000000   32.500000    0.100000   32.800000\n",
       "25%      3.000000   36.000000    0.700000   36.900000\n",
       "50%      4.000000   37.000000    1.000000   38.000000\n",
       "75%      6.000000   37.600000    1.400000   39.300000\n",
       "max     13.000000   41.000000    3.600000   44.800000"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hw.events[[\"duration\", \"avg_tmax\", \"std_tmax\", \"max_tmax\"]].describe()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "From the above we see that the CTX90PCT index resulted in 205 heat wave events\n",
    "between 1901 and 2020, with an average duration of nearly 5 days and an\n",
    "average maximum temperature of 36.8 °C."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `hw.metrics` attribute is a DataFrame with the annual heat waves properties.\n",
    "\n",
    "- hwn: number of events\n",
    "- hwf: number of days\n",
    "- hwd: duration of longest event\n",
    "- hwdm: mean duration of events\n",
    "- hwm: mean normalized magnitude\n",
    "- hwma: mean absolute magnitude\n",
    "- hwa: normalized magnitude of hottest day\n",
    "- hwaa: absolute magnitude of hottest day\n",
    "\n",
    "For a more detailed description of heat waves metrics see the [documentation](./heatwave_metrics.rst)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "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>hwn</th>\n",
       "      <th>hwf</th>\n",
       "      <th>hwd</th>\n",
       "      <th>hwdm</th>\n",
       "      <th>hwm</th>\n",
       "      <th>hwma</th>\n",
       "      <th>hwa</th>\n",
       "      <th>hwaa</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>year</th>\n",
       "      <th></th>\n",
       "      <th></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>1901</th>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>3.0</td>\n",
       "      <td>3.0</td>\n",
       "      <td>6.3</td>\n",
       "      <td>37.9</td>\n",
       "      <td>7.2</td>\n",
       "      <td>38.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1902</th>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>3.0</td>\n",
       "      <td>3.0</td>\n",
       "      <td>6.6</td>\n",
       "      <td>38.2</td>\n",
       "      <td>8.7</td>\n",
       "      <td>40.3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1903</th>\n",
       "      <td>1</td>\n",
       "      <td>3</td>\n",
       "      <td>3.0</td>\n",
       "      <td>3.0</td>\n",
       "      <td>4.4</td>\n",
       "      <td>36.0</td>\n",
       "      <td>4.6</td>\n",
       "      <td>36.2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1904</th>\n",
       "      <td>1</td>\n",
       "      <td>4</td>\n",
       "      <td>4.0</td>\n",
       "      <td>4.0</td>\n",
       "      <td>4.9</td>\n",
       "      <td>36.5</td>\n",
       "      <td>5.2</td>\n",
       "      <td>36.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1905</th>\n",
       "      <td>1</td>\n",
       "      <td>7</td>\n",
       "      <td>7.0</td>\n",
       "      <td>7.0</td>\n",
       "      <td>4.8</td>\n",
       "      <td>36.4</td>\n",
       "      <td>6.4</td>\n",
       "      <td>38.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      hwn  hwf  hwd  hwdm  hwm  hwma  hwa  hwaa\n",
       "year                                           \n",
       "1901    1    3  3.0   3.0  6.3  37.9  7.2  38.8\n",
       "1902    1    3  3.0   3.0  6.6  38.2  8.7  40.3\n",
       "1903    1    3  3.0   3.0  4.4  36.0  4.6  36.2\n",
       "1904    1    4  4.0   4.0  4.9  36.5  5.2  36.8\n",
       "1905    1    7  7.0   7.0  4.8  36.4  6.4  38.0"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hw.metrics.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Detect heat waves using a custom index\n",
    "\n",
    "Let's repeat the procedure devising a custom index, that we will call *extreme*, that aims to\n",
    "capture only the most severe cases of heat. We can define the heat waves under\n",
    "this index as the period of at least 4 concecutive days with maximum\n",
    "temperatures above 40 °C."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "extreme = hotspell.index(\n",
    "    name=\"extreme\",\n",
    "    var=\"tmax\",\n",
    "    fixed_thres=40,\n",
    "    min_duration=4\n",
    ")\n",
    "\n",
    "hw_extreme = hotspell.get_heatwaves(filename=processed_data, hw_index=extreme)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that at this extreme case study only two events satisfied the heat wave criteria. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "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>begin_date</th>\n",
       "      <th>end_date</th>\n",
       "      <th>duration</th>\n",
       "      <th>avg_tmax</th>\n",
       "      <th>std_tmax</th>\n",
       "      <th>max_tmax</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>index</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>1987-07-21</th>\n",
       "      <td>1987-07-21</td>\n",
       "      <td>1987-07-27</td>\n",
       "      <td>7</td>\n",
       "      <td>41.6</td>\n",
       "      <td>0.7</td>\n",
       "      <td>42.8</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2007-07-22</th>\n",
       "      <td>2007-07-22</td>\n",
       "      <td>2007-07-25</td>\n",
       "      <td>4</td>\n",
       "      <td>41.4</td>\n",
       "      <td>0.5</td>\n",
       "      <td>41.9</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           begin_date   end_date  duration  avg_tmax  std_tmax  max_tmax\n",
       "index                                                                   \n",
       "1987-07-21 1987-07-21 1987-07-27         7      41.6       0.7      42.8\n",
       "2007-07-22 2007-07-22 2007-07-25         4      41.4       0.5      41.9"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hw_extreme.events"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "ca4c86c56289943e9fcaf3c83d393f4507d68511bee36bc64ba787708615e7d1"
  },
  "kernelspec": {
   "display_name": "Python 3.9.6 64-bit ('hotspell_env': conda)",
   "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.9.18"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}