pandas.DataFrame.tz_localize#

DataFrame.tz_localize(tz,axis=0,level=None,copy=None,ambiguous='raise',nonexistent='raise')[source]#

Localize tz-naive index of a Series or DataFrame to target time zone.

This operation localizes the Index. To localize the values in atimezone-naive Series, useSeries.dt.tz_localize().

Parameters:

tzstr or tzinfo or None

Time zone to localize. PassingNone will remove thetime zone information and preserve local time.

axis{0 or ‘index’, 1 or ‘columns’}, default 0

The axis to localize

levelint, str, default None

If axis ia a MultiIndex, localize a specific level. Otherwisemust be None.

copybool, default True

Also make a copy of the underlying data.

Note

Thecopy keyword will change behavior in pandas 3.0.Copy-on-Writewill be enabled by default, which means that all methods with acopy keyword will use a lazy copy mechanism to defer the copy andignore thecopy keyword. Thecopy keyword will be removed in afuture version of pandas.

You can already get the future behavior and improvements throughenabling copy on writepd.options.mode.copy_on_write=True

ambiguous‘infer’, bool-ndarray, ‘NaT’, 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 designatesa non-DST time (note that this flag is only applicable forambiguous times)

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

• ‘raise’ will raise an AmbiguousTimeError if there are ambiguoustimes.

nonexistentstr, default ‘raise’

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

• ‘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 an NonExistentTimeError if there arenonexistent times.

Returns:

Series/DataFrame

Same type as the input.

Raises:

TypeError

If the TimeSeries is tz-aware and tz is not None.

Examples

Localize local times:

>>>s=pd.Series(...[1],...index=pd.DatetimeIndex(['2018-09-15 01:30:00']),...)>>>s.tz_localize('CET')2018-09-15 01:30:00+02:00    1dtype: int64

Pass None to convert to tz-naive index and preserve local time:

>>>s=pd.Series([1],...index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00']))>>>s.tz_localize(None)2018-09-15 01:30:00    1dtype: int64

Be careful with DST changes. When there is sequential data, pandascan infer the DST time:

>>>s=pd.Series(range(7),...index=pd.DatetimeIndex(['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.tz_localize('CET',ambiguous='infer')2018-10-28 01:30:00+02:00    02018-10-28 02:00:00+02:00    12018-10-28 02:30:00+02:00    22018-10-28 02:00:00+01:00    32018-10-28 02:30:00+01:00    42018-10-28 03:00:00+01:00    52018-10-28 03:30:00+01:00    6dtype: int64

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.Series(range(3),...index=pd.DatetimeIndex(['2018-10-28 01:20:00',...'2018-10-28 02:36:00',...'2018-10-28 03:46:00']))>>>s.tz_localize('CET',ambiguous=np.array([True,True,False]))2018-10-28 01:20:00+02:00    02018-10-28 02:36:00+02:00    12018-10-28 03:46:00+01:00    2dtype: int64

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

>>>s=pd.Series(range(2),...index=pd.DatetimeIndex(['2015-03-29 02:30:00',...'2015-03-29 03:30:00']))>>>s.tz_localize('Europe/Warsaw',nonexistent='shift_forward')2015-03-29 03:00:00+02:00    02015-03-29 03:30:00+02:00    1dtype: int64>>>s.tz_localize('Europe/Warsaw',nonexistent='shift_backward')2015-03-29 01:59:59.999999999+01:00    02015-03-29 03:30:00+02:00              1dtype: int64>>>s.tz_localize('Europe/Warsaw',nonexistent=pd.Timedelta('1h'))2015-03-29 03:30:00+02:00    02015-03-29 03:30:00+02:00    1dtype: int64