NAT'L INST. OF STAND & TECH

A111DS Tt.fib77

o

Reference

\

*<"»fAU of *

\

*

NBS

Publications

NBS TECHNICAL NOTE 1068-1

U.S. DEPARTMENT OF COMMERCE / National Bureau of Standards
NATIONAL BUREAU OF STANDARDS

The National Bureau of Standards' was established by an act of Congress on March 3, 1901. The Bureau's overall goal is to strengthen and advance the Nation's science and technology

and facilitate their effective application for public benefit. To this end, the Bureau conducts

research and provides: (1) a basis for the Nation's physical measurement system, (2) scientific and technological services for industry and government, (3) a technical basis tor equity in trade, and (4) technical services to promote public safety. The Bureau's technical work is per- formed by the National Measurement Laboratory, the National Engineering Laboratory, and

the Institute for Computer Sciences and Technology.

THE NATIONAL MEASUREMENT LABORATORY provides the national system of

physical and chemical and materials measurement; coordinates the system with measurement

systems of other nations and furnishes essential services leading to accurate and uniform

physical and chemical measurement throughout the Nation's scientific community, industry,

and commerce; conducts materials research leading to improved methods ot measurement,

standards, and data on the properties of materials needed by industry, commerce, educational

institutions, and Government; provides advisory and research services to other Government

agencies; develops, produces, and distributes Standard Reference Materials; and provides

calibration services. The Laboratory consists of the following centers:

Absolute Physical Quantities 2 — Radiation Research — Chemical Physics —

Analytical Chemistry — Materials Science

THE NATIONAL ENGINEERING LABORATORY provides technology and technical ser- vices to the public and private sectors to address national needs and to solve national problems; conducts research in engineering and applied science in support of these efforts; builds and maintains competence in the necessary disciplines required to carry out this research and technical service; develops engineering data and measurement capabilities;

provides engineering measurement traceability services; develops test methods and proposes

engineering standards and code changes; develops and proposes new engineering practices;

and develops and improves mechanisms to transfer results of its research to the ultimate user. The Laboratory consists of the following centers:

Applied Mathematics — Electronics and Electrical Engineering2 — Manufacturing

Engineering — Building Technology -- Fire Research — Chemical Engineering2

THE INSTITUTE FOR COMPUTER SCIENCES AND TECHNOLOGY conducts

research and provides scientific and technical services to aid Federal agencies in the selection, acquisition, application, and use of computer technology to improve effectiveness and

economy in Government operations in accordance with Public Law 89-306 (40 U.S.C. 759), relevant Executive Orders, and other directives; carries out this mission by managing the Federal Information Processing Standards Program, developing Federal ADP standards

guidelines, and managing Federal participation in ADP voluntary standardization activities; provides scientific and technological advisory services and assistance to Federal agencies; and

provides the technical foundation for computer-related policies of the Federal Government.

The Institute consists of the following centers:

Programming Science and Technology — Computer Systems Engineering.

'Headquarters and Laboratories at Gaithersburg, MD, unless otherwise noted; mailing address Washington, DC 20234. 'Some divisions within the center are located at Boulder, CO 80303.
Introduction to STARPAC i*

The Standards Time Series

and Regression Package

Janet R. Donaldson

Peter V. Tryon

Statistical Engineering Division

Center for Applied Mathematics

National Engineering Laboratory

National Bureau of Standards

Boulder, Colorado 80303

-j7h;q

U.S. DEPARTMENT OF COMMERCE. Malcolm Baldrige. Secretary

NATIONAL BUREAU OF STANDARDS. Ernest Ambler. Director

Issued October 1983
National Bureau of Standards Technical Note 1068-1

Natl. Bur. Stand. (U.S.), Tech. Note 1068-1, 24 pages (Oct. 1983)

CODEN: NBTNAE

U.S. GOVERNMENT PRINTING OFFICE

WASHINGTON: 1983

For sale by the Superintendent of Documents, U.S. Government Printing Office, Washington, DC 20402

Price $3.00

(Add 25 percent for other than U.S. mailing)
Disclaimer

No warranties } express or implied3 are made

by the distributors or developers that

STARPAC or its constituent parts are free of

error. They should not he relied upon as the sole basis for solving a problem whose

incorrect solution could result in injury to

person or property . If the programs are employed in such a manner^ it is at the

user's own risk and the distributors and

developers disclaim all liability for such

misuse.

Computers have been identified in this paper

in order to adequately specify the sample

programs and test results. Such

identification does not imply recommendation

or endorsement by the National Bureau of

Standards s nor does it imply that the

equipment identified, is necessarily the best

available for the purpose.

iii

Preface

STARPAC, the Standards Time Series and Regression Package, is a library

of Fortran subroutines for statistical data analysis developed by the

Statistical Engineering Division (SED) of the National Bureau of Standards

(NBS), Boulder, Colorado. Earlier versions of this library were distributed

by the SED under the name STATLIB [Tryon and Donaldson, 1978] . STARPAC

incorporates many changes to STATLIB, including additional statistical

