Agrupamento e agregação com pandas

Um grupo contém linhas com o mesmo valor de chave. Se a chave for region, todos os pedidos de North pertencerão a um grupo, mesmo que estejam espalhados pela tabela. Dividir, aplicar e combinar significa identificar esses grupos, realizar a mesma operação dentro de cada um e reunir os resultados.

Comece pelos dados dos pedidos

Os exemplos usam pandas 3 com import pandas as pd e NumPy como np. Crie a tabela de pedidos de bebidas:

sales = pd.DataFrame({
    "region": ["North", "South", "North", "East", "South", "East", "North", "South"],
    "product": ["tea", "tea", "coffee", "coffee", "coffee", "tea", "tea", "coffee"],
    "units": [10, 4, 7, 5, 9, 3, 6, 8],
    "revenue": [30, 12, 28, 20, 36, 9, 18, 32]
})

A receita não tem unidade monetária aqui. O chá tem receita de 3 por unidade e o café, de 4 por unidade. Os rótulos de linha padrão vão de 0 a 7.

De um objeto GroupBy a uma resposta

sales.groupby("region") retorna um objeto GroupBy, que contém as informações de agrupamento. Ele não é uma tabela de resumo. Escolha uma coluna e chame um método para calcular um resultado:

g = sales.groupby("region")
totals = g["units"].sum()

East contém as linhas 3 e 5, então seu total é 5 + 3 = 8. North contém as linhas 0, 2 e 6, resultando em 10 + 7 + 6 = 23. South contém as linhas 1, 4 e 7, resultando em 4 + 9 + 8 = 21. O pandas combina esses valores em uma Series chamada units, com os nomes das regiões como índice. Os totais somam 52, o total da coluna original.

A ordem padrão da saída é East, North, South porque as chaves dos grupos são ordenadas. sales.groupby("region", sort=False) usa a ordem da primeira ocorrência: North, South, East. Nenhuma das opções ordena as observações dentro de um grupo ou altera sales.

Inspecione e selecione

g.ngroups é 3. g.size() informa 2, 3 e 3 linhas para East, North e South. g.groups associa chaves a rótulos de linha, e g.get_group("North") retorna as três linhas de North. Você pode inspecionar um grupo por vez:

for name, group in g:
    print(name, group["units"].tolist())

A iteração ajuda a inspecionar ou exportar grupos. Para uma estatística, um método de grupo disponível evita que você escreva um laço Python e colete os resultados.

Selecionar g["units"] produz um SeriesGroupBy; sua soma é uma Series. Selecionar g[["units"]] produz um DataFrameGroupBy; sua soma é um DataFrame de uma coluna. Selecione g[["units", "revenue"]] quando precisar das duas colunas numéricas.

Escolha a forma da saída

Uma agregação como sum fornece um valor de resumo por grupo e coluna. Uma transformação fornece um valor para cada linha de entrada, como a participação de cada pedido no total de sua região. Uma filtragem mantém linhas ou grupos selecionados. O método geral apply trata resultados de grupos menos regulares.

A filtragem sales[sales["region"] == "North"] recupera as linhas de uma região. O agrupamento permite processar todas as regiões com a mesma operação.

As chaves podem vir de colunas, cálculos ou do índice das linhas. A pergunta importante é qual valor cada linha recebe como chave. Linhas com a mesma combinação de chaves são processadas juntas.

Use várias colunas

Passe uma lista de nomes de colunas para agrupar por combinações:

pair_totals = sales.groupby(["region", "product"])["units"].sum()

O resultado tem um MultiIndex de dois níveis. Suas entradas são East e coffee 5, East e tea 3, North e coffee 7, North e tea 16, South e coffee 17 e South e tea 4. North e tea combinam os dois pedidos de chá, com 10 e 6 unidades. Agrupar apenas por região também incluiria o pedido de café de North.

pair_totals.unstack() move o nível interno product para as colunas. As linhas são regiões, e as colunas são coffee e tea. Uma combinação ausente torna-se NaN; unstack(fill_value=0) pode representá-la como zero quando essa ausência significa nenhuma unidade.

Use uma lista para vários nomes de colunas. groupby(("region", "product")) trata a tupla como um único rótulo de coluna e procura uma coluna com essa tupla como nome.

Derive uma chave dos valores

Uma Series booleana pode dividir pedidos por tamanho sem adicionar uma coluna:

sales.groupby(sales["units"] >= 7)["revenue"].sum()

O grupo True contém as unidades 10, 7, 9 e 8; sua receita é 126. O grupo False contém os outros quatro pedidos e tem receita 59. O teste cria rótulos de grupo; ele não remove os pedidos menores.

Um mapeamento pode combinar regiões em zonas:

zones = {"North": "Zone 1", "East": "Zone 1", "South": "Zone 2"}
zone_key = sales["region"].map(zones)
sales.groupby(zone_key)["units"].sum()

Zone 1 recebe as 23 unidades de North e as 8 de East, totalizando 31. Zone 2 recebe as 21 de South. Mapeie a coluna primeiro: um dicionário passado diretamente a groupby mapeia rótulos do índice, não valores de região.

Agrupe usando o índice

Uma função passada como chave também recebe rótulos do índice. Para um estoque indexado por códigos de produto, a primeira letra pode identificar a família do produto:

stock = pd.Series([12, 8, 5, 9, 4],
                  index=["T01", "T02", "C01", "C02", "C03"])
stock.groupby(lambda code: code[0]).sum()

O total de C é 18 e o de T é 20. Para um MultiIndex existente, pair_totals.groupby(level="product").sum() reagrupa pelo nível nomeado do índice, produzindo coffee 29 e tea 23.

Verifique o alinhamento antes de agrupar

