diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 1109fc4effe4a..1dca7bc47c274 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -1946,15 +1946,14 @@ def delete(self, loc): def tz_convert(self, tz): """ - Convert tz-aware DatetimeIndex from one time zone to another (using - pytz/dateutil) + Convert tz-aware DatetimeIndex from one time zone to another. Parameters ---------- tz : string, pytz.timezone, dateutil.tz.tzfile or None - Time zone for time. Corresponding timestamps would be converted to - time zone of the TimeSeries. - None will remove timezone holding UTC time. + Time zone for time. Corresponding timestamps would be converted + to this time zone of the DatetimeIndex. A `tz` of None will + convert to UTC and remove the timezone information. Returns ------- @@ -1964,6 +1963,50 @@ def tz_convert(self, tz): ------ TypeError If DatetimeIndex is tz-naive. + + See Also + -------- + DatetimeIndex.tz : A timezone that has a variable offset from UTC + DatetimeIndex.tz_localize : Localize tz-naive DatetimeIndex to a + given time zone, or remove timezone from a tz-aware DatetimeIndex. + + Examples + -------- + With the `tz` parameter, we can change the DatetimeIndex + to other time zones: + + >>> dti = pd.DatetimeIndex(start='2014-08-01 09:00', + ... freq='H', periods=3, tz='Europe/Berlin') + + >>> dti + DatetimeIndex(['2014-08-01 09:00:00+02:00', + '2014-08-01 10:00:00+02:00', + '2014-08-01 11:00:00+02:00'], + dtype='datetime64[ns, Europe/Berlin]', freq='H') + + >>> dti.tz_convert('US/Central') + DatetimeIndex(['2014-08-01 02:00:00-05:00', + '2014-08-01 03:00:00-05:00', + '2014-08-01 04:00:00-05:00'], + dtype='datetime64[ns, US/Central]', freq='H') + + With the ``tz=None``, we can remove the timezone (after converting + to UTC if necessary): + + >>> dti = pd.DatetimeIndex(start='2014-08-01 09:00',freq='H', + ... periods=3, tz='Europe/Berlin') + + >>> dti + DatetimeIndex(['2014-08-01 09:00:00+02:00', + '2014-08-01 10:00:00+02:00', + '2014-08-01 11:00:00+02:00'], + dtype='datetime64[ns, Europe/Berlin]', freq='H') + + >>> dti.tz_convert(None) + DatetimeIndex(['2014-08-01 07:00:00', + '2014-08-01 08:00:00', + '2014-08-01 09:00:00'], + dtype='datetime64[ns]', freq='H') """ tz = timezones.maybe_get_tz(tz)