Nuclear Data Viewer Tutorial

The Nuclear Data Viewer gives you access to both experimental and evaluated data, and it allows you to make a wide variety of plots and overplots. You can even plot differences and ratios between curves, or input your own data to be compared with the numbers from our data base. Perspective 3-D plots of distributions can be made for a number of data types.

The Viewer has a fairly clear visual interface and extensive online help pages. It is usually possible to figure out how to use it by experimenting around. However, the following instructions may help to shorten the learning curve somewhat, or to suggest options and possibilities that may not occur to you.

Getting To The Desired Data

The Nuclear Data Viewer gets around the "stateless" property of HTML by accessing the nuclear data base in several steps. First, you must choose a "Type." You will first see a selection box containing the word "select" after Type. When you click on the arrow at the right of the word "select," you will get a menu of the various data types available for the Viewer; for example, ACE, ADL-3T, CSISRS, ENDF-neutron, etc. Click on the desired data type to set its value in the box, and then click on "Continue" to go on to the next step. If you need to know more about the various types before choosing, click on the underlined word "Type" to get a help page.

With the data type chosen, the Viewer will go to the data base for that type and see what elements are available for that type. You will see a selection box after the word "Elem" containing the word "select." As before, click on the arrow to the right of "select" to bring up a scrolling list of all the elements available, for example, Al, Am, B, Be, etc. Click on the desired element, and then click on "Continue" to go on to the next step.

With the element chosen, the Viewer will go to the data base for that element and see what isotopes are available. You will see a selection box after "Iso" containing the word "select." As usual, click on the down arrow to get a scrolling list of all the materials available for this element. The list may include isotopes, isomers of isotopes, an elemental evaluation ("nat"), or various versions of the above distinguished by suffixes or special names. As an example, the list for ACE aluminum includes 27, 27.50, 27.f1, and 27c. The first is the ordinary ENDF/B-VI ACE file, the second is the ENDF/B-V ACE file vintage 1980, the third is the FENDL-1 version (from Japan), and the last is the newer ENDF/B-VI data from Release 3. Click on the desired "Iso" and on "Continue" to go on.

Finally, you will get a scrolling list of all the reactions or experimental data sets available for plotting from the Type, Elem, and Iso that you selected. The lines of the list start with the ENDF MF and MT numbers for the reaction, or with the CSISRS accession numbers, which you can ignore if you are not an expert. After the first vertical bar, you will find a plain-text name for the reaction or experimental data set. After the second vertical bar, you will find the energy range for this reaction. For experimental data, the number of data points available is also given. Click on the reaction or data set that you want to plot. You can also make multiple choices at this point using whatever method is supported by your browser. For some browsers, simple clicks will select or deselect single choices. Sometimes, you can wipe across contiguous choice with the mouse. Or you can use CTRL with the left mouse button to make multiple noncontiguous selections. This allows you to make overplots of different reactions or to plot points from several different experiments.

Before clicking on "Continue," check the status of "Add Curve." If it is "No," the Viewer will begin to prepare to make the graph. If it is "Yes," the Viewer will go back to the beginning of the selection process and allow you to choose a Type, Elem, Iso, and Data for another curve. This is another way that the viewer allows you to make overplots of different theoretical curves and experimental data sets.

Setting Up the Graph

Once the data selection process has been finished, you will get a new form to use in setting up the graph pages. Everything defaults, and if you are willing to accept the built-in choices, just scroll down to the bottom of the page and click on the "Continue" button.

Title Lines

The form starts by allowing you to enter one or two lines of title information (to appear above the graph). The default is no titles. The titles can include special characters (Greek letters, letters with accents), subscripts and superscripts, different sizes, and different fonts. For instructions on how to enter special effects in the title lines, click on the "Title1" link.

Choosing Your Axes

The axes (X, Y, and sometimes Z) can be either linear or logarithmic. The default is linear. Linear graphs do a better job of showing the high-energy regions and log graphs are better for low-energy cross sections. If you are plotting a total, capture, or fission cross section using lin-lin, the resulting graph may not show anything! This is because the very high cross sections at thermal energies are all plotted on the left-hand Y axis. Change to log scales to see something more interesting. The Nuclear Data Viewer thins the data before sending it to your machine, and the thinning strategy depends on whether you selected log or linear axes. This can lead to confusion if you choose to output the numerical data instead of view the plot (see the "Output mode" radio button at the bottom of the page). As an example, if you choose a linear X axis for the capture reaction, you may see the X values jump from 1E-5 to 1E-2 with no intermediate points. This is because they have been thinned out (they clearly would not show up on the plot). To get the intermediate values, rerun the case using a log X axis.

