Merge pull request #6848 from jreback/sort

API: make Series.sort/order arguments in the same order

Author: jreback

doc/source/release.rst

@@ -86,7 +86,7 @@ API Changes
   for a Series with a ``DatetimeIndex`` or a ``PeriodIndex``; trying this on a non-supported Index type will
   now raise a ``TypeError``. (:issue:`4551`, :issue:`4056`, :issue:`5519`)
 
-  The following affected:
+  The following are affected:
 
   - ``date,time,year,month,day``
   - ``hour,minute,second,weekofyear``
@@ -135,26 +135,20 @@ API Changes
     the name of the inserted column containing the pivoted data.
 
 - Allow specification of a more complex groupby, via ``pd.Grouper`` (:issue:`3794`)
-
 - A tuple passed to ``DataFame.sort_index`` will be interpreted as the levels of
   the index, rather than requiring a list of tuple (:issue:`4370`)
-
 - Fix a bug where invalid eval/query operations would blow the stack (:issue:`5198`)
-
 - Following keywords are now acceptable for :meth:`DataFrame.plot` with ``kind='bar'`` and ``kind='barh'``:
 
   - `width`: Specify the bar width. In previous versions, static value 0.5 was passed to matplotlib and it cannot be overwritten. (:issue:`6604`)
-
-  - `align`: Specify the bar alignment. Default is `center` (different from matplotlib). In previous versions, pandas passes `align='edge'` to matplotlib and adjust the location to `center` by itself, and it results `align` keyword is not applied as expected. (:issue:`4525`)
-
+  - `align`: Specify the bar alignment. Default is `center` (different from matplotlib). In previous versions, pandas passes `align='edge'` to
+    matplotlib and adjust the location to `center` by itself, and it results `align` keyword is not applied as expected. (:issue:`4525`)
   - `position`: Specify relative alignments for bar plot layout. From 0 (left/bottom-end) to 1 (right/top-end). Default is 0.5 (center). (:issue:`6604`)
 
 - Define and document the order of column vs index names in query/eval (:issue:`6676`)
-
 - ``DataFrame.sort`` now places NaNs at the beginning or end of the sort according to the ``na_position`` parameter. (:issue:`3917`)
 - ``stack`` and ``unstack`` now raise a ``ValueError`` when the ``level`` keyword refers
   to a non-unique item in the ``Index`` (previously raised a ``KeyError``). (:issue:`6738`)
-
 - all offset operations now return ``Timestamp`` types (rather than datetime), Business/Week frequencies were incorrect (:issue:`4069`)
 - ``Series.iteritems()`` is now lazy (returns an iterator rather than a list). This was the documented behavior prior to 0.14. (:issue:`6760`)
 - ``Panel.shift`` now uses ``NDFrame.shift``. It no longer drops the ``nan`` data and retains its original shape.  (:issue:`4867`)
@@ -163,19 +157,19 @@ API Changes
   representation) (:issue:`6782`)
 - Arithmetic ops are now disallowed when passed two bool dtype Series or
   DataFrames (:issue:`6762`).
-
 - Added ``nunique`` and ``value_counts`` functions to ``Index`` for counting unique elements. (:issue:`6734`)
 
 - ``DataFrame.plot`` and ``Series.plot`` now support a ``table`` keyword for plotting ``matplotlib.Table``. The ``table`` kewyword can receive the following values.
 
   - ``False``: Do nothing (default).
-
   - ``True``: Draw a table using the ``DataFrame`` or ``Series`` called ``plot`` method. Data will be transposed to meet matplotlib's default layout.
-
   - ``DataFrame`` or ``Series``: Draw matplotlib.table using the passed data. The data will be drawn as displayed in print method (not transposed automatically).
-
   Also, helper function ``pandas.tools.plotting.table`` is added to create a table from ``DataFrame`` and ``Series``, and add it to an ``matplotlib.Axes``.
 
+- drop unused order argument from ``Series.sort``; args now in the same orders as ``Series.order``;
+  add ``na_position`` arg to conform to ``Series.order`` (:issue:`6847`)
+- default sorting algorithm for ``Series.order`` is not ``quicksort``, to conform with ``Series.sort``
+  (and numpy defaults)
 
 Deprecations
 ~~~~~~~~~~~~

doc/source/v0.14.0.txt

@@ -65,7 +65,7 @@ API changes
   for a Series with a ``DatetimeIndex`` or a ``PeriodIndex``; trying this on a non-supported Index type will
   now raise a ``TypeError``. (:issue:`4551`, :issue:`4056`, :issue:`5519`)
 
-  The following affected:
+  The following are affected:
 
   - ``date,time,year,month,day``
   - ``hour,minute,second,weekofyear``
@@ -208,6 +208,10 @@ API changes
 - Added ``nunique`` and ``value_counts`` functions to ``Index`` for counting unique elements. (:issue:`6734`)
 - ``stack`` and ``unstack`` now raise a ``ValueError`` when the ``level`` keyword refers
   to a non-unique item in the ``Index`` (previously raised a ``KeyError``).
+- drop unused order argument from ``Series.sort``; args now in the same orders as ``Series.order``;
+  add ``na_position`` arg to conform to ``Series.order`` (:issue:`6847`)
+- default sorting algorithm for ``Series.order`` is not ``quicksort``, to conform with ``Series.sort``
+  (and numpy defaults)
 
 .. _whatsnew_0140.sql:
 
@@ -329,20 +333,15 @@ Plotting
 ~~~~~~~~
 
 - Hexagonal bin plots from ``DataFrame.plot`` with ``kind='hexbin'`` (:issue:`5478`), See :ref:`the docs<visualization.hexbin>`.
