Add tutorial text

chahak13 · chahak13 · commit 76270ac1d6f8 · 2022-10-28T00:52:23.000-05:00
diff --git a/tutorials/introductory/animation_tutorial.py b/tutorials/introductory/animation_tutorial.py
@@ -3,37 +3,66 @@
 Animations using matplotlib
 ===========================
 
-Animations in matplotlib can be created using the `~matplotlib.Animation`
-module. This module provides 2 main animation classes -
-`~matplotlib.animation.FuncAnimation` and
-`~matplotlib.animation.ArtistAnimation`.
+Based on its plotting functionality, matplotlib also provides an interface to
+generate animations using the :class:`~matplotlib.animation` module. An
+animation is a sequence of frames where each frame corresponds to a plot on a
+:class:`~matplotlib.figure.Figure`. This tutorial covers a general guideline on
+how to create such animations and the different options available.
 """
 
 import matplotlib.pyplot as plt
 import matplotlib.animation as animation
 import numpy as np
 
 ###############################################################################
+# Animation Classes
+# =================
+#
+# The process of animation can be thought about in 2 different ways:
+#
+# 1. Generate data for first frame and then modify this data for each frame to
+# create an animated plot.
+# 2. Generate a list (iterable) of plots (/images) that will each be a frame in
+# the animation.
+#
+# Both of these thought processes can be translated into matplotlib using the
+# :class:`~matplotlib.animation`'s :class:`~matplotlib.animation.FuncAnimation`
+# and :class:`~matplotlib.animation.ArtistAnimation` classes respectively.
+#
 # :class:`~matplotlib.animation.FuncAnimation`
 # --------------------------------------------
+#
+# :class:`~matplotlib.animation.FuncAnimation` class allows us to create an
+# animation by passing a function that iteratively modifies the data of a plot.
+# This is achieved by using the *setter* methods on various
+# :class:`~matplotlib.artist.Artist`
+# (examples: :class:`~matplotlib.line.Line2D`,
+# :class:`~matplotlib.collections.PathCollection`, etc.). A usual
+# :class:`~matplotlib.animation.FuncAnimation` object takes a
+# :class:`~matplotlib.figure.Figure` that we want to animate and a function
+# *func* that modifies the data plotted on the figure. It uses the *frames*
+# parameter to determine the length of the animation. The *interval* parameter
+# is used to determine time in milliseconds between drawing of two frames.
+# (This is different than *fps* in `.animation.save` that we will
+# cover later). We will now look at some examples of using
+# :class:`~matplotlib.animation.FuncAnimation` with different artists.
 
-# :class:`~matplotlib.animation.FuncAnimation` uses a user-provided function by
-# repeatedly calling the function with at a regular *interval*. This allows
-# dynamic generation of data by using generators.
-
-
-def init():
-    ax.set_ylim(-1, 1)
-    ax.set_xlim(0, 10)
-    xdata.clear()
-    ydata.clear()
-    line.set_data(xdata, ydata)
-    return line,
+###############################################################################
+# Animating :class:`~matplotlib.lines.Line2D`
+# ---------------------------------------------------------
+#
+# `.pyplot.plot` returns a :class:`~matplotlib.lines.Line2D` collection. The
+# data on this collection can be modified by using the
+# `.lines.Line2D.set_data` function. Therefore we can use this to modify the
+# plot using the function for every frame.
 
 fig, ax = plt.subplots()
-line, = ax.plot([], [], lw=2)
-ax.grid()
+rng = np.random.default_rng()
+
 xdata, ydata = [], []
+line, = ax.plot(xdata, ydata, c='b')
+ax.grid()
+ax.set_ylim(-1, 1)
 
 
 def update(frame):
@@ -45,17 +74,20 @@ def update(frame):
         ax.set_xlim(xmin, 2*xmax)
         ax.figure.canvas.draw()
     line.set_data(xdata, ydata)
-
     return line,
 
 ani = animation.FuncAnimation(
-    fig=fig, func=update, frames=240, init_func=init, interval=30
+    fig=fig, func=update, interval=30
 )
 plt.show()
 
 ###############################################################################
-# Animating :class:`~matplotlib.lines.PathCollection`
-# ---------------------------------------------------
+# Animating :class:`~matplotlib.collections.PathCollection`
+# ---------------------------------------------------------
+#
+# `.pyplot.scatter` returns a :class:`~matplotlib.collections.PathCollection`
+# that can similarly be modified by using the
+# `.collections.PathCollection.set_offsets` function.
 
 fig, ax = plt.subplots()
 rng = np.random.default_rng()
@@ -84,6 +116,10 @@ def update(frame):
 ###############################################################################
 # Animating :class:`~matplotlib.image.AxesImage`
 # ---------------------------------------------------
+#
+# When we plot an image using `.pyplot.imshow`, it returns an
+# :class:`~matplotlib.image.AxesImage` object. The data in this object can also
+# similarly be modified by using the `.image.AxesImage.set_data` method.
 
 fig, ax = plt.subplots()
 rng = np.random.default_rng()
@@ -97,16 +133,17 @@ def update(frame):
     return aximg,
 
 ani = animation.FuncAnimation(
-    fig=fig, func=update, frames=240, interval=200
+    fig=fig, func=update, frames=None, interval=200
 )
 plt.show()
 
 ###############################################################################
 # :class:`~matplotlib.animation.ArtistAnimation`
 # ----------------------------------------------
 #
-# :class:`~matplotlib.animation.ArtistAnimation` uses a list of artists to
-# iterate over and animate.
+# On the other hand, :class:`~matplotlib.animation.ArtistAnimation` can be used
+# to generate animations if we have data on various different artists. This
+# list of artists is then converted frame by frame into an animation.
 
 
 fig, ax = plt.subplots()
@@ -125,9 +162,40 @@ def update(frame):
 ani = animation.ArtistAnimation(fig=fig, artists=artists, repeat_delay=1000)
 plt.show()
 
+###############################################################################
+# :class:`~matplotlib.animation.FuncAnimation` is more efficient in terms of
+# speed and memory as it draws an artist once and then modifies it. On the
+# other hand :class:`~matplotlib.animation.ArtistAnimation` is flexible as it
+# allows any iterable of artists to be animated in a sequence.
+
 ###############################################################################
 # Animation Writers
-# -------------------------------------------
+# -----------------
+#
+# Animation objects can be saved to disk using various multimedia writers
+# (ex: Pillow, *ffpmeg*, *imagemagick*). Not all video formats are supported
+# by all writers. A list of supported formats for each writer can be found at
+# the end of this tutorial. There are 4 major types of writers:
+#
+# 1. :class:`~matplotlib.animation.PillowWriter` - Uses the Pillow library to
+# create the animation.
+#
+# 2. :class:`~matplotlib.animation.HTMLWriter` - Used to create JS-based
+# animations.
+#
+# 3. Pipe-based writers - :class:`~matplotlib.animation.FFMpegWriter` and
+# :class:`~matplotlib.animation.ImageMagickWriter` are pipe based writers.
+# These writers pipe each frame to the utility (*ffmpeg* / *imagemagick*) which
+# then stitches all of them together to create the animation.
+#
+# 4. File-based writers - :class:`~matplotlib.animation.FFMpegFileWriter` and
+# :class:`~matplotlib.animation.ImageMagickFileWriter` are examples of
+# file-based writers. These writers are slower than their standard writers but
+# are more useful for debugging as they save each frame in a file before
+# stitching them together into an animation.
+#
+# Below we see examples for how to use different writers with
+# `.animation.Animation.save`
 
 fig, ax = plt.subplots()
 ax.grid()
@@ -153,8 +221,6 @@ def update(frame):
 # ani.save(filename="/tmp/pillow_example.gif", writer="pillow")
 # ani.save(filename="/tmp/pillow_example.apng", writer="pillow")
 
-# Why does HTMLWriter documentation have a variable named
-# supported_formats = ['png', 'jpeg', 'tiff', 'svg']
 # ani.save(filename="/tmp/html_example.html", writer="html")
 # ani.save(filename="/tmp/html_example.htm", writer="html")
 # ani.save(filename="/tmp/html_example.png", writer="html")
@@ -167,3 +233,14 @@ def update(frame):
 
 # Imagemagick
 # ani.save(filename="/tmp/imagemagick_example.gif", writer="imagemagick")
+
+###############################################################################
+#
+# ================================================  =============================
+# Writer                                            Supported Formats
+# ================================================  =============================
+# :class:`~matplotlib.animation.PillowWriter`       .gif, .apng
+# :class:`~matplotlib.animation.HTMLWriter`         .htm, .html, .png
+# :class:`~matplotlib.animation.FFMpegWriter`       All formats supported by *ffmpeg*
+# :class:`~matplotlib.animation.ImageMagickWriter`  .gif
+# ================================================  =============================
