DOC: time_rule deprecation in sphinx docs for moving window functions #1042. Also started on new timeseries docs.

Author: Chang She

doc/source/computation.rst

@@ -171,8 +171,10 @@ accept the following arguments:
   - ``window``: size of moving window
   - ``min_periods``: threshold of non-null data points to require (otherwise
     result is NA)
-  - ``time_rule``: optionally specify a :ref:`time rule <timeseries.timerule>`
-    to pre-conform the data to
+  - ``freq``: optionally specify a :ref: `frequency string <timeseries.freq>` or :ref:`DateOffset <timeseries.offsets>`
+    to pre-conform the data to. Note that prior to pandas v0.8.0, a keyword
+    argument ``time_rule`` was used instead of ``freq`` that referred to
+    the legacy time rule constants
 
 These functions can be applied to ndarrays or Series objects:
 

doc/source/timeseries.rst

@@ -130,44 +130,123 @@ particular day of the week:
    d + Week(weekday=4)
    (d + Week(weekday=4)).weekday()
 
-.. _timeseries.timerule:
+.. _timeseries.freq:
 
-Time rules
-~~~~~~~~~~
+Offset Aliases
+~~~~~~~~~~~~~~
 
 A number of string aliases are given to useful common time series
-frequencies. We will refer to these aliases as *time rules*.
+frequencies. We will refer to these aliases as *offset aliases*
+(referred to as *time rules* prior to v0.8.0).
 
 .. csv-table::
-    :header: "Rule name", "Description"
+    :header: "Alias", "Description"
     :widths: 15, 65
 
-    "WEEKDAY", "business day frequency"
-    "EOM", "business month end frequency"
-    "W\@MON", "weekly frequency (mondays)"
-    "W\@TUE", "weekly frequency (tuesdays)"
-    "W\@WED", "weekly frequency (wednesdays)"
-    "W\@THU", "weekly frequency (thursdays)"
-    "W\@FRI", "weekly frequency (fridays)"
-    "Q\@JAN", "quarterly frequency, starting January"
-    "Q\@FEB", "quarterly frequency, starting February"
-    "Q\@MAR", "quarterly frequency, starting March"
-    "A\@DEC", "annual frequency, year end (December)"
-    "A\@JAN", "annual frequency, anchored end of January"
-    "A\@FEB", "annual frequency, anchored end of February"
-    "A\@MAR", "annual frequency, anchored end of March"
-    "A\@APR", "annual frequency, anchored end of April"
-    "A\@MAY", "annual frequency, anchored end of May"
-    "A\@JUN", "annual frequency, anchored end of June"
-    "A\@JUL", "annual frequency, anchored end of July"
-    "A\@AUG", "annual frequency, anchored end of August"
-    "A\@SEP", "annual frequency, anchored end of September"
-    "A\@OCT", "annual frequency, anchored end of October"
-    "A\@NOV", "annual frequency, anchored end of November"
-
-These can be used as arguments to ``DateRange`` and various other time
+    "B", "business day frequency"
+    "D", "calendar day frequency"
+    "W", "weekly frequency"
+    "M", "month end frequency"
+    "BM", "business month end frequency"
+    "MS", "month start frequency"
+    "BMS", "business month start frequency"
+    "Q", "quarter end frequency"
+    "BQ", "business quarter endfrequency"
+    "QS", "quarter start frequency"
+    "BQS", "business quarter start frequency"
+    "A", "year end frequency"
+    "BA", "business year end frequency"
+    "AS", "year start frequency"
+    "BAS", "business year start frequency"
+    "H", "hourly frequency"
+    "T", "minutely frequency"
+    "S", "secondly frequency"
+    "L", "milliseonds"
+    "U", "microseconds"
+
+For some frequencies you can specify an anchoring suffix:
+
+.. csv-table::
+    :header: "Alias", "Description"
+    :widths: 15, 65
+
+    "W\-SUN", "weekly frequency (sundays). Same as 'W'"
+    "W\-MON", "weekly frequency (mondays)"
+    "W\-TUE", "weekly frequency (tuesdays)"
+    "W\-WED", "weekly frequency (wednesdays)"
+    "W\-THU", "weekly frequency (thursdays)"
+    "W\-FRI", "weekly frequency (fridays)"
+    "W\-SAT", "weekly frequency (saturdays)"
+    "(B)Q(S)\-DEC", "quarterly frequency, year ends in December. Same as 'Q'"
+    "(B)Q(S)\-JAN", "quarterly frequency, year ends in January"
+    "(B)Q(S)\-FEB", "quarterly frequency, year ends in February"
+    "(B)Q(S)\-MAR", "quarterly frequency, year ends in March"
+    "(B)Q(S)\-APR", "quarterly frequency, year ends in April"
+    "(B)Q(S)\-MAY", "quarterly frequency, year ends in May"
+    "(B)Q(S)\-JUN", "quarterly frequency, year ends in June"
+    "(B)Q(S)\-JUL", "quarterly frequency, year ends in July"
+    "(B)Q(S)\-AUG", "quarterly frequency, year ends in August"
+    "(B)Q(S)\-SEP", "quarterly frequency, year ends in September"
+    "(B)Q(S)\-OCT", "quarterly frequency, year ends in October"
+    "(B)Q(S)\-NOV", "quarterly frequency, year ends in November"
+    "(B)A(S)\-DEC", "annual frequency, anchored end of December. Same as 'A'"
+    "(B)A(S)\-JAN", "annual frequency, anchored end of January"
+    "(B)A(S)\-FEB", "annual frequency, anchored end of February"
+    "(B)A(S)\-MAR", "annual frequency, anchored end of March"
+    "(B)A(S)\-APR", "annual frequency, anchored end of April"
+    "(B)A(S)\-MAY", "annual frequency, anchored end of May"
+    "(B)A(S)\-JUN", "annual frequency, anchored end of June"
+    "(B)A(S)\-JUL", "annual frequency, anchored end of July"
+    "(B)A(S)\-AUG", "annual frequency, anchored end of August"
+    "(B)A(S)\-SEP", "annual frequency, anchored end of September"
+    "(B)A(S)\-OCT", "annual frequency, anchored end of October"
+    "(B)A(S)\-NOV", "annual frequency, anchored end of November"
+
+These can be used as arguments to ``date_range``, ``period_range``, constructors
+for ``PeriodIndex`` and ``DatetimeIndex``, as well as various other time
 series-related functions in pandas.
 
