From 630b6646047477c1aec87ef21852234231722d56 Mon Sep 17 00:00:00 2001 From: tp Date: Fri, 1 Sep 2017 18:51:46 +0100 Subject: [PATCH 1/3] Add examples to MultiIndex.get_level_values + related changes --- pandas/core/indexes/base.py | 11 ++++++++--- pandas/core/indexes/multi.py | 20 +++++++++++++++++++- pandas/tests/indexes/test_base.py | 6 ++++++ 3 files changed, 33 insertions(+), 4 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 6a30eaefaaae7..75ac9e7801880 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -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. Parameters ---------- - level : int + level : int or level name Returns ------- - values : Index + self : Index + + See also + --------- + pandas.MultiIndex.get_level_values : get values for a level of a + MultiIndex """ self._validate_index_level(level) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index d7d5b6d128a2c..c8eeb72ead12f 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -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 ---------- @@ -891,6 +891,24 @@ def get_level_values(self, level): Returns ------- values : Index + + Examples + --------- + + 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) diff --git a/pandas/tests/indexes/test_base.py b/pandas/tests/indexes/test_base.py index aa32e75ba0d58..210c662c109f5 100644 --- a/pandas/tests/indexes/test_base.py +++ b/pandas/tests/indexes/test_base.py @@ -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 + 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 From 8bfeec3fc3ef1bdbc1b36a15e0b4a0e5a4472423 Mon Sep 17 00:00:00 2001 From: tp Date: Sat, 2 Sep 2017 09:40:55 +0100 Subject: [PATCH 2/3] Updated according to comments (GH 17414) --- pandas/core/indexes/base.py | 8 ++++++-- pandas/core/indexes/multi.py | 17 ++++++++--------- pandas/tests/indexes/test_base.py | 2 +- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 75ac9e7801880..25594ecd1c3c9 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2533,11 +2533,15 @@ def _get_level_values(self, level): Parameters ---------- - level : int or level name + level : int or str + ``level`` is either the integer position of the level in the + MultiIndex, or the name of the level. Returns ------- - self : Index + values : Index + Because there is only one level when the index has one level, + the return value is always self in this case. See also --------- diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index c8eeb72ead12f..99250a02fcd66 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -886,7 +886,9 @@ def get_level_values(self, level): Parameters ---------- - level : int or level name + level : int or str + ``level`` is either the integer position of the level in the + MultiIndex, or the name of the level. Returns ------- @@ -897,18 +899,15 @@ def get_level_values(self, level): 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)) + >>> mi = pd.MultiIndex.from_arrays((list('abc'), list('def'))) + >>> mi.names = ['level_1', 'level_2'] 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') + >>> mi.get_level_values(0) Index(['a', 'b', 'c'], dtype='object', name='level_1') + >>> mi.get_level_values('level_2') + Index(['d', 'e', 'f'], dtype='object', name='level_2') """ level = self._get_level_number(level) values = self._get_level_values(level) diff --git a/pandas/tests/indexes/test_base.py b/pandas/tests/indexes/test_base.py index 210c662c109f5..ac3cb114de1f0 100644 --- a/pandas/tests/indexes/test_base.py +++ b/pandas/tests/indexes/test_base.py @@ -1438,7 +1438,7 @@ def test_get_level_values(self): result = self.strIndex.get_level_values(0) tm.assert_index_equal(result, self.strIndex) - # test with name + # GH 17414 index_with_name = self.strIndex.copy() index_with_name.name = 'a' result = index_with_name.get_level_values('a') From cc67b9af36090ed45cde7a0b2321db0e9a1d08fe Mon Sep 17 00:00:00 2001 From: tp Date: Sat, 2 Sep 2017 10:03:20 +0100 Subject: [PATCH 3/3] added explanation for return value of MultiIndex.get_level_values --- pandas/core/indexes/base.py | 5 ++--- pandas/core/indexes/multi.py | 2 ++ pandas/tests/indexes/test_base.py | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 25594ecd1c3c9..a9098126a38e3 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2534,14 +2534,13 @@ def _get_level_values(self, level): Parameters ---------- level : int or str - ``level`` is either the integer position of the level in the + ``level`` is either the integer position of the level in the MultiIndex, or the name of the level. Returns ------- values : Index - Because there is only one level when the index has one level, - the return value is always self in this case. + ``self``, as there is only one level in the Index. See also --------- diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 99250a02fcd66..8b2cf0e7c0b40 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -893,6 +893,8 @@ def get_level_values(self, level): Returns ------- values : Index + ``values`` is a level of this MultiIndex converted to + a single :class:`Index` (or subclass thereof). Examples --------- diff --git a/pandas/tests/indexes/test_base.py b/pandas/tests/indexes/test_base.py index ac3cb114de1f0..f96dbdcfb8acf 100644 --- a/pandas/tests/indexes/test_base.py +++ b/pandas/tests/indexes/test_base.py @@ -1438,7 +1438,7 @@ def test_get_level_values(self): result = self.strIndex.get_level_values(0) tm.assert_index_equal(result, self.strIndex) - # GH 17414 + # test for name (GH 17414) index_with_name = self.strIndex.copy() index_with_name.name = 'a' result = index_with_name.get_level_values('a')