Chapter ‍12 Internal Data Visualization

• 12.1 GAMELAN
• 12.2 Histogram Display
• 12.3 Plot Display
• 12.4 Graphs
• 12.5 Drawing options

12.1 GAMELAN

The data values and tables that we have introduced in the previous section can be visualized using built-in features of WHIZARD. To be precise, WHIZARD can write L^AT_EX code which incorporates code in the graphics language GAMELAN to produce a pretty-printed account of observables, histograms, and plots.

GAMELAN is a macro package for MetaPost, which is part of the T_EX/L^AT_EX family. MetaPost, a derivative of Knuth’s MetaFont language for font design, is usually bundled with the T_EX distribution, but might need a separate switch for installation. The GAMELAN macros are contained in a subdirectory of the WHIZARD package. Upon installation, they will be installed in the appropriate directory, including the gamelan.sty driver for L^AT_EX. WHIZARD uses a subset of GAMELAN’s graphics macros directly, but it allows for access to the full package if desired.

An (incomplete) manual for GAMELAN can be found in the share/doc subdirectory of the WHIZARD system. WHIZARD itself uses a subset of the GAMELAN capabilities, interfaced by SINDARIN commands and parameters. They are described in this chapter.

To process analysis output beyond writing tables to file, the write_analysis command described in the previous section should be replaced by compile_analysis, with the same syntax:

compile_analysis (analysis-tags) { options }

where analysis-tags, a comma-separated list of analysis objects, is optional. If there are no tags, all analysis objects are processed. The options script of local commands is also optional, of course.

This command will perform the following actions:

1. It writes a data file in default format, as write_analysis would do. The file name is given by $out_file, if nonempty. The file must not be already open, since the command needs a self-contained file, but the name is otherwise arbitrary. If the value of $out_file is empty, the default file name is whizard_analysis.dat.
2. It writes a driver file for the chosen datasets, whose name is derived from the data file by replacing the file extension of the data file with the extension .tex. The driver file is a L^AT_EX source file which contains embedded GAMELAN code that handles the selected graphics data. In the L^AT_EX document, there is a separate section for each contained dataset. Furthermore, a process-/analysis-specific makefile with the name <process_name>_ana.makefile is created that can be used to generate postscript or PDF output from the L^AT_EX source. If the steering flag ?analysis_file_only is set to true, then the L^AT_EX file and the makefile are only written, but no execution of the makefile resulting in compilation of the L^AT_EX code (see the next item) is invoked.
3. As mentioned above, if the flag ?analysis_file_only is set to false (which is the default), the driver file is processed by L^AT_EX(invoked by calling the makefile with the name <process_name>_ana.makefile), which generates an appropriate GAMELAN source file with extension .mp. This code is executed (calling GAMELAN/MetaPost, and again L^AT_EX for typesetting embedded labels). There is a second L^AT_EX pass (automatically done by the makefile) which collects the results, and finally conversion to PostScript and PDF formats.

The resulting PostScript or PDF file – the file name is the name of the data file with the extension replaced by .ps or .pdf, respectively – can be printed or viewed with an appropriate viewer such as gv. The viewing command is not executed automatically by WHIZARD.

Note that L^AT_EX will write further files with extensions .log, .aux, and .dvi, and GAMELAN will produce auxiliary files with extensions .ltp and .mpx. The log file in particular, could overwrite WHIZARD’s log file if the basename is identical. Be careful to use a value for $out_file which is not likely to cause name clashes.

12.1.1 User-specific changes

In the case, that the SINDARIN compile_analysis command is invoked and the flag named ?analysis_file_only is not changed from its default value false, WHIZARD calls the process-/analysis-specific makefile triggering the compilation of the L^AT_EX code and the GAMELAN plots and histograms. If the user wants to edit the analysis output, for example changing captions, headlines, labels, properties of the plots, graphs and histograms using GAMELAN specials etc., this is possible and the output can be regenerated using the makefile. The user can also directly invoke the GAMELAN script, whizard-gml, that is installed in the binary directly along with the WHIZARD binary and other scripts. Note however, that the L^AT_EX environment for the specific style files have to be set by hand (the command line invocation in the makefile does this automatically). Those style files are generally written into share/texmf/whizard/ directory. The user can execute the commands in the same way as denoted in the process-/analysis-specific makefile by hand.

12.2 Histogram Display

12.3 Plot Display

12.4 Graphs

Graphs are an additional type of analysis object. In contrast to histograms and plots, they do not collect data directly, but they rather act as containers for graph elements, which are copies of existing histograms and plots. Their single purpose is to be displayed by the GAMELAN driver.

Graphs are declared by simple assignments such as

graph g1 = hist1
graph g2 = hist2 & hist3 & plot1

The first declaration copies a single histogram into the graph, the second one copies two histograms and a plot. The syntax for collecting analysis objects uses the & concatenation operator, analogous to string concatenation. In the assignment, the rhs must contain only histograms and plots. Further concatenating previously declared graphs is not supported.

After the graph has been declared, its contents can be written to file (write_analysis) or, usually, compiledd by the L^AT_EX/GAMELAN driver via the compile_analysis command.

The graph elements on the right-hand side of the graph assignment are copied with their current data content. This implies a well-defined order of statements: first, histograms and plots are declared, then they are filled via record commands or functions, and finally they can be collected for display by graph declarations.

A simple graph declaration without options as above is possible, but usually there are options which affect the graph display. There are two kinds of options: graph options and drawing options. Graph options apply to the graph as a whole (title, labels, etc.) and are placed in braces on the lhs of the assigment. Drawing options apply to the individual graph elements representing the contained histograms and plots, and are placed together with the graph element on the rhs of the assignment. Thus, the complete syntax for assigning multiple graph elements is

