From a855c283c0b1b375c958fb9f9d7e8a5b5e41dab8 Mon Sep 17 00:00:00 2001 From: Natalia Mokeeva Date: Thu, 8 Aug 2024 23:06:04 +0200 Subject: [PATCH] Clarify the documentation for DataFrame.to_timestamp and DataFrame.to_timestamp --- pandas/core/frame.py | 28 ++++++++++++++++++++++------ pandas/core/series.py | 21 +++++++++++++++++---- 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index ea91046f4b8e4..982d36ed26360 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -13151,9 +13151,11 @@ def to_timestamp( copy: bool | lib.NoDefault = lib.no_default, ) -> DataFrame: """ - Cast PeriodIndex to DatetimeIndex of timestamps, at *beginning* of period. + Cast PeriodIndex to DatetimeIndex of timestamps. - This can be changed to the *end* of the period, by specifying `how="e"`. + Will cast at *beginning* of period if `freq` which is the offset frequency + is None. This can be changed to the *end* of the period, by specifying + `how="e"`. Will cast to the *end* of the period when specifying `freq`. Parameters ---------- @@ -13211,15 +13213,29 @@ def to_timestamp( >>> df1.index DatetimeIndex(['2023-01-01', '2024-01-01'], dtype='datetime64[ns]', freq=None) - Using `freq` which is the offset that the Timestamps will have + By specifying `how="e"` we can change the resulting timestamps to be + at the end of the year >>> df2 = pd.DataFrame(data=d, index=idx) - >>> df2 = df2.to_timestamp(freq="M") - >>> df2 + >>> df2 = df2.to_timestamp(how="e") + col1 col2 + 2023-12-31 23:59:59.999999999 1 3 + 2024-12-31 23:59:59.999999999 2 4 + >>> df2.index + DatetimeIndex(['2023-12-31 23:59:59.999999999', + '2024-12-31 23:59:59.999999999'], + dtype='datetime64[ns]', + freq=None) + + Using `freq` which is the offset that the Timestamps will have + + >>> df3 = pd.DataFrame(data=d, index=idx) + >>> df3 = df3.to_timestamp(freq="M") + >>> df3 col1 col2 2023-01-31 1 3 2024-01-31 2 4 - >>> df2.index + >>> df3.index DatetimeIndex(['2023-01-31', '2024-01-31'], dtype='datetime64[ns]', freq=None) """ self._check_copy_deprecation(copy) diff --git a/pandas/core/series.py b/pandas/core/series.py index a197886748bce..8428b9a330f87 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -5568,9 +5568,11 @@ def to_timestamp( copy: bool | lib.NoDefault = lib.no_default, ) -> Series: """ - Cast to DatetimeIndex of Timestamps, at *beginning* of period. + Cast PeriodIndex to DatetimeIndex of timestamps. - This can be changed to the *end* of the period, by specifying `how="e"`. + Will cast at *beginning* of period if `freq` which is the offset frequency + is None. This can be changed to the *end* of the period, by specifying + `how="e"`. Will cast to the *end* of the period when specifying `freq`. Parameters ---------- @@ -5625,11 +5627,22 @@ def to_timestamp( 2025-01-01 3 Freq: YS-JAN, dtype: int64 - Using `freq` which is the offset that the Timestamps will have + By specifying `how="e"` we can change the resulting timestamps to be + at the end of the year >>> s2 = pd.Series([1, 2, 3], index=idx) - >>> s2 = s2.to_timestamp(freq="M") + >>> s2 = s2.to_timestamp(how="e") >>> s2 + 2023-12-31 23:59:59.999999999 1 + 2024-12-31 23:59:59.999999999 2 + 2025-12-31 23:59:59.999999999 3 + dtype: int64 + + Using `freq` which is the offset that the Timestamps will have + + >>> s3 = pd.Series([1, 2, 3], index=idx) + >>> s3 = s3.to_timestamp(freq="M") + >>> s3 2023-01-31 1 2024-01-31 2 2025-01-31 3