Pandas Series: tz_localize() function

Last update on September 15 2022 12:55:18 (UTC/GMT +8 hours)

Localize tz-naive index of a Pandas Series

The tz_localize() function is used to localizes the Index. Localize tz-naive index of a Series or DataFrame to target time zone.

This operation localizes the Index. To localize the values in a timezone-naive Series, use Series.dt.tz_localize().

Syntax:

Series.tz_localize(self, tz, axis=0, level=None, copy=True, ambiguous='raise', nonexistent='raise')

Parameters:

Name	Description	Type/Default Value	Required / Optional
tz	String or pytz.timezone object	string or pytz.timezone object	Required
axis	The axis to localize.		Required
level	If axis ia a MultiIndex, localize a specific level. Otherwise must be None	int, str, Default Value: None	Required
copy	Also make a copy of the underlying data	boolean Default Value: True	Required
ambiguous	When clocks moved backward due to DST, ambiguous times may arise. For example in Central European Time (UTC+01), when going from 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the ambiguous parameter dictates how ambiguous times should be handled. ‘infer’ will attempt to infer fall dst-transition hours based on order bool-ndarray where True signifies a DST time, False designates a non-DST time (note that this flag is only applicable for ambiguous times) ‘NaT’ will return NaT where there are ambiguous times ‘raise’ will raise an AmbiguousTimeError if there are ambiguous times	‘infer’, bool-ndarray, ‘NaT’ Default Value: ‘raise’	Required
nonexistent	A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST. Valid values are: ‘shift_forward’ will shift the nonexistent time forward to the closest existing time ‘shift_backward’ will shift the nonexistent time backward to the closest 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 are nonexistent times	str Default Value: ‘raise’	Required

Returns: Series or DataFrame
Same type as the input.

Raises: TypeError if the TimeSeries is tz-aware and tz is not None.

Example - Localize local times:

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series([1],
index=pd.DatetimeIndex(['2019-09-15 01:30:00']))
s.tz_localize('CET')

Output:

2019-09-15 01:30:00+02:00    1
dtype: int64

Example - Be careful with DST changes. When there is sequential data, pandas can infer the DST time:

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(range(6), index=pd.DatetimeIndex([
 '2019-10-28 01:30:00',
 '2019-10-28 02:00:00',
 '2019-10-28 02:30:00',
 '2019-10-28 02:30:00',
 '2019-10-28 03:00:00',
 '2019-10-28 03:30:00']))
s.tz_localize('CET', ambiguous='infer')

Output:

2019-10-28 01:30:00+01:00    0
2019-10-28 02:00:00+01:00    1
2019-10-28 02:30:00+01:00    2
2019-10-28 02:30:00+01:00    3
2019-10-28 03:00:00+01:00    4
2019-10-28 03:30:00+01:00    5
dtype: int64

Example - In some cases, inferring the DST is impossible. In such cases, you can pass an ndarray to the ambiguous parameter to set the DST explicitly:

Python-Pandas Code:

import numpy as np
import pandas as pd
s = pd.Series(range(3), index=pd.DatetimeIndex([
 '2019-10-28 01:20:00',
 '2019-10-28 02:36:00',
 '2019-10-28 03:46:00']))
s.tz_localize('CET', ambiguous=np.array([True, True, False]))

Output:

2019-10-28 01:20:00+01:00    0
2019-10-28 02:36:00+01:00    1
2019-10-28 03:46:00+01:00    2
dtype: int64

Previous: Resample Pandas time-series data
Next: Select all the values in a row at the particular time of the day