DOC: update the pandas.Series.sort_index docstring #20248

dsakuma · 2018-03-10T21:39:45Z

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.Series.sort_index) #####################
################################################################################

Sort Series by index labels.

Returns a new Series sorted by label if `inplace` argument is `False`,
otherwise updates the original series and returns `null`.

Parameters
----------
axis : int, default 0
    Axis to direct sorting. This can only be 0 for Series.
level : int, optional
    If not None, sort on values in specified index level(s).
ascending : bool, default true
    Sort ascending vs. descending.
inplace : bool, default False
    If True, perform operation in-place.
kind : {'quicksort', 'mergesort', 'heapsort'}, default 'quicksort'
    Choice of sorting algorithm. See also :func:`numpy.sort` for more
    information.  'mergesort' is the only stable algorithm. For
    DataFrames, this option is only applied when sorting on a single
    column or label.
na_position : {'first', 'last'}, default 'last'
    If 'first' puts NaNs at the beginning, 'last' puts NaNs at the end.
    Not implemented for MultiIndex.
sort_remaining : bool, default True
    If true and sorting by level and index is multilevel, sort by other
    levels too (in order) after sorting by specified level.

Returns
-------
pandas.Series
    The original Series sorted by the labels

See Also
--------
DataFrame.sort_index: Sort DataFrame by the index
DataFrame.sort_values: Sort DataFrame by the value
Series.sort_values : Sort Series by the value

Examples
--------
>>> s = pd.Series(['a', 'b', 'c', 'd'], index=[3, 2, 1, 4])
>>> s.sort_index()
1    c
2    b
3    a
4    d
dtype: object

Sort Descending

>>> s.sort_index(ascending=False)
4    d
3    a
2    b
1    c
dtype: object

Sort Inplace

>>> s.sort_index(inplace=True)
>>> s
1    c
2    b
3    a
4    d
dtype: object

By default NaNs are put at the end, but use `na_position` to place
them at the beginning

>>> s = pd.Series(['a', 'b', 'c', 'd'], index=[3, 2, 1, np.nan])
>>> s.sort_index(na_position='first')
NaN     d
 1.0    c
 2.0    b
 3.0    a
dtype: object

Specify index level to sort

>>> arrays = [np.array(['qux', 'qux', 'foo', 'foo',
...                     'baz', 'baz', 'bar', 'bar']),
...           np.array(['two', 'one', 'two', 'one',
...                     'two', 'one', 'two', 'one'])]
>>> s = pd.Series([1, 2, 3, 4, 5, 6, 7, 8], index=arrays)
>>> s.sort_index(level=1)
bar  one    8
baz  one    6
foo  one    4
qux  one    2
bar  two    7
baz  two    5
foo  two    3
qux  two    1
dtype: int64

Does not sort by remaining levels when sorting by levels

>>> s.sort_index(level=1, sort_remaining=False)
qux  one    2
foo  one    4
baz  one    6
bar  one    8
qux  two    1
foo  two    3
baz  two    5
bar  two    7
dtype: int64

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

Docstring for "pandas.Series.sort_index" correct. :)

pep8speaks · 2018-03-10T21:39:47Z

Hello @dsakuma! Thanks for updating the PR.

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

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

villasv

Looking good

villasv · 2018-03-10T21:43:25Z

pandas/core/series.py


+        Returns
+        -------
+        sorted_obj : Series


Return values don't need names unless with tuples. Also missing description.

villasv · 2018-03-10T21:43:42Z

pandas/core/series.py

