docs/tutorials/calendar_properties.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Calendar construction and properties\n",
    "\n",
    "This tutorial covers calendar construction and offers a walk through of `ExchangeCalendar` properties (for methods see the [calendar methods](./calendar_methods.ipynb) tutorial).\n",
    "\n",
    "NB properties that _define_ a calendar (`open_times`, `special_closes_adhoc` etc) are not covered by this tutorial (see the [How can I create a new calendar](https://github.com/gerrymanoim/exchange_calendars/tree/master#how-can-i-create-a-new-calendar) section of the [README](https://github.com/gerrymanoim/exchange_calendars/tree/master))."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set up\n",
    "import exchange_calendars as xcals\n",
    "import pandas as pd\n",
    "\n",
    "hkg = xcals.get_calendar(\"XHKG\")  # Hong Kong Stock Exchange\n",
    "nys = xcals.get_calendar(\"XNYS\")  # New York Stock Exchange"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calendar construction\n",
    "\n",
    "The **`default_start`** and **`default_end`** class methods return the default calendar bounds, usually '20 years ago' and '1 year from now' respectively. These bounds represent the limits within which sessions and minutes can be interrogated and queried via the calendar's properties and methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2002-06-27 00:00:00'), Timestamp('2023-06-27 00:00:00'))"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.default_start(), nys.default_end()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `sessions` property returns all sessions covered by a calendar. The New York calendar created above can be seen to cover sessions over the period defined by the default bounds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2002-06-27', '2002-06-28', '2002-07-01', '2002-07-02',\n",
       "               '2002-07-03', '2002-07-05', '2002-07-08', '2002-07-09',\n",
       "               '2002-07-10', '2002-07-11',\n",
       "               ...\n",
       "               '2023-06-13', '2023-06-14', '2023-06-15', '2023-06-16',\n",
       "               '2023-06-20', '2023-06-21', '2023-06-22', '2023-06-23',\n",
       "               '2023-06-26', '2023-06-27'],\n",
       "              dtype='datetime64[ns]', length=5286, freq='C')"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.sessions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively the calendar bounds can be defined by passing the `start` and/or `end` parameters to `get_calendar` (or directly to a calendar class)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2020-02-19', '2020-02-20', '2020-02-21', '2020-02-24',\n",
       "               '2020-02-25', '2020-02-26', '2020-02-27', '2020-02-28',\n",
       "               '2020-03-02', '2020-03-03',\n",
       "               ...\n",
       "               '2025-12-17', '2025-12-18', '2025-12-19', '2025-12-22',\n",
       "               '2025-12-23', '2025-12-24', '2025-12-26', '2025-12-29',\n",
       "               '2025-12-30', '2025-12-31'],\n",
       "              dtype='datetime64[ns]', length=1477, freq='C')"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cal = xcals.get_calendar(\"XNYS\", start=\"2020-02-19\", end=\"2025-12-31\")\n",
    "cal.sessions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Some calendars have min and/or max bounds outside of which a calendar cannot be created. The **`bound_min`/`bound_max`** class methods return the earliest/latest date from/to which a calendar class can be constructed, or None if there is no limit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('1960-01-01 00:00:00'), Timestamp('2049-12-31 00:00:00'))"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.bound_min(), hkg.bound_max()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.bound_min() == nys.bound_max() == None"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**`valid_sides`** is a class method that returns all side values that can be passed to the constructor's `side` parameter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['both', 'left', 'right', 'neither']"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.valid_sides()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The side values available to 24 hour calendars is necessarily more limited."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['left', 'right']"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "open24 = xcals.get_calendar(\"24/7\", side=\"right\")\n",
    "open24.valid_sides()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NB the actual calendar side is returned by the **`side`** property (the default side for all calendars is \"left\")."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('left', 'right')"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.side, open24.side"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See the [minutes](./minutes.ipynb) tutorial for an explanation of how a calendar's side determines which minutes are treated as trading minutes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### General Calendar Properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'XNYS'"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<DstTzInfo 'America/New_York' LMT-1 day, 19:04:00 STD>"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.tz  # timezone"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'left'"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.side"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**`day`** returns a `CustomBusinessDay` for the calendar:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<CustomBusinessDay>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.day"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2021-12-29', '2021-12-30', '2021-12-31', '2022-01-03',\n",
       "               '2022-01-04', '2022-01-05'],\n",
       "              dtype='datetime64[ns]', freq='C')"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# for reference\n",
    "nys.sessions_in_range(\"2021-12-29\", \"2022-01-05\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Timestamp('2022-01-04 00:00:00')"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pd.Timestamp(\"2021-12-31\") + (nys.day * 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**`has_break`** queries if _any_ calendar session has a break"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.has_break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sessions and Minutes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE:** This section does little more than catalogue the calendar properties concerned with sessions or minutes. See the [sessions](./sessions.ipynb) and [minutes](./minutes.ipynb) tutorials for notes on 'working with sessions/minutes'."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### All of them"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2002-06-27', '2002-06-28', '2002-07-01', '2002-07-02',\n",
       "               '2002-07-03', '2002-07-05', '2002-07-08', '2002-07-09',\n",
       "               '2002-07-10', '2002-07-11',\n",
       "               ...\n",
       "               '2023-06-13', '2023-06-14', '2023-06-15', '2023-06-16',\n",
       "               '2023-06-20', '2023-06-21', '2023-06-22', '2023-06-23',\n",
       "               '2023-06-26', '2023-06-27'],\n",
       "              dtype='datetime64[ns]', length=5286, freq='C')"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.sessions  # DatetimeIndex representing all calendar sessions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2002-06-27 13:30:00+00:00', '2002-06-27 13:31:00+00:00',\n",
       "               '2002-06-27 13:32:00+00:00', '2002-06-27 13:33:00+00:00',\n",
       "               '2002-06-27 13:34:00+00:00', '2002-06-27 13:35:00+00:00',\n",
       "               '2002-06-27 13:36:00+00:00', '2002-06-27 13:37:00+00:00',\n",
       "               '2002-06-27 13:38:00+00:00', '2002-06-27 13:39:00+00:00',\n",
       "               ...\n",
       "               '2023-06-27 19:50:00+00:00', '2023-06-27 19:51:00+00:00',\n",
       "               '2023-06-27 19:52:00+00:00', '2023-06-27 19:53:00+00:00',\n",
       "               '2023-06-27 19:54:00+00:00', '2023-06-27 19:55:00+00:00',\n",
       "               '2023-06-27 19:56:00+00:00', '2023-06-27 19:57:00+00:00',\n",
       "               '2023-06-27 19:58:00+00:00', '2023-06-27 19:59:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=2053440, freq=None)"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.minutes  # DatetimeIndex representing every calendar trading minute"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Calendar Bounds"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2002-06-27 00:00:00', freq='C'),\n",
       " Timestamp('2023-06-27 00:00:00', freq='C'))"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_session, nys.last_session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2002-06-27 13:30:00+0000', tz='UTC'),\n",
       " Timestamp('2023-06-27 19:59:00+0000', tz='UTC'))"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_minute, nys.last_minute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2002-06-27 13:30:00+0000', tz='UTC'),\n",
       " Timestamp('2023-06-27 20:00:00+0000', tz='UTC'))"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_session_open, nys.last_session_close"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Schedule (open, close and break times)"
   ]
  },
  {
   "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>open</th>\n",
       "      <th>break_start</th>\n",
       "      <th>break_end</th>\n",
       "      <th>close</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2002-06-27</th>\n",
       "      <td>2002-06-27 02:00:00+00:00</td>\n",
       "      <td>2002-06-27 04:00:00+00:00</td>\n",
       "      <td>2002-06-27 05:00:00+00:00</td>\n",
       "      <td>2002-06-27 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2002-06-28</th>\n",
       "      <td>2002-06-28 02:00:00+00:00</td>\n",
       "      <td>2002-06-28 04:00:00+00:00</td>\n",
       "      <td>2002-06-28 05:00:00+00:00</td>\n",
       "      <td>2002-06-28 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2002-07-02</th>\n",
       "      <td>2002-07-02 02:00:00+00:00</td>\n",
       "      <td>2002-07-02 04:00:00+00:00</td>\n",
       "      <td>2002-07-02 05:00:00+00:00</td>\n",
       "      <td>2002-07-02 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2002-07-03</th>\n",
       "      <td>2002-07-03 02:00:00+00:00</td>\n",
       "      <td>2002-07-03 04:00:00+00:00</td>\n",
       "      <td>2002-07-03 05:00:00+00:00</td>\n",
       "      <td>2002-07-03 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2002-07-04</th>\n",
       "      <td>2002-07-04 02:00:00+00:00</td>\n",
       "      <td>2002-07-04 04:00:00+00:00</td>\n",
       "      <td>2002-07-04 05:00:00+00:00</td>\n",
       "      <td>2002-07-04 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-06-20</th>\n",
       "      <td>2023-06-20 01:30:00+00:00</td>\n",
       "      <td>2023-06-20 04:00:00+00:00</td>\n",
       "      <td>2023-06-20 05:00:00+00:00</td>\n",
       "      <td>2023-06-20 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-06-21</th>\n",
       "      <td>2023-06-21 01:30:00+00:00</td>\n",
       "      <td>2023-06-21 04:00:00+00:00</td>\n",
       "      <td>2023-06-21 05:00:00+00:00</td>\n",
       "      <td>2023-06-21 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-06-23</th>\n",
       "      <td>2023-06-23 01:30:00+00:00</td>\n",
       "      <td>2023-06-23 04:00:00+00:00</td>\n",
       "      <td>2023-06-23 05:00:00+00:00</td>\n",
       "      <td>2023-06-23 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-06-26</th>\n",
       "      <td>2023-06-26 01:30:00+00:00</td>\n",
       "      <td>2023-06-26 04:00:00+00:00</td>\n",
       "      <td>2023-06-26 05:00:00+00:00</td>\n",
       "      <td>2023-06-26 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2023-06-27</th>\n",
       "      <td>2023-06-27 01:30:00+00:00</td>\n",
       "      <td>2023-06-27 04:00:00+00:00</td>\n",
       "      <td>2023-06-27 05:00:00+00:00</td>\n",
       "      <td>2023-06-27 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5182 rows × 4 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                                open               break_start  \\\n",
       "2002-06-27 2002-06-27 02:00:00+00:00 2002-06-27 04:00:00+00:00   \n",
       "2002-06-28 2002-06-28 02:00:00+00:00 2002-06-28 04:00:00+00:00   \n",
       "2002-07-02 2002-07-02 02:00:00+00:00 2002-07-02 04:00:00+00:00   \n",
       "2002-07-03 2002-07-03 02:00:00+00:00 2002-07-03 04:00:00+00:00   \n",
       "2002-07-04 2002-07-04 02:00:00+00:00 2002-07-04 04:00:00+00:00   \n",
       "...                              ...                       ...   \n",
       "2023-06-20 2023-06-20 01:30:00+00:00 2023-06-20 04:00:00+00:00   \n",
       "2023-06-21 2023-06-21 01:30:00+00:00 2023-06-21 04:00:00+00:00   \n",
       "2023-06-23 2023-06-23 01:30:00+00:00 2023-06-23 04:00:00+00:00   \n",
       "2023-06-26 2023-06-26 01:30:00+00:00 2023-06-26 04:00:00+00:00   \n",
       "2023-06-27 2023-06-27 01:30:00+00:00 2023-06-27 04:00:00+00:00   \n",
       "\n",
       "                           break_end                     close  \n",
       "2002-06-27 2002-06-27 05:00:00+00:00 2002-06-27 08:00:00+00:00  \n",
       "2002-06-28 2002-06-28 05:00:00+00:00 2002-06-28 08:00:00+00:00  \n",
       "2002-07-02 2002-07-02 05:00:00+00:00 2002-07-02 08:00:00+00:00  \n",
       "2002-07-03 2002-07-03 05:00:00+00:00 2002-07-03 08:00:00+00:00  \n",
       "2002-07-04 2002-07-04 05:00:00+00:00 2002-07-04 08:00:00+00:00  \n",
       "...                              ...                       ...  \n",
       "2023-06-20 2023-06-20 05:00:00+00:00 2023-06-20 08:00:00+00:00  \n",
       "2023-06-21 2023-06-21 05:00:00+00:00 2023-06-21 08:00:00+00:00  \n",
       "2023-06-23 2023-06-23 05:00:00+00:00 2023-06-23 08:00:00+00:00  \n",
       "2023-06-26 2023-06-26 05:00:00+00:00 2023-06-26 08:00:00+00:00  \n",
       "2023-06-27 2023-06-27 05:00:00+00:00 2023-06-27 08:00:00+00:00  \n",
       "\n",
       "[5182 rows x 4 columns]"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sch = hkg.schedule\n",
    "sch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The schedule is a pandas DataFrame. It shows the dates the exchange is open and describes the bounds when the exchange is open for regular trading on each of those dates.\n",
    "\n",
    "The index represents the calendar's sessions as a timezone-naive pandas `DatetimeIndex`. For each session, the columns offer the open, close and, if applicable, break-start and break-end time. **The times are defined in UTC terms** and columns have dtype as `datetime64[ns, UTC]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2002-06-27   2002-06-27 02:00:00+00:00\n",
       "2002-06-28   2002-06-28 02:00:00+00:00\n",
       "2002-07-02   2002-07-02 02:00:00+00:00\n",
       "2002-07-03   2002-07-03 02:00:00+00:00\n",
       "2002-07-04   2002-07-04 02:00:00+00:00\n",
       "                        ...           \n",
       "2023-06-20   2023-06-20 01:30:00+00:00\n",
       "2023-06-21   2023-06-21 01:30:00+00:00\n",
       "2023-06-23   2023-06-23 01:30:00+00:00\n",
       "2023-06-26   2023-06-26 01:30:00+00:00\n",
       "2023-06-27   2023-06-27 01:30:00+00:00\n",
       "Freq: C, Name: open, Length: 5182, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sch.open"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The break_start/break_end columns take `pd.NaT` in the event that a session does not have a break."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "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>open</th>\n",
       "      <th>break_start</th>\n",
       "      <th>break_end</th>\n",
       "      <th>close</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2021-12-23</th>\n",
       "      <td>2021-12-23 01:30:00+00:00</td>\n",
       "      <td>2021-12-23 04:00:00+00:00</td>\n",
       "      <td>2021-12-23 05:00:00+00:00</td>\n",
       "      <td>2021-12-23 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2021-12-24</th>\n",
       "      <td>2021-12-24 01:30:00+00:00</td>\n",
       "      <td>NaT</td>\n",
       "      <td>NaT</td>\n",
       "      <td>2021-12-24 04:00:00+00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2021-12-28</th>\n",
       "      <td>2021-12-28 01:30:00+00:00</td>\n",
       "      <td>2021-12-28 04:00:00+00:00</td>\n",
       "      <td>2021-12-28 05:00:00+00:00</td>\n",
       "      <td>2021-12-28 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                open               break_start  \\\n",
       "2021-12-23 2021-12-23 01:30:00+00:00 2021-12-23 04:00:00+00:00   \n",
       "2021-12-24 2021-12-24 01:30:00+00:00                       NaT   \n",
       "2021-12-28 2021-12-28 01:30:00+00:00 2021-12-28 04:00:00+00:00   \n",
       "\n",
       "                           break_end                     close  \n",
       "2021-12-23 2021-12-23 05:00:00+00:00 2021-12-23 08:00:00+00:00  \n",
       "2021-12-24                       NaT 2021-12-24 04:00:00+00:00  \n",
       "2021-12-28 2021-12-28 05:00:00+00:00 2021-12-28 08:00:00+00:00  "
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.schedule.loc[\"2021-12-23\":\"2021-12-28\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The calendar properties **`opens`**, **`closes`**, **`break_starts`** and **`break_ends`** return the corresponding column of the schedule as a `pd.Series`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2002-06-27   2002-06-27 02:00:00+00:00\n",
       "2002-06-28   2002-06-28 02:00:00+00:00\n",
       "2002-07-02   2002-07-02 02:00:00+00:00\n",
       "2002-07-03   2002-07-03 02:00:00+00:00\n",
       "2002-07-04   2002-07-04 02:00:00+00:00\n",
       "                        ...           \n",
       "2023-06-20   2023-06-20 01:30:00+00:00\n",
       "2023-06-21   2023-06-21 01:30:00+00:00\n",
       "2023-06-23   2023-06-23 01:30:00+00:00\n",
       "2023-06-26   2023-06-26 01:30:00+00:00\n",
       "2023-06-27   2023-06-27 01:30:00+00:00\n",
       "Freq: C, Name: open, Length: 5182, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.opens"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2021-12-23   2021-12-23 08:00:00+00:00\n",
       "2021-12-24   2021-12-24 04:00:00+00:00\n",
       "2021-12-28   2021-12-28 08:00:00+00:00\n",
       "Freq: C, Name: close, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.closes[\"2021-12-23\":\"2021-12-28\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **`late_opens`** and **`early_closes`** properties return a `DatetimeIndex` of those sessions that have a later open/earlier close than the prevailing regular open/close time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2018-07-03', '2018-11-23', '2018-12-24', '2019-07-03',\n",
       "               '2019-11-29', '2019-12-24', '2020-11-27', '2020-12-24',\n",
       "               '2021-11-26', '2022-11-25'],\n",
       "              dtype='datetime64[ns]', freq=None)"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.early_closes[-10:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Bound Trading Minutes by-sessions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **`first_*`** and **`last_*`** methods return `pd.Series` with index as `sessions` and value as the corresponding trading minute (UTC) for the session. NB As explained in the [minutes tutorial](./minutes.ipynb), these minutes are not necessarily the same as the session open/close/break times."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2002-06-27   2002-06-27 13:30:00+00:00\n",
       "2002-06-28   2002-06-28 13:30:00+00:00\n",
       "2002-07-01   2002-07-01 13:30:00+00:00\n",
       "2002-07-02   2002-07-02 13:30:00+00:00\n",
       "2002-07-03   2002-07-03 13:30:00+00:00\n",
       "                        ...           \n",
       "2023-06-21   2023-06-21 13:30:00+00:00\n",
       "2023-06-22   2023-06-22 13:30:00+00:00\n",
       "2023-06-23   2023-06-23 13:30:00+00:00\n",
       "2023-06-26   2023-06-26 13:30:00+00:00\n",
       "2023-06-27   2023-06-27 13:30:00+00:00\n",
       "Freq: C, Name: first_minutes, Length: 5286, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_minutes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2002-06-27   2002-06-27 19:59:00+00:00\n",
       "2002-06-28   2002-06-28 19:59:00+00:00\n",
       "2002-07-01   2002-07-01 19:59:00+00:00\n",
       "2002-07-02   2002-07-02 19:59:00+00:00\n",
       "2002-07-03   2002-07-03 19:59:00+00:00\n",
       "                        ...           \n",
       "2023-06-21   2023-06-21 19:59:00+00:00\n",
       "2023-06-22   2023-06-22 19:59:00+00:00\n",
       "2023-06-23   2023-06-23 19:59:00+00:00\n",
       "2023-06-26   2023-06-26 19:59:00+00:00\n",
       "2023-06-27   2023-06-27 19:59:00+00:00\n",
       "Freq: C, Name: last_minutes, Length: 5286, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.last_minutes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2002-06-27   2002-06-27 15:59:00-04:00\n",
       "2002-06-28   2002-06-28 15:59:00-04:00\n",
       "2002-07-01   2002-07-01 15:59:00-04:00\n",
       "2002-07-02   2002-07-02 15:59:00-04:00\n",
       "2002-07-03   2002-07-03 15:59:00-04:00\n",
       "                        ...           \n",
       "2023-06-21   2023-06-21 15:59:00-04:00\n",
       "2023-06-22   2023-06-22 15:59:00-04:00\n",
       "2023-06-23   2023-06-23 15:59:00-04:00\n",
       "2023-06-26   2023-06-26 15:59:00-04:00\n",
       "2023-06-27   2023-06-27 15:59:00-04:00\n",
       "Freq: C, Name: last_minutes, Length: 5286, dtype: datetime64[ns, America/New_York]"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# in terms of local times...\n",
    "nys.last_minutes.dt.tz_convert(nys.tz)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2021-12-23   2021-12-23 03:59:00+00:00\n",
       "2021-12-24                         NaT\n",
       "2021-12-28   2021-12-28 03:59:00+00:00\n",
       "Freq: C, Name: last_am_minutes, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# last pre-break minute of am subsession\n",
    "hkg.last_am_minutes[\"2021-12-23\":\"2021-12-28\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2021-12-23   2021-12-23 05:00:00+00:00\n",
       "2021-12-24                         NaT\n",
       "2021-12-28   2021-12-28 05:00:00+00:00\n",
       "Freq: C, Name: first_pm_minutes, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# first post-break minute of pm subsession\n",
    "hkg.first_pm_minutes.loc[\"2021-12-23\":\"2021-12-28\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2021-12-23   2021-12-23 13:00:00+08:00\n",
       "2021-12-24                         NaT\n",
       "2021-12-28   2021-12-28 13:00:00+08:00\n",
       "Freq: C, Name: first_pm_minutes, dtype: datetime64[ns, Asia/Hong_Kong]"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# in local time...\n",
    "hkg.first_pm_minutes.loc[\"2021-12-23\":\"2021-12-28\"].dt.tz_convert(hkg.tz)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Nanos\n",
    "\n",
    "Many sessions/minutes properties that return a `DatetimeIndex` have a 'nanos' equivalent that returns a numpy ndarray of integers.\n",
    "\n",
    "Why? Internally `ExchangeCalendar` uses these nano arrays because they are faster to operate on than `DatetimeIndex`. Indeed, for some operations, working with nanos can be **much** faster."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1025136000000000000, 1025222400000000000, 1025568000000000000, ...,\n",
       "        1687478400000000000, 1687737600000000000, 1687824000000000000],\n",
       "       dtype=int64),\n",
       " array([1025143200000000000, 1025143260000000000, 1025143320000000000, ...,\n",
       "        1687852620000000000, 1687852680000000000, 1687852740000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.sessions_nanos, hkg.minutes_nanos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1025143200000000000, 1025229600000000000, 1025575200000000000, ...,\n",
       "        1687483800000000000, 1687743000000000000, 1687829400000000000],\n",
       "       dtype=int64),\n",
       " array([1025164800000000000, 1025251200000000000, 1025596800000000000, ...,\n",
       "        1687507200000000000, 1687766400000000000, 1687852800000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.opens_nanos, hkg.closes_nanos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1025150400000000000, 1025236800000000000, 1025582400000000000, ...,\n",
       "        1687492800000000000, 1687752000000000000, 1687838400000000000],\n",
       "       dtype=int64),\n",
       " array([1025154000000000000, 1025240400000000000, 1025586000000000000, ...,\n",
       "        1687496400000000000, 1687755600000000000, 1687842000000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.break_starts_nanos, hkg.break_ends_nanos, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1025143200000000000, 1025229600000000000, 1025575200000000000, ...,\n",
       "        1687483800000000000, 1687743000000000000, 1687829400000000000],\n",
       "       dtype=int64),\n",
       " array([1025164740000000000, 1025251140000000000, 1025596740000000000, ...,\n",
       "        1687507140000000000, 1687766340000000000, 1687852740000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.first_minutes_nanos, hkg.last_minutes_nanos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1025150340000000000, 1025236740000000000, 1025582340000000000, ...,\n",
       "        1687492740000000000, 1687751940000000000, 1687838340000000000],\n",
       "       dtype=int64),\n",
       " array([1025154000000000000, 1025240400000000000, 1025586000000000000, ...,\n",
       "        1687496400000000000, 1687755600000000000, 1687842000000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.last_am_minutes_nanos, hkg.first_pm_minutes_nanos"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python38 xcals",
   "language": "python",
   "name": "py38_xcals"
  },
  "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.10"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}