Uma chave em array do NumPy fornece rótulos por posição e deve ter um elemento por linha. Uma chave em Series é alinhada pelo rótulo do índice. Se seus rótulos cobrirem apenas as linhas 0 e 1, as outras linhas receberão chaves ausentes e serão excluídas pelo comportamento padrão de agrupamento. Uma Series reordenada ainda pode agrupar corretamente quando seus rótulos correspondem aos das linhas; substituí-la por seus valores muda a operação para correspondência por posição.

Um cálculo por grupos tem duas partes a inspecionar: os valores e os rótulos ao redor deles. O pandas permite escolher onde as chaves aparecem, como os grupos são ordenados e se chaves ausentes ou não utilizadas aparecem no relatório.

Mantenha as chaves no índice ou em colunas

Por padrão, as chaves tornam-se o índice do resultado:

sales.groupby("region")["revenue"].sum()

Essa Series tem East 29, North 76 e South 80. Para um relatório sem índice hierárquico, use:

report = sales.groupby("region", as_index=False)["revenue"].sum()

report tem colunas comuns region e revenue e um novo índice inteiro. Chamar .reset_index() na Series original produz a mesma disposição. Com várias chaves, ele converte cada nível do MultiIndex em uma coluna. unstack() tem outra finalidade: move um nível do índice para as colunas de uma grade.

Um resultado em Series mantém o nome da coluna selecionada. Use .rename("total_revenue") para dar um nome mais claro à Series ou .to_frame("total_revenue") para obter um DataFrame de uma coluna. A agregação nomeada pode fornecer nomes descritivos às colunas durante o cálculo.

Ordene chaves ou classifique valores

sort=True ordena as chaves, então a ordem alfabética das regiões continua sendo East, North, South, embora South tenha a maior receita. Para classificar os totais, ordene o resultado:

sales.groupby("region")["revenue"].sum().sort_values(ascending=False)

A saída é South 80, North 76, East 29. Use sort=False para manter as chaves na ordem da primeira ocorrência e evitar uma ordenação desnecessária em um conjunto de dados grande. Isso não ordena as linhas dentro dos grupos.

Considere chaves ausentes

O padrão dropna=True exclui linhas com chave de grupo ausente. Adicione um pedido com 5 unidades, mas sem região: a coluna inteira de unidades passa a totalizar 57, enquanto os totais dos grupos ainda somam 52. A linha omitida não tem uma região nomeada.

sales.groupby("region", dropna=False)["units"].sum()

Na tabela ampliada, isso adiciona um grupo de chave ausente que totaliza 5. Chaves ausentes determinam se uma linha entra em um grupo; valores ausentes determinam o que uma agregação conta ou calcula dentro de um grupo. São decisões distintas.

Mostre categorias não utilizadas quando necessário

Uma coluna categórica region pode listar East, North, South e West mesmo quando não há pedidos em West. Desde o pandas 3.0, observed=True é o padrão e mostra apenas categorias presentes nos dados. Com observed=False, West também aparece: sua soma e contagem são 0, enquanto sua média é NaN.

Escolha essa configuração explicitamente quando um relatório precisar mostrar as mesmas categorias todas as vezes. Uma categoria não utilizada e uma chave ausente são diferentes: observed trata valores categóricos declarados; dropna trata valores de chave ausentes.

as_index e sort definem a forma dos resultados de agregação. Transformações e filtragens como head, nth e filter mantêm os índices das linhas de entrada. Em um relatório de somas, comparar a soma dos totais dos grupos com o total da coluna original pode revelar chaves excluídas ou um filtro anterior.

Uma agregação reduz cada grupo a um valor de resumo para cada coluna selecionada. Escolha a medida de acordo com a pergunta: uma contagem de linhas, um total, uma média ou uma medida de variação descreve uma característica diferente dos dados.

Selecione a estatística

Os métodos comuns incluem sum, prod, mean, median, min, max, count, size, nunique, std, var, first, last e quantile. Uma chamada direta como .mean() e .agg("mean") solicitam a média de grupo do pandas. nunique() conta valores distintos não ausentes por padrão.

sales.groupby("product")["revenue"].agg(["mean", "median"])

As receitas de café são 28, 20, 36 e 32. Sua média é 29; ordená-las fornece os valores centrais 28 e 32, então sua mediana é 30. As receitas de chá são 30, 12, 9 e 18. Sua média é 17,25 e sua mediana é 15. O pedido grande de chá de 30 eleva a média acima da mediana.

Conte linhas ou valores registrados

size() conta linhas. count() conta valores não ausentes em cada coluna selecionada. Se as unidades estiverem ausentes na linha 2 de North e na linha 5 de East, os tamanhos continuam East 2, North 3, South 3, mas as contagens de unidades são 1, 2 e 3. Assim, colunas diferentes podem ter contagens diferentes dentro do mesmo grupo.

A maioria das reduções numéricas ignora valores ausentes. As unidades restantes de North, 10 e 6, têm média 8, usando dois valores registrados. Dividir sua soma pelas três linhas produziria a média errada. Um grupo com todos os valores ausentes tem soma 0 por padrão, mas média NaN. Desde o pandas 3.0, reduções como sum e mean aceitam skipna=False para retornar um resultado ausente quando um grupo contém um valor ausente.

Interprete a dispersão e os resumos combinados

std() e var() usam estatísticas amostrais, com ddof=1: o divisor é um a menos que o número de observações registradas. Os valores 1 e 3 têm desvio padrão amostral de aproximadamente 1,414. Um grupo com apenas o valor 5 tem desvio padrão amostral NaN.

describe() reúne contagem, média, desvio padrão, mínimo, quartis e máximo. Para as receitas de South 12, 36 e 32, a média é aproximadamente 26,67 e a mediana é 32. A coluna 50% é a mediana.

Controle as colunas e a ordem das linhas

Selecionar colunas numéricas evita tentar calcular a média de texto:

sales.groupby("region")[["units", "revenue"]].mean()

Um .mean() na tabela inteira falha na coluna de texto product; numeric_only=True é outra solução. Um .sum() na tabela inteira pode concatenar texto, produzindo "coffeetea" para East, o que não é um resumo útil de produtos.

