Understanding collections.Counter() in Python

If you’ve ever found yourself counting the frequency of items in a list or a dictionary, you might have found yourself wondering if there’s a better, more Pythonic way to accomplish this task. The collections.Counter() class is a simple and powerful tool in Python that can help you count the frequency of elements in a collection.

What is collections.Counter()?

collections.Counter() is a Python class that extends the functionality of dictionaries by providing a way to count the frequency of items in a collection. It is a subclass of the built-in Python dict class, and it works by storing elements as dictionary keys and their counts as dictionary values.

The Counter() class can be initialized in several ways:

# from an iterable
c = Counter('hello')

# from a dictionary or another Counter object
d = {'cat': 4, 'dog': 2, 'hamster': 1}
e = Counter(d)

# from keyword arguments
f = Counter(cats=4, dogs=2)

How does collections.Counter() work?

The Counter() class works by providing a count of the frequency of elements in a collection. Elements can be added to a Counter() object in several ways:

from collections import Counter

# create an empty Counter object
c = Counter()

# add elements manually
c['apple'] += 1
c['banana'] += 2

# add elements from an iterable
c.update(['apple', 'banana', 'cherry'])

Once elements are added to a Counter() object, you can access the count of an element by indexing the dictionary with the element as the key:

from collections import Counter

c = Counter(['apple', 'banana', 'banana', 'cherry'])
print(c['banana']) # 2

If you try to access the count of an element that is not in the Counter() object, it will return a count of 0:

from collections import Counter

c = Counter(['apple', 'banana', 'banana', 'cherry'])
print(c['orange']) # 0

You can also use the elements() method to return an iterator over the elements in the Counter() object, repeating each element as many times as its count:

from collections import Counter

c = Counter(a=3, b=1)
for elem in c.elements():
    print(elem)
# output:
# 'a'
# 'a'
# 'a'
# 'b'

Additional methods

collections.Counter() provides several methods beyond those available for all dictionaries. Here are a few of the most useful:

most_common()

The most_common() method returns a list of the n most common elements and their counts from the most common to the least. If n is omitted or None, most_common() returns all elements in the Counter() object.

from collections import Counter

c = Counter('abracadabra')
print(c.most_common(3))
# output: [('a', 5), ('b', 2), ('r', 2)]

subtract()

The subtract() method subtracts elements from an iterable or another mapping (or Counter()) object. Like dict.update(), but subtracts counts instead of replacing them.

from collections import Counter

c = Counter(a=4, b=2, c=0, d=-2)
d = Counter(a=1, b=2, c=3, d=4)
c.subtract(d)
print(c) # Counter({'a': 3, 'b': 0, 'c': -3, 'd': -6})