docs/tutorials/calendar_properties.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Calendar properties"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial 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": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set up\n",
    "import exchange_calendars as xcals\n",
    "import pandas as pd\n",
    "\n",
    "hkg = xcals.get_calendar(\"XHKG\", side=\"left\")  # Hong Kong Stock Exchange\n",
    "nys = xcals.get_calendar(\"XNYS\", side=\"left\")  # New York Stock Exchange"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calendar construction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The **`bound_*`** properties 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": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('1960-01-01 00:00:00+0000', tz='UTC'),\n",
       " Timestamp('2049-12-31 00:00:00+0000', tz='UTC'))"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.bound_start, hkg.bound_end"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.bound_start == nys.bound_end == None"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**`default_start`**/**`default_end`** return the dates from/to which a calendar will be created if the `start`/`end` parameters are not passed to the constructor (unless limited by the bounds, the defaults are '20 years ago' / '1 year from now'):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2001-10-22 00:00:00+0000', tz='UTC'),\n",
       " Timestamp('2022-10-22 00:00:00+0000', tz='UTC'))"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.default_start, nys.default_end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**`default_side`** is a class method that returns the calendar's default side in the event `side` is not otherwise passed to the constructor. By default 24-hour calendars are side \"right\" and all others side \"both\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('right', 'both')"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "open24 = xcals.get_calendar(\"24/7\")\n",
    "open24.default_side(), nys.default_side()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NB the actual calendar side is returned by the **`side`** property."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('both', 'left')"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.default_side(), nys.side"
   ]
  },
  {
   "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": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['both', 'left', 'right', 'neither']"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.valid_sides()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['left', 'right']"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "open24.valid_sides()"
   ]
  },
  {
   "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": [
       "DatetimeIndex(['2020-12-29 00:00:00+00:00', '2020-12-30 00:00:00+00:00',\n",
       "               '2020-12-31 00:00:00+00:00', '2021-01-04 00:00:00+00:00',\n",
       "               '2021-01-05 00:00:00+00:00', '2021-01-06 00:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq='C')"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# for reference\n",
    "nys.sessions_in_range(\"2020-12-29\", \"2021-01-06\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Timestamp('2021-01-05 00:00:00')"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pd.Timestamp(\"2020-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": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 15,
     "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": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2001-10-22 00:00:00+00:00', '2001-10-23 00:00:00+00:00',\n",
       "               '2001-10-24 00:00:00+00:00', '2001-10-25 00:00:00+00:00',\n",
       "               '2001-10-26 00:00:00+00:00', '2001-10-29 00:00:00+00:00',\n",
       "               '2001-10-30 00:00:00+00:00', '2001-10-31 00:00:00+00:00',\n",
       "               '2001-11-01 00:00:00+00:00', '2001-11-02 00:00:00+00:00',\n",
       "               ...\n",
       "               '2022-10-10 00:00:00+00:00', '2022-10-11 00:00:00+00:00',\n",
       "               '2022-10-12 00:00:00+00:00', '2022-10-13 00:00:00+00:00',\n",
       "               '2022-10-14 00:00:00+00:00', '2022-10-17 00:00:00+00:00',\n",
       "               '2022-10-18 00:00:00+00:00', '2022-10-19 00:00:00+00:00',\n",
       "               '2022-10-20 00:00:00+00:00', '2022-10-21 00:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=5289, freq='C')"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.sessions  # DatetimeIndex representing all calendar sessions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2001-10-22 13:30:00+00:00', '2001-10-22 13:31:00+00:00',\n",
       "               '2001-10-22 13:32:00+00:00', '2001-10-22 13:33:00+00:00',\n",
       "               '2001-10-22 13:34:00+00:00', '2001-10-22 13:35:00+00:00',\n",
       "               '2001-10-22 13:36:00+00:00', '2001-10-22 13:37:00+00:00',\n",
       "               '2001-10-22 13:38:00+00:00', '2001-10-22 13:39:00+00:00',\n",
       "               ...\n",
       "               '2022-10-21 19:50:00+00:00', '2022-10-21 19:51:00+00:00',\n",
       "               '2022-10-21 19:52:00+00:00', '2022-10-21 19:53:00+00:00',\n",
       "               '2022-10-21 19:54:00+00:00', '2022-10-21 19:55:00+00:00',\n",
       "               '2022-10-21 19:56:00+00:00', '2022-10-21 19:57:00+00:00',\n",
       "               '2022-10-21 19:58:00+00:00', '2022-10-21 19:59:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=2054430, freq=None)"
      ]
     },
     "execution_count": 17,
     "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": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2001-10-22 00:00:00+0000', tz='UTC', freq='C'),\n",
       " Timestamp('2022-10-21 00:00:00+0000', tz='UTC', freq='C'))"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_session, nys.last_session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2001-10-22 13:30:00+0000', tz='UTC'),\n",
       " Timestamp('2022-10-21 19:59:00+0000', tz='UTC'))"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_minute, nys.last_minute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Timestamp('2001-10-22 13:30:00'), Timestamp('2022-10-21 20:00:00'))"
      ]
     },
     "execution_count": 20,
     "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": 21,
   "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>market_open</th>\n",
       "      <th>break_start</th>\n",
       "      <th>break_end</th>\n",
       "      <th>market_close</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2001-10-22 00:00:00+00:00</th>\n",
       "      <td>2001-10-22 02:00:00</td>\n",
       "      <td>2001-10-22 04:00:00</td>\n",
       "      <td>2001-10-22 05:00:00</td>\n",
       "      <td>2001-10-22 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2001-10-23 00:00:00+00:00</th>\n",
       "      <td>2001-10-23 02:00:00</td>\n",
       "      <td>2001-10-23 04:00:00</td>\n",
       "      <td>2001-10-23 05:00:00</td>\n",
       "      <td>2001-10-23 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2001-10-24 00:00:00+00:00</th>\n",
       "      <td>2001-10-24 02:00:00</td>\n",
       "      <td>2001-10-24 04:00:00</td>\n",
       "      <td>2001-10-24 05:00:00</td>\n",
       "      <td>2001-10-24 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2001-10-26 00:00:00+00:00</th>\n",
       "      <td>2001-10-26 02:00:00</td>\n",
       "      <td>2001-10-26 04:00:00</td>\n",
       "      <td>2001-10-26 05:00:00</td>\n",
       "      <td>2001-10-26 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2001-10-29 00:00:00+00:00</th>\n",
       "      <td>2001-10-29 02:00:00</td>\n",
       "      <td>2001-10-29 04:00:00</td>\n",
       "      <td>2001-10-29 05:00:00</td>\n",
       "      <td>2001-10-29 08: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>2022-10-17 00:00:00+00:00</th>\n",
       "      <td>2022-10-17 01:30:00</td>\n",
       "      <td>2022-10-17 04:00:00</td>\n",
       "      <td>2022-10-17 05:00:00</td>\n",
       "      <td>2022-10-17 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-10-18 00:00:00+00:00</th>\n",
       "      <td>2022-10-18 01:30:00</td>\n",
       "      <td>2022-10-18 04:00:00</td>\n",
       "      <td>2022-10-18 05:00:00</td>\n",
       "      <td>2022-10-18 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-10-19 00:00:00+00:00</th>\n",
       "      <td>2022-10-19 01:30:00</td>\n",
       "      <td>2022-10-19 04:00:00</td>\n",
       "      <td>2022-10-19 05:00:00</td>\n",
       "      <td>2022-10-19 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-10-20 00:00:00+00:00</th>\n",
       "      <td>2022-10-20 01:30:00</td>\n",
       "      <td>2022-10-20 04:00:00</td>\n",
       "      <td>2022-10-20 05:00:00</td>\n",
       "      <td>2022-10-20 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2022-10-21 00:00:00+00:00</th>\n",
       "      <td>2022-10-21 01:30:00</td>\n",
       "      <td>2022-10-21 04:00:00</td>\n",
       "      <td>2022-10-21 05:00:00</td>\n",
       "      <td>2022-10-21 08:00:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5184 rows × 4 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "                                  market_open         break_start  \\\n",
       "2001-10-22 00:00:00+00:00 2001-10-22 02:00:00 2001-10-22 04:00:00   \n",
       "2001-10-23 00:00:00+00:00 2001-10-23 02:00:00 2001-10-23 04:00:00   \n",
       "2001-10-24 00:00:00+00:00 2001-10-24 02:00:00 2001-10-24 04:00:00   \n",
       "2001-10-26 00:00:00+00:00 2001-10-26 02:00:00 2001-10-26 04:00:00   \n",
       "2001-10-29 00:00:00+00:00 2001-10-29 02:00:00 2001-10-29 04:00:00   \n",
       "...                                       ...                 ...   \n",
       "2022-10-17 00:00:00+00:00 2022-10-17 01:30:00 2022-10-17 04:00:00   \n",
       "2022-10-18 00:00:00+00:00 2022-10-18 01:30:00 2022-10-18 04:00:00   \n",
       "2022-10-19 00:00:00+00:00 2022-10-19 01:30:00 2022-10-19 04:00:00   \n",
       "2022-10-20 00:00:00+00:00 2022-10-20 01:30:00 2022-10-20 04:00:00   \n",
       "2022-10-21 00:00:00+00:00 2022-10-21 01:30:00 2022-10-21 04:00:00   \n",
       "\n",
       "                                    break_end        market_close  \n",
       "2001-10-22 00:00:00+00:00 2001-10-22 05:00:00 2001-10-22 08:00:00  \n",
       "2001-10-23 00:00:00+00:00 2001-10-23 05:00:00 2001-10-23 08:00:00  \n",
       "2001-10-24 00:00:00+00:00 2001-10-24 05:00:00 2001-10-24 08:00:00  \n",
       "2001-10-26 00:00:00+00:00 2001-10-26 05:00:00 2001-10-26 08:00:00  \n",
       "2001-10-29 00:00:00+00:00 2001-10-29 05:00:00 2001-10-29 08:00:00  \n",
       "...                                       ...                 ...  \n",
       "2022-10-17 00:00:00+00:00 2022-10-17 05:00:00 2022-10-17 08:00:00  \n",
       "2022-10-18 00:00:00+00:00 2022-10-18 05:00:00 2022-10-18 08:00:00  \n",
       "2022-10-19 00:00:00+00:00 2022-10-19 05:00:00 2022-10-19 08:00:00  \n",
       "2022-10-20 00:00:00+00:00 2022-10-20 05:00:00 2022-10-20 08:00:00  \n",
       "2022-10-21 00:00:00+00:00 2022-10-21 05:00:00 2022-10-21 08:00:00  \n",
       "\n",
       "[5184 rows x 4 columns]"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.schedule"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The schedule is a pandas DataFrame. It shows the days the exchange is open and describes the bounds when the exchange is open for regular trading on each of those days.\n",
    "\n",
    "The index represents the calendar's sessions as a pandas DatetimeIndex with timezone as UTC. 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 although the actual columns' DatetimeIndex are tz-naive**.\n",
    "\n",
    "**NB It's proposed that from version 4.0 the timezone of the columns' DatetimeIndex will be set to \"UTC\" whilst the index will become tz-naive.** Have your say [here](https://github.com/gerrymanoim/exchange_calendars/issues/42).\n",
    "\n",
    "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": 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>market_open</th>\n",
       "      <th>break_start</th>\n",
       "      <th>break_end</th>\n",
       "      <th>market_close</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2020-12-23 00:00:00+00:00</th>\n",
       "      <td>2020-12-23 01:30:00</td>\n",
       "      <td>2020-12-23 04:00:00</td>\n",
       "      <td>2020-12-23 05:00:00</td>\n",
       "      <td>2020-12-23 08:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2020-12-24 00:00:00+00:00</th>\n",
       "      <td>2020-12-24 01:30:00</td>\n",
       "      <td>NaT</td>\n",
       "      <td>NaT</td>\n",
       "      <td>2020-12-24 04:00:00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2020-12-28 00:00:00+00:00</th>\n",
       "      <td>2020-12-28 01:30:00</td>\n",
       "      <td>2020-12-28 04:00:00</td>\n",
       "      <td>2020-12-28 05:00:00</td>\n",
       "      <td>2020-12-28 08:00:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                  market_open         break_start  \\\n",
       "2020-12-23 00:00:00+00:00 2020-12-23 01:30:00 2020-12-23 04:00:00   \n",
       "2020-12-24 00:00:00+00:00 2020-12-24 01:30:00                 NaT   \n",
       "2020-12-28 00:00:00+00:00 2020-12-28 01:30:00 2020-12-28 04:00:00   \n",
       "\n",
       "                                    break_end        market_close  \n",
       "2020-12-23 00:00:00+00:00 2020-12-23 05:00:00 2020-12-23 08:00:00  \n",
       "2020-12-24 00:00:00+00:00                 NaT 2020-12-24 04:00:00  \n",
       "2020-12-28 00:00:00+00:00 2020-12-28 05:00:00 2020-12-28 08:00:00  "
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.schedule.loc[\"2020-12-23\":\"2020-12-28\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The properties **`opens`**, **`closes`**, **`break_starts`** and **`break_ends`** return the corresponding column of the schedule as a pd.Series."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2001-10-22 00:00:00+00:00   2001-10-22 02:00:00\n",
       "2001-10-23 00:00:00+00:00   2001-10-23 02:00:00\n",
       "2001-10-24 00:00:00+00:00   2001-10-24 02:00:00\n",
       "2001-10-26 00:00:00+00:00   2001-10-26 02:00:00\n",
       "2001-10-29 00:00:00+00:00   2001-10-29 02:00:00\n",
       "                                    ...        \n",
       "2022-10-17 00:00:00+00:00   2022-10-17 01:30:00\n",
       "2022-10-18 00:00:00+00:00   2022-10-18 01:30:00\n",
       "2022-10-19 00:00:00+00:00   2022-10-19 01:30:00\n",
       "2022-10-20 00:00:00+00:00   2022-10-20 01:30:00\n",
       "2022-10-21 00:00:00+00:00   2022-10-21 01:30:00\n",
       "Freq: C, Name: market_open, Length: 5184, dtype: datetime64[ns]"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.opens"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As for the schedule, **although these times are defined in terms of UTC, the properties are tz-naive** (again, it's anticipated that from version 4.0 the timezone of these properties will be set to \"UTC\", see [#42](https://github.com/gerrymanoim/exchange_calendars/issues/42))."
   ]
  },
  {
   "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": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2017-11-24 00:00:00+00:00', '2018-07-03 00:00:00+00:00',\n",
       "               '2018-11-23 00:00:00+00:00', '2018-12-24 00:00:00+00:00',\n",
       "               '2019-07-03 00:00:00+00:00', '2019-11-29 00:00:00+00:00',\n",
       "               '2019-12-24 00:00:00+00:00', '2020-11-27 00:00:00+00:00',\n",
       "               '2020-12-24 00:00:00+00:00', '2021-11-26 00:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq=None)"
      ]
     },
     "execution_count": 24,
     "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": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2001-10-22 00:00:00+00:00   2001-10-22 13:30:00+00:00\n",
       "2001-10-23 00:00:00+00:00   2001-10-23 13:30:00+00:00\n",
       "2001-10-24 00:00:00+00:00   2001-10-24 13:30:00+00:00\n",
       "2001-10-25 00:00:00+00:00   2001-10-25 13:30:00+00:00\n",
       "2001-10-26 00:00:00+00:00   2001-10-26 13:30:00+00:00\n",
       "                                       ...           \n",
       "2022-10-17 00:00:00+00:00   2022-10-17 13:30:00+00:00\n",
       "2022-10-18 00:00:00+00:00   2022-10-18 13:30:00+00:00\n",
       "2022-10-19 00:00:00+00:00   2022-10-19 13:30:00+00:00\n",
       "2022-10-20 00:00:00+00:00   2022-10-20 13:30:00+00:00\n",
       "2022-10-21 00:00:00+00:00   2022-10-21 13:30:00+00:00\n",
       "Freq: C, Name: first_minutes, Length: 5289, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.first_minutes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2001-10-22 00:00:00+00:00   2001-10-22 19:59:00+00:00\n",
       "2001-10-23 00:00:00+00:00   2001-10-23 19:59:00+00:00\n",
       "2001-10-24 00:00:00+00:00   2001-10-24 19:59:00+00:00\n",
       "2001-10-25 00:00:00+00:00   2001-10-25 19:59:00+00:00\n",
       "2001-10-26 00:00:00+00:00   2001-10-26 19:59:00+00:00\n",
       "                                       ...           \n",
       "2022-10-17 00:00:00+00:00   2022-10-17 19:59:00+00:00\n",
       "2022-10-18 00:00:00+00:00   2022-10-18 19:59:00+00:00\n",
       "2022-10-19 00:00:00+00:00   2022-10-19 19:59:00+00:00\n",
       "2022-10-20 00:00:00+00:00   2022-10-20 19:59:00+00:00\n",
       "2022-10-21 00:00:00+00:00   2022-10-21 19:59:00+00:00\n",
       "Freq: C, Name: last_minutes, Length: 5289, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.last_minutes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2001-10-22 00:00:00+00:00   2001-10-22 15:59:00-04:00\n",
       "2001-10-23 00:00:00+00:00   2001-10-23 15:59:00-04:00\n",
       "2001-10-24 00:00:00+00:00   2001-10-24 15:59:00-04:00\n",
       "2001-10-25 00:00:00+00:00   2001-10-25 15:59:00-04:00\n",
       "2001-10-26 00:00:00+00:00   2001-10-26 15:59:00-04:00\n",
       "                                       ...           \n",
       "2022-10-17 00:00:00+00:00   2022-10-17 15:59:00-04:00\n",
       "2022-10-18 00:00:00+00:00   2022-10-18 15:59:00-04:00\n",
       "2022-10-19 00:00:00+00:00   2022-10-19 15:59:00-04:00\n",
       "2022-10-20 00:00:00+00:00   2022-10-20 15:59:00-04:00\n",
       "2022-10-21 00:00:00+00:00   2022-10-21 15:59:00-04:00\n",
       "Freq: C, Name: last_minutes, Length: 5289, dtype: datetime64[ns, America/New_York]"
      ]
     },
     "execution_count": 27,
     "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": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2020-12-23 00:00:00+00:00   2020-12-23 03:59:00+00:00\n",
       "2020-12-24 00:00:00+00:00                         NaT\n",
       "2020-12-28 00:00:00+00:00   2020-12-28 03:59:00+00:00\n",
       "Freq: C, Name: last_am_minutes, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# last pre-break minute of am subsession\n",
    "hkg.last_am_minutes[\"2020-12-23\":\"2020-12-28\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2020-12-23 00:00:00+00:00   2020-12-23 05:00:00+00:00\n",
       "2020-12-24 00:00:00+00:00                         NaT\n",
       "2020-12-28 00:00:00+00:00   2020-12-28 05:00:00+00:00\n",
       "Freq: C, Name: first_pm_minutes, dtype: datetime64[ns, UTC]"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# first post-break minute of pm subsession\n",
    "hkg.first_pm_minutes.loc[\"2020-12-23\":\"2020-12-28\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2020-12-23 00:00:00+00:00   2020-12-23 13:00:00+08:00\n",
       "2020-12-24 00:00:00+00:00                         NaT\n",
       "2020-12-28 00:00:00+00:00   2020-12-28 13:00:00+08:00\n",
       "Freq: C, Name: first_pm_minutes, dtype: datetime64[ns, Asia/Hong_Kong]"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# in local time...\n",
    "hkg.first_pm_minutes.loc[\"2020-12-23\":\"2020-12-28\"].dt.tz_convert(hkg.tz)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Nanos"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1003708800000000000, 1003795200000000000, 1003881600000000000, ...,\n",
       "        1666137600000000000, 1666224000000000000, 1666310400000000000],\n",
       "       dtype=int64),\n",
       " array([1003716000000000000, 1003716060000000000, 1003716120000000000, ...,\n",
       "        1666339020000000000, 1666339080000000000, 1666339140000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.sessions_nanos, hkg.minutes_nanos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1003716000000000000, 1003802400000000000, 1003888800000000000, ...,\n",
       "        1666143000000000000, 1666229400000000000, 1666315800000000000],\n",
       "       dtype=int64),\n",
       " array([1003737600000000000, 1003824000000000000, 1003910400000000000, ...,\n",
       "        1666166400000000000, 1666252800000000000, 1666339200000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.opens_nanos, hkg.closes_nanos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1003723200000000000, 1003809600000000000, 1003896000000000000, ...,\n",
       "        1666152000000000000, 1666238400000000000, 1666324800000000000],\n",
       "       dtype=int64),\n",
       " array([1003726800000000000, 1003813200000000000, 1003899600000000000, ...,\n",
       "        1666155600000000000, 1666242000000000000, 1666328400000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.break_starts_nanos, hkg.break_ends_nanos, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1003716000000000000, 1003802400000000000, 1003888800000000000, ...,\n",
       "        1666143000000000000, 1666229400000000000, 1666315800000000000],\n",
       "       dtype=int64),\n",
       " array([1003737540000000000, 1003823940000000000, 1003910340000000000, ...,\n",
       "        1666166340000000000, 1666252740000000000, 1666339140000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.first_minutes_nanos, hkg.last_minutes_nanos"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(array([1003723140000000000, 1003809540000000000, 1003895940000000000, ...,\n",
       "        1666151940000000000, 1666238340000000000, 1666324740000000000],\n",
       "       dtype=int64),\n",
       " array([1003726800000000000, 1003813200000000000, 1003899600000000000, ...,\n",
       "        1666155600000000000, 1666242000000000000, 1666328400000000000],\n",
       "       dtype=int64))"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg.last_am_minutes_nanos, hkg.first_pm_minutes_nanos"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "xcals 3.7",
   "language": "python",
   "name": "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.7.0"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}