first() e last() escolhem o primeiro e o último valor não ausente por coluna na ordem atual das linhas. Eles podem obter valores de linhas diferentes. Use nth(0) para recuperar a primeira linha real, incluindo seus valores ausentes; ordene primeiro quando “primeiro” significar o mais antigo.

Tamanhos desiguais dos grupos também afetam a interpretação. A média das receitas médias regionais é aproximadamente 22,17, mas a média geral é 185 dividido por 8, ou 23,125. Atribuir o mesmo peso a cada média regional dá ao grupo East, de duas linhas, a mesma influência que a cada grupo de três linhas.

Um relatório útil muitas vezes precisa de várias medidas dos mesmos grupos. agg, abreviação de aggregate, permite solicitar essas medidas juntas e controlar como suas colunas de saída são nomeadas.

Aplique várias funções a uma coluna

sales.groupby("region")["revenue"].agg(["sum", "mean", "max"])

East fornece 29, 14,5 e 20; North fornece 76, aproximadamente 25,33 e 30; South fornece 80, aproximadamente 26,67 e 36. Cada linha representa uma região, enquanto os nomes das funções tornam-se nomes de colunas.

Uma lista aplicada a várias colunas de valores produz colunas hierárquicas:

result = sales.groupby("region")[["units", "revenue"]].agg(["sum", "mean"])

Os quatro rótulos de coluna são os pares ("units", "sum"), ("units", "mean"), ("revenue", "sum") e ("revenue", "mean"). O primeiro nível identifica a coluna de entrada; o segundo identifica o cálculo. Esses são níveis das colunas, separados de quaisquer níveis de agrupamento no índice das linhas.

Atribua funções a colunas específicas

Um dicionário seleciona as colunas de entrada e suas funções:

sales.groupby("region").agg({
    "units": "sum",
    "revenue": ["mean", "max"]
})

Isso solicita o total de unidades, mas a média e o máximo da receita. Colunas ausentes do dicionário não aparecem. Funções diferentes podem fazer sentido para medidas diferentes; somar uma quantidade e calcular a média de uma taxa não são escolhas intercambiáveis.

Nomeie as saídas diretamente

A agregação nomeada dá a cada resultado um nome explícito:

report = sales.groupby("region").agg(
    total_units=("units", "sum"),
    avg_revenue=("revenue", "mean")
)

Cada palavra-chave nomeia uma coluna de saída. Sua tupla contém a coluna de origem e a função. total_units é 8, 23 e 21; avg_revenue é 14,5, aproximadamente 25,33 e aproximadamente 26,67. pd.NamedAgg(column="units", aggfunc="sum") é uma alternativa auxiliar para especificar a origem e a função.

Após selecionar uma única Series, use palavras-chave de função sem tuplas de coluna de origem:

sales.groupby("region")["units"].agg(total="sum", most="max")

Os totais são 8, 23 e 21, e os máximos são 5, 10 e 9. Um dicionário como {"total": "sum"} nessa Series selecionada gera um SpecificationError; ele não é a forma de dicionário usada em um DataFrame.

Uma lista de pares nomeados também funciona em uma coluna selecionada: .agg([("average", "mean"), ("spread", "std")]). Se você já tiver colunas MultiIndex feitas de rótulos em strings, result.columns = ["_".join(col) for col in result.columns] as achata, produzindo nomes como units_sum.

Escolha a função deliberadamente

Nomes em strings usam os cálculos de grupo disponíveis no pandas. Desde o pandas 3.0, uma função do NumPy ou Python passada a agg é chamada conforme fornecida. Para as receitas de East 20 e 9, "std" usa o divisor amostral e fornece aproximadamente 7,78, enquanto np.std usa o divisor populacional e fornece 5,5.

Uma agregação personalizada expressa um resumo que um método disponível por nome não fornece. Sua função recebe os valores de um grupo como uma Series e deve reduzi-los a um resultado útil.

Escreva e passe a função

def value_range(s):
    return s.max() - s.min()

sales.groupby("region")["revenue"].agg(value_range)

A amplitude de East é 20 menos 9, ou 11. A de North é 30 menos 18, ou 12. A de South é 36 menos 12, ou 24. Passe a própria função value_range; value_range() a chamaria imediatamente, sem a Series do grupo de que ela precisa.

Uma lambda é adequada para um cálculo curto:

sales.groupby("region")["revenue"].agg(
    share_20=lambda s: (s >= 20).mean()
)

Valores booleanos funcionam como 1 para True e 0 para False, então sua média é a proporção que atende à condição. East tem um pedido qualificado entre dois, ou 0,5. North e South têm dois entre três cada um, ou aproximadamente 0,667. Nomear o resultado torna seu significado mais claro que um rótulo automático de lambda. Listas com várias funções rotulam lambdas como <lambda_0>, <lambda_1> e assim por diante; uma única lambda em uma lista é rotulada como <lambda>.

Prepare colunas para usar reduções rápidas

Uma função Python é executada uma vez para cada grupo. Quando há muitos grupos, as reduções disponíveis costumam ser mais rápidas. O cálculo da proporção pode ser reescrito criando primeiro sua coluna booleana:

sales.assign(big=sales["revenue"] >= 20).groupby("region")["big"].mean()

A comparação é executada na coluna inteira, deixando o cálculo das médias dos grupos para o pandas.

Combine duas colunas por meio de seus totais

Uma função agg trata uma coluna por vez. Para obter a receita média por unidade, primeiro resuma ambas as colunas:

totals = sales.groupby("region")[["units", "revenue"]].sum()
avg_price = totals["revenue"] / totals["units"]

Os resultados são East 29/8 = 3,625, North 76/23 ≈ 3,304 e South 80/21 ≈ 3,810. Cada unidade recebe o mesmo peso. Calcular a média dos preços dos pedidos fornece East 3,5, North aproximadamente 3,333 e South aproximadamente 3,667, porque cada pedido recebe o mesmo peso, independentemente de seu tamanho. Decida se a pergunta se refere a uma unidade típica ou a um pedido típico antes de escolher a fórmula.

