DOC: update the pd.Index.argsort docstring #20232

dajcs · 2018-03-10T20:28:49Z

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.Index.argsort) #######################
################################################################################

Return the order of the indices.

We have an object with values and index. Using argsort method
returns a series of indices that would sort the index.

Parameters
----------
*args
    Passed to `numpy.ndarray.argsort`.
**kwargs
    Passed to `numpy.ndarray.argsort`.

Returns
-------
numpy.ndarray : Argsorted indices of the index

See also
--------
numpy.ndarray.argsort : Returns the indices that would sort this array.

Examples
--------
>>> s = pd.Series(data=[4,3,2,1],index=['c','b','a','d'])
>>> s.index.argsort()
array([2, 1, 0, 3], dtype=int64)

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

Errors found:
        Errors in parameters section
                Parameters {'args', 'kwargs'} not documented
                Unknown parameters {'**kwargs', '*args'}
                Parameter "*args" has no type
                Parameter "**kwargs" has no type

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.

We did our best to explain *args and **kwargs

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

closes #xxxx
tests added / passed
passes git diff upstream/master -u -- "*.py" | flake8 --diff
whatsnew entry

TomAugspurger · 2018-03-10T20:33:54Z

pandas/core/indexes/base.py

@@ -2316,16 +2316,31 @@ def shift(self, periods=1, freq=None):

    def argsort(self, *args, **kwargs):
        """
-        Returns the indices that would sort the index and its
-        underlying data.
+        Return the order of the indices.


Hmm I think the "would sort" is important. Does "Return the order of the indices that would sort the index" sound OK and fit on a line?

@TomAugspurger I think "order of the indices" is a bit strange no? I think it would be either "Return the order of the index" or "Return the indices that would sort the index", but not the combination

TomAugspurger · 2018-03-10T20:35:02Z

pandas/core/indexes/base.py

-        underlying data.
+        Return the order of the indices.
+
+        We have an object with values and index. Using argsort method


Probably don't need this section.

TomAugspurger · 2018-03-10T20:35:26Z

pandas/core/indexes/base.py


        See also
        --------
-        numpy.ndarray.argsort
+        numpy.ndarray.argsort : Returns the indices that would sort this array.


Say "similar method for NumPy arrays."

TomAugspurger · 2018-03-10T20:35:41Z

pandas/core/indexes/base.py

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


PEP8: spacing after commas.

jorisvandenbossche

Don't worry about the validation script erroring on the args/kwargs

jorisvandenbossche · 2018-03-10T20:35:41Z

pandas/core/indexes/base.py

+        Return the order of the indices.
+
+        We have an object with values and index. Using argsort method
+        returns a series of indices that would sort the index.


series -> array ?

jorisvandenbossche · 2018-03-10T20:37:40Z

pandas/core/indexes/base.py

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


I think you can create the Index directly like idx = pd.Index(['c', ..]) and then use that

ok, I will make two examples, one with series and one with index.

jreback · 2018-03-10T21:35:16Z

pandas/core/indexes/base.py

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


can you put spaces between the commas

jreback · 2018-03-10T21:35:40Z

pandas/core/indexes/base.py

+
+        Parameters
+        ----------
+        *args


@jorisvandenbossche this is the correct format for args/kwargs?

Yes, I was only thinking it might actually make more sense to list the ones that are useful. I think it is only kind ? (axis certainly not, and order not as well?)

yes we do this for Series.argsort now. so should replicate here. or shared these doc-strings (best)

jreback · 2018-03-10T21:36:01Z

pandas/core/indexes/base.py


        See also
        --------
-        numpy.ndarray.argsort
+        numpy.ndarray.argsort : Similar method for NumPy arrays.


see also Index.sort_values

jorisvandenbossche · 2018-03-10T23:14:00Z

pandas/core/indexes/base.py

@@ -2316,16 +2316,36 @@ def shift(self, periods=1, freq=None):

    def argsort(self, *args, **kwargs):
        """
-        Returns the indices that would sort the index and its
-        underlying data.
+        Return the order of the indices that would sort the index.


See #20232 (comment)

jreback · 2018-03-11T14:19:25Z

pandas/core/indexes/base.py

+
+        Parameters
+        ----------
+        *args


yes we do this for Series.argsort now. so should replicate here. or shared these doc-strings (best)

jreback · 2018-03-11T14:19:38Z

pandas/core/indexes/base.py


        See also
        --------
-        numpy.ndarray.argsort
+        numpy.ndarray.argsort : Similar method for NumPy arrays.
+        pd.Index.sort_values : Return sorted copy of Index


don't need the pd.

jreback · 2018-03-11T14:20:13Z

pandas/core/indexes/base.py

+        >>> pd.Index(['b','a','d','c']).argsort()
+        array([1, 0, 3, 2], dtype=int64)
+
+        When applying argsort to a Series object then the result won't


I don't think from here down is relevant. Series has its own example.

TomAugspurger · 2018-03-12T17:17:51Z

Thanks @dajcs!

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

jreback requested changes Mar 10, 2018

View reviewed changes

jreback added Docs Reshaping Concat, Merge/Join, Stack/Unstack, Explode labels Mar 10, 2018

DOC: update the pd.Index.argsort docstring

5a183d8

dajcs force-pushed the docstring_index_argsort branch from a1e9329 to 5a183d8 Compare March 10, 2018 21:50

jorisvandenbossche reviewed Mar 10, 2018

View reviewed changes

jreback requested changes Mar 11, 2018

View reviewed changes

TomAugspurger added 3 commits March 12, 2018 12:15

Updated

d421131

Clarify

2ea5416

Missing .

4a61dd4

TomAugspurger merged commit 0ed9916 into pandas-dev:master Mar 12, 2018

Uh oh!

DOC: update the pd.Index.argsort docstring #20232

DOC: update the pd.Index.argsort docstring #20232

Uh oh!

Conversation

dajcs commented Mar 10, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TomAugspurger commented Mar 12, 2018

Uh oh!

Uh oh!