From 7ef617e88e1e51bbfd5d0cf71f57ef4502b91b38 Mon Sep 17 00:00:00 2001 From: shiersansi <143710553+shiersansi@users.noreply.github.com> Date: Thu, 12 Oct 2023 23:10:59 +0800 Subject: [PATCH] DOC: Add DataFrame.index.levels (#55437) * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: ../pandas/core/indexes/multi.py * modified: ../pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * modified: pandas/core/indexes/multi.py * Update pandas/core/indexes/multi.py --------- Co-authored-by: Marc Garcia --- pandas/core/indexes/multi.py | 47 ++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index c5cab225fa7b1..0c3593eca178d 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -843,6 +843,53 @@ def size(self) -> int: @cache_readonly def levels(self) -> FrozenList: + """ + Levels of the MultiIndex. + + Levels refer to the different hierarchical levels or layers in a MultiIndex. + In a MultiIndex, each level represents a distinct dimension or category of + the index. + + To access the levels, you can use the levels attribute of the MultiIndex, + which returns a tuple of Index objects. Each Index object represents a + level in the MultiIndex and contains the unique values found in that + specific level. + + If a MultiIndex is created with levels A, B, C, and the DataFrame using + it filters out all rows of the level C, MultiIndex.levels will still + return A, B, C. + + Examples + -------- + >>> index = pd.MultiIndex.from_product([['mammal'], + ... ('goat', 'human', 'cat', 'dog')], names=['Category', 'Animals']) + >>> leg_num = pd.DataFrame(data=(4, 2, 4, 4), index=index, columns=['Legs']) + >>> leg_num + Legs + Category Animals + mammal goat 4 + human 2 + cat 4 + dog 4 + + >>> leg_num.index.levels + FrozenList([['mammal'], ['cat', 'dog', 'goat', 'human']]) + + MultiIndex levels will not change even if the DataFrame using the MultiIndex + does not contain all them anymore. + See how "human" is not in the DataFrame, but it is still in levels: + + >>> large_leg_num = leg_num[leg_num.Legs > 2] + >>> large_leg_num + Legs + Category Animals + mammal goat 4 + cat 4 + dog 4 + + >>> large_leg_num.index.levels + FrozenList([['mammal'], ['cat', 'dog', 'goat', 'human']]) + """ # Use cache_readonly to ensure that self.get_locs doesn't repeatedly # create new IndexEngine # https://github.com/pandas-dev/pandas/issues/31648