techniques, improved algorithms and enhanced portability.

We are releasing STARPAC source code in segments and the documentation as

a series of NBS Technical Notes. This will allow us to make the new capabilities of STARPAC available more quickly and to facilitate the release

of future changes. This Note gives an overview of the STARPAC library,

defines conventions used in the documentation, provides an example using

STARPAC subroutines, and presents general background material. It includes

information which is essential for using the STARPAC library, and users should

be familiar with its contents before attempting to use any STARPAC

subroutine.

The STARPAC code segments consist of subroutines for nonlinear least

squares regression, time series analysis (in both time and frequency domains)

,

line printer graphics, basic statistical analysis, linear least squares

regression, and nonlinear optimization. Users may obtain a list of the

available code segments and their associated documentation from their local

installer of STARPAC, or directly from the author.

STARPAC subroutines feature:

• ease of use, alone and with other Fortran subroutine libraries;

• extensive error handling facilities;

• comprehensive printed reports;

• no problem size restrictions other than effective machine size; and

• portability.

Notation, format, and naming conventions will remain constant throughout

the series of Technical Notes documenting STARPAC, allowing the documentation

for each code segment to be used alone or in conjunction with the

documentation for another.

The code for STARPAC was developed at the U.S. Department of Commerce

Boulder Laboratories on a CDC CYBER 170/750 under NOS 1.4, and all examples

presented in this documentation were executed in this environment using the

FTN 4.8+552 compiler with rounding. STARPAC has also been tested on the

following equipment.
Computer Facility

IBM 4340 National Center for Atmospheric Research,

VAX 11/780 Boulder, Colorado

Sperry 1100/82 National Bureau of Standards,

Gaithersburg, Maryland

Perkin-Elmer 3230 National Bureau of Standards,

Boulder, Colorado

Data General ECLIPSE S/140 Forest Fire Laboratory,

Riverside, California

STARPAC is written in Fortran '66. Adherence to a portable subset of

ANSI Fortran [1966] has been verified bv the PFORT Verifier [Ryder, 1974].

Workspace and machine-dependent constants are supplied using subroutines based

on the Bell Laboratories "Framework for a Portable Library" [Fox et al. , 1978a]. We have also used subroutines from LINPAQK [Dongarra et al. , 1979],

from the "Basic Linear Algebra Subprograms for Fortran Usage" [Lawson et al. , 1979], and from DATAPAC [Filliben, 1977]. The printed report generated by the

statistical analysis subroutines has been adapted from OMNITAR II [Hogben et

al. , 1971] .

Computer facilities for the STARPAC project have been provided in part by

the NOAA Computer Services Division, Boulder, Colorado, and we gratefully

acknowledge their support. The STARPAC subroutine library is the result of

the programming efforts of Janet R. Donaldson and John E. Koontz, with

assistance from Ginger A. Caldwell, Steven M. Keefer, and Linda L. Mitchell.

Valuable contributions have also been made by each of the members of the

Statistical Engineering Division in Boulder, and from many within the STARPAC

user community. We are grateful for the many valuable comments that we have

received on early drafts of the STARPAC documentation; we wish especially to

thank Paul T. Boggs, Ginger A. Caldwell, Sally E. Howe, John E. Koontz, James

T. Ringland, Ralph M. Slutz, and Dominic F. Vecchia. Finally, we wish to

thank Lorna Buhse for excellent manuscript support.

Janet R. Donaldson

Peter V. Tryon (deceased)

September 1983

VI
Contents

Preface v

1. Introduction to Using STARPAC 1-1.1

A. Overview of STARPAC and Its Contents 1-1.1

B . Documentation Conventions 1-1 .

C . A Sample Program 1-1 . 2

D . Us ing STARPAC 1-1.6

D.l The PROGRAM Statement 1-1.6

D.2 The Dimensioning Statements 1-1.6

D.3 The CALL Statements 1-1.8

D.4 STARPAC Output 1-1.8

D.5 STARPAC Error Handling 1-1.9

D.6 Common Programming Errors When Using STARPAC... 1-1.10

References 1-R.l

vii

Introduction

to

STARPAC

The Standards Time Series and Regression Package

Janet R. Donaldson and Peter V. Tryon

National Bureau of Standards

Washington, DC 20234

STARPAC, the Standards Time Series and Regression Package, is a library of Fortran subroutines for statistical data analysis

developed by the Statistical Engineering Division (SED) of the

National Bureau of Standards (NBS), Boulder, Colorado. Earlier

versions of this library were distributed by the SED under the name STATLIB [Tryon and Donaldson, 1978]. STARPAC incorporates many

changes to STATLIB, including additional statistical techniques,

improved algorithms and enhanced portability.

STARPAC emphasizes the statistical interpretation of results,

and, for this reason, comprehensive printed reports of auxiliary

statistical information, often in graphical form, are automatically

provided to augment the basic statistical computations performed by

each user-callable STARPAC subroutine. STARPAC thus provides the

best features of many stand-alone statistical software programs

within the flexible environment of a subroutine library.