graph graph-tag { graph-options }
= graph-element-tag1 { drawing-options1 }
& graph-element-tag2 { drawing-options2 }
…

This form is recommended, but graph and drawing options can also be set as global parameters, as usual.

We list the supported graph and drawing options in Tables ‍12.1 and 12.2, respectively.

---

Table 12.1: Graph options. The content of strings of type LATEX must be valid LATEX code (containing typesetting commands such as math mode). The content of strings of type GAMELAN must be valid GAMELAN code. If a graph bound is kept undefined, the actual graph bound is determined such as not to crop the graph contents in the selected direction.

Variable	Default	Type	Meaning
$title	""	LATEX	Title of the graph = subsection headline
$description	""	LATEX	Description text for the graph
$x_label	""	LATEX	x-axis label
$y_label	""	LATEX	y-axis label
graph_width_mm	130	Integer	graph width (on paper) in mm
graph_height_mm	90	Integer	graph height (on paper) in mm
?x_log	false	Logical	Whether the x-axis scale is linear or logarithmic
?y_log	false	Logical	Whether the y-axis scale is linear or logarithmic
x_min	undefined	Real	Lower bound for the x axis
x_max	undefined	Real	Upper bound for the x axis
y_min	undefined	Real	Lower bound for the y axis
y_max	undefined	Real	Upper bound for the y axis
gmlcode_bg	""	GAMELAN	Code to be executed before drawing
gmlcode_fg	""	GAMELAN	Code to be executed after drawing

---

---

Table 12.2: Drawing options. The content of strings of type GAMELAN must be valid GAMELAN code. The behavior w.r.t. the flags with undefined default value depends on the type of graph element. Histograms: draw baseline, piecewise, fill area, draw curve, no errors, no symbols; Plots: no baseline, no fill, draw curve, no errors, no symbols.

Variable	Default	Type	Meaning
?draw_base	undefined	Logical	Whether to draw a baseline for the curve
?draw_piecewise	undefined	Logical	Whether to draw bins separately (histogram)
?fill_curve	undefined	Logical	Whether to fill area between baseline and curve
$fill_options	""	GAMELAN	Options for filling the area
?draw_curve	undefined	Logical	Whether to draw the curve as a line
$draw_options	""	GAMELAN	Options for drawing the line
?draw_errors	undefined	Logical	Whether to draw error bars for data points
$err_options	""	GAMELAN	Options for drawing the error bars
?draw_symbols	undefined	Logical	Whether to draw symbols at data points
$symbol	Black dot	GAMELAN	Symbol to be drawn
gmlcode_bg	""	GAMELAN	Code to be executed before drawing
gmlcode_fg	""	GAMELAN	Code to be executed after drawing

---

12.5 Drawing options

The options for coloring lines, filling curves, or choosing line styles make use of macros in the GAMELAN language. At this place, we do not intend to give a full account of the possiblities, but we rather list a few basic features that are likely to be useful for drawing graphs.

Colors

GAMELAN knows about basic colors identified by name:

More generically, colors in GAMELAN are RGB triplets of numbers (actually, numeric expressions) with values between 0 and 1, enclosed in brackets:

To draw an object in color, one should apply the construct withcolor color to its drawing code. The default color is always black. Thus, this will make a plot drawn in blue:

$draw_options = "withcolor blue"

and this will fill the drawing area of some histogram with an RGB color:

$fill_options = "withcolor (0.8, 0.7, 1)"

Dashes

By default, lines are drawn continuously. Optionally, they can be drawn using a dash pattern. Predefined dash patterns are

Going beyond the predefined patterns, a generic dash pattern has the syntax

with an arbitrary repetition of on and off clauses. The numbers l1, l2, … are lengths measured in pt.

To apply a dash pattern, the option syntax dashed dash-pattern should be used. Options strings can be concatenated. Here is how to draw in color with dashes:

$draw_options = "withcolor red dashed evenly"

and this draws error bars consisting of intermittent dashes and dots:

$err_options = "dashed (withdashdots scaled 0.5)"

The extra brackets ensure that the scale factor 1/2 is applied only the dash pattern.

Hatching

Areas (e.g., below a histogram) can be filled with plain colors by the withcolor option. They can also be hatched by stripes, optionally rotated by some angle. The syntax is completely analogous to dashes. There are two predefined hatch patterns:

and a generic hatch pattern is written

where the numbers l1, l2, … determine the widths of the stripes, measured in pt.

When applying a hatch pattern, the pattern may be rotated by some angle (in degrees) and scaled. This looks like

$fill_options = "hatched (withstripes scaled 0.8 rotated 60)"

Smooth curves

Plot points are normally connected by straight lines. If data are acquired by statistical methods, such as Monte Carlo integration, this is usually recommended. However, if a plot is generated using an analytic mathematical formula, or with sufficient statistics to remove fluctuations, it might be appealing to connect lines by some smooth interpolation. GAMELAN can switch on spline interpolation by the specific drawing option linked smoothly. Note that the results can be surprising if the data points do have sizable fluctuations or sharp kinks.

Error bars

Plots and histograms can be drawn with error bars. For histograms, only vertical error bars are supported, while plot points can have error bars in x and y direction. Error bars are switched on by the ?draw_errors flag.

There is an option to draw error bars with ticks: withticks and an alternative option to draw arrow heads: witharrows. These can be used in the $err_options string.

Symbols

To draw symbols at plot points (or histogram midpoints), the flag ?draw_symbols has to be switched on.