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:

  1. df.groupby().nunique() retorna o número de valores distintos em cada grupo.
  2. df.groupby().agg() aplica a mesma contagem por meio da interface geral de agregação.
  3. 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.