w3resource

Pandas Series: tz_localize() function

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')
Pandas Series tz_localize image

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
Pandas Series tz_localize image

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



Follow us on Facebook and Twitter for latest update.