{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Calculate probabilistic impact yearset\n",
    "\n",
    "This module generates a yearly impact `yimp` object which contains probabilistic annual impacts for a specified amount of years (`sampled_years`). The impact values are extracted from a given impact `imp` object that contains impact values per event. The amount of `sampled_years` can be specified as an integer or as a list of years to be sampled for. The amount of events per sampled year (`events_per_year`) are determined with a Poisson distribution centered around n_events per year (`lam` = sum(event_impacts.frequency). Then, the probabilistic events occuring in each sampled year are sampled uniformaly from the input `imp` object and summed up per year. Thus, the `yimp` object contains the sum of sampled (event) impacts for each sampled year. In contrast to the expected annual impact (eai), an `yimp` object contains an impact for EACH sampled year and this value differs among years. The number of events_per_year and the selected_events are saved in a sampling vector (`sampling_vect`). \n",
    "\n",
    "The function impact_yearsets performs all these computational steps, taking an `imp` and the number of sampled_years (`sampled_years`) as input. The output of the function is the `yimp` object and the `sampling_vect`.\n",
    "Moreover, a `sampling_vect` (generated in a previous run) can be provided as optional input and the user can define `lam` and decide whether a correction factor shall be applied (the default is applying the correction factor).\n",
    "Reapplying the same sampling_vect does not only allow to reproduce the generated `yimp`, but also for a physically consistent way of sampling impacts caused by different hazards. \n",
    "The correction factor that is applied when the optional input `correction_fac`= True is a scaling of the computed `yimp` that assures that the eai(`yimp`) = eai(`imp`).\n",
    "\n",
    "To make the process more transparent, this tutorial shows the single computations that are performed when generating an `yimp` object for a dummy event_impacts object. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([2, 2, 2, 0, 4, 5, 4, 2, 3, 1])"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "\n",
    "import climada.util.yearsets as yearsets\n",
    "from climada.engine import Impact\n",
    "\n",
    "# dummy event_impacts object containing 10 event_impacts with the values 10-110 \n",
    "# and the frequency 0.2 (Return period of 5 years)\n",
    "imp = Impact()\n",
    "imp.at_event = np.arange(10,110,10)\n",
    "imp.frequency = np.array(np.ones(10)*0.2)\n",
    "\n",
    "# the number of years to sample impacts for (length(yimp.at_event) = sampled_years)\n",
    "sampled_years = 10\n",
    "\n",
    "# sample number of events per sampled year\n",
    "lam = np.sum(imp.frequency)\n",
    "events_per_year = yearsets.sample_from_poisson(sampled_years, lam)\n",
    "events_per_year"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[array([8, 3]),\n",
       " array([7, 0]),\n",
       " array([4, 6]),\n",
       " array([], dtype=int32),\n",
       " array([5, 9, 1, 2]),\n",
       " array([1, 6, 0, 7, 2]),\n",
       " array([4, 9, 5, 8]),\n",
       " array([9, 8]),\n",
       " array([5, 3, 4]),\n",
       " array([1])]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# generate the sampling vector\n",
    "sampling_vect = yearsets.sample_events(events_per_year, imp.frequency)\n",
    "sampling_vect"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[130, 90, 120, 0, 210, 210, 300, 190, 150, 20]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# calculate the impact per year\n",
    "imp_per_year = yearsets.compute_imp_per_year(imp, sampling_vect)\n",
    "imp_per_year"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.7746478873239436"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# calculate the correction factor\n",
    "correction_factor = yearsets.calculate_correction_fac(imp_per_year, imp)\n",
    "correction_factor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The yimp.at_event values equal our step-by-step computed imp_per_year:\n",
      "yimp.at_event =  [90, 240, 150, 70, 40, 90, 60, 90, 170, 110]\n",
      "imp_per_year =  [130, 90, 120, 0, 210, 210, 300, 190, 150, 20]\n"
     ]
    }
   ],
   "source": [
    "# compare the resulting yimp with our step-by-step computation without applying the correction factor:\n",
    "yimp, sampling_vect = yearsets.impact_yearset(imp, sampled_years=list(range(1,11)), correction_fac=False)\n",
    "\n",
    "print('The yimp.at_event values equal our step-by-step computed imp_per_year:')\n",
    "print('yimp.at_event = ', yimp.at_event)\n",
    "print('imp_per_year = ', imp_per_year)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The same can be shown for the case of applying the correction factor.The yimp.at_event values equal our step-by-step computed imp_per year:\n",
      "yimp.at_event =  [ 54.54545455  47.72727273  95.45454545 109.09090909   0.\n",
      "  40.90909091  27.27272727   0.         109.09090909  27.27272727]\n",
      "imp_per_year =  [167.81818182 116.18181818 154.90909091   0.         271.09090909\n",
      " 271.09090909 387.27272727 245.27272727 193.63636364  25.81818182]\n"
     ]
    }
   ],
   "source": [
    "# and here the same comparison with applying the correction factor (default settings):\n",
    "yimp, sampling_vect = yearsets.impact_yearset(imp, sampled_years=list(range(1,11)))\n",
    "\n",
    "print('The same can be shown for the case of applying the correction factor.' \n",
    "      'The yimp.at_event values equal our step-by-step computed imp_per year:')\n",
    "print('yimp.at_event = ', yimp.at_event)\n",
    "print('imp_per_year = ', imp_per_year/correction_factor)"
   ]
  }
 ],
 "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
}