STARPAC documentation is being published as a series of

Technical Notes. This Note is the first in the series. It gives an overview of the STARPAC library, defines conventions used in the

documentation, provides an example using STARPAC subroutines, and

presents general background material. This Note includes

information which is essential for using the STARPAC library, and

users should be familiar with its contents before attempting to use

any STARPAC subroutine.

Key words: data analysis; STARPAC; STARPAC overview; statistical

computing; statistical subroutine library; STATLIB.

ix

CHAPTER 1

INTRODUCTION TO USING STARPAC

A. Overview of STARPAC and Its Contents

STARPAC is a portable library of approximately 150 user-callable ANSI '66

Fortran subroutines for statistical data analysis. Designed primarily for

time series analysis and for nonlinear least squares regression, STARPAC also

includes subroutines for normal random number generation, line printer plots,

basic statistical analyses, linear least squares regression, and nonlinear

optimization. Emphasis has been placed on facilitating the interpretation of

statistical analyses, and, for this reason, comprehensive printed reports of

auxiliary statistical information, often in graphical form, are automatically

provided to augment the basic statistical computations performed by each

user-callable STARPAC subroutine. STARPAC thus provides the best features of

many stand-alone statistical software programs within the flexible environment

of a subroutine library.

STARPAC is designed to be easy to use; in many situations, only a few

lines of elementary Fortran code are required for the users' main programs. A

fundamental STARPAC philosophy is to provide two or more user-callable

subroutines for each method of analysis: one which minimizes the complexity

of the CALL statement, automatically producing a comprehensive printed report

of the results; and one or more others which provide user control of the

computations, allow suppression of all or part of the printed reports, and/or

provide storage of computed results for further analyses.

STARPAC has been developed and is maintained by the Statistical

Engineering Division of the National Bureau of Standards, Boulder, Colorado.

It is intended that STARPAC be a continually evolving library that will keep

pace with new developments in statistical methods, and will respond to the

ever-changing needs of the National Bureau of Standards. Users' comments and

suggestions, which have had significant impact already, are highly valued and

always welcomed. Comments and suggestions should be directed to:

Janet R. Donaldson

National Bureau of Standards

Mail Code 714

325 Broadway

Boulder, CO 80303.

B. Documentation Conventions

The documentation for the various STARPAC subroutines is being published

as a series of Technical Notes. Each Note in the series provides a standard

format description of the information needed to use a STARPAC subroutine,

including one or more examples.

1-1.1
References to chapter sections within the STARPAC documentation are made

using the symbol §, and refer to the identified section within the current

chapter of the current Note unless explicitly stated otherwise. Figures are identified by the section in which they occur. For example, figure C-2 refers

to the second figure in §C of the current chapter of this Note.

Names of INTEGER and REAL STARPAC subroutine arguments are consistent

with the implicit Fortran convention for specifying variable type. That is,

variable names beginning with I through N are type INTEGER while all others

are type REAL unless otherwise explicitly typed DOUBLE PRECISION or COMPLEX.

All dimensioned variables are explicitly declared in STARPAC documentation by

means of INTEGER, REAL, DOUBLE PRECISION, or COMPLEX statements, as appropriate. The convention used to specify the dimensioning statements is

discussed below in Sd . 2

The STARPAC library is available in either single or double precision

versions, and users should consult with their computing center staff or appropriate local documentation to determine which version they are using.

The precision of the STARPAC library is also indicated in the printed reports

generated by STARPAC: an S following the STARPAC version number in the output

heading indicates the single precision version is being used, while a D

indicates the double precision version. The STARPAC documentation is designed

for use with both the single and double precision versions. Subroutine

arguments which are double precision in both versions are declared DOUBLE

PRECISION; similarly, arguments which are single precision in both versions

are declared REAL. Arguments whose precision is dependent upon the precision

of the version of STARPAC being used are declared <real>. If the double

precision version of the STARPAC library is being used, then the user should

substitute DOUBLE PRECISION for <real>; if the single precision version is

being used, then the user should substitute REAL for <real>. Other precision

dependent features are discussed as they occur.

C . A Sample Program

The sample program shown in figure C-l illustrates the use of STARPAC

subroutines. This example was executed on the CYBER 170/750 at the U.S.

Department of Commerce Boulder Laboratories under the NOS 1.4 operating system

using a single precision version of the STARPAC library. The code shown is

portable ANSI '66 Fortran, except for the PROGRAM statement which is required

by most Fortran compilers on CDC machines. Section D below uses this example

to discuss Fortran programming as it relates to STARPAC.

The data used in this example are 84 relative humidity measurements taken

at Pikes Peak, Colorado. STARPAC subroutine PP plots the data versus time-order (fig. C-2) and STARPAC subroutine STAT prints a comprehensive

statistical analysis of the data (fig. C-3)

1-1.2
MAIN PR06RANI PROGRAM EXAMPL (INPUT* OUTPUT. TAPE5 - INPUT» TAPE6 • OUTPUT)

C REAL Y(IOO), X(IOO) DOUBLE PRECISION DSTAK(IOO)

