ENH: timezone-aware `Period`

[rwijtvliet]

Is your feature request related to a problem?

A Timestamp with a freq attribute can be used as a replacement/workaround for a Period, if time-zone awareness is needed. Below is an example.

With the deprecation of the .freq attribute for individual timestamps, this workaround will stop working in a future release.

Describe the solution you'd like

Implementation of timezone-awareness in the Period class.

API breaking implications

Period and PeriodIndex initializers take an additional tz parameter.

Describe alternatives you've considered

The alternative is what I'm currently using (Timestamp.freq) but will be deprecated.

Additional context

Current implementation of this functionality:

import pandas as pd


def ts_right(ts_left: pd.Timestamp) -> pd.Timestamp:
    """Right-bound timestamp associated with a (left-bound) timestamp."""
    if ts_left.freq == "D":
        kwargs = {"days": 1}
    elif ts_left.freq == "MS":
        kwargs = {"months": 1}
    elif ts_left.freq == "QS":
        kwargs = {"months": 3}
    elif ts_left.freq == "AS":
        kwargs = {"years": 1}
    else:
        raise ValueError(f"Invalid frequency: {ts_left.freq}.")
    return ts_left + pd.DateOffset(**kwargs)


def duration(ts_left: pd.Timestamp) -> float:
    """Duration [h] associated with a timestamp."""
    return (ts_right(ts_left) - ts_left).total_seconds() / 3600


ts1 = pd.Timestamp("2022-03-01", tz="Europe/Berlin", freq="D")  # "Timestamp.freq is deprecated and will be removed in a future version"
ts_right(ts1)  # Timestamp('2022-03-02 00:00:00+0100', tz='Europe/Berlin')
duration(ts1)  # 24.0

ts2 = pd.Timestamp("2022-03-27", tz="Europe/Berlin", freq="D")  # "Timestamp.freq is deprecated and will be removed in a future version"
ts_right(ts2)  # Timestamp('2022-03-28 00:00:00+0200', tz='Europe/Berlin')
duration(ts2)  # 23.0

[jbrockmendel]

Is there a reason you can't pass freq as a separate argument to ts_right?

[rwijtvliet]

Thanks @jbrockmendel. The Timestamp instances are used throughout my code to indicate periods of various natural lengths - an hour, a day, a month, etc. Without the freq attribute, I'd need to start passing two pieces of information around, or think of a replacement objects, e.g. (Timestamp, freq)-tuples, or custom dataclass instances.

In addition, the integration with the pandas.DatetimeIndex would be lost. Currently, if a DatetimeIndex has the .freq attribute set, each element is a pandas.Timestamp instance with the same .freq attribute. I can't imagine how I'll deal with the situations where I currently take a single element from such an index, which will in the future lose that .freq attribute.

(Including where this is done under the hood, e.g. when selecting a single Series entry or DataFrame row with .loc or iloc. etc.)

Don't get me wrong, I agree that timestamps denote infinitely short moments in time and have no 'duration' associated with them. But it's a workaround until Periods become timezone-aware - and the mentioned deprecation puts me in a bit of a bind.

[mroeschke]

Semantically Periods are spans of time (akin to timedeltas) which are supposed to be agnostic to timezone arithmetic in the first place, so I don't think it makes much sense to add timezone to a period

[rwijtvliet]

Thanks for your reply @mroeschke. Could you please expand on that? I've seen similar comments before, but I never understand the reasoning behind them.

The analogy to timestamps is very clear to me:

• A timestamp can be agnostic regarding UTC-offset, but, in order to unambiguously specify the moment that is meant, a UTC-offset must be included. 2022-02-11T15:00:00 (i.e., UTC-offset-agnostic) only works if the use-case implies a single non-changing timezone. If you tell me: "meet me (online) at 2022-02-11T15:00:00", it will not work unless you also tell me the UTC-offset. I think we all agree on this.
• Analogously: a time period can be timezone-agnostic, but, in order to unambiguously specify the time span that is meant, a timezone must be included. The calendar day 2022-02-11 (i.e., timezone-agnostic) only works if the use-case implies a single non-changing timezone. If you tell me: "send me a message sometime during the calendar day 2022-02-11 (and not on the day before or the day after)" I can't tell when that period is exactly, unless you also tell me its timezone.

The natural relation between periods and timestamps is that some timestamps fall inside the period, and other do not. If the timestamp is UTC-offset-agnostic, I can verify if it falls inside a timezone-agnostic period. Likewise, I should be able to verify if a timestamp with a UTC-offset falls inside a timezone-aware period. I.e., the timestamp 2022-02-11T01:00:00+04:00 falls within the calendar day 2022-02-11 of the Aukland timezone, but not of the New York timezone.

[rwijtvliet]

Now, that is not to say that I don't see that timezone-awareness in periods is more complex than in timestamps. Here are some of the difficulties:

• I can convert a timestamp from one UTC-offset to another. The same is not possible for periods. The calendar day 2022-03-27 in the Aukland timezone cannot be converted to an equally natural period in the New York timezone, simply because it cuts across 2 calendar days in that timezone. However, this is not a bug, but a feature: it's simply the reality of the situation.

• A timestamp belongs to exactly one timezone, expressed as offset from UTC, like +04:00 in my previous post. Periods can start with a timestamp having one offset, and end with a timestamp having another. For example, the 2022-03-27 in the Europe/Berlin timezone starts at 2022-03-27T00:00:00+01:00 and ends at 2022-03-28T00:00:00+02:00, and therefore only spans 23 * 3600 seconds, rather than the usual 24 * 3600 seconds. This too, however, is the reality of the situation, and not a bug but a feature.

NB: The latter example is what I'm currently using timezone-aware timestamps with frequency for. start = pd.Timestamp('2022-03-27 00:00', tz='Europe/Berlin', freq='D') gives me the correct start timestamp (2022-03-27 00:00:00+0100') and start + 1 * start.freq gives the correct end timestamp (2022-03-28 01:00:00+0200), note the difference in UTC offsets.

I hope I've been able to make my case :) But please share your perspectives and/or try to convince me otherwise.

[rwijtvliet]

One final thought. I don't want to go into possible implementation details here, but I think it's important to realize that a timezone can be expressed in two ways: as an offset from UTC (e.g., '+01:00'), or as tied to a geographic location (e.g., 'Europe/Berlin').

• The only way that makes sense for timezone-aware timestamps is the offset from UTC. Using the location can be ambiguous: 2022-10-30 02:30 (Europe/Berlin) can be either +01:00 or +02:00 due to the DST changeover

• The only way that makes sense for timezone-aware periods is the geographic location, as the start and end timestamps might have distinct UTC-offsets, as in the example in my previous post.

[jreback]

a period could have time zone aware end points but i don't see a good reason for a time zone aware duration (not to mention a massive increase in complexity)

same reason we are killing the freq attribute in a Timestamp which is an instant

[rwijtvliet]

If the end points are timezone-aware, the duration (which I understand to be the timedelta duration = end-start) is already taken care of.

[jreback]

exactly so why would you then need a time zone if a Period? or rather what does it mean at all? what if u have naive endpoints? what if it had time zone aware endpoints?

this is such a huge ambiguity that it is unworkable