Deixe claros o valor de retorno e os dados ausentes

Uma função que retorna os dois menores valores não cria duas linhas de resumo comuns com agg; no pandas 3.1, lambda s: s.nsmallest(2) armazena um objeto semelhante a uma lista em cada célula. Use apply quando um grupo precisar retornar vários valores ou linhas.

A Series de entrada ainda contém valores ausentes. s.mean() os ignora, enquanto len(s) conta suas linhas. Se as unidades estiverem ausentes nas linhas 2 e 5, .agg(len) fornecerá os tamanhos dos grupos 2, 3 e 3, não as contagens de valores não ausentes 1, 2 e 3.

Argumentos adicionais podem vir depois da função: .agg("quantile", 0.9) fornece o percentil 90 de cada grupo. As receitas de East 9 e 20 fornecem 18,9 por interpolação linear. A chamada direta .quantile(0.9) é mais fácil de ler para essa única operação.

Um resumo tem uma linha por grupo, mas às vezes cada linha original precisa da estatística de seu grupo. transform retorna um resultado com o comprimento e o índice originais, adequado para uma nova coluna.

Difunda um total para as linhas corretas

g = sales.groupby("region")["revenue"]
regional_total = g.transform("sum")
sales["share"] = sales["revenue"] / regional_total

A Series de totais contém 76, 80, 76, 29, 80, 29, 76 e 80 na ordem original das linhas. O total de North, 76, é repetido apenas nas linhas de North. A linha 0 recebe a proporção 30/76 ≈ 0,395; a linha 3 de East recebe 20/29 ≈ 0,690. Dentro de cada região, essas proporções de receita somam 1.

Atribuir g.sum() diretamente não associaria o resultado às linhas. Seu índice contém nomes de regiões, enquanto sales tem rótulos de linha de 0 a 7. O pandas alinha pelo rótulo do índice, então a coluna atribuída fica com valores ausentes. Use transform ou una explicitamente um resumo por region.

Compare uma linha com seu grupo

Subtrair a média do grupo fornece um desvio em relação à média do grupo:

x = sales["revenue"]
deviation = x - g.transform("mean")

A linha 0 de North está aproximadamente 4,67 acima da média de seu grupo, de aproximadamente 25,33. A linha 1 de South está aproximadamente 14,67 abaixo da média de seu grupo, de aproximadamente 26,67. Cada comparação usa a própria região da linha, não a média da tabela inteira.

Um escore z divide esse desvio pelo desvio padrão do grupo:

z = (x - g.transform("mean")) / g.transform("std")

Para a linha 0 de North, o desvio padrão amostral é aproximadamente 6,43 e o escore z, aproximadamente 0,73. A linha 3 de East tem escore z de aproximadamente 0,71, então está acima da média de sua região, embora sua receita de 20 esteja abaixo da média geral de 23,125. Um desvio padrão zero ou valores registrados insuficientes deixam o escore padronizado indefinido.

Preencha um valor ausente com dados de seu grupo

Suponha que as unidades nas linhas 2 e 5 estejam ausentes. As unidades registradas de North são 10 e 6, com média 8; o único valor de unidades registrado em East é 5.

with_missing = sales.copy()
with_missing.loc[[2, 5], "units"] = np.nan
means = with_missing.groupby("region")["units"].transform("mean")
filled_units = with_missing["units"].fillna(means)

Nessa tabela modificada, a linha 2 recebe 8 e a linha 5 recebe 5. Os valores existentes permanecem inalterados. Quando os grupos têm valores típicos diferentes, suas próprias médias podem fornecer substituições mais realistas que uma única média geral. Um grupo sem valores registrados continua sem uma média para fornecer.

Entenda uma transformação personalizada

Uma função fornecida a transform pode retornar um escalar, que o pandas repete dentro do grupo, ou uma Series indexada pelas linhas do grupo. Por exemplo, g.transform(lambda s: s - s.mean()) calcula os mesmos desvios que a média disponível seguida de subtração, mas invoca Python para cada grupo.

Uma Series mais curta retornada é associada por rótulo. g.transform(lambda s: s.head(1)) fornece apenas o valor da primeira linha de cada grupo; as outras linhas recebem NaN. Mantenha os cálculos por linha no índice original quando o resultado for atribuído de volta à tabela.

Cálculos acumulados e comparações com observações anteriores precisam tanto de um grupo quanto de uma ordem de linhas. O agrupamento impede que um cálculo passe para outro grupo; a ordenação determina o que significam “anterior” ou “até agora”.

Acumule dentro de cada grupo

Suponha que as linhas dos pedidos já estejam em ordem cronológica:

sales["running_units"] = sales.groupby("region")["units"].cumsum()

As unidades de North 10, 7 e 6 produzem totais acumulados 10, 17 e 23. As de South 4, 9 e 8 produzem 4, 13 e 21. As de East 5 e 3 produzem 5 e 8. Esses valores permanecem associados aos rótulos originais das linhas, então a saída completa na ordem das linhas é 10, 4, 17, 5, 13, 8, 23 e 21.

Sem groupby, sales["units"].cumsum() forneceria um único total para todos os pedidos: 10, 14, 21, 26, 35, 38, 44 e 52. O cálculo agrupado reinicia para cada região. Métodos relacionados incluem cumprod, cummax e cummin para produtos, máximos e mínimos acumulados.

cumcount() conta posições dentro dos grupos a partir de zero. Aqui ele fornece 0, 0, 1, 0, 1, 1, 2 e 2. Some 1 para obter os números do primeiro, segundo e terceiro pedidos dentro de cada região.

Atribua postos aos valores sem reorganizar as linhas

sales.groupby("region")["revenue"].rank(ascending=False)