C COMMON /CSTAK/ OSTAK COMMON /ERRCHK/ IERR

C

C DEFINE LDSTAK, THE LENGTH OF DSTAK

C LDSTAK - 100

CC READ NUMBER OF OBSERVATIONS INTO N, AND DATA INTO VECTOR Y

C READ (5, 100) N READ (J, 101) (Yd), 1-1, N)

C

C CREATE A VECTOR OF ORDER INDICES IN X C DO 10 I«1»N

X(I) - FLOAT(I)

10 CONTINUE

C

C PRINT TITLE, PLOT OF DATA, AND ERROR INDICATOR

C WRITE (6, 102) CALL PP (Y, X, N) WRITE (6, 103) IERR

C

C PRINT TITLE, STATISTICAL ANALYSIS OF DATA, AND ERROR INDICATOR

C WRITE (6, 102) CALL STAT (Y, N, LDSTAK)

WRITE (6, 103) IERR STOP

CC FORMAT STATEMENTS

C 100 FORMAT (15) 101 FORMAT (12F6.*)

102 FORMAT (1H1, 48HDAVIS-HARRIS0N PIKES PEAK RELATIVE HUMIDITY DATA)

103 FORMAT (8H IERR > , ID

END DATA l 8* .6067 .6087 .6086 .613* .6106 .6136 .6125 .6122 .6110 .610* .7213 .7078

.7021 .700* .6981 .72*2 .7266 .7*16 .7*07 .7199 .6225 .625* .6252 .6267

.6218 .6178 .6216 .6192 .6191 .6250 .6188 .6233 .6225 .620* .6207 .6168

.61*1 .6291 .6231 .6222 .6252 .6306 .6376 .6330 .6303 .6301 .6390 .6*23 .6300 .6260 .6292 .6298 .6290 .6262 .5952 .5951 .631* .6**0 .6*39 .6326

.6392 .6*17 .6*12 .6530 .6*11 .6355 .63** .6623 .6276 .6307 .635* .6197

.6153 .63*0 .6336 .628* .6162 .6252 .63*9 .63** .6361 .6373 .6337 .6383

Figure C-l

STARPAC sample program and data

1-1.3
I

HIa

•H

En

aa

pPu

a

exw

1-1.4
O O O O O O

I I I I I *

UJ UJ UJ UJ UJ ' m f>- o » O O

M » O * » *

«> -o o c o

IS! U> » .-I O Q • •••• en ro ** im *4 *\

t AJ

I ** ~

•-» IM O O

UJ LU

-r Prf co o

<VJ f- r» c*> m iHCM * IS

rfHOOHHNNrl>4 oooooooooo I I I I UJLAJUJUJUJUJUJUJ UJ LU OOOJJOONHO0

ooeoi*jocoeo«'i-j3<r

o^r-om^rf-cococ*!

at _j _i a

z •-•

a » z m oo UJ UJ « 1— l- 1 1 a O UJ « z UJ UJ *o S 1-4 UJ f-4 fvl f* a >UH -t *

a at u. UJUU CD i>-

•>» a a z .- o <o

u. a hi * u. m co a z • o Z f< u. o •* * a z- « at uj m a

to i— • < UJ 4 O • •

UJ to to at Z j> t> O «M

at13 to to

to 3 > »

to UJ O

UJ at to UJ UJ

"3 •* >- 1-

-J 3 > 3 3

< <3 UJ _J -J > to O o a

«o to

U. u. u. t- co co Q o a « <

UJ a to Z >r z » Z z z »— Z UJ 3 r> o i— 1i z> z> z 3 »

x- r iSt to to UJ to *

1—

»

i—

*

^ 4 O

2 K - h- o o o 3 O O

X z IE ffl) X 3 J» to X J» »- en i A

o 5c 2 pn

> *

at- at

O O O O O o

• I I I • I UJ LLJ UJ UJ 111 UJ u u CSOONIM z z

+ + 00«M(l UJ UJ O O O O 0> 0» o o **r*Mft -» miD-JW/BS U. u. •o r- r» o» eo to co z z

I mmw jjnn a a

r4 • ••••• u «j

jj < -a -e -c <s

•* o o o o © 0»

! I * O

UJ UJ UJ • H«0

-o co n oo-f i o -r w

CO -4 -o t- r- -r i-» N ft •< o

OB -C NKI*

4J3

a

4-1 3oH

<!H

O

0) i-t

o o

UJ Uio

to to

1 I O O

a *

x uj z

u. IS »- Z •< >- H> o HKauu UltM | Q. O. to XhOD uj zuiuiHnin

ex D s r r nn

- o o o a s • _i at at to to to c

o

to o to to z to uj *». UJ O -2 z > u. Z ZCONii.

Z < ai/iH O u. to O

ft. O u. uj z s a o u < o <_> o

at <o z a 3 3

• Z Z to to Z 3 O

at uj u. o o

Z »- O to to

u. o

as Oui >zz O a. o •« «

U. O X • LU UI Z UJ to Z Z