The default for scaling the axes is automatic scaling, which depends on the data values. The data values for scaling are taken from the first curve or data set. This can cause problems if the ranges of X and Y on the first curve are not sufficient to include all the data on the subsequent curves or data sets. You can alleviate this somewhat by choosing the order in which you request the curves or data sets. If that is not enough to get an attractive plot, you will have to adjust the axis scales manually. You may also want to use manual scaling to make things look better, to cut off high peaks in order to get a better view of the minima, or to make more room for a legend.

You can enter your desired scaling information in the boxes after "Limits:" on the desired axis. The X axis units are normally eV, so don't forget to include the "E6" when you get into the MeV range! The value of "step" should be a reasonable fraction of the low to high range. For example, use numbers like 0, 20E6, and 5E6 to get a presentable graph. The Viewer will try to give you an error message if you specify unreasonable values.

A input widget is provided for "X Scale." All the X values for all the curves are multiplied by this factor before being plotted. It can be used to change the units of the horizontal axis from eV to MeV by inputting 1E-6. When this is done, the axis limits will by based on the new values; for an MeV scale, the upper limit would become "20" instead of "20E6". Be sure to change the default X-axis label to reflect the proper units. This kind of scaling can produce more presentable plots for publications. There is a similar widget for "Y Scale" described below. The "Y Scale" value can be different for each curve. Once again, be sure to change the default Y axis label when scaling is used (if appropriate).

You can change the axis labels by editing the text in the "X Axis Label" and "Y Axis Label" fields. Special characters can be included here using the same rules as for the title fields. The code is not smart enough to automatically change the labels for quantities not given in barns, so watch out when you plot KERMA or damage (eV-barns). You will have to fix them manually.

Grids and Tick Marks

The Viewer allows you draw graphs with tick marks (inside or outside), grid lines, or neither. Just use the menu box after "Grid". Click on the small rectangular symbol to bring up the choices, and then click on the desired option.

Legends and Curve Tags

For plots with experimental data sets shown (with or without curves), the Legend Block option is the most suitable. It gives a block with a line for each curve or data set showing the symbol or line type used to represent those data and some identifying text. The text comes from the "Tag" element in the Curve section, which will be discussed below. When only curves are shown, it is sometimes useful to use text tags with arrows going to the associated curve. The text of the tag and its location on the plot are given in the Curve section, as described below. To choose between a legend block or curve tags, click on the small rectangle in the "Legend" menu box, and then click on your choice. If you choose a legend block, you may want to specify its location (the default is the upper left portion of the graph area). If so, enter axis values in the "LegX" and "LegY" fields. As an example, you might use LegX=5E6 and LegY=1.4 for a graph with an X range of 0 to 10 MeV and a Y range of 0 to 1.5. This would put the block near the upper edge of the plot area, just to the right of the center of the field. Sorry that this is not more automatic.