A maior receita recebe o posto 1 em sua própria região: linha 0 de North, linha 4 de South e linha 3 de East. A saída mantém o índice de entrada; atribuir postos não move as maiores linhas para o topo da tabela.

Por padrão, valores empatados recebem a média de seus postos. Se dois valores empatarem em primeiro lugar, ambos receberão 1,5 e o próximo receberá 3. method="min" dá 1 aos valores empatados e mantém 3 para o próximo. method="dense" dá 1 aos valores empatados e 2 ao próximo. Escolha uma regra de desempate adequada à interpretação dos postos.

Compare valores consecutivos

g = sales.groupby("region")["units"]
previous = g.shift(1)
change = g.diff()
relative_change = g.pct_change()

Os valores anteriores de North são ausente, 10 e 7. Suas diferenças são ausente, −3 e −1. Suas variações relativas são ausente, −0,3 e aproximadamente −0,143: a diferença é dividida pelo valor anterior. pct_change() retorna uma fração, então −0,3 significa uma redução de 30%, não de 0,3%.

A primeira observação de cada grupo não tem observação anterior e recebe NaN. Um shift() aplicado à coluna inteira usaria a linha anterior de toda a tabela, que poderia pertencer a outra região.

Antes desses cálculos ordenados, ordene as linhas pela coluna que define a sequência, como uma data ou número de evento. groupby(sort=True) ordena apenas as chaves dos grupos; ele não coloca as observações em ordem cronológica. A atribuição de postos compara valores e trata empates independentemente da cronologia, enquanto cálculos acumulados e com defasagem dependem da sequência escolhida.

Manter um grupo e resumi-lo são operações diferentes. Um filtro de grupos usa uma condição aplicada ao grupo inteiro para decidir quais linhas originais permanecem; métodos de seleção de linhas escolhem observações específicas de cada grupo.

Mantenha grupos inteiros

sales.groupby("region").filter(lambda g: len(g) >= 3)

North e South têm três pedidos cada um, enquanto East tem dois. O resultado contém as linhas 0, 1, 2, 4, 6 e 7, na ordem original e com seus rótulos originais. Ele não retorna duas linhas de resumo regional.

A condição deve produzir um valor booleano para cada grupo. lambda g: g["units"] > 5 produz uma Series booleana e é inválida para filter. Reduza essa condição com all() ou any():

sales.groupby("region").filter(lambda g: (g["units"] > 5).all())

Apenas North passa, porque todos os seus valores de unidades, 10, 7 e 6, são maiores que 5. Usar any() também mantém South, porque pelo menos um de seus pedidos supera 5.

Um tamanho de grupo transformado fornece uma máscara mais rápida, alinhada às linhas, para a primeira tarefa:

sizes = sales.groupby("region")["units"].transform("size")
sales[sizes >= 3]

Essa máscara pode ser combinada com outras condições de linha usando & e |. Filtrar sales.groupby("region")["revenue"].sum() manteria entradas de resumo, não os pedidos originais.

Obtenha linhas por posição

head(n) obtém as primeiras n linhas por grupo, tail(n) as últimas n e nth(k) a linha na posição k, contando a partir de zero. sales.groupby("region").head(1) retorna as linhas 0, 1 e 3: o primeiro pedido observado de cada região. Valores ausentes não fazem head(1) procurar uma linha posterior sem valor ausente.

Para selecionar o maior pedido por região, ordene primeiro pela receita:

sales.sort_values("revenue", ascending=False).groupby("region").head(1)

As linhas selecionadas são a linha 4 de South com receita 36, a linha 0 de North com 30 e a linha 3 de East com 20. A ordenação controla qual observação vem primeiro; a operação por grupo obtém então essa primeira linha. Com rótulos de linha únicos, sales.loc[sales.groupby("region")["revenue"].idxmax()] recupera os mesmos máximos por seus rótulos.

Faça amostragens dentro de cada grupo

sales.groupby("region").sample(n=1, random_state=0)

Isso extrai um pedido de cada região. Definir random_state torna reproduzíveis as execuções repetidas sobre os mesmos dados. Uma amostra do DataFrame inteiro poderia deixar uma região de fora, mesmo que ela tivesse três linhas no total.

Use frac=0.5 para extrair aproximadamente metade das linhas de cada grupo. O tamanho da amostra por grupo é arredondado: com frac=0.2, as duas linhas de East produzem 0,4 linha, arredondada para zero. Use n=1 explicitamente quando cada grupo não vazio tiver de contribuir com uma observação. O tamanho solicitado da amostra deve ser viável para os grupos nas configurações de amostragem escolhidas.

apply permite que uma função examine um grupo inteiro e retorne um escalar, uma Series ou um DataFrame. Essa flexibilidade é útil quando colunas precisam interagir ou o resultado contém várias linhas. Ela também torna a forma do resultado menos previsível que com agg ou transform.

Use várias colunas juntas

def price_per_unit(g):
    return g["revenue"].sum() / g["units"].sum()

sales.groupby("region").apply(price_per_unit)

A função recebe as linhas de uma região. Ela retorna um valor, então o pandas combina as saídas em uma Series indexada por região: East 3,625, North aproximadamente 3,304 e South aproximadamente 3,810. Uma razão de somas agrupadas disponíveis produz o mesmo resultado com menos trabalho em Python. np.average(g["revenue"] / g["units"], weights=g["units"]) expressa a média ponderada equivalente.

Para uma estatística que envolve duas colunas, como a correlação entre horas de estudo e nota dentro de cada grupo de turma, apply pode passar as duas Series de cada grupo para .corr().

Preveja como as saídas são combinadas

Uma função que retorna uma Series com os mesmos rótulos para todos os grupos cria uma linha de tabela por grupo:

sales.groupby("region").apply(
    lambda g: pd.Series({
        "orders": len(g),
        "avg_price": g["revenue"].sum() / g["units"].sum()
    })
)

