HOWTO · Pandas
Conte valores únicos por grupo(s) em Pandas
valores de contagem por coluna de agrupamento em DataFrame usando métodos df.groupby().nunique(), df.groupby().agg(), e df.groupby().unique() na biblioteca de pandas
Nesta página
Ao analisar um DataFrame, muitas vezes é preciso saber quantos valores distintos aparecem dentro de cada grupo, e não na coluna inteira. Por exemplo, um conjunto de dados pode registrar quais valores de code cada entrada em Countries usa, e você quer uma contagem por país. A operação groupby() do pandas oferece três ferramentas práticas para essa tarefa:
df.groupby().nunique()retorna o número de valores distintos em cada grupo.df.groupby().agg()aplica a mesma contagem por meio da interface geral de agregação.df.groupby().unique()lista os próprios valores distintos de cada grupo.
Todos os exemplos abaixo usam o mesmo DataFrame, construído a partir de nove linhas de pares de país e código.
Execute este exemplo:
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
import pandas as pd
data = [
[999, "Switzerland"],
[113, "Switzerland"],
[112, "Japan"],
[112, "Switzerland"],
[113, "Canada"],
[114, "Japan"],
[100, "Germany"],
[114, "Japan"],
[115, "Germany"],
]
df = pd.DataFrame(data, columns=["code", "Countries"])
print(df)
code Countries
0 999 Switzerland
1 113 Switzerland
2 112 Japan
3 112 Switzerland
4 113 Canada
5 114 Japan
6 100 Germany
7 114 Japan
8 115 Germany
Contar valores únicos com GroupBy.nunique()
A maneira mais direta de contar valores distintos por grupo é nunique(). Selecionar a coluna code depois de groupby() transforma o objeto agrupado em uma Series agrupada, de modo que nunique() conta os diferentes códigos dentro das linhas de cada país.
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
import pandas as pd
data = [
[999, "Switzerland"],
[113, "Switzerland"],
[112, "Japan"],
[112, "Switzerland"],
[113, "Canada"],
[114, "Japan"],
[100, "Germany"],
[114, "Japan"],
[115, "Germany"],
]
df = pd.DataFrame(data, columns=["code", "Countries"])
result = df.groupby("Countries")["code"].nunique()
print(result)
Countries
Canada 1
Germany 2
Japan 2
Switzerland 3
Name: code, dtype: int64
O resultado é uma Series cujo índice contém os nomes dos grupos e cujos valores contêm as contagens: a Suíça usa três códigos distintos, a Alemanha e o Japão usam dois cada um, e o Canadá usa um. Como as chaves de grupo viraram o índice, chame reset_index() se quiser um DataFrame plano de duas colunas, ou use a forma agg() na próxima seção. Por padrão, nunique() não conta entradas ausentes (NaN); passe dropna=False se os valores ausentes devem contar como um valor distinto.
Contar valores únicos com GroupBy.agg()
agg() é o método geral de agregação de um objeto agrupado. Passar nunique() como função de agregação produz as mesmas contagens por meio da interface DataFrame.aggregate(), com mais controle sobre o formato do resultado.
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
import pandas as pd
data = [
[999, "Switzerland"],
[113, "Switzerland"],
[112, "Japan"],
[112, "Switzerland"],
[113, "Canada"],
[114, "Japan"],
[100, "Germany"],
[114, "Japan"],
[115, "Germany"],
]
df = pd.DataFrame(data, columns=["code", "Countries"])
result = df.groupby(by="Countries", as_index=False).agg({"code": pd.Series.nunique})
print(result)
Countries code
0 Canada 1
1 Germany 2
2 Japan 2
3 Switzerland 3
O dicionário {"code": pd.Series.nunique} diz a agg() qual coluna agregar e qual função aplicar; pd.Series.nunique é a mesma operação chamada diretamente na seção anterior, e passar seu nome como string — agg({"code": "nunique"}) — funciona de forma idêntica. O argumento as_index=False mantém os nomes dos países como uma coluna comum em vez de movê-los para o índice, e é por isso que result é um DataFrame plano, e não uma Series indexada. Recorra a essa forma quando quiser um resultado em DataFrame ou quando a contagem de distintos for uma de várias agregações calculadas em uma única passada.
Listar valores únicos com GroupBy["code"].unique()
Uma contagem responde “quantos”, mas às vezes você precisa saber quais códigos cada país usa. Aplicar unique() a uma Series agrupada retorna os próprios valores distintos.
O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.
import pandas as pd
data = [
[999, "Switzerland"],
[113, "Switzerland"],
[112, "Japan"],
[112, "Switzerland"],
[113, "Canada"],
[114, "Japan"],
[100, "Germany"],
[114, "Japan"],
[115, "Germany"],
]
df = pd.DataFrame(data, columns=["code", "Countries"])
result = df.groupby("Countries")["code"].unique()
print(result)
Countries
Canada [113]
Germany [100, 115]
Japan [112, 114]
Switzerland [999, 113, 112]
Name: code, dtype: object
Cada entrada do resultado é um array dos valores distintos de code vistos para aquele país, em ordem de aparecimento — o array da Suíça confirma os três códigos contados antes: 999, 113 e 112. Como cada elemento é um array, e não um único número, a Series tem dtype object. Uma diferença de comportamento que vale notar: unique() inclui um NaN no array retornado, enquanto nunique() ignora valores ausentes por padrão.
Escolher entre contar e listar valores
Escolha nunique() quando a pergunta for quantitativa — “quantos códigos distintos cada país usa?” Ele retorna contagens numéricas organizadas que você pode ordenar, filtrar ou juntar de volta às linhas originais. Para anexar a contagem do grupo de cada linha como uma nova coluna, use df.groupby("Countries")["code"].transform("nunique"), que propaga a contagem por grupo para todas as linhas.
Escolha unique() quando a identidade dos valores importa — por exemplo, para auditar quais códigos são compartilhados entre países ou para alimentar as listas de valores em uma etapa posterior de processamento. Se você já tem o resultado de unique() e precisa dos seus tamanhos, result.apply(len) reproduz as mesmas contagens que nunique() daria.
Por fim, use agg() quando uma contagem de distintos for apenas parte de uma agregação maior, como agg({"code": "nunique", "price": "sum"}), que calcula várias estatísticas por grupo em uma única passada. Em resumo: nunique() para a contagem, unique() para os valores e agg() quando você precisa de um resultado em DataFrame ou quer combinar a contagem com outras agregações.