DOC: update the Index.get_level_values docstring #20210

bkil-syslogng · 2018-03-10T18:09:28Z

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.get_level_values)  ##################
################################################################################

Return an Index of values for requested level.

Return an Index of values for requested level, equal to the length
of the index.

Parameters
----------
level : int or str
    It is either the integer position of the level in the
    MultiIndex, or the `name` of the level.
    If given as an integer, it must be between 0 and the
    number of levels.

Returns
-------
values : Index
    `self`, as there is only one level in the Index.

See also
---------
pandas.MultiIndex.get_level_values : get values for a level of a
                                     MultiIndex

Notes
---------
For `Index`, level should be 0, since there are no multiple levels.

Examples
---------

Create an Index:

>>> idx = pd.Index(list('abc'))

Get level value by supplying level as integer:

>>> idx.get_level_values(0)
Index(['a', 'b', 'c'], dtype='object')

Create a MultiIndex:

>>> mi = pd.MultiIndex.from_arrays((list('abc'), list('def')))
>>> mi.names = ['level_1', 'level_2']

Get level values by supplying level as name:

>>> mi.get_level_values('level_2')
Index(['d', 'e', 'f'], dtype='object', name='level_2')

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

Docstring for "pandas.Index.get_level_values" correct. :)

TomAugspurger · 2018-03-10T18:38:08Z

pandas/core/indexes/base.py

-            ``level`` is either the integer position of the level in the
-            MultiIndex, or the name of the level.
+            It is either the integer position of the level in the
+            MultiIndex, or the `name` of the level.


Don't think name has to be in backticks, since it isn't a parameter

Since MultiIndex has its own docstring, you probably don't have to reference it here.

TomAugspurger · 2018-03-10T18:38:29Z

pandas/core/indexes/base.py

+            It is either the integer position of the level in the
+            MultiIndex, or the `name` of the level.
+            If given as an integer, it must be between 0 and the
+            number of levels.


Number of levels - 1?

TomAugspurger · 2018-03-10T18:39:48Z

pandas/core/indexes/base.py

+        Examples
+        ---------
+
+        Create an Index:


Probalby don't need this line. I'd remove it and add a line showing idx

TomAugspurger · 2018-03-10T18:40:06Z

pandas/core/indexes/base.py

+
+        Create a MultiIndex:
+
+        >>> mi = pd.MultiIndex.from_arrays((list('abc'), list('def')))


can pass names= to from_arrays

Although line wrapping would be needed and this case and it would still end up in two lines, which isn't as nice in my opinion. Although I'll change it as you've requested.

TomAugspurger · 2018-03-10T18:40:57Z

pandas/core/indexes/base.py

@@ -2788,26 +2788,55 @@ def set_value(self, arr, key, value):

    def _get_level_values(self, level):
        """
+        Return an Index of values for requested level.
+
        Return an Index of values for requested level, equal to the length


I would add that this is mainly for compatibility with MultiIndex.

TomAugspurger · 2018-03-10T18:43:08Z

Reading through this, it may make sense to say that this isn't very useful for non-MultiIndex indexes. A small example should be OK, but the most important bit is the See Also to MultiIndex.get_level_values.

joaoavf

Very good, I would just make it clear in the summary and extended summary that this method is specially useful to deal with MultiIndex.

joaoavf · 2018-03-10T18:39:59Z

pandas/core/indexes/base.py

@@ -2788,26 +2788,55 @@ def set_value(self, arr, key, value):

    def _get_level_values(self, level):
        """
+        Return an Index of values for requested level.


Return an Index of values for requested level. --> Return an Index of values for requested level, specially useful for MultiIndex.

It is important to make it clear somehow that this is most useful when dealing with a MultiIndex.

jreback · 2018-03-10T19:56:06Z

pandas/core/indexes/base.py


+        Notes
+        ---------
+        For `Index`, level should be 0, since there are no multiple levels.


no backticks

jreback · 2018-03-10T19:56:49Z

pandas/core/indexes/base.py

+        Create an Index:
+
+        >>> idx = pd.Index(list('abc'))
+


I wouldn't bother show this for an Index.

Please elaborate what kind of change you would like to us to make. MultiIndex already mentions the other example. In our view, working on an Index is also useful to see for users somewhere, and this would be a proper place for it.

bkil-syslogng · 2018-03-10T21:10:16Z

Most of the notes have been addressed and force pushed.

jreback · 2018-03-11T14:48:45Z

pandas/core/indexes/base.py