As colunas são orders e avg_price. As contagens aparecem como 2,0, 3,0 e 3,0 porque a Series retornada também contém um preço de ponto flutuante. Se as Series retornadas usarem rótulos diferentes, o pandas as empilhará em uma Series mais longa, adicionando as chaves dos grupos como nível externo do índice.

Um DataFrame por grupo é empilhado em um DataFrame maior:

def top(g, n=2, col="revenue"):
    return g.sort_values(col, ascending=False).head(n)

sales.groupby("region").apply(top)

As linhas são East 3 e 5, North 0 e 2 e South 4 e 7. Cada grupo é ordenado independentemente. Argumentos adicionais vêm depois da função: .apply(top, n=1, col="units") altera a seleção para o pedido com mais unidades.

Controle chaves e alinhamento

Para essas linhas retornadas, o padrão group_keys=True adiciona a região como nível externo do índice. sales.groupby("region", group_keys=False).apply(top) mantém apenas os rótulos originais das linhas. Ele ainda reúne os resultados grupo a grupo; não garante a ordem das linhas da tabela de entrada.

Desde o pandas 3.0, o DataFrame passado a um apply agrupado exclui as colunas de agrupamento. Neste exemplo, ele tem product, units e revenue, mas não region. Leia a chave do grupo atual em g.name quando a função precisar dela.

Use o método mais específico quando for adequado

apply executa código Python para cada grupo e infere como reunir a saída. Use agg para valores de resumo por coluna, transform para resultados alinhados a cada linha de entrada e filter para decisões de manter ou remover grupos inteiros.

Por exemplo, subtrair a média de cada região usando apply em uma Series selecionada retorna diferenças sob um MultiIndex de região e linha. transform retorna as diferenças com o índice original, prontas para atribuição como uma coluna.

A discretização em intervalos substitui valores numéricos por categorias de intervalos. Use-a quando um relatório precisar de faixas significativas, como faixas de notas, em vez de um grupo separado para cada número.

Defina limites explícitos

scores = pd.Series([42, 50, 55, 64, 68, 70, 73, 81, 85, 88, 97, 100])
bands = pd.cut(scores, [0, 50, 70, 85, 100])
bands.value_counts(sort=False)

Cinco limites definem quatro intervalos: (0, 50], (50, 70], (70, 85] e (85, 100]. Eles contêm 2, 4, 3 e 3 notas. Limites explícitos podem definir amplitudes desiguais porque descrevem fronteiras significativas.

Nessa notação, um parêntese exclui um extremo e um colchete o inclui. Com o padrão right=True, 50 pertence ao primeiro intervalo, 70 ao segundo, 85 ao terceiro e 100 ao quarto. Leia (50, 70] como “maior que 50 e no máximo 70”.

Trate os limites externos

Com esses limites explícitos, 0 é excluído do primeiro intervalo e 101 está além do último. Ambos recebem NaN. Use include_lowest=True para incluir um valor igual ao limite inferior. Valores abaixo do limite inferior ou acima do superior continuam sem intervalo atribuído.

Para intervalos fechados à esquerda, use right=False. Os mesmos limites definem então [0, 50), [50, 70), [70, 85) e [85, 100). Agora 50 passa para o segundo intervalo e 100 é excluído. As contagens do exemplo passam a ser 1, 4, 3 e 3, com uma atribuição de intervalo ausente. Um limite superior de 101 incluiria a nota 100 no último intervalo fechado à esquerda.

Alterar o fechamento muda a inclusão em um limite. Verifique um mínimo, um limite interno e um máximo antes de usar as faixas em um relatório.

Adicione rótulos legíveis

bands = pd.cut(
    scores, [0, 50, 70, 85, 100],
    labels=["fail", "pass", "merit", "distinction"]
)

Forneça um rótulo para cada intervalo: quatro rótulos para cinco limites. A saída é um tipo categórico ordenado, então sua ordem é fail, pass, merit, distinction, não a ordem alfabética. labels=False retorna códigos de intervalo de 0 a 3 para os valores atribuídos.

value_counts() normalmente ordena por frequência. Use sort=False ou ordene o índice resultante para manter a sequência dos intervalos. Caso contrário, a faixa mais frequente pode aparecer primeiro e dificultar a leitura da distribuição.

Solicite amplitudes iguais ao pandas

Passar um inteiro solicita essa quantidade de intervalos de mesma amplitude:

bands, edges = pd.cut(scores, 4, retbins=True)

A faixa de 42 a 100 abrange 58, resultando em amplitudes de 14,5. Os limites internos são 56,5, 71,0 e 85,5. O pandas estende ligeiramente o extremo inferior desses intervalos fechados à direita, fornecendo um primeiro limite de 41,942 para incluir o mínimo. Neste caso, cada intervalo contém três notas; amplitudes iguais geralmente não produzem contagens iguais.

retbins=True retorna os limites reais, além das atribuições. Limites explícitos devem estar em ordem crescente: [0, 70, 50, 100] não pode definir a sequência pretendida de intervalos.

Um quantil descreve uma posição em dados ordenados. A mediana é o quantil 0,5; quartis dividem a distribuição em quartos, decis em décimos e percentis em centésimos. qcut usa quantis amostrais como limites dos intervalos.

Calcule um quantil

Para as notas 42, 50, 55, 64, 68, 70, 73, 81, 85, 88, 97 e 100:

scores.quantile([0.25, 0.5, 0.75])

Os resultados são 61,75, 71,5 e 85,75. O pandas usa interpolação linear por padrão. Para o quantil 0,25, a posição contada a partir de zero é:

A posição 2 contém 55 e a posição 3 contém 64. Avance três quartos da distância entre elas:

Assim, um quantil amostral pode ficar entre valores observados. Ele não precisa ser igual a uma nota que alguém realmente recebeu.

Crie grupos de quantis

quartile = pd.qcut(scores, 4, labels=["Q1", "Q2", "Q3", "Q4"])

