DOC: update Series.sort_values docstring #20247

rafarui · 2018-03-10T21:36:58Z

Co-authored-by: @marielen

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
############## Docstring (pandas.core.series.Series.sort_values)  ##############
################################################################################

Sort by the values.

Sort a Series in ascending or descending order by some
criterion.

Parameters
----------
axis : {0 or 'index'}, default 0
    Axis to direct sorting. The value 'index' is accepted for
    compatibility with DataFrame.sort_values.
ascending : bool, default True
    If  True sort values in ascending order, otherwise descending.
inplace : bool, default False
    If True, perform operation in-place.
kind : {'quicksort', 'mergesort' or 'heapsort'}, default 'quicksort'
    Choice of sorting algorithm. See also :func:'numpy.sort' for more
    information. 'mergesort' is the only stable  algorithm.
na_position : {'first' or 'last'}, default 'last'
    Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
    the end.

Returns
-------
Series
    Series ordered by values.

See Also
--------
Series.sort_index : Sort by the Series indices.
DataFrame.sort_index : Sort DataFrame by indices.
DataFrame.sort_values : Sort by the values along either axis.

Examples
--------
>>> s = pd.Series([np.nan, 1, 3, 10, 5])
>>> s
0     NaN
1     1.0
2     3.0
3     10.0
4     5.0
dtype: float64

Sort values ascending order (default behaviour)

>>> s.sort_values(ascending=True)
1     1.0
2     3.0
4     5.0
3    10.0
0     NaN
dtype: float64

Sort values descending order

>>> s.sort_values(ascending=False)
3    10.0
4     5.0
2     3.0
1     1.0
0     NaN
dtype: float64

Sort values inplace

>>> s.sort_values(ascending=False, inplace=True)
>>> s
3    10.0
4     5.0
2     3.0
1     1.0
0     NaN
dtype: float64

Sort values putting NAs first

>>> s.sort_values(na_position='first')
0     NaN
1     1.0
2     3.0
4     5.0
3    10.0
dtype: float64

Sort a series of strings

>>> s = pd.Series(['z', 'b', 'd', 'a', 'c'])
>>> s
0    z
1    b
2    d
3    a
4    c
dtype: object

>>> s.sort_values()
3    a
1    b
4    c
2    d
0    z
dtype: object

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.core.series.Series.sort_values" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

DOC Series.sort_values docstring [Sao Paulo]

pep8speaks · 2018-03-10T21:37:00Z

Hello @rafarui! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 12, 2018 at 14:59 Hours UTC

jorisvandenbossche · 2018-03-10T21:40:00Z

Can you follow the guidelines please: paste the output of the validation script above (you can still edit your top post). And check PEP8 as well, as you have some errors there.

jorisvandenbossche · 2018-03-10T21:41:58Z

pandas/core/series.py

+        Parameters
+        ----------
+        axis : {0 or ‘index’}, default 0
+            Axis to direct sorting.


I would mention here that is can only be 0 for Series (accepted for compatibility with DataFrame.sort_values)

jorisvandenbossche · 2018-03-10T21:42:50Z

pandas/core/series.py

+        inplace : bool, default False
+            If True, perform operation in-place.
+        kind : {‘quicksort’, ‘mergesort’ or ‘heapsort’}, default ‘quicksort’
+            Choice of sorting algorithm. See also ndarray.np.sort [1]_ for more information. `mergesort` is the only stable


