pandas.Series.dt.tz_localize#

Series.dt.tz_localize(tz,ambiguous='raise',nonexistent='raise')[source]#

Localize tz-naive Datetime Array/Index to tz-aware Datetime Array/Index.

This method takes a time zone (tz) naive Datetime Array/Index objectand makes this time zone aware. It does not move the time to anothertime zone.

This method can also be used to do the inverse – to create a timezone unaware object from an aware object. To that end, passtz=None.

Parameters:
tzstr, zoneinfo.ZoneInfo,, pytz.timezone, dateutil.tz.tzfile, datetime.tzinfo or None

Time zone to convert timestamps to. PassingNone willremove the time zone information preserving local time.

ambiguous‘infer’, ‘NaT’, bool array, default ‘raise’

When clocks moved backward due to DST, ambiguous times may arise.For example in Central European Time (UTC+01), when going from03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at00:30:00 UTC and at 01:30:00 UTC. In such a situation, theambiguous parameter dictates how ambiguous times should behandled.

  • ‘infer’ will attempt to infer fall dst-transition hours based onorder

  • bool-ndarray where True signifies a DST time, False signifies anon-DST time (note that this flag is only applicable forambiguous times)

  • ‘NaT’ will return NaT where there are ambiguous times

  • ‘raise’ will raise a ValueError if there are ambiguoustimes.

nonexistent‘shift_forward’, ‘shift_backward, ‘NaT’, timedelta, default ‘raise’

A nonexistent time does not exist in a particular timezonewhere clocks moved forward due to DST.

  • ‘shift_forward’ will shift the nonexistent time forward to theclosest existing time

  • ‘shift_backward’ will shift the nonexistent time backward to theclosest existing time

  • ‘NaT’ will return NaT where there are nonexistent times

  • timedelta objects will shift nonexistent times by the timedelta

  • ‘raise’ will raise a ValueError if there arenonexistent times.

Returns:
Same type as self

Array/Index converted to the specified time zone.

Raises:
TypeError

If the Datetime Array/Index is tz-aware and tz is not None.

See also

DatetimeIndex.tz_convert

Convert tz-aware DatetimeIndex from one time zone to another.

Examples

>>>tz_naive=pd.date_range('2018-03-01 09:00',periods=3)>>>tz_naiveDatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00',               '2018-03-03 09:00:00'],              dtype='datetime64[us]', freq='D')

Localize DatetimeIndex in US/Eastern time zone:

>>>tz_aware=tz_naive.tz_localize(tz='US/Eastern')>>>tz_awareDatetimeIndex(['2018-03-01 09:00:00-05:00',               '2018-03-02 09:00:00-05:00',               '2018-03-03 09:00:00-05:00'],              dtype='datetime64[us, US/Eastern]', freq=None)

With thetz=None, we can remove the time zone informationwhile keeping the local time (not converted to UTC):

>>>tz_aware.tz_localize(None)DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00',               '2018-03-03 09:00:00'],              dtype='datetime64[us]', freq=None)

Be careful with DST changes. When there is sequential data, pandas caninfer the DST time:

>>>s=pd.to_datetime(pd.Series(['2018-10-28 01:30:00',...'2018-10-28 02:00:00',...'2018-10-28 02:30:00',...'2018-10-28 02:00:00',...'2018-10-28 02:30:00',...'2018-10-28 03:00:00',...'2018-10-28 03:30:00']))>>>s.dt.tz_localize('CET',ambiguous='infer')0   2018-10-28 01:30:00+02:001   2018-10-28 02:00:00+02:002   2018-10-28 02:30:00+02:003   2018-10-28 02:00:00+01:004   2018-10-28 02:30:00+01:005   2018-10-28 03:00:00+01:006   2018-10-28 03:30:00+01:00dtype: datetime64[us, CET]

In some cases, inferring the DST is impossible. In such cases, you canpass an ndarray to the ambiguous parameter to set the DST explicitly

>>>s=pd.to_datetime(pd.Series(['2018-10-28 01:20:00',...'2018-10-28 02:36:00',...'2018-10-28 03:46:00']))>>>s.dt.tz_localize('CET',ambiguous=np.array([True,True,False]))0   2018-10-28 01:20:00+02:001   2018-10-28 02:36:00+02:002   2018-10-28 03:46:00+01:00dtype: datetime64[us, CET]

If the DST transition causes nonexistent times, you can shift thesedates forward or backwards with a timedelta object or‘shift_forward’or‘shift_backwards’.

>>>s=pd.to_datetime(pd.Series(['2015-03-29 02:30:00',...'2015-03-29 03:30:00'],dtype="M8[ns]"))>>>s.dt.tz_localize('Europe/Warsaw',nonexistent='shift_forward')0   2015-03-29 03:00:00+02:001   2015-03-29 03:30:00+02:00dtype: datetime64[ns, Europe/Warsaw]
>>>s.dt.tz_localize('Europe/Warsaw',nonexistent='shift_backward')0   2015-03-29 01:59:59.999999999+01:001   2015-03-29 03:30:00+02:00dtype: datetime64[ns, Europe/Warsaw]
>>>s.dt.tz_localize('Europe/Warsaw',nonexistent=pd.Timedelta('1h'))0   2015-03-29 03:30:00+02:001   2015-03-29 03:30:00+02:00dtype: datetime64[ns, Europe/Warsaw]