Essa amostra fornece três notas por grupo de quartil. Os limites internos são os três quartis calculados. O primeiro intervalo inclui o mínimo; a exibição do intervalo ajusta seu rótulo inferior para um valor ligeiramente abaixo de 42. Use labels=False para códigos de 0 a 3 ou retbins=True para recuperar os limites numéricos.

Uma lista de proporções controla as faixas de quantis. pd.qcut(x, [0, 0.1, 0.5, 0.9, 1]) separa os 10% inferiores, duas partes intermediárias divididas na mediana e os 10% superiores.

Escolha amplitudes ou contagens

Tempos de entrega de 5, 6, 7, 7, 8, 9, 10, 12, 15, 20, 35 e 60 minutos mostram a diferença. Três intervalos de mesma amplitude contêm 10, 1 e 1 observações. Três intervalos de quantis contêm 4 cada um, com limites internos de aproximadamente 7,67 e 13 minutos. Atrasos longos ampliam a faixa de intervalos de mesma amplitude, deixando a maioria das observações no primeiro intervalo.

Use limites fixos quando as mesmas faixas de tempo precisarem ser comparadas entre conjuntos de dados. Os limites dos quantis mudam quando a amostra muda.

Mantenha os empates visíveis

Para os valores 2, 3, 3, 4, 5, 6, 6, 7, 8, 9, 10 e 12, os limites dos quartis são 3,75, 6 e 8,25. Ambos os valores 6 pertencem ao mesmo intervalo, então as contagens são 3, 4, 2 e 3. A discretização com contagens iguais é aproximada quando há valores empatados.

Com muitos empates, os limites dos quantis podem coincidir. Para 1, 1, 1, 1, 1, 1, 2 e 3, solicitar quartis produz limites repetidos. duplicates="drop" remove limites duplicados e deixa apenas dois intervalos, com contagens 6 e 2. Atribuir postos primeiro com rank(method="first") pode forçar quatro grupos de mesmo tamanho, mas separa valores iguais conforme a ordem das linhas. Isso muda o significado de intervalos de valores para grupos baseados em postos com desempate.

Um rótulo de intervalo pode servir como chave de agrupamento. Isso permite perguntar como uma variável muda entre faixas de outra, como a nota média de prova entre faixas de horas de estudo. O resumo descreve as observações em cada faixa.

Construa um resumo por faixas

Crie os dados dos estudantes:

students = pd.DataFrame({
    "group": ["day", "evening", "day", "evening", "day", "evening", "day", "evening", "day", "day", "evening", "day"],
    "hours": [2, 3, 3, 5, 4, 6, 6, 8, 7, 9, 10, 12],
    "score": [42, 50, 55, 64, 68, 70, 73, 81, 85, 88, 97, 100]
})
hour_band = pd.cut(students["hours"], [0, 3, 6, 9, 12])
students.groupby(hour_band)["score"].agg(["count", "mean"])

As quatro faixas contêm 3, 4, 3 e 2 estudantes. Suas notas médias são 49, 68,75, aproximadamente 84,67 e 98,5. Na primeira faixa, as notas são 42, 50 e 55; sua média é 147/3 = 49. A contagem mostra quantas notas registradas sustentam cada média.

A Series de faixas tem uma entrada por estudante e o mesmo índice, então suas atribuições correspondem às linhas durante o agrupamento. A coluna numérica hours permanece disponível para outros cálculos.

Mantenha intervalos vazios quando um relatório precisar deles

Desde o pandas 3.0, observed=True é o padrão de agrupamento para chaves categóricas. Adicione um limite de 15 e a faixa não utilizada (12, 15] será omitida. observed=False a mantém com contagem 0 e média NaN. Zero estudantes é uma contagem; uma média zero sugeriria incorretamente notas observadas com média zero.

Os intervalos são categorias ordenadas, então a saída agrupada normal segue a ordem dos intervalos do menor para o maior. Rótulos nomeados mantêm a ordem atribuída aos seus intervalos.

Analise grupos de quantis e combinações

quartile = pd.qcut(students["hours"], 4,
                   labels=["Q1", "Q2", "Q3", "Q4"])
students.groupby(quartile)["score"].agg(["count", "min", "max", "mean"])

As contagens são 3, 4, 2 e 3, com notas médias 49, 68,75, 83 e 95. Os valores empatados de 6 explicam as contagens desiguais. Para comparar estudantes de day e evening dentro de cada quartil, agrupe por [quartile, "group"] e chame .mean().unstack(). As médias de Q1 são day 48,5 e evening 50; as de Q4 são day 94 e evening 97.

A direção da análise importa. Agrupar horas de estudo por faixas de notas responde a outra pergunta: as médias de horas para as faixas fail, pass, merit e distinction são 2,5, 4,5, 7 e aproximadamente 10,33.

Decida qual população define um quantil

Uma divisão das notas pela mediana geral usa 71,5. Uma divisão dentro de cada turma usa sua própria mediana: day 73 e evening 70.

within_class = students.groupby("group")["score"].transform(
    lambda s: pd.qcut(s, 2, labels=["lower", "upper"])
)

O estudante de day com nota 73 está acima da mediana geral, mas pertence à metade inferior dentro do grupo day. Ambos os rótulos estão corretos porque respondem a perguntas de comparação diferentes.

Uma média crescente entre faixas de horas é uma associação. Estudantes em faixas diferentes podem diferir de outras maneiras, então a tabela, por si só, não permite estabelecer que o tempo extra de estudo causou a diferença de notas. Contagens pequenas também tornam uma média mais sensível a uma única observação.

Uma tabela dinâmica resume valores para combinações de chaves de linhas e colunas. Cada célula reúne as observações de uma interseção e aplica uma função, como soma ou média.

Defina os papéis explicitamente

sales.pivot_table(
    index="region", columns="product",
    values="revenue", aggfunc="sum"
)

index fornece as chaves das linhas, columns as chaves das colunas, values a variável medida e aggfunc o cálculo. A tabela é:

