KPG1_GRPHW

Draws a line graph, using supplied work arrays

Description:

Opens a graphics device and draws a graph displaying a supplied set of points. Each point is defined by an X and Y value, plus an optional error bar. An AST Plot is returned so that the calling application can add further graphics to the plot if needed. When complete, the calling application should annul the Plot, and close the workstation:

CALL AST_ANNUL( IPLOT, STATUS ) CALL KPG_PGCLS( ’ DEVICE’ , .FALSE., STATUS )

Various environment parameters are used to obtain options, etc. The names of these parameters are hard-wired into this subroutine in order to ensure conformity between applications.

Invocation

CALL KPG1_GRPHW( N, X, Y, NSIGMA, YSIGMA, XLAB, YLAB, TTL, XSYM, YSYM, MODE, NULL, XL, XR, YB, YT, APP, QUIET, LMODE, BSCALE, DX, DY, DBAR, IPLOT, STATUS )

Arguments

N = INTEGER (Given)
Nuumber of points
X( N ) = REAL (Given)
X value at each point. These are scaled by the value supplied in BSCALE(1) to generate the axis labels.
Y( N ) = REAL (Given)
Y value at each point. These are scaled by the value supplied in BSCALE(2) to generate the axis labels.
NSIGMA = REAL (Given)
Controls the length of the vertical error bars. A value of zero suppresses error bars. Otherwise error bars are drawn that extend from Y - NSIGMA∗YSIGMA to Y + NSIGMA∗YSIGMA.
YSIGMA( N ) = REAL (Given)
The standard deviation associated with each Y value. Not accessed if NSIGMA is zero.
XLAB = CHARACTER ∗ ( ∗ ) (Given)
A default label for the X axis. Only used if the user does not supply an alternative. Trailing spaces are ignored. If a Plot is supplied via IPLOT, then the " Label(1)" attribute in the Plot is used as the default in preference to XLAB.
YLAB = CHARACTER ∗ ( ∗ ) (Given)
A default label for the Y axis. Only used if the user does not supply an alternative. Trailing spaces are ignored. If a Plot is supplied via IPLOT, then the " Label(2)" attribute in the Plot is used as the default in preference to YLAB.
TTL = CHARACTER ∗ ( ∗ ) (Given)
A default title for the plot. Only used if the user does not supply an alternative. If a Plot is supplied via IPLOT, then the " Title" attribute in the Plot is used as the default in preference to TTL.
XSYM = CHARACTER ∗ ( ∗ ) (Given)
The default symbol for the horizontal axis. Only used if the user does not supply an alternative. This will be stored with the Plot in the AGI database and (for instance) used by KAPPA:CURSOR as axis symbols when displaying the cursor positions on the screen. If a Plot is supplied via IPLOT, then the " Symbol(1)" attribute in the Plot is used as the default in preference to XSYM.
YSYM = CHARACTER ∗ ( ∗ ) (Given)
The default symbol for the horizontal axis. Only used if the user does not supply an alternative. This will be stored with the Plot in the AGI database and (for instance) used by KAPPA:CURSOR as axis symbols when displaying the cursor positions on the screen. If a Plot is supplied via IPLOT, then the " Symbol(2)" attribute in the Plot is used as the default in preference to YSYM.
MODE = INTEGER (Given)
Determines the way in which the data points are represented. 1 – A " staircase" histogram, in which each horizontal line is centred on the X position. Bad values are flanked by vertical lines drawn down to the lower edge of the viewport. 2 – The points are joined by straight lines. 3 – A marker is placed at each point. 4 – (not used) 5 – A " chain" in which each point is indicated by a marker and also join by straight lines to its neighbouring points. 6 – The same as Mode 1, except that bad values are not flanked by vertical lines drawn down to the lower edge of the viewport (a simple gap is left instead). 7 – The data points are not drawn.
NULL = LOGICAL (Given)
If .TRUE., then the user may supply a null (!) value for most of the parameters accessed by this routine to indicate that nothing is to be plotted. In this case, no error is returned. Otherwise, a PAR__NULL error status is returned if a null value is supplied.
XL = REAL (Given)
The default value for the XLEFT parameter. If VAL__BADR is supplied, the minimum of the X values is used (plus a small margin).
XR = REAL (Given)
The default value for the XRIGHT parameter. If VAL__BADR is supplied, the maximum of the X values is used (plus a small margin).
YB = REAL (Given)
The default value for the YBOT parameter. If VAL__BADR is supplied, the minimum of the low end of the Y error bars is used (plus a small margin).
YT = REAL (Given)
The default value for the YTOP parameter. If VAL__BADR is supplied, the maximum of the high end of the Y error bars is used (plus a small margin).
APP = CHARACTER ∗ ( ∗ ) (Given)
The name of the application in the form " <package >_ <application >" , for instance " KAPPA_NORMALIZE" .
QUIET = LOGICAL (Given)
If .FALSE., a message is displayed indicating the number of points which were plotted. If .TRUE., nothing is displayed on the alpha screen.
LMODE = LOGICAL (Given)
If .TRUE., then the user is given the chance to specify the default vertical bounds for the plot using Parameter LMODE. If .FALSE., the supplied bounds (YB, YT ) are used, and the equivalent of " Extended" LMODE is used for any bounds that are not supplied.
BSCALE( 2 ) = DOUBLE PRECISION (Given)
Scale factors which converts the supplied (x,y) values into the values to label on the plot. A similar BZERO argument could be added if there is ever a need.
DX( N ) = DOUBLE PRECISION (Given and Returned)
Work space.
DY( N ) = DOUBLE PRECISION (Given and Returned)
Work space.
DBAR( N, 2 ) = DOUBLE PRECISION (Given and Returned)
Work space. Not accessed if NSIGMA is zero.
IPLOT = INTEGER (Given and Returned)
On entry, this can either be AST_NULL or a pointer to a two-dimensional Frame. If AST__NULL, the supplied values for the XLAB, YLAB, TTL, XSYM and YSYM arguments are used without change. If a Frame is supplied, the Label, Title, Units, and Symbol attributes of the Frame are used in preference to XLAB, YLAB, TTL, XSYM and YSYM (which are then ignored). Any supplied Frame pointer is annulled before returning, and a pointer to the Plot used to draw the axes is returned.
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Environment Parameters :

