Skip to content

Python Counter: Contar e Tabular Elementos com collections.Counter

Soren Atelier
Name
Soren Atelier

Updated on

Contar ocorrências de elementos em uma lista, caracteres em uma string ou palavras em um documento é uma das tarefas mais comuns na programação. Fazer isso manualmente significa escrever loops, inicializar dicionários e tratar chaves ausentes com condicionais ou chamadas .get(). Esse código boilerplate obscurece sua intenção real, introduz bugs e te atrasa toda vez que você precisa de uma contagem de frequência.

O collections.Counter do Python elimina essa fricção completamente. Ele conta objetos hasháveis em uma única linha, fornece métodos integrados para encontrar os elementos mais comuns e suporta operações aritméticas para comparar distribuições de frequência. Este guia cobre tudo que você precisa para usar o Counter efetivamente, desde contagem básica até operações avançadas de multiconjuntos.

📚

    O que é collections.Counter?

    Counter é uma subclasse de dicionário no módulo collections do Python projetada especificamente para contar objetos hasháveis. Cada elemento é armazenado como uma chave do dicionário, e sua contagem é armazenada como o valor correspondente.

    from collections import Counter
 
fruits = ['apple', 'banana', 'apple', 'cherry', 'banana', 'apple']
count = Counter(fruits)
print(count)
# Counter({'apple': 3, 'banana': 2, 'cherry': 1})

    Criando um Counter

    Counter aceita múltiplos tipos de entrada, tornando-o flexível para diferentes fontes de dados.

    from collections import Counter
 
# De uma lista
colors = Counter(['red', 'blue', 'red', 'green', 'blue', 'red'])
print(colors)  # Counter({'red': 3, 'blue': 2, 'green': 1})
 
# De uma string (conta cada caractere)
letters = Counter('mississippi')
print(letters)  # Counter({'s': 4, 'i': 4, 'p': 2, 'm': 1})
 
# De um dicionário
inventory = Counter({'apples': 15, 'oranges': 10, 'bananas': 7})
 
# De argumentos nomeados
stock = Counter(laptops=5, monitors=12, keyboards=30)

    Acessando Contagens

    Indexação Básica

    Acesse contagens como um dicionário regular, mas chaves ausentes retornam 0 em vez de lançar KeyError:

    from collections import Counter
 
c = Counter(['a', 'b', 'a'])
print(c['a'])  # 2
print(c['z'])  # 0 (sem KeyError!)
 
# Compare com comportamento de dict regular
d = {'a': 2, 'b': 1}
# d['z']  # Lançaria KeyError

    Esse comportamento de zero padrão elimina a necessidade de .get(key, 0) ou defaultdict(int) em muitos cenários de contagem.

    Obtendo Todos os Elementos

    O método elements() retorna um iterador sobre os elementos, repetindo cada um tantas vezes quanto sua contagem:

    from collections import Counter
 
c = Counter(a=3, b=2, c=1)
print(list(c.elements()))
# ['a', 'a', 'a', 'b', 'b', 'c']

    O Método most_common()

    O método most_common() retorna elementos ordenados por frequência.

    from collections import Counter
 
text = "to be or not to be that is the question"
word_freq = Counter(text.split())
 
# Todos os elementos ordenados por frequência
print(word_freq.most_common())
# [('to', 2), ('be', 2), ('or', 1), ('not', 1), ...]
 
# Apenas os Top N elementos
log_levels = Counter(['INFO', 'WARNING', 'INFO', 'ERROR', 'INFO', 'DEBUG',
                      'WARNING', 'INFO', 'ERROR', 'INFO'])
print(log_levels.most_common(2))
# [('INFO', 5), ('WARNING', 2)]
 
# Menos comuns (slice reverso)
print(log_levels.most_common()[-2:])
# [('DEBUG', 1), ('ERROR', 2)]

    Operações Aritméticas do Counter

    Counter suporta operações aritméticas e de conjuntos para combinar e comparar distribuições de frequência.

    from collections import Counter
 
