docs/notebooks/all_about_the_calendar.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Presenting the Calendar! 📅\n",
    "\n",
    "To explain some of the terminology used in this package, the image below can be used as reference.\n",
    "\n",
    "The calendar system revolves around so-called \"anchor dates\" and \"anchor years\". The **anchor date** is (generally) the start of the period you want to forecast. I.e. your target data. The anchor date is an abstract date, and does not include a year. For example, 5 June, or 25 December 🎄.\n",
    "\n",
    "**Anchor years** are used to create a full date with the anchor date (e.g., 25 December 2022), and to group the calendar intervals together.\n",
    "\n",
    "Two types of intervals exist. First are the **target intervals**, which is generally what you want to predict or forecast. The other type are **precursor intervals**, intervals preceding the anchor date representing the data that you would like to use to forecast the target interval.\n",
    "\n",
    "![Calendar Illustration](../assets/images/calendar_concept.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using the calendar\n",
    "First we import the package, and create an empty calendar with the anchor date 25 December:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lilio import Calendar\n",
    "cal = Calendar(\"12-25\")  # 🎄🎅\n",
    "cal"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To this calendar we can add an interval, in this case a \"target\" interval which we want to use as our target data.\n",
    "\n",
    "Note that when calling `add_intervals`, the default `n` (number of intervals) is 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.add_intervals(\"target\", length=\"1d\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When viewing the calendar, you can see that the calendar now contains this interval"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, this calendar is not mapped to any years yet. Before we can view which dates are represented by each interval, we have to map the calendar:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.map_years(start=2021, end=2022)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can call `.show()` and view the intervals generated. A table is returned, showing the anchor year(s) on the vertical axis and the intervals on the horizontal index, sorted by their interval index (`i_interval`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can add some precursor periods, and inspect the table again. We can add multiple intervals using the `n` keyword argument.\n",
    "\n",
    "Note that the target interval has a positive index, while the precursors have negative indices."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.add_intervals(\"precursor\", length=\"1d\", n=6)\n",
    "cal.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Besides a table view, the calendar can also be visualized in a plot. The default plotting backend is matplotlib (as in the image below).\n",
    "\n",
    "An interactive 'bokeh' plot, containing more information on the intervals, is also available. It is used by calling `.visualize(interactive=True)`. Do note that bokeh needs to be installed for this to work."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.visualize(n_years=1, add_legend=True, show_length=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For inputs such as `length`, you can use either days (`\"10d\"`), weeks (`\"3W\"`) or months (`\"1M\"`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.add_intervals(\"precursor\", length=\"1M\", n=2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in the visualization below, the length of the large precursor blocks is 31 and 30 days respectively, this is due to the input length of `1M`, and the months not having the same lengths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.visualize(n_years=1, add_legend=False, show_length=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Last but not least, are gaps. Gaps can be inserted between the previous interval and the new one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.add_intervals(\"precursor\", length=\"1M\", gap=\"1M\")\n",
    "cal.visualize(n_years=1, add_legend=False, show_length=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that these gaps can also be negative. This makes the new interval overlap with the previous one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.add_intervals(\"precursor\", length=\"1M\", gap=\"-2W\")\n",
    "cal.visualize(n_years=1, add_legend=False, show_length=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using the \"repr\" to reproduce calendars 📜\n",
    "When you just call the calendar, as in the cell below, the calendar will return a string **repr**esentation of itself. This is enough information to completely rebuild the calendar, so it can be used as a way to store or share a specific calendar."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal = Calendar(\"06-01\") \n",
    "cal.map_years(2020, 2022)\n",
    "cal.add_intervals(\"target\", \"1d\")\n",
    "cal.add_intervals(\"precursor\", \"7d\", \"1M\")\n",
    "cal"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we copy-paste the calendar, and we import the required classes from `lilio`. Note that it reproduces itself when you call `cal`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lilio import Interval\n",
    "Calendar(\n",
    "    anchor='06-01',\n",
    "    allow_overlap=False,\n",
    "    mapping=('years', 2020, 2022),\n",
    "    intervals=[\n",
    "        Interval(role='target', length='1d', gap='0d'),\n",
    "        Interval(role='precursor', length='7d', gap='1M')\n",
    "    ]\n",
    ")\n",
    "cal"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The `Interval` building block 🧱\n",
    "\n",
    "The basic building block of the Calendar is the **Interval**. Intervals have three properties: the **type** (target or precursor), the **length**, and the **gap**. The gap is defined as the gap between this interval and the preceding interval of the same type (or the anchor, if this interval is the first one).\n",
    "\n",
    "The length and gap are set in the same way. The most common way is to use a pandas-like frequency string (for example, \"10d\" for ten days, \"2W\" for two weeks, or \"3M\" for three months). Let's set the length to five days and the gap to a month:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "iv = Interval(\"target\", length=\"5d\", gap=\"1M\")\n",
    "iv"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Intervals can be changed in-place. Their gap and length can be set in the following way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "iv.gap = \"5d\"\n",
    "iv"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you are feeling adventurous, you can set the length and gap using a pandas.DateOffset compatible dictionary. This allows you to combine day, week, and month lengths:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "iv.length = {\"months\": 1, \"weeks\": 2}\n",
    "iv.length_dateoffset  # shows the length as a pandas.DateOffset object."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### All about anchors ⚓\n",
    "\n",
    "As said before, the anchor date is one of the basic elements of the calendar. Up to now we have just showcased setting the anchor as a date (\"MM-DD\"), however, there are some alternative options.\n",
    "\n",
    "If you are interested in *only* months, it is possible to create a calendar revolving solely around calendar months. The anchor can be defined as an *English* month name (e.g., \"January\" or the short name \"Jan\"). This is equivalent to setting the anchor to the first day of that month. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal = Calendar(anchor=\"December\")  # [December 01)\n",
    "cal.add_intervals(\"target\", \"1M\")\n",
    "cal.add_intervals(\"precursor\", \"1M\", n=11)\n",
    "cal.map_years(2022, 2022)\n",
    "cal.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Besides months, the calendar can also be used with **week numbers**. You can use either only a week number (\"W10\" for the 10th week of a year), or the combination of a week number and the day of the week (where Monday is 1 and Sunday 7). This can be especially useful with targets and precursor intervals that you would like to cover certain days of the week. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "Calendar(anchor=\"W12\")  # Week 12\n",
    "cal = Calendar(anchor=\"W12-5\")  # Friday on week 12\n",
    "cal.add_intervals(\"target\", \"1d\")\n",
    "cal.add_intervals(\"precursor\", \"1d\", gap=\"1W\")\n",
    "cal.map_years(2018, 2022)\n",
    "cal.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Modifying calendars in-place 🏗️\n",
    "If you want to do *funkier* things with the calendar, you can edit already existing calendars 🔨👷‍♀️\n",
    "\n",
    "For example, the anchor of the calendar can be changed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.anchor = \"01-01\"  # 🍾🥂\n",
    "cal"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, you do need to be careful when comparing two calendars, as data might have shifted to a different anchor year.\n",
    "\n",
    "Modifying the intervals is also possible. The precursors and target intervals are stored in lists, and can be changed in-place:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cal.precursors  # or cal.targets"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's change the gaps and lengths (for sake of demonstration):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for precursor in cal.precursors:\n",
    "    precursor.gap = \"7d\"\n",
    "\n",
    "for target in cal.targets:\n",
    "    target.length=\"1M\"\n",
    "\n",
    "cal.map_years(2022, 2022)\n",
    "cal.visualize(add_legend=False, show_length=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A more useful trick can be modifying the `gap` property of only the *first* target and precursor intervals. This allows you to shift all intervals relative to the anchor date.\n",
    "\n",
    "This shifting is demonstrated below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "cal = Calendar(\n",
    "    anchor='06-01',\n",
    "    allow_overlap=False,\n",
    "    mapping=('years', 2020, 2022),\n",
    "    intervals=[\n",
    "        Interval(role='target', length='1d', gap='0d'),\n",
    "        Interval(role='precursor', length='7d', gap='0d'),\n",
    "        Interval(role='precursor', length='7d', gap='0d')\n",
    "    ]\n",
    ")\n",
    "\n",
    "fig, (ax1, ax2) = plt.subplots(nrows=2)\n",
    "# Plot the original calendar\n",
    "cal.visualize(n_years=1, add_legend=False, show_length=True, ax=ax1)\n",
    "\n",
    "# Shift the calendar by a month\n",
    "cal.precursors[0].gap = \"1M\"\n",
    "cal.targets[0].gap = \"-1M\"\n",
    "\n",
    "# Plot the shifted calendar\n",
    "cal.visualize(n_years=1, add_legend=False, show_length=True, ax=ax2)\n",
    "\n",
    "# Make the plot pretty\n",
    "ax1.set_title(\"Original calendar\")\n",
    "ax2.set_title(\"Shifted calendar\")\n",
    "for ax in (ax1, ax2):\n",
    "    ax.set_xlim((np.datetime64(\"2022-04-15\"), np.datetime64(\"2022-06-05\")))\n",
    "fig.subplots_adjust(hspace=0.7)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Now you are ready to build your own calendar. We're curious to know what you come up with!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "lilio",
   "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.9.6"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "1ad84d851b7a3d072f2b3778c2795859f5c348aba25460fe1ff63101a851e075"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}