2.4.6. - Data Handling and Analysis Functions

data_grp(grp, npts, wid)

Configures data group grp. The group will have npts points, each having wid elements. If npts and wid match the previous values for the group, the data in the group is unchanged. Otherwise, the data values of the reconfigured group are set to zero. If wid is zero, the group is eliminated. If npts is zero, as many points as possible are configured. If npts is negative, as many points as possible, but not more than -npts are configured. If grp is -1, the current group configuration is displayed.

data_info(grp, what)

Returns data group configuration information for group grp, according to the the string what. Values for what are:

"npts"

the number of configured points.

"elem"

the number of configured elements.

"last"

the number of the last point added to the group.

"precision"

the number of bytes per element, either 4 or 8.

If the group number is invalid, or if the string what is none of the above, returns -1.

data_get(grp, npt, elem)

Returns the value of element elem of point npt in group grp.

data_put(grp, npt, elem, val)

Assigns the value val to element elem of point npt in group grp.

data_nput(grp, npt, val0 [, val1 ... ])

Assigns values to point npt of group grp. Element 0 is assigned val0, element 1 is assigned val1, etc. Not all elements need be given, although elements are assigned successively, starting at element 0.

data_uop(g_src, e_src, g_dst, e_dst, uop [, val ])

Performs the unary operation specified by the string uop on element e_src for all points in group g_src. The results are put in element e_dst of the corresponding points in group g_dst. The source and destination groups and/or elements may be the same. If the number of points in the groups differ, the operation is carried out on up to the smallest number of points among the groups. Values for uop are:

"clr"

clear to zero.

"fill"

each element is set to point number, starting at 0.

"neg"

Negative of source.

"abs"

Absolute value of source.

"inv"

Inverse of source.

"sin"

Sine of source.

"cos"

Cosine of source.

"tan"

Tangent of source.

"asin"

Arcsine of source.

"acos"

Arccosine of source.

"atan"

Arctangent of source.

"log"

Natural logarithm of source.

"exp"

Exponential of source.

"log10"

Log base 10 of source.

"pow"

The val power of source.

"copy"

Value of source.

"rev"

Reversed copy of source.

"sqrt"

Square root of source.

"set"

All elements set to the value of val.

"contract"

Every val points are averaged to make a new point.

"add"

Source plus val.

"sub"

Source minus val.

"mul"

Source times val.

"div"

Source divided by val.

If any of the operations would result in an exception (divide by zero, log or square root of a negative number, etc), the operation is not performed and a count of the operations skipped is printed as an error message.

data_bop(g0_src, e0_src, g1_src, e1_src, g_dst, e_dst, bop)

Performs the binary operation specified by the string bop on elements e0_src and e1_src for all points in the groups g0_src and g1_src. The results are put in element e_dst for the corresponding points of group g_dst. The source and destination groups and/or elements may be the same. If the number of points in the groups differ, the operation is carried out on up to the smallest number of points among the groups. Values for bop are:

"add"

The sum of the source elements.

"sub"

Source 0 minus source 1.

"mul"

The product of the source elements.

"div"

Source 0 divided by source 1.

If the divide would result in an exception, the operation is not performed and a count of the operations skipped is printed as an error message.

data_anal(grp, start, npts, el_0, el_1, op [, val ])

Performs the operations indicated by op on npts points in group grp, starting at point start. The operations use the values in element el_0 (if applicable) and el_1. If npts is zero, the operations are performed on points from start to the last point added using data_nput() or data_put(). The values for op are:

"min"

Returns the minimum value of el_1. (el_0 is unused.)

"max"

Returns the maximum value of el_1. (el_0 is unused.)

"i_at_min"

Returns the point number of the data point with the minimum value of el_1. (el_0 is unused.)

"i_at_max"

Returns the point number of the data point with the maximum value of el_1. (el_0 is unused.)

"i_<=_value"

Returns the point number of the nearest data point in el_1 at or below val, starting from the first point. (el_0 is unused.)

"i_>=_value"

Returns the point number of the nearest data point in el_1 at or above val, starting at the last point. (el_0 is unused.)

"uhmx"

Returns the value in el_0 corresponding to half the maximum value in el_1 and at a higher index.

"lhmx"

Returns the value in el_0 corresponding to half the maximum value in el_1 and at a lower index.

