<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Counter — Python Module of the Week</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.132',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="top" title="Python Module of the Week" href="../index.html" />
<link rel="up" title="collections – Container data types" href="index.html" />
<link rel="next" title="defaultdict" href="defaultdict.html" />
<link rel="prev" title="collections – Container data types" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="defaultdict.html" title="defaultdict"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="collections – Container data types"
accesskey="P">previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../data_types.html" >Data Types</a> »</li>
<li><a href="index.html" accesskey="U">collections – Container data types</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Counter</a><ul>
<li><a class="reference internal" href="#initializing">Initializing</a></li>
<li><a class="reference internal" href="#accessing-counts">Accessing Counts</a></li>
<li><a class="reference internal" href="#arithmetic">Arithmetic</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">collections – Container data types</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="defaultdict.html"
title="next chapter">defaultdict</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/collections/counter.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="counter">
<h1>Counter<a class="headerlink" href="#counter" title="Permalink to this headline">¶</a></h1>
<p>A <tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> is a container that keeps track of how many times
equivalent values are added. It can be used to implement the same
algorithms for which bag or multiset data structures are commonly used
in other languages.</p>
<div class="section" id="initializing">
<h2>Initializing<a class="headerlink" href="#initializing" title="Permalink to this headline">¶</a></h2>
<p><tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> supports three forms of initialization. Its
constructor can be called with a sequence of items, a dictionary
containing keys and counts, or using keyword arguments mapping string
names to counts.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">collections</span>
<span class="k">print</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">([</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'c'</span><span class="p">,</span> <span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">])</span>
<span class="k">print</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">({</span><span class="s">'a'</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span> <span class="s">'b'</span><span class="p">:</span><span class="mi">3</span><span class="p">,</span> <span class="s">'c'</span><span class="p">:</span><span class="mi">1</span><span class="p">})</span>
<span class="k">print</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">b</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">c</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
<p>The results of all three forms of initialization are the same.</p>
<div class="highlight-python"><pre>$ python collections_counter_init.py
Counter({'b': 3, 'a': 2, 'c': 1})
Counter({'b': 3, 'a': 2, 'c': 1})
Counter({'b': 3, 'a': 2, 'c': 1})</pre>
</div>
<p>An empty <tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> can be constructed with no arguments and
populated via the <tt class="xref py py-func docutils literal"><span class="pre">update()</span></tt> method.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">collections</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">()</span>
<span class="k">print</span> <span class="s">'Initial :'</span><span class="p">,</span> <span class="n">c</span>
<span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="s">'abcdaab'</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'Sequence:'</span><span class="p">,</span> <span class="n">c</span>
<span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s">'a'</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span> <span class="s">'d'</span><span class="p">:</span><span class="mi">5</span><span class="p">})</span>
<span class="k">print</span> <span class="s">'Dict :'</span><span class="p">,</span> <span class="n">c</span>
</pre></div>
</div>
<p>The count values are increased based on the new data, rather than
replaced. In this example, the count for <tt class="docutils literal"><span class="pre">a</span></tt> goes from <tt class="docutils literal"><span class="pre">3</span></tt> to
<tt class="docutils literal"><span class="pre">4</span></tt>.</p>
<div class="highlight-python"><pre>$ python collections_counter_update.py
Initial : Counter()
Sequence: Counter({'a': 3, 'b': 2, 'c': 1, 'd': 1})
Dict : Counter({'d': 6, 'a': 4, 'b': 2, 'c': 1})</pre>
</div>
</div>
<div class="section" id="accessing-counts">
<h2>Accessing Counts<a class="headerlink" href="#accessing-counts" title="Permalink to this headline">¶</a></h2>
<p>Once a <tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> is populated, its values can be retrieved
using the dictionary API.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">collections</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">(</span><span class="s">'abcdaab'</span><span class="p">)</span>
<span class="k">for</span> <span class="n">letter</span> <span class="ow">in</span> <span class="s">'abcde'</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s"> : </span><span class="si">%d</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">letter</span><span class="p">,</span> <span class="n">c</span><span class="p">[</span><span class="n">letter</span><span class="p">])</span>
</pre></div>
</div>
<p><tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> does not raise <a class="reference internal" href="../exceptions/index.html#exceptions-keyerror"><em>KeyError</em></a>
for unknown items. If a value has not been seen in the input (as with
<tt class="docutils literal"><span class="pre">e</span></tt> in this example), its count is <tt class="docutils literal"><span class="pre">0</span></tt>.</p>
<div class="highlight-python"><pre>$ python collections_counter_get_values.py
a : 3
b : 2
c : 1
d : 1
e : 0</pre>
</div>
<p>The <tt class="xref py py-func docutils literal"><span class="pre">elements()</span></tt> method returns an iterator that produces all of
the items known to the <tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">collections</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">(</span><span class="s">'extremely'</span><span class="p">)</span>
<span class="n">c</span><span class="p">[</span><span class="s">'z'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">0</span>
<span class="k">print</span> <span class="n">c</span>
<span class="k">print</span> <span class="nb">list</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">elements</span><span class="p">())</span>
</pre></div>
</div>
<p>The order of elements is not guaranteed, and items with counts less
than zero are not included.</p>
<div class="highlight-python"><pre>$ python collections_counter_elements.py
Counter({'e': 3, 'm': 1, 'l': 1, 'r': 1, 't': 1, 'y': 1, 'x': 1, 'z': 0})
['e', 'e', 'e', 'm', 'l', 'r', 't', 'y', 'x']</pre>
</div>
<p>Use <tt class="xref py py-func docutils literal"><span class="pre">most_common()</span></tt> to produce a sequence of the <em>n</em> most
frequently encountered input values and their respective counts.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">collections</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">()</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s">'/usr/share/dict/words'</span><span class="p">,</span> <span class="s">'rt'</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">f</span><span class="p">:</span>
<span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">line</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span>
<span class="k">print</span> <span class="s">'Most common:'</span>
<span class="k">for</span> <span class="n">letter</span><span class="p">,</span> <span class="n">count</span> <span class="ow">in</span> <span class="n">c</span><span class="o">.</span><span class="n">most_common</span><span class="p">(</span><span class="mi">3</span><span class="p">):</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s">: </span><span class="si">%7d</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">letter</span><span class="p">,</span> <span class="n">count</span><span class="p">)</span>
</pre></div>
</div>
<p>This example counts the letters appearing in all of the words in the
system dictionary to produce a frequency distribution, then prints the
three most common letters. Leaving out the argument to
<tt class="xref py py-func docutils literal"><span class="pre">most_common()</span></tt> produces a list of all the items, in order of
frequency.</p>
<div class="highlight-python"><pre>$ python collections_counter_most_common.py
Most common:
e: 234803
i: 200613
a: 198938</pre>
</div>
</div>
<div class="section" id="arithmetic">
<h2>Arithmetic<a class="headerlink" href="#arithmetic" title="Permalink to this headline">¶</a></h2>
<p><tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> instances support arithmetic and set operations for
aggregating results.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">collections</span>
<span class="n">c1</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">([</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'c'</span><span class="p">,</span> <span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">])</span>
<span class="n">c2</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">Counter</span><span class="p">(</span><span class="s">'alphabet'</span><span class="p">)</span>
<span class="k">print</span> <span class="s">'C1:'</span><span class="p">,</span> <span class="n">c1</span>
<span class="k">print</span> <span class="s">'C2:'</span><span class="p">,</span> <span class="n">c2</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\n</span><span class="s">Combined counts:'</span>
<span class="k">print</span> <span class="n">c1</span> <span class="o">+</span> <span class="n">c2</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\n</span><span class="s">Subtraction:'</span>
<span class="k">print</span> <span class="n">c1</span> <span class="o">-</span> <span class="n">c2</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\n</span><span class="s">Intersection (taking positive minimums):'</span>
<span class="k">print</span> <span class="n">c1</span> <span class="o">&</span> <span class="n">c2</span>
<span class="k">print</span> <span class="s">'</span><span class="se">\n</span><span class="s">Union (taking maximums):'</span>
<span class="k">print</span> <span class="n">c1</span> <span class="o">|</span> <span class="n">c2</span>
</pre></div>
</div>
<p>Each time a new <tt class="xref py py-class docutils literal"><span class="pre">Counter</span></tt> is produced through an operation, any
items with zero or negative counts are discarded. The count for <tt class="docutils literal"><span class="pre">a</span></tt>
is the same in <tt class="xref py py-data docutils literal"><span class="pre">c1</span></tt> and <tt class="xref py py-data docutils literal"><span class="pre">c2</span></tt>, so subtraction leaves it at
zero.</p>
<div class="highlight-python"><pre>$ python collections_counter_arithmetic.py
C1: Counter({'b': 3, 'a': 2, 'c': 1})
C2: Counter({'a': 2, 'b': 1, 'e': 1, 'h': 1, 'l': 1, 'p': 1, 't': 1})
Combined counts:
Counter({'a': 4, 'b': 4, 'c': 1, 'e': 1, 'h': 1, 'l': 1, 'p': 1, 't': 1})
Subtraction:
Counter({'b': 2, 'c': 1})
Intersection (taking positive minimums):
Counter({'a': 2, 'b': 1})
Union (taking maximums):
Counter({'b': 3, 'a': 2, 'c': 1, 'e': 1, 'h': 1, 'l': 1, 'p': 1, 't': 1})</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="defaultdict.html" title="defaultdict"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="collections – Container data types"
>previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../data_types.html" >Data Types</a> »</li>
<li><a href="index.html" >collections – Container data types</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Doug Hellmann.
Last updated on Oct 24, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br/><a href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/" rel="license"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png"/></a>
</div>
</body>
</html>