From b851cfdebf866efa9de469a0fe65575c2a641f8d Mon Sep 17 00:00:00 2001 From: Chin Hwee Date: Tue, 22 Oct 2019 12:38:15 +0800 Subject: [PATCH 1/3] edit set_levels docstring --- pandas/core/indexes/multi.py | 63 ++++++++++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 9 deletions(-) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index fda5c78a61e53..33e4312f71af6 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -736,8 +736,19 @@ def _set_levels( def set_levels(self, levels, level=None, inplace=False, verify_integrity=True): """ - Set new levels on MultiIndex. Defaults to returning - new index. + Set new levels on MultiIndex. Defaults to returning new index. + + ``set_levels`` passes a new value for each index in the level, + where the new values to be passed in each level are defined in + a list. It is assumed that a new value is provided for each + code describing values in the level. + + If the number of values passed is more than the number of index + values in the level, ``set_levels`` will still pass the values + to the level. The passed values are stored in the FrozenList + representing the levels attribute of the MultiIndex, even + though the index values may be truncated in the MultiIndex + output from set_levels. Parameters ---------- @@ -757,32 +768,66 @@ def set_levels(self, levels, level=None, inplace=False, verify_integrity=True): Examples -------- >>> idx = pd.MultiIndex.from_tuples([(1, 'one'), (1, 'two'), - (2, 'one'), (2, 'two')], + (2, 'one'), (2, 'two'), + (3, 'one'), (3, 'two')], names=['foo', 'bar']) - >>> idx.set_levels([['a', 'b'], [1, 2]]) + >>> idx + MultiIndex([('1', one), + ('1', two), + ('2', one), + ('2', two), + ('3', one), + ('3', two)], + names=['foo', 'bar']) + >>> idx.set_levels([['a', 'b', 'c'], [1, 2]]) MultiIndex([('a', 1), ('a', 2), ('b', 1), - ('b', 2)], + ('b', 2), + ('c', 1), + ('c', 2)], names=['foo', 'bar']) - >>> idx.set_levels(['a', 'b'], level=0) + >>> idx.set_levels(['a', 'b', 'c'], level=0) MultiIndex([('a', 'one'), ('a', 'two'), ('b', 'one'), - ('b', 'two')], + ('b', 'two'), + ('c', 'one'), + ('c', 'two')], names=['foo', 'bar']) >>> idx.set_levels(['a', 'b'], level='bar') MultiIndex([(1, 'a'), (1, 'b'), (2, 'a'), - (2, 'b')], + (2, 'b'), + (3, 'a'), + (3, 'b')], + names=['foo', 'bar']) + + ``set_levels()`` passes values into the levels attribute that + is represented by a FrozenList containing list of values for + each level in the MultiIndex, even when the number of values + passed for a level is more than the number of indexes + available in the MultiIndex itself. + + >>> idx.set_levels([['a', 'b', 'c'], [1, 2]], level=[0, 1]) + MultiIndex([('a', 1), + ('a', 2), + ('b', 1), + ('b', 2), + ('c', 1), + ('c', 2)], names=['foo', 'bar']) - >>> idx.set_levels([['a', 'b'], [1, 2]], level=[0, 1]) + >>> idx.set_levels([['a', 'b', 'c'], [1, 2]], level=[0, 1]).levels + FrozenList([['a', 'b', 'c'], [1, 2]]) + >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1]) MultiIndex([('a', 1), ('a', 2), ('b', 1), ('b', 2)], names=['foo', 'bar']) + >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1]).levels + FrozenList([['a', 'b', 'c'], [1, 2, 3, 4]]) """ if is_list_like(levels) and not isinstance(levels, Index): levels = list(levels) From bd07d3acd073c237f1e8813ba7ed7f561b147522 Mon Sep 17 00:00:00 2001 From: Chin Hwee Date: Sat, 9 Nov 2019 10:33:41 +0800 Subject: [PATCH 2/3] update set_levels docstrings --- pandas/core/indexes/multi.py | 38 +++--------------------------------- 1 file changed, 3 insertions(+), 35 deletions(-) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 0e55ecd6f351b..c23fea9ac09a9 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -739,18 +739,6 @@ def set_levels(self, levels, level=None, inplace=False, verify_integrity=True): """ Set new levels on MultiIndex. Defaults to returning new index. - ``set_levels`` passes a new value for each index in the level, - where the new values to be passed in each level are defined in - a list. It is assumed that a new value is provided for each - code describing values in the level. - - If the number of values passed is more than the number of index - values in the level, ``set_levels`` will still pass the values - to the level. The passed values are stored in the FrozenList - representing the levels attribute of the MultiIndex, even - though the index values may be truncated in the MultiIndex - output from set_levels. - Parameters ---------- levels : sequence or list of sequence @@ -772,14 +760,6 @@ def set_levels(self, levels, level=None, inplace=False, verify_integrity=True): (2, 'one'), (2, 'two'), (3, 'one'), (3, 'two')], names=['foo', 'bar']) - >>> idx - MultiIndex([('1', one), - ('1', two), - ('2', one), - ('2', two), - ('3', one), - ('3', two)], - names=['foo', 'bar']) >>> idx.set_levels([['a', 'b', 'c'], [1, 2]]) MultiIndex([('a', 1), ('a', 2), @@ -805,22 +785,10 @@ def set_levels(self, levels, level=None, inplace=False, verify_integrity=True): (3, 'b')], names=['foo', 'bar']) - ``set_levels()`` passes values into the levels attribute that - is represented by a FrozenList containing list of values for - each level in the MultiIndex, even when the number of values - passed for a level is more than the number of indexes - available in the MultiIndex itself. + If any of the levels passed to ``set_levels()`` exceeds the + existing length, all of the values from that argument will + be stored though truncated in the MultiIndex output. - >>> idx.set_levels([['a', 'b', 'c'], [1, 2]], level=[0, 1]) - MultiIndex([('a', 1), - ('a', 2), - ('b', 1), - ('b', 2), - ('c', 1), - ('c', 2)], - names=['foo', 'bar']) - >>> idx.set_levels([['a', 'b', 'c'], [1, 2]], level=[0, 1]).levels - FrozenList([['a', 'b', 'c'], [1, 2]]) >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1]) MultiIndex([('a', 1), ('a', 2), From f29a9b837ef56d9f317f373bc94dcc9f746fc4da Mon Sep 17 00:00:00 2001 From: Chin Hwee Date: Tue, 19 Nov 2019 21:35:55 +0800 Subject: [PATCH 3/3] update set_levels docstrings for clarity --- pandas/core/indexes/multi.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index 6c76453f8e224..9a2357bc71367 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -787,7 +787,8 @@ def set_levels(self, levels, level=None, inplace=False, verify_integrity=True): If any of the levels passed to ``set_levels()`` exceeds the existing length, all of the values from that argument will - be stored though truncated in the MultiIndex output. + be stored in the MultiIndex levels, though the values will + be truncated in the MultiIndex output. >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1]) MultiIndex([('a', 1),