+Note that prior to v0.8.0, time rules had a slightly different look. Pandas
+will continue to support the legacy time rules for the time being but it is
+strongly recommended that you switch to using the new offset aliases.
+
+.. csv-table::
+    :header: "Legacy Time Rule", "Offset Alias"
+    :widths: 15, 15
+
+    "WEEKDAY", "B"
+    "EOM", "BM"
+    "W\@MON", "W\-MON"
+    "W\@TUE", "W\-TUE"
+    "W\@WED", "W\-WED"
+    "W\@THU", "W\-THU"
+    "W\@FRI", "W\-FRI"
+    "W\@SAT", "W\-SAT"
+    "W\@SUN", "W\-SUN"
+    "Q\@JAN", "BQ\-JAN"
+    "Q\@FEB", "BQ\-FEB"
+    "Q\@MAR", "BQ\-MAR"
+    "A\@JAN", "BA\-JAN"
+    "A\@FEB", "BA\-FEB"
+    "A\@MAR", "BA\-MAR"
+    "A\@APR", "BA\-APR"
+    "A\@MAY", "BA\-MAY"
+    "A\@JUN", "BA\-JUN"
+    "A\@JUL", "BA\-JUL"
+    "A\@AUG", "BA\-AUG"
+    "A\@SEP", "BA\-SEP"
+    "A\@OCT", "BA\-OCT"
+    "A\@NOV", "BA\-NOV"
+    "A\@DEC", "BA\-DEC"
+    "min", "T"
+    "ms", "L"
+    "us": "U"
+
+Note that the legacy quarterly and annual frequencies are business quarter and
+business year ends. Also note the legacy time rule for milliseconds ``ms``
+versus the new offset alias for month start ``MS``. This means that offset
+alias parsing is case sensitive.
+
 .. _timeseries.daterange:
 
 Generating date ranges (DateRange)