-
 - Plotting with Error Bars is now supported in the ``.plot`` method of ``DataFrame`` and ``Series`` objects (:issue:`3796`), See :ref:`the docs<visualization.errorbars>`.
-
 - ``DataFrame.plot`` and ``Series.plot`` now support a ``table`` keyword for plotting ``matplotlib.Table``, See :ref:`the docs<visualization.table>`.
-
 - ``plot(legend='reverse')`` will now reverse the order of legend labels for
   most plot kinds. (:issue:`6014`)
 
 - Following keywords are now acceptable for :meth:`DataFrame.plot(kind='bar')` and :meth:`DataFrame.plot(kind='barh')`.
 
   - `width`: Specify the bar width. In previous versions, static value 0.5 was passed to matplotlib and it cannot be overwritten. (:issue:`6604`)
-
   - `align`: Specify the bar alignment. Default is `center` (different from matplotlib). In previous versions, pandas passes `align='edge'` to matplotlib and adjust the location to `center` by itself, and it results `align` keyword is not applied as expected. (:issue:`4525`)
-
   - `position`: Specify relative alignments for bar plot layout. From 0 (left/bottom-end) to 1(right/top-end). Default is 0.5 (center). (:issue:`6604`)
 
   Because of the default `align` value changes, coordinates of bar plots are now located on integer values (0.0, 1.0, 2.0 ...). This is intended to make bar plot be located on the same coodinates as line plot. However, bar plot may differs unexpectedly when you manually adjust the bar location or drawing area, such as using `set_xlim`, `set_ylim`, etc. In this cases, please modify your script to meet with new coordinates.
@@ -355,28 +354,19 @@ Prior Version Deprecations/Changes
 There are prior version deprecations that are taking effect as of 0.14.0.
 
 - Remove :class:`DateRange` in favor of :class:`DatetimeIndex` (:issue:`6816`)
-
 - Remove ``column`` keyword from ``DataFrame.sort`` (:issue:`4370`)
-
 - Remove ``precision`` keyword from :func:`set_eng_float_format` (:issue:`395`)
-
 - Remove ``force_unicode`` keyword from :meth:`DataFrame.to_string`,
   :meth:`DataFrame.to_latex`, and :meth:`DataFrame.to_html`; these function
   encode in unicode by default (:issue:`2224`, :issue:`2225`)
-
 - Remove ``nanRep`` keyword from :meth:`DataFrame.to_csv` and
   :meth:`DataFrame.to_string` (:issue:`275`)
-
 - Remove ``unique`` keyword from :meth:`HDFStore.select_column` (:issue:`3256`)
-
 - Remove ``inferTimeRule`` keyword from :func:`Timestamp.offset` (:issue:`391`)
-
 - Remove ``name`` keyword from :func:`get_data_yahoo` and
   :func:`get_data_google` ( `commit b921d1a <https://github.com/pydata/pandas/commit/b921d1a2>`__ )
-
 - Remove ``offset`` keyword from :class:`DatetimeIndex` constructor
   ( `commit 3136390 <https://github.com/pydata/pandas/commit/3136390>`__ )
-
 - Remove ``time_rule`` from several rolling-moment statistical functions, such
   as :func:`rolling_sum` (:issue:`1042`)
 

pandas/core/series.py

@@ -1563,20 +1563,22 @@ def update(self, other):
     #----------------------------------------------------------------------
     # Reindexing, sorting
 
-    def sort(self, axis=0, kind='quicksort', order=None, ascending=True):
+    def sort(self, axis=0, ascending=True, kind='quicksort', na_position='last'):
         """
         Sort values and index labels by value, in place. For compatibility with
         ndarray API. No return value
 
         Parameters
         ----------
         axis : int (can only be zero)
+        ascending : boolean, default True
+            Sort ascending. Passing False sorts descending
         kind : {'mergesort', 'quicksort', 'heapsort'}, default 'quicksort'
             Choice of sorting algorithm. See np.sort for more
             information. 'mergesort' is the only stable algorithm
-        order : ignored
-        ascending : boolean, default True
-            Sort ascending. Passing False sorts descending
+        na_position : {'first', 'last'} (optional, default='last')
+            'first' puts NaNs at the beginning
+            'last' puts NaNs at the end
 
         See Also
         --------
@@ -1588,9 +1590,9 @@ def sort(self, axis=0, kind='quicksort', order=None, ascending=True):
             raise ValueError("This Series is a view of some other array, to "
                              "sort in-place you must create a copy")
 
-        result = self.order(kind=kind,
-                            ascending=ascending,
-                            na_position='last')
+        result = self.order(ascending=ascending,
+                            kind=kind,
+                            na_position=na_position)
 
         self._update_inplace(result)
 
@@ -1690,7 +1692,7 @@ def rank(self, method='average', na_option='keep', ascending=True,
                      ascending=ascending, pct=pct)
         return self._constructor(ranks, index=self.index).__finalize__(self)
 
-    def order(self, na_last=None, ascending=True, kind='mergesort', na_position='last'):
+    def order(self, na_last=None, ascending=True, kind='quicksort', na_position='last'):
         """
         Sorts Series object, by value, maintaining index-value link
 
@@ -1700,7 +1702,7 @@ def order(self, na_last=None, ascending=True, kind='mergesort', na_position='las
             Put NaN's at beginning or end
         ascending : boolean, default True
             Sort ascending. Passing False sorts descending
-        kind : {'mergesort', 'quicksort', 'heapsort'}, default 'mergesort'
+        kind : {'mergesort', 'quicksort', 'heapsort'}, default 'quicksort'
             Choice of sorting algorithm. See np.sort for more
             information. 'mergesort' is the only stable algorithm
         na_position : {'first', 'last'} (optional, default='last')