Criando um MultiIndex

Um MultiIndex (também chamado de índice hierárquico) permite que um DataFrame ou Series do Pandas tenha múltiplos níveis de rótulos de linhas. Pense nele como uma chave composta em um banco de dados: em vez de identificar uma linha por um único rótulo, você a identifica por uma tupla, como (país, cidade) ou (ano, trimestre). MultiIndexes são essenciais para representar dados em painel, séries temporais transversais e qualquer conjunto de dados com uma estrutura natural de agrupamento em dois níveis.

pd.MultiIndex.from_tuples(list_of_tuples, names=) é a maneira mais explícita de criar um MultiIndex. Cada tupla se torna um rótulo de linha, e seus elementos se tornam os níveis. O parâmetro names atribui um rótulo a cada nível (por exemplo, ['year', 'quarter']). Esse método é útil quando você tem uma lista pré-construída de chaves compostas que deseja usar como índice de linhas.

pd.MultiIndex.from_product(iterables, names=) cria um MultiIndex a partir do produto cartesiano de várias listas — todas as combinações de elementos das listas de entrada. Esse é o método mais conveniente quando todas as combinações de níveis devem existir nos seus dados. Por exemplo, todas as combinações de 3 anos × 4 trimestres × 5 regiões criam automaticamente um painel equilibrado com 60 linhas.

A maneira mais comum de criar um MultiIndex na prática é começar com um DataFrame regular que tenha colunas de agrupamento e, em seguida, chamar df.set_index([col1, col2]). Isso promove essas colunas, transformando-as de colunas de dados em níveis de índice. O resultado é o mesmo que se você tivesse criado o índice do zero com from_tuples, mas requer apenas uma linha a partir de dados tabulares.

Um MultiIndex armazena seus dados em níveis (os valores exclusivos de cada nível) e códigos (ponteiros inteiros para os vetores de níveis). Inspecione os níveis com df.index.levels ou df.index.get_level_values(level). Use df.index.nlevels para verificar quantos níveis existem. O atributo names lista o nome atribuído a cada nível — defina esses nomes com df.index.set_names(['level0', 'level1']).

Um MultiIndex também pode ser aplicado às colunas, criando uma hierarquia de rótulos de coluna. Isso é comum quando você armazena várias métricas para cada categoria em um layout no estilo tabela dinâmica — por exemplo, (receita, T1), (receita, T2), (custo, T1), (custo, T2). Acesse as colunas com um MultiIndex da mesma forma que acessa as linhas — usando tuplas. Crie um MultiIndex de colunas com pd.MultiIndex.from_product e atribua-o a df.columns.

Quando você chama groupby([col1, col2]).agg(...), o DataFrame resultante tem um MultiIndex nas linhas (as duas chaves de groupby tornam-se os dois níveis do índice) e potencialmente um MultiIndex nas colunas (se você agregar várias métricas). Essa é a maneira mais comum de encontrar um MultiIndex na análise cotidiana de dados — entender como navegá-lo é essencial para trabalhar com resultados de groupby.

Use df.swaplevel() para trocar dois níveis do índice e df.reorder_levels([...]) para alterar a ordem de todos os níveis. A reordenação é útil quando você quer fazer uma seleção começando por um nível interno ou quando dois DataFrames têm seus níveis de índice em ordens diferentes e precisam ser alinhados antes da mesclagem. Depois de reordenar, sempre chame sort_index() para restaurar a ordem lexicográfica e permitir uma seleção eficiente.

A seleção em um MultiIndex só é eficiente quando o índice está ordenado lexicograficamente. Verifique se o índice está ordenado com df.index.is_monotonic_increasing. Se o resultado for False, ordene-o com df.sort_index(). Um MultiIndex não ordenado aciona um PerformanceWarning durante operações de seleção e pode retornar resultados incorretos em alguns casos extremos — sempre ordene o índice depois de criar ou modificar um MultiIndex.

Chame df.reset_index() para converter todos os níveis do índice novamente em colunas regulares, deixando o DataFrame com um RangeIndex inteiro simples. Esse é um padrão comum após agregações com groupby: calcule o resumo agrupado com um MultiIndex e, em seguida, redefina o índice para obter um DataFrame plano, adequado para outras operações do Pandas, combinações ou exportação para CSV. Use reset_index(level='name') para redefinir apenas um nível de um índice de dois níveis.

Use um MultiIndex quando seus dados tiverem uma estrutura hierárquica natural: séries temporais com granularidade inferior a um dia (data + hora), dados em painel (entidade + período) ou agrupamentos aninhados (país + região + cidade). Evite MultiIndexes para chaves de agrupamento simples em duas colunas, quando um DataFrame plano com colunas separadas for igualmente legível. Se você perceber que está chamando reset_index() constantemente apenas para acessar os dados, isso é um sinal de que o MultiIndex não está agregando valor ao seu fluxo de trabalho.

Teste sua compreensão sobre a criação de MultiIndex nesta lição.

Nesta lição, você aprendeu que: MultiIndexes fornecem rótulos hierárquicos de linhas (ou colunas) usando tuplas, criados com from_tuples, from_product ou set_index em várias colunas, e devem estar sempre ordenados para permitir o fatiamento eficiente. Em seguida, veremos como selecionar dados de um MultiIndex usando .loc, tuplas, fatias e o auxiliar IndexSlice.