NAG Library Routine Document
g01ajf (withdraw_plot_histogram)
1
Purpose
g01ajf prints a histogram on a character printing device, allowing you control over size, positioning, and the range of data values included.
2
Specification
Fortran Interface
Subroutine g01ajf ( 
x, n, nstepx, nstepy, itype, ispace, xmin, xmax, xstep, n1, multy, ifail) 
Integer, Intent (In)  ::  n, itype  Integer, Intent (Inout)  ::  nstepx, nstepy, ispace, ifail  Integer, Intent (Out)  ::  n1, multy  Real (Kind=nag_wp), Intent (In)  ::  x(n)  Real (Kind=nag_wp), Intent (Inout)  ::  xmin, xmax  Real (Kind=nag_wp), Intent (Out)  ::  xstep 

C Header Interface
#include <nagmk26.h>
void 
g01ajf_ (const double x[], const Integer *n, Integer *nstepx, Integer *nstepy, const Integer *itype, Integer *ispace, double *xmin, double *xmax, double *xstep, Integer *n1, Integer *multy, Integer *ifail) 

3
Description
A histogram is printed using vertical bars consisting of * characters. The output is directed to the current advisory message unit (see the
Users' Note for your implementation). It may be redirected by a call to
x04abf before calling
g01ajf.
The following options are available:
(a) 
inclusion of all data values, or only of those lying within a specified range; 
(b) 
specification of the size of the histogram in the vertical and horizontal directions, and of positioning in the horizontal direction; 
(c) 
calculation of frequencies or cumulative frequencies in the histogram. 
The maximum and minimum data values used, the (integral) number of observations represented by each * in the histogram, and the step size per character position in the horizontal direction, are returned.
The histogram is headed FREQUENCY or CUM.FREQ. depending on the option selected. Each line is annotated with the minimum frequency which a bar reaching that line represents. The data maximum and minimum are printed under the histogram, unless either exceeds $9999.99$ in modulus, in which case they are not printed (although they are still returned).
4
References
None.
5
Arguments
 1: $\mathbf{x}\left({\mathbf{n}}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the data values.
 2: $\mathbf{n}$ – IntegerInput

On entry: the number of data values.
Constraint:
${\mathbf{n}}\ge 1$.
 3: $\mathbf{nstepx}$ – IntegerInput/Output

On entry: the number of character positions to be used in the horizontal direction, i.e., the number of categories in the histogram.
On exit: if
${\mathbf{nstepx}}<10$ on entry,
nstepx is reset to
$10$.
If
${\mathbf{nstepx}}>99$ on entry,
nstepx is reset to
$99$.
Otherwise,
nstepx is unchanged on exit.
 4: $\mathbf{nstepy}$ – IntegerInput/Output

On entry: the number of character positions to be used in the vertical direction, i.e., the maximum height of a histogram bar.
On exit: if
${\mathbf{nstepy}}<10$ on entry,
nstepy is reset to
$10$.
If
${\mathbf{nstepy}}>99$ on entry,
nstepy is reset to
$99$.
Otherwise,
nstepy is unchanged on exit.
 5: $\mathbf{itype}$ – IntegerInput

On entry: indicates whether a histogram of frequencies or cumulative frequencies is required.
${\mathbf{itype}}=0$ for frequencies.
${\mathbf{itype}}\ne 0$ for cumulative frequencies.
The second option effectively displays the distribution function of the data rather than the density function.
 6: $\mathbf{ispace}$ – IntegerInput/Output

On entry: indicates how many spaces are to be inserted at the beginning of each output line.
If ${\mathbf{ispace}}<0$ on input, ${\mathbf{ispace}}=0$ is used
If ${\mathbf{ispace}}+{\mathbf{nstepx}}+14>120$, ${\mathbf{ispace}}=0$ is used.
The second condition imposes an effective line length limit of $120$ characters.
On exit: unchanged unless
${\mathbf{ispace}}<0$ or
${\mathbf{ispace}}+{\mathbf{nstepx}}+14>120$, in which case
ispace is set to
$0$.
 7: $\mathbf{xmin}$ – Real (Kind=nag_wp)Input/Output
 8: $\mathbf{xmax}$ – Real (Kind=nag_wp)Input/Output

On entry: if
${\mathbf{xmin}}<{\mathbf{xmax}}$, only those values in
x such that
${\mathbf{xmin}}\le {\mathbf{x}}\left(\mathit{i}\right)\le {\mathbf{xmax}}$, for
$\mathit{i}=1,2,\dots ,n$, are included in the histogram.
If ${\mathbf{xmin}}\ge {\mathbf{xmax}}$, all the data are included.
On exit: if
${\mathbf{xmin}}<{\mathbf{xmax}}$ on entry,
xmin and
xmax are unchanged.
If
${\mathbf{xmin}}\ge {\mathbf{xmax}}$ then
xmin and
xmax contain the minimum and maximum data values respectively.
 9: $\mathbf{xstep}$ – Real (Kind=nag_wp)Output

On exit: the width of each class interval.
 10: $\mathbf{n1}$ – IntegerOutput

On exit: the total number of observations actually included in the histogram.
 11: $\mathbf{multy}$ – IntegerOutput

On exit: the number of observations represented by each * in the histogram.
 12: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}\ge 1$.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
Accuracy is limited by the number of plotting positions available.
8
Parallelism and Performance
g01ajf is not threaded in any implementation.
The time taken by
g01ajf increases with
n,
nstepx and
nstepy.
A total of $\left({\mathbf{nstepx}}+{\mathbf{ispace}}+14\right)$ character positions are used in the horizontal direction, not including the carriage control character. It is important that this total does not exceed the maximum line length available on the output device.
A total of
$\left({\mathbf{nstepy}}+3\right)$ output lines are normally generated, one less if
xmin and/or
xmax is too large in modulus to be printed.
10
Example
A sample of
$50$ random numbers form the data, which correspond to a Normal distribution with mean and standard deviation both equal to
$5.0$. A histogram of the entire sample is drawn first, followed by a cumulative histogram of all data values lying between
$10.0$ and
$5.0$. The first histogram is indented
$10$ character positions. Note the use of
x04abf to direct the output to unit number
$6$.
10.1
Program Text
Program Text (g01ajfe.f90)
10.2
Program Data
Program Data (g01ajfe.d)
10.3
Program Results
Program Results (g01ajfe.r)