NAG Toolbox: nag_stat_plot_stem_leaf (g01ar)

Purpose

Syntax

Description

1  1  8
3  1  99
5  2  00
5  2  111
2  2
2  2  3
1  2  4

 1   1.  9
 1   1*
 1  -0.
 3  -0*  13
15  +0*  012233344444
15  +0.  55556667788
 5   1*  011
 2   1.  3
 1   2
 1   2.
 1   3   1

      LO   -19

  2   -0*  3
  3   +0T  1
  5   +0*  01
 10   +0T  22333
( 9)  +0F  444445555
 11   +0*  66677
  6   +0T  8
  5    1*  011
  2    1T  3

      HI   31

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{y}\left(\mathbf{n}\right)$ – double array

The $n$ observations.

2:     $\mathrm{nstepx}$ – int64int32nag_int scalar

The number of character positions to be plotted horizontally.

Constraint: $\mathbf{nstepx}\ge 35$.

3:     $\mathrm{nstepy}$ – int64int32nag_int scalar

The maximum number of character positions to be plotted vertically.

If $\mathbf{nstepy}\le 0$ a suitable value will be used by nag_stat_plot_stem_leaf (g01ar) for the number of character positions to be plotted vertically. This will clearly be less than or equal to the value of ldplot.

Constraint: $\mathbf{nstepy}\le 0$ or $\mathbf{nstepy}\ge 5$.

Optional Input Parameters

1:     $\mathrm{range}$ – string (length ≥ 1)

Default: $\text{'E'}$

Indicates whether you wish to scale the plot to the extremes of the data or to the fences.

$\mathbf{range}=\text{'E'}$

The display is a plot to the extremes, that is a plot of all the data.

$\mathbf{range}=\text{'F'}$

The display is a plot of the data between the fences.

Constraint: $\mathbf{range}=\text{'E'}$ or $\text{'F'}$.

2:     $\mathrm{prt}$ – string (length ≥ 1)

Default: $\text{'P'}$

Indicates whether the stem and leaf display is to be output to an external file.

$\mathbf{prt}=\text{'N'}$

The display is not output to an external file.

$\mathbf{prt}=\text{'P'}$

The display is output to the current advisory message unit as defined by nag_file_set_unit_advisory (x04ab). Only the first $132$ characters of each line are actually printed.

Constraint: $\mathbf{prt}=\text{'P'}$ or $\text{'N'}$.

3:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the array y.

$n$, the number of observations.

Constraint: $\mathbf{n}\ge 2$.

4:     $\mathrm{unit}$ – double scalar

Default: $0$

Indicates the leaf digit unit to be used.

If $\mathbf{unit}>0.0$ and is not a power of ten, it will be converted to the nearest power of ten below the input value for unit.

If $\mathbf{unit}\le 0.0$, the optimum unit will be used. This is based on the range of the data to be plotted and the number of lines available for the display.

Output Parameters

1:     $\mathrm{unit}$ – double scalar

Default: $0$

Contains the actual unit used in the stem and leaf display.

2:     $\mathrm{lines}$ – int64int32nag_int scalar

The actual number of lines needed for the display.

3:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

4:     $\mathrm{plot}\left(\mathit{ldplot},\mathbf{nstepx}\right)$ – cell array of strings

The stem and leaf display.

5:     $\mathrm{sorty}\left(\mathbf{n}\right)$ – double array

The observations sorted into ascending order.

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}<2$,
or	$\mathbf{nstepx}<35$,
or	$0<\mathbf{nstepy}<5$,
or	$\mathit{ldplot}<5$,
or	$\mathit{ldplot}<\mathbf{nstepy}$.

   $\mathbf{ifail}=2$

On entry,	$\mathbf{prt}\ne \text{'P'}$ or $\text{'N'}$,
or	$\mathbf{range}\ne \text{'E'}$ or $\text{'F'}$.

   $\mathbf{ifail}=3$

The number of lines needed to produce the display exceeds the maximum number of lines allowed. You may wish to increase nstepy.

   $\mathbf{ifail}=4$

One of the observations is too large and causes a value to exceed the maximum integer allowed.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g01ar_example

function g01ar_example


fprintf('g01ar example results\n\n');

y = [31;  1;   2;   3;    4;     5;     6;     7;     8;    -9;
          1;   2;   3;    4;     5;     6;     7;     8;
               2;   3;    4;     5;     6;     7;
                    3;    4;     5;     6;
                          4;     5];
nstepx = int64(72);
nstepy = int64(20);

[unit, lines, ifail, plot, sorty] = ...
  g01ar( ...
	 y, nstepx, nstepy, 'range', 'Fences');

[unit, lines, ifail, plot, sorty] = ...
  g01ar( ...
	 y, nstepx, nstepy, 'range', 'Extremes', 'prt', 'Noprint');

fprintf('\n');
for i = 1:lines
  fprintf('%s\n', char(plot(i,1:nstepx)));
end

g01ar example results

 Stem-and-leaf display
 Leaf digit unit = 1.0
 1  2  represents  12.

       LO  -9

   3    0  11
   6    0  222
  10    0  3333
  15    0  44444
  15    0  55555
  10    0  6666
   6    0  777
   3    0  88

       HI  31

Stem-and-leaf display                                                   
Leaf digit unit = 1.0                                                   
1  2  represents  12.                                                   
                                                                        
  1    -0. 9                                                            
  1    -0*                                                              
 15    +0* 11222333344444                                               
 15    +0. 55555666677788                                               
  1     1*                                                              
  1     1.                                                              
  1     2*                                                              
  1     2.                                                              
  1     3* 1