[yt-svn] commit/yt-doc: 2 new changesets
Bitbucket
commits-noreply at bitbucket.org
Thu Jul 26 11:44:20 PDT 2012
2 new commits in yt-doc:
https://bitbucket.org/yt_analysis/yt-doc/changeset/0d86e414a8bf/
changeset: 0d86e414a8bf
user: ngoldbaum
date: 2012-07-26 20:38:11
summary: Updating the making plots section of the orientation.
affected #: 1 file
diff -r 05087e70403d73a4f71ee34278c1d4418d9f5da9 -r 0d86e414a8bfbd869d802919c6bd14f81bdcb881 source/orientation/making_plots.rst
--- a/source/orientation/making_plots.rst
+++ b/source/orientation/making_plots.rst
@@ -1,18 +1,141 @@
Making Plots
------------
-Examining data by hand and looking at individual quantities one at a time can
-be interesting and productive, but yt also provides a set of visualization
-tools that you can use. One of the fundamental implementations of this is the
-``PlotCollection``, an object designed to enable you to make several related
-plots all at once. Originally, the idea was that yt would get used to make
-multiple plots of different fields, along different axes, all centered at the
-same point. This has somewhat faded with time, but it still functions as a
-convenient way to set up a bunch of plots with only one or two commands.
+Slices
+^^^^^^
+
+Examining data by hand and looking at individual quantities one at a time can be
+interesting and productive, but yt also provides a set of visualization tools
+that you can use. We'll start by showing you how to make visualizations of
+slices and projections through your data. We will then move on to demonstrate
+how to make analysis plots, including phase diagrams and profiles.
+
+The quickest way to plot a slice of a field through you data is to use
+:class:`~yt.visualization.plot_window.SlicePlot`. Say we want to visualize a
+slice through the Density field along the z-axis centered on the center of the
+simulation box in a simulation dataset we've opened and stored in the parameter
+file object ``pf``. This can be accomplished with the following command:
+
+.. clode-block:: python
+
+ >>> slc = SlicePlot(pf, 'z', 'Density')
+ >>> slc.save()
+
+These two commands will create a slice object and store it in a variable we've
+called ``slc``. We then call the ``save()`` function that is associated with
+the slice object. This automatically saves the plot in png image format with an
+automatically generated filename. If you don't want the slice object to stick
+around, you can accomplish the same thing in one line:
+
+.. clode-block:: python
+
+ >>> SlicePlot(pf, 'z', 'Density').save()
+
+It's nice to keep the slice object around if you want to modify the plot. By
+default, the plot width will be set to the size of the simulation box. To zoom
+in by a factor of ten, you can call the zoom function attached to the slice
+object:
+
+.. code-block:: python
+
+ >>> slc = SlicePlot(pf, 'z', 'Density')
+ >>> slc.zoom(10)
+ >>> slc.save('zoom')
+
+This will save a new plot to disk with a different filename - prepended with
+'zoom' instead of the name of the parmaeter file. If you want to set the width
+manually, you can do that as well. For example, the following sequence of
+commands will create a slice, set the width of the plot to 10 kiloparsecs, and
+save it to disk.
+
+.. code-block:: python
+
+ >>> slc = SlicePlot(pf, 'z', 'Density')
+ >>> slc.set_width((10,'kpc'))
+ >>> slc.save('10kpc')
+
+The SlicePlot also optionally accepts the coordinate to center the plot on and
+the width of the plot:
+
+.. code-block:: python
+
+ >>> SlicePlot(pf, 'z', 'Density', center=[0.2, 0.3, 0.8], width = (10,'kpc)).save()
+
+The center must be given in code units. Optionally, you can supply 'c' or 'm'
+for the center. These two options will center the plot on the center of the
+simulation box and the coordinate of the maximum density cell, respectively.
+
+One can also use the SlicePlot to make annotated plots. The following commands
+will create a slice, annotate it by marking the grid boundaries, and save the
+plot to disk:
+
+.. code-block:: python
+
+ >>> SlicePlot(pf, 'z', 'Density')
+ >>> SlicePlot.annotate_grids()
+ >>> SlicePlot.save()
+
+There are a number of annotations available. The rest of the annotations are
+described in :ref:`callbacks`.
+
+Projectiions
+^^^^^^^^^^^^
+
+It can be limiting to only look at slices through 3D data. In most cases, Doing
+so discards the vast majority of the data. For this reason, yt provides a
+simple interface for generating plot of projections through your data. The
+interface for making projection plots,
+:class:`~yt.visualization.plot_window.ProjectionPlot` is very similar to
+``SlicePlot``, described above. To create and save a plot of the projection of
+the density field through the z-axis of a dataset, centered on the center of the
+simulation box, do the following:
+
+.. code-block:: python
+
+ >>> ProjectionPlot(pf, 'z' 'Density).save()
+
+A ``ProjectionPlot`` can be modified and created in exactly the same keyword
+arguments as s ``SlicePlot``. For example, one can also adjust the width of
+the plot, either after creating the projection plot:
+
+.. clode-block:: python
+
+ >>> prj = ProjectionPlot(pf, 'z', 'Density')
+ >>> prj.set_width((10,'kpc'))
+
+or while creating the projection in the first place:
+
+.. clode-block:: python
+
+ >>> ProjectionPlot(pf, 'z', 'Density', width=(10,'kpc'))
+
+In addition, one can optionally supply a maximum level to project to, this is
+very useful for large datasets where projections can be costly:
+
+.. code-block:: python
+
+ >>> ProjectionPlot(pf, 'z', 'Density', max_level=10)
+
+as well as a field to weight the projection by. The following example creates a
+map of the density-weighted mean temperature, projected along the z-axis:
+
+.. code-block:: python
+
+ >>> ProjectionPlot(pf, 'z', 'Temperature', weight_field='Density')
+
+PlotCollection
+^^^^^^^^^^^^^^
+
+To create profiles, yt supplies the ``PlotCollection``, an object designed to
+enable you to make several related plots all at once. Originally, the idea was
+that yt would get used to make multiple plots of different fields, along
+different axes, all centered at the same point. This has somewhat faded with
+time, but it still functions as a convenient way to set up a bunch of plots with
+only one or two commands.
A plot collection is really defined by two things: the simulation output it
will make plots from, and the "center" of the plot collection. By default, the
-center is the place where all slices and phase plots are centered, although
+center is the place where all phase plots are centered, although
there is some leeway on this. We start by creating our plot collection. The
plot collection takes two arguments: the first is the parameter file (``pf``)
we associate the plot collection with, and the second is our center. Note that
@@ -25,32 +148,15 @@
We've chosen to center at [0.5, 0.5, 0.5], which for this simulation is the
center of the domain. We can now add a number of different types of
-visualizations to this plot, but we'll only look at a few. The first is a
-projection, which we talked about earlier. yt regards axes as integers: 0 for
-x, 1 for y, 2 for z. So we add a projection of Density along the x-axis with
-this command:
+visualizations to this plot collection, but we'll only look at a few.
- >>> p = pc.add_projection("Density", 0)
+Phase Plots
+^^^^^^^^^^^
-yt will then create the projection and hang the resultant plot onto the
-``PlotCollection``. It also returns the plot object when it's done, which we
-then assign to the variable ``p``. Plot objects are mostly useful if you want
-to do advanced things to the plot -- like overplotting grids, contours,
-vectors, or modifying the underlying visualization in some non-trivial way.
-Many modifications can be applied in simpler ways, but some complex
-modifications require the plot object (``p`` in this case) itself.
-
-We'll now add a slice of "x-velocity" to the plot collection. This should let
-us see how our spheres are moving. (But, since we centered in a relatively
-uninteresting section of the data, it won't look like too much!)
-
- >>> pc.add_slice("x-velocity", 0)
-
-We don't retain the plot object, in this case, but we could! Now, for our
-final trick, we'll create a phase plot. Phase plots are pretty cool -- they
-take all the data inside a data container and they bin it with respect to two
-variables. You can then have it calculate the average, or the sum, of some
-other quantity as a function of those two variables.
+Phase plots are pretty cool -- they take all the data inside a data container
+and they bin it with respect to two variables. You can then have it calculate
+the average, or the sum, of some other quantity as a function of those two
+variables.
This allows, for instance, the calculation of the average Temperature as a
function of Density and velocity. Or, it allows the distribution of all the
@@ -96,24 +202,7 @@
plot is saved out with that prefix. Each plot's name is calculated from a
combination of the type of plot and the fields in that plot. For plots where
many duplicates can be included, a counter is included too -- for instance,
-phase and profile plots. Note that the field of view is not included in the
-filename, which means that you will have to include that yourself.
-
-The default field of view for slices and projections is the entire domain. We
-can change that by calling ``set_width`` and specifying a value and a unit.
-Most astrophysical units are available, but two special units are also
-available: "unitary" and "1". "unitary" units are scaled to the domain width;
-so 0.5 in "unitary" would occupy half the domain. "1" means in the native
-units of the simulation code. (For enzo, "unitary" and "1" are usually but not
-always the same.) We'll set the width to half the domain size and save again::
-
- >>> pc.set_width(0.5, 'unitary')
- >>> pc.save("second_images")
-
-Note that the phase plots didn't change at all -- only the image plots. This
-is by design, to keep the code from grinding too much on the disk. yt assumes
-that when you create a phase plot, you already know what you are aiming to do,
-and it doesn't second guess that.
+phase and profile plots.
All of these commands can be run from a script -- which, in fact, is the way
that I would personally encourage. It will make it easier to produce plots
https://bitbucket.org/yt_analysis/yt-doc/changeset/0644cd32f51f/
changeset: 0644cd32f51f
user: MatthewTurk
date: 2012-07-26 20:44:20
summary: Merged in ngoldbaum/yt-doc (pull request #44)
affected #: 1 file
diff -r 538a7a4f9aec1db111ac36389371aa262016068e -r 0644cd32f51fc3bf0b343bc6a22d067ccb0133d5 source/orientation/making_plots.rst
--- a/source/orientation/making_plots.rst
+++ b/source/orientation/making_plots.rst
@@ -1,18 +1,141 @@
Making Plots
------------
-Examining data by hand and looking at individual quantities one at a time can
-be interesting and productive, but yt also provides a set of visualization
-tools that you can use. One of the fundamental implementations of this is the
-``PlotCollection``, an object designed to enable you to make several related
-plots all at once. Originally, the idea was that yt would get used to make
-multiple plots of different fields, along different axes, all centered at the
-same point. This has somewhat faded with time, but it still functions as a
-convenient way to set up a bunch of plots with only one or two commands.
+Slices
+^^^^^^
+
+Examining data by hand and looking at individual quantities one at a time can be
+interesting and productive, but yt also provides a set of visualization tools
+that you can use. We'll start by showing you how to make visualizations of
+slices and projections through your data. We will then move on to demonstrate
+how to make analysis plots, including phase diagrams and profiles.
+
+The quickest way to plot a slice of a field through you data is to use
+:class:`~yt.visualization.plot_window.SlicePlot`. Say we want to visualize a
+slice through the Density field along the z-axis centered on the center of the
+simulation box in a simulation dataset we've opened and stored in the parameter
+file object ``pf``. This can be accomplished with the following command:
+
+.. clode-block:: python
+
+ >>> slc = SlicePlot(pf, 'z', 'Density')
+ >>> slc.save()
+
+These two commands will create a slice object and store it in a variable we've
+called ``slc``. We then call the ``save()`` function that is associated with
+the slice object. This automatically saves the plot in png image format with an
+automatically generated filename. If you don't want the slice object to stick
+around, you can accomplish the same thing in one line:
+
+.. clode-block:: python
+
+ >>> SlicePlot(pf, 'z', 'Density').save()
+
+It's nice to keep the slice object around if you want to modify the plot. By
+default, the plot width will be set to the size of the simulation box. To zoom
+in by a factor of ten, you can call the zoom function attached to the slice
+object:
+
+.. code-block:: python
+
+ >>> slc = SlicePlot(pf, 'z', 'Density')
+ >>> slc.zoom(10)
+ >>> slc.save('zoom')
+
+This will save a new plot to disk with a different filename - prepended with
+'zoom' instead of the name of the parmaeter file. If you want to set the width
+manually, you can do that as well. For example, the following sequence of
+commands will create a slice, set the width of the plot to 10 kiloparsecs, and
+save it to disk.
+
+.. code-block:: python
+
+ >>> slc = SlicePlot(pf, 'z', 'Density')
+ >>> slc.set_width((10,'kpc'))
+ >>> slc.save('10kpc')
+
+The SlicePlot also optionally accepts the coordinate to center the plot on and
+the width of the plot:
+
+.. code-block:: python
+
+ >>> SlicePlot(pf, 'z', 'Density', center=[0.2, 0.3, 0.8], width = (10,'kpc)).save()
+
+The center must be given in code units. Optionally, you can supply 'c' or 'm'
+for the center. These two options will center the plot on the center of the
+simulation box and the coordinate of the maximum density cell, respectively.
+
+One can also use the SlicePlot to make annotated plots. The following commands
+will create a slice, annotate it by marking the grid boundaries, and save the
+plot to disk:
+
+.. code-block:: python
+
+ >>> SlicePlot(pf, 'z', 'Density')
+ >>> SlicePlot.annotate_grids()
+ >>> SlicePlot.save()
+
+There are a number of annotations available. The rest of the annotations are
+described in :ref:`callbacks`.
+
+Projectiions
+^^^^^^^^^^^^
+
+It can be limiting to only look at slices through 3D data. In most cases, Doing
+so discards the vast majority of the data. For this reason, yt provides a
+simple interface for generating plot of projections through your data. The
+interface for making projection plots,
+:class:`~yt.visualization.plot_window.ProjectionPlot` is very similar to
+``SlicePlot``, described above. To create and save a plot of the projection of
+the density field through the z-axis of a dataset, centered on the center of the
+simulation box, do the following:
+
+.. code-block:: python
+
+ >>> ProjectionPlot(pf, 'z' 'Density).save()
+
+A ``ProjectionPlot`` can be modified and created in exactly the same keyword
+arguments as s ``SlicePlot``. For example, one can also adjust the width of
+the plot, either after creating the projection plot:
+
+.. clode-block:: python
+
+ >>> prj = ProjectionPlot(pf, 'z', 'Density')
+ >>> prj.set_width((10,'kpc'))
+
+or while creating the projection in the first place:
+
+.. clode-block:: python
+
+ >>> ProjectionPlot(pf, 'z', 'Density', width=(10,'kpc'))
+
+In addition, one can optionally supply a maximum level to project to, this is
+very useful for large datasets where projections can be costly:
+
+.. code-block:: python
+
+ >>> ProjectionPlot(pf, 'z', 'Density', max_level=10)
+
+as well as a field to weight the projection by. The following example creates a
+map of the density-weighted mean temperature, projected along the z-axis:
+
+.. code-block:: python
+
+ >>> ProjectionPlot(pf, 'z', 'Temperature', weight_field='Density')
+
+PlotCollection
+^^^^^^^^^^^^^^
+
+To create profiles, yt supplies the ``PlotCollection``, an object designed to
+enable you to make several related plots all at once. Originally, the idea was
+that yt would get used to make multiple plots of different fields, along
+different axes, all centered at the same point. This has somewhat faded with
+time, but it still functions as a convenient way to set up a bunch of plots with
+only one or two commands.
A plot collection is really defined by two things: the simulation output it
will make plots from, and the "center" of the plot collection. By default, the
-center is the place where all slices and phase plots are centered, although
+center is the place where all phase plots are centered, although
there is some leeway on this. We start by creating our plot collection. The
plot collection takes two arguments: the first is the parameter file (``pf``)
we associate the plot collection with, and the second is our center. Note that
@@ -25,32 +148,15 @@
We've chosen to center at [0.5, 0.5, 0.5], which for this simulation is the
center of the domain. We can now add a number of different types of
-visualizations to this plot, but we'll only look at a few. The first is a
-projection, which we talked about earlier. yt regards axes as integers: 0 for
-x, 1 for y, 2 for z. So we add a projection of Density along the x-axis with
-this command:
+visualizations to this plot collection, but we'll only look at a few.
- >>> p = pc.add_projection("Density", 0)
+Phase Plots
+^^^^^^^^^^^
-yt will then create the projection and hang the resultant plot onto the
-``PlotCollection``. It also returns the plot object when it's done, which we
-then assign to the variable ``p``. Plot objects are mostly useful if you want
-to do advanced things to the plot -- like overplotting grids, contours,
-vectors, or modifying the underlying visualization in some non-trivial way.
-Many modifications can be applied in simpler ways, but some complex
-modifications require the plot object (``p`` in this case) itself.
-
-We'll now add a slice of "x-velocity" to the plot collection. This should let
-us see how our spheres are moving. (But, since we centered in a relatively
-uninteresting section of the data, it won't look like too much!)
-
- >>> pc.add_slice("x-velocity", 0)
-
-We don't retain the plot object, in this case, but we could! Now, for our
-final trick, we'll create a phase plot. Phase plots are pretty cool -- they
-take all the data inside a data container and they bin it with respect to two
-variables. You can then have it calculate the average, or the sum, of some
-other quantity as a function of those two variables.
+Phase plots are pretty cool -- they take all the data inside a data container
+and they bin it with respect to two variables. You can then have it calculate
+the average, or the sum, of some other quantity as a function of those two
+variables.
This allows, for instance, the calculation of the average Temperature as a
function of Density and velocity. Or, it allows the distribution of all the
@@ -96,24 +202,7 @@
plot is saved out with that prefix. Each plot's name is calculated from a
combination of the type of plot and the fields in that plot. For plots where
many duplicates can be included, a counter is included too -- for instance,
-phase and profile plots. Note that the field of view is not included in the
-filename, which means that you will have to include that yourself.
-
-The default field of view for slices and projections is the entire domain. We
-can change that by calling ``set_width`` and specifying a value and a unit.
-Most astrophysical units are available, but two special units are also
-available: "unitary" and "1". "unitary" units are scaled to the domain width;
-so 0.5 in "unitary" would occupy half the domain. "1" means in the native
-units of the simulation code. (For enzo, "unitary" and "1" are usually but not
-always the same.) We'll set the width to half the domain size and save again::
-
- >>> pc.set_width(0.5, 'unitary')
- >>> pc.save("second_images")
-
-Note that the phase plots didn't change at all -- only the image plots. This
-is by design, to keep the code from grinding too much on the disk. yt assumes
-that when you create a phase plot, you already know what you are aiming to do,
-and it doesn't second guess that.
+phase and profile plots.
All of these commands can be run from a script -- which, in fact, is the way
that I would personally encourage. It will make it easier to produce plots
Repository URL: https://bitbucket.org/yt_analysis/yt-doc/
--
This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.
More information about the yt-svn
mailing list