morning = Counter(coffee=10, tea=5, juice=3)
afternoon = Counter(coffee=8, tea=7, water=4)
 
# Adição: combina contagens
total = morning + afternoon
print(total)  # Counter({'coffee': 18, 'tea': 12, 'water': 4, 'juice': 3})
 
# Subtração: mantém apenas contagens positivas
stock = Counter(apples=20, oranges=15, bananas=10)
sold = Counter(apples=8, oranges=15, bananas=12)
remaining = stock - sold
print(remaining)  # Counter({'apples': 12})
 
# Interseção (&): mínimo das contagens correspondentes
a = Counter(apple=3, banana=2, cherry=5)
b = Counter(apple=1, banana=4, cherry=2)
print(a & b)  # Counter({'cherry': 2, 'banana': 2, 'apple': 1})
 
# União (|): máximo das contagens correspondentes
print(a | b)  # Counter({'cherry': 5, 'banana': 4, 'apple': 3})
 
# + unário: remove contagens zero e negativas
c = Counter(a=3, b=0, c=-2)
print(+c)  # Counter({'a': 3})

    Atualizar e Subtrair

    from collections import Counter
 
# update() SOMA contagens (diferente de dict.update que substitui)
c = Counter(a=3, b=1)
c.update(['a', 'b', 'b', 'c'])
print(c)  # Counter({'a': 4, 'b': 3, 'c': 1})
 
# subtract() subtrai contagens (mantém zero e negativos)
c = Counter(a=4, b=2, c=0)
c.subtract(Counter(a=1, b=3, c=2))
print(c)  # Counter({'a': 3, 'b': -1, 'c': -2})
 
# total() retorna a soma de todas as contagens (Python 3.10+)
inventory = Counter(widgets=50, gadgets=30, gizmos=20)
print(inventory.total())  # 100

    Casos de Uso Práticos

    Análise de Frequência de Palavras

    from collections import Counter
import re
 
text = """
Python is a versatile programming language. Python is used for web development,
data science, machine learning, and automation. Python's simplicity makes it
a favorite among developers.
"""
 
words = re.findall(r'\b[a-z]+\b', text.lower())
word_freq = Counter(words)
 
print("Top 5 most frequent words:")
for word, count in word_freq.most_common(5):
    print(f"  {word}: {count}")

    Detecção de Anagramas

    from collections import Counter
 
def are_anagrams(word1, word2):
    return Counter(word1.lower()) == Counter(word2.lower())
 
print(are_anagrams("listen", "silent"))  # True
print(are_anagrams("hello", "world"))    # False

    Sistema de Contagem de Votos

    from collections import Counter
 
votes = ['Alice', 'Bob', 'Alice', 'Charlie', 'Bob', 'Alice',
         'Charlie', 'Alice', 'Bob', 'Alice']
 
results = Counter(votes)
winner, winning_votes = results.most_common(1)[0]
total_votes = sum(results.values())
 
print(f"Election Results (Total votes: {total_votes}):")
for candidate, count in results.most_common():
    percentage = (count / total_votes) * 100
    print(f"  {candidate}: {count} votes ({percentage:.1f}%)")
print(f"\nWinner: {winner} with {winning_votes} votes")

    Análise de Arquivos de Log

    from collections import Counter
import re
 
log_entries = [
    "2026-02-10 08:15:00 ERROR Database connection failed",
    "2026-02-10 08:15:01 INFO Retrying connection",
    "2026-02-10 08:15:02 ERROR Database connection failed",
    "2026-02-10 08:16:00 WARNING Disk usage at 85%",
    "2026-02-10 08:17:00 INFO Request processed",
    "2026-02-10 08:18:00 ERROR API timeout",
]
 