*~ to <o a u.

J» Z Z to O

o tp a z

Z m « to Z 3 • a to to z ae a at 3 a •

u. I at uj u. to - o ^

to U. U. U. CJ • Z O O O UJ • u, O ft. O UL *— O Q O x • •*

•- z z z uj «o a

*©

1-1.5
D. Using STARPAC

The following subsections provide general information needed when using

STARPAC, including a discussion of Fortran programming as it relates to

STARPAC usage. Although only elementary knowledge of Fortran is required to

use STARPAC, users may still have to consult with a Fortran test and/or their

computing center staff when questions arise.

D.l The PROGRAM Statement

The PROGRAM statement, which is required by most Fortran compilers on CDC

machines, serves two purposes: the first is to name the user's main program;

and the second is to specify the files (devices) which will be used for

reading and writing information during execution of the user's program. In

figure C-l, the PROGRAM statement is

PROGRAM EXAMPL (INPUT, OUTPUT, TAPE5 = INPUT, TAPE6 = OUTPUT).

The name EXAMPL is assigned to the main program in this example. The

program name cannot be the name of any variable in the user's main program

and, in addition, cannot be the name of any other subroutine or function

called during execution of the user's code. Specifically, it cannot be the name of any subroutine within STARPAC. To ensure that the name of a STARPAC

subroutine is not inadvertently chosen for the name of the main program, users

should consult with the local installer of STARPAC to obtain a list of the

STARPAC subroutine names.

The file declaration function of the program statement is machine

dependent. The files declared in the program statements used in this example

and throughout the STARPAC documentation are those required when using STARPAC

on the CYBER 170/7 50 at the U.S. Department of Commerce Boulder Laboratories

under the NOS 1.4 operating systems. Users at other installations should

consult §D.4 and the local installer of STARPAC for additional information on

controlling file specification.

D.2 The Dimensioning Statements

The user's program must include dimensioning statements to define the

sizes and types of the vectors (1-dimensional arrays) and matrices

(2-dimensional arrays) required by each STARPAC subroutine used; STARPAC

itself has no inherent upper limit problem size.

Within the STARPAC documentation for the subroutine declaration and CALL

statements, italicized lowercase identifiers in the dimensioning statements

represent integer constants which must equal or exceed the value of the

identically spelled uppercase argument. For example, if the documentation

specifies the minimum dimension of a variable as <real> XM(?z,w), and if the

number of observations N is 15, and the number of columns of data M is 3, then

(assuming the single precision version of STARPAC is being used) the minimum

array size is given by the dimensioning statement REAL XM(15,3).

1-1.
The exact dimensions assigned to some vectors and matrices must be

supplied in the CALL statements to some STARPAC subroutines. For example, the

argument 1XM is defined as "the exact value of the first dimension of the

matrix XM as declared in the calling program." Continuing the example from

the preceding paragraph, if the statement REAL XM(20,5) is used to dimension

the matrix XM for a particular subroutine, and IXM is an argument in the CALL

statement, then IXM must have the value 20 regardless of the value assigned to

the variable N.

Many STARPAC subroutines require a work area for internal computations.

This work area is provided by the DOUBLE PRECISION vector DSTAK. The rules

for defining DSTAK are as follows.

1. Programs which call subroutines requiring the work vector DSTAK must

include both the statement

COMMON /CSTAK/ DSTAK

and the DOUBLE PRECISION statement dimensioning DSTAK.

2. Since all STARPAC subroutines use the same work vector, the length of

DSTAK must equal or exceed the longest length required by any of the

individual STARPAC subroutines called by the user' s program.

3. The length, LDSTAK, of the work vector DSTAK must be specified in the

CALL statement of any STARPAC subroutine using DSTAK to enable STARPAC

to verify that there will be sufficient work area for the problem.

It is recommended that a variable LDSTAK be set to the length of DSTAK,

and that this variable be used in each CALL statement requiring the length of

DSTAK to be specified. Then, if a future modification to the user's program

requires the length of DSTAK to be changed, the only alterations required in

the existing code would be to the DOUBLE PRECISION dimensioning statement and

to the statement which assigns the length of DSTAK to LDSTAK.

STARPAC manages its work area using subroutines modeled after those in

ACM Algorithm 528: Framework for a Portable Library [Fox et al. , 1978a]

Although STARPAC and the Framework share the same COMMON for their work areas,

there are differences between the STARPAC management subroutines and those of

the Framework. In particular, the STARPAC management subroutines

re-initialize DSTAK each time the user invokes a STARPAC subroutine requiring

work area, destroying all data previously stored in DSTAK; the Framework only

initializes DSTAK the first time any of its management subroutines are

invoked, preserving work area allocations still in use. Thus, users must be

cautious when utilizing STARPAC with other libraries which employ the

Framework, such as PORT [Fox et al. , 1978b].

The sample program shown in figure D-l provides an example of the use of

dimensioned variables with STARPAC. The REAL vector Y, used by both

subroutines PP and STAT, contains the 84 relative humidity measurements; its

