conver_timezone_using_python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Convert timezone using python\n",
    "\n",
    "Objective:\n",
    "* Find timezone based on longtidue and latitude\n",
    "* Change UTC time to local time\n",
    "\n",
    "Packages:\n",
    "* [timezonefinder](https://pypi.org/project/timezonefinder/)\n",
    "* [pandas](https://pandas.pydata.org/)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import packages\n",
    "from timezonefinder import TimezoneFinder\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`timezonefinder` is used to identify local time zone based on longitude and latitude. To save computing time at the cost of memory consumption and initialisation time pass `in_memory=True`. This causes all binary files to be read into memory. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'America/Chicago'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Find timezone based on longitude and latitude\n",
    "tf = TimezoneFinder(in_memory=True)\n",
    "longitude = -88\n",
    "latitude = 36\n",
    "local_time_zone = tf.timezone_at(lng=longitude, lat=latitude)\n",
    "local_time_zone"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we will create a DatetimeIndex (April 06 - 07, 2019 with frequency of 4 hours) using pandas [date_range](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html) function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2019-04-06 00:00:00', '2019-04-06 04:00:00',\n",
       "               '2019-04-06 08:00:00', '2019-04-06 12:00:00',\n",
       "               '2019-04-06 16:00:00', '2019-04-06 20:00:00',\n",
       "               '2019-04-07 00:00:00'],\n",
       "              dtype='datetime64[ns]', freq='4H')"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Create naive timestamps using pandas\n",
    "test_naive = pd.date_range('2019-04-06', '2019-04-07', freq='4H')\n",
    "test_naive"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see from the above output, the timestamps are in naive format, i.e. without timezone information. A typical problem we usually encounter is that the above timestamps is under UTC for some observations or model results, and we'd like to convert it to local time zone in order to calcualte some local information (e.g. daily precipitation). To do that, we first need to add time zone information for the naive timestamps, e.g., we can set them to UTC (assume they are actually in UTC) using the [tz_localize](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.tz_localize.html) function from pandas."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2019-04-06 00:00:00+00:00', '2019-04-06 04:00:00+00:00',\n",
       "               '2019-04-06 08:00:00+00:00', '2019-04-06 12:00:00+00:00',\n",
       "               '2019-04-06 16:00:00+00:00', '2019-04-06 20:00:00+00:00',\n",
       "               '2019-04-07 00:00:00+00:00'],\n",
       "              dtype='datetime64[ns, UTC]', freq='4H')"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Set time to be UTC\n",
    "test_UTC = test_naive.tz_localize('UTC')\n",
    "test_UTC"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The output now has additional time zone information (e.g. `+00:00`). Then we can convert it to local time genrated by longitude and latidue at the beginning using the [tz_convert](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.tz_convert.html) function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2019-04-05 19:00:00-05:00', '2019-04-05 23:00:00-05:00',\n",
       "               '2019-04-06 03:00:00-05:00', '2019-04-06 07:00:00-05:00',\n",
       "               '2019-04-06 11:00:00-05:00', '2019-04-06 15:00:00-05:00',\n",
       "               '2019-04-06 19:00:00-05:00'],\n",
       "              dtype='datetime64[ns, America/Chicago]', freq='4H')"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Convert UTC to local time\n",
    "test_local = test_UTC.tz_convert(local_time_zone)\n",
    "test_local"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Apparently, the time zone now is changed to local time automatically, i.e. `-05:00` instead of `+00:00`. Sometimes, we also need to convert the timestamps with timezonen information back to naive timestamps but still in local time zone. We can use [tz_localize](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.tz_localize.html) function again, but this time the argument is `None` which means naive timestamps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DatetimeIndex(['2019-04-05 19:00:00', '2019-04-05 23:00:00',\n",
       "               '2019-04-06 03:00:00', '2019-04-06 07:00:00',\n",
       "               '2019-04-06 11:00:00', '2019-04-06 15:00:00',\n",
       "               '2019-04-06 19:00:00'],\n",
       "              dtype='datetime64[ns]', freq='4H')"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Convert back to naive timestamps, but in local time zone.\n",
    "test_local_naive = test_local.tz_localize(None)\n",
    "test_local_naive"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we have convert the UTC time to local time and the format is the same, i.e. naive timestamps. Functions we used in this conversion are\n",
    "\n",
    "* [tf.timezone_at](https://pypi.org/project/timezonefinder/): get time zone based on longitude and latidue\n",
    "* [tz_localize](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.tz_localize.html): convert naive timestamps to timestamps with time zone information, or the reverse process\n",
    "* [tz_convert](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.tz_convert.html): convert timestamps between different time zones"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}