(sec:run-aspect:visualize:stat-data)=
# Visualizing statistical data
In addition to the graphical output discussed above,
ASPECT produces a statistics file that collects
information produced during each time step. For the remainder of this section,
let us assume that we have run ASPECT with the
input file discussed in {ref}`sec:cookbooks:convection-box`, simulating convection in a
box. After running ASPECT, you will find a file
called `statistics` in the output directory that, at the time of writing this,
looked like this:
``` ksh
# 1: Time step number
# 2: Time (seconds)
# 3: Number of mesh cells
# 4: Number of Stokes degrees of freedom
# 5: Number of temperature degrees of freedom
# 6: Iterations for temperature solver
# 7: Iterations for Stokes solver
# 8: Velocity iterations in Stokes preconditioner
# 9: Schur complement iterations in Stokes preconditioner
# 10: Time step size (seconds)
# 11: RMS velocity (m/s)
# 12: Max. velocity (m/s)
# 13: Minimal temperature (K)
# 14: Average temperature (K)
# 15: Maximal temperature (K)
# 16: Average nondimensional temperature (K)
# 17: Outward heat flux through boundary with indicator 0 ("left") (W)
# 18: Outward heat flux through boundary with indicator 1 ("right") (W)
# 19: Outward heat flux through boundary with indicator 2 ("bottom") (W)
# 20: Outward heat flux through boundary with indicator 3 ("top") (W)
# 21: Visualization file name
0 0.0000e+00 256 2467 1089 0 29 30 29 1.2268e-02 1.79026783e+00 2.54322608e+00
1 1.2268e-02 256 2467 1089 32 29 30 30 3.7388e-03 5.89844152e+00 8.35160076e+00
2 1.6007e-02 256 2467 1089 20 28 29 29 2.0239e-03 1.09071922e+01 1.54298908e+01
3 1.8031e-02 256 2467 1089 15 27 28 28 1.3644e-03 1.61759153e+01 2.28931189e+01
4 1.9395e-02 256 2467 1089 13 26 27 27 1.0284e-03 2.14465789e+01 3.03731397e+01
5 2.0424e-02 256 2467 1089 11 25 26 26 8.2812e-04 2.66110761e+01 3.77180480e+01
```
In other words, it first lists what the individual columns mean with a hash
mark at the beginning of the line and then has one line for each time step in
which the individual columns list what has been explained above.[^footnote1]
This file is easy to visualize. For example, one can import it as a whitespace
separated file into a spreadsheet such as Microsoft Excel or
OpenOffice/LibreOffice Calc and then generate graphs of one column against
another. Or, maybe simpler, there is a multitude of simple graphing programs
that do not need the overhead of a full fledged spreadsheet engine and simply
plot graphs. One that is particularly simple to use and available on every
major platform is `Gnuplot`. It is extensively documented at
.
`Gnuplot` is a command line program in which you enter commands that plot data
or modify the way data is plotted. When you call it, you will first get a
screen that looks like this:
```
/home/user/aspect/output gnuplot
G N U P L O T
Version 4.6 patchlevel 0 last modified 2012-03-04
Build System: Linux x86_64
Copyright (C) 1986-1993, 1998, 2004, 2007-2012
Thomas Williams, Colin Kelley and many others
gnuplot home: http://www.gnuplot.info
faq, bugs, etc: type "help FAQ"
immediate help: type "help" (plot window: hit 'h')
Terminal type set to 'qt'
gnuplot>
```
At the prompt on the last line, you can then enter commands. Given the
description of the individual columns given above, let us first try to plot
the heat flux through boundary 2 (the bottom boundary of the box), i.e.,
column 19, as a function of time (column 2). This can be achieved using the
following command:
``` gnuplot
plot "statistics" using 2:19
```
The left panel of {numref}`fig:viz-gnuplot` shows what `Gnuplot` will display in its
output window. There are many things one can configure in these plots (see the
`Gnuplot` manual referenced above). For example, let us assume that we want to
add labels to the $x$- and $y$-axes, use not just points but lines and points
for the curves, restrict the time axis to the range $[0,0.2]$ and the heat
flux axis to $[-10:10]$, plot not only the flux through the bottom but also
through the top boundary (column 20) and finally add a key to the figure, then
the following commands achieve this:
``` gnuplot
set xlabel "Time"
set ylabel "Heat flux"
set style data linespoints
plot [0:0.2][-10:10] "statistics" using 2:19 title "Bottom boundary", \
"statistics" using 2:20 title "Top boundary"
```
If a line gets too long, you can continue it by ending it in a backslash as
above. This is rarely used on the command line but useful when writing the
commands above into a script file, see below. We have done it here to get the
entire command into the width of the page.
```{figure-md} fig:viz-gnuplot
Visualizing the statistics file obtained from the example in {ref}`sec:cookbooks:convection-box` using Gnuplot: Output using simple commands.
```
For those who are lazy, `Gnuplot` allows to abbreviate things in many
different ways. For example, one can abbreviate most commands. Furthermore,
one does not need to repeat the name of an input file if it is the same as the
previous one in a plot command. Thus, instead of the commands above, the
following abbreviated form would have achieved the same effect:
``` gnuplot
se xl "Time"
se yl "Heat flux"
se sty da lp
pl [:0.2][-10:10] "statistics" us 2:19 t "Bottom boundary", "" us 2:20 t "Top boundary"
```
This is of course unreadable at first but becomes useful once you become more
familiar with the commands offered by this program.
Once you have gotten the commands that create the plot you want right, you
probably want to save it into a file. `Gnuplot` can write output in many
different formats. For inclusion in publications, either `eps` or `png` are
the most common. In the latter case, the commands to achieve this are
``` gnuplot
set terminal png
set output "heatflux.png"
replot
```
The last command will simply generate the same plot again but this time into
the given file. The result is a graphics file similar to the one shown in
{numref}`fig:convection-box-stats`.
:::{note}
After setting output to a file, *all* following plot commands will want to write to this file.
Thus, if you want to create more plots after the one just created, you need to reset output back to
the screen. On Linux, this is done using the command `set terminal X11`. You can then continue
experimenting with plots and when you have the next plot ready, switch back to output to a file.
:::
What makes `Gnuplot` so useful is that it doesn't just allow entering
all these commands at the prompt. Rather, one can write them all into a file,
say `plot-heatflux.gnuplot`, and then, on the command line, call
``` ksh
gnuplot plot-heatflux.gnuplot
```
to generate the `heatflux.png` file. This comes in handy if one wants to
create the same plot for multiple simulations while playing with parameters of
the physical setup. It is also a very useful tool if one wants to generate the
same kind of plot again later with a different data set, for example when a
reviewer requested additional computations to be made for a paper or if one
realizes that one has forgotten or misspelled an axis label in a plot.[^footnote2]
`Gnuplot` has many many more features we have not even touched upon. For
example, it is equally happy to produce three-dimensional graphics, and it
also has statistics modules that can do things like curve fits, statistical
regression, and many more operations on the data you provide in the columns of
an input file. We will not try to cover them here but instead refer to the
manual at . You can also get a good amount of
information by typing `help` at the prompt, or a command like `help plot` to
get help on the `plot` command.
[^footnote1]: With input files that ask for initial adaptive refinement, the first time step may appear twice because we solve on a mesh that
is globally refined and we then start the entire computation over again on a once adaptively refined mesh (see the parameters
in {ref}`parameters:Mesh_20refinement` for how to do that).
[^footnote2]: In my own work, I usually save the ASPECT input file, the statistics output file and the Gnuplot script along with the
actual figure I want to include in a paper. This way, it is easy to either re-run an entire simulation, or just tweak the graphic
at a later time. Speaking from experience, you will not believe how often one wants to tweak a figure long after it was first
created. In such situations it is outstandingly helpful if one still has both the actual data as well as the script that generated
the graphic.