.. _callbacks:

Plot Modification Mechanisms
============================

Because the plots in ``yt`` are considered to be "volatile" -- existing
independent of the canvas on which they are plotted -- before they are saved,
you can have a set of "callbacks" run that modify them before saving to disk.
By adding a callback, you are telling the plot that whatever it does it itself,
your callback gets the last word.

These can all be accessed through a registry attached to every plot object.
When you add a plot to a :class:`yt.raven.PlotCollection`, you get back that
affiliated plot object.  By accessing ``modify`` on that plot object, you have
access to the available callbacks.  For instance,

.. code-block:: python

   p = PlotCollection.add_slice("Density", 0)
   p.modify["velocity"]()

would add the :func:`velocity` callback to the plot object.  When you save the
plot, the list of callbacks will be iterated over, and the velocity callback
will be handed the current state of the plot.  It will then be able to
dynamically modify the plot before saving -- in this case, adding on velocity
vectors atop the image.

Available Callbacks
-------------------

These are the callbacks available through the ``modify[]`` mechanism.  The
underlying functions are documented (largely identical to this) in
:ref:`callback-api`.

.. include:: _cb_docstrings.inc


