<h3 dir="auto">Problem</h3>
<p dir="auto">The landing page for the matplotlib documentation link <a href="https://matplotlib.org/devdocs/contents.html" rel="nofollow">https://matplotlib.org/devdocs/contents.html</a> is simply a table of contents, which can be hard to navigate for someone unfamiliar with matplotlib.<br>
<a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/1300499/106089175-6bfe1600-60f5-11eb-853f-ce08ba1d92e0.png"><img src="https://user-images.githubusercontent.com/1300499/106089175-6bfe1600-60f5-11eb-853f-ce08ba1d92e0.png" alt="image" style="max-width: 100%;"></a></p>
<h3 dir="auto">Suggested Improvement</h3>
<p dir="auto">Rework this page so there's some roadmapping/guidance on what the different parts of the documentation are. For example, the Pandas docs (<a href="https://pandas.pydata.org/docs/" rel="nofollow">https://pandas.pydata.org/docs/</a>):<br>
<a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/1300499/106089349-cb5c2600-60f5-11eb-8759-59e2b6b8f05f.png"><img src="https://user-images.githubusercontent.com/1300499/106089349-cb5c2600-60f5-11eb-8759-59e2b6b8f05f.png" alt="image" style="max-width: 100%;"></a><br>
Or the numpy docs which require less HTML/CSS/work but still has more guidance (<a href="https://numpy.org/doc/stable/" rel="nofollow">https://numpy.org/doc/stable/</a>):<br>
<a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/1300499/106089546-20983780-60f6-11eb-9ba9-60d144c9b6a8.png"><img src="https://user-images.githubusercontent.com/1300499/106089546-20983780-60f6-11eb-9ba9-60d144c9b6a8.png" alt="image" style="max-width: 100%;"></a></p>
<h3 dir="auto">Problem</h3>

<p dir="auto">The example in <a href="https://matplotlib.org/gallery/animation/histogram.html" rel="nofollow">https://matplotlib.org/gallery/animation/histogram.html</a> supposedly shows how to make an animated histogram out of some data (in the example, random numbers from a gaussian distribution). However, the example generates a wrong animation.</p>
<p dir="auto">This can be a big issue for people who do not have much experience tinkering with matplotlib and just plug their data into the example, thinking that it will work, and who might even end up going through all their data thinking that the histogram is correct and their data is bad (I just spent some time helping a friend to fix the histogram).</p>
<p dir="auto">The problem lies in the fact that <code class="notranslate">np.histogram</code> is used to generate a completely new histogram, from completely new data, at each timestep. However, only the top coordinates of each bin are updated. The code assumes that bins returned by <code class="notranslate">np.histogram</code> will always have the same x coordinates and do not need to be completely redrawn. This is of course wrong. The presence of outliers may force the bins to change width and may cause them to "move" towards one of the sides.</p>
<h3 dir="auto">Suggested Improvement</h3>

<p dir="auto">The simplest improvement is, of course, to update the <code class="notranslate">animate</code> function to completely redraw the bins, including inside the animate function more of the code that is already present outside it, to generate the patch in the first place:</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="def animate(i):
    # simulate new data coming in
    data = np.random.randn(1000)
    n, bins = np.histogram(data, 100)

    left = np.array(bins[:-1])
    right = np.array(bins[1:])
    top = bottom + n

    verts[0::5, 0] = left
    verts[0::5, 1] = bottom
    verts[1::5, 0] = left
    verts[1::5, 1] = top
    verts[2::5, 0] = right
    verts[2::5, 1] = top
    verts[3::5, 0] = right
    verts[3::5, 1] = bottom

    return [patch, ]"><pre class="notranslate"><code class="notranslate">def animate(i):
    # simulate new data coming in
    data = np.random.randn(1000)
    n, bins = np.histogram(data, 100)

    left = np.array(bins[:-1])
    right = np.array(bins[1:])
    top = bottom + n

    verts[0::5, 0] = left
    verts[0::5, 1] = bottom
    verts[1::5, 0] = left
    verts[1::5, 1] = top
    verts[2::5, 0] = right
    verts[2::5, 1] = top
    verts[3::5, 0] = right
    verts[3::5, 1] = bottom

    return [patch, ]
</code></pre></div>
<p dir="auto">Note that an alternative solution, namely the use of <code class="notranslate">np.digitize</code> instead of <code class="notranslate">np.histogram</code> to fit the new data to the existing histogram, would not work, as the new data might cover a different range than the original bins.</p>
<p dir="auto">This would make the code much better, but there is another hidden problem: <code class="notranslate">set_xlim</code> and <code class="notranslate">set_ylim</code> are currently called based on the first batch of data. This might cause two issues, which do not show up that much with gaussian-distributed data, but may arise in real-world usage:</p>
<ul dir="auto">
<li>if outliers force the bin distribution to be much to the left or much to the right, some bins might be outside of limits and not show up;</li>
<li>if some bins end up being taller, they will be "cut" at the top of the plot.</li>
</ul>
<p dir="auto">To solve this issue, it is necessary to know beforehand the left-most, right-most and tallest bin across <strong>all</strong> batches of data. However, the solution to this is not trivial and may change depending on the actual real-world scenario in which this example is being applied. So I am not sure which solution should be implemented in the example:</p>
<ul dir="auto">
<li>assume that it is not possible to analyze all data before starting the plotting; in this case, just hard-code reasonable values for left, right and top limits;</li>
<li>call <code class="notranslate">np.histogram</code> on each batch of data, find the left-most left bin edge, right-most right bin edge and tallest bin across all histograms computed, set those as the limits;</li>
<li>call  <code class="notranslate">np.histogram</code> once on all the data, generating a single set of bins; set the left and right limits based on these bins; then use <code class="notranslate">np.digitize</code> to assign each data point from each batch to the correct bin; use these assignments to find the tallest bin, not the original values from <code class="notranslate">np.histogram</code> (those would be too high); the advantage of this solution over the previous one is that the bins themselves do not move; they only change height.</li>
</ul>
<p dir="auto">The second or third solution would require quite a big refactoring of the source code, which might be good in general, as the new version of <code class="notranslate">animate</code> shown above would have quite a lot of code duplication with the main script, which could be avoided with a refactoring.</p>