Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_plot_histogram (g01aj)

## Purpose

nag_stat_plot_histogram (g01aj) prints a histogram on a character printing device, allowing you control over size, positioning, and the range of data values included.

## Syntax

[xstep, n1, multy, ifail, nstepx, nstepy, ispace, xmin, xmax] = g01aj(x, nstepx, nstepy, 'n', n, 'itype', itype, 'ispace', ispace, 'xmin', xmin, 'xmax', xmax)
[xstep, n1, multy, ifail, nstepx, nstepy, ispace, xmin, xmax] = nag_stat_plot_histogram(x, nstepx, nstepy, 'n', n, 'itype', itype, 'ispace', ispace, 'xmin', xmin, 'xmax', xmax)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 23: xmin now optional (default 0), xmax now optional (default 0), ispace now optional (default 0), itype now optional (default 0), output parameters have been reordered
.

## Description

A histogram is printed using vertical bars consisting of * characters. The output is directed to the current advisory message unit. It may be redirected by a call to nag_file_set_unit_advisory (x04ab) before calling nag_stat_plot_histogram (g01aj).
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$9999.99$ in modulus, in which case they are not printed (although they are still returned).

None.

## Parameters

### Compulsory Input Parameters

1:     x(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The data values.
2:     nstepx – int64int32nag_int scalar
The number of character positions to be used in the horizontal direction, i.e., the number of categories in the histogram.
3:     nstepy – int64int32nag_int scalar
The number of character positions to be used in the vertical direction, i.e., the maximum height of a histogram bar.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array x.
The number of data values.
Constraint: n1${\mathbf{n}}\ge 1$.
2:     itype – int64int32nag_int scalar
Indicates whether a histogram of frequencies or cumulative frequencies is required.
itype = 0${\mathbf{itype}}=0$ for frequencies.
itype0${\mathbf{itype}}\ne 0$ for cumulative frequencies.
The second option effectively displays the distribution function of the data rather than the density function.
Default: 0$0$
3:     ispace – int64int32nag_int scalar
Indicates how many spaces are to be inserted at the beginning of each output line.
If ispace < 0${\mathbf{ispace}}<0$ on input, ispace = 0${\mathbf{ispace}}=0$ is used
If ispace + nstepx + 14 > 120${\mathbf{ispace}}+{\mathbf{nstepx}}+14>120$, then ispace = 0${\mathbf{ispace}}=0$ is used.
The second condition imposes an effective line length limit of 120$120$ characters.
Default: 0$0$
4:     xmin – double scalar
5:     xmax – double scalar
If ${\mathbf{xmin}}<{\mathbf{xmax}}$, only those values in x such that xminx(i)xmax${\mathbf{xmin}}\le {\mathbf{x}}\left(\mathit{i}\right)\le {\mathbf{xmax}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$, are included in the histogram.
If ${\mathbf{xmin}}\ge {\mathbf{xmax}}$, all the data are included.
Default: 0$0$

None.

### Output Parameters

1:     xstep – double scalar
The width of each class interval.
2:     n1 – int64int32nag_int scalar
The total number of observations actually included in the histogram.
3:     multy – int64int32nag_int scalar
The number of observations represented by each * in the histogram.
4:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).
5:     nstepx – int64int32nag_int scalar
If nstepx < 10${\mathbf{nstepx}}<10$ on entry, nstepx is reset to 10$10$.
If nstepx > 99${\mathbf{nstepx}}>99$ on entry, nstepx is reset to 99$99$.
Otherwise, nstepx is unchanged on exit.
6:     nstepy – int64int32nag_int scalar
If nstepy < 10${\mathbf{nstepy}}<10$ on entry, nstepy is reset to 10$10$.
If nstepy > 99${\mathbf{nstepy}}>99$ on entry, nstepy is reset to 99$99$.
Otherwise, nstepy is unchanged on exit.
7:     ispace – int64int32nag_int scalar
Default: 0$0$
Unchanged unless ispace < 0${\mathbf{ispace}}<0$ or ispace + nstepx + 14 > 120${\mathbf{ispace}}+{\mathbf{nstepx}}+14>120$, in which case ispace is set to 0$0$.
8:     xmin – double scalar
9:     xmax – double scalar
Default: 0$0$
If ${\mathbf{xmin}}<{\mathbf{xmax}}$ on entry, then xmin and xmax are unchanged.
If ${\mathbf{xmin}}\ge {\mathbf{xmax}}$ then xmin and xmax contain the minimum and maximum data values respectively.

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 1${\mathbf{n}}<1$.

## Accuracy

Accuracy is limited by the number of plotting positions available.

The time taken by nag_stat_plot_histogram (g01aj) increases with n, nstepx and nstepy.
A total of (nstepx + ispace + 14)$\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 (nstepy + 3)$\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.

## Example

```function nag_stat_plot_histogram_example
x = [2.68;
8.23;
0.11;
1.39;
-2.77;
-1.17;
3.49;
7.39;
5.22;
5.44;
7.06;
6.17;
-4.44;
5.98;
14.02;
8.06;
10.96;
0.99;
7.87;
4.85;
9.76;
3.3;
4.45;
7.02;
5.43;
3.57;
1.98;
3.09;
-2.66;
5.04;
14.52;
-0.61;
5.04;
6.85;
3.94;
4.87;
3.82;
5.93;
7.89;
9.48;
6.81;
6.91;
7.76;
6.21;
0.55;
-2.44;
18.09;
6.19;
9.19;
10.55];
nstepx = int64(10);
nstepy = int64(10);
ispace = int64(10);
[xstep, n1, multy, ifail, nstepxOut, nstepyOut, ispaceOut, xminOut, xmaxOut] = ...
nag_stat_plot_histogram(x, nstepx, nstepy, 'ispace', ispace)
```
```
FREQUENCY
20  .          .   20
18  .          .   18
16  .          .   16
14  .          .   14
12  .    *     .   12
10  .    **    .   10
8  .   ***    .    8
6  .   ***    .    6
4  .* *****   .    4
2  .******* * .    2
------------
-4.44    18.09

xstep =

2.2530

n1 =

50

multy =

2

ifail =

0

nstepxOut =

10

nstepyOut =

10

ispaceOut =

10

xminOut =

-4.4400

xmaxOut =

18.0900

```
```function g01aj_example
x = [2.68;
8.23;
0.11;
1.39;
-2.77;
-1.17;
3.49;
7.39;
5.22;
5.44;
7.06;
6.17;
-4.44;
5.98;
14.02;
8.06;
10.96;
0.99;
7.87;
4.85;
9.76;
3.3;
4.45;
7.02;
5.43;
3.57;
1.98;
3.09;
-2.66;
5.04;
14.52;
-0.61;
5.04;
6.85;
3.94;
4.87;
3.82;
5.93;
7.89;
9.48;
6.81;
6.91;
7.76;
6.21;
0.55;
-2.44;
18.09;
6.19;
9.19;
10.55];
nstepx = int64(10);
nstepy = int64(10);
ispace = int64(10);
[xstep, n1, multy, ifail, nstepxOut, nstepyOut, ispaceOut, xminOut, xmaxOut] = ...
g01aj(x, nstepx, nstepy, 'ispace', ispace)
```
```
FREQUENCY
20  .          .   20
18  .          .   18
16  .          .   16
14  .          .   14
12  .    *     .   12
10  .    **    .   10
8  .   ***    .    8
6  .   ***    .    6
4  .* *****   .    4
2  .******* * .    2
------------
-4.44    18.09

xstep =

2.2530

n1 =

50

multy =

2

ifail =

0

nstepxOut =

10

nstepyOut =

10

ispaceOut =

10

xminOut =

-4.4400

xmaxOut =

18.0900

```