date_binning.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8eb71b2c",
   "metadata": {},
   "source": [
    "# Date Binning with the `Period` Class\n",
    "\n",
    "The following code demonstrates various ways to use and apply the functionality in the `Period` class. In general, the class expects a date range defined with a `start_date` and `end_date`, and a `periodicity` (see options below). From there, it can generate date bins from `start_date` to `end_date` (inclusive by default) for the given `periodicity`. Date bins are in the form of a list of tuples, where each tuple contains that bin's start date and end date. The class can also convert given date bins from one periodicity to another, it can redistribute data from one periodicity to another given the data and original date bins, and can output pre-defined or custom labels.\n",
    "\n",
    "The class supports the following options for `periodicity`. The ISO options follow the ISO-8601 Standard. If a `periodicity` isn't provided, the default is \"ISO Week\".\n",
    "\n",
    "- \"ISO Week\" (default): weekly bins starting on a Monday\n",
    "- \"ISO Biweekly\": bins of 2 ISO week periods, grouping weeks 01 and 02, then 03 with 04, etc.\n",
    "- \"ISO Month (4 Weeks)\": monthly bins where months are defined by grouping ISO weeks within the ISO year in a pattern of 4 weeks each (this creates 13 months). Month 1 is weeks 01-04, month 2 is weeks 05-08, etc.\n",
    "- \"ISO Month (4 + 5 + 4)\": monthly bins where months are defined by grouping ISO weeks within the ISO year in a pattern of 4 weeks, 5 weeks, then 4 weeks. Month 1 is weeks 01-04, month 2 is weeks 05-09, etc.\n",
    "- \"ISO Month (4 + 4 + 5)\": monthly bins where months are defined by grouping ISO weeks within the ISO year in a pattern of 4 weeks, 4 weeks, then 5 weeks. Month 1 is weeks 01-04, month 2 is weeks 05-08, etc.\n",
    "- \"ISO Quarter (13 Weeks)\": quarterly bins of 13 ISO week periods. Quarter 1 is weeks 01-13, quarter 2 is weeks 14-26, etc.\n",
    "- \"ISO Semiannual (26 Weeks)\": semiannual bins of 26 ISO week periods. The first period is weeks 01-26 and second is weeks 27 to either 52 or 53, depending on the year\n",
    "- \"ISO Annual\": bins of full ISO years. If `start_date` is not the first day of the ISO year, the first bin will be a partial year\n",
    "- \"Custom Days\": bins starting on `start_date` with a number of days between them as given by `custom_days` parameter in `get_date_bins`\n",
    "- \"Weekly\": weekly bins starting on `start_date`'s weekday\n",
    "- \"Biweekly\": bins of 2-week periods, starting on `start_date`'s weekday\n",
    "- \"Calendar Month\": bins by calendar month\n",
    "- \"Monthly\": monthly bins starting on `start_date`\n",
    "- \"Calendar Quarter\": bins of 3-month periods based on a calendar year (Jan-Mar, Apr-Jun, etc.)\n",
    "- \"Quarterly\": bins of 3-month periods starting on `start_date`\n",
    "- \"Calendar Year\": calendar year bins (Jan-Dec). If `start_date` is not Jan 1, the first bin will be a partial year\n",
    "- \"Annually\": yearly bins starting from `start_date`\n",
    "- \"Entire Period\": one bin spanning the given date range\n",
    "\n",
    "## Partial (\"Stub\") Periods\n",
    "\n",
    "The `Period` class respects the user-provided `start_date` and `end_date`, even if they don't respect the convention of the `periodicity`. For example, if the user wants bins by \"Calendar Year\", but the `start_date` they provide is not January 1st, then the first bin will be a stub year from `start_date` to December 31st.\n",
    "\n",
    "For all ISO periodicity options, if `start_date` is not a Monday or week 01 of any other ISO period, the first bin will represent a stub period. For periodicity options of \"Calendar Month\" and \"Calendar Year\", if `start_date` is not the first of that year, the first bin will represent a partial month/year. For \"Weekly\", \"Biweekly\", \"Calendar Quarter\", and \"Annually\" options, there's no concept of a partial period - it starts binning with `start_date` and counts off bins from there.\n",
    "\n",
    "Not all `periodicity` choices create stub periods. Any option with \"ISO\" or \"Calendar\" in the name will create stub periods, as they all have defined starting and ending points. The options for \"Custom Days\", \"Weekly\", \"Biweekly\", \"Annually\", and \"Entire Period\" don't create stub periods, as they start binning from the `start_date`, regardless of which day of the week/month/year it is."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "13410607",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "from dateutil.relativedelta import relativedelta\n",
    "\n",
    "from forecast import Period"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "250ebdc9",
   "metadata": {},
   "source": [
    "## Using the `Period` Class\n",
    "\n",
    "\n",
    "### Get Date Bins for ISO Week Periodicity\n",
    "\n",
    "The following example creates date bins by ISO week for the current year. Since ISO years may have 52 or 53 weeks, the `n_weeks_in_cy` variable is used to get the week number for the final week of the year (December 28th is always in the last week of the ISO year).\n",
    "\n",
    "The default `periodicity` for the `Period` class is \"ISO Week\", so it's not necessary to provide it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "688c0f15",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 1), datetime.date(2024, 1, 7)),\n",
       " (datetime.date(2024, 1, 8), datetime.date(2024, 1, 14)),\n",
       " (datetime.date(2024, 1, 15), datetime.date(2024, 1, 21)),\n",
       " (datetime.date(2024, 1, 22), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 2, 4)),\n",
       " (datetime.date(2024, 2, 5), datetime.date(2024, 2, 11)),\n",
       " (datetime.date(2024, 2, 12), datetime.date(2024, 2, 18)),\n",
       " (datetime.date(2024, 2, 19), datetime.date(2024, 2, 25)),\n",
       " (datetime.date(2024, 2, 26), datetime.date(2024, 3, 3)),\n",
       " (datetime.date(2024, 3, 4), datetime.date(2024, 3, 10)),\n",
       " (datetime.date(2024, 3, 11), datetime.date(2024, 3, 17)),\n",
       " (datetime.date(2024, 3, 18), datetime.date(2024, 3, 24)),\n",
       " (datetime.date(2024, 3, 25), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 4, 7)),\n",
       " (datetime.date(2024, 4, 8), datetime.date(2024, 4, 14)),\n",
       " (datetime.date(2024, 4, 15), datetime.date(2024, 4, 21)),\n",
       " (datetime.date(2024, 4, 22), datetime.date(2024, 4, 28)),\n",
       " (datetime.date(2024, 4, 29), datetime.date(2024, 5, 5)),\n",
       " (datetime.date(2024, 5, 6), datetime.date(2024, 5, 12)),\n",
       " (datetime.date(2024, 5, 13), datetime.date(2024, 5, 19)),\n",
       " (datetime.date(2024, 5, 20), datetime.date(2024, 5, 26)),\n",
       " (datetime.date(2024, 5, 27), datetime.date(2024, 6, 2)),\n",
       " (datetime.date(2024, 6, 3), datetime.date(2024, 6, 9)),\n",
       " (datetime.date(2024, 6, 10), datetime.date(2024, 6, 16)),\n",
       " (datetime.date(2024, 6, 17), datetime.date(2024, 6, 23)),\n",
       " (datetime.date(2024, 6, 24), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 7, 7)),\n",
       " (datetime.date(2024, 7, 8), datetime.date(2024, 7, 14)),\n",
       " (datetime.date(2024, 7, 15), datetime.date(2024, 7, 21)),\n",
       " (datetime.date(2024, 7, 22), datetime.date(2024, 7, 28)),\n",
       " (datetime.date(2024, 7, 29), datetime.date(2024, 8, 4)),\n",
       " (datetime.date(2024, 8, 5), datetime.date(2024, 8, 11)),\n",
       " (datetime.date(2024, 8, 12), datetime.date(2024, 8, 18)),\n",
       " (datetime.date(2024, 8, 19), datetime.date(2024, 8, 25)),\n",
       " (datetime.date(2024, 8, 26), datetime.date(2024, 9, 1)),\n",
       " (datetime.date(2024, 9, 2), datetime.date(2024, 9, 8)),\n",
       " (datetime.date(2024, 9, 9), datetime.date(2024, 9, 15)),\n",
       " (datetime.date(2024, 9, 16), datetime.date(2024, 9, 22)),\n",
       " (datetime.date(2024, 9, 23), datetime.date(2024, 9, 29)),\n",
       " (datetime.date(2024, 9, 30), datetime.date(2024, 10, 6)),\n",
       " (datetime.date(2024, 10, 7), datetime.date(2024, 10, 13)),\n",
       " (datetime.date(2024, 10, 14), datetime.date(2024, 10, 20)),\n",
       " (datetime.date(2024, 10, 21), datetime.date(2024, 10, 27)),\n",
       " (datetime.date(2024, 10, 28), datetime.date(2024, 11, 3)),\n",
       " (datetime.date(2024, 11, 4), datetime.date(2024, 11, 10)),\n",
       " (datetime.date(2024, 11, 11), datetime.date(2024, 11, 17)),\n",
       " (datetime.date(2024, 11, 18), datetime.date(2024, 11, 24)),\n",
       " (datetime.date(2024, 11, 25), datetime.date(2024, 12, 1)),\n",
       " (datetime.date(2024, 12, 2), datetime.date(2024, 12, 8)),\n",
       " (datetime.date(2024, 12, 9), datetime.date(2024, 12, 15)),\n",
       " (datetime.date(2024, 12, 16), datetime.date(2024, 12, 22)),\n",
       " (datetime.date(2024, 12, 23), datetime.date(2024, 12, 29))]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "current_year = datetime.datetime.now().year\n",
    "n_weeks_in_cy = datetime.date(current_year, 12, 28).isocalendar().week\n",
    "start_date = datetime.date.fromisocalendar(current_year, 1, 1)\n",
    "end_date = datetime.date.fromisocalendar(current_year, n_weeks_in_cy, 7)\n",
    "\n",
    "# Create an instance of Period and generate the date bins\n",
    "p = Period(start_date=start_date, end_date=end_date)\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1dff26c3",
   "metadata": {},
   "source": [
    "If `start_date` is not a Monday, or `end_date` is not a Sunday, the first or last bin will be a stub period, respectively. The following example uses a Wednesday (weekday 3) in week 01 as `start_date` and a Friday (weekday 5) in week 04 as an `end_date`. The resulting first and last bins are partial weeks to respect the user's date range. The middle 2 bins are full ISO weeks starting on Monday."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "44f3f617",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 3), datetime.date(2024, 1, 7)),\n",
       " (datetime.date(2024, 1, 8), datetime.date(2024, 1, 14)),\n",
       " (datetime.date(2024, 1, 15), datetime.date(2024, 1, 21)),\n",
       " (datetime.date(2024, 1, 22), datetime.date(2024, 1, 26))]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date.fromisocalendar(current_year, 1, 3)\n",
    "end_date = datetime.date.fromisocalendar(current_year, 4, 5)\n",
    "\n",
    "# Create an instance of Period and generate the date bins\n",
    "p = Period(start_date=start_date, end_date=end_date)\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3220f2c1",
   "metadata": {},
   "source": [
    "### Get Labels for Date Bins\n",
    "\n",
    "The `Period` class has the `get_period_labels` method to generate labels for given date bins. It has built-in formats for all periodicity options, or the user can provide their own format string to suit their needs. The method supports any Python [strftime formatters](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes), which uses the 1989 C standard.\n",
    "\n",
    "If a custom format is provided, the user can also indicate which date for each bin - the bin's start date or the bin's end date - to use to create the labels. The built-in formats use the bin's start date for ISO-based periodicity options and the bin's end date for the others, with the exception of the \"Entire Period\" periodicity, which uses both dates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "94eeaf95",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Week 1-24', 'Week 2-24', 'Week 3-24', 'Week 4-24']"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels\n",
    "p.get_period_labels(bins, periodicity=\"ISO Week\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "4c2529c0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Jan-07', 'Jan-14', 'Jan-21', 'Jan-26']"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get custom-formatted labels of form MMM-DD using the end date of each bin\n",
    "p.get_period_labels(\n",
    "    bins,\n",
    "    periodicity=\"ISO Week\",\n",
    "    date_format_string=\"%b-%d\",\n",
    "    use_bin_start_date_for_label=False\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89d61c42",
   "metadata": {},
   "source": [
    "### Convert Date Bins from One Periodicity to Another\n",
    "\n",
    "The following example converts bins from \"ISO Week\" to \"ISO Quarter (13 Weeks)\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "d1136250",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 1), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 9, 29)),\n",
       " (datetime.date(2024, 9, 30), datetime.date(2024, 12, 29))]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date.fromisocalendar(current_year, 1, 1)\n",
    "end_date = datetime.date.fromisocalendar(current_year, n_weeks_in_cy, 7)\n",
    "\n",
    "# Create an instance of Period and generate the date bins\n",
    "p = Period(start_date=start_date, end_date=end_date)\n",
    "iso_week_bins = p.get_date_bins()\n",
    "\n",
    "# Convert ISO Week bins to ISO Quarter (13 Weeks) bins\n",
    "iso_q_bins = p.convert_dates(iso_week_bins, \"ISO Quarter (13 Weeks)\")\n",
    "iso_q_bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "15c1a179",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Q1-24', 'Q2-24', 'Q3-24', 'Q4-24']"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(iso_q_bins, \"ISO Quarter (13 Weeks)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e6d265a",
   "metadata": {},
   "source": [
    "### Redistribute Data from One Bin to Another\n",
    "\n",
    "Given numerical data and date bins of the same length, the `Period` class's `redistribute_data` method can convert the date bins and \"re-bin\" the numerical data values. Note that it assumes the data are distributed evenly across the days in their respective bins before they are redistributed to the new bins.\n",
    "\n",
    "The resulting object has the new date bins as keys and the redistributed data as values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "4a8a8486",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OrderedDict([((datetime.date(2024, 1, 1), datetime.date(2024, 3, 31)),\n",
       "              Decimal('1299.999999999999999999999995')),\n",
       "             ((datetime.date(2024, 4, 1), datetime.date(2024, 6, 30)),\n",
       "              Decimal('2600.000000000000000000000025')),\n",
       "             ((datetime.date(2024, 7, 1), datetime.date(2024, 9, 29)),\n",
       "              Decimal('3900.000000000000000000000010')),\n",
       "             ((datetime.date(2024, 9, 30), datetime.date(2024, 12, 29)),\n",
       "              Decimal('1299.999999999999999999999995'))])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data = [100] * 13 + [200] * 13 + [300] * 13 + [100] * 13\n",
    "data = data + ([100] if n_weeks_in_cy == 53 else [])\n",
    "\n",
    "# Convert ISO Week data to ISO Quarter data\n",
    "q_data = p.redistribute_data(data, iso_week_bins, \"ISO Quarter (13 Weeks)\")\n",
    "q_data"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3571bd9",
   "metadata": {},
   "source": [
    "## ISO Periodicity Date Bin Examples\n",
    "\n",
    "The following examples illustrate the other ISO-based periodicity options for creating date bins. All examples use a `start_date` that is the last week of the prior ISO year and an `end_date` in the first week of the following ISO year. This is to show that the binning applies patterns of including specific ISO weeks in a defined \"month\", \"quarter\", half year, etc.\n",
    "\n",
    "### ISO Biweekly\n",
    "\n",
    "Note that the first bin is only 1 week, since it's a stub period of the last biweekly period in the prior ISO year, followed by 2-week bins that group ISO weeks 1 and 2, then 3 and 4, and so forth. The final bin is also a 1 week long stub period since the `end_date` splits that biweekly period."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "7e9e321b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Start Date: 2023-12-25, End Date: 2025-01-05\n"
     ]
    }
   ],
   "source": [
    "# `start_date` is the last week of the prior ISO year\n",
    "start_date = datetime.date.fromisocalendar(current_year, 1, 1) - relativedelta(days=7)\n",
    "\n",
    "# `end_date` is the first week of the following ISO year\n",
    "end_date = datetime.date.fromisocalendar(current_year, n_weeks_in_cy, 7) + relativedelta(days=7)\n",
    "print(f\"Start Date: {start_date}, End Date: {end_date}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "67766685",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 1, 14)),\n",
       " (datetime.date(2024, 1, 15), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 2, 11)),\n",
       " (datetime.date(2024, 2, 12), datetime.date(2024, 2, 25)),\n",
       " (datetime.date(2024, 2, 26), datetime.date(2024, 3, 10)),\n",
       " (datetime.date(2024, 3, 11), datetime.date(2024, 3, 24)),\n",
       " (datetime.date(2024, 3, 25), datetime.date(2024, 4, 7)),\n",
       " (datetime.date(2024, 4, 8), datetime.date(2024, 4, 21)),\n",
       " (datetime.date(2024, 4, 22), datetime.date(2024, 5, 5)),\n",
       " (datetime.date(2024, 5, 6), datetime.date(2024, 5, 19)),\n",
       " (datetime.date(2024, 5, 20), datetime.date(2024, 6, 2)),\n",
       " (datetime.date(2024, 6, 3), datetime.date(2024, 6, 16)),\n",
       " (datetime.date(2024, 6, 17), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 7, 14)),\n",
       " (datetime.date(2024, 7, 15), datetime.date(2024, 7, 28)),\n",
       " (datetime.date(2024, 7, 29), datetime.date(2024, 8, 11)),\n",
       " (datetime.date(2024, 8, 12), datetime.date(2024, 8, 25)),\n",
       " (datetime.date(2024, 8, 26), datetime.date(2024, 9, 8)),\n",
       " (datetime.date(2024, 9, 9), datetime.date(2024, 9, 22)),\n",
       " (datetime.date(2024, 9, 23), datetime.date(2024, 10, 6)),\n",
       " (datetime.date(2024, 10, 7), datetime.date(2024, 10, 20)),\n",
       " (datetime.date(2024, 10, 21), datetime.date(2024, 11, 3)),\n",
       " (datetime.date(2024, 11, 4), datetime.date(2024, 11, 17)),\n",
       " (datetime.date(2024, 11, 18), datetime.date(2024, 12, 1)),\n",
       " (datetime.date(2024, 12, 2), datetime.date(2024, 12, 15)),\n",
       " (datetime.date(2024, 12, 16), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Biweekly\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "3c496396",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Weeks 52-52 23',\n",
       " 'Weeks 1-2 24',\n",
       " 'Weeks 3-4 24',\n",
       " 'Weeks 5-6 24',\n",
       " 'Weeks 7-8 24',\n",
       " 'Weeks 9-10 24',\n",
       " 'Weeks 11-12 24',\n",
       " 'Weeks 13-14 24',\n",
       " 'Weeks 15-16 24',\n",
       " 'Weeks 17-18 24',\n",
       " 'Weeks 19-20 24',\n",
       " 'Weeks 21-22 24',\n",
       " 'Weeks 23-24 24',\n",
       " 'Weeks 25-26 24',\n",
       " 'Weeks 27-28 24',\n",
       " 'Weeks 29-30 24',\n",
       " 'Weeks 31-32 24',\n",
       " 'Weeks 33-34 24',\n",
       " 'Weeks 35-36 24',\n",
       " 'Weeks 37-38 24',\n",
       " 'Weeks 39-40 24',\n",
       " 'Weeks 41-42 24',\n",
       " 'Weeks 43-44 24',\n",
       " 'Weeks 45-46 24',\n",
       " 'Weeks 47-48 24',\n",
       " 'Weeks 49-50 24',\n",
       " 'Weeks 51-52 24',\n",
       " 'Weeks 1-1 25']"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Biweekly\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f351dc26",
   "metadata": {},
   "source": [
    "### ISO Month (4 Weeks)\n",
    "\n",
    "This periodicity defines months as equal, 4-ISO week periods for a total of 13 months. The default labels use \"M13\" for the final month's name. In the event the ISO year has 53 weeks, the final week is included in the last month."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "b99eb5d2",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 2, 25)),\n",
       " (datetime.date(2024, 2, 26), datetime.date(2024, 3, 24)),\n",
       " (datetime.date(2024, 3, 25), datetime.date(2024, 4, 21)),\n",
       " (datetime.date(2024, 4, 22), datetime.date(2024, 5, 19)),\n",
       " (datetime.date(2024, 5, 20), datetime.date(2024, 6, 16)),\n",
       " (datetime.date(2024, 6, 17), datetime.date(2024, 7, 14)),\n",
       " (datetime.date(2024, 7, 15), datetime.date(2024, 8, 11)),\n",
       " (datetime.date(2024, 8, 12), datetime.date(2024, 9, 8)),\n",
       " (datetime.date(2024, 9, 9), datetime.date(2024, 10, 6)),\n",
       " (datetime.date(2024, 10, 7), datetime.date(2024, 11, 3)),\n",
       " (datetime.date(2024, 11, 4), datetime.date(2024, 12, 1)),\n",
       " (datetime.date(2024, 12, 2), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Month (4 Weeks)\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "52d5b805",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['M13 (4w)-23',\n",
       " 'Jan (4w)-24',\n",
       " 'Feb (4w)-24',\n",
       " 'Mar (4w)-24',\n",
       " 'Apr (4w)-24',\n",
       " 'May (4w)-24',\n",
       " 'Jun (4w)-24',\n",
       " 'Jul (4w)-24',\n",
       " 'Aug (4w)-24',\n",
       " 'Sep (4w)-24',\n",
       " 'Oct (4w)-24',\n",
       " 'Nov (4w)-24',\n",
       " 'Dec (4w)-24',\n",
       " 'M13 (4w)-24',\n",
       " 'Jan (4w)-25']"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Month (4 Weeks)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "be8ca538",
   "metadata": {},
   "source": [
    "### ISO Month (4 + 5 + 4)\n",
    "\n",
    "This periodicity defines months as grouped ISO weeks in the pattern of 4 weeks, 5 weeks, then 4 weeks, with the first month including ISO weeks 01-04 and so forth. In the event the ISO year has 53 weeks, the final week is included in the last month."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "34a02c5f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 3, 3)),\n",
       " (datetime.date(2024, 3, 4), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 4, 28)),\n",
       " (datetime.date(2024, 4, 29), datetime.date(2024, 6, 2)),\n",
       " (datetime.date(2024, 6, 3), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 7, 28)),\n",
       " (datetime.date(2024, 7, 29), datetime.date(2024, 9, 1)),\n",
       " (datetime.date(2024, 9, 2), datetime.date(2024, 9, 29)),\n",
       " (datetime.date(2024, 9, 30), datetime.date(2024, 10, 27)),\n",
       " (datetime.date(2024, 10, 28), datetime.date(2024, 12, 1)),\n",
       " (datetime.date(2024, 12, 2), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Month (4 + 5 + 4)\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "32524f3c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Dec (4w)-23',\n",
       " 'Jan (4w)-24',\n",
       " 'Feb (5w)-24',\n",
       " 'Mar (4w)-24',\n",
       " 'Apr (4w)-24',\n",
       " 'May (5w)-24',\n",
       " 'Jun (4w)-24',\n",
       " 'Jul (4w)-24',\n",
       " 'Aug (5w)-24',\n",
       " 'Sep (4w)-24',\n",
       " 'Oct (4w)-24',\n",
       " 'Nov (5w)-24',\n",
       " 'Dec (4w)-24',\n",
       " 'Jan (4w)-25']"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Month (4 + 5 + 4)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6c8f2738",
   "metadata": {},
   "source": [
    "### ISO Month (4 + 4 + 5)\n",
    "\n",
    "This periodicity defines months as grouped ISO weeks in the pattern of 4 weeks, 4 weeks, then 5 weeks, with the first month including ISO weeks 01-04 and so forth. In the event the ISO year has 53 weeks, the final week is included in the last month."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "ea0e27dd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 2, 25)),\n",
       " (datetime.date(2024, 2, 26), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 4, 28)),\n",
       " (datetime.date(2024, 4, 29), datetime.date(2024, 5, 26)),\n",
       " (datetime.date(2024, 5, 27), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 7, 28)),\n",
       " (datetime.date(2024, 7, 29), datetime.date(2024, 8, 25)),\n",
       " (datetime.date(2024, 8, 26), datetime.date(2024, 9, 29)),\n",
       " (datetime.date(2024, 9, 30), datetime.date(2024, 10, 27)),\n",
       " (datetime.date(2024, 10, 28), datetime.date(2024, 11, 24)),\n",
       " (datetime.date(2024, 11, 25), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Month (4 + 4 + 5)\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "6e4c9559",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Dec (5w)-23',\n",
       " 'Jan (4w)-24',\n",
       " 'Feb (4w)-24',\n",
       " 'Mar (5w)-24',\n",
       " 'Apr (4w)-24',\n",
       " 'May (4w)-24',\n",
       " 'Jun (5w)-24',\n",
       " 'Jul (4w)-24',\n",
       " 'Aug (4w)-24',\n",
       " 'Sep (5w)-24',\n",
       " 'Oct (4w)-24',\n",
       " 'Nov (4w)-24',\n",
       " 'Dec (5w)-24',\n",
       " 'Jan (4w)-25']"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Month (4 + 4 + 5)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dfbbb279",
   "metadata": {},
   "source": [
    "### ISO Quarter (13 Weeks)\n",
    "\n",
    "This periodicity defines quarters as grouped ISO weeks in the pattern of 13 weeks each, with the first quarter including ISO weeks 01-13 and so forth. In the event the ISO year has 53 weeks, the final week is included in the last quarter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "1159bde4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 9, 29)),\n",
       " (datetime.date(2024, 9, 30), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Quarter (13 Weeks)\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "13b500a9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Q4-23', 'Q1-24', 'Q2-24', 'Q3-24', 'Q4-24', 'Q1-25']"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Quarter (13 Weeks)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf4f5eff",
   "metadata": {},
   "source": [
    "### ISO Semiannual (26 Weeks)\n",
    "\n",
    "This periodicity defines a semi-annual period as grouped ISO weeks in the pattern of 26 weeks each, with the first half-year including ISO weeks 01-26 and the second half-year including weeks 27-52. In the event the ISO year has 53 weeks, the final week is included in the second half-year."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "53d27ed0",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Semiannual (26 Weeks)\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "77ac4f71",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['HY2-23', 'HY1-24', 'HY2-24', 'HY1-25']"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Semiannual (26 Weeks)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0294dd1a",
   "metadata": {},
   "source": [
    "### ISO Annual\n",
    "\n",
    "This periodicity returns bins by ISO year."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "14b7bba4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2023, 12, 25), datetime.date(2023, 12, 31)),\n",
       " (datetime.date(2024, 1, 1), datetime.date(2024, 12, 29)),\n",
       " (datetime.date(2024, 12, 30), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"ISO Annual\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "30c387ee",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['2023', '2024', '2025']"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get default-formatted labels for date bins\n",
    "p.get_period_labels(bins, \"ISO Annual\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "621eeaf8",
   "metadata": {},
   "source": [
    "## Calendar and Other Periodicity Date Bin Examples\n",
    "\n",
    "The following examples illustrate the calendar-based and other periodicity options for creating date bins.\n",
    "\n",
    "### Custom Days\n",
    "\n",
    "The most flexible of the periodicity options, this one creates bins starting on `start_date` with a number of days between them as given by the additional `custom_days` parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "7019cac5",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 12, 6), datetime.date(2024, 12, 10)),\n",
       " (datetime.date(2024, 12, 11), datetime.date(2024, 12, 15)),\n",
       " (datetime.date(2024, 12, 16), datetime.date(2024, 12, 20)),\n",
       " (datetime.date(2024, 12, 21), datetime.date(2024, 12, 25)),\n",
       " (datetime.date(2024, 12, 26), datetime.date(2024, 12, 30)),\n",
       " (datetime.date(2024, 12, 31), datetime.date(2025, 1, 4)),\n",
       " (datetime.date(2025, 1, 5), datetime.date(2025, 1, 5))]"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.datetime.now().date()\n",
    "end_date = start_date + relativedelta(days=30)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Custom Days\")\n",
    "bins = p.get_date_bins(custom_days=5)\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "8d9731be",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['12/10/24',\n",
       " '12/15/24',\n",
       " '12/20/24',\n",
       " '12/25/24',\n",
       " '12/30/24',\n",
       " '01/04/25',\n",
       " '01/05/25']"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Custom Days\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f4862598",
   "metadata": {},
   "source": [
    "### Weekly\n",
    "\n",
    "This periodicity option creates weekly bins based on `start_date`'s weekday."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "7b66131d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 15), datetime.date(2024, 1, 21)),\n",
       " (datetime.date(2024, 1, 22), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 2, 4)),\n",
       " (datetime.date(2024, 2, 5), datetime.date(2024, 2, 11)),\n",
       " (datetime.date(2024, 2, 12), datetime.date(2024, 2, 18)),\n",
       " (datetime.date(2024, 2, 19), datetime.date(2024, 2, 25))]"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 1, 15)\n",
    "end_date = start_date + relativedelta(days=41)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Weekly\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "3f682fca",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['01/21/24', '01/28/24', '02/04/24', '02/11/24', '02/18/24', '02/25/24']"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Weekly\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a96bd2a3",
   "metadata": {},
   "source": [
    "### Biweekly\n",
    "\n",
    "This periodicity option creates bins with lengths of 2 weeks starting from `start_date`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "c7720706",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 15), datetime.date(2024, 1, 28)),\n",
       " (datetime.date(2024, 1, 29), datetime.date(2024, 2, 11)),\n",
       " (datetime.date(2024, 2, 12), datetime.date(2024, 2, 25))]"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Biweekly\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "4c695bbd",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['01/28/24', '02/11/24', '02/25/24']"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Biweekly\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8d21436",
   "metadata": {},
   "source": [
    "### Calendar Month\n",
    "\n",
    "This periodicity option creates calendar-month bins. If `start_date` doesn't fall on the first of the month, the first bin will be a stub period."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "2194d6fb",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 15), datetime.date(2024, 1, 31)),\n",
       " (datetime.date(2024, 2, 1), datetime.date(2024, 2, 29)),\n",
       " (datetime.date(2024, 3, 1), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 4, 30)),\n",
       " (datetime.date(2024, 5, 1), datetime.date(2024, 5, 31)),\n",
       " (datetime.date(2024, 6, 1), datetime.date(2024, 6, 14))]"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 1, 15)\n",
    "end_date = datetime.date(current_year, 6, 14)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Calendar Month\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "17411a22",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Jan-24', 'Feb-24', 'Mar-24', 'Apr-24', 'May-24', 'Jun-24']"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Calendar Month\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b6572f6",
   "metadata": {},
   "source": [
    "### Monthly\n",
    "\n",
    "This periodicity option creates monthly bins starting from `start_date`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "5dbba314",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 15), datetime.date(2024, 2, 14)),\n",
       " (datetime.date(2024, 2, 15), datetime.date(2024, 3, 14)),\n",
       " (datetime.date(2024, 3, 15), datetime.date(2024, 4, 14)),\n",
       " (datetime.date(2024, 4, 15), datetime.date(2024, 5, 14)),\n",
       " (datetime.date(2024, 5, 15), datetime.date(2024, 6, 14))]"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 1, 15)\n",
    "end_date = datetime.date(current_year, 6, 14)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Monthly\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "84bb606c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Feb-24', 'Mar-24', 'Apr-24', 'May-24', 'Jun-24']"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Monthly\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef72db8d",
   "metadata": {},
   "source": [
    "### Calendar Quarter\n",
    "\n",
    "This periodicity option creates quarterly bins (periods of 3 months) based on the calendar year. Quarter 1 is Jan-Mar, Q2 is Apr-Jun, Q3 is Jul-Sep, and Q4 is Oct-Dec. If `start_date` doesn't fall at the beginning of the quarter, the first bin will be a stub period."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "id": "f6c01901",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 15), datetime.date(2024, 3, 31)),\n",
       " (datetime.date(2024, 4, 1), datetime.date(2024, 6, 30)),\n",
       " (datetime.date(2024, 7, 1), datetime.date(2024, 9, 30)),\n",
       " (datetime.date(2024, 10, 1), datetime.date(2024, 12, 31)),\n",
       " (datetime.date(2025, 1, 1), datetime.date(2025, 3, 31))]"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 1, 15)\n",
    "end_date = datetime.date(current_year + 1, 3, 31)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Calendar Quarter\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "id": "103aa83d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['03-24Q', '06-24Q', '09-24Q', '12-24Q', '03-25Q']"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Calendar Quarter\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d3f195c",
   "metadata": {},
   "source": [
    "### Quarterly\n",
    "\n",
    "This periodicity option creates quarterly bins (periods of 3 months) starting from `start_date`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "id": "0429ef96",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 11, 15), datetime.date(2025, 2, 14)),\n",
       " (datetime.date(2025, 2, 15), datetime.date(2025, 5, 14)),\n",
       " (datetime.date(2025, 5, 15), datetime.date(2025, 8, 14)),\n",
       " (datetime.date(2025, 8, 15), datetime.date(2025, 11, 14))]"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 11, 15)\n",
    "end_date = datetime.date(current_year + 1, 11, 14)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Quarterly\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "id": "58d7f70f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['02-25Q', '05-25Q', '08-25Q', '11-25Q']"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Quarterly\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a710e61",
   "metadata": {},
   "source": [
    "### Calendar Year\n",
    "\n",
    "This periodicity option creates calendar year bins from Jan-Dec. If `start_date` doesn't fall at the beginning of the year, the first bin will be a stub period."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "id": "ccea70a6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 1, 15), datetime.date(2024, 12, 31)),\n",
       " (datetime.date(2025, 1, 1), datetime.date(2025, 12, 31)),\n",
       " (datetime.date(2026, 1, 1), datetime.date(2026, 12, 31))]"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 1, 15)\n",
    "end_date = datetime.date(current_year + 2, 12, 31)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Calendar Year\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "id": "aec63b27",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['12/31/24', '12/31/25', '12/31/26']"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Calendar Year\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d3175e0",
   "metadata": {},
   "source": [
    "### Annually\n",
    "\n",
    "This periodicity option creates yearly bins starting from `start_date`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "id": "7553b13d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(datetime.date(2024, 7, 15), datetime.date(2025, 7, 14)),\n",
       " (datetime.date(2025, 7, 15), datetime.date(2026, 7, 14))]"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "start_date = datetime.date(current_year, 7, 15)\n",
    "end_date = datetime.date(current_year + 2, 7, 14)\n",
    "\n",
    "p = Period(start_date=start_date, end_date=end_date, periodicity=\"Annually\")\n",
    "bins = p.get_date_bins()\n",
    "bins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "id": "90fdfb1d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['07/14/25', '07/14/26']"
      ]
     },
     "execution_count": 41,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p.get_period_labels(bins, \"Annually\")"
   ]
  }
 ],
 "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}