A Slightly Longer Introduction
==============================

This section will contain a short (but a bit longer than :ref:`quick-start`)
introduction to analyzing and plotting data with ``yt``, using a scripting
interface.  If you're not familiar with Python, you might be able to pick it up
from this section, but you'd probably be better off reading one of the many
other sources listed in :ref:`learn-python`.)

.. note:: If you know Python, you might enjoy reading :ref:`cookbook`!

Writing a Script
----------------

The very first step to using ``yt`` is to open up a text editor, write a little
script, and then run it.  You can use your favorite text editor (for instance,
`vim <http://www.vim.org/>`_) and then save it as something ending in ``.py``.
At the command line, you can execute this script by calling the name of the
python interpreter that you used to install ``yt`` and then the name of the
script:

.. code-block:: bash

   $ python2.6 my_script.py

This will load the interpreter, read and run the script ``my_script.py`` and
then terminate regardless of the success or failure of the script.

To have the python interpreter load, run, and then return an interactive
prompt, you can execute the script with

.. code-block:: bash

   $ python2.6 -i my_script.py

There's a bit more information about invocation of python in :ref:`debug-drive`.

Okay, so now we know how to launch a script, but what do we put in it?  Let's
start with one of the most simple things to do.  Let's load some data and find
the most dense point.  Here's a sample little script that loads our data,
prints the maximum density, and the location of that maximum density.

We first import ``yt`` -- the very first line in this sample script loads
``yt``, brings a bunch of variables, functions and classes into the local
namespace, and initializes a few settings.

The next line loads the parameter file into memory, and then we find the
maximum density.

.. code-block:: python

   from yt.mods import *
   pf = load("RedshiftOutput0010.dir/RedshiftOutput0010")
   value, position = pf.h.find_max("Density")

   print "Maximum density: %0.5e at %s" % (value, position)

The last line in that script is a format string which prints the value and the
position.  You can find a number of sample recipes in the :ref:`cookbook`.
Let's move on to making a script that makes some plots before terminating.

Plots and Plot Types
--------------------

The next step we might want to take is to visually inspect our data.  ``yt``
has a facility for creating several linked plots --
:class:`yt.raven.PlotCollection` handles adding multiple plots that are linked
by width and parameter files.  We can add a couple slices, along each axis and
then zoom in.  This is one of the most fundamental idioms in ``yt`` -- during my
thesis work, almost all of my scripts started out like this.

.. code-block:: python

   from yt.mods import *
   pf = load("DataDump0020.dir/DataDump0020")
   pc = PlotCollection(pf)

   pc.add_slice("Density", 0)
   pc.add_slice("Temperature", 0)

   pc.set_width(1000.0, 'au')

   pc.save()

This particular script will create a PlotCollection centered on the most dense
point (unless you feed in a center, it searches for and finds the most dense
point) add a Density slice, a Temperature slice, set the width to 1000.0 AU,
and then save the lot of them.

For more complicated examples, be sure to check out the :ref:`cookbook` and the
API for :class:`yt.raven.PlotCollection` as well as the :mod:`yt.raven`
documentation as a whole.

Plot Modification
-----------------

yt comes with a number of mechanisms of adding visual and textual information
to plots.  These include grid boundaries, scale boxes, vector fields, contour
fields and text annotations.  More documentation is available in
:ref:`callbacks`, with full API documentation in :mod:`yt.raven.Callbacks`.

The plot modifications all follow a uniform interface; the concept is that each
plot has a base plot, and on top of that a set of *callbacks* that are applied,
in order, to modify it and produce a final result.  To apply a new
modification, the ``modify`` dictionary of the plot is accessed, and from that
the appropriate modification keyword is selected.  Each of these accepts a set
of arguments.

For example, from start to finish, this command will output a slice through the
most dense point in the simulation, taken along the x axis, with the grid
boundaries drawn.

.. code-block:: python

   from yt.mods import *
   p = plots.get_slice("my_data0001", "Density", 0)
   p.modify["grids"]()
   p.save_image("my_data0001_Density")

To add on a contour of the field "Temperature", you can add on another
modification:

.. code-block:: python

   p.modify["contour"]("Temperature")
   p.save_image("my_data0001_Density_Temperature")

The plots returned by the class:`~yt.raven.PlotCollection` methods also
respect this interface, which means that you can also do things like:

.. code-block:: python

   from yt.mods import *
   pf = load("my_data0001")
   pc = PlotCollection(pf)
   for ax in range(3): pc.add_slice("Density", ax).modify["grids"]()
   pc.save("my_data0001")

Wrapped up into this snippet are the methods for adding slices along all three
axes and then instantly applying to them the grid boundary outlines.

A full list of the different possibilities for plot modifications is available
in :ref:`callbacks`.

Time Series Movies
------------------

.. note:: The :ref:`command-line-tool` can also do time series plots.  Here we
          showcase how to do them from a script so that more modifications can
          be made.

The process of constructing a time series movie involves, very simply,
constructing a set of plots over a set of parameter files.  By iterating over a
set of data files, or over a set of numbers, a series of plots can be output.
These can then be concatenated into a movie to show changes in features and
fields over time.

For example, the simplest possible time series movie script would be:

.. code-block:: python

   from yt.mods import *
   for i in range(1000):
      p = plots.get_slice("my_data%04i" % i, "Density", 0)
      p.save_image("my_data%04i" % i)

Because we are using the full API here, more complicated visualizations can be
built up.  For instance, with the addition of

.. code-block:: python

   p.set_width(10, 'kpc')
   p.set_zlim(1e-27, 1e-24)

the width of each image will be 10 kpc and the color limits will be set to
``1e-27`` and ``1e-24``.

Even More!
----------

There's quite a bit more that you can do with ``yt`` from a scripting
perspective -- not only can you use the modules that come with ``yt``, but you
can use all of the modules available for Python as a whole.  `SciPy
<http://www.scipy.org>`_ is a good starting point, and there are lots of fun
subpackages as well as other scientific plotting packages available.

If you find something cool that you find a neat way to apply to Adaptive Mesh
Refinement data, you should be sure to email :ref:`mailing-list` to tell us
about it!
