REFERENCE I NBS

PUBLICATIONS

NBSIR 86-3448

A 11 IDE b 3 1 Ml

NAT’L INST OF STANDARDS & TECH R.I.C. gk

All 102631417

Donaldson, Janet R/STARPAC : the standa QC100 .U56 NO.86-3448 1987 VI 9 C.1 NBS-P me standards Times Senes and

Regression Package

Janet R. Donaldson

Peter V. Tryon

U.S. DEPARTMENT OF COMMERCE

National Bureau of Standards

Boulder, Colorado 80303

January 1987

U.S. DEPARTMENT OF COMMERCE

,-QC

100

4156

86-3448

1987

U OF STANDARDS

NBSIR 86-3448

STARPAC

THE STANDARDS TIMES SERIES AND

REGRESSION PACKAGE

NSS

RESEARCH

INFORMATION CENTER /USSR

Oluoo

f u

\H%1

Janet R. Donaldson

Peter V. Tryon

U.S. DEPARTMENT OF COMMERCE

National Bureau of Standards

Boulder, Colorado 80303

January 1987

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

NATIONAL BUREAU OF STANDARDS. Ernest Ambler, Director

In memory of
Disclaimer

No warranties 3 express or implied3 are made

by the distributors or developers that

STARPAC or its constituent parts are free of

error. They should not be 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 manner3 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 3 nor does it imply that the

equipment identified is necessarily the best

available for the purpose.
Preface

STARPAC, the Standards Time Series arid 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] . Chapter 1 and

chapter 9 of this document were previously distributed as NBS Technical Notes

1068-1 and 1068-2, respectively [Donaldson and Tryon, 1983a and 1983b].

STARPAC incorporates many changes to STATLIB, including additional statistical

techniques, improved algorithms and enhanced portability.

STARPAC consists of families of subroutines for nonlinear least squares

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

printer graphics, basic statistical analysis, and linear least squares

regression. These subroutines feature:

o 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 are constant throughout the

STARPAC documentation, allowing the documentation for each family of

subroutines 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 180/840 under NOS 2.3. All examples

presented in this documentation were executed in this environment using the

FTN 5.1+617 compiler with rounding.

STARPAC is written in ANSI Fortran '77 [American National Standards

Institute, 1977] using the Hollerith Extension. 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 LINPACK [Dongarra et al. 1979] , from the "Basic

Linear Algebra Subprograms for Fortran Usage” [Lawson et al. 1979], from

DATAPAC [Filliben, 1977] and from the portable special function subroutines of

Fullerton [1977]. The analyses generated by several of the subroutine

families have been adapted from OMNITAB II [Hogben et al. 1971]; users are directed to Peavy et al. [1985] for information about OMNITAB 80, the current

version of OMNITAB.

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

the National Oceanic and Atmospheric Administration Mountain Administrative

Support Center Computer Division, Boulder, Colorado, and we gratefully

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

v
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)

October 1985
Contents

Preface v

1. INTRODUCTION TO USING STARPAC 1-1

A. Overview of STARPAC and Its Contents- 1-1

B. Documentation Conventions 1-1

C. A Sample Program 1-2

D. Using STARPAC 1-6

D.l The PROGRAM Statement 1-6

D.2 The Dimension Statements 1-6

D.3 The CALL Statements 1-8

D. 4 STARPAC Output. .. 1-8

D. 5 STARPAC Error Handling. 1-9

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

2. LINE PRINTER GRAPHICS 2-1

A. Introduction 2-1

B . Subroutine Descriptions. 2-1

C. Subroutine Declaration and CALL Statements 2-2

D. Dictionary of Subroutine Arguments and COMMON Variables.... 2-11

E. Computational Details 2-14

F. Examples 2-15

3 . NORMAL RANDOM NUMBER GENERATION. 3-1

A. Introduction 3-1

B. Subroutine Descriptions... 3-1

C. Subroutine Declaration and CALL Statements 3-1

D. Dictionary of Subroutine Arguments. 3-2

E. Computational Methods............. 3-3

F. Example. 3-3

G. Acknowledgments. 3-6

4. HISTOGRAMS....... 4-1

A . Introduction. 4-1

B. Subroutine Descriptions 4-1

C. Subroutine Declaration and CALL Statements 4-1

D. Dictionary of Subroutine Arguments 4-2

E. Computational Methods 4-3

E. l Algorithms..... 4-3

E.2 Computed Results and Printed Output 4-3

F. Example 4-5

G. Acknowledgments... 4-8
5. STATISTICAL ANALYSIS OF A UNIVARIATE SAMPLE

A. Introduction . B. Subroutine Descriptions

C. Subroutine Declaration and CALL Statements.....

D. Dictionary of Subroutine Arguments and COMMON Variables....

E. Computational Methods

E.l Algorithms

E.2 Computed Results and Printed Output

F . Example

G. Acknowledgments . . .

6 . ONE-WAY ANALYSIS OF VARIANCE

A. Introduction

B. Subroutine Descriptions.....

C. Subroutine Declaration and CALL Statements..........

D. Dictionary of Subroutine Arguments and COMMON Variables....

E. Computational Methods

E .1 Algorithms

E.2 Computed Results and Printed Output

F . Example

G . Acknowled gme nts. ......................... ..................

7

.

CORRELATION ANALYSIS

A . Introduction.

B. Subroutine Descriptions....................................

C. Subroutine Declaration and CALL Statements.................

D. Dictionary of Subroutine Arguments and COMMON Variables....

E o Comp utat xonal Me thods ....... ...... ..............

Eol Algon t hms .......... ....... ......... .««........©©..*..

E.2 Computed Results and Printed Output...................

F . Example . . . Go Acknowledgments. .oo®o..«oo©o©«*o.©...©.*.««o...o.». ........

LINEAR LEAST SQUARES.

A . Introduction

B. Subroutine Descriptions......

C. Subroutine Declaration and CALL Statements

D. Dictionary of Subroutine Arguments and COMMON Variables....

E. Computational Methods

E.l The Linear Least Squares Algorithm

E.2 Computed Results and Printed Output

F . Examples.

G. Acknowledgments.

5-1

5-1

5-1

5-1

5-3

5-8

5-8

5-8

5-8

5-11

6-1

6-1

6-1

6-1

6-2

6-3

6-3

6-3

6-6

6-9

7-1

7-1

7-1

7-1

7-2

7-3

7-3

7-3

7-7

7-11

8-1

8-1

8-2

8-2

8-5

8-9

8-9

8-9

8-12

8-2 3

viii
9. NONLINEAR LEAST SQUARES 9-1

A. Introduction 9-1

B. Subroutine Descriptions 9-2

B.l Nonlinear Least Squares Estimation Subroutines 9-2

B .2 Derivative Step Size Selection Subroutines 9-3

B.3 Derivative Checking Subroutines 9-4

C. Subroutine Declaration and CALL Statements 9-4

D. Dictionary of Subroutine Arguments and COMMON Variables.... 9-10

E. Computational Methods 9-20

E.l Algorithms 9-20

E.l.a Nonlinear Least Squares Estimation 9-20

E.l.b Derivative Step Size Selection 9-22

E.l.c Derivative Checking 9-24

E .2 Computed Results and Printed Output.............. 9-25

E.2.a The Nonlinear Least Squares Estimation

Subroutines 9-2 5 E.2.b The Derivative Step Size Selection Subroutines. P-28

E.2.c The Derivative Checking Subroutines 9-28

F . Examples 9-2 9

G. Acknowledgments...... 9-49

10. DIGITAL FILTERING. 10-1

A. Introduction. 10-1

B. Subroutine Descriptions..... 10-1

B.l Symmetric Linear Filter Subroutines 10-1

B .2 Autoregressive or Difference Linear Filter

Subroutines. 10-3

B.3 Gain and Phase Function Subroutines 10-4

C. Subroutine Declaration and CALL Statements 10-4

D. Dictionary of Subroutine Arguments and COMMON Variables.... 10-8

E. Computational Methods.... 10-14

E .1 Algorithms . 10-14

E .2 Computed Results and Printed Output 10-14

F . Examples. 10-14

G. Acknowledgments. . 10-20

11. COMPLEX DEMODULATION........... 11-1

A. Introduction........... 11-1

B. Subroutine Descriptions 11-1

C. Subroutine Declaration and CALL Statements 11-2

D. Dictionary of Subroutine Arguments and COMMON Variables.... 11-2

E. Computational Methods 11-4

E.l Algorithms 11-4

E .2 Computed Results and Printed Output 11-5

F. Example 11-5

G. Acknowledgments 11-9
12. CORRELATION AND SPECTRUM ANALYSIS 12-1

A. Introduction 12-1

B. Subroutine Descriptions 12-1

B.l Correlation Analysis..... 12-2

B.l.a Univariate Series 12-2

B.l.b Bivariate Series 12-3

B .2 Spectrum Estimation 12-4

B .2 .a Univariate Series. 12-4

B .2 .b Bivariate Series. 12-7

C. Subroutine Declaration and CALL Statements.. 12-7

D. Dictionary of Subroutine Arguments and COMMON Variables.... 12-20

E. Computational Methods 12-37

E.l Algorithms 12-37

E.l.a Correlation Analysis 12-37

E.l.b Spectrum Analysis................. 12-37

E.2 Computed Results and Printed Output................... 12-38

E.2.a Correlation Analysis.. 12-38

E.2.b Spectrum Analysis 12-41

F . Examples 12-44

G. Acknowledgments. ........................................... 12-77

13. ARIMA MODELING 13-1

A. Introduction 13-1

B . Subroutine Descriptions. ................................... 13-3

B.l ARIMA Estimation Subroutines..................... 13-3

B.2 ARIMA Forecasting Subroutines......................... 13-3

C. Subroutine Declaration and CALL Statements.......... 13-4

D. Dictionary of Subroutine Arguments and COMMON Variables.... 13-5

E . Computational Methods ...................................... 13-14

E.l Algorithms 13-14

E.l.a ARIMA Estimation....... 13-14

E.l.b ARIMA Forecasting.............................. 13-15

E.2 Computed Results and Printed Output............. 13-15

E.2 .a The ARIMA Estimation Subroutines............... 13-15

E.2.b The ARIMA Forecasting Subroutines.. 13-18

F . Examples. 13-18

G. Acknowledgments 13-2 9

Appendix A A-l

Appendix B B-l

Appendix C ....... C-l

References R-l

x
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 of the National

Bureau of Standards, 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.

Key words: data analysis; nonlinear least squares; STARPAC;

statistical computing; statistical subroutine library; statistics;

STATLIB; time series analysis.
I
CHAPTER 1

INTRODUCTION TO USING STARPAC

A. Overview of STARPAC and Its Contents

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

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 and linear least squares. 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.

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 subroutine families uses a standard format description of the information needed to use a STARPAC

subroutine, including one or more examples.

References to chapter sections within the STARPAC documentation are made

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

chapter 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 this chapter (chapter 1).
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 dimension statements is

discussed below in §D.2.

Currently, only the single precision version of the STARPAC library is

supported by the Statistical Engineering Division. However, a double

precision version can be generated relatively easily. The precision of the

STARPAC library is 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

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 whether the single or double precision

version of STARPAC is 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 CDC CYBER 180/840 at the U.S.

Department of Commerce Boulder Laboratories under the NOS 2.3 operating system

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

portable ANSI '77 Fortran. 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, documented in chapter 2,

plots the data versus time-order (fig. C-2) and STARPAC subroutine STAT,

documented in chapter 4, prints a comprehensive statistical analysis of the

data (fig. C-3).

1-2
OOOOOOOOOO

MAIN PROGRAM! PROGRAM EXAMPL

OAT At

DEMONSTRATE STAT ANO PP USING SINGLE PRECISION VERSION OF STaRPAC

RUN ON CYBER 190/840.

OUTPUT UNIT IS 6 (AUTOMATICALLY EOUATED TO FILE T API 6 ON CYRERS)

ISEE CHAPTER 1* SECTION D.43

N.B. DECLARATION OF Y AND X MUST BE CHANGED TO DOUBLE PRECISION

IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL Y(100), X(IOO) DOUBLE PRECISION DSTAM100)

C COMMON /CSTAK/ OSTAK COMMON /ERRCHK / I ERR

C

c define ldstak, the length of dstak

c IDSTAK 100

c

C READ NUMBER OF OBSERVATIONS INTO N AND

C DATA INTO VECTOR Y READ 100* N READ 101* ( Y ( I ) » I-1*N>

C

C CREATE A VECTOR OF QROER INDICES IN X

C DO 10 I-l*N

X( I) - I 10 CONTINUE

C

C PRINT TITLE* PLOT OF DATA ANO ERROR INDICATOR

C WRITE (6* 102) CALL PP t Y * X* N) WRITE (6* 101) IERR

C

C PRINT TITLE* STATISTICAL ANALYSIS OF DATA ANO ERROR INDICATOR

C WRITE (6* 102) CALL STAT (T* N* LOSTAK) WRITE (6* 103) IERR

C STOP

c

C FORMAT STATEMENTS

C 100 FORMAT

101 FORMAT

102 FORMAT

103 FORMAT

END

(19)

(12F7.4)

( UOAVIS-HARRI SON PIKES PEAK RELATIVE HUMIOITY DATA 8

! (• IERR • •» ID

84 0.6007 0.6087 0.6086 0.6134 0.6108 0.6138 0.6129 0.6122 0.6110 0.6104 0. 7213 Oo 707a 0.7021 0.7004 0.6981 0.7242 0.7268 0.7418 0.7407 0.7199 0.6229 0.6294 0.6292 0.6267

0.6218 0.6178 0.6216 0.6192 0.6191 0.6290 0.6188 0.6233 0.6229 0.6204 0.6207 0.6166

0.6141 0.6291 0.6231 0.6222 0.6292 0.6308 0.6376 0.6330 0.6303 0.6301 0.6390 0.6423

0.6300 0.6260 0.6292 0.6298 0.6290 0.6262 0. 9992 0.9991 0.6314 0.6440 0. 6439 0.6326

0.6192 0.6417 0.6412 0.6930 0.6411 0.6199 0.6344 0.6623 0.6276 0.6307 0.6394 0.6197

0.6193 0.6140 0.6318 0.6284 0.6162 0.6292 0.6349 0.6344 0.6361 0.6373 0.6137 0.6383

Figure C-l

STARPAC sample program and data

1-3
0AVJS-HARRI

SON

PIKES

PEAK

RELATIVE

HUNIOITY

DATA
I IMii««i«m o o © o o o III I I . 1 1

tu IU VM tX3 tti k. o © ©

•H • © #-• ^ N O# © im © © ©* • N r # H! © o XQ X © © © © < tu WUO N* = © X MXU1 © • ©<J 2 Mtt> finZ 4 CW » U4 © Ud 4 O 9 1ft C >U I I 0 O1 I

CM

K ^ «4

H* «<

I*

©

©• • © © o o © ©I I © *» m m O

rt

©• • © «v

IA V* © ©

IK • © o

u>

u

oooooooooo I I I I yj yj |y y| yj y, y| yj 00©00©<V4«*0© o © r> rvi o ON f*1 O < OONOON^OOO 00©m©©©*\©© © ©®m©©»foH«m rnNNONHOr^

©*»

W

© U) ftfc) ui 3 9

OL -d <md © © ©

-i 3 X 9 3 © © u* j J

X> y*© GO » *»9 M ' © © o © © «e w xxx rf 0^3©3X3» [ © ^^000900

©

*>©K3 ©•an

»=> 3

**)I

ooooeo i i i i i i IU W W W UMW ««OONN 4>#0 Oin«\ 000090

h>KO©©

© c © e © • © ©©©©©©

©©fie©©X

»y

X

x

©

ty

iy

x©

ns

X

H ^ © <B 3 X 7 04 x

<**-

X

© ^» >- 4 KOU WOM | ^4. X M O ©

©

©

uu

uy

©> 

o oi l o o

## oo oo oo • e ©

iy ui iy • ho o © © © OO <f • © © *H m «h © ^

^>

© •* ©©*»«* • © « ©

MhO m*

O 6 I Ik 8 t * O O © UI 4 Oh O O -i © ui MOW• u U. IAK O ^ ui

UI U0 4 • 4 a o © o o j o jaV)4 01 ©

©

*i ©» 0 OM • ® e • e ® ® ® © e H-. « O M © © © 3 X us ^ X « 3 X U. 404 MO 3 O ui • y U MO • U U X X O 3 3 3 X MM © OW4 OO WHO MM o o

ui • X

X • *.©©© O M • UI Ml Z WM XX

O (f IMO

I-I •-• y» o X

v» •*

X

X 3 •

UI 14. vt

U.

W U.H

O

N

O

O

O

O •

1-5

NOTE -

ITENS

IN

PARENTHESES

REFER

TO

PA6E

NUNBER

IN

NBS

HANDBOOK

91I

NATREll

A*

19661 I

ERR-0
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 text and/or their

Computing Center staff when questions arise.

D. 1 The PROGRAM Statement

The PROGRAM statement is used to name the user's main program. 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.

D.2 The Dimension Statements

The user's program must include dimension statements to define the sizes

and types of the vectors, matrices and three-dimensional arrays required by

each STARPAC subroutine used; STARPAC itself has no inherent upper limit on problem size.

Within the STARPAC documentation for the subroutine declaration and CALL

statements, italicized lowercase identifiers in the dimension 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 (n,m) y 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 dimension statement REAL XM(15,3).

The exact dimensions assigned to some vectors and matrices must be

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

argument IXM 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.

1-6
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 the statements

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

where Idstak indicates the integer constant used to dimension 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 dimension 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 C-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;

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

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

in this case, is defined in §D of chapter 4. In this example, the dimensions

of Y, X, and DSTAK, are each 100, exceeding the required minimum values.

1-7
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 (fig. C-l) 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

the example, 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. The use of variables can also clarify the

meaning of the program.

D. 4 STARPAC Output

Most STARPAC subroutines produce extensive printed reports, freeing the

user from formatting and printing all statistics 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 ( '1DAVIS-HARRIS0N 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-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 initiated calculation cannot be completed or the results from the called

subroutine are questionable. For example, when the least squares model and

data are found to be singular, the desired computations cannot be completed;

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 a computation error is detected, STARPAC generates a report

which identifies the 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 handle STARPAC 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 chapter 9, §D,

argument IERR]. If the CALL statement is followed with a statement of the. f orm

IF (IERR ,NE. 0) STOP

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

value of IERR is 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-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 dimension 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 dimension

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.
CHAPTER 2

LINE PRINTER GRAPHICS

A. Introduction

STARPAC contains 36 subroutines for producing 2 basic styles of line

printer plots.

The first, called a page plot, uses a single 11 x 14 inch page of line

printer paper.

The second, called a vertical plot, is designed for plotting time series.

The user specifies only the y-axis values since the x-axis values (independent

variable) are assumed to be equally spaced and ordered consecutively. The

independent variable in the resulting plot is oriented vertically and the plot

will continue over as many pages as necessary to plot one point per line.

Within these two basic styles the user has many options, including

controlling the plot symbol, plotting multivariate values, designating missing

data, using log scales and specifying plot limits and plot size.

Users are directed to §B for a brief description of the subroutines. The

actual declaration and CALL statements are given in §C and the subroutine

arguments are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F

.

B . Subroutine Descriptions

PP (.Page Plot) and VP (Vertical Plot) are the simplest of the STARPAC

line printer plot subroutines. For both, plot limits are automatically set by

the range of the data and other control parameters are set to the default

values given in §D. The remaining plotting subroutines are named by adding

letters to the beginning and/or end of PP and VP.

© Prefix S (e.g. , SPP) indicates the user controls the plot symbol for

each point.

© Prefix M indicates the subroutine will accept multivariate y-axis

values (e.g., MPP).

© Suffix M subroutines allow data with missing observations to be plotted

(e.g., VPM )

.

© Suffix L indicates log scales can be used (e.g., PPL).

© Suffix C subroutines allow control of the parameters which specify the

plot limits, size, scale, etc. (e.g., VPC).

2-1
The following table, which indicates the capabilities of each of the

STARPAC plotting subroutines, can be used to select f rom the available

subroutines. Subroutine declaration and CALL statements are given in §C

,

listed in the same order as in the table.

Plot

Symbol Multiple Page Vertical Missing Log Control

Control Y-Axis Plot Plot Data Scale Parameters

Name (S) (M) (PP) (VP) (M) (L) (c)

PP /

PPL /

V /V PPC / / /

PPM / /

PPML / / /

PPMC / / /

SPP ~T~ /

SPPL / / /

SPPC / / / /

SPPM / / /

' SPPML / / /

SPPMC / / / / /

MPP

MPPL

MPPC

MPPM

MPPML

MPPMC

VP

VPL

VPC

VPM

VPML

VPMC

SVP

7 “7“

SVPL / / /

SVPC / / / /

SVPM / / /

SVPML / / /

SVPMC / / / / /

MVP

~7~ 7

MVPL / / /

MV PC / / / /

MV PM / / /

MVPML / / / /

MV PMC / / / / /

C. Subroutine Declaration and CALL Statements

NOTE: Argument definitions and s ample programs are given in §D and §F,

respective ly

.

The conventions used to present the following declaration and

CALL statments are given in chapter 1 , §B and §D

.
Page Plots

PP: Print Y versus X scatterplot; linear axes; default control values and

axis limits; no missing values allotted

<real> Y(n), X(n)

#CALL PP (Y, X, N)

PPL: Print Y versus X scatterplot; log or linear axes; default control

values and axis limits; no missing values allotted

<real> Y(n), X(rc)

SCALL PPL (Y, X, N, ILOG)

PPC : Print Y versus X scatterplot; log or linear axes; user-supplied

control values and axis limits; no missing values allotted

<real> Y(n), X(n), YLB , YUB, XLB , XUB

SCALL PPC (Y, X, N, ILOG, ISIZE, NOUT, YLB, YUB, XLB, XUB)

PPM: Print Y versus X scatterplot; linear axes; default control values and

axis limits; missing values allowed

<real> Y(n), YMISS, X(n), XMISS

CALL PPM (Y, YMISS, X, XMISS, N)

PPML: Print Y versus X scatterplot; log or linear axes; default control

values and axis limits; missing values allowed

<real> Y(n), YMISS, X(n), XMISS

CALL PPML (Y, YMISS, X, XMISS, N, ILOG)

2-3
PPMC: Print Y versus X scatterplot; log or linear oozes; user-supplied,

control values and axis limits; missing values allowed

<real> Y(n), YMISS, X(n), XMISS, YLB , YUB , XLB , XUB

CALL PPMC (Y, YMISS, X, XMISS, N, ILOG, ISIZE, NOUT, YLB, YUB,

1 XLB, XUB)

SPP: Print Y versus X scatterplot with individual plot symbols specified

by user; linear axes; default control values and axis limits; no missing values allowed

<real> Y(n), X(n)

INTEGER ISYM(rc)

CALL SPP (Y, X, N, ISYM)

SPPL: Print Y versus X scatterplot with individual plot symbols specified

by user; log or linear axes; default control values and axis limits; no missing values allowed

<real> Y(n), X(n)

INTEGER ISYM(n)

CALL SPPL (Y, X, N, ISYM, ILOG)

SPPC: Print Y versus X scatterplot with individual plot symbols specified

by user; log or linear axes; user-supplied control values and axis

limits; no missing values allowed

<real> Y(n), X(n), YLB, YUB, XLB, XUB

INTEGER ISYM(n)

CALL SPPC (Y, X, N, ISYM, ILOG, ISIZE, NOUT, YLB, YUB, XLB, XUB)

2-4
SPPM: Print Y versus X seatterplot with individual plot symbols specified

by user; linear axes; default control values and axis limits; missing

values allowed

<real> Y(n), YMISS, X(n), XMISS

INTEGER ISYM(n)

CALL SPPM (Y, YMISS, X, XMISS, N, ISYM)

SPPML: Print Y versus X seatterplot with individual plot symbols specified

by user; log or linear axis; default control values and axis limits;

missing values allowed

<real> Y(n), YMISS, X(n), XMISS

INTEGER ISYM(n)

CALL SPPML (Y, YMISS, X, XMISS, N, ISYM, ILOG)

SPPMC: Print Y versus X seatterplot with individual plot symbols specified

by user; log or linear axes; user-supplied control values and axis

limits; missing values allowed

<real> Y(n), YMISS, X(n), XMISS, YLB , YUB, XLB , XUB

INTEGER ISYM(n)

CALL SPPMC (Y, YMISS, X, XMISS, N, ISYM, ILOG, ISIZE, NOUT, YLB,

1 YUB, XLB, XUB)

MPP: Print plot of multiple Y vectors versus a common X vector; linear

axes; default control values and axis limits; no missing values

allowed

<real> YM (n,m) t X(n)

CALL MPP (YM, X, N, M, IYM)

2-5
MPPL: Print plot of multiple Y vectors versus a common X vector; log or linear axes; default control values and axis limits; no missing values

allowed

<real> YM( nt m)> X(n)

CALL MPPL (YM, X, N, M, IYM , ILOG)

MPPC : Print plot of multiple Y vectors versus a common X vector; log or linear axes; user-supplied control values and axis limits; no missing

values allowed

<real> YM(n,m), X(n), YLB , YUB, XLB, XUB

CALL MPPC (YM, X, N, M, IYM, ILOG, ISIZE, NOUT, YLB, YUB, XLB,

1 XUB)

MPPM: Print plot of multiple Y vectors versus a common X vector; linear

axes; default control values and axis limits; missing values allowed

<real> YM (n,m), YMMISS(m), X(n), XMISS

CALL MPPM (YM, YMMISS, X, XMISS, N, M, IYM)

MPPML: Print plot of multiple Y vectors versus a common X

linear axes; default control values and axis limits;

allowed

<real> YM (n,m), YMMISS(m), X(n), XMISS

SCALL MPPML (YM, YMMISS, X, XMISS, N, M, IYM, ILOG)

MPPMC: Print plot of multiple Y vectors versus a common X

linear axes; user-supplied control values and axis limits; missing

values allowed

<real> YM {n,m)

,

YMMISS(m), X(n), XMISS, YLB, YUB, XLB, XUB

CALL MPPMC (YM, YMMISS, X, XMISS, N, M, IYM, ILOG, ISIZE, NOUT,

1 YLB, YUB, XLB, XUB)

vector; log or missing values

vector; log or

2-6
Vertical Plots

VP: Print vertical plot of Y versus input order; linear axes; default

control values and axis limits; no missing values allowed

<real> Y(n)

tCALL VP (Y, N, NS)

VPL: Print vertical plot of Y versus input order; log or linear horizontal

(Y) axis; default control values and axis limits; no missing values

allowed

<real> Y (n

)

1CALL VPL (Y, N, NS, ILOG)

VPC: Print vertical plot of Y versus input order; log or linear horizontal

(Y) axis; user-supplied control values and axis limits; no missing

values allowed

<real> Y (n ) , YLB , YUB , XLB , XINC

iCALL VPC (Y, N, NS, ILOG, ISIZE, IRLIN, IBAR, YLB, YUB, XLB,

1 XINC)

VPM: Print vertical plot of Y versus input order; linear axis; default

control values and axis limits; missing values allowed

<real> Y(n), YMISS

CALL VPM (Y, YMISS, N, NS)

VFML: Print vertical plot of Y versus input order; log or linear horizontal

(Y) axis; default control values and axis limits; missing values

allowed

<real> Y (n ) , YMISS

CALL VPML (Y, YMISS, N, NS, ILOG)

2-7
VPMC: Print vertical plot of Y versus input order; log or linear horizontal

(Y) axis; user- supplied control values and axis limits; missing values

allowed

<real> Y(n), YMISS, YLB , YUB , XLB , XINC

CALL VPMC (Y, YMISS, N, NS, ILOG, ISIZE, IRLIN, IBAR, YLB, YUB,

1 XLB, XINC)

SVP: Print vertical plot of Y versus input order with individual plot

symbols specified by user; linear axis; default control values and

axis limits; no missing values allowed

<real> Y(n)

INTEGER ISYM(n)

CALL SVP (Y, N, NS, ISYM)

SVPL: Print vertical plot of Y versus input order with individual plot

symbols specified by user; log or linear horizontal (Y) axis; default

control values and axis limits; no missing values allowed

<real> Y(n)

INTEGER ISYM(n)

CALL SVPL (Y, N, NS, ISYM, ILOG)

SVPC: Print vertical plot of Y versus input order with individual plot

symbols specified by user; log or linear horizontal (Y) axis;

user-supplied control values and axis limits; no missing values

allowed

<real> Y(n), YLB, YUB, XLB, XINC

INTEGER ISYM(n)

CALL SVPC (Y, N, NS, ISYM, ILOG, ISIZE, IREFLN, IBAR, YLB, YUB,

1 XLB, XINC)

2-8
SVPM:

SVPML:

SVPMC:

MVP:

Print vertical plot of Y versus input order with individual plot

symbols specified by user; linear axis; default control values and

axis limits; missing values allowed

<real> Y(n), YMISS

INTEGER ISYM(tt)

CALL SVPM (Y, YMISS, N, NS, ISYM)

Print vertical plot of Y versus input order with individual plot

symbols specified by user; log or linear horizontal (Y) axis; default

control values and axis limits; missing values allowed

<real> Y(n), YMISS

INTEGER ISYM(n)

CALL SVPML (Y, YMISS, N, NS, ISYM, ILOG)

Print vertical plot of Y versus input order with individual plot

symbols specified by user; log or linear horizontal (Y) axis;

user-supplied control values and axis limits; missing values allowed

<real> Y(n), YMISS, YLB , YUB , XLB , XING

INTEGER ISYM(n)

CALL SVPMC (Y, YMISS, N, NS, ISYM, ILOG, ISIZE, IRLIN, IBAR, YLB,

1 YUB, XLB, XING)

Print vertical plot of multiple Y vectors versus input order; linear

axis; default control values and horizontal (Y) axis limits; no missing values allowed

<real> YM(n3 m)

CALL MVP (YM, N, M, IYM , NS)

2-9
MVPL: Print vertical plot of multiple Y vectors versus input order; log or linear horizontal (Y) axis; default control values and axis limits; no missing values allowed

<real> YM (ny m)

CALL MVPL (YM, N, M, IYM, NS, ILOG)

MVPC: Print vertical plot of multiple Y vectors versus input order; log or linear horizontal (Y) axis; user-supplied control values and axis

limits; no missing values allowed

<real> YM YLB

,

YUB , XLB , XINC

CALL MVPC (YM, N, M, IYM, NS, ILOG, ISIZE, YLB, YUB, XLB, XINC)

MVPM: Print vertical plot of multiple Y vectors versus input order; linear

axis; default control values and axis limits; missing values allowed

<real> YM (n} m), YMMISS(m)

CALL MVPM (YM, YMMISS, N, M, IYM, NS)

MVPML: Print vertical plot of multiple Y vectors versus input order; log or linear horizontal (Y) axis; default control values and axis limits;

missing values allowed

<real> YM (n, m ) , YMMISS(m)

CALL MVPML (YM, YMMISS, N, M, IYM, NS, ILOG)

MVPMC: Print vertical plot of multiple Y vectors versus input order; log or linear horizontal (Y) axis; user-supplied control values and axis

limits; missing values allowed

<real> YM(n,m), YMMISS (tf?) , YLB, YUB, XLB, XINC

CALL MVPMC (YM, YMMISS, N, M, IYM, NS, ILOG, ISIZE, YLB, YUB,

1 XLB, XINC)

2-10
D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE:

I BAR

I ERR

I LOG

IRLIN

—> indicates that the argument is input to the subroutine and that

the input value is preserved;

< — indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine;

indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

**• indicates that the variable is passed via COMMON. —> The indicator variable used to designate whether a vertical plot

is to be a bar plot or not. Bar plots connect the plotted points

to the reference line [see argument IRLIN] with a string of plot

symbols. [See, e.g., chapter 12, figure F-lc. ] If IBAR > 1, the

plot is a bar plot. If IBAR < 0, it is not. The default value is

IBAR = 0. When IBAR is not an argument in the subroutine CALL

statement the default value is used.

'** An error flag returned in COMMON /ERRCHK/. [See chapter 1, § D . 5 .

]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided.

IERR = 0 indicates that no errors were detected and that the plot

was completed satisfactorily.

IERR = 1 indicates that improper input was detected or that some error prevented the plot from being completed. —> The indicator variable used to designate whether the axes are to

be on a log or linear scale. ILOG is a two-digit integer, pq

,

where the value of p is used to designate the scale of the x-axis

and the value of q is used to designate the scale of the y-axis.

If p = 0 (q = 0) the x-axis (y-axis) is on a linear scale; if

p * 0 (q * 0) the x-axis (y-axis) is on a log scale. For vertical

plots, the value of q is used to specify the scale on the

horizontal-axis and the value of p is ignored. The default value

is ILOG = 0, corresponding to linear scale for both the x-axis and

the y-axis. When ILOG is not an argument in the subroutine CALL

statement the default value is used. —•> The indicator variable used to designate whether zero or the

series mean is to be plotted as a reference line on the vertical

plots or whether no reference line should be used. If IRLIN < -1,

no reference line is plotted. If IRLIN = 0, a reference line is

plotted showing the location of zero on the plot. If IRLIN > 1, a reference line is plotted showing the series mean. The default

value is IRLIN = -1. When IRLIN is not an argument in the

subroutine CALL statement the default value is used.

2-1

1
[SIZE —> The indicator variable used to designate the size of a page plot.

ISIZE is a two-digit integer, pq , where the value of p is used to

designate the size of the x-axis and the value of q is used to

designate the size of the y-axis. If p = 0 (q = 0) the x-axis

(y-axis) is the maximum possible, 101 columns (51 rows), i.e., 101

(51) plot positions. If p t 0 (q t 0) the x-axis (y-axis) is half

the maximum, or 51 columns (26 rows). For vertical plots, the

value of q is used to specify the size of the horizontal-axis and

the value of p is ignored. The default value is ISIZE = 0,

corresponding to a plot of 51 rows by 101 columns. When ISIZE is

not an argument in the subroutine CALL statement the default value

is used.

ISYM —> The vector of dimension at least N that contains the values

designating the plotting symbol to be used for each point. The

plot symbols designated by each possible integer value are given

below.

IYM

ISYM(* )< 1 + +

I SYM (

« )= 2 - • I SYM(* )= 3 + *

I SYM ( ° )= 4 -

I SYM ( • )= 5 A

I SYM ( • )= 6 > B

I SYM ( * )= 7 * C

I SYM (

» )= 8 -» D

ISYM( • )= 9 -» E

ISYM( ® )=10 + F

ISYM( » ) = 11 G

ISYM( • ) = 1 2 ->• H

ISYM( • )=1 3 * I ISYM( ® )=14 * J

I SYM (

® ) = 1 5 + K

ISYM( • ) = 1 6 -» L

ISYM( « )=1 7 + M

ISYM( • ) = 18 + N

ISYM( • ) = 19 - 0

ISYM( • )=20 + P

ISYM( • )=2 1 * Q

ISYM( • )=22 * R

ISYM(» )=23 + S ISYM(» )=24 T

I SYM ( • )=25 -v U

ISYM(* )=26 + V

I SYM (

® )=27 W

ISYM(» )=28 ^ Y

ISYM(» )> 29 Z

> The exact value of the first dimension of the matrix YM as specified in the calling program.

M --> The number of columns of data in YM.

N —> The number of observations.

NOUT —> The number of points falling outside the plot limits that are to

be listed following the plot. If NOUT > 1 , a message giving the

total number of points falling outside the plot limits and a list

of the coordinates of these points (up to a maximum of NOUT or 50,

whichever is smaller) is printed. If NOUT = 0, only a message

listing the number of points falling outside the limits is

printed. If NOUT < 0, no points are listed and no message is

given. The default value is NOUT = 0. When NOUT is not an argument in the subroutine CALL statement the default value is

used.

NS —> The sampling frequency of the points plotted on a vertical plot.

If NS = 1, every point is plotted; if NS = 2, every second point

is plotted; if NS = 3, every third point is plotted, etc. The

default value is NS = 1. When NOUT < 0 or NS is not an argument

in the subroutine CALL statement the default value is used.

2-12
X —> The vector of dimension at least N that contains the x-axis

values.

XINC —> The increment to be used for labeling the x-axis (i.e., the

vertical-axis) on vertical plots. The x-axis labels are XLB

,

XLB + NS»XINC, XLB + 2»NS*XINC, etc. The default value is

XINC = 1.0. When XINC is not an argument in the subroutine CALL

statement the default value is used.

XLB --> The lower bound for the x-axis.

For page plots:

The default value is the smallest x-axis value within the range

of the y-axis values to be plotted. If XLB > XUB , the default

value is used.

For vertical plots:

The default value is 1.0.

For both page and vertical plots, when XLB is not an argument in

the subroutine CALL statements the default value is used. (The

plot limits may be adjusted slightly from the user-supplied values

when the plotting subroutine uses a log scale.

)

XMISS —> The missing value code used within the vector X to indicate that a value is missing. The user must indicate missing observations by

putting the missing value code in place of each missing

observation. Missing data are not indicated on page plots in any

way

.

XUB —> The upper bound for the x-axis. The default value is the largest

x-axis value within the range of the y-axis values to be plotted.

If XLB > XUB or XUB is not an argument in the subroutine CALL

statement the default value is used. (The plot limits may be

adjusted slightly from the user-supplied value when the plotting

subroutines use a log scale.

)

Y --> The vector of dimension at least N that contains the y-axis

values.

YLB --> The lower bound for the y-axis. The default value is the smallest

y-axis value within the range of the x-axis values to be plotted.

If YLB > YUB or YLB is not an argument in the subroutine CALL

statement the default value is be used. (The plot limits may be

adjusted slightly from the user-supplied value when the plotting

subroutines use a log scale.

)

YM —> The matrix of dimension at least N by M whose columns each contain

one of the M sets of N observations to be plotted against a common

X vector.

2-13
YMISS —> The missing value code used within the vector Y to indicate a value is missing. The user must indicate missing observations by

putting the missing value code in place of each missing

observation. Missing data are indicated on vertical plots by the

word "MISSING" next to the right axis of the appropriate line.

Missing data are not indicated on page plots in any way.

YMMISS —> The vector of dimension at least M that contains the codes used

within each of the M columns of YM to indicate a value is missing,

where the first element of YMMISS is the missing value code for

the first column of YM, etc. The user must indicate missing

observations by putting the appropriate missing value code in

place of each missing observation. Missing data are indicated on vertical plots by the word "MISSING" next to the right axis of the

appropriate line. Missing data are not indicated on page plots in

any way.

YUB —> The upper bound for the y-axis. The default value is the largest

y-axis value within the range of the x-axis values to be plotted.

If YLB YUB or YUB is not an argument in the subroutine CALL

statement the default value is used. (The plot limits may be

adjusted slightly from the user-supplied value when the plotting

subroutines use a log scale.

)

E . Computational Details

Plotting Symbols . The plotting symbol used depends on the type of plot

and whether or not more than one point falls on a given plot position. If two

to nine points fall on a single plot position, the integer corresponding to

the number of points is used as the plotting symbol. When 10 or more values

fall on a single position the plotting symbol X is used. This is the only way

that integers or X are used as plot symbols.

Subroutines without an S or M prefix use the plotting symbol + to

indicate one point on a single printer position.

For subroutines with an S prefix the user-supplied vector ISYM of integer

values is used to specify the plotting symbol for each data point. The

Fourier spectrum plot shown in chapter 12, figure F-3b, is an example of this

option.

Subroutines with an M prefix use a different letter as the plot symbol

for each column of the matrix of the dependent variables (y-axis): A for the

first, B for the second, ..., Z for columns 25 and beyond, with X still only

used to indicate that 10 or more points fell on a single plot position.

2-14
Continuity of Vertical Plots . Normally, a line printer will

automatically provide margins at the top and bottom of each page, causing a break in the continuity of a vertical plot or any other output continuing over

two or more pages. However, these automatic page-ejects can be suppressed by

the user on many systems. Appendix A gives the control sequence necessary to

suppress automatic page-ejects on a Cyber computer. Users of other systems

should consult their Computer Center staff for any equivalent method

available.

F . Examples

The example program of figure F-la uses MPP to display the 12 years of

monthly airline data listed on page 531 of Box and Jenkins [1976] versus

month. The year is indicated by the plotting symbol (A = 1949, B = 1950,

etc.). Figure F-lb shows the output from this program.

Other examples of STARPAC plots can be found in the output of many of the

subroutines discussed elsewhere. The output from the complex demodulation

subroutines includes a simple vertical plot (VP) (chapter 11, figure F-lb) and

a vertical plot of multivariate data (MVPC) (chapter 11, figure F-lc); the

output from the autocorrelation and cross correlation subroutines includes

vertical plots using the bar plot, option (VPC) (chapter 12, figure F-lc); and

the output from the Fourier spectrum subroutines (chapter 12, figure F-3b) is

produced using a symbol plot (SPPC).
MAIN PROGRAMI “ROGRAN EXAHPL

DATA I

C

C DEMONSTRATE MPP USING SINGLE PRECISION VERSION OF STARPAC

C RUN ON CYBER 180/BA0.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE6 ON CYBERS)

C CSEE CHAPTER 1> SECTION D.43

C

C N.B. DECLARATION OF X AND YM MUST BE CHAN6ED TO DOUBLE PRECISION IF

C DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL X ( 20 ) « YN ( 20» 2 0

)

C

C SPECIFY NECESSARY DIMENSIONS

C

I YM « 20

C

C READ NUMBER OF OBSERVATIONS AND NUMBER OF COLUMNS OF DATA

C X-AXIS VALUES

C Y-AXIS VALUES

C READ 100» N» M READ 101# (X(Ii» I«1#N» READ 101# ( t YM ( I # J ) # X«1#N)# J«»l,Mi

C

C PRINT TITLE AND CALL MPP FOR PLOT

C WRITE (6 # 102) CALL MPP (YM, X# N* M# I YM

)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (215)

101 FORMAT J12F6.1)

102 FORMAT (URiSUlTS OF STARPAC PLOT SUBROUTINE HPP»)

END

12 12 1.0 2.0 3.0 5.0 3.0 6.0 7.0 e.o 9.0 10.0 11.0 12.0

112.0 118.0 132.0 129.0 m.o 133.0 158.0 158.0 136.0 119.0 105.0 116.0

115.0 126.0 151.0 135.0 125.0 159.0 170.0 170.0 158.0 133.0 115.0 150.0

155.

0

150.0 178.0 163.0 172.0 178.0 199.0 199.0 185.0 162.0 156.0 166.

0

m.o 180.0 193.0 m.o 183.0 218.0 230.0 252.

0

209.0 191.0 172.0 195.0

196.0 196.0 236.0 233.0 229.0 253.0 265.0 272.0 237.0 211.0 180.0 201.0

205.0 188.0 235.0 227.0 235.0 265.0 302.0 293.0 259.0 229.0 203.0 229.0

252.0 233.0 267.0 269.0 270.0 313.0 365.0 357.0 312.0 275.0 237.0 278.0

285.0 277.0 317.0 313.0 318.0 375.0 513.0 509.0 335.0 306.0 271.0 306.0

313.0 301.0 336.0 358.0 353.0 522.0 563.0 567.0 505.0 357.0 309.0 336.0

350.0 316.0 362.0 358.0 363.0 535.0 591.0 505.0 505.0 359.0 310.0 337.0

360.0 352.0 506.0 396.0 520.0 572.0 358.0 539.0 563.0 507.0 362.0 505.0

517.0 391.0 519.0 561.0 572.0 535.0 622.0 606.0 308.0 561 .0 390.0 532.0

Figure F-la

Example program using MPP

2-16
Example

of

MPP

output
I

p

p

p

fl

(1

III

III

III

III

III

III

111

1

I

II

II

n

[i
CHAPTER 3

NORMAL RANDOM NUMBER GENERATION

A. Introduction

STARPAC contains two subroutines for generating pseudo-random numbers

(noise) which obey a normal probability law with mean p and standard deviation

a. Such random numbers are often useful for evaluating data analysis

procedures or computer programs.

Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithm used by these subroutines is discussed in

§E. A sample program showing the use of these subroutines is given in §F.

B

.

Subroutine Descriptions

STARPAC subroutine NRAND generates a vector of standard (zero mean and

unit standard deviation) normal (Gaussian) random numbers. There is no printed output from this subroutine.

STARPAC subroutine NRANDC generates Gaussian noise with mean p and

standard deviation a using the transformation

z = ay + p

where

y is a standard normal psuedo-random number;

p is the desired mean (see §D, argument YMEAN); and

o is the desired standard deviation (see §D, argument SIGMA).

There is no printed output from NRANDC.

C

.

Subroutine Declaration and CALL Statements

NOTE: Argument definitions and a sample program are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and D.

3-1
NRAND: Generate a vector of normal pseudo-random numbers with zero mean and

unit standard deviation

<real> Y (n)

CALL NRAND (Y, N, ISEED)

NRANDC: Generate a vector of normal pseudo-random numbers with mean YMEAN and

standard deviation SIGMA

<real> Y («)

CALL NRANDC (Y, N, ISEED, YMEAN, SIGMA)

D. Dictionary of Subroutine Arguments

NOTE: —> indicates that the argument is input to the subroutine and that

the input value is preserved;

<-- indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine;

- — indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

* *

• indicates that the variable is passed via COMMON,

IERR ... An error flag returned in COMMON /ERRCHK/. [See chapter 1, §D.5.]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

ISEED ' —> The basis for the pseudo-random number generation.

For ISEED t 0, use of the same value of ISEED will always

generate the same data set.

For ISEED = 0, a different data set will be produced by each call

to NRAND or NRANDC in the user's program, although

the numbers generated will not differ from run to run.

N —> The number of random numbers to be generated.

3-2
SIGMA —> The standard deviation of the generated random numbers.

Y <— The vector of dimension at least N that contains the

normal pseudo-random numbers.

YMEAN —> The mean of the generated random numbers.

E . Computational Methods

generated

The normal pseudo-random number generation procedure is that of Marsaglia

and Tsang [1984]. The same pseudo-random numbers (to within final round-off

error) will be generated on any computer. The code was written by Boisvert

and Kahanar of the National Bureau of Standards Scientific Computing

Division.

F . Example

The sample program shown in figure F-la illustrates the use of both NRAND

and NRANDC. NRAND is used to generate a standard normal pseudo-random sample

of size 50 from a normal population with zero mean and unit standard

deviation. NRANDC is then used to generate a sequence of normal pseudo-random

numbers with a mean of 4 and standard deviation 0.5. The same seed is used

for both NRAND and NRANDC. Therefore, the values generated by NRANDC are YMEAN plus SIGMA times the values generated by NRAND, i.e.

,

YMEAN (I, 2) = YMEAN + S IGMA*YMEAN (1,1) f or I = 1 ,

. . .

,

N.

The generated random numbers are displayed using STARPAC plot subroutine MVP.

Figure F-lb shows the output from MVP. There is no output from NRAND and

NRANDC.
MAIN PROGRAHl

c

c

cc

c

cc

c

c

c

c

c

c

c

c

c

c

c

c

cc

c

c

cc

c

e

c

c

ec

e

PROGRAM EXAMPL DEMONSTRATE NR AND AND NRANDC AND DISPLAT RESULTS WITH MVP USING

SINGLE PRECISION VERSION OF STARPAC RUN ON CYBER 180/8*0.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE6 ON CYBERS)

[SEE CHAPTER 1» SECTION D.A1

N.B. DECLARATION OF YM MUST BE CHANGED TO DOUBLE PRECISION IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL YH ( 100» 2

)

SPECIFY NECESSARY DIMENSIONS

I YH - 100

SET THE SEED

THE NUMBER OF VALUES TO BE GENERATED

THE NUMBER OF SETS OF DATA TO BE GENERATED

ISEEO » 931

N • 90

M 2 GENERATE STANDARD NORMAL PSEUDO-RANDOM NUMBERS INTO COLUMN l OF YH

CALL NR AND (YM(l#lJj> N» ISEEO

»

GENERATE NORMAL PSEUDO-RANDOM NUMBERS WITH MEAN AeO AND STANDARD DEVIATION 0.5 INTO COLUMN 2 OF YM YHEAN * A.O SIGMA * 0.9 CALL NRANDC !YMU»2I«> N» ISElDg YHEAN? SIGNAI PRINT TITLE AND CALL MVP TO PLOT RESULTS

WRITE (6? 1008 CALL MVP «YM» N» Mg IYH9

STOP FORMAT STATEMENTS

100 FORMAT C'lRfSULTS OF STARPAC NORMAL PSUIDO-RANDOM NUMBER *

t

1 » GENERATION SUBROUTINES »

t

2 * DISPLAYED WITH STARPAC PLOT SUBROUTINE MVP* > END

Figure F-la

Example program using NRAND, NRANDC and MVP

3-4
1

«

*r> JC>

OLOJ

er «r> T O

ooooooooo ooooooooo oooooo ooo oooooo

oooooooo oooooooo oooooooooooooooo ooooo ooo

oooooooo

ooooooooo ooooooo o o ooooooooo

oooooooo oooooooo

uo

UJ

• « • • • • • • » o hn to ^ri or>'flDOo«-4<vjm'*-irv-or-«DQ‘0 r-e <M rr* 1*1 ON « 0' OH (vim < in ^ M> ff'O

CO m (tl in ^ ^ «# ^ ^ ^ ^

3-5

Example

of

NRAND

and

NRANDC

results

displayed

using

MVP
G . Acknowledgments

The code used to generate the pseudo-random numbers was written by H

Boisvert and Kahanar of the National Bureau of Standards Scientific Computing

Division.

I

a

a

ii

si

H

I

1

II

1

I

I

a

a

a

3-6
CHAPTER 4

HISTOGRAMS

A. Introduction

STARPAC contains two subroutines for producing histograms. Both

subroutines produce a one-page printout which includes, in addition to the

histogram, a number of summary statistics (mean, median, standard deviation,

cell fractions, etc. ) and several tests for normality.

Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F

.

B

.

Subroutine Descriptions

HIST provides the analysis described in §A using a preset procedure for

choosing the number of cells. The lower and upper bounds of the histogram are chosen from the range of the observations.

HISTC provides the same analysis as HIST but allows the user to specify

the number of cells and the upper and lower cell boundaries. Statistics are based only on the data within the user-supplied bounds.

C

.

Subroutine Declaration and CALL Statements

NOTE; Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and D.

HIST: Compute and print a histogram and summary statistics, with automatic

selection of number of cells and cell boundaries

<real> Y(n)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL HIST (Y, N, LDSTAK)
HISTC: Compute and print a histogram and summary statistics with user

control of number of cells and cell boundaries

<real> Y(n)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL HISTC (Y, N, NCELL, YLB , YUB , LDSTAK)

D. Dictionary of Subroutine Arguments

NOTE: —> indicates that the argument is input to the subroutine and that

the input value is preserved;

< — indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; --- indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

* * * indicates that the variable is passed via COMMON.

DSTAK. c “ The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

IERR * * * An error flag returned in COMMON /ERRCHK/. [See chapter 1, §D . 5 .

]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

LDSTAK —> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P = 0.5,

otherwise P = 1.0. [See chapter 1, § B .

]

For HIST: LDSTAK > (17+N)/2 + 26-P

For HISTC: LDSTAK > (17+N)/2 + max( NCELL, 26)«P

N —> The number of observations.

NCELL —> The number of cells in the histogram. If NCELL < 0 or NCELL is

not an argument in the subroutine CALL statement the subroutine

will choose the number of cells.

4-2
Y —> The vector of dimension at least N that contains the observed

data.

YLB —> The lower bound for constructing the histogram. The interval

[YLB, YUB ] is divided into NCELL increments. If YLB > YUB , the

lower and upper bounds for constructing the histogram will be the

minimum and maximum observations.

YUB —> The upper bound for constructing the histogram. The interval

[YLB, YUB] is divided into NCELL increments. If YLB > YUB, the

lower and upper bounds for constructing the histogram will be the

minimum and maximum observations.

E . Computational Methods

E . 1 Algorithms

The code and output for the histogram subroutines are modeled after early

versions of MINITAB [Ryan et al. 1974]

.

E „ 2 Computed Results and Printed Output

The output from the histogram family of subroutines includes a summary of

the input data in addition to the actual histogram. This summary includes the

following information, where the actual output headings are given by the

underlined, uppercase phrases. Results which correspond to subroutine CALL

statements arguments are identified by the argument name in uppercase (not

underlined). In the formulas, x \ , X2 , ...» x^ denotes the ordered

observations of Y such that YLB < Y(i) < YUB, i = 1, ..., N, i.e. , x^ is the

smallest observation of Y such that YLB < Y(i), x^ is the largest observation

of Y such that Y(i) < YUB, etc. The value of expressions enclosed in square

brackets, e.g. , [(k/2) +1], is the largest integer less than or equal to the

value of the expression.

© NUMBER OF OBSERVATIONS , N

© MINIMUM OBSERVATION

o MAXIMUM OBSERVATION

© HISTOGRAM LOWER BOUND , YLB

© HISTOGRAM UPPER BOUND , YUB

o NUMBER OF CELLS , NCELL

o OBSERVATIONS USED , k, where

k = the number of observations for which

YLB < Y(i) < YUB, i = 1, ..., N

4-3
o MIN. OBSERVATION USED , x L

, where 1

= the smallest observation such that YLB < Y(i), i = 1, N

p

o MAX. OBSERVATION USED , xk , where

xk

= the largest observation such that Y(i) < YUB, i = 1, ..., N J

o MEAN VALUE , xmean , where

k

^Snean k

I xi

i = l

o MEDIAN VALUE , Xmedian’ where

xmedian = x [(k+l)/2] if k is odd

xmedian = °* 5 *( x [k/2] + x [(k/2) + 1]) 1

© 25 PCT TRIMMED MEAN , xtritn , where

k~[k/4]

xtrim =

[ k“( 2 * [k/^])]" 1 l x£

i=l+ [k/ 4

]

• STANDARD DEVIATION, s, where

k

9 1/2

s = ( (k— 1 £ (x-i ^ean' ) i=l

© MEAN DEV. /STD. DEV.

,

r, where

k

r - (s»k) £ l xi”xmearJ

i=l

• SQRT(BETA ONE)

,

&l

1/2

, where

Bl = ( (k-l)

3 .s

6

) -1( l (xi-xmean) 3

)

2 .k

i = l

© BETA TWO

,

g2, where,

8 2 = ( (k— 1

)

2

« s

4

)

1 l (xi"xmean ) 4 .k

i = l

V

V

k is even

11

I

I

I

II

9

I

a

9

I

I

4-4
Information provided for each cell, £ = 1, NCELL, of the histogram

includes the following.

® INTERVAL MID POINT , cmid , where

Cmid = YLB + (YUB-YLB)/ (2* NCELL)

• CUM. FRACT. , the cumulative fraction of the observations which are in

cells 1 through £

• 1-CUM. FRACT. , the cumulative fraction of the observations which are in cells £ through NCELL

9 CELL FRACT. , the fraction of the observations which are in cell £

9 NO. OBS. , the actual number of observations which are in cell £

.

The histogram itself displays the actual number of observations in each

cell when the largest number of observations per cell does not exceed 50.

When the largest number of observations per cell does exceed 50 then the

histogram displays the cell fraction.

F . Example

The example program of figure F-la uses HIST to analyze the 39

measurements of the velocity of light shown on page 81 of Mandel [1964]. The

output from HIST is shown in figure F-lb.

4-5
MAIN PROGRAM! PROGRAM EXAMPL

DATA!

C

C DEMONSTRATE HIST USING SIN6LI PRECISION VERSION OP STARPAC

C RUN ON CYBER 1BO/8AO.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPES ON CYBERS)

C C SEE CHAPTER 1# SECTION D.4J

C

C N.B. DECLARATION OF Y MUST BE CHANGED TO DOUBLE PRECISION IF

C DOUBLE PRECISION VERSION OF STARPAC IS USED*

C REAL YC2O0S DOUBLE PRECISION OSTAM2O0)

C COMMON /CSTAK/ DSTAK

CC SPECIFY NECESSARY DIMENSIONS

C LDSTAK ® 20©

C

C READ NUMBER OF OBSERVATIONS

C OBSERVED DATA

C READ 100# M READ 101# IYCIJ# X-1#N>

C

C PRINT TITLE AND CALL HIST TO ANAL VIE RESULTS

C WRITE (6# 102

1

CALL HIST ( Y# N# LDSTAK

I

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT CIS!

101 FORMAT U3F9.1)

101 FORMAT (URESULTS OF STARPAC HISTOGRAM SUBROUTINE HIST')

END

39 0.4 0.6 1.0 i.e 1.0 0.9 6.6 O.T 1 e 6 0.6 0.2 1.9 0.2

0.4 0.0 -0.4 ®0 © s © 9 © -0.4 -0.1 0.1 - 0.1 0.2 -0.9 0.3 -0.1

0.2 “0.2 0.8 © ® t> 0.8 © 8 ? O.T 0.2 0.9 e.T 0.6 1.1

Figure F-la

Example program using HIST

4-6
9««iMi<«Mi«i««mi

**J p*3 «**<

O

O

©O

O

© I i t a UJ UJ UJ LU UJ

«#

©

<M O* >#• *0 o ^ © -O m © 0D «r O ® -^ © K> Cl » O

«v© (-<

m o © o ® ® ^ ^ 2 « 4 Z> uj O uj Z (« ©

=>

© «* « *—

IU ni

O

U £> KZ X ttj^G

«©'«*=»

@£

® ^ © » *-

a « tt)UJ 3

t»= ^ ©

®

©

© '—

a. z Z «« < < Ot K>

if< »»

u

aw

w wrwaj

(?* *^i o

«*»

©

©| 4> uj rjj © © © OOo © o © ©oa oM z Z

»-> o o > - *~

at •< *« uj >• >

i/

aa

m unu O «> on

03 CD

U.CO c ©

©

A

O

Uf UJ © ©© o © O O ©o © o o o o• • r» h0 3 3 a a

CD CD 3r a. C Ol -J 3

at at o © o o

H- fr- iz* I/) X I

fb ^ *-<

©H

H

©

©©

a

«*> e i uj uj uj uj © © © ©

(*a

© ©a**© 00 4 0 © © r* © © O NO o o © o 09H0 • • • •

«T> t-4 •+ *\

Ul (r» UJ O Z » > 3 a a uj _j

U.

H UJ UJ 3 4

OH- on t/i _j » 4 (D (S <

a. > O

O >• Z

JC on z x < o D ai m < uj uj 2 I I I I 2 cr> *-• © X <NJ C I QC Ha. o

a. <m

oc on * o fr-

<** on

UJ

U UJ Z O fr- O

on uj 4 ai </) H «J UJ

UJ CDX

® < 0-

'**» t— u. a uj C ©

u> oc ©CO oc U

<k on © 1-5

® Z on <o

•m. uj 0 I

on o ^ a z a, • O >> A. X ft- ^ 3 on

uj Z ©

on

UJ D> 3 O on I —J * H Ul l/> z - *« DUH < UJ on

*— «. on

4/1

O uj

O «*> cd

•<

—I O H- O O z • OC o fr— a B O o • *-> U OB

>,

©

QC

ocO • UJ JVJ • on O ® z c > o

OC Q- I

0)

J-i

5c

°H + + +

4, <*. +

om HHr»o

«#

® fSI <Vi OB

© <©

«n «v

®® ru

© «s»

N (V HOO

© « ® <o

©

© ** f*

mm fsj «nj o c n o o # N < O < O

Ml 03 -O « K f>

O

HN IO « O

O©

HNHHQl 0 0 0 0 0 4 1111 +

UJ UJ UJ UJ uj I + HOON- r-« r- f\j o r> i H B ^ O O I ri ® H o N i ® <\J H O + I N + B o O i <n h m n h ( m

4-7

Example

of

HIST

output
G. Acknowledgments

The code and

early versions of

output

MINITAB

f or the histogram subrout

[Ryan et al. 1974]

.

ines is modeled on that in

4-8
CHAPTER 5

STATISTICAL ANALYSIS OF A UNIVARIATE SAMPLE

A. Introduction

STARPAC contains 4 subroutines for performing a comprehensive statistical

analysis of a univariate sample. They each compute 53 different statistics

which summarize the sample through measures of location (mean, median, etc),

measures of dispersion (standard deviation, mean deviation, etc. ) and

diagnostic features such as tests for outliers, non-normality, trends and

non-randomness (assuming the input order of the data is a meaningful time

sequence). Common statistics such as Student's t and confidence intervals for

the mean and standard deviation are also included. NBS Technical Note 756, A

User's Guide to the OMNITAB Command "STATISTICAL ANALYSIS ," by H. H. Ku [1973]

provides a complete discussion of the output of these subroutines, which is

the same output as that provided by the OMNITAB II Command STATISTICAL [Hogben

et al. 1971] .

Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F.

B

.

Subroutine Descriptions

STAT computes and prints the 53 descriptive statistics described in §A.

STATS provides the same analysis as STAT but allows the user to suppress

the printed output and store the computed statistics for further use.

STATW and STATWS perform a weighted analysis and are otherwise identical

to STAT and STATS, respectively.

C

.

Subroutine Declaration and CALL Statements

NOTE: Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

5-1
STAT: Compute and print 53 statistics describing the input data

<real> Y(n)

DOUBLE PRECISION DSTAK ( Idstak ) COMMON /CSTAK/ DSTAK

CALL STAT (Y, N, LDSTAK)

STATS: Compute and optionally print 53 statistics describing input data;

return statistics

<real> Y(n), STS(53)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL STATS (Y, N, LDSTAK, STS, NPRT

)

STATW: Compute and print 53 statistics describing weighted input data

<real> Y(n), WT (n)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL STATW (Y, WT, N, LDSTAK)

STATWS: Compute and optionally print 53 statistics describing weighted input

data; return statistics

<real> Y (n ) , WT(rc), STS(53)

DOUBLE PRECISION DSTAK (Idstak ) COMMON /CSTAK/ DSTAK

CALL STATWS (Y, WT, N, LDSTAK, STS, NPRT)

5-2
D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE:

DSTAK

IERR

LDSTAK

N

NPRT

STS

—> indicates that the argument is input to the subroutine and that

the input value is preserved;

< — indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; —— indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

**• indicates that the variable is passed via COMMON.

* * * The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

* *

* An error flag returned in COMMON /ERRCHK/. [See chapter 1, § D . 5 .

]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

-~> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed (N/2) + 7. —> The number of observations.

TM> The argument controlling printed output.

If NPRT = 0 the printed output is suppressed.

If NPRT £ 0 the printed output is provided. —> The vector of dimension at least 53 that contains the computed

statistics. The contents of STS are listed below, along with

applicable references; the number in parenthesis is the location

within STS that the given statistic is stored. In the formulas, x denotes the ordered observations of Y for which the weight is

nonzero, i.e. , xi is the smallest observation of Y with a nonzero

weight, x^ is the largest observation of Y with a nonzero weight,

etc. The weight associated with x-j_ is denoted w^. Zero weighted

observations are not included in the analysis. The value of

expressions enclosed in square brackets, e.g., [(k/2) +1], is the

largest integer less than or equal to the value of the

expression.

(1) NUMBER OF OBSERVATIONS, N

(2) NUMBER OF NONZERO WEIGHTS, k

5-3
(3) UNWEIGHTED MEAN [Dixon and Massey, 1957, p. 14],

^Snean k

I xi

i = l

(4)

WEIGHTED MEAN [Brownlee, 1965, pp. 95-97],

l_ ( wi* xi) xwtdmean ~ ili-

, . - . n k

I wi

i=l

(5) MEDIAN [Dixon and Massey, 1957, p. 70],

xmedian = x [(k+l)/2] if k is odd

xmedian = °’ 5 *( x [k/2] + x [(k/2) + 1]) if k is even

(6) MID-RANGE [Dixon and Massey, 1957, p. 71],

xmid = 0 ' 5 *( x i + xk>

(7) 25 PCT UNWTD TRIMMED MEAN [Crow and Siddiqui, 1967],

k-[k/4]

x trim =

I k~( 2 * W^])]~l l xi

i=l+ [k/4]

(8) 25 PCT WTD TRIMMED MEAN,

k-[k/4]

l (wi'Xi)

xwtdtritn

= ___ k-[k/4]

l wi

i=l+ [k/4]

(9) WEIGHTED STANDARD DEVIATION [Snedecor and Cochran, 1967,

P* 44]

,

s

( (k 1) I wi*^ x i Xwtdmean^ ) i=l

(10)

WTD S«D. OF MEAN [Brownlee, 1965, p. 80],

s mean

= s ' ( I wi)

W2

i=l

5-4
(11)

RANGE [Snedecor and Cochran, 1967, p. 39],

x range xk

X

1 (12)

MEAN DEVIATION [Duncan, 1965, p. 50],

k

_ 1 V Ii xmeandev ~ x L I x i -xwtdmean

I

i=l

(13) VARIANCE [Snedecor and Cochran, 1967, p. 44],

k

s

2 = (k- 1)" 1 l (Xi-Xvtdmean^2

i = l

(14) COEF. OF VAR. (PERCENT) [Snedecor and Cochran, 1967, p. 62],

cvar = | 100 -s/xwtdmean |

(15) LOWER CONFIDENCE LIMIT, MEAN [Natrella, 1966, pp. 2-2, 2-3],

xmean

~ t 0.025* s mean

where tQ 025 is the appropriate t-statistic with (k- 1 ) degrees of freedom

(16)

UPPER CONFIDENCE LIMIT, MEAN [Natrella, 1966, pp. 2-2, 2-3],

xmean + t 0.025* s mean

where tQ Q 25 is the appropriate t-statistic with (k- 1 ) degrees of freedom

(17) LOWER CONFIDENCE LIMIT, S.D. [Natrella, 1966, p. 2-7],

s*( (k-l)/x

2 o o 97 5 ) 1/2

where x

2 0 975 i s t ^ie appropriate chi-square statistic with

(k- 1 ) degrees of freedom

(18) UPPER CONFIDENCE LIMIT, S.D. [Natrella, 1966, p. 2-7],

, . . 9 > 1/2

s *l (k-l)/xz 0 . 02 5J

where x

2 0 025 :*' s t ^ie appropriate chi-square statistic with

(k- 1 ) degrees of freedom

(19) SLOPE [Fisher, 1950, p. 136],

= ( k* (k 2 -l )

)

-1

k

12 l

ii = l(x- ^td mean •

5-5
(20) S.D. OF SLOPE,

[( 12 ,I ^i-Xwtdmean) 2

) ~ B

2

* k- (k2 -1 )]

1 72

S B = Llli (k« (k 2 -1 )

- (k-2)) 1/2

(21) SLOPE/S. D. OF SLOPE = T,

tQ = B / sg with (k-2) degrees of freedom

(22) PROB EXCEEDING ABS VALUE OF OBS T [Brownlee, 1965, p. 344],

Pr{t < — | tQ I and t > + 1 1 q | }

(23) NO. OF RUNS UP AND DOWN [Brownlee, 1965, p. 223], r

(24) EXPECTED NO. OF RUNS [Bradley, 1965, p. 279],

E (r ) = (2k—1 )/3

(25) S.D. OF NO. OF RUNS [Bradley, 1965, p. 279],

r sd = [ ( 1 6k—2 9 ) / 9 0

]

(26) MEAN SQ SUCCESSIVE DIFF [Brownlee, 1965, p. 222],

k-1

D = (k-l)~l l (xi+1

-

Xi ) i=l

(27) MEAN SQ SUCC DIFF/VAR [Brownlee, 1965, p. 222],

2 . 2 D /s

(28) NO. OF + SIGNS,

u = number of times sign of (x d

""xwtcj mean) is positive

(29) NO. OF - SIGNS,

v = number of times sign of (x^-x^j ) is negative

(30) NO. OF RUNS [Brownlee, 1965, p. 224],

RUNS = 1 + number of changes in sign of (x^'x^^ )

(31) EXPECTED NO. OF RUNS [Brownlee, 1965, p. 227],

E(RUNS) = 1 + (2«u«v)/k

5-6
(32) S.D. OF RUNS [Brownlee, 1965, p. 230],

RUNSgd = (

[ (u+v) 2 • (k-1 ) ] 1 • 2» u» v» ( 2» u» v - u - v))

1/2

(33) DIFF . /S.D. OF RUNS [Brownlee, 1965, p. 230],

[RUNS - E(RUNS)] / RUNSgd

(34) MINIMUM [Natrella, 1966, p. 19-1],

xj = smallest value with nonzero weight

(35) MAXIMUM [Natrella, 1966, p. 19-3],

= largest value with nonzero weight

(36) BETA ONE [Snedecor and Cochran, 1967, p. 86],

lc 61 = ( (k-D^s6 )" 1

( l (x i ~xwtdmean ) 3

)

2 ck

i = l

(37) BETA TWO [Snedecor and Cochran, 1967, p. 87],

lc 62 = ((k-1) *s ) £

^ x i _xwtdmean^ * k

i=l

(38) WTD SUM. OF VALUES,

k

l wi* x

i i=l

(39) WTD SUM OF SQUARES,

k

I wr x

i i=l

(40) WTD SUM OF DEVS SQUARED,

k

2

I wi

e ( x i"xwtd me an^

i=l

(41) STUDENT'S T [Brownlee, 1965, p. 296],

k

1/2

t = ( l wd ) • / s with (k-1) degrees of freedom

i = l

5-7
(42) WTD SUM ABSOLUTE VALUES,

k

l wi* |

|

i=l

(43) WTD AVE ABSOLUTE VALUES,

I wi* l xil

i=l

k

I wi

i=l

(44-53) FREQUENCY DISTRIBUTION [Freund and Williams, 1958, p. 17].

WT <-- The vector of dimension at least N that contains the weights. A

zero weight excludes the corresponding observation from the

analysis. If the weights are all equal to 1.0, the resulting

analysis is equivalent to an unweighted analysis.

Y --> The vector of dimension at least N that contains the observations.

The tests for trend and randomness will not be meaningful unless

the sample is ordered with respect to time or some other relevant

variable.

E . Computational Methods

E . 1

,

Formulas for the computed statistics are given in §D under argument STS.

The code for the statistical analysis subroutines is adapted from OMNITAB II

[Kogben, et al. 1971].

E .

2

. Computed Results and Printed Output

The output consists of a one-page display of the 53 statistics listed for

argument STS in §D. The argument, NPRT, controlling the printed output is

discussed in §D.

F . Example

The example program of figure F-la uses STAT to analyze the 39

measurements of the velocity of light shown on page 81 of Mandel [1964]. The

output from STAT is shown in figure F-lb.
cin

n

ci

MAIN PROGRAM! PROGRAM E X AM PL

DATAI

CC DEMONSTRATE STAT USING SINGLE PRECISION VERSION OF STARPAC

C RUN ON CYBER 180/0*0.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EOUATED TO FILE TAPE6 ON CYBERS)

C [SEE CHAPTER 1# SECTION 0.*]

C

C N.B. DECLARATION OF Y MUST BE CHANGED TO DOUBLE PRECISION IF

C DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL Y ( 200

)

DOUBLE PRECISION DSTAM200I

C COMMON /CSTAK/ OSTAK

CC SPECIFY NECESSARY DIMENSIONS

C LDSTAK • 200 READ NUMBER OF OBSERVATIONS

OBSERVED DATA

READ 100* N READ 101* CYIII* I-1»N)

C

C PRINT TITLE AND CALL STAT TO PERFORM STATISTICAL ANALYSIS

C WRITE (6# 102) CALL STAT (Y» N* LDSTAK)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (15) 101 FORMAT (13F5.1)

102 FORMAT C'lRESULTS OF STARPAC STATISTICAL ANALYSIS'*

* • SUBROUTINE STAT')

END

30 0.* 0.6 1.0 1.0 1.0 0.5 0.6 0.7 1.0 0.6 0.2 1.9 0.2

0.* 0.0 -0.* -0.3 0.0 -0.4 -0.3 0.1 -0.1 0.2 -0.5 0.3 -0.1

0.2 -0.2 O.S 0.5 0.6 0.8 0.7 0.7 0.2 0.5 0.7 0.8 1.1

Figure F-la

Example program using STAT

5-9
STATISTICAL

ANALYSIS

HN

O

H

H

M 0 o o © e © 1 I I I o o r\i «r *r t W O M

cm o n ^

tE o -o

m o

cn

O OD sr»

HO ^ O

W

O »<O

m ffNj

»r> od ># TNI « ® O © o >-> or • »

U, WO

x i OUZNU, QmZ 4 ixuj

k» Ud <«. uj

O s * a £ » © © o o © o © 1(1111 a/ lu lu unu iu H p4 O Q NN f eOOlJT«T

-£>

O© & O

r\ io o o o o mnoocs oooomw HNOOtMN # # r # <r © z

Uiz o © © •*

»->

X ^ QC©©

O TX I & Q>

X *->QC Z aiuiMiMr 3 j r r m <v

k* *> o <v o o o —

m O

r- r» O o0 l UJ OJ

-£) O'- o ® © © ^ C*5

wo «/»

§e ar C O

fet u=.

»tI rr! < <« z z o o © © o o

U* U/ o c

(/»

wI 8 o o

rtO WOfS^ © o © o © o t «. J + *

ctt w«J UJ Ud UJ o © o o © o OO H rsi o O © © m «o © o © O ^ O3 © © © © © k° © 04 © © (T\ f?T © -f*0 © & & m *Q •& + k»

© *+> O *% o © © <M O CD © kj

rfl

H

W P«4O »f\ fsj (ft i 8 f 0

irt LU OJ 3 ©

e/i S

(/) mo uj aiA

•s *<3 »

<<T CT UJ

WO

© 2* »

UU Ub) k- k 3 3

«J <e) o a

wo v°» U, U» Ik *» ® ffi GOO <* <* tu e vs. Z Z y 5 X Z Z *«• Z «A4 OOOk-OOOZG> Z Z wo m wo %±s wo <m <W M <A* < © Z w k*r»© 0 ©G©© « J2 H<

E- i CD s a

•H * &4 o

CD rH

a.

COXW

(»iw nrt

©

©

©

© I 8 ( «

cv rt jv

r- a* r- 0>#H

B

©

© <© S 43 ®

k or-©

© «rt

«r> o ©

«#• k=> ®> o p I O

O

®

© ( «v k ra

C i o *st Z wo O © Z I z a D

(/»

w

a, o •-« a ©

wo

© uj ® ©

wo

C * ( z z o :

<£ «£ MAO -5 •-« V> CZ> Z

wo wo z Z © • © oc a I Of o • UJ u. wo

U. U. U. L- CD '*» O O O U •

QC

O

IXt U, I U. k» O * a © • • » a

a

a

O

O

O

x « «-> Z Z Z ta* wo o COCO «J ® —J QC wo wo wo o. «a o - Ox • i Z uj wo :

5-10 II9IIIVIIV1II1

III1
G. Acknowledgments

The code and output for the statistical analysis subroutines is adapted

from OMNITAB II [Hogben et al. 1971].

5-11

CHAPTER 6

ONE-WAY ANALYSIS OF VARIANCE

A. Introduction

STARPAC contains two subroutines for one-way analysis of variance. The

output from these subroutines includes the usual analysis of variance table

plus the robust Kruskal-Wallis rank test. Comprehensive summary statistics

are also given, including means, standard deviations, standard deviations of

the mean and confidence intervals for the mean of each group. Within group

standard deviations, standard deviations of the mean and 95-percent confidence

intervals for the mean are given assuming fixed effects and random effects

models and also assuming ungrouped data. The output also includes pair-wise

multiple comparisons using the Newman-Keuls and Scheffe techniques; the

Cochran's C, the Bartlett-Box F and variance ratio tests for homogeneity of

variances; and the random effects model components of variance estimate. The

analysis performed by these subroutines is the same as that performed by the

OMNITAB II command ONEWAY [Hogben et al. 1971]. A reference for one-way

analysis of variance is Brownlee [1965], chapter 10.

Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F

.

B . Subroutine Descriptions

Subroutine A0V1 computes and prints the one-way analysis of variance

described in §A.

Subroutine A0V1S provides the same analysis as A0V1 but allows the user

to suppress the printed output and to store the number of observations in each

group, the group means and the group standard deviations.

C . Subroutine Declaration and CALL Statements

NOTE: Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

6-1
A0V1: Compute and print a one-way analysis of variance of the input data

REAL Y(n) , TAG(rc)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL A0V1 (Y, TAG, N, LDSTAK)

AOV1S: Compute and optionally print a one-way analysis of variance of the

input data; return tag value of each group, number of observations in

each groups group averages, and group standard deviations

REAL Y(n) , TAG(n), GSTAT (igs tat, 4)

DOUBLE PRECISION DSTAK( Idstak)

COMMON /CSTAK/ DSTAK

CALL AOV1S (Y, TAG, N, LDSTAK, NPRT, GSTAT, IGSTAT, NG)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE: --> indicates that the argument is input to the subroutine and that

the input value is preserved;

<— indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine;

indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

* * * indicates that the variable is passed via COMMON.

DSTAK **• The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

GSTAT <— The matrix of dimension at least NG by four whose columns contain,

in order, the tag value of the group, number of observations in

the group, group average and group standard deviation. The groups

are in order of ascending tag values.

I ERR **• An error flag returned in COMMON /ERRCHK/ . [See chapter 1, § D . 5 .

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

6-2
IGSTAT —> The exact value of the first dimension of the matrix GSTAT as specified in the calling program.

LDSTAK --> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P =0.5,

otherwise P = 1.0 [see chapter 1, § B ]

.

For AOV 1 : LDSTAK > 22 + N + (8«NG+N)*P

For AOV 1 S : LDSTAK ^ 22 + N + (4*NG+N).P

N —> The total number of observations (all of the groups combined).

NG <-- The number of distinct groups, that is, the number of different

positive tag values.

NPRT —> The parameter controlling printed output.

If NPRT = 0 the printed output is suppressed.

If NPRT t 0 the printed output is provided.

TAG —> The vector of dimension at least N that contains the tag value for

each observation. The tag values may be any REAL number. Groups

are formed from observations having the same positive tag value.

Observations having a zero or negative tag value will not be

included in the analysis.

Y —> The vector of dimension at least N that contains the observed

data. The order of the observations in Y is arbitrary since

groups are specified by the values in the corresponding elements

of vector TAG.

E . Computational Methods

E . 1 Algorithms

The code and output for the one-way analysis of variance subroutines are adapted from OMNITAB II [Hogben et al. 1971]. The computations performed are discussed below.

E . 2 Computed Results and Printed Output

The argument controlling the printed output, NPRT, is discussed in §D.

Each of the five sections of automatic printing is described below under

the headings which appear on the printed page as shown in example F-lb. The

discussion is taken from the OMNITAB II User's Reference Manual [Hogben et

al. 1971], pages 122 to 124.

6-3
ANALYSIS OF VARIANCE . The traditional analysis of variance for a one-way

classification is printed. This shows the sources of variation, the degrees

of freedom, the sums of squares, the mean squares, the F-ratio for testing for

differences between group means and the significance level of the F-ratio.

The usual assumptions of normality, independence and constant variance of

measurement errors are made. A discussion of the statistical treatment of a one-way classification can be found in §10.2 of Brownlee [1965],

If the significance level of the F ratio (F PROB . ) for

F = (Between Groups Mean Square) / (Within Groups Mean Square)

is less than 0.10 and the number of groups exceeds two, the between groups

(means) sum of squares is separated into two components: the first associated

with the slope (one degree of freedom) and the second representing deviations

about the straight line regression of group averages on group number. This

information, which does not appear in a traditional analysis of variance, can

be used to examine the effect of time. A discussion of some of the

statistical aspects of this procedure are found in §11.12 of Brownlee [1965].

Following the above mentioned analysis of variance, the results for the

Kruskal-Wallis non-parame t ri c H-~test for testing for differences between group

means (averages) are printed. The value of H is printed along with its

significance level (F PROB.). The H-test uses the ranks of the measurements

and avoids any assumption about the distribution of measurement errors. Details of this test may be found in §7.7 of Brownlee [1965].

E STIMATES . The following items are printed for each group:

(1) group number,

(2) number of observations in the group,

(3) mean,

(4) within standard deviation,

(5) standard deviation of the mean,

(6) minimum (i.e., smallest) observation,

(7) maximum (i.e., largest) observation,

(8) the sum of the ranks of the observations, and

(9) a 95-percent confidence interval for the mean. The results are printed with the group numbers (tags) in consecutive,

increasing order regardless of the order in which the numbers were entered.

In printing the means and standard deviations of the groups, the

characters + and - are put immediately after the high (largest) and low

(smallest) values. If two or more values are tied for the largest value, the

character + is put immediately after all of the tied values. Ties for the

smallest values are handled in an analogous manner using the character -. If

the number of observations in a group equals one, ESTIMATE NOT AVAILABLE is

printed under WITHINS S.D. and S.D. OF MEAN. Also, ********** TO **********

appears under 95PCT CONF INT FOR MEAN.

The total number of observations, mean, minimum observation and maximum

observation are also printed for the whole dataset combined. In addition, the

within standard deviation, standard deviation of the mean and 95-percent

6-4
confidence interval for the mean are printed for three different models: a fixed effects model (Model I), a random effects model (MODEL II) and a model

which assumes that all observations are from a single group. The confidence

limits are formed by taking the grand mean plus (and minus) the product of the

percentage point of Student's t distribution and the standard deviation of the mean. Let k be the number of groups and n be the total number of observations

with postitive tag. Then, the standard deviation of the mean is the square

root of the variance of the mean formed as follows:

Model Variance Variance of

Mean

Degrees of

Freedom

I Vj = Within groups mean square V x /n n-k

II v n * I (Yd) - T)

2 /0-l)

i=l

v n/k t—i i

Ungrouped Vu

= Total mean square Vn n-1

PAIRWISE MULTIPLE COMPARISON OF MEANS . This section only appears if the

significance level (value of F PROB.) of the between groups F-ratio is less

than 0.10. The Newman-Keuls-Hartley procedure is not performed if the number

of measurements with positive tag is less than four plus the number of

groups.

The purpose of this comparison is to divide the groups in such a way that

the group means within a division are not significantly different at the 0.05

significance level, whereas the group means in different divisions are significantly different at the 0.05 level. Two different procedures are used:

the Newman-Keuls-Hartley method and the Scheffe" method. The two methods are similar but not identical and frequently give slightly different results. The

Newman-Keuls-Hartley method is described in §10.6 of Snedecor [1956] and §10.8

of Snedecor and Cochran [1967]. The Scheffe^ method is discussed in §10.3 of

Brownlee [1965] . Groups are separated by a string of five asterisks. If two

divisions have no group means in common, the two divisions are separated by

two strings of five asterisks.

Both the Newman-Keuls-Hartley method and the Scheffe^ method require

percentage points of the studentized range: an approximation developed by

Mandel is used to compute them. Since the Newman-Keuls-Hartley method is

designed for use when the number of observations in each group is the same,

the number of observations in each of the two groups is approximated by m, where

1/m = ( 1

/ 2 )*(l/mi + 1/mj

)

and m^ and m^ are the actual number of measurements in each of the two

g roups.

TEST FOR HOMOGENEITY OF VARIANCES . The usual analysis of variance for a one-way classification assumes that the variances of all groups are the same.

6-5
This section of output provides information for assessing the validity of this

assumption. Small values of the significance level P indicate lack of

homogeneity of variance. The Cochran's C statistic printed is discussed on page 180 of Dixon and Massey [1957] and in more detail in chapter 15 of

Eisenhart et al. [1947]. The Bartlett-Box F-test is a modification of

Bartlett's test which uses the F-distribution rather than the chi-squared

distribution and is less sensitive to non-normality. It is discussed on pages

179 and 180 of Dixon and Massey [1957], A table of critical values of

(maximum variance) / (minimum variance) for equal sample sizes is given on pages

100 and 101 of Owen [1962].

If either P value is less than or equal to 0.10, the approximate between

mean F-test in the presence of heterogeneous variance and its significance

level P are also printed. This approximate F-test for testing for differences

between means is described on pages 287-289 of Snedecor [1956] . This

information does not appear in figure F-lb because both P values (significance

levels) exceed 0.10.

MODEL II - COMPONENTS OF VARIANCE . This is the usual analysis of

variance estimate for the between component in a random effects model (Model

II). For a discussion of this analysis, see §10.6 and §10.7 of Brownlee

[1965].

The example program of figure F-la uses A0V1 to analyze 16 determinations

of the gravitational constant, grouped according to the material used to make

the measurements. Figure F-lb shows the output from this example. A

discussion of this example can be found on pages 314-316 of Brownlee [1965].
MAIN PROGRAMI PROGRAM EXANPL

DATA 8

CC DEMONSTRATE AO VI USING SINGLE PRECISION VERSION OP STARPAC

C RUN ON CYBER 180/BA0.

CC OUTPUT UNIT IS 6 (AUTOMATICALLY EOUATED TO FILE T A P E 6 ON CYRERS)

C [SEE CHAPTER 1# SECTION D.AI

C

C N.B. DECLARATION OF Y AND TAG MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL Y ( 2 0 ) > T AG ( 20

)

DOUBLE PRECISION DSTAM200)

C COMMON /CSTAK/ DSTAK

C

C SPECIFY NECESSARY DIMENSIONS

C LDSTAK 200

C

C RE AO NUMBER OF OBSERVATIONS

C OBSERVED DATA

C TAG VALUES

C READ 100, N READ 101, ( Y ( I ) » I«1,N) READ 101, ( TAG ( I ) , I 1 » N ) CC PRINT TITLE AND CALL A0V1 FOR ANALYSIS OF VARIANCE

C WRITE (6, 102) CALL A0V1 (Y, TAG, N, LDSTAK)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (15)

101 FORMAT (20F5.U

102 FORMAT ( '1RESULTS OF STARPAC ONE-WAY ANALYSIS OF VARIANCE',

* • SUBROUTINE AOVl'J

ENO

16 83.

0

81.0

1.0

1.0

76.0

78.0

1.0

1.0

79.0

72.0

1.0

1.0

61. 0 61.0

2.0

2.0

67.0

67.0

2.0

2.0

6 A . 0 78.0

2.0 3.0

71.0

75.0

3.0 3.0

72. C 7 A .

0

3.0 3.0

Figure F-la

Example program using AOV

1

6-7
•-U o

CD UJo I »-Oz

CDO

or

© Ui

UJ

O

X

tX

UJ

X

or - O </* 1 tu uj z ~j : CD -J I •-3 < I c/v r . v> wo z X ( a; uj : Uj Z

ec cd

m. z i 3 3 '

a. cl i 3 3 i o a

oc ol : CP o « • o

c* o O iv o o • • 3

ao <x O O o «*» <V o

uj

® ^ UJ

h

O rt Mr Ort

If'fO

W

O • •

(SI •& &\ GO CO O

«V 9 <V

CD <V

«<

a o

UJ

O CD o o

MUJtU MM OWMGO O’ *>

uj

® ^ UJU NOr mr m o w ^ o#o W W ^ © e 2) ^ n « rv o o

<c -*>© 3 © Z «/* © 3 «»

QCO * aw

u o 3a a.

ft) 3 < o

UJ

© CD Z CL VI u Q > Z Z O X ^ O

O 'T « r o N M (5 a a a ^ o o

>£» «f*> ^ OKI?1 h ivjr •TOO K Cl K

U «*» O itz o © o

UJ

W UJ o © © © © © © © © ©

«T) K=

®

© c® *•> © © ©

UJ UJ UJ © © © © © © © © ©

fv , i © ©

©

©

©

UJ UJ UJ m +

t*> & f*=

C3J ^ ^ ^ «v r com

UJ UJ Ud

ffi

O (<i

C©

C

©©

*> <« © © *^ © © ©

UJ UJ UJ Z K> © ©

•*

O OO uj *£> Q O

3C «-*

©O c -e -f ^© © ©© © © O © © © © © © © © © ©

HNW

C

M IT

tr> p-4 pn

r-J -O

O

M

O

*=

© o K ? K c a a ^ ^ O (V% «-J

trs p«j

®

O <*» K- m & o Z uj»

«*£ UJ

a. >* * 3 -J Z O u. <»« Of Z UJ © •o z <* '

9*©©

©

©

©

4>

u uj uj r mO e Mr <kj «=«

«V6 ffu

UJ UJ UJ O C p< ^ <FU

t°c ^ ©

cya <»

CSJ «\l «P PJ h « U UJ O

uju

u u»

©

U UJ UJ Z 3 © o o

uj© Of

x Z ©

O I © u

u. Q£ 3

H=

C -J z 3 a

uj© : i/s llj X ©

or 3 3

G.

OL <S» o a © z I

(A Q> <

<« 3 X

uj

Q

or oc i/t © © a> Z 3 NWO

O)P3

b£ >C< ©

fru Z 3 X uj a fr= ©

aE

03Xw

uj Z “J

or •-> o Z >» © Z *M> u ^ Q X Z © uj ^ z Z O O 3 ^ z <v z

oc

— z ^ oc « X < T. : Ot oc : © ©

.J

© • I rH ^4

U

X •— Z O oc UJ © CD 4 © I » O u"> - 3u u t o « I o « z © ^ © o! © • oo * < O 4 U) D X oc -J Z X

6-8

J

MODEL

IICOMPONENTS

OF

VAN I

ANCE.

ESTIMATE

OF

BETWEEN

COMPONENT

9.11A706E«01
G. Acknowledgments

The code and output for the one-way analysis of variance subroutines is

adapted from OMNITAB II [Hogben et al. 1971]. The discussion of the results

( §E . 2 ) is taken from the OMNITAB II User's Reference Manual [Hogben et al.

1971] .

6-9

CHAPTER 7

CORRELATION ANALYSIS

A. Introduction

STARPAC contains two subroutines for correlation analysis of a multivariate random sample. The analysis provided by these subroutines consists of

seven tables, which, when used together, aid the user in using correlation

techniques effectively for prediction and model building. The analysis is the same as that provided by the OMNITAB II command CORRELATION [Hogben et al.

1971], For further information on correlation techniques users should consult

Kendall and Stuart [1973], Brownlee [1965] and Anderson [1958].

Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F

.

B

.

Subroutine Descriptions

Subroutine CORR computes and prints 1) the simple correlation matrix and

2) the significance levels of the simple correlation coefficients; 3) the

partial correlation coefficients and 4) their significance levels; 5) the

Spearman rank correlation coefficients; 6) a test for a quadratic relationship

among the variables; and 7) 95-percent and 99-percent confidence intervals for

the simple correlation coefficients.

Subroutine CORRS provides the same analysis as CORR but returns the

variance-covariance matrix used to compute the correlation coefficients. The

user can also optionally suppress the printed output.

C

.

Subroutine Declaration and CALL Statements

NOTE; Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

CORR: Compute and print a correlation analysis of a multivariate random

sample

<real> YM (n,m)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL CORR (YM, N, M, IYM , LDSTAK

)

7-1
CORRS: Compute and optionally print a correlation analysis of a multivariate

random sample; return variance-oovarianee matrix

<real> YM(n, m) > VC

DOUBLE PRECISION DSTAK (l dstak ) COMMON /CSTAK/ DSTAK

tCALL CORRS (YM, N, M, IYM, LDSTAK, NPRT, VCV , IVCV)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE: —> indicates that the argument is input to the subroutine and that

the input value is preserved; <-- indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; —- indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

* *

• indicates that the variable is passed via COMMON.

DSTAK The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

IERR ' *

* An error flag returned in COMMON /ERRCHK/. [See chapter 1, §D.5.]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

IVCV -—> The exact value of the first dimension of the matrix VCV as specified in the calling program.

IYM —> The exact value of the first dimension of the matrix YM as specified in the calling program.

LDSTAK —> The length of the double precision workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P = 0.5,

otherwise P = 1.0. [See chapter 1, §B.] — continued —

7-2
For CORR:

LDSTAK > (47+max(N,M)) /2 + (max(N,M)+N« (M+3)+M+7«

M

2

) «P

For CORRS:

LDSTAK > (47+IO«max(N,M)) /2 + 10 • (max(N,M)+N» (M+3)+M+6* M2

) •

P

where 10 = 0 if NPRT = 0 and 10 = 1 if NPRT t 0

M —> The number of variables measured for each observation, that is,

the number of columns of data in YM.

N --> The number of observations, that is, the number of rows of data in

YM.

NPRT --> The argument controlling printed output.

If NPRT = 0 the printed output is suppressed.

If NPRT t 0 the printed output is provided.

VCV <— The matrix of dimension at least M by M that contains the

variance-covariance matrix,

N

VCV ( j , k) = (N-l)" 1 l (YM(i,j) - Y0(YM(i,k) - Y

fc ) i=l

N _ N

where Y- = N” 1

. J YM(i,j) and Yk

= N" 1. J YM(i,k).

i=l i=l

YM --> The matrix of dimension at least N by M that contains the observed

multivariate data. The element in the i

1-*1 row and column is

the i

c ^ observation on the variable.

E . Computational Methods

E . 1 Algorithms

Formulas for the computed tables are given in §E.2. The code and output

for the correlation analysis subroutines are adapted from OMNITAB II [Hogben

et al. 1971] .

E . 2 Computed Results and Printed Output

The argument controlling the printed output, NPRT, is discussed in §D.

7-3
STARPAC correlation analysis subroutines compute and print a seven-part

correlation analysis. The output for each part is discussed individually

below; the text for this discussion is taken from the OMNITAB II User’s

Reference Manual [Hogben et al. 1971],

The Simple Correlation Coefficient Matrix . The (j,k) t ^1 entry of this

matrix is the simple (product moment) correlation coefficient, r jk> between

the data in columns j and k defined by

r

ik = VCV(.j,k)

t (VCV(j,j).VCV(k,k))l / 2

Note that when more than two variables are under study, the simple correlation

coefficient can be seriously distorted by the effect of other variables. The

partial correlation coefficient (see below) can be used to identify such

distortion.

The Significance Levels of the Simple Correlation Coefficients . The

(jjk)"^ entry of this table is the significance level, S r

( j

, k) of the

corresponding partial correlation coefficient, rj k ,

S r (j,k) = probability of exceeding Fq(1,N-2)

where Fq is an F-statistic with 1 and N-2 degrees of freedom,

(N-2)r ik

2 F0

( 1 ,N-2) = —( l“ r

j k

2

)

If the “true" correlation coefficient is equal to zero, then S r (j,k) is the

probability that in a random sample (of the same size) the absolute value of a sample correlation coefficient will exceed the absolute value of the observed

correlation coefficient, rj^..

The Partial Correlation Coefficients . The partial correlation

coefficient, Pj k > between the data in columns j and k, j*k, with the remaining

variables fixed, i.e., held constant, is given by

Pjk ~ “c jk^ c

j j

* c kk^

where Cj k denotes the (j,k) t '1 element of the inverse of the simple correlation

matrix. Because the partial correlation coefficient measures the correlation

between two variables after eliminating the effect of the remaining variables,

it may avoid the distortion suffered by the simple correlation coefficient

when more than two variables are under study. The user should therefore

compare the simple correlation coefficients with the partial correlation

7-4
coefficients. Any "large" discrepancy indicates that one or more of the

remaining variables is having an important effect on the relationship. [See

Kendall and Stuart, 1961, §27.5, page 318.]

The Significance Levels of the Partial Correlation Coefficients . The

entry of this table is the significance level, Sp( j

, k) of the

corresponding partial correlation coefficient, pj k ,

Sp(j,k) = probability of exceeding Fq(1,N-M)

where Fq is an F-statistic with 1 and N-M degrees of freedom,

(N-M)p

j

k

2 Fq(1,N-M) = •(1-Pjk2

)

If the "true" partial correlation coefficient is equal to zero, then Sp(j,k)

is the probability that in a random sample (of the same size) the absolute

value of a partial correlation coefficient will exceed the absolute value of

the observed partial correlation coefficient, Pj k

*

Spearman Rank Correlation Coefficient . The rank correlation coefficient

does not require the assumption that the data have a bivariate normal

distribution. The Spearman rank correlation coefficient, Sj k , for the data in

columns j and k is computed from

where

/(A - 2Tj ) (A - 2Tk

)

N

Dj k

2 = l [ r ank ( YM ( i , j ) ) - rank( YM(i ,k)) ] 2

, i = l

A = (N— l)(N)(N+l)/6,

Tj > (l/12)g(t

J -l)(tj)(t

j

+l)),

j

Tk

= (l/12)K(t k-D(tk)(t k+l»,

k

tj - number of ties in a set of tied values in column j of YM , and

t k

= number of ties in a set of tied values in column k of YM.

7-5
The quantities Tj and adjust for ties in the ranks, If there are no ties, Tj and equal zero and

Sjk - 1 ~ (Djk / A).

A comparison should be made between the rank correlation coefficients and the

corresponding simple and partial correlation coefficients. Again, a "large"

discrepancy between two comparable coefficients is an indicator of some abnormality in the data. See Kendall [1948] for further details.

Significance Level of Quadratic Fit over Linear Fit . Underlying the use

of a correlation coefficient is the assumption that the two variables are linearly related. The results in this part are useful in assessing the

validity of this assumption of linearity. The variables are all assumed to be

normally distributed. The numbers printed are the significance levels for a F-test of the hypothesis that the quadratic term in a quadratic model is zero. The F-statistic used is

Fq(1,N-3) = RSS(linear model) - RSS(quadratic model)

RSS(quadratic model) / (N-3)

with 1 and (N-3) degrees of freedom, where RSS is the residual sum of squares

function. The values of 1 and (N-3) are printed in the heading. The

significance level, Sq, is then computed as

Sq = Pr(F > Fq).

Small values of the significance level (less than 0.05, for example) indicate

lack of linearity. The test results differ depending upon which variable of a pair is considered the dependent variable and which one is considered the

independent (or predictor) variable. Hence, the entire table is printed,

rather than just the lower triangle. The diagonal entries are always equal to one and have no particular relevance. Tests of hypotheses in linear

regression are discussed in §13.8 of Brownlee [1965].

Confidence Intervals For Simple Correlation Coefficients . Both 95-percent

and 99-percent confidence intervals for the simple correlation coefficients

are printed in this two-way table. There are two entries in each cell of the

table. The values 0.95 and 0.99 are printed along the upper left to lower

right diagonal. The 95-percent confidence limits are printed below the

diagonal and the 99-percent confidence limits are printed above the diagonal.

The number in the lower left of each cell is the lower confidence limit and

the number in the upper right is the upper confidence limit.

The confidence intervals are based on a normal approximation. [See

Morrison, 1967, chapter 3, page 101.] They are computed as follows:

Lower confidence limit: tanh[z-u//N-3]

Upper confidence limit: tanh [z+u//N-3]

7-6
where

and

tanh 1 (r

0.50 loge

[ ( l+rj k )/(l-rj k )

]

u 1.96

I 2.58

for 95-percent

for 99-percent

confidence

confidence

interval

interval.

F . Example

The

data are study to

relative

4) . The

sample program shown in figure F-la illustrates the use of CORR. The

taken from Draper and Smith [1968], page 216. The data are part of a determine the effect of relative urbanization, educational level, and

income (columns 1, 2, and 3, respectively) on product usage (column

output from CORR is shown in figures F-lb and F-lc.

7-7
MAIN PROGRANI PR06RAH EXAMPl

C

C DEMONSTRATE CORR USING SINGLE PRECISION VERSION OP STARPAC

C RUN ON CYBER 180/840.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO PILE TAPE6 ON CYBERS)

C ESEE CHAPTER 1# SECTION D.43

C

C N.Be DECLARATION OP YM MUST BE CHANGED TO DOUBLE PRECISION

C IP DOUBLE PRECISION VERSION OF STARPAC IS USED,

C REAL YN ( 20» 6 ) DOUBLE PRECISION DSTAM200S

C COMMON /CSTAK / DSTAK

C

C SPECIFY NECESSARY DIMENSIONS

C LDSTAK • 206

I YM = 20

C

C READ NUMBER OP OBSERVATIONS AND NUMBER OF VARIABLES

C OBSERVED NULTIVARIATi DATA

C READ 160s Ns M READ 101# ( (YH(Z#J)» J«1#HI» I«1#NJ

C

C PRINT TITLE AND CALL CORR TO PERFORM CORRELATION ANALYSIS

C NR I Ti ( 6# 162

)

CALL CORR < YM# N# H# 1 YM# LOST AK

I

STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (215)

101 FORMAT (AFfe.li 102 FORMAT (URESULTS OF STARPAC*#

* » CORRELATION ANALYSIS SUBROUTINE CORR*)

END

D AT A l 9 A 42.2 11 ©2 31 © 9 167.1

48©6 10© 6 13.2 174.4

42 ©6 10 ©6 26.7 160.8

39.0 10©4 26.1 162.0

34o? 9.3 30©1 14C.8

44 = 5 10©8 8.5 174.6

39.1 10c7 24.3 163.7

40© 1 1 0 © 0 18©fe 174.5

45 ©9 12.0 20.4 IBS .7

Figure F-la

Example program using CORR

7-8
«s1aa

<r\ ©

<v

Q£U4 Oo©e

«N«

o»

OS

a

i]aaaa

*2 2!

*-5 C3

©

oO

©

«v r% © © K ^ n e

»«j

© ©>

•h

© *u ^ NO ® o> «* «v© ** K» © K* © K H K • © ® l ©e©

UJ

©

©N

©

©

a

© f"3 © K

«r» •% « h

©N

©N

O©

© «o © ^ •I © o © © © ©O K N OHO OK « O 9 N • O K

©

«%©©

©

©» © © K © © *4© ©

O

© o © o © o © o © O H

OhK

©

© w\ ON H OO O OO N ONO • H © I Cb

0)

i-l 3

60

•H

u*

a

iia

*/»

u z ** O U. © o x •-• o

*-> » « tuz K OO © H* Z O Kat © X © -* O O Ui H I a K < OC © KO J MU

® <nj © ©

H

O

K

© *4 © rt © K*

r» *h H O © ©

HN

©

©© I I I © © © © ® «*» ivm r Z HNW < g ^

OO HfM © tn © © u. O © «> O o oo wo- ok © «n *o Oh -O g> -J O W *\ O Ui • O © H > O Z HNW<

OKW

©

©

©

IO WOO

OHK © © © i O © © O «D •H O © © o o © OHO • o o

HNW

O

z>—

a

7-9

Example

of

CORR

output
O

O

us -j w O

13 U> MSo vi

*3

fto x xo

r=3

y

XX

oxM ft *' US

ft *> m u k*i, 9=3 » X ft ©«<5 e ft lit? v»©

© vj ft ®

«v

m

*4 f*> ft

vs v» m & o o

ft o

ft

©

©

©oo

ft

© ? © IAS VI © © © © ©

Vi

ft ft

© ( © • © < i ©I ©©K

A

© ft

© e

i-a < © v» © ft v» © © © © G © ©

O

© o ft © ft © © © *“C © © © ©• VI > V*} c ©

*=>

X VU O t>

© VI

ft©

©©

©

©©

©

©

©

©

©©

®

© o © ©© © ©® © © © © •

ft v* O ©

m us

KO ft ft va© ft ft

w

u NO^©

© US ft

© VI ft

X>

X • ©

©© <_} ft

©

©©© ft ft ft ft o ^ <V © VI VI US ft &£ © © Vi ffe ft ft © ft V © « ft m © ft9 ft © © © ft ft ft ©

ft ft© ft

© at© ft©

©

© ft ft ft

© t*3 U o © © © © ft *4 • © ft ft ft ©

14: A=8 <#>

® vs ©i

w

u

© ft© o ft

©

© ft

X

G 0=3

©

© t> ft

© e e ft© ft

U

© IAS

©

M ft ft ft

HM «J

X e ©

© c

ft VI ft o 1 1 X ©

A? US » ft © X VI « ©

<*© ft 1 S ft © U$ © VI c x © ft 8 ft

© e*» O ft o «> u © © © us ft ft

«fc

O

€OV xJ

©

© ft ft©O ftK o « © -$> <#> «u VI us © © ft © ft m ft Vi © G=0 © V» VS VS =4 ft ft O © © ft © © ft Vi

<»4 ft

©

©

©

©©

O

© ft

© ft ft ft V*

IAS ^4

© V* ft VI >» VI

® o ft) ft ft ft ft ft

X « « «=ss ft FU ft ft

©©©© ft ft

© ft

IAS ft e • ® US fW

© • • ft * © • ©

«*§ ft

X ft VI© ft

X « © • • • US Uf •“> aJ 1 CJ -4 X U. US ft <t X X v© ft VI © <-> X X ft ft ft X X US K

t-3V o us

y©

U US «r

© *5 © e=o ft

©

X « y U, US

y I

0)

Ufa

«rH

7-10

Example

of

CORR

output

(continued)
G . Acknowledgments

The code and output for the correlation subroutines

OMNITAB II [Hogben et al. 1971], The discussion of the

taken from the OMNITAB II Users' Reference Manual [Hogben et

is adapted from

results (§E.2) is

al. 1971].

7-1 1

CHAPTER 8

LINEAR LEAST SQUARES

A. Introduction

STARPAC contains eight subroutines for linear least squares analysis.

For four of these, the user specifies the model by supplying the design matrix

(the matrix whose columns are the independent variables plus a column of ones

if a constant term is being estimated). The other four perform the same analysis for the special case of a polynomial model, where the need for the

user to explicitly create the design matrix is eliminated.

Each of the subroutines described in this chapter assumes that the

observations of the dependent variable, y^, which are measured with error, are modeled by

NPAR

Yi = [ I 6(j)*x i (j)] + for i = 1, ..., N,

j = l

where

N is the number of observations;

NPAR is the number of parameters;

x-^(j) is the j

1-^1 element of the i

c ^ row of the design matrix (for the

user-specified model, x^(j) = XM(i,j) for i = 1, ..., N and j = 1

,

NPAR, while for the polynomial model, x.j_(j) = X(i)d“l for i = 1,

. . «

,

N and j — 1, NPAR^

;

8 is the vector of the NPAR unknown parameters (coefficients); and

e

i is the random error in the i th observation.

A The least squares solution, B, is that which minimizes (with respect to B) the

residual sum of squares function

N

RSS(B) = l [e 1

2 -wt i ] i = l

N - NPAR

=

l [(Yi " [ l 3(j )*x i (j ) ])

2 •wt i ] i=l j=l

where carat ( A

) denotes the estimated quantity, and

wt t is the weight assigned to the i th observation (wt-L = 1.0 in the

"unweighted" case). Appendix B discusses several common applications

for weighted least squares.

8-1
Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F

.

B . Subroutine Descriptions

The linear least squares estimation subroutines permit both weighted and

unweighted analysis. The user has two levels of control over the computations

and printed output.

• In level one, a four-part printed report is automatically provided

and the residuals are returned to the user via the subroutine

argument list.

• Level two also returns the residuals. It. allows the user to specify

the amount of printed output, and, in addition, returns the

following estimated values via the argument list: - the estimated parameters;

- the residual standard deviation;

- the predicted values;

- the standard deviations of the predicted values;

- the standardized residuals; and

- the variance-covariance matrix of the estimated parameters.

The simplest of the linear least squares subroutines are LLS for the

user-specified model and LLSP for the polynomial model. They perform

unweighted analyses, provide a four-part printed report and return the

residuals via the argument list (level one control). The other six

subroutines provide greater flexibility by adding the weighting and/or level

two control features. These features are each indicated by a different suffix

letter on the subroutine name (e.g., LLSS_ and LLSPWS )

.

• Suffix W indicates user-supplied weights.

• Suffix S indicates level two control of the computations and output.

C. Subroutine Declaration and CALL Statements

NOTE: Argument definitions and sample programs are given in §D and §F

,

respectively. The conventions used to present the following declaration and

CALL statements are given in chapter 1, §B and §D.

8-2
LLS: Compute and print a four-part unweighted linear least squares

analysis with user-specified model (design matrix); return residuals

<real> Y (n ) , XM (n,npar), RES(n)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL LLS (Y, XM, N, IXM, NPAR, RES, LDSTAK)

LLSS: Compute and optionally print a four-part unweighted linear least

squares analysis with user- specified model (design matrix); return

residuals, parameter estimates, residual standard deviation, predicted

values, standard deviations of the predicted values, standardized

residuals, and variance-covariance matrix of parameters

<real> Y (n ) , XM (n y npar)

,

RES(n)

<real> PAR(npar), PV(rc), SDPV(n), SDRES(n), VCV(npar,npar)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL LLSS (Y, XM, N, IXM, NPAR, RES, LDSTAK,

1 NPRT, PAR, RSD, PV, SDPV, SDRES , VCV , IVCV)

LLSW: Compute and print a four-part weighted linear least squares analysis

with user-specified model (design matrix) ; return residuals

<real> Y(n), XM (n ,npar)

,

RES(n)

<real> WT(rc)

DOUBLE PRECISION DSTAK (Idstak.)

COMMON /CSTAK/ DSTAK

CALL LLSW (Y, WT, XM, N, IXM, NPAR, RES, LDSTAK)

8-3
LLSWS: Compute and optionally print a four-part weighted linear least

squares analysis with user-speaified model (design matrix) ; return

residuals, parameter estimates, residual standard deviation, predicted

values, standard deviations of the predicted values, standardized

residuals, and variance-covariance matrix of parameters

<real> Y (n ) , XM (n,npar), RES (n)

<real> WT(n), PAR (npar), PV(n), SDPV(n), SDRES(n), VCV (npar ,npar

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL LLSWS (Y, WT, XM, N, IXM, NPAR, RES, LDSTAK,

1 NPRT, PAR, RSD, PV, SDPV, SDRES , VCV, IVCV)

LLSP: Compute and print a four-part unweighted linear least squares

analysis with polynomial model (design matrix) ; return residuals

<real> Y(n), X(n), RES(n)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL LLSP (Y, X, N, NDEG, RES, LDSTAK)

LISPS: Compute and optionally print a four-part unweighted linear least

squares analysis with polynomial model (design matrix); return

residuals, parameter estimates, residual standard deviation, predicted

values, standard deviations of the predicted values, standardized

residuals, and variance-covariance matrix of parameters

<real> Y(n), X(n), RES(n)

<real> PAR (npar), PV(n), SDPV(n), SDRES (n), VCV (npar , npar ) DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL LLSPS (Y, X, N, NDEG, RES, LDSTAK,

1 NPRT, LPAR, PAR, NPAR, RSD, PV, SDPV, SDRES, VCV, IVCV)

8-4
LLSPW: Compute and print a four-part weighted linear least squares analysis

with polynomial model (design matrix) ; return residuals

<real> Y(n), X(n), RES(rc)

<real> WT(n)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL LLSPW (Y, WT, X, N, NDEG, RES, LDSTAK)

LLSPWS: Compute and optionally print a four-part weighted linear least

squares analysis with polynomial model (design matrix); return

residuals, parameter estimates, residual standard deviation, predicted

values, standard deviations of the predicted valuess standardized

residuals, and variance-covariance matrix of parameters

<real> Y (n ) , X(n), RES(n)

<real> WT(n), PAR (npar), PV(n), SDPV(n), SDRES(n), VCV (npar,npar)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL LLSPWS (Y, WT, X, N, NDEG, RES, LDSTAK,

1 NPRT, LPAR, PAR, NPAR, RSD, PV, SDPV, SDRES , VCV , IVCV)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE: —> indicates that the argument is input to the subroutine and that

the input value is preserved;

<-- indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine;

indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

• * * indicates that the variable is passed via COMMON.

DSTAK *** The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

8-5
IERR

IVCV

IXM

LDSTAK

LPAR

N

NDEG

NPAR

** An error flag returned in COMMON /ERRCHK/. [See chapter 1, § D . 5 .

]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected and that the

least squares solution was found.

IERR = 1 indicates that improper input was detected.

IERR = 2 indicates that the model is computationally singular,

which may mean the model has too many parameters. The

user should examine the model and data to determine and

remove the cause of the singularity.

IERR = 3 indicates that at least one of the standardized residuals

could not be computed because its standard deviation was

zero. The validity of the variance-covariance matrix is

questionable.

-> The exact value of the first dimension of the matrix VCV as specified in the calling program. —> The exact value of the first dimension of the matrix XM as specified in the calling program. —> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the value given below, where if the single

precision version of STARPAC is being used P = 0.5, otherwise

P = 1.0. [See chapter 1, §B.]

LDSTAK > 28 + [ 6® N+l + 5® NPAR+NPAR* N+2« NPAR2 ]«P

-> The actual length of the vector PAR as specified in the calling

program. —> The number of observations.

-> The degree of the polynomial model. The number of estimated

parameters is NPAR = NDEG + 1. — The number of parameters to be estimated. NPAR is input to the

subroutines with a user-specified model; for the subroutines with

a polynomial model, NPAR = NDEG + 1 is returned.

8-6
IS

II

*s

«

i

I!

i

i

i

«

ii

ii

m

»!

NPRT —> The argument controlling printed output. NPRT is a four-digit

integer, where the value of the I

1-'1 digit (counting from left to

right) controls the I

tla section of the output.

If the I

1-^1 digit = 0, the output from the I

1"*1 section is

suppressed

;

= 1, the brief form of the section is given;

> 2, the full form of the I*-^1 section is given.

The default value for NPRT is 1112. If the user-supplied value of

NPRT is less than zero or NPRT is not an argument in the

subroutine CALL statement the default value will be used.

A full discussion of the printed output is given in §E.2 and is

summarized as follows.

Section 1 provides information for each observation based on the

solution. Brief output includes information for the

first 40 observations, while full output provides the

information for all of the data.

Section 2 is a set of four residual plots. Brief output and full

output are the same for this section.

Section 3 is an analysis of variance. Brief output and full

output are the same for this section.

Section 4 is the final summary of the estimated parameters. Brief

output does not include printing the variance-covariance

matrix while full output does.

PAR <-- The vector of dimension at least NPAR that contains the estimated

parameter values.

PV <— The vector of dimension at least N that contains the predicted

values of the dependent variable,

RES

NPAR - PV(i) = l 8(j).

j = l <— The vector of dime

the solution,

NPAR

RES(i) = y ± - I

j = l

= Yi

“

Yi =

i( j ) = y± for i = 1 , . . .

,

sion at least N that cont

A8 ( j ) x

i (j)

Ak for i = 1 , . . . , N.

N.

ins the residuals at

8-7
RSD <— The residual standard deviation at the solution,

RSD = (RSS(8)/(Nnzw-NPAR)) 1/2

where Nnzw is the number of observations with nonzero weights.

SDPV <— The vector of dimension at least N that contains the standard

deviation of each predicted value at the solution,

SDPV(i) = the i

1"^1 diagonal element of [D» VCV* D^] 1 /2

for i = 1, N, where D is the design matrix, D(i,j) = x^(j)

with x^(j) defined in §A, and D

T

is the transpose of D.

SDRES <— The vector of dimension at least N that contains the standardized

*_ r_ residuals at the solution, i.e., the i cn residual divided by its

estimated standard deviation,

SDRES(i) = RES(i)/[(RSD2 /wt 1 ) “ SDPV(i) 2

] 1/2

for i = 1, ..., N.

VCV <-- The matrix of dimension at least NPAR by NPAR that contains the

variance-covariance matrix of the estimated parameters at the

solution,

VCV = RSD2 • (DT * W» D)”1

where W is the N by N diagonal matrix of weights,

W = diagjwt-^, i=l , ..., N} ,

and D is the design matrix, D(i,j) = x^(j) with x^(j) defined in

§A, and is the transpose of D«

WT

X

XM

Y

“"> The vector of dimension at least N that contains the weights.

Negative weights are not allowed and the number of nonzero weights

must equal or exceed the number of parameters being estimated. A

zero weight eliminates the corresponding observation from the

analysis, although the residual, the predicted value and the

standard deviation of the predicted value of a zero-weighted

observation are still computed. [See Appendix B.

]

—> The vector of dimension at least N that contains the independent

variable used to construct the design matrix for the polynomial

model. —> The matrix of dimension at least N by NPAR that contains the

design matrix, i.e., the matrix whose columns are the independent

variables plus a column of ones if a constant term is being

estimated. —> The vector of dimension

variable.

at least N that contains the dependent

8-8
E. Computational Methods

E . 1 . The Linear Least Squares Algorithm

The linear least squares estimation subroutines use a modified

Gram-Schmidt algorithm [Davis, 1962; Walsh, 1962] . The printed output for the

linear least squares subroutines has been modeled on the linear least squares

output used by OMNITAB II [Hogben et al. 1971],

E . 2 Computed Results and Printed Output

The argument controlling the printed output, NPRT, is discussed in §D.

The output from the linear least squares estimation subroutines consists

of four sections, several of which include tables summarizing the results. In

the following descriptions, the actual table headings are given by the

underlined, uppercase phrases. Results which correspond to input or returned

arguments are identified by the argument name in uppercase (not underlined).

Section 1 provides the following information for each observation, i, i = 1,

. .

. , N, based on the solution.

® ROW ‘ the row number of the observation.

• PREDICTOR VALUES : the values for up to the first three columns of the

independent variable (design matrix). For subroutines with a user-supplied model, this is up to the first three columns of the

matrix XM (excluding the first column if it is all ones, indicating a constant term); for the polynomial model subroutines, this is the

variable X.

• DEPENDENT VARIABLE : the values of the dependent variable, Y.

• PREDICTED VALUE : the predicted values, PV, from the fit.

® STD DEV OF PREP VALUE : the standard deviations of the predicted

values, SDPV.

® RESIDUAL s the error estimate, RES.

• STD RES : the standardized residual, SDRES.

o WEIGHT : the user-supplied weights, WT, printed only when weighted

analysis is performed.

8-9
Section 2 displays the following plots of the standardized residuals.

• The standardized residuals versus row numbers.

o The standardized residuals versus predicted values.

® The autocorrelation function of the (non-standardized) residuals.

• The normal probability plot of the standardized residuals.

Section 3 provides an analysis of variance. The results of this analysis

depend, upon the order of the columns of the design matrix unless the

columns are orthogonal . The analysis includes the following

information.

9 PAR INDEX : the index, j, of the parameter being examined, 8(j)*

• SUM OF SQUARES RED DUE TO PAR : SSj, the reduction in the sum of

squares due to fitting 8(j) after having fit parameters 8(0, 8(2),

...» 8(j~l). SSj depends on the order of the parameters unless the

design matrix has orthogonal columns. This is a decomposition of the

total sum of squares, TSS, into NPAR + 1 parts

NPAR

TSS = ( l SSj) + RSS(S).

j = l

The residual sum of squares and total sum of squares is also listed in

this column.

• CUM MS RED : the cumulative mean square reduction,

3 MSREDj = l SSk /j for j = 1, . .., NPAR.

k=l

• DF (MSRED) ; the degrees of freedom associated with the cumulative mean square reduction for each parameter, DF(MSREDj) = j for

j = 1, ..., NPAR. The degrees of freedom for the residuals,

Nnzw~^Pj^R » and t *le tota l degrees of freedom, Nnzw , where Nnzw is the

number of observations with nonzero weights, are also listed in this

column.

® CUM RES MS : the cumulative residual mean square,

NPAR

RMSj = ( RSS(8

)

+ l SSk )/(Nnzw-j) for j = 1, ..., NPAR.

k=j + l

o DF(RMS )

: the degrees of freedom associated with the cumulative

residual mean square for each parameter, DF(RMSj) = N nzw-j for

j = 1 ,

. .

.

NPAR.

8-10
9 PAR=0 , F and PROB(F): the F-ratio and its significance level under

the null hypotheses that 8(j) is zero after allowance has been made

for parameters 8(1) > 8(2), 8 (

j

— 1 )

This F-ratio is

Fj = SSj/RMS^jpAR for j = 1, •••, NPAR,

with 1 and Nnzw

-NPAR degrees of freedom. The significance level

listed is the probability of exceeding the calculated F-ratio under

the null hypothesis that the corresponding parameter, 8(j), is zero.

• PARS=0, F and PROB(F) : the F-ratio and its significance level under

the null hypothesis that parameters 8(j), 8(j+l), • ••, 8(NPAR), are zero after allowance has been made for parameters 8(1), 8(2), . .., 8(j-l). This F-ratio is

NPAR

F

i = ( l SSk/(NPAR-j+l))/RMSNPAR for j = 1, ..., NPAR,

k=j

with NPAR-j+1 and Nnzw~NPAR degrees of freedom. The significance

level listed is the probability of exceeding the calculated F-ratio

under the null hypothesis that all of the parameters 8(j), 8 (j+1),

..., 8 (NPAR) are zero.

The numerator of this ratio is the extra sum of squares accounted for

by inclusion of the terms 8(j)*x(j) + 8( j+1) *x( j+1) + ... + 8(NPAR)»

x(NPAR) in the model, divided by its degrees of freedom; the

denominator is the residual mean square of the full model. This ratio

is a means of comparing the extra sum of squares to its expected value

as estimated by the residual mean square. When the terms of the model

have a logical order of entry, this series of F-tests can be used to

judge how many terms should be included in the model. [See Draper and

Smith, 1981, pages 97 and 98.]

Section 4 summarizes the following information about the final parameter

estimates and their variances.

o The variance-covariance matrix, VCV , of the estimated parameters, and

the corresponding correlation matrix,

r

j

k = VCV( J,k)/(VCV( j, j)-VCV(k,k))

1/2

for j = 1, ..., NPAR

and k = 1, ..., NPAR.

• ESTIMATES FROM FIT :

° ESTIMATED PARAMETER : the final estimate for each parameter,

PAR(j) for j = 1, ..., NPAR.

° SD OF PAR : the standard deviation of the estimated parameter,

( VCV( j, j)) 1 /2 for j = 1, ..., NPAR.

° T(PAR=0) : the Student's t statistic under the null hypothesis that

PAR(j) is actually zero,

8-11
T(PAR=0)

j = PAR(j )/(VCV(j ,j)) 1/2 for j = 1, NPAR.

o PRQB (T) : the two-sided significance level of T(PAR=0)j. This is

the probability of exceeding the given t value under the null

hypothesis that the parameter PAR( j ) is actually zero.

o ACC DIG : an estimate of the number of reliable digits in the

parameter estimates, i.e., an indication of the computational

accuracy of the solution. A computationally accurate solution will

produce values between DIGITS-2 and DIGITS, where DIGITS is the

number of decimal digits carried by the user’s computer for a single

precision value when the single precision version of STARPAC is

being used and is the number carried for a double precision value

otherwise. Values less than DIGITS-4 may indicate some computational difficulty such as poor scaling or near singularity.

• ESTIMATES FROM FIT OMITTING LAST PREDICTOR VALUE ; ESTIMATED

PARAMETER, SD OF PAR, T(PAR=0) and PROB(T) values for a fit omitting

the last column of the design matrix and thus omitting the last

parameter from the model.

• The residual standard deviation, RSD.

• The residual degrees of freedom, Nnzw“NPAR, where Nnzw is the number

of observations with nonzero weights.

o The squared multiple correlation coefficient,

N

__ l wti

» Y(i

)

where YrT _ i=l w — — —. . N

l wt i i=l

R2 is a measure of how well the fitted equation accounts for the total

variation of the dependent variable, Y. It is only computed when the

first parameter of the model is a constant, i.e., when the elements of

the first column of the design matrix are all equal.

R = 1.0 RSS(g)

I Wtl (Yd) - Yj 2

i = l

F . Examples

User-Specified Model (Design Matrix) . In the example program of figure

F-la, LLS is used to compute the least squares solution for the example given

on pages 61-65 of Daniel and Wood [1971]. The results for this problem are also discussed in Draper and Smith [1981], pages 372 and 373. Figures F-lb

through F-le show the four pages of output from LLS.

Polynomial Model (Design Matrix) . In the example program of figure F-2a,

LLSP is used to compute the least squares solution for the example given on page 311 of Miller and Freund [1977]. Figures F-2b through F-2e show the four

pages of output from LLSP.

8-12
Linear Least Squares

With User-Specified Model (Design Matrix)

MAIN PROGRAM!

c

cc

c

cc

c

e

c

PROGRAM EXANPL DEMONSTRATE LIS USING SINGLE PRECISION VERSION OF STARPAC

RUN ON CYBER 180/840.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE 6 ON CYBERS)

tSEE CHAPTER 1# SECTION 0.4]

N.B « DECLARATION OF Y# XH AND RES RUST BE CHANGED TO DOUBLE PRECISION

IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL Y( 30) » XM<30#5)# RiSCIG}

DOUBLE PRECISION DSTAM500)

C COMMON /CSTAK/ OSTAK

CC SPECIFY NECESSARY DIMENSIONS

C

l OSTAK • see

IXK « 10

CC READ NUMBER OF OBSERVATIONS AND NUMBER OF UNKNOWN PARAHETERS

C INDEPENDENT VARIABLES

C DEPENDENT VARIABLES

C READ 100» N# NPAR

READ 101# UXHU#Ji» I*1#N»# J*1»NPAR)

READ 101# (Yd)# I®1, N

)

C

C PRINT TITLE AND CALL LLS TO PERFORM LINEAR LEAST SQUARES ANALYSIS

C WRITE (6# 102) CALL LLS (Y# XN» N» 1XN# NPAR# RES# LOSTAK)

C STOP

C

C FQRNAY STATEMENTS

e 100 FORMAT (219)

101 FORMAT C21F1.0)

102 FORMAT C1RESULTS FROM STARPAC ( # • • LINEAR LEAST SQUARES SUBROUTINE LLS*

)

END DATA! 21 4

l i 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 86 80 75 62 62 62 62 62 98 98 56 98 98 58 50 90 50 50 50 96 70

2? 2? 29 24 22 23 24 24 23 18 18 17 18 19 16 18 19 19 20 20 20

69 88 90 87 87 87 93 93 87 80 89 88 82 91 89 86 72 79 80 82 91

42 IT 37 28 IS 18 19 20 15 14 14 13 11 12 8 7 8 8 9 15 15

Figure F-la

Example program using LLS

8-13
o

UJ

** at OiSlO©ft*»<*OOftO^Ottf»H 09«OOOft Hh>ri>dDfM>«^O#oa#O 0 «t^»4 ^^«

*4 I *4 *4 I j | | 94 8 6 III ** I I

fl^OWO^ o o #n ft <n o m *> m +» *\ t* «

**> r\ ^ #4 ft

m H«> » HO 4^0 ^ pu o o o o

ft ft o o • O > ft i 9 M • » ft

O I O' ft o I ft o i o ft o ft o «U

© ft m © o ^o t fV 9* 8 I

#> ft < O O I fw ft o o < 1 o +* * > o o < i o O

ft o e • H OI

tu ^e<o«vr#o> a> ^oo#coHOO<^<ortH *=> us

U> 3 A^#NH«»»#MAO0O^»9OMhK *« —

ft 94 ft© 94© 00 ftmft*j*( 0 ©ft© 0®©0

O <

U) Z> »©©©©©•••••••

® ft

© «\ ft «% • « OK OOfyflVdO^S^s^O^cH©#**^ • ® © • ® O W

fi m« 9»J^HfVJWWHHHHHH»»« 0 ®^HW I

<UP3

bo « c « « «

UJ© # « Oft

<a « z « « # ==?#©* * kU #

us «> «

000000000060000000000 OQOOOOOOOOOOOOOOOOOOO ooooooooooooooooooooo ooooooooooooooooooooo ooooooooooooooooooooo ooooooooooooooooooooo • «««»©©•©••»• «ooooo©« *aP**K>©©© 0 ©OftftH» 94 tfW) © « • © » f) 9% ft O ftftfc CVS ^ oH «“3 W 93 9$ ^ 94 94 O O O • O’ 94 «<

9«=

W t O # 144 * © # •= ft ft « M # e * I • O ft at e

iA ft UJ ft • *9 ft »A ft 3 ft US ft ft ® ft 2 ft < * N t © ft s-« ft ® « 3 ft «A ft ft

ft * ft U* ft O ft »A ft *«3 ft < ft ft* ft

ooooooooooooooooooooo

ooooooooooooooooooooo ooooooooooooooooooooo

ooooooooooooooooooooo © ©®«c©e©o©©«c «••»•©•• » OOOOOO<0lp*Q©©ftrfOTO®MO©*i 94 OOOOOOOOOOOOOOOOOOOOO

US ft •ft ft

O

g o o o © o o © o © o ©

©© o o o o o o © o ft Z ft *« e o o o © © © © o © © © © © © © © © © o © © ft «! ft u 0 » o o o o © o © o © o © o © o © © o o © © o at ft 0 © © © © o o © o © © © o © © o o o © © o © ft ft ft •A 1 ft o o © o © © © © © o © o © o © © © © © © o us ft US ft «* i o © o © o © o © © © © © o o o © o o © © o © z> ft ft « 0 »

*=» ft «A ft ** s o ? 5 •ft

N

m ft ft

m o o o o o o m

© 6 0 0 0 ft US ft s i 9=C «v

ft at ft

© !1 o

«-» ft •ft ft 4A

J1 us

ft ft

G ft 1 OL

a. ft o ft

O |1 ft

ft. ft 9A ft •A (I ft ft ft •« ft ft ft US (1 o o ©

©

©

©

©

©©©

©

©

©

©

© o ©

©

©©© ft «A ft a*S (1 © © © © o o © o © © © © © © © © © o © o © ft ft ft 11 © © © © © © o © © © © © © o o © o © © o o X ft US ft * (1 © © © © o © G © © © o © © © © o © © © o © c ft wS ft © I © © © © © © o © © © © o © © o © o o o o © ft ft ft at |1 © © o © o o © o o © © o © © © o o © o © o Ub. ft a. ft u (1 ft ft ft 1I © © o M N »rf f* *4 o ft o » o o © o o © © ft © <a ft us ft «A I| o o o © ft ft ft ft r% o o o o> o o. m o O Ct o o ft Z ft P- 11 H ft ft -J 1 o ft -» ft S <! » •< 9*0 O ft o ft o o o o •H o m ft r» ft o ft o o (A ft ft 4A |! G H 94 94 94 893 K3 K5 US ft ft U3 j\ ft « ft ft

8-14

Example

of

LLS

output
a

a

a

a

i

I]

a

a

a

a

at

ii

ai

#> •

i

i

«

•

l

l

l

I •

i

l

iI•

lt

I

I

t •N

• •

• 04

I 04

I

Se«B*8081#8i0§<t>8l884>lie8

O

w.o

3

T.O

oc

y* |I

I

I

II

I

I

I

9

I

I•

9 •

I

II

I

I <&m

«

r» •

© 9 =* 0 w |

« Mr 0 ©

9

8 O I «4 I ft. I >» 8 o® 0 » 8 «4

»- I fl I •« 8 ® 8 O 8 or 0 ft. 9

8 -S 8 r I « •

8 8 B 8 f * t 9 <> 8 6 ft B * 9 9 8 8 8 0 8 8

-4 • ^3 9 O « « I •* 8 U4 8

o

O

8 8 8 8 ! § 8 0 I I 8 I 4> I | I 8 | « O O O l> M K M8 • o •

O- 04 • I

I

0)3

be

iH

U8|t8+tflll'»«ICt*lll fulfil I O

o

*

O I « I K •

I 21

•

I

8

I•

I O

•

ui I or. i S I u

o |

• •• • ••• ••• « fl +It|l-+||lf9 + |lll4llll + o o «\ *> Cl O H 4) H H

8-15

O

I I •

•O r-t

Example

of

LLS

output

(continued)
©

© *> * o © o ^ O O O • ® • • o *>

US

CD£O

<38 W©

Ob - ^ fg ^ M I m <m © m l

«-«>

© *»

m I U> • © G +* | (9 © <S © 0 © © ® | F<^« «

oo « # © & © *c © © t* o

«s# oX

N=

#S *4 <0

K3 «n h» • « © m ® « • # m *

l«! <£ •# ® *=« •* • ©

U*

<Wvu0 06mXG=

<st U9

VS©

<-/ 1^ »» © X < vs Z w>

«5

OS tfS 6& VJ © «r © © 9>CMO

*4 as *45

© ^ as ® © ® **> v as w ® © © 0*600 © OS <0 r*9 © © as ©>

»*3 ?<oCW

<«.**©© ^ *> © 6* ® • • • • 66# #»KO #OKO : CL O 6 (it O

O l o

Ut 3 © © S us

OfgQI K ** +* i • o • © # r o 6 © ^« »< ©

rtMA #

T3I t**

0)

L-<

5c

tH

8-16

Example

of

LLS

output

(continued)
II

ft] iiiiii

Ml

11

Cl

OON o o o © © ©

9»N • • • 9 A A

©© *A m © m

©

at

ifc

«y # h © © © l • « Ohn N M A • C m m> « a»

04

A

© v«

00 •

at • ^ 1 I M I £ I m

Ml | © OA^N 04 > 1 N444 1 • ©

© Mi | 0A04 1 to m C 1 • ^ AN 1 *4 ol o4

m «A 3 a 1 1 • • • o • • a • Z at | 1 1 © IN © c=fl osj a i u A A AA ©

t*> a. 1 Cl 3 Z 8 © A a & 8 04 m 3

<3=5 UD 1 o o *» 0 i i © A a i Ml Ml 1- #044 Ml

ob9 z I ffc. «*

©© tw

O

© ©© K*

W » I ANM

A • © OOfN Ml

© K> 8 ©

a • a

a z o vi 8 0044 at © f Ml 8 A K A4 A © 8 •i AAMN © © Ml 8 © a a A a ©

ai Z 8 z 4AAA©

K© o«j - 8 o • • • • © *4 AI z

«N 8 © 1 1 1 © 4KOA AI 04 Cl

0=3 u. 8 ©

a AONA

©©

©

UO • 04 at

AA AK

© • Mi

UA 1 o © • © • © AI •

a. vt. | »-> a. AAA • e z

Ml 0 Ml

© 04 44 1 1 ©

© 04 8 U 8 z 8 IN »-> at « 1 N* Mi A

w> at 9 AOAN z 8 © m 8 J z AAN4 o © 04 3 4 8 © a NAO at #4 at © C « Z -4 • 44 A Mb AI © 04 Z • O Ml M • •40 at © 41 ON AI 3 o

K* 5 ! ©

A KAMO

A 4 © • ©©

O ex O 8 A «l • •A A mi a OANO IN

©

X

w 8 ^ a mi NAN

A N- 4 0 4 4 Mi * 1 © z at • • « • 4 IN A ANA N* H» z a 8 o © 1 1 z o AOON Z 3 o -A 8 uj © 04 © © © © Mi A. 04 Ml 8 X © vi A- © • A4A 04 Z

o- at 1 - 04 oa at

A

A AH Cl o A at 8 o z Ml A • • • z z Cl Z O 8 Ui Mi o o IN

*4 o >MIM

AO IN >>

O- oxo

K Ml Mi mJ

M ° « - «x 4 A AN

© Mi

O N*

Ui Z a in KNOO o* at Cl

O * Z IN 4AOO > IN Ml

m Mi

O Mi H4KO at Mi z ©

IM Ml at

O r+ AN«

A Ml

O IN o ©

at o < UiU • O • A N»

O 04

O

•a z at HK 40 Mi 40NA o K- Cl © © v* * Z 4 A AO z A OHA © A © O A Ui O A • • • 4 KN4A © Ml —l

IN

m at

©

m 04 1 1 l at

©O

© AI

O Mi Ml

O

-a Z Mi tA

©

A AI AI z at© o- > 4U4 A. A 4 A A © © at «. m O Z -* © © © AI K Ml o Mi © u at © mi O • ANA A O Cl ©

Ui 1 Z ANA 4 Ui

©

K • A Z

Ui > at at

K A"

A • A • -J z Ml 3 u o © O => A 1 I © o —I Z

at z u>u -i Z 3 A. © A i O 04 o o 04 Mi

Ui 04 III

u 0- A* lil

X z at M ANA4 v» an -J 0- 4 © Ml Ml © 3 —1 > m m Z * IVU3

bC

8-17

Example

of

LLS

output

(continued)
Linear Least Squares

With Polynomial Model (Design Matrix)

MAIN PROGRAM! PROGRAM EXAMPL

c

C DEMONSTRATE LLSP USING SINGLE PRECISION VERSION OE STARPAC

C RUN ON CYBER 160/640.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE T A p E 6 ON CYBERSJ

C tSEE CHAPTER 1» SECTION D.43

C

C N.B. DECLARATION OF Ya X AND RES MUST BE CHAN6ED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL Y ( 30 ) # X(30l> RES ( 303 DOUBLE PRECISION DSTAM500)

C COMMON /CSTAX/ DSTAK

C

C SPECIFY NECESSARY DIMENSIONS

C LOSTAK • 906

CC READ NUMBER OF OBSERVATIONS AND DEGREE OF THE POLYNOMIAL TO BE FIT

C INDEPENDENT AND DEPENDENT VARIABLES

C READ 160a Na NDEG

READ 101a (XU»a YU) a I«1aN)

c

c PRINT TITLE AND CALL LLSP TO PERFORM LINEAR LEAST SQUARES ANALYSIS

C WRITE (6a 102) CALL LLSP (Ya X# N» NOEGa RESa LOSTAK)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (219)

101 FORMAT (2F5.1)

102 FORMAT C1RESULTS OF STARPAC 8 # * » LINEAR LEAST SQUARES SUBROUTINE LLSP 8

J END

DATA! 9 2 0 e 6 12.0

1.6 10.5

2.0 19.0

3.0 8.0 4.0 7.0

5.0 B.O 6.0 7.9

7.0 B.9 B.O 9.0

Figure F-2a

Example program using LLSP

8-18
ni«««iii

tf

ri)

Ml£

11

19

II

** o

-I #>

© 3 O o z

ac® >»S

Ul ©> fr«> m « o-o <«?«'* 3 « ® ® z

tA « © « M

vt# 4 < * c

Ml t o

o. *

OK »- o ® ac # << «A ® Ml 3 «• -I

ia t Q ** •* • * «* a% .4 * * K ui M« ••••••••• | | «4 | I I •

•4o

Ut 0 ^ ^ ®

® ^ ® N W ^ #S» ®N • ® e ^ISIIM^O«M.# 0 « M ®H® («t H0O K«4 W < 1^® ®0 ••

UI N*^ 8* r r 8* #

•* i*

II. UI 03 0N90K00N9 «3 ®# 0 ®# 0 ® #0#0

«M > »S»9 H»n C9 o ^ «u •* m «* ® ^4 ^ o o ©4 ^ ^ O ^ ** * ** O UI #NN<VMNNM#

I* ©C • ••©•••©• O ®N® ® N® 0 H® m #^® w®©®

»> ^ ®2JU22®o S*

®n® ®e#<® O® M®N0MN® UI > © MH m ®*0 ••••••• ® *4 •* o m fffe m o

UI ooooooooo

Z«l ooooooooo

Ml® OOOOOOOOO OOOOOOOOO ZMui ac ooooooooo ® ® • • iOOO® ® o W> MOO «••••# I ® • UI • ac I S I 3 I s •

X)

CSJI3

b£) •H

O

OOO oo o o o o o o o o o o o o o o o o oo o o o o o o o o o o oo o o o o oo o o o o

8-19

Example

of

LLSP

output
UMCAR

HAS?

SQUARES

SSTINATIOM

WITH

POLTMOMIAl

MOOSl#

CONTINUED

STARPAC

2.00S

-

OECEhBEA

t,

I9M

SID

RfS

VS

ROM

NUMBER

STD

RES

VS

PREDICTED

VALUES

I » I 1*9 §6 1*1 9 1 0*1 C 0 0 © 0 S 8 * §•§•• i »«> ei 9

I

I

I

I «

» (B

I «

« »

I

• t • e • i i i i i i m

t l l l • • §

• 0 e i «> 9669*919 §•

•

I

I ©©

• A

9 9 9 6 * 6 9 6 9*9A

6 9 1*99 6 9*9•%

9 e

o

O 9 m «

«# 9

9

99

9

I mN

9 A

9* fb

9 0 ffi I m 9 M 9 m 9 « 9

9 Ik 9 G 9 X 9 21

*» 9 *

• » • t

«C 0

6 « 9 « 9 O 9

0 § I

o

©

*9999*69I§*9999*9I99*999 9 A « 9 • I*

9 9991*6 9 9 9 * 6 9 9 9 * 1 9 9 9*9999*0

9

9

9

9 O

9 * 9*

m. *1696*9 991*9991*999 9*99 II*

8-20

T3

<U3

C

0

tsi

1 U-j

01u

3

bo

±j3

a

CLW2 _)

a>a

E

(0X

u

I

I

I

I

I

I

I

I

1
I]0aaa

0iaa

at

ft!

if

ca5 G I a.

©

O *» I « o o o I <B o o o ! a • • •

at o a. III u. I © o © • O A M A 0 © IA «**

a.« ©

©

©

©©

©

© • • • Iz©oX 998 U» II9 m <m + 9s* «% ® e=3 ® « OA » • • N A A A v* ® ^ ^

HIX f*» 0 A

U4 ^ A# u x VI f* ^ r- X © Mi f*> A* < at © © ©

e==3 «l aoN

© as

©

X

A 4

lift

A HI

© • • *4

G » €K

u

M

A •

\\

x Hi

«* It. » » © X X HI ' © V*

S=3 M£ VD Of «•

«> <«

© 1 <=s9 —5 m > us < A at , § Z HI

<8 ^ AX

H «H

A 1 x m O*? «< Ik

ad

©

«* at

k

x 1 o* at

T3

«Ni Cfa

a)w3

&0

O AMI

e«« MO# K OM AO KAO K AM M K n on O • o S K O

8-21

Example

of

LLSP

output

(continued)
oo o © o• • s-u*9Q

OK• <Si to • •3 «V)I © ©

IVS <0

k> «n

K=

©

r»

w o « o « K «

K= #9

K*> <ft K «

Kt> #»9 «0 <TO e® O *9 o

VD 6 a 9 iu i K= 0 tM $ £ 6 ^ I « 9 •« 8 * 96 O «

1*9 9 O© < Q 1 si O 9 < «3 « <8 IM oz«O <«€ tu « X < **> © s

U£ IU >© X <U « *=*> < «*> X ttt iUOW « © ^ Mfl €a9 UZWK^ » « « o < © u » w

??

#a o» «w ^ K® K® eoo ® © © e © ® 9 0 9 M0 9*9 K® «• srt K* ® KOK © ® *4 MOO • «r> © • • • 9 9

WWW o oo © 0* © OCM m> & m ® m <® K OM *43 © s©

©U

© ^

c=3 r3

©

© **

©

©© «4 M M ©«**€ • (ft 0* © ® © WK « 6 ©eU4 KM ©

#<K= © ©

©

©©

© f4 <r * <# » •# #© © K# • • «

WOW ® « K4 © © <T CM o

<#>**

©

®

®©

©

© K9

M MM Cft

© o 0*

*>K»«

oOC

©• ©I©

wou o a » © *» IM < M « m > «*> © I*© G

MOU

m*

X

M

© «/

©

K o o «

0)

es!!

0)u3

bo

"H

8-22

Example

of

LLSP

output

(continued)
G. Acknowledgments

The code and printed output for the linear least squares subroutines has

been modeled on the linear least squares code and output used by OMNITAB II

[Hogben et al. 1971].

8-23

CHAPTER 9

NONLINEAR LEAST SQUARES

A. Introduction

STARPAC contains 16 user-callable subroutines for nonlinear least squares

regression* Twelve of these are estimation subroutines that compute the least

squares solution as described below, performing either weighted or unweighted

regression with either numerically approximated or user-supplied (analytic)

derivatives. The estimation subroutines allow three levels of control of the

computations and printed output, and allow the user to specify a subset of the

parameters to be treated as constants, with their values held fixed at their

input values. This last feature allows the user to examine the results

obtained estimating various subsets of the parameters of a general model

without rewriting the model subroutine for each subset. The other four

subroutines described in this chapter are utility procedures which choose

optimum step sizes for numerically approximating the derivative and which

verify the correctness of user-supplied (analytic) derivatives.

Each of the subroutines described in this chapter assumes that the

observations of the dependent variable, y^, are modeled by

y-j_ = f

i (xi ,$) + for i = 1, ...» N,

where

N is the number of observations;

f^ is the function (nonlinear in its parameters) that models the i

1"*1 observation;

x^ is the vector of the M independent variables at the i*1 *1 observation;

g is the vector of the NPAR model parameters; and

e i is the unobservable random error in the i

c ^ observation, which is

estimated by the i*"*1 residual.

The least squares estimates of the parameters, g, are obtained using an iterative procedure that requires the matrix of partial derivatives of the

model with respect to each parameter,

D(i,k) = 3fi (x i ,g)/9g(k) for i = 1, ..., N and k = 1, ..., NPAR.

The derivative matrix may be supplied analytically or approximated

numerically

.

A The least squares solution, g, is that which minimizes (with respect to

g ) the residual sum of squares function,

9-1
[e^.wti]

N N

RSS(B) = I [Oi - f

i (xis 6))2owt

i ] = l i=l i=l

where carat

(*

*

) denotes the estimated quantity, and

wt^ is the weight assigned to the i

c ^ observation (wt-^ = 1.0 in the

"unweighted" case). Appendix B discusses several common applications

for weighted least squares.

The user must supply both initial values for the parameters and the

subroutine NLSMDL (described in §D) used to compute f

Xj_ ,B£ )

» i = 1, ..., N,

i.e., the predicted values of the dependent variable given the independent

variables and the parameter values from iteration £ for £ = 1, 2, ... . Initial parameter values should be chosen with care, since good values can significantly reduce computing time.

STARPAC provides a variety of subroutines to accommodate many levels of

user sophistication and problem difficulty. Users are directed to §B for a brief description of the subroutines. The declaration and CALL statements are given in §C, and the subroutine arguments are defined in §D. The algorithms

used and the output produced by these subroutines are discussed in §E. Sample

programs and their output are shown in §F.

B . Subroutine Descriptions

B. 1 Nonlinear Least Squares Estimation Subroutines

The simplest of the 12 nonlinear least squares estimation subroutines,

NLS, requires neither user-supplied weights nor analytic derivatives. The

estimated results and a variety of statistics are automatically summarized in

a five-part printed report, and the estimated parameters and residuals are returned to the user via the subroutine argument list (level one control,

described below). Most nonlinear least squares problems can be solved using

NLS.

The other 11 estimation subroutines add the weighting, derivative and

level two and three control features both singly and in combination, providing

greater flexibility to the user at the price of less simplicity. These

features are indicated by the suffix letter(s) on the subroutine name (e.g.,

NLS_S and NLSWDC).

• Suffix W indicates user-supplied weights.

• Suffix D indicates user-supplied (analytic) derivatives.

© Suffix C indicates level two control of the computations.

© Suffix S indicates level three control of the computations.

9-2
The three levels of computation and printed output control are as

f ollows.

o In level one, a five-part printed report, discussed in detail in

§E.2.a, is automatically provided and the estimated model parameters

and residuals are returned to the user via the argument list.

• Level two also returns the estimated parameters and residuals, and,

in addition, allows the user to supply arguments to indicate

- a subset of the model parameters to be treated as constants,

with their values held fixed at their input values;

~ either the step sizes used to compute the numerical approximations to the derivative, or, when user-supplied analytic

derivatives are used, whether they will be checked;

- the maximum number of iterations allowed;

- the convergence criteria;

- the scale (i.e. , the typical size) of each parameter;

- the maximum change allowed in the parameters at the first

iteration;

- how the variance-covariance matrix is to be approximated; and

- the amount of printed output desired.

© Level three has all the features of level two, and, in addition

returns the following estimated values via the argument list; - the number of nonzero weighted observations (only when a weighted analysis is performed);

- the number of parameters actually estimated;

- the residual standard deviation;

- the predicted values;

-- the standard deviations of the predicted values;

- the standardized residuals; and

- the variance-covariance matrix of the estimated parameters.

B «2 Derivative Step Size Selection Subroutines

When the partial derivatives used in the nonlinear least squares solution

are not available analytically, STARPAC subroutines approximate them numerically. In this case, the subroutines can select optimum step sizes for

approximating the derivatives. [See §E.l.b.] The user also has the option of

computing these step sizes independently of the estimation process by calling

either of the two step size selection subroutines directly. For example, when

planning to use the parameter fixing capability [argument IFIXED] to examine

several subsets of the parameters of a general model, computing the step sizes

first and passing them to the estimation subroutine is more efficient than

recomputing them each time the estimation subroutine is called.

The simplest of the two user-callable step size selection subroutines,

STPLS, summarizes the step size selection information for each parameter in a printed report and returns the step sizes to the user via the subroutine

argument list.

9-3
The second step size selection subroutine, STPLSC, differs from STPLS

only in that it enables the user to supply arguments to indicate

- the number of reliable digits in the model results;

- the number of exemptions allowed by the acceptance criteria,

specified as a proportion of the total number of observations (see §E.l.b);

- the scale (i.e. , the typical size) of each parameter; and

~ the amount of printed output desired.

B . 3 Derivative Checking Subroutines

When the partial derivatives used in the nonlinear least squares solution

are available analytically, the user can code them for use by the estimation

subroutines. [See §D, argument NLSDRV.] Because coding errors are a common

problem with user-supplied derivatives, the STARPAC estimation subroutines

automatically check the validity of the user-supplied derivative code by

comparing its results to numerically approximated values for the derivative.

When the results are questionable, the checking procedure attempts to

determine whether the problem lies with the user's code or with the accuracy

of the numerical approximation. [See §E.l.c.] Although the checking procedure is automatically available to the estimation subroutines which accept

user-supplied derivatives, the user may want to check the derivative code

independently of the estimation process. In these cases, the user can call

either of the two derivative checking subroutines directly, and suppress

checking by the estimation subroutines. [See §D, argument IDRVCK.]

The simplest of the two derivative checking subroutines, DCK.LS,

summarizes the results of the check in a printed report.

The second of the derivative checking subroutine, DCKLSC, differs from

DCKLS only in that it enables the user to supply arguments to indicate

- the number of reliable digits in the model results;

- the agreement tolerance;

- the scale (i.e., the typical size) of each parameter;

- the row at which the derivative is to be checked; and

- the amount of printed output desired.

C . Subroutine Declaration and CALL Statements

NOTE: Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B, and §D.

9-4
Nonlinear Least Squares Estimation Subroutines

The <basic declaration block> identifies declaration statements that are needed by all of the nonlinear least squares estimation subroutines. The user

should substitute the following four statements for each occurrence of <basic

declaration block> given below.

<real> Y (n), XM PAR (npar), RES(n)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

EXTERNAL NLSMDL

NLS: Compute and print a five-part weighted nonlinear least squares

analysis with numerically approximated derivatives; return parameter

estimates and residuals

<basic declaration block>

CALL NLS (Y, XM, N, M, IXM, NLSMDL, PAR, NPAR, RES, LDSTAK)

NLSC: Compute and optionally print a five-part unweighted nonlinear least

squares analysis with numerically approximated derivatives using

user-supplied control values; return parameter estimates and

residuals

<basic declaration block>

INTEGER IFIXED (npar)

<real> STP (npar), STOPSS, STOPP, SCALE (npar)

,

DELTA

CALL NLSC (Y, XM, N, M, IXM, NLSMDL, PAR, NPAR, RES, LDSTAK,

1 IFIXED, STP, MIT, STOPSS, STOPP, SCALE, DELTA, IVAPRX, NPRT)

9-5
NLSS: Compute and optionally print a five-part unweighted nonlinear least

squares analysis with numerically approximated derivatives using

user-supplied control values; return parameter estimatess residuals

,

number of nonzero weights, number of parameters estimated> residual

standard deviation> predicted valuess standard deviations of the

predicted values and variance-covariance matrix of the estimated

parameters

<basic declaration block>

INTEGER IFIXED (npar)

<real> STP (npar), STOPSS, STOPP, SCALE (npar)

DELTA

<real> RSD, PV(n), SDPV(n), SDRES(n), VCV (npar

e

s npare)

CALL NLSS (Y, XM, N, M, IXM, NLSMDL, PAR, NPAR, RES, LDSTAK,

1 IFIXED, STP, MIT, STOPSS, STOPP, SCALE, DELTA, IVAPRX, NPRT,

2 NPARE, RSD, PV, SDPV, SDRES, VCV, IVCV)

NLSW: Compute and print a five-part weighted nonlinear least squares

analysis with numerically approximated derivatives; return parameter

estimates and residuals

<basic declaration block>

<real> WT(n)

CALL NLSW (Y, WT, XM, N, M, IXM, NLSMDL, PAR, NPAR, RES, LDSTAK)

NLSWC: Compute and optionally print a five-part weighted nonlinear least

squares analysis with numerically approximated derivatives using

user-supplied control values; return, parameter estimates and residuals

<basic declaration block>

INTEGER IFIXEL(npar)

<real> WT(n)

<real> STP(npar), STOPSS, STOPP, SCALE(npar) , DELTA

CALL NLSWC (Y, WT, XM, N, M, IXM, NLSMDL, PAR, NPAR, RES, LDSTAK,

1 IFIXED, STP, MIT, STOPSS, STOPP, SCALE, DELTA, IVAPRX, NPRT)

9-6
NLSWS: Compute and optionally print a five-part weighted nonlinear least

squares analysis with numerically approximated derivatives using

user-supplied control values; return parameter estimates, residuals,

number of nonzero weights, number of parameters estimated, residual

standard deviation, predicted values, standard deviations of the

predicted values and variance-covariance matrix of the estimated

parameters

<basic declaration block>

INTEGER IFIXED (npar)

<real> WT(n)

<real> STP(npar), STOPSS, STOPP, SCALE(npar^), DELTA

<real> RSD, PV(rc), SDPV(n), SDRES(n), VCV (npare, npare)

CALL NLSWS 'Y, WT, XM, N, M, IXM, NLSMDL, PAR, NPAR, RES, LDSTAK,

1 IFIXED, STP, MIT, STOPSS, STOPP, SCALE, DELTA, IVAPRX, NPRT,

2 NNZW, NPARE, RSD, PV, SDPV, SDRES , VCV , IVCV)

NLSD: Compute and print a five-part unweighted nonlinear least squares

analysis with user-supplied derivatives; return parameter estimates

and residuals

<basic declaration block>

EXTERNAL NLSDRV

CALL NLSD (Y, XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, RES,

1 LDSTAK)

NLSDC: Compute and optionally print a five-part unweighted nonlinear least

squares analysis with user-supplied derivatives using user-supplied

control values; return parameter estimates and residuals

<basic declaration block>

EXTERNAL NLSDRV

INTEGER IFIXED (npar)

<real> STOPSS, STOPP, S CALE (npar )

,

DELTA

CALL NLSDC (Y, XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, RES,

1 LDSTAK, IFIXED, IDRVCK, MIT, STOPSS, STOPP, SCALE, DELTA,

2 IVAPRX, NPRT)

9-7
NLSDS: Compute and optionally print a five-part unweighted nonlinear least

squares analysis with user-supplied derivatives using user-supplied

control values; return parameter estimates, residuals, number of

parameters estimated, residual standard deviation, predicted values,

standard deviations of the predicted values and variance-covariance

matrix of the estimated parameters

<basic declaration block>

EXTERNAL NLSDRV

INTEGER IFIXED (npar)

<real> STOPSS, STOPP, SCALE (npar) , DELTA

<real> RSD, PV(n), SDPV(n), SDRES(n), VCV (npare, npare )

CALL NLSDS (Y, XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, RES,

1 LDSTAK, IFIXED, IDRVCK, MIT, STOPSS, STOPP, SCALE, DELTA,

2 IVAPRX, NPRT, NPARE, RSD, PV, SDPV, SDRES, VCV, IVCV)

NLSWD: Compute and print a five-part weighted nonlinear least squares

analysis with user-supplied derivatives; return parameter estimates

and residuals

<basic declaration block>

EXTERNAL NLSDRV

<real> WT(n)

CALL NLSWD (Y, WT, XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, RES,

1 LDSTAK)

NLSWDC: Compute and optionally print a five-part weighted nonlinear least

squares analysis with user-supplied derivatives using user-supplied

control values; return parameter estimates and residuals

<basic declaration block>

EXTERNAL NLSDRV

INTEGER IFIXED(npar’)

<real> WT(n)

<real> STOPSS, STOPP, SCALE(npar») , DELTA

CALL NLSWDC (Y, WT, XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, RES,

1 LDSTAK, IFIXED, IDRVCK, MIT, STOPSS, STOPP, SCALE, DELTA,

2 IVAPRX, NPRT)

9-8
NLSWDS: Compute and optionally print a five-part weighted nonlinear least

squares analysis with user-supplied derivatives using user- supplied

control values; return parameter estimates, residuals, number of

nonzero weights, number of parameters estimated, residual standard

deviation, predicted values, standard deviations of the predicted

values and variance-covariance matrix of the estimated parameters

<basic declaration block>

EXTERNAL NLSDRV

INTEGER IFIXED(npar)

<real> WT(n)

<real> STOPSS, STOPP, SCALE(npar’) , DELTA

<real> RSD, PV(rc), SDPV(n), SDRES(n), VCM (npare, npare)

CALL NLSWDS (Y, WT, XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, RES,

1 LDSTAK, IFIXED, IDRVCK, MIT, STOPSS, STOPP, SCALE, DELTA,

2 IVAPRX , NPRT, NNZW, NPARE, RSD, PV, SDPV, SDRES , VCV , IVCV)

Step Size Selection Subroutines

STPLS: Compute and print optimum step sizes for numerically approximating

derivatives; return selected step sizes

<real> XM(n,/7z), PAR (npar), STP(npar)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

EXTERNAL NLSMDL

CALL STPLS (XM, N, M, IXM, NLSMDL, PAR, NPAR, LDSTAK, STP)

STPLSC: Compute and optionally print optimum step sizes for numerically

approximating derivatives using user-supplied control values; return

selected step sizes

<real> XM (n,m), PAR (npar), STP (npar)

<real> EXMPT, SCALE (npar)

DOUBLE PRECISION DSTAK {.Idstak)

COMMON /CSTAK/ DSTAK

EXTERNAL NLSMDL

CALL STPLSC (XM, N, M, IXM, NLSMDL, PAR, NPAR, LDSTAK, STP,

1 NETA, EXMPT, SCALE, NPRT)

9-9
Derivative Checking Subroutines

DCKLS: Perform and print derivative checking analysis; return error code

<real> XM (n ,m)

PAR(npar»)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

EXTERNAL NLSMDL, NLSDRV

CALL DCKLS (XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, LDSTAK)

DCKLSC: Perform and optionally print derivative checking analysis using

user-supplied control values; return error code

<real> XM(n,77z)> PAR (jipar)

<real> SCALE (jipar)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

EXTERNAL NLSMDL, NLSDRV

CALL DCKLSC (XM, N, M, IXM, NLSMDL, NLSDRV, PAR, NPAR, LDSTAK,

1 NETA, NTAU, SCALE, NROW, NPRT)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE? —> indicates that the argument is input to the subroutine and that

the input value is preserved;

<— indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; — indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

° ° • indicates that the variable is passed via COMMON.

D <-- The matrix of exact dimension N by NPAR that contains the partial

derivatives of the model with respect to each parameter,

PAR(k), k = 1, ..., NPAR. This argument is used within derivative

subroutine NLSDRV [see argument NLSDRV below].

DELTA “> The maximum scaled change allowed in the parameters at the first

iteration, i.e.

6q. [See §E.l.a.] The default value is 100.0.

When DELTA <0.0 or when DELTA is not an argument of the —continued—

9-10
subroutine CALL statement the default value is used. A smaller

value of DELTA may be appropriate if, at the first iteration, the

computation of the predicted values from the user’s model subroutine produces an arithmetric overflow or the parameters leave the

region of interest in parameter space. A reasonable alternative

to the default value of DELTA is an upper bound to the scaled

change that the estimated parameters should be allowed to make on the first iteration,

DELTA = min{ lA^xBCk) | /SCALE(k), for k = 1, ..., NPAR}

where A^BCk) is the maximum change allowed for the k

th parameter

at the first iteration.

DSTAK ee * The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

EXMPT —> The proportion used to compute the number of observations,

a = EXMPT»N, for which the forward difference quotient derivative

with respect to a given parameter is exempted from meeting the

acceptance criteria for step size selection. [See §E.l.b.] The

default value for EXMPT is 0.1 (10 percent). When the usersupplied value is outside the range [0.0, 1.0]

,

or when EXMPT is

not an argument of the subroutine CALL statement, the default

value is used.

IDRVCK —> The indicator variable used to designate whether or not the

user-supplied derivative subroutine is to be checked. When

IDRVCK $ 0 the derivative is checked, and when IDRVCK =0 it is

not. The default value is IDRVCK * 0. When IDRVCK is not an argument of the subroutine CALL statement the default value is

used.

IERR An error flag returned in COMMON /ERRCHK/. [See chapter 1, §D. 5.

]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

For the estimation subroutines:

IERR = 0 indicates that no errors were detected, and that the

iterations converged satisfactorily.

IERR = 1 indicates that improper input was detected.

IERR = 2 indicates that the computation of the residual sum of

squares using the initial parameter values produced an arithmetic overflow. The user should reduce the size

of DELTA or should supply new starting values. —continued

9-11
IERR = 3 indicates that the model is computationally singular,

which means the model has too many parameters near the

solution. The user should examine the model and data

to determine and remove the cause of the singularity.

IERR = 4 indicates that at least one of the standardized

residuals could not be computed because its standard

deviation was zero. The validity of the covariance

matrix is questionable.

IERR = 5 indicates false convergence. [See §E.l.a.]

IERR = 6 indicates that convergence was not reached in the

allowed number of iterations or model subroutine calls.

[See argument MIT.]

IERR = 7 indicates that the variance-covariance matrix could not

be computed.

For the step size selection subroutines.

IERR = 0 indicates that no errors were detected, and that all

the step sizes satisfied the selection criteria.

IERR = 1 indicates that improper input was detected.

IERR = 2 indicates that one or more of the step sizes did not

satisfy the selection criteria.

For the derivative checking subroutines:

IERR = 0 indicates that no errors were detected, and that the

user-supplied derivative code appears to be correct.

IERR = 1 indicates that improper input was detected.

IERR = 2 indicates that the user-supplied derivative code and

numerical derivatives do not agree for at least one parameter, but that in each case of disagreement the

accuracy of the numerical derivatives is questionable.

Further testing is suggested.

IERR = 3 indicates that the user-supplied derivative code and

numerical derivatives do not agree for at least one parameter, and in at least one instance of disagreement

there is no reason to doubt the numerical derivatives.

IFIXED TM> The vector of dimension at least NPAR that contains values used to

indicate whether the corresponding parameter in PAR is to be

treated as a fixed constant or is to be estimated. If —continued

9-12
IFIXED(I) > 0, PAR(I) will be held fixed at its input value; if

IFIXED(I) = 0, PAR(I) will be estimated using the least squares

procedure described in §A. The default values are IFIXED(I) = 0,

I = 1, . .., NPAR, i.e., all parameters are estimated. When

IFIXED(l) < -1 , or when IFIXED is not an argument of the

subroutine CALL statement, the default value will be used.

IVCV --> The exact value of the first dimension of the matrix VCV as specified in the calling program.

IVAPRX —> The indicator variable used to specify how the variance-covariance

matrix, VCV, is to be approximated. Three approximations are available:

At (1) VCV = RSD2 * (DT .W«D)~1

(2) VCV = RSD2 •

H

_1

At, At, (3) VCV = rsd2 «h-1

. (dt .w*d)«h

-

1

where

At. A^ N At A* At, At H = DT.W»D + { l

e i *wt i

» (a 2 e i /ag (j )ae (k)) for j

i=l and k

W is an N by N diagonal matrix of weights,

W = diag{wt^, i = 1, ..., N}

,

when a weighted analysis is performed, and is the identity matrix

A otherwise, and D is the matrix that contains the partial

derivatives of the model with respect to each parameter.

A T Approximation (1) is based on the assumption that H ~ D • W»

D

because the residuals are sufficiently small at the solution;

approximation (2) is based on the assumption that the necessary

conditions for asymptotic maximum likelihood theory have been met;

and approximation (3) is based on the assumption that the

necessary conditions for asymptotic maximum likelihood theory may

be violated. The results of a recent study by Donaldson and

Schnabel [1985] indicate that approximation (1) is preferable

because it is simple, less expensive, more numerically stable and

at least as accurate as approximations (2) and (3). However, all

approximations to the variance-covariance matrix are subject to

sampling variation because they are computed using the estimated

parameter values. The variance-covariance matrix computed for any

particular nonlinear least squares solution should thus be

regarded as only a rough estimate [Bard, 1974; Donaldson and

Schnabel, 1985]

.

= 1 , . . o

,

NPAR

= 1 , . . .

,

NPAR} ;

—continued

9-13
If IVAPRX = 1 or 4 then approximation (1) is used;

= 2 or 5 then approximation (2) is used; and

= 3 or 6 then approximation (3) is used.

If IVAPRX = 1, 2, or 3, then, when user-supplied analytic

derivatives are available [see argument NLSDRV] , they are used to

compute VCV; if IVAPRX =4, 5, or 6, then only the predicted

values from the model subroutine are used to compute VCV. When

analytic derivatives are available, options 1, 2, or 3, will

generally result in a faster, more accurate computation of VCV.

The default value for IVAPRX is 1. When argument IVAPRX is

outside the range [1, 6], or when IVAPRX is not an argument of the

subroutine CALL statement, then the default value will be used.

IXM --> The exact value of the first dimension of the matrix XM as specified in the calling program.

LDSTAK --> The length of the DOUBLE PRECISION workspace vector DSTAK . LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P = 0.5,

otherwise P = 1.0. [See chapter 1, §B.]

For NLS, NLSC , NLSS, NLSW, NLSWC and NLSWSs

LDSTAK > 27 + max( IS* (N+NPAR) , 30+NPARE} + max { I S • 1 0 • N , 9 4+N • ( 3+NPAR )+( 3 * NPARE2 +3 7 * NPARE ) /2 } •

P

with IS = 1 if default values are used for the derivative step

sizes, and IS = 0 otherwise.

For NLSD, NLSDC , NLSDS, NLSWD, NLSWDC and NLSWDSj

LDSTAK > 45 + NPAR + ( 94+N« (3+NPAR )+( 3 • NPARE2 +35* NPARE) fl ) •

P

For STPLS and STPLSC:

LDSTAK > 27 + (N+NPAR) + 10»N«P

For DCKLS and DCKLSC:

LDSTAK > 14 + NPAR + (N* NPAR+N+NPAR) •

P

M —> The number of independent variables, i.e., the number of columns

of data in XM.

MIT —> The maximum number of iterations allowed. This argument is also

used to compute the maximum number of model subroutine calls,

( 2 * MI T ) . The iterations will stop if either limit is reached,

although, as a rule, the maximum number of iterations will be

reached first. The default value for the maximum number of

iterations is 21. When MIT < 0 or when MIT is not an argument of

the subroutine CALL statement the default value will be used.

9-14
N —> The number of observations.

NETA --> The number of reliable decimal digits in the predicted values (PV)

computed by the user's model subroutine. The default value for

NETA is experimentally determined by the procedure described in

Appendix C. The default value will be used when NETA is not an argument in the subroutine CALL statement, or when the

user-supplied value of NETA is outside the range [1, DIGITS],

where DIGITS is the number of decimal digits carried by the user's

computer for a single precision value when the single precision

version of STARPAC is being used and is the number carried for a double precision value otherwise.

NLSDRV *** The name of the user-supplied subroutine that computes the partial

derivative matrix (Jacobian). This argument must be listed in an EXTERNAL statement in the program which calls the STARPAC

estimation or derivative checking subroutine. The form of the

derivative subroutine argument list and dimensioning statements

must be exactly as shown below, although if there is only one independent variable (M = 1), XM may be declared to be a vector

with dimension IXM.

SUBROUTINE NLSDRV (PAR, NPAR, XM, N, M, IXM, D)

<real> PAR (NPAR) , XM(IXM,M), D(N,NPAR)

< Computations for D(I,J), 1=1, N and J = 1, NPAR >

RETURN

END

NLSMDL *** The name of the user-supplied subroutine that computes the

predicted value of the dependent variable given the independent

variables and the current values of the model parameters. This

argument must be listed in an EXTERNAL statement in the program

which calls the STARPAC estimation, step size selection, and/or

derivative checking subroutines. The form of the model subroutine

argument list and dimensioning statements must be exactly as shown

below, although if there is only one independent variable (M = 1),

XM may be declared to be a vector with dimension IXM.

SUBROUTINE NLSMDL (PAR, NPAR, XM, N, M, IXM, PV)

<real> PAR (NPAR) , XM(IXM,M), PV(N)

< Computations for PV(I), 1=1, ..., N >

RETURN

END

NNZW <— The number of observations with nonzero weights. N.B. This value

is returned by the estimation subroutines.

9-15
NPAR

NPARE

NPRT

-> The number of parameters in the model, including both those held

fixed at their starting values and those which are to be

estimated. — The number of parameters actually estimated, i.e., the number of

zero elements in IFIXED. N.B. This value is returned by the

estimation subroutines.

-> The argument controlling printed output.

For the estimation subroutines:

NPRT is a five-digit integer, in which the value of

digit (counting from left to right) is used to control

section of the output.

the I th

the I th

If the I

1-*1 digit = 0 the output from the section is

suppressed;

= 1 the brief form of the I

c ^ section is given;

> 2 the full form of the 1**^ section is given.

The default value for NPRT is 11112. When NPRT < -1 , or when

NPRT is not an argument in the subroutine CALL statement, the

default value will be used. If the convergence criteria are not

satisfied the subroutine gives a suitable warning and provides a printed report even if NPRT =0. A full discussion of the

printed output is given in §E.2.a and is summarized as follows.

Section 1 lists the starting estimates and control values.

Brief output and full output are the same for this

section.

Section 2 reports the results of the iterations. Brief output

includes information only about the first and last

iteration while full output includes information about

all of the iterations.

Section 3 provides information for each observation based on the

final solution. Brief output includes information for

the first 40 observations while full output provides

the information for all of the data.

Section 4 is a set of four residual plots. Brief output and

full output are the same for this section.

Section 5 is the final summary of the estimated parameters.

Brief output does not include printing the

variance-covariance matrix while full output does.

For the step size selection and derivative checking subroutines:

If NPRT = 0 the printed output is suppressed.

If NPRT ^ 0 the printed output is provided. —continued

9-16
When the acceptance criteria are not met a printed report is

provided even if NPRT = 0.

NROW •—> The row of the independent variable matrix at which the

user-supplied derivative code is to be checked. The default value

is the first row with no independent variables equal to zero; when

all rows have one or more independent variables equal to zero, row one will be used for the default value. When the user-supplied

value is outside the range [1, N] or when NROW is not an argument

of the subroutine CALL statement the default value will be used.

NTAU —•> The agreement tolerance, i.e., the number of digits of agreement

required between the user-supplied derivatives and the derivatives

numerically approximated by the derivative checking subroutine.

The default value is NETA/4. When the user-supplied value of NTAU

is outside the range [1, NETA/2] or when NTAU is not an argument

of the subroutine CALL statement the default value will be used.

PAR — The vector of dimension at least NPAR that contains the parameter

values. For all estimation subroutines it must contain initial

values for the parameters on input and will contain the final

values on return. For the step size and derivative checking

subroutines it must contain the parameter values at which the

operations are to be performed.

PV <— The vector of dimension at least N that contains the predicted

values of the dependent variable at the solution,

a <*. PV (i ) = f^x-pB) = y± for i = 1, N.

RES <— The vector of dimension at least N that contains the residuals at

the solution,

/*> a * RES(i) = y (i ) - f 1 (xi

, 3 ) = y(i) - y(i) = e(i) for i = 1, N,

RSD <— The residual standard deviation at the solution,

* RSD - (RSS(8)/(NNZW-NPARE))

1/2

.

SCALE --> The vector of dimension at least NPAR that contains the scale, or typical size, of each parameter. The vector SCALE is used to

normalize the size of each parameter so that

1 8j£ (j ) / SCALE( j ) | » |8 £ (k)/SCALE(k)| for k = 1, ..., NPAR

and j = 1 , . . .

,

NPAR.

Values of |sCALE(k)| > | 8^ (k )

|

can be used to increase the step

size in cases where the model function is known to be insensitive

to small changes in the value B^C^). —continued

9-17
For the estimation subroutines:

The default values for SCALE are selected by the NL2S0L

algorithm [Dennis et al. 1981a and 1981b] and are updated at

each iteration. When SCALE is not an argument in the subroutine

CALL statement or when the user-supplied value for SCALE(l) <0

the default procedure will be used to select scale values. When

SCALE (1 ) > 0, values of SCALE (k) < 0 for k = 2, NPAR will

be interpreted as an input error. User-supplied scale values

may be either a vector of the typical size of each parameter or

a vector of ones if the typical sizes of the parameters are roughly equal; user-supplied scale values can sometimes result

in reduced computing time since these values are not updated at

each iteration.

For the derivative checking and step size selection subroutines:

The default values of SCALE are defined as:

SCALE(k) = 1.0 if PAR(k) = 0.0 ,} for k = 1, ..., NPAR.

SCALE(k) = j PAR(k) | otherwise

When SCALE is not an argument in the subroutine CALL statement

or when the user-supplied value of |SGALE(k)| < | PAR ( k ) | the

default value for SCALE(k) is used. When SCALE(l) < 0, the

default values will be used for SCALE(k), k = 1, ..., NPAR.

When SCALE (1 ) > 0, values of SCALE (k) <0 for k = 2, ..., NPAR

will be interpreted as an input error.

SDPV <“- The vector of dimension at least N that contains an approximation

to the standard deviation of each predicted value at the

solution,

Ab A SDPV(i) = the i

c ^ diagonal element of [ (D® VCV»

D

T

)]

1 /2

for i = 1, ..., N. This approximation is based on a linearization

of the model in the neighborhood of the solution; the validity of

the approximation depends on the nonlinearity of the model. This

approximation may be extremely inaccurate for a problem with a highly nonlinear model.

SDRES <-- The vector of dimension at least N that contains an approximation

to the standardized residuals at the solution,

SDRES (i ) = RES(i ) /[ ( RSD2 /WT(i ) ) - SDPV(i)2

] 1/2

for i = l, . N, which is the i

t ^1 residual divided by its

individual estimated standard deviation. This approximation is

based on a linearization of the model in the neighborhood of the

solution; the validity of the approximation depends on the

nonlinearity of the model. This approximation may be extremely

inaccurate for a problem with a highly nonlinear model.

9-18
STOPP —

>

The stopping value for the convergence test based on the maximum

scaled relative change in the parameters at the most recent

iteration. The convergence criterion is satisfied if the current

step is a Newton step and

maxf [ Bo 4-] (k)-B^ (k) 1 /SCALE(k) for k - 1, . .., NPAR} gTOPP

max{( | +| B^ (k) | ) /SCALE (k) for k =1, ..., NPAR}

[See Dennis et al. 1981a. J This convergence test is roughly

equivalent to the test based on the maximum relative change in

each parameter as measured by max{ | B^+i (k)-B^ (k) | / | (k) | for k =

1, ..., NPAR} . STOPP is not a scale-dependent value; if its value

is 10”4 then this criteria will be met when the first four digits

of each parameter are the same at two successive iterations

regardless of the size of the parameter values.

The default value is approximately iq“BIGITS/ 2 ^ where DIGITS is

the number of decimal digits carried by the user's computer for a single precision value when the single precision version of

STARPAC is being used and is the number carried for a double

precision value otherwise. When the user-supplied value for STOPP

is outside the interval [0.0, 1.0] or when STOPP is not an argument of the subroutine CALL statement the default value will

be used.

STOPSS —> The stopping value for the convergence test based on the ratio of

the forecasted change in the residual sum of squares, ARSS^+j, to

the current residual sum of squares, RSSCB^). The convergence

criterion is satisfied if certain conditions are met and

ARSS£+1 /RSS(3 £

) < STOPSS.

[See Dennis et al. 1981a. ] This convergence test is roughly

equivalent to the test based on the relative change in the

residual standard deviation between two iterations l and £+1 as measured by (s^ - s£+i)/s £* STOPSS is not a scale-dependent

value; if its value is 10~5 this criteria will be met when the

first five digits of the residual sum of squares are the same at

two successive iterations regardless of the size of the residual

sum of squares.

The default value is approximately the maximum of 10- ^ and

10-2. DIGITS/3, where DIGITS is the number of decimal digits

carried by the user's computer for a single precision value when

the single precision version of STARPAC is being used and is the

number carried for a double precision value otherwise. When the

user-supplied value for STOPSS is outside the interval

[10 S, o.l] or when STOPSS is not an argument of the

subroutine CALL statement the default value will be used.

9-19
STP The vector of dimension at least NPAR that contains the relative

step sizes used to approximate the derivative matrix numerically.

It is input to the estimation subroutines and returned from the

step size selection subroutines. The procedure used to select the

default values is described in §E.l»b. For the estimation

subroutines, when STP is not an argument of the subroutine CALL

statement or when STP(l) < 0 the default values will be used for

all of the step sizes, and when.STP(l) > 0 values of STP(k) < 0

for k = 2, ..., NPAR will be interpreted as an input error.

VCV <—- The matrix of dimension at least NPARE by NPARE that contains the

variance-covariance matrix of the estimated parameters, approximated as designated by argument IVAPRX. The parameters which are held fixed [see argument IFIXED] are not included in the variancecovariance matrix.

The approximation of the variance-covariance matrix is based on a linearization of the model in the neighborhood of the solution;

the validity of the approximation depends on the nonlinearity of

the model. This approximation may be extremely inaccurate for a problem with a highly nonlinear model.

WT --> xhe vector of dimension at least N that contains the weights.

Negative weights are not allowed and the number of nonzero weights

must equal or exceed the number of parameters being estimated. A

zero weight eliminates the corresponding observation from the

analysis, although the residual, the predicted value and the

standard deviation of the predicted value are still computed.

[See Appendix B.]

XM —> The matrix of dimension at least N by M whose j*-*1 column contains

the N values of the j

1-*1 independent variable, j = 1, ..., M.

Y ~-> The vector of dimension at least N that contains the dependent

variable.

E . Computational Methods

E . 1 Algorithms

E.l.a Nonlinear Least Squares Estimation

The nonlinear least squares estimation subroutines use the NL2S0L

software package written by Dennis et al. [1981a and 1981b]. The observations

of the dependent variable, which are measured with error, are iteratively fit

to a nonlinear model by minimizing the sums of squares of the errors as described in §A. The iterations continue until the convergence criteria based on the change in the parameter values or in the residual sum of squares are satisfied [see §D, arguments STOPP and STOPSS], the maximum number of

iterations (or model subroutine calls) is reached [see §D, argument MIT], or the iterations are terminated due to singularity in the model or false

9-20
convergence. All but the first of these stopping conditions may indicate

computational problems and will produce an error report. [See chapter 1,

§D. 5. ]

Singular convergence means that the model contains too many parameters,

at least near the solution, while false convergence can indicate that either

STOPSS or STOPP is set too small for the accuracy to which the model and its

derivatives are being computed or that there- is an error or discontinuity in

the derivative. Users should examine their models to determine and correct

the underlying cause of singular or false convergence.

Iterative procedures for solving nonlinear least squares problems are discussed in Dennis and Schnabel [1983] , Draper and Smith [1981] and Kennedy

and Gentle [1980]. The specific procedure used in STARPAC is as follows. At

iteration £+1 the values of the parameter vector 8^+1 are given by

&£ +1 =

&£ “ ( D

£

T * W,D£ + S£ + A £)~1 * D

£

T* W*££ T

subject to the restriction that

NPAR

{ I [(S*+lOO “ 6 £ (k))/SCALE(k)]2}l/2 < , k=l

the vector of NPAR estimated parameter values from the £

iteration.

D£ is the N by NPAR matrix of the partial derivatives,

D£(i»k) = 9

f

i (x i ,6^ )/38^ (k) for i = 1, ..., N and k = 1, . .

.

,

NPAR.

W is an N by N diagonal matrix of user-supplied weights,

W = diag{ wt-^ » i = 1, ...» N} ,

when a weighted analysis is performed and is the identity matrix

otherwise.

S^ is an approximation to the exact term S^* in the matrix of second

order terms (Hessian) of the Taylor series expansion of the residual

sum of squares function,

N

S

£ *

( j

» k ) = l [e£i ,wt i -(9 2 e £ (i)/90

£ (j)98 4 (k>) ]

, i=l

for j = 1, ..., NPAR and k = 1, ..., NPAR.

is the vector of the N residuals from the previous iteration.

where

$£ is

9-21
6^ is the adaptively chosen diameter of the trust region, i.e., the

region in which the local approximation to the user's model function

is reliable. At each iteration l , 6^ is computed based on information

from the previous iteration. At the first iteration, the initial

value, 6 q, is supplied by argument DELTA which can be used to control

the change in the parameters permitted at the first iteration.

is an NPAR by NPAR diagonal matrix,

A = diagj A^ /SCALE(k) , k = 1, ..., NPAR} ,

where A^ is chosen to approximate the smallest non-negative number

such that the restriction given above on the size of the change in the

parameters is satisfied.

The second order term $£ , which is expensive and difficult to compute

accurately, is important only if it is large compared to the term D£ T*W®D£,

that is, when the residuals are large or the model is highly nonlinear. When

S^* is large compared to D£ T«W®D£, algorithms which ignore it, such as Levenberg-Marquardt or Gauss-Newton, may converge slowly. The NL2S0L

algorithm used by STARPAC, however, adaptively decides when inclusion of this

term is necessary for reliable results and uses an inexpensive approximation

to in those cases.

The matrix, D, of partial derivatives of the model with respect to each

parameter is either computed analytically using a user-supplied subroutine,

NLSDRV , or is numerically approximated using forward difference quotients as described in §E.l.b. When the derivatives are approximated numerically, the

least squares solution, especially the variance-covariance matrix, can be

sensitive to the step sizes used for the approximation. The user may want to

use STARPAC subroutines STPLS or STPLSC to recompute the step sizes at the

solution provided by the estimation subroutines to assure that the step sizes

which were used are still acceptable. If there is a significant change in the

step size the least squares solution should be recomputed with the new step

sizes from the current point. In addition, if the estimation subroutine has

convergence problems the user may want to recompute the step sizes with the

most recent parameter values to see if a change in the curvature of the model,

which will be reflected as a change in the optimum step sizes, is causing the

problem.

Dennis et al. [1981a] provides a detailed description of the algorithm

used in STARPAC. STARPAC also includes the subroutines NL2S0L, NL2SN0, and

NL2ITR, which they reference, and which can be used as documented by them.

[See Dennis et al. 1981b.]

E.l.b Derivative Step Size Selection

The STARPAC step size selection subroutines use an algorithm developed by

Schnabel [1982] to compute optimum step sizes for approximating the partial

derivatives of the model with respect to each parameter. Briefly, the

relative step sizes selected by these subroutines are those which produce

9-22
forward difference quotient approximations to the derivative, D^, that agree

reasonably well with the central difference quotient approximations, Dccj» The

central difference quotient approximations are twice as accurate but also

twice as expensive to compute. Since the additional accuracy is not usually

needed, central difference quotient approximations are not used by the

estimation subroutines.

The number of reliable digits in these derivatives is a function of the

step sizes used to compute them. Given properly chosen step sizes, the number

of reliable digits in Dfd and Dcd will be approximately n /2 and n,

respectively, where q is the number of reliable digits in the predicted

values, PV, from the user's model subroutine. For example, if the predicted

values are computed using an iterative procedure (such as quadrature or a solution of partial differential equations) which is expected to provide five

good digits, then q would be five; if the predicted values are calculated from

a simple algebraic expression translated directly into Fortran code, then q would (usually) be the number of decimal digits carried by the user's computer

for the results.

The relative step size for 8(k), k = 1, NPAR, is initially

STP(k) = 2 (10"NETA

/y)

1/2

for k = 1, NPAR,

where

Y is the average curvature (estimated by STARPAC) of the model with

respect to 8 (k)

.

The forward difference quotient approximations with respect to 8(k),

k = 1 ,. . .

,

NPAR are then

f 1 (x i ,0

k

) - f

i (x i ,$)

Df (j(i,k) = for i = 1, ..., N,

STP(k)« SCALE (k)» SIGN(g (k)

)

where

is the function which models the i*-*

1 observation.

is the vector of the values of the M independent variables at the i tk

observation.

8 is the vector of the NPAR parameter values.

8

k is a vector which has the same values as 8 except that the k^1 parameter is equal to

8 (k) + ( STP(k)» SCALE (k)» SIGN(8 (k) ))

.

SIGN is a function which returns the sign of its argument.

9-23
The central difference approximations to the model derivative with

respect to B(k), k = 1, NPAR, are

f i( x i,B

+k

) - f^x^S-1*)

D

C(J (i,k) = for i = 1, ..., N,

3

1 / 3 . 10~NETA/ 3 .SCALE(k)*SIGN(B(k))

where

B +k is a vector which has the same values as B except that the k

tE

parameter is equal to

B (k) + (3 1/3 « 10_NETA/ 3 .SCALE(k)«SIGN(B(k))) .

B is a vector which has the same values as B except that the k

tn

parameter is equal to

B (k) -

( 3

1 / 3

« 10"NETA/ 3 .SCALE(k)*SIGN(B(k)))

.

The relative step size is considered acceptable if, for at least N-a

observations

,

|D fd (i,k) - Dcd (i,k)| < min( 10“NETA/^

s 10" 2

} for i = 1, . N,

where a is the number of observations exempted from meeting the above

acceptance criterion. [See §D, argument EXMPT.] If the step size is not

acceptable, it is adjusted by factors of 10 until the condition is met or until no further decrease in the number of failures can be made, although in no case will the selected relative step size be greater than 1.0 or less than

10“NETA

Note that the step size selection subroutines will return the selected

step sizes even when the number of failures exceeds the allowed value; this

condition will be noted by the value of IERR. The detailed printed output

should always be examined for problems discovered by the step size selection

subroutines.

E.l.c Derivative Checking

The STARPAC derivative checking subroutines use an algorithm developed by

Schnabel [1982] to determine the validity of the user-supplied derivative

subroutine. The user-supplied derivative subroutine is considered correct for

a given row i, i = 1, ..., N, and coefficient B (k), k = 1, ..., NPAR, if

|D fd (i,k) - D(i , k) | < 10“T

| D (i,k)|

where

D is the derivative computed by the user’s subroutine.

9-24
Df^ is the forward difference quotient approximation to the derivative

described in §E.l.b.

x is the agreement tolerance, i.e. , number of digits of agreement

required between D and Df^, which must be less than or equal to the

number of good digits in Df^. [See §D, argument NTAU.

]

When the agreement tolerance is not satisfied the checking subroutine

attempts to determine whether the disagreement is due to an error in the

user's code or is due to the inaccuracy of the difference quotient approximation, caused either by high curvature in the user's model or by significant

roundoff error.

The derivative checking subroutines each check only one row of the

derivative matrix. The user should examine the row at which the derivatives

were checked to ensure that some relation between the parameters and

independent variables, such as a zero-valued independent variable or a factor

(x^ “ 8(k)) when x^ = 8(k), is not hiding the effect of an incorrectly

computed derivative. Checking only one row is appropriate since the same code

is frequently used to compute the model function and derivatives at each row

1 = 1, . . . , N, as is the case in the examples shown in §F. If the code used

to express the model function and derivatives is not the same for each row,

then each distinct section of the code should be checked by making multiple

calls to DCKLSC with argument NROW set to a row within each section.

E . 2 Computed Results and Printed Output

E.2.a The Nonlinear Least Squares Estimation Subroutines

The argument controlling the printed output, NPRT, is discussed in §D.

The output from the nonlinear least squares estimation subroutines

consists of five sections, several of which include tables summarizing the

results. In the following descriptions the actual table headings are given by

the underlined, uppercase phrases. Results which correspond to input or returned subroutine CALL statement arguments are identified by the argument

name in uppercase (not underlined).

Section 1 provides a summary of the initial estimates and control values. It

lists the following information.

• The initial values of the parameters, PAR, and whether they are to be

held fixed or not, IFIXED.

• The scale values, SCALE.

• Either the step sizes used to approximate the derivatives numerically,

or, when user-supplied (analytic) derivatives are used, the results of

the checking procedure; and the control values used in these computations as applicable. [See §E.l.b and §E.l.c.]

9-25
• The number of observations, N.

• The number of observations with nonzero weights, NNZW.

• The number of independent variables, M.

• The maximum number of iterations allowed, MIT.

o The maximum number of model subroutine calls allowed.

• The two convergence criteria, STOPSS and STOPP.

• The maximum change in the parameters allowed at the first iteration,

DELTA.

• The residual sum of squares computed using the starting parameter

values.

• The residual standard deviation, RSD, computed using the starting

parameter values.

Section 2 lists selected information about each iteration and includes the

reason the iterations were terminated. The information provided for

each iteration includes the following.

• The iteration number.

• MODEL CALLS : the total number of times since execution began that the

user’s model subroutine has been called, not including calls required

to approximate the derivatives numerically.

® RSD ; the residual standard deviation computed using the parameter

values from the current iteration.

• RSS : the residual sum of squares computed using the parameter values

from the current iteration.

• REL CHNG RSS : the relative change in the residual sum of squares

caused by the current iteration.

• FORECASTED REL CHNG RSS : the forecasted relative change in the

residual sum of squares at the current iteration, and whether this

value was checked against STOPSS ( CHKD = Y) or not ( CHKD = N).

• REL CHNG PAR : the maximum scaled relative change in the parameters at

the current iteration, and whether this value was checked against

STOPP ( CHKD = Y) or not ( CHKD = N).

• CURRENT PARAMETER VALUES : the estimated parameter values resulting

from the current iteration.

9-26
Section 3 provides the following information for each observation, i = 1,

N, based on the final solution.

• ROW the row number of the observations.

• PREDICTOR VALUES : the values for up to the first three columns of the

independent variable matrix, XM, not including the first column if it

is constant.

• DEPENDENT VARIABLE : the values of the dependent variable, Y.

• PREDICTED VALUE : the estimated predicted values, PV, from the fit.

• STD DEV OF PREP VALUE : the standard deviations of the predicted

values, SDPV.

• RESIDUAL : the error estimates, RES.

• STD RES : the standardized residuals, SDRES.

® WEIGHT ; the user-supplied weights, WT, printed only when weighted

analysis is performed.

Section 4 displays the following plots of the standardized residuals.

• The standardized residuals versus row numbers.

• The standardized residuals versus predicted values.

• The autocorrelation function of the (non-standardized) residuals.

• The normal probability plot of the standardized residuals.

Section 5 summarizes the following information about the final parameter

estimates and their variances.

• The variance-covariance matrix, VCV, of the estimated (unfixed)

parameters, and the corresponding correlation matrix,

r jk = VCV(j,k)/(VCV(j,j) VCV(k,k))

1/2

f or ,j = 1 , ..., NPARE

and k = 1, ..., NPARE.

• PARAMETER : the final value of each parameter, PAR(k), k = 1, ..., NPAR.

• SD OF PAR : the standard deviation of each estimated parameter,

( VCV(k,k)) 1/2 for k = 1, ..., NPAR.

• RATIO : the ratio of each estimated parameter to its standard

deviation,

RATI Ok = PAR(k)/(VCV(k,k)) 1/2 for k = 1, ..., NPAR.

9-27
• APPROXIMATE 95-PERCENT CONFIDENCE LIMITS : the lower and upper

95-percent confidence limits for each parameter, computed using the

appropriate value of the Student's t distribution with NNZW-NPARE

degrees of freedom.

o the residual sum of squares, RSS(B).

• the residual standard deviation at the solution, RSD.

o the residual degrees of freedom, NNZW-NPARE.

® an approximation to the condition number of the derivative matrix, D

(the Jacobian), under the assumption that the absolute error in each

column of D is roughly equal. The approximation will be meaningless

if this assumption is not valid; otherwise it will usually

underestimate the actual condition number by a factor of from 2 to 10.

[See Dongarra et al. 1979, p. 9.5.]

NOTE ; The standard deviation of the predicted values, the standardized

residuals, the variance-covariance matrix, the standard deviations of the

parameters and the 95-percent confidence limits on the parameters are all

based on a linear approximation to the model in a neighborhood of the

solution; the validity of this approximation depends on the nonlinearity of

the model. The statistics based on this approximation may be extremely

inaccurate for a problem with a highly nonlinear model.

E.2.b The Derivative Step Size Selection Subroutines

The argument controlling the printed output, NPRT, is discussed in §D.

The output from the step size selection subroutines consists of a summary

of the input and control values and, for each parameter, the selected relative

step size, the number of observations at which this step size failed the step

size selection criteria and the row numbers at which the failures occurred.

E . 2 . c The Derivative Checking Subroutines

The argument controlling the printed output, NPRT, is discussed in §D.

The output for the derivative checking subroutines consists of a summary

of the input and control values and the results of the derivative checking

test with respect to each of the model parameters, 6(k), k = 1, ..., NPAR.

The possible test results are:

OK -

® The user-supplied derivative and the numerical derivative agree to the

required number of digits.
QUESTIONABLE -

o The user-supplied derivative and the approximated derivative agree to

the required number of digits but both are equal to zero. The user

should recheck the derivative at another row.

o The user-supplied derivative and the approximated derivative do not

agree to the required number of digits but the user-supplied derivative is identically zero and the approximated derivative is nearly

zero. The user should recheck the derivative at another row.

© The user-supplied derivative and the approximated derivative disagree

but the user-supplied derivative is identically zero. The user should

recheck the derivative at another row.

® The user-supplied derivative and the approximated derivative disagree

but the validity of the approximated derivative is questionable

because either the ratio of the relative curvature of the model to the

slope of the model is too high or SCALE(k) is wrong.

• The user-supplied derivative and the approximated derivative disagree

but the validity of the estimated derivative is questionable because

the ratio of the relative curvature of the model to the slope of the

model is too high.

• The user-supplied derivative and the approximated derivative disagree,

and there is no reason to question the accuracy of the approximated

derivative.

The sample programs of this section use the model and data given in

example one, pages 428 to 441 of Daniel and Wood [1980]; the model is

Nonlinear Least Squares Estimation . In the example program of figure

F-la, NLS is used to compute the least squares solution using numerically

approximated derivatives; figures F-lb through F-lf show the output from NLS.

In the example program of figures F-2a and F-2b, NLSD is used to compute

the least squares solution given analytic derivatives; figures F-2c through

F-2g show the output from NLSD.

Derivative Step Size Selection . In the example program of figure F-3a,

STPLS is used to compute the optimum step sizes for numerically approximating

the derivatives with respect to each of the parameters, 0(k), k = 1, 2.

Figure F-3b shows the output from STPLS.

INCORRECT -

F

f-[(x£,0) - 0 ( 1

) »x^( 1 (2) f or i = i N

9-29
Derivative Checking . In the example program of figures F-4a and F-4b,

DCKLS is used to check the validity of a user-supplied, derivative subroutine.

In figure F-4b, the derivative subroutine has been intentionally coded

incorrectly in order to display the report obtained when the derivative

checking subroutine determines the derivatives are incorrect, and the starting

parameter values have been chosen in order to display the report obtained when

the test results are questionable. Figure F-4c shows the output from DCKLS.

9-30
Nonlinear Least Squares Estimation

With Numerically Approximated Derivatives

MAIN PROGRAM!

MODEL SUBROUTINE

«

PROGRAM EXANPl

C

C DEMONSTRATE NLS USING SINGLE PRECISION VERSION OF STARPaC

C RUN ON CYBER 180/8*0.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE6 ON CYRIRS)

C CSEE CHAPTER 1 * SECTION D.4J

CC N.B. DECLARATION OF Y* XM* PAR AND RES MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USEO.

C REAL Y ( 10 ) * XM ( 10* 9 ) * PAR ( 5 ) * RES(IO) DOUBLE PRECISION DSTAM200)

C EXTERNAL NLSMDL

C COMMON /CSTAK/ DSTAK

CC SPECIFY NECESSARY DIMENSIONS

C LOST AM 200

IXM « 10

C

C READ NUMBER OF PARAMETERS

C STARTING VALUES FOR PARAMETERS

C NUMBER OF OBSERVATIONS AND NUMBER OF INDEPENDENT VARIABLES

C INDEPENDENT AND DEPENDENT VARIABLES

C READ 100* NPAR READ 101* ( P AR ( I ) * I»1,NPAR»

READ 100* N* H READ 101# ( (XM(I*J8» I-1#N>» J-lsMI* (YCII* I«1*N»

C

C PRINT TITLE AND CALL NLS TO PERFORM NONLINEAR REGRESSION

C KITH NUMERICALLY APPROXIMATED DERIVATIVES

C WRITE (6, 102 J CALL NLS <T* XM# N» M* IXM# NLSMDL* PAR* NPAR* RES# LDSTAKJ

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT <2198

101 FORMAT (6F6.38

102 FORMAT P1RESULTS OF STARPAC'*

* « NONLINEAR LEAST SOUARES SUBROUTINE NLS»)

END SUBROUTINE NLSMDL (PAR, NPAR# XM* N« M, IXM* PV8

C

C SUBROUTINE TO COMPUTE PREDICTED VALUES OF DEPENDENT VARIABLE

C

C N.B. DECLARATION OF PAR* XM AND PV MUST BE CHAN6ED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL P AR ( NP AR 8 » XM(XXN,M8» PV(N8

C DO 10 I - 1* N PVU) - PAR(l) * XM ( I * 1) ** PAR(28

10 CONTINUE

C RETURN

END

2 0.729 4.000

6 1 1.309 1.471

2.138 3.421

1.490 1.969 1.611

3.997 4.340 4.882

1.680

9.660

Figure F-la

Example program using NLS

9-31
RESULTS

OF

STARPAC

NONLINEAR

LEAST

SQUARES

SUBROUTINE

NIS

STARPAC ’.

OJS »

NONLINEAR

LEAST

SQUARES

ESTIMATION

WITH

NUNERICALLV

APPRO*

INATE D

DERIVATIVES «

***### ##** **************

«#*A

***«*#*

A#«A

#*##******####**##•******#***

**AA«

© IA, Z 9=> ^ © ©i e

is*a

*Sl &

a= o O *=«A 4/t «*>

<£©

© z k«

ISt

X (MI < © 05 <

fit, Of (A) 8W & fi

<tt

©©e e «v© «r\ ® ^ « Ctt © ®

©

w

v*

a

&= tTM

«=J =5 3 3 © O © © © o o o © ©

«sa

is* ©* •

c->

©

=s 4M < IS ^ ©

Ur,

«/* <« Z© ey=s *< Z

»->

©

</* (A/ ® K © &U

X <* * z ©

•« z

<« ui X © u z< tu X >

at

x

O •*

M.

©

cla z z

«*

©

x to x UJ z a

9-32

RESIDUAL

STANDARD

DEVIATION

FOR

INPUT

PARAMETER

VALUES

IRSDI

„6067E-0i
o

UJ©8oo

'VJ o©©u

a s > < xXu s*8 X O X 8 u ui tu © ©

<si ^

UJ •* « » •-*

«/»

tf

Q > < *

a.

X

O ^ X © x e uww© m j =j w

tu ^ <r

Q£ » (NS

U

OfU4 o

4«

© »=

© ^ X

t~

W

O

<a

X

vj

X

kU (J U4

QC 3 ^ C a! a^ O

(A,

W < f*3

fit

F6*

<J«

© >» OVIK

Uft Z

l»

u

(A tf> « X ««* W 8 U9UUUIW

ae 3 •* O tJ «J ^ y iv <t (V

as » me i fa

0)

tf3

&C

°H

fa

m

iin i ^0 oII•I OL 8 M.' I 0 I Z 0 3 I x u.; U4 => o _J

_J 4/0 «SJ u.1 _J O —4 o «<

(SJ U4HK

—i *»

•jw -j c _J o <

9-33

Example

of

NLS

output

(continued)
RE

SUITS

FROM

1EAST

SQUARES

FIT

in

<x>

m ^ o o

«r <\i <\l 35 I fvi . fVJ • o o o o o o 1(11(1 Ui UJ UJ UJ U» U£ <H # O N ^ a m fi fn o j> ^ CO ** ® ^ «# ^ o n -o r»® ® cr m

*> en

m ^ oo £ 93 N W <0 O

ff*5 O* ^5 9** e r » <€ uj » © 0 o © o © © 1 e i i i e UJ UJ ID tafc) W) ULI 9D ^ CD ftJ c-0 e°4 fSJ o m as h N

O’

O tn fV 9*5

K -fl

H -flo<® o # <fi e vt h

«v» «f «>«<© ^ ^ «pcj *=S es*J 5=® 5^

ffe «#

© e=4 <£

»-< r* <#

O «*» ff4H# ^flV ®

<f> r* «T «V <0 ^ **© ® «n «* ©

<# sx avi

® 0 O « O C ® ® <« w ^ tf

X «=J UJ ® © **. X «

ua®

G= <as uy

©06000 o o o © @ © © o o o © o eoo oo o ® eX © CVS ©

i*a «\* o ® 0

** 'G & m e <& © ® © © ^1 «*5 «« 0> I fe

cup3

be

(•= C-4 3! BB88888888 ©

©©

©

©©

©

© o o e o © © © © © © © © © o © o © •* © g*fc V* © © f*> o* 0 fl-< ©

iw «r 0 «\ 0 0 8 ft C A 88888I(Ie98 3i cvi w> os* et 0 8 © 8 ft 8

9-34

Example

of

NLS

output

(continued)
if

til n

UJ

<r 4 1 c 8 1 8 8 1 4 1 8 1 4 8 1 1 8 4 | 1 1 1 4- | 8 r 4 fi 1 fi 4 1 1 1 4 | *0 14 1 fi 0 8 4 X 4 # 4 4 OH

UJ 1 8 1 O 1 8 8 1 -UJ 1 l r* 1 fi O 1 I o » 1 1 8 xC 1 1 1 1 1 ° 1 1 1 fi OH 1 fi tn 1 1 8 1 O 1 1 1 1 4 4 4 • 1 1 in f 1 1 * 0 UJ fi t 1 1 « 8 8 O wy 1 8 8 1 1 1 © 0 fi Q. oJ 1 1 M> | 1 CE < fi fi Vt 0 fi 4L > 0 t 1 § i I u» 6 & 8 t/? © 4 O 4 4

UJ 8 8 8 fi >=> 1 8 » 8 1 o 1 1 Q 8 * fi C=q 1 fi 6ft mJ 1 fi o 4 4= m A. 4 4 ©

UJ 1 1 & 0 & 8 6 * >“ 1 0 ©

a. 6 1 <m •— 8 1 8 1 8 «/* «> 4 ~J 4 4 e > 8 8 « fi UJ 8 # 8 ffi e 1

fi 1 <* 8 fi 2 lb 1 8 fi 1 8 too or. 1 e O 0 fi (*=' 8 i S 8 8 2 Q 8 8 A 1 4 1 © (=> 0 8 0 1 u 4A 8 fi —8 0 fi 4 4 «€ 4

Ck 1 1 Z « fi 4/t • 8 « 8 1 4*9 1 fi O 6 1 » 1 1 Z 8 1 8«5 8 fi 1 1 »- 8 8 1 fi 8 1 1 0 8 8 1 fi *>« 8 1 * 1 fi or * 4 T*> 4

UJ * 8 8 *•01 8 8 0 8 0 8 fi 1 1 8 fi 6 0 *x 4 8 B fi 4 8 fi 8 4 6 6 B 4 fi 8 8 8 4 8 8 e a 4 «h o OH oh n OH OH 0% e oh ot oh OH OH OH •

C“=

N <M ^ fM r- CVJ CM ^ CM

© « • • • • • • e « e • • 8 wu m CM 8 CM CM 9 CM m 1 § 1 a <*zX 4 § B 0 0 <*> e 1 8 8 8 8 4 1 8 114 0 8 0 1 O 4 8 fi fi 4 fl 8 8 4 8 § 8 4 g 8 8 § 4 fi 0 8 8 4 © c 4 4 © 4 ©

H* ilO 4 I0) po

bC

°H Ii8I8I «« « J 0 41 4 3 8 Q ( ** I l/» 0 UJ 8 ssr 00 u» e o o x t O 8 •-* 0 H> |

II I • B 9 I I I I I I I 9 I I fi I I I 4 *4 | I • 4 I I I I I r-5 O I Q I 4 | I | I i

9-35

Example

of

NLS

output

(continued)
APPROXIMATION

BASED

ON

ASSUMPTION

THAT

RESIDUALS

ARE

SHALL

x\

CDryCjft©2

t*= ft &

e=* ft »*J <«9 2 Ob •"$ *M

e«J ft CM

© *

ftft

Of<

ft. o

ft) »

645 <U

ft) 2

N> ft* * © 2 «

ft ^ ft <C £ M

ft) s

t#© 0" ©

ob3 © ® ® o© s£ IW 0s C* © © 8*>

9>0 ^

U-l

*“4I Pc-i

0)

J-J D

be

-H

(ft

© efi 9=

C-0 ©

ftX

»-

m cv © ©

«-5 9 0 9 «€ O ft) ft) 2 =S © ^ O U) ^ 4*6 «& ® «*l <© <« oS <* tft <« * ft «M ® ^ © X ft m <® O «* ^ «M

ft <fc© CO X * 8 »* w > © Z

ft) UJ » ft e=c D ly <n A »> *-« © oC ft 0 ft © ft (S^8

Q1 ft © © H * ft) © m r** ft ^

«* * 2 # ©

ft

© ««©

© *« #-* cn ^ X ft *-» e • <« O <? 9 ^ Z ~)

ft * ft < im a » a- * o-*o o » © 0 8 0 OOG 8 ft S « I * I 3 I O j 4^> |6 *» 8 «A 8 * 9 ft 6 ft 88 S 8 O 8 ft 8 ft 6 © « m t*o @i© = o © * CM *

ft P*»

(A=0 0=0 © ©6 8 ft ft

ft

© «** * ©

ft (f% 0=3 <©

ft® CM

O <M

«M©8 ft©

«*v

^=<

«*V ©

©9 ft

(P=5 -# F*C e=$ <£> C*v *> «\ fr*» C ® N i •

1*1

©

© <SM CM 8 ©

© 2 m

c« • ® © <© ev

cm

©

© *e e © ® © © ©

P*> e © fSfc

© ftO ©* © 8— ft m ©X * Q O© ©

N-3 ft

«« tn

9-36

Example

of

NLS

output

(continued)
Nonlinear Least Squares Estimation

With User-Supplied Analytic Derivatives

MAIN PROGRAM

MODEL SUBROUTINE*

PROGRAM E X AM PL

C

C DEMONSTRATE NLSD USING SINGLE PRECISION VERSION OF STARPAC

C RUN ON CYRER 180/840.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EOUATED TO FILE TAPE6 ON CY8ERS)

C ISEE CHAPTER 1* SECTION D.4J

C

C N.B. DECLARATION OF Y» XM, PAR AND RES MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USEO.

C REAL Y ( 10 ) , XM ( 10* 5 ) » PAR(5I, RES(IO)

DOUBLE PRECISION 0STAM200)

C EXTERNAL NLSMDL* NL SDR V

C COMMON /CSTAK/ DSTAK

c

C SPECIFY NECESSARY DIMENSIONS

C LDSTAK - 200

IXM * 10

C

C READ NUMBER OF PARAMETERS

C STARTING VALUES FOR PARAMETERS

C NUMBER OF OBSERVATIONS AND NUMBER OF INDEPENDENT VARIABLES

C INDEPENDENT AND DEPENDENT VARIABLES

C READ 100* NPAR

RE AO 101* ( PAR ( I ) » I" 1* NPAR

)

READ 100* N, M READ 101* UXN«I»J)» I-1,N), J •! » M 1 * C Y( I J » I-1,N)

C

C PRINT TITLE ANO CALL NLSD TO PERFORM NONLINEAR REGRESSION

C WITH USER-SUPPLIED DERIVATIVES

C UR ITE (6* 102

}

CALL NLSD (Y, XN, N* M» IXM* NLSMDL* NLSORV* PAR* NPAR* RES*

* LOSTAtO

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (215 } 101 FORMAT (6F6.3)

102 FORMAT C1RESULTS OF STARPAC*

« * NONLINEAR LEAST SQUARES SUBROUTINE NLSD*)

END SUBROUTINE NLSMDL (PAR* NPAR* XN* N* M* IXM* PV>

C

C SUBROUTINE TO COMPUTE PREDICTED VALUES OF DEPENDENT VARIABLE

C

C N.B. DECLARATION OF PAR* XM AND PV MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USEO.

C REAL PAR(NPAR)* XM(IXN*M), PV(N)

C DO 10 I - 1* N PV(I) • P AR ( 1 ) * XM ( I * 1) * P AR ( 2 ) 10 CONTINUE

C RETURN

END

Figure F-2a

Example program using NLSD
DERIVATIVE SUBROUT INE 6 SUBROUTINE NLSBBV IPAR* NBAS* XN C N» N» IXHt 08

C

C SUBROUTINE TQ CONFUTE THE PARTIAL DERIVATIVE ( JACOBI AN i NATRIX

C

C Mel. DECLARATION OF BAR* IN AND 0 MUST BE CHANCED TO DOUBLE PRECISION

C IF DOUBLE BRECISION VERSION OF SYARBAC IS USED.

C REAL BAR(NPAR)# XNiIXN#H|» DtN»NPAR>

C DO 10 I > I* N DU»1S « XM*I»1» *» BARI2I

DU«I> * BARU» * XNU»1) •* BAR (21 ALOCCXNI 1*11 » 10 CONTINUE

C RETURN

END

DATA! £ 0.723 A. 000

0 1 1.309 1.471 1.490 1.369 1.611 1.660

2.136 3.421 3.397 4.340 4.682 3.660

Figure F-2b

Example program using NLSD (continued)
Example

of

NLSD

output
flO

©

I

u

(X,

•» * * ©

y I o^? m %*9

m G *>

<m sr

<&, z

XJ>

<i£> ffe S 9 yiuw

frr^ rr~J\ S^f w<e « » ^4

xo

u

«A0

©»

<jS

6

m

m

Md

svtx

^> 4a»

VE> «£ « s

(UU «M

« » ^©

M

W ®

Z 8 * I -5 ** O 0 ** ^ *o • © N I 04

2 I*«

»

M {

U0 G ^ © <=* Z X <

1*9 « »

SU

GW* M OSS

<&> «& *1

<*l m w

<u> x e

« ^ «

c C

I '1

e

K • S »

•* I m •

© -J o •* K «J

W>

o

T5 CM

I E*<0) tl3

60 H

Uc

9"40

Example

of

NLSD

output

(continued)
«1 u

Uio8 V o M

® ^ o

(«= ui # NN«

vts • ••••• 0 e o o o o 1 i t i i i (Al Ui Ul Ui Ui Ui ^ «•* m ® m & +

<m ^ o o » 0* <© *+ © + om 0 m

VI #0 0 ^ ® m 0 0 N m 0 0

oc

H

K 0 ® ^ H ^ © © © © © © 8 6 8 9 6 6 Ui tkUi UitU 10

t&> Utf # ^ ©3 *>« 04 •<*-• *M ^ «•• ® **> 0* ^ ^ ^ « tfk w w

IU 4 H* © © ** ^ © 0* 0* © 03 »© <ss> <# <© s© 3 Ui ^ »>< »4N ® ® © •

V» i ( ©© 0 9

9401^ #0

A o4 ^ >C ® •

«# ^ 08 0^ ©

fte H« 00

®

oN 00 ««I 0 0 © © © © © ® 04 «0 « «# ® 0*

oeoo o o o o o o o o © oo © ® ©

©

©

©©N

O

®

©

© 0 © © ® o © • 04 «0 <# ^ ®* 0) CMi fe©

W!3

bO

eH

II

SI

si o oo o o o o oo o o o o o o o o o o oo o o o

9> HO 0 H

O

O f-o 0*40

0®

H HH HHH

9-41

Example

of

NLSD

output

(continued)
9

i i ii + ttii + titi+efit + ffttt*

i

« 0898 + 68l8*fi8l6*§§89 + B 16 8*

0 0 8 8 8 I • I m

8 8 8 8*888 8 * %

tit as•w

8

8 8

I

8 <&

I 4

I •

I m

8

I

86

8

8

8

I

8*

0II

8 m

m

8 9>

8 ©

I *a

I*

© 0 *> 8

9•

ife 8 © *

« 9 *4 *

8

I

8 4* fte ® m4

*t «

CN

I fea

w>s>

8 6 8 6 * 8 Cl8 I

flfc

0 8 * 08 8*9 6 9l+e\

K <c

• 8

fc©

C«Z(M

+ 6 6 88 + 8 If 8 + 1 188*088 0*8888 + •

8

8

8

6

I

9

0+

6

0

8

6

I <2 6 m 8 m 9 C I S>X 8 © 8 m

©©

8 8 8 6 +

«*

0 * e 6 «

M)

8

+ ©+ • *8e88*8««e + iee6 + 8669 + o e i » ©

i .

0 8 0 8 + « ©

«i 9 <«© 8

I w 8 06 8 m 8 •Iit. i e I* s i e

*»u« •• X < t « 3 * •

2

•6 »* |

|

X * © t

act | m e c l © 9* © « SI

! o

4 t S I t « I I t I » • t I t • •

9*=42

Example

of

NLSD

output

(continued)
ii««3] 8m©o

<SJ

VI

©©© MttS 94 *>4

4^J 0 a 8 ue 8 t~ 0 iv 0

«4

O

©

©

©

94© © * ® ©

X

© 0 ag 94 0 © —> 8 © X © 0 © 9*

© ^ © o Ui 0 © X UI m o u © 0 IV X m ©

9* 0 © o © ^

•> IV 0 © mA 94

©

vi Z 0 UI

© 94

m© 0 © 94 f*>

X

— 0 ff*= °

90 0 © o m © © © IV X X 9» VD

90 <3 © X IV

tv « © o

«A o IV

wG© *» #u 90

UI oi -J 94 o ©©

© 9- UI © © 9= • • • 0 X X © M © IV IV © ^ 1 o © © © >4 © 94

© me

© 9* I* o 94 o © u» V) © M #* © VO o IV 90 © 1 © © 94 94 94 © © © VO 0 © © f» *0 ft •

(U IV t- IV 9 0 ©

m o (A o © X IV IV • e <*> fU s *4 X 9* ©) IV © © 94 © 9» © o © K 90 X X 0 e © © ©

9>

©

X©

© IV IV 94

© 0 M X o X O CVS © © <v X 9-0 UI © O © X K It © © « © 94 X o © © -I <r © © 94 © o *4 X *4 © IV V © K 9 © e • 9- 9» 3 © X © © © 9- 0 © V* o © © M 94 | © -4 VS Ui © • • u 9 X Ui © X © VI 9 9 M © 9- 9- K v» • © © z © X IV l X X IV

Ul o O UI UI

© 0 o o ©

uc

uX UI 9-© 0 90

OX

O

OX o » © I ©

O

© 9 Ui

(A o Ui

© I- 94

O

O 0 UI

N VI VI

© UiX Ui z VI © IV 9 Vt> 1 9- M O Ui 9* © © © © x © IV 1 IV © © © X IV X •4 © IV O UI © O K 0 K © O © Ui o

IV

© o O 94 VI 1 ©©©©O IV 94 o u X © Ui u © K © 0 © © © O o 9-

VO z o © «M

N Ui • © 9* • VI o 94

© 9* v»

©

X 94©

© -J 0 • • ©

© VI o 9" 94 1 1- UI o © O 0 u © Ui X

VO

©

© o VI 94

©

©X 0 o O Ui o © © ! * * Ui 1- • • O 1 X © u Ui X 0 9- M u © 0 © ! O X © © o • M 9- Z -8 u 1 Ui O o © 9- UI UI u 0 O © © Ui X X X VI M O f- © 0 0 © © 9- m VI 1 90 © © Ui 0 © > © © Ui 0 u -i X X

Ui

u 9 ©

O

©

O 9- 1 ©© o 94

XX • 9 «J > u z 94 «*)

© 0 ©

©

M

9-1

© • K

X 1 X o o o o

-J 99 1 I • 1 0 © 9- | Ui 9— 9- Ui©

X

© I —«

9- 9 O 94

N VI VI VI

©

O

© | O VI 0 X •v Ui

©

©

X > 1 u Ui 1 9*

m

©

©©

be CNI fa&

5>

•H

fc

9-43

Example

of

NLSD

output

(continued)
Derivative Step Size Selection

NAIM PROGRAM I PROGRAM EXANPL

C

C DEMONSTRATE STPLS USING SINGLE PRECISION VERSION OF STARPAC

C RUN ON CYBER 100/040.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE6 ON CYBERSt

C (SEE CHAPTER 1# SECTION 0.4)

C

C N.B. DECLARATION OF XM* PAR AND STP MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL IN(10*5>* PARIS) * STPISS DOUBLE PRECISION DSTAM200)

C EXTERNAL NLSNOL* DERI

V

C COMMON /CSTAK/ OSTAK

C

C SPECIFY NECESSARV DIMENSIONS

C LOST AK • 200

IXN • 10

C

C READ NUMBER OF PARAMETERS

C STARTING VALUES FOR PARAMETERS

C NUMBER OF OBSERVATIONS AND NUMBER OF INDEPENDENT VARIABLES

C INDEPENDENT VARIABLES

C READ 160* NPAR READ 101* (PAR (II# I*1*NPARI READ 100* N* M READ 101* I (XN(I»J)» I»1*N)# J«1*NI

CC PRINT TITLE AND CALL STPLS TO SELECT STEP SUES FOR

C APPROXIMATING DERIVATIVES

C WRITE (0* 102) CALL STPLS (XM* N* H* IXN* NLSNOL* PAR* NPAR* IDSTAK* STP)

C STOP

C

C FORMAT STATEMENTS

C 100 FQRNAY (215)

1@1 FORMAT (6F6.3)

102 FORMAT CIRESULTS OF STARPAC”*

« « DERIVATIVE STEP SUE SELECTION SUBROUTINE STPLS”)

ENO MODEL SUBROUTINE!

C

CC

C

CC

C

c

SUBROUTINE NLSNOL (PAR* NPAR* XM* M* N* IXN* PV)

SUBROUTINE TO CONPUTE PREDICTED VALUES OF DEPENDENT VARIABLE

N.B. DECLARATION OF PAR* XN AND PV NUST BE CHANGED TO DOUBLE PRECISION

IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

RIAL PAR (NPAR ) * XH(IXN*N)» PV(N)

DO 10 I • l* N PV(1) * PAR(l) 4 XM ( I * 1) *4 PAR ( 2

)

16 CONTINUE

RETURN

END

DATA* 2 6.72S 4.006

6 1 le36« 1.471 1.406 1.S6S 1.011 1.606

Figure F~3a

Example program using STPLS

9-44
m

m

9-45

Example

of

STPLS

output
Derivative Checking

MAIN PROCRANl

CC

Cc

c

c

c

c

c

c

c

€

C

c

e

ce

c

tc

e

e

€

PROCRAM EXAMPL DEMONSTRATE DCKLS USINC SINCE! PRECISION VERSION OF STARPAC

RUN ON CYBER 1B0/640.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE6 ON CYBERS)

CSEE CHAPTER 1* SECTION 0.4]

N*B. DECLARATION OF XN AND PAR MUST BE CHANCED TO DOUBLE PRECISION

IF OOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL XH( 10*5 ) * PARIS)

DOUBLE PRECISION DSTAK<200» EXTERNAL NLSNDL* NLSDRV

COMMON /CSTAK / OSTAK SPECIFY NECESSARY DIMENSIONS

LOSTAK • 200

IXR • 10 READ HUMBER OF PARAMETERS

STARTINC VALUES FOR PARAMETERS NUMBER OF OBSERVATIONS AND NUMBER OF INDEPENDENT VARIABLES INDEPENDENT VARIABLES

READ IDO* NPAR

READ 101* i PAR ID* 1*1»NPAR) READ 100* N* M READ 101* <(IK(I*J)» I ®1*N) » <g-l*Hl PRINT TITLE ANO CALL DCKLS TO PERFORM DERIVATIVE CHECKINC

WRITE (4* 102) CALL DCKLS (XH» N» N» IXN* NLSNDL* NLSDRV* PAR* NPAR* LOSTAK)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (219) 101 FORMAT (4P4.3)

102 FORMAT C'lRISULTS OF STARPAC •

»

4 « DERIVATIVE CHECKINC SUBROUTINE DCKLS 8 ) END MODEL SUCROUTINEl SUBROUTINE NLSMDL (PAR* NPAR* IN* N* N* IXN* PVI

C

C SUBROUTINE TO COMPUTE PREDICTED VALUES OF DEPENDENT VARIABLE

C

C N.B. DECLARATION OF PAR* XM AND PV MUST BE CHANCED TO OOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL PAR(NPAR)* XN(IXN*N)* PV(N)

C DO 10 I - 1* N PVC1) • PAR(l) * XMCI, 1) •* PAR(2)

10 CONTINUE

e RETURN

END

Figure F-4a

Example program using DCKLS

9-46
DERIVATIVE SUBROUTINE*

e

c

c

cc

c

ccc

c

e

SUBROUTINE NLSDRV (EAR* NP AR » XM» N/> N t IXh, 01 SUBROUTINE TO COMPUTE THE PARTIAL DERIVATIVE (JACOBIAN) MATRIX DERIVATIVE WITH RESPECT TO EIRST PARAMETER HAS BEEN CODED

INCORRECTLY TO DEMONSTRATE ERROR DETECTION CAPABILITIES

N.B. DECLARATION OF PAR* XN AND 0 MUST BE CHAN6ED TO DOUBLE PRECISION

IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL PAR(NPAR)* XM(IXN»N)« D(N*NPAR

I

DO 10 I • 1* N 0(1*1) IN( 1*1 ) A PAR (2

)

0(1*2) • PAR(l) * XH( 1*1 ) ** PAR (1 ) e AL06( XN( 1* 1 )

)

10 CONTINUE

RETURN

END

OATAl 2 0.000 0.000

6 I 1.909 1.471 1.490 1.969 1.611 1.680

Figure F-4b

Example program using DCKLS (continued)
%w©

i*4 ©»

©>

©

©

©

©

X z

M= <m

© *r> M3 M © z Z z w

M*

«>

© mi

MB £= *= <=£ X X ©i © M3 Q*4 (49 © Ml X © X O © w * o © z X *« © « © ©

ve 6=0 ms

UM

©

a»5 AS %* z m e M Ml * ^3 Oft M (40 «« u* © © MS (41 o © © « © ©

X

MD z © o Z z © es* © W 6*1 M* z (M K w

MS

X Ml M3 o X *« c 6*1 O X © © N> X © MS M © <*• oW) © a <• © © M0 449 «*9 ck9 «0 x © © U M © © O »* ol Ml © © © © © 64 © © © © X u u U= 44, MS Ul ¥* Z U 6* z *t «*> 149 HI Ml © X Ml M Mi

e=o M>

© o X

©

© Ml ^ M » © © u © ©

<U MU Z Ml 6*1©

Ml o » © US

X

X «M

X

©

©

u

©

U z s=©

© M<

© z 6*1 6*1X

w Ul

X

X

X

X MS 14 o © Z MO

M

M

M* 9 III

©

u

M > X

M>

©

© Ml

©

© 6*1

©©©

©

X 1«

X

X o o X 649 X o V» © o « M M. Z o 8rC #> # « M= ** o Ul MS MO © © 6*1 © © • 6*fl <4® © o •ft © © © 6*1 6*1 © © •*

6*1 «• » Z X© o 149 z M3 o O 6*1 o z O « Z « © W © o X © © o m o « M) * * ^ W o • z X X *4 • ^ « a? • © m o z © © M5 M u *- 9* M © * w * © © • Ul ms © •1 m: ©

ft. •#-m «• • ©

©

M US 0 X 6*1

X

m *>X «>m

©

© •0 Ml

© *-x z ©

© «•

M «> 4 © M3 CM *-

X 6*1 1*1 «• © Mi f«9 © » 6*1 © V*

**> «* 0*9 # z ©

© Ml

M

© 14O -I

©

•»

X # MS **>

©

©

© OX© o

m> * MJ #> 1 © **

X o <•> <• © X M 64 6*1 «A 64 © » © 149 M o O © 6*1 O

kf» •*

X « C4» tft

© z ©

M= <* » # ©

©

©

©©

© -1

©

€>

© c m

K Ul 6*1 z © 6*1 3 t 149 *> ms © © © X © « © * © *4 «¥) Z *4 z z X 1 z

Ml * Z w

©© o © « €> © * MO z z © z

9-48

Example

of

DCKLS

output
G. Acknowledgments

The subroutines used to compute the nonlinear least squares solution are those referenced in Dennis et al. [1981] . The algorithms used to select

optimum step sizes for numerical derivatives, and to check analytic

derivatives were developed by Schnabel [1982] . The printed output for the

nonlinear least squares subroutines has been modeled on the linear least

squares output used by OMNITAB II [Hogben et al. 1971],

9-49

CHAPTER 10

DIGITAL FILTERING

A. Introduction

STARPAC contains 16 subroutines for digital filtering time series. These

include subroutines which: compute a least squares approximation to an ideal

low-pass filter; perform symmetric linear filter operations; sample values

from a series; perform autoregressive (or difference) filter operations; and

compute the gain function of any symmetric linear filter and the gain and

phase functions of any autoregressive (or difference) filter.

Users are directed to §B for a brief description of the. subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and the output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F.

B . Subroutine Descriptions

Ed Symmetric Linear Filter Subroutines

Subroutine LPCOEF computes symmetric linear low-pass filter coefficients

using a least squares approximation to an ideal low-pass filter that has

convergence factors which reduce overshoot and ripple [Bloomfield, 1976],

This low-pass filter has a transfer function which changes from approximately

one to zero in a transition band about the ideal cutoff frequency FC, that is

from (FC - 1/K) to (FC + 1/K), as shown in figure B.l-1. The user must

specify the cutoff frequency in cycles per sample interval and the number of

filter coefficients, which must be odd. The user must also choose the number

of filter terms, K, so that (FC - 1/K) > 0 and (FC + 1/K) < 0.5. In addition,

K must be chosen as a compromise between:

1) A sharp cutoff, that is, 1/K small; and

2) Minimizing the number of data points lost by the filtering operations

( (K - 1 ) / 2 data points will be lost from each end of the series)

.

The subroutine returns the normalized low-pass filter coefficients. There is no printed output.

For any low-pass filter there is a corresponding high-pass filter

equivalent to subtracting the low-pass filtered series from the original

series. Subroutine HPCOEF returns symmetric linear high-pass filter

coefficients computed from user supplied low-pass symmetric linear filter

coefficients. The number of filter coefficients must be odd. There is no printed output.

10-1
LEAST

SQUARES

APPROX

SHAT

ION

TO

IDEAL

LOW

PASS

FILTER

WITH

TRANSITION

BAND

10-2

Transfer

function

of

41-term

least

squares

low-pass

filter

with

a

cutoff

frequency

of

1/22

cycles

per

sample

interval
Subroutine MAFLT performs a simple moving average filter operation on the

input series using the simple moving average filter defined by

HMA(J) = 1/K for J = 1, K.

The user must specify the number of filter coefficients, K, which must be odd;

the subroutine returns the filtered series and the number of observations in

the filtered series. There is no printed output.

Subroutine SLFLT performs a symmetric linear filter operation with user

supplied coefficients and returns the filtered series to the user. The filter

coefficients must be normalized on input to SLFLT. The filtered series and

the number of observations in the filtered series are returned. There is no printed output.

t" v» Subroutine SAMPLE samples every NS cn observation from an input series.

If the input series was obtained using an NS term low-pass filter, this

sampling rate removes the autocorrelation introduced by the filtering

operation. This subroutine returns the series of sampled observations and the

number of observations in the series. There is no printed output.

Subroutine LOPASS computes low-pass filter coefficients as described for

subroutine LPCOEF and then performs the filtering operation described for

subroutine SLFLT. The user must specify the cutoff frequency in cycles per

sample interval and the number of filter terms, which must be odd. The

subroutine returns the normalized filter coefficients, the filtered series and

the number of observations in the filtered series. There is no printed

output.

Subroutine HIPASS computes the high-pass filter coefficients equivalent

to using HPCOEF with the input low-pass filter coefficients supplied by LPCOEF

and performs the filtering operation described for subroutine SLFLT. The user

must specify the cutoff frequency in cycles per sample interval and the number

of filter terms, which must be odd. The subroutine returns the filter

coefficients, the filtered series and the number of observations in the

filtered series. There is no printed output.

B o 2 Autoregressive or Difference Linear Filter Subroutines

Subroutine ARFLT subtracts the series mean from each observation and

performs an autoregressive linear filter operation with user supplied filter

coefficients. This subroutine returns the filtered series and the number of

observations in the filtered series. There is no printed output.

Subroutine DIF performs a first difference filter operation on the input

series. It returns the differenced series and the number of observations in

the differenced series. There is no printed output.

Subroutine DIFC performs a user controlled differencing operation. It

returns the order of the difference filter specified, the coefficients of the

difference filter, the differenced series and the number of observations in

10-3
the differenced series. This subroutine can be used as a high-pass filter or for differencing series in the style of Box and Jenkins [1976] . There is no printed output.

Subroutines DIFM and DIFMC are the same as DIF and DIFC, respectively,

except that the input series may contain missing data. A missing value code

must be used within the input series to specify time points without an observed value. The difference between a missing value and an observed value, or between two missing values, will result in a missing value in the

differenced series; the missing value code used in the differenced series is

also returned to the user. Users should note that the number of missing

values may be significantly increased by the differencing operation.

B.3 Gain and Phase Function Subroutines

Subroutine GFSLF computes the gain function of a symmetric linear filter.

The printed output consists of a plot of the gain function versus frequency.

Subroutine GFSLFS is the same as GFSLF but allows the user to specify

various options which are preset in GFSLF, including the frequency range, the

number of frequencies for which the gain function is to be computed and the

type of plot to be used. In addition, the gain function is returned to the

user, permitting the use of other methods of displaying the results.

Subroutine GFARF computes the gain and phase functions of either

autoregressive or difference filters. The output consists of a plot of the

gain and phase functions versus frequency.

Subroutine GFARFS is the same as GFARF but provides the user with the same options as are available for subroutine GFSLFS.

C o Subroutine Declaration and CALL Statements

NOTES Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

Subroutines Supporting Symmetric Linear Filter Operations

LP'COEF: Compute symmetric linear low-pass filter coefficients; return filter

coefficients (no printed output)

<real> HLP(k)

CALL LPCOEF (FC, K, HLP)

10-4
HPCOEF: Compute symmetric linear high-pass filter coefficients; return

coefficients (no printed output)

<real> HLP(fc), HHP (fc )

tCALL HPCOEF (HLP, K, HHP)

MAFLT: Perform simple moving average; return filtered series (no printed

output)

<real> Y(n), YF (n

)

CALL MAFLT (Y, N, K, YF , NYF

)

SLFLT: Perform symmetric linear filter operation with user- supplied filter

coefficients; return filtered series (no printed output)

<real> Y(n), H(fc), YF (n)

$CALL SLFLT (Y, N, K, H, YF , NYF)

SAMPLE: Sample (extract) every NS

^

observation from a series; return

sampled series (no printed output)

<real> Y(n), YS(n)

ICALL SAMPLE (Y, N, NS, YS , NYS

)

LOPASS: Filter series with symmetric linear low-pass filter; return filtered

series (no printed output)

<real> Y(n), HLP(k), YF(n)

CALL LOPASS (Y, N, FC , K, HLP, YF , NYF)
HIPASS: Filter series with symmetric linear high-pass filter; return

filtered series (no printed output)

<real> Y(n), HHP(fc), YF (n)

SCALL HIPASS (Y, N, FC, K, HHP, YF , NYF

)

Subroutines for Autoregressive or Difference Linear Filters

ARFLT: Perform autoregressive filter operation with user-supplied filter

coefficients; return filtered series (no printed output)

<real> Y(n), PHI (iar»), YF(n)

iCALL ARFLT (Y, N, IAR, PHI, YF , NYF)

DIF o Perform first-difference filter operation; return differenced series

(no printed output)

<real> Y(n), YF(n)

ZCALL DIF (Y, N, YF , NYF)

DIFC: Perform user-specified difference filter operation; return

differenced series (no printed output)

INTEGER ND(n/ac), IOD(n/ac)

<real> Y(n), YF(n), PHI (iar*)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL DIFC (Y, N, NFAC, ND, IOD, IAR, PHI, LPHI, YF , NYF, LDSTAK)

DIFM: Perform first-difference filter operation on series with missing

data; return differenced series (no printed output)

<real> Y(n), YF(n)

CALL DIFM (Y, YMISS, N, YF , YFMISS, NYF)

10-6
DIFMC:

GFSLF

GFSLFS:

GFARF:

Perform user-specified difference filter operation on series with

missing data; return differenced series (no printed output)

INTEGER ND (nfac), lOD(nfac)

<real> Y(n), YF(n), PHI (iar)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL DIFMC (Y, YMISS, N, NFAC, ND, IOD, IAR, PHI, LPHI, YF

,

1 YFMISS, NYF , LDSTAK)

Subroutines for Computing the Gain and Phase Functions

Compute and plot gain function of symmetric linear filter

<real> H (k.)

$CALL GFSLF (H, K)

Compute and optionally plot gain function of symmetric linear filter

with user-supplied control values; return gain function values and

corresponding frequency values

<real> H(k), GAIN(n/), FREQ(nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL GFSLFS (H, K, NF , FMIN, FMAX , GAIN, FREQ, NPRT, LDSTAK)

Compute and plot gain and phase functions of autoregressive or difference filter

<real> PHI (iar®)

CALL GFARF (PHI, IAR)

10-7
GFARFS: Compute and optionally plot gain and phase functions of

autoregressive or difference filter; with user- supplied control

values; return gain and phase function values and corresponding

frequency values

<real> PHI( iar), GA.IN(nf) , PHAS(nf), FREQ(nf)

DOUBLE PRECISION DSTAK(ldstak)

COMMON / CSTAK/ DSTAK

CALL GFARFS (PHI, IAR, NF , FMIN, FMAX , GAIN, PHAS, FREQ, NPRT,

1 LDSTAK)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE: —> indicates that the argument is input to the subroutine and that

the input value is preserved;

<— indicates that the argument is returned by the subroutine; <-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; —- indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

° * * indicates that the variable is passed via COMMON*

DSTAK The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK are overwritten during subroutine

execution.

FC “> The cutoff frequency for the filter, in cycles per sample

interval. FC must lie between 0.0 and 0.5.

FMAX -“> The maximum frequency, in cycles per sample interval, at which the

gain and phase functions are computed (0.0 < FMIN < FMAX < 0.5).

The default value is 0.5. If FMAX is outside the range FMIN to

0.5 or is not an argument in the CALL statement the default value

is used.

FMIN —> The minimum frequency, in cycles per sample interval, at which the

gain and phase functions are computed (0.0 < FMIN < FMAX < 0.5).

The default value is 0.5. If FMIN is outside the range 0.0 to

FMAX or is not an argument in the CALL statement the default value

is used.

FREQ <--- The vector of dimension at least NF containing the NF frequencies

at which the gain and phase functions are computed.

GAIN <— The vector of dimension at least NF containing the NF gain

function values over the range FMIN to FMAX. — continued —

10-8
For symmetric linear filters:

The gain function of a symmetric linear filter is

K

GAIN(I) = | l (H(J) cos [ 2ir

| K^-J | (FMIN+Ax)]}|

J=1

for I = 1, NF, where

is the midpoint of the symmetric filter, K

m

= (K+l)/2, and

Aj is the frequency increment, defined as

Aj = 2 ( I— 1 ) (FMAX-FMIN) / (NF-1)

There is no phase change in a symmetric linear filter.

For autoregressive (or difference) filters:

The gain and phase functions of an autoregressive (o

difference) filter are

GAIN(I) »

IAR

|l - l {PHI(J) (cos[2ttJ(FMIN+AI)] + i sin[ 2tt J(FMIN+A I)] )

}

J=1

and

IAR

l

{ PHI ( J ) sin[iTT J(FMIN+AI)]}

J=1

PHAS(I) = Arctan ———

IAR

1 - l{ PHI ( J ) cos [ iir J(FMIN+AI)]}

J=1

for I = 1, 2, ..., NF, where

1/2

i is the complex value (-1) ; and

Aj is the frequency increment, defined as

A X = 2(1-1) (FMAX-FMIN) / (NF-1).

-> The vector of dimension at least K containing filter coefficients

which must be symmetric about H((K+l)/2).

10-9
HHP <— The vector of dimension at least K containing the K high-pass

filter coefficients, which are symmetric about HHP[ (K+l ) /2) . The

high-pass filter coefficients are computed from the low-pass

coefficients by

K

HHP(J) = 1- [ HLP( J ) / l HLP(J)] for J = V

L=1

K

HHP(J) = -[ HLP( J ) / l HLP ( J ) ] for J = 1, . .., K^-l , K^+l , . .., K.

L=1

HLP -—- The vector of dimension at least K containing the K low-pass

filter coefficients, which must be symmetric about HLP[ (K+l

)

/

2

] . HLP must be input to HPCOEF; it is returned by LPCOEF and LOPASS.

For LPCOEF and LOPASS, HLP is defined by

K

HLP(J) = hj / l hj for J = 1 K,

1=1

where

hj is computed by

hj = 2* FC for J = ^

sin[2ir Ik^-J | FC] sin[2Tr | K^-J | / K]

hJ

= ________ « __________ for J

» |Km

-J| 2* |Km

-j| / K

with the midpoint of the filter, K

m

= (K+l)/2.

This low-pass filter has a transfer function which changes from

approximately one to zero in a transition band about the ideal

cutoff frequency FC, that is from (FC - 1/K) to (FC + 1/K), as shown in figure B.l-1.

IAR — The number of coefficients in the autoregressive (or difference)

filter, including zero coefficients. Equivalently, IAR is the

maximum order of the backward shift operator. IAR must be input

to ARFLT, GFARF and GFARFS; it is returned by DIFC and DIFMC. IAR

is defined by

NDF

IAR = l

[ IOD(J)»ND(J)]

.

J=1

— 1 , . . • , Km-1, VI,

... , K

10-10
IERR

IOD

K

LDSTAK -

LPHI

N

ND

NF

** An error flag returned in COMMON /ERRCHK/. [See chapter 1, § D . 5 .

]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected. —> The vector of dimension at least NFAC containing the NFAC values

designating the order of each difference factor. —> The number of coefficients in the symmetric linear filter. K must

be odd. For LPCOEF, LOPASS, and HIPASS, the user must choose the

number of filter terms, K, so that (FC - 1/K) > 0 and

(FC + 1/K) < 0.5. In addition, K must be chosen as a compromise

between:

1) A sharp cutoff, that is, 1/K small; and

2) Minimizing the number of data points lost by the filtering

operations (K - 1 ) / 2 data points will be lost from each end of

the series.

-> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P = 0.5,

otherwise P = 1.0. [See chapter 1, § B .

]

For DIFC and DIFMC

:

NFAC

LDSTAK >7+2* £ [ND(J). IOD(J)] *P

J=1

For GFSLFS and GFARFS

:

LDSTAK > ( 11+10* (9+NF)) /2 + I0-2.NF.P

where 10 = 0 if NPRT = 0, and 10 = 1 if NPRT * 0.

-> The length of the vector PHI. LPHI must equal or exceed IAR. —> The number of observations in the time series. The minimum number

of observations is three.

-> The vector of dimension at least NFAC containing the NFAC values

designating the number of times each difference factor is to be

applied. —> The number of frequencies at which the gain and phase functions

are to be computed. The default value is 101. If NF is not an argument of the subroutine CALL statement the default value is

used.

10-1

1
NFAC —> The number of difference factors.

NPRT —> The argument controlling printed output.

If NPRT < 0, the output consists of a plot of the gain function

versus frequency, where the gain function is

expressed in decibels and is adjusted so that the

peak is at zero. For GFARFS only the output also

includes a plot of the phase function versus

f requency

.

If NPRT = 0, the automatic printout is suppressed.

If NPRT > 0, the output consists of a log-linear plot of the gain

function versus frequency. For GFARFS only, the

output also includes a plot of the phase function

versus frequency.

The default value is -1. If NPRT is not an argument of the

subroutine CALL statement the default value is used.

NS —> The sample rate, 1 < NS < N.

NYF <— The number of observations in YF.

NYS <— The number of observations in YS.

PHAS <— The vector of dimension at least NF containing the NF phase

function values over the range FMIN to FMAX.

PHI — The vector of dimension at least NF containing IAR autoregressive

or difference filter coefficients. PHI must be input to ARFLT,

GFARF, and GFARFS; it is returned by DIFC and DIFMC.

For DIFC and DIFMC the difference filter coefficients are obtained

by expanding the difference operator

NFAC

II J=1

( i.” Biod(J)^ nd(j) =

1 - PHICUB1 - PHI(2)B

2 - • •• - PHI(IAR)B IAR

where

B is the backward shift operator. defined by B

1 y t Yt-i’

PHI (i

)

is the i

1-*1 difference filter coefficient,

positive or negative integer if the i th

shift operator B

1 is used, and zero if

backward shift operator is unused.

which will be a order backward

the i^ order

10-12
Y

YF

YFMISS <

YMISS

—> The vector of dimension at least N containing the N observations

of the time series.

-- The vector of dimension at least N containing the NYF values of

the filtered series. The filtered series will start in

YF ( 1 ) ; YF(NYF+1) through YF(N) will be set to zero.

For symmetric linear filters:

The filtered series obtained by applying a moving average filter

is defined by

K

YF ( I ) = l H( J

) • Y( I+K-J ) for 1=1, NYF,

J=1

where

NYF is the number of values in the filtered series,

NYF = N - (K-l), reflecting the (K-l)/2 data points lost

from each end of the original series by the filtering

operation.

For autoregressive or difference filters:

The filtered series obtained using an autoregressive (or

difference) filter is computed by

IAR

YF(I) = Z (I+IAR) - l

[ PHI ( J )

• Z ( I+IAR-J ) ] for I = 1, . NYF,

J=1

where

Z is the N observation time series being filtered which, for

ARFLT is the input series Y minus its mean and, for DIF,

DIFC, DIFM and DIFMC is the input series Y;

NYF is the number of observations in the filtered series,

NYF = N-IAR, reflecting the IAR data points lost from the

beginning of the original series by the filtering operation. — The missing value code used within the filtered series YF to

indicate that a value could not be computed due to missing data.

-> The missing value code used within the input series Y to indicate

that an observation is missing.

10-13
YS <— The vector of dimension at least N containing the series formed by

sampling every NS^ element of Y,

YS ( J) = Y[ ( J— 1

) • NS + 1) for J = 1, NYS,

where NYS, the number of observations in the sampled series, is

returned by subroutine SAMPLE. The series will start in YS(1);

YS(NYS+1) through YS(N) will be set to zero.

E . Computational Methods

E. 1 Algorithms

The code for computing the low-pass filter coefficients is based on subroutine LOPASS, listed on page 149 of Bloomfield [1976], The transforms

used to compute the gain function of symmetric filters and the gain and phase

functions autoregressive (or difference) filters are based on the algorithms

shown on pages 311 and 420, respectively, of Jenkins and Watts [1968].

E . 2 Computed Results and Printed Output

Except for the gain and phase function subroutines, STARPAC digital

filtering subroutines do not produce printed output. For the gain and phase

function subroutines, the argument controlling the printed results is NPRT and

is discussed in §D; the output from the gain and phase function subroutines

consists of line printer plots of the gain and phase function of the input

filter.

F . Examples

In the example program of figure F-la, DIF is used to filter the input

series Y; VP (documented in chapter 2) is used to display the log of the

original series and the differenced series; and GFARF is used to plot the gain

and phase functions of the first difference filter. The data used are the

natural logarithm of Series G, the airline data, listed on page 531 of Box and

Jenkins [1976] . The formulas for the gain and phase functions of a first

difference filter and a plot of the corresponding gain function are shown on pages 296 and 9, respectively, of Jenkins and Watts [1968].

Figures F-lb and F-lc display the VP plot of the log of the original

series and the differenced series, respectively. Both plots have been

truncated so that they will fit on one page of this manual; the actual plots

generated by VP continue for another 90 lines. Figures F-ld and F-le show the

output from GFARF. There is no automatic printout from DIF.

10-14
o

oo

o

MAIN PROGRAM* PROGRAM EXAMPL

DATA l

C

Cc

c

cc

c

c

cc

DEMONSTRATE DIF AND GFARF USING SINGLE PRECISION VERSION OF STARPAC

RUN ON CYBER 180/8*0.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TA»E6 ON CYBERS)

C S EE CHAPTER 1* SECTION D.41

N.B. DECLARATION OF Y, YF AND PHI MUST BE CHANGED TO DOUBLE PRECISION

IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL Y (200 ) , YF(200)» PHI ( 5

)

READ NUMBER OF OBSERVATIONS

OBSERVED SERIES

READ 100. N RE AO 101. (Y(I), I-1»N)

C

C COMPUTE LOG OF DATA

C 00 10 I • 1, N

Y ( I ) - AL06 ( Y ( I ) > 10 CONTINUE

C

C CALL OIF TO PERFORM DIFFERENCING OPERATION

C CALL DIF ( Y , N, YF, NYF

)

CC PRINT TITLE AND CALL VP TO DISPLAY LOG OF ORIGINAL SERIES

WRITE (6, 102

1

CALL VP «Y, N, 1)

C

C PRINT TITLE AND CALL VP TO DISPLAY DIFFERENCED SERIES

C WRITE (6, 1031 CALL VP (YF, NYF, 1)

C

C SIT PARAMETERS FOR FIRST DIFFERENCE FILTER

C PMim - i.o

IAR « 1

c

C PRINT TITLE AND CALL GFARF TO COMPUTE 6AIN AND PHASE OF

C FIRST DIFFERENCE FILTER

C WRITE (6, 10*1 CALL GFARF (PHI, IAR)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (415)

101 FORMAT (12F6.1)

102 FORMAT (

1 1L06 OF 0RI6INAL SERIES DISPLAYED WITH STARPAC PLOT',

1 • SUBROUTINE VP') 103 FORMAT (URESULTS OF STARPAC FIRST DIFFERENCE DIGITAL FILTERING',

1 « SUBROUTINE DIF DISPLAYED WITH STARPAC PLOT SUBROUTINE VP») 104 FORMAT C1RESULTS OF STARPAC,

* » GAIN AND PHASE FUNCTION SUBROUTINE GFARF')

END

144 112.0 118.0 132.0 129.0 121.0 139.0 148.0 148.0 134.0 119.0 104.0 118.0

119.0 126.0 141.0 139.0 129.0 149.0 170.0 170.0 198.0 133.0 114.0 140.0

149.0 190.0 178.0 163.0 172.0 178.0 199.0 199.0 184.0 162.0 146.0 166.0

171.0 180.0 193.0 181.0 183.0 218.0 230.0 242.0 209.0 191 .0 172 .0 194.0

196.0 196.0 236.0 239.0 229.0 243.0 264.0 272.0 237.0 211.0 180.0 201.0

204.0 188.0 239.0 227.0 234.0 264.0 302.0 293.0 299.0 229.0 203.0 229.0

242.0 233.0 267.0 269.0 270.0 319.0 364.0 347.0 312.0 274.0 237.0 278.0

284.0 277.0 317.0 313.0 318.0 374.0 413.0 409.0 399.0 306.0 271.0 306.0

319.0 301.0 396.0 348.0 399.0 422.0 469.0 467.0 404.0 347.0 309.0 336.0

340.0 318.0 362.0 348.0 363.0 439.0 491.0 909.0 404.0 399.0 310.0 337.0

360.0 342.0 406.0 396.0 420.0 472.0 948.0 999.0 463.0 407.0 362.0 409.0

417.0 391.0 419.0 461.0 472.0 939.0 622.0 606.0 908.0 461 .0 390.0 432.0

Figure F-la

Example program using DIF, VP and GFARF

10-15
8.06

OF

ORIGINAL

SERIES

DISPLAYS®

MITH

STARPAC

PLOT

SUBROUTINE

VP

®OMOif'O^NfgO^O'^^®^Ofr'r8ir(VO'OH'OOH^^Hrni^>fN^f\J^WMCD(^4’CD(r»(NJNKN

*\ o o o <* *** ^- •#• i ^r*»®®r^oooor“'«i h N ^ tfMO (y

t\« <n» < -r <r

•* I •-< P-1 * I ***> frxO C=S tv* (

t/» rf> o

I

CD

J-a 3

bo ‘H

® 9 «"8 0 © N1 «* 9

e

io

© e e c«3 ** 0

I

•

(Si | W •

ffVJ G ® Q © *4

«# 0

0

0

9 # 0 <* 0 « I © «

OGOOOOOOOGOeOOOOOOOGOOOOOOOeOOOOOOOOOOOOOOOOO ooooooooooooooooooooooooooooooooooooooooooooo ooooooooooooooooooooooooooooooooooooooooooooo ©©OOOOOOO*©®©*®®*®®®®®®**®**®*®*'*©®*®©®**®*** » e © c © C © « •G^N(Tt#tft«K(D90HN«14> ^<Oh> «^OH(Nnn4> «I«h<GO> OHN(n^r8

ooooooooo oooooo ooo ooooooooo

«MMyOHN<n« + -r r r r r r

10-16

Example

of

partial

VP

output

displaying

the

log

of

the

original

series
0 o o o

1 It I m UJ uj ui c h9 n m

*4 <M O' O & O

cm *h cm <r O —» ^ H W -O H ^

0

1 Ui^ r» «*> r m # mm

0 o

1 I Ui Ui O CM O

fM rt in o ^ m

NrtH HM 51

CD IO

«e cd cm >r o O ( (> «f\ « *© T*> I

0

1 ui

«*» IT* O CM CM <SI

0

1 Ui

rt ^

*4 <T ©* OO^ *»• CM C*

<\» *> m

O ^ C*> ^ *« o

m r- QD m h® c* 1

«# a »v

•# ® «r\ f*> CM *-< m «r -«

0 00000 00 o o

1 I 1 1 I I tl I I Ui Ui Ui UJ Ui Ui Ui Ui UI UJ O ^ CD ^

^momc*-^<*)^«ocDir\'*>.©r*»<*»^ «N(»»®«N^H<?Oir. BOOC-OW C M O N H a COM*)OCO ONO KHHHMlOO'CHHaiinHC <°|l H

OOO I I t

'C ^ m

•#* « m

CM «T« O* c N in

t I ©til I I • e 1 « 1 t § u UJ f fcH *M «»S U* « I lUClH

C CMCM

8 ® >00O O

ui • •* Z CM UJ

*“* o

t~ ^

0^*1 Oft©

« K

<£ < 0 1-0

crt O

t^> its *-c

8 Ui

CD N!

s

4rt %&

u

*

e e

9 I

I P*4

0)D

bC

°H

fa

O' w

6

e 0

1 © 8

Ui I CM I CM•

I

J

OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 00000000000000000000000000000000000000000000000000000 OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO OOOOOOOOO • ••••••• • • * • • • • » •Oe4CMfV»*‘«>'0r'»«>0'O»-4<Mfn'*«%'0^-»OO»4CMC'n<«’n'0r»«D0k O^4CM<n*'rt^)^»CD9‘OHfM««>

I

10-17

I

Example

of

partial

VP

output

displaying

the

differenced

series
RESULTS

OF

STARRAC

SAIM

AMD

RHASi

FUNCTTOM

SUBROlinMI

GFARF

fit 9 ^ e

6

I « e

uj e0 Z 6 (U I « 0 U9 |

fc*= 6

© 8

0 ®> fi us e

3*> 8

I X | M »*< M W §

e w 6

(&$ 6 or I «$ 0

3<* 8

8 z e

o

o

I r

O <SJ O r\| «r> 'si

O rr, © rr* O rr>

I O

I O *5

I IT C

5 r< *

I

I o

0 o

0 r»

1 o

GO

» 8 x

©m

©

xxx 0 xxxx g xxxx 0

e=*o x x < xxxx § XXXI 0 x x x x B x x x x I x x x x | ©

<u> z

3*

0

rv

««VX

I

o

a

P

P

M

O w

O P»

r< i/> m oo

<M

3

a

I

a.P

3

be

fc

a:<

PuO

u< a

E

(0X

w

10-18
10-19

Example

of

GFARF

output

(continued)
G. Acknowledgments

The code for computing the low-pass filter coefficients is

subroutine LOPASS, listed on page 149 of Bloomfield [1976]. The

used to compute the gain function of symmetric filters and the gain

functions of autoregressive (or difference) filters are based

algorithms shown on pages 311 and 420, res-pectively , of Jenkins

[1968].

based on transforms

and phase

on the

and Watts

10-20
CHAPTER 11

COMPLEX DEMODULATION

A. Introduction

STARPAC contains two subroutines which find the amplitude and phase

functions of a demodulated series as described in Bloomfield [1976]

.

The demodulated series 5(t) is formed by multiplying the observed series

by a complex sinusoid at the demodulation frequency. If the observed series Y

is a sinusoid of the nominal demodulation frequency FD with varying amplitude

and phase plus noise, that is,

Y(t ) = R(t) cos(2rFDt + <J>(t)) + a(t)

. if 2rFDt + $(t)l ~if2irFDt + <{>(t)) = 0.5 R(t )

[ e

1 J + e

1

] + a(t)

then the demodulated series may be represented by

-i2ir FD

6 (t ) - e Y(t)

i<b ( t ) -i(4irFDt + cj>(t)l -i2TTFD

0.5 R(t)e + (0.5)R(t)e + e a(t)

for t - 1. © o •

N is the

i is the

FD is the

R(t) is the

<j> (t) is the

a(t) is the

Users are

, N, where

1/2

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F.

B . Subroutine Descriptions

Subroutine DEMOD computes the smoothed amplitude and phase components of

the demodulated series. The user must specify the demodulation frequency,

along with the number of filter terms and the cutoff frequency which define

1 l-l
the low-pass filter utilized to smooth the demodulated series. Output from

DEMOD consists of plots of the amplitude and phase functions. The phase

function plot reduces discontinuities using the method suggested by Bloomfield

[1976]. As shown in figure F-lc this method displays both the principle phase

value, which is defined to lie in the range —it to it, and the principle phase

value plus or minus 2tt , where the sign is chosen such that the second value

lies in the range ~2tt to 2tt .

Subroutine DEMODS is the same as DEMOD except that the computed amplitude

and phase functions arc returned to the user and the printed output described

for DEMOD is optional.

C . Subroutine Declaration and GALL Statements

NOTE; Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

DEMOD: Compute and plot the results of a complex demodulation of the input

series

<real> Y (ji)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

ICALL DEMOD (Y, N, FD, FC, K, LDSTAK)

DEMODS: Compute and optionally plot the results of a complex demodulation of

the input series; return amplitude and phase functions of demodulated

series

<real> Y(n), AMPL(n), PHAS (n)

DOUBLE PRECISION VSTMUldstak)

COMMON /CSTAK/ DSTAK

CALL DEMODS (Y, N, FD, FC, K, AMPL, PHAS, NDEM, NPRT, LDSTAK)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE; —> indicates that the argument is input to the subroutine and that

the input value is preserved; <-- indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; — indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

* •

• indicates that the variable is passed via COMMON.

11-2
AMPL <

DSTAK

FC

FD

IERR

K

LDSTAK -

— The vector of dimension at least N-(K-l) that contains the NDEM

values of the smoothed amplitude function of the observed series,

AMPL(I) = R(t), where R(t) is defined in §A and the index I is

computed as I = t - (K-l)/2 for t = (K+l)/2 to N-(K-l)/2. The

stored values of the amplitude function will start in AMPL(l);

AMPL(NDEM+1) to AMPL(N) will be set to zero.

* * The DOUBLE PRECISION vector in COMMON /CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

--> The cutoff frequency for the low-pass filter in cycles per sample

interval. FC must lie between 1/K and FD.

-> The demodulation frequency in cycles per sample interval. FD must

lie between 0.0 and 0.5.

An error flag returned in COMMON /ERRCHK/ . [See chapter 1, §D.5.]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

-> The number of terms in the low-pass filter used to extract the

amplitude and phase functions. K must be odd. The user must

choose the number of filter terms, K, so that (FC - 1/K) > 0 and

(FC + 1/K) < 0.5. In addition, K must be chosen as a compromise

between.

1) A sharp cutoff, that is, 1/K small; and

2) Minimizing the number of data points lost by the filtering

operations. ( (K - 1 ) / 2 data points will be lost from each end

of the series.)

-> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P = 0.5,

otherwise P = 1.0. [See chapter 1, §B.]

For DEMOD:

LDSTAK > 10 + ( 3 • N+K )

• P

For DEMODS:

LDSTAK > 9 + (10- 2* N+K)*

P

where 10 = 0 if NPRT = 0 and 10 = 1 if NPRT t 0.

1 1-3
N —> The number of observations, which must equal or exceed 17.

NDEM <— The number of observations in AMPL and PHAS, NDEM = N - (K-l).

NPRT —> The variable controlling printed output.

If NPRT = 0, the automatic printout is suppressed.

If NPRT t 0, the automatic printout is provided.

The default value is 1. If NPRT is not an argument of the

subroutine CALL statement the default value is used.

PHAS <— The vector of dimension at least NDEM = N-(K-l) that contains the

NDEM primary values of the smoothed phase function of the observed

series, PHAS(I) = <|>(t), where <f>(t) is defined in §A and the index

I is computed as I = t - ( K- 1 ) / 2 for t = ( K+ 1 ) / 2 to N - ( K- 1 )

/

2

.

The stored values of the phase function will start in PHAS(l);

PHAS(NDEM+1) to PHAS(N) will be set to zero.

Y —> The vector of dimension at least N that contains the observations

of the time series.

E . Computational Methods

E. 1 Algorithms

The STARPAC code for performing complex demodulation was adapted from the

subroutines given on pages 147 to 150 of Bloomfield [1976]. As noted in

Bloomfield, the first term of the demodulated series defined in §A is centered

about zero frequency while the remaining two terms are centered at frequencies

FD and 2FD. Thus, the first term can be separated from the others using the

low-pass filter described in chapter 10 (with FC » FD/2), resulting in the

complex filtered series

K

YF(t) = l HLP(J).6(t+Km

-J)

J=1

= a (t ) + i* 8 (t )

i<J>(t) = 0. 5« R(t ) * e for t = K^, K^+l , ..., (N-K^+l),

where

K is the number of filter terms;

is the midpoint of the filter, = (K+l)/2;

HLP(J) is the J

t ^1 low-pass filter coefficient, defined in chapter 10, §D;

1 1-4
a(t) is the real part of the filtered series;

3(t) is the imaginary part of the filtered series.

The smoothed estimates of the amplitude R and phase <j> functions can then be

extracted from the filtered series using

R(t) - 2(a(t)2 + B(t)2)

1/2

and

A

cf>(t) = tan_1 (a(t)/B (t)) .

Note that (K-l)/2 points have been lost from each end of the demodulated

series by the filtering operation.

E . 2 Computed Results and Printed Output

The argument controlling the printed output, NPRT, is discussed in §D.

The output consists of plots of the smoothed amplitude and phase functions,

and a list of the demodulation frequency, cutoff frequency and number of terms

in the low-pass filter used to smooth the demodulated series.

F . Example

In the example program of figure F-la, DEMOD is used to estimate the

amplitude and phase function corresponding to the input series Y. The data

used are the Wolf sunspot numbers for the years 1700 to 1960 as tabulated by

Waldmeier [1961] . Figure F-lb shows the plot of the amplitude function and

figure F-lc shows the plot of the phase function. Both plots have been

truncated so that they will fit on one page of this manual; the actual plots

generated by DEMOD continue for another 177 lines. The transfer function of

the low-pass filter used in this example is shown in chapter 10, figure B.l-1.

Further discussion of this example can be found on pages 137 to 141 of

Bloomfield [1976].

11-5
IAIN PROGRAM PROGRAM E X AM PL

C

C DEMONSTRATE DEMOD USING SINGLE PRECISION VERSION OF STARPAC

C RUN ON CYBER 180/9A0.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE T A PI 6 ON CYBERS)

C ESEE CHAPTER 1# SECTION D.A]

C

C N.B. DECLARATION OF Y MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL Y ( 300

)

DOUBLE PRECISION DSTAM900)

C COMMON /CSTAK/ DSTAK

c

C SPECIFY NECESSARY DIMENSIONS

C LDSTAK = 500

C

C READ NUMBER OF OBSERVATIONS

C OBSERVED SERIES

C READ 100# N READ 101# ( Y ( I J # I •!# N ) CC SET DEMODULATION FREQUENCY

C CUTOFF FREQUENCY

C NUMBER OF TERMS IN THE LOW-PASS FILTER

C FD « 1.0 7 11.0

FC = 1.0 / 22.0

K » A1

c

C PRINT TITLE ANO CALL DEMOO FOR COMPLEX DEMODULATION ANALYSIS

C WRITE (6* 102) CALL DEMOD (V, N# FD# FC# K# LDSTAK)

C STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (15) 101 FORMAT (10F7.2)

102 FORMAT (URESULTS OF STARPAC#

* « COMPLEX DEMODULATION SUBROUTINE DEMOD*

S

END DATA I 261

5 .00 11.00 16.00 23.00 36.00 96.00 29.00 20.00 10 .00 8 .00

3 .00 0.00 0.00 2.00 11.00 27.00 A7.00 63.00 60 .00 39 .00

28 .06 26.00 22.00 11.00 21.00 AOoOO 78.00 122.00 103 .00 73 .00 AT .00 35.00 11. DC 9.00 16.00 3A.00 70.00 61.00 111 .00 101 .00

73 .00 AO. 00 20. OC 16.00 5.00 11.00 22.00 AO. 00 60 .00 80 .90 83 .AO A7.70 A7.80 30.70 12.20 9.60 10.20 32. AO A7 .60 5 A .CO

62 .90 85.90 61.20 AS. 10 36. AO 20.90 11. AO 37.80 69 .80 106 .10 100 .80 61.60 66.90 3A.80 30.60 7.00 19.80 92.50 ISA .AO 125 .90

BA .80 68.10 36.90 22.80 10.20 2A.10 82.90 132.00 130 .90 118 .10

89 .90 66.60 60.00 A6.90 A1.00 21.30 16.00 6. AO A .10 6 . 80 1A .50 3A.00 A9.00 A3. 10 A7.50 A2.20 28.10 10.10 8 .10 2 .50

0 .00 1. AO 9.00 12.20 13.90 39. AO A5.80 A1.10 30 .10 23 .90

15 .60 6.60 A. 00 l.SO 8.50 16.60 36.30 A 9 . 60 6 A .20 67 .00 70 .90 AT. 80 27.50 8.50 13.20 36.90 121.50 138.30 103 .20 85 .70

6A .60 36.70 2A.20 10.70 15.00 AO. 10 61.50 98.50 124 .70 96 . 30 66 .60 6A.90 5 A , 1

0

39.00 20.60 6.70 A. 30 22.70 5 A .80 93 . 80

95 .80 77.20 59.10 AA .00 A7.00 30.30 16.30 7.30 37 .60 7A .00 139 .00 111.20 101.60 66.20 AA.70 17.00 11.30 12. AO 3 .AO 6 .00

32 .30 5A.30 59.70 63.70 63.50 92.20 25. AO 13.10 6 .80 6 .30

7 .10 35.60 73.00 85.10 76.00 6A.00 A1.80 26.20 26 .70 12 .10

9 .50 2.70 5.00 2A.A0 A2.00 63.50 53.80 62.00 A 8 .50 A3 .90

18 .60 3.70 3.60 1. AO 9.60 A7.A0 57.10 103. 90 80 .60 63 .60

37 .60 26.10 1A.20 5.80 16.70 AA.30 63.90 69.00 77 .80 6 A .90

35 .70 21.20 11.10 5.70 8.70 36.10 79.70 11A. AO 109 .60 88 .80

67 .BO A7.50 30.60 16.30 9.60 33.20 92.60 151.60 136 .30 13A .70 83 .90 69. AO 31.50 13.90 A. AO 36.00 1A1.70 190.20 1 8 A .80 159 . 00 112.30

Figure F-la

Example program using DEMOD

11-6
I

N CD H M ^ ^ ^ I ift«rO®N^H^#<VflD(»nr»Kif>NNOSHC-<®^^ON<,O^^SON^CM>H^ON(NJ»nfn(i,» OeH^OHNH^mN^OON^^^NOftJlfMA^O^NCXWCCDIt OODO^ONi^C^NO^fM

OMinNON^ON^O^NMHHOC^ OCDNO^«ffOHON^^inn^rjMfMHHO? O © © <\l n m in n (*) # -# ^ ^ ^ -# < m wfncfimmmnwmmcnmNNw rom

I J=3 M W I I M M W H I w I ^ I

II

I r* I ® I 5 I • *-j ® I ® I•

•

I o i ^ 8

<<3 9 c°3 8 * fcX) ^ I ifv I

I

9I O I 6 9 © I ® 8

4>

« I «#• 08I ® 0 o 0 K 8 t* 8 0 *-t «-a 9

8

I

I ©* I H I $

1

0 030 ® 9 a*» 99

0

•C

«*h

I

0) XXXZXXXXXXXXZZ! zcszccYccxECsrzcrcrzzsxzr

z r- i e—j v\ H U9 r*= 6 3 ft-3 « G O or x • w

or UJ cv 11 SD vn or m 11 3 «-4 us 11 ©m l1 0 1 1 Z ¥~ «*2 A8 O <m. or «v 1 1 K -j <« ^ 1

! *“ 3 X (1 9“ C» »=3 © O © «B0

<-« © «r* O

3 Of E «h «v 1 O © IT* UJ u O i 1 O O ^ 0« 0 a«J z © m A 1 UJ o- + ++ © 1 1 O OOd uj >- «U 1 1 e • X «rt ^ 1 1 X (Ui O 1 1 UJ W X O z • t-c <_J Z #N> » O UJ 1 1 a. O X >' W

x z «<fc *H1 i i 0 0 w Hi 1 1 0 z U 1 1 —J UJ V» <Si O Vi cu 1 0 Z> 3 «-> E 0-) w t *< O 0 or UJ K t a. O Ol ^ Ui 0 z r- t1 at E Of UK 3 h •

•< U£ u Z »- - O UJ UL E (HI v» Z 3 O —

*ri O O a. UL

11. UJ h uj a E 0

O K- a ui

or. < U. OD Z

%r» UJ *4 E u. O

«/* 3 U- 3 O *-« _J O U. Z 0-

uj O *-

V> X E KUi O O

U.' uj 3 X 1 O

or OC»K A. -J

00000000000000000000000000000000000000000000 00000000000000000000000000000000000000000000 00000000000000000000000000000000000000000000 OOOOOOOOO©©©*©*©*©©*******©**©©**©**©*©**©** • • • • c • • • •0HN(n4»«Mi90H^<n4tfN4)M>a0HN(n«»«M>e0HNm^

I

0

Example

of

DEMOD

output
LOCATION

OF

IERO

IS

GIVEN

BY

PLOT

CHARACTER

0

-

6.2832

-

9.0269

-

1.7699

-

2.9133

-

1.2966

.

000 ®

1.2566

2.5133

3.7699

5.0265

6.2832

lf5 00O

(XUJ

1 M N N M M M M l

i £ eo ffi ffi e <s

<® m < ^ <*, <« < < <5 <«S

*=“=©©© © © © < ^oGoodooooedeeeoeoeoQeeooeeooeoeeoeo 1

i

a

•H

pH

^ 0B ffi «B i

I

9

9

I

9

9 w

fl WWMNW«WIW9=)N1MNWC

©GGOOGOGOGOOOOOOOOGGOOeOOeGOOOOOOOOOOOOOOOOO OOOOOOOOOOOOOOOOOOOOOOOOOOOOQOOOOOOOOOOOOOOO OOOOOOOOOOOOGOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO ©©©©©©©©© ®©®«®®®®®®®®®®« • ••©••©•••••#•#•••••

1 1-8

u

Example

of

DEM0D

output

(continued)
' G. Acknowledgments

The code for performing the complex demodulation was adapted from the

subroutines given on pages 147 to 150 of Bloomfield [1976].

11-9

CHAPTER 12

CORRELATION AND SPECTRUM ANALYSIS

A. Introduction

STARPAC contains 50 subroutines for time series correlation and spectrum

estimation. Both univariate and bivariate series can be analyzed. Included

are subroutines that compute the correlation function using the fast Fourier

transform and that accept time series with missing observations. The user may

choose from spectrum analysis subroutines implementing the classical Fourier

transformed covariance function techniques presented in Jenkins and Watts

[1968], the autoregressive or rational spectrum techniques described by Jones

[1971] or the direct Fourier transform (periodogram) techniques discussed in

Bloomfield [1976]

.

Users are directed to §B for a brief description of the subroutines. The

declaration and CALL statements are given in §C and the subroutine arguments

are defined in §D. The algorithms used and output produced by these

subroutines are discussed in §E. Sample programs and their output are shown

in §F.

B. Subroutine Descriptions

STARPAC correlation and spectrum analysis subroutines are divided into

seven families. For correlation analysis of univariate and bivariate series

there are two families of subroutines supporting

1. Autocorrelation Analysis and

2. Cross Correlation Analysis.

For spectrum estimation there are four families of subroutines for univariate

series and one family for bivariate series supporting

3. Univariate Spectrum Estimation Using the Fourier Transform of the

Autocorrelation Function,

4. Univariate Spectrum Estimation Using Autoregressive Models,

5. Univariate Spectrum Estimation Using the Direct Fourier Transform,

6. Univariate Series Utilities and

7. Bivariate Spectrum Estimation Using the Fourier Transform of the

Cross Correlation Function.

In general, each family of subroutines has one basic subroutine which

performs the desired computations with a minimum of user input. The other

subroutines in each family provide greater flexibility to the user at the

price of more input. The features of these subroutines are indicated by the

suffix letter(s) on the subroutine (e.g., ACFM and BFSFS ) . Not all features

are available for each family. Features which are common to more than one family are described here. Features which are unique to a specific family are described in the subsections below.

o Suffix S indicates that the user is allowed to specify various options

which are preset in the simplest call and that certain results are

12-1
returned to the user via the subroutine CALL statement. In the subsections that follow, the specific details of this feature are discussed individually for each family of subroutines.

• Suffix M indicates that the series contains missing data. A missing

value code must be used within the series to specify time points

without an observed value. There is no limit on the percentage of data

that can be missing. However, because the correlation matrix computed

from a series with missing values is not necessarily positive definite,

the partial autocorrelation function estimates and autoregressive order

selection statistics are not computed and caution must be used in

interpreting those results which are provided. Analysis of time series

with missing values is discussed in Jones [1971],

• Suffix F indicates that the covariances are computed using the

Singleton [1969] fast Fourier transform (FFT). When the number of

observations in the series is large this method of computation is more efficient than the direct computation normally used by STARPAC.

Subroutines with an F suffix reduce the amount of workspace needed by

using the vector originally containing the data as workspace; the data

must be copied into another vector prior to calling these subroutines

if the data are to be preserved. These subroutines automatically

extend the length of the input series by appending enough zeros to meet

the requirements of this FFT code; the length of the vector used to

pass the data to these subroutines must therefore equal or exceed the

extended series length, NFFT, as discussed in §D.

® Suffix V indicates that the user inputs the covariances rather than the

original series, thus avoiding a time-consuming recoraputation of the

covariance function if it is already available, for example, from

subroutines ACFS, ACFFS, ACFMS , CCFS, CCFFS or CCFMS.

B . 1 Correlation Analysis

B.l.a Univariate Series

Autocorrelation Analysis . STARPAC ' s autocorrelation function (acf)

subroutines compute and plot the autocorrelation function estimates; compute

the large lag standard error of the estimates; perform a chi-squared test of

the null hypothesis that the series is white noise; compute the partial

autocorrelation function coefficients estimates; and, using the modified

Akaike information criterion [Akaike, 1974] , select the order of an autoregressive process which models the series and estimate the parameters of

this autoregressive model. The user should note that a purely autoregressive

model may approximate the true structure of the model with an unnecessarily

large number of terms. Such an autoregressive model must be used with

discretion since the true structure might actually be more complex including

moving average components, harmonic terms or some mixture of deterministic and

stochastic elements. For some purposes, a purely autoregressive approximation

may be useful. In other cases, careful model identification can lead to the

discovery of more detailed structure of the data or to a more parsimonious

model.

12-2
The simplest of the Autocorrelation Function subroutines is ACF, which

performs the basic analysis described in the preceding paragraph. The other

autocorrelation analysis subroutines provide the same basic analysis as ACF

while adding the features indicated above by suffixes S, M, F, MS and FS.

For the ACF family of subroutines, the suffix S feature allows the user

to indicate:

1) the maximum lag value for which the correlation function is to be

computed; and

2) the amount of printed output.

The acf subroutines with suffix S also return the autocovariance function

estimates and the coefficients of the selected autoregressive model to the

user via the subroutine CALL statement.

The ACF family of subroutines also includes subroutine ACFD, where the

suffix D indicates that the autocorrelation analysis will be performed for a sequence of differenced series. The difference factors are provided by the user. If the number of difference factors, NFAC, is greater than one,

difference factors beyond the first are applied to the input series Y(t) to

yield a series Z(t) given by

NFAC

Z(t) = { n (i

J=2

fi IOD( J

) j ND( J)| Y(t)

where the Bk indicates the backward shift operator defined by

Bk Y(t

)

= Y(t-k)

and IOD and ND are defined in §D. If the number of difference factors is

equal to one, Z(t) = Y(t). In either case, the autocorrelation analysis is

performed first on the series Z and then on series Z with the difference

factor (l - applied 1 to ND(1) times. This produces ND(1) + 1 passes

of the basic ACF analysis.

B.l.b Bivariate Series

Cross Correlation Analysis . STARPAC's cross correlation analysis

subroutines compute and plot the cross correlation function coefficients and

provide the large lag standard error of these estimates. Subroutine CCF is

the simplest of the Cross Correlation Function subroutines. The other five cross correlation analysis subroutines provide the same basic analysis as CCF

while adding the features indicated above by suffixes S, M, F, MS and FS.

For the CCF family of subroutines, suffix S indicates that the analysis

is provided for each pair of series of a multivariate time series. The suffix

S feature also allows the user to indicate:

12-3
1) the maximum lag value for which the correlation function is to be

computed; and

2) the amount of printed output.

In addition, the cross covariance function estimates are returned to the user.

B . 2 Spectrum Estimation

B.2.a Univariate Series

Univariate Spectrum Estimation Using the Fourier Transform of the

Autocorrelation Function . The UFS (Univariate Fourier Spectrum) subroutine

family computes the estimated spectrum from the Fourier transform of the

autocovariance function (acvf) as discussed in Jenkins and Watts [1968], The

spectrum is smoothed using Parzen windows with the bandwidth controlled either

by the user or a window-closing algorithm. The principal output from each of

these subroutines consists of plots of the estimated spectrum.

Subroutine UFS has the simplest CALL statement of this family of

subroutines. The printed output consists of four spectrum plots with

successively narrower bandwidths. Each spectrum is displayed in decibels (10

times the base 10 logarithm of the power spectrum) scaled so that the maximum

value plotted is zero. The length of the upper and lower 95-percent

confidence intervals and the bandwidth for each spectrum are shown on the

plots.

The other nine univariate Fourier spectrum estimation subroutines provide

the same basic analysis as UFS while adding the features indicated above by

suffixes S, M, F, V, FS, MS, VS, MV and MVS.

For the UFS family of subroutines, the suffix S feature allows the user

to indicate:

1) the number of different window bandwidths to be used and the lag

window truncation point for each;

2) the frequency range and the number of frequencies for which the

spectrum is to be computed; and

3) whether the plot is to be in decibels or on a logarithmic scale.

In addition, the spectrum values are returned to the user.

Univariate Spectrum Estimation Using Autoregressive Models . STARPAC

Univariate Autoregressive Spectrum estimation subroutines (UAS family)

approximate an input series with an autoregressive model and compute the

corresponding theoretical spectrum for that model. For comparative purposes,

the plot of the autoregressive spectrum is superimposed against a Fourier

spectrum plot.

Subroutine UAS is the simplest of the autoregressive spectrum estimation

subroutines. It uses the modified Akaike information criterion [Akaike, 1974]

to select the order of the autoregressive model to be used. The autoregressive coefficients are then computed from the autocovariance function using the

Levinson-Durbin recursive method [Box and Jenkins, 1976] for solving the

12-4
Yule-Walker equations. The lag window truncation point used for the Fourier

spectrum is half the maximum truncation point which would have been selected

by subroutine UFS. [See §D, argument LAGS.] The output consists of several

autoregressive order selection statistics and a plot of the autoregressive and

Fourier spectra in decibels (10 times the base 10 logarithm of the power

spectrum) scaled such that the maximum value plotted is zero. The bandwidth

and the length of the 95-percent confidence interval for the Fourier spectrum

are shown on the plot. This Fourier spectrum and its confidence intervals

should be used in interpreting the autoregressive spectrum since confidence

intervals are not computed by STARPAC for the autoregressive spectrum. (The

bandwidth is not relevant to the autoregressive spectrum.

)

The other five autoregressive spectrum subroutines provide the same basic

analysis as subroutine UAS while adding the features indicated above by

suffixes S, F, V, FS and VS.

For the autoregressive spectrum family of subroutines, the suffix S

feature allows the user to indicate;

1) the order of the autoregressive model to be used for the autoregressive spectrum;

2) the lag window truncation point to be used for the Fourier spectrum;

3) the frequency range and the number of frequencies within this range

at which the spectrum is to be computed; and

4) whether the plot is to be in decibels or on a logarithmic scale.

In addition, the autoregressive and Fourier spectra are returned to the user. The user should be cautious about using high order models without checking

order selection statistics since such models can produce spurious peaks in the

spectrum.

Univariate Spectrum Estimation Using the Direct Fourier Transform . The

STARPAC direct Fourier transform subroutines (PGM family) implement the

PeriodoGraM approach to time series analysis discussed in Bloomfield [1976],

Subroutines are included for computing the raw periodogram and for computing

and plotting the integrated periodogram (or cumulative spectrum).

Subroutine PGM computes the periodogram of the series as described for

argument PER in §D using zeros to extend the length of the input series.

Output consists of a plot of the computed periodogram in decibels (10 times

the base 10 logarithm of the periodogram estimates) scaled so that the maximum

value plotted is zero. The input series must be either centered or tapered by

the user before PGM is called.

PGMS provides the same basic analysis as PGM but allows the user to

indicate:

1) whether zeros or the series mean is used to extend the series;

2) the length of the extended series; and

3) the amount of printed output.

In addition, the periodogram values and their frequencies are returned to the

user via the subroutine CALL statement.

12-5
The integrated periodogram subroutine IPGM first subtracts the series

mean from the series, then extends the input series with zeros and finally

computes the normalized integrated periodogram. Output consists of a one-page

plot of the integrated periodogram, accompanied by 95-percent contours for

testing the null hypothesis of white noise. The integrated periodogram is

discussed in chapter 8 of Box and Jenkins [1976].

The other three integrated periodogram- subroutines add the features

indicated by suffixes S, P and PS. The suffix S option allows the user to

control the amount of printed output; the integrated periodogram values and

their corresponding frequencies are also returned to the user via the

subroutine CALL statement. The suffix P option indicates that the user inputs

the periodogram rather than the original series, thus avoiding a time-consuming recomputation of the periodogram if it is already available,

for example, from subroutine PGMS.

Utilities . STARPAC includes utility subroutines for centering

(subtracting the mean) and tapering the observed series, periodogram smoothing

and for computing the Fourier coefficients of the series. These routines are particularly useful when using direct Fourier techniques such as PGM and

IPGM.

Subroutine CENTER subtracts the series mean from the series and returns

the centered series. There is no printed output.

Subroutine TAPER centers the input series and applies the splitcosine-bell taper described for argument YT in §D. The user specifies the

total proportion of the series to be tapered. The centered tapered series is

returned to the user and can be used as input to subroutine PGM or PGMS.

There is no printed output.

Subroutine FFTLEN computes for an observed series length, N, the minimum

extended series length, NFFT, which will meet the requirements of the

Singleton FFT code. The value of the extended series length is returned to

the user. There is no printed output.

Subroutine MDFLT smooths the input periodogram by applying a sequence of

modified Daniell filters as discussed in chapter 7 of Bloomfield [1976], The

filtered series is returned to the user. There is no printed output.

Subroutine MDFLT takes advantage of the symmetry of the periodogram to avoid

losing values from the ends of the series. It should therefore not be used

for input series that are not symmetric about their end values. Other digital

filtering routines, such as those described in chapter 10, may also be used

for periodogram smoothing but end effect losses will be incurred.

Subroutine FFTR computes the Fourier coefficients of an input series of

single precision observations. There is no printed output.

12-6
B.2.b Bivariate Series

Bivariate Spectrum Estimation Using the Fourier Transform of the Cross

Correlation Function . The BFS (Bivariate _Fourier Spectrum) subroutine family

computes the estimated spectrum from the Fourier transform of the covariance

function as discussed in Jenkins and Watts [1968]. The spectrum is smoothed

using Parzen windows with the bandwidth controlled either by the user or a window-closing algorithm. The principal output from each of these subroutines

consists of plots of the squared coherency and phase components of the cross spectrum.

Subroutine BFS provides the basic analysis with a brief CALL statement.

The printed output consists of four spectrum plot pairs (a squared coherency

plot and a phase plot) with successively narrower bandwidths chosen by the

window-closing algorithm. The upper and lower 95-percent confidence intervals

and the 95-percent significance levels are shown on the coherency plots.

The other nine bivariate Fourier spectrum estimation subroutines provide

the basic analysis described for BFS while adding the features indicated above

by suffixes S, M, F, V, FS, MS, VS, MV and MVS.

For the BFS family of subroutines, the suffix S feature allows the user

to indicate:

1) the number of different window bandwidths to be used and the lag

window truncation point for each;

2) the frequency range and the number of frequencies for which the

spectrum is to be computed; and

3) whether the plot is to be in decibels or on a logarithmic scale.

In addition, the squared coherency and phase values are returned to the user.

C . Subroutine Declaration and CALL Statements

NOTE: Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

Subroutines for Autocorrelation Analysis

ACF: Compute and print a two-part autocorrelation analysis of a series

<real> Y (n)

1CALL ACF (Y, N)

12-7
ACFS: Compute and optionally print a two-part autoaorrelation analysis of

a series using user- supplied control values; return autocovariance

function and order and parameter estimates of selected autoregressive

model

<real> Y (n), ACOV

(

lagmax+1 ) , PHI {lagmax)

DOUBLE PRECISION DSTAK {Idstak)

COMMON / CSTAK/ DSTAK

CALL ACFS (Y, N, LAGMAX, LACOV, ACOV, IAR, PHI, NPRT , LDSTAK)

ACFM: Compute and print a two-part autocorrelation analysis of a series

with missing observations

<real> Y (n)

CALL ACFM (Y, YMISS, N)

ACFMS: Compute and optionally print a two-part autocorrelation analysis

of a series with missing observations using user- supplied control

values; return autocovariance function

INTEGER NLPPA (lagmax+1)

<real> Y(n), ACOV (lagmax+1)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL ACFMS (Y, YMISS, N, LAGMAX, LACOV, ACOV, AMISS, NLPPA, NPRT,

1 LDSTAK)

ACFF: Compute and print a two-part autocorrelation analysis of a series;

use FFT for computations; return autocovariance function and order

and parameter estimates of selected autoregressive model

<real> YFFT{nfft)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL ACFF (YFFT, N, LYFFT, LDSTAK)

12-8
ACFFS: Compute and optionally print a two-part autocorrelation analysis of

a series using user-supplied control values; use FFT for

computations; return autocovariance function and order and parameter

estimates of selected autoregressive model

<real> YFFT (nfft), A.COV (l agmax+1 ) , ?H.I(lagmax)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL ACFFS (YFFT, N, LYFFT, LDSTAK, LAGMAX, LACOV, ACOV, IAR, PHI,

I NPRT)

ACFD: Compute and print a two-part autocorrelation analysis of a

differenced series

INTEGER ND (nfac) t lOD(nfac)

<real> Y(n)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL ACFD (Y, N, LAGMAX, NFAC, ND, IOD, LDSTAK)

Subroutines for Cross Correlation Analysis

CCF: Compute and print a two-part cross correlation analysis of a pair of

series

<real> Yl(n), Y2(rc)

CALL CCF (Yl, Y2 , N)

CCFS: Compute and optionally print a two-part cross correlation analysis

of a multivariate series using user-supplied control values; return

cross covariance function

<real> YM (n,m), CCOV (l agmax+1 3 m> m)

DOUBLE PRECISION DSTAK(ldstak)

COMMON /CSTAK/ DSTAK

CALL CCFS (YM, N, M, IYM , LAGMAX, CCOV, ICCOV, JCCOV,

1 NPRT, LDSTAK)

12-9
CCFM:

CCFMS:

CCFF:

CCFFS:

Compute and print a two-part cross correlation analysis of a pair of

series with missing observations

<real> Yl(n), Y2(n)

CALL CCFM (Yl, YMISS1 , Y2, YMISS2, N)

Compute and optionally print a two-part cross correlation analysis

of a multivariate series with massing observations using user- supplied control values; return cross covariance function

INTEGER NLPPC (lagmax+1 3 m3 m)

<real> YM(n3 m), YMMISS(tfz), CCOV (l agmax+1 9 m3 m)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL CCFMS (YM, YMMISS, N, M, IYM, LAGM.AX , CCOV, CMISS,

1 ICCOV, JCCOV, NLPPC , I NLPPC , JNLPPC , NPRT , LDSTAK)

Compute and print a two-part cross correlation analysis of a pair of

series; use FFT for computations

<real> YFFT1 (nfft)

,

YFFT2 (nfft)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL CCFF(YFFT1, YFFT2 , N, LYFFT, LDSTAK)

Compute and optionally print a two-part cross correlation analysis

of a multivariate series using user-supplied control values; use FFT

for computations; return cross covariance function

<real> YMFFT (nfft3 m), CCOV (l agmax+1 3 m3 m)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL CCFFS (YMFFT, N, M, IYMFFT, LAGMAX, CCOV,

1 ICCOV, JCCOV, NPRT, LDSTAK)

12-10
Subroutines for Univariate Spectrum Estimation

Using the Fourier Transform of the Autocorrelation Function

UFS: Compute and print a univariate Fourier spectrum analysis of a series

<real> Y (n)

CALL UFS (Y, N)

UFSS: Compute and optionally print a univariate Fourier spectrum analysis

of a series using user-supplied control values; return Fourier

spectrum and corresponding frequencies

INTEGER LAGS (raj)

<real> Y(n), SPCF(n/,raj) , FREQ(n/)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL UFSS (Y, N, NW, LAGS , NF , FMIN, FMAX , NPRT, SPCF, ISPCF,

1 FREQ, LDSTAK)

UFSF: Compute and print a univariate Fourier spectrum analysis of a series

;

use FFT for computations

<real> YFFT (nfft)

DOUBLE PRECISION DSTAK

(

Idstak ) COMMON /CSTAK/ DSTAK

CALL UFSF (YFFT, N, LYFFT, LDSTAK)

UFSFS: Compute and optionally print a univariate Fourier spectrum analysis

of a series using user*- supplied control values; use FFT for computations; return Fourier spectrum and corresponding frequencies

INTEGER LAGS (nw)

<real> YFFT(nfft ) , SPCF (nf,nw), FREQ (nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL UFSFS (YFFT, N, LYFFT, LDSTAK, NW , LAGS, NF , FMIN, FMAX, NPRT,

1 SPCF, ISPCF , FREQ)

12-1

1
UFSM: Compute and print a univariate Fourier spectrum analysis of a series

with missing observations

<real> Y(n)

CALL UFSM (Y, YMISS, N)

UFSMS: Compute and optionally print a univariate Fourier spectrum analysis

of a series with missing observations using user- supplied control

values; return Fourier spectrum and corresponding frequencies

INTEGER LAGS (raj)

<real> Y (n)

,

SPCF( nf3 nw), FREQ(nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL UFSMS (Y, YMISS , N, NW , LAGS , NF , FMIN, FMAX, NPRT, SPCF,

1 ISPCF , FREQ, LDSTAK)

UFSV: Compute and print a univariate Fourier spectrum analysis of a series;

input covariances rather than original series

<real> ACOV(lagmax+1)

CALL UFSV (ACOV, LAGMAX, N)

UFSVS: Compute and optionally print a univariate Fourier spectrum analysis

of a series using user-supplied control values; input covariances

rather than original series; return Fourier spectrum and corresponding frequencies

INTEGER LAGS (nw)

<real> kCOV (lagmax+1 ) , SPCF (nf9 nw)> FREQ (nf)

DOUBLE PRECISION DSTAK( Idstak)

COMMON /CSTAK/ DSTAK

CALL UFSVS (ACOV, LAGMAX, N, NW , LAGS, NF, FMIN, FMAX,

1 NPRT, SPCF, ISPCF, FREQ, LDSTAK)

12-12
UFSMV : Compute and print a univariate Fourier spectrum analysis of a series

with missing observations; input covariances rather than original

series

INTEGER WLPPA (l agmax+1 ) <real> ACOV (lagmax+1)

CALL UFSMV (ACOV, NLPPA , LAGMAX, N)

UFSMVS: Compute and optionally print a univariate Fourier spectrum analysis

of a series with missing observations using user-supplied control

values; input covariances rather than original series; return Fourier

spectrum and corresponding frequencies

INTEGER NLPPA (lagmax+1)

<real> ACOV {lagmax+1 ) , SPCF (nf,nw), FREQ (nf)

DOUBLE PRECISION DSTAK( Idstak)

COMMON /CSTAK/ DSTAK

CALL UFSMVS (ACOV, NLPPA, LAGMAX, N, NW , LAGS, NF , FMIN,

1 FMAX, NPRT, SPCF, ISPCF, FREQ, LDSTAK)

Subroutines for Univariate Spectrum Estimation Using Autoregressive Models

UAS: Compute and print a univariate autoregressive spectrum analysis of a series

<real> Y(n)

CALL UAS (Y, N)

UAS’S: Compute and optionally print a univariate autoregressive spectrum

analysis of a series using user-supplied control values; return

autoregressive and Fourier spectrum and corresponding frequencies

<real> Y(w), PHI (lagmax) t SPCF (nf), SPCA(nf), FREQ (nf)

DOUBLE PRECISION DSTAK

(

Idstak

)

COMMON /CSTAK/ DSTAK

CALL UASS (Y, N, IAR, PHI, LAGMAX, LAG, NF , FMIN, FMAX, NPRT,

1 SPCA, SPCF, FREQ, LDSTAK)

12-13
UASF: Compute and print a univariate autoregressive spectrum analysis of a series; use FFT for computations

<real> YFFT (nfft)

DOUBLE PRECISION DSTAK {Idstak)

COMMON / CSTAK/ DSTAK

CALL UASF(YFFT, N, LYFFT, LDSTAK)

UASFS: Compute and optionally print a univariate autoregressive spectrum

analysis of a series using user- supplied control values; use FFT for

computations; return autoregressive and Fourier spectrum and

corresponding frequencies

<real> YFFT (nfft), PHI (lagmax), SPCA(nf), SPCF(nf), FREQ(rz/)

DOUBLE PRECISION DSTAK {Idstak)

COMMON /CSTAK/ DSTAK

CALL UASFS (YFFT, N, LYFFT, LDSTAK, IAR, PHI, LAGMAX, LAG, NF , FMIN,

1 FMAX , NPRT, SPCA, SPCF , FREQ)

UASV: Compute and print a univariate autoregressive spectrum analysis of a series; input covariances rather than original series

<real> ACOV ( lagmax+1 )

%CALL UASV (ACOV, LAGMAX, N)

UASVS: Compute and optionally print a univariate autoregressive spectrum

analysis of a series using user-supplied control values; input

covariances rather than original series; return autoregressive and

Fourier spectrum and corresponding frequencies

<real> AGOV (lagmax+1 )

,

Y (n), PHI (lagmax)

<real> SPCA(n/), SPCF(nf), FREQ(nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL UASVS (ACOV, LAGMAX, Y, N, IAR, PHI, LAG, NF , FMIN,

1 FMAX, NPRT, SPCA, SPCF, FREQ, LDSTAK)

12-14
Subroutines for Univariate Spectrum Estimation Using the

Direct Fourier Transform

PGM:

PGMS:

IPGM:

IPGMS:

Compute and print a periodogram analysis of a series; use FFT for

computations

<real> YFFT (nfft)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

1CALL PGM (YFFT, N, LYFFT, LDSTAK)

Compute and optionally print a periodogram analysis of a series; use

FFT for computations; return periodogram and corresponding frequencies

<real> YFFT (nfft) t PER(nf), FREQ (nf)

CALL PGMS (YFFT, N, NFFT, LYFFT, IEXTND, NF , PER, LPER, FREQ,

1 LFREQ, NPRT)

Compute and print an integrated periodogram analysis of a series;

use FFT for computations

<real> YFFT (nfft)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL IPGM (YFFT, N, LYFFT, LDSTAK)

Compute and optionally print an integrated periodogram analysis of a series; use FFT for computations; return integrated periodogram and

corresponding frequencies

<real> YFFT (nfft), PERI (nf), FREQ (nf)

DOUBLE PRECISION VSTAK(ldstak)

COMMON /CSTAK/ DSTAK

CALL IPGMS (YFFT, N, LYFFT, LDSTAK, NF , PERI, LPERI , FREQ, LFREQ,

1 NPRT)

12-15
IPGMP:

IPGMPS:

CENTER:

TAPER:

FFTLEN

Compute and print an integrated periodogram analysis of a series

;

input periodogram rather than original series

<real> PER (nf), FREQ(nf)

DOUBLE PRECISION DSTAK

(

Idstak ) COMMON /CSTAK/ DSTAK

iCALL IPGMP (PER, FREQ, NF , N, LDSTAK)

Compute and optionally print an integrated periodogram analysis of a series; input periodogram rather than original series; return integrated periodogram and corresponding frequencies

<real> PER(nf), FREQ (nf) , PERI(nf)

DOUBLE PRECISION DSTAK

(

Idstak)

COMMON /CSTAK/ DSTAK

SCALL IPGMPS (PER, FREQ, NF, N, LDSTAK, PERI, NPRT)

Utility Subroutines

Subtract the series mean from each observation of a series; return

the centered series ( no printed output)

<real> Y («), YC(«)

£CALL CENTER (Y, N, YC)

Center a series about its mean and apply a split-cosine-bell taper;

return the tapered series ( no printed output)

<real> Y(n), YT(n)

SCALL TAPER (Y, N, TAPERP, YT)

Compute the minimum extended series length for using the Singleton

FFT; return the extended series length ( no printed output)

CALL FFTLEN (N, NDIV, NFFT)

12-16
MDFLT: Smooth a periodogram by applying a sequence of modified Daniell

filters; return the smoothed periodogram (no printed output)

INTEGER KMD (nk ) <real> PER(n/), PERF(nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL MDFLT (PER, NF , NK, KMD, PERF, LDSTAK)

FFTR: Compute the Fourier coefficients of an input series of REAL (single

precision) observations; return the Fourier coefficients (no printed

output)

<r eal> YFFT(n), kB(nfft)

CALL FFTR ( YFFT, N, NF FT, IEXTND, NF , AB, LAB)

Subroutines for Bivariate Spectrum Estimation Using the

Fourier Transform of the Cross Correlation Function

BFS: Compute and print a bivariate Fourier spectrum analysis of a pair of

series

<real> Yl(n), Y2(n)

CALL BFS (Yl, Y2, N)

BFSS: Compute and optionally print a bivariate Fourier spectrum analysis

of a pair of series using user-supplied control values; return

squared coherency and phase components of the cross spectrum and the

corresponding frequencies

INTEGER LAGS (nw)

<real> Yl(n), Y2(n), CSPC2 (nf,nw), PHAS (nf,nw), FREQ(nf)

DOUBLE PRECISION DSTPK (Idstak)

COMMON /CSTAK/ DSTAK

CALL BFSS (Yl, Y2, N, NW , LAGS, NF , FMIN, FMAX , NPRT,

1 CSPC2, ICSPC2 , PHAS, IPHAS, FREQ, LDSTAK)

12-17
BFSF: Compute and print a bivariate Fourier spectrum analysis of a pair of

series; use FFT for computations

<real> YFFT1 (nfft ) , YFFT2(n//t)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL BFSF (YFFT1 , YFFT2 , N s LYFFT, LDSTAK)

BFSFS: Compute and optionally print a bivariate Fourier spectrum analysis

of a pair of series using user-supplied control values; use FFT for

computations; return squared coherency and phase components of the

cross spectrum and the corresponding frequencies

INTEGER LAGS (nw)

<real> YFFT1 (nfft ) , YFFT2(rc//t) , CSPC2(n/,nw) , PHAS (nf, nw )

,

1 FREQ (nf)

DOUBLE PRECISION DSTMH(ldstak)

COMMON /CSTAK/ DSTAK

CALL BFSFS (YFFT1 , YFFT2 , N, LYFFT, LDSTAK, NW, LAGS,

1 NF, FMIN, FMAX, NPRT, CSPC2 , ICSPC2 , PHAS, IPHAS, FREQ)

BFSM: Compute and print a bivariate Fourier spectrum analysis of a pair of

series with missing observations

<real> Yl(n), Y2(n)

*CALL BFSM (Y1 , YMISS1 , Y2, YMISS2 , N)

BFSMS: Compute and optionally print a bivariate Fourier spectrum analysis

of a pair of series with missing observations using user-supplied

control values; return squared coherency and phase components of the

cross spectrum and the corresponding frequencies

INTEGER LAGS(nw)

<real> Yl(n), Y2(n), CSPC2(n/,nw ) , PHAS (n.f, nw ) , FREQ (nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL BFSMS (Yl, YMISS1, Y2, YMISS2 , N, NW , LAGS, NF , FMIN,

1 FMAX, NPRT, CSPC2 , ICSPC2 , PHAS, IPHAS, FREQ, LDSTAK)

12-18
BFSV: Compute and print a bivariate Fourier speotrum analysis of a pair of

series; input covariances rather than original series

<real> CCOV (lagmax+1 ,m,m)

CALL BFSV (CCOV, INDEX 1, INDEX2 , N, LAGMAX, ICCOV, JCCOV)

BFSVS : Compute and optionally print a bivariate Fourier speotrum analysis

of a pair of series using user-supplied control values; input

oovariances rather than original series; return squared coherency and

phase components of the cross spectrum and the corresponding frequencies

INTEGER LAGS (jiw)

<real> CCOV (l agmax+1 , m, m) , CSPC2 (nf,nw), PHAS {nf, nw ) , FREQ (nf ) DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

CALL BFSVS (CCOV, INDEX1, INDEX2 , N, ICCOV, JCCOV,

1 NW, LAG, NF, FMIN, FMAX, NPRT, CSPC2 , ICSPC2 , PHAS, IPHAS,

2 FREQ, LDSTAK)

BFSMV: Compute and print a bivariate Fourier spectrum analysis of a pair of

series with missing observations; input covariances rather than

original series

INTEGER WLBVC (lagmax+l,m,m)

<real> CCOV( lagmax+1 ,m,m)

CALL BFSMV (CCOV,

1 LAGMAX, ICCOV,

NLPPC , INDEX 1 , INDEX2, N,

JCCOV, INLPPC , JNLPPC

)

12-19
BFSMVS: Compute and optionally print a bivariate Fourier spectrum analysis

of a pair of series with missing observations using user- supplied

control values; input covariances rather than original series; return

squared coherency and phase components of the cross spectrum and the

corresponding frequencies

INTEGER NLPPC(Z.agmax+1 ,m,m) y LAGS(nw)

<real> CCOV(ns m,m), CSPC2 (nf,nw), PHAS (nf,nw), FREQ(nf)

DOUBLE PRECISION DSTAK (Idstak)

COMMON /CSTAK/ DSTAK

CALL BFSMVS (CCOV, NLPPC , INDEX 1 , INDEX2, N, ICCOV

,

1 JCCOV, INLPPC, JNLPPC, NW, LAGS, NF , FMIN, FMAX , NPRT,

2 CSPC2 , ICSPC2 , PHAS, IPHAS, FREQ, LDSTAK)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTES --> indicates that the argument is input to the subroutine and that

the input value is preserved;

<“• indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine; — indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

* ° * indicates that the variable is passed via COMMON.

AB <-- The vector of dimension at least 2«NF that contains the NF real

and the NF imaginary components of the Fourier coefficients of the

input series. The real and imaginary components of the Fourier

coefficients are returned in the REAL (single precision) array AB

stored such that the real and imaginary parts of the complex

Fourier coefficients are

AB(2I-1) + i.AB(2I) for 1=1, ..., NF,

where

i is the complex value (-1) 1/2

; and

NF is the number of harmonic frequencies, NF = NFFT/2.

The vector YFFT used to input the observed series can also be used

in place of the vector AB to conserve storage space.

ACOV — The vector of dimension at least LAGMAX + 1 that contains the

LAGMAX+1 autocovariance function (acvf) estimates for lags i = 0,

. . . , LAGMAX. ACOV is returned from the autocorrelation analysis

subroutines; it is input to the spectrum analysis subroutines. — continued —

12-20
The acvf estimate for lag i, c(i), is defined by

N-i

(N-i). I [(Y(t)-YHY(t+i)-Y>€(t).S(t+i)]

c(i) = c(-i) = t=l

N-i

N l [?(t)«C(t+i)]

t=l

for lags i = 0 to LAGMAX, where

Y is the average of all observed values; and

£(t) is an indicator variable, defined by

£(t) = 1 if Y(t) is observed (Y(t) * YMISS), and

C (t) = 0 if Y(t) is missing (Y(t) = YMISS).

The acvf are stored in ACOV such that ACOV(I) = c(I-l) for I = 1,

. .

. , LAGMAX+1. When there are no missing observations the above

formula for the acvf reduces to that of the usual positive

definite acvf estimator.

AMISS <— The missing value code used within ACOV to indicate that the

autocovariance function at a given lag could not be computed

because of missing data.

CCOV The three-dimensional array of dimension at least LAGMAX+1 by M

by M that contains the cross covariance function (ccvf) estimates.

CCOV is returned by the cross correlation analysis subroutines; it

is input to the spectrum analysis subroutines.

The ccvf estimate, c.si,(i), for lag i between the series stored in

the j cn and k

cn column of YM is defined by

Cjk(i) — ckj

N-i

(N-i) • l [(YM(t,j)-YM i )*(YM(t+i,k)-YMk

)-? i (t).5 k

(t+i)] = t=l

N-i

N- I [5 i (t)-C k (t+i)]

t=l

for lags i = 0, ..., LAGMAX and for series j = 1, ..., M and k =

1 , . . .

,

M, where

YMj is the average of all the observed values for the column

of YM; — continued —

12-21
Fj(t) is an indicator variable, defined by

£j(t) = 1 if YM(t,j) is observed (YM(t,j) t YMMISS(J))

£j(t) = 0 if YM(t , j ) is missing (YM(t,j) = YMMISS(J)) .

When there are no missing observations the above formula for the

ccvf reduces to that of the usual. positive definite ccvf estimator

and when j = k the above formula is that of the autocovariance

function for the series®

The ccvf are stored in CCOV such that

CCOV(I,J,K) = C

j k

(i-1) = ckj (-i+1 ) for I = 1, . .., LAGMAX+1.

The appropriate formulas for the ccvf estimates computed by CCF

and CCFM can be obtained by letting M = 2 and by substituting

Yl(t) for YM(t,l) and Y2(t) for YM(t,2) in the above.

CMISS <— The missing value code used in CCOV to indicate that the cross covariance function at a given lag could not be computed because

of missing data.

CSPC2 <— The matrix of dimension at least NF by NW that contains the

squared coherency component of the cross spectra between two

series, designated j and k, respectively. CSPC2(I,L) contains the

smoothed squared coherency value for the I

1"*1 frequency computed

using the L^ lag point specified in LAGS. The returned values

are expressed as shown below regardless of the plot option

selected.

The estimated smoothed squared coherency component of the cross spectrum is

COSPEC(I,L) 2 + QSPEC(I , L

)

2

CSPC2(I,L) = —

SPCFj (I,L)*SPCFk

(I,L)

for I = 1, . . . , NF and L = 1, . .., NW, where

COSPEC(I,L) is the smoothed co-spectra for the L

1-*1 lag point,

LAGS (L)-l

COSPEC(I,L) = EVEN0 + 2 \ {EVEN

£

Wl U) cos[ 2tt£ (FMIN+A t )] }

; £ = 1

QSPEC(X,L)

point

,

is the smoothed quadrature spectra for the L

th lag — continued —

12-22
LAGS (L)-l

QSPEC(I,L) =2 l

{ ODD^ WL

(£) sin[ 2tt

£

(FMIN+A x )] }

; £=1

W^(£ ) is the Parzen lag window function for the window,

defined by

W(£) = 1 £ =0

W (£) = 1— 6( |£ | /LAGS(L) ) 2 +6( |£ | /LAGS(L)) 3 1< \l |< LAGS (L) /2

W (£) = 2[ 1—( | £ | /LAGS(L))] 3 LAGS (L) /2< | Jl |<LAGS(L)

W(£) =0 LAGS (L)< |£ | ;

A j is the frequency increment,

A t = 2(1 - 1 ) (FMAX - FMIN)/(NF - 1);

EVEN^ and ODD^ are functions of CCOV defined by

EVEffy = CCOV(£+l ,j ,k) + CC0V(£+l,k,j) for £ =0, . .., LAGS (L)

ODD^ = CCOV(£+l,j,k) - CC0V(£+l,k,j) for £ =0, . .., LAGS (L)

;

SPCFj(I,L) and SPCF^CljL) are the univariate Fourier spectrum

estimates for series j and k, respectively, computed using the

Lth lag window truncation point. [See argument SPCF.]

Note that the modifications necessary for series with missing data

are included in the computation of CCOV.

DSTAK ••• The DOUBLE PRECISION vector in COMMON / CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

FMAX •—> The maximum frequency, in cycles per sample interval, at which the

spectrum is to be computed (0.0 < FMIN < FMAX < 0.5). The default

value is 0.5. If FMAX is outside the range FMIN to 0.5 or is not an argument in the CALL statement the default value is used.

FMIN —> The minimum frequency, in cycles per sample interval, at which the

spectrum is to be computed (0.0 < FMIN < FMAX < 0.5). The default

value is 0.0. If FMIN is outside the range 0.0 to FMAX or is not

an argument in the CALL statement the default value is used.

FREQ The vector of dimension at least NF that contains the NF frequency

values at which the spectrum is computed. FREQ is an input

argument to subroutines IPGMP and IPGMPS. The values of FREQ are returned by all other subroutines including it in their CALL

s tatements.

12-23
IAR The order of the autoregressive model chosen to approximate the

series and the order of the autoregressive model to be used in

computing the autoregressive spectrum. IAR is returned by the

autocorrelation subroutines; it is input to the autoregressive

spectrum analysis subroutines.

For the autoregressive spectrum subroutines:

The order IAR of the autoregressive model must not exceed

LAGMAX. In no case may IAR exceed N/2.

If IAR>0, the user must supply the coefficients for the order

IAR autoregressive model in the vector PHI. (These

coefficients are available, for example, from subroutine ACFS and ACFFS or perhaps from the ARIMA model

fitting procedure discussed in chapter 13.)

If IAR<0, the coefficients for the order | IAR | autoregressive

model will be computed by the STARPAC subroutine using

Durbin's recursive method.

If IAR=0, the order and model coefficients will be chosen using

the model selection criteria discussed below in §E.2.b

and the input value of IAR will be overwritten by the

selected value. If the IAR = 0 option is used the

user must specify the order with a variable, i.e.

,

IAR = 0

CALL ASPS ( . . . , IAR, . . .)

NOT

CALL ASPS ( . . . , 0, . . . ).

The latter will cause the value of zero to be

redefined on many computers including the CYBER 840

and 855.

ICCOV —> The exact value of the first dimension of CCOV as specified in the

calling program.

ICSPC2 —> The exact value of the first dimension of CSPC2 as specified in

the calling program.

IERR *** An error flag returned in COMMON /ERRCHK/. [See chapter 1, §D.5.]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

IERR = 0 indicates that no errors were detected.

IERR = 1 indicates that improper input was detected.

12-24
IEXTND

INDEX1

INDEX

2

INLPPC

IOD

IPHAS

ISPCF

XYM

XYMFFT

JCCOV

JNLPPC

KMD

LAB

LACOV

LAG

--> The indicator variable used to designate whether zero or the

series mean is to be used to extend the series. If IEXTND = 0,

zero will be used. If IEXTND * 0, the series mean will be used. —> The index of the first series used in computing the cross covariance function, corresponding to the subscript j used in the

definition of CCOV. —> The index of the second series used in computing the cross covariance function, corresponding to the subscript k used in the

definition of CCOV. —> The exact value of *the first dimension of NLPPC as specified in

the calling program.

--> The vector of dimension at least NFAC that contains the NFAC

values designating the order of each difference factor.

-=-> The exact value of the first dimension of PHAS as specified in the

calling program.

-~> The exact value of the first dimension of SPCF as specified in the

calling program. —-> The exact value of the first dimension of the matrix YM as specified in the calling program.

”-> The exact value of the first dimension of the matrix YMFFT as specified in the calling program.

“-> The exact value of the second dimension of CCOV as specified in

the calling program.

-~> The exact value of the second dimension of NLPPC as specified in

the calling program.

--> The vector of dimension at least NK that contains the NK modified

Daniell filter lengths. All values in KMD must be even.

--> The length of the vector AB. LAB must equal or exceed NFFT.

--> The length of the vectors ACOV and NLPPA. LACOV must equal or exceed LAGMAX + 1.

<-> The lag window truncation point to be used for computing the

Fourier spectrum. The default value is half the maximum

truncation point selected by the algorithm described for the

default values of LAGS. If LAG Is not an argument of the CALL

statement or if LAG is outside the range [1, N— 1 ] the default

value will be used. If the user supplied value for LAG is less — continued —

12-25
than or equal to zero, the Input value will be overwritten by the

selected value . The user must therefore specify the lag window

truncation point with a variable in this case, i.e.

,

LAG = 0

CALL ASPS ( . . . , LAG, . . .

)

NOT

CALL ASPS ( . . « , 0, . . . ).

The latter will cause the value of zero to be redefined on many

computers including the CYBER 840 and 855.

LAGMAX --> The maximum lag value for which the correlation coefficients are computed. The default value of LAGMAX is selected by STARPAC as follows.

LAGMAX = 100 if 301 < N.

LAGMAX = N/3 if 96 < N < 300

LAGMAX = 32 if 33 < N < 95

LAGMAX =• N-l if N < 32

If LAGMAX is less than or equal to zero or if neither LAGMAX nor LAGS is an argument in the CALL statement the default value is

used. When LAGS is an argument in the CALL statement, LAGMAX is

the largest value in LAGS.

LAGS —> The vector of dimension at least NW that contains the NW lag

window truncation points, 1 < LAGS(i) < N-l for i = 1, ... NW. By

default, four lag window truncation points are used. The smallest

lag window truncation point T]^ is selected by examining the

covariance function. It is chosen to be 3/16 times the lag value

beyond which the covariance function remains less than the

95-percent confidence limits for white noise, although in no case

is T^ greater than LAGMAX

/

8 . The values of the remaining lag

window truncation points are then specified by T2 = 2»T^,

T 3 = 4®Tj and T^ = 8 »Tj, resulting in progressively narrower

bandwidths. The procedure of using progressively narrower

bandwidths to compute the spectrum of a given time series is

called window closing. It is discussed in Jenkins and Watts

[1968]. If LAGS is not an argument in the CALL statement the four

default values are used.

LDSTAK --> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below. In the

following specifications of the value of LDSTAK, if the single

precision version of STARPAC is being used P = 0.5, otherwise — continued —

12-26
P = 1.0. [See chapter 1, § B . ] Also, 10 = 0 if NPRT = 0 and

10 = 1 if NPRT * 0.

For autocorrelation subroutine

ACFS : LDSTAK > 12 + [ 5 » LAGMAX + 1

] •

P

ACFMS : LDSTAK > 10.(13 + [6* LAGMAX + i].p)

ACFF : LDSTAK > 6 + NFFT.P

ACFFS : LDSTAK > 12 + [4* LAGMAX + NFFT + 1

] •

P

ACFD: LDSTAK > 16 + [7* LAGMAX + N + 2] • P

For cross correlation subroutine

CCFS : LDSTAK > 12 + [2*M + 10. (4. LAGMAX + 2)]«P

CCFMS : LDSTAK (26+M)/2 + [2«M + 10. (4* LAGMAX + 2) ]•

P

CCFF: LDSTAK > 6 + NFFT.P

CCFFS : LDSTAK > 13 + [NFFT + 2«M + 10. (4. LAGMAX + 2)]»P

For univariate Fourier spectrum subroutine

UFSS : LDSTAK > [26 + I0» (NF+5) ] / 2 +

[2. LAGMAX + 2 + 10* (2. NF+10)] • P

UFSF : LDSTAK > 7 + NFFT.P

UFSFS : LDSTAK > [26 + 10. (NF+5)]/2 + [LAGMAX + 1 + NFFT + I0« (2« NF+10)] «P

UFSMS : LDSTAK > [29 + LAGMAX + 1 + IO-(NF+5)]/2 +

[ 2» LAGSMX + 2 + 10. (2. NF+10)] •

P

UFSVS: LDSTAK > [23 + IO.(NF+5)]/2 + [LAGMAX + 1 + 10* (2. NF+10)] »P

UFSMVS : LDSTAK > [23 + 10* (NF+5) ] / 2 + [LAGMAX + 1 + 10. (2. NF+10)] «P — continued

12-27
For autoregressive spectrum subroutine

UASS

LDSTAK > [32 + I0« (2«NF+5)]/2 +

[ 2 • LAGMAX + 2 + IA» ( 3* LAGMAX+1 ) +

10. (4.NF+10)] .P

UASF

LDSTAK > 7 + NFFT.P

UASFS

LDSTAK > [32 + I0« (2-NF.+5) ] /2 +

[2* LAGMAX + 2 + NFFT + IA. ( 3* LAGMAX+1 ) +

10. (4.NF+10)] *P

UASVS

LDSTAK > [29 + 10- (2. NF+5) ] /2 + [LAGMAX + 1 + IA* (3. LAGMAX+1) +

10. (4.NF+10)] »P

where IA = 0 if IAR t 0 and IA = 1 if IAR = 0.

For direct Fourier spectrum subroutine

PGM: LDSTAK > 9 + NFFT.P

IPGM: LDSTAK > [123 + NFFT/2]/2 + [2* NFFT + 206]*

P

IPGMSLDSTAK > 10. ([123 + NFFT/2]/2 + [2* NFFT + 206]. P)

IPGMPLDSTAK > [126 + NF]/2 + [3«NF + 206].

P

I PGM.PSLDSTAK > 10. ([123 + NF]/2 + [2«NF + 206]. P)

For utility subroutine

MDFLT: LDSTAK > 7 + NF.P

For bivariate Fourier spectrum subroutine

BFSS

;

LDSTAK > [38 + I0*4.NF]/2 + [/.LAGMAX + 7 + IO«8«NF].P

BFSF

;

LDSTAK > 7 + NFFT.P

BFSFSLDSTAK > [38 + IO-4-NFJ/2 +

[6. LAGMAX + 6 + NFFT + IO» 8»NF].P

BFSMSLDSTAK > [45 + 4* LAGMAX + I0.4«NF]/2 +

[7. LAGMAX + 7 + 2-NF + 10*8. NF]-P

BFSVS

LDSTAK > [35 + IO»4«NF]/2 +

[3. LAGMAX + 3 + 2»NF + I0«8«NF].P

BFSMVSLDSTAK > [35 + IO-4.NFJ/2 +

[3. LAGMAX + 3 + 2.NF + 10* 8. NF]»P

LFREQ --> The length of the vector FREQ. LFREQ must equal or exceed NF.

12-28
LPER

LPERI

LYFFT

M

N

ND

NDIV

NF

NFAC

NFFT

—> The length of the vector PER. LPER must equal or exceed NF. —> The length of the vector PERI. LPERI must equal or exceed NF. —> The maximum length allowed for the extended series created in

YFFT. LYFFT must equal or exceed the actual extended series

length, NFFT. If too small a value of LYFFT is used an error

message giving the correct value is generated. —> The number of columns of data in YM. —> The number of time points in each series. For the correlation

analysis subroutines the minimum number of time points is 3; for

the spectrum analysis subroutines the minimum number of time

points is 17. —> The vector of dimension at least NFAC that contains the values

designating the number of times each difference factor is to be

applied. —> A required constant used by FFTLEN to determine the extended

series length. (See NFFT.) NDIV must be two for a simple FFT.

It must be four when the covariance function is being computed.

-> The number of frequencies at which the spectrum is computed.

For the Fourier and autoregressive spectrum subroutines and the

utility subroutines:

NF is an input argument. The default value of NF is 101. If NF

is not an argument of the CALL statement the default value will

be used.

For the direct Fourier spectrum subroutines:

NF is returned by the subroutine. The returned value is NF = NFFT/2. —> The number of difference factors. — The minimum extended series length that meets the requirements of

the Singleton FFT code. NFFT is returned by FFTLEN; it must be

input to PGMS and FFTR; it is computed internally by all of the

other subroutines using the FFT.

The extended length of the series is

NFFT = N + LAGMAX + K

where N is the number of observations in the series. K > 2 is

chosen so that NFFT is as small as possible, NFFT-2 is divisible

by 4 and has no prime factors greater than 23, and the product of

the square-free prime factors of NFFT-2 does not exceed 209. In — continued —

12-29
general, NFFT will be less than N+LAGMAX+100 for the correlation,

Fourier spectrum and autoregressive spectrum subroutines. STARPAC

subroutine FFTLEN, when called using the sequence

NK

NLPPA

NLPPC

NPRT

CALL FFTLEN (N+LAGMAX, NDIV, NFFT)

with NDIV =' 2 when a simple FFT is to be computed and

NDIV = 4 when the covariance function is to be computed,

returns the value of NFFT that is actually used by these

subroutines. —> The number of modified Daniell filters to be applied.

!— The vector of dimension at least LAGMAX+ 1 that contains the

LAGMAX+1 values designating the number of lagged product pairs

used to compute the autocovariance function at each lag,

N-i

NLPPA(I) = l [c(t)«C(t+i>] for i = 0, ...» LAGMAX and I = i + 1 , t=l

where £(t) = 1 if Y(t) * YMISS, and £(t) = 0 if Y(t) = YMISS.

-- The three-dimensional array of dimension at least LAGMAX+1 by M by

M that contains the number of lagged product pairs used to compute

the cross covariance function for each pair of series at each

lag,

N-i

NLPPC(I,J,K) = l [5j(t)€k (t+i>] for i = 0, . .., LAGMAX

t=0 and I = i + 1,

where the indices J and K correspond directly to the subscripts j

and k, respectively, for j — 1 , ..., M and k = 1, ..., M; and

5

j (t) = 1 if YM(t, j)*YMMISS(j) and £j(t) = 0 if YM(t , j )=YMMISS(j

)

.

-> The argument controlling printed output. In each case, when NPRT

is not an argument in the subroutine CALL statement the default

value is used.

For the correlation analysis subroutines:

If NPRT = 0, the printed output is suppressed.

If NPRT £ 0, the printed output is provided.

The default value is NPRT t 0. — continued —

12-30
For the Fourier and autoregressive spectrum analysis subroutines:

NW

PER

If NPRT < -1, the spectra are plotted in decibels on a linear

scale adjusted so that the peak is at zero.

If NPRT = 0, the printed output is suppressed.

If NPRT > 1, the spectra are plotted on a log-linear scale.

The default value is NPRT = -1.

For the periodogram subroutines:

If NPRT < -2, the printed output consists of a page plot of the

periodogram versus frequency on a log-linear

scale.

If NPRT = -1, the printed output consists of a page plot of the

periodogram in decibels on a linear scale.

If NPRT = 0, the printed output is suppressed.

If NPRT = 1, the printed output consists of a vertical plot of

the periodogram in decibels on a linear scale.

The vertical axis shows the frequency in the left

margin.

If NPRT > 2, the printed output consists of a vertical plot of

the periodogram on a log scale. The vertical axis

shows the frequency in the left margin.

The default value is NPRT = -1.

For the integrated periodogram subroutines:

If NPRT = 0, the printed output is suppressed.

If NPRT * 0, the printed output is provided.

The default value is NPRT t 0.

--> The number of different window bandwidths to be used. The default

value is four for the Fourier spectrum subroutines and one for the

autoregressive spectrum subroutines. When NW is not an argument

of the subroutine CALL statement the default value is used.

The vector of dimension at least NF that contains the NF

periodogram values. PER is returned by subroutine PGMS; it must

be input to subroutines IPGMP, IPGMPS and MDFLT. The vector YFFT

used to input the observed series to PGMS can also be used in

place of the vector PER to conserve storage space. (The values in

YFFT will be overwritten even when YFFT is not used in place of

PER. ) — continued —

12-31
The series periodogram is computed at the harmonic frequencies

f k

= k/ (NFFT-2) for k = 0, . .., (NFFT-2)/2

by a direct Fourier transformation of the series using

PER(I) = A(I) 2 + B(I) 2 for 1=1, ..., NF,

where

NF is the number of harmonic frequencies at which the periodogram

is computed, NF = NFFT/2;

A(I) is the real component of the Fourier coefficient,

NFFT

A(X) = (2/(NFFT-2)) J [YCT(t )• cos( 2irt ( 1-1 ) /(NFFT-2)) ]

; t=l

B(I) is the imaginary component of the. Fourier coefficient,

NFFT

B(I) = (2/ (NFFT-2)) J [YCT(t)«sin( 2Trt (1-1 )/ (NFFT-2)) ]

; t=l

YCT(t) is the value of the centered (or tapered) input series at

time t» [See arguments YC and YT„

]

PERF <— The vector of dimension at least NF that contains the NF values of

the periodogram smoothed by applying a sequence of modified

Daniell filters to the raw periodogram. The sequence of filtered

series is

KMD(£)

PERF£ (I) = l [h

£ (j)«PERF£ „ 1 (t I )] for 1 = 1, ..., NF

£ = 1 and £ = 1 , . . . , NK,

where

KMD(£ ) is the number of terms in the £

t51 filter (KMD(£) must be

even) ;

h

£ ( j ) is the j

1-*1 filter coefficient of the £

t ^1 filter, defined by

~ [2®KMD(£)j 1 for j = 1 and KMD(£)

h

£

(j ) = KMD(£)“1 for j = 2, KMD(£)-1;

PERF

£

is the periodgram smoothed using the first £ filters (PERFq

is the input periodogram and PERF^k

is the series actually

returned to the user); — continued —

12-32
tj is index of PERF^_^ defined by

t T = 2-[I+(KMD(£)/2)-l+j] l<I<KMD(£)/2

tj = I-(KMD(£)/2)-l+j (KMD(£)/2)+l<I<N-KMD(£ )/2

t x = 2N-[I+(KMD(£)/2)+l+j ] N-(KMD(£)/2)+l<I<N

PERI <— The vector of dimension at least NF that contains the integrated

periodogram values. The vector YFFT used to input the observed

series to IPGMS may be used in place of the vector PERI to

conserve storage space.

The integrated periodogram is defined by

I PERI( I) = (N® YVAR)TM1 l PER(K) for I = 1, . . . , NF

K=1

where

N _ 2 N

YVAR = (N-l)“l

l (Y(t)-Y) with Y = N"” 1 £ Y(t).

t=l t=l

PHAS <-- The matrix of dimension at least NF by NW that contains the

smoothed phase component of the cross spectra between two series,

designated j and k, respectively. PHAS ( I , L ) contains the phase

value for the I

c ^ frequency computed using the L

t ^1 lag window

truncation point specified in LAGS.

The estimated phase component of the cross spectrum is

QSPEC(I,L) 2

PHAS(I,L) =

COSPEC(I,L) 2

for 1=1, ...,NF and L = 1, NW, where

COSPEC(I,L) is the smoothed co-spectra for the lag point,

LAGS ( L

) —

1

COSPEC(I,L) = EVENq +2 l (EVEN

£

Wl

(£ ) cos[ 2tt£ ( FMIN+A

j )] }

; £ = 1

QSPEC(I,L) is the smoothed quadrature spectra for the L*"^ lag

point,

QSPEC( I, L

)

LAGS (L)-l

2 l {ODDjj Wl

(£) sin[ 2tt£(FMIN+A i )] }

; £= 1 — continued —

12-33
PHI

SPCA

Wl(£) is the Parzen lag window function for the L

1-^ window,

defined by

w(£) = 1 i =o

W(£) = l-6( U|/LAGS(L)) 2 +6( U|/LAGS(L)) 3 U u l<LAGS(L)/2

W(£) = 2[l-( U|/LAGS(L))] 3 LAGS(L)/2< U |< LAGS(L)

W(£) = 0 LAGS(L)<U | ;

Aj is the frequency increment,

A x = 2 • (I-I) • (FMAX-FMIN)/ (NF-1) ; and

EVEN£ and ODD£ are functions of CCOV defined by

EVEN£ - CC0V(£+1, j,k) + CC0V(£+l,k, j) for £ = 0, . .., LAGS(L)

0DD£ = CC0V(£+1, j,k) - CCOV ( £+1 ,k, j) for £ = 0, LAGS(L)

.

— The vector of dimension at least LAGMAX that contains the IAR

coefficients of the order IAR autoregressive model. PHI is

returned by the autocorrelation subroutines; it is input or returned by the autoregressive spectrum estimation subroutines

depending on the value of IAR.

<-•“ The vector of dimension at least NF that contains the NF values of

the autoregressive spectrum. The autoregressive spectrum estimates are defined by

SPCA(I) = S IAR

2

{

1 1 ~ l PHI( £ )«e[ l FtUN + A

: )] | 2

} £=1

for 1=1, . .., NF, where

Star

2 is the residual or one step prediction variance of the order

IAR autoregressive model,

IAR

S IAR

2 = (N-IAR-D-iNjACOVd) - J

[ PHI (£ ) • AC0V(£+1 )

]

} , £=1

i is the complex value (-1) 1/2

; and

Aj is the frequency increment,

A X « 2« (!“!)• (FMAX-FMIN)/ (NF-1

)

. — continued —

12-34
SPCF

TAPERP -

Y

YC <

' — The array of dimension at least NF by NW that contains the NF

values of the Fourier spectrum for each of the NW lag windows.

For the autoregressive spectrum analysis subroutines, NW = 1 and

SPCF may be dimensioned as a vector of length at least NF.

SPCF(I,L) contains the spectrum value for the I

1"*1 frequency

computed using the lag point (see arguments LAG and LAGS).

The returned spectrum values are expressed as shown below

regardless of the plot option selected.

The estimated Fourier spectrum values are

LAGMAX

SPCF(I,L) = AC0V(1) +2 l (ACOVU+1) Wl

(£ ) cos[ 2tt£ (FMIN+A j )] } £ =

1

for I = 1, NF and L - 1, NW, where

W^(£ ) is the Parzen lag window function for the L*-*1 window,

defined by

W(£) = 1 £ =0

W(£) = l-6( | £ | /LAGS (L) ) 2 +6( | £ | /LAGS (L) ) 3 1< |£ |< LAGS (L) /2

W (£) » 2[ l-( | £ | /LAGS (L) ) ] 3 LAGS (L) /2< \l |< LAGS (L)

W (£) =0 LAG S ( L ) < | £ | ;

Aj is the frequency increment,

Aj = 2* ( I— 1

)

• ( FMAX-FMI N ) / ( NF- 1 )

.

Note that the modifications necessary for series with missing data

are included in the computation of ACOV. —> The total proportion of the input data to be tapered using a split-cosine-bell taper. [See argument YT. ] If TAPER < 0.0, the

tapered series is identical to the centered series, YC . If

TAPERP > 1.0, a 100-percent taper is applied to the series.

-> The vector of dimension at least N that contains the N observations of a time series. — The vector of dimension at least N that contains the centered time

series. The centered series is

YC(t ) = Y(t) - Y for t * 1, ..., N

where Y is the mean of the input series — continued —

12-35
Y

N

N

_1

( l

t = l Y(t)).

YFFT <-> The vector of dimension at least NFFT containing the N

observations of a time series to be analyzed using the FFT. The

length of the vector YFFT must be greater than N to allow for

extending the series. Note that the input series is overwritten

by the FFT computations.

YFFT1 <-> The vector of dimension at least NFFT containing the N

observations of the first of a pair of series selected from a multivariate time series to be analyzed using the FFT. The length

of the vector YFFT must be greater than N to allow for extending

the series. Note that the input series is overwritten by the FFT

computations.

YFFT2 <-> The vector of dimension at least NFFT containing the N

observations of the second of a pair of series selected from a multivariate time series to be analyzed using the FFT. The length

of the vector YFFT must be greater than N to allow for extending

the series. Note that the input series is overwritten by the FFT

computations.

YM -> The matrix of dimension at least N by M each of whose M columns

contains the N observations of a multivariate time series.

YMFFT <=> The matrix of dimension at least NFFT by M each of whose M columns

contains the N observations of a multivariate time series to be

analyzed using the FFT. The first dimension of the array YMFFT

must be greater than N to allow for extending the series. Note

that the input series are overwritten by the FFT computations.

YMISS ~“> The missing value code used within the input series Y to indicate

that an observation is missing.

YMISS1 ~“> The missing value code used within the input series Y1 to indicate

that an observation is missing.

YMISS2 --> The missing value code used within the input series Y2 to indicate

that an observation is missing.

YMMISS --> The vector of dimension at least M that contains the M missing

value codes (one for each column) used within each of the M series

contained in YM to indicate that an observation is missing.

YT <-- The vector of dimension at least N that contains the tapered time

series. The tapered series is

YT(t ) = W(t )® YC(t ) for t = 1, ..., N,

where — continued —

12-36
W(t) is the split-cosine-bell taper weight used at time t,

W(t) = 0.5» { l-cos[ir(t-0.5)/m] }

W(t) = 1

W(t) = 0.5» { l-cos[-rr(N-t+0.5)/m].} N-m + 1< t< N

m + 1< t< N-m

1< t< m

with m computed such that 2m/N = TAPERP is the proportion of data

to be tapered. The importance of tapering is discussed in chapter

5 of Bloomfield [1976].

Y

1

--> The vector of dimension at least N that contains the N observations of the first series of a multivariate time series pair.

Y2 —> The vector of dimension at least N that contains the N observations of the second series of a multivariate time series pair.

E . Computational Methods

E. 1 Algorithms

E.l.a Correlation Analysis

The code for computing the autocovariance and cross covariance functions

using a fast Fourier transform are based on subroutines written by Jones

[1971]. The subroutines which compute the fast Fourier transform and which

compute the Fourier transform of real data are those written by Singleton

[1969] and the subroutine to compute the cosine transform was written by

Richard H. Jones. A discussion of the use of the fast Fourier transform for

computing the correlation function can be found on pages 165 to 167 of

Bloomfield [1976]. Zeros are automatically appended to the end of the series

to meet the requirements of computing the correlation function using an FFT.

Correlation function subroutines not using the FFT compute the correlation

function directly using the formulas given in §D for arguments ACOV and CCOV.

The autoregressive model coefficients given are the Yule-Walker estimates, computed as described in Appendix A3. 2 of Box and Jenkins [1976]. This

is not a recommended estimation procedure but rather a means of providing

starting values for a maximum likelihood or least squares estimation procedure. Chapter 13 provides subroutines for estimating the least squares values

of the parameters of an autoregressive model using these starting values.

E.l.b Spectrum Analysis

The transformation used to compute the univariate Fourier spectrum is

performed using the algorithm shown on page 311 of Jenkins and Watts [1968],

modified to correspond to the definition of the spectrum given for argument

SPCF in §D. (The computed spectrum is half that shown in Jenkins and Watts.

)

The bivariate or cross Fourier spectrum is discussed in chapters 8 and 9 of

12-37
Jenkins and Watts. Smoothed squared coherency and phase estimation are discussed in detail on pages 377-380 of Jenkins and Watts. The algorithm used

is described on pages 418-420. The confidence interval and significance test

for coherency is discussed in Bloomfield [1976] on pages 224-228. The

modifications necessary for series with missing data are included in the

computation of the covariance function described in §D under arguments ACOV

and CCOV. Covariance function values computed using a fast Fourier transform

use the FFT code written by Singleton [1968]; a discussion of this technique

for computing the covariance function can be found on pages 165 to 167 of

Bloomfield [1976]. Subroutines using the FFT automatically subtract the

series mean and append zeros to the end of the series to meet the requirements

of computing the covariance function using Singleton's code.

The code for computing the autoregressive order selection statistics and

autoregressive spectrum estimates is based on subroutines written by Jones

[1971], The coefficients PHI(k), k = 1, . .., IAR of the autoregressive model

are computed from the autocovariance function using the Levinson-Durbin

recursive method for solving the Yule-Walker equations discussed in Appendix

A3.2 of Box and Jenkins [1976]. The order of the autoregressive model

selected by STARPAC is that having the lowest Akaike final prediction error

[ Akaike , 1974]

.

Subroutines PGM, XPGM, and IPGMS automatically append zeros to the end of

the series to meet the length requirements of the Singleton FFT code [1969],

Subroutine PGMS and FFTR do not automatically center or extend the input

series. Centering and extending the series by appending either zeros or the

series mean must be done by the user. The resulting computations are wrong if

the extension does not comply with the code requirements.

The subroutines for the split-cosine-bell taper and the modified Daniell

filter operation were adapted from subroutines TAPER and MODDAN given on pages

116 and 178 of Bloomfield [1976].

E .2 Computed Results and Printed Output

Ec2.a Correlation Analysis

The Autocorrelation Subroutines . The argument controlling the printed

output, NPRT, is discussed in §D. The output from the autocorrelation

analysis subroutines includes summary statistics describing the input series;

the autocorrelation function estimates and their large lag standard errors;

the chi-squared test statistic for white noise and its significance level; the

partial autocorrelation function estimates; autoregressive model order selection statistics; and parameter estimates for the selected model. In addition,

plots are provided of the autocorrelation and partial autocorrelation function

estimates.

The estimated coefficients of the autocorrelation function (acf), r(i), are computed with the formula

r(i) = ACOV ( i +1 ) / ACOV ( 1 ) for lag i = 1, ..., LAGMAX

.

12-38
The estimated standard errors (SE) of the acf are the large lag standard

errors discussed on pages 34 to 36 of Box and Jenkins [1976], The standard

error listed at lag i is computed assuming that the acf is zero for lags

greater than i. The formula is given by

SE [r(i ) ] = SE [r(-i) ] =

o 1/2

(N-i)»{(N-i) + 2» £ [ (N-i-v)« r ( v) ]} v=l

N*NLPPA(i+l

)

for i = 1, . .., LAGMAX, where q is the minimum of n - i and i - 1. The user

must select the "correct" large lag standard error based on whether the acf

estimates are compatible with the assumption that the acf is zero for the

selected lag value and beyond. This technique is intended primarily to

provide a means of selecting the largest lag value for which the acf is

significantly different from zero rather than to provide actual standard error

estimates for each acf. The large lag standard error at the selected lag is

valid for all acf estimates at lags greater than or equal to the selected lag;

the standard error estimates for lag values less than the selected lag are meaningless.

As discussed on pages 64-66 of Box and Jenkins [1976], the estimated

partial autocorrelation function (pacf) coefficients, p(i) for i = 1, ..., LAGMAX, are estimates of the i

t ^1 coefficient in an autoregressive process of

order i. Use of the pacf, in conjunction with the acf, to identify an autoregressive moving average process is discussed on pages 174-193 of Box and

Jenkins. It should be noted, however, that the method used to compute the

pacf [discussed in Appendix A3. 2 of Box and Jenkins] is very sensitive to

rounding errors. The pacf estimates may not be reliable if the values of the

parameters are close to the nonstationarity boundaries.

The order IAR of the autoregressive model selected for the series is that

having the lowest Akaike final prediction error [Akaike, 1974]. The modified

Akaike information criteria (AIC) is then computed as

AIC(J) = N.Loge (FPEj) for J = 1, LAGMAX,

where

LAGMAX is the maximum lag value for which the acvf has been estimated and is

therefore the maximum order of autoregressive model which can be

selected;

FPEj is the Akaike final prediction error, normalized so the minimum final

prediction error is one, that is,

FPEj = (Sj2 - (N+J+1))/(SIAR

2 . (N+IAR+1)) ;

2 Sj is the residual or one step prediction variance of the order J

autoregressive model, computed as

12-39
J

Sj2 = (N-J-1)“1 .n*(AC0V(1) -• l PHI( £) «ACOV (£+1) } ; £=1

c

2 S IAR 1S

IAR is

N is

The AIC of

the residual or one step prediction variance of the selected model;

the order of the AR model which produced the minimum AIC;

the number of observations in the series,

the selected model order will always be zero.

The partial F-test of the change in the residual sum of squares is a test

of the null hypothesis that the order J pacf is zero. The F-ratio is given

by

F 1,N-J-1 = (ASj 2 )/Sj 2 = (N-1-J)-PHI(J) 2 /[1-PHX(J) 2

]

where

ASj2 is the change in the residual variance due to the hypothesis that

PHI(J) = 0 (1 degree of freedom),

ASj2 = Sj.!

2 - Sj2

;

S

j

2 is the residual variance of the order J autoregressive model (N-J-l

degrees of freedom)

.

The significance level of each F-ratio is also listed.

The Cross Correlation Subroutines. The argument controlling the printed

outpuT^ NPRT, is discussed in §D« The output from the cross correlation

analysis subroutines includes summary statistics describing the two input

series; the cross correlation coefficient estimates and their standard errors;

and a plot of the cross correlation estimates.

The cross correlation function (ccf) estimate for the pair of series

stored in the j*"*1 and columns of YM is

r

jk

(i) = CCOV ( i+1 ,

j

,k)

/

(CCOV (1 , j , j)CCOV (l,k,k))

1/2

for lag 1=0, ..., LAGMAX, j = 1, ..., M, and k = 1, ..., M, where

rjk^ 1 ) = rkj( -i )

The estimated standard errors (SE) of the ccf are computed as

12-40
SE[rj k

(i)] = SE [rkj (—i)

]

(N-i) • { (N-i ) + 2« l [(N-i-v)Tjj(v)»rkk (v)]} 1/2

v=l

N*NLPPC(i+l , j ,k)

for lag i = 0, ...» LAGMAX and for series j = 1, M and k = 1, M,

where q is the smaller of N-i and i - 1. This standard error formula

assumes that there are no cross correlations between the two series being

compared. It does not assume the two series are white noise, although when

both series have been prewhitened the summed portion of the equation is

approximately zero and the results will approximately equal N

_1 /2

, which is

the standard error assuming white noise. However, the importance of prewhitening before performing cross correlation analysis is clear from the above

equation. The presence of autocorrelation in either one or both series can cause a significant increase in the variance of the cross correlation

estimates, and, as shown in the example on page 338 of Jenkins and Watts

[1968] , the cross correlation function estimates can become quite unreliable.

Autocorrelation in the input series should be suspected if the standard error

estimates computed by the subroutine are not approximately N

_1 /2 . It is best

to use ACF to routinely check for autocorrelation in the input series before

performing cross correlation analyses and to prewhiten the series when

necessary. The digital filtering subroutines [chapter 10] or the autoregressive model subroutines can be used for prewhitening the input series before cross correlation analysis is performed.

E„2.b Spectrum Analysis

The Univariate Fourier Spectrum Analysis Subroutines . The argument

controlling the printed output, NPRT, is discussed in §D. The output from the

univariate Fourier spectrum analysis subroutines consists of four spectrum

plots with successively narrower bandwidths. Each spectrum is plotted

either in decibels (10 times the base 10 logarithm of the power spectrum),

scaled so that the maximum value plotted is zero, or on a logarithmic scale.

The 95-percent confidence interval and the bandwidth for each spectrum are shown on the plots.

The bandwidth of a Parzen lag window with truncation point T is

approximately 1.85/T for T<<N and a low percentage of missing values. The

actual bandwidth is

T -1

BW = { l [WU)2.(N-|a| )2/(N*NLPPAOO)]}

a =-t

where W (l ) is the Parzen lag window function defined in §D under argument

SPCF. The bandwidth is indicated by the displayed ”B * W” in the upper-right

portion of the plot.

12-41
The effective degrees of freedom (edf) a spectrum estimate using a Parzen lag window is

edf = 2.BW.N.

in

For large values of N and a low percentage of missing values this can be

approximated by 3.71»N/T.

A 95-percent confidence interval for the estimated spectrum is

SPCF(I)«edf SPCF(I).edf

» — for I = 1, . NF,

2 2 x edf, 0.975 X edf, 0.025

2 where X

e(jf a is the a-percent point function for a chi-square distribution

with edf degrees of freedom. Note that when the logarithm of the spectrum is

plotted this confidence interval has constant width over frequency although it

is not symmetric. In this case, the lower confidence interval limit is

l°glo[SPCF(I).ed£/X

2 edf>0>975 ] = log10 [SPCF(D] + log10[edfA edf>0 . 975]

and the upper confidence interval limit is

l°glo[ SPCF ( I )* edf /X edf, 0.025] = log 10 [SPCF(I)] + log 10 [edf/X e df,0.025]

for I = 1 , . . .

,

NF.

The width of the confidence interval is indicated by the displayed

”°C * I" aligned vertically in the upper-right portion of the plot. The

asterisk (*) separates the upper limit from the lower limit. The user is

reminded that the confidence interval applies to individual frequency points,

not to the spectrum as a whole.

The Autoregressive Spectrum Subroutines . The argument controlling the

printed output, NPRT, is discussed in §D. The output from the autoregressive

spectrum analysis subroutines consists of a plot of the autoregressive and

Fourier spectra either in decibels (10 times the base 10 logarithm of the

power spectrum) scaled such that the maximum value plotted is zero or on a logarithmic scale. The output also includes the autoregressive order

selection statistics when the user does not supply the value of the order via

argument IAR. The bandwidth and the length of the 95-percent confidence

interval for the Fourier spectrum are shown on the plot. The bandwidth is not

relevant to the autoregressive spectrum. The Fourier spectrum and its

confidence intervals should be used in interpreting the autoregressive

spectrum since the confidence intervals for the autoregressive spectrum are not computed.

The autoregressive order selection statistics include the modified Akaike

information criteria (AIC); the results of a partial F-test of the change in

the residual sum of squares with the addition of the most recent

12-42
autoregressive parameter; the order of the autoregressive model selected; and

the Yule-Walker estimates of the parameters of the selected model.

The modified Akaike information criteria (AIC) is

AIC(J) = N-loge (FPEj) for J = 0, LAGMAX,

where

LAGMAX is the maximum lag value for which the autocovariance has been

computed, and is therefore also the maximum order autoregressive model

which can be selected;

FPEj is the Akaike final prediction error, normalized so that the minimum

final prediction variance Sj^r2 is one, that is,

FPEj = ( (N-hJ+1) • Sj2

) / ( (N+IAR+1) *S IAR

2

)

;

sj2 is the residual or one step prediction variance of the order J model;

S IAR

2 is the residual or one step prediction variance of the selected model;

IAR is the order of the model which produced the minimum AIC, i.e., the

order having the lowest Akaike final prediction error [Akaike,

1974].

The AIC of the selected model order will always be zero.

The partial F-test of the change in the residual sum of squares is a test

of the null hypothesis that the J*1 *1 autoregressive coefficient of the order J

model is zero. The F-ratio is given by

fi,n-j-i = < asj

2 )/ sj2

where

ASj2 is the change in the residual variance due to the hypothesis that

PHI(J) = 0 (one degree of freedom)

,

2 2 2 ASj - Sj_;l - Sj ;

Sj2 is the residual variance of the order J autoregressive model (N-J-l

degrees of freedom)

.

The significance level of each F-ratio is also listed.

The estimated Fourier spectrum and its bandwidth and confidence interval

are computed as described above.

The Direct Fourier Transform Subroutines . The argument controlling the

printed output, NPRT, is discussed in §D. The output from the periodogram

12-43
subroutines consists of a plot of the computed periodogram displayed either in

decibels (10 times the base 10 logarithm of the periodogram estimates), scaled

so that the maximum value plotted is zero, or on a logarithmic scale. The

output from the integrated periodogram subroutines consists of a one-page plot

of the integrated periodogram accompanied by 95-percent confidence bands for

testing the null hypothesis of white noise. These bands are the

Kolmogoroff-Smirnov probability limits applicable to cumulative distribution

functions [Hald, 1952]

.

The Bivariate Fourier Spectrum. The argument controlling the printed

output, NPRT, is discussed in §D. The output from the bivariate Fourier

spectrum subroutines consists of four spectrum plot pairs (a squared coherency

plot and a phase plot) with successively narrower bandwidths chosen by the

window-closing algorithm. The 95-percent confidence intervals and the

95-percent significance levels are shown on the coherency plots.

The bandwidth of a Parzen lag window with truncation point T is

approximately 3.71»N/T for T<<N and a low percentage of missing values. The

actual bandwidth is

i. -i

BW = { l [W(k) 2 (N-|k| ) 2 /(N« NLPPC (k)) ] }. k=-T

NLPPC (k) is the number of lagged product pairs used to compute the covariance

function for lag k, that is

N~Jk | NLPPC (k) = I Ci<t)C 2

Ct:"| k | ) t=l

where C(t) is an indicator variables £(t) = 1 if Y(t) has been observed, and

£(t) = 0 if Y(t) is missing.

F c Examples

Autocorrelation Analysis . In the example program of figure F-la ACF is

used to compute and plot the autocorrelations, partial autocorrelations, and

autoregressive order selection statistics of the input series Y, where the

data used is the series Xj , a simulated first order autoregressive model with

PHI(l) = 0.6, listed on page 362 in Jenkins and Watts [1968]. The correlation

estimates for this series are given on page 421 of Jenkins and Watts.

Figures F-lb through F-le show four pages of output from ACF. The first

two pages are autocorrelations and the second two pages are partial

autocorrelations. Note that for all correlation plots the value of the

lag, i, is is shown on the left margin and the actual correlation coefficients

are shown on the right margin of each of the plots.

12-44
Cross Correlation Analysis . In the example program of figure F-2a CCF is

used to compute and plot the cross correlations between the first 50 values of

the series X-^ and X

2 listed on page 361 of Jenkins and Watts [1968] . The

correlation estimates for these series are given on page 420 of Jenkins and

Watts.

Figures F-2b through F-2d show the two-part output from CCF. Note that

for all correlation plots the value of the lag, i, is shown on the left margin

and the actual correlation coefficients are shown on the right margin of each

of the plots.

Univariate Fourier Spectrum Analysis . In the example program of figure

F-3a, UFS is used to compute and plot the univariate Fourier spectrum

estimates for the first 50 values of the series listed on page 318 of Jenkins

and Watts [1968]; the spectrum of this series is shown for various bandwidths

on page 270 of Jenkins and Watts [1968] .

Figures F-3b through F-3e show the four plots of the power spectrum (in

decibels versus frequency) produced by UFS. Each spectrum plotted is computed

using a narrower bandwidth than the preceding one. The bandwidth, lag window

truncation point and effective degrees of freedom for the spectrum are listed

at the top of each page. The bandwidth and the 95-percent confidence interval

of the individual spectrum values are shown graphically on each plot.

Autoregressive Spectrum Analysis . In the example program of figure F-4a,

UAS is used to compute and plot the univariate autoregressive and Fourier

spectrum estimates for the first 50 values listed on page 318 of Jenkins and

Watts [1968] . The theoretical and Fourier spectra of this series are shown on page 270 of Jenkins and Watts [1968] .

Figures F-4b and F-4c show the two pages of output produced by UAS. The

first page lists the autoregressive order selection statistics while the

second gives a plot of the autoregressive and Fourier spectra. The bandwidth,

lag window truncation point and effective degrees of freedom of the Fourier

spectrum are listed at the top of the plot. The 95-percent confidence

interval and the bandwidth of the Fourier spectrum are displayed on the plot.

The concept of bandwidth does not apply to the autoregressive spectrum and

confidence intervals for the autoregressive spectrum are not computed.

Direct Fourier Transform of a Univariate Series and Utility Subroutines . In the example program of figures F-5a and F-5b, TAPER is used to center the

input series and to taper 10 percent of the data at the ends of the series

(5 percent at each end) and PGMS is used to compute the raw periodogram of the

tapered series. MDFLT is then used to smooth the raw periodogram returned by

PGMS with three applications of a modified Daniell filter of length eight.

PPL (chapter 3) is used to produce a log plot the smoothed periodogram versus

frequency. (VPL could also have been used to display the results.) The data

used are the Wolf sunspot numbers from 1700 to 1960 as tabulated by Waldmeier

12-45
[1961]. The raw and smoothed periodograms of the tapered series are shown on pages 95 and 176, respectively, of Bloomfield [1976].

Figure F-5c shows the raw periodogram output from PGMS while figure F-5d

shows the smoothed periodogram. There is no printed output from TAPER or MDFLT.

Bivariate Fourier Spectrum Analysis . In the example program of figure

F-6a BFS is used to compute and plot the cross' spectrum for the series Xj and

X2 listed on page 361 of Jenkins and Watts [1968]. The squared coherency and

phase spectra for these series are shown on pages 387 and 388 of Jenkins and

Watts. Figures F-6b through F~6i show the eight pages of output from BFS.

12-46
Autocorrelation Analysis

MAIN PR06RAP* AS 068 AW EXANPL

e

C DENONSTRATE ACF USXN6 SIN6LI PRECISION VERSION OF STARPAC

C RUN ON CYBER 116/840.

C

C OUTPUT UNIT IS 6 ( AUTONATIC AUT EQUATED TO FILE TAPE6 ON C TIERS

)

C f SEE CHAPTER 1» SECTION D.43

C

C N.B. DECLARATION OF Y WUST BE CHANS! 0 TO DOUBLE PRECISION

C IF OOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL Y(900)

C

C READ NUNBER OF OBSERVATIONS

C OBSERVED SERIES

C READ 100* N READ 101* tvm» I-1#N)

C

C PRINT TITLE AND CALL ACF FOR AUTOCORRELATION ANALYSIS

C WRITE (6# 102) CALL ACF <Y» N)

C STOP

C

C FORNAT STATENENTS

C 100 FORNAT (19) 101 FORNAT (10F6.2)

102 FORNAT (URESULTS OF STARPAC AUTOCORRELATION SUBROUTINE ACF')

END

100

-2.07 -1.19 0.69 -0.46 -1.49 -0.70 -1.07 -0.69 -0.66 1.27

-1.09 -0.09 •0.64 -0.62 -0.49 -1.29 -0.49 -1.06 -0.1B -0.92

-0.19 1.90 -1.91 -0.49 -1.91 -0.76 0.91 -0.99 -0.90 -0.90

-1.02 -0.99 0.19 1.40 1.22 0.99 0.70 1.70 2.7S 1.96

1.9* 1.B9 2.60 0.91 2.77 1.16 1.07 -0.46 -0.92 0.97

0.00 -loW -1.79 0.70 0.71 1.16 „ 0.06 -0.02 1.10 -0.99

-1.6T -1.97 1.16 1.S4 9.99 0.40 0.49 1.90 0.99 1.17

-1.74 -1.2B -0.07 1.90 0.91 0.20 -0.42 1.16 0.62 1.90

2.92 1.11 1.21 1.16 0.79 0.60 1.14 1.02 1.02 -0.71

-0.17 -1.90 -0.26 -0.91 0.91 -0.91 -1.12 -2.99 -2.09 -1.11

Figure F-la

Example program using ACF

12-47
«M *4 ft ft

©

m

as. ft ft ft ft

O ft

NS

® • « •

ft 1 m

ft ft ft ft ft «q

04) Oft ft

© ft e ® § © e O M ft ft ft ft

ft

© ft ft© ft

©© 0 0 0 ^ ^ ft3 ft ft ft ft ft ft o ft ft © ft ft ft ft © a © ® « • 1 CM# © ft ft IV OA © *4 ft © ft ft ft ft • © © e « © 0

ft ft ft ftm ft ft

© ft

© ft ftO ft ft

© ft • • 0 • ® © 1 « A ft • #» ft © ft m

ft ft ft

© ft ftO ft • 0 0 © 1 0 o

e* ft ft ^ ft ft

©© ft

M 94 ft ft ft CM

O ft 9 ® © ® e ©

© oom 0 0 ik © tfiO w

1*2

© r»

<m

© p* n ft ft ft* ft

© ft ft ft

O ft

m <#

w

W 94 ft ft ft ft

© ft

X •*0

®

ft

© 1 1 ftX© © ess 0m ft *0 ft n © ft ft ft

ft ft ft ft ft ft ft

© ft

U e ® # © 0 ©

ft ft i i Z© 8i« M SI ft ft ft ft ft © ft ft ft ft ft U0 ft ft ft ft ft ft ft © ft

ft

M

x <3^ ft ft t 1 6A£ Ul ft m 4* «* m IU © I0S 94 ft O ft ft ft ft ft ft

ft

X

X ft ft ft ft ft ft

O ft

© ft ft o 0 • • • e 0

ft ft©

M c 3> «*> «« tU ft

ft tto

© ft *»

u

ft 93X

©

X

««- z ft * 0© 3

ft ft Kkt©G U£ ft

ft* ft ft 3 « X ft «4

X

ft

© tu ft

m -ft

©m at at ft ft X ft z » too O o a m ft ft » ft ft «£ at m

ft ft) ft <u> ft at at at

«k*

w Ik

© ft ~tw 109 IS

©w

© M*. ft

ft

©© ft

a Ct

a £ s

IM

m ft ftm at «

ft « fiS2 o ft ft ft i 8

ft filSttl o © o o

ft

m

m is o z z X

•s*t ft UJ ft

X ft ft «£

M ft IS a. ft IS 10 ft

<*> » X> ft 9 ft 3 ft

W ft ft o ft ftO ft « ft MS<J ft ^ ft SI ft ft ft ft ft ft I (J.I

01u3

be 3

C.

4-i 3O

U.; o<o

0)

9-4aE

<0

12-48

THI

NULL

HFFOTHES

IS

OF

MHITE

NOISE -

79.94

DECREES

OF

FREEDOH >

);

OBSERVED

SIGNIFICANCE

LEVEL •

.0000
LOCATION

OF

IEBO

IS

6IVEN

BV

*LOT

CHARACTER

0

•1.0000

-.SOOO

-.6000

°-»6000

-.2000

.0000

.2000

.6000

.6000

.BOOO

1.0000

oooooo oooooo oo

• T t • e i i I i • i I 0 o o o o _ _

1 t I I I II

UJ VA1 Ui UA UA (U bt&csowsmri'G

Am*AOSOCOCMO>4AOOONA«N#K^«iMOlMHCCp4AK

I I I I I I I I • i i I e « e i

9 MHHNMHHNMMNI

w

I [a--

0)u&

H

Pu

t

^

o oo OO i o o o oooooooo ooooooooo

SSSSSSSSSSSUSSSSSSSSSSil ooooooooooooooooooooooooo

*.m« . r « N •. o i

12-49

Example

of

ACF

output

(continued)
m

N 0 C(V A

O ®=4) ft ft «v o ® o ^

0 NM# ^ MO^O«

ft ft ft c*

> © ^ #n w» N«S ViO «

N O «

« • 9 e

I <*»

«*»

e m o b

© © ® © ©

»«9 *»S @ g*« «* fvoeo^ moM o«

I m o#o^ © IA <© ^

e ® » •

in H

© (*& «V © © © c •

©4 ff» © #1

© ® e v

I ft e*S

© © <SI © ft*

^> © ft* ©«8 ^

©4 ©4 © © A

IOMM# > ©* © ft ft

» t f *

I w «e^N« © • © ©

e ©

h» ft ft m ©«# ©<***#

i o n a n i® o • •* A®

e © © 9 © * • •

p—

<

i Ue©

S)

•H

r> © ® m

© © © ©

cnO ft © ft » ^

) © 0^ © ^ #W©^*4 ft

© ® © • © © © ©

© ft M «D *- o Ur ft 0K

• &

ft **

i ft <€ ^ fcC

O *» US O ft *» a

» ©

U O ft A

O ft * ft* H. ©

<*UUft ft o o

Cl Cl

ft 9*> «> ft

sft «r* ft © a © © ©

«*5 2V9

OftOft

© © • ©

4toeoft

fi ft9

m «* *« ft *4

*4 © ® ft W> ©COG

e ft

ft

><\J Aft # K O <J O K

)OftO • NONOf g © ® ® © e e ©

M«0»ft © <© ft* ftt p4 A«4» O ft* © O

I © o • •*

l •* eft ft ft AO Cl I0N00 0AKKO IO® A A NO 0 O® • • • • •••• i « » a

Cl ft o •-*

: ft O A

US Cl

ftg ** ® o

12-50

Example

of

ACF

output

(continued)
I

[

o o o oooooooooooo oooooooooooooo ii i i i i i i i t i i i i i i i i e i i i i i i i i i i uj m m uj ui m ui *41 ^ ^ m vm K*4m«9N«ON«K(*lO#O0^KN^O^««O^«<\NKK>N<0

O OHN 00 MO ® -« ® # # ® •** © <"* *# *“> »Nf4 NNO^#«4 N

«r»©****©-*^^*'*©«*o « — ~s <* 0 *> p» *> * *\ © «m o 90

II III! 181 I eiiii III

o©

O I MN«WWMWWWI«WWWWMW(»WWWWWlW»wmwcs«WWW(aiW

• M

I

I

I

II O I © I © I

I © te=S

80I

•

I © I © I

8

I

• M

8 •

8I

8 oSG I o 0 <r 6

Q)U

3

b£)

« ©

« o *< o

0

o SI ® o I «D • * • Ui I I

•A O — o

o o o

ooooooooooooooooopooooooooooooooo OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO 000000000000000000000000000000000 000000000 • • • • • ••• • • • •• • •••••• • • • • • • • • •

12-51

Example

of

ACF

output

(continued)
0^0

<H)

oom

<T&

<J“&

<T>

(TIOOOOOOOOO

Cross Correlation Analysis

MAIN PROGRAMS PROGRAM EXAMPL DEMONSTRATE CCE USING SINGLE PRECISION VERSION OF STARPAC

RUN ON CYBER 180/8*0.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE* ON CYBIRS)

C SEE CHAPTER It SECTION 0.4]

N.B. DECLARATION OF YX AND Y2 MUST BE CHANGED TO OOUBLE PRECISION

IF OOUBLE PRECISION VERSION OF STARPAC IS USED.

RIAL YH160)* Y2(100»

READ NUMBER OF OBSERVATIONS

SERIES X SERIES 2 READ 100* N READ 101* Itinil* I*1»N! READ 161* ( Y2( I )* I«I»NI PRINT TITLE AND CALL CCF FOR CROSS CORRELATION ANALYSIS

WRITE (6* 1021 CALI CCF CV1# Y2» N)

STOP FORMAT STATEMENTS

100 FORMAT (19) 101 FORNAT (12F6.2)

102 FORNAT CIRESULTS OF STARPAC CROSS CORRELATION SUBROUTINE CCF') IN©

BATA* 90

'@.18 •0.1© -1.87 -1.12 1.30 2.13 2.76 0.96 -0.69 -1.79 -3.82 -2.JB

1.00 0.70 -0.19 0.98 0.11 -0.39 -0.73 0.89 -1.63 -0.44 -1.37 -1.71

1.22 •2.00 -0.22 0.1B 1.31 0.71 0.32 0.4B -1.B8 -0.94 -1.94 -0.13

lcG2 0.02 -0.77 0.11 -0.00 -0.92 -0.09 1.23 1.46 0.61 0.42 2.16

Sell 2.16

0.70 1.12 -1.10 -2.39 -1.79 -0.82 -0.36 1.27 1.79 2.44 0.36 -2.10

1.99 -1.10 -1.79 -0.34 0.74 0.49 0.70 0.71 0.09 0.99 1.94 0.14

6. 99 “1.40 -2.99 -1.66 -0.43 0.90 2. 18 -0.24 0.98 -0.18 -1.99 -0.64

•1 ,6% 0.90 -0.66 -0.39 0.4B 0.90 0.09 -0.6B 0.24 0.96 -1.26 -0.29

6.29 2. IB

Figure F-2a

Example program using CCF

12-52
RESULTS

OF

STAR

FAC

CROSS

CORRELATION

SUBROUTINE

CCF I!

Mfl ©* <*«©<*« go® I e c I ^ 6

*=> «

10*4

M *4K • « • • M 0494 *40 *< Be® 0 ® © ^ (P )Or< ^ 0«4 © © o • Wm

AW ^ N© G4K» «*fl ^ © MOH p© 04 04 © pag Mf<P) Be© 0 ® • © e * © B 1 e B H ^ ^ & 6* *> ^ H © 4

Mi

© a* 1 O

M

© <*» Mi fv pH 0 © © © © © © © • 9 i • a 6 0 OK4 MWN I 1 1 MO a© «H 1 H 94 0 © © 0 © * © ® • B B

00© 04 &m

© • M»0 ^fl© ©a ^ m e *> © «* <p* <H ^ 0 m « Mi ^ 0< a © ©a m » • * 8 ® • © ® O «« © e # l © ^ • © *4 X © © OHfll f*> © & • © ®Nl“ 0 i i 9 94 m MHH B *» «C

©“ o <i • * • ® a* i 9 oe

94 c o# © ** » & <&>

m ^9><0 o*e « 0 CP«

Mi cH> <J=0 H©

H 1 H

M o mi HHH WHH

04 I* > » • ©

© e » • • © «* © M) -«* e i © 9* ** m 4 © © 4T% 04 ® *0 X

•©

V K*> ®> T© •« •#'#*©© 4>GC

fO «« a© p-o *© cH 0 © Mi

If*

© 04 «£D * ©

© Be©

©©

© <p® *» » c 0 8 ( * « f* * 04 B- O M WM C © 0 « uu X 0*0 I 1 1 1 1 1 I #* Mi •#* M4 1 0 I MO

H

w

H K« 0 • • M 04 1 1 B 04

"H O* X

144 * U1 OH> 2 0 1 1 0 1 1 O *4

••* » I

m. •-•3-4 1 0 04 o 04

•H 04 «-> X ^ OM

04 3 o o o z 00

H* 04 HO«e

«>U *» -/ • 8 « 1 WU.O X UlOH o Ol OH *- * *- o. M -J « I M « M1V(

04

O o 04

X IAJ

K 04 I4H4. 3 o MKM » -4 ++ O «C 04 4 Ml H- M U04

m

m « ®L ©L ac ac

X ~ K << 04

M

O o O o o o O

-4 b- o: ac ac ac «K ar ac ac 04 - l* 04 «H -K X ac m a» ac at ac ar UL O a ®C -IIAIOI 04 04 MU, AAA AAA Mi 04 O O •4 OK Ui *- X O o o * H> o O o O o o o

oi at o « O

m ac at •t

m ac ac

O <flt *o

O

—

HHH •HH

a •a

® 004 04 »o

u ^ o O

O

O o o o

acXm <* v»

X

X

X

XX

X

X

Oi < K ac o ml >>-D -a «K o ® o H * UH * U " * u»- •a «_» AUK < MI —4 o u -1 O M -1 UH _IOM -lO M -lOM -AUH -4U M

Xi

CSII0) l*5

•H

Cfe

12-53

Example

of

CCF

output
0

1©©

m m too » «*» *

Z © «»• » •*> to => «> (UtUtf * « to

t®

<u>

?? I ?? ?? ???? ? I ?? t*3 *At> M

• •to»OtoiKmM#«^cotoP«#i40#rc9»o^9»rttos«##««4»4i4iwN»»r«

S

©

e i need 8 6 9 11 8 9 6 1110 0 16 6

I • toe

eto |

© I © I O 6 m 9 ® #n0

© I e 0 © 8 « •

to

0

0 © 6 © 8 © e M 6

© 8 ©

© 0 © «*0e © i * e

0 to © © 8 to ©

frf ®*9 Gfee i

yfcj «» © K kW

6-9 ^

£d 94

0 0

0» 9 0» to to © © | W) 0

ftfl * © 0 «=2 to 0 •ft © ® IX

to to

to to

to to to

to <£ to to ^tototo

to to to to to

to to to

to to to to

to to to to to to

to

to to to to to

to to to to to to to

to

to

toto

to

toto to to to to

to to to to

to to to

to to to

- . to to to

to to

to to to

CJ

csa

I

to to to

to to

to to to

to

to to

to to

to to to to to to

to to

to to

to to

to to

to to

to

to to to to to to

to to to to to to to to

0)u

3

be

to to to to

to to to to

to to to

to to to

to to to

to to to to to to

to to to to to

to to to

to to to

to to to to to to

to to to

to to to

to to to

to to to to to to

to to to

to to

to to

to to to to totototototototo

to

to to

<« © 0

to to

to! © 0 Z © 6 4^ ® B=0

0 0

to to

toto

to

to» © m

to ©

*3 © m W ox9

*0 0 I * J •ft© 0 © «

M

to to s

e© 8 C O M

m ®*3 0 ** e tceas«E3*sawws«weE5(»*!a*ffle«9o»B3esoaiiM

wt, X

« <*= St<U? «W __>©©©©©©©©©_ >00©0e000000©0©0©00sssfs: © © © © © < ipOOOO o< >©©©©<©©©<®o©©©©__ po&opooopoopp - - - - >oo©oo oop ->©000000000 >000000000 M*4PtotoK«ft#toMNOtoto|kpAto«MtoO • • ® © • • • • • « fe* ^ • 000800000§®0i008§0880000®0000000®

ssssssssss OOOOOOOOOO ~ OOOOOOO - o

oO O

12-54

n

Example

of

CCF

output

(continued)
0 o © © o

1 I I I I bU (tMi1 tt u

P o P + ^ * ** rs a © «% ^ « o O « ^ « 14 ft I 04 • O *4 © O r*

0 o o

1 I f 0 o

1 I ^^OO©©#*^**©® © © T\ ^ **a r 4 # O O « •# ©r N OK«» ^ N # M *40 <><•» ©

I I I I I

© «> «8> « ©

csi

i

a>3

bC

°H

«*

g oooooooooooopooopoooo ooooooooooooooooooooo oooooooooooooooooooooo

12-55

Example

of

CCF

output

(continued)
Univariate Fourier Spectrum Analysis

WAIN PR06RAHJ

c

e

c

ce

c

ecc

c

c

cc

e

c

cc

PROGRAM EXAWPL DEMONSTRATE UFS USING SINGLE PRECISION VERSION OF STARPAC

RUN ON CYBER 160/840*

OUTPUT UNIT IS 6 ( AUTOMATICALLY EOUATID TO FILE TAPE6 ON CYBERSI

{SEE CHAPTER 1» SECTION 0*4]

N.6. DECLARATION OF Y MUST BE CHANGE 0 TO DOUBLE PRECISION

IF DOUBLE PRECISION VERSION OF STARPAC IS USED* REAL Vf 306) READ NUMBER OF OBSERVATIONS

OBSERVED SERIES

READ 100* N READ 101* mil* I-1*NS PRINT TITLE AND CALL UFS FOR UNIVARIATE FOURIER SPECTRUM ANALYSIS

WRITE (6* 1021 CALL UFS IT* N) STOP

C

C FORMAT STATEMENTS

C 100 FORMAT (19) 101 FORMAT C10F6.2)

102 FORMAT I '1RESULTS OF STARPAC*

• • UNIVARIATE FOURIER SPECTRUM ANALYSIS SUBROUTINE UFSM

C END DATA* 90 -0.8B

-2.76

0.06

0.14

”0 . 8?

”0®12 ”0.60

•1* TT 0.98

-0,17 -1.01

1.99 -0.76

-O.At 0.26

-1.36 -0.6?

1.00 -0.70

-1.04 -0.66

-l.ee -1.77

1.90 2.14

1.03 2.14 0.39 -1.10 -1.76

”1.01 -1.30 -0.89 -0.46 1.63

”1.12 -0.91 -0.71 -0.20 -0.13

-1*20 0.49 -0.07 -0.63 -0.39

1.09 0.31 1.07 2.67 2.44

Figure F-3a

Example program using UFS

12-56
12-57

Example

of

UFS

output
(06!

*2

M3I0H131O -

S00'2

Example

of

UFS

output

(continued)

SHOOTMfJJ

FOUIUIB

SPfC?#U« ~

fH

MSNDOM

MB

fM

IAS

M!MDe

TRUNCe

8Te

=>

326

8«®

»fflft90 6

SOP®

12=60
Autoregressive Spectrum Analysis

MAIN PR06R AMI PR06RAH EXAMPL

C

C DEMONSTRATE UAS USING SINGLE PRECISION VERSION OF STARPAC

C RUN ON CYBER 180/640.

C

C OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPES. ON CYIEPSI

C CSEE CHAPTER 1* SECTION ©.A3

C

C N.B. DECLARATION OF Y MUST BE CHANGED TO DOUBLE PRECISION

C IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

C REAL Y ( 300)

CC READ NUMBER OF OBSERVATIONS

C OBSERVED SERIES

C READ 100* N read ioi* mn« i>i*n)

c

C PRINT TITLE ANO CALL UAS FOR UNIVARIATE AUTOREGRESSIVE SPECTRUM ANALYSIS

C WRITE (6* 102)

CALL UAS (Y* N)

C STOP

CC FORMAT STATEMENTS

C 100 FORMAT (IS) 101 FORMAT (10F6.2)

102 FORMAT (*1RESULTS OF STARPAC * * • • UNIVARIATE AUTOREGRESSIVE SPECTRUM ANALYSIS SUBROUTINE UAS 1

) END DATA! 90 -0.88 -0.12

-2.76 -1.77

0.06 -0.17

0.14 1.99

—0.87 -0.62

-0.89 -1.38

0.98 1.00

-1.01 -1.04

-0.76 -1.08

0.28 1.90

-0.07 1.03

-0.70 -1.01

—0.66 —1.12

-1.77 -1.20

2.14 1.09

2.14 0.39

-1.30 -0.89

-0.91 -0.71

0.49 -0.07

0.31 1.07

-1.10 -1.78

-0.46 1.63

-0.20 -0.13

-0.63 -0.39

2.67 2.44

Figure F-4a

Example program using UAS

12-61
o©

a. 04

O ©4 •4 «U <\i

® « AM* W « • « ® • • • 0b © 0® *4 1*

©4 <£ 0#© 4** «*>

O a4 <#> o m 04 <fi> ©

© • • • © © • «w *> ©4 A

© ev

® At #

©4 <s*b

© ^ 04

® 04

a

©

©©

©® e4 ©4

ert 06

o>©

©n ©4 & Sf» «4

0* *4 fto 09 «b «b <© © ® ® © © © C&£ => w UU4

c4

©

m

m

© ©#« o o © US

QA0 N9M4 0® ©4 o ©

m

X • • 9 © • • • © « M ^ 04 (?4 Ott

ft*M

m Vb

US

©

u

or ffc© $=* tft ^ ^ 8^ « 04

m 01 40

©

m mm <*> ©4 ©4 « 4> 04 fit » « • • « c c • • ® fi 0® €M 0® *4 0® UD

0®

X

o* fib oc

«« «©<#><#> o o 0%© o» > ^ o ^ N AO0 0® e © ©

<«s • • © • • ©

©© « 4) US < A 06 fib * X N 0% 06 a

<*s

K QAS 04 ® fit

X fib

© ®» ^ ^ 09

© ©4 04 •0 0b * o s © » At 0=0 <?4 © ® 0fl © ® 0-> Of © © © © © © • e © ©

ft= Oil ©4

m e <4 <u <ss <* US © US

X. Ul

X

w <#> fifi firb « « O 0 « m 0b <04 o- ft*

lib 06 fib ^ e4 ^ 04 04

u

U3

©

©

©®

© • © * • m

u » #8® 9SI *? ~A ©

O* 04 144 0® 05> *A o®

V®

U

CAfi 04 0^ o e e*

X

K ^ @ ft* 04

® «4 « 04 0%

© 0® 1*4

<3S

©

© • © • • • ©

O us ox

m •# ftO

© •m US o o

<x ft* ft* o 04 © «« «J 0 u

i- ft* US u.

u

0® *5

© 94 ^ ®O « m «0 0V -4 144 <0 © ©4 <& o« 9- O 9* 09 <G © m «fi u. o X • ® • ® • • • • • o> O O m © © o4

c=0 06 U4 US

•0 ft* o»

uX c=c <U> U? Z ft- IK m « > «• o m © r» 4> n «» U 4 0 m4 © fib © #40 0# 04 a- O O 04 u. » m • © • • • • © • • 0 K O a*o V® fib 49b 43 m 0. -4 X M ©4 m » 0» s <M> US at m » X

<LZ

© ox

O 0 fit W OX

X

fit

© 0b ftfig us U »- 0 US or *4 01

ft* » XK t» o US 06 0=3 => K* O’- us US V® w M OO at at «r WL V® <=£ «? O fir U4 © Ii£ 04 04 ox X

at «•®m r» fi>—

J

06 &>

© ^ e> < G 41 •o US 0

ft® US ft® « o«

A 04 « ftX

—

J « ft*

© ft* e ft*

O fit Ob 1 © <« ci 0® ft* 13> o •?. K (J O • 1. 0UC u © US «4 US © ^ 04 ©XI or X © « 4 Ik •* It w. ^ 4 U, u O O I U*Vuo

be I o4 & o © o u

M

12-62

Example

of

UAS

output
FOURIER

SFECTRUN

<)

<1*6

KINO,

TRUNC

s

FT,"

16t

>«•

»12* 9

t

£<>F«

AND

ORDER

t

AUTOREGRESSIVE

SFECIRUN

fl.)

J

12-63

Example

of

UAS

output

(continued)
0

0

6^

O

6^

<Tfr

(T& O

fTl O

O

O

O

>f>

<H>> O

O

(P^^OOO^OOOO

Direct Fourier Transform of a Univariate Series and Utility Subroutines

MAIN PROCRAHl PR OCR AH EXAHPL OENONSTRATE DIRECT FOURIER TRANSFORM SUBROUTINES USIN6 SINGLE PRECISION

VERSION OF STARPAC RUN ON CYBER 1BO/SAO.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE6 ON CYBERS)

(SEE CHAPTER 1# SECTION D.A1 N.B» DECLARATION OF Y, YFFT* PER* FREQ AND PEAF MUST BE CHANCED TO DOUBLE

PRECISION IF DOUBLE PRECISION VERSION OF STARPAC IS USED.

REAL Y(600)» YFFT(600I* PER(SOO)* FREQ(SOO)* PERF(iOO)

INTECER KMD(IO)

DOUBLE PRECISION DSTAKUOOO)

COMMON /CSTARS OSTAK SPECIFY NECESSARY DIMENSIONS

IDSTAK • 1000

LPER « 600

LFREQ * 300 LYFFT e 600 READ NUMBER OF MODIFIED DANIEL FILTERS TO BE APPLIED

FILTER IENCTHS NUMBER OF OBSERVATIONS

OBSERVED SERIES READ 100* NK READ 100* (KNDm* I - 1* NR) READ ISO* N READ 101* (Y(I)» I s i*M)

CENTER THE SERIES AND APPLY A TEN PERCENT TAPER TO THE ENOS OF THE DATA YAPERP » 0*10

CALL TAPER «Y» N* YAPERP* YFFT) PRINT TITLE AND CALL PCNS TO CONPUTi PER I060CR AM OF TAPERED ANO EXTENDED SERIES.

WRITE $6* 102) NFFT * 914

IfKTNO 0 NPRT « f-1) CALL PCMS (YFFT* N» NFFT, LYFFT, IEXTNO, NF, PER* LPER* FREQ,

1 LFREQ* NPRT) APPLY MODIFIED OANIELL FILTERS TO SNOOTH THE PERIOOOCRAN

CALL HDFIT (PER* NF* NR* RNO* PERF* LOST AM) PRINT TITLE ANO CALL PPL TO OISPLAY SNOOTHEO PERIOOOCRAN

WRIT! (6* 103)

HOC « 1 CALL PPL (PERF* FREO* NF* ILOC)

C STOP

C FORMAT STATEMENTS

C 100 FORMAT (1019)

101 FORMAT (10F7.2)

102 FORMAT ( 'IRE SUITS OF STARPAC

103 FORMAT ( '1RESULTS OF STARPAC

* # DISPLAYED USINC STARPAC

END

PER IOOQGR AM SUBROUTINE PGMS •

) FILTER SUBROUTINE NDFLT •» PLOT SUBROUTINE PPL')

Figure F~5a

Example program using TAPER, PGMS, MDFLT and PPL

12-64
DATA!

e

3

0 8 2619.00 11.00 16.00 23.00 36.00 90.00 29.00 20.00 10.00 6.00

3.00 0.00 0.00 2.00 11.00 27.00 47.00 63.00 60.00 39.00

20.00 26.00 22.00 11.00 21.00 40.00 78.00 122.00 103.00 73.00

47.00 39.00 11.00 9.00 16.00 34.00 70.00 81.00 111.00 101.00

73.00 40.00 20.00 16.00 9.00 11.00 22.00 40.00 60.00 60.90

•3.40 47.70 47.00 30.70 12.20 9.60 10.20 32.40 47.60 94.00

62.90 8 9.90 61.20 49.10 36.40 20.90 11.40 37.00 69.80 106.10

100.00 01.60 66.90 34.00 30.60 7.00 19.00 92.90 194.40 129.90

04.00 60.10 30.90 22.00 10.20 24.10 02.90 132.00 130.90 110.10

09.90 66.60 60.00 46.90 41.00 21.30 16.00 6.40 4.10 6 . 00 14.90 34.00 49.00 43.10 47.90 42.20 20.10 10.10 9.10 2.90

0.00 1.40 9.00 12.20 13.90 39.40 49.00 41.10 30.10 23.90

19.60 6.60 4.00 1.00 0.90 16.60 36.30 49.60 64.20 67.00

70.90 47.00 27.90 0.90 13.20 96.90 121.90 130.30 103 .20 09.70

64.60 36.70 24.20 10.70 19.00 40.10 61.90 90.90 124.70 96.30

66.60 64.90 94.10 39.00 20.60 6.70 4.30 22.70 94.00 93.00

99.00 77.20 99.10 44.00 47.00 30.90 16.30 7.30 37.60 74.00

139.00 111.20 101.60 66.20 44.70 17.00 11.30 12.40 3.40 6.00

32.30 94.30 99.70 63.70 63.90 92.20 29.40 13.10 6.90 6.30

7.10 39.60 73.00 89.10 70.00 64.00 41.00 26.20 26.70 12.10

9.90 2.70 9.00 24.40 42.00 63.90 93.00 62.00 40.90 43.90

10.60 9.70 3.60 1.40 9.60 47.40 97.10 103.90 00.60 63.60

37.60 26.10 14.20 9.80 16.70 44.30 63.90 69.00 77.00 64.90

39.70 21.20 11.10 9.70 0.70 36.10 79.70 114.40 109.60 06.60

67.00 47.90 30.60 16.30 9.60 33.20 92.60 191.60 136.30 134.70

03.90 69.40 31.90 13.90 4.40 30.00 141.70 190.20 104.00 199.00

112.00

Figure F-5b

Example program using TAPER, PGMS , MDFLT and PPL (continued)

12-65
SAMPLE

P6«I0OO6*AM

ON

0ICBIEIS8

12-66

Example

of

PCJMS

output
ESULTS

Of

STARPAC

FILTER

SUBROUTINE

NDFLT

DISPLAYED

USINS

STARPAC

PLOT

SUBROUTINE

PEL

[

I

12-67

Example

of

PPL

output

displaying

smoothed

perlodogram
Bivariate Fourier Spectrum Analysis

MAIN PROGRAM

C

cc

e

c

c

e

c

c

c

e€

e

e

e

e

e

PROGRAM E1AHPI

DEMONSTRATE BPS USING SINGLE PRECISION VERSION OF STARPAC

RUN ON CYBER 160/840.

OUTPUT UNIT IS 6 (AUTOMATICALLY EQUATED TO FILE TAPE 6 ON CYBERS)

(SEE CHAPTER 1* SECTION 0.41

N.B. DECLARATION OF Y1 ANO Y2 MUST BE CHANGED TO OOUBLE PRECISION

IF OOUBLE PRECISION VERSION OF STARPAC IS USIO.

REAL Yl( 100) » Y2C10O)

READ NUMBER OF OBSERVATIONS

SERIES 1 SERIES 2 READ 100* N READ 101* fYltlli I«1#N) READ 101# ( Y2 ( I ) * I»1»N* PRINT TITLE ANO CALL 8FS FOR BIVARIATE FOURIER SPECTRUM ANALYSIS

WRITE (6* 102) CALL BFS (Yl» Y2» N)

C STOP

€

C FORMAT STATEMENTS

100 FORMAT (15) 101 FORMAT (12F6.2)

102 FORMAT C'lRESULTS OF STARPAC •* * • BIVARIATE FOURIER SPECTRUM ANALYSIS SUBROUTINE BFS')

END

DATA* 100

-0.88 -0.16 -1.87

1.00 0.70 -0.15

-1.22 -2.00 -0.22

1.02 0.02 -0.77

1.18 2.10 0.17

-0.12 -1.88 -1.50

0.89 1.71 1.05

1.92 0.51 -1.08

-0.07 0.24 0.55

0.79 1.12 -1.10

-1©93 -1.10 -1.75

0.55 -1.40 -2.55

-1.09 0.90 —0.66

0.25 2.18 2.96

-0.16 -0.37 -1.39

-0.05 0.41 0.15

1.00 1.71 0.58

0.11 0.00 2.14

-1.12 1.18 2.13

0.98 0.11 -0.15

o.se 1.31 0.71

0.11 -0.60 -0.52

-0.24 0.57 -0.51

1.54 1.11 1.08

0.15 -1.04 0.12

0.49 -0.58 0.17

-2.16

-2.19 -1.75 -0.62

-0.14 0.74 0.49

•1.66 -0.41 0.56

-0.95 0.48 0.50

1.56 -0.16 -0.39

-4.19 -0.71 -0.96

2.69 0.57 0.29

1.97 0.99 1.94

1.88

2.76 0.56 -0.69

0.71 0.69 -1.61

0.12 0.46 -1.66

0.09 1.21 1.46

2.44 1.02 -0.51

1.71 0.79 1.55

0.06 0.11 -2.62

1.15 -0.97 -1.61

•0.16 1.27 1.75

0.70 0.71 0.09

2.16 -0.24 0.98

0.05 -0.68 0.24

•0.12 1.01 2.11

0.16 0.06 -1.94

1.10 0.48 -1.06

2.18 1.14 0.60

•1.74 -9. 82 -2.36

-0.44 -1.37 -1.71

-0.44 -1.54 -0.13

0.61 0.42 2.16

-2.44 -2.12 -1.04

0.89 -0.69 — 1. II -1.28 1.07 3.20

1.14 -0.67 -0.86

2.44 0.36 -2.10

0.59 1.54 0.14

-0.16 -1.95 -0.64

0.98 -1.26 -0.29

0.76 0.69 -1.49

-0.08 0.17 1.00

-2.26 -2.03 -0.75

0.91 1.39 0.96

Figure F-6a

Example program using BFS

1 2-68
I

12-69

Example

of

BFS

output
I w W 0

fflso 0b* gs« «) I

o

68

8w ^

3* 6 O

8 *>

I

a

<*> c «> © e=® ft 6 * © 9 *

ttf 88 <*

I

a *• i &> a ft a

6 ft

8

'

* 0

(fie e X 8= © ft

ftX €> © ^

X * (

ft ft 6® c^

lfi£ ft X

•» »

©

9

i o

I •> » •

o «* O N

TJ

(V3

C

I • «

CJ sO

I U- 3

a

0) 3

u. o

3

be cn

«*H Cu

Cb CO

a.E

03X

CxJ

I e

i o

• o

I o

8 WJMKW I *S WIB5 63 | »Q- «$ geft **5 g » m M M Q » «) *25 *« fe W M « M I « M* *® « fi MM M M | M •« M* ft* « "MM** I

AS

ft»

ft

ft M

ft

ft

ft

ft

© <*B X ft

•ft <*?

ft) *«

I

Pfc mm

I

12-70

I

I

I

I
(

I

m e i T3

J " vO

i 1

1•

1 fcu

1 O

1 0)

1 •> U

C*c

1 N 3 • •

• + be

1 T-l

1 Cb

12-71

Example

of

BFS

output

(continued)
SMOOTHS®

SOUBISB

SBSCTBWW

IBHASS

COMPOMIMTI

-**

SBABJEM

MI

MOOU

MUM

LAG

WINS®

TBUN£

e

P?

0®

8

S

8M*>

»23%9

S

iOB«

I « W) W W I «5 ( ) «*»8 **) | MW WW 0 HMI > « 0 » M « W |

©©

oo

I ©

I *>

*30 *=3 0«S5 fc=0 | »S) &S3 *E® u*j | MNtUM

« M

' I

i

K.

K>

*0

I

l o fv

I O ^

I o *4

I © *•

i *> r*

I m m

O «

m

© m

I O

I O <3

I rv <o

I - -o

i o

I o

I o

• o

I

oo

O M

0) sD

I u.

m

12-72

Example

of

BFS

output

(continued)
«I o w9 u. © e o •-»

(*=>

uz

U£o

Ut • z » a « Z ft, O»aw * I

at a» • H < I u -ft I ui I a. Z I ^ h- I « I at s I Ui M M > I Qt O 3 O O Z oo 9 « I Ot ft W • 6 • N II8 * I a n

ton* I fti I # N

<V

IS8 # ft < O < I ft < I oI o8 ft I NI - I O ft- I o o 8 ft I ft « ** • • 8 « I«IV O« o8 O8 *-9

r*> « • I O I ft * wisI oI o oooo ooo oo ooo oo

sDI &-0) 3

&0

12-73

Example

of

BFS

output
fe, 0 & 0 IM 6 ^ 00

s*a 0 ^ 6 0=3 fi «=0 IW o 08 e o * 8 ® 0 6 ^ 8 8 6-5 W6 ® 8

«« i ea t (19 03 » 8 I hhmm I > « « I W9

M I I ••

W | | M MM

M | m « 8 aa © 9 s *=> « © & 8 fe 8 * O 0 © iaf « U X 0 S 0 e&j m 8 s » « 3 8 <K <& 8 = ^ fi «=»«=» 8 «&s e Qb s e o 0 OI «f> MB •

12-74

O *t ©

•# AJ • •

AJ ooo* *>M I O H • O K I «N tf\ I A • o «« o m o m II oI oI tft I A*O K O *> ** « m © 3 © 8 tw WWW 8 MW W W 0 MMW M t M WWW ^

MB3 MB

©

m

©©©©©

©

© o o o o

U,

w

©©©

©

©

©O© o o o

IX©

©

©

©

©

©

©

© o o o © © © © © © © © © o o o « e e • e c e c • • • X IAS © *3 © c M « •# © = M © •#> M5 ** o AJ o © « 0 0 94 vK «»0 Afl A* A* 0W *• © 8 8 1 • 1 1 1 •

b£) v£>I Cxbe -H

u* IIIII*

Example

of

BFS

output

(continued)
STASPAC

2.03S

-

Di

CE

M9E R

2*

1905

SMOOTHEO

FOUAIER

SPECTRUM

CSOUAAED

COHERENCV

COMPONENT

»

«*»

95

PCT.

CONFIDENCE

UNITS

«.»

ANO

95

PCU

SIGNIFICANCE

LEVEL

I-l

(PARZEN

WINDOW

WITH

LAG

WIND.

TRUNC«

PT«»

33t

BW«

e0393

t

SDF«

S28

0I

| M M R-4 «« g I

l=t Ki(W M | W««N | » *~9 M g W*«JW**! | g | *r0 s-d W g M »=>* « • O

o

I o

i o

f © EM

I © <M

I r* <M

I PM

•( © *4

I © ^

I €\ r

I m •

e=o e ©

j W

I

•

e © (*> 9 © m

I o «

9 m m

** e e

I (« I fc

< II

I

e

i

i ©

0 O

• r»

1 N

I

I o

I o

I N

0)u

3

bC

© i•

i

i

i

i © ^

i ©

I r»

I ©

+* • •

I ©

I

I

0

|

f ©

I

I

I H

I O

!§

I O

©

o

o

o o

o

o

» 0

• o

o

oo

O M

12-75

Example

of

BFS

output

(continued)
CvX

JAi U4©8

iSi O©

*9UX 9 Cm3

M » § MM Ht4 0 eaS

M #a3 fcsrS

g *=S

M

MW | tea te* CH9 C*» | teGW t«

M

g

M

M

H

M

J B9

M *4 I «8809I88e fc*3 •8I8C•89I*=5Q99•III86 t*3Ie8888880 w

<*> i«

cb4 0a098 e ( 6

iso

fet 9 © 9988

SS> 9 © 80 © c*c © e e 9I X 8989 0 i

fi ^ B=*S e9 z e 8 e*g e 0 Z l=> 8 © A, 9 a, 1 * ® 8 © ^ 6=3 X 8 © I <K fl a/» t» 9 «a 8 X « 5 <*> © 9 » z 9 teo 9 X X U31 «B 40 0 •» •9 U9 $ fib z 6 e« *=> 6 teO 1

fi£

X 9 U9 •«

*«5

X 9 as © ©© z

it, 

X ©

8ftfl Z X «U

*= fefl © as a < K ft. «« »ee

tsj » M

M

©

e> <€> mi

15=8 ccaa e*3J 8 « 6*3 « *»3 I ©O©©

*£

Pb9 ©©©

©

Oo© oo I tea

<• « 9 9 <v II99I O ** I fsi I rs fv I # ©a M • Cw II9I O #i I © m I m I * m

sDI tx- 1 ©1 O1 A 0) 1 *4 J-l m+ e • 3 9 # 1 bo I o• oI NO « r « H « 8 OI o• r• o ooo

12-76

Example

of

BFS

output

(continued)
G. Acknowledgments

The code for computing the autocovariance and cross covariance functions

using a fast Fourier transform are based on subroutines written by Jones

[1971], The subroutines which compute the fast Fourier transform and which

compute the Fourier transform of real data are those written by Singleton

[1969] and the subroutine to compute the cosine transform was written by

Jones.

The transformation used to compute the univariate Fourier spectrum is

performed using the algorithm shown on page 311 of Jenkins and Watts [1968].

The algorithm used is described on pages 418-420.

The code for computing the autoregressive order selection statistics and

autoregressive spectrum estimates is based on subroutines written by Jones

[1971]. The coefficients PHI(k), k = 1 , ..., IAR of the autoregressive model

used by the autoregressive spectrum subroutines are computed from the

autocovariance function using the Levinson-Durbin recursive method for solving

the Yule-Walker equations discussed in Appendix A3. 2 of Box and Jenkins

[1976]

The subroutines for the split-cosine-bell taper and the modified Daniell

filter operation were adapted from subroutines TAPER and MODDAN given on pages

116 and 178 of Bloomfield [1976],

12-77
•• •'
CHAPTER 13

ARIMA MODELING

A. Introduction

STARPAC contains five user-callable subroutines for AutoRegressive Tntegrated Moving Average (ARIMA) modeling. Three are for computing the least

squares estimates of the parameters of an ARIMA model and two are for

computing the minimum mean square error forecasts using these estimates. Both

the estimation and forecasting subroutines allow several levels of control of

the computations and printed output. The estimation subroutines also allow

the user to specify a subset of the parameters to be treated as constants with

their values held fixed at their input values. This last feature allows the

user to examine the results obtained estimating various subsets of the

parameters of a general model without respecifying the model for each subset.

Each of the subroutines in this chapter models the input series, y^,

i = 1, ..., N, with a user-specified general multiplicative ARIMA model using

the techniques discussed in Box and Jenkins [1976]. Briefly, this model is

defined by

NFAC NFAC NFAC

[ n (44

> ( j)

(Bs (j)))][( n (vs(j) ) d (j>) yi -u] - [ n (e^^assU)))^

j=l j=l j=l

for i = 1,

N

NFAC

B

s

y

. . .

N, where

is the number of observations in the series;

is the number of factors in the model;

is the backward shift operator of order s, i.e.

bS v± = yi-s

;

is the expected value of the differenced series, i.e.

NFAC

y = E [

II (

s( j

J )) Yi ] , j-1

which can be used to allow for a deterministic polynomial trend;

<[>p(j )(B s (j

)

is the polynomial in B

S ^J^ of order p(j), i.e.,

Mj)(BS(J) > *

1 - - * 2> jB2*s<j> - ... *p( j ),j

BP<J),S(J)

. which represents the j

th autoregressive factor in the model;

13-1
(V

s ( j

)

) d ^^ is the backward difference operator, i.e.,

( v s( j ))

d( j ) = (1 - B

s ^ ) ) d ^ )

= 1 - d(j)Bs ^> + ... B

d (j)* s (j>,

which represents the j

th difference factor in the model;

0_q( j

)(

B

s ^j

)) is the polynomial in B

s ^j^ of order q(j), i.e.,

! - 01,jBS(j) - 02,jB2 - s <J) - ... 8 q(j)(j BqO)-8«),

which represents the j

1-*1 moving average factor in the model; and

a-j_ is the unobservable random noise component at the i

1-*1 observation.

The least squares estimates of the parameters,

4>1,1» $2,1* ***’ <f>p(l),l’ *1,2* ^p(NFAC) ,NFAC» u ’

0 1 S 1» 0 2, 1 » •••» 0 q ( 1 )

, 1 » 9

1 , 2 » •••» 0 q (NFAC) ,NFAC

are obtained using back forecasts at each iteration as discussed in §E.l.a.

The least squares solution is that which minimizes (with respect to the

parameters) the sum of the squares of the random noise components, a^ , i.e.,

N -

I *i

2 i=-oo

where carat (* ) denotes the estimated quantity. The iterative procedure used

is documented in chapter 9.

The user must supply both initial values for the parameters and an array

specifying the orders p(j)» d(j), q(j) and s(j) for each factor j = 1, ..., NFAC in the model. Initial parameter values for the estimation subroutines

should be chosen with care since good values can significantly reduce computer

time

.

Users are directed to §B for a brief description of the subrout

declaration and CALL statements are given in §C and the subroutine

are defined in §D. The algorithms used and output produced

subroutines are discussed in §E. Sample programs and their output

in §F.

ines. The

arguments

by these

are shown

13-2
B . Subroutine Descriptions

B.l ARIMA Estimation Subroutines

The simplest of the three ARIMA estimation subroutines, AIME,

automatically summarizes the estimated results and a variety of statistics in

a five-part printed report described in §E.2.a, and returns the estimated

parameters and residuals to the user via the subroutine argument list (level

one control). Most ARIMA estimation problems can be solved using AIME.

The other two estimation subroutines, AIMEC and AIMES, provide greater

flexibility to the user at the price of more input.

AIMEC, like AIME, also returns estimated parameters and residuals from

the fit. In addition, it allows the user to supply arguments to indicate

- a subset of the model parameters to be treated as constants,

with their values held fixed at their input values;

- the step sizes used to compute the numerical approximations to

the derivative as described in chapter 9, §E.l.b;

- the maximum number of iterations allowed;

- the convergence criteria;

- the scale (i.e. , the typical size) of each parameter;

- the maximum change allowed in the parameters at the first

iteration;

- how the variance-covariance matrix is to be approximated; and

- what sections of the five-part printed report are wanted.

AIMES has all the features of AIMEC and, in addition, returns the

following estimated values via the argument list: - the number of parameters actually estimated;

- the residual standard deviation;

- the predicted values;

- the standard deviations of the predicted values;

- the standardized residuals; and

- the variance-covariance matrix of the estimated parameters.

B ,2 ARIMA Forecasting Subroutines

The simplest of the three ARIMA forecasting subroutines, AIMF,

automatically summarizes the estimated results in a two-part printed report.

Forecasts are made using N as the origin and extending [N/10] + 1 steps into

the future, i.e., observations are forecast for indices N+l,

N+2, ..., N+[N/10]+1. Many forecasting problems can be solved using AIMF.

The second forecasting subroutine, AIMFS, allows the user to supply

arguments to indicate the number of forecasts to be made, the origins to be

13-3
used and the amount of printed output. This subroutine also returns the

forecasts and their standard deviations via the argument list.

C . Subroutine Declaration and CALL Statements

NOTE: Argument definitions and sample programs are given in §D and §F,

respectively. The conventions used to present the following declaration and

CALL statments are given in chapter 1, §B and §D.

The <basic declaration block> identifies declaration statements that are needed by all of the ARIMA estimation and forecasting subroutines. The user should substitute the following four statements for each occurrence of <basic

declaration block> given below.

<real> Y (n), PAR( npar)

INTEGER MSPEC (4 ,nfaa)

DOUBLE PRECISION DSTAK (Idstak)

COMMON / CSTAK/ DSTAK

Subroutine for ARIMA Estimation

AIME i Compute and print a five-part least squares analysis of the parameter

estimates of an ARIMA model ; return parameter estimates and residuals

<basic declaration block>

<real> RES(n)

CALL AIME (Y, N, MSPEC, NFAC , PAR, NPAR, RES, LDSTAK)

AIMEC : Compute and optionally print a five-part least squares analysis of

the parameter estimates of an ARIMA model using user- supplied control

values; return parameter estimates and residuals

<basic declaration block>

<real> RES(n)

INTEGER IFIXED (npar)

<real> STP (npar), STOPSS, STOPP, S CALE (npar

)

f DELTA

CALL AIMEC (Y, N, MSPEC, NFAC, PAR, NPAR, RES, LDSTAK,

1 IFIXED, STP, MIT, STOPSS, STOPP, SCALE, DELTA, IVAPRX , NPRT

)

13-4
AIMES: Compute and optionally print a five-part least squares analysis of

the parameter estimates of an ARIMA model using user-supplied control

values; return parameter estimates, residuals, number of parameters

estimated, residual standard deviation, predicted values, standard

deviations of the predicted values and variance-covariance matrix of

the estimated parameters

<basic declaration block>

<real> RES(rc)

INTEGER IFIXED (npar)

<real> STP(npar’), STOPSS, STOPP, SCALE (npar») , DELTA

<real> RSD, PV(rc), SDPV(n), SDRES(n), VCV (npare,npare)

CALL AIMES (Y, N, M, MSPEC, NFAR, PAR, NPAR, RES, LDSTAK,

1 IFIXED, STP, MIT, STOPSS, STOPP, SCALE, DELTA, IVAPRX, NPRT,

2 NPARE , RSD, PV, SDPV, SDRES , VCV , IVCV)

Subroutines for ARIMA Forecasting

AIMF: Compute and print the minimum mean square error forecasts obtained

using an ARIMA model

<basic declaration block>

CALL AIMF (Y, N, MSPEC, NFAC , PAR, NPAR, LDSTAK)

AIMFS: Compute and optionally print the minimum mean square error forecasts

obtained using an ARIMA model; return forecasts and their standard

errors

<basic declaration block>

<real> FCST (nfcst ,nfcsto)

SDFCST (nfcst)

INTEGER IFCSTO(nfesto)

CALL AIMFS (Y, N, MSPEC, NFAC, PAR, NPAR, LDSTAK,

1 NFCST, NFCSTO, IFCSTO, NPRT, FCST, IFCST, FCSTSD)

D. Dictionary of Subroutine Arguments and COMMON Variables

NOTE: —> indicates that the argument is input to the subroutine and that

the input value is preserved;

<— indicates that the argument is returned by the subroutine;

<-> indicates that the argument is input to the subroutine and that

the input value is overwritten by the subroutine;

indicates that the argument is input to some subroutines and is

returned by others; *** indicates that the argument is a subroutine name;

••• indicates that the variable is passed via COMMON.

13-5
DELTA --> The maximum scaled change allowed in the parameters at the first

iteration, i.e. , 6q. [See chapter 9, §E.l.a.] The default value

is 100.0. When DELTA < 0.0 or when DELTA is not an argument of

the subroutine CALL statement the default value is used. Normally, the default value should be used. However a smaller value of

DELTA may be appropriate if, at the first iteration, the computation of the predicted values produces an arithmetric overflow or the parameters leave the region of interest in parameter space. A

reasonable alternative to the default value of DELTA is an upper

bound to the scaled change that the estimated parameters should be

allowed to make on the first iteration,

DELTA = min{ |A max

PAR(k) | /SCALE(k), for k = 1, ..., NPAR}

where A_ovPAR(k) is the maximum change allowed for the k

1^

parameter at the first iteration.

DSTAK ••• The DOUBLE PRECISION vector in COMMON / CSTAK/ of dimension at

least LDSTAK. DSTAK provides workspace for the computations. The

first LDSTAK locations of DSTAK will be overwritten during

subroutine execution.

FCST <”- The array of dimension at least NFCST by NFCSTO that contains the

NFCST forecasts computed from each of the NFCSTO origins.

FCSTSD <— The vector of dimension at least NFCST that contains the standard

deviation of each of the forecasts,

K-l

FCSTSD(K) = RSD * ( J

'{' i 2

) 1/2 for K = 1, ..., NFCST,

‘j-o

where

= 1 and Yj = + ... + '['p+D * ^

j -P-D “ e

j

NFAC NFAC

with P = £ p(j); D = £ d(j); and

j=l j“l

ip ^ = the coefficient of B

1 in the polynomial defined by

NFAC

1 (tp(j)( BS(J) ))-((V s(j

)dj)

j=l

13-6
IERR *** An error flag returned in COMMON /ERRCHK/ . [See chapter 1, §D.5.]

Note that using (or not using) the error flag will not affect the

printed error messages that are automatically provided even when

the user has suppressed the normal printed output.

For AIME, AIMEC , and AIMES:

IERR = 0 indicates that no errors were detected and that the

iterations converged satisfactorily.

IERR = 1 indicates that improper input was detected.

IERR = 2 indicates that the computation of the residual sum of

squares using the initial parameter values produced an arithmetic overflow. The user should reduce the size

of DELTA or should supply new starting values.

IERR = 3 indicates that the model is computationally singular,

which means the model has too many parameters near the

solution. The user should examine the model and data

to identify and remove the cause of the singularity.

IERR = 4 indicates that at least one of the standardized residuals could not be computed because its standard

deviation was zero. The validity of the variancecovariance matrix is questionable.

IERR = 5 indicates false convergence. [See chapter 9, §E.l.a.]

IERR = 6 indicates that convergence was not reached in the

allowed number of iterations or model subroutine calls.

[See argument MIT.]

IERR = 7 indicates that the variance-covariance matrix could not

be computed because of computational difficulties.

For AIMF and AIMFS:

IERR = 0 indicates that no errors were detected and that all the

forecasts were computed.

IERR = 1 indicates that improper input was detected.

IFCST —> The exact value of the first dimension of the matrix FSCT as specified in the calling subroutine.

IFCSTO —> The vector of dimension at least NFCSTO that contains the NFCSTO

indices to be used as origins, where l < IFCSTO(J) < N for J = 1, ..., NFCSTO. The default value for each element of IFCSTO is N. When IFCSTO(J) is outside the range [1, N] or IFCSTO is not an argument of the subroutine CALL statement the default value is

used.

13-7
IFIXED -—> The vector of dimension at least NPAR that contains values used to

indicate whether the corresponding parameter in PAR is to be

treated as a fixed constant or is to be estimated. If

IFIXED(I)>0, PAR(I) will be held fixed at its input value; if

IFIXED( I )=0 , PAR ( I ) will be estimated using the least squares

procedure described in §A. The default values are IFIXED(I)=0, I = 1, . .., NPAR, i.e. , all parameters are estimated. When

IFIXED(1)<-1 or when IFIXED is not an argument of the subroutine

CALL statement the default value will be used.

IVCV ““> The exact value of the first dimension of the matrix VCV as specified in the calling program.

IVAPRX ---> The indicator variable used to specify how the variance-covariance

matrix, VCV, is to be approximated. Three approximations are available:

a <*» (1) VCV = RSD2 ® (DT «D)“ 1

(2) VCV = RSD2 • H”

1

(3) VCV --- RSD2 « H” 1

« (DT « D) •H~l

where

Dt j = aa-jyas (j ) for i

and j

<A. A N <*» /</=>. A H = D

T® D - { l a1 *(3 2 a

i /3e(j)36(k>) for j

i=l and k

The results of a recent study by Donaldso

indicate that approximation (1) is prefe

simple, less expensive, more numerically s accurate as approximations (2) and

approximations to the variance-covariance matrix are subject to

sampling variation because they are computed using the estimated

parameter values. The variance-covariance matrix computed for any

particular nonlinear least squares solution should thus be

regarded as only a rough estimate [Bard, 1974; Donaldson and

Schnabel, 1985] .

If IVAPRX - lor 4 then approximation (1) is used;

= 2 or 5 then approximation (2) is used; and

= 3 or 6 then approximation (3) is used.

The default value for IVAPRX is 1. When argument IVAPRX is

outside the range [1, 6] or when IVAPRX is not an argument of the

subroutine CALL statement then the default value is used.

= 1, = 1 ,

, N

, NPAR; and

= 1 , . .

.

, NPAR

= 1 ,

. . . , NPAR} .

n and Schnabel [1985]

rable because it is

table and at least as (3). However, all

1 3-8
LDSTAK —> The length of the DOUBLE PRECISION workspace vector DSTAK. LDSTAK

must equal or exceed the appropriate value given below, where if

the single precision version of STARPAC is being used P = 0.5,

otherwise P = 1.0. [See chapter 1, §B.] Also,

NFAC NFAC

MBO = maximum { [ (p( j )+d( j )) »s( j ) , £ qCj)-s(j) }.

j=l j-1

For AIME, AIMEC and AIMES:

LDSTAK ^ 43 + max{ IS* (N+NPAR) , 30+NPARE} + 2» NFAC + max { IS«10»N + 6*MB0+606.

94 + 4 • ( N+MB0+ 101) + 5»MBO + ( 3 « NPARE2 +3 5« NPARE ) / 2 }*P

where IS = 1 if default values are used for the derivative

step sizes, and IS = 0 otherwise.

For AIMF and AIMFS

LDSTAK > 18 + 2» NFAC + ( 5*MBO+2« (N+MBO+101)) •

MIT —-> The maximum number of iterations allowed. This argument is also

used to compute the maximum number of model subroutine calls,

(2*MIT). The iterations will stop if either limit is reached,

although, as a rule, the maximum number of iterations will be

reached first. The default value for the maximum number of

iterations is 21. When MIT < 0 or when MIT is not an argument of

the subroutine CALL statement the default value is used.

MSPEC —> The array of dimension exactly 4 rows

that contains the orders p, d, q and

model where p(j), j = 1, ..., NFAC must

d ( j ) , j = 1, ..., NFAC must

q(j), j = 1> •••» NFAC must

s(j), j = 1, ..., NFAC must

Values of p(j), d(j), q(j) and s(j), j

equal or exceed zero.

by at least NFAC columns

s for each factor in the

be in row 1,

be in row 2,

be in row 3, and

be in row 4. = 1, ..., NFAC, must each

N —> The number of observations.

NFAC —> The number of factors in the model.

NFCST —> The number of forecasts to be computed. The default value is

[N/10]+l. When NFCST<0 or when NFCST is not an argument of the

subroutine CALL statement the default value is used.

NFCSTO —> The number of forecast origins supplied. The default value is 1. When NFCSTO<0 or when NFCSTO is not an argument of the subroutine

CALL statement the default value is used.

13-9
NPAR —> The number of parameters in the model including both those held

fixed at their starting values and those which are to be

estimated,

NFAC

NPAR = 1 + l (p(j) + q(j)) . j-1

NPARE <— The number of parameters actually estimated, i.e. , the number of

zero elements in IFIXED. N.B. This value is returned by the

estimation subroutines.

NPRT —> The argument controlling printed output.

For AIME, AIMEC and AIMES:

NPRT is a five-digit integer for which the value of the I th

digit (counting from left to right) is used to control the I th

section of the output.

If the I

1-*1 digit = 0 the output from the I1-*1 section is

suppressed

;

= 1 the brief form of the I^ section is given;

> 2 the full form of the I

c ^ section is given.

The default value for NPRT is 11112. When NPRT < -1 or when

NPRT is not an argument in the subroutine CALL statement the

default value is used. If the convergence criteria are not

satisfied, the subroutine gives a suitable warning and provides

a printed report even if NPRT =0. A full discussion of the

printed output is given in §E.2.a and is summarized as follows.

Section 1 lists the starting estimates and control values.

Brief output and full output are the same for this

section.

Section 2 reports the results of the iterations. Brief output

includes information only about the first and last

iteration while full output includes information about

all of the iterations.

Section 3 provides information for each observation based on the

final solution. Brief output includes information for

the first 40 observations while full output provides

the information for all of the data.

Section 4 is a set of four residual plots. Brief output and

full output are the same for this section.

Section 5 is the final summary of the estimated parameters.

Brief output does not include printing the variancecovariance matrix while full output does.— continued —

13-10
For AIMF and AIMFS:

If NPRT = 0 the printed output is suppressed.

If NPRT * 0 the printed output is provided.

The default value for NPRT is 1. When NPRT<-1 or when NPRT is

not an argument in the subroutine CALL statement the default

value will be used.

PAR The vector of dimension at least NPAR that contains the parameter

values. For both the estimation and the forecasting subroutines,

parameter values must be ordered

*1,1* ^2,1* •••» *p(l),l. ^1,2’ '

0 ’ ^p(NFAC) ,NFAC S

M >

0 1,1» 8 2, 1 » 8 q( 1 )

, 1

’ 8

1 , 2> •••» 0 q(NFAC),NFAC»

i.e., the parameter values from the autoregressive factors are first, followed by p, followed by the parameter values from the

moving average factors. For all estimation subroutines PAR must

contain initial values for the parameters on input and will

contain the final values on return. For the forecasting subroutines PAR must contain the parameter values for which the

forecasts are to be computed.

PV <—• The vector of dimension at least N that contains the predicted

values of the dependent variable at the solution,

A PV(i) = yi “ a

i for i = 1, .

. , N.

RES <-- The vector of dimension at least N that contains the residuals at

the solution,

A RES(i) = a(i) for i = 1, ..., N„

RSD <— The residual standard deviation at the solution,

N

1/2

RSD = [( l RES(i) 2 )/(N-NPARDF-NPARE)]

i=l

NFAC

where NPARDF = £ s(j)*d(j) . j-1

13-1
SCALE --> The vector of dimension at least NPAR that contains the scale, or typical size, of each parameter. The vector SCALE is used to

normalize the size of each parameter so that

| PAR^ ( j ) / SCALE(j ) | » |PAR.£ (k) /SCALE (k) | for j = 1 , ..., NPAR

and k = 1 , .

.

.

,

NPAR,

where PAR^ ( j ) is the value of the j

th parameter at the £

th

iteration. Values of |SCALE(k)| > |PAR^(k)| can be used to

increase the step size in cases where the model function is known

to be insensitive to small changes in the value PAR^(k), although

normally the default values should be used.

The default values for SCALE are selected by the NL2S0L algorithm

[Dennis et al® 1981a and 1981b] and are updated at each

iteration. When SCALE is not an argument in the subroutine CALL

statement or when the user-supplied value for SCALE(1)<0 the

default procedure will be used to select scale values. When

SCALE(1)>0, values of SCALE(k)<0 for k = 2, ..., NPAR will be

interpreted as an input error. User-supplied scale values may be

either a vector of the typical size of each parameter or a vector

of ones if the typical sizes of the parameters are roughly equal;

user-supplied scale values can sometimes result in reduced com- puting time since these values are not updated at each iteration.

SDPV <— The vector of dimension at least N that contains an approximation

to the standard deviation of each predicted value at the

solution,

A A SDPV(i) = the i

t ^1 diagonal element of [ (D» VCV» D^)]

for i - 1, N, where

Djj = 9 a^/88 (j ) for i = 1, . .., N and j = 1, ..., NPAR.

This approximation is based on a linearization of the model in the

neighborhood of the solution; the validity of the approximation

depends on the nonlinearity of the model. This approximation may

be extremely inaccurate for a problem with a highly nonlinear

model.

SDRES <— The vector of dimension at least N that contains an approximation

to the standardized residuals at the solution,

SDRES (i ) - RES(i) /[ RSD2 -SDPV(i ) 2

]

1 72

for i = 1, . N, which is the i

11 *1 residual divided by its

individual estimated standard deviation. This approximation is

based on a linearization of the model in the neighborhood of the

solution; the validity of the approximation depends on the

nonlinearity of the model. This approximation may be extremely

inaccurate for a problem with a highly nonlinear model.

13-12
STOPP --> The stopping value for the convergence test based on the maximum

scaled relative change in the parameters at the most recent

iteration. The convergence criterion is satisfied if the current

step is a Newton step and

max{ |PAR„+i (k)-PAR„ (k) |

| /SCALE (k) for k = 1, ..., NPAR}

max{ | n PARj£ + 1 (k) | + PAR^ (k) | J / SCALE (k) for k = 1, ..., NPAR}

< STOPP

where PAR^(k) is the value of the k*-*1 parameter at the 2^

iteration. [See Dennis et al. 1981a. ] This convergence test is

roughly equivalent to the test based on the maximum relative

change in each parameter as measured by

max{ |PAR£+1 (k)-PAR£ (k)|/|PAR^(k)| for k = 1, ..., NPAR} .

STOPP is not a scale-dependent value; if its value is 10“**

, then

this criteria will be met when the first four digits of each

parameter are the same at two successive iterations regardless of

the size of the parameter values.

The default value is approximately io~DIGITS/2^ where DIGITS is

the number of decimal digits carried by the user's computer for a single precision value when the single precision version of

STARPAC is being used and is the number carried for a double

precision value otherwise. When the user-supplied value for STOPP

is outside the interval [0.0, 1.0] or when STOPP is not an argument of the subroutine CALL statement the default value is

used.

STOPSS --> The stopping value for the convergence test based on the ratio of

the forecasted change in the residual sum of squares at iteration

2+1, ARSS^+i, to the residual sum of squares at iteration 2 ,

N - RSS^ =

£

. i=-oo

The convergence criterion is satisfied if certain conditions are met and

ARSS£ +1 /RSS£ < STOPSS.

[See Dennis et al. 1981a.] This convergence test is roughly

equivalent to the test based on the relative change in the

residual standard deviation between two iterations 2 and 2+1 as measured by (RSS£ 1/2 - RSS^+j 1 /2 VRSS^ 1 /2 . STOPSS is not a scaledependent value; if its value is 10

-

^ this criteria will be met

when the first five digits of the residual sum of squares are the same at two successive iterations regardless of the size of the

residual sum of squares. — continued —

13-13
STP

VCV

The default value is approximately the maximum of 10 ^ and

10~2.DIGITS/3

> where DIGITS is the number of decimal digits

carried by the user’s computer for a single precision value when

the single precision version of STARPAC is being used and is the

number carried for a double precision value otherwise. When the

user-supplied value for STOPSS is outside the interval

[10 0.1] or when STOPSS is not an argument of the

subroutine CALL statement the default value will be used. — The vector of dimension at least NPAR that contains the relative

step sizes used by the estimation subroutines to approximate the

derivative matrix numerically. The procedure used to select the

default values is described in chapter 9, §E.l.a. When STP is not an argument of the subroutine CALL statement or when STP(1)<0 the

default values will be used for all of the step sizes; when

STP( 1 )>0 s values of STP(k)<0 for k = 2, ..., NPAR will be

interpreted as an input error.

<-- The matrix of dimension at least NPARE by NPARE that contains the

variance-covariance matrix of the estimated parameters, approximated as designated by argument IVAPRX. The parameters which are held fixed (as specified by argument IFIXED) are not included in

the variance-covariance matrix.

The approximation of the variance-covariance matrix is based on a linearization of the model in the neighborhood of the solution;

the validity of the approximation depends on the nonlinearity of

the model. This approximation may be extremely inaccurate for a problem with a highly nonlinear model.

Y —> The vector of dimension at least N that contains the series being

modeled.

E o Computational Methods

E . 1 Algorithms

E.l.a ARIMA Estimation

The ARIMA estimation subroutines use the NL2S0L software package written

by Dennis et al. [1981a and 1981b]. The observations of the series, which are measured with error, are iteratively fit to the ARIMA model by minimizing the sums of squares of the estimated random noise component as described in §A.

The back forecasting technique discussed on pages 215-220 of Box and Jenkins

[1976] is used to compute the random noise component. Up to 101 back

forecasts are computed. The back forecasts are assumed to be negligible when

their magnitude is less than 0.01 times the first value of the differenced

series (centered about its mean) obtained entirely from the observed data.

If, at the last iteration, the 101 st back forecast is not negligible a warning

message is printed.

13-14
The iterations continue until the convergence criteria based on the

change in the parameter values or in the residual sum of squares are satisfied

[arguments STOPP and STOPSS], the maximum number of iterations (or model

subroutine calls) is reached [argument MIT], or the iterations are terminated

due to singularity in the model or false convergence. All but the first of

these stopping conditions may indicate computational problems and will produce

an error report. [See chapter 1, §D . 5 . ] Singular convergence means that the

model contains too many parameters, at least near the solution, while false

convergence can indicate that either STOPSS or STOPP is set too small for the

accuracy to which the model and its derivatives are being computed or that

there is a discontinuity in the derivative. Iterative procedures for solving

nonlinear least squares problems are discussed in Dennis and Schnabel [1983],

Draper and Smith [1981] , and Kennedy and Gentle [1980] . The specific

procedure used in STARPAC is discussed in chapter 9 and Dennis et al.

[1981a]

E.l.b ARIMA Forecasting

The ARIMA forecasting subroutines use the techniques discussed in Box and

Jenkins [1976], chapter 5. The back forecasting technique discussed on pages

215-220 of Box and Jenkins [1976] is used to compute the random noise

component needed for the forecasts. Values of a^ for i greater than the

forecast origin are assumed to be zero. Up to 101 back forecasts are computed. The back forecasts are assumed to be negligible when their

magnitude is less than 0.01 times the first value of the differenced series

(centered about its mean) obtained entirely from the observed data. If the

101 st back forecast is not negligible a warning message is printed.

E . 2 Computed Results and Printed Output

E„2.a The ARIMA Estimation Subroutines

The argument controlling the printed output, NPRT, is discussed in §D.

The output from the ARIMA estimation subroutines consists of five

sections, several of which include tables summarizing the results. In the

following descriptions, the actual table headings are given by the underlined,

uppercase phrases. Results which correspond to input or returned subroutine

CALL statement arguments are identified by the argument name in uppercase

(not underlined).

Section 1 provides a summary of the initial estimates and control values. It

lists the following information.

© The initial values of the parameters, PAR, and whether they are to be

held fixed or not as indicated by argument IFIXED.

• The scale values, SCALE.

13-15
• The step sizes used to approximate the derivatives numerically, STP.

• The number of observations, N.

• The maximum number of iterations allowed, MIT.

• The maximum number of model subroutine calls allowed.

• The two convergence criteria, STOPSS and STOPP.

• The maximum change in the parameters allowed at the first iteration,

DELTA.

• The residual sum of squares computed using the starting parameter

values.

• The residual standard deviation computed using the starting parameter

values, RSD.

Section 2 lists selected information about each iteration and includes the

reason the iterations were terminated. The information provided for

each iteration includes the following.

• The iteration number.

• MODEL CALLS ; the total number of times since execution began that the

user's model subroutine has been called, not including calls required

to approximate the derivatives numerically.

• RSD i the residual standard deviation computed using the parameter

values from the current iteration.

• RSS s the residual sum of squares computed using the parameter values

from the current iteration.

® REL CHNG RSS ; the relative change in the residual sum of squares

resulting from the current iteration.

• FORECASTED REL CHNG RSS : the forecasted relative change in the residual sum of squares at the current iteration and whether this value was checked against STOPSS ( CHKD = Y) or not ( CHKD = N).

• REL CHNG PAR : the maximum scaled relative change in the parameters at

the current iteration and whether this value was checked against STOPP

( CHKD = Y) or not ( CHKD = N).

• CURRENT PARAMETER VALUES : the estimated parameter values resulting

from the current iteration.

13-16
Section 3 provides the following information for each observation, i = 1,

N, based on the final solution.

• ROW : the row number of the observations.

© SERIES : the value of the dependent variable, Y.

• PREDICTED VALUE : the estimated predicted value, PV, from the fit.

© STD DEV OF PREP VALUE : the standard deviation of the predicted

value, SDPV.

© RESIDUAL : the error estimate, RES.

• STD RES ; the standardized residual, SDRES.

Section 4 displays the following plots.

© The standardized residuals versus row numbers.

• The autocorrelation function of the (non-standardized) residuals.

• The normal probability plot of the standardized residuals.

Section 5 summarizes the following information about the final parameter

estimates and their variances.

• The variance-covariance matrix, VCV, of the estimated (unfixed)

parameters and the corresponding correlation matrix,

r jk = VCV(j,k)/(VCV(j,j) VCV(k,k))

1/2

for j = 1, ..., NPARE

and k = 1, ..., NPARE.

• PARAMETER ESTIMATES (PAR) : the final value of each parameter, PAR(k),

k = 1 , . .

.

NPAR.

© STD DEV OF PARAMETER ESTIMATES : the standard deviation of each

estimated parameter,

( VCV(k,k)) 1/2 for k = 1, ..., NPAR.

• RATIO PAR/SD OF PAR : the ratio of each estimated parameter to its

standard deviation,

RATIOk = PAR(k)/(VCV(k,k)) 1/2 f or k = 1 , ..., NPAR.

• APPROXIMATE 95-PERCENT CONFIDENCE LIMITS : the lower and upper

95-percent confidence limits for each parameter, computed using the

appropriate value of the Student's t distribution with

13-17
NFAC

N - ( l s(j )*d(j )) - NPARE

i=l

degrees of freedom.

• The residual sum of squares at the solution.

• The residual standard deviation at the solution, RSD.

NFAC

® The residual degrees of freedom, N - ( £ s(j)*d(j)) - NPARE.

i=l

• An approximation to the condition number of the derivative matrix,

Djj = 3ai /8g(j) for i = 1, ..., N and j = 1, ..., NPAR

(the Jacobian), under the assumption that the absolute error in each

column of D is roughly equal. The approximation will be meaningless

if this assumption is not valid; otherwise it will usually

underestimate the actual condition number by a factor of from 2 to 10

[see Dongarra et al. 1979, page 9.5],

NOTE ; The standard deviation of the predicted values, the standardized

residuals, the variance-covariance matrix, the standard deviations of the

parameters and the 95-percent confidence limits on the parameters are all

based on a linear approximation to the model in a neighborhood of the

solution; the validity of this approximation depends on the nonlinearity of

the model. The statistics based on this approximation may be extremely

inaccurate for a problem with a highly nonlinear model.

E„2.b The ARIMA Forecasting Subroutines

The argument controlling the printed output, NPRT, is discussed in §D.

The output from the ARIMA forecasting subroutines consists of a summary

of the model used to produce the forecasts and, for each origin, a plot and a list of the computed forecasts and a 95-percent confidence interval about the

forecasts along with the actual series value when known.

The sample

table 9.1 of Box

programs of this

and Jenkins [1976]

section use the

; the model is

model and data given in

V 1

X *V 121

® y± - v = (i-e 1>r Bi) ° (1—01,2*®^) * a-L for i = 1 , ... , N.

13-18
ARIMA Estimation . In the sample program of figure F-la, AIME is used to

compute the least squares estimates of the parameters; figures F-lb through

F-lf show the output from AIME.

ARIMA Forecasting . In the sample program of figures F-2a, AIMF is used

to compute the minimum mean square error forecasts using the least squares

estimates obtained in example 1; figures F-2b and F-2c show the output from

AIMF.

13-19
ARIMA Estimation

IAIN PROGRAM*

cc

c

c

ec

c

c

c

c

c

c

c

c

e

c

c

cc

ec

PROGRAM EXANPL DEMONSTRATE AI«E OSINS SINGLE PRECISION VERSION QF STARPAC

PUN ON CYBER 180/8*0.

OUTPUT UNIT IS % ( AUTOMATIC ALLY EQUATED TO PILE T* 9 E6 ON CY8EPS)

ISEE CHAPTER 1, SECTION D.*3

N.B. DECLARATION OP Y» **, PAR AND RES NUST 9E CHANGED TO OOUBLE PRECISION

IP DOUBLE PRECISION VERSION OF STARPAC IS USED. INTEGER “$ PEC ( *» 5 ) REAL Y ( 200 ) f P AR t 5 J # 8ES«200>

DOUBLE PRECISION 0STAM5006I

CONNQN /CSTAN/ ostak DEFINE VARIABLES FOR VARIOUS OINENSIONS

LDSTAK • 5006

READ NU“BER OP FACTORS IN MODEL VALUES OP »» 0, a AND S p nR EACH factor NU»BER OP PARANETERS

STARTIN6 VALUES FOR PARANETERS

NUNBE® OP observations

OBSERVED SERIES READ 100* N F AC READ 100* UHSPEC(X.J)* I»1**J» J«l f NPAC)

READ 100* near

READ 101* (PAR(I), I«1*NPAR»

READ 10 0* N READ 101, (YCH* I-l.NJ

c

C COMPUTE LOG OP OATA

C DO 10 I 1. N

Y( I ) « AL06 ( Y( I )

10 CONTINUE

c PRINT TITLE and CALL A I* E TO PERFORM ARINA ESTIMATION ANALYSIS

C VR XTE <6* 192) CALL A I N | (Y, N» N$P|C» NF AC » 9 AR » NPAR, RES* LDSTAK)

C STOP

c

c FORMAT STATEMENTS

c loe format i*is)

101 FORMAT { 12F6 . 1 ) 10 1 POR«AT (UBESUITS OP STARPAC ARINA E ST !AT ION SUBROUTINE A INE ' ) C END DATA* 20

0 111 1 1 12

3 9.0 0.* 0.6

U*

112.0 118.0 132.0 129.0 121.0 135.0 1*8.0 1*8.0 136.0 119.0 10*.

118.9

115.0 13 6.0 1*1.0 135.0 125.0 1*9.0 170.0 170.0 138.0 133.0 11*.1*0.0

1*5.0 150.0 1TB.

163.

172.0 178.0 199,0 199.0 18*. 0 162.0 1*6.0 166.0

171.0 1 80.0 193.0 181.0 133.0 218.0 230.0 2*2.0 299.0 191.0 172.0 19*.

196.0 196.0 236.0 235.0 229.0 2*3.0 26*.

272.0 237.9 211 .0 180.0 201 .0 20*.

198.0 235.0 227.0 23*.26* .0 302.0 293 .0 259.0 229.0 203.0 229.9

2*2 .0 233.0 267.0 269.9 270.0 315.0 36*.

3*7.0 312.0 27*.

237.0 278.0

28*.

277.0 117.

33 3.0 319.0 37*.

*13.0 *05.0 355.0 306.0 271.0 306.0

915.0 101.0 156.0 3*8.0 359.0 *22.0 *65.0 *67.6 *04.0 3*7.0 305.0 336.0

3*0.0 318.0 1*2.0 3*8.0 363 .0 *35.0 *91.0 505.0 *0* .0 359.0 310.0 337.0

360.0 3*2.0 *06.0 396.0 *20.0 *72.0 5*8.0 559.0 *63.0 *97.9 367.0 05.0

*17.0 391.0 *19.0 *61.0 *72.0 535.0 622.0 606.0 308.0 *61.9 390.0 *32.0

Figure F-la

Example program and data using AIME

13-20
USI«£

BACKFOftECmS

ft V» UI o* # 4 « OZ>4 o o o

a, ~ » 8- III & isi m NT> I a ui & at O

u* 0t l » c § t I I I I f

&• + **

ft. *% ^ 0* 0 O1 I U0 UI

«* «% ^ MA

<© ft

©

u=zu

GO© I m©

© « o • Z »

<8 « c • W •

or *

ftz

ft « * «*

atUS

!*> * UI » « Z

€> ft Z • m • M H f y|

•A •

U3 V» • UI

ft • 01 r * < •-* ©

or # o o w # O • >» ^ • w* ft ft t UI © Z * * £ I

»“ II £1o I W I 21o II 5 I u» I

ft -* 3 ©© UO ft < ft mu a. u. u. I M UI UI UI I © o o ; I : i I I I I : ; o o o © © ©

u# ui ui ft« © © © 24 *lit i ! 2• t- t 4 o o o a e © 4 im •

ItM lit 4 I —

Z ft or z ft

aC o o o © •ft z u* ft Ml

cs.

O ut z z z ft UI ft* ft* ft ft

© <4 *4

W

K©

©

© or UI ft

© - M UI UI UI z ft ft o u © UI •ft Z ft ft Z • 4 1 © Z ft ft> Z or * 4

ft i -J

A1 ft ft

© ft

u -1 t- UI Z ft ft ft ft

© <4 ^4

M ft

© z o ft

u« or I O-C «u o •ft z UI 4 u. o ui j ^4 •ft or UI ft UI X o 1 z ft - z > s z z

or or o ©

U »ft o o

uiO ft •ft or z u. 4 o

ft o o - 1 o Ui ft Uft Ui

44> ui I •ft -j u. > -1 ft ft Ui z Z M or Ui ft UI o Ui 4 ft o •ft z Ui o z - ft Ui ft > U. o or ui © ^ ~ o o o ft ft UI O © O u.

-ft ft. >- *- or Ui Ui

—

J o o u 1- o 4 1 o o o o I- ft ft ft M

U- - » or ft

O

U £

ft UI 4 Ui o Ui u ft -ft •ft Ui UI u 10 X ft UI or H «V

ft- o V -w o Z 5

UI S2 ft

© ft- Ui

M

© o X ft ft o o o

—I •ft Z K o Ui ft

M

—I

•1 Z

Ui u. z 5

ftO ft z ft ft o O or 3 ft u. Z 5 © © O ft 4 ft! ft Ui z z Ui z o o o X Ui m~ ft 4 > 4 M 4 UI © Z ft ft z ft u ft ft X © ft ft o ft U« Ui ft

«-i Z Z Z o z ft ft ft

-CI Ci°

0)w3

DC

13-21

Example

of

AIME

output
USKH6

BACKFOftECASfS*

CONIINUiC

<%

m © «e>> © X © v

x X X w u

© « «

X © X ©

x e X 1 ^ U£ |M &>w m

© © © ^

«S «(

Mi © d« «!<<• « » «* « » «* • ©

met ** © VI X ©MX <aS t&s es x wftX

ttt *> «a* » W

© m «& *

t

Off © ©

e © X © © X (P« X V» X 0 <u> x 0 t«g <*> ttf a*) Mf »UMfi6 © » © © © © M

X G «; «fi e^<^# W tA* © © tfc. M© ©

X « » © «>M © • © X

«s © M © Ifc M © *4 © m 0 m « ft 94

Ml m tie ©

VI *® o © f» ©

«£ X M © X © XI m X M © X © ©

«J> 01 *4 U> at

tie 9 m © © «© X <a£ • *4 © © ttfl 00 m X X

*-

I U-0» w

5c

Cl.

m

13-22

F.xanple

of

AlME

output

(continued)
RESULTS

FROM

LEAST

SQUARES

FIT

uuO

I

l/S oO

©w

I I

I I Oh ««»k r

r

* r * § § i* r i « »<> I I HH I | f4 H|rMMf4 | |

I *4 II oooooooooooooooooooooooooooooooooooooooo I I I I I I • I I I I I I I I I I « I I I I I I I I • I I I I I • I I I • I I I

»«MO«NOM»N^KO«f«Kt>AOMRKf4AMMHO»A«VHON«ON<\«M

0

1

0) u

3

&C

I • III! I I I I I • I I I I I I » C S

mJ

>> M m >

a o

O ui

I I

i I I •

s ooooopooooooopooooooopopooopopooooooooop -j iiiiiTiiiiiiiTiTiiiiiTiTiiiTiTiiiiiiiiiT

#«H«u^ 60 K«s^K^#Nor*>cM 9 «oooreoHP«oK^rtHr^mnfM

Mn«M\NN«NNNA 9 HMC«O» 0 NNMI»«N«CMh>H» 9 NM 0 MW>fl

ooooeooooooooooooooooo «*«* >00000000000000

M> PKO#KR4 (nM 0 NMO<#«MK#i>K»fn^M»##^H«O 0 O#NOKH^KH

^ O ® h> l >-#® 0 ®»# 0 ® 9 CK 0 i h>^COC^OO 9 ^®K^®^^*^OHO 9 ^ 0 »OHHON®migO 9 HHHHM

OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO

®#HNO-rNN-#«o-#NHO-#m®®®®»®w® 9 0 OH» NHH® # 0 ©®KMNN®H 0 ®<MM^M®OKK®HH®K O O (

m®M®®® 00 fn® 0 ® 9 MO 0 ®O^®#^®®®K® 0 OK 0 00 ® 0000 ^ 00000 ^ ONK#K 00 O®®O® 0®0

OOOHK 0 h 000 p 0 O® 0 ®® 00 ^H 0 O®®OOH 00 H 0 ®®O ^NO®^OOOO^®NK®OO0OHHO0f*0®OHO0HMMMOOHHHNH

X HN®0®®K0OOHfg000®h-0OOHISi®0®®N®OOHN0«®®^0OO • • • -#•

13-23

pjxample

of

AfMR

output

(continued)
USINS

MCKFORECmS#

COWllMUfe

&DGa

m

•<

m i s i *

8 at o © I m 6c

«* e » «i

e m c e 6 * e

§8

I

IC

II

I

6I

8

8

8 8 8 8 6 8 I c C i 8 0 c 0 8 8 6 c 8 « 8 « e

• c e

«>*

«- # e

8 c ©

C •

<e «

« «

«•

«>

«> *

« «>

«

€>

• I I • 8 18 I I 88 I 8 I I (III I *

•

I N

*, s •

• I * I • I

2 l C ‘ «

%

•AC

«

i

8

*

• €

C | fc | 8 c fi | 8 | I 8

C I 8 I t C 8 I 8 D C 8 8

8 0 C I 6 m

e

e i 8 i

i l l I

licit

! i|

I o•

• o

I

II

I•

II

I

• € m.

• l c • r *e

I I o

o

I •

I

I

I

•

I

I o

cititcttitcifiitct 8 t t c 1 i t t i • I licit • I I I o licit

I o

c o

• I •

*u

0>

I CU. *->

ac

LxLx: X

C-E

<0X

u:

13-24

i

i

i

i

i

i

i

i

i

i

i

i

i

i

i

s

i

i

i
USINC

a*CKF0*£C4STS»

CONTINUED 4c c ^

**

© z a w O U «!

moo o o o •

4)

m • ©

© & +4 *+ N ^

«M

©

© poo • U4 Utf 141

f*>

W

©©

©

<SS©

<M©• © • I © <«* © •* *4 M« o o o

«• I a 6 8*5 II Ml 0 C I © 9

1*1 9 » I « 9 O I m 9 H 9 © 9

** 0 8* 9 •*3 09 l*D 0 51I i*» 9 O 9• «n | W) 9 U 9 *o 0 « I - 0 © 0 X 00 Z I O 0 +* 00 < 9 -» 0 Ml 0 Z 9 4 0 — 99 ^ 9 > 0 SI0 0 Ml 0 SI o©

=> o z or

«/»

O

© 0MMf z o z O MJ UJ > MIM OO ZU UI 0 HM 40 < u. © X u. • i*i Om at O

a. o •*O 4 u >u 0 110

© I ** < © < o < 0

??1*1 Ml © • O K i «d n « ©

??UJ Ml • o 0 Us- © - 0 Ml 0 0 »- 0 9 5 l © (**

m

w # r» f- ** «-S O o o o 0 « 0o o o 9 0 0 © ©© © ^ *» © © © © • © • • OO o o o 0 Ml Ml Ml o n «* ON

nm© • 9 •

fi

g 0 Ml 1 o0 z 1 M

©u

^=5I Ex*

a>ij3

&C

tH

Ex*

?• ^ • « © oo o M o o © o *— 3 0 K O o o O

13-25

Example

of

AIME

output

(continued)
ARIMA Forecasting,

A I N »» OSSA "

6

••C 6 *A*

ee OfiONSTMTI Al BE USINS SINGLE EtfCISION VEtSIO* OE STAt»AC

C »UH ON CT8E» 180/840.

C

C OUT tuT UNIT IS 8 (AUTO»lTK»UT EOUATED TO ERE T*t E 6 ON CTBEIS)

C tSEE CHAtTIt l, SECTION O.AJ

C

C 9.8. OEClAtAYIgN OE v ANO »At nusT BE Chanced To DOUBLE ••ECISIPN

C 1 E DOUBLE B*EC IS I ON VEISION OE ST At E ac IS USED.

C INTfSE# NSt«C(A,5)

•E*L v(200). t At ( J

)

DOUBLE ttECISION 0STAM8000)

c CONNON / CSTAK / ostak

c

C OEEINI VAt I able S to* VAtlOUS 0 I*ENS IONS

c LOSTak e 9090

c

C *E AO NUNBEt Of EACTOtS IN n<J0EL

C VALUES OE t, 0, 0 ANO S E 01 Each EaCTQC

C NUNBEt OE t At A "E T M J

C VALUES E Qt EAt ANfTEtS

C NU«8Et OE rtSEtVATIONS

C OBSItVEO Situs

c

t

f

ao loo , ne ac

•E AO KO* UNSEEC(I»JI» i«i.4i» j*i,neac>

•E AO 100* NEAt

BEAD 101, (EAtCII, I«l,NEAtJ

• I AO lOOt N bead 102 * <vm* i *i# n i c

C CO-EUTE LOS OE CATA

C DO 10 I • 1, N raj • ALOsmin

10 CONTINUE

• BINT TITLE AH C CALL A 1*8 TO *|tEOtN aIINa eoiecaSTINC ANALYSIS

vtfTf ( 8, 101)

CALL A I "E (V, N, *S»EC, NE AC » *At * NEAt, LDSTAO

STOE EOtNAT STATENfNTS

106 EOtNAT (415)

101 E08NAT (12E4.1I

102 e Dt *AT (12E4.3)

103 EOtNAT CHESULTS OE STAtEAC AtINA EOtECASTINS SUBtOUTINE AlNf«)

END

9 aTa 8 29 1 1 1 0

3

1 1 12 0.000 0 . 3<»5 0.615

144 112.0 116.0 132.0 129 .

C

121.0 135.0

11 ! sO 1

* 6.0 1 * 1 .

C

135 .

C

125.0 149,0

149.0 150,0 1 ? 8.3 163.0 172.0 17 8.0

171 .0 160.0 103.0 181.0 183.0 218.0

196.0 1 «6.0 236.0 235.0 229.0 243.0

204.0 16 B .0 23«.0 227.0 * 34.0 264.0

242 .

C

233.0 267.0 269.0 270.0 315.0

264.0 27?.

0

317.0 313.0 318.0 374.0

315.0 301.0 356.0 348.0 155.0 * 22.0

346 .

C

318.0 362.0 348.0 163.0 415.0

3

* 0.0 342.0 406.0 306 .

C

420.0 472 .0 417.0 301.

0

419.0 461.0 472.0 535.0

Figure F-2a

148.0 141.0 136.0 114.0 104.0 118.0

170.

0

1 TO .0 158.0 133.0 114.0 140.0

1 * 9.0 199.0 184.0 162 .0 146 .0 166.0

230.0 242.0 209.0 191 .0 172.0 1 « 4.0

264.0 272.

0

237.0 211.0 180.0 201.0

302.0 293.0 29 B.O 229.0 201.0 224.0

364.0 3 * 7.0 112.0 274.0 237.0 278.0

* 11.0 403.0 395.0 106.0 271.0 306.0

465.0 4 * 7.0 * 04.0 347.0 105.0 116.0

491.0 505.0 * 04.0 354 .0 110.0 > 37.0

548.0 559.0 463.0 407.0 162.0 405.0

622.0 606.0 508.0 461.0 390.0 432.0

Example program and data using AIMF

13-26
F0RECASTIN6

SUBR0UTm

AINE

STaRP

*C2.

00SotCEHBER

1995 •

IRINA

FORICASTIN6 * uttt atO

u,Xu

ft. vt

u» uj ft

ft IU4 t. I 8 I8I o o o o o o o o o o o o o o o OAD O^H

©I ft

«ta

N8 O Ui I M o oo O U-o o4 O o o

JO

CN|I u-0) u

Sc

u.

13-27

Example

of

AIMF

output
ARINA

FORECASTING*,

CONTINUED 0 31 • 30 m u x i o ^ a ^ o < i o •< o ^ ^

Vt, I 0 e ^ *4 • t i i S I # M «rf » 9 I • « • • • I t « « « I t I fi t® V* « « * *x U£ -B. UjMft W u c &> I u I i u AS i 1 O’ ui 1 fi a. 10 6 1 at fi « 1 f < 8 X fi fi e oe «*> « «

fi | IU

w i 8 3 tef 8 fi o e

fi fi m£ fi

O « *4 «4«\K 0 0 4^9

r4»«»*4^A»#^««CA#

MMN #*<#9 # «

®«jR«f Nf 00R4P4 © ^ ^ eoMA0o«o«9e0» © 01 *% ©©*©«<«©<

0*

M

«S f

fe? 6 t«#(rt^0<#«4»O0O0*4l

MO 6 m I M^0«M0»0ON000< ©I

Ms I 000 r4O«»^O00NMI ( fi #Q0 »O«90 GO *r*M O ' f fi R(OOfMKlfi |f f ANONNI e 6 ©••©••••••••• 8 fi «00«0000«000«t 6 s

fi 0 di^MA000k«»O»«N0000K< #####0##00000A0000| R< 94 R( rR «c r< r4*4«<r4r<r<N^#<94i

40

9>

M

m

M

M

M

M

M « » M

M

M M>

M «M

M

M » • © W © «. ^9 § © fi si« i :• tui el « II « I « II I * SI » I • I I « I • * I

T!I I i I I MI I ! II

fiI © • i m •* * © fi fi H ** • © © © X s *=» « © fi **

0& «** 0 © fi © G • l • © i 0 © • «*? o ©

It* !*> • 9 ©

9ft

w » «

&s 9\

«® <C

O •«:«*» ir < r-. o »»

U 0

UU •

(S©

Ur

I- I

(J

<NII u.Vu

13-28

Kx

ample

of

AIHF

output

(continued)
r*

vj • Acknowledgments

The subroutines used to compute the least squares solution are those

referenced in Dennis et al. [1981], The algorithm used to select optimum step

sizes for numerical derivatives was developed by Schnabel [1982]. The printed

output for the ARIMA estimation subroutines has been modeled in part on the

linear least squares output used by OMNITAB II [Hogben et al. 1971],

13-29
-
Appendix A

CONTINUITY OF VERTICAL PLOTS

ON THE CDC CYBER 840 AND 855

Normally, a line printer will automatically provide margins at the top

and bottom of each page causing a break in the continuity of a vertical plot

extending over two or more pages. However, these automatic page-ejects

within a vertical plot can be suppressed by the user on many systems. On the

CDC Cyber 840 and 855 model machines this would be done by printing a Q

carriage control in column one immediately before the call to the vertical

plot routine. Printing an R carriage control will cancel this effect. For

example, the sequence

WRITE (6, 100)

100 FORMAT (1H1 , 23HTITLE FOR VERTICAL PLOT)

WRITE (6, 101)

101 FORMAT (1HQ)

CALL VP (Y, N)

WRITE (6, 102)

102 FORMAT (1HR)

will produce a vertical plot beginning on a new page, without any breaks in

continuity and without affecting the automatic page-ejects in the rest of the

output. Users of other systems should consult their Computer Center staff for

any equivalent method available.

A-l

Appendix B

WEIGHTED LEAST SQUARES

Weighted least squares can be used to eliminate observations from the

analysis and to compensate for unequal variances in the observational errors.

Observations can be eliminated from the analysis by using weight values

consisting only of zeros and ones. This will produce the same results as performing an unweighted analysis with the zero-weighted values removed except

that the predicted values, the standard deviations of the predicted values,

and the residuals of the zero-weighted data are computed. There are two main

reasons for weighting observations zero. The first is to obtain the predicted

values and their standard deviations for a set of independent variables not

included in the observed data. (This is done by assigning any arbitrary value

to the dependent variable of the desired set of independent variables, and

then weighting these values zero. ) The second reason is to allow easy

examination of the effect of outliers and influential data points. Outliers

often appear as large values in residual plots. Careful checking of the data

often leads to confirmation that the data are in error, and sometimes to a correction. When a cause for suspicious data cannot be found, it may be

advisable to compare the analysis with and without the questionable data.

Caution is in order if the estimates or conclusions are highly sensitive to a small amount of suspicious data. Data that have a very high influence on a fitted curve may not result in large residuals, however, even if they are in error. In fact, extremely influential observations may force the fitted curve

to be very close, leading to very small residuals. It is therefore desirable

to identify influential observations and to compare the results obtained with

and without these points. Several methods for detecting influential

observations are discussed in Bement and Williams [1969] , Cook [1977] , Hoaglin

and Welsch [1978], and Belsley et al. [1980].

Using weights to compensate for unequal observational error variances is

not as straightforward as using zero weights to eliminate observations from

the analysis. When the variances of the observational errors, e^, are not

equal, the unweighted least squares estimates remain unbiased but do not have

minimum variance. Minimum variance estimates are obtained by using weights

wt^ = 1/Variance [e ^ ] when the error variances are known . If weights must be

estimated, they should be based on at least 10 degrees of freedom [see Bement

and Williams, 1969]. In practice, however, weights are derived from theory, or obtained from the data being fit, and either of these methods can do more harm than good. When the need for weights is suspected and the error

variances are not known, first fit the data using unweighted least squares;

analysis of the residuals may confirm the need for weighting and may also

provide estimates for the weights themselves. If the need for weights is

confirmed, then a statistician should be consulted to assist in selecting the

weights and in interpreting the results.

B-l
-
Appendix C

ESTIMATING THE NUMBER OF RELIABLE DIGITS

IN THE RESULTS OF A FUNCTION

The number of reliable digits, p, in the results of a real valued

function, g(B), can be estimated in most cases by evaluating

p = -log 10 ( { 1 g( B

J ) - [a + j»b] 1} ) j -—2 , ...

,

2 |

g

( B ) |

where

B

3 is the vector of the NPAR parameters of the function given by,

B^(k) = B(k) + B (k)« j « io"( DIG1TS/2) for j = _ 2? 2,

and k = 1 ,. . . , NPAR,

where

DIGITS is the number of decimal digits carried by the user’s computer

for a single precision value when the single precision version of

STARPAC is being used and is the number carried for a double precision

value otherwise.

2 a = (0.20). I g(0J).

j=-2

2 b = (0.10). I j. g(0J).

J—

2

This procedure may underestimate the number of reliable digits if g(6) is

extremely nonlinear. A more elaborate and more robust procedure is described

in Gill et al. [1981].

C-l

REFERENCES

Abramowitz, M.; Stegun, I. (1964). Handbook of mathematical functions. Nat.

Bur. Stand. (U.S.) Appl. Math. Ser. 55.

Akaike, H. (1974). A new look at statistical model identification. IEEE

Transactions on Automatic Control, AC-19.

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

York, NY: American National Standards Institute.

Anderson, T. W. (1958). An introduction to multivariate statistical analysis.

New York, NY: John Wiley and Sons.

An s combe, F. J. ; Tukey , J. W. (1963). The examination and analysis of

residuals. Technometrics, 5: 141-160.

Bard, Y. (1974). Nonlinear parameter estimation. New York, NY: Academic

Press.

Belsley, D. A.; Kuh, E.; Welsch, R. E. (1980). Regression diagnostics. New

York, NY: John Wiley and Sons.

Bement, T. R.; Williams, J. S. (1969). Variance of weighted regression

estimators when sampling errors are independent and heteroscedastic. J. Amer.

Statists. Assoc. 64: 1369-1382.

Bloomfield, P. (1976). Fourier analysis of time series: an introduction.

New York, NY: John Wiley and Sons.

Box, G. E. P. ; Jenkins, G. M. (1976). Time series analysis forecasting and

control. San Francisco, CA: Holden-Day.

Bradley, J. V. (1968). Distribution-free statistical tests. Englewood

Cliffs, NJ: Prentice-Hall.

Brownlee, K. A. (1965). Statistical theory and methodology in science and

technology. Second edition. New York, NY: John Wiley and Sons.

Cook, D. R. (1977). Detection of influential observations in linear

regression. Technometrics, 19: 15.

Crow, E. L. ; Siddiqui, M. M. (1967). Robust estimation of locations. J. Amer. Stat. Assoc. 62: 353-389.

Daniel, C.; Wood, F. S. (1980). Fitting equations to data. Second edition.

New York, NY: John Wiley and Sons.

Davis, P. J. (1962). Orthonormalization codes in numerical analysis. In

Survey of Numerical Analysis, J. Todd, ed. New York, NY: McGraw-Hill.

R-l
Dennis, J. E. Jr.; Gay, D. M.; Welsch, R. E. (1981a). An adaptive nonlinear

least-squares algorithm. ACM Trans. Math. Software, 7(3): 348-368.

Dennis, J. E. Jr.; Gay, D. M.; Welsch, R. E. (1981b). Algorithm 573:

NL2S0L - an adaptive nonlinear least squares algorithm [E4] . ACM Trans. Math.

Software, 7(3): 369-383.

Dennis, J. E. Jr.; Schnabel, R. B. (1983). Numerical methods for unconstrained optimization and nonlinear equations. Englewood Cliffs, NJ:

Prentice-Hall.

Dixon, W. J. ; Massey, F. J. Jr. (1957). Introduction to statistical

analysis. Second edition. New York, NY: McGraw-Hill.

Donaldson, J. R.; Schnabel, R. B. (1985). Computational experience with

confidence regions and confidence intervals for nonlinear least squares.

University of Colorado Department of Computer Science Technical Report

CU-CS-302-84.

Donaldson, J. R.; Tryon, P. V. (1983a). Introduction to STARPAC, the

Standards time series and regression package. Nat. Bur. Stand. (U.S.) Tech.

Note 1068-1.

Donaldson, J. R.; Tryon, P. V. (1983b). 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. ( 1 9 79). L1NPACK

users' guide. Philadelphia, PA: SIAM.

Draper, N. R. ; Smith, H. (1981). Applied regression analysis. Second

edition. New York, NY: John Wiley and Sons.

Duncan, A. J. (1965). Quality control and industrial statistics. Third

edition. Richard D. Irwin.

Eisenhart, C. (1947). Significance of the largest of a set of sample

estimates of variance. In Techniques of Statistical Analysis. C. Eisenhart,

M. W. Hastay and W. A. Wallis, eds. New York, NY: McGraw-Hill.

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

(Unpublished - available from NBS Statistical Engineering Division/

Gaithersburg.

)

Fisher, R. A. (1950). Statistical methods for research workers. Eleventh

edition. Edenburg: Oliver and Boyd.

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

for a portable library [ Z ] . ACM Trans. Math. Sof twa re, 4(2): l 7 7 - 1 HH.

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

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

R-2
Freund, J. E.; Williams, F. J. (1958). Modern business statistics. Englewood

Cliffs, NJ: Prentice-Hall.

Fullerton, L. W. (1977). Portable special function routines. In Portability

of Numerical Software: 452-483. Oak Brook, IL: Springer-Verlag.

Gill, P. E.; Murray, W.; Wright, M. H. (1981). Practical optimization. New

York, NY: Academic Press.

Hald, A. (1952). Statistical theory with engineering applications. New York,

NY: John Wiley and Sons.

Hoaglin, D. C.; Welsch, R. E. (1978). The hat matrix in regression and ANOVA.

American Statistician, 32: 17.

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

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

Jenkins, G. M.; Watts, D. C. (1968). Spectral analysis and its applications.

San Francisco, CA: Holden-Day.

Jones, R. H. (1971). Spectrum estimation with missing observations. Annals

of the Institute of Statistical Mathematics, 23: 3.

Kendall, M. G. (1948). Rank, correlation methods. London: Charles Griffen

and Co.

Kendall, M. G. ; Stuart, A. (1973). The advanced theory of statistics.

Inference and Relationship, Vol. 2: London: Charles Griffin and Co.

Kennedy, W. J. Jr.; Gentle, J. E. (1980). Statistical computing. New York,

NY: Marcel-Dekker Inc.

Ku, H. H. (1973). A user's guide to the OMNI TAB command "STATISTICAL

ANALYSIS." Nat. Bur. Stand. (U.S.) Tech. Note 756.

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

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

Maridel, J. (1964). The statistical analysis of experimental data. New York,

NY: Interscience.

Marsaglia, G. ; Tsang, W. W. (1984). A fast, easily implemented method for

sampling from decreasing or symmetric unimodal density functions. SIAM J.

Sci. Stat. Comput. 5 (2): 349-358.

Miller, I.; Freund, J. E. (1977). Probability and statistics for engineers.

Second edition. Englewood Cliffs, NJ: Prentice-Hall.

Morrison, D. F. (1967). Multivariate statistical methods. New York, NY:

McGraw-Hi 1 1.

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

Handb. 91.

Owen, D. B. (1962). Handbook of statistical tables. Reading, MA: AddisonWesley Publishing Co.

Ryan, T. A.; Joiner, B. L. ; Ryan, B. F. (1974). Student handbook for the

MINITAB statistical computing system. The Pennsylvania State University.

Schnabel, R. B. (1982). Finite difference derivatives - theory and practice.

(Unpublished - available from NBS Statistical Engineering Divi sion/Boul der.

)

Singleton, R. C. (1969). An algorithm for computing the mixed radix fast

Fourier transform. IEEE Transactions on Audio and Electroacoustics, 17: 2.

Snedecor, G. W. (1956). Statistical methods. Fifth edition. Ames, IA: Iowa

State University Press.

Snedecor, G. W.; Cochran, W. G. (1967). Statistical methods. Sixth edition.

Ames, IA : Iowa State University Press.

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

subroutines for statistical analysis of experimental data. (Unpublished - available from NBS Statistical Engineering Division/Boulder.)

Waldmeier, M. (1961).

Schulthess.

Walsh, P. J. (1962).

511-513.

The Sunspot activity in

Algorithm 127 - ORTHO.

the years 1610-1960.

Comm. Assoc. Comp.

Zurich:

Mach. 5:

R-4
NBS-1 14A 1REV. 2 -ec) U.S. DEPT. OF COMM.

BIBLIOGRAPHIC DATA

SHEET (See instructions)

1. PUBLICATION OR

REPORT NO.

NBSIR 86-3448

2. Performing Organ. Report No.' 3. Publ i cation D ate January 1987

4. TITLE AND SUBTITLE

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 N BS, see instructions) 7. Contract/Grant No. national bureau of standards

DEPARTMENT OF COMMERCE

WASHINGTON, D.C. 20234

8. Type of Report & Period Covered

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

10. SUPPLEMENTARY NOTES

[~~1 Document describes a computer program; SFT85, 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].

I 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.

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

data analysis; nonlinear least squares; STARPAC- statistical computing; statistical

subroutine library; statistics; STATLIB; tine series analysis.

13. AVAILABILITY 14. NO. OF

PRINTED PAGES

Uni imited

| | For Official Distribution. Do Not Release to NTIS

| | Order From Superintendent of Documents, U.S. Government Printing Office, Washington, D.C. 300

20402. 15. Price

[_Xj Order From National Technical Information Service (NTIS), Springfield, VA. 22161 $24.95

USCOMM-OC 9043-PS0