When curve tags are used, enter the text in the "Tag" field for each curve ("Curve1", Curve2", etc.). Enter the X and Y position of the left edge of the tag text in "TagX" and "TagY". Finally, enter the X position for the arrow point in the "Point" field. The Viewer will automatically determine the Y location for the arrow point by interpolating in the data table for that curve. You will probably have to view the curve and readjust the positions several times to get an attractive graph. Fortunately, this is quite easy if you have access to ghostview through your Web browser.

Page and Window Colors

We provide a selection a light colors to be used for the page background color and the color inside the graphics window. We don't allow for the light lettering and curves on dark backgrounds that some people prefer. The lettering is always black, and as described below, we provide a selection of darker colors for curves.

Curve Specifications

You will see one or more curve specification areas on the Viewer form; they will be labeled "Curve 1", "Curve 2", and so on. The Type, Elem, Iso, and Data fields come from the data selection procedure as described above, and they should not be edited on this form! If there is more than one curve or data set, the "Tag" field will be filled in with text taken from the data base. This text will probably have to be edited to obtain the most attractive display for your legend block or curve tags. The position of the text and arrow point for the curve tag are also specified here; see the discussion above for the details.

You can also choose the line type for a curve (e.g., solid, dashed), or specify that the points should not be connected (none). A color and a thickness can also be chosen for the line. We provide a selection of darker colors that contrast properly with the light colors allowed for the window color. The symbol used for displaying data can be chosen from the "Symbol" menu box, or you can choose "none". The vertical axis for this curve can be scaled using the left-hand or right-hand axis limits by using the "Axis On" menu box. The right-hand axis is automatically selected when you are plotting the difference between two curves.

The "Y Scale" value can be used to adjust the units of an axis (e.g., from barns to millibarns). Be sure to change the default label on the y axis appropriately. The "Y Scale" option can also be used to adjust curves to be closer to each other for easier comparison; in these cases, it is useful to add a note to the curve tag, such as "x10" to indicate that this has been done. This scaling option can also be used to move curves apart so that they are more visible. This is often done on log plots using factors of 10.

The last curve section contains an "Add Curve" option. Choosing "Yes" will take you back through the data selection process to add another curve or data set. Choosing "No" will enable you to plot up the page as defined by this form.

Output Mode

The Nuclear Data Viewer has five different output modes: Postscript plots, PDF plots, PNG plots, GIF plots, and Data. The Postscript plots are the native format of the plotting code, and they give very flexible results. They can be viewed on the screen by using an auxiliary application like ghostview without any preimposed resolution limits. They can also be printed on any Postscript printer at full resolution. PDF plots are also very flexible, and they are often supported by the OS (e.g.Macs) or by common browesers. The PNG and GIF plots are very useful for people who don't have a Postscript or PDF viewer in operation, and they come down very fast. Unfortunately, they won't print as well as Postscript plots, because the resolution is limited by the dots on your screen. It is possible to mix these two strategies when necessary--view using PNG or GIF, but download the Postscript file as text and send it to a printer.

It is also possible to ask the Viewer to just send down a table of the data and skip the plot. The format of this data file is just that of the internal file used by the viewr.f program adapted from the NJOY Nuclear Data Processing System. It contains the numerical X and Y coordinates (and error limits when included), but it also contains the titles, axis labels, symbol code, and so on. You should be able to edit or postprocess this file to adapt it to other graphical systems, or you can simply extract the numbers from the text to make tables. Details on the format used can be obtained by clicking on the "Output mode" link.

User Data

The Nuclear Data Viewer has an option that allows the user to enter numerical values to be plotted together with curves or experimental data sets from our data base. For example, an experimentalist could enter some experimental results and quickly compare them to an evaluated cross section curve from ENDF/B-VI. Or a theorist could enter a set of computed X and Y values and compare the curve with several experimental data sets from CSISRS. The Viewer can also be used as a convenient general-purpose plotting code by entering all the data values manually and not bothering with the T-2 data base.

To enter data points manually, choose "user-input" for the curve "Type". When you click on the "Continue" button, the code will skip directly to the graph setup form without going through the element, isotope, and reaction dialog. The user-input curve specification block will contain a text entry widget called "User Input". Click on the "User Input" link for help. The text area is seeded with prototype input lines; be sure to edit these or your run will just lead to a Viewer error (it doesn't like the "x" and "y" where it expects numbers). As an example, you could enter

    0. 0./
    1. 1./
to prepare a very simple graph of a straight line. Symmetric and asymmetric X and Y error bars can be entered using the format described on the help page. It may be possible to paste text from another window on your screen into the text entry window.

Unfortunately, the settings in the User Data area are not preserved when a subsequent data type is entered. So wait until all the data types have been entered before you fill in the user x and y values, or give the user data last.

Difference and Ratios Between Curves

If you use the data selection mechanism to specify two curves, two new options appear for "Type" when you start specifying the third curve; namely, "difference" and ratio." If you choose one of these from the Type menu then click on "Continue", the code will automatically jump to the graph specification form without going through the element, isotope, and reaction dialog. A new line for describing the "R" axis type and limits will appear, and the default R-axis label will be "Percent Difference or "Ratio." You will normally be able to leave this with the default settings. Don't change the difference axis to log!

The specification block for Curve 3" will be already filled in with the tag name "difference" or "ratio" and the "dotted" line type. It will also say that the right-hand axis is to be used for this curve. If you prefer to use curve tags for this plot instead of a legend block, you will have to fill in the tag X, Y, and Point values.

Caution: The differences and ratios are computed between the two curves as sent to your browser. Therefore, both curves may have been thinned. This thinning could lead to unrealistically large percent difference between the two curves. If this is a problem, try to reduce the X range of the data enough to prevent thinning; that is, try to keep the number of actual points in the X range down to 2 or 3 thousand.

If the curves are very different, the percent-difference scale won't come out reasonably. But then, you don't really need to see a percent difference; the difference between the two curves is there on the graph for anyone to see.

The first curve entered is used as the denominator for the ratio or the reference for the percent difference. The energy grid for the ratios or percent differences is the grid of the first data set entered. If the second curve has more detail than the first, this can give confusing results. However, it does provide a handy way to extract data from ENDF files onto a specified grid--just enter a user data set with the desired energies and values of unity. Then request a ratio with numerical output. The resulting ratio will be the desired values on the specified grid.

As mentioned above, the user data points won't be preserved as multiple curves are defined. To compare two sets of user input, just define the two curves without entering data. At the last step, enter both sets of data while defining the other plotting parameters.

Resonance Cross Sections

In most evaluated cross section files, the resonance range is represented using resonance parameters. The data in the file in these ranges may be zero, or it may be a smallish background correction. This is confusing to many users--they say, "Why are the cross sections zero below 100 keV?" To see the actual data in these resonance ranges, you must select a data "Type" that has been processed through a code like NJOY. In some cases, we have provided a PENDF (or pointwise ENDF) type for this purpose (see the type ending with "pointwise"). For ENDF/B-VI and JENDL-3.3 evaluations, we have the type ending with "ACE," which include complete representations for the resonance ranges. Pointise or ACE files are large, and we have been a little cautious about adding them to our disk!

Caution: Some of the PENDF files in the data base for the Nuclear Data Viewer have been processed with a comparatively coarse reconstruction tolerance. This tolerance is suitable for making graphs, but please don't expect good results if you download the PENDF files and try to use them for a more exacting applications.

3-D Perspective Plots

Nice 3-D perspective plots of energy and angle distributions for secondary particles can be obtained using the Nuclear Data Viewer. Just select the "3D plot" option from the radio button on the main page of the Viewer. The "Type" menu gives you the same options as for 2-D plots, however, it is not reasonable to select CSISRS. Similarly, the element and isotope dialogs are the same as for 2-D plots. The Data selection widget, however, will only contain data items that are appropriate for 3-D plots, such as angular distributions. Also, the option to select additional curves is missing, because only one data set can be plotted on a 3-D page.

The plot specification form is a little different from the 2-D case. Lines are now given to specify the Z-axis type, range, and label. In addition, text entry areas are provided to change the viewpoint and workbox. There are help links to explain about viewpoint and workbox. Basically, the 3D workbox has its X and Z axes in the foreground, and its Y axis goes away from you into the page. The Z axis is always vertical and Z coordinates increase upwards. The sense of the X axis can be controlled using the sign of WorkX. If positive, it increases to the right. If negative, it increases to the left.

The actual values of WorkX, WorkY, and WorkZ are only relative, because the plot is always renormalized to fit into the window. However, the size of the labels relative to the lengths of the axes is affected by the scale of the workbox dimensions. The nominal character height is 0.30 in. If you increase the workbox size, the characters will appear to be smaller.

The ViewX, ViewY, and ViewZ values control the viewpoint, and their absolute magnitudes are on the same scale as the workbox sides. The viewpoint will not affect the size of the plot in the window, but long viewpoint vectors will reduce the perspective effect. The coding is not very smart, and things will probably look pretty bad if you move the viewpoint out of the default octant. However, you can move it around by small amounts to direct the view to be more from the top, front, or side, if desired. The "Page Color" is used for the background for the entire perspective plot. The "Window Color" is used for slices that represent the 3-D function.
21 June 2004