diff --git a/ci/code_checks.sh b/ci/code_checks.sh index add35ffbd3b8e..e76d355f139ed 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -91,7 +91,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Series.size \ pandas.Series.T \ pandas.Series.hasnans \ - pandas.Series.to_timestamp \ pandas.Series.to_list \ pandas.Series.__iter__ \ pandas.Series.keys \ @@ -218,7 +217,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Period.year \ pandas.Period.asfreq \ pandas.Period.now \ - pandas.Period.to_timestamp \ pandas.arrays.PeriodArray \ pandas.Interval.closed \ pandas.Interval.left \ @@ -562,7 +560,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.DataFrame.swapaxes \ pandas.DataFrame.first_valid_index \ pandas.DataFrame.last_valid_index \ - pandas.DataFrame.to_timestamp \ pandas.DataFrame.attrs \ pandas.DataFrame.plot \ pandas.DataFrame.sparse.density \ diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 77c8be6be07e4..f44178700503d 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1841,6 +1841,13 @@ cdef class _Period(PeriodMixin): Returns ------- Timestamp + + Examples + -------- + >>> period = pd.Period('2023-1-1', freq='D') + >>> timestamp = period.to_timestamp() + >>> timestamp + Timestamp('2023-01-01 00:00:00') """ how = validate_end_alias(how) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 79f423b17383d..16fc4a19aefaf 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -11013,6 +11013,37 @@ def to_timestamp( ------- DataFrame The DataFrame has a DatetimeIndex. + + Examples + -------- + >>> idx = pd.PeriodIndex(['2023', '2024'], freq='Y') + >>> d = {'col1': [1, 2], 'col2': [3, 4]} + >>> df1 = pd.DataFrame(data=d, index=idx) + >>> df1 + col1 col2 + 2023 1 3 + 2024 2 4 + + The resulting timestamps will be at the beginning of the year in this case + + >>> df1 = df1.to_timestamp() + >>> df1 + col1 col2 + 2023-01-01 1 3 + 2024-01-01 2 4 + >>> 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 + + >>> df2 = pd.DataFrame(data=d, index=idx) + >>> df2 = df2.to_timestamp(freq='M') + >>> df2 + col1 col2 + 2023-01-31 1 3 + 2024-01-31 2 4 + >>> df2.index + DatetimeIndex(['2023-01-31', '2024-01-31'], dtype='datetime64[ns]', freq=None) """ new_obj = self.copy(deep=copy) diff --git a/pandas/core/series.py b/pandas/core/series.py index d69c057c85783..9693cac38a01c 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -5710,6 +5710,35 @@ def to_timestamp( Returns ------- Series with DatetimeIndex + + Examples + -------- + >>> idx = pd.PeriodIndex(['2023', '2024', '2025'], freq='Y') + >>> s1 = pd.Series([1, 2, 3], index=idx) + >>> s1 + 2023 1 + 2024 2 + 2025 3 + Freq: A-DEC, dtype: int64 + + The resulting frequency of the Timestamps is `YearBegin` + + >>> s1 = s1.to_timestamp() + >>> s1 + 2023-01-01 1 + 2024-01-01 2 + 2025-01-01 3 + Freq: AS-JAN, dtype: int64 + + Using `freq` which is the offset that the Timestamps will have + + >>> s2 = pd.Series([1, 2, 3], index=idx) + >>> s2 = s2.to_timestamp(freq='M') + >>> s2 + 2023-01-31 1 + 2024-01-31 2 + 2025-01-31 3 + Freq: A-JAN, dtype: int64 """ if not isinstance(self.index, PeriodIndex): raise TypeError(f"unsupported Type {type(self.index).__name__}")