"sum"

Returns the sum of the values in el_1. (el_0 is unused.)

"fwhm"

Returns the full-width in el_0 at half the maximum value of el_1.

"cfwhm"

Returns the center of the full-width in el_0 at half the maximum value of el_1.

"com"

Returns the center of mass in el_0 with respect to el_1. The value is the sum of the products of each el_0 and el_1 divided by the number of points.

"x_at_min"

Returns the value of el_0 at the minimum in el_1.

"x_at_max"

Returns the value of el_0 at the maximum in el_1.

"sumsq"

Returns the sum of the squares in el_1. (el_0 is unused.)

The following operations treat a data group as a two dimensional data array with rows indexed by the point number and the columns indexed by the element number. The operations work on the portion of the group determined by the starting row start the number of rows npts, the starting column el_0 and the end row el_1. As usual, if npts is zero, all points (rows) from start to the last are considered. A negative element (column) number is added to the group width to obtain the element (column) to use.

"gmin"

Returns the minimum value.

"gmax"

Returns the maximum value.

"gsum"

Returns the sum of all values.

"i_at_gmin"

Returns the index number of the minimum value. The index number is the row number times the group width plus the element number.

"i_at_gmax"

Returns the index number, as defined above, of the maximum value.

data_read(file_name, grp, start, npts)

Reads data from the ASCII file file_name, and stuffs the data into group grp starting at point start, reading up to npts points. If npts is zero, all the points in the file are read. The values on each line of the file are assigned into successive elements for each point in the group. If there are more elements on a line in the file than fit in the group, or if there are more points in the file than in the group, the extra values are ignored. Lines beginning with the # character are ignored. Returns -1 if the file can't be opened, otherwise returns the number of points read.

data_fit(pars, grp, start, npts, el_data, el_data [, ... ])

Performs a linear fit of the data in element el_data to the terms in the elements specified by el_pars. The fitted parameters are returned in the array pars supplied by the user. The function returns the chi-squared value of the fit, if the fit was successful. A -1 is returned if there are insufficient arguments or the covariance matrix is singular. The fit algorithm is along the same lines as the lfit() routine in Numerical Recipes (W.H. Press, et al., Cambridge University Press, 1986, page 512).

data_plot(grp, start, npts, el_0, el_1 [, el_2 ... ])

Plots the current data in group grp starting at point start and plotting npts points. Element el_0 is used for x. Elements given by the subsequent arguments (up to a maximum of 64) are plotted along the y axis. The element arguments can be combined in a single space- or comma-delimited string, which can make creation of macros to plot a variable numbers of curves in the same plot window easier.

If npts is zero, only the points from start to the last point added using data_nput() or data_put() are plotted.

If preceded by a call of plot_cntl("addpoint") and the ranges have not changed, only point start + npts - 1 is drawn. If preceded by a call of plot_cntl("addline") the current plot will not be erased, and the plot ranges will not be changed.

The plotting area is not automatically erased by a call of data_plot()-use plot_cntl("erase") for that. The axis ranges are set using the plot_range() function. See plot_cntl() for other options that affect drawing the plot.

plot_cntl(cmd)

Selects built-in plotting features. The argument cmd is a string of comma- or space-delimited options. The following options may be preceded by a minus sign to turn the associated feature off, nothing (or an optional plus sign) to turn the feature on or a question mark to return a value of one or a zero that indicates whether the associated feature is currently on or off:

"xlog"

Use a logarithmic x axis.

"ylog"

Use a logarithmic y axis.

"xexact"

Force x-axis minimum and maximum to be set to the scan endpoints (as opposed to being rounded).

"colors"

Enable the use of colors.

"dots"

Draw graphics-mode points with large dots.

"lines"

Connect graphics-mode points with lines.

"ebars"

Draw vertical lines through each point of length equal to the twice the square root of the y value.

"persist"

Keep graphics mode on after ordinary user input.

"perpetual"

Keep graphics mode on continuously (appropriate if using X windows, for example).

Other plot_cntl() options are:

"colors=bgnd:win:text:axis:symb:..."

Assigns colors for drawing the various graphics-mode elements. The values for bgnd (the background color of the area outside the axis), win (the background color of the area inside the axis), text (the color of the text), axis (the color of the axis) and symb ... (the color of the plotting symbols) are integers. The first 10 colors are standardized according to the following table:

0	background	(normally white or black)
1	foreground	(normally black or white)
2	blue	3	red
4	green	5	yellow
6	cyan	7	magenta
8	white	9	black

Other colors may be available depending on the particular device. You don't have to assign values to all colors.

"colors[numb]"

Returns the current color assignments, where numb is a number between zero and 67. Numbers zero through three return the colors assigned to the bgnd, win , text and axis elements respectively. Numbers from 4 through 67 return the colors assigned to the symbols for data elements zero through 63.

"filternumb"

Selects filter number numb, where numb can be any of the numerals from 1 through 5. All plotting commands are directed to this filter. The default filter is filter 1. Each filter is associated with a separate process. On an X windows display, each filter is associated with a separate window.

"title=string"

On an X windows display, the title given by string is used in the XSetWMName() and XSetWMIconName() calls to set the window and icon labels. With most X11 window managers, that means the title will appear in the window's title bar.

"geometry=widthxheight+xoff+yoff"

With the x11 high-resolution plot windows, sets the size and position of the window. As with the conventional X11 syntax for specifying window geometry, not all parts of the geometry string are required.

"open"

Turn on graphics mode. If there is no graphics filter program currently active for the current filter number (see above), the filter program associated with the current GTERM variable is started. Recognized GTERM values are vga, ega, cga, herc, x11, and sun.

"close"

Turn off graphics mode, unless the perpetual or persistent mode has been selected.

"kill"

Turn off graphics mode and terminate graphics process.

"erase"

Clear the graphics-mode screen (or the text screen if graphics mode is off).

"addpoint"

Before a call to data_plot() will cause the plot to be made with minimal redrawing. Used for updated plotting during scans.

"addline"

Before a call to data_plot() will prevent the current data from being erased and the new data from changing the ranges when the new data points are drawn. Used for plotting several data sets from different data groups on top of each other.

"mca"

Before a call to data_plot() will cause the data points to be displayed using a minimal redrawing algorithm, appropriate for displaying data actively being accumulated by an MCA-type device. The "dots" and "ebars" modes must be turned off for the algorithm to work effectively.

"lp"

Before a call to data_plot() will generate printing instructions appropriate for plotting on a 132-column printer.

data_dump(grp, start, npts, el_0, [, el_1 ... ] [, fmt1 ] [, fmt2 ])

Efficiently writes elements from group grp to turned on output devices. The starting point is start and the number of points is npts. The elements specified by el_0, e1_1, etc., are printed. If el_0 is the string "all", all the elements for each point are printed. If npts is zero, only the points from start to the last point added using data_nput() or data_put() are printed. The element arguments can be combined in a single space- or comma-delimited string.

The optional argument fmt1 is a string, having the format "%#", that specifies how many data points (specified by the number #) are to be printed on each line. If the number # is followed by the letter C, a backslash is added to each continued line, appropriate for saving MCA data in manageable length lines. New versions (since May 1, 1995) of the C-PLOT scans.4 user function interpret the continued lines correctly for MCA data. The optional argument fmt2 is a string that specifies an alternate printf()-style format for the values. Only e, g and f formats are recognized. For example, "%15.8f" uses fixed-point format with eight digits after the decimal point and a fifteen-character-wide field. The default output format is "%g". See printf() in a C manual for more information. Note that in the default installation, the internal data arrays use single-precision floating values, which contain only about 8 decimal digits of significance.

plot_move(x, y [, string [, color ]])

Moves the current position to column x and row y, where column 0, row 0 is the upper left corner of the screen. If the third argument string is present, it is written as a label at the given position. If using color high-resolution graphics, the fourth argument, if present, is the color to use to draw the label. The background color for the entire label will be the background color at the starting position. If graphics mode is not on, plot_move() works just as tty_move(). Returns true .

plot_range(xmin, xmax, ymin, ymax)

Sets the ranges of the internally generated plots. If any of the arguments is the string "auto", the corresponding range limit is determined automatically from the data at the time the plot is drawn. If any of the arguments is the string "extend", the corresponding range limit is only changed if the current data decrease the minimum or increase the maximum. Returns true .

2.4.6.1. - The Data-Pipe Facility