Improve doc strings, also indexer_at/between/_time

Author: tp

pandas/core/generic.py

@@ -6703,9 +6703,10 @@ def at_time(self, time, asof=False):
         """
         Select values at particular time of day (e.g. 9:30AM).
 
-        Notes
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        AttributeError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
@@ -6717,25 +6718,27 @@ def at_time(self, time, asof=False):
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='4D2min')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='12H')
         >>> 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')
+        2018-04-09 12:00:00  2
+        2018-04-10 00:00:00  3
+        2018-04-10 12:00:00  4
+
+        >>> ts.at_time('12:00')
                              A
-        date
-        2018-04-13 00:02:00  2
+        2018-04-09 12:00:00  2
+        2018-04-10 12:00:00  4
 
         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
+        DatetimeIndex.indexer_at_time : Get just the index positions for
+            values at particular time of the day
         """
         try:
             indexer = self.index.indexer_at_time(time, asof=asof)
@@ -6748,9 +6751,13 @@ 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
+        By setting ``start_time`` to be later than ``end_time``,
+        you can get the times that are *not* between the two times.
+
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        AttributeError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
@@ -6765,24 +6772,35 @@ def between_time(self, start_time, end_time, include_start=True,
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='2min')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='1D20min')
         >>> 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')
+        2018-04-10 00:20:00  2
+        2018-04-11 00:40:00  3
+        2018-04-12 01:00:00  4
+
+        >>> ts.between_time('0:15', '0:45')
                              A
-        2018-04-09 00:02:00  2
-        2018-04-09 00:04:00  3
+        2018-04-10 00:20:00  2
+        2018-04-11 00:40:00  3
+
+        You get the times that are *not* between two times by setting
+        ``start_time`` later than ``end_time``:
+
+        >>> ts.between_time('0:45', '0:15')
+                             A
+        2018-04-09 00:00:00  1
+        2018-04-12 01:00:00  4
 
         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
+        DatetimeIndex.indexer_between_time : Get just the index positions for
+            values between particular times of the day
         """
         try:
             indexer = self.index.indexer_between_time(
@@ -7036,29 +7054,36 @@ def first(self, offset):
         Convenience method for subsetting initial periods of time series data
         based on a date offset.
 
-        Notes
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        NotImplementedError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
         offset : string, DateOffset, dateutil.relativedelta
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='D')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
         >>> 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
+        2018-04-11  2
+        2018-04-13  3
+        2018-04-15  4
+
+        Get the rows for the first 3 days:
+
         >>> ts.first('3D')
                     A
         2018-04-09  1
-        2018-04-10  2
-        2018-04-11  3
+        2018-04-11  2
+
+        Notice the data for 3 first calender days were returned, not the first
+        3 days observed in the dataset, and therefore data for 2018-04-13 was
+        not returned.
 
         Returns
         -------
@@ -7094,29 +7119,36 @@ def last(self, offset):
         Convenience method for subsetting final periods of time series data
         based on a date offset.
 
-        Notes
+        Raises
         -----
-        For this method to work, the index must to be a :class:`DatetimeIndex`
+        NotImplementedError
+            If the index is not  a :class:`DatetimeIndex`
 
         Parameters
         ----------
         offset : string, DateOffset, dateutil.relativedelta
 
         Examples
         --------
-        >>> i = pd.date_range('2018-04-09', periods=4, freq='D')
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
         >>> 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
+        2018-04-11  2
+        2018-04-13  3
+        2018-04-15  4
+
+        Get the rows for the last 3 days:
+
         >>> ts.last('3D')
                     A
-        2018-04-10  2
-        2018-04-11  3
-        2018-04-12  4
+        2018-04-13  3
+        2018-04-15  4
+
+        Notice the data for 3 last calender days were returned, not the last
+        3 observed days in the dataset. and therefore data for 2018-04-13 was
+        not returned.
 
         Returns
         -------

pandas/core/indexes/datetimes.py

@@ -2378,15 +2378,23 @@ def tz_localize(self, tz, ambiguous='raise', errors='raise'):
 
     def indexer_at_time(self, time, asof=False):
         """
-        Select values at particular time of day (e.g. 9:30AM)
+        Returns index locations of index values at particular time of day
+        (e.g. 9:30AM).
 
         Parameters
         ----------
         time : datetime.time or string
+            datetime.time or string in appropriate format ("%H:%M", "%H%M",
+            "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
+            "%I%M%S%p").
 
         Returns
         -------
-        values_at_time : TimeSeries
+        values_at_time : array of integers
+
+        See Also
+        --------
+        indexer_between_time, DataFrame.at_time
         """
         from dateutil.parser import parse
 
@@ -2408,24 +2416,25 @@ def indexer_at_time(self, time, asof=False):
     def indexer_between_time(self, start_time, end_time, include_start=True,
                              include_end=True):
         """
-        Select values between particular times of day (e.g., 9:00-9:30AM).
-
-        Return values of the index between two times.  If start_time or
-        end_time are strings then tseries.tools.to_time is used to convert to
-        a time object.
+        Return index locations of values between particular times of day
+        (e.g., 9:00-9:30AM).
 
         Parameters
         ----------
         start_time, end_time : datetime.time, str
             datetime.time or string in appropriate format ("%H:%M", "%H%M",
             "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
-            "%I%M%S%p")
+            "%I%M%S%p").
         include_start : boolean, default True
         include_end : boolean, default True
 
         Returns
         -------
-        values_between_time : TimeSeries
+        values_between_time : array of integers
+
+        See Also
+        --------
+        indexer_at_time, DataFrame.between_time
         """
         start_time = tools.to_time(start_time)
         end_time = tools.to_time(end_time)