add Notes, Examples and See Also to at_time/between_time/first/last

Author: tp

pandas/core/generic.py

@@ -6770,13 +6770,39 @@ def at_time(self, time, asof=False):
         """
         Select values at particular time of day (e.g. 9:30AM).
 
+        Notes
+        -----
+        For this method to work, the index must to be a :class:`DatetimeIndex`
+
         Parameters
         ----------
         time : datetime.time or string
 
         Returns
         -------
         values_at_time : type of caller
+
+        Examples
+        --------
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='4D2min')
+        >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
+        >>> ts
+                             A
+        date
+        2018-04-09 00:00:00  1
+        2018-04-13 00:02:00  2
+        2018-04-17 00:04:00  3
+        2018-04-21 00:06:00  4
+        >>> ts.at_time('0:02')
+                             A
+        date
+        2018-04-13 00:02:00  2
+
+        See Also
+        --------
+        between_time : Select values between particular times of the day
+        first : Select initial periods of time series based on a date offset
+        last : Select final periods of time series based on a date offset
         """
         try:
             indexer = self.index.indexer_at_time(time, asof=asof)
@@ -6789,6 +6815,10 @@ def between_time(self, start_time, end_time, include_start=True,
         """
         Select values between particular times of the day (e.g., 9:00-9:30 AM).
 
+        Notes
+        -----
+        For this method to work, the index must to be a :class:`DatetimeIndex`
+
         Parameters
         ----------
         start_time : datetime.time or string
@@ -6799,6 +6829,27 @@ def between_time(self, start_time, end_time, include_start=True,
         Returns
         -------
         values_between_time : type of caller
+
+        Examples
+        --------
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2min')
+        >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
+        >>> ts
+                             A
+        2018-04-09 00:00:00  1
+        2018-04-09 00:02:00  2
+        2018-04-09 00:04:00  3
+        2018-04-09 00:06:00  4
+        >>> ts.between_time('0:02', '0:04')
+                             A
+        2018-04-09 00:02:00  2
+        2018-04-09 00:04:00  3
+
+        See Also
+        --------
+        at_time : Select values at a particular time of the day
+        first : Select initial periods of time series based on a date offset
+        last : Select final periods of time series based on a date offset
         """
         try:
             indexer = self.index.indexer_between_time(
@@ -7052,17 +7103,39 @@ def first(self, offset):
         Convenience method for subsetting initial periods of time series data
         based on a date offset.
 
+        Notes
+        -----
+        For this method to work, the index must to be a :class:`DatetimeIndex`
+
         Parameters
         ----------
         offset : string, DateOffset, dateutil.relativedelta
 
         Examples
         --------
-        ts.first('10D') -> First 10 days
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='D')
+        >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
+        >>> ts
+                    A
+        2018-04-09  1
+        2018-04-10  2
+        2018-04-11  3
+        2018-04-12  4
+        >>> ts.first('3D')
+                    A
+        2018-04-09  1
+        2018-04-10  2
+        2018-04-11  3
 
         Returns
         -------
         subset : type of caller
+
+        See Also
+        --------
+        last : Select final periods of time series based on a date offset
+        at_time : Select values at a particular time of the day
+        between_time : Select values between particular times of the day
         """
         from pandas.tseries.frequencies import to_offset
         if not isinstance(self.index, DatetimeIndex):
@@ -7088,17 +7161,39 @@ def last(self, offset):
         Convenience method for subsetting final periods of time series data
         based on a date offset.
 
+        Notes
+        -----
+        For this method to work, the index must to be a :class:`DatetimeIndex`
+
         Parameters
         ----------
         offset : string, DateOffset, dateutil.relativedelta
 
         Examples
         --------
-        ts.last('5M') -> Last 5 months
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='D')
+        >>> ts = pd.DataFrame({'A': [1,2,3,4]}, index=i)
+        >>> ts
+                    A
+        2018-04-09  1
+        2018-04-10  2
+        2018-04-11  3
+        2018-04-12  4
+        >>> ts.last('3D')
+                    A
+        2018-04-10  2
+        2018-04-11  3
+        2018-04-12  4
 
         Returns
         -------
         subset : type of caller
+
+        See Also
+        --------
+        first : Select initial periods of time series based on a date offset
+        at_time : Select values at a particular time of the day
+        between_time : Select values between particular times of the day
         """
         from pandas.tseries.frequencies import to_offset
         if not isinstance(self.index, DatetimeIndex):