+
+        >>> import numpy as np
+        >>> arrays = [np.array(['qux', 'qux', 'foo', 'foo',\
+                                'baz', 'baz', 'bar', 'bar']),


Bad indentation.

jreback

lgtm. very minor change. ping when pushed.

jreback · 2018-03-11T13:44:19Z

pandas/core/series.py

+
+        Specify index level to sort
+
+        >>> import numpy as np


don't need the numpy import

jreback · 2018-03-11T13:47:54Z

pandas/core/series.py

+
+        See Also
+        --------
+        sort_values : Sort by the value


can you add DataFrame.sort_index, DataFrame.sort_values

jreback · 2018-03-11T13:48:03Z

pandas/core/series.py

+
+        See Also
+        --------
+        sort_values : Sort by the value


make this Series.sort_values

jorisvandenbossche

Thanks for the PR! Added some more comments

jorisvandenbossche · 2018-03-11T14:16:48Z

pandas/core/series.py

    def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
                   kind='quicksort', na_position='last', sort_remaining=True):
+        """
+        Sort object by labels.


"Sort object by labels." -> "Sort Series by index labels." (if we make the docstring specific for Series and not share it with DataFrame, we can make it more specific)

jorisvandenbossche · 2018-03-11T14:17:29Z

pandas/core/series.py

+        Parameters
+        ----------
+        axis : int, default 0
+            Axis to direct sorting.


Can you mention this can only be 0 for Series ?

jorisvandenbossche · 2018-03-11T14:17:48Z

pandas/core/series.py

+        ----------
+        axis : int, default 0
+            Axis to direct sorting.
+        level : int, default None


" default None" -> "optional"

jorisvandenbossche · 2018-03-11T14:18:10Z

pandas/core/series.py

+            Axis to direct sorting.
+        level : int, default None
+            If not None, sort on values in specified index level(s).
+        ascending : boolean, default true


boolean -> bool (consistent with keyword below)

jorisvandenbossche · 2018-03-11T14:18:49Z

pandas/core/series.py

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


"ndarray.np.sort" -> "numpy.sort"
(or even better to link to the docs: :func:`numpy.sort`)

jorisvandenbossche · 2018-03-11T14:20:04Z

pandas/core/series.py

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


you can use normal quotes in this case (like 'mergesort') to indicate it is a string

jorisvandenbossche · 2018-03-11T14:20:52Z

pandas/core/series.py

+            DataFrames, this option is only applied when sorting on a single
+            column or label.
+        na_position : {'first', 'last'}, default 'last'
+            If `first` puts NaNs at the beginning, `last` puts NaNs at the end.


same here (using normal quotes instead of backticks around first and last)

jorisvandenbossche · 2018-03-11T14:21:33Z

pandas/core/series.py

+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'b', 'c', 'd'], index=[3,2,1,4])


spaces after comma (PEP8)

jorisvandenbossche

Added some more comments on the examples. We are getting there!

jorisvandenbossche · 2018-03-12T16:32:26Z

pandas/core/series.py

+
+        Examples
+        --------
+        >>> s = pd.Series(['a','b','c','d'], index=[3,2,1,4])


Can you add spaces after the comma for PEP8 in all examples?
Maybe my previous comment was unclear, but the ['a', 'b', 'c', 'd'], was already good, but commented for adding spaces in [3,2,1,4]

jorisvandenbossche · 2018-03-12T16:32:36Z

pandas/core/series.py

+            DataFrames, this option is only applied when sorting on a single
+            column or label.
+        na_position : {'first', 'last'}, default 'last'
+            If `first` puts NaNs at the beginning, 'last' puts NaNs at the end.


'first' also with normal single quotes

jorisvandenbossche · 2018-03-12T16:34:50Z

pandas/core/series.py


+        Sort Descending
+
+        >>> s = pd.Series(['a','b','c','d'], index=[3,2,1,4])


You don't need to re-define the series, the examples are run in the same process, so it still knows the s from the previous one. So this full lines can be removed.

jorisvandenbossche · 2018-03-12T16:35:00Z

pandas/core/series.py

+
+        Sort Inplace
+
+        >>> s = pd.Series(['a','b','c','d'], index=[3,2,1,4])


jorisvandenbossche · 2018-03-12T16:35:26Z

pandas/core/series.py

+
+        Sort placing NaNs at first
+
+        >>> s = pd.Series(['a','b','c','d'], index=[3,2,1,np.nan])


this one is fine to keep since it is a different series (but same comment regarding PEP8)

jorisvandenbossche · 2018-03-12T16:36:13Z

pandas/core/series.py

+        4    d
+        dtype: object
+
+        Sort placing NaNs at first


Can you change "Sort placing NaNs at first" in "By default NaNs are put at the end, but use na_position to place them at the beginning"

jorisvandenbossche · 2018-03-12T16:37:11Z

pandas/core/series.py

+        ...                     'baz','baz','bar','bar']),
+        ...           np.array(['two','one','two','one',
+        ...                     'two','one','two','one'])]
+        >>> s = pd.Series([1,2,3,4,5,6,7,8], index=arrays)


jorisvandenbossche · 2018-03-12T16:37:24Z

pandas/core/series.py

+        ...                     'baz','baz','bar','bar']),
+        ...           np.array(['two','one','two','one',
+        ...                     'two','one','two','one'])]
+        >>> s = pd.Series([1,2,3,4,5,6,7,8], index=arrays)


Sam here, this does not need to be redefined

dsakuma · 2018-03-12T16:55:13Z

@jorisvandenbossche, @jreback and @villasv Thanks for the comments!

jorisvandenbossche · 2018-03-12T17:00:16Z

@dsakuma Thanks a lot!

Improve docstring for pandas.Series.sort_index

b2ca255

villasv approved these changes Mar 10, 2018

View reviewed changes

Fix style and add description to Return section

0bc7869

jorisvandenbossche added the Docs label Mar 10, 2018

jreback approved these changes Mar 11, 2018

View reviewed changes

pandas/core/series.py Outdated

Specify index level to sort

>>> import numpy as np

Copy link

Contributor

jreback Mar 11, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't need the numpy import

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

jreback added this to the 0.23.0 milestone Mar 11, 2018

jreback reviewed Mar 11, 2018

View reviewed changes

pandas/core/series.py Outdated

See Also

--------

sort_values : Sort by the value

Copy link

Contributor

jreback Mar 11, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

make this Series.sort_values

jorisvandenbossche reviewed Mar 11, 2018

View reviewed changes

Change docstring to be more specific for Series and fix style

5e061fb

jorisvandenbossche reviewed Mar 12, 2018

View reviewed changes

Improve text and fix style

7457421

Update series.py

3a66142

jorisvandenbossche approved these changes Mar 12, 2018

View reviewed changes

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the pandas.Series.sort_index docstring #20248

DOC: update the pandas.Series.sort_index docstring #20248

dsakuma commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading

villasv left a comment

villasv Mar 10, 2018

villasv Mar 10, 2018

jreback left a comment

jreback Mar 11, 2018

jreback Mar 11, 2018

jreback Mar 11, 2018

jorisvandenbossche left a comment

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche Mar 11, 2018

jorisvandenbossche left a comment

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

jorisvandenbossche Mar 12, 2018

dsakuma commented Mar 12, 2018

jorisvandenbossche commented Mar 12, 2018


		Sort Descending

		>>> s = pd.Series(['a','b','c','d'], index=[3,2,1,4])


		Sort Inplace

		>>> s = pd.Series(['a','b','c','d'], index=[3,2,1,4])


		Sort placing NaNs at first

		>>> s = pd.Series(['a','b','c','d'], index=[3,2,1,np.nan])

DOC: update the pandas.Series.sort_index docstring #20248

DOC: update the pandas.Series.sort_index docstring #20248

Conversation

dsakuma commented Mar 10, 2018 • edited Loading

pep8speaks commented Mar 10, 2018 • edited Loading

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

villasv left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jreback 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

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

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

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

dsakuma commented Mar 12, 2018

jorisvandenbossche commented Mar 12, 2018

dsakuma commented Mar 10, 2018 •

edited

Loading

pep8speaks commented Mar 10, 2018 •

edited

Loading