docs/tutorials/minutes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Minutes tutorial"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# setup\n",
    "from datetime import datetime\n",
    "\n",
    "import pandas as pd\n",
    "import exchange_calendars as xcals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `minute` parameter\n",
    "Methods that require a single minute to be specified take a `minute` parameter. Those that act on a range of minutes take `start` and `end` parameters.\n",
    "\n",
    "A `minute` parameter can take a `Minute` or a `TradingMinute` type, defined as:\n",
    "\n",
    "```python\n",
    "Minute = typing.Union[pd.Timestamp, str, int, float, datetime.datetime]\n",
    "TradingMinute = Minute\n",
    "```\n",
    "In short, a `minute` parameter can take any type that can be passed as a single argument to pd.Timestamp(). For example, the argument of `next_minute` takes a `Minute` type, such any of the following inputs are valid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "inputs = [\n",
    "    \"2021-06-15 14:33\",\n",
    "    pd.Timestamp(\"2021-06-15 14:33\"),\n",
    "    datetime(2021, 6, 15, 14, 33),\n",
    "    1623767580000000000,\n",
    "]\n",
    "lon = xcals.get_calendar(\"XLON\")\n",
    "for input in inputs:\n",
    "    assert lon.next_minute(input) == pd.Timestamp('2021-06-15 14:34', tz='UTC')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The difference between `Minute` and `TradingMinute` is that whilst an object passed to a parameter annotated `Minute` can represent any minute, an object passed to a parameter annotated `TradingMinute` must represent a 'trading minute', i.e. a minute when the exchange is open. To the contrary the method will raise a `NotTradingMinuteError`.\n",
    "\n",
    "For example, the first argument of `minutes_window` takes a `TradingMinute`, such that whilst this is valid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2021-06-15 14:33:00+00:00', '2021-06-15 14:34:00+00:00',\n",
       "               '2021-06-15 14:35:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq=None)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "lon.minutes_window(inputs[0], count=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "but this isn't..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lon.minutes_window(\"2021-06-15 22:30\", count=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "NotTradingMinuteError                     Traceback (most recent call last)\n",
    "Input In [4], in <cell line: 1>()\n",
    "----> 1 lon.minutes_window(\"2021-06-15 22:30\", count=3)\n",
    "\n",
    "NotTradingMinuteError: Parameter `minute` takes a trading minute although received input that parsed to '2021-06-15 22:30:00+00:00' which is not a trading minute of calendar 'XLON'.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To find out **which type a `minute` parameter takes**, simply refer to the annotated types in the method signature:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "lon.minutes_window?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "```\n",
    "Signature:\n",
    "lon.minutes_window(\n",
    "    minute: 'TradingMinute',\n",
    "    count: 'int',\n",
    "    _parse: 'bool' = True,\n",
    ") -> 'pd.DatetimeIndex'\n",
    "...\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Which minutes are treated as trading minutes?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Any minute that represents a time when an exchange is open is referred to as a 'trading minute'. At a session's bounds, which of a session's open/close and break start/end are considered as trading minutes is determined by the calendar's `side` parameter:\n",
    "\n",
    "* **\"left\"** - treat session open and break-end as trading minutes,\n",
    "    do not treat session close or break-start as trading minutes.\n",
    "* **\"right\"** - treat session close and break-start as trading minutes,\n",
    "    do not treat session open or break-end as tradng minutes.\n",
    "* **\"both\"** - treat all of session open, session close, break-start\n",
    "    and break-end as trading minutes.\n",
    "* **\"neither\"** - treat none of session open, session close,\n",
    "    break-start or break-end as trading minutes.\n",
    "\n",
    "So, looking at the session \"2021-06-15\" for XHKG (Hong Kong):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "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-06-15</th>\n",
       "      <td>2021-06-15 01:30:00+00:00</td>\n",
       "      <td>2021-06-15 04:00:00+00:00</td>\n",
       "      <td>2021-06-15 05:00:00+00:00</td>\n",
       "      <td>2021-06-15 08:00:00+00:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                open               break_start  \\\n",
       "2021-06-15 2021-06-15 01:30:00+00:00 2021-06-15 04:00:00+00:00   \n",
       "\n",
       "                           break_end                     close  \n",
       "2021-06-15 2021-06-15 05:00:00+00:00 2021-06-15 08:00:00+00:00  "
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_left = xcals.get_calendar(\"XHKG\")\n",
    "hkg_left.schedule.loc[[\"2021-06-15\"]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NB** open, close, and break times are **independent of a calendar's `side`**. These properties reflect times corresponding with the start and end of regular trading periods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# the default side is \"left\", such that the open is a trading minute...\n",
    "hkg_left.is_trading_minute(\"2021-06-15 01:30\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# ...and so is the break_end (i.e. the open of the afternoon subsession)...\n",
    "hkg_left.is_trading_minute(\"2021-06-15 05:00\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# but the close is not a trading minute\n",
    "hkg_left.is_trading_minute(\"2021-06-15 08:00\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# and neither is the break_start (i.e. the close of the morning subsession)...\n",
    "hkg_left.is_trading_minute(\"2021-06-15 04:00\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[False, False, True, True]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# everything's reversed when `side` is \"right\"...\n",
    "hkg_right = xcals.get_calendar(\"XHKG\", side=\"right\")\n",
    "times = [\"01:30\", \"05:00\", \"08:00\", \"04:00\"]\n",
    "[ hkg_right.is_trading_minute(\"2021-06-15 \" + tm) for tm in times ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[True, True, True, True]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# everything's True when `side` is \"both\"...\n",
    "hkg_both = xcals.get_calendar(\"XHKG\", side=\"both\")\n",
    "[ hkg_both.is_trading_minute(\"2021-06-15 \" + tm) for tm in times ]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[False, False, False, False]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# and False when `side` is \"neither\".\n",
    "hkg_neither = xcals.get_calendar(\"XHKG\", side=\"neither\")\n",
    "[ hkg_neither.is_trading_minute(\"2021-06-15 \" + tm) for tm in times ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The effect of the calendar's side can be seen in all methods that interrogate or evaluate trading minutes. For example, note the effect of different sides on the minutes associated with the XHKG session \"2021-06-15\":"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2021-06-15 01:30:00+00:00', '2021-06-15 01:31:00+00:00',\n",
       "               '2021-06-15 01:32:00+00:00', '2021-06-15 01:33:00+00:00',\n",
       "               '2021-06-15 01:34:00+00:00', '2021-06-15 01:35:00+00:00',\n",
       "               '2021-06-15 01:36:00+00:00', '2021-06-15 01:37:00+00:00',\n",
       "               '2021-06-15 01:38:00+00:00', '2021-06-15 01:39:00+00:00',\n",
       "               ...\n",
       "               '2021-06-15 07:50:00+00:00', '2021-06-15 07:51:00+00:00',\n",
       "               '2021-06-15 07:52:00+00:00', '2021-06-15 07:53:00+00:00',\n",
       "               '2021-06-15 07:54:00+00:00', '2021-06-15 07:55:00+00:00',\n",
       "               '2021-06-15 07:56:00+00:00', '2021-06-15 07:57:00+00:00',\n",
       "               '2021-06-15 07:58:00+00:00', '2021-06-15 07:59:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=330, freq=None)"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "session = \"2021-06-15\"\n",
    "hkg_left.session_minutes(session)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2021-06-15 01:31:00+00:00', '2021-06-15 01:32:00+00:00',\n",
       "               '2021-06-15 01:33:00+00:00', '2021-06-15 01:34:00+00:00',\n",
       "               '2021-06-15 01:35:00+00:00', '2021-06-15 01:36:00+00:00',\n",
       "               '2021-06-15 01:37:00+00:00', '2021-06-15 01:38:00+00:00',\n",
       "               '2021-06-15 01:39:00+00:00', '2021-06-15 01:40:00+00:00',\n",
       "               ...\n",
       "               '2021-06-15 07:51:00+00:00', '2021-06-15 07:52:00+00:00',\n",
       "               '2021-06-15 07:53:00+00:00', '2021-06-15 07:54:00+00:00',\n",
       "               '2021-06-15 07:55:00+00:00', '2021-06-15 07:56:00+00:00',\n",
       "               '2021-06-15 07:57:00+00:00', '2021-06-15 07:58:00+00:00',\n",
       "               '2021-06-15 07:59:00+00:00', '2021-06-15 08:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=330, freq=None)"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_right.session_minutes(session)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2021-06-15 01:30:00+00:00', '2021-06-15 01:31:00+00:00',\n",
       "               '2021-06-15 01:32:00+00:00', '2021-06-15 01:33:00+00:00',\n",
       "               '2021-06-15 01:34:00+00:00', '2021-06-15 01:35:00+00:00',\n",
       "               '2021-06-15 01:36:00+00:00', '2021-06-15 01:37:00+00:00',\n",
       "               '2021-06-15 01:38:00+00:00', '2021-06-15 01:39:00+00:00',\n",
       "               ...\n",
       "               '2021-06-15 07:51:00+00:00', '2021-06-15 07:52:00+00:00',\n",
       "               '2021-06-15 07:53:00+00:00', '2021-06-15 07:54:00+00:00',\n",
       "               '2021-06-15 07:55:00+00:00', '2021-06-15 07:56:00+00:00',\n",
       "               '2021-06-15 07:57:00+00:00', '2021-06-15 07:58:00+00:00',\n",
       "               '2021-06-15 07:59:00+00:00', '2021-06-15 08:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=332, freq=None)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_both.session_minutes(session)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE:** as a consequence of treating both sides of the session as open, the number of minutes associated with the session is 332, which is two higher than the session duration (330 minutes). This is because both the open and close are treated as trading minutes (+1) and both the break-start and break-open are treated as trading minutes (another +1). NB For calendars/sessions without a break, the difference is +1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2021-06-15 01:31:00+00:00', '2021-06-15 01:32:00+00:00',\n",
       "               '2021-06-15 01:33:00+00:00', '2021-06-15 01:34:00+00:00',\n",
       "               '2021-06-15 01:35:00+00:00', '2021-06-15 01:36:00+00:00',\n",
       "               '2021-06-15 01:37:00+00:00', '2021-06-15 01:38:00+00:00',\n",
       "               '2021-06-15 01:39:00+00:00', '2021-06-15 01:40:00+00:00',\n",
       "               ...\n",
       "               '2021-06-15 07:50:00+00:00', '2021-06-15 07:51:00+00:00',\n",
       "               '2021-06-15 07:52:00+00:00', '2021-06-15 07:53:00+00:00',\n",
       "               '2021-06-15 07:54:00+00:00', '2021-06-15 07:55:00+00:00',\n",
       "               '2021-06-15 07:56:00+00:00', '2021-06-15 07:57:00+00:00',\n",
       "               '2021-06-15 07:58:00+00:00', '2021-06-15 07:59:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', length=328, freq=None)"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_neither.session_minutes(session)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE** for the \"neither\" side the situation is reversed and the number of minutes associated with the session is two less than the session duration (or -1 for calendars/sessions that do not have a break).\n",
    "\n",
    "These discrepancies will make themselves known in all methods that evaluate or interrogate minutes. **If you are not aware of how trading minutes are evaluated, you might get output that you weren't expecting...**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[330, 330, 332, 328]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "calendars =  [hkg_left, hkg_right, hkg_both, hkg_neither]\n",
    "[ cal.sessions_minutes_count(session, session) for cal in calendars ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE**: the default side is **\"left\"**..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Has it always been this way?\n",
    "\n",
    "No.\n",
    "\n",
    "The original `trading_calendars` package did not have a side option and treated trading minutes as if side were \"right\". This behaviour came about as a result of defining the open time as one minute later than the true open.\n",
    "\n",
    "When support for `trading_calendars` ended `exchange_calendars` came into being. With the initial release 3.0 the opportunity was taken to amend open times to reflect the true open times. Trading minutes continued to be evaluated as previously which had the effect of treating trading minutes as if side were \"both\".\n",
    "\n",
    "In release 3.4 the `ExchangeCalendar` side option was implemented to provide users with flexibility over how to treat trading minutes. In order to best preserve behaviour since release 3.0, the default side was \"right\" for the few 24-hour calendars and \"both\" for all others.\n",
    "\n",
    "In release 4.0 the default side was set to \"left\" for all calendars. This is not expected to change going forwards."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Can a `minute` parameter have a 'second' component?\n",
    "\n",
    "Depends on the `side`...\n",
    "\n",
    "#### 'left' and 'right'\n",
    "\n",
    "Only if a calenar's side is either \"left\" or \"right\" can `minute` be passed with a second (or milisecond...) component. This is because only these sides allow for a minute timestamp to represent a specific sixty seconds...\n",
    "\n",
    "Consider the minute timestamp **\"2021-06-12 15:30:00\"**:\n",
    "* If the side is \"left\" then this timestamp will sit on the left side of the sixty seconds that it represents, that's to say it will represent the period from **\"2021-06-12 15:30:00\" through \"2021-06-12 15:30:59\"**. Indeed it will represent the period through to the instance before \"2021-06-12 15:31:00\", but it will NOT include \"2021-06-12 15:31:00\".\n",
    "* If the side is \"right\" then the timestamp will sit on the right of the sixty seconds it represents, that's to say it will represent the period from the instance after \"2021-06-12 15:30:00\" through \"2021-06-12 15:31:00\". It will NOT include \"2021-06-12 15:30:00\" but will include \"2021-06-12 15:31:00\".\n",
    "\n",
    "Thought of in this way it becomes clear why an exchange that closes at 16.00 <!--TODO - make sure using a time that follows the example above)--> is considered open at \"16:00\" when side is \"right\" but closed when the side is \"left\"...\n",
    "* when the side is \"right\" the timestamp \"16:00\" refers to the sixty seconds from (but not including) 15:59 through 16:00, i.e. the last minute of the trading day during which the exchange was very much open.\n",
    "* when the side is \"left\"  the timestamp \"16:00\" refers to the sixty seconds from 16:00 to (but not including) 16:01, i.e the first minute after the close when the exchange was very much closed.\n",
    "\n",
    "When a `minute` parameter is receieved with a time component more specific than a minute then the corresponding minute timestamp is evaluated by simply rounding up or down if the `side` is \"right\" or \"left\" respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Timestamp('2021-06-15 05:26:00+0000', tz='UTC')"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_left.next_minute(\"2021-06-15 05:25:30\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Timestamp('2021-06-15 05:27:00+0000', tz='UTC')"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_right.next_minute(\"2021-06-15 05:25:30\")\n",
    "# passed argument is represented by the trading minute \"05:26\", hence next_minute is..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hkg_left.is_open_on_minute(\"2021-06-15 07:59:59\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 'both' and 'neither'\n",
    "\n",
    "If the calendar's `side` is either \"both\" or \"neither\" then the sixty second period that a minute timestamp refers to is ambiguous. Looked at the other way around, it's ambiguous which minute timestamp represents any specific second. In order to avoid this ambiguity, if the calendar's side is \"both\" or \"neither\" then any `minute` parameter must be received with a time component no more specific than a minute. To the contrary, a ValueError is raised..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hkg_both.is_open_on_minute(\"2021-06-15 07:59:59\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "ValueError                                Traceback (most recent call last)\n",
    "Input In [22], in <cell line: 1>()\n",
    "----> 1 hkg_both.is_open_on_minute(\"2021-06-15 07:59:59\")\n",
    "\n",
    "ValueError: `timestamp` cannot have a non-zero second (or more accurate) component for `side` 'both'. `timestamp` parsed as '2021-06-15 07:59:59+00:00'.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `minute` timezone"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`exchange_calendars` will always return minutes in terms of UTC. However, a `minute` parameter can take a timestamp of any timezone (`exchange_calendars` just parses it to UTC). Consider a session of the New York Stock Exchange:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "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-06-15</th>\n",
       "      <td>2021-06-15 13:30:00+00:00</td>\n",
       "      <td>NaT</td>\n",
       "      <td>NaT</td>\n",
       "      <td>2021-06-15 20:00:00+00:00</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                open break_start break_end  \\\n",
       "2021-06-15 2021-06-15 13:30:00+00:00         NaT       NaT   \n",
       "\n",
       "                               close  \n",
       "2021-06-15 2021-06-15 20:00:00+00:00  "
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys = xcals.get_calendar(\"XNYS\", side=\"left\")\n",
    "nys.schedule.loc[[\"2021-06-15\"]]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "False"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.is_open_on_minute(pd.Timestamp(\"2021-06-15 09:35\"))\n",
    "# NB tz-naive input is assumed as UTC"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.is_open_on_minute(pd.Timestamp(\"2021-06-15 09:35\", tz=nys.tz))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Timestamp('2021-06-15 13:36:00+0000', tz='UTC')"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.next_minute(pd.Timestamp(\"2021-06-15 09:35\", tz=nys.tz))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Timestamp('2021-06-15 09:36:00-0400', tz='America/New_York')"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nys.next_minute(pd.Timestamp(\"2021-06-15 09:35\", tz=nys.tz)).tz_convert(nys.tz)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `minute` bounds"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nearly all methods that have a `minute` parameter will require that `minute` is received as an object representing a minute that's no earlier than the calendar's first trading minute and no later than the calendar's last trading minute (this is always the case for a `minute` annotated with `TradingMinute`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nys.is_open_on_minute(nys.first_minute - pd.Timedelta(1, \"T\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "MinuteOutOfBounds                         Traceback (most recent call last)\n",
    "Input In [28], in <cell line: 1>()\n",
    "----> 1 nys.is_open_on_minute(nys.first_minute - pd.Timedelta(1, \"T\"))\n",
    "\n",
    "MinuteOutOfBounds: Parameter `minute` receieved as '2002-06-10 13:29:00+00:00' although cannot be earlier than the first trading minute of calendar 'XNYS' ('2002-06-10 13:30:00+00:00').\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nys.next_open(nys.last_minute + pd.Timedelta(1, \"T\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "MinuteOutOfBounds                         Traceback (most recent call last)\n",
    "Input In [29], in <cell line: 1>()\n",
    "----> 1 nys.next_open(nys.last_minute + pd.Timedelta(1, \"T\"))\n",
    "\n",
    "MinuteOutOfBounds: Parameter `minute` receieved as '2023-06-09 20:00:00+00:00' although cannot be later than the last trading minute of calendar 'XNYS' ('2023-06-09 19:59:00+00:00').\n",
    "```"
   ]
  }
 ],
 "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
}