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 locations 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 locations 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)