@@ -2788,26 +2788,45 @@ def set_value(self, arr, key, value):

    def _get_level_values(self, level):
        """
+        Return an Index of values for requested level, specially useful for


need to be 1 line. you can remove after the comma.

jreback · 2018-03-11T14:49:02Z

pandas/core/indexes/base.py


+        Notes
+        ---------


make the same length as Notes

TomAugspurger · 2018-03-11T15:05:50Z

pandas/core/indexes/base.py

@@ -2788,26 +2788,45 @@ def set_value(self, arr, key, value):

    def _get_level_values(self, level):
        """
+        Return an Index of values for requested level, specially useful for
+        MultiIndex.
+
        Return an Index of values for requested level, equal to the length


This is pretty repetitive with the summary. I think just the bit about MultiIndex is useful.

The is primarily useful to get an individual level of values from a MultiIndex, but is provided on Index as well for compatability.

TomAugspurger · 2018-03-11T15:07:29Z

pandas/core/indexes/base.py

-            ``level`` is either the integer position of the level in the
-            MultiIndex, or the name of the level.
+            It is either the integer position or the name of the level.
+            If given as an integer, it must be between 0 and the


Ah this isn't quite right. Negative indices are accepted as well. Probably OK to just remove the second sentence, as to most Python programmers, "integer position" is clear enough.

TomAugspurger · 2018-03-11T15:08:06Z

pandas/core/indexes/base.py

+        >>> idx
+        Index(['a', 'b', 'c'], dtype='object')
+
+        Get level value by supplying level as integer:


backtick around `level`. Add "an" between "as integer"

jorisvandenbossche · 2018-03-17T12:01:46Z

@bkil-syslogng Do you have time to update the PR based on the last comments?

…ating_Index.get_level_values_docstring

codecov · 2018-07-08T15:06:39Z

Codecov Report

❗ No coverage uploaded for pull request base (master@20ca108). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20210   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49162           
  Branches          ?        0           
=========================================
  Hits              ?    45096           
  Misses            ?     4066           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.11% <100%> (?)`
#single	`41.86% <56.25%> (?)`

Impacted Files	Coverage Δ
pandas/core/indexes/base.py	`96.66% <100%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 20ca108...6aa8b77. Read the comment docs.

jorisvandenbossche · 2018-07-08T15:07:08Z

Rebased and added final fixes.

@bkil-syslogng Thanks!

TomAugspurger reviewed Mar 10, 2018

View reviewed changes

TomAugspurger added Docs MultiIndex labels Mar 10, 2018

joaoavf reviewed Mar 10, 2018

View reviewed changes

jreback requested changes Mar 10, 2018

View reviewed changes

DOC: Improve the docstring of Index.get_level_values

fe2f525

bkil-syslogng force-pushed the updating_Index.get_level_values_docstring branch from 90e6b68 to fe2f525 Compare March 10, 2018 20:51

jreback requested changes Mar 11, 2018

View reviewed changes

TomAugspurger reviewed Mar 11, 2018

View reviewed changes

jorisvandenbossche added 2 commits July 8, 2018 10:01

Merge remote-tracking branch 'upstream/master' into bkil-syslogng-upd…

6c00bd6

…ating_Index.get_level_values_docstring

fixups

6aa8b77

jorisvandenbossche added this to the 0.24.0 milestone Jul 8, 2018

jorisvandenbossche merged commit 44c08d4 into pandas-dev:master Jul 8, 2018

Sup3rGeo pushed a commit to Sup3rGeo/pandas that referenced this pull request Oct 1, 2018

DOC: update the Index.get_level_values docstring (pandas-dev#20210)

cb5f820

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: update the Index.get_level_values docstring #20210

DOC: update the Index.get_level_values docstring #20210

bkil-syslogng commented Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger Mar 10, 2018

bkil-syslogng Mar 10, 2018

TomAugspurger Mar 10, 2018

TomAugspurger commented Mar 10, 2018

joaoavf left a comment

joaoavf Mar 10, 2018

jreback Mar 10, 2018

jreback Mar 10, 2018

bkil-syslogng Mar 10, 2018

bkil-syslogng commented Mar 10, 2018

jreback Mar 11, 2018

jreback Mar 11, 2018

TomAugspurger Mar 11, 2018

TomAugspurger Mar 11, 2018

TomAugspurger Mar 11, 2018

jorisvandenbossche commented Mar 17, 2018

codecov bot commented Jul 8, 2018

jorisvandenbossche commented Jul 8, 2018


		Create a MultiIndex:

		>>> mi = pd.MultiIndex.from_arrays((list('abc'), list('def')))

DOC: update the Index.get_level_values docstring #20210

DOC: update the Index.get_level_values docstring #20210

Conversation

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

TomAugspurger commented Mar 10, 2018

joaoavf 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

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

jorisvandenbossche commented Mar 17, 2018

codecov bot commented Jul 8, 2018

Codecov Report

jorisvandenbossche commented Jul 8, 2018