levels = Counter(
    re.search(r'(INFO|WARNING|ERROR)', line).group()
    for line in log_entries
)
print("Log Level Distribution:")
for level, count in levels.most_common():
    print(f"  {level}: {count}")

    Counter vs defaultdict(int): Quando Usar Qual

    CaracterísticaCounterdefaultdict(int)
    PropósitoConstruído especificamente para contarDicionário com valor padrão genérico
    InicializaçãoCounter(iterable) conta em um passoRequer loop manual
    Chaves ausentesRetorna 0Retorna 0
    most_common()Método integradoPrecisa ordenar manualmente
    Aritmética (+, -)SuportadaNão suportada
    Operações de conjuntos (&, |)SuportadasNão suportadas
    elements()Retorna iterador expandidoNão disponível
    Comportamento de update()Soma às contagensSubstitui valores
    PerformanceImplementação C otimizadaLigeiramente mais lento
    Melhor paraAnálise de frequência, ops multiconjuntoLógica de valor padrão customizada

    Use Counter quando seu objetivo principal é contar elementos ou comparar distribuições de frequência. Use defaultdict(int) quando a contagem é secundária a um padrão de estrutura de dados mais amplo.

    Visualizando Distribuições de Frequência

    Depois de contar elementos com Counter, você frequentemente quer visualizar a distribuição. Para exploração interativa de distribuições de frequência, PyGWalker (opens in a new tab) transforma um DataFrame pandas em uma interface interativa estilo Tableau diretamente no Jupyter:

    from collections import Counter
import pandas as pd
import pygwalker as pyg
 
# Converter Counter para DataFrame
data = Counter("abracadabra")
df = pd.DataFrame(data.items(), columns=['Character', 'Count'])
 
# Lançar visualização interativa
walker = pyg.walk(df)

    Isso é especialmente útil quando você tem contadores grandes e quer filtrar, ordenar e explorar distribuições de frequência interativamente.

    FAQ

    O que faz collections.Counter no Python?

    collections.Counter é uma subclasse de dicionário que conta objetos hasháveis. Você passa qualquer iterável e ele retorna um objeto tipo dicionário onde as chaves são os elementos e os valores são suas contagens. Fornece métodos como most_common() para análise de frequência, operadores aritméticos para combinar contagens e retorna zero para chaves ausentes em vez de lançar KeyError.

    Como conto ocorrências de itens em uma lista usando Python Counter?

    Importe Counter de collections e passe sua lista diretamente: Counter(['a', 'b', 'a', 'c']) retorna Counter({'a': 2, 'b': 1, 'c': 1}). Para contagens específicas, indexe com o elemento: counter['a'] retorna 2. Para os itens mais frequentes, use counter.most_common(n).

    Qual é a diferença entre Counter e um dicionário regular para contagem?

    Counter é construído especificamente para contagem: conta um iterável inteiro em uma chamada, retorna 0 para chaves ausentes em vez de KeyError, tem most_common() para frequências ordenadas, suporta operações aritméticas (+, -, &, |) e inclui update() que soma às contagens em vez de substituí-las. Um dicionário regular requer construção manual de loops e não possui essas funcionalidades.

    Posso subtrair ou somar dois objetos Counter?

    Sim. O operador + combina contagens: Counter(a=3) + Counter(a=1) produz Counter({'a': 4}). O operador - subtrai contagens e descarta resultados zero ou negativos. O operador & dá o mínimo (interseção) e | dá o máximo (união) das contagens correspondentes. Para subtração que preserva contagens negativas, use o método subtract().

    Python Counter é eficiente para grandes conjuntos de dados?

    Sim. Counter é implementado em código C otimizado no CPython, tornando-o mais rápido que loops manuais Python para contagem. Criar um Counter de um iterável é O(n). Acessar contagens individuais é O(1). A operação most_common(k) usa um heap internamente para eficiência O(n log k) quando você precisa apenas dos top-k elementos.

    Conclusão

    O collections.Counter do Python é a ferramenta padrão para contar elementos e realizar análise de frequência. Ele substitui a contagem manual com dicionários por uma única chamada ao construtor, fornece most_common() para classificação instantânea e suporta operações aritméticas que tornam comparações de multiconjuntos triviais. Seja analisando frequências de palavras, contando votos, gerenciando inventário ou analisando arquivos de log, Counter cuida da contagem para que você possa focar na lógica que importa.

    📚