Skip to content

DOC/TST: Add examples to MultiIndex.get_level_values + related changes #17414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 6, 2017
Merged

DOC/TST: Add examples to MultiIndex.get_level_values + related changes #17414

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
630b664
Add examples to MultiIndex.get_level_values + related changes
Sep 1, 2017
8bfeec3
Updated according to comments (GH 17414)
Sep 2, 2017
cc67b9a
added explanation for return value of MultiIndex.get_level_values
Sep 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions pandas/core/indexes/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2529,15 +2529,20 @@ def set_value(self, arr, key, value):
def _get_level_values(self, level):
"""
Return an Index of values for requested level, equal to the length
of the index
of the index.
Copy link
Member

Choose a reason for hiding this comment

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

Not Blocking : I would really like if we could condense this into one line (doc-string convention), but it's hard to see ATM what to remove from this...

Copy link
Contributor Author

@topper-123 topper-123 Sep 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

I haven't got a better proposal either.


Parameters
----------
level : int
level : int or level name
Copy link
Member

@gfyoung gfyoung Sep 2, 2017 •
edited
Loading

Choose a reason for hiding this comment

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

The general format is to specify the data type on the first line followed by an explanation of their semantics in a subsequent block.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok, I've changed this, also for MultiIndex.


Returns
-------
values : Index
self : Index
Copy link
Member

Choose a reason for hiding this comment

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

You aren't returning self are you? I would leave this line alone and instead add a line below explaining what the output is.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Actually it is returning self. this method probably meant to make the API the same for MultiIndex and other Index types, so for Index types this really doesn't do much. The name values is used for MultiIndex, but isn't used here...

should I still change it?

Copy link
Member

Choose a reason for hiding this comment

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

@topper-123 : Sorry, I wasn't able to check the actual file on my phone. Yes, you are correct that self is returned. While I do stand corrected, I do think leaving it unchanged is preferable for consistency. You can however, in a line beneath that explain that values in this implementation is just self because there is only one level.


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

self._validate_index_level(level)
Expand Down
20 changes: 19 additions & 1 deletion pandas/core/indexes/multi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -882,7 +882,7 @@ def _get_level_values(self, level):
def get_level_values(self, level):
"""
Return vector of label values for requested level,
equal to the length of the index
equal to the length of the index.

Parameters
----------
Expand All @@ -891,6 +891,24 @@ def get_level_values(self, level):
Returns
-------
values : Index
Copy link
Member

Choose a reason for hiding this comment

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

Let's explain what values is here since you are updating the docs.


Examples
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Note that I've made the examples a bit simpler. No need to demonstrate CategoricalIndex etc. here...

---------

Create a MultiIndex:

>>> i1 = pd.Index(list('abc'), name='level_1')
>>> i2 = pd.CategoricalIndex(list('def'), name='level_2')
>>> mi = pd.MultiIndex.from_arrays((i1, i2))

Get level values by supplying level as either integer or name:

>>> mi.get_level_values(1)
CategoricalIndex(['d', 'e', 'f'], categories=['d', 'e', 'f'],
ordered=False, name='level_2',
dtype='category')
>>> mi.get_level_values('level_1')
Index(['a', 'b', 'c'], dtype='object', name='level_1')
"""
level = self._get_level_number(level)
values = self._get_level_values(level)
Expand Down
6 changes: 6 additions & 0 deletions pandas/tests/indexes/test_base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1438,6 +1438,12 @@ def test_get_level_values(self):
result = self.strIndex.get_level_values(0)
tm.assert_index_equal(result, self.strIndex)

# test with name
Copy link
Member

Choose a reason for hiding this comment

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

Reference your PR here.

index_with_name = self.strIndex.copy()
index_with_name.name = 'a'
result = index_with_name.get_level_values('a')
tm.assert_index_equal(result, index_with_name)

def test_slice_keep_name(self):
idx = Index(['a', 'b'], name='asdf')
assert idx.name == idx[1:].name
Expand Down