3.1 File formats

As described in section 2.1 for 1D data sets, 2D data sets are read using the command 'load'. Multiple data sets might be read by repeating the command 'load' and 1D and 2D data sets might be imported in any combination. The command 'rese' clears the currently loaded data sets and the next file is read as set number one again.

A summary of the supported 2D file formats is given in Table 3.1. All file formats are "normal" text files that can be viewed and edited with every text editor. Since these files are normally larger in size compared to a binary version, archived files might be compressed with standard UNIX tools like 'compress' or 'gzip'. The standard file format for 2D data is the so-called NIPL format which was developed at the Insitut für Mineralogie und Kristallographie in München. The NIPL format ('ni') is defined as follows:

    1      nx ny
    2      xmin xmax ymin ymax
    3ff    z z z z ...

The first line contains the number of data points in x- and in y-direction. The next line gives the x- and y-limits of the plot area. All following lines contain the z-values row by row starting in the lower left corner. The z-values are real numbers and not restricted in any way. However, the value -9999.0 is reserved for excluded regions (see below).

 

Table 3.1: Supported file formats for 2D data

Format	add. Parameters	Description
de	$\Delta x,\Delta y$	Reads xy-file and creates a 2D data set with the number of points that are inside a specified grid box $\Delta x,\Delta y$ as z-values.
ni	[exclude]	Reads NIPL file format (see text). The optional parameter is a file containing excluded regions.
pg		Reads PGM file format (see text).
zz	$\Delta x,\Delta y$	Reads xyz-file and bins the data to the given grid size $\Delta x,\Delta y$

The optional third parameter listed in Table 3.1 is the name of a file containing excluded regions, i.e. areas of the data file that should be excluded from the plot. An example is shown in Figure 3.1. The plot on the bottom was created by reading the NIPL file 'test.nipl' using the command 'load ni, test.nipl' and thus reading all data. The data shown here are actually neutron diffuse scattering from calcium stabilized zirconia collected by R.B. Neder at the neutron source in Garching, Germany. Sometimes one wants to exclude certain regions within the data from the actual plot, in our example the strong Bragg peaks. This can be done by creating a file with coordinates of rectangles within the plotting area that should be excluded. Such a file can be created using a text editor. In our example, the excluded region file 'test.excl' looks like this:

 10
 0.87  1.13  0.81  1.17
 2.85  3.15  0.81  1.26
 1.85  2.34  3.70  4.28
 2.82  3.18  2.79  3.28
 0.87  1.18  2.81  3.23
 0.00  0.24  3.68  4.28
 0.00  0.12  1.73  2.24
 0.00  0.58  0.00  0.79
 1.78  2.22  0.00  0.35
 1.90  2.17  1.81  2.13

The first line contains the number of rectangle coordinates in the file followed by 'xmin,xmax,ymin,ymax' for each excluded region. Rereading the file 'test.nipl' using the command 'load ni, test.nipl, test.excl' results in the right view graph of Figure 3.1. Note that KUPLOT will replace all z-values within an excluded region by -9999.0 and those values will be ignored by most KUPLOT functions. If a file read with excluded regions is saved later on, the data within those excluded regions are lost.

  

Figure 3.1: Usage of excluded regions for 2D files

The second more general 2D file format is the PGM (portable graymap) format which is defined as part of the PNM format Jef Poskanzer. Various programs are capable of reading PNM files and the 'pnmplus-package' is a freely available collection of tools and conversion programs from PNM to virtually any other graphics format. KUPLOT only supports ASCII PGM files which are defined as follows:

    1      P2
    2      nx ny
    3      255
    4ff    z z z z z

The code 'P2' in the first line identifies the file as ASCII PGM format. The dimensions nx and ny of the data set are given in the next line. The PGM format is an integer bitmap and the number in line 3 gives the maximum depth (here 255 or 8 bit). Although the PGM format is generally not restricted to 8 bit resolution, it was found that many programs are not capable of reading PNM files with a larger resolution. Comments can be included in the file starting with a '#' as first character. The actual data are integer values written row by row starting (in contrast to NIPL files) from the top left corner. Besides being limited to integer values ranging from $0 \rightarrow 255$, the PGM file format does not contain any information about the x and y limits and KUPLOT sets x- and y-values to the pixel number. However, the x- and y-values might be manipulated (see chapter 7) and the file can be saved in NIPL format (see section 3.4), thus allowing the conversion of PGM files to NIPL files and vice versa.

The PGM and NIPL files are restricted to data points being on a equidistant rectangular grid. The file format 'zz' can be used to read any data file containing the data points (x_i, y_i, z_i) on a separate line. This is practically the extension of the 'xy' file format. However, KUPLOT can internally only work with z-values lying on a rectangular equidistant grid. Thus the read data points are binned to a grid size defined by $\Delta x$ and $\Delta y$ given as additional parameters to the 'load' command. Each resulting grid point contains the average of all data points within the file that fall within the area of the specific grid point. If the specified grid size is too small, the resulting plot will contain empty grid points. The following command reads the XYZ file 'test.xyz' and bins it to a grid size of $\Delta x = \Delta y = 0.05$:

    load zz,test.xyz,0.05,0.05

This file format can also be used to rebin data sets to a broader grid by saving the NIPL (or PGM) file as XYZ file and rereading the file with the new desired grid size.

The file format 'de' (for density) works similar to the previously discussed 'zz' format but rather than averaging the z-values in each grid point, the resulting z-value is the number of points (x_i, y_i) falling within the corresponding grid volume which is defined as before by the additional parameters $\Delta x$ and $\Delta y$. The program reads the first two real numbers in each line as x- and y-value. For example DISCUS can export the atom positions of all atoms without the translational part, i.e. all atoms are in one unit cell. The resulting file can be read using the 'cr' format resulting in a marker for each atom. Alternatively the same file (since the first two numbers are x and y) can be read using the 'de' format which will result in a density plot which can be displayed either using contour lines or a bitmap.