AXES = _LOGICAL (Read)
TRUE if annotated axes are to be produced.
CLEAR = _LOGICAL (Read)
TRUE if the graphics device is to be cleared on opening.
DEVICE = DEVICE (Read)
The plotting device.
LMODE = LITERAL (Read)
If the subroutine argument LMODE is .TRUE., then Parameter LMODE is used to specify how the default values for YBOT and YTOP are found. If argument LMODE is .FALSE. then " Extended" mode is always used. This parameter can take the following values:

  • " Range" – The lowest and highest supplied data values are used (including error bars).

  • " Extended" – The lowest and highest supplied data values are used (including error bars), extended to give a margin of 2.5% of the total data range at each end.

  • " Extended,10,5" – Like " Extended" , except the margins at the two ends are specified as a pair of numerical value in the second and third elements of the array. These values are percentages of the total data range. So, " Extended,10,5" includes a margin of 10% of the total data range in YBOT, and 5% in YTOP. If only one numerical value is given, the same value is used for both limits. If no value is given, both limits default to 2.5. " Range" is equivalent to " Extended,0,0" .

  • " Percentiles,5,95" – The second and third elements of the array are interpreted as percentiles. For instance, " Perc,5,95" causes 5% of the data points (ignoring error bars) to be below YBOT, and 10% to be above the YTOP. If only one value (p1) is supplied, the other one, p2, defaults to (100 - p1). If no values are supplied, p1 and p2 default to 5 and 95.

  • " Sigma,2,3" – The second and third elements of the array are interpreted as multiples of the standard deviation of the data values (ignoring error bars). For instance, " S,2,3" causes the YBOT to be the mean of the data values, minus two sigma, and YTOP to be the mean plus three sigma. If only one value is supplied, the same value is used for both limits. If no values are supplied, both values default to 3.0.

The above strings can be abbreviated to one character.

MARGIN( 4 ) = _REAL (Read)
The widths of the margins to leave for axis annotation, given as fractions of the corresponding dimension of the current picture. Four values may be given in the order bottom, right, top, left. If fewer than four values are given, extra values are used equal to the first supplied value. If these margins are too narrow any axis annotation may be clipped. The dynamic default is 0.15 (for all edges) if either annotated axes or a key are produced, and zero otherwise.
MARKER = _INTEGER (Read)
The PGPLOT marker type to use. Only accessed if MODE is 3 or 5.
STYLE = GROUP (Read)
A description of the plotting style required. The following synonyms for graphical elements may be used.

  • " Err(Bars)" – Specifies colour, etc. for error bars. Size(errbars) scales the size of the serifs (i.e. a size value of 1.0 produces a default size).

  • " Sym(bols)" – Specifies colour, etc. for markers (used in Modes 3 and 5).

  • " Lin(es)" – Specifies colour, etc. for lines (used in Modes 1, 2, and 5).

TEMPSTYLE = GROUP (Read)
A description of plotting style required in addition to that define by STYLE. See STYLE for allowed synonyms. Unlike STYLE its values are not persistent between invocations.
XLEFT = _DOUBLE (Read)
The axis value to place at the left-hand end of the horizontal axis. The dynamic default is specified by argument XL. The value supplied may be greater than or less than the value supplied for XRIGHT.
XRIGHT = _DOUBLE (Read)
The axis value to place at the right-hand end of the horizontal axis. The dynamic default is specified by argument XR. The value supplied may be greater than or less than the value supplied for XLEFT.
YBOT = _DOUBLE (Read)
The axis value to place at the bottom end of the vertical axis. The dynamic default is specified by argument YB. The value supplied may be greater than or less than the value supplied for YTOP.
YTOP = _DOUBLE (Read)
The axis value to place at the top end of the vertical axis. The dynamic default is specified by argument YT. The value supplied may be greater than or less than the value supplied for YBOT.