{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5be1a8c7",
   "metadata": {},
   "source": [
    "# Date and Time\n",
    "\n",
    "With pandas you can create `Series` with date and time information. In the following we will show common operations with date data.\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "pandas supports dates stored in [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) values using the `datetime64[ns]` datatype. Local times from a single time zone are also supported. Multiple time zones are supported by a [pandas.Timestamp](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html) object. If you need to handle times from multiple time zones, I would probably split the data by time zone and use a separate DataFrame or Series for each time zone.\n",
    "</div>\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "**See also:**\n",
    "\n",
    "* [Time series / date functionality](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html)\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a6f32e13",
   "metadata": {},
   "source": [
    "## Loading UTC time data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "3c1f1337",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2022-03-27 00:00:00', '2022-03-27 01:00:00',\n",
       "               '2022-03-27 02:00:00', '2022-03-27 03:00:00',\n",
       "               '2022-03-27 04:00:00', '2022-03-27 05:00:00'],\n",
       "              dtype='datetime64[ns]', freq='h')"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import pandas as pd\n",
    "\n",
    "\n",
    "dt = pd.date_range(\"2022-03-27\", periods=6, freq=\"h\")\n",
    "\n",
    "dt"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "2f596835",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2022-03-27 00:00:00+00:00', '2022-03-27 01:00:00+00:00',\n",
       "               '2022-03-27 02:00:00+00:00', '2022-03-27 03:00:00+00:00',\n",
       "               '2022-03-27 04:00:00+00:00', '2022-03-27 05:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq='h')"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "utc = pd.to_datetime(dt, utc=True)\n",
    "\n",
    "utc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f7af8ef",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "The type of the result `dtype='datetime64[ns, UTC]'` indicates that the data is stored as UTC.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6da836d1",
   "metadata": {},
   "source": [
    "Let’s convert this series to the time zone Europe/Berlin:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "459fb1df",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2022-03-27 01:00:00+01:00', '2022-03-27 03:00:00+02:00',\n",
       "               '2022-03-27 04:00:00+02:00', '2022-03-27 05:00:00+02:00',\n",
       "               '2022-03-27 06:00:00+02:00', '2022-03-27 07:00:00+02:00'],\n",
       "              dtype='datetime64[ns, Europe/Berlin]', freq='h')"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "utc.tz_convert(\"Europe/Berlin\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c35aa1c0",
   "metadata": {},
   "source": [
    "## Conversion of local time to UTC"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "d4bfa601",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2022-03-27 00:00:00+00:00', '2022-03-27 01:00:00+00:00',\n",
       "               '2022-03-27 02:00:00+00:00', '2022-03-27 03:00:00+00:00',\n",
       "               '2022-03-27 04:00:00+00:00', '2022-03-27 05:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq='h')"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "local = utc.tz_convert(\"Europe/Berlin\")\n",
    "\n",
    "local.tz_convert(\"UTC\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55b524a3",
   "metadata": {},
   "source": [
    "## Conversion to Unix time\n",
    "\n",
    "If you have a `Series` with UTC or local time information, you can use this code to determine the seconds according to Unix time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "779c2d88",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1.6483392e+09, 1.6483428e+09, 1.6483464e+09, 1.6483500e+09,\n",
       "       1.6483536e+09, 1.6483572e+09])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "uts = pd.to_datetime(dt).view(int) / 10**9\n",
    "\n",
    "uts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "90428328",
   "metadata": {},
   "source": [
    "To load the Unix time in UTC, you can proceed as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "020c78c8",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2022-03-27 00:00:00+00:00', '2022-03-27 01:00:00+00:00',\n",
       "               '2022-03-27 02:00:00+00:00', '2022-03-27 03:00:00+00:00',\n",
       "               '2022-03-27 04:00:00+00:00', '2022-03-27 05:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq=None)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(pd.to_datetime(uts, unit=\"s\").tz_localize(\"UTC\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da3c36e7",
   "metadata": {},
   "source": [
    "## Manipulation of dates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c55c25d",
   "metadata": {},
   "source": [
    "### Convert to strings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ef9982c",
   "metadata": {},
   "source": [
    "With [pandas.DatetimeIndex](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html) you have some possibilities to convert date and time into strings, for example into the name of the weekday:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "f506f0a6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Index(['Sunday', 'Sunday', 'Sunday', 'Sunday', 'Sunday', 'Sunday'], dtype='object')"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "local.day_name(locale=\"en_GB.UTF-8\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "575affb9",
   "metadata": {},
   "source": [
    "You can find out which `locale` is available to you with `locale -a`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "c361ce40",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "en_NZ\n",
      "nl_NL.UTF-8\n",
      "pt_BR.UTF-8\n",
      "fr_CH.ISO8859-15\n",
      "eu_ES.ISO8859-15\n",
      "en_US.US-ASCII\n",
      "af_ZA\n",
      "bg_BG\n",
      "cs_CZ.UTF-8\n",
      "fi_FI\n",
      "zh_CN.UTF-8\n",
      "eu_ES\n",
      "sk_SK.ISO8859-2\n",
      "nl_BE\n",
      "fr_BE\n",
      "sk_SK\n",
      "en_US.UTF-8\n",
      "en_NZ.ISO8859-1\n",
      "de_CH\n",
      "sk_SK.UTF-8\n",
      "de_DE.UTF-8\n",
      "am_ET.UTF-8\n",
      "zh_HK\n",
      "be_BY.UTF-8\n",
      "uk_UA\n",
      "pt_PT.ISO8859-1\n",
      "en_AU.US-ASCII\n",
      "kk_KZ.PT154\n",
      "en_US\n",
      "nl_BE.ISO8859-15\n",
      "de_AT.ISO8859-1\n",
      "hr_HR.ISO8859-2\n",
      "fr_FR.ISO8859-1\n",
      "af_ZA.UTF-8\n",
      "am_ET\n",
      "fi_FI.ISO8859-1\n",
      "ro_RO.UTF-8\n",
      "af_ZA.ISO8859-15\n",
      "en_NZ.UTF-8\n",
      "fi_FI.UTF-8\n",
      "hr_HR.UTF-8\n",
      "da_DK.UTF-8\n",
      "ca_ES.ISO8859-1\n",
      "en_AU.ISO8859-15\n",
      "ro_RO.ISO8859-2\n",
      "de_AT.UTF-8\n",
      "pt_PT.ISO8859-15\n",
      "sv_SE\n",
      "fr_CA.ISO8859-1\n",
      "fr_BE.ISO8859-1\n",
      "en_US.ISO8859-15\n",
      "it_CH.ISO8859-1\n",
      "en_NZ.ISO8859-15\n",
      "en_AU.UTF-8\n",
      "de_AT.ISO8859-15\n",
      "af_ZA.ISO8859-1\n",
      "hu_HU.UTF-8\n",
      "et_EE.UTF-8\n",
      "he_IL.UTF-8\n",
      "uk_UA.KOI8-U\n",
      "be_BY\n",
      "kk_KZ\n",
      "hu_HU.ISO8859-2\n",
      "it_CH\n",
      "pt_BR\n",
      "ko_KR\n",
      "it_IT\n",
      "fr_BE.UTF-8\n",
      "ru_RU.ISO8859-5\n",
      "zh_TW\n",
      "zh_CN.GB2312\n",
      "no_NO.ISO8859-15\n",
      "de_DE.ISO8859-15\n",
      "en_CA\n",
      "fr_CH.UTF-8\n",
      "sl_SI.UTF-8\n",
      "uk_UA.ISO8859-5\n",
      "pt_PT\n",
      "hr_HR\n",
      "cs_CZ\n",
      "fr_CH\n",
      "he_IL\n",
      "zh_CN.GBK\n",
      "zh_CN.GB18030\n",
      "fr_CA\n",
      "pl_PL.UTF-8\n",
      "ja_JP.SJIS\n",
      "sr_YU.ISO8859-5\n",
      "be_BY.CP1251\n",
      "sr_YU.ISO8859-2\n",
      "sv_SE.UTF-8\n",
      "sr_YU.UTF-8\n",
      "de_CH.UTF-8\n",
      "sl_SI\n",
      "pt_PT.UTF-8\n",
      "ro_RO\n",
      "en_NZ.US-ASCII\n",
      "ja_JP\n",
      "zh_CN\n",
      "fr_CH.ISO8859-1\n",
      "ko_KR.eucKR\n",
      "be_BY.ISO8859-5\n",
      "nl_NL.ISO8859-15\n",
      "en_GB.ISO8859-1\n",
      "en_CA.US-ASCII\n",
      "is_IS.ISO8859-1\n",
      "ru_RU.CP866\n",
      "nl_NL\n",
      "fr_CA.ISO8859-15\n",
      "sv_SE.ISO8859-15\n",
      "hy_AM\n",
      "en_CA.ISO8859-15\n",
      "en_US.ISO8859-1\n",
      "zh_TW.Big5\n",
      "ca_ES.UTF-8\n",
      "ru_RU.CP1251\n",
      "en_GB.UTF-8\n",
      "en_GB.US-ASCII\n",
      "ru_RU.UTF-8\n",
      "eu_ES.UTF-8\n",
      "es_ES.ISO8859-1\n",
      "hu_HU\n",
      "el_GR.ISO8859-7\n",
      "en_AU\n",
      "it_CH.UTF-8\n",
      "en_GB\n",
      "sl_SI.ISO8859-2\n",
      "ru_RU.KOI8-R\n",
      "nl_BE.UTF-8\n",
      "et_EE\n",
      "fr_FR.ISO8859-15\n",
      "cs_CZ.ISO8859-2\n",
      "lt_LT.UTF-8\n",
      "pl_PL.ISO8859-2\n",
      "fr_BE.ISO8859-15\n",
      "is_IS.UTF-8\n",
      "tr_TR.ISO8859-9\n",
      "da_DK.ISO8859-1\n",
      "lt_LT.ISO8859-4\n",
      "lt_LT.ISO8859-13\n",
      "zh_TW.UTF-8\n",
      "bg_BG.CP1251\n",
      "el_GR.UTF-8\n",
      "be_BY.CP1131\n",
      "da_DK.ISO8859-15\n",
      "is_IS.ISO8859-15\n",
      "no_NO.ISO8859-1\n",
      "nl_NL.ISO8859-1\n",
      "nl_BE.ISO8859-1\n",
      "sv_SE.ISO8859-1\n",
      "pt_BR.ISO8859-1\n",
      "zh_CN.eucCN\n",
      "it_IT.UTF-8\n",
      "en_CA.UTF-8\n",
      "uk_UA.UTF-8\n",
      "de_CH.ISO8859-15\n",
      "de_DE.ISO8859-1\n",
      "ca_ES\n",
      "sr_YU\n",
      "hy_AM.ARMSCII-8\n",
      "ru_RU\n",
      "zh_HK.UTF-8\n",
      "eu_ES.ISO8859-1\n",
      "is_IS\n",
      "bg_BG.UTF-8\n",
      "ja_JP.UTF-8\n",
      "it_CH.ISO8859-15\n",
      "fr_FR.UTF-8\n",
      "ko_KR.UTF-8\n",
      "et_EE.ISO8859-15\n",
      "kk_KZ.UTF-8\n",
      "ca_ES.ISO8859-15\n",
      "en_IE.UTF-8\n",
      "es_ES\n",
      "de_CH.ISO8859-1\n",
      "en_CA.ISO8859-1\n",
      "es_ES.ISO8859-15\n",
      "en_AU.ISO8859-1\n",
      "el_GR\n",
      "da_DK\n",
      "no_NO\n",
      "it_IT.ISO8859-1\n",
      "en_IE\n",
      "zh_HK.Big5HKSCS\n",
      "hi_IN.ISCII-DEV\n",
      "ja_JP.eucJP\n",
      "it_IT.ISO8859-15\n",
      "pl_PL\n",
      "ko_KR.CP949\n",
      "fr_CA.UTF-8\n",
      "fi_FI.ISO8859-15\n",
      "en_GB.ISO8859-15\n",
      "fr_FR\n",
      "hy_AM.UTF-8\n",
      "no_NO.UTF-8\n",
      "es_ES.UTF-8\n",
      "de_AT\n",
      "tr_TR.UTF-8\n",
      "de_DE\n",
      "lt_LT\n",
      "tr_TR\n",
      "C\n",
      "POSIX\n"
     ]
    }
   ],
   "source": [
    "!locale -a"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6ffa209",
   "metadata": {},
   "source": [
    "Other attributes of `DatetimeIndex` that can be used to convert date and time into strings are:\n",
    "\n",
    "Attribute | Description\n",
    ":------- | :-----------\n",
    "`year` | the year as `datetime`.\n",
    "`month` | the month as January `1` and December `12`\n",
    "`day` | the day of the `datetime`\n",
    "`hour` | the hours of the `datetime`\n",
    "`minute` | the minutes of the `datetime`\n",
    "`seconds` | the seconds of the 'datetime\n",
    "`microsecond` | the microseconds of the `datetime`.\n",
    "`nanosecond` | the nanoseconds of `datetime`\n",
    "`date` | returns a NumPy array of Python `datetime.date` objects\n",
    "`time` | returns a NumPy array of `datetime.time` objects\n",
    "`timetz` | returns a NumPy array of `datetime.time` objects with timezone information\n",
    "`dayofyear`, `day_of_year` | the ordinal day of the year\n",
    "`dayofweek` | the day of the week with Monday (`0`) and Sunday (`6`)\n",
    "`day_of_week` | the day of the week with Monday (`0`) and Sunday (`6`)\n",
    "`weekday` | the day of the week with Monday (`0`) and Sunday (`6`)\n",
    "`quarter` | returns the quarter of the year\n",
    "`tz` | returns the time zone\n",
    "`freq` | returns the frequency object if it is set, otherwise `None`\n",
    "`freqstr` | returns the frequency object as a string if it is set, otherwise `None`\n",
    "`is_month_start` | indicates if the date is the first day of the month\n",
    "`is_month_end` | indicates whether the date is the last day of the month\n",
    "`is_quarter_start` | indicates whether the date is the first day of a quarter\n",
    "`is_quarter_end` | shows if the date is the last day of a quarter\n",
    "`is_year_start` | indicates whether the date is the first day of a year\n",
    "`is_year_end` | indicates whether the date is the last day of a year\n",
    "`is_leap_year` | Boolean indicator if the date falls in a leap year\n",
    "`inferred_freq` | tries to return a string representing a frequency determined by `infer_freq`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22c92750",
   "metadata": {},
   "source": [
    "However, there are also some methods with which you can convert the `DatetimeIndex` into strings, for example `strftime`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "f36cfb67",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Index(['27.03.2022', '27.03.2022', '27.03.2022', '27.03.2022', '27.03.2022',\n",
       "       '27.03.2022'],\n",
       "      dtype='object')"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "local.strftime(\"%d.%m.%Y\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53ec4219",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "In [strftime() and strptime() Format Codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) you get an overview of the different formatting possibilities of `strftime`.\n",
    "</div>\n",
    "\n",
    "Other methods are:\n",
    "\n",
    "Method | Description\n",
    ":----- | :-----------\n",
    "`normalize` | converts times to midnight\n",
    "`strftime` | converts to index using the specified date format\n",
    "`snap` | snaps the timestamp to the next occurring frequency\n",
    "`tz_convert` | convert a `tz` capable datetime array/index from one time zone to another\n",
    "`tz_localize` | localises `tz`-naive datetime array/index into `tz`-compatible datetime array/index\n",
    "`round` | rounds the data up to the nearest specified frequency\n",
    "`floor` | rounds the data sown to the specified frequency\n",
    "`ceil` | round the data to the specified frequency\n",
    "`to_period` | converts the data to a PeriodArray/Index at a given frequency\n",
    "`to_perioddelta` | calculates `TimedeltaArray` of the difference between the index values and the index converted to `PeriodArray` at the specified frequency\n",
    "`to_pydatetime` | returns `Datetime` array/index as `ndarray` object of `datetime.datetime` objects\n",
    "`to_series` | creates a `series` with index and values corresponding to index keys; useful with `map` for returning an indexer\n",
    "`to_frame` | creates a `DataFrame` with a column containing the index\n",
    "`month_name` | returns the month names of the `DateTimeIndex` with the specified `locale`\n",
    "`day_name` | returns the day names of the `DateTimeIndex` with the specified `locale`\n",
    "`mean` | returns the mean value of the array\n",
    "`std` | returns the standard deviation of the sample across the requested axis"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.13 Kernel",
   "language": "python",
   "name": "python313"
  },
  "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.13.0"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}