minimum length, N (the number of observations) , is 84. The REAL vector X used

by subroutine PP contains the corresponding time order indices of the data;

1-1.7
its minimum length is also 84. The DOUBLE PRECISION vector DSTAK contains the

work area needed by STAT for intermediate computations; its minimum length is

49 in this case. In this example, the dimensions of Y, X, and DSTAK, are each

100, exceeding the required minimum values.

D.3 The CALL Statements

The STARPAC CALL statement arguments provide the interface for specifying

the data to be used, controlling the computations, and providing space for any

returned results. The CALL statements used in the example are CALL PP(Y, X, N) and CALL STAT(Y, N, LDSTAK) . Note that scalar arguments may

be specified either by a variable preset to the desired value, as was done in

figure C-l, or by the actual numerical values. For example, CALL PP(Y, X, 84)

and CALL STAT(Y, 84, 100) could have been used instead of the forms shown. We

recommend using variables rather than the actual numerical values in order to

simplify future changes in the program. When variables are used, changes need

to be made in only one place; numerical values have to be changed every place

they occur. In addition, the use of variables can also clarify the meaning of

the program.

D . 4 STARPAC Outpu t

Most STARPAC subroutines produce extensive printed reports, freeing the

user from formatting and printing each statistic of interest. The standard

output device is used for these reports. The user has the options of titling

the reports and changing the output device.

The first page of the report from each STARPAC subroutine does not start

on a new page. This allows the user to supply titles. For example,

WRITE (6, 100)

100 FORMAT (1H1, 4 8H DAVIS-HARRISON PIKES PEAK RELATIVE HUMIDITY DATA)

CALL PP (Y, X, N)

will print the title DAVIS-HARRISON PIKES PEAK RELATIVE HUMIDITY DATA on the

top line of a new page, immediately preceding the plot as shown in figure C-2.

Users should note that titles more than one line in length can cause a printed

report designed for one page to extend beyond the bottom of the page.

The unit number, IPRT, of the output device used by STARPAC is returned

by STARPAC subroutine IPRINT. Users can change the output device unit number

by including with their program a subroutine IPRINT which will supersede the

STARPAC subroutine of the same name. The subroutine must have the form

SUBROUTINE IPRINT(IPRT)

IPRT = u RETURN

END

where u is an integer value specifying the output unit to which all STARPAC

output will be written.

1-1.8
D.5 STARPAC Error Handling

STARPAC provides extensive error-checking facilities which include both

printed reports and a program-accessible error flag variable. There are essentially two types of errors STARPAC can detect.

The first type of error involves incorrect problem specification, i.e., one or more of the input arguments in the subroutine statement has an improper

value. For example, the number of observations, N, might have an obviously

meaningless non-positive value. In the case of improper problem specification

STARPAC generates a printed report identifying the subroutine involved, the

error detected, and the proper form of the subroutine CALL statement. The

latter is provided because improper input is often the result of an incorrectly specified subroutine argument list.

A second type of error can be thought of as a computation error: either

the results from the called subroutine are questionable, or the initiated

calculation cannot be completed. For example, when one or more of the

standardized residuals from a least squares fit cannot be computed because the

standard deviation of the residual is zero, the results of the error estimates

from the least squares regression may be questionable; if the least squares

model is found to be singular, then the desired computations cannot be

completed. In the case of a computation error, STARPAC generates a report

which identifies the computation error, and, to aid the user in determining

the cause of the error, summarizes the completed results in a printed report.

STARPAC error reports cannot be suppressed, even when the normal output

from the STARPAC subroutine has been suppressed. Because of this, users seldom have to consciously consider handling error conditions in their code.

When proper execution of the user' s program depends on knowing whether or not an error has been detected, the error flag can be examined from within the

user's code. When access to the error flag is desired, the statement

COMMON /ERRCHK/ IERR

must be placed with the Fortran declaration statements in the user's program.

Following the execution of a STARPAC subroutine, the variable IERR will be set

to zero if no errors were detected, and to a nonzero value otherwise; the

value of IERR may indicate the type of error [e.g., see Donaldson and Tryon,

1983, chapter 1, §D, argument IERR]. If the CALL statement is followed with a statement of the form

IF (IERR .NE. 0) STOP

then the program will stop when an error is detected. (In figure C-l , the

value of IERR has been printed following each CALL statement to show the value

returned.

)

'STARPAC output must be directed to a separate output device [see §D.4] when

users do not want any STARPAC reports displayed under any conditions.

1-1.9
D. 6 Common Programming Errors When Using STARPAC

STARPAC error checking procedures catch many programming errors and print

informative diagnostics when such errors are detected. However, there are some errors which STARPAC cannot detect. The more common of these are discussed below.

1. The most common error involves array dimensions which are too small.

Although certain arguments are checked by STARPAC to verify that array

dimensions are adequate, if incorrect information is supplied to

STARPAC, or if the dimension of an array which is not checked is too

small, the program will produce erroneous results and/or will stop

prematurely. Users should check the dimensioning statements in their

program whenever difficulties are encountered in using STARPAC.