you can use :func:`np.sort` as a syntax to create this reference automatically (then you don't need the [1]_

jorisvandenbossche · 2018-03-10T21:43:46Z

pandas/core/series.py

+        7     45.0
+        dtype: float64
+
+        Sort values ascending order


Can you add something like (default behaviour) ?

jorisvandenbossche · 2018-03-10T21:45:37Z

pandas/core/series.py

+
+        Examples
+        --------
+        >>> s = pd.Series([np.nan, 1, 232, 323, 1, 2, 3, 45])


I would make this a bit shorter (try to aim at 5 elements)

math-and-data · 2018-03-10T21:54:34Z

pandas/core/series.py

+        2    232.0
+        3    323.0
+        dtype: float64
+        """


If you find time, it would be nice to have an example that includes strings as well so that users see that sorting can apply to anything.

math-and-data · 2018-03-10T21:57:34Z

pandas/core/series.py

+        0      NaN
+        dtype: float64
+
+        Sort values descending order


Quick grammar comment: Sort values in descending order

math-and-data · 2018-03-10T21:57:44Z

pandas/core/series.py

+        7     45.0
+        dtype: float64
+
+        Sort values ascending order


Quick grammar comment: Sort values in ascending order

fix reviewed pull request

jorisvandenbossche · 2018-03-10T23:24:50Z

pandas/core/series.py

        Examples
        --------
-        >>> s = pd.Series([np.nan, 1, 232, 323, 1, 2, 3, 45])
+        >>> s = pd.Series([np.nan, 1, 3, 5, 10])


maybe put the 5 and 10 out of order?

change example as suggested

jreback · 2018-03-11T13:46:18Z

pandas/core/series.py

+        """
+        Sort by the Series values.
+
+        Sort (or order) a Series in ascending or descending order by some


by the values.

jreback · 2018-03-11T13:46:33Z

pandas/core/series.py

+        """
+        Sort by the Series values.
+
+        Sort (or order) a Series in ascending or descending order by some


just say Sort

Fix short description

jreback · 2018-03-11T14:03:24Z

lgtm. @jorisvandenbossche

jorisvandenbossche

Looking good! Added a few more comments

jorisvandenbossche · 2018-03-12T08:57:20Z

pandas/core/series.py

+        inplace : bool, default False
+            If True, perform operation in-place.
+        kind : {‘quicksort’, ‘mergesort’ or ‘heapsort’}, default ‘quicksort’
+            Choice of sorting algorithm. See also :func:`np.sort` for more


np.sort -> numpy.sort

jorisvandenbossche · 2018-03-12T08:57:31Z

pandas/core/series.py

+            If True, perform operation in-place.
+        kind : {‘quicksort’, ‘mergesort’ or ‘heapsort’}, default ‘quicksort’
+            Choice of sorting algorithm. See also :func:`np.sort` for more
+             information. `mergesort` is the only stable  algorithm.


identation is off by one space here

jorisvandenbossche · 2018-03-12T08:58:02Z

pandas/core/series.py

+            Choice of sorting algorithm. See also :func:`np.sort` for more
+             information. `mergesort` is the only stable  algorithm.
+        na_position : {'first' or 'last'}, default 'last'
+             Argument `first` puts NaNs at the beginning, `last` puts NaNs at


For first and last, can you use normal single quotes (not backticks) like in the line above?

jorisvandenbossche · 2018-03-12T09:02:01Z

pandas/core/series.py

+            If  `True` sort values in ascending order, otherwise descending.
+        inplace : bool, default False
+            If True, perform operation in-place.
+        kind : {‘quicksort’, ‘mergesort’ or ‘heapsort’}, default ‘quicksort’


it seems you are using here not the 'normal' single quote, but king of curved smart quote. Can you change this? (see the quotes in the type description of the na_position keyword, that are the good ones)

fix quotes

fix ident

jorisvandenbossche · 2018-03-12T15:00:07Z

@rafarui Thanks a lot!

rafarui and others added 5 commits March 10, 2018 15:56

sort_values docstring

04c8faa

fix

206b7e6

fix

388ed2b

fix type True/False

027e1e5

Merge pull request #1 from rafarui/pandas-sort_values

4aea67c

DOC Series.sort_values docstring [Sao Paulo]

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

math-and-data reviewed Mar 10, 2018

View reviewed changes

rafarui and others added 2 commits March 10, 2018 20:16

fix reviewed pull request

fef8f4c

Merge pull request #2 from rafarui/pandas-sort_values

fb7c0c8

fix reviewed pull request

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

change example ordered as suggested

3c61e6e

jorisvandenbossche added the Docs label Mar 10, 2018

Merge pull request #3 from rafarui/pandas-sort_values

973b741

change example as suggested

jreback requested changes Mar 11, 2018

View reviewed changes

jreback added the Reshaping Concat, Merge/Join, Stack/Unstack, Explode label Mar 11, 2018

rafarui and others added 2 commits March 11, 2018 10:53

Fix short description

3d19051

Merge pull request #4 from rafarui/pandas-sort_values

668ada1

Fix short description

jreback approved these changes Mar 11, 2018

View reviewed changes

jreback added this to the 0.23.0 milestone Mar 11, 2018

rafarui mentioned this pull request Mar 11, 2018

DOC: update the Series.sort_values docstring #20215

Closed

9 tasks

jorisvandenbossche reviewed Mar 12, 2018

View reviewed changes

rafarui and others added 5 commits March 12, 2018 08:35

fix quotes

8b09ee5

Merge pull request #5 from rafarui/pandas-sort_values

3af4e29

fix quotes

fix ident

afc528d

Merge pull request #6 from rafarui/pandas-sort_values

1264a6b

fix ident

Update series.py

9717c8b

jorisvandenbossche approved these changes Mar 12, 2018

View reviewed changes

jorisvandenbossche merged commit b2e472a into pandas-dev:master Mar 12, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update Series.sort_values docstring #20247

DOC: update Series.sort_values docstring #20247

rafarui commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading

jorisvandenbossche commented Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jorisvandenbossche Mar 10, 2018

math-and-data Mar 10, 2018

math-and-data Mar 10, 2018

math-and-data Mar 10, 2018

jorisvandenbossche Mar 10, 2018

jreback Mar 11, 2018

jreback Mar 11, 2018

jreback commented Mar 11, 2018

jorisvandenbossche left a comment

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche commented Mar 12, 2018

DOC: update Series.sort_values docstring #20247

DOC: update Series.sort_values docstring #20247

Conversation

rafarui commented Mar 10, 2018 • edited Loading

pep8speaks commented Mar 10, 2018 • edited Loading

Comment last updated on March 12, 2018 at 14:59 Hours UTC

jorisvandenbossche commented Mar 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback commented Mar 11, 2018

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 12, 2018

rafarui commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading