Histograms and Arrays of Floats

TCL API

C Routine Interface

hg -- a tcl histogram package

concepts

This package is a collection of tcl verbs and c functions to do histograms and arrays of floating points values.

The basic structures

We define the following structures in the package: The hg package provides the basic manipulation of these strucures, including plotting. There is also some interface to regions (hgReg fills a histogram with the pixel values in a region) and lists (the routine afFromList fills an AF with the values from a liked list.) The pgplot package does the actual display.

Selecting with the cursor from a plot

Several functions allow you to pick from a plot. When you go into the cursor mode, the following message appears on the tcl prompt window: Waiting for cursor input You can choose 1, 2, or 0 points. To choose one point, click with the left mouse button. To select two points, use the middle mouse button, one click at each position. To bail out with doing minimal damage, click the right button once anywhere.

HG: selecting one point selects the BIN at that x value. Selecting two points gets all the bins between the two selected bins. The y value is ignored.

AF: selecting one point gets the object closest to the point. Distance is calculated as sqrt(delta_x^2 + delta_y^2) in whatever units are plotted. Selecting two points gets you everything inside the rectangle; it is possible to have nothing returned.

afMask: masking items

Several functions use afMask to indicate which items are to be used. If afMask==NULL then ALL items are used. Otherwise, only items with the afMask->value==1 are used. The function afInvert takes the (logical) inverse of an afMask, so you can plot all the good objects with afMask, make the inverse of afMask, and plot all the not-good objects with afMaskInverse.

Example

eagphot> hgNew h1 eagphot> hgDefine h1 "-name First Example" -xLabel Counts -max 10000 -nbin 100 eagphot> hgFill h1 30 eagphot> hgFill h1 35 eagphot> hgFill h1 40 eagphot> hgFill h1 50 -weight 10 eagphot> hgPrint h1 id = 0 name = First Example xLabel = Counts yLabel = nbin = 50 minimum = 0.000000 maximum = 100.000000 underflow = 0.000000 overflow = 0.000000 entries = 4 mean = 47.461538 sigma = 134.359801 eagphot> hgMean h1 47.461538 eagphot> hgSigma h1 134.359801 eagphot> pgstateNew h2 eagphot> pgstateOpen h2 Open /XWINDOW eagphot> hgPlot h2 h1 eagphot> pgstateClose h2 Close /XWINDOW In the graphics window: click any mouse button or type <RETURN> to continue eagphot>

Controlling the plot with PGSTATE

After creating a PGSTATE you control various features with the pgstateSet comand: eagphot> pgstateSet h2 -nxwindow 2 sets the number of windows in the x direction to 2. The following parameters may be set:

Styles - plot symbols

The parameter symb gives the following types of plot symbols:

Styles - line styles

The parameter lineStyle gives the following types of lines: The lineWidth parameter says how many strokes are in each line. This may be set from 1 to 201 inclusive.

Styles - color indices

The colors for the marks, lines, boxes, labels, and error bars are chosen with a color index. The representation of the color can also be chosen by defining (R,G,B) intensities for the index. The default color indices are: Higher numbers are defined but I can't tell the difference in the colors.

Chains

Chains are used to communicate between pgplot windows and saoDisplay windows. The tcl interface that creates a chain uses the command chainFromPlot. The command chainToSao takes the elements on the chain and marks their position in the saoDisplay window. From a distribution of parameters, chain elements that are near the selected point (or inside the selected rectangle) are marked on the image display.

A future release will have the ability to select a position in the saoDisplay and feed the information from selected objects to the pgplot window.

The C structures

/* HistoGram Structure */ typedef struct Hg { /* list management */ TYPE type; struct Hg *next, *prev; const int id; /* info for this histogram */ double minimum; double maximum; char *name, *xLabel, *yLabel; unsigned int nbin; float *contents; float *binPosition; double underflow; double overflow; unsigned int entries; double wsum, sum, sum2; } HG; /* Array Float Structure */ typedef struct Af { TYPE type; struct Af *next, *prev; const int id; char *name; unsigned int nValue; float *value, *error; } AF; typedef struct Pt { TYPE type; struct Pt *next, *prev; int id; float row, col, radius; } PT; /* Structure to define the state of the plotting */ typedef struct Pgstate { /* list management */ TYPE type; struct Pgstate *next, *prev; const int id; /* info for the hg plotting state */ char device[HG_DEVICE_NAMELEN]; int nxwindow, nywindow; /* number of windows in x and y */ float xfract, yfract; /* window filling fraction in x and y */ int ixwindow, iywindow; /* current window in x and y */ int just; /* "just" of pgplot_pgenv */ int axis; /* "axis" of pgplot_pgenv */ int full; /* 0 if plot is empty; 1 if it is full */ /* parameters used in PGBOX */ char xopt[12], yopt[12]; float xtick, ytick; int nxsub, nysub; } PGSTATE; /* PoinT Structure */ typedef struct Pt { TYPE type; struct PT *next, *prev; const int id; float row, col, radius; } PT;