2. The second most common error involves incorrect CALL statements, that

is, CALL statements in which the STARPAC subroutine name is

misspelled, the arguments are incorrectly ordered, one or more

arguments are omitted, or the argument types (INTEGER, REAL, DOUBLE

PRECISION, and COMPLEX) are incorrect. Users having problems using

STARPAC should carefully check their declaration and CALL statements

to verify that they agree with the documentation.

3. The third most common error involves incorrect specification of the

work vector DSTAK. Programs which call STARPAC subroutines requiring

work area must include both the DOUBLE PRECISION statement

dimensioning DSTAK and the COMMON /CSTAK/ DSTAK statement.

4. The final common error involves user-supplied subroutines which have

the same name as a subroutine in the STARPAC library. Users should

consult with the local installer of STARPAC to obtain a list of all

STARPAC subroutine names. This list can then be used to ensure that a STARPAC subroutine name has not been duplicated.

Users who have not found the cause of a problem after checking the

possibilities mentioned above should consult with their computing center

advisers.

1-1.10
References

American National Standards Institute. (1966). ANS FORTRAN X3. 9-1966. New

York: American National Standards Institute.

Donaldson, J. R.; Tryon, P. V. (1983). Nonlinear least squares regression

using STARPAC, the Standards time series and regression package. Nat. Bur.

Stand. (U.S.) Tech. Note 1068-2.

Dongarra, J. J.; Moler, C. B.; Bunch, J. R.; Stewart, G. W. (1979). UNPACK

users' guide. Philadelphia: SIAM.

Fillihen, J. J. (1977). User's guide to the DATAPAC data analysis package.

Unpublished.

Fox, P. A.; Hall, A. D.; Schryer, N. L. (1978a). Algorithm 528: framework

for a portable library. ACM Trans. Math. Software, 4(2): 177-188.

Fox, P. A.; Hall, A. D.; Schryer, N. L. (1978b). The PORT mathematical

subroutine library. ACM Trans. Math. Software, 4(2): 104-126.

Hogben, D.; Peavy, S. T.; Varner, R. N. (1971). OMNITAB II user's reference

manual. Nat. Bur. Stand. (U.S.) Tech. Note 552.

Lawson, C; Hanson, R.; Kincaid, D.; Krogh, F. (1979). Basic linear algebra

subprograms for FORTRAN usage. ACM Trans. Math. Software, 5(3): 308-323.

Natrella, M. G. (1966). Experimental statistics. Nat. Bur. Stand. (U.S.)

Handb. 91.

Ryder, G. B. (1974). The PFORT verifier. Software Practice and Experience,

4(4); October-December: 359-377.

Tryon, P. V.; Donaldson, J. R. (1978). STATLIB: a library of Fortran

subroutines for statistical analysis of experimental data.

(Unpublished - available from J. R. Donaldson.)

1-R.l
HBS-1UA (REV. 2-8C) U.S. DEPT. OF COMM.

BIBLIOGRAPHIC DATA

SHEET (See instructions,)

1. PUBLICATION OR

REPORT NO.

NBS TN-1068-1

2. Performing Organ. Report No 3. Publication Date

October 1983

4. TITLE AND SUBTITLE

Introduction to STARPAC, The Standards Time Series and Regression Package

5. AUTHOR(S) Janet R. Donaldson and Peter V. Tryon

6. PERFORMING ORGANIZATION (If joint or other than NBS. see instructions)

NATIONAL BUREAU OF STANDARDS

DEPARTMENT OF COMMERCE

WASHINGTON, D.C. 20234

7. Contract/Grant No.

8. Type of Report & Period Covered

Report #1 in a series

9. SPONSORING ORGANIZATION NAME AND COMPLETE ADDRESS (Street. City. State, ZIP)

10. SUPPLEMENTARY NOTES

~] Document describes a computer program; SF-185, FlPS Software Summary, is attached.

11. ABSTRACT (A 200-word or less factual summary of most significant information. If document includes a significant

bibliography or literature survey, mention it here)

STARPAC, the Standards Time Series and Regression Package, is a library of Fortran

subroutines for statistical data analysis developed by the Statistical Engineering

Division (SED) of the National Bureau of Standards (NBS), Boulder, Colorado. Earlier

versions of this library were distributed by the SED under the name STATLIB [Tryon

and Donaldson, 1978]. STARPAC incorporates many changes to STATLIB, including

additional statistical techniques, improved algorithms and enhanced portability.

STARPAC emphasizes the statistical interpretation of results, and, for this reason,

comprehensive printed reports of auxiliary statistical information, often in

graphical form, are automatically provided to augment the basic statistical

computations performed by each user-callable STARPAC subroutine. STARPAC thus

provides the best features of many stand-alone statistical software programs within

the flexible environment of a subroutine library. STARPAC documentation is being

published as a series of Technical Notes. This Note is the first in the series. It

gives an overview of the STARPAC library, defines conventions used in the

documentation, provides an example using STARPAC subroutines, and presents general

background material. This Note includes information which is essential for using the

