pandas.Series.tz_localize#

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

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

This operation localizes the Index. To localize the values in atime zone 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 False

This keyword is now ignored; changing its value will have noimpact on the method.

Deprecated since version 3.0.0:This keyword is ignored and will be removed in pandas 4.0. Sincepandas 3.0, this method always returns a new object using a lazycopy mechanism that defers copies until necessary(Copy-on-Write). See theuser guide on Copy-on-Writefor more details.

ambiguous‘infer’, bool, 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 (or 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 a ValueError 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 a ValueError if there arenonexistent times.

Returns:
Series/DataFrame

Same type as the input, with time zone naive or aware index, depending ontz.

Raises:
TypeError

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

See also

Series.dt.tz_localize

Localize the values in a time zone naive Series.

Timestamp.tz_localize

Localize the Timestamp to a timezone.

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’.

>>>dti=pd.DatetimeIndex(...["2015-03-29 02:30:00","2015-03-29 03:30:00"],dtype="M8[ns]"...)>>>s=pd.Series(range(2),index=dti)>>>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