North e tea combinam as receitas 30 e 18, então sua soma é 48. South e coffee combinam 36 e 32, resultando em 68. Os mesmos dados podem ser resumidos com sales.groupby(["region", "product"])["revenue"].sum().unstack().

O aggfunc padrão é "mean". Omiti-lo forneceria 24 para North e tea e 34 para South e coffee. Indique aggfunc="sum" quando a pergunta solicitar totais; a disposição de uma tabela não informa qual estatística ela contém.

Preencha combinações ausentes com cuidado

Combinações sem observações aparecem como NaN. Remova o pedido de tea de East e essa célula ficará ausente. fill_value=0 pode representar a ausência de pedidos em um relatório de somas ou contagens. Para uma média, substituir uma célula vazia por 0 sugere uma média observada que nunca foi medida. Mantenha seu estado ausente quando não houver média.

Chaves categóricas seguem a escolha de observed; desde o pandas 3.0, o padrão mostra as categorias observadas. Defina-o explicitamente quando um relatório precisar manter categorias não utilizadas.

Adicione resumos marginais usando a mesma função

sales.pivot_table(
    index="region", columns="product", values="revenue",
    aggfunc="sum", margins=True, margins_name="Total"
)

Os totais das linhas são East 29, North 76 e South 80. Os totais das colunas são coffee 116 e tea 69; o total geral é 185. margins_name substitui o rótulo padrão All.

Os resumos marginais são recalculados a partir das linhas originais usando a função de agregação. Para uma tabela dinâmica de médias, o canto é 23,125, a média dos oito pedidos. Calcular a média das seis médias exibidas nas células forneceria aproximadamente 21,17, porque as células contêm números diferentes de observações. Um resumo marginal não é uma instrução geral para somar ou calcular a média dos números exibidos.

Amplie a tabela ou faça contagens

aggfunc=["sum", "mean"] cria um bloco de colunas para cada estatística. Com units, North e tea têm soma 16 e média 8. Um dicionário de funções como {"units": "sum", "revenue": "max"} atribui funções a colunas de valores distintas. Várias chaves também podem criar linhas ou colunas hierárquicas, e valores discretizados funcionam como chaves categóricas.

aggfunc="size" conta linhas por célula, enquanto "count" conta valores não ausentes na coluna de valores escolhida. North tem um pedido de coffee e dois de tea.

pivot não faz agregação e exige combinações únicas de linhas e colunas. A tabela de vendas tem combinações repetidas de North e tea e de South e coffee, então pivot gera um erro de entrada duplicada. Use pivot_table quando várias observações precisarem ser combinadas em uma célula.

Uma tabulação cruzada, ou tabela de contingência, conta observações para combinações de variáveis categóricas. As proporções permitem comparar grupos que contêm números diferentes de observações.

Conte combinações

Os dados da pesquisa têm seis usuários do plano básico: quatro usam celulares e dois usam laptops. Seus quatro usuários premium incluem um usuário de celular e três usuários de laptop.

survey = pd.DataFrame({
    "plan": ["basic"] * 6 + ["premium"] * 4,
    "device": ["phone", "phone", "phone", "laptop", "phone", "laptop",
               "laptop", "laptop", "phone", "laptop"],
    "minutes": [20, 35, 15, 40, 25, 50, 60, 45, 30, 55]
})
counts = pd.crosstab(survey["plan"], survey["device"], margins=True)

Passe as Series reais, não as strings "plan" e "device". A primeira variável fornece as linhas e a segunda fornece as colunas. A linha basic contém laptop 2 e phone 4; a linha premium contém laptop 3 e phone 1. Os totais das linhas são 6 e 4, os totais das colunas são 5 e 5 e o total geral é 10.

Para contagens absolutas, uma combinação ausente é mostrada como zero. Contagens equivalentes podem ser obtidas com survey.groupby(["plan", "device"]).size().unstack(fill_value=0) ou uma tabela dinâmica usando aggfunc="size". survey.value_counts(["plan", "device"]) fornece uma lista longa de frequências ordenada por contagem.

Escolha o denominador a partir da pergunta

“Que proporção dos usuários premium usa laptop?” começa pelos usuários premium, então o denominador é 4. Use a normalização por linha; a resposta é 3/4 = 0,75. “Que proporção dos usuários de celular tem o plano básico?” começa pelos usuários de celular, então o denominador é 5. Use a normalização por coluna; a resposta é 4/5 = 0,8.

Uma contagem de três usuários premium de laptop supera a contagem de dois do plano básico, mas a comparação dentro dos planos é de 75% contra aproximadamente 33,3%. Identifique a população comparada antes de transformar uma contagem em proporção. Multiplique os valores normalizados por 100 para obter percentuais.

Com margins=True, os resumos marginais normalizados também têm significados. A normalização por linha adiciona uma linha All que mostra as proporções gerais de dispositivos, 0,5 e 0,5. A normalização por coluna adiciona uma coluna All que mostra as proporções gerais de planos, 0,6 e 0,4.

Resuma uma terceira variável

Forneça values e aggfunc para substituir frequências por uma estatística numérica:

pd.crosstab(survey["plan"], survey["device"],
            values=survey["minutes"], aggfunc="mean")

As sessões de laptop do plano básico de 40 e 50 minutos têm média 45. As sessões de celular do plano básico de 20, 35, 15 e 25 minutos têm média 23,75. As sessões de laptop premium de 60, 45 e 55 minutos têm média de aproximadamente 53,33, enquanto a única sessão de celular premium dura 30 minutos. Essas células descrevem a duração das sessões, não contagens de usuários.

Uma lista de Series pode fornecer vários níveis de linhas ou colunas. Notas discretizadas também funcionam como categorias: cruzar fail, pass, merit e distinction com o grupo da turma fornece contagens de day 1, 2, 2, 2 e de evening 1, 2, 1, 1. O significado de cada célula continua decorrendo de sua chave de linha, chave de coluna e estatística escolhida.