STARPAC library, and users should be familiar with its contents before attempting to

use any STARPAC subroutine.

12. KEY WORDS (Six to twelve entries; alphabetical order; capitalize only proper names; and separate key words by semicolons)

data analysis; STARPAC; STARPAC overview; statistical computing: statistical subroutine

library; STATLIB.

13. AVAILABILITY

J5J Unlimited

| | For Official Distribution. Do Not Release to NTIS

["XJ Order From Superintendent of Documents, U.S. Government Printing Office, Washington, D.C. 20402.

^\ Order From National Technical Information Service (NTIS), Springfield, VA. 22161

14. NO. OF

PRINTED PAGES

24

15. Price

$3.00

•frU.S. GOVERNMENT PRINTING OFFICE: 1983-776-875/65 USCOMM-DC 6043-P80


NBS TECHNICAL PUBLICATIONS

PERIODICALS

JOURNAL OF RESEARCH—The Journal of Research of the National Bureau of Standards reports NBS research and develop- ment in those disciplines of the physical and engineering sciences in which the Bureau is active. These include physics, chemistry,

engineering, mathematics, and computer sciences. Papers cover a broad range of subjects, with major emphasis on measurement

methodology and the basic technology underlying standardization. Also included from time to lime are survey articles on topics

closely related to the Bureau's technical and scientific programs. As a special service to subscribers each issue contains complete

citations to all recent Bureau publications in both NBS and non- NBS media. Issued six times a year. Annual subscription: domestic

$18; foreign $22.50. Single copy, $5.50 domestic; $6.90 foreign.

NONPERIODICALS

Monographs—Major contributions to the technical literature on

various subjects related to the Bureau's scientific and technical activities. Handbooks—Recommended codes of engineering and industrial practice (including safety codes) developed in cooperation with in- terested industries, professional organizations, and regulatory

bodies. Special Publications—Include proceedings of conferences sponsored by NBS, NBS annual reports, and other special publications

appropriate to this grouping such as wall charts, pocket cards, and

bibliographies. Applied Mathematics Series—Mathematical tables, manuals, and

studies of special interest to physicists, engineers, chemists,

biologists, mathematicians, computer programmers, and others engaged in scientific and technical work

National Standard Reference Data Series—Provides quantitative data on the physical and chemical properties of materials, compiled from the world's literature and critically evaluated. Developed under a worldwide program coordinated by NBS under

the authority of the National Standard Data Act (Public Law

90-396).

NOTE: The principal publication outlet for the foregoing data is the Journal of Physical and Chemical Reference Data (JPCRD)

published quarterly for NBS by the American Chemical Society

(ACS) and the American Institute of Physics (AIP). Subscriptions,

reprints, and supplements available from ACS, I 155 Sixteenth St., NW, Washington, DC 20056.

Building Science Series—Disseminates technical information developed at the Bureau on building materials, components,

systems, and whole structures. The series presents research results,

test methods, and performance criteria related to the structural and

environmental functions and the durability and safety characteristics of building elements and systems.

Technical Notes—Studies or reports which are complete in themselves but restrictive in their treatment of a subject. Analogous to monographs but not so comprehensive in scope or definitive in treatment of the subject area. Often serve as a vehicle for final reports of work performed at NBS under the sponsorship of other government agencies.

Voluntary Product Standards—Developed under procedures

published by the Department of Commerce in Part 10, Title 15, of

the Code of Federal Regulations The standards establish nationally recognized requirements for products, and provide all concerned interests with a basis for common understanding of the

characteristics of the products N BS administers this program as a supplement to the activities of the private sector standardizing

organizations. Consumer Information Series—Practical information, based on N BS research and experience, covering areas of interest to the con- sumer. Easily understandable language and illustrations provide

useful background knowledge for shopping in today's tech- nological marketplace. Order the above NBS publications jrom: Superintendent of Documents, Government Printing Office. Washington. DC 20402

Order the following NBS publications —FIPS and NBSIR's—from

the National Technical Information Service . Springfield. VA 22161

Federal Information Processing Standards Publications (FIPS

PUB)—Publications in this series collectively constitute the Federal Information Processing Standards Register. The Register

serves as the official source of information in the Federal Govern- ment regarding standards issued by NBS pursuant to the Federal Property and Administrative Services Act of 1949 as amended.

Public Law 89-306 (79 Stat. 1127), and as implemented by Executive Order 11717(38 FR 12315, dated May II, 1973) and Part 6 of Title 15 CFR (Code of Federal Regulations).

NBS Interagency Reports (NBSIR)—A special series of interim or

final reports on work performed by NBS for outside sponsors

(both government and non-government). In general, initial dis- tribution is handled by the sponsor: public distribution is by the National Technical Information Service , Springfield, VA 22161,

in paper copy or microfiche form.
U.S. Department of Commerce

National Bureau of Standards

Washington, DC. 20234

Official Business

Penalty for Private Use $300

POSTAGE AND FEES PAID

U S DEPARTMENT OF COMMERC

COM-215

FIRST CLASS