I'm not sure if this is fully documented anywhere, but the animated state of the artist controls whether it is turned on when drawing a graph.
If animated is True, then the artist will not be drawn when fig.draw() called. Instead, it will only appear when manually calling draw_artist(artist_with_animated_set) . This simplifies blitting functions.
Note. This does not apply to all backends! I think this applies to almost all interactive backends, but this does not apply to non-interactive backends. It is intended for use in conjunction with blitting, so backends that do not support blits do not support the animated flag.
For example, if we do something similar to this:
import matplotlib.pyplot as plt fig, ax = plt.subplots() ax.plot(range(10), animated=True) plt.show()
We get an empty plot - the line will not be drawn. (Note: if you save this drawing, a line will appear. See Caution about non-interactive backends above. Matplotlib temporarily switches to a non-interactive backend to save the figure.)
To understand why this is useful, suppose you were creating an animation or an interactive gui (and not using the new animation structure). You want to use blitting to make the animation look smooth.
However, when the image size changes, etc., the animation background needs to be updated. The best way to handle this is to attach a callback to the draw event. Without the animated flag, you have to redraw the graph inside the callback callback, which will cause an infinite loop. (The workaround is to disconnect and reconnect the drawing event callback, but this is a bit of a pain.)
Anyway, the animated flag simplifies this process quite a bit. For example, you can use the animated flag in something like this:
import numpy as np import matplotlib.pyplot as plt class AnimatedSinWave(object): def __init__(self, speed=0.1, interval=25): self.fig, self.ax = plt.subplots() self.x = np.linspace(0, 6 * np.pi, 200) self.i, self.speed = 0.0, speed self.line, = self.ax.plot(self.x, np.sin(self.x), animated=True) self.ax.set_title('Try resizing the figure window') self.fig.canvas.mpl_connect('draw_event', self.update_background) self.t = self.fig.canvas.new_timer(interval, [(self.update, [], {})]) self.t.start() def update_background(self, event): self._background = self.fig.canvas.copy_from_bbox(self.ax.bbox) def update(self): self.fig.canvas.restore_region(self._background) self.line.set_ydata(np.sin(self.i * self.speed + self.x)) self.ax.draw_artist(self.line) self.i += 1 self.fig.canvas.blit(self.ax.bbox) def show(self): plt.show() AnimatedSinWave().show()
Note. For various reasons, you'll have some weird things on OSX and qt * Agg. If the background is black when the window first pops up, move or focus the window and it should fix itself.
In any case, without the animated flag (or the new animation structure) this example becomes much more complicated.