© All Rights Reserved

22 views

© All Rights Reserved

- Comparison of Command Shells
- Niagara Quick Start Guide
- Securing Extreme Switch
- Jasper Server Install Guide
- DIAGNOSING AND TROUBLESHOOTING WIRELESS NETWORK.docx
- Connect-It 4.10 User's Guide
- null
- Max Manual
- Amazon EC 2 Cloud Automation: Scheduled Startup/Shutdown of Amazon EC2 Instances
- ReadMe.txt
- Auto-size Select and Search Prompt
- Time
- Practicals OS GTU for practice
- CLI4.0
- Untitled
- Intro Sci Lab
- Getting Started With Lotus Suspension Analysis
- Intro Unix 2016 2
- KVFinder Manual
- Module 01 Core Configuration

You are on page 1of 1049

TM

3.2 for UNIX

Users Guide

Aptech Systems, Inc.

Information in this document is subject to change without notice and does not

represent a commitment on the part of Aptech Systems, Inc. The software described in

this document is furnished under a license agreement or nondisclosure agreement. The

software may be used or copied only in accordance with the terms of the agreement.

The purchaser may make one copy of the software for backup purposes. No part of this

manual may be reproduced or transmitted in any form or by any means, electronic or

mechanical, including photocopying and recording, for any purpose other than the

purchasers personal use without the written permission of Aptech Systems, Inc.

c _Copyright Aptech Systems, Inc. Maple Valley WA 1984-2000

All Rights Reserved.

GAUSS, GAUSS Light, GAUSSi, GAUSS-386, and GAUSS-386i are trademarks of

Aptech Systems, Inc.

GEM is a trademark of Digital Research, Inc.

Lotus is a trademark of Lotus Development Corp.

HP LaserJet and HP-GL are trademarks of Hewlett-Packard Corp.

PostScript is a trademark of Adobe Systems Inc.

IBM is a trademark of International Business Machines Corporation

Hercules is a trademark of Hercules Computer Technology, Inc.

GraphiC is a trademark of Scientic Endeavors Corporation

Tektronix is a trademark of Tektronix, Inc.

Other trademarks are the property of their respective owners.

Part Number: GM-UNIX-PDF

Revision Date: August 9, 2000

Contents

1 Installation and Operation 1

1.1 Installing GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.1 Extracting the Files . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.2 Solaris 2.x Volume Management . . . . . . . . . . . . . . . . . . . 2

1.1.3 Uncompressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.4 Conguring GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2 Starting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.3 Exiting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3.1 X Window Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3.2 Terminal Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.4 Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.5 Running GAUSS programs . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.6 Quitting GAUSS Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.6.1 X Window Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.6.2 Terminal Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.7 Editing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.8 Command Line Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.9 Command Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.10 Running Programs Written for the PC . . . . . . . . . . . . . . . . . . . . 9

1.11 atog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.12 File Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.12.1 Data Sets, Matrix Files and String Files . . . . . . . . . . . . . . . 10

1.13 Cache Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.14 Graphics Conguration File . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2 Tutorial 15

2.1 Loading and Exiting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.1.1 Starting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.1.2 Exiting GAUSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.2 Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.2.1 The let Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.2.2 Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.2.3 Special Matrix Functions . . . . . . . . . . . . . . . . . . . . . . . 17

2.2.4 Keyboard Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.3 Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

ii

2.3.1 String Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.3.2 Keyboard Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.3.3 String Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.4 Matrix Description and Printing . . . . . . . . . . . . . . . . . . . . . . . 20

2.4.1 The print Statement . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.4.2 The format Statement . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.5 Indexing Matrices and Extracting Submatrices . . . . . . . . . . . . . . . 23

2.5.1 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.5.2 Using delif and selif . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2.6 Running a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

2.7 Element-by-Element Operators . . . . . . . . . . . . . . . . . . . . . . . . 27

2.8 Creating a Data Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

2.8.1 Reading an ASCII File . . . . . . . . . . . . . . . . . . . . . . . . . 30

2.9 Writing a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.10 Vectorizing for Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3 Windows 37

3.1 General Window Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.1.1 Opening a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.1.2 Moving a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.1.3 Resizing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

iii

3.1.4 Panning a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.1.5 Clearing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.1.6 Closing a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.1.7 Selecting a Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.1.8 Getting Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.2 PQG Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.2.1 Opening a PQG Window . . . . . . . . . . . . . . . . . . . . . . . 40

3.2.2 Selecting Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.2.3 Aspect Ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.3 Text Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.3.1 Opening a Text Window . . . . . . . . . . . . . . . . . . . . . . . . 41

3.3.2 Selecting Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.3.3 Locating Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.3.4 Wrapping Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.4 TTY Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.4.1 Opening a TTY Window . . . . . . . . . . . . . . . . . . . . . . . 43

3.4.2 Locating Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.4.3 Wrapping Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.5 Special Purpose Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

3.5.1 Command Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.5.2 Help Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

3.5.3 Active Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

iv

4 Debugger 49

4.1 Starting the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

4.2 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

4.3 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

4.4 Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

5 Foreign Language Interface 55

5.1 Creating Dynamic Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 55

5.1.1 Solaris 2.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.1.2 SunOS 4.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.1.3 IBM AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.1.4 DEC OSF1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5.1.5 HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5.1.6 SGI IRIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5.1.7 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5.2 Writing FLI Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

6 FLI Function Reference 59

7 Language Fundamentals 65

7.1 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

7.2 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

v

7.2.1 Executable Statements . . . . . . . . . . . . . . . . . . . . . . . . . 66

7.2.2 Nonexecutable Statements . . . . . . . . . . . . . . . . . . . . . . . 67

7.3 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

7.3.1 Main Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

7.3.2 Secondary Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

7.4 Compiler Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

7.5 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

7.6 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

7.6.1 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

7.6.2 Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

7.6.3 Strings and String Arrays . . . . . . . . . . . . . . . . . . . . . . . 77

7.6.4 Character Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

7.6.5 Special Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

7.7 Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

7.8 Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

7.8.1 Looping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

7.8.2 Conditional Branching . . . . . . . . . . . . . . . . . . . . . . . . . 88

7.8.3 Unconditional Branching . . . . . . . . . . . . . . . . . . . . . . . 88

7.9 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

7.10 Rules of Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

vi

7.10.1 Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

7.10.2 Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

7.10.3 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7.10.4 Extraneous Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7.10.5 Symbol Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7.10.6 Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

7.10.7 Assignment Statements . . . . . . . . . . . . . . . . . . . . . . . . 91

7.10.8 Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . 92

7.10.9 Indexing Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

7.10.10Arrays of Matrices and Strings . . . . . . . . . . . . . . . . . . . . 93

7.10.11Arrays of Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 93

8 Operators 95

8.1 Element-by-Element Operators . . . . . . . . . . . . . . . . . . . . . . . . 95

8.2 Matrix Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

8.2.1 Numeric Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

8.2.2 Other Matrix Operators . . . . . . . . . . . . . . . . . . . . . . . . 100

8.3 Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

8.4 Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

8.5 Other Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

8.6 Using Dot Operators with Constants . . . . . . . . . . . . . . . . . . . . . 110

vii

9 Procedures and Keywords 111

9.1 Dening a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

9.1.1 Procedure Declaration . . . . . . . . . . . . . . . . . . . . . . . . . 112

9.1.2 Local Variable Declarations . . . . . . . . . . . . . . . . . . . . . . 113

9.1.3 Body of Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

9.1.4 Returning from the Procedure . . . . . . . . . . . . . . . . . . . . 114

9.1.5 End of Procedure Denition . . . . . . . . . . . . . . . . . . . . . . 114

9.2 Calling a Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

9.3 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

9.3.1 Dening a Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . 116

9.3.2 Calling a Keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

9.4 Passing Procedures to Procedures . . . . . . . . . . . . . . . . . . . . . . . 117

9.5 Indexing Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

9.6 Multiple Returns from Procedures . . . . . . . . . . . . . . . . . . . . . . 119

10 Libraries 121

10.1 Autoloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

10.1.1 Forward References . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

10.1.2 The Autoloader Search Path . . . . . . . . . . . . . . . . . . . . . 122

10.2 Global Declaration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

10.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

10.3.1 Using dec Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

viii

11 Compiler 133

11.1 Compiling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

11.1.1 Compiling a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

11.1.2 Compiling from EDIT Mode, DOS Only . . . . . . . . . . . . . . . 134

11.2 Saving the Current Workspace . . . . . . . . . . . . . . . . . . . . . . . . 134

11.3 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

12 File I/O 137

12.1 ASCII Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

12.1.1 Matrix Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

12.1.2 General File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

12.2 Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

12.2.1 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

12.2.2 Creating Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

12.2.3 Reading and Writing . . . . . . . . . . . . . . . . . . . . . . . . . . 142

12.2.4 Distinguishing Character and Numeric Data . . . . . . . . . . . . . 143

12.3 Matrix Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

12.4 File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

12.4.1 Small Matrix v89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

12.4.2 Extended Matrix v89 . . . . . . . . . . . . . . . . . . . . . . . . . 147

12.4.3 Small String v89 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

ix

12.4.4 Extended String v89 . . . . . . . . . . . . . . . . . . . . . . . . . . 148

12.4.5 Small Data Set v89 . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

12.4.6 Extended Data Set v89 . . . . . . . . . . . . . . . . . . . . . . . . 149

12.4.7 Matrix v92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

12.4.8 String v92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

12.4.9 Data Set v92 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

12.4.10Matrix v96 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

12.4.11Data Set v96 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

13 Data Transformations 155

13.1 Data Loop Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

13.2 Using Other Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

13.3 Debugging Data Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

13.3.1 Translation Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

13.3.2 Compilation Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

13.3.3 Execution Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

13.4 Reserved Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

14 Data Loop Reference 159

15 Graphics Categorical Reference 175

15.1 Graph Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

x

15.2 Axes Control and Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

15.3 Text, Labels, Titles, and Fonts . . . . . . . . . . . . . . . . . . . . . . . . 176

15.4 Main Curve Lines and Symbols . . . . . . . . . . . . . . . . . . . . . . . . 176

15.5 Extra Lines and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

15.6 Window, Page, and Plot Control . . . . . . . . . . . . . . . . . . . . . . . 177

15.7 Output Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

15.8 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

16 Publication Quality Graphics 179

16.1 Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

16.2 General Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

16.3 Using Publication Quality Graphics . . . . . . . . . . . . . . . . . . . . . 180

16.3.1 Getting Started Right Away . . . . . . . . . . . . . . . . . . . . . . 180

16.3.2 Graphics Coordinate System . . . . . . . . . . . . . . . . . . . . . 183

16.4 Graphics Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

16.4.1 Using Window Functions . . . . . . . . . . . . . . . . . . . . . . . 185

16.4.2 Transparent Windows . . . . . . . . . . . . . . . . . . . . . . . . . 186

16.4.3 Saving Window Congurations . . . . . . . . . . . . . . . . . . . . 186

16.5 Interactive Draft Mode, DOS Only . . . . . . . . . . . . . . . . . . . . . . 186

16.6 Fonts and Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . 187

16.6.1 Selecting Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

xi

16.6.2 Greek and Mathematical Symbols . . . . . . . . . . . . . . . . . . 188

16.7 Hardcopy and Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

16.7.1 Printing the Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

16.7.2 Exporting Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

16.8 Global Control Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

17 Graphics Reference 205

18 Time and Date 257

18.1 Time and Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

18.2 Time and Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

18.2.1 Timed Iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

19 Utility: atog 263

19.1 Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

19.2 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

19.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

19.4 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

20 Utility: liblist 279

20.1 Report Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

20.2 Using liblist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

xii

21 Categorical Reference 283

21.1 Window Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

21.2 Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

21.3 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

21.4 Error Handling and Debugging . . . . . . . . . . . . . . . . . . . . . . . . 285

21.5 Workspace Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

21.6 Program Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

22 Command Reference 287

23 Command Reference Introduction 331

23.1 Using This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

23.2 Global Control Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

23.2.1 Changing the Default Values . . . . . . . . . . . . . . . . . . . . . 332

23.2.2 The Procedure gausset . . . . . . . . . . . . . . . . . . . . . . . . 333

24 Commands by Category 335

24.1 Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

24.2 Matrix Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

24.3 Data Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

24.4 Compiler Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

24.5 Program Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

xiii

24.6 OS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

24.7 Workspace Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

24.8 Error Handling and Debugging . . . . . . . . . . . . . . . . . . . . . . . . 353

24.9 String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

24.10Time and Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

24.11Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

24.12Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

25 Command Reference 357

A Fonts 973

B Performance Hints 979

B.1 Library System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979

B.2 Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979

B.3 Virtual Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980

B.3.1 Data Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980

B.3.2 Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981

B.3.3 Hard Disk Maintenance . . . . . . . . . . . . . . . . . . . . . . . . 981

B.3.4 Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981

B.3.5 CPU Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 981

C Reserved Words 983

xiv

D Operator Precedence 987

E Singularity Tolerance 989

E.1 Reading and Setting the Tolerance . . . . . . . . . . . . . . . . . . . . . . 989

E.2 Determining Singularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990

F Saving Compiled Procedures 991

G transdat 993

H Error Messages 997

I Limits 1015

Index 1017

xv

xvi

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

Chapter 1

Installation and Operation

This chapter covers the basics of installing and running GAUSS on a UNIX

workstation. Please read the entire chapter before beginning. It is short and will save

time in the long run.

Please read the README* les that came with your shipment! They contain important

information that became available after the manual was printed.

1.1 Installing GAUSS

GAUSS is shipped on 3.5

installation instructions for each. Each shipment also includes a hardcopy Installation

memo.

SEE THE INSTALLATION MEMO that came with your shipment! Instructions on the

memo, where dierent, override the instructions in this supplement.

If you are unfamiliar with UNIX, see your system administrator or system

documentation for information on the system commands referred to below. The device

names given are probably correct for your system.

1.1.1 Extracting the Files

Use mkdir to create a directory for GAUSS.

1

1. INSTALLATION AND OPERATION

mkdir gauss

Use cd to make the directory you created the current working directory.

cd gauss

Use tar to extract the les.

tar xvf device name

The following device names are suggestions. See your system administrator. If you are

using Solaris 2.x, see Section 1.1.2.

Operating System 3.5 inch diskette 1/4 inch tape DAT tape

Solaris 1.x SPARC /dev/rfd0 /dev/rst8

Solaris 2.x SPARC /dev/rfd0a (vol. mgt. o) /dev/rst12 /dev/rmt/1l

Solaris 2.x SPARC /vol/dev/aliases/floppy0 /dev/rst12 /dev/rmt/1l

Solaris 2.x x86 /dev/rfd0c (vol. mgt. o) /dev/rmt/1l

Solaris 2.x x86 /vol/dev/aliases/floppy0 /dev/rmt/1l

HP-UX /dev/rfloppy/c20Ad1s0 /dev/rmt/0m

IBM AIX /dev/rfd0 /dev/rmt.0

SGI IRIX /dev/rdsk/fds0d2.3.5hi

If GAUSS came on diskettes, repeat the tar command for each diskette.

1.1.2 Solaris 2.x Volume Management

If Solaris 2.x volume management is running, insert the oppy disk and type:

volcheck

to signal the system to mount the oppy. Then execute the tar command. When the

tar command nishes type:

eject

and remove the oppy if it is not automatically ejected.

The oppy device names for Solaris 2.x change when the volume manager is turned o

and on. To turn o volume management, become the superuser and type:

/etc/init.d/volmgt off

To turn on volume management, become the superuser and type:

/etc/init.d/volmgt on

2

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

1. INSTALLATION AND OPERATION

1.1.3 Uncompressing

If the media was diskette, use the gunpack script to uncompress the les:

gunpack

1.1.4 Conguring GAUSS

GAUSSHOME environment variable

GAUSS needs an environment variable called GAUSSHOME. It should contain the

complete name of your GAUSS home directory. For example:

C shell

setenv GAUSSHOME /home/usr1/gauss

Korn, Bourne shell

GAUSSHOME=/home/usr1/gauss

export GAUSSHOME

GAUSS looks in the $GAUSSHOME directory for its conguration le, gauss.cfg.

gauss.cfg is a commented ASCII le that controls several startup defaults. It can be

edited before getting into GAUSS, allowing you to change any of the defaults. Anyone

who will be running GAUSS needs to have at least read access to gauss.cfg.

The standard GAUSS system directory layout is as follows:

$GAUSSHOME Base directory, executable les, conguration les

$GAUSSHOME/src Source les

$GAUSSHOME/lib Library les

$GAUSSHOME/examples Example les

$GAUSSHOME/wksp Workspace les, log les

As it is shipped, gauss.cfg assumes this directory structure and uses GAUSSHOME

to establish the base directory, so you dont have to edit it unless you change the

directory structure.

GAUSS creates temporary les during operation. Anyone who uses GAUSS must have

read/write/execute access to the directories where those les are located. As it is

shipped, this is the $GAUSSHOME/wksp directory.

You can specify a path to an alternate conguration le with the GAUSS CFG

environment variable. For example:

3

1. INSTALLATION AND OPERATION

C shell

setenv GAUSS_CFG /home/usr1/gauss/project1

Korn, Bourne shell

GAUSS_CFG=/home/usr1/gauss/project1

export GAUSS_CFG

The name of the le remains the same, i.e., gauss.cfg.

You can use the $() syntax in gauss.cfg to reference environment variables. For

example:

src_path = $(GAUSSHOME)/src

GAUSS uses an internal variable named gaussdir in gauss.cfg, so do not try to use an

environment variable named gaussdir in the le.

PATH environment variable

You should place a reference to the $GAUSSHOME directory in your system PATH

environment variable, so the operating system can nd the GAUSS executables.

1.2 Starting GAUSS

UNIX is case sensitive, so the commands below are case sensitive.

To start GAUSS in X Window mode, type:

gauss &

To start GAUSS in terminal or vanilla mode, type:

gauss -v

You must be in a UNIX terminal window such as an xterm or Command Tool. The

graphics and windowing functions are not available in terminal mode.

The GAUSS prompt looks like this:

(gauss)

4

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

1. INSTALLATION AND OPERATION

1.3 Exiting GAUSS

1.3.1 X Window Mode

To end a GAUSS session, click on the Quit button.

1.3.2 Terminal Mode

If you are in terminal mode, type:

quit enter

at the GAUSS command prompt. See Section 1.6 for ways to stop a GAUSS program

that is executing.

1.4 Log Files

GAUSS creates an error log le and a command log le for each session. These will

need to be deleted periodically. They are generated with unique names containing the

process ID of the GAUSS session that created them. They are located in the directories

specied in the conguration le. The default is $GAUSSHOME/wksp.

1.5 Running GAUSS programs

To run a program from the GAUSS prompt, type

run lename

For example:

run max1.e

Programs to run can be listed on the command line when you start GAUSS. At the

UNIX command prompt, type

gauss lename [[lename...]]

GAUSS will run the programs specied, and return to the GAUSS command line.

5

1. INSTALLATION AND OPERATION

1.6 Quitting GAUSS Programs

1.6.1 X Window Mode

Click on Stop or Kill.

Use Kill only when necessaryit will always work, but it literally kills the compiler and

executer with no questions asked. It can leave your workspace in an indeterminate

state.

1.6.2 Terminal Mode

Esc enter

or

Esc! enter

or

stop enter

or

Ctrl-C

or

kill enter

You will be returned to the GAUSS command line.

If you have programs that expect to pick up Esc with the key function, you can turn

the trapping of Esc o in the conguration le. Either way, Esc! is active to stop a

program.

Use kill only when necessary, see above reference under X Window mode.

1.7 Editing Files

For the time being, you will have to use your own text editor to write GAUSS

programs. Several come with UNIX if you dont have one of your own. You can specify

a hook to an editor in the conguration le (see gauss.cfg for instructions). The

default editor is vi which is started by typing

edit myfile

from the GAUSS prompt.

6

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

1. INSTALLATION AND OPERATION

1.8 Command Line Flags

There are several ags you can specify on the command line when starting GAUSS.

The following ags are supported:

-b run GAUSS in batch mode, look for keyboard input.

-B run GAUSS in batch mode, dont look for keyboard input. Use this

when you want to run GAUSS in the background.

-m turn o make.

-M turn on make.

-n do an implicit new before each program. Ignored if not in batch mode.

-s run stdin as a GAUSS program. During the execution of the program,

no keyboard input will be recognized. This ag cannot be combined with

others behind the same , and it must come after any other ags.

-T turn the translator on.

-t turn the translator o.

-v terminal or vanilla mode.

You can run GAUSS in batch mode. If your programs require user input, use the -b

ag. At the UNIX command prompt, type

gauss -b lename [[lename...]]

GAUSS will start up in batch mode, run the programs specied, then drop to the

UNIX command prompt. You can break the run with Ctrl-C, Esc, etc. (see below);

GAUSS will drop to command mode.

If your programs dont require user input, use the -B ag. At the UNIX command

prompt, type

gauss -B lename [[lename...]]

or

gauss -B lename [[lename...]] &

GAUSS will start up in batch mode, run the programs specied, then drop to the

system. You can break the run with Ctrl-C; GAUSS will drop to the GAUSS prompt.

All other keyboard input is ignored, including Esc. When you want to run GAUSS in

the background, use -B.

If you want to run stdin as a GAUSS program, use the -s ag. At the UNIX command

prompt, type

gauss [[lename...]] -s [[lename...]]

7

1. INSTALLATION AND OPERATION

Other programs can be run at the same time as stdin. GAUSS will start up in batch

mode, run the programs and stdin in the order listed, then drop to the system. The -s

ag forces GAUSS into the same mode as the -B ag; all keyboard input is ignored

except for Ctrl-C.

The -T and -t ags turn the translator on and o respectively, overriding the translator

setting in gauss.cfg.

The -n ag is used to execute a new command between programs to prevent any

symbol conicts if the programs use variables with the same names.

When the -M ag is on if you edit a le that contains symbols in use the le will be

recompiled.

1.9 Command Filtering

By default, when GAUSS is in terminal mode, most of the following commands are

available interactively at any time, even during compilation or execution of a GAUSS

program:

cancel cancel any pending commands

stop stop the current program politely

Esc, Esc! stop the current program politely

kill terminate current program immediately

quit terminate GAUSS and return to the OS

status list status, current command, pending commands

translator on[o turn data loop translator on or o

cong set compile-time and run-time options

help on-line help

dos exec a command shell

[[editor alias]] exec an editor (see gauss.cfg)

!! repeat previous command

debug run program under debugger

This is done by ltering them out of the keyboard input stream and handling them

immediately, rather than putting them in the compiler command queue. This can give

you unexpected results, e.g., if you type status as the input to a cons statement.

This ltering can be turned o during program execution. You can specify the default

command ltering mode for all GAUSS sessions by setting the cmd lter parameter in

the conguration le, or use the cong command (run options) to set the default

ltering mode for a single GAUSS session. You can also use the #lteron and

#ltero compiler directives to set the command ltering mode for a single program

run. #lteron and #ltero must be placed at the top of your program.

stop and dos can be used in GAUSS programs; the rest of the commands can only be

used interactively.

8

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

1. INSTALLATION AND OPERATION

1.10 Running Programs Written for the PC

In general, you should be able to run GAUSS programs that were originally written for

the PC without any problems. The main limitations relate to the advanced hardware

control commands.

The coprocessor control commandsenable, disable, etc.are not available. All

coprocessor exceptions are currently masked.

The ags for the lib command are specied with a dash () instead of a slash (/).

For example:

lib gauss -n;

This is because the slash is a separator in UNIX le specications.

The new command cannot change the main program space size or the number of global

symbols available. These settings can be specied in gauss.cfg.

If youre working in a GAUSS X window, keyboard input works the same as on PCs.

If youre working in terminal mode, however, it doesnt. Because of the way the system

buers input, GAUSS doesnt see any keyboard input until you hit Enter. So, if you

are using the key command for single key input, you will have to enter

keystroke enter

If you are using cons or the key command for multiple key input, you can type in your

entire input, then hit Enter, and it will all be available to GAUSS.

If you want to input a carriage return, press Enter when there is no pending input, and

GAUSS will recognize it as input.

Programs written for the PC are generally written with an 80-character wide screen in

mind. So, if youre running under an X window manager, you should size your windows

to at least 80 columns to guarantee that your program output doesnt wrap.

1.11 atog

atog for UNIX has no interactive mode, and can only be run from within GAUSS by

using the shell command, i.e., shell atog. Execute atog without command line

arguments for a help screen. For general instructions on using atog, see the Utility:

atog chapter in Volume I.

9

1. INSTALLATION AND OPERATION

1.12 File Handling

Files are created with the following permissions:

Owner read/write

Group read

World read

This can be controlled from gauss.cfg.

1.12.1 Data Sets, Matrix Files and String Files

There are new formats available for data sets, matrix les and string les. See the File

I/O chapter in Volume I of the manual.

Data sets now consist of one le with a .dat extension, not two les with .dht and

.dat extensions.

The header has changed for matrix and string lesotherwise, theyre the same as

before.

We have a new utility, transdat, for converting these les from one format to another.

If you have data sets, matrix les or string les you want to transfer from your PC to

the workstation, you can use transdat to convert them. transdat must be run from the

UNIX prompt. Execute transdat with no arguments for a help screen. See G for details.

1.13 Cache Size

There is a line for cache size in the conguration le. Set it to the size of the CPU data

cache for your machine. The default is 32K.

This aects the choice of algorithms used for certain math functions. This can

dramatically aect performance for large matrices. Results will be the same.

1.14 Graphics Conguration File

The name and format of the graphics conguration le have been changed. The le is

now called .gaussrc instead of pqgrun.cfg; formatwise, it is a standard X Windows

resource le. GAUSS searches for .gaussrc in the following directories, in the order

listed:

10

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

1. INSTALLATION AND OPERATION

1. The directory specied by GAUSS CFG, if it is dened

2. The users home directory

3. The $GAUSSHOME directory

4. The current working directory

The rst one found is used. If none is found, GAUSS creates a default .gaussrc (using

internal defaults) in the users home directory.

The following resources can be included in .gaussrc:

Resource

gauss.pqg.print.margin.left

gauss.pqg.print.margin.right

gauss.pqg.print.margin.top

gauss.pqg.print.margin.bottom

Denition Left/right/top/bottom print margin.

Options Any nonnegative decimal value. Interpreted as inches.

Default 1.00"

Resource

gauss.pqg.print.resolution

Denition Print resolution.

Options MinRes, LoRes, HighRes, MaxRes

Default MaxRes

Resource

gauss.pqg.print.filename

Denition Output lename when printing to le or converting graph.

Options String, any valid lename. File must be writeable.

Default none

Resource

gauss.pqg.print.placement

11

1. INSTALLATION AND OPERATION

Denition Placement of graph within margins. Aects xed aspect graphs only.

Options TopLeft, Top, TopRight, Left, Center, Right, BotLeft, Bottom, BotRight

Default Center

Resource

gauss.pqg.print.orientation

Denition Orientation of graph on page.

Options Landscape, Portrait

Default Landscape

Resource

gauss.pqg.print.dest

Denition Destination of graphics printout.

Options Printer, File

Default Printer

Resource

gauss.pqg.print.aspect

Denition Aspect ratio of printed graph. Fixed aspect graphs are printed within the

limits dened by the margins, whereas variable aspect graphs are stretched

to t the margins.

Options Fixed, Variable

Default Fixed

Resource

gauss.pqg.print.driver

Denition Driver used to convert graph to format suitable for your printer.

Options PS, EPS, HPLJET3, HPGL, PIC

The le prndev.tbl in the $GAUSSHOME directory lists additional

printer/le types that are available but not tested. You can try any of the

types listed there except the type 4 entries (i.e., those with a 4 in the

second eld), which are NOT supported.

12

I

n

s

t

a

l

l

a

t

i

o

n

a

n

d

O

p

e

r

a

t

i

o

n

1. INSTALLATION AND OPERATION

Default PS

Resource

gauss.pqg.print.command

Denition Command that will be executed to print a graph.

Options String, any valid print command.

Default lp -c $FILE

Resource

gauss.pqg.print.color

Denition Print color mode: black/white, color, or gray scale.

Options BW, RGB, Gray

Default BW

Resource

hpgl.pen.black

hpgl.pen.dark_grey

hpgl.pen.red

hpgl.pen.light_red

hpgl.pen.brown

hpgl.pen.light_brown

hpgl.pen.green

hpgl.pen.light_green

hpgl.pen.cyan

hpgl.pen.light_cyan

hpgl.pen.blue

hpgl.pen.light_blue

hpgl.pen.magenta

hpgl.pen.light_magenta

hpgl.pen.grey

hpgl.pen.white

Denition Pen color for HPGL-format output.

Options Integer, any valid pen number.

Default

13

1. INSTALLATION AND OPERATION

hpgl.pen.black 1

hpgl.pen.dark grey 1

hpgl.pen.red 5

hpgl.pen.light red 5

hpgl.pen.brown 7

hpgl.pen.light brown 7

hpgl.pen.green 3

hpgl.pen. 3

hpgl.pen.cyan 4

hpgl.pen.light cyan 4

hpgl.pen.blue 2

hpgl.pen.light blue 2

hpgl.pen.magenta 6

hpgl.pen.light magenta 6

hpgl.pen.grey 8

hpgl.pen.white 8

You may also see the following entries in .gaussrc:

gauss.pqg.print.size: 100%

gauss.pqg.print.scaling: ByPage

These are reserved for future development.

The WinPrintPQG command now works. Also, its functionality has been expanded to

include that of WinConvertPQG, and WinConvertPQG has been dropped. See the

on-line help for details on how to use WinPrintPQGit has a dierent syntax now.

You can now zoom multiple times in a graph.

Default Fonts

You can specify default normal and bold fonts for GAUSS to use in Text and TTY

windows by including gauss.font.normal and gauss.font.bold resources in the

.gaussrc le. Set them to any valid nonproportional font specication string.

14

T

u

t

o

r

i

a

l

Chapter 2

Tutorial

This tutorial will introduce you to the basics of GAUSS.

2.1 Loading and Exiting GAUSS

This lesson covers starting, stopping and suspending GAUSS.

2.1.1 Starting GAUSS

From the OS (operating system) prompt there are two ways to start GAUSS. The rst:

gauss &

will start up GAUSS in an X window. The second:

gauss -v

will start GAUSS in text mode in your current terminal.

2.1.2 Exiting GAUSS

To exit GAUSS when in X window mode, click on the Quit button. To exit GAUSS in

terminal mode, at the (gauss) prompt type:

quit

15

2. TUTORIAL

2.2 Matrices

This lesson covers the basic commands that create matrices.

2.2.1 The let Statement

Type this in and press Enter:

let x = { 1 2 3, 4 5 6, 7 8 9 };

You just created a 3x3 matrix called x. To print it out type:

print x;

Try it again without the let.

x = { 1 2 3, 4 5 6, 7 8 9 };

An assignment statement with the data enclosed in curly braces is an implicit let

statement. let statements are run-time initialization statements. Only a list of

constants is allowed to the right of the equal sign in a let statement.

Now lets create a column vector and print it out.

x = { 1,2,3,4,5,6,7,8,9 };

print x;

Now a row vector.

x = { 1 2 3 4 };

print x;

The constants in a let statement can be real or complex. Try the following:

x = { 1 2+3 4 5-6i 7 8i };

print x;

Complex constants can be entered in one of two ways. If a number has both a real and

an imaginary part, just join the two with the sign (+ or -). If a number has no real

part, append an i to it, and GAUSS will recognize it as imaginary. Notice that the

i can be appended even if the number has a real part.

16

T

u

t

o

r

i

a

l

2. TUTORIAL

2.2.2 Concatenation

The concatenation operators are used to create matrices from other matrices or from

expressions. Enter:

a = { 1.1 3.2 };

b = { 2.3 -4.5 };

Now try these statements:

hc = a~b;

print hc;

hcp = a+1~b+2;

print hcp;

vc = a|b;

print vc;

The is the horizontal concatenation operator, and the | is the vertical concatenation

operator.

2.2.3 Special Matrix Functions

To create a matrix of zeros or ones, or random numbers, try the following statements.

Zeros

x = zeros(4,4);

print x;

Ones

y = ones(2,4);

print y;

Uniform Random Numbers

z = rndu(6,3);

print z;

17

2. TUTORIAL

Normal Random Numbers

z = rndn(6,3);

print z;

Random Integers

rndint = ceil( rndu(6,4) * 100 );

print rndint;

Constant Matrix

To create a constant matrix, all you need to do is add the desired constant to a matrix

of zeros. For example, to create a 6x3 matrix of 7s, this statement will work:

sevens = 7 + zeros(6,3);

print sevens;

Identity Matrix

id = eye(3);

print id;

Additive Sequence

t1 = seqa(0,0.1,10);

print t1;

t2 = seqa(pi/4,pi/4,4);

print t2;

Multiplicative Sequence

t1 = seqm(2,2,10);

print t1;

18

T

u

t

o

r

i

a

l

2. TUTORIAL

Reshaping Matrices

x = seqa(1,1,3);

y = reshape(x,5,3);

print x;

print y;

2.2.4 Keyboard Input

The con function requests keyboard input of a matrix. Type this in.

x = con(3,3);

The ? is your prompt. The con function is requesting 9 numbers. Type in 9 numbers,

each followed by a space.

Are you back at the (gauss) prompt? If so, print your new matrix x.

The con function can accept complex numbers. It uses the same rules for entering

complex numbers as the let statement. Try entering some.

x = con(2,2);

print x;

Notice that the con function, like the let statement, only understands constants.

2.3 Strings

We will cover two ways to create a string.

2.3.1 String Constant

s = "This is a string.";

The double quotes enclose a string constant. Printing a string is like printing a matrix.

Try it.

19

2. TUTORIAL

2.3.2 Keyboard Input

The cons function requests keyboard input of a string. Type this in.

s = cons;

There is no visible prompt. Type something in and press Enter.

You should be back to the GAUSS prompt. Print s.

Now lets do it with a prompt so we can tell when we are being asked to type

something in.

print /flush "Enter the string: ";; s = cons;

Enter another string, then print s. The double semicolons at the end of the print

statement suppressed a line feed afterward so the cons statement would start requesting

input on the same line. The /ush ag forces immediate display of the prompt.

2.3.3 String Concatenation

Lets tack two strings together. Type this in.

s = s $+ "catfish";

print s;

The $+ is the string addition or concatenation operator.

2.4 Matrix Description and Printing

This is a short section on using some of the functions that describe matrices. You will

learn how to nd the number of rows and columns in a matrix and nd the largest and

smallest elements in a particular column or in the entire matrix. Also, you will be

introduced to some more features of the print statement.

To nd the number of rows and columns in a matrix, use the rows and cols functions.

Type in the following statements:

x = rndu(10,4);

r = rows(x);

c = cols(x);

print "Matrix x is: " r " by " c;

20

T

u

t

o

r

i

a

l

2. TUTORIAL

The print statement could have been written:

print "Matrix x is :" rows(x) " by " cols(x);

To nd the maximum and minimum elements of each column of a matrix, use the maxc

and minc functions. Try this:

print x;

print maxc(x);

print minc(x);

To nd the largest or smallest element in an entire matrix, call maxc and minc twice:

print "Maximum is: " maxc(maxc(x));

print "Minimum is: " minc(minc(x));

2.4.1 The print Statement

In entering the statement

print "Matrix x is: " r " by " c;

you probably noticed that the statement combined the printing of string constants (the

phrases between double quotes) and variables (r and c). GAUSS uses a space to

separate the individual expressions in a print statement. Therefore, extraneous spaces

are illegal in print statements. Try:

print 3 + 5;

The error you will get is:

(0) : error G0064 : Operand missing

GAUSS translated that as three expressions. The middle expression was the addition

operator with no operands. There are two ways to write the above statement correctly:

1. No extraneous spaces.

print 3+5;

2. Parentheses.

print (3 + 5);

21

2. TUTORIAL

2.4.2 The format Statement

If you are still using the default print format, then the statements:

print "Rows: " r;

print "Cols: " c;

print the number of rows and columns with 8 digits of precision.

Create a variable containing an integer value.

x = 5;

To change the print format, enter the following format statement:

format /rdn 1,0;

The /rdn ag indicates that numbers are right-justied in decimal format followed by

nothing. The 1 sets the eld width, which will be overridden if the number requires

more space, and the 0 sets the precision or number of places to the right of the decimal

point. This format statement is suitable for printing integers.

print "(" x ")";

Lets leave out the n and see what happens, type:

format /rd 1,0;

The /rd ag indicates that numbers are right-justied in decimal format followed by a

space, which is the default.

print "(" x ")";

As you can see, the number is now followed by a single space character. Try another

format and print x again.

format /len 12,4;

Any numbers printed after this format statement will be left-justied using scientic

notation in a 12-character eld followed by nothing with 4 decimal places of precision.

Type in the following:

22

T

u

t

o

r

i

a

l

2. TUTORIAL

let x = 1+2 3-4;

format /rds 4,2;

print x;

For complex numbers, the eld and precision settings refer to the eld width and

precision for each part of the number. Also, when the number is printed, the real and

imaginary parts are separated by a sign ( + or - ), and an i is appended to the

imaginary part. You will need to gure this in when you want to print complex

numbers in a nice format.

Lets change x a bit.

let x = { 1+2 3-4, 5 6i };

print x;

When the imaginary part of a complex number is 0, it is not printed at all. We do,

however, pad the place where the 0 would appear with spaces, to keep the rest of the

printout aligned.

Now reset the format to one more like the default format.

format /ro 12,4;

2.5 Indexing Matrices and Extracting Submatrices

This section describes how to index individual elements of a matrix and extract

submatrices of a matrix. First clear your workspace of all previously dened globals.

To do this, enter

new;

Now create a matrix using seqa and reshape:

x = reshape( seqa(1,1,32), 8, 4 );

print x;

2.5.1 Indexing

Now, lets extract the rst and third columns of x:

col1 = x[.,1];

print col1;

23

2. TUTORIAL

col3 = x[.,3];

print col3;

Now, extract a row, whose index might be variable:

i = 2;

row = x[i,.];

print row;

Now, index a set of rows. I will leave out the print statements from here on, except

when necessary. You can print whatever you want to take a look at.

idx = { 1 3 6 8 };

ridx = x[idx,.];

Finally, index a set of rows and columns:

rowidx = { 1 3 5 8 };

colidx = { 3 4 };

newmat = x[rowidx,colidx];

The matrix newmat consists of the intersection of rows 1, 3, 5, and 8 and columns 3

and 4.

newmat = x[1 3:6,2:4]

The matrix newmat now consists of the intersection of rows 1, 3-6 and columns 2-4.

The submat function can also be used to extract submatrices.

r = { 1 3 5 };

c = { 3 4 };

newmat = submat(x,r,c);

This will index rows 1, 3 and 5 and columns 3 and 4.

2.5.2 Using delif and selif

You may want to create a submatrix based on some selection or deletion criteria. This

section will show you one way to do this, using the selif and delif functions.

First, create a matrix of normally distributed random numbers:

y = rndn(100,4);

24

T

u

t

o

r

i

a

l

2. TUTORIAL

Now we will create a new matrix, which contains only those rows of y where column 2

is greater than 0.5. To do this, we will create a vector of 1s and 0s that has a 1 in each

row we want to select.

ex = y[.,2] .> 0.5;

print ex;

The vector ex should have a 1 wherever the corresponding entry in the second column

of y is greater than 0.5. The expression y1[.,2] .> 0.5 uses a dot operator which

returns a matrix of 1s and 0s with a 1 wherever the expression is true and a 0 wherever

it is false. The result of the expression above is a vector with the same number of rows

as y. Well use such a vector of 1s and 0s in the selif and delif statements.

Now, we want to create a submatrix of the matrix y containing all the rows in which

the second column is greater than 0.5. Here is how we would use the selif function to

create this submatrix:

suby = selif(y,ex);

Print suby to see that column 2 contains only numbers greater than 0.5.

Here is another example of a logical expression that can be used with the selif function.

ex2 = abs( y[.,1] ) .< 0.33 .and y[.,2] .> 0.66;

The delif function works in a complementary fashion. Instead of selecting elements to

go in the submatrix, you delete those elements that you dont want. For example:

ex = y[.,1] .< 0.33;

v = delif(y,ex);

Of course, this would be equivalent to this set of statements which use selif:

ex = y[.,1] .>= 0.33;

v = selif(y,ex);

The logical expression may almost always be nested inside of the call to the functions

that require them. The above two statements could be combined into one statement:

v = selif(y,y[.,1] .>= 0.33);

25

2. TUTORIAL

2.6 Running a Program

Up until nowwe have been executing single line commands. Now lets write a program.

Create a le called lesson1 and type this into the new le.

A = rndn(3,3);

b = rndn(3,1);

x = b/A;

print A;

print b;

print x;

Save your le without exiting your editor and at the (gauss) prompt type:

run lesson1;

from the GAUSS prompt.

You just solved a system of linear equations. This is an example of the / (slash)

operator. It is quite powerful.

The / operator is supposed to solve the linear system

Ax = b

Lets check it from the command line. If the equation above is true, A*x-b should be

zeros.

print A*x;

print b;

print A*x-b;

Its pretty close, isnt it? There will usually be a little rounding error when doing

calculations on real numbers.

Lets try the / operator on a dierent kind of problem. Edit your program so that the

whole thing looks like this:

x = { 1 2 3,

4 5 6,

7 8 9 };

y = 2;

z = x / y;

print x;

print;

print y;

print z;

26

T

u

t

o

r

i

a

l

2. TUTORIAL

The empty print statement just prints a carriage return/line feed.

Execute your new program.

The / operator is now doing standard division. You should have gotten:

1 2 3

4 5 6

7 8 9

2

0.5 1 1.5

2 2.5 3

3.5 4 4.5

2.7 Element-by-Element Operators

Now get back into your program and change the second and third lines so the program

looks like this:

x = { 1 2 3,

4 5 6,

7 8 9 };

y = { 1 2 3 }; /* row vector */

z = x ./ y; /* dot slash operator */

print x;

print;

print y;

print z;

The /* row vector */ statement is a comment. Comments dont do anything but you

can use them to make your programs easier to understand when you come back to

them six months later.

Execute your new program. You should have gotten:

1 2 3

4 5 6

7 8 9

1 2 3

1 1 1

4 2.5 2

7 4 3

27

2. TUTORIAL

This is element-by-element division. The dot slash always does element-by-element

division. This is an example of what we refer to as element-by-element conformability.

The row vector y was swept down the matrix x and the corresponding divisions were

done.

Get back into the le.

Make it look like this:

x = { 1 2 3,

4 5 6,

7 8 9 };

y = { 1, 2, 3 }; /* column vector */

z = x ./ y; /* use dot slash */

print x;

print y;

print z;

Execute it. You will get:

1 2 3

4 5 6

7 8 9

1

2

3

1 2 3

2 2.5 3

2.333 2.667 3

Here the column vector was swept across the matrix.

Now get out of GAUSS by typing quit or clicking on the Quit button. Get back into

GAUSS and run your program at the same time by typing either:

gauss lesson1

or

gauss -v lesson1

Lets make one nal change to your le. Add two lines to the program so it looks like:

28

T

u

t

o

r

i

a

l

2. TUTORIAL

x = { 1 2 3,

4 5 6,

7 8 9 };

x = complex(x,1); /* create complex matrix */

y = { 1, 2, 3 }; /* column vector */

y = complex(y,1); /* create complex matrix */

z = x ./ y; /* use dot slash */

format /rz 4,2; /* suitable format for x, y and z */

print x;

print y;

print z;

Run the program. The output should look like this:

1 + 1i 2 + 1i 3 + 1i

4 + 1i 5 + 1i 6 + 1i

7 + 1i 8 + 1i 9 + 1i

1 + 1i

2 + 1i

3 + 1i

1 1.5 0.5i 2 1i

1.8 0.4i 2.2 0.6i 2.6 0.8i

2.2 0.4i 2.5 0.5i 2.8 0.6i

This is an example of element-by-element complex division. Try using the .*

element-by-element multiplication operator to check the answer you just got. You can

do this from the command line.

a = z .* y;

print a;

a equals x (except for a little round-o error). Can you gure out why x ./ z doesnt

equal y?

2.8 Creating a Data Set

We will now create a small data set.

29

2. TUTORIAL

2.8.1 Reading an ASCII File

First we will create a small ASCII data le. In your editor create a le named rawdata.

Type in the following numbers.

1 3 2 1

3 2 7 4

9 2 6 3

5 1 2 7

4 8 5 2

1 7 5 7

Save rawdata. We can now load rawdata into a matrix.

load x[6,4] = rawdata;

print x;

This is the quick and dirty way to use load for small ASCII les. See load in the

COMMAND REFERENCE section for a way to use it that has more error checking.

See the Utility: atog chapter in Volume I of the manual for converting larger les.

To create a small GAUSS data set from the matrix x, we will use saved.

call saved(x,"mydata",0);

This statement created a data set called mydata.dat. Check to see if it was created.

If the third argument to saved is 0, the names for the columns of the data set will all

start with X. People using GAUSS for statistical analysis will use these for the names

of their variables. Each row of the data set is then a case or observation.

We can now get some statistics on this data set.

call dstat("mydata",0); call ols("mydata",0,0);

If you want to see what the arguments to the ols or dstat procedures mean, click on the

Help button or type help at the GAUSS prompt. You will be asked for the topic you

want help on. Answer with ols or dstat. Press the capitalized letter of the desired

option to page up and down, etc., in the le. Type q enter to exit the help system.

This on-line help is available for your own functions. Lets make one.

30

T

u

t

o

r

i

a

l

2. TUTORIAL

2.9 Writing a Procedure

Create a le named sumd.src in your text editor.

We will create a procedure that sums the columns of a data set and returns a vector of

the sums. We will go a line or two at a time and I will explain each statement.

proc sumd(name);

This is the beginning of a procedure denition. This is a user-dened function. It will

return 1 item. That is the default. It will take one argument which will be the name of

the data set.

local fp,sum;

These variables, fp and sum, are local variables. They only exist while this procedure is

being called.

open fp = ^name;

The open command opens a le. The argument, name, will be a string variable. The

other variable, fp, is going to be used as a le handle. Most le-related functions in

GAUSS take a le handle to identify which le you want to work on. The ^ (caret)

operator in the context of the open statement means that what follows is a string

variable and we need the contents of it.

if fp == -1;

errorlog "Cant open the file";

end;

endif;

The comparison operator is == instead of just one equal sign. We are testing to see if

the le handle is a -1 because the open command will set it to -1 if it cant open the

le. errorlog prints an error message to the screen and the error log le. If the le

cannot be opened, the program will end.

sum = 0;

We need to zero out the variable to contain the sums.

do until eof(fp);

We are going to start a loop. We will keep doing this loop until we get to the end of the

le.

31

2. TUTORIAL

sum = sum + sumc(readr(fp,50));

This line calls readr which will read 50 rows from the data set we opened under the

handle fp. The result of this read is passed to sumc which will return the sums of each

column. These sums are added to sum on each iteration of the loop. If there arent 50

rows left, then readr will read however many there are.

endo;

This is the end of the loop.

fp = close(fp);

Now we close the le, again using the le handle.

retp(sum);

The retp statement is used to return from the procedure. The vector of column sums is

returned.

endp;

The endp statement is the close of the procedure denition. Here is our complete

procedure.

proc sumd(name);

local fp,sum;

open fp = ^name;

if fp == -1;

errorlog "Cant open the file";

end;

endif;

sum = 0;

do until eof(fp);

sum = sum + sumc(readr(fp,50));

endo;

fp = close(fp);

retp(sum);

endp;

Save the procedure without exiting your editor as before.

We need to do one more thing to make this procedure available to GAUSS. Type this

in at the GAUSS command prompt:

32

T

u

t

o

r

i

a

l

2. TUTORIAL

lib user sumd.src

This adds a listing for all procedures and global variables in sumd.src (theres only

one) to the default library user.lcg. Now GAUSS knows where to nd the procedure

sumd when you call it.

sumd is also available to the help system. Click on Help (in terminal mode, type help

at the GAUSS prompt) and answer sumd at the help prompt.

This is how to get on-line help for your own functions. If you put a comment at the top

which explains what it is used for, your sumd procedure will be complete. Ill leave

that for you to do later if you think sumd would be a useful function to have around. If

not, you can delete the entry for it from the user library. For now, lets try to use it on

our data set. Type q enter to exit the help system.

sum = sumd("mydata");

print sum;

Since this returns a column vector, if you want the sum of the entire data set you could

use:

sum = sumc(sumd("mydata"));

print sum;

These procedures work just like any other function. This makes the GAUSS language

easy to extend to accommodate the routines specic to your profession.

2.10 Vectorizing for Speed

In this lesson, we will introduce you to the looping statements, and then discuss when

loops should and should not be used in GAUSS.

First, in your editor create a le called lesson2. Now type in the following program.

x = 1;

do until x+1 == 1;

eps = x;

x = x/2;

endo;

format /rz 1,8;

print "Machine epsilon: " eps;

33

2. TUTORIAL

This program nds the smallest number eps such that

eps +1 > 1

Now suppose you want to recode a vector, based on which elements fall into specic

categories.

Create a le called lesson3.

Next, create the vector you might want to recode:

r = 20;

v = ceil(100*rndu(r,1))/10;

Now, suppose you want to assign to a new vector, v1, a 1 if the corresponding element

in v is less than 3, a 2 if the corresponding element in v is between 3 and 7, and a 3

otherwise. You could do so with this loop:

v1 = zeros(r,1);

i = 1;

do until i > r;

if v[i] < 3;

v1[i] = 1;

elseif v[i] > 7;

v1[i] = 3;

else;

v1[i] = 2;

endif;

i = i + 1;

endo;

format /rd 8,1;

print v~v1;

This program illustrates the use of the do loop and the if statement for conditional

branching. Also, notice that in order to index into the vector v1, we had to rst

initialize it. In this program, we initialized it as a vector of zeros.

This isnt a particularly ecient way to accomplish the desired task, however. Tasks

like these can be vectorized. This one in particular can be written in one line, using

logical expressions.

Get back into the program. Now add the following statement to your program:

v2 = (v .< 3) +

( 3 .<= v .and v .<= 7 ) * 2 +

(v .> 7) * 3;

34

T

u

t

o

r

i

a

l

2. TUTORIAL

Remember that the dot operators create a vector or matrix of 1s and 0s.

Execute this program. Now, in the command line, we can check to make sure that v1

and v2 are identical. From the command line, type:

maxc(abs(v1-v2));

This will return the maximum dierence between any of the corresponding elements in

v1 and v2. This dierence should be 0.

Finally, lets time the dierent procedures for recoding our vector v. To time a segment

of code, well use the hsec function. Here is how you can time a segment of code:

et = hsec; /* Start timer */

/* Segment of code to be timed here */

et = (hsec - et)/100; /* Stop timer, convert to seconds */

The function hsec uses your computers clock to return the hundredths of seconds that

have passed since midnight. Add timer statements and change the value of r to 1000 at

the top of your program, so that lesson3 looks like:

r = 1000;

v = ceil(100*rndu(r,1))/10;

et1 = hsec;

v1 = zeros(r,1);

i = 1;

do until i > r;

if v[i] < 3;

v1[i] = 1;

elseif v[i] > 7;

v1[i] = 3;

else;

v1[i] = 2;

endif;

i = i + 1;

endo;

et1 = (hsec - et1)/100;

et2 = hsec;

v2 = (v .< 3) +

( 3 .<= v .and v .<= 7 ) * 2 +

(v .> 7) * 3;

et2 = (hsec - et2)/100;

35

2. TUTORIAL

format /rd 6,2;

print "Loop: " et1;

print "Vectorized: " et2;

print "Ratio L/V: " et1/et2;

The vectorized process should be over 10 times as fast as the loop. In general, any time

you can vectorize a process, do so. The vectorized process will usually be substantially

faster.

Another function you can use to recode data in the way we did above is subscat. See

the COMMAND REFERENCE for details on using this function.

36

W

i

n

d

o

w

s

Chapter 3

Windows

The current release of GAUSS for UNIX includes a simple programming interface to

Version 11 of the X Window System. It provides a wide variety of new window support

functions, allowing you to easily develop X Window compatible GAUSS programs.

Also, many previously existing commands have been modied to work within the new

window system.

Three types of GAUSS windows are currently supported:

PQG Windows - graphics windows for display of Publication Quality Graphics

Text Windows - text I/O windows with xed-sized rectangular buers

TTY Windows - text I/O windows with scrolling output history logs

These window types share certain common properties (each can be opened, closed,

moved, resized, panned, cleared, and refreshed), but they dier greatly in purpose and

functionality. (Many of the new GAUSS window functions are dened for a specic

window type only, and will generate errors if passed the handle of an incorrect window

type.)

This chapter is divided into ve sections. The rst section contains an overview of

general window operations. In the next three sections, each window type is examined in

more detail. Section ve describes the command and help windows, and the concept of

the active window and its role in GAUSS window programs.

3.1 General Window Operations

The following operations are basic window control functions, and can be done on any

window type. The details of the function calls vary by window type. The most

37

3. WINDOWS

recognizable dierence being that arguments for PQG windows are usually given in

pixels, while arguments for Text and TTY windows are usually given in rows and

columns. Several operations refer to the special purpose windows; see Section 3.5 for

denitions of those.

3.1.1 Opening a Window

WinOpenPQG opens (creates) a PQG window, WinOpenText opens a Text window,

WinOpenTTY opens a TTY window. See Sections 3.2.1, 3.3.1 and 3.4.1 for

information on window attributes and defaults.

3.1.2 Moving a Window

WinMove repositions a window on the screen. You can move a window partially or

completely o-screen. Arguments are in pixels. Nonintegral arguments are truncated.

3.1.3 Resizing a Window

WinResize resizes a window. There are no limits for sizing PQG windows or TTY

windows, but Text windows are limited by the size of their text buer. You can resize a

Text window smaller than its buer, but not larger. For PQG windows, arguments are

in pixels; for Text windows and TTY windows, arguments are in rows and columns.

Nonintegral arguments are truncated.

You can specify a window as nonresizeable when you open it. WinResize will return a

failure code on a nonresizeable window.

3.1.4 Panning a Window

WinPan pans through the contents of a window. For PQG windows, arguments are in

pixels; for Text and TTY windows, arguments are in rows and columns. Nonintegral

arguments are truncated.

WinPan is not supported for PQG windows.

For Text windows, panning is limited by the buer boundaries.

For TTY windows, you cannot pan above the rst line or to the left of the rst column.

You can pan the current output line to the top of the window (this is how cls and

WinClear clear TTY windows), and you can pan to the right as far as you like.

38

W

i

n

d

o

w

s

3. WINDOWS

3.1.5 Clearing a Window

WinClear clears a specied window, cls clears the active window. Windows are cleared

to the background color. For PQG windows, the graphics le is truncated to zero

length; For Text windows, the window buer is cleared; for TTY windows, the current

output line is merely panned to the top of the window. To clear the output log of a

TTY window, use WinClearTTYLog.

WinClearArea clears a specied region of a Text window to the background color.

Arguments are in rows and columns. As with Winclear, that region of the window

buer is cleared. WinClearArea is only supported for Text windows.

Closely related to WinClearArea, the scroll function allows you to scroll a region of

text in the active window. The area the text is scrolled away from is cleared to a

specied color. scroll is only supported for Text windows.

3.1.6 Closing a Window

WinClose closes (destroys) a window. WinCloseAll closes all windows except window 1

(the command window).

Closing a window does not mean iconizing it; closing a window destroys it. Once a

window is closed, there is no way to retrieve any information it contained.

3.1.7 Selecting a Font

Before using a font, it must be loaded from the system. When you are done with it you

should unload it, to conserve memory resources. FontLoad loads a font, FontUnload

unloads it.

Once a font is loaded, you have to let GAUSS know you want to use it for a particular

window. You can set the font either upon opening a window or when it is the active

window. font sets the font for the active window.

Changing the font in a window will generally result in a change in the number of rows

and columns displayed. Changing to a smaller font in a Text window can result in the

window being down-sized, since the window cannot be larger than its buer.

Setting the font of a PQG window, while not supported, will not cause an error.

3.1.8 Getting Input

The active window always has the keyboard focus in a GAUSS program. con, cons,

key, keyw, wait and waitc all get input from the active window.

39

3. WINDOWS

3.2 PQG Window

A PQG window is specically designed to display Publication Quality Graphics. Text

input and output is not supported for PQG windows.

3.2.1 Opening a PQG Window

WinOpenPQG opens a PQG window. You can specify the following on opening:

window position (pixels)

window size (text rows and columns)

colormap

foreground and background color

xed or variable aspect ratio

resizeability

Defaults are dened for each of these settings:

window position: (0,0) (upper left corner of screen)

window size: 640480

16 color colormap ( emulates PC EGA palette )

black background, white foreground

xed aspect ratio

resize by function or mouse

You can retain any or all of the default values on opening a window.

3.2.2 Selecting Colors

Each PQG window has an associated colormap. You can examine the colors in the

colormap with WinGetColorCells, and change them with WinSetColorCells. Out of

the colormap you can select the foreground and background colors for window output.

The foreground is the the default color of the lines, text, and other PQG output, and

the background is the color of the eld on which they are drawn. You can change the

foreground and background through the commands provided in the Publications

Quality Graphics interface.

Note: The graphics library used in Publication Quality Graphics is currently limited to

using the 16 color palette. While the appearance of the screen can be changed by the

selection of an alternate colormap, all output to the printer, and all le conversions are

treated as if the active colormap is 16 color.

40

W

i

n

d

o

w

s

3. WINDOWS

3.2.3 Aspect Ratio

PQG windows may be opened with either a xed or variable aspect ratio. For windows

opened with xed aspect ratio, both resizing and zooming are aected. The system

forces one dimension of the window or zoom box to change by an amount proportional

to any change in the other dimension. For the zoom feature, the X size of the zoom box

determines the Y size. For resizing, the window manager determines which dimension is

dominant, if any. The default for PQG windows is xed aspect ratio.

3.3 Text Window

A Text window is a text I/O window with an underlying text buer. All operations

take place with respect to the buer. A window cannot be resized larger than its buer.

3.3.1 Opening a Text Window

WinOpenText opens a Text window. You can specify the following on opening:

window location (pixels)

window size (text rows and columns)

buer size (text rows and columns)

text font

colormap

foreground and background color

text wrapping mode

refresh mode

resizeability

Defaults are dened for each of these settings:

window position: (0,0) (upper left corner of screen)

window size: 2580

buer size: 2580

system font

system colormap

system foreground and background

character wrap

refresh on newline (\n)

resize by function or mouse

You can retain any or all of the default values on opening a window.

41

3. WINDOWS

3.3.2 Selecting Colors

Each Text window has an associated colormap. You can examine the colors in the

colormap with WinGetColorCells, and change them with WinSetColorCells. Out of

the colormap you can select the foreground and background colors for Text window

output. The foreground is the color of the text itself, and the background is the color of

the eld on which it is printed. You can change the foreground color at any time, the

background color, however, may not be changed after the window has been opened.

The color command sets the foreground color for the active window.

3.3.3 Locating Text

Text windows give you full control over text location, allowing you to paint a screen

and set up output elds wherever you like. All text location functions operate with

respect to the window buer, NOT the current window appearance. Thus, you may

locate and print text in an area that is not currently visible.

WinSetCursor sets the cursor position in a specied window. locate sets the cursor

position in the active window. tab sets the cursor position on the current line of the

active window. You can tab forward and backward. You can also embed tab commands

within a print statement.

When you locate and print in a region that already has text, the existing text is

overwritten.

Nonintegral arguments to the text location functions are truncated; for example,

locate 13.25, 40.75;

is equivalent to:

locate 13, 40;

It is not necessary for location arguments to be located within the window buer. For

example,

locate 1,-5;

is allowed. You can think of the buer as covering a small region in text coordinate

space; text written within the buer bounds is remembered, text written outside it is

lost.

42

W

i

n

d

o

w

s

3. WINDOWS

3.3.4 Wrapping Text

Three text wrapping modes are supported:

word wrapping

character wrapping

clipping

Word wrapping: Lines are wrapped between words. A line wrap on the last row of the

buer forces an auto-scroll of the buer contents. Outputting a newline (\n) on the

last row also forces an auto-scroll.

Character wrapping: Lines are wrapped between characters. Auto-scrolling is the same

as for word wrapping.

Clipping: Lines are clipped at the buer edge. No auto-scrolling takes place, not even

when a newline (\n) is output to the last row of the buer. If you want to scroll the

contents of the buer, you must do it explicitly with the scroll command.

Again, all output commands in a Text window operate with respect to the buer, not

the window. So, in clipping mode, any text that goes beyond the width of the buer is

discarded and cannot be retrieved. Likewise, any time text is scrolled o the top of the

buer, it is permanently discarded.

3.4 TTY Window

A TTY window is a text I/O window that logs output for a user-specied number of

lines. Each line of output is saved in its entirety, and the window size, text wrap mode,

etc., merely determine how the output is displayed. The only time you lose information

in a TTY window is when you reach the output log limit and lines begin to scroll o

the top of the output log.

TTY windows have color support for foreground only. The color commands will run in

a TTY window, however, they will only eect the foreground color.

There are no sizing limits for TTY windows.

3.4.1 Opening a TTY Window

WinOpenTTY opens a TTY window. You can specify the following on opening:

43

3. WINDOWS

window location (pixels)

window size (text rows and columns)

output log size (number of lines)

text font

colormap

foreground and background color

text wrapping mode

refresh mode

resizeability

Defaults are dened for each of these settings:

window position: (0,0) (upper left corner of screen)

window size: 2580

output log size: 500 lines

system font

system colormap

system foreground and background

character wrap

refresh on newline (\n)

resize by function or mouse

You can retain any or all of the default values on opening a window.

3.4.2 Locating Text

TTY windows have minimal text location support. You can use tab and locate to tab

the cursor forward and backward in the active window, or WinSetCursor to tab the

cursor in a specied window. For locate and WinSetCursor, the row argument is

ignored.

When you tab backward and then print, the existing text is overwritten.

The tabbing commands operate with respect to the length of the current output line,

not the window appearance. This becomes signicant when a line gets longer than the

window width, and wraps. For example, if a window is 80 columns wide and the output

line is 90 columns wide, and you tab to column 85, the cursor will appear to be in

column 5. If you then widen the window to 100 columns, the output line will unwrap

and the cursor will appear where you expect it, in column 85.

44

W

i

n

d

o

w

s

3. WINDOWS

3.4.3 Wrapping Text

Three text wrapping modes are supported:

word wrapping

character wrapping

clipping

Word wrapping: Lines are wrapped between words. A line wrap on the last row of the

window forces an auto-scroll of the buer contents. Outputting a newline (\n) on the

last row also forces an auto-scroll.

Character wrapping: Lines are wrapped between characters. Auto-scrolling is the same

as for word wrapping.

Clipping: Lines are clipped at the window edge. Auto-scrolling takes place only when a

newline (\n) is output to the last row of the window. (Note the dierence between this

and a clipped Text window, which never auto-scrolls.)

The text wrap mode in a TTY window denes how output is displayed in the window;

it has nothing to do with how output is stored, as is the case in a Text window. So, the

word and character wrapping modes specify that each line of output should be

completely displayed within the window boundaries; nothing is hidden o-screen

(until it scrolls o the top of the window). If you resize the window, the entire display

will change as output is rewrapped accordingly. Likewise, clipping mode species that

the portions of a line beyond the edges of the window should be clipped from the

display, but nothing discarded. If you widen the window, you will see more of the text.

A nal note about auto-scrolling: if the current output line has been panned below the

bottom edge of the window, additional output will not scroll the window contents. The

output is still added to the output log; it just doesnt aect the display. This allows you

to study previous text during ongoing output. Pan the output line back within view,

and normal window updating and auto-scrolling will resume.

3.5 Special Purpose Windows

GAUSS recognizes three special purpose windows: the command window, the help

window, and the active window.

45

3. WINDOWS

3.5.1 Command Window

The command window ( window 1 ) is the main window used for controlling GAUSS.

It contains both the control buttons, and a TTY text pane for running GAUSS

interactively. ( If GAUSS is running in terminal mode, the system terminal window is

the command window. ) Since the window handle for the command window is 1, the

command window is sometimes referred to as window 1.

The top of the command window contains buttons which are used to control a GAUSS

session. (These replace the main interactive control commands used in the DOS

version.) The following buttons appear in window 1:

Help toggle GAUSS help system on/o

Status display program status, processes executing

Cong display/modify Compile and Run options

Trans toggle le translation on/o

Cancel cancel any commands pending in the command buer

Stop stop the currently executing progam

Kill terminate child processes

Quit quit GAUSS and exit to system.

The text pane portion of the command window is a standard TTY window. Most of

the GAUSS commands which are valid for user dened TTY windows are also valid for

the command window. To execute a GAUSS function on the command window, simply

set the window handle parameter of the command to 1. There are some functions

which are not dened for the command window, such as WinClose, and

WinSetRefresh. These are documented in the Command Reference. The command !!

may be used to repeat the last typed command.

3.5.2 Help Window

The help window is the window used for displaying output from the interactive help

system. The Help button on the command window toggles the help window on and o.

The help system is available at any time during a GAUSS session, with output directed

to a dedicated TTY window. The window handle for the help window is 2. ( If GAUSS

is running in terminal mode, the system terminal window is the help window. )

Most of the GAUSS commands which are valid for user dened TTY windows are also

valid for the help window. To execute a GAUSS function on the help window, simply

set the window handle parameter of the command to 2. There are some functions such

as WinClose and WinSetRefresh which are either not dened for the help window, or

which operate dierently on the help window. These are documented in the Command

Reference.

46

W

i

n

d

o

w

s

3. WINDOWS

3.5.3 Active Window

The active window refers to the default I/O window. All the input functions (con,

cons, key, keyw, wait and waitc) get their input from the active window, and all the

output and output-related commands that do not take a window handle as an

argument (locate, output, print, scroll, tab, etc.) operate on the active window. In

addition, certain functions that set window or output attributes (color, font, etc.)

operate on the active window.

WinSetActive and WinGetActive set and get the active window. Any window can be

the active window, and you can change the active window whenever you want. Many

windows can be visible simultaneously, but there is only one active window.

When you rst start GAUSS, the command window (window 1) is the active window.

It is possible not to have an active window; you can remove the active window by

unsetting it with WinSetActive or closing it with WinClose. If there is no active

window, the commands that operate on it will still runthey just wont have any eect

(for example, the output of a print statement will simply not be displayed anywhere).

If there is no active window when a GAUSS program ends, the command window

automatically becomes the active window.

Note: If you set the active window to a PQG window, no character I/O will be

processed.

47

3. WINDOWS

48

D

e

b

u

g

g

e

r

Chapter 4

Debugger

GAUSS for UNIX includes a source level debugger which executes a program one line

or opcode at a time, enabling the user to examine and modify program variables during

execution.

The debugger is a dynamically linked X Window application. The X libraries must be

available on the system when it is invoked.

4.1 Starting the Debugger

To start the debugger, enter:

debug lename

at the GAUSS prompt.

The debugger initially displays two windows: the Command window, which contains

buttons used to control program ow, and the Source window, which displays the

source code to be executed. Section 4.3 describes the other windows the debugger uses.

Debugger commands are issued by clicking on the buttons in the Command window.

49

4. DEBUGGER

4.2 Commands

Next Line Execute next source line

Step Line Execute next source line, enter procedure calls

Next Opcode Execute next opcode

Step Opcode Execute next opcode, enter procedure calls

Go Execute with no tracing

Verbose Execute with opcode tracing

Brkpts On[O Toggle breakpoint checking on and o

Brkpts Set Detailed information and control of breakpoints

Examine Examine and modify variable contents

History Toggle opcode history on and o

Stack Examine and modify stack contents

Procs List procedures and set breakpoints

Quit Exit debugger

Next Line Executes the currently highlighted source line. If the current line contains

any procedure calls, they are executed (along with any procedures which they

call) before the debugger pauses for input.

Step Line Executes the currently highlighted source line. If the current line contains a

procedure call, execution pauses at the rst line within the procedure. If the line

contains more than one procedure call, execution will pause at the rst line in

each procedure (assuming you continue pressing Step Line).

Next Opcode Executes the currently highlighted opcode. If the opcode is a procedure

call, the entire procedure is executed (along with any procedures which it calls)

before the debugger pauses for input.

Step Opcode Executes the currently highlighted opcode. If the opcode is a procedure

call, execution pauses at the rst opcode within the procedure.

Go Executes the program until reaching either a breakpoint or the end of the code.

Selecting Go automatically turns o the Opcode History window.

Verbose Executes the program until reaching either a breakpoint or the end of the

code. Selecting Verbose automatically turns on the Opcode History window.

Brkpts On[O Toggles breakpoint checking on and o. When breakpoint checking is

o, the debugger ignores all breakpoints. When breakpoint checking is on, the

debugger stops at the rst active breakpoint.

A small banner is displayed in the upper right corner of the Command window

when breakpoint checking is on.

50

D

e

b

u

g

g

e

r

4. DEBUGGER

Brkpts Set Opens/closes the Breakpoint window. The Breakpoint window displays

the data for all breakpoints currently specied in the program. You can modify

breakpoint settings in this window. See Section 4.4 for details.

Examine Requests a variable name, then opens an Examine window to display it. The

window is updated after each command. It remains open until it is explicitly

closed or the variable is no longer valid. Global variables are always valid; local

variables become invalid after a retp. The debugger will allow up to 100

variables to be monitored at any given time.

History Opens/closes the Opcode History window. When open, the Opcode History

window displays and logs opcodes as they are executed. It can log up to 4096

opcodes. This window is automatically opened whenever the Next Opcode,

Step Opcode, or Verbose command is issued, and closed whenever the Go

command is issued. While immensely useful for tracking down program errors,

generating the opcode history is very output intensive and greatly increases

program execution time while active.

Stack Opens/closes the Stack window. The Stack window displays the contents of the

stack for examination and modication. The window is automatically updated

after each command.

You will only see stack activity when youre selecting Next Opcode or Step

Opcode. If youre selecting Next Line or Step Line, the stack will appear to be

always empty.

Procs Opens/closes the Procedure window. The Procedure window lists the names of

all procedures and functions found in the source code. Procedure breakpoints

can be set and cleared from this window. See Section 4.4 for details.

Quit Ends the debugging session and exits the debugger.

4.3 Windows

The debugger utilizes a variety of dierent windows to display and edit the various

types of program data and debugger settings.

Window types include:

Command Command buttons, status indicators, debugger messages

Source Currently executing source code, highlight indicates next

source line to be executed

51

4. DEBUGGER

History Opcode history, highlight indicates next opcode to be

executed

Breakpoint Lists all dened breakpoints, allows editing of breakpoints,

highlight indicates currently selected breakpoint

Stack Displays current stack contents, highlight indicates

currently selected stack element, clicking on selected

item opens Examine window

Procedure Displays the names of all procedures and functions dened

in the current program, highlight indicates currently

selected procedure name

Matrix Examine Matrix window, displays the contents of matrix,

highlight indicates currently selected element, clicking

on selected element allows modication

String Examine String window, displays the contents of string,

no highlight is displayed (strings cannot be modied)

Edit Allows text/numeric entry into the debugger, highlight

indicates current cursor position

The windows have a given default size, but can be adjusted (within limits) to whatever

size is desired. Since there is often more information available than can be displayed

within the window, the debugger supports keystroke movement of the highlight or

window contents as follows:

Up move up one element

Down move down one element

Left move left one element

Right move right one element

Shift+Up move up one window height

Shift+Down move down one window height

Shift+Left move left one window width

Shift+Right move right one window width

Ctrl+Up go to top

Ctrl+Down go to bottom

Ctrl+Left go to far left

Ctrl+Right go to far right

PageUp move up one window height

PageDown move down one window height

Ctrl+PageUp go to top

Ctrl+PageDown go to bottom

52

D

e

b

u

g

g

e

r

4. DEBUGGER

Home go to upper left

End go to lower right

Enter select item or accept changes

Esc discard changes, close window

While the denition of element may vary according to the window type, every eort

has been made to keep the keystroke actions intuitive, and there should be no confusion.

4.4 Breakpoints

The debugger supports two types of breakpoints, procedure breakpoints and line

number breakpoints. Procedure breakpoints pause execution when the specied

procedure or function is entered. Line number breakpoints pause execution when the

specied line is reached. In either case, the break occurs before any of the GAUSS code

for the procedure or line is executed.

Procedure breakpoints can be set and cleared in the Procedure window by clicking on

the desired procedure name. You can also use the cursor keys to move the highlight to

the desired procedure, then press Enter to set/clear a breakpoint.

Line number breakpoints can be set and cleared in the Source window by clicking on

the desired line.

Breakpoints can be set, cleared and modied in the Breakpoints window, which is

opened and closed by the Brkpts Set command. This window displays all the

breakpoints dened for the current debugging session. You can select a breakpoint by

clicking on it with the mouse or moving the highlight with the cursor keys. Once

selected, the breakpoint settings can be modied as follows:

1. Clicking on the ON/OFF eld toggles the state of the breakpoint. Breakpoints

which are o remain dened, but are inactive. Active breakpoints are indicated

in the Procedure and Source windows with an inverse video tag [BP], inactive

breakpoints are indicated with the tag (BP) in normal video.

2. Clicking on the Skip eld opens an Edit window, which allows the skip value to

be changed. Breakpoint checking in the debugger skips over the breakpoint the

specied number of times. For example, 0 = dont skip, 24 = skip 24 times,

break on the 25th occurence. Skip counters are reset to 0 whenever the

breakpoint causes a break. For example, a skip value of 24 on a breakpoint

within a loop from 1 to 100 will break 4 times, at i = 25, 50, 75, and 100).

Note: The Skip eld is currently only valid for line number breakpoints.

3. Clicking on the Line # eld opens an Edit window, which allows the line

number to be changed.

53

4. DEBUGGER

54

F

o

r

e

i

g

n

L

a

n

g

u

a

g

e

I

n

t

e

r

f

a

c

e

Chapter 5

Foreign Language Interface

The Foreign Language Interface (FLI) allows users to create functions written in C,

FORTRAN, or other languages and call them from a GAUSS program. The functions

are placed in dynamic-link libraries (DLLs, also known as shared libraries or shared

objects) and linked in at run-time as needed. The FLI support functions are:

dlibrary Link and unlink dynamic libraries at run-time.

dllcall Call functions located in dynamic libraries.

GAUSS recognizes a default dynamic library directory, a directory where it will look

for your dynamic-link libraries when you call dlibrary. You can specify the default

directory in gauss.cfg by setting dlib path. As it is shipped, gauss.cfg species

$GAUSSHOME/dlib as the default directory.

5.1 Creating Dynamic Libraries

Assume you want to build a dynamic library named libmyfuncs.so, containing the

functions found in two source les, myfunc1.c and myfunc2.c. The following sections

show the compile and link commands you would use on the various platforms GAUSS

for Unix runs on, assuming youre using the ANSI C compiler oered for each platform.

The compiler command is rst, followed by the linker command, followed by remarks

regarding that platform.

The ANSI C compiler is included on some platforms; on others it is a separate purchase.

The compiler is usually called cc, the linker is usually called ld. On some platforms, the

linker is invoked by the compiler; on most platforms, we call it directly. Thus, the link

command is sometimes done with ld, sometimes with cc.

55

5. FOREIGN LANGUAGE INTERFACE

For explanations of the various ags used, see the man pages on your system. Two ags

are common to all platforms. The -c compiler ag means compile only, dont link.

Virtually all compilers will perform the link phase automatically unless you tell them

not to. When building a dynamic library we want to compile the source code les to

object (.o) les, then link the object les in a separate phase into a dynamic library.

The -o linker ag means name the output le as follows, and must be followed by the

name of the library you want to create, in this case libmyfuncs.so.

$(CFLAGS) indicates any optional compilation ags you might add.

You may have to use the -l ag to specify additional libraries on the link command line.

5.1.1 Solaris 2.x

cc -c $(CFLAGS) myfunc1.c myfunc2.c

ld -G -o libmyfuncs.so myfunc1.o myfunc2.o

5.1.2 SunOS 4.x

acc -pic -c $(CFLAGS) myfunc1.c myfunc2.c

ld -assert pure-text -assert definitions -o libmyfuncs.so

myfunc1.o myfunc2.o

5.1.3 IBM AIX

cc -pic -c $(CFLAGS) myfunc1.c myfunc2.c

cc -o libmyfuncs.so myfunc1.o myfunc2.o -bE:libmyfuncs.exp

-bM:SRE -e _nostart

The -bE:libmyfuncs.exp ag species the name of the export le. The AIX linker

requires that you specify the names of the symbols that will be exported, i.e., made

callable by other processes, from the dynamic library. The export le is just a text le

that lists the exported symbols, one per line. Assume that myfunc1.c and myfunc2.c

contain the functions func1(), func2(), and func3(), and a static function func4() that

is called by the others, but never directly from GAUSS. For this example, the export

le would look like this:

func1

func2

func3

56

F

o

r

e

i

g

n

L

a

n

g

u

a

g

e

I

n

t

e

r

f

a

c

e

5. FOREIGN LANGUAGE INTERFACE

5.1.4 DEC OSF1

cc -c $(CFLAGS) myfunc1.c myfunc2.c

ld -shared -o libmyfuncs.so myfunc1.o myfunc2.o -lc

Under OSF1, if your library calls functions in the standard C runtime library, libc.so,

you have to explicitly link it in. The -lc ag does this.

5.1.5 HP-UX

cc -c +z $(CFLAGS) myfunc1.c myfunc2.c

ld -b -c libmyfuncs.exp -o libmyfuncs.so myfunc1.o myfunc2.o

Like AIX, the HP-UX linker requires that you indicate the symbols to be exported. In

this case, however, the -c libmyfuncs.exp ag species the name of an indirect

command le. Indirect command les can contain any linker switches you want to place

in them; for our purposes, libmyfuncs.exp contains only +e, or mark symbol for

export , switches. Assuming the example described in the AIX section, libmyfuncs.exp

would look like this:

+e func1

+e func2

+e func3

5.1.6 SGI IRIX

cc -c $(CFLAGS) myfunc1.c myfunc2.c

ar cq myfuncs.a myfunc1.o myfunc2.o

ld -elf -rdata_shared -shared -all myfuncs.a -o libmyfuncs.so

IRIX requires an extra step. The object les produced by the compiler are combined

into a standard archive le using ar; this archive le becomes the input from which the

linker constructs the dynamic library.

5.1.7 Linux

gcc -fpic -c $(CFLAGS) myfunc1.c myfunc2.c

gcc -shared -o libmyfuncs.so myfunc1.o myfunc2.o -lc

Like the DEC, if your library calls functions in the standard C runtime library, libc.so,

you have to explicitly link it in under Linux. Once again, the -lc ag does this.

57

5. FOREIGN LANGUAGE INTERFACE

5.2 Writing FLI Functions

Your FLI functions should be written to the following specications:

1. Take 0 or more pointers to doubles as arguments.

This doesnt mean you cant pass strings to an FLI function. Just recast the

double pointer to a char pointer inside the function.

2. Take those arguments either in a list or a vector.

3. Return an integer.

In C syntax, then, your functions would take one of the following forms:

1. int func(void);

2. int func(double *arg1[[, double *arg2, etc.]]);

3. int func(double *argv[]);

Functions can be written to take a list of up to 100 arguments, or a vector (in C terms,

a 1-dimensional array) of up to 1000 arguments. This does not aect how the function

is called from GAUSS; the dllcall statement will always appear to pass the arguments

in a list. That is, the dllcall statement will always look as follows:

dllcall func(a,b,c,d[[,e...]]);

See dllcall in chapter 6 for details on calling your function, passing arguments to it and

getting data back, and what the return value means.

58

F

o

r

e

i

g

n

L

a

n

g

u

a

g

e

I

n

t

e

r

f

a

c

e

Chapter 6

FLI Function Reference

59

dlibrary 6. FLI FUNCTION REFERENCE

Purpose

Dynamically links and unlinks shared libraries.

Format

dlibrary lib1 [lib2...];

dlibrary -a lib1 [lib2...];

dlibrary -d;

dlibrary;

Input

lib1 lib2... literal, the base name of the library or the fully pathed name of the library.

dlibrary takes two types of arguments, base names and le names. Arguments

without any / path separators are assumed to be library base names, and are

expanded by adding the prex lib and the sux .so. They are searched for in

the default dynamic library directory. Arguments that include / path

separators are assumed to be le names, and are not expanded. Relatively

pathed le names are assumed to be specied relative to the current working

directory.

-a append ag, the DLLs listed are added to the current set of DLLs rather than

replacing them. For search purposes, the new DLLs follow the already active

ones. Without the -a ag, any previously linked libraries are dumped.

-d dump ag, ALL DLLs are unlinked and the functions they contain are no longer

available to your programs. If you use dllcall to call one of your functions after

executing a dlibrary -d, your program will terminate with an error.

Remarks

If no ags are used, the DLLs listed are linked into GAUSS and any previously linked

libraries are dumped. When you call dllcall, the DLLs will be searched in the order

listed for the specied function. The rst instance of the function found will be called.

dlibrary with no arguments prints out a list of the currently linked DLLs. The order in

which they are listed is the order in which they are searched for functions.

dlibrary recognizes a default directory in which to look for dynamic libraries. You can

specify this by setting the variable dlib path in gauss.cfg. Set it to point to a single

directory, not a sequence of directories. A new case (case 24) has also been added to

sysstate for getting and setting this default.

GAUSS maintains its own DLL, libgauss.so. libgauss.so is listed when you execute

dlibrary with no arguments, and searched when you call dllcall. By default,

60

F

o

r

e

i

g

n

L

a

n

g

u

a

g

e

I

n

t

e

r

f

a

c

e

6. FLI FUNCTION REFERENCE dlibrary

libgauss.so is searched last, after all other DLLs, but you can force it to be searched

earlier by listing it explicitly in a dlibrary statement. libgauss.so is always active. It

is not unlinked when you execute dlibrary -d. libgauss.so is located in the

$GAUSSHOME directory.

See also

dllcall, sysstatecase 24

61

dllcall 6. FLI FUNCTION REFERENCE

Purpose

Calls functions located in dynamic libraries.

Format

dllcall [-r] [-v] func[(arg1[,arg2...])];

dllcall works in conjunction with dlibrary. dlibrary is used to link dynamic-link libraries

(DLLs) into GAUSS; dllcall is used to access the functions contained in those DLLs.

dllcall searches the DLLs (see dlibrary for an explanation of the search order) for a

function named func, and calls the rst instance it nds. The default DLL,

libgauss.so, is searched last.

Input

func the name of a function contained in a DLL (linked into GAUSS with dlibrary).

If func is not specied or cannot be located in a DLL, dllcall will fail.

arg# arguments to be passed to func; optional. These must be elementary variables;

they cannot be expressions.

-r optional ag. If -r is specied, dllcall examines the value returned by func, and

fails if it is nonzero.

-v optional ag. Normally, dllcall passes parameters to func in a list. If -v is

specied, dllcall passes them in a vector. See below for more details.

Remarks

func should be written to:

1. Take 0 or more pointers to doubles as arguments.

2. Take arguments either in a list or a vector.

3. Return an integer.

In C syntax, func should take one of the following forms:

1. int func(void);

2. int func(double *arg1[,double *arg2...]);

3. int func(double *argv[]);

62

F

o

r

e

i

g

n

L

a

n

g

u

a

g

e

I

n

t

e

r

f

a

c

e

6. FLI FUNCTION REFERENCE dllcall

dllcall can pass a list of up to 100 arguments to func; if it requires more arguments

than that, you MUST write it to take a vector of arguments, and you MUST specify

the -v ag when calling it. dllcall can pass up to 1000 arguments in vector format. In

addition, in vector format dllcall appends a null pointer to the vector, so you can write

func to take a variable number of arguments and just test for the null pointer.

Arguments are passed to func by reference. This means you can send back more than

just the return value, which is usually just a success/failure code. (It also means that

you need to be careful not to overwrite the contents of matrices or strings you want to

preserve.) To return data from func, simply set up one or more of its arguments as

return matrices (basically, by making them the size of what you intend to return), and

inside func assign the results to them before returning.

See also

dlibrary, sysstatecase 24

63

dllcall 6. FLI FUNCTION REFERENCE

64

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

Chapter 7

Language Fundamentals

GAUSS is a compiled language. GAUSS is also an interpreter. These may seem

contradictory but it is necessary to understand each of these ideas to understand how

GAUSS works and how it can be used most eectively.

GAUSS is a compiled language because it scans the entire program once and translates

it into a binary code before it starts to execute the program. GAUSS is an interpreter

because the binary code is not the native code of the CPU. When GAUSS executes the

binary pseudocode it must interpret each instruction for the computer rather than

just turning loose the CPU to execute the binary code by itself.

How then can GAUSS be so fast if it is an interpreter? There are two reasons. The rst

is that GAUSS has a fast interpreter, and the binary compiled code is compact and

ecient. The second reason, and the most signicant one, is that GAUSS is a matrix

language. It is designed to tackle problems that can be solved in terms of matrix or

vector equations. Much of the time lost in interpreting the pseudocode is made up in

the matrix or vector operations.

In the following pages it will be necessary to understand the distinction between

compile time and execution time because these are two very dierent stages in the

life of a GAUSS program.

7.1 Expressions

An expression is a matrix, string, constant, function or procedure reference or any

combination of these joined by operators. An expression returns a result that can be

assigned to a variable with the assignment operator =.

65

7. LANGUAGE FUNDAMENTALS

7.2 Statements

A statement is a complete expression or command. Statements end with a semicolon.

y = x*3;

If an expression has no assignment operator (=), it will be assumed to be an implicit

print statement.

print x*3;

x*3;

The two statements above are equivalent.

output on;

This is an example of a statement that is a command rather than an expression.

Commands cannot be used as a part of an expression.

There can be multiple statements on the same line as long as each statement is

terminated with a semicolon.

7.2.1 Executable Statements

Executable statements are statements that can be executed over and over during the

execution phase of a GAUSS program. As an executable statement is compiled, binary

code is added to the program being compiled at the current location of the instruction

pointer. This binary code will be executed whenever the interpreter passes through this

section of the program. If this code is in a loop, it will be executed each iteration of the

loop.

Here are some examples of executable statements.

y = 34.25;

print y;

x = { 1 3 7 2 9 4 0 3 };

66

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

7.2.2 Nonexecutable Statements

Nonexecutable statements are statements that have an eect only at compile time.

They generate no executable code at the current location of the instruction pointer.

Here are some examples:

declare matrix x = { 1 2 3 4 };

external matrix ybar;

Procedure denitions are nonexecutable. They do not generate executable code at the

current location of the instruction pointer. Here is an example:

zed = rndn(3,3);

proc sqrtinv(x);

local y;

y = sqrt(x);

retp(y+inv(x));

endp;

zsi = sqrtinv(zed);

The two executable statements are the rst line and the last line. In the binary code

that is generated, the last line will follow immediately after the rst line. Everything in

the procedure denition is tucked away somewhere else. The last line is the call to the

procedure. This generates executable code. The procedure denition generates no code

at the current location of the instruction pointer.

There is code generated in the procedure denition, but it is isolated from the rest of

the program. It is executable only within the scope of the procedure and can be

reached only by calling the procedure.

7.3 Programs

A program is any set of statements that are run together at one time. This is a rather

loose denition, but it should suce. If the run statement is used from within a

program, it starts a new program. There are two distinct sections within a program

which need to be understood.

67

7. LANGUAGE FUNDAMENTALS

7.3.1 Main Section

The rst is the main section. The main section of the program is all of the code that is

compiled together WITHOUT relying on the autoloader. This means code that is in

the main le or is included in the compilation of the main le with an #include

statement. ALL executable code should be in the main section.

There is always a main section even if it only consists of a call to the one and only

procedure that is called in the program. The main program code is stored in an area of

memory that can be adjusted in size with the new command.

7.3.2 Secondary Sections

Secondary sections of the program are les that are neither run directly nor included in

the main section with #include statements.

The secondary sections of the program can be left to the autoloader to locate and

compile when they are needed. Secondary sections must have only procedure denitions

and other nonexecutable statements. If you violate this, you will have problems.

GAUSS does not currently enforce this, but it will in later versions.

#include statements are okay in secondary sections as long as the le being included

does not violate the above criteria. Here is an example of a secondary section.

declare matrix tol = 1.0e-15;

proc feq(a,b);

retp(abs(a-b) <= tol);

endp;

7.4 Compiler Directives

Compiler directives are commands that tell GAUSS how to process a program during

compilation. Directives determine what the nal compiled form of a program will be.

They can aect part or all of the source code for a program. Directives are not

executable statements and have no eect at run-time.

The #include statement mentioned above is actually a compiler directive. It tells

GAUSS to compile code from a separate le as though it were actually part of the le

being compiled. This code is compiled in at the position of the #include statement.

Here are the compiler directives available in GAUSS:

68

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

#dene Dene a case-insensitive text-replacement or ag variable.

#denecs Dene a case-sensitive text-replacement or ag variable.

#undef Undene a text-replacement or ag variable.

#ifdef Compile code block if a variable has been #dened.

#ifndef Compile code block if a variable has not been #dened.

#iight Compile code block if running GAUSS Light.

#ifdos Compile code block if running DOS.

#ifos2win Compile code block if running OS/2 or Windows.

#ifunix Compile code block if running Unix.

#else Else clause for #if-#else-#endif code block.

#endif End of #if-#else-#endif code block.

#include Include code from another le in program.

#lineson Compile program with line number and le name records.

#lineso Compile program without line number and le name records.

#srcle Insert source le name record at this point

(currently used when doing data loop translation).

#srcline Insert source le line number record at this point

(currently used when doing data loop translation).

The #dene statement can be used to dene abstract constants. For example, you

could dene the default graphics page size as:

#define hpage 9.0

#define vpage 6.855

You can then write your program using hpage and vpage, and GAUSS will replace

them with 9.0 and 6.855 when it compiles the program. This can make programs much

more readable.

The #ifdef#else#endif directives allow you to conditionally compile sections of a

program, depending on whether a particular ag variable has been #dened. For

example:

#ifdef log_10

y = log(x);

#else

y = ln(x);

#endif

This allows the same program to calculate answers using dierent base logarithms,

depending on whether or not the program has a #dene log 10 statement at the top.

#undef allows you to undene text-replacement or ag variables, so they no longer

aect a program, or so you can #dene them again with a dierent value for a

dierent section of the program. If you use #denecs to dene a case-sensitive

variable, you must use the right case when #undefing it.

69

7. LANGUAGE FUNDAMENTALS

With #lineson, #lineso, #srcline and #srcle you can include line number and le

name records in your compiled code, so that run-time errors will be easier to track

down. #srcline and #srcle are currently used by GAUSS when doing data loop

translation (see Chapter 13). For a discussion of line number tracking see the

Debugger, or Error Handling and Debugging chapter in your platform supplement. See

also #lineson in the COMMAND REFERENCE.

The syntax for #srcle and #srcline is a little dierent than for the other directives

that take arguments. Typically, directives do not take arguments in parentheses (i.e.

they look like keywords).

#define red 4

#srcle and #srcline, however, do take their arguments in parentheses (like

procedures).

#srcline(12)

This allows you to place #srcline statements in the middle of GAUSS commands, so

that line numbers are reported precisely as you want them. For example:

#srcline(1)

print "Here is a multi-line "

#srcline(2)

"sentence--if it contains a run-time error, "

#srcline(3) "you will know exactly "

#srcline(4) "which part of the sentence has the problem.";

The argument supplied to #srcle does not need quotes.

#srcfile(/gauss/test.e)

7.5 Procedures

A procedure allows you to dene a new function which you can then use as if it were an

intrinsic function. It is called in the same way as an intrinsic function.

y = myproc(a,b,c);

Procedures are isolated from the rest of your program and cannot be entered except by

calling them. Some or all of the variables inside a procedure can be local variables.

local variables are variables that exist only when the procedure is actually executing

and then disappear. Local variables cannot get mixed up with other variables of the

same name in your main program or in other procedures.

See Chapter 9 for details on dening and calling procedures.

70

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

7.6 Data Types

There are only two basic data types in GAUSS, matrices and strings. It is not

necessary to declare the type of a variable. The data type and size can change in the

course of a program.

The declare statement, used for compile-time initialization, enforces type checking and

it is good programming practice to respect the types of variables whenever possible.

Short strings of up to 8 bytes can be entered into elements of matrices, to form

character matrices. These are discussed in Section 7.6.4.

7.6.1 Constants

The following constant types are supported.

Decimal

Decimal constants can be either integer or oating point values.

1.34e-10

1.34e123

-1.34e+10

-1.34d-10

1.34d10

1.34d+10

123.456789345

Up to 18 consecutive digits before and after the decimal point(depending on the

platform) are signicant, but the nal result will be rounded to double precision if

necessary. The range is the same as for matrices. See Section 7.6.2.

String

String constants are enclosed in quotation marks.

This is a string.

71

7. LANGUAGE FUNDAMENTALS

Hexadecimal Integer

Hexadecimal integer constants are prexed with 0x.

0x0ab53def2

Hexadecimal Floating Point

Hexadecimal oating point constants are prexed with 0v. This allows you to input a

double precision value exactly as you want using 16 hexadecimal digits. The highest

order byte is to the left.

0vf8000000000000

7.6.2 Matrices

Matrices are 2-dimensional arrays of double precision numbers. All matrices are

implicitly complex, although if it consists only of zeros, the imaginary part may take up

no space. Matrices are stored in row major order. A 2x3 real matrix will be stored in

the following way from the lowest addressed element to the highest addressed element.

[1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]

A 2x3 complex matrix will be stored in the following way from the lowest addressed

element to the highest addressed element.

(real part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]

(imaginary part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]

Conversion between complex and real matrices occurs automatically and is transparent

to the user in most cases. Functions are provided to provide explicit control when

necessary.

All numbers in GAUSS matrices are stored in double precision oating point format,

and each takes up 8 bytes of memory. This is the IEEE 754 format.

Bytes Data Type Signicant Range

Digits

8 oating point 1516 4.19x10

307

[X[ 1.67x10

+308

72

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

Matrices with only one number (1x1 matrices) are referred to as scalars, and matrices

with only one row or column (1xN or Nx1 matrices) are referred to as vectors.

Any matrix or vector can be indexed with 2 indices. Vectors can be indexed with one

index. Scalars can be indexed with one or two indices also, because scalars, vectors,

and matrices are the same data type to GAUSS

The majority of functions and operators in GAUSS take matrices as arguments. The

following functions and operators are used for dening, saving, and loading matrices:

[ ] indexing matrices

= assignment operator

| vertical concatenation

horizontal concatenation

con numeric input from keyboard

cons character input from keyboard

declare compile-time matrix or string initialization

let matrix denition statement

load load matrix (same as loadm)

readr read from a GAUSS le

save save matrices, procedures and strings to disk

saved convert a matrix to a GAUSS data set

stof convert string to matrix

submat extract a submatrix

writer write data to a GAUSS data set

Examples of matrix denition statements are:

let x = { 1 2 3, 4 5 6, 7 8 9 };

or

x = { 1 2 3, 4 5 6, 7 8 9 };

x =

1 2 3

4 5 6

7 8 9

An assignment statement followed by data enclosed in braces is an implicit let

statement. Only constants are allowed in let statements; operators are illegal. When

braces are used in let statements, commas are used to separate rows.

let x[3,3] = 1 2 3 4 5 6 7 8 9;

73

7. LANGUAGE FUNDAMENTALS

x =

1 2 3

4 5 6

7 8 9

let x[3,3] = 1;

x =

1 1 1

1 1 1

1 1 1

let x[3,3];

x =

0 0 0

0 0 0

0 0 0

let x = 1 2 3 4 5 6 7 8 9;

x =

1

2

3

4

5

6

7

8

9

let x[2,2] = 1+2i 3-4 5 6i;

x =

1 + 2i 3 4i

5 0 + 6i

Complex constants can be entered in a let statement. Note that in this case, the + or -

is not a mathematical operator, but connects the two parts of a complex number.

There can be no spaces between the + or - and the parts of the number. If a number

74

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

has both real and imaginary parts, the trailing i is not necessary. If a number has no

real part, you can indicate that it is imaginary by appending the i.

Complex constants can also be used with the declare, con and stof statements.

An empty matrix is a matrix that contains no data. Empty matrices are created with

the let statement.

x = {};

You must use the form of the let statement with curly braces to create an empty

matrix.

Empty matrices are currently supported ONLY by the rows and cols functions and the

concatenation (~,|) operators.

x = {};

hsec0 = hsec;

do until hsec-hsec0 > 6000;

x = x ~ data_in(hsec-hsec0);

endo;

You can test whether a matrix is empty by entering rows(x), cols(x) and scalerr(x). If

the matrix is empty rows and cols will return a 0, and scalerr will return 65535.

y = 12|34;

The is the horizontal concatenation operator and the | is the vertical concatenation

operator. This statement would be evaluated as:

y = (12)|(34);

because horizontal concatenation has precedence over vertical concatenation, and would

result in a 2x2 matrix.

1 2

3 4

y = 1+12*2|3-26/2;

75

7. LANGUAGE FUNDAMENTALS

This statement would be evaluated as:

y = ((1+1)(2*2))|((3-2)(6/2));

because the arithmetic operators have precedence over concatenation, and would result

in a 2x2 matrix. See also section 7.7.

2 4

1 3

let x[2,2] = 1 2 3 4;

The let command is used to initialize matrices with constant values. Unlike the

concatenation operators, it cannot be used to dene matrices in terms of expressions

such as:

y = x1-x2x2|x3*3x4;

y = x[1:3,5:8];

will put the intersection of the rst 3 rows and the fth through eighth columns of x

into the matrix y.

y = x[1 3 1,5 5 9];

will create a 3x3 matrix y with the intersection of the specied rows and columns

pulled from x (in the indicated order).

let r = 1 3 1;

let c = 5 5 9;

y = x[r,c];

will have the same eect as the example above, but is more general.

y[2,4] = 3;

76

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

will set the 2,4 element of the existing matrix y to 3. This statement is illegal if y does

not have at least 2 rows and 4 columns.

x = con(3,2);

will cause a ? to be printed on the screen, and will prompt the user until 6 numbers

have been entered from the keyboard.

load x[] = b:mydata.asc

will load data contained in an ASCII le into an Nx1 vector x (use rows(x) to nd out

how many numbers were loaded, and use reshape(x,N,K) to reshape it to an NxK

matrix).

load x;

will load the matrix x.fmt from disk (using the current load path) into the matrix x in

memory.

open d1 = dat1;

x = readr(d1,100);

will read the rst 100 rows of the GAUSS data set dat1.dat.

7.6.3 Strings and String Arrays

Strings

Strings can be used to store the names of les to be opened, messages to be printed,

entire les, or whatever else you might need. Any byte value is legal in a string from

0255. The buer where a string is stored always contains a terminating byte of ASCII

0. This allows passing strings as arguments to C functions through the foreign language

interface. Here is a partial list of the functions for manipulating strings.

77

7. LANGUAGE FUNDAMENTALS

$+ combines two strings into one long string.

^ interpret following name as a variable, not a literal.

chrs convert vector of ASCII codes to character string.

ftocv character representation of numbers in NxK matrix.

ftos character representation of numbers in 1x1 matrix.

getf load ASCII or binary le into string.

indcv nd index of element in character vector.

lower convert to lowercase.

stof convert string to oating point.

strindx nd index of a string within a second string.

strlen length of a string.

strsect extract substring of string.

upper convert to uppercase.

vals convert from string to numeric vector of ASCII codes.

Strings can be created like this:

x = "example string";

or

x = cons; /* keyboard input */

or

x = getf("myle",0); /* read a le into a string */

They can be printed like this:

print x;

A character matrix must have a $ prexed to it in a print statement.

print $x;

A string can be saved to disk with the save command in a le with a .fst extension

and then loaded with the load command as follows:

save x;

loads x;

or

loads x=x.fst;

The backslash is used as the escape character inside double quotes to enter special

characters. backslash escape character

"\b" backspace (ASCII 8)

"\e" escape (ASCII 27)

"\f" formfeed (ASCII 12)

"\g" beep (ASCII 7)

"\l" line feed (ASCII 10)

"\r" carriage return (ASCII 13)

"\t" tab (ASCII 9)

"\\" a backslash

"\###" the ASCII character whose decimal value is ###.

78

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

When entering DOS pathnames in double quotes two backslashes must be used to

insert one backslash.

st = "c:\\gauss\\myprog.prg";

An important use of strings (and also character elements of matrices; see below) is with

the substitution, or caret (^), operator.

In a command like the following:

create f1 = olsdat with x,4,2;

by default GAUSS will interpret the olsdat as a literal, i.e., the literal name of the

GAUSS data le that you want to create. It will also interpret the x as the literal prex

string for the variable names: x1 x2 x3 x4.

If you want to get the data set name from a string variable, the (^) caret operator

could be used as:

dataset="olsdat";

create f1=^dataset with x,4,2;

If you want to get the data set name from a string variable and the variable names

from a character vector, then use the following:

dataset="olsdat";

let vnames=age pay sex;

create f1=^dataset with ^vnames,0,2;

The (^) caret operator works with load, save, and dos also.

lpath="/gauss/procs";

name="mydata";

load path=^lpath x=^name;

command="dir *.fmt";

dos ^command;

The general syntax is:

^variable name

Expressions are not allowed. The following commands are supported with the

substitution operator.

create f1=^dataset with ^vnames,0,2;

create f1=^dataset using ^cmdle;

open f1=^dataset;

output le=^outle;

load x=^datale;

load path=^lpath x,y,z,t,w;

loadexe buf=^exele;

save ^name=x;

save path=^spath;

dos ^cmdstr;

run ^prog;

msym ^mstring;

79

7. LANGUAGE FUNDAMENTALS

String Arrays

String arrays are NxK matrices of strings. Here is a partial list of the functions for

manipulating string arrays:

80

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

$| vertical string array concatenation operator.

$~ horizontal string array concatenation operator.

[ ] extract subarrays or individual strings from their

corresponding array, or assign their values.

/ transpose operator.

./ bookkeeping transpose operator.

declare initializes variables at compile time.

delete deletes specied global symbols.

fgetsa reads multiple lines of text from a le.

fgetsat reads multiple lines of text from a le, discarding

newlines.

format denes output format for matrices, string arrays,

and strings.

fputs writes strings to a le.

fputst writes strings to a le, appending newlines.

let initializes matrices, strings, and string arrays.

loads loads a string or string array le (.fst file).

lprint prints expressioins to the printer.

lshow prints global symbol table to the printer.

print prints expressions on screen and/or auxiliary output.

reshape reshapes a matrix or string array to new dimensions.

save saves matrix, string array, string, procedure, function

or keyword to disk and gives the disk le either a .fmt,

.fst or .fcg extension.

show displays global symbol table.

sortcc quick-sorts rows of matrix or string array based on

character column.

type indicates whether variable passed as argument is matrix,

string, or string array.

typecv indicates whether variables named in argument are strings,

string arrays, matrices, procedures, functions or keywords.

varget accesses the global variable named by a string array.

varput assigns the global variable named by a string array.

vec stacks columns of a matrix or string array to form a

column vector.

vecr stacks rows of a matrix or string array to form a column vector.

81

7. LANGUAGE FUNDAMENTALS

String arrays are created through the use of the string array concatenation operators.

Below is a contrast of the horizontal string and horizontal string array concatenation

operators.

x = "age";

y = "pay";

n = "sex";

s = x $+ y $+ n;

sa = x $~ y $~ n;

s = agepaysex

sa = age pay sex

7.6.4 Character Matrices

Matrices can have either numeric or character elements. For convenience we refer to a

matrix containing character elements as a character matrix.

A character matrix is not a separate data type but just gives you the ability to store

and manipulate data elements that are composed of ASCII characters as well as

oating point numbers. For example, you may want to concatenate a column vector

containing the names of the variables in an analysis onto a matrix containing the

coecients, standard errors, t-statistic, and p-value. You can then print out the whole

matrix with a separate format for each column with one call to the function printfm.

The logic of the programs will dictate the type of data that is assigned to a matrix, and

the increased exibility allowed by being able to bundle both types of data together in

a single matrix can be very powerful. You could, for instance, create a moment matrix

from your data, concatenate a new row onto it containing the names of the variables

and save it to disk with the save command.

Numeric matrices are double precision, which means that each element is stored in

8 bytes. A character matrix can thus have elements of up to 8 characters. Character

matrices are ideal for the manipulation of the names of the columns in a data matrix,

which are limited to 8 characters.

GAUSS does not automatically keep track of whether a matrix contains character or

numeric information. The ASCII to GAUSS conversion program atog will record the

types of variables in a data set when it creates it. The create command will, too. The

function vartypef gets a vector of variable type information from a data set. This

vector of ones and zeros can be used by printfm when printing your data. Since

GAUSS does not know whether a matrix has character or numeric information, it is up

to the user to specify which type of data it contains when printing the contents of the

matrix. See print and printfm for details.

Most functions that take a string argument will take an element of a character matrix

also, interpreting it as a string of up to 8 characters.

82

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

7.6.5 Special Data Types

The IEEE oating point format has many encodings that have special meaning. The

print command will print them accurately so that you can tell if your calculation is

producing results that are meaningful.

NaN

There are many oating point encodings which do not correspond to a real number.

These encodings are referred to as NaNs. NaN stands for Not A Number.

Certain numerical errors will cause the math coprocessor to create a NaN called an

indenite. This will be printed as a -NaN when using the print command. These

values are created by the following operations.

+ plus

+ minus +

minus

0

/

0 / 0

Operations where one or both operands is a NaN

Trigonometric functions involving

INF

When the math coprocessor overows, the result will be a properly signed innity.

Most subsequent calculations will not deal with innities very well, and it is usually a

signal of an error in your program. The result of an operation involving an innity is

usually a NaN.

DEN, UNN

When some math coprocessors underow, they may do so gradually by shifting the

signicand of the number as necessary to keep the exponent in range. The result of this

83

7. LANGUAGE FUNDAMENTALS

is a denormal (DEN). When denormals are used in calculations, they are usually

handled automatically in an appropriate way. The result will either be an unnormal

(UNN), which like the denormal represents a number very close to zero, or a normal,

depending on how signicant the eect of the denormal was in the calculation. In some

cases the result will be a NaN. This can happen in GAUSS for DOS when the value

that is in a math coprocessor register in 80-bit format is an unnormal and has an

exponent that is within the range of the 64-bit double precision format. Therefore,

sometimes multiplying an unnormal by another number will result in a NaN. Following

are some procedures for dealing with these values.

The procedure isindef will return 1 (true) if the matrix passed to it contains any NaNs

that are the indenite mentioned above. The GAUSS missing value code as well as

GAUSS scalar error codes are NaNs, but this procedure tests only for indenite.

proc isindef(x);

retp(not x $/= __INDEFn);

endp;

Be sure to call gausset before calling isindef. gausset will initialize the value of the

global INDEFn to a platform specic encoding.

The procedure normal will return a matrix with all denormals and unnormals set to

zero.

proc normal(x);

retp(x .* (abs(x) .> 4.19e-307));

endp;

This procedure, isinf, will return 1 (true) if the matrix passed to it contains any

innities.

proc isinf(x);

local plus,minus;

plus = __INFp;

minus = __INFn;

retp(not x /= plus or not x /= minus);

endp;

Be sure to call gausset before calling isinf. gausset will initialize the value of the

globals INFn and INFp to platform specic encodings.

7.7 Operator Precedence

The order in which an expression is evaluated is determined by the precedence of the

operators involved and the order in which they are used. For example, the * and /

84

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

operators have a higher precedence than the + and - operators. In expressions which

contain the above operators, the operand pairs associated with the * or / operator are

evaluated rst. Whether * or / is evaluated rst depends on which comes rst in the

particular expression.

The precedence of all operators is listed in Appendix D.

The expression

-5+3/4+6*3

is evaluated as

(5) +(3/4) + (6 3)

Within a term, operators of equal precedence are evaluated from left to right.

The term

2^3^7

is evaluated

(2

3

)

7

In the expression

f1(x)*f2(y)

the function f1 is evaluated before f2.

Here are a few examples:

expression evaluation

a+b*c+d (a +(b c)) +d

-2+4-6*inv(8)/9 ((2) + 4) ((6 inv(8))/9)

3.14^5*6/(2+sqrt(3)/4) ((3.14

5

) 6)/(2 + (sqrt(3)/4))

-a+b*c^2 (a) + (b (c

2

))

a+b-c+d-e (((a +b) c) +d) e

a^b^c*d ((a

b

)

c

) d

a*b/d*c ((a b)/d) c

a^b+c*d (a

b

) + (c d)

2^4! (2

4

)!

2*3! 2 (3!)

85

7. LANGUAGE FUNDAMENTALS

7.8 Flow Control

A computer language needs facilities for decision making and looping to control the

order in which computations are done. GAUSS has several kinds of ow control

statements.

7.8.1 Looping

do loop

The do statement can also be used in GAUSS to control looping.

do while scalar expression; Loop if expression is true.

.

.

.

statements

.

.

.

endo;

do until scalar expression; Loop if expression is false.

.

.

.

statements

.

.

.

endo;

The scalar expression is any expression that returns a scalar result. The expression will

be evaluated as TRUE if its real part is nonzero and FALSE if it is zero. There is no

counter variable that is automatically incremented in a do loop. If one is used, it must

be set to its initial value before the loop is entered and explicitly incremented or

decremented inside the loop. The following example illustrates nested do loops that use

counter variables.

format /rdn 1,0;

space = " ";

comma = ",";

i = 1;

do while i <= 4;

j = 1;

do while j <= 3;

print space i comma j;;

j = j+1;

endo;

i = i+1;

print;

endo;

86

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

The example above will print the following.

1,1 1,2 1,3

2,1 2,2 2,3

3,1 3,2 3,3

4,1 4,2 4,3

Use the relational and logical operators without the dot . in the expression that

controls a do loop. These operators always return a scalar result.

break and continue are used within do loops to control execution ow. When break is

encountered, the program will jump to the statement following the endo. This

terminates the loop. When continue is encountered, the program will jump up to the

top of the loop and reevaluate the while or until expression. This allows you to

reiterate the loop without executing any more of the statements inside the loop.

do until eof(fp); /* continue jumps here */

x = packr(readr(fp,100));

if scalmiss(x);

continue; /* iterate again */

endif;

s = s + sumc(x);

count = count + rows(x);

if count >= 10000;

break; /* break out of loop */

endif;

endo;

mean = s / count; /* break jumps here */

for loop

The fastest looping construct in GAUSS is the for loop.

for counter (start , stop, step);

.

.

.

statements

.

.

.

endfor;

counter is the literal name of the counter variable. start , stop and step are scalar

expressions. start is the initial value, stop is the nal value and step is the increment.

break and continue are also supported by for loops. For more information see for in

the COMMAND REFERENCE.

87

7. LANGUAGE FUNDAMENTALS

7.8.2 Conditional Branching

The if statement controls conditional branching.

if scalar expression;

.

.

.

statements

.

.

.

elseif scalar expression;

.

.

.

statements

.

.

.

else;

.

.

.

statements

.

.

.

endif;

The scalar expression is any expression that returns a scalar result. The expression will

be evaluated as TRUE if its real part is nonzero and FALSE if it is zero.

GAUSS will test the expression after the if statement. If it is TRUE, then the rst list

of statements is executed. If it is FALSE, then GAUSS will move to the expression

after the rst elseif statement, if there is one, and test it. It will keep testing

expressions and will execute the rst list of statements that corresponds to a TRUE

expression. If no expression is TRUE, then the list of statements following the else

statement is executed. After the appropriate list of statements is executed, the program

will go to the statement following the endif and continue on.

Use the relational and logical operators without the dot . in the expression that

controls an if or elseif statement. These operators always return a scalar result.

if statements can be nested.

One endif is required per if clause. If an else statement is used, there may be only one

per if clause. There may be as many elseifs as are required. There need not be any

elseifs or any else statement within an if clause.

7.8.3 Unconditional Branching

The goto and gosub statements control unconditional branching. The target of both a

goto and a gosub is a label.

88

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

goto

A goto is an unconditional jump to a label with no return.

label:

.

.

goto label;

Parameters can be passed with a goto. The number of parameters is limited by

available stack space. This is handy for common exit routines.

.

.

goto errout("Matrix singular");

.

.

goto errout("File not found");

.

.

errout:

pop errmsg;

errorlog errmsg;

end;

gosub

With a gosub, the address of the gosub statement is remembered and when a return

statement is encountered, the program will resume executing at the statement following

the gosub.

Parameters can be passed with a gosub in the same way as a goto. With a gosub it is

also possible to return parameters with the return statement.

Subroutines are not isolated from the rest of your program and the variables referred to

between the label and the return statement can be accessed from other places in your

program.

Since a subroutine is only an address marked by a label, there can be subroutines inside

of procedures. The variables that are used in these subroutines are the same variables

that are known inside the procedure. They will not be unique to the subroutine, but

they may be locals that are unique to the procedure that the subroutine is in. See

gosub in the COMMAND REFERENCE for the details.

89

7. LANGUAGE FUNDAMENTALS

7.9 Functions

Single line functions that return one item can be dened with the fn statement.

fn area(r) = pi * r * r;

These functions can be called in the same way as intrinsic functions. The above

function could be used in the following program sequence.

diameter = 3;

radius = 3 / 2;

a = area(radius);

7.10 Rules of Syntax

This section lists the general rules of syntax for GAUSS programs.

7.10.1 Statements

A GAUSS program consists of a series of statements. A statement is a complete

expression or command. Statements in GAUSS end with a semicolon. See your

supplement for the maximum statement length in this implementation.

There is one exception to the rule that statements must end with a semicolon. From

the GAUSS command line, the nal semicolon in an interactive program is implicit if it

is not explicitly given.

(gauss) x=5; z=rndn(3,3); y=x+z

Column position is not signicant. Blank lines are allowed. Inside a statement and

outside of double quotes, the carriage return/line feed at the end of a physical line will

be converted to a space character as the program is compiled.

A statement containing a quoted string can be continued across several lines with a

backslash as follows.

s = "This is one really long string that would be "\

"difficult to assign in just a single line.";

7.10.2 Case

GAUSS does not distinguish between uppercase and lowercase except inside double

quotes.

With some operating systems, le names are case sensitive.

90

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

7.10.3 Comments

/* This kind of comment can be nested */

@ This kind cannot be nested @

7.10.4 Extraneous Spaces

Extraneous spaces are signicant in print and lprint statements where the space is a

delimiter between expressions.

print x y z;

In print and lprint statements, spaces can be used in expressions that are in parentheses.

print (x * y) (x + y);

7.10.5 Symbol Names

The names of matrices, strings, procedures, and functions can be up to 32 characters

long. The characters must be alphanumeric or the underscore. The rst character must

be alphabetic or an underscore.

7.10.6 Labels

A label is used as the target of a goto or a gosub. The rule for naming labels is the

same as for matrices, strings, procedures, and functions. A label is followed

immediately by a colon.

here:

The reference to a label does not use a colon.

goto here;

7.10.7 Assignment Statements

The equal sign = is the assignment operator.

y = x + z;

Multiple assignments must be enclosed in braces.

{ mant,pow } = base10(x);

The (equal to) comparison operator is two equal signs ==.

if x == y;

print "x is equal to y";

endif;

91

7. LANGUAGE FUNDAMENTALS

7.10.8 Function Arguments

The arguments to functions are enclosed in parentheses.

y = sqrt(x);

7.10.9 Indexing Matrices

Brackets [ ] are used to index matrices.

x = { 1 2 3,

3 7 5,

3 7 4,

8 9 5,

6 1 8 };

y = x[3,3];

z = x[1 2:4,1 3];

Vectors can be indexed with either 1 or 2 indices.

v = { 1 2 3 4 5 6 7 8 9 };

k = v[3];

j = v[1,6:9];

x[2,3] returns the element in the second row and the third column of x.

x[1 3 5,4 7] returns the submatrix that is the intersection of rows 1, 3 and 5 and

columns 4 and 7.

x[.,3] returns the third column of x.

x[3:5,.] returns the submatrix containing the third through the fth rows of x.

The indexing operator will take vector arguments for submatrix extraction or

submatrix assignments.

y = x[rv,cv];

y[rv,cv] = x;

rv and cv can be any expressions returning vectors or matrices. The elements of rv will

be used as the row indices and the elements of cv will be used as the column indices. If

rv is a scalar 0, then all rows will be used and if cv is a scalar 0, then all columns will

be used. If a vector is used in an index expression, then it is illegal to use the space

operator or the colon operator on the same side of the comma as the vector.

92

L

a

n

g

u

a

g

e

F

u

n

d

a

m

e

n

t

a

l

s

7. LANGUAGE FUNDAMENTALS

7.10.10 Arrays of Matrices and Strings

It is possible to index sets of matrices or strings using the varget function. Consider

the following example.

mvec = { x y z a };

i = 2;

g = inv(varget(mvec[i]));

In this example, a set of matrix names is assigned to mvec. The name y is indexed

from mvec and passed to varget which will return the global matrix y. The returned

matrix is inverted and assigned to g.

The following procedure can be used to index the matrices in mvec more directly.

proc imvec(i);

retp(varget(mvec[i]));

endp;

Then imvec(i) will equal the matrix whose name is in the i

th

element of mvec.

In the example above, the procedure imvec() was written so that it always operates on

the vector mvec. The following procedure makes it possible to pass in the vector of

names being used.

proc get(array,i);

retp(varget(array[i]));

endp;

Then get(mvec,3) will return the 3

rd

matrix listed in mvec.

proc put(x,array,i);

retp(varput(x,array[i]));

endp;

And put(x,mvec,3) will assign x to the 3

rd

matrix listed in mvec and return a 1 if

successful or a 0 if it fails.

7.10.11 Arrays of Procedures

It is also possible to index procedures. The ampersand (&) operator is used to return a

pointer to a procedure.

As an example, assume that f1, f2, and f3 are procedures that take a single argument.

The following code denes a procedure that will return the value of the i

th

procedure,

evaluated at x.

93

7. LANGUAGE FUNDAMENTALS

nms = &f1 | &f2 | &f3;

proc fi(x,i);

local f;

f = nms[i];

local f:proc;

retp( f(x) );

endp;

For instance, (x,2) will return f2(x). The ampersand is used to return the pointers to

the procedures. nms is just a numeric vector that contains a set of pointers. The local

statement is used twice. The rst one tells the compiler that f is a local matrix. The i

th

pointer (which is just a number) is assigned to f. Then the second local statement tells

the compiler to treat f as a procedure from this point on, and so the subsequent

statement f(x) is interpreted as a procedure call.

94

O

p

e

r

a

t

o

r

s

Chapter 8

Operators

8.1 Element-by-Element Operators

The operators described as element-by-element operators share common rules of

conformability. Some functions that have two arguments also operate according to the

same rules.

The element-by-element operators handle those situations in which matrices are not

conformable according to standard rules of matrix algebra. When a matrix is said to be

ExE conformable, it refers to this element-by-element conformability. The following

cases are supported.

matrix op matrix

matrix op scalar

scalar op matrix

matrix op vector

vector op matrix

vector op vector

In a typical expression involving an element-by-element operator:

z = x + y;

conformability is dened as follows.

95

8. OPERATORS

If x and y are the same size, the operations are carried out corresponding

element by corresponding element.

x =

1 3 2

4 5 1

3 7 4

y =

2 4 3

3 1 4

6 1 2

z =

3 7 5

7 6 5

9 8 6

If x is a matrix and y is a scalar, or vice versa, then the scalar is operated on

with respect to every element in the matrix. For example, x + 2 will add 2 to

every element of x.

x =

1 3 2

4 5 1

3 7 4

y = 2

z =

3 5 4

6 7 3

5 9 6

If x is an Nx1 column vector and y is an NxK matrix, or vice versa, the vector is

swept across the matrix.

vector matrix

1 2 4 3

4 3 1 4

3 6 1 2

result

3 5 4

7 5 8

9 4 5

If x is an 1xK column vector and y is an NxK matrix, or vice versa, then the

vector is swept down the matrix.

96

O

p

e

r

a

t

o

r

s

8. OPERATORS

vector 2 4 3

2 4 3

matrix 3 1 4

6 1 2

4 8 6

result 5 5 7

8 5 5

When one argument is a row vector and the other is a column vector, the result

of an element-by-element operation will be the table of the two.

row vector 2 4 3 1

3 5 7 6 4

column vector 2 4 6 5 3

5 7 9 8 6

If x and y are such that none of these conditions apply, then the matrices are not

conformable to these operations and an error message will be generated.

8.2 Matrix Operators

The following operators work on matrices. Some assume numeric data and others will

work on either character or numeric data.

8.2.1 Numeric Operators

See Section 8.1 for details on how matrix conformability is dened for

element-by-element operators.

+ Addition:

y = x + z;

97

8. OPERATORS

Performs element-by-element addition.

Subtraction or negation:

y = x z;

y = k;

Performs element-by-element subtraction or the negation of all elements,

depending on context.

* Matrix multiplication or multiplication:

y = x * z;

When z has the same number of rows as x has columns, this will perform matrix

multiplication (inner product). If x or z are scalar, this performs standard

element-by-element multiplication.

/ Division or linear equation solution.

x = b / A;

If A and b are scalars, it performs standard division. If one of the operands is a

matrix and the other is scalar, the result is a matrix the same size with the

results of the divisions between the scalar and the corresponding elements of the

matrix. Use ./ for element-by-element division of matrices.

If b and A are conformable, this operator solves the linear matrix equations.

Ax = b

Linear equation solution is performed in the following cases.

If A is a square matrix and has the same number of rows as b, then this

statement will solve the system of linear equations using an LU

decomposition.

If A is rectangular with the same number of rows as b, then this statement

will produce the least squares solutions by forming the normal equations

and using the Cholesky decomposition to get the solution.

y =

A

b

A

A

If trap 2 is set, missing values will be handled with pairwise deletion.

For least squares solutions on OS/2 and DOS, all computations and storage

of intermediate results are done in 80-bit precision. prcsn 64 can be

specied to force 64-bit precision for smaller matrices or when using these

platforms.

98

O

p

e

r

a

t

o

r

s

8. OPERATORS

% Modulo division:

y = x % z;

For integers, this returns the integer value that is the remainder of the integer

division of x by z. If x or z are noninteger, they will rst be rounded to the

nearest integer. This is an element-by-element operator.

! Factorial:

y = x!;

Computes the factorial of every element in the matrix x. Nonintegers are

rounded to the nearest integer before the factorial operator is applied. This will

not work with complex matrices. If x is complex, a fatal error will be generated.

.* Element-by-element multiplication:

y = x .* z;

If x is a column vector, and z is a row vector (or vice versa), then the outer

product or table of the two will be computed. See Section 8.1 for

conformability rules.

./ Element-by-element division:

y = x ./ z;

^ Element-by-element exponentiation.

y = x^z;

If x is negative, z must be an integer.

.^ Same as ^

.*. Kronecker (tensor) product:

y = x .*. z;

This results in a matrix in which every element in x has been multiplied (scalar

multiplication) by the matrix z. For example:

x = { 1 2,

3 4 };

z = { 4 5 6,

7 8 9 };

y = x .*. z;

99

8. OPERATORS

x =

1 2

3 4

z =

4 5 6

7 8 9

y =

4 5 6 8 10 12

7 8 9 14 16 18

12 15 18 16 20 24

21 24 27 28 32 36

Horizontal direct product.

z = x y;

x =

1 2

3 4

y =

5 6

7 8

z =

5 6 10 12

21 24 28 32

The input matrices x and y must have the same number of rows. The result will

have cols(x) * cols(y) columns.

8.2.2 Other Matrix Operators

/ Transpose operator

y = x

;

In the expression above the columns of y will contain the same values as the

rows of x and the rows of y will contain the same values as the columns of x.

For complex matrices this computes the complex conjugate transpose.

If an operand immediately follows the transpose operator, the

will be

interpreted as

*. Thus y = x

x is equivalent to y = x

*x.

.

y = x.

;

This is provided primarily as a matrix handling tool for complex matrices. For

all matrices, the columns of y will contain the same values as the rows of x and

the rows of y will contain the same values as the columns of x. The complex

conjugate transpose is NOT computed when you use .

.

If an operand immediately follows the bookkeeping transpose operator, the .

will be interpreted as .

*. Thus y = x.

x is equivalent to y = x.

*x.

100

O

p

e

r

a

t

o

r

s

8. OPERATORS

| Vertical concatenation

z = x|y;

x =

1 2 3

3 4 5

y = 7 8 9

z =

1 2 3

3 4 5

7 8 9

Horizontal concatenation

z = xy;

x =

1 2

3 4

y =

5 6

7 8

z =

1 2 5 6

3 4 7 8

8.3 Relational Operators

See Section 8.1 for details on how matrix conformability is dened for

element-by-element operators.

Each of these operators has two equivalent representations. Either can be used (e.g., <

or lt), depending only upon preference. The alphabetic form should be surrounded by

spaces.

A third form of these operators has a $ and is used for comparisons between character

data and for comparisons between strings or string arrays. The comparisons are done

byte by byte starting with the lowest addressed byte of the elements being compared.

The equality comparison operators (<=, ==, >=, /=) and their dot equivalents can

be used to test for missing values and the NaN that is created by oating point

exceptions. Less than and greater than comparisons are not meaningful with missings

or NaNs, but equal and not equal will be valid. These operators are sign-insensitive for

missings, NaNs, and zeros.

The string $ versions of these operators can also be used to test missings, NaNs and

zeros. Because they do a strict byte-to-byte comparison, they are sensitive to the sign

101

8. OPERATORS

bit. Missings, NaNs, and zeros can all have the sign bit set to 0 or 1, depending on

how they were generated and have been used in a program.

If the relational operator is NOT preceded by a dot ., then the result is always a

scalar 1 or 0, based upon a comparison of all elements of x and y. All comparisons

must be true for the relational operator to return TRUE.

By this denition, then

if x /= y;

is interpreted as: is every element of x not equal to the corresponding element of y.

To check if two matrices are not identical, use:

if not x == y;

For complex matrices, the ==, /=, .== and ./= operators compare both the real and

imaginary parts of the matrices; all other relational operators compare only the real

parts.

Less than

z = x < y;

z = x lt y;

z = x $< y;

Less than or equal to

z = x <= y;

z = x le y;

z = x $<= y;

Equal to

z = x == y;

z = x eq y;

z = x $== y;

Not equal

z = x /= y;

z = x ne y;

z = x $/= y;

102

O

p

e

r

a

t

o

r

s

8. OPERATORS

Greater than or equal to

z = x >= y;

z = x ge y;

z = x $>= y;

Greater than

z = x > y;

z = x gt y;

z = x $> y;

If the relational operator IS preceded by a dot ., then the result will be a matrix of 1s

and 0s, based upon an element-by-element comparison of x and y.

Element-by-element less than

z = x .< y;

z = x .lt y;

z = x .$< y;

Element-by-element less than or equal to

z = x .<= y;

z = x .le y;

z = x .$<= y;

Element-by-element equal to

z = x .== y;

z = x .eq y;

z = x .$== y;

Element-by-element not equal to

z = x ./= y;

z = x .ne y;

z = x .$/= y;

Element-by-element greater than or equal to

z = x .>= y;

103

8. OPERATORS

z = x .ge y;

z = x .$>= y;

Element-by-element greater than

z = x .> y;

z = x .gt y;

z = x .$> y;

8.4 Logical Operators

The logical operators perform logical or Boolean operations on numeric values. On

input a nonzero value is considered TRUE and a zero value is considered FALSE. The

logical operators return a 1 if TRUE and a 0 if FALSE. Decisions are based on the

following truth table.

Complement

X not X

T F

F T

Conjunction

X Y X and Y

T T T

T F F

F T F

F F F

Disjunction

X Y X or Y

T T T

T F T

F T T

F F F

104

O

p

e

r

a

t

o

r

s

8. OPERATORS

Exclusive Or

X Y X xor Y

T T F

T F T

F T T

F F F

Equivalence

X Y X eqv Y

T T T

T F F

F T F

F F T

For complex matrices, the logical operators consider only the real part of the matrices.

The following operators require scalar arguments. These are the ones to use in if and

do statements.

Complement

z = not x;

Conjunction

z = x and y;

Disjunction

z = x or y;

Exclusive or

z = x xor y;

Equivalence

z = x eqv y;

If the logical operator is preceded by a dot ., the result will be a matrix of 1s and 0s

based upon an element-by-element logical comparison of x and y.

Element-by-element logical complement

z = .not x;

105

8. OPERATORS

Element-by-element conjunction

z = x .and y;

Element-by-element disjunction

z = x .or y;

Element-by-element exclusive or

z = x .xor y;

Element-by-element equivalence

z = x .eqv y;

8.5 Other Operators

Assignment Operator

Assignments are done with one equal sign.

y = 3;

(comma)

Commas are used to delimit lists.

clear x,y,z;

Commas are also used to separate row indices from column indices within brackets.

y = x[3,5];

And to separate arguments of functions within parentheses.

y = momentd(x,d);

(period)

Dots are used in brackets to signify all rows or all columns.

y = x[.,5];

106

O

p

e

r

a

t

o

r

s

8. OPERATORS

(space)

Spaces are used inside of index brackets to separate indices.

y = x[1 3 5,3 5 9];

No extraneous spaces are allowed immediately before or after the comma, or

immediately after the left bracket or before the right bracket.

Spaces are also used in print and lprint statements to separate the separate expressions

to be printed.

print x/2 2*sqrt(x);

Therefore, no extraneous spaces are allowed within expressions in print or lprint

statements unless the expression is enclosed in parentheses.

print (x / 2) (2 * sqrt(x));

(colon)

A colon is used within brackets to create a continuous range of indices.

y = x[1:5,.];

(ampersand)

The (&) ampersand operator will return a pointer to a procedure (proc) or function

(fn). It is used when passing procedures or functions to other functions and for

indexing procedures. See Section 9.5.

String Concatenation

x = "dog";

y = "cat";

z = x $+ y;

print z;

dogcat

107

8. OPERATORS

If the rst argument is of type STRING, the result will be of type STRING. If the rst

argument is of type MATRIX, the result will be of type MATRIX. See the following

examples:

y = 0 $+ "caterpillar";

The result will be a 1x1 matrix containing caterpil.

y = zeros(3,1) $+ "cat";

The result will be a 3x1 matrix, each element containing cat.

If we use the y created above in the following:

k = y $+ "fish";

The result will be a 3x1 matrix with each element containing catsh.

If we then use k created above:

t = "" $+ k[1,1];

The result will be a STRING containing catsh. If we used the same k to create z as

follows:

z = "dog" $+ k[1,1];

The resulting z will be a string containing dogcatsh.

String Array Concatenation

$| vertical string array concatenation.

x = "dog";

y = "fish";

k = x $| y;

print k;

dog

fish

$~ horizontal string array concatenation.

x = "dog";

y = "fish";

k = x $~ y;

print k;

dog fish

108

O

p

e

r

a

t

o

r

s

8. OPERATORS

String Variable Substitution

In a command like the following:

create f1 = olsdat with x,4,2;

by default GAUSS will interpret olsdat as the literal name of the GAUSS data le that

you want to create. It will also interpret x as the literal prex string for the variable

names: x1 x2 x3 x4.

If you want to get the data set name from a string variable, the substitution (^)

operator could be used as follows:

dataset = "olsdat";

create f1 = ^dataset with x,4,2;

If you want to get the data set name from a string variable and the variable names

from a character vector, use the following:

dataset = "olsdat";

vnames = { age, pay, sex };

create f1 = ^dataset with ^vnames,0,2;

The general syntax is:

^variable name

Expressions are not allowed.

The following commands are supported with the substitution operator in the current

version.

create f1 = ^dataset with ^vnames,0,2;

create f1 = ^dataset using ^cmdfile;

open f1 = ^dataset;

output file = ^outfile;

load x = ^datafile;

load path = ^lpath x,y,z,t,w;

loadexe buf = ^exefile;

save ^name = x;

save path = ^spath;

dos ^cmdstr;

run ^prog;

msym ^mstring;

109

8. OPERATORS

8.6 Using Dot Operators with Constants

When you use those operators preceded by a . (the dot operators) with a scalar

integer constant, make sure to put a space between the constant and any following dot

operator. Otherwise, the dot will be interpreted as part of the scalar, i.e., the decimal

point, and you may get results other than you expect. For example:

let y = 1 2 3;

x = 2.<y;

will return x as a scalar 0, not a vector of 0s and 1s, because

x = 2.<y;

is interpreted as

x = 2. < y;

not

x = 2 .< y;

Most of the time, it will be the dot relational (.<, .<=, .==, ./=, .>, .>=) operators

that will trip you up. The same problem can occur with other dot operators, though,

too. For example:

let x = 1 1 1;

y = x./2./x;

will return y as a scalar .5 rather than a vector of .5s, because

y = x./2./x;

is interpreted as

y = (x ./ 2.) / x;

not

y = (x ./ 2) ./ x;

The second division, then, is handled as a matrix division rather than an

element-by-element division.

110

P

r

o

c

e

d

u

r

e

s

a

n

d

K

e

y

w

o

r

d

s

Chapter 9

Procedures and Keywords

Procedures are multiple-line, recursive functions that can have either local or global

variables. Procedures allow a large computing task to be written as a collection of

smaller tasks. These smaller tasks are easier to work with and can hide the details of

their operation from the other parts of the program that do not need to know them.

This makes programs easier to understand and easier to maintain.

A procedure in GAUSS is basically a user-dened function that can be used as if it

were an intrinsic part of the language. They can be as small and simple or as large and

complicated as necessary to perform whatever task you need done. Procedures allow

people to build on their previous work and on the work of others rather than starting

over again and again to perform related tasks.

Any intrinsic command or function may be used in a procedure, as well as any

user-dened function or other procedure. Procedures can refer to any global variable

(that is, any variable that is in the main symbol table and that can be shown with the

show command). It is also possible to declare local variables within a procedure. These

variables are known only inside the procedure they are dened in and cannot be

accessed from other procedures or from the main level program code.

All labels and subroutines inside a procedure are local to that procedure and will not

be confused with labels of the same name in other procedures.

9.1 Dening a Procedure

A procedure denition consists of ve parts, four of which are denoted by explicit

GAUSS commands:

111

9. PROCEDURES AND KEYWORDS

1. Procedure declaration proc statement

2. Local variable declaration local statement

3. Body of procedure

4. Return from procedure retp statement

5. End of procedure denition endp statement

There is always one proc statement and one endp statement in a procedure denition.

Any statements that come between these two statements are part of the procedure.

Procedure denitions cannot be nested. local and retp statements are optional. There

can be multiple local and retp statements in a procedure denition. Here is an example

of a procedure denition:

proc (3) = regress(x, y);

local xxi,b,ymxb,sse,sd,t;

xxi = invpd(xx);

b = xxi * (xy);

ymxb = y-xb;

sse = ymxbymxb/(rows(x)-cols(x));

sd = sqrt(diag(sse*xxi));

t = b./sd;

retp(b,sd,t);

endp;

This could be used as a function that takes two matrix arguments and returns three

matrices as a result. An example of how it might be used is:

{ b,sd,t } = regress(x,y);

The ve parts of the procedure denition will now be discussed in more detail:

9.1.1 Procedure Declaration

The proc statement is the procedure declaration statement. The format is as follows:

proc [[(rets) =]] name([[arg1,arg2,...argN]]);

rets Optional constant, number of values returned by the procedure. Acceptable

values here are 0-1023, the default is 1.

name The name of the procedure, up to 32 alphanumeric characters or an underscore,

beginning with an alpha or an underscore.

arg# Names that will be used inside of the procedure for the arguments that are

passed to the procedure when it is called. There can be 0-1023 arguments.

These names will be known only in the procedure being dened. Other

procedures can use the same names, but they will be separate entities.

112

P

r

o

c

e

d

u

r

e

s

a

n

d

K

e

y

w

o

r

d

s

9. PROCEDURES AND KEYWORDS

9.1.2 Local Variable Declarations

The local statement is used to declare local variables. Local variables are variables

known only to the procedure being dened. The names used in the argument list of the

proc statement are always local. The format of the local statement is:

local x,y,f :proc,g:fn,z,h:keyword;

Local variables can be matrices or strings. If :proc, :fn, or :keyword follows the variable

name in the local statement, the compiler will treat the symbol as if it were a

procedure, function, or keyword respectively. This allows passing procedures, functions,

and keywords to other procedures. See Section 9.4.

Variables that are global to the system (that is, variables that are listed in the global

symbol table and can be shown with the show command) can be accessed by any

procedure without any redundant declaration inside of the procedure. If you want to

create variables that are known only to the procedure being dened, the names of these

local variables must be listed in a local statement. Once a variable name is encountered

in a local statement, further references to that name inside of the procedure will be to

the local rather than to a global having the same name. See clearg, varget, and varput

for ways of accessing globals from within procedures that have locals with the same

name.

The local statement does not initialize (set to a value) the local variables. If they are

not passed in as parameters, they must be assigned some value before they are accessed

or the program will terminate with a Variable not initialized error.

All local and global variables are dynamically allocated and sized automatically during

execution. Local variables, including those that were passed as parameters, can change

in size during the execution of the procedure.

Local variables exist only when the procedure is executing and then disappear. Local

variables cannot be listed with the show command.

The maximum number of locals is limited by stack space and the size of workspace

memory. The limiting factor applies to the total number of active local symbols at any

one time during execution. If cat has 10 locals and it calls dog which has 20 locals,

then there are 30 active locals whenever cat is called. See your supplement for the

maximum number of locals allowed in this implementation.

There can be multiple local statements in a procedure. They will aect only the code

in the procedure that follows. Therefore, for example, it is possible to refer to a global

x in a procedure and follow that with a local statement that declares a local x. In that

case all subsequent references to x would be to the local x. This is not good

programming practice, but it demonstrates the principle that the local statement

aects only the code that is physically below it in the procedure denition. Another

example of this is a symbol that is declared as a local and then declared as a local

procedure or function later in the same procedure denition. This allows doing

arithmetic on local function pointers before calling them, see Section 9.5.

113

9. PROCEDURES AND KEYWORDS

9.1.3 Body of Procedure

The body of the procedure can have any GAUSS statements necessary to perform the

task the procedure is being written for. Other user-dened functions and other

procedures can be referenced as well as any global matrices and strings.

GAUSS procedures are recursive, so the procedure can call itself as long as there is

logic in the procedure to prevent an innite recursion. The process would otherwise

terminate with either an Insucient workspace memory message or a Procedure

calls too deep message, depending on the space necessary to store the locals for each

separate invocation of the procedure.

9.1.4 Returning from the Procedure

The return from the procedure is accomplished with the retp statement.

retp;

retp(expression1,expression2,...expressionN);

The retp statement can have multiple arguments. The number of items returned must

coincide with the number of rets in the proc statement.

If the procedure is being dened with no items returned, then the retp statement is

optional. The endp statement which ends the procedure will generate an implicit retp

with no objects returned. If the procedure returns one or more objects, there must be

an explicit retp statement.

There can be multiple retp statements in a procedure, and they can be anywhere inside

the body of the procedure.

9.1.5 End of Procedure Denition

The endp statement marks the end of the procedure denition.

endp;

An implicit retp statement that returns nothing is always generated here so it is

impossible to run o the end of a procedure without returning. If the procedure was

dened to return one or more objects, then executing this implicit return will result in

a Wrong number of returns error message and the program will terminate.

114

P

r

o

c

e

d

u

r

e

s

a

n

d

K

e

y

w

o

r

d

s

9. PROCEDURES AND KEYWORDS

9.2 Calling a Procedure

Procedures are called like this:

dog(i,j,k); /* no returns */

y = cat(i,j,k); /* one return */

{ x,y,z } = bat(i,j,k); /* multiple returns */

call bat(i,j,k); /* ignore any returns */

Procedures are called in the same way that intrinsic functions are called. The

procedure name is followed by a list of arguments in parentheses. The arguments must

be separated by commas.

If there is to be no return value then use:

proc (0) = dog(x,y,z);

when dening the procedure and use:

dog(ak,4,3);

or

call dog(ak,4,3);

when calling it.

The arguments passed to procedures can be complicated expressions involving calls to

other functions and procedures. This calling mechanism is completely general. For

example:

y = dog(cat(3*x,bird(x,y))-2,1);

is legal.

9.3 Keywords

A keyword, like a procedure, is a subroutine that can be called interactively or from

within a GAUSS program. A keyword diers from a procedure in that a keyword

accepts exactly one string argument, and returns nothing. Keywords can perform many

tasks not as easily accomplished with procedures.

115

9. PROCEDURES AND KEYWORDS

9.3.1 Dening a Keyword

A keyword denition is much like a procedure denition. Keywords always are dened

with 0 returns and 1 argument. The beginning of a keyword denition is the keyword

statement.

keyword name(strarg);

name The name of the keyword, up to 32 alphanumeric characters or an underscore,

beginning with an alpha or an underscore.

strarg Name that will be used inside of the keyword for the argument that is passed to

the keyword when it is called. There is always 1 argument. The name is known

only in the keyword being dened. Other keywords can use the same name, but

they will be separate entities. This will always be a string. If the keyword is

called with no characters following the name of the keyword, this will be a null

string.

The rest of the keyword denition is the same as a procedure denition as in Section 9.1

above. Keywords always return nothing. Any retp statements, if used, should be empty.

retp;

9.3.2 Calling a Keyword

When a keyword is called, every character up to the end of the statement, excluding

the leading spaces, is passed to the keyword as one string argument.

keyword what(str);

print "The argument is: " str "";

endp;

The keyword above will print the string argument passed to it. The argument will be

printed enclosed in single quotes. For example if you type:

what is the argument;

The keyword will respond:

The argument is: is the argument

Here is another example:

116

P

r

o

c

e

d

u

r

e

s

a

n

d

K

e

y

w

o

r

d

s

9. PROCEDURES AND KEYWORDS

keyword add(s);

local tok,sum;

sum = 0;

do until s $== "";

{ tok, s } = token(s);

sum = sum + stof(tok);

endo;

format /rd 1,2;

print "Sum is: " sum;

endp;

To use this keyword, type:

add 1 2 3 4 5;

It will respond with:

Sum is: 15.00

9.4 Passing Procedures to Procedures

Procedures and functions can be passed to procedures in the following way:

proc max(x,y); /* procedure to return maximum */

if x>y;

retp(x);

else;

retp(y);

endif;

endp;

proc min(x,y); /* procedure to return minimum */

if x<y;

retp(x);

else;

retp(y);

endif;

endp;

fn lgsqrt(x) = ln(sqrt(x)); /* function to return

:: log of square root

*/

117

9. PROCEDURES AND KEYWORDS

proc myproc(&f1,&f2,x,y);

local f1:proc, f2:fn, z;

z = f1(x,y);

retp(f2(z));

endp;

The procedure myproc takes 4 arguments. The rst is a procedure f1 that has 2

arguments. The second is a function f2 that has one argument. It also has two other

arguments that must be matrices or scalars. In the local statement, f1 is declared to be

a procedure and f2 is declared to be a function. They can be used inside the procedure

in the usual way. f1 will be interpreted as a procedure inside of myproc, and f2 will be

interpreted as a function. The call to myproc is made as follows:

k = myproc(&max,&lgsqrt,5,7); /* log of square root of 7 */

k = myproc(&min,&lgsqrt,5,7); /* log of square root of 5 */

The ampersand (&) in front of the function or procedure name in the call to myproc

causes a pointer to the function or procedure to be passed. No argument list should

follow the name when it is preceded by the ampersand.

Inside of myproc, the symbol that is declared as a procedure in the local statement is

assumed to contain a pointer to a procedure. It can be called exactly like a procedure is

called. It cannot be saved but it can be passed on to another procedure. If it is to be

passed on to another procedure, use the ampersand in the same way.

9.5 Indexing Procedures

This example assumes there are a set of procedures named f1-f5 which are already

dened. A 1x5 vector procvec is dened by horizontally concatenating pointers to these

procedures. A new procedure, g(x,i ) is then dened which will return the value of the

i

th

procedure evaluated at x:

procvec = &f1 ~ &f2 ~ &f3 ~ &f4 ~ &f5;

proc g(x,i);

local f;

f = procvec[i];

local f:proc;

retp( f(x) );

endp;

Notice that the local statement is used twice. The rst time, f is declared to be a local

matrix. After f has been set equal to the i

th

pointer, f is declared to be a procedure

and is called as a procedure in the retp statement.

118

P

r

o

c

e

d

u

r

e

s

a

n

d

K

e

y

w

o

r

d

s

9. PROCEDURES AND KEYWORDS

9.6 Multiple Returns from Procedures

Procedures can return multiple items, up to 1023. The procedure is dened like this

example of a complex inverse:

proc (2) = cminv(xr,xi); /* (2) specifies number of

:: return values

*/

local ixy, zr, zi;

ixy = inv(xr)*xi;

zr = inv(xr+xi*ixy); /* real part of inverse. */

zi = -ixy*zr; /* imaginary part of inverse. */

retp(zr,zi); /* return: real part, imaginary part */

endp;

It can then be called like this:

{ zr,zi } = cminv(xr,xi);

To make the assignment, the list of targets must be enclosed in braces.

Also, a procedure that returns more than one argument can be used as input to

another procedure or function that takes more than one argument:

proc (2) = cminv(xr,xi);

local ixy, zr, zi;

ixy = inv(xr)*xi;

zr = inv(xr+xi*ixy); /* real part of inverse. */

zi = -ixy*zr; /* imaginary part of inverse. */

retp(zr,zi);

endp;

proc (2) = cmmult(xr,xi,yr,yi);

local zr,zi;

zr = xr*yr-xi*yi;

zi = xr*yi+xi*yr;

retp(zr,zi);

endp;

{ zr,zi } = cminv( cmmult(xr,xi,yr,yi) );

The two returned matrices from cmmult() are passed directly to cminv() in the

statement above. This is equivalent to the following statements:

{ tr,ti } = cmmult(xr,xi,yr,yi);

{ zr,zi } = cminv(tr,ti);

119

9. PROCEDURES AND KEYWORDS

This is completely general so the following program is legal:

proc (2) = cmcplx(x);

local r,c;

r = rows(x);

c = cols(x);

retp(x,zeros(r,c));

endp;

proc (2) = cminv(xr,xi);

local ixy, zr, zi;

ixy = inv(xr)*xi;

zr = inv(xr+xi*ixy); /* real part of inverse. */

zi = -ixy*zr; /* imaginary part of inverse. */

retp(zr,zi);

endp;

proc (2) = cmmult(xr,xi,yr,yi);

local zr,zi;

zr = xr*yr-xi*yi;

zi = xr*yi+xi*yr;

retp(zr,zi);

endp;

{ xr,xi } = cmcplx(rndn(3,3));

{ yr,yi } = cmcplx(rndn(3,3));

{ zr,zi } = cmmult( cminv(xr,xi),cminv(yr,yi) );

{ qr,qi } = cmmult( yr,yi,cminv(yr,yi) );

{ wr,wi } = cmmult(yr,yi,cminv(cmmult(cminv(xr,xi),yr,yi)));

120

L

i

b

r

a

r

i

e

s

Chapter 10

Libraries

The GAUSS library system allows for the creation and maintenance of modular

programs. The user can create libraries of frequently used functions that the GAUSS

system will automatically nd and compile whenever they are referenced in a program.

10.1 Autoloader

The autoloader resolves references to procedures, keywords, matrices, and strings that

are not dened in the program from which they are referenced. The autoloader

automatically locates and compiles the les containing the symbol denitions that are

not resolved during the compilation of the main le. The search path used by the

autoloader is rst the current directory, and then the paths listed in the src path

conguration variable in the order they appear. src path can be dened in the GAUSS

conguration le.

10.1.1 Forward References

When the compiler encounters a symbol that has not previously been dened, that is

called a forward reference. GAUSS handles forward references in two ways, depending

on whether they are left-hand side or right-hand side references.

Left-Hand Side

A left-hand side reference is usually a reference to a symbol on the left-hand side of the

equal sign in an expression.

121

10. LIBRARIES

x = 5;

Left-hand side references, since they are assignments, are assumed to be matrices. In

the statement above, x is assumed to be a matrix and the code is compiled accordingly.

If, at execution time, the expression actually returns a string, the assignment is made

and the type of the symbol x is forced to string.

Some commands are implicit left-hand side assignments. There is an implicit left-hand

side reference to x in each statement below:

clear x;

load x;

open x = myfile;

Right-Hand Side

A right-hand side reference is usually a reference to a symbol on the right-hand side of

the equal sign in an expression.

z = 6;

y = z + dog;

print y;

In the program above, since dog is not previously known to the compiler, the

autoloader will search for it in the active libraries. If it is found, the le containing it

will be compiled. If it is not found in a library, the autoload/autodelete state will

determine how it is handled.

10.1.2 The Autoloader Search Path

If the autoloader is OFF, no forward references are allowed. Every procedure, matrix,

and string referenced by your program must be dened before it is referenced. An

external statement can be used above the rst reference to a symbol, but the denition

of the symbol must be in the main le or in one of the les that are #included. No

global symbols are automatically deleted.

If the autoloader is ON, GAUSS searches for unresolved symbol references during

compilation using a specic search path as outlined below. If the autoloader is OFF, an

Undened symbol error will result for right-hand side references to unknown symbols.

When autoload is ON, the autodelete state controls the handling of references to

unknown symbols. The following search path will be followed to locate any symbols not

previously dened:

122

L

i

b

r

a

r

i

e

s

10. LIBRARIES

Autodelete ON

1. user library

2. User-specied libraries.

3. gauss library

4. Current directory, then src path for les with a .g extension.

Forward references are allowed and .g les need not be in a library. If there are symbols

that cannot be found in any of the places listed above, an Undened symbol error will

be generated and all uninitialized variables and all procedures with global references

will be deleted from the global symbol table. This autodeletion process is transparent

to the user, since the symbols are automatically located by the autoloader the next

time the program is run. This process results in more compile time, which may or may

not be signicant, depending on the speed of the computer and the size of the program.

Autodelete OFF

1. user library

2. User-specied libraries.

3. gauss library

All .g les must be listed in a library. Forward references to symbols that are not listed

in an active library are not allowed. For example:

x = rndn(10,10);

y = sym(x); /* Forward reference to sym */

proc sym(x);

retp(x+x);

endp;

Use an external statement for anything referenced above its denition if autodelete is

OFF.

external proc sym;

x = rndn(10,10);

y = sym(x);

proc sym(x);

retp(x+x);

endp;

When autodelete is OFF, symbols not found in an active library will not be added to

the symbol table. This prevents the creation of uninitialized procedures in the global

symbol table. No deletion of symbols from the global symbol table will take place.

123

10. LIBRARIES

Libraries

The rst place GAUSS looks for a symbol denition is in the active libraries. A

GAUSS library is a text le that serves as a dictionary to the source les that contain

the symbol denitions. When a library is active, GAUSS will look in it whenever it is

looking for a symbol it is trying to resolve. The library statement is used to make a

library active. Library les should be located in the subdirectory listed in the lib path

conguration variable. Library les have a .lcg extension.

Suppose you have several procedures that are all related and you would like to have

them all dened in the same le. You can create such a le, and, with the help of a

library, the autoloader will be able to nd the procedures dened in that le whenever

they are called.

First, create the le that is to contain your desired procedure denitions. By

convention, we usually name these les with an .src extension, but you can use any

name and any le extension you wish. In that le, put all the denitions of related

procedures you wish to use. Here is an example of such a le. It is called norm.src.

/*

** norm.src

**

** This is a file containing the definitions of three

** procedures which return the norm of a matrix x.

** The three norms calculated are the 1-norm, the

** inf-norm and the E-norm.

*/

proc onenorm(x);

retp(maxc(sumc(abs(x))));

endp;

proc infnorm(x);

retp(maxc(sumc(abs(x))));

endp;

proc Enorm(x);

retp(sumc(sumc(x.*x)));

endp;

Next, create a library le that contains the name of the le you want access to, and the

list of symbols dened in it. This can be done with the lib command. See lib in the

COMMAND REFERENCE.

A library le entry has a lename that is ush left. The drive and path can be included

to speed up the autoloader. Indented below the lename are the symbols included in

124

L

i

b

r

a

r

i

e

s

10. LIBRARIES

the le. There can be multiple symbols listed on a line with spaces between. The

symbol type follows the symbol name with a colon delimiting it from the symbol name.

The valid symbol types are:

fn user-dened single line function.

keyword keyword.

proc procedure.

matrix matrix, numeric or character.

string string.

If the symbol type is missing, the colon must not be present and the symbol type is

assumed to be proc. Both library les below are valid.

125

10. LIBRARIES

/*

** math

**

** This library lists files and procedures for mathematical routines.

*/

norm.src

onenorm:proc infnorm:proc Enorm:proc

complex.src

cmmult:proc cmdiv:proc cmadd:proc cmsoln:proc

poly.src

polychar:proc polyroot:proc polymult:proc

/*

** math

**

** This library lists files and procedures for mathematical routines.

*/

c:\gauss\src\norm.src

onenorm : proc

infnorm : proc

Enorm : proc

c:\gauss\src\complex.src

cmmult : proc

cmdiv : proc

cmadd : proc

cmsoln : proc

c:\gauss\src\fcomp.src

feq : proc

fne : proc

flt : proc

fgt : proc

fle : proc

fge : proc

c:\gauss\src\fcomp.dec

_fcmptol : matrix

Once the autoloader nds, via the library, the le containing your procedure denition,

everything in that le will be compiled. For this reason, you will probably want to

combine related procedures in the same le to minimize the compiling of procedures

not needed by your program. In other words, do not combine unrelated functions in

one .src le because if one function in an .src le is needed, the whole le will be

compiled. This does not apply to library (.lcg) les.

126

L

i

b

r

a

r

i

e

s

10. LIBRARIES

user Library

This is a library for user-created procedures. If the autoloader is ON, the user library is

the rst place GAUSS looks when trying to resolve symbol references.

You can update the user library with the lib command as follows:

lib user myfile.src

This will update the user library by adding a reference to myfile.src.

No user library is shipped with GAUSS. It will be created the rst time you use the lib

command to update it.

See the COMMAND REFERENCE for a detailed discussion of the parameters

available with the lib command.

G Files

If autoload and autodelete are ON and a symbol is not found in a library, the

autoloader will assume it is a procedure and look for a le that has the same name as

the symbol and a .g extension. For example, if you have dened a procedure called

square, you could put the denition in a le called square.g on one of the

subdirectories listed in your src path. If autodelete is OFF, the .g le needs to be

listed in an active library, for example, in the user library. See user Library above.

10.2 Global Declaration Files

If your application makes use of several global variables, you will probably want to

create a le containing declare statements. In our code, we use les with the extension

.dec to assign default values to global matrices and strings with declare statements. A

le with an .ext extension containing the same symbols in external statements can

also be created and #included at the top of any le that references these global

variables. An appropriate library le should contain the name of the .dec les and the

names of the globals they declare. The example below demonstrates more specically

how these les work together.

Here is an example that illustrates the way in which .dec, .ext, .lcg and .src les

work together. We always begin the names of global matrices or strings with to

distinguish them easily from procedures.

127

10. LIBRARIES

/*

** fcomp.src

**

** These functions use _fcmptol to fuzz the comparison operations

** to allow for roundoff error.

**

** The statement: y = feq(a,b);

**

** is equivalent to: y = a eq b;

**

** Returns a scalar result, 1 (true) or 0 (false)

**

** y = feq(a,b);

** y = fne(a,b);

*/

#include fcomp.ext;

proc feq(a,b);

retp(abs(a-b) <= _fcmptol);

endp;

proc fne(a,b);

retp(abs(a-b) > _fcmptol);

endp;

/*

** fcomp.dec - global declaration file for fuzzy comparisons.

*/

declare matrix _fcmptol != 1e-14;

/*

** fcomp.ext - external declaration file for fuzzy comparisons.

*/

external matrix _fcmptol;

/*

** fcomp.lcg - fuzzy compare library

128

L

i

b

r

a

r

i

e

s

10. LIBRARIES

*/

fcomp.dec

_fcmptol:matrix

fcomp.src

feq:proc

fne:proc

With the exception of the library (.lcg) les, these les must be located along your

src path. The library les must be on your lib path. With these les in place, the

autoloader will be able to nd everything needed to run the following programs:

library fcomp;

x = rndn(3,3);

xi = inv(x);

xix = xi*x;

if feq(xix,eye(3));

print "Inverse within tolerance.";

else;

print "Inverse not within tolerance.";

endif;

If the default tolerance of 1e 14 is too tight, the tolerance could be relaxed.

library fcomp;

x = rndn(3,3);

xi = inv(x);

xix = xi*x;

_fcmptol = 1e-12; /* reset tolerance */

if feq(xix,eye(3));

print "Inverse within tolerance.";

else;

print "Inverse not within tolerance.";

endif;

10.3 Troubleshooting

Below is a partial list of errors you may encounter in using the library system, followed

by the most probable cause of these errors.

(4) : error G0290 : /gauss/lib/prt.lcg : Library not found

The autoloader is looking for a library le called tt prt.lcg, because it has been

activated in a library statement. Check the subdirectory listed in your lib path

conguration variable for a le called prt.lcg.

129

10. LIBRARIES

(0) : error G0292 : prt.dec : File listed in library not found

The autoloader cant nd a le called prt.dec. Check for this le. It should exist

somewhere along your src path, if you have it listed in prt.lcg.

Undefined symbols:

PRTVEC /gauss/src/tstprt.g(2)

The symbol prtvec could not be found. Check if the le containing prtvec is in the

src path. You may have not activated the library which contains your symbol

denition. Activate the library in a library statement.

/gauss/src/prt.dec(3) : Redefinition of __vnames

(proc)__vnames being declared external matrix

You are trying to illegally force a symbol to another type. You probably have a name

conict that needs to be resolved by renaming one of the symbols.

/gauss/lib/prt.lcg(5) : error G0301 : prt.dec : Syntax error in library

Undefined symbols:

__VNAMES /gauss/src/prt.src(6)

Check your library to see that all lenames are ush left and that all the symbols

dened in that le are indented by at least one space.

10.3.1 Using dec Files

Below is some advice you are encouraged to follow when constructing your own library

system:

Whenever possible, declare variables in a le that contains only declare

statements. When your program is run again without clearing the workspace,

the le containing the variable declarations will not be compiled and declare

warnings will be prevented.

Provide a function containing regular assignment statements to reinitialize the

global variables in your program if they ever need to be reinitialized on the y or

between runs. Put this in a separate le from the declarations.

proc (0) = globset;

_vname = "X";

_con = 1;

_row = 0;

_title = "";

endp;

130

L

i

b

r

a

r

i

e

s

10. LIBRARIES

Never declare any global in more than one le.

Never declare a global more than once in any one le. A global should only be

declared ONCE. By observing this advice, you will avoid meaningless

redenition errors and declare warnings. Redenition error messages and

declare warnings are meant to help you prevent name conicts, and will be

useless to you if your code generates them normally.

The point of the above is to make sure that any declare warnings and redenition

errors you get are meaningful . By knowing that such warnings and errors are

signicant, you will be able to debug your programs more eciently.

131

10. LIBRARIES

132

C

o

m

p

i

l

e

r

Chapter 11

Compiler

GAUSS allows you to compile your large frequently used programs to a le that can be

run over and over with no compile time. The compiled image is usually smaller than

the uncompiled source. This is not a native code compiler; rather, it compiles to a form

of pseudo-code. The le will have a .gcg extension.

The compile command will compile an entire program to a compiled le, or a le can

be compiled directly from the GAUSS editor. An attempt to edit a compiled le will

cause the source code to be loaded into the editor if it is available to the system. The

run command assumes a compiled le if no extension is given and a le with a .gcg

extension is in the src path. A saveall command is available to save the current

contents of memory in a compiled le for instant recall later. The use command will

instantly load a compiled program or set of procedures at the beginning of an ASCII

program before compiling the rest of the ASCII program le.

Since the compiled les are encoded binary les, the compiler is useful for developers

who do not want to distribute their source code.

11.1 Compiling Programs

Programs can be compiled with the compile command or directly from the GAUSS

editor.

11.1.1 Compiling a File

Source code program les that can be run with the run command can be compiled to

.gcg les with the compile command.

133

11. COMPILER

compile qxy.e;

All procedures, global matrices and strings, and the main program segment will be

saved in the compiled le. The compiled le can be run later using the run command.

Any libraries used in the program will need to be present and active during the

compile, but will not need to be present or active when the program is run. If the

program uses the loadexe command, the .rex les will need to be present when the

program is run and the loadexe path will need to be set to the correct subdirectory.

This will usually be automatically handled in your startup le, but should be kept in

mind if the program is run on a dierent computer than it was compiled on.

11.1.2 Compiling from EDIT Mode, DOS Only

Press Alt-X,C to get the Compile Options menu. The compile to le mode (among

other things) can be set here. There are four compile modes:

OFF the compiled program is not saved when the program is executed (default).

ONCE the compiled program is saved when the program is executed and the

compile mode is toggled to OFF.

ON the compiled program will be saved when the program is executed.

ONLY the program will be compiled and saved, but it will not be executed.

Press Alt-X,R to get the Run Options menu. From here, you can select whether to

compile the program with or without line number records. A program compiled with

line number records will be a little slower and 10-20% larger than it would be if

compiled without line number records.

When you run the program by pressing F2 or Alt-X,X, a compiled version of the

program will be saved on the same subdirectory the source is located on.

If you use the compile ON or ONLY option, dont forget to turn it o or you will be

creating lots of compiled les you dont want.

11.2 Saving the Current Workspace

The simplest way to create a compiled le containing a set of frequently used

procedures is to use saveall and an external statement.

library pgraph;

external proc xy,logx,logy,loglog,hist;

saveall pgraph;

134

C

o

m

p

i

l

e

r

11. COMPILER

Just list the procedures you will be using in an external statement and follow it with a

saveall statement. You do not need to list procedures that you do not explicitly call

but are called from another procedure because the autoloader will nd them

automatically before the saveall command is executed. You also do not need to be

exhaustive in listing every procedure you will be calling unless the source will not be

available when the compiled le is used.

Remember that the list of active libraries is NOT saved in the compiled le so you may

still need a library statement in a program that is useing a compiled le.

11.3 Debugging

If you are using compiled code in a development situation where debugging is

important, you should compile the le with line number records. After the development

is over you can recompile without line number records if the maximum possible

execution speed is important. If you want to guarantee that all procedures contain line

number records, put a new statement at the top of your program and turn line number

tracking on.

135

11. COMPILER

136

F

i

l

e

I

/

O

Chapter 12

File I/O

Following is a partial list of the I/O commands in the GAUSS programming language.

close close a le.

closeall close all open les.

colsf number of columns in a le.

create create GAUSS data set.

dfree space remaining on disk.

eof test for end of le.

fcheckerr check error status of a le.

fclearerr check error status of a le and clear error ag.

ush ush a les output buer.

fgets read a line of text from a le.

fgetsa read multiple lines of text from a le.

fgetsat read multiple lines of text from a le, discarding newlines.

fgetst read a line of text from a le, discarding newline.

leinfo returns names and info of les matching a specication.

les returns a list of les matching a specication.

lesa returns a list of les matching a specication.

fopen open a le.

fputs write strings to a le.

fputst write strings to a le, appending newlines.

fseek reposition le pointer.

fstrerror get explanation of last le I/O error.

ftell get position of le pointer.

getf load a le into a string.

getname get variable names from data set.

137

12. FILE I/O

iscplxf returns whether a data set is real or complex.

load load matrix le or small ASCII le (same as loadm).

loadd load a small GAUSS data set into a matrix.

loadm load matrix le or small ASCII le.

loads load string le.

open open a GAUSS data set.

output control printing to an auxiliary output le or device.

readr read a specied number of rows from a le.

rowsf number of rows in le.

save save matrices, strings, procedures.

saved save a matrix in a GAUSS data set.

seekr reset read/write pointer in a data set.

sortd sort a data set.

typef get type of data set (bytes per element).

writer write data to a data set.

12.1 ASCII Files

GAUSS has facilities for reading and writing ASCII les. Most other software can also

read and write ASCII les so this provides a way of sharing data between GAUSS and

many other kinds of programs.

12.1.1 Matrix Data

Reading

Files containing numeric data that are delimited with spaces or commas and are small

enough to t into a single matrix or string can be read with load. Larger ASCII data

les can be converted to GAUSS data sets with the atog utility program which is

documented in the UTILITIES section of this manual. atog can convert packed ASCII

les as well as delimited les.

For small delimited data les, the load statement can be used to load the data directly

into a GAUSS matrix. The limit here is that the resulting GAUSS matrix must be no

larger than the limit for a single matrix.

load x[] = dat1.asc;

This will load the data in the le dat1.asc into an Nx1 matrix x. This is the preferred

method because rows(x) can be used to determine how many elements were actually

loaded and the matrix can be reshaped to the desired form.

138

F

i

l

e

I

/

O

12. FILE I/O

load x[] = dat1.asc;

if rows(x) eq 500;

x = reshape(x,100,5);

else;

errorlog "Read Error";

end;

endif;

For quick interactive loading without error checking you can use:

load x[100,5] = dat1.asc;

This will load the data into a 100x5 matrix. If there are more or fewer than 500

numbers in the data set, the matrix will be automatically reshaped to 100x5.

Writing Using Auxiliary Output

To write data to an ASCII le the print or printfm commands are used to print to the

auxiliary output. The resulting les are standard ASCII les, and can be edited with

GAUSSs editor or another text editor.

The output and outwidth commands are used to control the auxiliary output. print or

printfm commands are used to control what is sent to the output le.

The screen can be turned on and o using screen. When printing a large amount of

data to the auxiliary output, the screen can be turned o using the command:

screen off;

This will speed things up considerably, especially if the auxiliary output is a disk le.

It is easy to forget to turn the screen on again, and you may think your computer is

broken. It is therefore good practice to use the end statement to terminate your

programs. end will automatically perform screen on and output o.

The following commands can be used to control printing to the auxiliary output:

format controls format for printing a matrix.

output open, close, rename auxiliary output le or device.

outwidth auxiliary output width.

printfm formatted matrix print.

print print matrix or string.

screen Turn printing to the screen on and o.

The following example illustrates printing a matrix to a le:

139

12. FILE I/O

format /rd 8,2;

outwidth 132;

output file = myfile.asc reset;

screen off;

print x;

output off;

screen on;

The numbers in the matrix x will be printed with a eld width of 8 spaces per number,

and with 2 places beyond the decimal point. The resulting le will be an ASCII data

le. It will have 132 column lines maximum.

A more extended example is given below. This program will write the contents of the

GAUSS le mydata.dat into an ASCII le called mydata.asc. If there were an existing

le by the name of mydata.asc, it would be overwritten:

output file = mydata.asc reset;

screen off;

format /rd 1,8;

open fp = mydata;

do until eof(fp);

print readr(fp,200);;

endo;

fp = close(fp);

end;

The output ... reset command will create an auxiliary output le called mydata.asc to

receive the output. The screen is turned o to speed up the process. The GAUSS data

le mydata.dat is opened for read and 200 rows will be read per iteration until the end

of the le is reached. The data that are read will be printed to the auxiliary output

mydata.asc only, because the screen is o.

12.1.2 General File I/O

getf will read a le and return it in a string variable. Any kind of le can be read in

this way as long as it will t into a single string variable.

To read les sequentially, use fopen to open the le and use fgets, fputs and associated

functions to read and write the le. The current position in a le can be determined

with ftell. The procedure below uses these functions to copy an ASCII text le.

proc copy(src, dest);

local fin, fout, str;

140

F

i

l

e

I

/

O

12. FILE I/O

fin = fopen(src, "rb");

if not fin;

retp(1);

endif;

fout = fopen(dest, "wb");

if not fin;

call close(fin);

retp(2);

endif;

do until eof(fin);

str = fgets(fin, 1024);

if fputs(fout, str) /= 1;

call close(fin);

call close(fout);

retp(3);

endif;

endo;

call close(fin);

call close(fout);

retp(0);

endp;

12.2 Data Sets

GAUSS data sets are the preferred method of storing data for use within GAUSS. Use

of these data sets allows extremely fast reading and writing of data. Many library

functions are designed to read data from these data sets.

12.2.1 Layout

GAUSS data sets are arranged as matrices. That is, they are organized in terms of

rows and columns. The columns in a data le are assigned names, and these names are

stored in the header, or in the case of the v89 format, in a separate header le.

The limit on the number of rows in a GAUSS data set is determined by disk size. The

limit on the number of columns is listed in your supplement. Data can be stored in 2,

4, or 8 bytes per number, rather than just 8 bytes as in the case of GAUSS matrix les.

141

12. FILE I/O

The ranges of the dierent formats is as follows:

Bytes Type Significant Range

Digits

2 integer 4 32768 <= X <= 32767

4 single 6 7 8.43E 37 <= [X[ <= 3.37E +38

8 double 15 16 4.19E 307 <= [X[ <= 1.67E +308

12.2.2 Creating Data Sets

Data sets can be created with the create command. The names of the columns, the

type of data, etc., can be specied. See create in the COMMAND REFERENCE for

complete details.

Data sets, unlike matrices, cannot change from real to complex or vice-versa. Data sets

are always stored a row at a time. The rows of a complex data set, then, have the real

and imaginary parts interleaved, element by element. For this reason, you cannot write

rows from a complex matrix to a real data setthere is no way to interleave the data

without rewriting the whole data set. If you need to do so, explicitly convert the rows

of data rst using the real and imag functions (see the COMMAND REFERENCE),

then write them to the data set. Rows from a real matrix CAN be written to a complex

data set; GAUSS simply supplies 0s for the imaginary part.

To create a complex data set, include the complex ag in your create command.

12.2.3 Reading and Writing

The basic functions in GAUSS for reading data les are open and readr:

open f1 = dat1;

x = readr(f1,100);

The readr function here will read in 100 rows from dat1.dat. The data will be

assigned to a matrix x.

loadd and saved can be used for loading and saving small data sets.

The following code illustrates the creation of a GAUSS data le by merging

(horizontally concatenating) two existing data sets:

file1 = "dat1";

file2 = "dat2";

142

F

i

l

e

I

/

O

12. FILE I/O

outfile = "daty";

open fin1 = ^file1 for read;

open fin2 = ^file2 for read;

varnames = getname(file1)|getname(file2);

otyp = maxc(typef(fin1)|typef(fin2));

create fout = ^outfile with ^varnames,0,otyp;

nr = 400;

do until eof(fin1) or eof(fin2);

y1 = readr(fin1,nr);

y2 = readr(fin2,nr);

r = maxc(rows(y1)|rows(y2));

y = y1[1:r,.] ~ y2[1:r,.];

call writer(fout,y);

endo;

closeall fin1,fin2,fout;

In this example, data sets dat1.dat and dat2.dat are opened for reading. The

variable names from each data set are read using getname and combined in a single

vector called varnames. A variable called otyp is created which will be equal to the

larger of the two data types of the input les. This will insure that the output is not

rounded to less precision than the input les. A new data set daty.dat is created using

the create ... with ... command. Then, on every iteration of the loop, 400 rows are

read in from each of the two input data sets, horizontally concatenated, and written

out to daty.dat. When the end of one of the input les is reached, reading and writing

will stop. The closeall command is used to close all the les.

12.2.4 Distinguishing Character and Numeric Data

Although GAUSS itself does not distinguish between numeric and character columns in

a matrix or data set, some of the GAUSS Application programs do, so it is important

when creating a data set to indicate the type of data in the various columns. The

following discusses two ways of doing this.

Using Type Vectors

The v89 data set format distinguished between character and numeric data in data sets

by the case of the variable names associated with the columns. The v96 data set

format, however, stores this type information separately, resulting in a much cleaner

and more robust method of tracking variable types, and greater freedom in the naming

of data set variables.

When you create a data set, you can supply a vector indicating the type of data in each

column of the data set. For example:

143

12. FILE I/O

data = { M 32 21500,

F 27 36000,

F 28 19500,

M 25 32000 };

vnames = { "Sex" "Age" "Pay" };

vtypes = { 0 1 1 };

create f = mydata with ^vnames, 3, 8, vtypes;

call writer(f,data);

f = close(f);

To retrieve the type vector you use vartypef.

open f = mydata for read;

vn = getnamef(f);

vt = vartypef(f);

print vn;

print vt;

Sex Age Pay

0 1 1

Note that the function getnamef in this example returns a string array rather than a

character vector, so you can print it without the $ prex.

Using the Uppercase/Lowercase Convention

The following method for distinguishing character/numeric data is in the process of

being obsoleted; you should use the approach described above.

To distinguish numeric variables from character variables in GAUSS data sets, some

GAUSS Application programs recognize an uppercase/lowercase convention: if the

variable name is uppercase, the variable is assumed to be numeric, and if it is

lowercase, the variable is assumed to be character. The atog utility program

implements this convention when you use the # and $ operators to toggle between

character and numeric variable names listed in the invar statement and you have

specied nopreservecase.

It should be remembered that GAUSS does not make this distinction internally and it

is up to the program to keep track of and make use of the information recorded in the

case of the variable names in a data set.

When creating a data set using the saved command, this convention can be established

as follows:

144

F

i

l

e

I

/

O

12. FILE I/O

data = { M 32 21500,

F 27 36000,

F 28 19500,

M 25 32000 };

dataset = "mydata";

vnames = { "sex" AGE PAY };

call saved(data,dataset,vnames);

It is necessary to put sex into quotes in order to prevent it from being forced to

uppercase.

The procedure getname can be used to retrieve the variable names:

print $getname("mydata");

The names are:

sex

AGE

PAY

When you are writing or creating a data set (as the above example using saved does)

the case of the variable names is important. This is especially true if the GAUSS

Applications programs will be used on the data set.

12.3 Matrix Files

GAUSS matrix les are les created by the save command.

The save command takes a matrix in memory, adds a header that contains information

on the number of rows and columns in the matrix, and stores it on disk. Numbers are

stored in double precision just as they are in matrices in memory. These les have the

extension .fmt.

Matrix les can be no larger than a single matrix. No variable names are associated

with matrix les.

GAUSS matrix les can be loaded into memory using the load or loadm commands or

they can be opened with the open command and read with the readr command. With

the readr command a subset of the rows can be read. With the load command, the

entire matrix is loaded.

GAUSS matrix les can be opened for read, but not for append, or for update.

If a matrix le has been opened and assigned a le handle, rowsf and colsf can be used

to determine how many rows and columns it has without actually reading it into

memory. seekr and readr can be used to jump to particular rows and to read them into

memory. This can be useful when only a subset of rows is needed at any time. This

procedure will save memory and can be much faster than loading the entire matrix

into memory.

145

12. FILE I/O

12.4 File Formats

This section discusses the GAUSS binary le formats.

There are 4 currently supported matrix le formats:

Version Extension Support

Small Matrix v89 .fmt Obsolete, read on Intel x86 processors only

Extended Matrix v89 .fmt Obsolete, read on Intel only

Matrix v92 .fmt Obsolete, read on Unix only

Universal Matrix v96 .fmt Supported for read/write

There are 4 currently supported string le formats:

Version Extension Support

Small String v89 .fst Obsolete, read on Intel x86 processors only

Extended String v89 .fst Obsolete, read on Intel only

String v92 .fst Obsolete, read on Unix only

Universal String v96 .fst Supported for read/write

There are 4 currently supported data set formats:

Version Extension Support

Small Data Set v89 .dat, .dht Obsolete, read on Intel x86 processors only

Extended Data Set v89 .dat, .dht Obsolete, read on Intel only

Data Set v92 .dat Obsolete, read on Unix only

Universal Data Set v96 .dat Supported for read/write

12.4.1 Small Matrix v89

Matrix les are binary les, and cannot be read with a text editor. They are created

with save. Matrix les have a .fmt extension and a 16-byte header formatted as

follows:

oset description

0-1 DDDD hex, identication ag

2-3 rows, unsigned 2-byte integer

4-5 columns, unsigned 2-byte integer

6-7 size of le minus 16-byte header, unsigned 2-byte integer

8-9 type of le, 0086 hex for real matrices, 8086 hex for complex matrices

10-15 reserved, all 0s

146

F

i

l

e

I

/

O

12. FILE I/O

The body of the le starts at oset 16 and consists of IEEE format double precision

oating point numbers or character elements of up to 8 characters. Character elements

take up 8 bytes and are padded on the right with zeros. The size of the body of the le

is 8*rows*cols rounded up to the next 16-byte paragraph boundary. Numbers are

stored row by row. A 2x3 real matrix will be stored on disk in the following way from

the lowest addressed element to the highest addressed element:

[1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]

For complex matrices, the size of the body of the le is 16*rows*cols. The entire real

part of the matrix is stored rst, then the entire imaginary part. A 2x3 complex matrix

will be stored on disk in the following way from the lowest addressed element to the

highest addressed element:

(real part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]

(imaginary part) [1, 1] [1, 2] [1, 3] [2, 1] [2, 2] [2, 3]

12.4.2 Extended Matrix v89

In older 32-bit versions, matrices with more than 8190 elements were saved in a format

that cannot be read by the 16-bit version. These extended les have a 16-byte header

formatted as follows:

oset description

0-1 EEDD hex, identication ag

2-3 type of le, 0086 hex for real matrices, 8086 hex for complex matrices

4-7 rows, unsigned 4-byte integer

8-11 columns, unsigned 4-byte integer

12-15 size of le minus 16-byte header, unsigned 4-byte integer

The size of the body of an extended matrix le is 8*rows*cols (not rounded up to a

paragraph boundary). Aside from this, the dierences in the le header, and the

number of elements allowed in the le, extended matrix les conform to the matrix le

description specied above.

12.4.3 Small String v89

String les are created with save. String les have a 16-byte header formatted as

follows:

oset description

0-1 DFDF hex, identication ag

2-3 1, unsigned 2-byte integer

4-5 length of string plus null byte, unsigned 2-byte integer

6-7 size of le minus 16-byte header, unsigned 2-byte integer

8-9 001D hex, type of le

10-15 reserved, all 0s

147

12. FILE I/O

The body of the le starts at oset 16. It consists of the string terminated with a null

byte. The size of the le is the 16-byte header plus the length of the string and null

byte rounded up to the next 16-byte paragraph boundary.

12.4.4 Extended String v89

In the 32-bit version, strings with more than 65519 characters are saved in a format

that cannot be read by the 16-bit version. These extended les have a 16-byte header

formatted as follows:

oset description

0-1 EEDF hex, identication ag

2-3 001D hex, type of le

4-7 1, unsigned 4-byte integer

8-11 length of string plus null byte, unsigned 4-byte integer

12-15 size of le minus 16-byte header, unsigned 4-byte integer

The body of the le starts at oset 16. It consists of the string terminated with a null

byte. The size of the le is the 16-byte header plus the length of the string and null

byte rounded up to the next 8-byte boundary.

12.4.5 Small Data Set v89

The .dat le is used with the .dht descriptor le. The format of the .dat le is binary

data. It will be in one of three types:

8-byte IEEE oating point

4-byte IEEE oating point

2-byte signed binary integer, twos complement

Numbers are stored row by row.

The .dht le is used in conjunction with the .dat le as a descriptor le and as a place

to store names for the columns in the .dat le. Its format is as follows:

oset description

0-1 DADA hex, identication ag

2-5 reserved, all 0s

6-7 columns, unsigned 2-byte integer

8-9 row size in bytes, unsigned 2-byte integer

10-11 header size in bytes, unsigned 2-byte integer

12-13 data type in .dat le (2 4 8), unsigned 2-byte integer

14-17 reserved, all 0s

18-21 reserved, all 0s

22-23 control ags, unsigned 2-byte integer

24-127 reserved, all 0s

148

F

i

l

e

I

/

O

12. FILE I/O

Column names begin at oset 128 and are stored 8 bytes each in ASCII format. Names

with less than 8 characters are padded on the right with bytes of 0.

The number of rows in the .dat le is calculated in GAUSS using the le size, columns,

and data type. This means that users can modify the .dat le by adding or deleting

rows with other software without updating the header information.

Names for the columns should be lowercase for character data if you want to be able to

distinguish them from numeric data with vartype.

GAUSS currently examines only the 4s bit of the control ags. This bit is set to 0 for

real data sets, 1 for complex data sets. All other bits are 0.

Data sets are always stored a row at a time. A real data set with 2 rows and 3 columns

(not an overlarge data set!) will be stored on disk in the following way from the lowest

addressed element to the highest addressed element:

[1, 1] [1, 2] [1, 3]

[2, 1] [2, 2] [2, 3]

The rows of a complex data set are stored with the real and imaginary parts

interleaved, element by element. A 2x3 complex data set, then, will be stored on disk in

the following way from the lowest addressed element to the highest addressed element:

[1, 1]r [1, 1]i [1, 2]r [1, 2]i [1, 3]r [1, 3]i

[2, 1]r [2, 1]i [2, 2]r [2, 2]i [2, 3]r [2, 3]i

12.4.6 Extended Data Set v89

In the 32-bit version, data sets with more than 8175 columns are saved in a format that

cannot be read by the 16-bit version. These extended les have a .dht descriptor le

formatted as follows:

oset description

0-1 EEDA hex, identication ag

2-3 data type in .dat le (2 4 8), unsigned 2-byte integer

4-7 reserved, all 0s

8-11 columns, unsigned 4-byte integer

12-15 row size in bytes, unsigned 4-byte integer

16-19 header size in bytes, unsigned 4-byte integer

20-23 reserved, all 0s

24-27 reserved, all 0s

28-29 control ags, unsigned 2-byte integer

30-127 reserved, all 0s

Aside from the dierences in the descriptor le and the number of columns allowed in

the data le, extended data sets conform to the v89 data set description specied above.

149

12. FILE I/O

12.4.7 Matrix v92

oset description

0-3 always 0

4-7 always 0xEECDCDCD

8-11 reserved

12-15 reserved

16-19 reserved

20-23 0 - real matrix, 1 - complex matrix

24-27 number of dimensions

0 - scalar

1 - row vector

2 - column vector, matrix

28-31 header size, 128 + number of dimensions

* 4, padded to 8-byte boundary

32-127 reserved

If the data is a scalar, the data will directly follow the header.

If the data is a row vector, an unsigned integer equaling the number of columns in the

vector will precede the data, along with 4 padding bytes.

If the data is a column vector or a matrix, there will be two unsigned integers preceding

the data. The rst will represent the number of rows in the matrix and the second will

represent the number of columns.

The data area always begins on an even 8-byte boundary. Numbers are stored in

double precision (8 bytes per element, 16 if complex). For complex matrices, all of the

real parts are stored rst, followed by all imaginary parts.

12.4.8 String v92

oset description

0-3 always 0

4-7 always 0xEECFCFCF

8-11 reserved

12-15 reserved

16-19 reserved

20-23 size of string in units of eight bytes

24-27 length of string plus null terminator in bytes

28-127 reserved

The size of the data area is always divisible by 8, and is padded with nulls if the length

of the string is not evenly divisible by 8. If the length of the string is evenly divisible by

8 the data area will be the length of the string plus 8. The data area follows

immediately after the 128-byte header.

150

F

i

l

e

I

/

O

12. FILE I/O

12.4.9 Data Set v92

oset description

0-3 always 0

4-7 always 0xEECACACA

8-11 reserved

12-15 reserved

16-19 reserved

20-23 rows in data set

24-27 columns in data set

28-31 0 for real data set, 1 for complex data set

32-35 type of data in data set, 2, 4, or 8

36-39 header size in bytes is 128 + columns * 9

40-127 reserved

The variable names begin at oset 128 and are stored 8 bytes each in ASCII format.

Each name corresponds to one column of data. Names less than 8 characters are

padded on the right with bytes of zero.

The variable type ags immediately follow the variable names. They are 1-byte binary

integers, one per column, padded to an even 8-byte boundary. A 1 indicates a numeric

variable and a 0 indicates a character variable.

The contents of the data set follow the header and start on an 8-byte boundary. Data is

either 2-byte signed integer, 4-byte single precision oating point or 8-byte double

precision oating point.

151

12. FILE I/O

12.4.10 Matrix v96

oset description

0-3 always 0xFFFFFFFF

4-7 always 0

8-11 always 0xFFFFFFFF

12-15 always 0

16-19 always 0xFFFFFFFF

20-23 0xFFFFFFFF for forward byte order, 0 for backward byte order

24-27 0xFFFFFFFF for forward bit order, 0 for backward bit order

28-31 always 0xABCDEF01

32-35 currently 1

36-39 reserved

40-43 oating point type, 1 for IEEE 754

44-47 1008 (double precision data)

48-51 8, the size in bytes of a double matrix

52-55 0 for real matrix, 1 for complex matrix

56-59 1 - imaginary part of matrix follows real part (standard GAUSS style)

2 - imaginary part of each element immediately follows real part

(FORTRAN style)

60-63 number of dimensions

0 scalar

1 row vector

2 column vector or matrix

64-67 1 for row major ordering of elements, 2 for column major

68-71 always 0

72-75 header size, 128 + dimensions * 4, padded to 8-byte boundary

76-127 reserved

If the data is a scalar, the data will directly follow the header.

If the data is a row vector, an unsigned integer equaling the number of columns in the

vector will precede the data, along with 4 padding bytes.

If the data is a column vector or a matrix, there will be two unsigned integers preceding

the data. The rst will represent the number of rows in the matrix and the second will

represent the number of columns.

The data area always begins on an even 8-byte boundary. Numbers are stored in

double precision (8 bytes per element, 16 if complex). For complex matrices, all of the

real parts are stored rst, followed by all the imaginary parts.

152

F

i

l

e

I

/

O

12. FILE I/O

12.4.11 Data Set v96

oset description

0-3 always 0xFFFFFFFF

4-7 always 0

8-11 always 0xFFFFFFFF

12-15 always 0

16-19 always 0xFFFFFFFF

20-23 0xFFFFFFFF for forward byte order, 0 for backward byte order

24-27 0xFFFFFFFF for forward bit order, 0 for backward bit order

28-31 0xABCDEF02

32-35 version, currently 1

36-39 reserved

40-43 oating point type, 1 for IEEE 754

44-47 12 for signed 2-byte integer

1004 for single precision oating point

1008 for double precision oat

48-51 2, 4, or 8, the size of an element in bytes

52-55 0 for real matrix, 1 for complex matrix

56-59 1 - imaginary part of matrix follows real part (standard GAUSS style)

2 - imaginary part of each element immediately follows real part

(FORTRAN style)

60-63 always 2

64-67 1 for row major ordering of elements, 2 for column major

68-71 always 0

72-75 header size, 128 + columns * 33, padded to 8-byte boundary

76-79 reserved

80-83 rows in data set

84-87 columns in data set

88-127 reserved

The variable names begin at oset 128 and are stored 32 bytes each in ASCII format.

Each name corresponds to one column of data. Names less than 32 characters are

padded on the right with bytes of zero.

The variable type ags immediately follow the variable names. They are 1-byte binary

integers, one per column, padded to an even 8-byte boundary. A 1 indicates a numeric

variable and a 0 indicates a character variable.

Contents of the data set follow the header and start on an 8-byte boundary. Data is

either 2-byte signed integer, 4-byte single precision oating point or 8-byte double

precision oating point.

153

12. FILE I/O

154

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

Chapter 13

Data Transformations

GAUSS allows expressions that directly reference variables (columns) of a data set.

This is done within the context of a data loop.

dataloop infile outfile;

drop wagefac wqlec shordelt foobly;

csed = ln(sqrt(csed));

select csed > 0.35 and married $== "y";

make chfac = hcfac + wcfac;

keep csed chfac stid recsum voom;

endata;

GAUSS translates the data loop into a procedure that does the required operations and

then calls the procedure automatically at the location (in your program) of the data

loop. It does this by translating your main program le into a temporary le and then

executing the temporary le.

A data loop may be placed only in the main program le. Data loops in les that are

#included or autoloaded are not recognized.

13.1 Data Loop Statements

A data loop begins with a dataloop statement and ends with an endata statement.

Inside of a data loop, the following statements are supported:

155

13. DATA TRANSFORMATIONS

code create variable based on a set of logical expressions.

delete delete rows (observations) based on a logical expression.

drop specify variables NOT to be written to data set.

extern allows access to matrices and strings in memory.

keep specify variables to be written to output data set.

lag lag variables a number of periods.

listwise controls deletion of missing values.

make create new variable.

outtyp specify output le precision.

recode change variable based on a set of logical expressions.

select select rows (observations) based on a logical expression.

vector create new variable from a scalar returning expression.

In any expression inside of a data loop, all text symbols not immediately followed by a

left parenthesis ( are assumed to be data set variable (column) names. Text symbols

followed by a left parenthesis are assumed to be procedure names. Any symbol listed in

an extern statement is assumed to be a matrix or string already in memory.

13.2 Using Other Statements

All program statements in the main le and not inside of a data loop are passed

through to the temporary le without modication. Program statements within a data

loop that are preceded by a # are passed through to the temporary le without

modication. The adept user who is familiar with the code generated in the temporary

le can use this to do out-of-the-ordinary operations inside the data loop.

13.3 Debugging Data Loops

The translator that processes data loops can be turned on and o. When the translator

is on, there are three distinct phases in running a program.

Translation translation of main program le to temporary le.

Compilation compilation of temporary le.

Execution execution of compiled code.

13.3.1 Translation Phase

In the translation phase, the main program le is translated into a temporary le. Each

data loop is translated into a procedure and a call to this procedure is placed in the

156

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

13. DATA TRANSFORMATIONS

temporary le at the same location as the original data loop. The data loop itself is

commented out in the temporary le. All the data loop procedures are placed at the

end of the temporary le.

Depending upon the status of line number tracking, error messages encountered in this

phase will be printed with the le name and line numbers corresponding to the main

le.

13.3.2 Compilation Phase

In the compilation phase, the temporary le $xrun$.tmp is compiled. Depending upon

the status of line number tracking, error messages encountered in this phase will be

printed with the le name and line numbers corresponding to both the main le and

the temporary le.

13.3.3 Execution Phase

In the execution phase, the compiled program is executed and error messages will

include line number references from both the original le and the temporary le,

depending upon the status of line number tracking.

13.4 Reserved Variables

The following local variables are created by the translator and used in the produced

code:

x cv x iptr x ncol x plag

x drop x keep x nlag x ptrim

x fpin x lval x nrow x shft

x fpout x lvar x ntrim x tname

x i x n x out x vname

x in x name x outtyp x x

These variables are reserved, and should not be used within a dataloop... endata

section.

157

13. DATA TRANSFORMATIONS

158

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

Chapter 14

Data Loop Reference

159

code 14. DATA LOOP REFERENCE

Purpose

Creates new variables with dierent values based on a set of logical expressions.

Format

code [[#]] [[$]] var [[default defval ]] with

val 1 for expression 1,

val 2 for expression 2,

.

.

.

val n for expression n;

Input

var literal, the new variable name.

defval scalar, the default value if none of the expressions are TRUE.

val scalar, value to be used if corresponding expression is TRUE.

expression logical scalar-returning expression that returns nonzero TRUE or zero

FALSE.

Remarks

If $ is specied, the new variable will be considered a character variable. If # or

nothing is specied, the new variable will be considered numeric.

The logical expressions must be mutually exclusive, i.e., only one may return TRUE for

a given row (observation).

Any variables referenced must already exist, either as elements of the source data set,

as externs, or as the result of a previous make, vector, or code statement.

If no default value is specied, 999 is used.

Example

code agecat default 5 with

1 for age < 21,

2 for age >= 21 and age < 35,

3 for age >= 35 and age < 50,

4 for age >= 50 and age < 65;

code $ sex with

"MALE" for gender == 1,

"FEMALE" for gender == 0;

See also

recode

160

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE dataloop

Purpose

Species the beginning of a data loop.

Format

dataloop inle outle;

Input

inle string variable or literal, the name of the source data set.

Output

outle string variable or literal, the name of the output data set.

Remarks

The statements between the dataloop... endata commands are assumed to be

metacode to be translated at compile time. The data from inle is manipulated by the

specied statements, and stored to the data set outle. Case is not signicant within

the dataloop... endata section, except for within quoted strings. Comments can be

used as in any GAUSS code.

Example

src = "source";

dataloop ^src dest;

make newvar = x1 + x2 + log(x3);

x6 = sqrt(x4);

keep x6, x5, newvar;

endata;

Here, src is a string variable requiring the caret (^) operator, while dest is a string

literal.

161

delete 14. DATA LOOP REFERENCE

Purpose

Removes specic rows in a data loop based on a logical expression.

Format

delete logical expression;

Remarks

Deletes only those rows for which logical expression is TRUE. Any variables referenced

must already exist, either as elements of the source data set, as externs, or as the result

of a previous make, vector, or code statement.

GAUSS expects logical expression to return a row vector of 1s and 0s. The relational

and other operators (e.g. <) are already interpreted in terms of their dot equivalents

(. <), but it is up to the user to make sure that function calls within logical expression

result in a vector.

Example

delete age < 40 or sex == FEMALE;

See also

select

162

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE drop

Purpose

Species columns to be dropped from the output data set in a data loop.

Format

drop variable list;

Remarks

Commas are optional in variable list.

Deletes the specied variables from the output data set. Any variables referenced must

already exist, either as elements of the source data set, or as the result of a previous

make, vector, or code statement.

If neither keep nor drop is used, the output data set will contain all variables from the

source data set, as well as any dened variables. The eects of multiple keep and drop

statements are cumulative.

Example

drop age, pay, sex;

See also

keep

163

extern 14. DATA LOOP REFERENCE

Purpose

Allows access to matrices or strings in memory from inside a data loop.

Format

extern variable list;

Remarks

Commas in variable list are optional.

extern tells the translator not to generate local code for the listed variables, and not to

assume they are elements of the input data set.

extern statements should be placed before any reference to the symbols listed. The

specied names should not exist in the input data set, or be used in a make statement.

Example

This example shows how to assign the contents of an external vector to a new variable

in the data set, by iteratively assigning a range of elements to the variable. The

reserved variable x x contains the data read from the input data set on each iteration.

The external vector must have at least as many rows as the data set.

base = 1; /* used to index a range of elements from exvec */

dataloop oldata newdata;

extern base, exvec;

make ndvar = exvec[seqa(base,1,rows(x_x))];

# base = base + rows(x_x); /* execute command literally */

endata;

164

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE keep

Purpose

Species columns (variables) to be saved to the output data set in a data loop.

Format

keep variable list;

Remarks

Commas are optional in variable list.

Retains only the specied variables in the output data set. Any variables referenced

must already exist, either as elements of the source data set, or as the result of a

previous make, vector, or code statement.

If neither keep nor drop is used, the output data set will contain all variables from the

source data set, as well as any newly dened variables. The eects of multiple keep and

drop statements are cumulative.

Example

keep age, pay, sex;

See also

drop

165

lag 14. DATA LOOP REFERENCE

Purpose

Lags variables a specied number of periods.

Format

lag nv1 = var1:p1 [[nv2 = var2:p2...]];

Input

var name of the variable to lag.

p scalar constant, number of periods to lag.

Output

nv name of the new lagged variable.

Remarks

You can specify any number of variables to lag. Each variable can be lagged a dierent

number of periods. Both positive and negative lags are allowed.

Lagging is executed before any other transformations. If the new variable name is

dierent from that of the variable to lag, the new variable is rst created and appended

to a temporary data set, _lagtmp_.dat, on the default directory. This temporary data

set becomes the input data set for the dataloop, and is then automatically deleted.

166

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE listwise

Purpose

Controls listwise deletion of missing values.

Format

listwise [[read]]|[[write]];

Remarks

If read is specied, the deletion of all rows containing missing values happens

immediately after reading the input le and before any transformations. If write is

specied, the deletion of missing values happens after any transformations and just

before writing to the output le. If no listwise statement is present, rows with missing

values are not deleted.

The default is read.

167

make 14. DATA LOOP REFERENCE

Purpose

Species the creation of a new variable within a data loop.

Format

make [[#]] numvar = numeric expression;

make $ charvar = character expression;

Remarks

A numeric expression is any valid expression returning a numeric vector. A

character expression is any valid expression returning a character vector. If neither $

nor # is specied, # is assumed.

The expression may contain explicit variable names and/or GAUSS commands. Any

variables referenced must already exist, either as elements of the source data set, as

externs, or as the result of a previous make, vector, or code statement. The variable

name must be unique. A variable cannot be made more than once, or an error is

generated.

Example

make sqvpt = sqrt(velocity * pressure * temp);

make $ sex = lower(sex);

See also

vector

168

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE outtyp

Purpose

Species the precision of the output data set.

Format

outtyp num constant ;

Remarks

num constant must be 2, 4, or 8, to specify integer, single precision, or double

precision, respectively.

If outtyp is not specied, the precison of the output data set will be that of the input

data set. If character data is present in the data set the precision will be coerced to

double.

Example

outtyp 8;

169

recode 14. DATA LOOP REFERENCE

Purpose

Changes the value of a variable with dierent values based on a set of logical

expressions.

Format

recode [[#]] [[$]] var WITH

val 1 for expression 1,

val 2 for expression 2,

.

.

.

val n for expression n;

Input

var literal, the new variable name.

val scalar, value to be used if corresponding expression is true.

expression logical scalar-returning expression that returns nonzero TRUE or zero

FALSE.

Remarks

If $ is specied, the variable will be considered a character variable. If # is specied,

the variable will be considered numeric. If neither is specied, the type of the variable

will be left unchanged.

The logical expressions must be mutually exclusive, that is only one may return TRUE

for a given row (observation).

If none of the expressions is TRUE for a given row (observation), its value will remain

unchanged.

Any variables referenced must already exist, either as elements of the source data set,

as externs, or as the result of a previous make, vector, or code statement.

Example

recode age with

1 for age < 21,

2 for age >= 21 and age < 35,

3 for age >= 35 and age < 50,

4 for age >= 50 and age < 65,

5 for age >= 65;

170

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE recode

recode $ sex with

"MALE" for sex == 1,

"FEMALE" for sex == 0;

recode # sex with

1 for sex $== "MALE",

0 for sex $== "FEMALE";

See also

code

171

select 14. DATA LOOP REFERENCE

Purpose

Selects specic rows (observations) in a data loop based on a logical expression.

Format

select logical expression;

Remarks

Selects only those rows for which logical expression is TRUE. Any variables referenced

must already exist, either as elements of the source data set, as externs, or as the result

of a previous make, vector, or code statement.

Example

select age > 40 AND sex $== MALE;

See also

delete

172

D

a

t

a

T

r

a

n

s

f

o

r

m

a

t

i

o

n

s

14. DATA LOOP REFERENCE vector

Purpose

Species the creation of a new variable within a data loop.

Format

vector [[#]] numvar = numeric expression;

vector $ charvar = character expression;

Remarks

A numeric expression is any valid expression returning a numeric value. A

character expression is any valid expression returning a character value. If neither $

nor # is specied, # is assumed.

vector is used in place of make when the expression returns a scalar rather than a

vector. vector forces the result of such an expression to a vector of the correct length.

vector could actually be used anywhere that make is used, but would generate slower

code for expressions that already return vectors.

Any variables referenced must already exist, either as elements of the source data set,

as externs, or as the result of a previous make, vector, or code statement.

Example

vector const = 1;

See also

make

173

vector 14. DATA LOOP REFERENCE

174

G

r

a

p

h

i

c

s

Chapter 15

Graphics Categorical Reference

This chapter summarizes all of the procedures and global variables available within the

Publication Quality Graphics System. A general usage description and command

reference may be found in Chapters 16 and 17 respectively.

15.1 Graph Types

xy Graph X,Y using Cartesian coordinate system.

logx Graph X,Y using logarithmic X axis.

logy Graph X,Y using logarithmic Y axis.

loglog Graph X,Y using logarithmic X and Y axes.

bar Generate bar graph.

hist Compute and graph frequency histogram.

histf Graph a histogram given a vector of frequency counts.

histp Graph a percent frequency histogram of a vector.

box Graph data using the box graph percentile method.

xyz Graph X, Y, Z using 3-D Cartesian coordinate system.

surface Graph a 3-D surface.

contour Graph contour data.

draw Supply additional graphic elements to graphs.

15.2 Axes Control and Scaling

175

15. GRAPHICS CATEGORICAL REFERENCE

paxes Turn axes on or o.

pcross Control where axes intersect.

pgrid Control major and minor grid lines.

pxpmax Control precision of numbers on X axis.

pypmax Control precision of numbers on Y axis.

pzpmax Control precision of numbers on Z axis.

pxsci Control use of scientic notation on X axis.

pysci Control use of scientic notation on Y axis.

pzsci Control use of scientic notation on Z axis.

pticout Control direction of tick marks on axes.

scale Scale X,Y axes for 2-D plots.

scale3d Scale X,Y,Z axes for 3-D plots.

xtics Scale X axis and control tick marks.

ytics Scale Y axis and control tick marks.

ztics Scale Z axis and control tick marks.

15.3 Text, Labels, Titles, and Fonts

plegctl Set location and size of plot legend.

plegstr Specify legend text entries.

pmsgctl Control message position.

pmsgstr Specify message text.

paxht Control size of axes labels.

pnumht Control size of axes numeric labels.

pnum Axes numeric label control and orientation.

pdate Date string contents and control.

ptitlht Control main title size.

xlabel X axis label.

ylabel Y axis label.

zlabel Z axis label.

title Specify main title for graph.

asclabel Dene character labels for tick marks.

fonts Load fonts for labels, titles, messages and legend.

15.4 Main Curve Lines and Symbols

pboxctl Control box plotter.

pboxlim Output percentile matrix from box plotter.

176

G

r

a

p

h

i

c

s

15. GRAPHICS CATEGORICAL REFERENCE

plctrl Control main curve and frequency of data symbols.

pcolor Control line color for main curves.

pltype Control line style for main curves.

plwidth Control line thickness for main curves.

pstype Control symbol type for main curves.

psymsiz Control symbol size for main curves.

pzclr Z level color control for contour and surface.

15.5 Extra Lines and Symbols

parrow Create arrows.

parrow3 Create arrows for 3-D graphs.

pline Plot extra lines and circles.

pline3d Plot extra lines for 3-D graphs.

psym Plot extra symbols.

psym3d Plot extra symbols for 3-D graphs.

perrbar Plot error bars.

15.6 Window, Page, and Plot Control

pagesiz Control size of graph for printer output.

pageshf Shift the graph for printer output.

plotsiz Control plot area size.

plotshf Control plot area position.

protate Rotate the graph 90 degrees.

margin Control graph margins.

axmargin Control axes margins and plot size.

begwind Window initialization procedure.

endwind End window manipulation, display graphs.

window Create tiled windows of equal size.

makewind Create window with specied size and position.

setwind Set to specied window number.

nextwind Set to next available window number.

getwind Get current window number.

savewind Save window conguration to a le.

loadwind Load a window conguration from a le.

axmargin is preferred to the older plotsiz and plotshf globals for establishing an

absolute plot size and position.

177

15. GRAPHICS CATEGORICAL REFERENCE

15.7 Output Options

pnotify Control interactive mode and progress reports.

pscreen Control graphics output to screen.

psilent Control nal beep.

pzoom Specify zoom parameters.

ptek Control creation and name of graphics .tkf le.

graphprt Generate print, conversion le.

15.8 Miscellaneous

pbox Draw a border around window/screen.

pframe Draw a frame around 2-D, 3-D plots.

pcrop Control cropping of graphics data outside axes area.

pmcolor Control colors to be used for axes, title, x.

and y labels, date, box and background.

pxmem Memory control for graphics .rex les.

view Set 3-D observer position in workbox units.

viewxyz Set 3-D observer position in plot coordinates.

volume Set length, width and height ratios of 3-D workbox.

rerun Display most recently created graph.

graphset Reset all PQG globals to default values.

178

G

r

a

p

h

i

c

s

Chapter 16

Publication Quality Graphics

GAUSS Publication Quality Graphics is a set of routines built on the graphics

functions in GraphiC by Scientic Endeavors Corp.

The main graphics routines include xy, xyz, surface, polar and log plots, as well as

histograms, bar, and box graphs. Users can enhance their graphs by adding legends,

changing fonts, and adding extra lines, arrows, symbols and messages.

The user can create a single full size graph, inset a smaller graph into a larger one, tile

a screen with several equally sized graphs or place several overlapping graphs on the

screen. Window size and location are all completely under the users control.

16.1 Conguration

Before using the Publication Quality Graphics system, you may need to congure the

system for the hardware. See the graphics conguration section in the platform

supplement for your platform.

16.2 General Design

GAUSS Publication Quality Graphics consists of a set of main graphing procedures and

several additional procedures and global variables for customizing the output.

179

16. PUBLICATION QUALITY GRAPHICS

bar Bar graphs.

box Box plots.

contour Contour plots.

draw Draws graphs using only global variables.

hist Histogram.

histp Percentage histogram.

histf Histogram from a vector of frequencies.

loglog Log scaling on both axes.

logx Log scaling on X axis.

logy Log scaling on Y axis.

polar Polar plots.

surface 3-D surface with hidden line removal.

xy Cartesian graph.

xyz 3-D Cartesian graph.

All of the actual output to the screen happens during the call to these main routines.

16.3 Using Publication Quality Graphics

16.3.1 Getting Started Right Away

There are four basic parts to a graphics program. These elements should be in any

program that uses graphics routines. The four parts are header, data setup, graphics

format setup, and graphics call.

1. Header

In order to use the graphics procedures, the pgraph library must be active. This

is done in the library statement at the top of your program or command le.

The next line in your program will typically be a command to reset the graphics

global variables to the default state. The top two lines of your graphics program

should look something like this:

library mylib, pgraph;

graphset;

2. Data Setup

The data to be graphed must be in matrices.

x = seqa(1,1,50);

y = sin(x);

3. Graphics Format Setup

Most of the graphics elements contain defaults which allow the user to generate

a plot without modication. These defaults, however, may be overridden by the

180

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

user through the use of global variables and graphics procedures. Some of the

elements custom congurable by the user are axes numbering, labeling,

cropping, scaling, line and symbol sizes and types, legends and colors.

4. Calling Graphics Routines

It is in the main graphics routines where all of the work for the graphics

functions get done. The graphics routines take as input the user data and global

variables which have previously been set up. It is in these routines where the

graphics le is created and displayed.

Here are three Publication Quality Graphics examples. The rst two programs are

dierent versions of the same graph. The variables that begin with p are the global

control variables used by the graphics routines. See Section 16.8 for a detailed

description of the global control variables.

If using UNIX, a graphics window will have to be opened with the WinOpenPQG

function, see the COMMAND REFERENCE section in the UNIX supplement.

Example 1:

The routine being called here is a simple XY plot. The entire screen will be used. Four

sets of data will be plotted with the line and symbol attributes automatically selected.

This graph will include a legend, title, and a time/date stamp (time stamp is on by

default).

library pgraph; /* activate PGRAPH library */

graphset; /* reset global variables */

x = seqa(.1,.1,100); /* generate data */

y = sin(x);

y = y ~ y*.8 ~ y*.6 ~ y*.4; /* 4 curves plotted against x */

_plegctl = 1; /* legend on */

title("Example xy Graph"); /* Main title */

xy(x,y); /* Call to main routine */

Example 2:

Here is the same graph with more of the graphics format controlled by the user. The

rst two data sets will be plotted using symbols at graph points only (observed data),

and the data in the second two sets will be connected with lines (predicted results).

library pgraph; /* activate PGRAPH library */

graphset; /* reset global variables */

x = seqa(.1,.1,100); /* generate data */

y = sin(x);

y = y ~ y*.8 ~ y*.6 ~ y*.4; /* 4 curves plotted against x */

_pdate = ""; /* date is not printed */

181

16. PUBLICATION QUALITY GRAPHICS

_plctrl = { 1, 1, 0, 0 }; /* 2 curves w/symbols, 2 without */

_pltype = { 1, 2, 6, 6 }; /* dashed, dotted, solid lines */

_pstype = { 1, 2, 0, 0 }; /* symbol types circles, squares */

_plegctl= { 2, 3, 1.7, 4.5 }; /* legend size and locations */

_plegstr= "Sin wave 1.\0"\ /* 4 lines legend text */

"Sin wave .8\0"\

"Sin wave .6\0"\

"Sin wave .4";

ylabel("Amplitude"); /* Y axis label */

xlabel("X Axis"); /* X axis label */

title("Example xy Graph"); /* main title */

xy(x,y); /* call to main routine */

Example 3:

In this example, two graphics windows are drawn. The rst window is a full-sized

surface representation, and the second is a half-sized inset containing a contour of the

same data located in the lower left corner of the screen.

library pgraph; /* activate pgraph library */

/* Generate data for surface and contour plots */

x = seqa(-10,0.1,71); /* note x is a row vector */

y = seqa(-10,0.1,71); /* note y is a column vector */

z = cos(5*sin(x) - y); /* z is a 71x71 matrix */

begwind; /* initialize graphics windows */

makewind(9,6.855,0,0,0); /* first window full size */

makewind(9/2,6.855/2,1,1,0); /* second window inset to first */

setwind(1); /* activate first window */

graphset; /* reset global variables */

_pzclr = { 1, 2, 3, 4 }; /* set Z level colors */

title("cos(5*sin(x) - y)"); /* set main title */

xlabel("X Axis"); /* set X axis label */

ylabel("Y Axis"); /* set Y axis label */

scale3d(miss(0,0),miss(0,0),-5|5); /* scale Z axis */

surface(x,y,z); /* call surface routine */

nextwind; /* activate second window. */

graphset; /* reset global variables */

_pzclr = { 1, 2, 3, 4 }; /* set Z level colors */

_pbox = 15; /* white border */

contour(x,y,z); /* call contour routine */

endwind; /* Display windows */

While the structure has changed somewhat, the four basic elements of the graphics

program are all here. The additional routines begwind, endwind, makewind, nextwind,

and setwind are all used to control the graphics windows.

182

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

As Example 3 illustrates, the code between window functions (i.e. setwind or

nextwind) may include assignments to global variables, a call to graphset, or may set

up new data to be passed to the main graphics routines.

At this point, you may want to look through Chapter 15 to get an overview of the

capabilities of the Publication Quality Graphics, or proceed directly to Section 16.8 and

Chapter 17 for in-depth information on the Publication Quality Graphics functions and

global control variables. For more information on how to create graphics windows,

continue reading the section below.

You are encouraged to run the example programs supplied with GAUSS. Analyzing

these programs is perhaps the best way to learn how to use the Publication Quality

Graphics system. The example programs are located on the examples subdirectory.

16.3.2 Graphics Coordinate System

The Publication Quality Graphics uses a 4190x3120 pixel resolution on a 9.0x6.855 inch

hardcopy output screen or page. There are 3 units of measure supported with most of

the graphics global elements.

Inch Coordinates

Inch coordinates are based on the dimensions of the full-size 9.0x6.855 inch output

page. The origin is (0,0) at the lower left corner of the page. If the picture is rotated

the origin is at the upper left. See Inch Units in Graphics Windows in Section 16.4.1.

Plot Coordinates

Plot coordinates refer to the coordinate system of the graph in the units of the users

X, Y and Z axes.

Pixel Coordinates

Pixel coordinates refer to the 4096x3120 pixel coordinates of the full-size output page.

The origin is (0,0) at the lower left corner of the page. If the picture is rotated the

origin is at the upper left.

16.4 Graphics Windows

Multiple windows for graphics are supported. These windows allow the user to display

multiple graphs on one screen or page.

183

16. PUBLICATION QUALITY GRAPHICS

A window is any rectangular subsection of the screen or page. Windows may be any

size and position on the screen and may be tiled or overlapping, transparent or

nontransparent.

Tiled Windows

Tiled windows do not overlap. The screen can easily be divided into any number of

tiled windows with the window command. window takes three parameters: number of

rows, number of columns, and window attribute (1=transparent, 0=nontransparent).

window(nrows,ncols,attr);

window(2,3,0);

This command will divide the screen into 6 equally sized windows. There will be two

rows of three windows, 3 windows in the upper half of the screen and 3 in the lower

half. In this case, the attribute value of 0 is arbitrary since there are no other windows

beneath them.

Overlapping Windows

Overlapping windows are laid on top of one another as they are created, much as if you

were using the cut and paste method to place several graphs together on one page. An

overlapping window is created with the makewind command:

makewind(hsize,vsize,hpos,vpos,attr);

window(2,3,0);

makewind(4,2.5,1,1.5,0);

This makewind command will create an overlapping window of size 4 inches

horizontally by 2.5 inches vertically and positioned 1 inch from the left edge of the page

and 1.5 inches from the bottom of the page. It will be nontransparent.

Nontransparent Windows

A nontransparent window is one which is blanked before graphics information is

written to it. Therefore, information in any previously drawn windows that lie under it

will not be visible.

184

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

Transparent Windows

A transparent window is one which is not blanked, allowing the window beneath it to

show through. Transparent windows are useful for adding information to the page

without erasing information below it. For example, using a transparent window, the

user can add an arrow which begins in one window and ends in another.

16.4.1 Using Window Functions

The following is a summary of the available window functions:

begwind Window initialization procedure.

endwind End window manipulations, display graphs.

window Partition screen into tiled windows.

makewind Create window with specied size and position.

setwind Set to specied window number.

nextwind Set to next available window number.

getwind Get current window number.

savewind Save window conguration to a le.

loadwind Load window conguration from a le.

The following example creates 4 tiled windows and one window which overlaps the

other four:

library pgraph;

graphset;

begwind;

window(2,2,0); /* Create four tiled windows (2 rows, 2 columns) */

xsize = 9/2; /* Create window that overlaps the tiled windows */

ysize = 6.855/2;

makewind(xsize,ysize,xsize/2,ysize/2,0);

x = seqa(1,1,1000); /* Create X data */

y = (sin(x) + 1) * 10.; /* Create Y data */

setwind(1); /* Graph #1, upper left corner */

xy(x,y);

nextwind; /* Graph #2, upper right corner */

logx(x,y);

nextwind; /* Graph #3, lower left corner */

logy(x,y);

nextwind; /* Graph #4, lower right corner */

loglog(x,y);

nextwind; /* Graph #5, center, overlayed */

bar(x,y);

endwind; /* End window processing, display graph */

185

16. PUBLICATION QUALITY GRAPHICS

Inch Units in Graphics Windows

Some global variables allow coordinates to be input in inches. If a coordinate value is in

inches and is being used in a window, that value will be scaled to window inches and

positioned relative to the lower left corner of the window. A window inch is a true inch

in size only if the window is scaled to the full screen, otherwise X coordinates will be

scaled relative to the horizontal window size and Y coordinates will be scaled relative

to the vertical window size.

For help in nding the exact inch coordinates on the output page for positioning text

and other items, see Section 16.5.

16.4.2 Transparent Windows

Lines, symbols, arrows, error bars and other graphics objects may extend from one

window to the next by using transparent windows. First create the desired window

conguration. Then create a full screen, transparent window using the makewind or

the window command. Set the appropriate global variables to position the desired

object on the transparent window. Use the draw procedure to draw it. This window

will act as a transparent overlay on top of the other windows. Transparent windows

can be used to add text or to superimpose one window on top of another.

16.4.3 Saving Window Congurations

The functions savewind and loadwind allow the user to save window congurations.

Once windows are created (using makewind and window) savewind may be called.

This will save to disk the global variables containing information about the current

window conguration. To load this conguration again, call loadwind. See Chapter 17.

16.5 Interactive Draft Mode, DOS Only

Interactive Draft mode allows the user to nd inch position coordinates on the graph

interactively using a mouse or cursor keys. This is useful for locating coordinates for

text, symbols, lines and other items which will be added to the graph.

Draft mode is selected by setting pnotify to 2. This will cause the graph to be drawn

while the graphics le is being created. When each window is complete, the program

will pause before drawing any other windows. At this point, type P. A cursor will

appear and the cursor location will be printed in the lower right corner of the screen.

186

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

The cursor may be positioned with the arrow keys (holding down the Shift key causes

ner movement) or with a mouse.

If the cursor enters the most recent window, two sets of coordinates will be displayed.

The upper coordinates are in window inches relative to the current window. The lower

coordinates are absolute full-page coordinates. See Inch Units in Graphics Windows in

Section 16.4.1.

To exit the interactive mode, press the Esc key.

This function is available on CGA, EGA, and VGA displays only. Thick lines show up

as normal width.

16.6 Fonts and Special Characters

Graphics text elements, such as titles, messages, axes labels, axes numbering and

legends can be modied and enhanced by changing fonts, adding superscripting,

subscripting and special mathematical symbols.

To make these modications and enhancements, the user can embed escape codes in the

text strings which are passed to title, xlabel, ylabel and asclabel or assigned to

pmsgstr and plegstr.

The escape codes used for graphics text are:

\000 String termination character (null byte).

[ Enter superscript mode, leave subscript mode.

] Enter subscript mode, leave superscript mode.

@ Interpret next character as literal.

\20n Select font number n. (see discussion on fonts below)

The escape code \L can be embedded into title strings to create a multiple line title:

title("This is the first line\lthis is the second line");

A null byte \000 is used to separate strings in plegstr and pmsgstr:

_pmsgstr = "First string\000Second string\000Third string";

or

_plegstr = "Curve 1\000Curve 2";

Use the [..] to create the expression M(t) = E(e

tx

):

_pmsgstr = "M(t) = E(e[tx])";

Use the @ to use [ and ] in an X axis label:

xlabel("Data used for x is: data@[.,1 2 3@]");

187

16. PUBLICATION QUALITY GRAPHICS

16.6.1 Selecting Fonts

Four fonts are supplied with Publication Quality Graphics. They are Simplex,

Complex, Simgrma, and Microb. To see the characters in these fonts, see Appendix A.

Fonts are loaded by passing to the fonts procedure a string containing the names of all

fonts to be loaded. For example, this statement will load all four fonts:

fonts("simplex complex microb simgrma");

The fonts command must be called before any of the fonts may be used in text strings.

One of these fonts may then be selected by embedding an escape code of the form

\20n in the string which is to be written in the new font. The n will be 1, 2, 3 or 4,

depending on the order in which the fonts were loaded in fonts. If fonts were loaded as

they are in the above example, then the escape characters for each of the fonts would

be:

\201 Simplex

\202 Complex

\203 Microb

\204 Simgrma

Now select a font for each string to be written:

title("\201This is the title using Simplex font");

xlabel("\202This is the label for X using Complex font");

ylabel("\203This is the label for Y using Microb font");

Once a font is selected, all succeeding text will use that font until another font is

selected. If no fonts are selected by the user, a default font (Simplex) is loaded and

selected automatically for all text work.

16.6.2 Greek and Mathematical Symbols

The following examples illustrate the use of the Simgrma font. This example assumes

that Simgrma was the fourth font loaded. The Simgrma font table in Appendix A lists

the characters available and their numbers. The Simgrma characters are specied by

either:

1. The character number, preceeded by a \.

2. The regular text character with the same number.

188

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

For example, to get an integral sign

the string that has been currently set to use Simgrma font.

To produce the title f(x) = sin

2

(x), the following title string should be used:

title("\201f(x) = sin[2](\204p\201x)");

The p (character 112) corresponds to in Simgrma.

To number the major X axis tick marks with multiples of /4, the following could be

passed to asclabel:

lab = "\2010 \204p\201/4 \204p\201/2 3\204p\201/4 \204p";

asclabel(lab,0);

xtics(0,pi,pi/4,1);

xtics is used to make sure that major tick marks are placed in the appropriate places.

This example will number the X axis tick marks with the labels

2

,

1

, 1, , and

2

:

lab = "\204m\201[-2] \204m\201[-1] 1 \204m m\201[2]";

asclabel(lab,0);

This example illustrates the use of several of the special Simgrma symbols:

_pmsgstr = "\2041\2011/2\204p ,\201e[-\204m[\2012]\201/2]d\204m";

This produces:

1/2

2

/2

d

16.7 Hardcopy and Exporting

When a graphics procedure is called, a graphics le is created. This le contains

graphics commands which may be used later for viewing or printing.

When the graph is displayed on the screen, the user may, in DOS, press the Enter key

to obtain a menu containing available options. If using OS/2 or Unix simply select one

of the menu bar options. These options allow the user to print the graph, zoom in, or

convert the le to another format.

189

16. PUBLICATION QUALITY GRAPHICS

16.7.1 Printing the Graph

The graph may be printed by selecting one of the interactive print options: normal or

draft. The normal print uses a resolution level taken from the PQG conguration le.

The fast draft print always uses a low resolution print. Most of the print parameters

such as page size, margins, and orientation may be changed by editing the

conguration le or by using the graphprt procedure. See Chapter 17 for more

information on graphprt.

If you have purchased the optional DOS play.exe program you may choose to print

your graph using the options available with it. play.exe is documented in the DOS

supplement.

Zooming

To zoom in on a graph interactively, press Z from the graphics display, or select zoom

from the menu bar. An arrow will appear in the center of the graph with a rubberband

box. You may size the box using the the cursor keys or by moving the mouse. Pressing

the right mouse button (or Ctrl-Cursor keys, DOS only) will allow you to move the box.

Pressing the Enter key or left mouse button will select the box as the area to zoom.

Press Esc to cancel zoom mode.

The user may bypass the interactive menu by using a global variable to pass zoom

parameters to the graphics routines. The parameters are set with a 3x1 matrix named

pzoom. See Section 16.8 for a description of this global.

16.7.2 Exporting Graphs

By pressing C, in DOS, from either the graphics menu or the displayed graph, or

selecting File from the menu bar, in OS/2, the graphics le may be converted into other

formats. These formats are widely used by other applications for importing graphs into

word processing and desktop publishing programs. The currently available format

types are:

Encapsulated PostScript le.

Lotus .PIC le

HP-GL Plotter le

PCX bitmap image

DOS only

Other export options are available with the optional program play.exe. For a

complete description of command parameters to play.exe, see the DOS supplement.

190

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

UNIX only

The convert menu option will convert the graph to the le type specied by the

gauss*print.driver variable located in the .gaussrc le. Other export le options

are located in the prndev.tbl le.

16.8 Global Control Variables

The following global variables are used to control various graphics elements. Default

values are provided. Any and all of these variables may be set before calling one of the

main graphing routines. The default values may be modied by changing the

declarations in pgraph.dec and the statements in the procedure graphset in

pgraph.src. graphset may be called anytime the user wishes to reset these variables to

their default values.

pageshf 2x1 vector, the graph will be shifted to the right and up if this is not

zero. If this is zero, the graph will be centered on the output page. The

default is 0.

Note: Used internally, see axmargin for the same functionality. This is

used by the graphics window routines. The user must not set this when

using the window procedures.

pagesiz 2x1 vector, size of the graph in inches on the printer output. Maximum

size is 9.0 x 6.855 inches (unrotated) or 6.855 x 9.0 inches (rotated). If

this is 0, the maximum size will be used. The default is 0.

Note: Used internally, see axmargin for the same functionality. This is

used by the graphics window routines. The user must not set this when

using the window procedures.

parrow Mx11 matrix, draws one arrow per row M of the input matrix. If scalar

zero, no arrows will be drawn.

[M,1] x starting point.

[M,2] y starting point.

[M,3] x ending point.

[M,4] y ending point.

[M,5] ratio of the length of the arrow head to half its width.

[M,6] size of arrow head in inches.

[M,7] type and location of arrow heads. This integer number will be

interpreted as a decimal expansion mn, for example: if 10, then

m = 1, n = 0

m, form of arrow head

191

16. PUBLICATION QUALITY GRAPHICS

0 solid.

1 empty.

2 open.

3 closed.

n, location of arrow head

0 none.

1 at the nal end.

2 at both ends.

[M,8] color of arrow.

[M,9] coordinate units for location.

1 x,y starting and ending locations in plot coordinates.

2 x,y starting and ending locations in inches.

3 x,y starting and ending locations in pixels.

[M,10] line type

1 dashed.

2 dotted.

3 short dashes.

4 closely spaced dots.

5 dots and dashes.

6 solid.

[M,11] Controls. thickness of lines used to draw arrow. This value may

be zero or greater. A value of zero is normal line width.

The following statement could be used to create two single-headed

arrows. They will be located using inches.

_parrow = { 1 1 2 2 3 0.2 11 10 2 6 0,

3 4 2 2 3 0.2 11 10 2 6 0 };

parrow3 Mx12 matrix, draws one 3-D arrow per row of the input matrix. If scalar

zero, no arrows will be drawn.

[M,1] x starting point in 3-D plot coordinates.

[M,2] y starting point in 3-D plot coordinates.

[M,3] z starting point in 3-D plot coordinates.

[M,4] x ending point in 3-D plot coordinates.

[M,5] y ending point in 3-D plot coordinates.

[M,6] z ending point in 3-D plot coordinates.

[M,7] ratio of the length of the arrow head to its half width.

[M,8] size of arrow head in inches.

192

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

[M,9] type and location of arrow heads. This integer number will be

interpreted as a decimal expansion mn, for example:

if 10, then m = 1, n = 0

m, form of arrow head

0 solid.

1 empty.

2 open.

3 closed.

n, location of arrow head

0 none.

1 at the nal end.

2 at both ends.

[M,10] color of arrow.

[M,11] line type.

1 dashed.

2 dotted.

3 short dashes.

4 closely spaced dots.

5 dots and dashes.

6 solid.

[M,12] controls thickness of lines used to draw arrow. This value may

be zero or greater. A value of zero is normal line width.

The following statement could be used to create two single-headed

arrows. They will be located using plot coordinates.

_parrow3 = { 1 1 1 2 2 2 3 0.2 11 10 6 0,

3 4 5 2 2 2 3 0.2 11 10 6 0 };

paxes scalar, 2x1, or 3x1 vector for independent control for each axis. The rst

element controls the X axis, the second controls the Y axis, and the

third (if set) will control the Z axis. If 0 the axis will not be drawn.

Default is 1.

If this is a scalar, it will be expanded to that value.

For example:

_paxes = { 1, 0 }; /* turn X axis on, Y axis off */

_paxes = 0; /* turn all axes off */

_paxes = 1; /* turn all axes on */

paxht scalar, size of axes labels in inches. If 0, a default size will be computed.

Default 0.

193

16. PUBLICATION QUALITY GRAPHICS

pbartyp global 1x2 or Kx2 matrix. Controls bar shading and colors in bar graphs

and histograms.

The rst column controls the bar shading:

0 no shading.

1 dots.

2 vertical cross-hatch.

3 diagonal lines with positive slope.

4 diagonal lines with negative slope.

5 diagonal cross-hatch.

6 solid.

The second column controls the bar color.

pbarwid global scalar, width of bars in bar graphs and histograms. The valid

range is 0-1. If this is 0, the bars will be a single pixel wide. If this is 1,

the bars will touch each other. The default is 0.5, so the bars take up

about half the space open to them.

pbox scalar, draws a box (border) around the entire graph. Set to desired

color of box to be drawn. Use 0 if no box is desired. Default 0.

pboxctl 5x1 vector, controls box plot style, width, and color. Used by procedure

box only.

[1] box width between 0 and 1. If zero, the box plot is drawn as two

vertical lines representing the quartile ranges with a lled circle

representing the 50

th

percentile.

[2] box color. If this is set to 0, the colors may be individually

controlled using global variable pcolor.

[3] Min/max style for the box symbol. One of the following:

1 Minimum and maximum taken from the actual limits of the

data. Elements 4 and 5 are ignored.

2 Statistical standard with the minimum and maximum

calculated according to interquartile range as follows:

intqrange = 75

th

25

th

min = 25

th

1.5intqrange

max = 75

th

+ 1.5intqrange

Elements 4 and 5 are ignored.

3 Minimum and maximum percentiles taken from elements 4

and 5.

[4] Minimum percentile value (0-100) if pboxctl[3] = 3.

[5] Maximum percentile value (0-100) if pboxctl[3] = 3.

194

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

pboxlim 5xM output matrix containing computed percentile results from

procedure box. M corresponds to each column of input y data.

[1,M] minimum whisker limit according to pboxctl[3].

[2,M] 25th percentile (bottom of box).

[3,M] 50th percentile (median).

[4,M] 75th percentile (top of box).

[5,M] maximum whisker limit according to pboxctl[3].

pcolor scalar or Kx1 vector, colors for main curves in xy, xyz and log graphs.

To use a single color set for all curves set this to a scalar color value. If

0, use default colors. Default 0.

The default colors come from a global vector called pcsel. This vector

can be changed by editing pgraph.dec to change the default colors.

pcsel is not documented elsewhere.

pcrop scalar or 1x5 vector, allows plot cropping for dierent graphic elements

to be individually controlled. Valid values are 0 (disabled) or 1

(enabled). If cropping is enabled, any graphical data sent outside the

axes area will not be drawn. If this is scalar, pcrop is expanded to a

1x5 vector using the given value for all elements. All cropping is enabled

by default.

[1] Crop main curves/symbols.

[2] Crop lines generated using pline.

[3] Crop arrows generated using parrow.

[4] Crop circles/arcs generated using pline.

[5] Crop symbols generated using psym.

_pcrop = { 1 1 0 1 0 };

This will crop main curves, and lines and circles drawn by pline.

pcross scalar. If 1, the axes will intersect at the (0,0) X-Y location if it is

visible. The default is 0, meaning the axes will be at the lowest end of

the X-Y coordinates.

pdate date string. If this contains characters, the date will be appended and

printed. The default is set as follows (note the rst character is a font

selection escape code):

_pdate = "\201GAUSS ";

If this is set to a null string, no date will be printed. See Section 16.6 for

more information on using fonts within strings.

195

16. PUBLICATION QUALITY GRAPHICS

perrbar Mx9 matrix, draws one error bar per row of the input matrix. If scalar

0, no error bars will be drawn.

[M,1] x location in plot coordinates.

[M,2] left end of error bar.

[M,3] right end of error bar.

[M,4] y location in plot coordinates.

[M,5] bottom of error bar.

[M,6] top of error bar.

[M,7] line type.

1 dashed.

2 dotted.

3 short dashes.

4 closely spaced dots.

5 dots and dashes.

6 solid.

[M,8] color.

[M,9] line thickness.. This value may be zero or greater. A value of

zero is normal line width.

The following statement could be used to create one error bar using solid

lines:

_perrbar = { 1 0 2 2 1 3 6 2 0 };

pframe 2x1 vector, controls frame around axes area. On 3-D plots this is a cube

surrounding the 3-D workspace.

[1] 1 frame on.

0 frame o.

[2] 1 tick marks on frame.

0 no tick marks.

The default is a frame with tick marks.

pgrid 2x1 vector to control grid.

[1] grid through tick marks.

0 no grid.

1 dotted grid.

2 ne dotted grid.

3 solid grid.

196

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

[2] grid subdivisions between major tick marks.

0 no subdivisions.

1 dotted lines at subdivisions.

2 tick marks only at subdivisions.

The default is no grid and tick marks at subdivisions.

plctrl scalar or Kx1 vector to control whether lines and/or symbols will be

displayed for the main curves. This also controls the frequency of

symbols on main curves. The rows (K) is equal to the number of

individual curves to be plotted in the graph. Default 0.

0 draw line only.

>0 draw line and symbols every plctrl points.

<0 draw symbols only every plctrl points.

1 all of the data points will be plotted with no connecting lines.

_plctrl = { 0, 10, -5 };

This example draws a line for the rst curve, draws a line and plots a

symbol every 10 data points for the second curve, and plots symbols

only every 5 data points for the third curve.

plegctl scalar or 1x4 vector, legend control variable.

If scalar 0, no legend is drawn (default). If nonzero scalar, create legend

in the default location in the lower right of the page.

If 1x4 vector, set as follows:

[1] Legend position coordinate units.

1 Coordinates are in plot coordinates.

2 Coordinates are in inches.

3 Coordinates are in pixels.

[2] Legend text font size. 1 size 9. Default 5.

[3] x coordinate of lower left corner of legend box.

[4] y coordinate of lower left corner of legend box.

_plegctl = 1;

This example puts a legend in the lower right corner.

_plegctl = { 2 3 2.5 1 };

This example creates a smaller legend and positions it 2.5 inches from

the left and 1 inch from the bottom.

197

16. PUBLICATION QUALITY GRAPHICS

plegstr string, legend entry text. Text for multiple curves is separated by a null

byte (\000).

For example:

_plegstr = "Curve 1\000Curve 2\000Curve 3";

plev Mx1 vector, user-dened contour levels for contour. Default 0. See

contour.

pline Mx9 matrix, to draw lines, circles, or radii. Each row controls one item

to be drawn. If this is a scalar zero, nothing will be drawn. The default

is 0.

[M,1] item type and coordinate system.

1 line in plot coordinates.

2 line in inch coordinates.

3 line in pixel coordinates.

4 circle in plot coordinates.

5 circle in inch coordinates.

6 radius in plot coordinates.

7 radius in inch coordinates.

[M,2] line type.

1 dashed.

2 dotted.

3 short dashes.

4 closely spaced dots.

5 dots and dashes.

6 solid.

[M,3-7] coordinates and dimensions.

( 1 ) Line in plot coordinates.

[M,3] x starting point in plot coordinates.

[M,4] y starting point in plot coordinates.

[M,5] x ending point in plot coordinates.

[M,6] y ending point in plot coordinates.

[M,7] 0 if this is a continuation of a curve, 1 if this begins a

new curve.

( 2 ) Line in inches.

[M,3] x starting point in inches.

[M,4] y starting point in inches.

[M,5] x ending point in inches.

[M,6] y ending point in inches.

[M,7] 0 if this is a continuation of a curve, 1 if this begins a

new curve.

198

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

( 3 ) Line in pixel coordinates.

[M,3] x starting point in pixels.

[M,4] y starting point in pixels.

[M,5] x ending point in pixels.

[M,6] y ending point in pixels.

[M,7] 0 if this is a continuation of a curve, 1 if this begins a

new curve.

( 4 ) Circle in plot coordinates.

[M,3] x center of circle in plot coordinates.

[M,4] y center of circle in plot coordinates.

[M,5] radius in x plot units.

[M,6] starting point of arc in radians.

[M,7] ending point of arc in radians.

( 5 ) Circle in inches.

[M,3] x center of circle in inches.

[M,4] y center of circle in inches.

[M,5] radius in inches.

[M,6] starting point of arc in radians.

[M,7] ending point of arc in radians.

( 6 ) Radius in plot coordinates.

[M,3] x center of circle in plot coordinates.

[M,4] y center of circle in plot coordinates.

[M,5] beginning point of radius in x plot units, 0 is the center

of the circle.

[M,6] ending point of radius.

[M,7] angle in radians.

( 7 ) Radius in inches.

[M,3] x center of circle in inches.

[M,4] y center of circle in inches.

[M,5] beginning point of radius in inches, 0 is the center of the

circle

[M,6] ending point of radius in inches.

[M,7] angle in radians.

[M,8] color.

[M,9] Controls line thickness. This value may be zero or greater. A

value of zero is normal line width.

pline3d Mx9 matrix. Allows extra lines to be added to an xyz or surface graph

in 3-D plot coordinates.

199

16. PUBLICATION QUALITY GRAPHICS

[M,1] x starting point.

[M,2] y starting point.

[M,3] z starting point.

[M,4] x ending point.

[M,5] y ending point.

[M,6] z ending point.

[M,7] color.

[M,8] line type.

1 dashed.

2 dotted.

3 short dashes.

4 closely spaced dots.

5 dots and dashes.

6 solid.

[M,9] Line thickness, 0 = normal width.

[M,10] Hidden line ag, 1 = obscured by surface, 0 = not obscured.

plotshf 2x1 vector, distance of plot from lower left corner of output page in

inches. [1] is x distance, [2] is y distance. If scalar 0, there will be no

shift. Default 0.

Note: Used internally, see axmargin for the same functionality. This is

used by the graphics window routines. The user must not set this when

using the window procedures.

plotsiz 2x1 vector, size of the axes area in inches. If scalar 0, the maximum size

will be used.

Note: Used internally, see axmargin for the same functionality. This is

used by the graphics window routines. The user must not set this when

using the window procedures.

pltype scalar or Kx1 vector, line type for the main curves. If this is a nonzero

scalar, all lines will be this type. If scalar 0, line types will be default

styles. The default is 0.

1 dashed.

2 dotted.

3 short dashes.

4 closely spaced dots.

5 dots and dashes.

6 solid.

200

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

The default line types come from a global vector called plsel. This

vector can be changed by editing pgraph.dec to change the default line

types. plsel is not documented elsewhere.

plwidth scalar or Kx1 vector, line thickness for main curves. This value may be

zero or greater. A value of zero is normal (single pixel) line width.

Default 0.

pmcolor 9x1 vector, color values to use for plot

[1] axes.

[2] axes numbers.

[3] X axis label.

[4] Y axis label.

[5] Z axis label.

[6] title.

[7] box.

[8] date.

[9] background.

If this is scalar, it will be expanded to a 9x1 vector

pmsgctl Lx7 matrix of control information for printing the strings contained in

pmsgstr.

[L,1] horizontal location of lower left corner of string.

[L,2] vertical location of lower left corner of string.

[L,3] character height in inches.

[L,4] angle in degrees to print string. This may be -180 to 180 relative

to the positive X axis.

[L,5] location coordinate system.

1 location of string in plot coordinates.

2 location of string in inches.

[L,6] color.

[L,7] Font thickness, may be zero or greater. If 0 use normal line

width.

pmsgstr string, contains a set of messages to be printed on the plot. Each

message is separated from the next with a null byte ( \000 ). The

number of messages must correspond to the number of rows in the

pmsgctl control matrix. This can be created as follows:

201

16. PUBLICATION QUALITY GRAPHICS

_pmsgstr = "Message one.\000Message two.";

pnotify scalar, controls screen output during the creation of the graph. Default

1.

0 No activity to the screen while writing .tkf le.

1 Display progress as fonts are loaded, and .tkf le is being

generated.

2 Display graph while writing .tkf le and enter interactive draft

mode.

pnum scalar, 2x1 or 3x1 vector for independent control for axes numbering.

The rst element controls the X axis numbers, the second controls the Y

axis numbers, and the third (if set) controls the Z axis numbers. Default

is 1.

If this value is scalar, it will be expanded to a vector.

0 No axes numbers displayed.

1 Axes numbers displayed, vertically oriented on Y axis.

2 Axes numbers displayed, horizontally oriented on Y axis.

For example:

_pnum = { 0, 2 }; /* no X axis numbers, horizontal on Y axis */

pnumht scalar, size of axes numbers in inches. If 0 (default), a size of .13 will be

used.

protate scalar, if 0, no rotation, if 1, plot will be rotated 90 degrees. Default 0.

pscreen scalar, if 1, display graph on screen, if 0, do not display graph on screen.

Default 1.

psilent scalar, if 0, a beep will sound when the graph is nished drawing to the

screen. Default 1 (no beep).

pstype scalar or Kx1 vector, controls symbol used at graph points. To use a

single symbol type for all points set this to one of the following scalar

values:

1 Circle 8 Solid Circle

2 Square 9 Solid Square

3 Triangle 10 Solid Triangle

4 Plus 11 Solid Plus

5 Diamond 12 Solid Diamond

6 Inverted Triangle 13 Solid Inverted Triangle

7 Star 14 Solid Star

202

G

r

a

p

h

i

c

s

16. PUBLICATION QUALITY GRAPHICS

If this is a vector, each line will have a dierent symbol. Symbols will

repeat if there are more lines than symbol types.

psurf 2x1 vector, controls 3-D surface characteristics.

[1] if 1, show hidden lines. Default 0.

[2] Color for base (default 7). The base is an outline of the X-Y

plane with a line connecting each corner to the surface. If 0 no

base is drawn.

psym Mx7 matrix, M extra symbols will be plotted.

[M,1] x location.

[M,2] y location.

[M,3] symbol type. See pstype.

[M,4] symbol height. If this is 0, a default height of 5.0 will be used.

[M,5] symbol color.

[M,6] type of coordinates.

1 plot coordinates.

2 inch coordinates.

[M,7] line thickness. A value of zero is normal line width.

psym3d Mx7 matrix for plotting extra symbols on a 3-D (surface or xyz) graph.

[M,1] x location in plot coordinates.

[M,2] y location in plot coordinates.

[M,3] z location in plot coordinates.

[M,4] symbol type. See pstype.

[M,4] symbol height. If this is 0, a default height of 5.0 will be used.

[M,6] symbol color.

[M,7] Line thickness. A value of 0 is normal line width.

Use psym for plotting extra symbols in inch coordinates.

psymsiz scalar or Kx1 vector, symbol size for the symbols on the main curves.

This is NOT related to psym. If 0, a default size of 5.0 is used.

ptek string, name of Tektronix format graphics le. This must have a .tkf

extension. If this is set to a null string, the graphics le will be

suppressed. The default is graphic.tkf.

pticout scalar, if 1, tick marks point outward on graphs. Default 0.

203

16. PUBLICATION QUALITY GRAPHICS

ptitlht scalar, the height of the title characters in inches. If this is 0, a default

height of approx. 0.13 will be used.

pversno string, the graphics version number.

pxpmax scalar, the maximum number of places to the right of the decimal point

for the X axis numbers. Default 12.

pxsci scalar, the threshold in digits above which the data for the X axis will be

scaled and a power of 10 scaling factor displayed. Default 4.

pypmax scalar, the maximum number of places to the right of the decimal point

for the Y axis numbers. Default 12.

pysci scalar, the threshold in digits above which the data for the Y axis will be

scaled and a power of 10 scaling factor displayed. Default 4.

pzclr scalar, row vector, or Kx2 matrix, Z level color control for procedures

surface and contour. See surface.

pzoom 1x3 row vector, magnies the graphics display for zooming in on detailed

areas of the graph. If scalar 0 (default), no magnication is performed.

[1] Magnication value. 1 is normal size.

[2] Horizontal center of zoomed plot (0-100).

[3] Vertical center of zoomed plot (0-100).

To see the upper left quarter of the screen magnied 2 times use:

_pzoom = { 2 25 75 };

pzpmax scalar, the maximum number of places to the right of the decimal point

for the Z axis numbers. Default 3.

pzsci scalar, the threshold in digits above which the data for the Z axis will be

scaled and a power of 10 scaling factor displayed. Default 4.

204

G

r

a

p

h

i

c

s

Chapter 17

Graphics Reference

205

asclabel 17. GRAPHICS REFERENCE

Purpose

To set up character labels for the X and Y axes.

Library

pgraph

Format

asclabel(xl ,yl );

Input

xl string or Nx1 character vector, labels for the tick marks on the X axis. Set

to 0 if no character labels for this axis are desired.

yl string or Mx1 character vector, labels for the tick marks on the Y axis. Set

to 0 if no character labels for this axis are desired.

Example

This illustrates how to label the X axis with the months of the year:

let lab = JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC;

asclabel(lab,0);

This will also work:

lab = "JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC";

asclabel(lab,0);

If the string format is used, then escape characters may be embedded in the labels. For

example, the following produces character labels that are multiples of . The font

Simgrma must be previously loaded in a fonts command. See Section 16.6.

fonts("simplex simgrma");

lab = "\2010.25\202l \2010.5\202l \2010.75\202l l";

asclabel(lab,0);

Here, the \202l produces the symbol from Simgrma.

Source

pgraph.src

Globals

pascx, pascy

See also

xtics, ytics, scale, scale3d, fonts

206

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE axmargin

Purpose

Set absolute margins for the plot axes which control placement and size of plot.

Library

pgraph

Format

axmargin(l ,r,t ,b);

Input

l scalar, the left margin in inches.

r scalar, the right margin in inches.

t scalar, the top margin in inches.

b scalar, the bottom margin in inches.

Remarks

axmargin sets an absolute distance from the axes to the edge of the window. Note that

the user is responsible for allowing enough space in the margin if axes labels, numbers

and title are used on the graph, since axmargin does not size the plot automatically as

in the case of margin.

All input inch values for this procedure are based on a full size screen of 9 x 6.855

inches. If this procedure is used within a window, the values will be scaled to window

inches automatically.

If both margin and axmargin are used for a graph, axmargin will override any sizes

specied by margin.

Example

axmargin(1,1,.5,.855);

This will create a plot area of 7 inches horizontally by 5.5 inches vertically, and

positioned 1 inch right and .855 up from the lower left corner of the window/page.

Source

pgraph.src

Globals

paxmarx, plotshf, plotsiz

207

bar 17. GRAPHICS REFERENCE

Purpose

Bar graph.

Library

pgraph

Format

bar(val ,ht );

Input

val Nx1 numeric vector, bar labels. If scalar 0, a sequence from 1 to rows(ht )

will be created.

ht NxK numeric vector, bar heights.

K overlapping or side-by-side sets of N bars will be graphed.

For overlapping bars, the rst column should contain the set of bars with

the greatest height and the last column should contain the set of bars with

the least height. Otherwise the bars which are drawn rst may be obscured

by the bars drawn last. This is not a problem if the bars are plotted

side-by-side.

pbarwid global scalar, width and type of bars in bar graphs and histograms. The

valid range is 0-1. If this is 0, the bars will be a single pixel wide. If this is

1, the bars will touch each other.

If this value is positive, the bars will overlap. If negative, the bars will be

plotted side-by-side. The default is 0.5.

pbartyp Kx2 matrix.

The rst column controls the bar shading:

0 no shading.

1 dots.

2 vertical cross-hatch.

3 diagonal lines with positive slope.

4 diagonal lines with negative slope.

5 diagonal cross-hatch.

6 solid.

The second column controls the bar color.

208

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE bar

Remarks

Use scale or ytics to x the scaling for the bar heights.

Example

library pgraph;

graphset;

t = seqa(0,1,10);

x = (t^2/2).*(1~0.7~0.3);

_plegctl = { 1 4 };

_plegstr = "Accnt #1\000Accnt #2\000Accnt #3";

title("Theoretical Savings Balance");

xlabel("Years");

ylabel("Dollars x 1000");

_pbartyp = { 1 10 }; /* Set color of the bars to */

/* 10 (magenta) */

_pnum = 2;

bar(t,x); /* Use t vector to label X axis. */

In this example, three overlapping sets of bars will be created. The three heights for

the i

th

bar are stored in x[i,.] .

Source

pbar.src

Globals

rerun, xtics, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx,

pascy, paxes, paxht, paxnum, pbartyp, pbarwid, pbox, pcartx, pcarty,

pcrop, pcross, pcwin, pdate, perrbar, pfonts, pgrid, plegctl, plegstr,

plotshf, plotsiz, pmargin, pmsgctl, pncwin, pnotify, pnum, pnumht,

pqgtype, protate, pscreen, ptek, pticout, ptitle, ptitlht, pworld,

pwrscal, pxfmt, pxlabel, pxpmax, pxscale, pxsci, pyfmt, pylabel,

pypmax, pyscale, pysci, setpage, txtlt

See also

asclabel, xy, logx, logy, loglog, scale, hist

209

begwind 17. GRAPHICS REFERENCE

Purpose

Initialize global window variables.

Library

pgraph

Format

begwind;

Remarks

This procedure must be called before any other window functions are called.

Source

pwindow.src

Globals

pageshf, pagesiz, pappend, pcwin, pdate, prstw, pncwin, pscreen,

pwindmx, pwindno

See also

endwind, window, makewind, setwind, nextwind, getwind

210

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE box

Purpose

Graph data using the box graph percentile method.

Library

pgraph

Format

box(grp,y);

Input

grp 1xM vector. This contains the group numbers corresponding to each

column of y data. If scalar 0, a sequence from 1 to cols(y) will be

generated automatically for the X axis.

y NxM matrix. Each column represents the set of y values for an individual

percentiles box symbol.

Global Input

pboxctl 5x1 vector, controls box style, width, and color.

[1] box width between 0 and 1. If zero, the box plot is drawn as two

vertical lines representing the quartile ranges with a lled circle

representing the 50

th

percentile.

[2] box color. If this is set to 0, the colors may be individually

controlled using the global variable pcolor.

[3] Min/max style for the box symbol. One of the following:

1 Minimum and maximum taken from the actual limits of the

data. Elements 4 and 5 are ignored.

2 Statistical standard with the minimum and maximum

calculated according to interquartile range as follows:

intqrange = 75

th

25

th

min = 25

th

1.5intqrange

max = 75

th

+ 1.5intqrange

Elements 4 and 5 are ignored.

3 Minimum and maximum percentiles taken from elements 4 and

5.

[4] Minimum percentile value (0-100) if pboxctl[3] = 3.

[5] Maximum percentile value (0-100) if pboxctl[3] = 3.

211

box 17. GRAPHICS REFERENCE

plctrl 1xM vector or scalar as follows:

0 Plot boxes only, no symbols.

1 Plot boxes and plot symbols which lie outside the min and max

box values.

2 Plot boxes and all symbols.

-1 Plot symbols only, no boxes.

These capabilities are in addition to the usual line control capabilities of

plctrl.

pcolor 1xM vector or scalar for symbol colors. If scalar, all symbols will be one

color.

Remarks

If missing values are encountered in the y data, they will be ignored during calculations

and will not be plotted.

Source

pbox.src

Globals

rerun, xtics, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx,

pascy, paxes, paxht, paxnum, pbox, pboxctl, pcartx, pcarty, pcolor,

pcrop, pcross, pcsel, pcwin, pdate, perrbar, pfonts, pgrid, plctrl,

plegctl, plegstr, pline, plotshf, plotsiz, plsel, pltype, plwidth, pmargin,

pmsgctl, pncwin, pnotify, pnum, pnumht, pqgtype, protate, pscreen,

pssel, pstype, psymsiz, ptek, pticout, ptitle, ptitlht, pworld, pwrscal,

pxfmt, pxlabel, pxpmax, pxscale, pxsci, pyfmt, pylabel, pypmax,

pyscale, pysci, setpage, txtlt

212

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE contour

Purpose

To graph a matrix of contour data.

Library

pgraph

Format

contour(x,y,z);

Input

x 1xK vector, the X axis data. K must be odd.

y Nx1 vector, the Y axis data. N must be odd.

z NxK matrix, the matrix of height data to be plotted.

plev Kx1 vector, user-dened contour levels for contour. Default 0.

pzclr Nx1 or Nx2 vector. This controls the Z level colors. See surface for a

complete description of how to set this global.

Remarks

A vector of evenly spaced contour levels will be generated automatically from the z

matrix data. Each contour level will be labeled. For unlabeled contours, use ztics.

To specify a vector of your own unequal contour levels, set the vector plev before

calling contour.

To specify your own evenly spaced contour levels, see ztics.

Source

pcontour.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,

paxes, paxht, paxnum, pbox, pcartx, pcarty, pcartz, pcrop, pcross,

pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plev,

plotshf, plotsiz, plsel, pltype, pmargin, pmsgctl, pncwin, pnotify,

pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype, psymsiz,

ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel, pxpmax,

pxscale, pxsci, pyfmt, pylabel, pypmax, pyscale, pysci, pzclr, pzfmt,

pzpmax, pzscale, setpage, txtlt

See also

surface

213

draw 17. GRAPHICS REFERENCE

Purpose

Graphs lines, symbols, and text using the PQG global variables. This procedure does

not require actual X, Y, or Z data since its main purpose is to manually build graphs

using pline, pmsgctl, psym, paxes, parrow and other globals.

Library

pgraph

Format

draw;

Remarks

draw is especially useful when used in conjunction with transparent windows.

Example

library pgraph;

graphset;

begwind;

makewind(9,6.855,0,0,0); /* make full size window for plot */

makewind(3,1,3,3,0); /* make small overlapping window for text */

setwind(1);

x = seqa(.1,.1,100);

y = sin(x);

xy(x,y); /* plot data in first window */

nextwind;

_pbox = 15;

_paxes = 0;

_pnum = 0;

_ptitlht = 1;

margin(0,0,2,0);

title("This is a text window.");

draw; /* add a smaller text window */

endwind; /* create graph */

Source

pdraw.src

214

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE draw

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,

paxes, paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross,

pcsel, pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plotshf, plotsiz,

plsel, pltype, pmargin, pmsgctl, pncwin, pnotify, pnum, pnumht,

pqgtype, protate, pscreen, pssel, pstype, psymsiz, ptek, pticout,

ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel, pxpmax, pxscale, pxsci,

pyfmt, pylabel, pypmax, pyscale, pysci, setpage, txtlt

See also

window, makewind

215

endwind 17. GRAPHICS REFERENCE

Purpose

End window manipulation, display graphs with rerun.

Library

pgraph

Format

endwind;

Remarks

This function uses rerun to display the most recently created .tkf le.

Source

pwindow.src

Globals

rerun, pageshf, pagesiz, pappend, prstw, pscreen, pwindmx, pwindno

See also

begwind, window, makewind, setwind, nextwind, getwind

216

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE fonts

Purpose

Load fonts to be used in the graph.

Library

pgraph

Format

fonts(str);

Input

str string or character vector containing the names of fonts to be used in the

plot.

Simplex standard sans serif font.

Simgrma Simplex greek, math.

Microb bold and boxy.

Complex standard font with serif.

The rst font specied will be used for the axes numbers.

If str is a null string, or fonts is not called, Simplex is loaded by default.

Remarks

See Section 16.6 for instructions on how to select fonts within a text string.

Source

pgraph.src

Globals

pfonts

See also

title, xlabel, ylabel, zlabel

217

getwind 17. GRAPHICS REFERENCE

Purpose

Retrieve the current window number.

Library

pgraph

Format

n = getwind;

Output

n scalar, window number of current window.

Remarks

The current window is the window in which the next graph will be drawn.

Source

pwindow.src

Globals

pwindno

See also

endwind, begwind, window, setwind, nextwind

218

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE graphprt

Purpose

Controls automatic printer hardcopy and conversion le output.

Library

pgraph

Format

graphprt(str);

Input

str string, control string.

Remarks

graphprt is used to create hardcopy output automatically without user intervention.

The input string str can have any of the following items, separated by spaces. If str is a

null string, the interactive mode is entered. This is the default.

-P print graph.

-PF=name set output print le name.

-PO=c set print orientation.

L landscape.

P portrait.

-PS=c set print page size.

Q quarter page.

H half page.

F full page.

-PM=l,r,t,b set print margins to left,right,top,bottom in inch units.

-PR=n set print resolution.

1 low.

2 medium.

3 high.

-C=n convert to another le format.

1 Encapsulated PostScript le.

2 Lotus .PIC le.

3 HPGL Plotter le.

4 PCX bitmap format.

219

graphprt 17. GRAPHICS REFERENCE

-CF=name set converted output le name.

-CO=n set conversion le orientation.

L landscape.

P portrait.

-CS=c set conversion le page size.

Q quarter page.

H half page.

F full page.

-CM=l,r,t,b set conversion le margins to left,right,top,bottom in inch units.

-W=n display graph, wait n seconds, then continue.

If you are not using windows, you can call graphprt anytime before the call to the

graphics routine. If you are using windows, call graphprt just before the endwind

statement.

The print option default values are obtained from the graphics conguration le. Any

parameters passed through graphprt will override the default values. See Section ??.

Under DOS this uses a utility called pqgrun. pqgrun is documented in the DOS

supplement.

Example

Automatic print using a single graphics call.

library pgraph;

graphset;

load x,y;

graphprt("-p"); /* tell "xy" to print */

xy(x,y); /* create graph and print */

Automatic print using multiple graphics windows. Note graphprt is called once just

before the endwind call.

library pgraph;

graphset;

load x,y;

begwind;

window(1,2); /* create two windows */

setwind(1);

xy(x,y); /* first graphics call */

nextwind;

xy(x,y); /* second graphics call */

graphprt("-p");

endwind; /* print page containing all graphs */

220

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE graphprt

The next example shows how to build a string to be used with graphprt.

library pgraph;

graphset;

load x,y;

prtnam = "myprint.prn"; /* name of output print file */

prtres = "1"; /* low-res print */

prtmarg= ".5,.5,.5,.5" /* page margins */

/* concatenate options into one string */

cmdstr = "-p" $+ " -pf=" $+ prtnam $+ " -pr=" $+ prtres;

cmdstr = cmdstr $+ " -pm=" $+ prtmarg;

graphprt(cmdstr); /* tell "xy" to print */

xy(x,y); /* create graph and print */

The above string cmdstr will look like this:

"-p -pf=myprint.prn -pr=1 -pm=.5,.5,.5,.5"

Source

pgraph.src

Globals

pcmdlin

See also

ptek

221

graphset 17. GRAPHICS REFERENCE

Purpose

Reset graphics globals to default values.

Library

pgraph

Format

graphset;

Remarks

This procedure is used to reset the defaults between graphs.

graphset may be called between each window to be displayed.

To change the default values of the global control variables, make the appropriate

changes in the le pgraph.dec and to the procedure graphset.

Source

pgraph.src

Globals

pageshf, pagesiz, parrow, parrow3, pascx, pascy, paxes, paxht,

paxmarx, pbartyp, pbarwid, pbox, pbox3d, pboxctl, pcolor, pcrop,

pcross, pcsel, pcwin, perrbar, pfonts, pframe, pgrid, plctrl, plegctl,

plegstr, plev, pline, pline3d, plotshf, plotsiz, plsel, pltype, plwidth,

pmargin, pmcolor, pmsgctl, pmsgstr, pncwin, pnotify, pnum, pnumht,

protate, pscreen, pssel, pstype, psurf, psym, psym3d, psymsiz, ptek,

pticout, ptitle, ptitlht, pview, pvolume, pwindmx, pworld, pxfmt,

pxlabel, pxpmax, pxscale, pxsci, pyfmt, pylabel, pypmax, pyscale,

pysci, pzclr, pzfmt, pzlabel, pzoom, pzpmax, pzscale

222

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE hist

Purpose

Computes and graphs a frequency histogram for a vector. The actual frequencies are

plotted for each category.

Library

pgraph

Format

{ b,m,freq } = hist(x,v);

Input

x Mx1 vector of data.

v Nx1 vector, the breakpoints to be used to compute the frequencies,

or

scalar, the number of categories.

Output

b Px1 vector, the breakpoints used for each category.

m Px1 vector, the midpoints of each category.

freq Px1 vector of computed frequency counts.

Remarks

If a vector of breakpoints is specied, a nal breakpoint equal to the maximum value of

x will be added if the maximum breakpoint value is smaller.

If a number of categories is specied, the data will be divided into v evenly spaced

categories.

Each time an element falls into one of the categories specied in b, the corresponding

element of freq will be incremented by one. The categories are interpreted as follows:

freq[1] = x <= b[1]

freq[2] = b[1] < x <= b[2]

freq[3] = b[2] < x <= b[3]

Example

223

hist 17. GRAPHICS REFERENCE

library pgraph;

x = rndn(5000,1);

{ b,m,f } = hist(x,20);

Source

phist.src

Globals

bar, pascx, pcolor, pcsel, pmcolor, pmsgctl, pmsgstr, pnum, ptitle,

pworld, pxlabel, pxpmax, pylabel

See also

histp, histf, bar

224

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE histf

Purpose

To graph a histogram given a vector of frequency counts.

Library

pgraph

Format

histf(f ,c);

Input

f Nx1 vector, frequencies to be graphed.

c Nx1 vector, numeric labels for categories. If this is a scalar 0, a sequence

from 1 to rows(f ) will be created.

Remarks

The axes are not automatically labeled. Use xlabel for the category axis and ylabel for

the frequency axis.

Source

phist.src

Globals

bar, pcolor, pcsel, pworld

See also

hist, bar, xlabel, ylabel

225

histp 17. GRAPHICS REFERENCE

Purpose

Computes and graphs a percent frequency histogram of a vector. The percentages in

each category are plotted.

Library

pgraph

Format

{ b,m,freq } = histp(x,v);

Input

x Mx1 vector of data.

v Nx1 vector, the breakpoints to be used to compute the frequencies,

or

scalar, the number of categories.

Output

b Px1 vector, the breakpoints used for each category.

m Px1 vector, the midpoints of each category.

freq Px1 vector of computed frequency counts. This is the vector of counts, not

percentages.

Remarks

If a vector of breakpoints is specied, a nal breakpoint equal to the maximum value of

x will be added if the maximum breakpoint value is smaller.

If a number of categories is specied, the data will be divided into v evenly spaced

categories.

Each time an element falls into one of the categories specied in b, the corresponding

element of freq will be incremented by one. The categories are interpreted as follows:

freq[1] = x <= b[1]

freq[2] = b[1] < x <= b[2]

freq[3] = b[2] < x <= b[3]

226

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE histp

Source

phist.src

Globals

bar, pascx, pcolor, pcsel, pmcolor, pmsgctl, pmsgstr, pnum, ptitle,

pworld, pxlabel, pxpmax, pylabel

See also

hist, histf, bar

227

loadwind 17. GRAPHICS REFERENCE

Purpose

Load a previously saved window conguration.

Library

pgraph

Format

err = loadwind(namestr);

Input

namestr string, name of le to be loaded.

Output

err scalar, 0 if successful, 1 if window matrix is invalid. Note that the current

window conguration will be overwritten in either case.

Source

pwindow.src

Globals

pwindmx

See also

savewind

228

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE loglog

Purpose

Graphs X vs. Y using log coordinates.

Library

pgraph

Format

loglog(x,y);

Input

x Nx1 or NxM matrix. Each column contains the X values for a particular

line.

y Nx1 or NxM matrix. Each column contains the Y values for a particular

line.

Source

ploglog.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, paxes, paxht,

pbox, pcartx, pcarty, pcolor, pcrop, pcross, pcsel, pcwin, pdate,

perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plotshf, plotsiz, plsel,

pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify, pnum, pnumht,

pqgtype, protate, pscreen, pssel, pstype, psymsiz, ptek, pticout,

ptitle, ptitlht, pworld, pxlabel, pxscale, pylabel, pyscale, setpage,

txtlt

See also

xy, logy, logx

229

logx 17. GRAPHICS REFERENCE

Purpose

Graphs X vs. Y using log coordinates for the X axis.

Library

pgraph

Format

logx(x,y);

Input

x Nx1 or NxM matrix. Each column contains the X values for a particular

line.

y Nx1 or NxM matrix. Each column contains the Y values for a particular

line.

Source

plogx.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascy, paxes,

paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross, pcsel,

pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plotshf,

plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify,

pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype, psymsiz,

ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxlabel, pxscale, pyfmt,

pylabel, pypmax, pyscale, pysci, setpage, txtlt

See also

xy, logy, loglog

230

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE logy

Purpose

Graphs X vs. Y using log coordinates for the Y axis.

Library

pgraph

Format

logy(x,y);

Input

x Nx1 or NxM matrix. Each column represents the X values for a particular

line.

y Nx1 or NxM matrix. Each column represents the Y values for a particular

line.

Source

plogy.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, paxes,

paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross, pcsel,

pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, pline,

plotshf, plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin,

pnotify, pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype,

psymsiz, ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel,

pxpmax, pxscale, pxsci, pylabel, pyscale, setpage, txtlt

See also

xy, logx, loglog

231

makewind 17. GRAPHICS REFERENCE

Purpose

Create a window of specic size and position and add it to the list of windows.

Library

pgraph

Format

makewind(xsize,ysize,xshft,yshft ,typ);

Input

xsize scalar, horizontal size of the window in inches.

ysize scalar, vertical size of the window in inches.

xshft scalar, horizontal distance from left edge of screen in inches.

yshft scalar, vertical distance from bottom edge of screen in inches.

typ scalar, window attribute type. If this value is 1, the windows will be

transparent. If 0, the windows will be nontransparent.

Remarks

Note that if this procedure is used when rotating the page, the passed parameters are

scaled appropriately to the newly oriented page. The size and shift values will not be

true inches when printed, but the window size to page size ratio remains the same. The

result of this implementation automates the rotation and eliminates the required

window recalculations by the user.

See the window command for creating tiled windows. For more information on using

windows see Section 16.4.

Source

pwindow.src

Globals

pagedim, pwindmx

See also

window, endwind, setwind, getwind, begwind, nextwind

232

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE margin

Purpose

Sets the margins for the current graph window.

Library

pgraph

Format

margin(l ,r,t ,b);

Input

l scalar, the left margin in inches.

r scalar, the right margin in inches.

t scalar, the top margin in inches.

b scalar, the bottom margin in inches.

Remarks

By default, the dimensions of the graph are the same as the window dimensions. With

this function the graph dimensions may be decreased. The result will be a smaller plot

area surrounded by the specied margin. This procedure takes into consideration the

axes labels and numbers for correct placement.

All input inch values for this procedure are based on a full size screen of 9 x 6.855

inches. If this procedure is used with a window, the values will be scaled to window

inches automatically.

If the axes must be placed an exact distance from the edge of the page, axmargin

should be used.

Source

pgraph.src

Globals

pmargin

See also

axmargin

233

nextwind 17. GRAPHICS REFERENCE

Purpose

Set the current window to the next available window.

Library

pgraph

Format

nextwind;

Remarks

This function selects the next available window to be the current window. This is the

window in which the next graph will be drawn.

See the discussion on using graphics windows in Section 16.4.

Source

pwindow.src

Globals

getwind, setwind

See also

endwind, begwind, setwind, getwind, makewind, window

234

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE polar

Purpose

Graph data using polar coordinates.

Library

pgraph

Format

polar(radius,theta);

Input

radius Nx1 or NxM matrix. Each column contains the magnitude for a particular

line.

theta Nx1 or NxM matrix. Each column represents the angle values for a

particular line.

Source

polar.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,

paxes, paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcsel,

pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr, plotshf,

plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify,

pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype, psymsiz,

ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel, pxpmax,

pxscale, pyfmt, pylabel, pypmax, pyscale, setpage, txtlt

See also

xy, logx, logy, loglog, scale, xtics, ytics

235

rerun 17. GRAPHICS REFERENCE

Purpose

Displays the most recently created graphics le.

Library

pgraph

Format

rerun;

Remarks

rerun is used by the endwind function.

Under DOS, rerun invokes the graphics utility pqgrun.exe. pqgrun is documented in

the DOS supplement.

Source

pcart.src

Globals

pcmdlin, pnotify, psilent, ptek, pzoom

236

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE savewind

Purpose

Save the current window conguration to a le.

Library

pgraph

Format

err = savewind(lename);

Input

lename Name of le.

Output

err scalar, 0 if successful, 1 if window matrix is invalid. Note that the le is

written in either case.

Remarks

See the discussion on using graphics windows in Section 16.4.

Source

pwindow.src

Globals

pwindmx

See also

loadwind

237

scale 17. GRAPHICS REFERENCE

Purpose

Fix the scaling for subsequent graphs. The axes endpoints and increments are

computed as a best guess based on the data passed to it.

Library

pgraph

Format

scale(x,y);

Input

x matrix, the X axis data.

y matrix, the Y axis data.

Remarks

x and y must each have at least 2 elements. Only the minimum and maximum values

are necessary.

This routine xes the scaling for all subsequent graphs until graphset is called. This

also clears xtics and ytics whenever it is called.

If either of the arguments is a scalar missing, the main graphics function will set the

scaling for that axis using the actual data.

If an argument has 2 elements, the rst will be used for the minimum and the last will

be used for the maximum.

If an argument has 2 elements, and contains a missing value, that end of the axis will

be scaled from the data by the main graphics function.

If you want direct control over the axes endpoints and tick marks, use xtics or ytics. If

xtics or ytics have been called after scale, they will override scale.

Source

pscale.src

Globals

pworld, pxscale, pyscale

See also

xtics, ytics, ztics, scale3d

238

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE scale3d

Purpose

Fix the scaling for subsequent graphs. The axes endpoints and increments are

computed as a best guess based on the data passed to it.

Library

pgraph

Format

scale3d(x,y,z);

Input

x matrix, the X axis data.

y matrix, the Y axis data.

z matrix, the Z axis data.

Remarks

x, y and z must each have at least 2 elements. Only the minimum and maximum

values are necessary.

This routine xes the scaling for all subsequent graphs until graphset is called. This

also clears xtics, ytics and ztics whenever it is called.

If any of the arguments is a scalar missing, the main graphics function will set the

scaling for that axis using the actual data.

If an argument has 2 elements, the rst will be used for the minimum and the last will

be used for the maximum.

If an argument has 2 elements, and contains a missing value, that end of the axis will

be scaled from the data by the main graphics function.

If you want direct control over the axes endpoints and tick marks, use xtics, ytics, or

ztics. If one of these functions have been called, they will override scale3d.

Source

pscale.src

Globals

pworld, pxscale, pyscale, pzscale

See also

scale, xtics, ytics, ztics

239

setwind 17. GRAPHICS REFERENCE

Purpose

Set the current window to a previously created window number.

Library

pgraph

Format

setwind(n);

Input

n scalar, window number.

Remarks

This function selects the specied window to be the current window. This is the

window in which the next graph will be drawn.

See the discussion on using graphics windows in Section 16.4.

Source

pwindow.src

Globals

pwindmx, pwindno

See also

begwind, endwind, getwind, nextwind, makewind, window

240

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE surface

Purpose

To graph a 3-D surface.

Library

pgraph

Format

surface(x,y,z);

Input

x 1xK vector, the X axis data.

y Nx1 vector, the Y axis data.

z NxK matrix, the matrix of height data to be plotted.

Global Input

psurf 2x1 vector, controls 3-D surface characteristics.

[1] if 1, show hidden lines. Default 0.

[2] Color for base (default 7). The base is an outline of the X-Y plane

with a line connecting each corner to the surface. If 0, no base is

drawn.

pticout scalar, if 0 (default), tick marks point inward, if 1, tick marks point

outward.

pzclr Z level color control.

There are 3 ways to set colors for the Z levels of a surface graph.

1. To specify a single color for the entire surface plot, set the color

control variable to a scalar value 115. Example:

_pzclr = 15;

2. To specify multiple colors distributed evenly over the entire Z

range, set the color control variable to a vector containing the

desired colors only. GAUSS will automatically calculate the

required corresponding Z values for you. The following example

will produce a three color surface plot, the Z ranges being

lowest=blue, middle=light blue, highest=white:

241

surface 17. GRAPHICS REFERENCE

_pzclr = { 1, 10, 15 };

3. To specify multiple colors distributed over selected ranges, the Z

ranges as well as the colors must be manually input by the user.

The following example assumes -0.2 to be the minimum value in

the z matrix:

_pzclr = { -0.2 1, /* z >= -0.2 blue */

0.0 10, /* z >= 0.0 light blue */

0.2 15 }; /* z >= 0.2 white */

Since a Z level is required for each selected color, the user must be

responsible to compute the minimum value of the z matrix as the

rst Z range element. This may be most easily accomplished by

setting the pzclr matrix as shown above (the rst element being

an arbitrary value), then reset the rst element to the minimum z

value as follows:

_pzclr = { 0.0 1,

0.0 10,

0.2 15 };

_pzclr[1,1] = minc(minc(z));

Source

psurface.src

Globals

rerun, cmnlt, decreas, fontsiz, linlt, pageshf, pagesiz, pappend,

paxes, paxht, paxnum, pbox, pcartx, pcarty, pcartz, pcrop, pcwin,

pdate, pfonts, plegctl, plegstr, pline3d, plotshf, plotsiz, pmargin,

pmsgctl, pncwin, pnotify, pnum, pnumht, poptic, pqgtype, prngerr,

protate, pscreen, psurf, psym3d, ptek, pticout, ptitle, ptitlht, pview,

pvolume, pworld, pxlabel, pxpmax, pxscale, pylabel, pypmax, pyscale,

pzclr, pzlabel, pzpmax, pzscale, range, setpage, txtlt

See also

volume, view

242

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE title

Purpose

To set the title for the graph.

Library

pgraph

Format

title(str);

Input

str string, the title to display above the graph.

Remarks

Up to three lines of title may be produced by embedding a line feed character (\L) in

the title string. For example,

title("First title line\L Second title line\L Third title line");

Fonts may be specied in the title string. See Section 16.6 for instructions on using

fonts.

Source

pgraph.src

Globals

ptitle

See also

xlabel, ylabel, fonts

243

view 17. GRAPHICS REFERENCE

Purpose

To set the position of the observer in workbox units for 3-D plots.

Library

pgraph

Format

view(x,y,z);

Input

x scalar, the X position in workbox units.

y scalar, the Y position in workbox units.

z scalar, the Z position in workbox units.

Remarks

The size of the workbox is set with volume. The viewer MUST be outside of the

workbox. The closer the position of the observer, the more perspective distortion there

will be. If x = y = z, the projection will be isometric.

If view is not called, a default position will be calculated.

Use viewxyz to locate the observer in plot coordinates.

Source

pgraph.src

Globals

pview

See also

volume, viewxyz

244

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE viewxyz

Purpose

To set the position of the observer in plot coordinates for 3-D plots.

Library

pgraph

Format

viewxyz(x,y,z);

Input

x scalar, the X position in plot coordinates.

y scalar, the Y position in plot coordinates.

z scalar, the Z position in plot coordinates.

Remarks

The viewer MUST be outside of the workbox. The closer the observer, the more

perspective distortion there will be.

If viewxyz is not called, a default position will be calculated.

Use view to locate the observer in workbox units.

Source

pgraph.src

Globals

pview

See also

volume, view

245

volume 17. GRAPHICS REFERENCE

Purpose

To set the length, width, and height ratios of the 3-D workbox.

Library

pgraph

Format

volume(x,y,z);

Input

x scalar, the X length of the 3-D workbox.

y scalar, the Y length of the 3-D workbox.

z scalar, the Z length of the 3-D workbox.

Remarks

The ratio between these values is what is important. If volume is not called, a default

workbox will be calculated.

Source

pgraph.src

Globals

pvolume

See also

view

246

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE window

Purpose

Partition the screen into tiled windows of equal size.

Library

pgraph

Format

window(row,col ,typ);

Input

row scalar, number of rows of windows.

col scalar, number of columns of windows.

typ scalar, window attribute type. If 1, the windows will be transparent, if 0,

the windows will be nontransparent (blanked).

Remarks

The windows will be numbered from 1 to (row)(col ) starting from the left topmost

window and moving right.

See the makewind command for creating windows of a specic size and position. For

more information see Section 16.4.

Source

pwindow.src

Globals

makewind, pagedim

See also

endwind, begwind, setwind, nextwind, getwind, makewind

247

xlabel 17. GRAPHICS REFERENCE

Purpose

To set a label for the X axis.

Library

pgraph

Format

xlabel(str);

Input

str string, the label for the X axis.

Source

pgraph.src

Globals

pxlabel

See also

title, ylabel, zlabel

248

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE xtics

Purpose

To set and x scaling, axes numbering and tick marks for the X axis.

Library

pgraph

Format

xtics(min,max,step,minordiv);

Input

min scalar, the minimum value.

max scalar, the maximum value.

step scalar, the value between major tick marks.

minordiv scalar, the number of minor subdivisions.

Remarks

This routine xes the scaling for all subsequent graphs until graphset is called.

This gives you direct control over the axes endpoints and tick marks. If xtics is called

after a call to scale, it will override scale.

X and Y axes numbering may be reversed for xy, logx, logy, and loglog graphs. This

may be accomplished by using a negative step value in the xtics and ytics functions.

Source

pscale.src

Globals

pxscale

See also

scale, ytics, ztics

249

xy 17. GRAPHICS REFERENCE

Purpose

Graphs X vs. Y using Cartesian coordinates.

Library

pgraph

Format

xy(x,y);

Input

x Nx1 or NxM matrix. Each column contains the X values for a particular

line.

y Nx1 or NxM matrix. Each column contains the Y values for a particular

line.

Remarks

Missing values are ignored when plotting symbols. If missing values are encountered

while plotting a curve, the curve will end and a new curve will begin plotting at the

next non-missing value.

Source

pxy.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, pascx, pascy,

paxes, paxht, paxnum, pbox, pcartx, pcarty, pcolor, pcrop, pcross,

pcsel, pcwin, pdate, perrbar, pfonts, pgrid, plctrl, plegctl, plegstr,

plotshf, plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin,

pnotify, pnum, pnumht, pqgtype, protate, pscreen, pssel, pstype,

psymsiz, ptek, pticout, ptitle, ptitlht, pworld, pwrscal, pxfmt, pxlabel,

pxpmax, pxscale, pxsci, pyfmt, pylabel, pypmax, pyscale, pysci,

setpage, txtlt

See also

xyz, logx, logy, loglog

250

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE xyz

Purpose

Graphs X vs. Y vs. Z using Cartesian coordinates.

Library

pgraph

Format

xyz(x,y,z);

Input

x Nx1 or NxK matrix. Each column contains the X values for a particular

line.

y Nx1 or NxK matrix. Each column contains the Y values for a particular

line.

z Nx1 or NxK matrix. Each column contains the Z values for a particular

line.

Remarks

Missing values are ignored when plotting symbols. If missing values are encountered

while plotting a curve, the curve will end and a new curve will begin plotting at the

next non-missing value.

Source

pxyz.src

Globals

rerun, cmnlt, fontsiz, linlt, pageshf, pagesiz, pappend, parrow3,

paxes, paxht, paxnum, pbox, pcartx, pcarty, pcartz, pcolor, pcrop,

pcsel, pcwin, pdate, pfonts, plctrl, plegctl, plegstr, pline3d, plotshf,

plotsiz, plsel, pltype, plwidth, pmargin, pmsgctl, pncwin, pnotify,

pnum, pnumht, poptic, pqgtype, prngerr, protate, pscreen, pssel,

pstype, psym3d, psymsiz, ptek, pticout, ptitle, ptitlht, pview,

pvolume, pworld, pxlabel, pxpmax, pxscale, pylabel, pypmax, pyscale,

pzlabel, pzpmax, pzscale, range, setpage, txtlt

See also

xy, surface, volume, view

251

ylabel 17. GRAPHICS REFERENCE

Purpose

To set a label for the Y axis.

Library

pgraph

Format

ylabel(str);

Input

str string, the label for the Y axis.

Source

pgraph.src

Globals

pylabel

See also

title, xlabel, zlabel

252

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE ytics

Purpose

To set and x scaling, axes numbering and tick marks for the Y axis.

Library

pgraph

Format

ytics(min,max,step,minordiv);

Input

min scalar, the minimum value.

max scalar, the maximum value.

step scalar, the value between major tick marks.

minordiv scalar, the number of minor subdivisions.

Remarks

This routine xes the scaling for all subsequent graphs until graphset is called.

This gives you direct control over the axes endpoints and tick marks. If ytics is called

after a call to scale, it will override scale.

X and Y axes numbering may be reversed for xy, logx, logy and loglog graphs. This

may be accomplished by using a negative step value in the xtics and ytics functions.

Source

pscale.src

Globals

pyscale

See also

scale, xtics, ztics

253

zlabel 17. GRAPHICS REFERENCE

Purpose

To set a label for the Z axis.

Library

pgraph

Format

zlabel(str);

Input

str string, the label for the Z axis.

Source

pgraph.src

Globals

pzlabel

See also

title, xlabel, ylabel

254

G

r

a

p

h

i

c

s

17. GRAPHICS REFERENCE ztics

Purpose

To set and x scaling, axes numbering and tick marks for the Z axis.

Library

pgraph

Format

ztics(min,max,step,minordiv);

Input

min scalar, the minimum value.

max scalar, the maximum value.

step scalar, the value between major tick marks.

minordiv scalar, the number of minor subdivisions. If this function is used with

contour, contour labels will be placed every minordiv levels. If 0, there

will be no labels.

Remarks

This routine xes the scaling for all subsequent graphs until graphset is called.

This gives you direct control over the axes endpoints and tick marks. If ztics is called

after a call to scale3d, it will override scale3d.

Source

pscale.src

Globals

pzscale

See also

scale3d, xtics, ytics, contour

255

ztics 17. GRAPHICS REFERENCE

256

T

i

m

e

a

n

d

D

a

t

e

Chapter 18

Time and Date

GAUSS oers a comprehensive set of time and date functions. These functions aord

the user the ability to return the current time and date, to carry out most related

calculations and format the results for output. GAUSS also allows the user to perform

timed iterations.

In the year 1 AD the calendar in general use was the Julian calendar. The Gregorian

calendar that we use today was not invented until the late 1500s. This new calendar

changed the method of calculating leap years on century marks. With the Julian

system simply every fourth year was a leap year. The Gregorian system made every

fourth year a leap year with the exception of century marks which are only leap years if

divisible by 400. The British adoption of this calendar, which the GAUSS date

functions are based on, did not happen until the year 1752. In that year eleven days

were removed; September 2, 1752 was followed by September 14, 1752.

dtvnormal and utctodtv are accurate back to 1 AD. The rest of the GAUSS date

functions assume a normal Gregorian system regardless of year. Thus, they will not

account for the days taken out in September of 1752, nor will they account for all

century marks being leap years before the adoption of the Gregorian system in 1752.

The time is given by your operating system, daylight savings time is not automatically

accounted for by GAUSS in calculations.

18.1 Time and Date Formats

The Time and Date formats in GAUSS fall into one of two major categories,

matrix/vector and string. The matrix/vector formats can be used for either

257

18. TIME AND DATE

calculations or if desired for output. The string formats are, however, mostly for use as

ouput. Some manipulation of strings is possible with the use of the stof function.

A 41 vector is returned by both the date and time functions.

d = date;

d;

1997.00 /* Year */

5.00000 /* Month */

29.0000 /* Day */

56.4700 /* Hundredths of a second since midnight */

t = time;

t;

10.00 /* Hours since midnight */

17.00 /* Minutes */

33.00 /* Seconds */

13.81 /* Hundredths of a second */

These vectors can be written to a string of the desired form by passing them through

the corresponding function.

d = { 1997, 5, 29, 56.47 };

datestr(d);

5/29/97

datestrymd(d);

19970529

t = { 10, 17, 33, 13.81 };

timestr(t);

10:17:33

A list and brief description of these, and other related functions is provided in the table

in section 18.2.

Another major matrix/vector format is the dtv, or date and time vector. The dtv

vector is a 18 vector used with the dtvnormal and utctodtv functions. The format for

the dtv vector is:

Y ear Month Day Hour Min Sec DoW DiY

1955 4 21 4 16 0 4 110

258

T

i

m

e

a

n

d

D

a

t

e

18. TIME AND DATE

Where:

Year Year, four digit integer.

Month 1-12, Month in year.

Day 1-31, Day of month.

Hour 0-23, Hours since midnight.

Min 0-59, Minutes.

Sec 0-59, Seconds.

DoW 0-6, Day of week, 0=Sunday.

DiY 0-365, Days since Jan 1 of current year.

dtvnormal normalizes a date. The last two elements are ignored for input, as shown in

the following example. They are set to the correct values on output. The input can be

18 or N8.

dtv = { 1954 3 17 4 16 0 0 0 };

dtv = dtvnormal(dtv);

1954 3 17 4 16 0 3 75

dtv[3] = dtv[3] + 400;

print dtv;

1954 3 417 4 16 0 3 75

dtv = dtvnormal(dtv);

print dtv;

1955 4 21 4 16 0 4 110

18.2 Time and Date Functions

Following is a partial listing of the time and date functions available in GAUSS.

datestr Formats a Date vector to a string (mo/dy/yr).

datestrymd Formats a Date vector to an eight character

string of the type yyyymmdd.

dayinyr Returns day number in the year of a given date.

daypryr Returns the number of days in the years given as input.

dtvnormal Normalizes a 1x8 dtv vector.

etdays Computes the dierence in days between two dates.

259

18. TIME AND DATE

ethsec Computes the dierence between two times in

hundredths of a second.

etstr Formats a time dierence measured in hundreths

of a second to a string.

isleap Returns a vector of ones and zeros, 1 if leap year 0 if not.

timestr Formats a Time vector to a string hr:mn:sc.

timeutc Universal time coordinate, number of seconds since

January 1, 1970 Greenwich Mean Time.

utctodtv Converts a scalar, number of seconds since, or before, Jan 1

1970 Greenwich mean time, to a dtv vector.

Below is an example of two ways to calculate a time dierence.

d1 = { 1996, 12, 19, 82 };

d2 = { 1997, 4, 28, 4248879.3 };

dif = ethsec(d1,d2);

ds = etstr(dif);

dif = 1.1274488e +09

ds = 130days 11hours 48minutes 7.97seconds

If only the number of days is needed use etdays.

d1 = { 1996, 12, 19, 82 };

d2 = { 1997, 4, 28, 4248879.3 };

dif = etdays(d1,d2);

dif = 130.00000

The last element of d1 is optional when used as an input for etdays.

isleap returns a matrix of ones and zeros, ones when the corresponding year is a leap

year.

x = seqa(1970,1,20);

y = _isleap(x);

delif(x,abs(y-1));

1972.0000 /* Vector containing all leap years

1976.0000 between 1970 - 1989 */

1980.0000

1984.0000

1988.0000

260

T

i

m

e

a

n

d

D

a

t

e

18. TIME AND DATE

To calculate the days of a number of consecutive years:

x = seqa(1983,1,3);

y = _daypryr(x);

sumc(y);

1096.0000

To add a portion of the following year:

g = { 1986, 2, 23, 0 };

dy = dayinyr(g);

sumc(y)+dy;

1150.0000

For more information on any of these functions see their respective pages in the

command reference.

18.2.1 Timed Iterations

Iterations of a program can be timed with the use of the hsec function in the following

manner.

et = hsec; /* Start timer */

/* Segment of code to be timed */

et = (hsec-et)/100; /* Stop timer, convert to seconds */

A specic example is located in the tutorial section of your supplement.

In the case of a program running from one day into the next you would need to replace

the hsec function with the date function. The ethsec function should be used to

compute the time dierence; a straight subtraction as in the previous example will not

give the desired result.

261

18. TIME AND DATE

dstart = date; /* Start timer */

/* Segment of code to be timed */

dend = date; /* Stop timer */

dif = ethsec(dstart,dend)/100; /* Convert time difference to seconds */

262

U

t

i

l

i

t

i

e

s

Chapter 19

Utility: atog

atog is a utility program to convert ASCII les into GAUSS data les. atog can

convert delimited and packed ASCII les into GAUSS data sets.

From DOS:

atog cmdle

From GAUSS:

atog cmdle;

In the examples above, cmdle is the lename of the command le. If no extension is

given, .cmd will be assumed. If no command le is specied, you will be asked for one.

Pressing Enter at that point begins the interactive mode. Interactive mode allows the

user to create a command le interactively or specify information for the data

conversion directly. The Unix version of atog does not support interactive mode.

19.1 Command Summary

The following commands are supported with atog:

append Append data to an existing le.

complex Treat data as complex variables.

help Display command summary.

263

19. UTILITY: ATOG

input The name of the ASCII input le.

invar Input le variables (column names).

msym Specify missing value character.

nocheck Dont check data type or record length.

nodata Modify the header le only.

output The name of the GAUSS data set to be created.

outtyp Output data type.

outvar List of variables to be included in output le.

quit Exit without converting. Valid only in interactive mode.

run Begin executioncease keyboard input. Valid only in interactive mode.

save Controls saving of command le while in interactive mode.

The principle commands for converting an ASCII le that is delimited with spaces or

commas are given in the following simple example. These commands are placed in a

command le or typed directly into atogs interactive mode.

input agex.asc;

output agex;

invar $ race # age pay $ sex region;

outvar region age sex pay;

outtyp d;

In this example a delimited ASCII le agex.asc is converted to a double precision

GAUSS data le agex.dat. A header is created which contains the names of the

variables and other system information. The input le has 5 variables. The le will be

interpreted as having 5 columns:

column name data type

1 race character

2 AGE numeric

3 PAY numeric

4 sex character

5 region character

The output le will have 4 columns since the rst column of the input le (race) is not

included in the output variables. The columns of the output le are:

264

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

column name data type

1 region character

2 AGE numeric

3 sex character

4 PAY numeric

When using the v89 format (see create in the COMMAND REFERENCE) the header

information is stored in a separate .dht le, thus agex.dht. The v92 and v96 formats

store header information at the top of the .dat le.

If the variable is explicitly designated as a character variable, its name will be stored in

lowercase. The $ in the invar statement species that the variables that follow are

character type. The # species numeric. If $ or # are not used in an invar statement,

the default is numeric.

Comments in command les must be enclosed between @ characters.

19.2 Commands

A detailed explanation of each command follows.

append

Instructs atog to append the converted data to an existing data le.

append;

No assumptions are made regarding the format of the existing le. You should make

certain that the number, order and type of data converted match the existing le.

complex

Instructs atog to convert the ASCII le into a complex GAUSS data set.

complex;

Complex GAUSS data sets are stored by rows, with the real and imaginary parts

interleaved, element by element. atog assumes the same structure for the ASCII input

le, and will thus read TWO numbers out for EACH variable specied. complex

cannot be used with packed ASCII les.

help

Display help screen in interactive mode.

help;

265

19. UTILITY: ATOG

input

The input command species the le name of the ASCII le which is to be converted.

The full path name can be used in the le specication. For example, the command:

input data.raw;

will expect an ASCII data le in the current working directory. The command:

input /research/data/myle.asc;

species a le to be located in the /research/data subdirectory.

invar

Soft Delimited ASCII Files

Soft delimited les may have spaces, commas, or cr/lf as delimiters between elements.

Two or more consecutive delimiters with no data between them are treated as one

delimiter.

invar age $ name sex # pay var[1:10] x[005];

The invar command above species the following variables:

column name data type

1 AGE numeric

2 name character

3 sex character

4 PAY numeric

5 VAR01 numeric

6 VAR02 numeric

7 VAR03 numeric

8 VAR04 numeric

9 VAR05 numeric

10 VAR06 numeric

11 VAR07 numeric

12 VAR08 numeric

13 VAR09 numeric

14 VAR10 numeric

15 X001 numeric

16 X002 numeric

17 X003 numeric

18 X004 numeric

19 X005 numeric

As the input le is translated, the rst 19 elements will be interpreted as the rst row

(observation), the next 19 will be interpreted as the second row, and so on. If the

number of elements in the le is not evenly divisible by 19, the nal incomplete row will

be dropped and a warning message will be given.

266

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

Hard Delimited ASCII Files

Hard delimited les have a printable character as a delimiter between elements. Two

delimiters without intervening data between them will be interpreted as a missing. If

\n is specied as a delimiter, the le should have one element per line and blank lines

will be considered missings. Otherwise, delimiters must be printable characters. The

dot . is illegal and will always be interpreted as a missing value. To specify the

backslash as a delimiter, use \\. If \r is specied as a delimiter, the le will be assumed

to contain one case or record per line with commas between elements and no comma at

the end of the line.

For hard delimited les the delimit subcommand is used with the invar command. The

delimit subcommand has two optional parameters. The rst parameter is the delimiter.

The default is a comma. The second parameter is an N. If the second parameter is

present, atog will expect N delimiters. If it is not present, atog will expect N-1

delimiters.

invar delimit(, N) $ name # var[5];

would expect a le like this:

BILL , 222.3, 123.2, 456.4, 345.2, 533.2,

STEVE, 624.3, 340.3, , 624.3, 639.5,

TOM , 244.2, 834.3, 602.3, 333.4, 822.5,

invar delimit(,) $ name # var[5];

or

invar delimit $ name # var[5];

would expect a le like this:

BILL , 222.3, 123.2, 456.4, 345.2, 533.2,

STEVE, 624.3, 340.3, , 624.3, 639.5,

TOM , 244.2, 834.3, 602.3, 333.4, 822.5

The dierence between specifying N or N-1 delimiters can be seen in the following

example:

456.4, 345.2, 533.2,

, 624.3, 639.5,

602.3, 333.4,

267

19. UTILITY: ATOG

If the invar statement specied 3 variables and N-1 delimiters were specied, this le

would be interpreted as having three rows containing a missing in the 2,1 element and

the 3,3 element like this:

456.4 345.2 533.2

missing 624.3 639.5

602.3 333.4 missing

If N delimiters were specied, this le would be interpreted as having two rows, and a

nal incomplete row which is dropped:

456.4 345.2 533.2

missing 624.3 639.5

The spaces are shown only for clarity and are not signicant in delimited les so:

BILL,222.3,123.2,456.4,345.2,533.2,

STEVE,624.3,340.3,,624.3,639.5,

TOM,244.2,834.3,602.3,333.4,822.5

would work just as well. Linefeeds are signicant only if \n is specied as the delimiter

or when using \r.

invar delimit(\r) $ name # var[5];

would expect a le with no comma after the nal element in each row:

BILL , 222.3, 123.2, 456.4, 345.2, 533.2

STEVE, 624.3, 340.3, 245.3, 624.3, 639.5

TOM , 244.2, 834.3, 602.3, 333.4, 822.5

Packed ASCII Files

Packed ASCII les must have xed length records. The record subcommand is used to

specify the record length and variables are specied by giving their type, starting

position, length, and the position of an implicit decimal point if necessary.

Note that outvar is not used with packed ASCII les. Instead, invar is used to specify

only those variables to be included in the output le.

For packed ASCII les the syntax of the invar command is as follows:

invar record=reclen (format) variables (format) variables;

268

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

where,

reclen the total record length in bytes including the nal carriage return/line feed if

applicable. Records must be xed length.

format (start,length.prec) where:

start starting position of the eld in the record, 1 is the rst position. The

default is 1.

length the length of the eld in bytes. The default is 8.

prec optional, a decimal point will be inserted automatically prec places in

from the RIGHT edge of the eld.

If several variables are listed after a format denition, each succeeding eld will be

assumed to start immediately after the preceding eld. If an asterisk is used to specify

the starting position, the current logical default will be assumed. An asterisk in the

length position will select the current default for both length and prec. This is illegal:

(3,8.*).

The type change characters $ and # are used to toggle between character and numeric

data type.

Any data in the record that is not dened in a format is ignored.

The examples below assume a 32-byte record with a carriage return/line feed occupying

the last 2 bytes of each record. The data below can be interpreted in dierent ways

using dierent invar statements:

ABCDEFGHIJ12345678901234567890<CR><LF>

| | | | | |

position 1 10 20 30 31 32

invar record=32 $(1,3) group dept #(11,4.2) x[3] (*,5) y;

variable value type

group ABC character

dept DEF character

X1 12.34 numeric

X2 56.78 numeric

X3 90.12 numeric

Y 34567 numeric

invar record=32 $ dept (*,2) id # (*,5) wage (*,2) area

269

19. UTILITY: ATOG

variable value type

dept ABCDEFGH character

id IJ character

WAGE 12345 numeric

AREA 67 numeric

msym

Species the character in the input le that is to be interpreted as a missing value.

msym &;

The statement above denes the character & as the missing value character. The

default . (dot) will always be interpreted as a missing value unless it is part of a

numeric value.

nocheck

Optional, suppresses automatic checking of packed ASCII record length and output

data type. The default is to increase the record length by 2 bytes if the second record

in a packed le starts with cr/lf, and any les that have explicitly dened character

data will be output in double precision regardless of the type specied.

nodata

If specied, the .dat le which contains the data will not be modied. nodata is used

to change the variable names or to reshape the le. Since the data is not modied, the

kind of reshaping that is possible is limited. This is usually used to change the names

of the variables or to reshape a le that has one variable to have several variables and

vice versa.

output cvx;

invar x;

outtyp d;

nodata;

output

The name of the GAUSS data set. Two les will be created with the extensions .dat

and .dht for the data and header le pair. The full DOS le path is supported. For

example:

output /gauss/dat/test;

creates the les test.dat and test.dht on the /gauss/dat directory.

outtyp

Selects the numerical accuracy of the output le. Use of this command should be

dictated by the accuracy of the input data and storage space limitations. The format is:

outtyp fmt;

270

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

where fmt is:

D or 8 double precision

F or 4 single precision (default)

I or 2 integer

The ranges of the dierent formats are:

bytes data type signicant range

digits

2 integer 4 32768 X 32767

4 single precision 67 8.43x10

37

[X[ 3.37x10

+38

8 double precision 1516 4.19x10

307

[X[ 1.67x10

+308

If the output type is integer, the input numbers will be truncated to integers. If your

data has more than 6 or 7 signicant digits, you should specify outtyp as double.

Character data require outtyp d. atog automatically selects double precision when

character data is specied in the invar statement unless you have specied nocheck.

The precision of the storage selected does not aect the accuracy of GAUSS calculations

using the data. GAUSS converts all data to double precision when the le is read.

outvar

To select the variables to be placed in the GAUSS data set. The outvar command

needs only the list of variables to be included in the output data set. outvar is not used

with packed ASCII les. They can be in any order.

invar $name #age pay $sex #var[1:10] x[005];

outvar sex age x001 x003 var[1:8];

column name data type

1 sex character

2 AGE numeric

3 X001 numeric

4 X003 numeric

5 VAR01 numeric

6 VAR02 numeric

7 VAR03 numeric

8 VAR04 numeric

9 VAR05 numeric

10 VAR06 numeric

11 VAR07 numeric

12 VAR08 numeric

271

19. UTILITY: ATOG

outvar is not used with packed ASCII les.

preservecase

Optional, preserves the case of variable names. The default is nopreservcase which will

force variable names for numeric variables to upper case and character variables to

lower case.

quit

To exit atog without executing. Used in atog interactive mode only.

quit;

run

Used in atog interactive mode only. This command starts execution of a command set

that has been specied in interactive mode.

run;

save

Controls saving of interactive commands in a le.

save qdata;

This command will open a le qdata.cmd. As subsequent commands are typed in, they

will be saved in this le.

save +qdata;

This will open the le qdata.cmd and process any commands already in the le. Any

subsequent commands that are typed in will be appended to the le.

save -;

This will close the le, and stop saving commands.

If no le name is specied, the default name is atog.cmd.

19.3 Examples

The rst example is a soft delimited ASCII le called agex1.asc. The le contains

seven columns of ASCII data.

272

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

Jan 167.3 822.4 6.34E06 yes 84.3 100.4

Feb 165.8 987.3 5.63E06 no 22.4 65.6

Mar 165.3 842.3 7.34E06 yes 65.4 78.3

The atog command le agex1.cmd:

input /gauss/agex1.asc;

output agex1;

invar $month #temp pres vol $true var[02];

outvar month true temp pres vol;

The output data set will contain the following information:

name month true TEMP PRES VOL

case 1 Jan yes 167.3 822.4 6.34e+6

case 2 Feb no 165.8 987.3 5.63e+6

case 3 Mar yes 165.3 842.3 7.34e+6

type char char numeric numeric numeric

The data set is double precision since character data is explicitly specied.

The second example is a packed ASCII le xlod.asc which contains 32-character

records.

AEGDRFCSTy02345678960631567890<CR><LF>

EDJTAJPSTn12395863998064839561<CR><LF>

GWDNADMSTy19827845659725234451<CR><LF>

| | | | | |

position 1 10 20 30 31 32

The atog command le xlod.cmd:

input /gauss/dat/xlod.asc;

output xlod2;

invar record=32 $(1,3) client[2] zone (*,1) reg #(20,5) zip;

The output data set will contain the following information:

name client1 client2 zone reg ZIP

case 1 AEG DRF CST y 60631

case 2 EDJ TAJ PST n 98064

case 3 GWD NAD MST y 59725

type char char char char numeric

273

19. UTILITY: ATOG

The data set is double precision since character data is explicitly specied.

The third example is a hard delimited ASCII le called cplx.asc. The le contains six

columns of ASCII data.

456.4, 345.2, 533.2, -345.5, 524.5, 935.3,

-257.6, 624.3, 639.5, 826.5, 331.4, 376.4,

602.3, -333.4, 342.1, 816.7, -452.6, -690.8

The atog command le cplx.cmd:

input /gauss/cplx.asc;

output cplx;

invar delimit #cvar[3];

complex;

The output data set will contain the following information:

name cvar1 cvar2 cvar3

case 1 456.4 + 345.2i 533.2 - 345.5i 524.5 + 935.3i

case 2 -257.6 + 624.3i 639.5 + 826.5i 331.4 + 376.4i

case 3 602.3 - 333.4i 342.1 + 816.7i -452.6 - 690.8i

type numeric numeric numeric

The data set defaults to single precision since no character data is present, and no

outtyp command is specied.

19.4 Error Messages

atog - Cant find input file

The ASCII input le could not be opened.

1. The le is not there.

2. You are out of le handles. Check the config.sys le on the root directory of

the disk you boot from to make sure it has a les=25 or greater statement.

atog - Cant open output file

The output le could not be opened.

274

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

1. The disk or directory is full.

2. You are out of le handles. Check the config.sys le on the root directory of

the disk you boot from to make sure it has a les=25 or greater statement.

atog - Cant open temporary file

Notify Aptech Systems of the circumstances of this error.

atog - Cant read temporary file

Notify Aptech Systems of the circumstances of this error.

atog - Character data in output file

Setting output file to double precision

The output le contains character data. The type was set to double precision

automatically.

atog - Character data longer than 8 bytes were truncated

The input le contained character elements longer than 8 bytes. The conversion

continued and the character elements were truncated to 8 bytes.

atog - Disk Full

The output disk is full. The output le is incomplete.

atog - Found character data in numeric field

This is a warning that character data was found in a variable that was specied as

numeric. The conversion will continue.

atog - Header file rename unsuccessful

The temporary header le atog.$dh could not be renamed. This could be a disk full

problem. atog.$dh has been left on the disk and can be renamed manually if you want

to recover from the error.

atog - Illegal command

An unrecognizable command was found in a command le.

atog - Internal error

Notify Aptech Systems of the circumstances of this error.

atog - Invalid delimiter

275

19. UTILITY: ATOG

The delimiter following the backslash is not supported.

atog - Invalid output type

Output type must be I, F, or D.

atog - Missing value symbol not found

No missing value was specied in an msym statement.

atog - No Input file

No ASCII input le was specied. The input command is probably missing.

atog - No input variables

No input variable names were specied. The invar statement may be missing.

atog - No output file

No output le was specied. The output command is probably missing.

atog - output type d required for character data

Character data in output file will be lost

Output le contains character data and is not double precision.

atog - Open comment

The command le has a comment that is not closed. Comments must be enclosed in

@s.

@ comment @

atog - Out of memory

Notify Aptech Systems of the circumstances of this error.

atog - read error

A read error has occurred while converting a packed ASCII le.

atog - Read error on .dht file

The temporary header le atog.$dh could not be read.

atog - Record length must be 1-16384 bytes

276

U

t

i

l

i

t

i

e

s

19. UTILITY: ATOG

The record subcommand has an out of range record length.

atog - Statement too long

Command le statements must be less than 16384 bytes.

atog - Syntax error at:

There is unrecognizable syntax in a command le.

atog - Too many input variables

More input variables were specied than available memory permitted.

atog - Too many output variables

More output variables were specied than available memory permitted.

atog - Too many variables

More variables were specied than available memory permitted.

atog - Undefined variable

A variable requested in an outvar statement was not listed in an invar statement.

ATOG WARNING: missing ) at:

The parentheses in the delimit subcommand were not closed.

ATOG WARNING: some records begin with cr/lf

A packed ASCII le has some records that begin with a carriage return/linefeed. The

record length may be wrong.

atog - complex illegal for packed ASCII file.

A complex command was encountered following an invar command with record

specied.

atog - Cannot read packed ASCII. (complex specified)

An invar command with record specied was encountered following a complex

command.

277

19. UTILITY: ATOG

278

U

t

i

l

i

t

i

e

s

Chapter 20

Utility: liblist

liblist is a library symbol listing utility.

It is a stand-alone program that lists the symbols available to the GAUSS autoloading

system. liblist will also perform .g le conversion and listing operations.

Note that .g les are specic les once used in older versions of GAUSS. Due to

compiler eciency and other reasons, .g les are no longer recommended for use. The

liblist options related to .g les are supplied to aid the user in consolidating .g les

and converting them to the standard .src les.

The format for using liblist from the operating system is:

liblist -ags lib1 lib2 ... libn

ags control ags to specify the operation of liblist.

G list all .g les in the current directory and along the src path.

D create gfile.lst using all .g les in the current directory and along the

src path.

C convert .g les to .src les and list the les in srcfile.lst.

L list the contents of the specied libraries.

N list library names.

P send listing to printer (lpt1).

F use page breaks and form feed characters.

I assume complex library extensions (.lcg).

279

20. UTILITY: LIBLIST

The search is performed in the following manner:

1. List all symbols available as .g les in the current directory and then the

src path.

2. List all symbols dened in .l32 les (.lcg les if you included the I control ag)

in the lib path subdirectory. gauss.lcg, if it exists, will be listed last.

20.1 Report Format

The listing produced will go to the standard output. The order the symbols will be

listed in is the same order that they will be found by GAUSS, except that liblist

processes the .lcg les in the order they appear in the lib path subdirectory, whereas

GAUSS processes libraries according to the order specied in your library statement.

liblist assumes that all of your libraries are active, i.e., you have listed them all in a

library statement. gauss.lcg will be listed last.

The listing looks like this:

Symbol Type File Library Path

====================================================================

1. autoreg ------ autoreg .src auto.lcg /gauss/src

2. autoprt ------ autoreg .src auto.lcg /gauss/src

3. autoset ------ autoreg .src auto.lcg /gauss/src

4. _pticout matrix pgraph .dec pgraph.lcg /gauss/src

5. _pzlabel string pgraph .dec pgraph.lcg /gauss/src

6. _pzpmax matrix pgraph .dec pgraph.lcg /gauss/src

7. asclabel proc pgraph .src pgraph.lcg /gauss/src

8. fonts proc pgraph .src pgraph.lcg /gauss/src

9. graphset proc pgraph .src pgraph.lcg /gauss/src

10. _svdtol matrix svd .dec gauss.lcg /gauss/src

12. __maxvec matrix system .dec gauss.lcg /gauss/src

13. besselj proc bessel .src gauss.lcg /gauss/src

14. bessely proc bessel .src gauss.lcg /gauss/src

15. xcopy keyword dos .src gauss.lcg /gauss/src

16. atog keyword dos .src gauss.lcg /gauss/src

Symbol is the symbol name available to the autoloader.

Type is the symbol type. If the library is not strongly typed, this will be a line of

dashes.

File is the le the symbol is supposed to be dened in.

Library is the name of the library, if any, the symbol is listed in.

Path is the path the le is located on. If the le cannot be found, the path will be

*** not found ***.

280

U

t

i

l

i

t

i

e

s

20. UTILITY: LIBLIST

20.2 Using liblist

liblist is executed from the operating system or GAUSS with:

liblist -ags lib1 lib2 ... libn

To put the listing in a le called lib.lst:

liblist -l > lib.lst

To convert all your .g les and list them in srcfile.lst:

liblist -c

The numbers are there so you can sort the listing if you want and still tell which

symbol would be found rst by the autoloader. You may have more than one symbol

by the same name in dierent les. liblist can help you keep them organized so you

dont inadvertently use the wrong one.

281

20. UTILITY: LIBLIST

282

C

a

t

e

g

o

r

i

c

a

l

R

e

f

e

r

e

n

c

e

Chapter 21

Categorical Reference

This categorical reference lists those commands that either operate dierently under

GAUSS for UNIX than other platforms, or are supported only under GAUSS for

UNIX. For a general categorical reference of commands, see chapter ??.

21.1 Window Control

WinOpenPQG Open a PQG window.

WinOpenText Open a Text window.

WinOpenTTY Open a TTY window.

WinSetActive Set the active window.

WinGetActive Get the active window.

WinMove Move a window.

WinResize Resize a window.

WinPan Pan through a window.

WinRefresh Refresh a window.

WinRefreshArea Refresh a rectangular area of a Text window.

WinClose Close a window.

WinCloseAll Close all windows except Window 1

WinSetTextWrap Set the text wrap mode for a window.

WinSetRefresh Set the refresh mode for a window.

WinGetAttributes Get attributes for a window.

283

21. CATEGORICAL REFERENCE

21.2 Console I/O

con Request input, create matrix.

cons Request input, create string.

key Return the next key in the input buer of the active

window. If none are pending, return 0.

keyw Return the next key in the input buer of the active

window. If none are pending, wait for one.

wait Wait until a key is pressed in the active window.

waitc Flush input buer of the active window, then wait until a

key is pressed in it.

key can be used to trap most keystrokes. For example, the following loop will trap the

ALT-H key combination:

kk = 0;

do until kk == 1035;

kk = key;

if not key;

sleep(0.5);

endif;

endo;

Other key combinations, function keys and cursor key movement can also be trapped.

key and keyw have the same return values.

21.3 Output

WinSetCursor Set the cursor position for a window.

WinGetCursor Get the cursor position for a window.

WinPrint Print formatted data to a window.

WinClear Clear a window.

WinClearArea Clear a rectangular area of a Text window.

WinClearTTYLog Clear the output log of a TTY window.

WinPrintPQG Print PQG graph to le or printer.

WinZoomPQG Display enlarged area of PQG graph.

WinSetColorCells Set color cell RGB values for a window.

WinGetColorCells Get color cell RGB values for a window.

WinSetForeground Set the foreground color for a window.

284

C

a

t

e

g

o

r

i

c

a

l

R

e

f

e

r

e

n

c

e

21. CATEGORICAL REFERENCE

WinSetBackground Set the background color for a window.

WinSetColormap Select a standard colormap for a window.

FontLoad Load a system font.

FontUnload Unload a system font.

FontUnloadAll Unload all system fonts.

output Open/close auxiliary output for the active window.

outwidth Set line width of auxiliary output for the active window.

print Print formatted data to the active window.

printdos Print string to the active window (calls C printf()),

emulate ANSI.SYS commands.

printfm Print matrix to the active window, use specied format.

print on[o Turn auto print on/o for the active window.

screen on[o Direct/suppress print statements to the active window.

screen out Dump snapshot of the active window to its auxiliary output.

plot Draw text style XY plot in the active window.

plotsym Set symbol used for plot in the active window.

cls Clear the active window.

font Set font to be used in the active window.

color Set foreground, background / colorcells for the active window.

csrcol Get column position of cursor in the active window.

csrlin Get line (row) position of cursor in the active window.

csrtype Sets the cursor shape.

format Dene print format for the active window.

locate Position the cursor in the active window.

tab Tab the cursor in the active window.

scroll Scroll a section of the active window.

setvmode Set the active window to emulate DOS video mode.

The results of all printing may be sent to an output le using output. This le can

then be printed or ported as an ASCII le to other software. A separate output le can

be opened for each window.

locate acts like tab in TTY windows. The row argument is ignored.

scroll is supported only for Text windows.

21.4 Error Handling and Debugging

errorlog Send error message to Window 1 and error log le.

285

21. CATEGORICAL REFERENCE

21.5 Workspace Management

new Clear current workspace, close all windows except Window 1.

21.6 Program Control

end Terminate a program, close all windows except Window 1.

stop Terminate a program, leave all windows open.

system Quit GAUSS and return to the OS.

Both stop and end terminate the execution of a program. end closes all open windows

except for Window 1; stop leaves all windows open. Neither stop or end is required to

terminate a GAUSS program; if neither is found, an implicit stop is executed.

286

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

Chapter 22

Command Reference

The command reference is broken into two sections. This rst section details commands

that operate dierently under GAUSS for UNIX and GAUSS for other operating

systems. The second section denes commands that are supported only under GAUSS

for UNIX.

cls cls clears the active window. For Text windows, this means

the window buer is cleared to the background color. For TTY

windows, the current output line is panned to the top of the

window, eectively clearing the display. The output log is

still intact. To clear the output log of a TTY window, use

WinClearTTYLog. For PQG windows, the window is

cleared to the background color, and the graphics data

are discarded.

color color aects the active window. X supports foreground and

background colors. The color command makes no distinction

between text and pixel colors; both aect the foreground color

of the active window. If both a pixel color and text color are

specied, the pixel color will be ignored, and the text color

will be used to set the foreground color.

287

22. COMMAND REFERENCE

con con gets input from the active window. If you are working

in terminal mode, GAUSS will not see any input until you

press Enter, so follow each entry with an Enter.

cons cons gets input from the active window. If you are working

in terminal mode, GAUSS will not see your input until you

press Enter.

csrcol csrcol returns the cursor column for the active window.

For Text windows, this value is the cursor column with respect

to the text buer. For TTY windows, this value is the cursor

column with respect to the current output line.

For PQG windows, this value is meaningless.

csrlin csrlin returns the cursor line for the active window.

For Text windows, this value is the cursor row with respect

to the text buer. For TTY windows, this value is the current

output line number (i.e., the number of lines logged + 1).

For PQG windows, this value is meaningless.

end end closes all windows except window 1. If you want to leave a

programs windows open, use stop.

errorlog errorlog prints to window 1 and the error log le.

format format sets the print statement format for the active window.

Each window remembers its own format, even when it is no

longer the active window.

key key gets input from the active window. If you are working

in terminal mode, key doesnt see any keystrokes until

Enter is pressed.

288

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE

keyw keyw gets the next key from the input buer of the active

window. If the input buer is empty, keyw waits for a

keystroke. If you are working in UNIX terminal mode,

GAUSS will not see any input until you press the Enter key.

locate locate locates the cursor in the active window. The row

argument is ignored for window 1 and TTY windows,

making locate act like tab in those windows.

new new closes all open windows except window 1.

output output commands aect the active window. Each window

remembers its own settings, even when it is no longer

the active window.

Each window can have its own auxiliary output le, or

several windows can write to the same output le.

outwidth outwidth aects the active window. Each window

remembers its own setting, even when it is no longer

the active window.

plot plot writes to the active window. Supported only for

Text windows.

print print writes to the active window. The refresh setting of

the window determines when output is displayed. To force

immediate display, use the /ush ag:

print /ush expr1 expr2 ...;;

289

22. COMMAND REFERENCE

print on[o print on[o aects the active window. Each window

remembers its own setting, even when it is no longer

the active window.

printdos printdos writes to the active window. The refresh setting of

the window determines when output is displayed. To force

immediate display, use the WinRefresh command.

printfm printfm writes to the active window. The refresh setting of

the window determines when output is displayed. To force

immediate display, use the WinRefresh command.

screen on[o screen on[o aects the active window. Each window

remembers its own setting, even when it is no longer

the active window.

screen out screen out aects the active window. Not supported for

PQG windows.

scroll scroll scrolls a region of the active window. Supported

only for Text windows.

setvmode setvmode aects the active window. This command forces

the active window into a DOS emulation mode, and is

supported for backwards compatibility only. Window size,

resolution, font and/or colormap may be changed to

accomodate the requested video mode. Not supported for

window 1 and TTY windows.

stop stop does not close any windows. If you want to close a

290

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE

programs windows when it is done, use end.

tab tab tabs the cursor in the active window. tab is not supported

in terminal mode.

wait wait waits for a keystroke in the active window. If you are

working in terminal mode, wait doesnt see any keystrokes

until Enter is pressed.

waitc waitc ushes the input buer of the active window, then

waits for a new keystroke in the active window. If you are

working in terminal mode, waitc doesnt see any keystrokes

until Enter is pressed.

The rest of the command reference denes the commands that are supported only

under GAUSS for UNIX.

291

font 22. COMMAND REFERENCE

Purpose

Set the font for the active window.

Format

oldfonth = font(fonthandle);

Input

fonthandle scalar, font handle or 1.

Output

oldfonth scalar, handle of previous font.

Remarks

font sets the font for the active window to fonthandle and returns the handle of the

windows previous font in oldfonth. If fonthandle = 1, font returns the current font

handle without changing it.

font is not supported for PQG windows.

292

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE FontLoad

Purpose

Load a font.

Format

fonthandle = FontLoad(fontspec);

Input

fontspec string, font specication.

Output

fonthandle scalar, font handle.

Remarks

FontLoad loads the X11 font specied in fontspec, where fontspec is a standard X11

font name, and may contain the wildcard characters and ?.

If the font is successfully loaded, FontLoad returns a GAUSS font handle which is used

in other routines (e.g., font, WinGetAttributes) to refer to the font.

If the font requested cannot be loaded, FontLoad returns a 1.

Font handles 1 through 4 are reserved by GAUSS; font handles returned by FontLoad

are 5.

293

FontUnload 22. COMMAND REFERENCE

Purpose

Unload a font.

Format

ret = FontUnload(fonthandle);

Input

fonthandle scalar, font handle.

Output

ret scalar, 0 if call is successful, 1 if it fails.

Remarks

FontUnload unloads the font specied by fonthandle, freeing the memory associated

with using it. If the font is still in use by a window, FontUnload will run successfully,

but the font will be maintained internally until the window relinquishes it. Then it will

be unloaded.

When a font is unloaded, you should set its handle to zero, to let your program know

that it no longer refers to a valid font. The best way to do this is:

fonthandle = FontUnload(fonthandle);

Font handles 1 through 4 are reserved by GAUSS, and cannot be unloaded.

294

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE FontUnloadAll

Purpose

Unload all currently loaded fonts.

Format

FontUnloadAll;

Remarks

FontUnloadAll unloads all the currently loaded fonts, freeing the memory associated

with using them. If any of the fonts are still in use by any windows, FontUnloadAll will

run successfully, but the fonts in use will be maintained internally until relinquished.

Then they will be unloaded.

When fonts are unloaded, you should set their handles to zero, to let your program

know that they no longer refer to valid fonts. The easiest way to do this is:

clear f1, f2[,f3...];

Font handles 1 through 4 are reserved by GAUSS, and cannot be unloaded.

295

WinClear 22. COMMAND REFERENCE

Purpose

Clear a window.

Format

WinClear(whandle);

Input

whandle scalar, window handle.

Remarks

WinClear clears the window to the background color. The eect of WinClear on

window data depends upon the window type, as follows:

If whandle is a PQG window, the current graphics data are discarded. The image can

only be restored by repeating the sequence of commands that originally generated it.

If whandle is a Text window, its text buer is cleared, destroying all data for the

window. The previous contents of the window can only be restored by repeating the

sequence of commands that originally generated it.

If whandle is a TTY window, the current output line is panned to the top of the

window. Window data is not aected.

See also

WinClearTTYLog

296

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinClearArea

Purpose

Clear a rectangular region of a Text window.

Format

WinClearArea(whandle,row,col ,nrows,ncols);

Input

whandle scalar, window handle.

row scalar, the topmost row to clear.

col scalar, the leftmost column to clear.

nrows scalar, the number of rows to clear.

ncols scalar, the number of columns to clear.

Remarks

WinClearArea clears a rectangular region of a Text window to the background color.

The region has its top-left corner at (row,col ), and is nrowsncols in size.

The corresponding region of the text buer is cleared, destroying all data for the

region. The previous contents of the region can only be restored by repeating the

sequence of commands that originally generated it.

WinClearArea is supported only for Text windows.

297

WinClearTTYLog 22. COMMAND REFERENCE

Purpose

Clear the output log of a TTY window.

Format

WinClearTTYLog(ttywhandle);

Input

ttywhandle scalar, window handle of a TTY window.

Remarks

WinClearTTYLog deletes the output log of a TTY window, destroying the window

data. The window is automatically cleared and refreshed.

See also

WinClear

298

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinClose

Purpose

Close a window.

Format

ret = WinClose(whandle);

Input

whandle scalar, window handle.

Output

ret scalar 0.

Remarks

WinClose closes (destroys) the window specied by whandle. When a window is closed,

GAUSS destroys all of the internal information required to maintain the window. Any

further commands which reference whandle will result in an error.

When a window is closed, the window handle should be set to to zero, to let your

program know that it no longer refers to a valid window. The easiest way to do this is:

wh = WinClose(wh);

If you close the active window, you will have no active window. To set a new one, use

WinSetActive.

Window 1 cannot be closed.

299

WinCloseAll 22. COMMAND REFERENCE

Purpose

Close all windows except window 1.

Format

WinCloseAll;

Remarks

WinCloseAll closes all open windows except window 1.

You should set the aected window handles to zero after a WinCloseAll, to let your

program know that they no longer refer to valid windows. The easiest way to do this is:

clear wh1, wh2 [,wh3...];

If window 1 is not the active window, you will have no active window. To set a new

one, use WinSetActive.

The end command also closes all open windows (except window 1). If you want to

terminate a program but leave its windows open, use stop.

300

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinGetActive

Purpose

Get the active window.

Format

whandle = WinGetActive;

Output

whandle scalar, the active window handle.

Remarks

WinGetActive returns the window handle of the active window. If there is no active

window, WinGetActive returns a 1.

301

WinGetAttributes 22. COMMAND REFERENCE

Purpose

Get window attributes.

Format

wattr = WinGetAttributes(whandle);

Input

whandle scalar, window handle.

Output

wattr 251 vector, window attributes, or scalar -1 if error.

PQG Window

[1] X window position in pixels

[2] Y window position in pixels

[3] X window size in pixels

[4] Y window size in pixels

[5] unused

[6] unused

[7] unused

[8] colormap

[9] foreground color

[10] background color

[11] aspect ratio attribute

[12] unused

[13] resizing attribute

[14] x pixel at left edge

[15] y pixel at top edge

[16] GAUSS window handle

[17] system window handle

[18] active window ag

[19] window type

[20] unused

[21] unused

[22] unused

302

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinGetAttributes

[23] bits per pixel

[24] unused

[25] unused

Text Window

[1] X window position in pixels

[2] Y window position in pixels

[3] window rows

[4] window columns

[5] buer rows

[6] buer columns

[7] font (handle)

[8] colormap

[9] foreground color

[10] background color

[11] text wrapping mode

[12] automatic refresh mode

[13] resizing attribute

[14] buer row at top of window

[15] buer column at left side of window

[16] GAUSS window handle

[17] system window handle

[18] active window ag

[19] window type

[20] cursor text row

[21] cursor text column

[22] cursor type

[23] bits per pixel

[24] character height in pixels

[25] character width in pixels

TTY Window

[1] X window position in pixels

[2] Y window position in pixels

[3] window rows

303

WinGetAttributes 22. COMMAND REFERENCE

[4] window columns

[5] number of lines to log

[6] number of lines logged

[7] font (handle)

[8] colormap

[9] foreground color

[10] background color

[11] text wrapping mode

[12] automatic refresh mode

[13] resizing attribute

[14] buer line at top of window

[15] buer column at left of window

[16] GAUSS window handle

[17] system window handle

[18] active window ag

[19] window type

[20] cursor text row (number of lines logged+1)

[21] cursor text column

[22] cursor type

[23] bits per pixel

[24] character height in pixels

[25] character width in pixels

Remarks

WinGetAttributes returns the attributes of the window specied by whandle. If

whandle is 1, the attributes of the GAUSS command window are returned. If whandle

is 2, the attributes of the GAUSS help window are returned.

wattr[1] and wattr[2] indicate the position on the display of the upper left corner of the

window border (i.e., the border the window manager supplies).

wattr[3] and wattr[4] indicate the size of the window. For PQG windows, these values

are given in pixels, for Text and TTY windows, these values are given in rows and

columns.

wattr[8] is the colormap number as specied in the WinSetColormap command.

For a PQG window, wattr[11] indicates whether the aspect ratio is xed or not. For

Text and TTY windows it indicates how text is wrapped. wattr[12] indicates how the

window is refreshed. wattr[13] indicates how the window can be resized.

304

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinGetAttributes

wattr[14] and wattr[15] indicate the buer coordinates at the upper left corner of Text

windows. For TTY windows, wattr[14] indicates the line of the output log displayed at

the top of the window.

wattr[16], the GAUSS window handle, is the handle ID assigned by GAUSS. wattr[17],

the system window handle, is the handle ID assigned by the window manager. All

GAUSS functions that take a window handle expect a GAUSS window handle.

wattr[18] indicates whether this window is the active window (1 = true, 0 = false).

wattr[22] is the cursor type number as specied in the csrtype command.

See WinOpenPQG, WinOpenText, and WinOpenTTY for details on window

attributes.

305

WinGetColorCells 22. COMMAND REFERENCE

Purpose

Get normalized RGB values from a window colormap.

Format

rgb = WinGetColorCells(whandle,cellidx);

Input

whandle scalar, window handle.

cellidx N1 vector, color cell indices.

Output

rgb N3 matrix, RGB settings of color cells.

Remarks

Each row of rgb contains the RGB values for the color cell specied in the

corresponding row of cellidx. The RGB values are normalized to range from 0.0 (black)

to 1.0 (full intensity). The columns are laid out as follows:

[.,1] red values

[.,2] green values

[.,3] blue values

If any row of cellidx contains an invalid color cell index, the corresponding row of rgb

will contain 1 in each column.

306

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinGetCursor

Purpose

Get the cursor position for a Text or TTY window.

Format

{ r,c } = WinGetCursor(whandle);

Input

whandle scalar, window handle.

Output

r scalar, cursor row position.

c scalar, cursor column position.

Remarks

If whandle is a Text window, (r,c) species the location of the cursor in the window

buer. If whandle is a TTY window, r species the current output line (i.e., the

number of lines logged + 1), c species the cursor location on that line. If whandle is a

PQG window, r and c are meaningless.

For a Text window, the upper left corner of the buer is (1,1). For a TTY window, the

rst column of the line is column 1.

307

WinMove 22. COMMAND REFERENCE

Purpose

Move a window.

Format

WinMove(whandle,x,y);

Input

whandle scalar, window handle.

x scalar, X window position in pixels.

y scalar, Y window position in pixels.

Remarks

WinMove moves the window specied by whandle to the position (x,y). (x,y) species

the position on the display of the upper left corner of the window border (i.e., the

border supplied by the window manager). The upper left corner of the display is (0,0).

(x,y) can specify an o-screen location.

To use the current value of x or y, set that argument to a missing value.

308

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinOpenPQG

Purpose

Open a PQG graphics window.

Format

whandle = WinOpenPQG(wattr,wtitle,ititle);

Input

wattr 131 vector, window attributes.

[1] X window position in pixels.

[2] Y window position in pixels.

[3] X window size in pixels.

[4] Y window size in pixels.

[5] unused.

[6] unused.

[7] unused.

[8] colormap.

[9] foreground color.

[10] background color.

[11] aspect ratio attribute.

[12] unused.

[13] resizing attribute.

wtitle string, window title.

ititle string, icon title.

Output

whandle scalar, window handle.

Remarks

wattr[1] and wattr[2] specify the position on the display of the upper left corner of the

window border (i.e., the border supplied by the window manager). The upper left

corner of the display is (0,0).

wattr[8] species the colormap for the window. See WinSetColormap for the list of

valid colormap values.

309

WinOpenPQG 22. COMMAND REFERENCE

wattr[11], the aspect ratio attribute, determines whether the aspect ratio of the window

is maintained during resize and zoom actions:

0 aspect ratio can change

1 aspect ratio is xed

The aspect ratio attribute cannot be changed.

wattr[13], the resizing attribute, controls the resizing of the window as follows:

0 the window cannot be resized

1 the window can be resized only through a WinResize call

2 the window can be resized through a WinResize call or external event

(e.g., resizing with the mouse)

The resizing attribute cannot be changed.

Default values are dened for the elements of wattr as follows:

[1] 0 window position: (0, 0)

[2] 0

[3] 640 window size: 640 480

[4] 480

[5] 0 unused

[6] 0 unused

[7] 1 unused

[8] 6 colormap: 16 color

[9] 15 foreground color: white

[10] 0 background color: black

[11] 1 xed aspect ratio

[12] 0 unused

[13] 2 resize by function or mouse

To use the default value for any attribute, set that element to a missing value.

WinOpenPQG returns a 1 if it fails to open the window.

Note that opening a window does not make it the active window.

310

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinOpenText

Purpose

Open a Text window.

Format

whandle = WinOpenText(wattr,wtitle,ititle);

Input

wattr 131 vector, window attributes.

[1] X window position in pixels.

[2] Y window position in pixels.

[3] window rows.

[4] window columns.

[5] buer rows.

[6] buer columns.

[7] font (handle).

[8] colormap.

[9] foreground color.

[10] background color.

[11] text wrapping mode.

[12] automatic refresh mode.

[13] resizing attribute.

wtitle string, window title.

ititle string, icon title.

Output

whandle scalar, window handle.

Remarks

wattr[1] and wattr[2] specify the position on the display of the upper left corner of the

window border (i.e., the border supplied by the window manager). The upper left

corner of the display is (0,0).

wattr[8] species the colormap for the window. See WinSetColormap for the list of

valid colormap values.

311

WinOpenText 22. COMMAND REFERENCE

wattr[11], the text wrapping mode, controls how text is wrapped in the window buer

as follows:

0 text is word-wrapped

1 text is character-wrapped

2 text is clipped

The text wrapping mode can be changed with WinSetTextWrap.

wattr[12], the automatic refresh mode, controls how the window display is refreshed as

follows:

0 the display is refreshed whenever a newline (\n) is output

1 the display is refreshed whenever anything is output

2 the display is never automatically refreshed; you must explicitly

refresh it

The refresh mode can be changed with WinSetRefresh.

wattr[13], the resizing attribute, controls the resizing of the window as follows:

0 the window cannot be resized

1 the window can be resized only through a WinResize call

2 the window can be resized through a WinResize call or external event

(e.g., resizing with the mouse)

The resizing attribute cannot be changed.

Default values are dened for the elements of wattr as follows:

[1] 0 window position: (0, 0)

[2] 0

[3] 25 window size: 25 80

[4] 80

[5] 25 buer size: 25 80

[6] 80

[7] 1 system default font

[8] 0 system default colormap

[9] 1 system foreground color

[10] 0 system background color

[11] 1 character wrap

[12] 0 refresh on \n

[13] 2 resize by function or mouse

To use the default value for any attribute, set that element to a missing value.

WinOpenText returns a 1 if it fails to open the window.

Note that opening a window does not make it the active window.

312

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinOpenTTY

Purpose

Open a TTY window.

Format

whandle = WinOpenTTY(wattr,wtitle,ititle);

Input

wattr 131 vector, window attributes.

[1] X window position in pixels.

[2] Y window position in pixels.

[3] window rows.

[4] window columns.

[5] number of lines to log.

[6] unused.

[7] font (handle).

[8] colormap.

[9] foreground color.

[10] background color.

[11] text wrapping mode.

[12] automatic refresh mode.

[13] resizing attribute.

wtitle string, window title.

ititle string, icon title.

Output

whandle scalar, window handle.

Remarks

wattr[1] and wattr[2] specify the position on the display of the upper left corner of the

window border. The upper left corner of the display is (0,0).

wattr[8] species the colormap for the window. See WinSetColormap for the list of

valid colormap values.

313

WinOpenTTY 22. COMMAND REFERENCE

wattr[11], the text wrapping mode, controls how text is wrapped in the window as

follows:

0 text is word-wrapped

1 text is character-wrapped

2 text is clipped

The text wrapping mode can be changed with WinSetTextWrap.

wattr[12], the automatic refresh mode, controls how the window display is refreshed as

follows:

0 the display is refreshed whenever a newline (\n) is output

1 the display is refreshed whenever anything is output

2 the display is never automatically refreshed; you must explicitly

refresh it

The refresh mode can be changed with WinSetRefresh.

wattr[13], the resizing attribute, controls the resizing of the window as follows:

0 the window cannot be resized

1 the window can be resized only through a WinResize call

2 the window can be resized through a WinResize call or external event

(e.g. resizing with the mouse)

The resizing attribute cannot be changed.

Default values are dened for the elements of wattr as follows:

[1] 0 window position: (0, 0)

[2] 0

[3] 25 window size: 25 80

[4] 80

[5] 500 log 500 lines

[6] 0 unused

[7] 1 system default font

[8] 0 system default colormap

[9] 1 system foreground color

[10] 0 system background color

[11] 1 character wrap

[12] 0 refresh on \n

[13] 2 resize by function or mouse

To use the default value for any attribute, set that element to a missing value.

WinOpenTTY returns a 1 if it fails to open the window.

Note that opening a window does not make it the active window.

314

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinPan

Purpose

Pan through a Text or TTY window.

Format

WinPan(whandle,r,c);

Input

whandle scalar, window handle.

r scalar, number of rows to pan.

c scalar, number of columns to pan.

Remarks

WinPan pans through the contents of the window specied by whandle. To pan up and

left, use negative r and c. To pan down and right, use positive r and c.

WinPan is not supported for PQG windows.

315

WinPrint 22. COMMAND REFERENCE

Purpose

Print to a specied window.

Format

WinPrint [[/ush]] [[/typ]] [[/fmted]] [[/mf ]] [[/jnt]] whandle [[expr1 expr2...]];[[;]]

Input

whandle scalar, window handle.

Remarks

WinPrint and the print statement have exactly the same syntax and behavior, except

that WinPrint prints to a specied window, and print prints to the active window.

WinPrint is not supported for PQG windows.

316

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinPrintPQG

Purpose

Prints a PQG graph to a le or the printer.

Format

WinPrintPQG(whandle,prtopts);

Input

whandle scalar, window handle.

prtopts string, print options.

WinPrintPQG prints the graphics data for whandle to the system printer, or to a le, if

one is specied in prtopts.

prtopts consists of a series of option ags and their settings. Separate items in prtopts

with spaces.

The following ags and settings are dened:

-f output le name, any valid lename. File must be writeable.

-o print orientation.

L landscape

P portrait

-t printer/le type.

PS PostScript

EPS Encapsulated PostScript

HPLJET3 HP LaserJet III, IIID

HPGL Hewlett-Packard Graphics Language

PIC Lotus PIC

The le prndev.tbl in the $GAUSSHOME directory lists additional

printer/le types that are available but not tested. You can try any of the

types listed there except the type 4 entries (i.e., those with a 4 in the

second eld), which are not supported.

-r print resolution.

1 low resolution

2 medium resolution

3 high resolution

4 maximum resolution

317

WinPrintPQG 22. COMMAND REFERENCE

-m print margins, specied in inches.

left,right,top,bottom

This is a list of four decimal values. Separate margin values with commas.

Do not put any white space between values.

Example:

-m .5,.5,.5,.75

-c print color mode.

BW black/white

GRAY gray scale

RGB 16 color

-a print aspect ratio.

F xed

V variable

-g print placement.

TL top left

T top

TR top right

L left

C center

R right

BL bottom left

B bottom

BR bottom right

Flags and settings are case-sensitive.

Print options not specied in prtopts are set to their values in .gaussrc. prtopts can

be a null string.

WinPrintPQG is supported only for PQG windows.

Example

WinPrintPQG(wh, -f /tmp/graph.out -o P -t EPS);

WinPrintPQG(wh, -m 1,1,1,1.5 -a V -r 1);

WinPrintPQG(wh, -a F -g TL -m 1,1,1,4);

318

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinRefresh

Purpose

Refresh a window.

Format

WinRefresh(whandle);

Input

whandle scalar, window handle.

Remarks

WinRefresh redraws the window specied by whandle using the current contents of the

windows graphics data, text buer or output log, depending upon the window type.

This is the only way to update windows with an automatic refresh

mode = [no refresh].

319

WinRefreshArea 22. COMMAND REFERENCE

Purpose

Refresh a rectangular region of a Text window.

Format

WinRefreshArea(whandle,row,col ,nrows,ncols);

Input

whandle scalar, window handle.

row scalar, top row of area in buer to refresh.

col scalar, left column of area in buer to refresh.

nrows scalar, number of rows to refresh.

ncols scalar, number of cols to refresh.

Remarks

WinRefreshArea redraws a rectangular region of the Text window using the current

contents of the text buer. The region has its top-left corner at (row,col ), and is

nrowsncols in size.

320

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinResize

Purpose

Resize a window.

Format

WinResize(whandle,height ,width);

Input

whandle scalar, window handle.

height scalar, window height.

width scalar, window width.

Remarks

WinResize changes the size of the window specied by whandle. The position of the

upper left corner of the window remains xed.

For PQG windows, height and width are specied in pixels. The nal size of the window

may dier from the requested size. If the window was opened with xed aspect ratio,

the width will be used to calculate the height required to maintain the correct ratio.

For Text and TTY windows, height and width are specied in characters. (Thus, the

actual requested size of the window is dependent upon the window font. ) For Text

windows, the size of the window cannot be larger than the text buer.

height and width can be nonintegral, but will be truncated to integers..

To use the current value of height or width, set that argument to a missing value.

321

WinSetActive 22. COMMAND REFERENCE

Purpose

Set the active window.

Format

whout = WinSetActive(whin);

Input

whin scalar, window handle or 1.

Output

whout scalar, window handle.

Remarks

WinSetActive sets the active window to whin and returns the handle of the previous

active window in whout . If whin is 1, the active window is deactivated.

If there was no previous active window, WinSetActive returns a 1.

322

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinSetBackground

Purpose

Set the background color for the specied window.

Format

oldback = WinSetBackground(whandle,color);

Input

whandle scalar, window handle.

color scalar, color index or 1.

Output

oldback scalar, previous background color index.

Remarks

WinSetBackground sets the background color index for whandle to color and returns

the previous background color index. If color is 1, the current background color index

is returned.

323

WinSetColorCells 22. COMMAND REFERENCE

Purpose

Set one or more cells in a windows colormap.

Format

ret = WinSetColorCells(whandle,cellidx,colorspec);

Input

whandle scalar, window handle.

cellidx N1 vector, color cell indices.

colorspec N3 matrix, color specications.

Output

ret scalar, 0 if call is successful, 1 if one or more colors cant be found.

Remarks

The columns of colorspec are interpreted as follows:

[.,1] red values

[.,2] green values

[.,3] blue values

Color values can range from 0.0 (black) to 1.0 (full intensity). Values < 0.0 will be

treated as 0.0, values > 1.0 will be treated as 1.0.

Due to the X11 color handling protocol, WinSetColorCells has to regard the contents

of colorspec as color suggestions rather than color commands, but it will always give

you colors as close to the settings of colorspec as it can. See Chapter 3 for details.

WinSetColorCells attempts to change the RGB values for the specied color cells. If it

succeeds in setting all of them, it returns a 0. If it fails to set all of them specically,

if cellidx or colorspec contain any invalid values, or the system fails to reset the color

cell WinSetColorCells returns a 1.

324

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinSetColormap

Purpose

Set the colormap for a window.

Format

mapinfo = WinSetColormap(whandle,cmap);

Input

whandle scalar, window handle.

cmap scalar, colormap number or 1.

The supported colormaps are:

0 System Color

1 System BW

2 True BW

3 4 Gray

4 4 Color

5 16 Gray

6 16 Color

7 64 Gray

8 256 Color

Output

mapinfo 31 vector, colormap information.

mapinfo[1] number of colors in colormap

mapinfo[2] number of bits per pixel

mapinfo[3] current colormap number

Remarks

WinSetColormap sets the colormap for the window whandle to cmap, and returns

information about the selected colormap. If cmap = 1, no changes are made, but the

information for the current colormap is returned.

On error, scalar 0 is returned.

325

WinSetCursor 22. COMMAND REFERENCE

Purpose

Set the cursor position for a Text or TTY window.

Format

WinSetCursor(whandle,r,c);

Input

whandle scalar, window handle.

r scalar, cursor row.

c scalar, cursor column.

Remarks

If whandle is a Text window, (r,c) species where to locate the cursor in the window

buer. If whandle is 1 or a TTY window, r is ignored, and c species where to locate

the cursor on the current line.

For a Text window, the upper left corner of the buer is (1,1). For a TTY window, the

rst column of a line is column 1.

(r,c) can specify a location that is outside the buer. You can think of the buer as

covering a small region in text coordinate space; text written within the buer

bounds is remembered, text written outside it is lost.

Note that there is no right-hand boundary in a TTY window. So, if you locate to

column 254328 and begin printing, GAUSS will attempt to allocate enough memory to

store a 254K line of output.

r and c are truncated if they are not integers.

WinSetCursor is not supported for PQG windows.

326

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinSetForeground

Purpose

Set the foreground color for the specied window.

Format

oldfore = WinSetForeground(whandle,color);

Input

whandle scalar, window handle.

color scalar, color index or 1.

Output

oldfore scalar, previous foreground color index.

Remarks

WinSetForeground sets the foreground color index for whandle to color and returns

the previous foreground color index. If color is 1, the current foreground color index

is returned.

327

WinSetRefresh 22. COMMAND REFERENCE

Purpose

Set the refresh mode for a window.

Format

oldref = WinSetRefresh(whandle,refresh);

Input

whandle scalar, window handle.

refresh scalar, refresh mode.

Output

oldref scalar, previous refresh mode.

Remarks

refresh can be one of the following:

0 refresh on newline (\n); this is the system default

1 refresh on any output

2 refresh only on WinRefresh call

To get the current refresh mode, call WinGetAttributes.

WinSetRefresh is not supported for window 1 or PQG windows.

328

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

22. COMMAND REFERENCE WinSetTextWrap

Purpose

Set the text wrapping mode for a window.

Format

oldtwrap = WinSetTextWrap(whandle,textwrap);

Input

whandle scalar, window handle.

textwrap scalar, text wrapping mode.

Output

oldtwrap scalar, previous text wrapping mode.

Remarks

textwrap can be one of the following:

0 text is word-wrapped

1 text is character-wrapped

2 text is clipped

For Text windows, the text wrapping mode species how lines are stored in the window

buer. For TTY windows, the text wrapping mode species how lines are displayed in

the window. Thus, for Text windows, clipped output is actually lost, as is output that

scrolls o the top of the buer; for TTY windows, clipped output is merely displayed

dierently than wrapped output.

To get the current text wrap mode, call WinGetAttributes.

WinSetTextWrap is not supported for PQG windows.

329

WinZoomPQG 22. COMMAND REFERENCE

Purpose

Display a zoomed image in a PQG window.

Format

WinZoomPQG(whandle,x,y,xsize,ysize);

Input

whandle scalar, window handle.

x scalar, x position of zoom rectangle in pixels.

y scalar, y position of zoom rectangle in pixels.

xsize scalar, x size of zoom rectangle in pixels.

ysize scalar, y size of zoom rectangle in pixels.

Remarks

WinZoomPQG displays a zoomed image of the area specied. If the PQG window has

the aspect ratio attribute set to xed, the y size of the rectangle will be adjusted as

needed to maintain the aspect ratio.

To zoom out (that is, to redisplay the entire graph in the PQG window), use:

WinZoomPQG(whandle,0,0,0,0);

WinZoomPQG provides the same capabilities as the Zoom pop-up menu available in

the PQG windows.

For more details, consult the PQG graphics section of the manual.

WinZoomPQG is supported only for PQG windows.

330

I

n

t

r

o

d

u

c

t

i

o

n

Chapter 23

Command Reference Introduction

The COMMAND REFERENCE describes each of the commands, procedures and

functions available in the GAUSS programming language. These functions can be

roughly divided into three categories:

Mathematical, statistical and scientic functions.

Data handling routines, including data matrix manipulation and description

routines, and le I/O.

Programming statements, including branching, looping, display features, error

checking, and shell commands.

The rst category contains those functions to be expected in a high level mathematical

language: trigonometric functions and other transcendental functions, distribution

functions, random number generators, numerical dierentiation and integration

routines, Fourier transforms, Bessel functions and polynomial evaluation routines. And,

as a matrix programming language, GAUSS includes a variety of routines which

perform standard matrix operations. Among these are routines to calculate

determinants, matrix inverses, decompositions, eigenvalues and eigenvectors, and

condition numbers.

Data handling routines include functions which return dimensions of matrices, and

information about elements of data matrices, including functions to locate values lying

in specic ranges or with certain values. Also under data handling routines fall all

those functions which create, save, open and read from and write to GAUSS data sets.

A variety of sorting routines which will operate on both numeric and character data are

also available.

Programming statements are all of the commands which make it possible to write

complex programs in GAUSS. These include conditional and unconditional branching,

looping, le I/O, error handling, and system-related commands to execute OS shells

and access directory and environment information.

331

23. COMMAND REFERENCE INTRODUCTION

23.1 Using This Manual

Users who are new to GAUSS should make sure they have familiarized themselves with

Chapter 7 in Volume I before proceeding here. That chapter contains the basics of

GAUSS programming.

In all, there are over 400 routines described in this manual. We suggest that new

GAUSS users skim through Chapter 24, and then browse through the main part of this

manual, the COMMAND REFERENCE section. Here, the user can familiarize him or

herself with the kinds of tasks that GAUSS can handle easily.

Chapter 24 gives a categorical listing of all functions in the COMMAND REFERENCE

section, and a short discussion of the functions in each category. Complete syntax,

description of input and output arguments, and general remarks regarding each

function are given in the COMMAND REFERENCE section.

If a function is an extrinsic (i.e., part of the Run-Time Library), its source code can be

found on the src subdirectory. The name of the le containing the source code is given

in the COMMAND REFERENCE under the discussion of that function.

23.2 Global Control Variables

Several GAUSS functions use global variables to control various aspects of their

performance. The les gauss.ext, gauss.dec and gauss.lcg contain the external

statements, declare statements, and library references to these globals. All globals used

by the GAUSS Run-Time library begin with an underscore .

Default values for these common globals can be found in the le gauss.dec, located on

the src subdirectory. The default values can be changed by editing this le. See

Section 23.2.1 for information on how to change default values.

23.2.1 Changing the Default Values

To permanently change the default setting of a common global, two les need to be

edited: gauss.dec and gauss.src.

To change the value of the common global output from 2 to 0, for example, edit the

le gauss.dec and change the statement

declare matrix __output = 2;

so it reads:

332

I

n

t

r

o

d

u

c

t

i

o

n

23. COMMAND REFERENCE INTRODUCTION

declare matrix __output = 0;

Also, edit the procedure gausset, located in the le gauss.src, and modify the

statement

__output = 2;

similarly.

23.2.2 The Procedure gausset

The global variables aect your program, even if you have not set them directly in a

particular command le. If you have changed them in a previous run, they will retain

their changed values until you exit GAUSS or execute the new command.

The procedure gausset will reset the Run-Time Library globals to their default values.

gausset;

If your program changes the values of these globals, you can use gausset to reset them

whenever necessary. gausset resets the globals as a whole; you can write your own

routine to reset specic ones.

333

23. COMMAND REFERENCE INTRODUCTION

334

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

Chapter 24

Commands by Category

24.1 Mathematical Functions

Scientic Functions

abs Returns absolute value of argument.

arccos Computes inverse cosine.

arcsin Computes inverse sine.

atan Computes inverse tangent.

atan2 Computes angle given a point x,y.

besselj Computes Bessel function, rst kind.

bessely Computes Bessel function, second kind.

cos Computes cosine.

cosh Computes hyperbolic cosine.

exp Computes the exponential function of x.

gamma Computes gamma function value.

ln Computes the natural log of each element.

lnfact Computes natural log of factorial function.

log Computes the log

10

of each element.

pi Returns .

sin Computes sine.

sinh Computes the hyperbolic sine.

sqrt Computes the square root of each element.

tan Computes tangent.

tanh Computes hyperbolic tangent.

All trigonometric functions take or return values in radian units.

335

24. COMMANDS BY CATEGORY

Dierentiation and Integration

gradp Computes rst derivative of a function.

hessp Computes second derivative of a function.

intgrat2 Integrate a 2-dimensional function over a user-dened region.

intgrat3 Integrate a 3-dimensional function over a user-dened region.

intquad1 Integrate a 1-dimensional function.

intquad2 Integrate a 2-dimensional function over a user-dened

rectangular region.

intquad3 Integrate a 3-dimensional function over a user-dened

rectangular region.

intsimp Integrate by Simpsons method.

gradp and hessp use a nite dierence approximation to compute the rst and second

derivatives. Use gradp to calculate a Jacobian.

intquad1, intquad2, and intquad3 use Gaussian quadrature to calculate the integral of

the user-dened function over a rectangular region.

To calculate an integral over a region dened by functions of x and y, use intgrat2 and

intgrat3.

To get a greater degree of accuracy than that provided by intquad1, use intsimp for

one-dimensional integration.

Linear Algebra

balance Balances a matrix.

cond Computes condition number of a matrix.

chol Computes Cholesky decomposition, X = Y

Y .

choldn Performs Cholesky downdate on an upper triangular matrix.

cholsol Solves a system of equations given the Cholesky factorization

of a matrix.

cholup Performs Cholesky update on an upper triangular matrix.

crout Computes Crout decomposition, X = LU (real matrices only).

croutp Computes Crout decomposition with row pivoting (real matrices

only).

det Computes determinant of square matrix.

detl Computes determinant of decomposed matrix.

hess Computes upper Hessenberg form of a matrix (real matrices

only).

inv Inverts a matrix.

336

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

invpd Inverts a positive denite matrix.

invswp Generalized sweep inverse.

lu Computes LU decomposition with row pivoting (real and complex

matrices).

null Computes orthonormal basis for right null space.

null1 Computes orthonormal basis for right null space.

orth Computes orthonormal basis for column space x.

pinv Generalized pseudo-inverse: Moore-Penrose.

qqr QR decomposition: returns Q

1

and R.

qqre QR decomposition: returns Q

1

, R and a permutation vector, E.

qqrep QR decomposition with pivot control: returns Q

1

, R and E.

qr QR decomposition: returns R.

qre QR decomposition: returns R and E.

qrep QR decomposition with pivot control: returns R and E.

qtyr QR decomposition: returns Q

Y and R.

qtyre QR decomposition: returns Q

Y ,R and E.

qtyrep QR decomposition with pivot control: returns Q

Y ,R and E.

qyr QR decomposition: returns QY and R.

qyre QR decomposition: returns QY , R and E.

qyrep QR decomposition with pivot control: returns QY , R and E.

qrsol Solves a system of equations Rx = b given an upper triangular

matrix, typically the R matrix from a QR decomposition.

qrtsol Solves a system of equations R

matrix, typically the R matrix from a QR decomposition.

rank Computes rank of a matrix.

rcondl Returns reciprocal of the condition number of last

decomposed matrix.

rref Computes reduced row echelon form of a matrix.

schur Computes Schur decomposition of a matrix (real matrices

only).

solpd Solves a system of positive denite linear equations.

svd Computes the singular values of a matrix.

svd1 Computes singular value decomposition, X = USV

.

svd2 Computes svd1 with compact U.

The decomposition routines are chol for Cholesky decomposition, crout and croutp for

Crout decomposition, qqrqyrep for QR decomposition, and svd, svd1, and svd2 for

singular value decomposition.

null, null1, and orth calculate orthonormal bases.

inv, invpd, solpd, cholsol, qrsol and the / operator can all be used to solve linear

systems of equations.

rank and rref will nd the rank and reduced row echelon form of a matrix.

det, detl and cond will calculate the determinant and condition number of a matrix.

337

24. COMMANDS BY CATEGORY

Eigenvalues

eig Computes eigenvalues of general matrix.

eigh Computes eigenvalues of complex Hermitian or real symmetric

matrix.

eighv Computes eigenvalues and eigenvectors of complex Hermitian

or real symmetric matrix.

eigv Computes eigenvalues and eigenvectors of general matrix.

There are four eigenvalue-eigenvector routines. Two calculate eigenvalues only, and two

calculate eigenvalues and eigenvectors. The three types of matrices handled by these

routines are:

General: eig, eigv

Symmetric or Hermitian: eigh, eighv

Polynomial Operations

polychar Computes characteristic polynomial of a square matrix.

polyeval Evaluates polynomial with given coecients.

polyint Calculates N

th

order polynomial interpolation given known

point pairs.

polymake Computes polynomial coecients from roots.

polymat Returns sequence powers of a matrix.

polymult Multiplies two polynomials together.

polyroot Computes roots of polynomial from coecients.

See also recserrc, recsercp, and conv.

Fourier Transforms

dt Computes discrete 1-D FFT.

dti Computes inverse discrete 1-D FFT.

t Computes 1- or 2-D FFT.

tn Computes 1- or 2-D FFT using prime factor algorithm.

ti Computes inverse 1- or 2-D FFT.

tm Computes multi-dimensional FFT.

tmi Computes inverse multi-dimensional FFT.

rt Computes real 1- or 2-D FFT.

338

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

rtn Computes real 1- or 2-D FFT using prime factor algorithm.

rtp Computes real 1- or 2-D FFT, returns packed format FFT.

rtnp Computes real 1- or 2-D FFT using prime factor algorithm,

returns packed format FFT.

rti Computes inverse real 1- or 2-D FFT.

rtip Computes inverse real 1- or 2-D FFT from packed format FFT.

Random Numbers

rndbeta Computes random numbers with beta distribution.

rndgam Computes random numbers with gamma distribution.

rndn Computes random numbers with Normal distribution.

rndns Computes random numbers with Normal distribution

using specied seed.

rndnb Computes random numbers with negative binomial

distribution.

rndp Computes random numbers with Poisson distribution.

rndu Computes random numbers with uniform distribution.

rndus Computes random numbers with uniform distribution

using specied seed.

rndcon Changes constant of random number generator.

rndmod Changes modulus of random number generator.

rndmult Changes multiplier of random number generator.

rndseed Changes seed of random number generator.

The random number generator can be seeded. Set the seed using rndseed or generate

the random numbers using rndus or rndns. For example:

rndseed 44435667;

x = rndu(1,1);

seed = 44435667;

x = rndus(1,1,seed);

Fuzzy Conditional Functions

feq Fuzzy ==

fge Fuzzy >=

fgt Fuzzy >

339

24. COMMANDS BY CATEGORY

e Fuzzy <=

t Fuzzy <

fne Fuzzy / =

dotfeq Fuzzy . ==

dotfge Fuzzy . >=

dotfgt Fuzzy . >

dote Fuzzy . <=

dott Fuzzy . <

dotfne Fuzzy ./ =

The global variable fcomptol controls the tolerance used for comparison. By default,

this is 1e-15. The default can be changed by editing the le fcompare.dec.

Statistical Functions

dstat Computes descriptive statistics of a data set or matrix.

conv Computes convolution of two vectors.

corrm Computes correlation matrix of a moment matrix.

corrvc Computes correlation matrix from a variance-

covariance matrix.

corrx Computes correlation matrix.

crossprd Computes cross product.

design Creates a design matrix of 0s and 1s.

meanc Computes mean value of each column of a matrix.

median Computes medians of the columns of a matrix.

moment Computes moment matrix (x

of missing values.

momentd Computes moment matrix from a data set.

ols Computes least squares regression of data set or matrix.

olsqr Computes OLS coecients using QR decomposition.

olsqr2 Computes OLS coecients, residuals, and

predicted values using QR decomposition.

stdc Computes standard deviation of the columns of a matrix.

toeplitz Computes Toeplitz matrix from column vector.

vcm Computes a variance-covariance matrix from a moment matrix.

vcx Computes a variance-covariance matrix from a data matrix.

Advanced statistics and optimization routines are available in the GAUSS Applications

programs. Contact Aptech Systems for more information.

340

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

Statistical Distributions

cdfbeta Computes integral of beta function.

cdfbvn Computes lower tail of bivariate Normal cdf.

cdfchic Computes complement of cdf of

2

.

cdfchii Computes

2

abscissae values given probability

and degrees of freedom.

cdfchinc Computes integral of noncentral

2

.

cdc Computes complement of cdf of F.

cdnc Computes integral of noncentral F.

cdfgam Computes integral of incomplete function.

cdfmvn Computes multivariate Normal cdf.

cdfn Computes integral of Normal distribution: lower tail,

or cdf.

cdfn2 Computes interval of Normal cdf.

cdfnc Computes complement of cdf of Normal distribution

(upper tail).

cdftc Computes complement of cdf of t -distribution.

cdftnc Computes integral of noncentral t -distribution.

cdftvn Computes lower tail of trivariate Normal cdf.

erf Computes Gaussian error function.

erfc Computes complement of Gaussian error function.

lncdfbvn Computes natural log of bivariate Normal cdf.

lncdfmvn Computes natural log of multivariate Normal cdf.

lncdfn Computes natural log of Normal cdf.

lncdfn2 Computes natural log of interval of Normal cdf.

lncdfnc Computes natural log of complement of Normal cdf.

lnpdfn Computes Normal log-probabilities.

lnpdfmvn Computes multivariate Normal log-probabilities.

pdfn Computes standard Normal probability density function.

Series and Sequence Functions

recserar Computes autoregressive recursive series.

recsercp Computes recursive series involving products.

recserrc Computes recursive series involving division.

seqa Creates an additive sequence.

seqm Creates a multiplicative sequence.

341

24. COMMANDS BY CATEGORY

Precision Control

base10 Convert number to x.xxx and a power of 10.

ceil Round up towards +.

oor Round down towards .

prcsn Set computational precision for matrix operations.

round Round to the nearest integer.

trunc Truncate toward 0.

All calculations in GAUSS are done in double precision, with the exception of some of

the intrinsic functions on OS/2 and DOS. These may use extended precision (18-19

digits of accuracy). Use prcsn to change the internal accuracy used in these cases.

round, trunc, ceil and oor convert oating point numbers into integers. The internal

representation for the converted integer is double precision (64 bits).

Each matrix element in memory requires 8 bytes of workspace. See the function

coreleft to determine the amount of workspace available.

24.2 Matrix Manipulation

Creating Vectors and Matrices

editm Simple matrix editor.

eye Creates identity matrix.

let Creates matrix from list of constants.

medit Full-screen spreadsheet-like matrix editor.

ones Creates a matrix of ones.

zeros Creates a matrix of zeros.

Use zeros or ones to create a constant vector or matrix.

medit is a full-screen editor which can be used to create matrices to be stored in

memory, or to edit matrices that already exist.

Matrices may also be loaded from an ASCII le, from a GAUSS matrix le, or from a

GAUSS data set. For more information see the File I/O chapter in Volume I of the

manual.

342

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

Loading and Storing Matrices

loadd Load matrix from data set.

loadm Load matrix from ASCII or matrix le.

save Save matrix to matrix le.

saved Save matrix to data set.

Size, Ranking, and Range

cols Returns number of columns in a matrix.

colsf Returns number of columns in an open data set.

counts Returns number of elements of a vector falling in specied

ranges.

countwts Returns weighted count of elements of a vector falling

in specied ranges.

indexcat Returns indices of elements falling within a specied

range.

maxc Returns largest element in each column of a matrix.

maxindc Returns row number of largest element in each column

of a matrix.

minc Returns smallest element in each column of a matrix.

minindc Returns row number of smallest element in each column

of a matrix.

rankindx Returns rank index of Nx1 vector. (Rank order of

elements in vector).

rows Returns number of rows in a matrix.

rowsf Returns number of rows in an open data set.

cumprodc Computes cumulative products of each column of a

matrix.

cumsumc Computes cumulative sums of each column of a matrix.

prodc Computes the product of each column of a matrix.

sumc Computes the sum of each column of a matrix.

These functions are used to nd the minimum, maximum and frequency counts of

elements in matrices.

Use rows and cols to nd the number of rows or columns in a matrix. Use rowsf and

colsf to nd the numbers of rows or columns in an open GAUSS data set.

343

24. COMMANDS BY CATEGORY

Sparse Matrix Functions

sparseFD Converts dense matrix to sparse matrix.

sparseFP Converts packed matrix to sparse matrix.

sparseOnes Generates sparse matrix of ones and zeros.

sparseEye Creates sparse identity matrix.

sparseTD Multiplies sparse matrix by dense matrix.

sparseTrTD Multiplies sparse matrix transposed by dense matrix.

sparseSolve Solves Ax = B for x where A is a sparse matrix.

sparseHConcat Horizontally oncatenates sparse matrices.

sparseVConcat Vertically concatenates sparse matrices.

sparseSubmat Returns sparse submatrix of sparse matrix.

denseSubmat Returns dense submatrix of sparse matrix.

sparseRows Returns number of rows in sparse matrix.

sparseCols Returns number of columns in sparse matrix.

sparseNZE Returns the number of nonzero elements in sparse matrix.

isSparse Tests whether a matrix is a sparse matrix.

sparseSet Resets sparse library globals.

Miscellaneous Matrix Manipulation

rev Reverses the order of rows of a matrix.

rotater Rotates the rows of a matrix, wrapping elements

as necessary.

shiftr Shifts rows of a matrix, lling in holes with a specied

value.

reshape Reshapes a matrix to new dimensions.

vec Stacks columns of a matrix to form a single column.

vech Reshapes the lower triangular portion of a symmetric

matrix into a column vector.

vecr Stacks rows of a matrix to form a single column.

xpnd Expands a column vector into a symmetric matrix.

delif Deletes rows from a matrix using a logical expression.

diag Extracts the diagonal of a matrix.

diagrv Puts a column vector into the diagonal of a matrix.

exctsmpl Creates a random subsample of data set, with replacement.

lowmat Returns the main diagonal and lower triangle.

lowmat1 Returns a main diagonal of 1s and the lower triangle.

upmat Returns the main diagonal and upper triangle.

upmat1 Returns a main diagonal of 1s and the upper triangle.

selif Selects rows from a matrix using a logical expression.

344

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

submat Extracts a submatrix from a matrix.

trimr Trims rows from top or bottom of a matrix.

union Returns the union of two vectors.

intrsect Returns the intersection of two vectors.

setdif Returns elements of one vector that are not in another.

complex Creates a complex matrix from two real matrices.

imag Returns the imaginary part of a complex matrix.

real Returns the real part of a complex matrix.

vech and xpnd are complementary functions. vech provides an ecient way to store a

symmetric matrix; xpnd expands the stored vector back to its original symmetric

matrix.

delif and selif are complementary functions. delif deletes rows of a matrix based on a

logical comparison, and selif selects rows based on a logical comparison.

lowmat, lowmat1, upmat, and upmat1 extract triangular portions of a matrix.

To delete rows which contain missing values from a matrix in memory, see the function

packr.

24.3 Data Handling

Data Sets

close Closes an open data set (.dat le).

closeall Closes all open data sets.

create Creates and opens a data set.

eof Tests for end of le.

loadd Loads a small data set.

open Opens an existing data set.

readr Reads rows from open data set.

saved Creates small data sets.

seekr Moves pointer to specied location in open data set.

iscplxf Returns whether a data set is real or complex.

typef Returns the element size (2, 4 or 8 bytes) of

data in open data set.

writer Writes matrix to an open data set.

These functions all operate on GAUSS data sets (.dat les). See the File I/O chapter

in Volume I for more discussion.

345

24. COMMANDS BY CATEGORY

To create a GAUSS data set from a matrix in memory, use the function saved. To

create a data set from an existing one, use create. To create a data set from a large

ASCII le, use the utility atog (see Chapter 19 in Volume I).

Data sets can be opened, read from, and written to using the functions open, readr,

seekr and writer. Test for the end of a le using eof, and close the data set using close

or closeall.

The data in data sets may be typed as character or numeric. See the File I/O chapter

in Volume I, create, and vartypef.

typef returns the element size of the data in an open data set.

Data Set Variable Names

getname Returns column vector of variable names in a data set.

getnamef Returns string array of variable names in a data set.

indcv Returns column numbers of variables within a data set.

indices Retrieves column numbers and names from a data set.

indices2 Similar to indices, but matches columns with names

for dependent and independent variables.

mergevar Concatenates column vectors to create larger matrix.

makevars Decomposes matrix to create column vectors.

setvars Creates globals using the names in a data set.

vartype Determine whether variables in data set are character

or numeric.

vartypef Returns column vector of variable types (numeric/character)

in a data set.

Use getnamef to retrieve the variable names associated with the columns of a GAUSS

data set and vartypef to retrieve the variable types. Use makevars and setvars to

create global vectors from those names. Use indices and indices2 to match names with

column numbers in a data set.

getname and vartype are supported for backwards compatibility.

Data Coding

code Code the data in a vector by applying a logical set

of rules to assign each data value to a category.

dummy Creates a dummy matrix, expanding values in vector

346

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

to rows with ones in columns corresponding to true

categories and zeros elsewhere.

dummybr Similar to dummy.

dummydn Similar to dummy.

ismiss Returns 1 if matrix has any missing values, 0 otherwise.

miss Change specied values to missing value code.

missex Change elements to missing value using logical expression.

missrv Change missing value codes to specied values.

msym Set symbol to be interpreted as missing value.

packr Delete rows with missing values.

recode Similar to code, but leaves the original data in place

if no condition is met.

scalmiss Test whether a scalar is the missing value code.

substute Similar to recode, but operates on matrices.

subscat Simpler version of recode, but uses ascending bins

instead of logical conditions.

code, recode, and subscat allow the user to code data variables and operate on vectors

in memory. substute operates on matrices, and dummy, dummybr and dummydn

create matrices.

missex, missrv and miss should be used to recode missing values.

Sorting and Merging

sortc Quick-sort rows of matrix based on numeric key.

sortcc Quick-sort rows of matrix based on character key.

sortd Sort data set on a key column.

sorthc Heap-sort rows of matrix based on numeric key.

sorthcc Heap-sort rows of matrix based on character key.

sortind Returns a sorted index of a numeric vector.

sortindc Returns a sorted index of a character vector.

sortmc Sort rows of matrix on the basis of multiple columns.

uniqindx Returns a sorted unique index of a vector.

unique Remove duplicate elements of a vector.

intrleav Produces one large sorted data le from two smaller

sorted les having the same keys.

mergeby Produces one large sorted data le from two smaller

sorted les having a single key column in common.

sortc, sorthc and sortind operate on numeric data only. sortcc, sorthcc and sortindc

operate on character data only.

347

24. COMMANDS BY CATEGORY

unique and uniqindx operate on both numeric and character data.

Use sortd to sort the rows of a data set on the basis of a key column.

Both intrleav and mergeby operate on data sets.

24.4 Compiler Control

#dene Dene a case-insensitive text-replacement or ag variable.

#denecs Dene a case-sensitive text-replacement or ag variable.

#undef Undene a text-replacement or ag variable.

#ifdef Compile code block if a variable has been #dened.

#ifndef Compile code block if a variable has not been #dened.

#iight Compile code block if running GAUSS Light.

#ifdos Compile code block if running DOS.

#ifos2win Compile code block if running OS/2 or Windows.

#ifunix Compile code block if running Unix.

#else Alternate clause for #if-#else-#endif code block.

#endif End of #if-#else-#endif code block.

#include Include code from another le in program.

#lineson Compile program with line number and le name records.

#lineso Compile program without line number and le name records.

#srcle Insert source le name record at this point

(currently used when doing data loop translation).

#srcline Insert source le line number record at this point

(currently used when doing data loop translation).

These commands are compiler directives. That is, they do not generate GAUSS

program instructions; rather, they are instructions that tell GAUSS how to process a

program during compilation. They determine what the nal compiled form of a

program will be. They are not executable statements and have no eect at run-time.

See Section 7.4 for a discussion and examples of how to use compiler directives.

24.5 Program Control

Execution Control

end Terminate a program and close all les.

348

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

pause Pause for the specied time.

run Run a program in a text le.

sleep Sleep for the specied time.

stop Stop a program and leave les open.

system Quit and return to the OS.

Both stop and end will terminate the execution of a program; end will close all open

les, and stop will leave those les open. Neither stop or end is required in a GAUSS

program.

Branching

if..endif Conditional branching.

goto Unconditional branching.

pop Retrieve goto arguments.

if iter > itlim;

goto errout("Iteration limit exceeded");

elseif iter == 1;

j = setup(x,y);

else;

j = iterate(x,y);

endif;

.

.

.

errout:

pop errmsg;

print errmsg;

end;

Looping

break Jump out the bottom of a do or for loop.

continue Jump to the top of a do or for loop.

do while.. endo Loop if TRUE.

do until.. endo Loop if FALSE.

for.. endfor Loop with integer counter.

349

24. COMMANDS BY CATEGORY

iter = 0;

do while dif > tol;

{ x,x0 } = eval(x,x0);

dif = abs(x-x0);

iter = iter + 1;

if iter > maxits;

break;

endif;

if not prtiter;

continue;

endif;

format /rdn 1,0;

print "Iteration: " iter;;

format /re 16,8;

print ", Error: " maxc(dif);

endo;

for i (1, cols(x), 1);

for j (1, rows(x), 1);

x[i,j] = x[i,j] + 1;

endfor;

endfor;

Subroutines

gosub Branch to subroutine.

pop Retrieve gosub arguments.

return Return from subroutine.

Arguments can be passed to subroutines in the branch to the subroutine label and then

popped, in rst-in-last-out order, immediately following the subroutine label denition.

See the COMMAND REFERENCE for complete details.

Arguments can then be returned in an analogous fashion through the return statement.

Procedures

350

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

local Declare variables local to a procedure.

proc Begin denition of multi-line procedure.

retp Return from a procedure.

endp Terminate a procedure denition.

Here is an example of a GAUSS procedure:

proc (3) = crosprod(x,y);

local r1, r2, r3;

r1 = x[2,.].*y[3,.]-x[3,.].*y[2,.];

r2 = x[3,.].*y[1,.]-x[1,.].*y[3,.];

r3 = x[1,.].*y[2,.]-x[2,.].*y[1,.];

retp( r1,r2,r3 );

endp;

The (3) = indicates that the procedure returns three arguments. All local variables,

except those listed in the argument list, must appear in the local statement.

Procedures may reference global variables. There may be more than one retp per

procedure denition; none is required if the procedure is dened to return 0 arguments.

The endp is always necessary and must appear at the end of the procedure denition.

Procedure denitions cannot be nested. The syntax for using this example function is:

{ a1,a2,a3 } = crosprod(u,v);

See Chapters 9 and 10 for more details.

Libraries

call Call function and discard return values.

declare Initialize variables at compile time.

external External symbol denitions.

library Set up list of active libraries.

lib Build or update a GAUSS library.

call allows functions to be called when return values are not needed. This is especially

useful if a function produces printed output (dstat, ols for example) as well as return

values.

351

24. COMMANDS BY CATEGORY

Compiling

compile Compiles and saves a program to a .gcg le.

saveall Saves the contents of the current workspace to a le.

use Loads previously compiled code.

save Saves the compiled image of a procedure to disk.

loadp Loads compiled procedure.

GAUSS procedures and programs may be compiled to disk les. By then using this

compiled code, the time necessary to compile programs from scratch is eliminated. Use

compile to compile a command le. All procedures, matrices and strings referenced by

that program will be compiled as well.

Stand-alone applications may be created by running compiled code under the

Run-Time Module. Contact Aptech Systems for more information on this product.

To save the compiled images of procedures that do not make any global references, use

the save command. This will create an .fcg le. To load the compiled procedure into

memory, use loadp. This is not recommended because of the restriction on global

references and the need to explicitly load the procedure in each program that references

it. This is here to maintain backward compatibility with previous versions.

24.6 OS Functions

cdir Returns current directory.

chdir Change directory interactively.

ChangeDir Change directory in program.

dfree Returns free space on disk.

shell Shells to OS.

envget Get an environment string.

exec Execute an executable program le.

leinfo Takes a le specication, returns names and information of

les that match.

les Takes a le specication, returns names of les that match.

lesa Takes a le specication, returns names of les that match.

24.7 Workspace Management

352

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

clear Set matrices equal to 0.

clearg Set global symbols to 0.

coreleft Returns amount of workspace memory left.

maxvec Returns maximum allowed vector size.

delete Delete specied global symbols.

new Clear current workspace.

show Display global symbol table.

iscplx Returns whether a matrix is real or complex.

hasimag Examines matrix for nonzero imaginary part.

type Returns type of argument (matrix or string).

typecv Returns type of symbol (argument contains

the name of the symbol to be checked).

When working with limited workspace, it is a good idea to clear large matrices that are

no longer needed by your program.

coreleft is most commonly used to determine how many rows of a data set may be read

into memory at one time.

24.8 Error Handling and Debugging

debug Execute a program under the source level debugger.

disable Disable invalid operation interrupt of coprocessor.

error Create user-dened error code.

errorlog Send error message to screen and log le.

enable Enable invalid operation interrupt of coprocessor.

#lineson Include line number and le name records in program.

#lineso Omit line number and le name records from program.

ndpchk Examine status word of coprocessor.

ndpclex Clear coprocessor exception ags.

ndpcntrl Set and get coprocessor control word.

scalerr Test for a scalar error code.

trace Trace program execution for debugging.

trap Control trapping of program errors.

trapchk Examine the trap ag.

To trap coprocessor overows, invalid operations, divide by zero, and other exceptions,

use ndpchk. To clear these exceptions, use ndpclex. To set exceptions to be checked,

use ndpcntrl.

To trace the execution of a program, use trace.

User-dened error codes may be generated using error.

353

24. COMMANDS BY CATEGORY

24.9 String Handling

chrs Convert ASCII values to a string.

ftocv Convert an NxK matrix to a character matrix.

ftos Convert a oating point scalar to string.

getf Load ASCII or binary le into string.

loads Loads a string le (.fst le).

lower Convert a string to lowercase.

putf Writes a string to disk le.

stof Convert a string to oating point scalar.

strindx Find starting location of one string in another string.

strlen Returns length of a string.

strrindx Find starting location of one string in another string,

searching from the end to the start of the string.

strsect Extract a substring of a string.

upper Changes a string to uppercase.

vals Convert a string to ASCII values.

varget Access the global variable named by a string.

varput Assign a global variable named by a string.

vargetl Access the local variable named by a string.

varputl Assign a local variable named by a string.

strlen, strindx, strrindx, and strsect can be used together to parse strings.

Use ftos to print to a string.

To create a list of generic variable names (X1, X2, X3, X4... for example), use ftocv.

24.10 Time and Date Functions

date Returns current system date.

datestr Formats date as mm/dd/yy.

datestring Formats date as mm/dd/yyyy.

datestrymd Formats date as yyyymmdd.

dayinyr Returns day number of a date.

etdays Dierence between two times in days.

ethsec Dierence between two times in 100ths of a second.

etstr Convert elapsed time to string.

hsec Returns elapsed time since midnight in 100ths of a second.

time Returns current system time.

timestr Format time as hh:mm:ss.

354

C

o

m

m

a

n

d

s

b

y

C

a

t

e

g

o

r

y

24. COMMANDS BY CATEGORY

Use hsec to time segments of code. For example,

et = hsec;

x = y*y;

et = hsec - et;

will time the GAUSS multiplication operator.

24.11 Console I/O

con Request console input, create matrix.

cons Request console input, create string.

key Gets the next key from the keyboard buer. If buer

is empty, returns a 0.

keyw Gets the next key from the keyboard buer. If buer

is empty, waits for a key.

wait Wait for a keystroke.

waitc Flush buer, then wait for a keystroke.

key can be used to trap most keystrokes. For example, the following loop will trap the

ALT-H key combination:

kk = 0;

do until kk == 1035;

kk = key;

endo;

Other key combinations, function keys and cursor key movement can also be trapped.

See key in the COMMAND REFERENCE.

cons and con can be used to request information from the console. keyw, wait and

waitc will wait for a keystroke.

24.12 Output Functions

Text Output

355

24. COMMANDS BY CATEGORY

comlog Control interactive command logging.

output Redirect print statements to auxiliary output.

outwidth Set line width of auxiliary output.

print Print to screen.

print [[on[o]] Turn auto screen print on and o.

printfm Print matrices using a dierent format for each column.

screen [[on[o]] Direct/suppress print statements to screen.

screen out Dump snapshot of screen to auxiliary output.

lpos Returns print head position in printer buer.

lprint Print expression to the printer.

lprint [[on[o]] Switch auto printer mode on and o.

lpwidth Species printer width.

lshow Print global symbol table on the printer.

plot Plot elements of two matrices in text mode.

plotsym Controls data symbol used by plot.

cls Clear the screen.

color Set pixel, text, background colors.

csrcol Get column position of cursor on screen.

csrlin Get row position of cursor on screen.

edit Edits a le with the GAUSS editor.

ed Access an alternate editor.

format Denes format of matrix printing.

locate Position the cursor on the screen.

printdos Print a string for special handling by the OS.

scroll Scroll a section of the screen.

tab Position the cursor on the current line.

The results of all printing may be sent to an output le using output. This le can

then be printed or ported as an ASCII le to other software.

printdos can be used to print in reverse video, or using dierent colors. It requires that

ansi.sys be installed.

To produces boxes, etc. using characters from the extended ASCII set, use chrs.

Screen Graphics

graph Set pixels.

setvmode Set video mode.

color Set color.

line Draw lines.

The function graph allows the user to plot individual pixels.

356

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

Chapter 25

Command Reference

357

abs 25. COMMAND REFERENCE

Purpose

Returns the absolute value or complex modulus of x.

Format

y = abs(x);

Input

x NK matrix.

Output

y NK matrix containing absolute values of x.

Example

x = rndn(2,2);

y = abs(x);

x =

0.675243 1.053485

0.190746 1.229539

y =

0.675243 1.053485

0.190746 1.229539

In this example, a 22 matrix of Normal random numbers is generated and the

absolute value of the matrix is computed.

358

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

A

25. COMMAND REFERENCE arccos

Purpose

Computes the inverse cosine.

Format

y = arccos(x);

Input

x NK matrix.

Output

y NK matrix containing the angle in radians whose cosine is x.

Remarks

If x is complex or has any elements whose absolute value is greater than 1, complex

results are returned.

Example

x = { -1, -0.5, 0, 0.5, 1 };

y = arccos(x);

x =

1.000000

0.500000

0.000000

0.500000

1.000000

y =

3.141593

2.094395

1.570796

1.047198

0.000000

Source

trig.src

Globals

None

359

arcsin 25. COMMAND REFERENCE

Purpose

Computes the inverse sine.

Format

y = arcsin(x);

Input

x NK matrix.

Output

y NK matrix, the angle in radians whose sine is x.

Remarks

If x is complex or has any elements whose absolute value is greater than 1, complex

results are returned.

Example

x = { -1, -0.5, 0, 0.5, 1 };

y = arcsin(x);

x =

1.000000

0.500000

0.000000

0.500000

1.000000

y =

1.570796

0.523599

0.000000

0.523599

1.570796

Source

trig.src

Globals

None

360

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

A

25. COMMAND REFERENCE atan

Purpose

Returns the arctangent of its argument.

Format

y = atan(x);

Input

x NK matrix.

Output

y NK matrix containing the arctangent of x in radians.

Remarks

y will be a matrix the same size as x, containing the arctangents of the corresponding

elements of x.

For real x, the arctangent of x is the angle whose tangent is x. The result is a value in

radians in the range

2

to

+

2

. To convert radians to degrees, multiply by

180

.

For complex x, the arctangent is dened everywhere except i and -i . If x is complex, y

will be complex.

Example

x = { 2, 4, 6, 8 };

z = x/2;

y = atan(z);

y =

0.785398

1.107149

1.249046

1.325818

See also

atan2, sin, cos, pi, tan

361

atan2 25. COMMAND REFERENCE

Purpose

Compute an angle from an x,y coordinate.

Format

z = atan2(y,x);

Input

y NK matrix, the Y coordinate.

x LM matrix, EE conformable with y, the X coordinate.

Output

z max(N,L) by max(K,M) matrix.

Remarks

Given a point x,y in a Cartesian coordinate system, atan2 will give the correct angle

with respect to the positive X axis. The answer will be in radians from -pi to +pi.

To convert radians to degrees, multiply by

180

.

atan2 operates only on the real component of x, even if x is complex.

Example

x = 2;

y = { 2, 4, 6, 8 };

z = atan2(y,x);

z =

0.785398

1.107149

1.249046

1.325818

See also

atan, sin, cos, pi, tan, arcsin, arccos

362

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

B

25. COMMAND REFERENCE balance

Purpose

Balances a square matrix.

Format

{ b,z } = balance(x)

Input

x KK matrix.

Output

b KK matrix, balanced matrix.

z KK matrix, diagonal scale matrix.

Remarks

balance returns a balanced matrix b and another matrix z with scale factors in powers

of two on its diagonal. b is balanced in the sense that the absolute sums of the

magnitudes of elements in corresponding rows and columns are nearly equal.

balance is most often used to scale matrices to improve the numerical stability of the

calculation of their eigenvalues. It is also useful in the solution of matrix equations.

In particular,

b = z

1

xz

balance uses the BALANC function from EISPACK.

Example

let x[3,3] = 100 200 300

40 50 60

7 8 9;

{ b,z } = balance(x);

b =

100.0 100.0 37.5

80.0 50.0 15.0

56.0 32.0 9.0

z =

4.0 0.0 0.0

0.0 2.0 0.0

0.0 0.0 0.5

363

band 25. COMMAND REFERENCE

Purpose

Extracts bands from a symmetric banded matrix.

Format

a = band(y,n);

Input

y KK symmetric banded matrix.

n scalar, number of subdiagonals.

Output

a K(N+1) matrix, 1 subdiagonal per column.

Remarks

y can actually be a rectangular PQ matrix. K is then dened as min(P,Q). It will be

assumed that a is symmetric about the principal diagonal for y[1:K,1:K].

The subdiagonals of y are stored right to left in a, with the principal diagonal in the

rightmost (N+1th) column of a. The upper left corner of a is unused; it is set to 0.

This compact form of a banded matrix is what bandchol expects.

Example

x = { 1 2 0 0,

2 8 1 0,

0 1 5 2,

0 0 2 3 };

bx = band(x,1);

bx =

0.0000000 1.0000000

2.0000000 8.0000000

1.0000000 5.0000000

2.0000000 3.0000000

364

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

B

25. COMMAND REFERENCE bandchol

Purpose

Computes the Cholesky decomposition of a positive denite banded matrix.

Format

l = bandchol(a);

Input

a KN compact form matrix.

Output

l KN compact form matrix, lower triangle of the Cholesky decomposition

of a.

Remarks

Given a positive denite banded matrix A, there exists a matrix L, the lower triangle of

the Cholesky decomposition of A, such that A = L L

see band for a description of the format of a.

l is the compact form of L. This is the form of matrix that bandcholsol expects.

Example

x = { 1 2 0 0,

2 8 1 0,

0 1 5 2,

0 0 2 3 };

bx = band(x,1);

bx =

0.0000000 1.0000000

2.0000000 8.0000000

1.0000000 5.0000000

2.0000000 3.0000000

cx = bandchol(bx);

cx =

0.0000000 1.0000000

2.0000000 2.0000000

0.50000000 2.1794495

0.91766294 1.4689774

365

bandcholsol 25. COMMAND REFERENCE

Purpose

Solves the system of equations Ax = b for x, given the lower triangle of the Cholesky

decomposition of a positive denite banded matrix A.

Format

x = bandcholsol(b,l );

Input

b KM matrix.

l KN compact form matrix.

Output

x KM matrix.

Remarks

Given a positive denite banded matrix A, there exists a matrix L, the lower triangle of

the Cholesky decomposition of A, such that A = L*L. l is the compact form of L; see

band for a description of the format of l .

b can have more than one column. If so, Ax = b is solved for each column. That is,

A*x[.,i] = b[.,i]

Example

x = { 1 2 0 0,

2 8 1 0,

0 1 5 2,

0 0 2 3 };

bx = band(x,1);

bx =

0.0000000 1.0000000

2.0000000 8.0000000

1.0000000 5.0000000

2.0000000 3.0000000

cx = bandchol(bx);

366

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

B

25. COMMAND REFERENCE bandcholsol

cx =

0.0000000 1.0000000

2.0000000 2.0000000

0.50000000 2.1794495

0.91766294 1.4689774

xi = BandCholSol(eye(4),cx);

xi =

2.0731707 0.53658537 0.14634146 0.097560976

0.53658537 0.26829268 0.073170732 0.048780488

0.14634146 0.073170732 0.29268293 0.19512195

0.097560976 0.048780488 0.19512195 0.46341463

367

bandltsol 25. COMMAND REFERENCE

Purpose

Solves the system of equations Ax = b for x, where A is a lower triangular banded

matrix.

Format

x = bandltsol(b,A);

Input

b KM matrix.

A KN compact form matrix.

Output

x KM matrix.

Remarks

A is a lower triangular banded matrix in compact form. See band for a description of

the format of A.

b can have more than one column. If so, Ax = b is solved for each column. That is,

A*x[.,i] = b[.,i]

Example

bx =

0.0000000 1.0000000

2.0000000 8.0000000

1.0000000 5.0000000

2.0000000 3.0000000

cx = bandchol(bx);

cx =

0.0000000 1.0000000

2.0000000 2.0000000

0.50000000 2.1794495

0.91766294 1.4689774

xci = bandLTSol(eye(4),cx);

xci =

1.0000000 0.0000000 0.0000000 0.0000000

1.0000000 0.50000000 0.0000000 0.0000000

0.22941573 0.11470787 0.45883147 0.0000000

0.14331487 0.071657436 0.28662975 0.68074565

368

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

B

25. COMMAND REFERENCE bandrv

Purpose

Creates a symmetric banded matrix, given its compact form.

Format

y = bandrv(a);

Input

a KN compact form matrix.

Output

y KK symmetrix banded matrix.

Remarks

a is the compact form of a symmetric banded matrix, as generated by band. a stores

subdiagonals right to left, with the principal diagonal in the rightmost (N

th

) column.

The upper left corner of a is unused. bandchol expects a matrix of this form.

y is the fully expanded form of a, a KK matrix with N-1 subdiagonals.

Example

bx =

0.0000000 1.0000000

2.0000000 8.0000000

1.0000000 5.0000000

2.0000000 3.0000000

x = bandrv(bx);

x =

1.0000000 2.0000000 0.0000000 0.0000000

2.0000000 8.0000000 1.0000000 0.0000000

0.0000000 1.0000000 5.0000000 2.0000000

0.0000000 0.0000000 2.0000000 3.0000000

369

bandsolpd 25. COMMAND REFERENCE

Purpose

Solves the system of equations Ax = b for x, where A is a positive denite banded

matrix.

Format

x = bandsolpd(b,A);

Input

b KM matrix.

A KN compact form matrix.

Output

x KM matrix.

Remarks

A is a positive denite banded matrix in compact form. See band for a description of

the format of A.

b can have more than one column. If so, Ax = b is solved for each column. That is,

A*x[.,i] = b[.,i]

370

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

B

25. COMMAND REFERENCE base10

Purpose

Break number into a number of the form #.####... and a power of 10.

Format

{ M,P } = base10(x);

Input

x scalar, number to break down.

Output

M scalar, in the range 10 < M < 10.

P scalar, integer power such that:

M 10

P

= x

Example

{ b, e } = base10(4500);

b = 4.5000000

e = 3.0000000

Source

base10.src

Globals

None

371

besselj 25. COMMAND REFERENCE

Purpose

To compute a Bessel function of the rst kind, J

n

(x).

Format

y = besselj(n,x);

Input

n NK matrix, the order of the Bessel function. Nonintegers will be

truncated to an integer.

x LM matrix, EE conformable with n.

Output

y max(N,L) by max(K,M) matrix.

Example

n = { 0, 1 };

x = { 0.1 1.2, 2.3 3.4 };

y = besselj(n,x);

y =

0.99750156 0.67113274

0.53987253 0.17922585

See also

bessely, mbesseli

372

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

B

25. COMMAND REFERENCE bessely

Purpose

To compute a Bessel function of the second kind (Webers function), Y

n

(x).

Format

y = bessely(n,x);

Input

n NK matrix, the order of the Bessel function. Nonintegers will be

truncated to an integer.

x LM matrix, EE conformable with n.

Output

y max(N,L) by max(K,M) matrix.

Example

n = { 0, 1 };

x = { 0.1 1.2, 2.3 3.4 };

y = bessely(n,x);

y =

1.5342387 0.22808351

0.052277316 0.40101529

See also

besselj, mbesseli

373

break 25. COMMAND REFERENCE

Purpose

Breaks out of a do or for loop.

Format

break;

Example

x = rndn(4,4);

r = 0;

do while r < rows(x);

r = r + 1;

c = 0;

do while c < cols(x);

c = c + 1;

if c == r;

x[r,c] = 1;

elseif c > r;

break; /* terminate inner do loop */

else;

x[r,c] = 0;

endif;

endo; /* break jumps to the statement after this endo */

endo;

x =

1.000 0.326 2.682 0.594

0.000 1.000 0.879 0.056

0.000 0.000 1.000 0.688

0.000 0.000 0.000 1.000

Remarks

This command works just like in C.

See also

continue, do, for

374

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE call

Purpose

Calls a function or procedure when the returned value is not needed and can be

ignored, or when the procedure is dened to return nothing.

Format

call function name(argument list);

call function name;

Remarks

This is useful when you need to execute a function or procedure and do not need the

value that it returns. It can also be used for calling procedures that have been dened

to return nothing.

function name can be any intrinsic GAUSS function, a procedure (proc), or any valid

expression.

Example

call chol(x);

y = detl;

The above example is the fastest way to compute the determinant of a positive denite

matrix. The result of chol is discarded and detl is used to retrieve the determinant that

was computed during the call to chol.

See also

proc

375

cdfbeta 25. COMMAND REFERENCE

Purpose

Computes the incomplete beta function (i.e., the cumulative distribution function of

the beta distribution).

Format

y = cdfbeta(x,a,b);

Input

x NK matrix.

a LM matrix, EE conformable with x.

b PQ matrix, EE conformable with x and a.

Output

y max(N,L,P) by max(K,M,Q) matrix.

Remarks

y is the integral from 0 to x of the beta distribution with parameters a and b.

Allowable ranges for the arguments are:

0 x 1

a > 0

b > 0

A -1 is returned for those elements with invalid inputs.

Example

x = { .1, .2, .3, .4 };

a = 0.5;

b = 0.3;

y = cdfbeta(x,a,b);

y =

0.142285

0.206629

0.260575

0.310875

376

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfbeta

See also

cdfchic, cdc, cdfn, cdfnc, cdftc, gamma

Technical Notes

cdfbeta has the following approximate accuracy:

max(a,b) 500 the absolute error is approx. 5e13

500 < max(a,b) 10, 000 the absolute error is approx. 5e11

10, 000 < max(a,b) 200, 000 the absolute error is approx. 1e9

200, 000 < max(a,b) Normal approximations are used and

the absolute error is approx. 2e9

References:

1. ALGORITHM 179 INCOMPLETE BETA RATIO, O.G. Ludwig,

Comm. ACM, Vol. 6, No. 6, pp. 314, June 1963

2. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, M.C.

Pike and I.D. Hill, Comm. ACM, Vol. 10, No. 6, pp. 375-6, June. 1967

3. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, N. E.

Bosten and E.L. Battiste, Comm. ACM, Vol. 17, No. 3, pp. 156-7, March

1974

4. ASYMPTOTICALLY PEARSONS TRANSFORMATIONS, L.N.

Bolshev, Teor. Veroyat. Primen. (Theory of Probability and its

Applications), Vol. 8, No. 2, pp. 129-155, 1963

5. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND

OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer

and J.W. Pratt, Journal of American Statistical Association Journal, Vol.

63, pp. 1416-1456, Dec. 1968.

6. Tables of the F- and related distributions with algorithms, K.V. Mardia

and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5

377

cdfbvn 25. COMMAND REFERENCE

Purpose

Computes the cumulative distribution function of the standardized bivariate Normal

density (lower tail).

Format

c = cdfbvn(h,k,r);

Input

h NK matrix, the upper limits of integration for variable 1.

k LM matrix, EE conformable with h, the upper limits of integration for

variable 2.

r PQ matrix, EE conformable with h and k, the correlation coecients

between the two variables.

Output

c max(N,L,P) by max(K,M,Q) matrix, the result of the double integral from

to h and to k of the standardized bivariate Normal density

f(x, y, r).

Remarks

The function integrated is:

f(x, y, r) =

e

0.5w

2

1 r

2

with

w =

x

2

2rxy +y

2

1 r

2

Thus, x and y have 0 means, unit variances, and correlation = r.

Allowable ranges for the arguments are:

< h < +

< k < +

1 r 1

A -1 is returned for those elements with invalid inputs.

To nd the integral under a general bivariate density, with x and y having nonzero

means and any positive standard deviations, use the transformation equations:

378

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfbvn

h = (ht - ux) ./ sx;

k = (kt - uy) ./ sy;

where ux and uy are the (vectors of) means of x and y, sx and sy are the (vectors of)

standard deviations of x and y, and ht and kt are the (vectors of) upper integration

limits for the untransformed variables, respectively.

See also

cdfn, cdftvn

Technical Notes

The absolute error for cdfbvn is approximately 5.0e9 for the entire range of

arguments.

References:

1. A Table of Normal Integrals, D.B. Owen, Commun. Statist.-Simula.

Computa., B9(4), pp. 389-419, 1980

2. Computation of Bi- and Tri-variate Normal Integral, D.J. Daley, Appl.

Statist., Vol. 23, No. 3, pp. 435-438, 1974

379

cdfchic 25. COMMAND REFERENCE

Purpose

Computes the complement of the cdf of the chi-square distribution.

Format

y = cdfchic(x,n)

Input

x NK matrix.

n LM matrix, EE conformable with x.

Output

y max(N,L) by max(K,M) matrix.

Remarks

y is the integral from x to of the chi-square distribution with n degrees of freedom.

The elements of n must all be positive integers. The allowable ranges for the arguments

are:

x 0

n > 0

A -1 is returned for those elements with invalid inputs.

This equals 1 F(x, n), where F is the chi-square cdf with n degrees of freedom. Thus,

to get the chi-square cdf, subtract cdfchic(x,n) from 1. The complement of the cdf is

computed because this is what is most commonly needed in statistical applications, and

because it can be computed with fewer problems of roundo error.

Example

x = { .1, .2, .3, .4 };

n = 3;

y = cdfchic(x,n);

380

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfchic

y =

0.991837

0.977589

0.960028

0.940242

See also

cdfbeta, cdc, cdfn, cdfnc, cdftc, gamma

Technical Notes

For n 1000, the incomplete gamma function is used and the absolute error is approx.

6e13. For n > 1000, a Normal approximation is used and the absolute error is

2e8.

For higher accuracy when n > 1000, use:

1-cdfgam(0.5*x,0.5*n);

References:

1. ALGORITHM AS 32, THE INCOMPLETE GAMMA INTEGRAL,

G.P. Bhattacharjee, Applied Statistics, Vol. 19, pp. 285-287, 1970.

2. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND

OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer

and J.W. Pratt, Journal of American Statistical Association Journal, Vol.

63, pp. 1416-1456, Dec. 1968.

3. Tables of the F- and related distributions with algorithms, K.V. Mardia

and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5

381

cdfchii 25. COMMAND REFERENCE

Purpose

Compute chi-square abscissae values given probability and degrees of freedom.

Format

c = cdfchii(p,n);

Input

p MN matrix, probabilities.

n LK matrix, EE conformable with p, degrees of freedom.

Output

c max(M,L) by max(N,K) matrix, abscissae values for chi-square

distribution.

Example

The following generates a 33 matrix of pseudo-random numbers with a chi-squared

distribution with expected value of 4:

rndseed 464578;

x = cdfchii(rndu(3,3),4+zeros(3,3));

x =

2.1096456 1.9354989 1.7549182

4.4971008 9.2643386 4.3639694

4.5737473 1.3706243 2.5653688

Globals

gammaii

Source

cdfchii.src

382

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfchinc

Purpose

The integral under noncentral chi-square distribution, from 0 to x. It can return a

vector of values, but the degrees of freedom and noncentrality parameter must be the

same for all values of x.

Format

y = cdfchinc(x,v,d);

Input

x N1 vector, values of upper limits of integrals, must be greater than 0.

v scalar, degrees of freedom, v > 0.

d scalar, noncentrality parameter, d > 0.

This is the square root of the noncentrality parameter that sometimes goes

under the symbol lambda. See Schee, THE ANALYSIS OF VARIANCE,

1959, app. IV.

Output

y N1 vector, integrals from 0 to x of noncentral chi-square.

Technical Notes

Relation to cdfchic:

cdfchic(x,v) = 1 - cdfchinc(x,v,0);

The formula used is taken from Abramowitz and Stegun, HANDBOOK

OF MATHEMATICAL FUNCTIONS, 1970, p. 942, formula 26.4.25.

Example

x = { .5, 1, 5, 25 };

p = cdfchinc(x,4,2);

0.0042086234

0.016608592

0.30954232

0.99441140

Source

cdfnonc.src

Globals

None

See also

cdnc, cdftnc

383

cdc 25. COMMAND REFERENCE

Purpose

Computes the complement of the cdf of the F distribution.

Format

y = cdc(x,n1,n2);

Input

x NK matrix.

n1 LM matrix, EE conformable with x.

n2 PQ matrix, EE conformable with x and n1.

Output

y max(N,L,P) by max(K,M,Q) matrix

Remarks

y is the integral from x to of the F distribution with n1 and n2 degrees of freedom.

Allowable ranges for the arguments are:

x 0

n1 > 0

n2 > 0

A -1 is returned for those elements with invalid inputs.

This equals 1 G(x, n1, n2), where G is the F cdf with n1 and n2 degrees of freedom.

Thus, to get the F cdf, subtract cdc(x,n1,n2) from 1. The complement of the cdf is

computed because this is what is most commonly needed in statistical applications, and

because it can be computed with fewer problems of roundo error.

Example

x = { .1, .2, .3, .4 };

n1 = 0.5;

n2 = 0.3;

y = cdffc(x,n1,n2);

384

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdc

y =

0.751772

0.708152

0.680365

0.659816

See also

cdfbeta, cdfchic, cdfn, cdfnc, cdftc, gamma

Technical Notes

For max(n1,n2) 1000, the absolute error is approx. 5e13. For max(n1,n2) > 1000,

Normal approximations are used and the absolute error is approx. 2e6.

For higher accuracy when max(n1,n2) > 1000, use:

cdfbeta(n2/(n2+n1*x), n2/2, n1/2);

References:

1. ALGORITHM 179 INCOMPLETE BETA RATIO, O.G. Ludwig,

Comm. ACM, Vol. 6, No. 6, pp. 314, June 1963

2. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, M.C.

Pike and I.D. Hill, Comm. ACM, Vol. 10, No. 6, pp. 375-6, June. 1967

3. REMARK ON ALGORITHM 179 INCOMPLETE BETA RATIO, N. E.

Bosten and E.L. Battiste, Comm. ACM, Vol. 17, No. 3, pp. 156-7, March

1974

4. ASYMPTOTICALLY PEARSONS TRANSFORMATIONS, L.N.

Bolshev, Teor. Veroyat. Primen. (Theory of Probability and its

Applications), Vol. 8, No. 2, pp. 129-155, 1963

5. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND

OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer

and J.W. Pratt, Journal of American Statistical Association Journal, Vol.

63, pp. 1416-1456, Dec. 1968.

6. Tables of the F- and related distributions with algorithms, K.V. Mardia

and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5

7. Statistical Computing, W.J. Kennedy, Jr. and J.E. Gentle, Marcel Dekker,

Inc., New York, 1980.

385

cdnc 25. COMMAND REFERENCE

Purpose

The integral under noncentral F distribution, from 0 to x.

Format

y = cdnc(x,v1,v2,d);

Input

x N1 vector, values of upper limits of integrals, x > 0.

v1 scalar, degrees of freedom of numerator, v1 > 0.

v2 scalar, degrees of freedom of denominator, v2 > 0.

d scalar, noncentrality parameter, d > 0.

This is the square root of the noncentrality parameter that sometimes goes

under the symbol lambda. See Schee, THE ANALYSIS OF VARIANCE,

1959, app. IV.

Output

y N1 vector of integrals from 0 to x of noncentral F.

Technical Notes

Relation to cdc:

cdc(x,v1,v2) = 1 - cdnc(x,v1,v2,0);

The formula used is taken from Abramowitz and Stegun, HANDBOOK

OF MATHEMATICAL FUNCTIONS, 1970, p. 947, formula 26.6.20.

Source

cdfnonc.src

Globals

None

See also

cdftnc, cdfchinc

386

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfgam

Purpose

Incomplete gamma function.

Format

g = cdfgam(x,intlim);

Input

x NK matrix of data.

intlim LM matrix, EE compatible with x, containing the integration limit.

Output

g max(N,L) by max(K,M) matrix.

Remarks

The incomplete gamma function returns the integral

intlim

0

e

t

t

(x1)

gamma(x)

dt

The allowable ranges for the arguments are:

x > 0

intlim 0

A -1 is returned for those elements with invalid inputs.

Example

x = { 0.5 1 3 10 };

intlim = seqa(0,.2,6);

g = cdfgam(x,intlim);

x = 0.500000 1.00000 3.00000 10.0000

intlim =

0.000000

0.200000

0.400000

0.600000

0.800000

1.000000

387

cdfgam 25. COMMAND REFERENCE

g =

0.000000 0.000000 0.000000 0.000000

0.472911 0.181269 0.00114848 2.35307E 014

0.628907 0.329680 0.00792633 2.00981E 011

0.726678 0.451188 0.0231153 9.66972E 010

0.794097 0.550671 0.0474226 1.43310E 008

0.842701 0.632120 0.0803014 1.11425E 007

This computes the integrals over the range from 0 to 1, in increments of .2, at the

parameter values 0.5, 1, 3, 10.

Technical Notes

cdfgam has the following approximate accuracy:

x < 500 the absolute error is approx. 6e13

500 x 10, 000 the absolute error is approx. 3e11

10, 000 < x a Normal approximation is used and

the absolute error is approx. 3e10

References:

1. ALGORITHM AS 32, THE INCOMPLETE GAMMA INTEGRAL,

G.P. Bhattacharjee, Applied Statistics, Vol. 19, pp. 285-287, 1970.

2. A NORMAL APPROXIMATION FOR BINOMIAL, F, BETA, AND

OTHER COMMON, RELATED TAIL PROBABILITIES, I, D.B. Peizer

and J.W. Pratt, Journal of American Statistical Association Journal, Vol.

63, pp. 1416-1456, Dec. 1968.

3. Tables of the F- and related distributions with algorithms, K.V. Mardia

and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5

388

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfmvn

Purpose

Computes multivariate Normal cumulative distribution function.

Format

y = cdfmvn(x,r);

Input

x KL matrix, abscissae.

r KK matrix, correlation matrix.

Output

y L1 vector, Pr(X < x[r).

See also

cdfbvn, cdfn, cdftvn, lncdfmvn

Source

lncdfn.src

389

cdfn, cdfnc 25. COMMAND REFERENCE

Purpose

cdfn computes the cumulative distribution function (cdf) of the Normal distribution.

cdfnc computes 1 minus the cdf of the Normal distribution.

Format

n = cdfn(x);

nc = cdfnc(x);

Input

x NK matrix.

Output

n NK matrix.

nc NK matrix.

Remarks

n is the integral from to x of the Normal density function, and nc is the integral

from x to +.

Note that: cdfn(x) + cdfnc(x) = 1. However, many applications expect cdfn(x) to

approach 1, but never actually reach it. Because of this, we have capped the return

value of cdfn at 1 machine epsilon, or approximately 1 1.11e16. As the relative

error of cdfn is about 5e15 for cdfn(x) around 1, this does not invalidate the result.

What it does mean is that for abs(x) > (approx.)8.2924, the identity does not hold

true. If you have a need for the uncapped value of cdfn, the following code will return

it:

n = cdfn(x);

if n >= 1-eps;

n = 1;

endif;

where the value of machine epsilon is obtained as follows:

x = 1;

do while 1-x /= 1;

eps = x;

x = x/2;

endo;

390

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfn, cdfnc

Note that this is an alternate denition of machine epsilon. Machine epsilon is usually

dened as the smallest number such that 1 + machine epsilon > 1, which is about

2.23e16. This denes machine epsilon as the smallest number such that

1 machine epsilon < 1, or about 1.11e16.

The erf and erfc functions are also provided, and may sometimes be more useful than

cdfn and cdfnc.

Example

x = { -2 -1 0 1 2 };

n = cdfn(x);

nc = cdfnc(x);

x = 2.00000 1.00000 0.00000 1.00000 2.00000

n = 0.02275 0.15866 0.50000 0.84134 0.97725

nc = 0.97725 0.84134 0.50000 0.15866 0.02275

See also

erf, erfc, cdfbeta, cdfchic, cdftc, cdc, gamma

Technical Notes

For the integral from to x:

x 37, cdfn underows and 0.0 is returned

36 < x < 10, cdfn has a relative error of approx. 5e12

10 < x < 0, cdfn has a relative error of approx. 1e13

0 < x, cdfn has a relative error of approx. 5e15

For cdfnc, i.e., the integral from x to +, use the above accuracies but change x to x.

References:

1. ALGORITHM 304 NORMAL CURVE INTEGRAL, I.D. Hill and S.A.

Joyce, Comm. ACM, Vol. 10, No. 6, pp. 374-5, June 1967

2. REMARK ON ALGORITHM 304 NORMAL CURVE INTEGRAL,

A.G. Adams, Comm. ACM, Vol. 12, No. 10, pp. 565-6, Oct. 1969

3. REMARK ON ALGORITHM 304 NORMAL CURVE INTEGRAL, B.

Holmgren, Comm. ACM, Vol. 13, No. 10, Oct. 1970

4. Tables of the F- and related distributions with algorithms, K.V. Mardia

and P.J. Zemroch, Academic Press, New York, 1978, ISBN 0-12-471140-5

391

cdfn2 25. COMMAND REFERENCE

Purpose

Computes interval of Normal cumulative distribution function.

Format

y = cdfn2(x,dx);

Input

x MN matrix, abscissae.

dx KL matrix, ExE conformable to x, intervals.

Output

y max(M,K) by max(N,L) matrix, the integral from x to x+dx of the

Normal distribution, i.e., Pr(x X x +dx).

Remarks

The relative error is:

[x[ 1 and dx 1 1e 14

1 < [x[ < 37 and [dx[ < 1/[x[ 1e 13

min(x, x +dx) > 37 and y > 1e 300 1e 11 or better

A relative error of 1e 14 implies that the answer is accurate to better than 1 in

the 14th digit.

Example

print cdfn2(1,0.5);

9.1848052662599017e-02

print cdfn2(20,0.5);

2.7535164718736454e-89

print cdfn2(20,1e-2);

5.0038115018684521e-90

print cdfn2(-5,2);

1.3496113800582164e-03

print cdfn2(-5,0.15);

3.3065580013000255e-07

392

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdfn2

See also

lncdfn2

Source

lncdfn.src

393

cdftc 25. COMMAND REFERENCE

Purpose

Computes the complement of the cdf of the Students t distribution.

Format

y = cdftc(x,n);

Input

x NK matrix.

n LM matrix, EE conformable with x.

Output

y max(N,L) by max(K,M) matrix.

Remarks

y is the integral from x to of the t distribution with n degrees of freedom.

Allowable ranges for the arguments are:

< x < +

n > 0

A 1 is returned for those elements with invalid inputs.

This equals 1 F(x, n), where F is the t cdf with n degrees of freedom. Thus, to get

the t cdf, subtract cdftc(x,n) from 1. The complement of the cdf is computed because

this is what is most commonly needed in statistical applications, and because it can be

computed with fewer problems of roundo error.

Example

x = { .1, .2, .3, .4 };

n = 0.5;

y = cdftc(x,n);

y =

0.473165

0.447100

0.422428

0.399555

394

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdftc

See also

cdfbeta, cdfchic, cdc, cdfn, cdfnc, gamma

Technical Notes

For results greater than 0.5e30, the absolute error is approx. 1e14 and the relative

error is approx. 1e12. If you multiply the relative error by the result, then take the

minimum of that and the absolute error, you have the maximum actual error for any

result. Thus, the actual error is approx. 1e14 for results greater than 0.01. For

results less than 0.01, the actual error will be less. For example, for a result of 0.5e30,

the actual error is only 0.5e42.

References:

1. Reference Table: Students t-Distribution Quantiles to 20D, G.W. Hill,

Division of Mathematical Statistics Technical Paper No. 35,

Commonwealth Scientic and Industrial Research Organization, Australia,

1972

2. ALGORITHM 395 STUDENTS t -DISTRIBUTION, G.W. Hill, Comm.

ACM. Vol. 13, No. 10, Oct. 1970

3. Handbook of Mathematical Functions, Eds. M. Abramowitz and I. A.

Stegun, Dover, New York, 7th Ed, 1970, ISBN 0-486-61272-4

395

cdftnc 25. COMMAND REFERENCE

Purpose

The integral under noncentral Students t distribution, from to x. It can return a

vector of values, but the degrees of freedom and noncentrality parameter must be the

same for all values of x.

Format

y = cdftnc(x,v,d);

Input

x N1 vector, values of upper limits of integrals.

v scalar, degrees of freedom, v > 0.

d scalar, noncentrality parameter.

This is the square root of the noncentrality parameter that sometimes goes

under the symbol lambda. See Schee, THE ANALYSIS OF VARIANCE,

1959, app. IV.

Output

y N1 vector, integrals from to x of noncentral t .

Technical Notes

Relation to cdftc:

cdftc(x,v) = 1 - cdftnc(x,v,0);

The formula used is based on the formula in SUGI Supplemental Library

Users Guide, 1983, SAS Institute, page 232 (which is attributed to

Johnson and Kotz, 1970).

The formula used here is a modication of that formula. It has been tested

against direct numerical integration, and against simulation experiments in

which noncentral t random variates were generated and the cdf found

directly.

We invite any feedback from those using this function.

Source

cdfnonc.src

Globals

None

See also

cdnc, cdfchinc

396

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdftvn

Purpose

Computes the cumulative distribution function of the standardized trivariate Normal

density (lower tail).

Format

c = cdftvn(x1,x2,x3,rho12,rho23,rho31);

Input

x1 N1 vector of upper limits of integration for variable 1.

x2 N1 vector of upper limits of integration for variable 2.

x3 N1 vector of upper limits of integration for variable 3.

rho12 scalar or N1 vector of correlation coecients between the two variables

x1 and x2.

rho23 scalar or N1 vector of correlation coecients between the two variables

x2 and x3.

rho31 scalar or N1 vector of correlation coecients between the two variables

x1 and x3.

Output

c N1 vector containing the result of the triple integral from to x1,

to x2, and to x3 of the standardized trivariate Normal density:

f(x1,x2,x3,rho12,rho23,rho31)

Remarks

Allowable ranges for the arguments are:

< x1 < +

< x2 < +

< x3 < +

1 < rho12 < 1

1 < rho23 < 1

1 < rho31 < 1

397

cdftvn 25. COMMAND REFERENCE

In addition, rho12, rho23 and rho31 must come from a legitimate positive denite

matrix. A -1 is returned for those rows with invalid inputs.

A separate integral is computed for each row of the inputs.

The rst 3 arguments (x1,x2,x3) must be the same length, N. The second 3 arguments

(rho12,rho23,rho31) must also be the same length, and this length must be N or 1. If

it is 1, then these values will be expanded to apply to all values of x1,x2,x3. All inputs

must be column vectors.

To nd the integral under a general trivariate density, with x1, x2, and x3 having

nonzero means and any positive standard deviations, transform by subtracting the

mean and dividing by the standard deviation. For example:

x1 = ( x1 - meanc(x1) ) / stdc(x1);

See also

cdfn, cdfbvn

Technical Notes

The absolute error for cdftvn is approximately 2.5e8 for the entire range of

arguments.

References:

1. A Table for Computing Trivariate Normal Probabilities, G.P. Steck,

Ann. Math. Statist., Vol. 29, pp. 780-800

2. Computation of Bi- and Tri-variate Normal Integral, D.J. Daley, Appl.

Statist., Vol. 23, No. 3, pp. 435-438, 1974

398

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cdir

Purpose

Returns the current directory.

Format

y = cdir(s);

Input

s string, if the rst character is A-Z and the second character is a colon :

then that drive will be used. If not, the current default drive will be used.

Output

y string containing the drive and full path name of the current directory on

the specied drive.

Remarks

If the current directory is the root directory, the returned string will end with a

backslash, otherwise it will not.

A null string or scalar zero can be passed in as an argument to obtain the current drive

and path name.

Example

x = cdir(0);

y = cdir("d:");

print x;

print y;

C:\GAUSS

D:\

See also

les

399

ceil 25. COMMAND REFERENCE

Purpose

Round up toward +.

Format

y = ceil(x);

Input

x NK matrix.

Output

y NK matrix.

Remarks

This rounds every element in the matrix x to an integer. The elements are rounded up

toward +.

Example

x = 100*rndn(2,2);

y = ceil(x);

x =

77.68 14.10

4.73 158.88

y =

78.00 14.00

5.00 158.00

See also

oor, trunc

400

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE ChangeDir

Purpose

Changes the working directory.

Format

d = ChangeDir(s);

Input

s string, directory to change to

Output

d string, new working directory, or null string if change failed

See also

chdir

401

chdir 25. COMMAND REFERENCE

Purpose

Changes working directory.

Format

chdir dirstr;

Input

dirstr literal or string, directory to change to

Remarks

This is for interactive use. Use ChangeDir in a program.

If the directory change fails, chdir prints an error message.

The working directory is listed in the status report on the Unix version.

402

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE chol

Purpose

Computes the Cholesky decomposition of a symmetric, positive denite matrix.

Format

y = chol(x);

Input

x NN matrix.

Output

y NN matrix containing the Cholesky decomposition of x.

Remarks

y is the square root matrix of x. That is, it is an upper triangular matrix such that x

= y

y.

chol does not check to see that the matrix is symmetric. chol will look only at the

upper half of the matrix including the principal diagonal.

If the matrix x is symmetric but not positive denite, either an error message or an

error code will be generated, depending on the lowest order bit of the trap ag:

trap 0 Print error message and terminate program.

trap 1 Return scalar error code 10.

See scalerr and trap for more details about error codes.

Example

x = moment(rndn(100,4),0);

y = chol(x);

ypy = yy;

x =

90.746566 6.467195 1.927489 15.696056

6.467195 87.806557 6.319043 2.435953

1.927489 6.319043 101.973276 4.355520

15.696056 2.435953 4.355520 99.042850

y =

9.526099 0.678892 0.202338 1.647690

0.000000 9.345890 0.661433 0.380334

0.000000 0.000000 10.074465 0.424211

0.000000 0.000000 0.000000 9.798130

ypy =

90.746566 6.467195 1.927489 15.696056

6.467195 87.806557 6.319043 2.435953

1.927489 6.319043 101.973276 4.355520

15.696056 2.435953 4.355520 99.042850

See also

crout, solpd

403

choldn 25. COMMAND REFERENCE

Purpose

Performs a Cholesky downdate of one or more rows on an upper triangular matrix.

Format

r = choldn(C,x);

Input

C KK upper triangular matrix.

x NK matrix, the rows to downdate C with.

Output

r KK upper triangular matrix, the downdated matrix.

Remarks

C should be a Cholesky factorization.

choldn(C,x) is equivalent to chol(C

C - x

stable.

Warning: it is possible to render a Cholesky factorization non-positive denite with

choldn. You should keep an eye on the ratio of the largest diagonal element of r to the

smallestif it gets very large, r may no longer be positive denite. This ratio is a

rough estimate of the condition number of the matrix.

Example

let C[3,3] = 20.16210005 16.50544413 9.86676135

0 11.16601462 2.97761666

0 0 11.65496052;

let x[2,3] = 1.76644971 7.49445820 9.79114666

6.87691156 4.41961438 4.32476921;

r = choldn(C,x);

r =

18.87055964 15.32294435 8.04947012

0.00000000 9.30682813 2.12009339

0.00000000 0.00000000 7.62878355

See also

cholup

404

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cholsol

Purpose

Solves a system of linear equations given the Cholesky factorization of the system.

Format

x = cholsol(b,C);

Input

b NK matrix.

C NN matrix.

Output

x NK matrix.

Remarks

C is the Cholesky factorization of a linear system of equations A. x is the solution for

Ax = b. b can have more than one column. If so, the system is solved for each column,

i.e., A x[., i] = b[., i].

cholsol(eye(N),C) is equivalent to invpd(A). Thus, if you have the Cholesky

factorization of A, cholsol is the most ecient way to obtain the inverse of A.

Example

let b[3,1] = 0.03177513 0.41823100 1.70129375;

let C[3,3] = 1.73351215 1.53201723 1.78102499

0 1.09926365 0.63230050

0 0 0.67015361;

x = cholsol(b,C);

x =

1.94396905

1.52686768

3.21579513

A0 =

3.00506436 2.65577048 3.08742844

2.65577048 3.55545737 3.42362593

3.08742844 3.42362593 4.02095978

405

cholup 25. COMMAND REFERENCE

Purpose

Performs a Cholesky update of one or more rows on an upper triangular matrix.

Format

r = cholup(C,x);

Input

C KK upper triangular matrix.

x NK matrix, the rows to update C with.

Output

r KK upper triangular matrix, the updated matrix.

Remarks

C should be a Cholesky factorization.

cholup(C,x) is equivalent to chol(C

C + x

stable.

Example

let C[3,3] = 18.87055964 15.32294435 8.04947012

0 9.30682813 -2.12009339

0 0 7.62878355;

let x[2,3] = 1.76644971 7.49445820 9.79114666

6.87691156 4.41961438 4.32476921;

r = cholup(C,x);

r =

20.16210005 16.50544413 9.86676135

0.00000000 11.16601462 2.97761666

0.00000000 0.00000000 11.65496052

See also

choldn

406

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE chrs

Purpose

Converts a matrix of ASCII values into a string containing the appropriate characters.

Format

y = chrs(x);

Input

x NK matrix.

Output

y string of length N*K containing the characters whose ASCII values are

equal to the values in the elements of x.

Remarks

This function is useful for imbedding control codes in strings and for creating variable

length strings when formatting printouts, reports, etc.

Example

n = 5;

print chrs(ones(n,1)*42);

*****

Since the ASCII value of the asterisk character is 42, the program above will print a

string of n asterisks.

y = chrs(67~65~84);

print y;

CAT

See also

vals, ftos, stof

407

clear 25. COMMAND REFERENCE

Purpose

Clears space in memory by setting matrices equal to scalar zero.

Format

clear x, y;

Remarks

clear x; is equivalent to x = 0;.

Matrix names are retained in the symbol table after they are cleared.

Matrices can be cleared even though they have not previously been dened. clear can

be used to initialize matrices to scalar 0.

Example

clear x;

See also

clearg, new, show, delete

408

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE clearg

Purpose

This command clears global symbols by setting them equal to scalar zero.

Format

clearg a,b,c;

Output

a,b,c scalar global matrices containing 0.

Remarks

clearg x; is equivalent to x = 0;, where x is understood to be a global symbol. clearg

can be used to initialize symbols not previously referenced. This command can be used

inside of procedures to clear global matrices. It will ignore any locals by the same name.

Example

x = 45;

clearg x;

x = 0.0000000

See also

clear, delete, new, show, local

409

close 25. COMMAND REFERENCE

Purpose

Close a GAUSS le.

Format

y = close(handle);

Input

handle scalar, the le handle given to the le when it was opened with the open,

create, or fopen command.

Output

y scalar, 0 if successful, -1 if unsuccessful.

Remarks

handle is the scalar le handle created when the le was opened. It will contain an

integer which can be used to refer to the le.

close will close the le specied by handle, and will return a 0 if successful and a -1 if

not successful. The handle itself is not aected by close unless the return value of close

is assigned to it.

If f1 is a le handle and it contains the value 7, then after:

call close(f1);

the le will be closed but f1 will still have the value 7. The best procedure is to do the

following:

f1 = close(f1);

This will set f1 to 0 upon a successful close.

It is important to set unused le handles to zero because both open and create check

the value that is in a le handle before they proceed with the process of opening a le.

During open or create, if the value that is in the le handle matches that of an already

open le, the process will be aborted and a File already open message will be given.

This gives you some protection against opening a second le with the same handle as a

currently open le. If this happened, you would no longer be able to access the rst le.

An advantage of the close function is that it returns a result which can be tested to see

if there were problems in closing a le. The most common reason for having a problem

410

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE close

in closing a le is that the disk on which the le is located is no longer in the disk

driveor the handle was invalid. In both of these cases, close will return a -1.

Files are not automatically closed when a program terminates. This allows users to run

a program that opens les, and then access the les from COMMAND mode after the

program has been run. Files are automatically closed when GAUSS exits to the

operating system or when a program is terminated with the end statement. stop will

terminate a program but not close les.

As a rule it is good practice to make end the last statement in a program, unless

further access to the open les is desired from COMMAND mode. You should close

les as soon as you are done writing to them to protect against data loss in the case of

abnormal termination of the program due to a power or equipment failure.

The danger in not closing les is that anything written to the les may be lost. The

disk directory will not reect changes in the size of a le until the le is closed and

system buers may not be ushed.

Example

open f1 = dat1 for append;

y = writer(f1,x);

f1 = close(f1);

See also

closeall

411

closeall 25. COMMAND REFERENCE

Purpose

Close all currently open GAUSS les.

Format

closeall;

closeall list of handles;

Remarks

list of handles is a comma-delimited list of le handles.

closeall with no specied list of handles will close all les. The le handles will not be

aected. The main advantage of using closeall is ease of use; the le handles do not

have to be specied, and one statement will close all les.

When a list of handles follows closeall, all les are closed and the le handles listed are

set to scalar 0. This is safer than closeall without a list of handles because the handles

are cleared.

It is important to set unused le handles to zero because both open and create check

the value that is in a le handle before they proceed with the process of opening a le.

During open or create, if the value that is in the le handle matches that of an already

open le, the process will be aborted and a File already open message will be given.

This gives you some protection against opening a second le with the same handle as a

currently open le. If this happened, you would no longer be able to access the rst le.

Files are not automatically closed when a program terminates. This allows users to run

a program that opens les, and then access the les from COMMAND mode after the

program has been run. Files are automatically closed when GAUSS exits to the

operating system or when a program is terminated with the end statement. stop will

terminate a program but not close les.

As a rule it is good practice to make end the last statement in a program, unless

further access to the open les is desired from COMMAND mode. You should close

les as soon as you are done writing to them to protect against data loss in the case of

abnormal termination of the program due to a power or equipment failure.

The danger in not closing les is that anything written to the les may be lost. The

disk directory will not reect changes in the size of a le until the le is closed and

system buers may not be ushed.

Example

open f1 = dat1 for read;

open f2 = dat1 for update;

x = readr(f1,rowsf(f1));

x = sqrt(x);

call writer(f2,x);

closeall f1,f2;

412

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE closeall

See also

close, open

413

cls 25. COMMAND REFERENCE

Purpose

Clear the screen.

Format

cls;

Portability

Unix, OS/2, Windows

cls clears the active window. For Text windows, this means the window buer is

cleared to the background color. For TTY windows, the current output line is panned

to the top of the window, eectively clearing the display. The output log is still intact.

To clear the output log of a TTY window, use WinClearTTYLog. For PQG windows,

the window is cleared to the background color, and the related graphics le is truncated

to zero length.

Remarks

This command will cause the screen to clear and will locate the cursor at the upper left

hand corner of the screen.

See also

locate

414

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE code

Purpose

Allows a new variable to be created (coded) with dierent values depending upon

which one of a set of logical expressions is true.

Format

y = code(e,v);

Input

e NK matrix of 1s and 0s. Each column of this matrix is created by a

logical expression using dot conditional and boolean operators. Each of

these expressions should return a column vector result. The columns are

horizontally concatenated to produce e. If more than one of these vectors

contains a 1 in any given row, the code function will terminate with an

error message.

v (K+1)x1 vector containing the values to be assigned to the new variable.

Output

y N1 vector containing the new values.

Remarks

If none of the K expressions is true, the new variable is assigned the default value,

which is given by the last element of v.

Example

let x1 = 0 /* column vector of original values */

5

10

15

20;

let v = 1 /* column vector of new values */

2

3; /* the last element of v is the "default" */

e1 = (0 .lt x1) .and (x1 .le 5); /* expression 1 */

e2 = (5 .lt x1) .and (x1 .le 25); /* expression 2 */

e = e1~e2; /* concatenate e1 & e2 to make a 1,0 mask

:: with one less column than the number

:: of new values in v.

*/

y = code(e,v);

415

code 25. COMMAND REFERENCE

x1[5, 1] =

0

5

10

15

20

(column vector of original values)

v[3, 1] = 1 2 3 (Note: v is a column vector)

e[5, 2] =

0 0

1 0

0 1

0 1

0 1

y[5, 1] =

3

1

2

2

2

For every row in e, if a 1 is in the rst column, the rst element of v is used. If a 1 is in

the second column, the second element of v is used, and so on. If there are only zeros in

the row, the last element of v is used. This is the default value.

If there is more than one 1 in any row of e, the function will terminate with an error

message.

Source

datatran.src

Globals

None

See also

recode, substute

416

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE color

Purpose

Set pixel, text, background color, or VGA palette color registers.

Format

y = color(cv)

Input

cv scalar, 21 or 31 vector of color values or N4 matrix of palette color

values. See Portability for platform specics.

If the input vector is smaller than 31 or the corresponding element in the

input vector is -1, the corresponding color will be left unchanged.

If the input is an N4 matrix, it will initialize the VGA palette with

user-dened RGB colors interpreted as follows:

[N,1] palette register index 0-255

[N,2] red value 0-63

[N,3] green value 0-63

[N,4] blue value 0-63

Output

y vector, or N4 matrix the same size as the input which contains the

original color values or palette values.

Portability

Dos

[1] pixel color

[2] text color

[3] ignored

Unix

color aects the active window. X supports foreground and background colors. The

color command makes no distinction between text and pixel colors; both aect the

foreground color of the active window. If both a pixel color and text color are specied,

417

color 25. COMMAND REFERENCE

the pixel color will be ignored, and the text color will be used to set the foreground

color. Thus:

[1] foreground

or

[1] ignored

[2] foreground

or

[1] ignored

[2] foreground

[3] background

OS/2, Windows

This function is not supported under OS/2 or Windows.

Remarks

This changes the screen colors for your programs output. The editor and COMMAND

mode will not be aected.

The color values 0-15 may be obtained through the help system by requesting help on

@PQG. You will have to page down several pages to the page listing the color values.

Under DOS, the VGA color palette registers may be set only if the display adapter has

been already been initialized to VGA graphics mode 19 (320200, 256 colors) with the

setvmode command. The registers will retain the new values until the adapter is reset

to text mode, which resets the palette to the default VGA colors.

This function is useful for obtaining 64 shades of a single color and/or mixing colors to

user-specication.

See also

graph, line, setvmode

418

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cols, colsf

Purpose

cols returns the number of columns in a matrix.

colsf returns the number of columns in a GAUSS data (.dat) le or GAUSS matrix

(.fmt) le.

Format

y = cols(x);

yf = colsf(fh);

Input

x any valid expression that returns a matrix.

fh le handle of an open le.

Output

y number of columns in x.

yf number of columns in the le that has the handle fh.

Remarks

If x is an empty matrix, rows(x) and cols(x) return 0.

For colsf, the le must be open.

Example

x = rndn(100,3);

y = cols(x);

y = 3.000000

create fp = myfile with x,10,4;

b = colsf(fp);

b = 10.000000

See also

rows, rowsf, show, lshow

419

comlog 25. COMMAND REFERENCE

Purpose

Controls logging of COMMAND mode commands to a disk le.

Format

comlog [[le=lename]] [[on[o[reset]] ;

Input

lename literal or ^string.

The le=lename subcommand selects the le to log COMMAND mode

statements to. This can be any legal le name.

If the name of the le is to be taken from a string variable, the name of the

string must be preceded by the ^ (caret) operator.

There is no default le name.

on, o, reset literal, mode command

on turns on command logging to the current log le. If the le already

exists, subsequent commands will be appended.

o closes the log le and turns o command logging.

reset similar to the on subcommand, except that it resets the log le by

deleting any previous commands.

Portability

This function is supported only under DOS.

Remarks

COMMAND mode statements are always logged into the le specied in the log le

conguration variable, regardless of the state of comlog.

The command comlog le=lename selects the le but does not turn on logging.

The command comlog o will turn o logging. The lename will remain the same. A

subsequent comlog on will cause logging to resume. A subsequent comlog reset will

cause the existing contents of the log le to be destroyed and a new le created.

The command comlog by itself will cause the name and status of the current log le to

be printed on the screen.

In COMMAND mode under DOS, F10 will load the current log le into the editor if

logging is on. If logging is o, the default log le listed in the log le conguration

variable will be loaded into the editor.

420

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE compile

Purpose

Compiles a source le to a compiled code le. See also Chapter 11.

Format

compile source fname;

Input

source literal or string, the name of the le to be compiled.

fname literal or string, optional, the name of the le to be created. If not given,

the le will have the same lename and path as source. It will have a .gcg

extension.

Remarks

The source le will be searched for in the src path if the full path is not specied and it

is not present in the current directory.

The source le is a regular DOS text le containing a GAUSS program. There can be

references to global symbols, Run-Time Library references, etc.

If there are library statements in source, they will be used during the compilation to

locate various procedures and symbols used in the program. Since all of these library

references are resolved at compile time, the library statements are not transferred to the

compiled le. The compiled le can be run without activating any libraries.

If you do not want extraneous stu saved in the compiled image, put a new at the top

of the source le or execute a new from COMMAND level before compiling.

The program saved in the compiled le can be run with the run command. If no

extension is given, the run command will look for a le with the correct extension for

the version of GAUSS. The src path will be used to locate the le if the full path name

is not given and it is not located on the current directory.

When the compiled le is run, all previous symbols and procedures are deleted before

the program is loaded. It is therefore unnecessary to execute a new before running a

compiled le.

If you want line number records in the compiled le you can put a #lineson statement

in the source le or turn line tracking on from the Options menu.

Dont try to include compiled les with #include.

Example

421

compile 25. COMMAND REFERENCE

compile qxy.e;

In this example, the src path would be searched for qxy.e, which would be compiled to

a le called qxy.gcg on the same subdirectory qxy.e was found.

compile qxy.e xy;

In this example, the src path would be searched for qxy.e which would be compiled to

a le called xy.gcg on the current subdirectory.

See also

run, use, saveall

422

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE complex

Purpose

Converts a pair of real matrices to a complex matrix.

Format

z = complex(xr,xi );

Input

xr NK real matrix, the real elements of z.

xi NK real matrix or scalar, the imaginary elements of z.

Output

z NK complex matrix.

Example

x = { 4 6,

9 8 };

y = { 3 5,

1 7 };

t = complex(x,y);

t =

4.0000000 + 3.0000000i 6.0000000 + 5.0000000i

9.0000000 + 1.0000000i 8.0000000 + 7.0000000i

See also

imag, real

423

con 25. COMMAND REFERENCE

Purpose

Requests input from the keyboard (console), and returns it in a matrix.

Format

x = con(r,c);

Input

r scalar, row dimension of matrix.

c scalar, column dimension of matrix.

Output

x RC matrix.

Portability

Unix, OS/2, Windows

con gets input from the active window. If you are working in terminal mode GAUSS

will not see any input until you press Enter, so follow each entry with an Enter.

Cursor keys are not supported in terminal mode.

Remarks

r and c may be any scalar-valued expressions. Nonintegers will be truncated to an

integer.

A con function in a program will cause a question mark to appear on the screen. You

can then type in numbers, and they will be placed into a matrix. GAUSS will wait

until r c numbers have been typed in (e.g., if r = 3 and c = 2, then GAUSS will wait

for 6 numbers). All GAUSS cares about is getting enough numbersit knows how to

arrange them in a matrix from the dimensions specied. The numbers can be separated

by spaces, commas or carriage returns.

When r c numbers have been entered, the program will resume with the next

command.

A matrix editor is invoked when the con function is called. This editor allows you to

move around the matrix you are entering and make changes. See editm for an

additional discussion.

424

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE con

The matrix editor allows you to use the cursor keys to move along rows or up and down

columns in the matrix. When you come to the end of a row or column, movement is

left and up, or right and down. If, for instance, you are moving left to right along a row

using the right cursor key, you will move down to the beginning of the next row when

you come to the end of the row you are in. GAUSS will beep at you if you try to move

outside the matrix.

The matrix editor will show you what is in each element, and will prompt you for a new

number. If you do not want to change anything, you can move to a dierent element by

hitting the appropriate cursor key. If you start to type a number and then hit a cursor

key, the number will not be saved. The BACKSPACE key will delete characters to the

left of the cursor.

If you type in a space, comma or carriage return before you type a number, nothing

will happen. GAUSS will wait until you type a number or use a cursor key to move to

a new element.

Numbers can be entered in scientic notation. The syntax is: dE+n or dE-n, where d

is a number and n is an integer (denoting the power of 10). Thus, 1E+10, 1.1e-4,

1100E+1 are all legal.

Complex numbers can be entered by joining the real and imaginary parts with a sign

(+ or -); there can be no spaces between the numbers and the sign. Numbers with no

real part can be entered by appending an i to the number. For example, 1.2+23,

8.56i, 3-2.1i, -4.2e+6i and 1.2e-4-4.5e+3i are all legal.

If using DOS, and e can be entered with Alt-P and Alt-E.

A con function can appear anywhere in an expression that any other function can

appear.

Example

n = con(1,1);

print rndn(n,n);

? 2

0.148030 0.861562

1.791516 0.663392

In this example, the con function is used to obtain the size of a square matrix of

Normal random variables which is to be printed out.

See also

cons, editm, let, load, medit

425

cond 25. COMMAND REFERENCE

Purpose

This procedure will compute the condition number of a matrix using the singular value

decomposition.

Format

c = cond(x);

Input

x NK matrix.

Output

c scalar, an estimate of the condition number of x. This equals the ratio of

the largest singular value to the smallest. If the smallest singular value is

zero or not all of the singular values can be computed, the return value is

10

300

.

Example

x = { 4 2 6,

8 5 7,

3 8 9 };

y = cond(x);

y = 9.8436943

Source

svd.src

Globals

None

426

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE conj

Purpose

Returns the complex conjugate of a matrix.

Format

y = conj(x);

Input

x NK matrix.

Output

y NK matrix, the complex conjugate of x.

Remarks

Compare conj with the transpose (

) operator.

Example

x = { 1+9i 2,

4+4i 5i,

7i 8-2i };

y = conj(x);

x =

1.0000000 + 9.0000000i 2.0000000

4.0000000 + 4.0000000i 0.0000000 +5.0000000i

0.0000000 + 7.0000000i 8.0000000 2.0000000i

y =

1.0000000 9.0000000i 2.0000000

4.0000000 4.0000000i 0.0000000 5.0000000i

0.0000000 7.0000000i 8.0000000 +2.0000000i

427

cons 25. COMMAND REFERENCE

Purpose

Retrieves a character string from the keyboard.

Format

x = cons;

Output

The characters entered from the keyboard. The output will be of type string.

Portability

Unix

cons gets input from the active window.

Remarks

x is assigned the value of a character string typed in at the keyboard. The program will

pause to accept keyboard input. The maximum length of the string that can be entered

is 254 characters. The program will resume execution when the Enter key is pressed.

The standard DOS editing keys will be in eect.

Example

x = cons;

At the cursor enter:

probability

x = probability

See also

con

428

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE continue

Purpose

Jumps to the top of a do or for loop.

Format

continue;

Example

x = rndn(4,4);

r = 0;

do while r < rows(x);

r = r + 1;

c = 0;

do while c < cols(x); /* continue jumps here */

c = c + 1;

if c == r;

continue;

endif;

x[r,c] = 0;

endo;

endo;

x =

1.032195 0.000000 0.000000 0.000000

0.000000 1.033763 0.000000 0.000000

0.000000 0.000000 0.061205 0.000000

0.000000 0.000000 0.000000 0.225936

Remarks

This command works just like in C.

429

conv 25. COMMAND REFERENCE

Purpose

Computes the convolution of two vectors.

Format

c = conv(b,x,f ,l );

Input

b N1 vector.

x L1 vector.

f scalar, the rst convolution to compute.

l scalar, the last convolution to compute.

Output

c Q1 result, where Q = (l f + 1) .

If f is 0, the rst to the l th convolutions are computed. If l is 0, the f th

to the last convolutions are computed. If f and l are both zero, all the

convolutions are computed.

Remarks

If x and b are vectors of polynomial coecients, this is the same as multiplying the two

polynomials.

Example

x = { 1,2,3,4 };

y = { 5,6,7,8 };

z1 = conv(x,y,0,0);

z2 = conv(x,y,2,5);

z1 =

5

16

34

60

61

52

32

z2 =

16

34

60

61

See also

polymult

430

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE coreleft

Purpose

Returns the amount, in bytes, of free workspace memory.

Format

y = coreleft;

Output

y scalar, number of bytes free.

Remarks

The amount of free memory is dynamic and can change rapidly as expressions and

procedures are being executed. coreleft returns the amount of workspace memory free

at the time it is called. Workspace memory is used for storing matrices, strings,

procedures, and for manipulating matrices and strings.

This function can be used to write programs that automatically adjust their use of

memory so they do not crash with the Insucient memory error if they are used on

machines with less free memory than the one used for development or if the size of the

data used becomes larger. A common use is to adjust the number of rows that are read

per iteration of a read loop in programs that access data from a disk.

Example

open fp = myfile;

k = colsf(fp); /* columns in file */

fac = 4;

/* check amount of memory available */

nr = coreleft/(fac*k*8);

In this example, nr, the number of rows to read, is computed by taking the number of

bytes free (coreleft) divided by fac*k*8. fac is a guesstimate of the number of copies of

the data read each iteration that the algorithm we are using will require plus a little

slop. k*8 is the number of columns times the number of bytes per element.

See also

dfree, new

431

corrm, corrvc, corrx 25. COMMAND REFERENCE

Purpose

Computes a correlation matrix.

Format

cx = corrm(m);

cx = corrvc(vc);

cx = corrx(x);

Input

m KK moment (x

variable when the moment matrix was computed.

vc KK variance-covariance matrix (of data or parameters).

x NK matrix of data.

Output

cx PP correlation matrix. For corrm, P = K 1. For corrvc and corrx,

P = K.

Source

corr.src

Globals

None

See also

momentd

432

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cos

Purpose

Returns the cosine of its argument.

Format

y = cos(x);

Input

x NK matrix.

Output

y NK matrix.

Remarks

For real matrices, x should contain angles measured in radians.

To convert degrees to radians, multiply the degrees by

180

.

Example

x = { 0, .5, 1, 1.5 };

y = cos(x);

y =

1.00000000

0.87758256

0.54030231

0.07073720

See also

atan, atan2, pi

433

cosh 25. COMMAND REFERENCE

Purpose

Computes the hyperbolic cosine.

Format

y = cosh(x);

Input

x NK matrix.

Output

y NK matrix containing the hyperbolic cosines of the elements of x.

Example

x = { -0.5, -0.25, 0, 0.25, 0.5, 1 };

x = x * pi;

y = cosh(x);

x =

1.570796

0.785398

0.000000

0.785398

1.570796

3.141593

y =

2.509178

1.324609

1.000000

1.324609

2.509178

11.591953

Source

trig.src

Globals

None

434

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE counts

Purpose

Count the numbers of elements of a vector that fall into specied ranges.

Format

c = counts(x,v);

Input

x N1 vector containing the numbers to be counted.

v P1 vector containing breakpoints specifying the ranges within which

counts are to be made. The vector v MUST be sorted in ascending order.

Output

c P1 vector, the counts of the elements of x that fall into the regions:

x v[1],

v[1] < x v[2],

.

.

.

v[p 1] < x v[p].

Remarks

If the maximum value of x is greater than the last element (the maximum value) of v,

the sum of the elements of the result, c, will be less than N, the total number of

elements in x.

If

x =

1

2

3

4

5

6

7

8

9

and v =

4

5

8

then

c =

4

1

3

435

counts 25. COMMAND REFERENCE

The rst category can be a missing value if you need to count missings directly. Also

+ or are allowed as breakpoints. The missing value must be the rst breakpoint

if it is included as a breakpoint and innities must be in the proper location depending

on their sign. must be in the [2,1] element of the breakpoint vector if there is a

missing value as a category as well, otherwise it has to be in the [1,1] element. If + is

included, it must be the last element of the breakpoint vector.

Example

x = { 1, 3, 2,

4, 1, 3 };

v = { 0, 1, 2, 3, 4 };

c = counts(x,v);

c =

0.0000000

2.0000000

1.0000000

2.0000000

1.0000000

436

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE countwts

Purpose

Returns a weighted count of the numbers of elements of a vector that fall into specied

ranges.

Format

c = countwts(x,v,w);

Input

x N1 vector, the numbers to be counted.

v P1 vector, the breakpoints specifying the ranges within which counts are

to be made. This MUST be sorted in ascending order (lowest to highest).

w N1 vector, containing weights.

Output

c P1 vector containing the weighted counts of the elements of x that fall

into the regions:

x v[1]

v[1] < x v[2]

. . .

v[p 1] < x v[p]

That is, when x[i] falls into region j , the weight w[i] is added to the j

th

counter.

Remarks

If any elements of x are greater than the last element of v, they will not be counted.

Missing values are not counted unless there is a missing in v. A missing value in v

MUST be the rst element in v.

Example

x = { 1, 3, 2, 4, 1, 3 };

w = { .25, 1, .333, .1, .25, 1 };

v = { 0, 1, 2, 3, 4 };

c = countwts(x,v,w);

c =

0.000000

0.500000

0.333000

2.00000

0.100000

437

create 25. COMMAND REFERENCE

Purpose

Creates and opens a GAUSS data set for subsequent writing.

Format

create [[vag]] [[complex]] fh = lename with vnames,col ,dtyp,vtyp;

create [[vag]] [[complex]] fh = lename using comle;

Input

vag version ag.

-v89 supported on DOS, OS/2, Windows NT

-v92 supported on Unix

-v96 supported on all platforms

See the File I/O chapter in Volume I of the manual for details on the

various versions. The default format can be specied in gauss.cfg by

setting the dat fmt version conguration variable. If dat fmt version

is not set, the default is v96.

lename literal or ^string

lename is the name to be given to the le on the disk. The name can

include a path if the directory to be used is not the current directory. This

le will automatically be given the extension .dat. If an extension is

specied, the .dat will be overridden. If the name of the le is to be taken

from a string variable, the name of the string must be preceded by the ^

(caret) operator.

create... with...

vnames literal or ^string or ^character matrix.

vnames controls the names to be given to the columns of the data le. If

the names are to be taken from a string or character matrix, the ^ (caret)

operator must be placed before the name of the string or character matrix.

The number of columns parameter, col , also has an eect on the way the

names will be created. See below and see the examples for details on the

ways names are assigned to a data le.

col scalar expression.

col is a scalar expression containing the number of columns in the data le.

If col is 0, the number of columns will be controlled by the contents of

vnames. If col is positive, the le will contain col columns and the names

to be given each column will be created as necessary depending on the

vnames parameter. See the examples.

438

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE create

dtyp scalar expression.

dtyp is the precision used to store the data. This is a scalar expression

containing 2, 4, or 8, which is the number of bytes per element.

2 signed integer

4 single precision

8 double precision

data type digits range

integer 4 32768 X 32767

single 6-7 8.43x10

37

[X[ 3.37x10

+38

double 15-16 4.19x10

307

[X[ 1.67x10

+308

If the integer type is specied, numbers will be rounded to the nearest

integer as they are written to the data set. If the data to be written to the

le contains character data, the precision must be 8 or the character

information will be lost.

vtyp matrix, types of variables.

The types of the variables in the data set. If rows(vtyp)*cols(vtyp) < col

only the rst element is used. Otherwise nonzero elements indicate a

numeric variable and zero elements indicate character variables. vtyp is

ignored for v89 les.

create... using...

comle literal or ^string.

comle is the name of a command le that contains the information

needed to create the le. The default extension for the command le is

.gcf, which can be overridden.

There are three possible commands in this le:

NUMVAR n str;

OUTVAR varlist;

OUTTYP dtyp;

NUMVAR and OUTVAR are alternate ways of specifying the number and

names of the variables in the data set to be created.

When NUMVAR is used, n is a constant which species the number of

variables (columns) in the data le and str is a string literal specifying the

prex to be given to all the variables. Thus:

numvar 10 xx;

439

create 25. COMMAND REFERENCE

says that there are 10 variables and that they are to be named xx01

through xx10. The numeric part of the names will be padded on the left

with zeros as necessary so the names will sort correctly:

xx1, . . . xx9 19 names

xx01, . . . xx10 1099 names

xx001, . . . xx100 100999 names

xx0001, . . . xx1000 10008100 names

If str is omitted, the variable prex will be X.

When OUTVAR is used, varlist is a list of variable names, separated by

spaces or commas. For instance:

outvar x1, x2, zed;

species that there are to be 3 variables per row of the data set, and that

they are to be named X1, X2, ZED, in that order.

OUTTYP species the precision. It can be a constant: 2, 4, or 8, or it can

be a literal: I, F, or D. See dtyp above in the discussion of create... with...

for an explanation of the available data types.

The OUTTYP statement does not have to be included. If it is not, then

all data will be stored in 4 bytes as single precision oating point numbers.

Output

fh scalar.

fh is the le handle which will be used by most commands to refer to the

le within GAUSS. This le handle is actually a scalar containing an

integer value that uniquely identies each le. This value is assigned by

GAUSS when the create (or open) command is executed.

Remarks

If the complex ag is included, the new data set will be initialized to store complex

number data. Complex data is stored a row at a time, with the real and imaginary

halves interleaved, element by element.

Example

let vnames = age sex educat wage occ;

create f1 = simdat with ^vnames,0,8;

obs = 0; nr = 1000;

do while obs < 10000;

data = rndn(nr,colsf(f1));

if writer(f1,data) /= nr;

440

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE create

print "Disk Full"; end;

endif;

obs = obs+nr;

endo;

closeall f1;

The example above uses create... with... to create a double precision data le called

simdat.dat on the default drive with 5 columns. The writer command is used to write

10000 rows of Normal random numbers into the le. The variables (columns) will be

named: AGE, SEX, EDUCAT, WAGE, OCC.

Here are some examples of the variable names that will result when using a character

vector of names in the argument to the create function.

vnames = { AGE PAY SEX JOB };

typ = { 1, 1, 0, 0 };

create fp = mydata with ^vnames,0,2,typ;

The names in the above program will be: AGE PAY SEX JOB

AGE and PAY are numeric variables, SEX and JOB are character variables.

create fp = mydata with ^vnames,3,2;"

The names will be: AGE PAY SEX

create fp = mydata with ^vnames,8,2;

The names will now be: AGE PAY SEX JOB1 JOB2 JOB3 JOB4 JOB5

If a literal is used for the vnames parameter, then the number of columns should be

explicitly given in the col parameter and the names will be created as follows:

create fp = mydata with var,4,2;

Giving the names: VAR1 VAR2 VAR3 VAR4

For the next example we will assume a command le called comd.gcf containing the

following lines has been created using a text editor.

outvar age, pay, sex;

outtyp i;

Then the following program could be used to write 100 rows of random integers into a

le called smpl.dat in the subdirectory called /gauss/data:

441

create 25. COMMAND REFERENCE

filename = "/gauss/data/smpl";

create fh = ^filename using comd;

x = rndn(100,3)*10;

if writer(fh,x) /= rows(x);

print "Disk Full"; end;

endif;

closeall fh;

For platforms using the backslash as a path separator, remember that two backslashes

(\\) are required to enter one backslash inside of double quotes. This is because a

backslash is the escape character used to embed special characters in strings.

See also

open, readr, writer, eof, close, output, iscplxf

442

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE crossprd

Purpose

Computes the cross-products (vector products) of sets of 31 vectors.

Format

z = crossprd(x,y);

Input

x 3K matrix, each column is treated as a 31 vector.

y 3K matrix, each column is treated as a 31 vector.

Output

z 3K matrix, each column is the cross-product (sometimes called vector

product) of the corresponding columns of x and y.

Remarks

The cross-product vector z is orthogonal to both x and y. sumc(x.*z) and sumc(y.*z)

will be K1 vectors all of whose elements are 0 (except for rounding error).

Example

x = { 10 4,

11 13,

14 13 };

y = { 3 11,

5 12,

7 9 };

z = crossprd(x,y);

z =

7.0000000 39.000000

28.000000 107.00000

17.000000 95.000000

Source

crossprd.src

Globals

None

443

crout 25. COMMAND REFERENCE

Purpose

Computes the Crout decomposition of a square matrix without row pivoting, such that:

X = LU.

Format

y = crout(x);

Input

x NN square nonsingular matrix.

Output

y NN matrix containing the lower (L) and upper (U) matrices of the Crout

decomposition of x. The main diagonal of y is the main diagonal of the

lower matrix L. The upper matrix has an implicit main diagonal of ones.

Use lowmat and upmat1 to extract the L and U matrices from y.

Remarks

Since it does not do row pivoting, it is intended primarily for teaching purposes. See

croutp for a decomposition with pivoting.

Example

X = { 1 2 -1,

2 3 -2,

1 -2 1 };

y = crout(x);

L = lowmat(y);

U = upmat1(y);

y =

1 2 1

2 1 0

1 4 2

L =

1 0 0

2 1 0

1 4 2

U =

1 2 1

0 1 0

0 0 1

See also

croutp, chol, lowmat, lowmat1, lu, upmat, upmat1

444

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE croutp

Purpose

Computes the Crout decomposition of a square matrix with partial (row) pivoting.

Format

y = croutp(x);

Input

x NN square nonsingular matrix.

Output

y (N+1)xN matrix containing the lower (L) and upper (U) matrices of the

Crout decomposition of a permuted x. The N+1 row of the matrix y gives

the row order of the y matrix. The matrix must be reordered prior to

extracting the L and U matrices. Use lowmat and upmat1 to extract the

L and U matrices from the reordered y matrix.

Example

This example illustrates a procedure for extracting L and U of the permuted x matrix.

It continues by sorting the result of LU to compare with the original matrix x.

X = { 1 2 -1,

2 3 -2,

1 -2 1 };

y = croutp(x);

r = rows(y); /* the number of rows of y */

indx = y[r,.]; /* get the index vector */

z = y[indx,.]; /* z is indexed RxR matrix y */

L = lowmat(z); /* obtain L and U of permuted matrix X */

U = upmat1(z);

q = sortc(indx~(L*U),1); /* sort L*U against index */

x2 = q[.,2:cols(q)]; /* remove index column */

X =

1 2 1

2 3 2

1 2 1

y =

1 0.5 0.2857

2 1.5 1

1 3.5 0.5714

2 3 1

445

croutp 25. COMMAND REFERENCE

r = 4

indx =

2

3

1

z =

2 1.5 1

1 3.5 0.5714

1 0.5 0.2857

L =

2 0 0

1 3.5 0

1 0.5 0.2857

U =

1 1.5 1

0 1 0.5714

0 0 1

q =

1 1 2 1

2 2 3 2

3 1 2 1

x2 =

1 2 1

2 3 2

1 2 1

See also

crout, chol, lowmat, lowmat1, lu, upmat, upmat1

446

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE csrcol, csrlin

Purpose

Returns the position of the cursor.

Format

y = csrcol;

y = csrlin;

Portability

Unix

csrcol returns the cursor column for the active window. For Text windows, this value is

the cursor column with respect to the text buer. For TTY windows, this value is the

cursor column with respect to the current output line, i.e., it will be the same whether

the text is wrapped or not. For PQG windows, this value is meaningless.

csrlin returns the cursor line for the active window. For Text windows, this value is the

cursor row with respect to the text buer. For TTY windows, this value is the current

output line number (i.e., the number of lines logged + 1). For PQG windows, this value

is meaningless.

OS/2, Windows

csrcol returns the cursor column with respect to the current output line, i.e., it will

return the same value whether the text is wrapped or not. csrlin returns the cursor line

with respect to the top line in the window.

Remarks

y will contain the current column or row position of the cursor on the screen. The

upper left corner is (1,1). Under DOS, columns are usually numbered 180, rows are

usually numbered 125. setvmode will return the current screen dimensions.

csrcol returns the column position of the cursor. csrlin returns the row position.

The locate statement allows the cursor to be positioned at a specic row and column.

Example

r = csrlin;

c = csrcol;

cls;

locate r,c;

In this example the screen is cleared without aecting the cursor position.

See also

cls, locate, lpos, setvmode

447

csrtype 25. COMMAND REFERENCE

Purpose

To set the cursor shape.

Format

old = csrtype(mode);

Portability

Unix

This function is not supported in terminal mode.

OS/2, Windows

This function is not supported under OS/2 or Windows.

Input

mode scalar, cursor type to set.

DOS

0 cursor o

1 normal cursor

2 large cursor

Unix

0 cursor o

1 normal cursor

2 large cursor

3 triangular cursor

Output

old scalar, original cursor type.

Remarks

Under DOS, this function will set the same shape as GAUSS is already using for its

three modes. See the Conguration chapter in the DOS supplement for details.

Example

x = csrtype(2);

See also

csrcol, csrlin

448

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE cumprodc

Purpose

Computes the cumulative products of the columns of a matrix.

Format

y = cumprodc(x);

Input

x NK matrix.

Output

y NK matrix containing the cumulative products of the columns of x.

Remarks

This is based on the recursive series recsercp. recsercp could be called directly as

follows:

recsercp(x,zeros(1,cols(x)))

to accomplish the same thing.

Example

x = { 1 -3,

2 2,

3 -1 };

y = cumprodc(x);

y =

1.00 3.00

2.00 6.00

6.00 6.00

Source

cumprodc.src

Globals

None

See also

cumsumc, recsercp, recserar

449

cumsumc 25. COMMAND REFERENCE

Purpose

Computes the cumulative sums of the columns of a matrix.

Format

y = cumsumc(x);

Input

x NK matrix.

Output

y NK matrix containing the cumulative sums of the columns of x.

Remarks

This is based on the recursive series function recserar. recserar could be called directly

as follows:

recserar(x, x[1,.] , ones(1,cols(x)))

to accomplish the same thing.

Example

x = { 1 -3,

2 2,

3 -1 };

y = cumsumc(x);

y =

1 3

3 1

6 2

Source

cumsumc.src

Globals

None

See also

cumprodc, recsercp, recserar

450

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

C

25. COMMAND REFERENCE curve

Purpose

Computes a one-dimensional smoothing curve.

Format

{ u,v } = curve(x,y,d,s,sigma,G);

Input

x K1 vector, x-abscissae (x-axis values).

y K1 vector, y-ordinates (y-axis values).

d K1 vector or scalar, observation weights.

s scalar, smoothing parameter. If s = 0, curve performs an interpolation. If

d contains standard deviation estimates, a reasonable value for s is K.

sigma scalar, tension factor.

G scalar, grid size factor.

Output

u K*G1 vector, x-abscissae, regularly spaced.

v K*G1 vector, y-ordinates, regularly spaced.

Remarks

sigma contains the tension factor. This value indicates the curviness desired. If sigma

is nearly zero (e. g. .001), the resulting curve is approximately the tensor product of

cubic curves. If sigma is large, (e. g. 50.0) the resulting curve is approximately

bi-linear. If sigma equals zero, tensor products of cubic curves result. A standard value

for sigma is approximately 1.

G is the grid size factor. It determines the neness of the output grid. For G = 1, the

input and output vectors will be the same size. For G = 2, the output grid is twice as

ne as the input grid, i.e., u and v will have twice as many rows as x and y.

Source

spline.src

451

cvtos 25. COMMAND REFERENCE

Purpose

Converts a character vector to a string.

Format

s = cvtos(v);

Input

v N1 character vector, to be converted to a string.

Output

s string, contains the contents of v.

Remarks

cvtos in eect appends the elements of v together into a single string.

cvtos was written to operate in conjunction with stocv. If you pass it a character

vector that does not conform to the output of stocv, you may get unexpected results.

For example, cvtos DOES NOT look for 0 terminating bytes in the elements of v; it

assumes every element except the last is 8 characters long. If this is not true, there will

be 0s in the middle of s.

If the last element of v does not have a terminating 0 byte, cvtos supplies one for s.

Example

let v = { "Now is t" "he time " "for all " "good men" };

s = cvtos(v);

s = Now is the time for all good men

See also

stocv, vget, vlist, vput, vread

452

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE datalist

Purpose

List selected variables from a data set.

Format

datalist dataset [[var1 [[var2...]]]];

Input

dataset literal, name of the dataset.

var# literal, the names of the variables to list.

range global scalar, the range of rows to list. The default is all rows.

miss global scalar, controls handling of missing values.

0 display rows with missing values.

1 do not display rows with missing values.

The default is 0.

prec global scalar, the number of digits to the right of the decimal point to

display. The default is 3.

Remarks

The variables are listed in an interactive mode. As many rows and columns as will t

on the screen are displayed. You can use the cursor keys to pan and scroll around in

the listing.

Example

datalist freq age sex pay;

This command will display the variables age, sex, and pay from the data set freq.dat.

Source

datalist.src

453

date 25. COMMAND REFERENCE

Purpose

Returns the current date in a 4-element column vector, in the order: year, month, day,

and hundredths of a second since midnight.

Format

y = date;

Remarks

The hundredths of a second since midnight can be accessed using hsec.

Example

print date;

1998.0000

6.0000000

15.000000

4011252.7

See also

time, timestr, ethsec, hsec, etstr

454

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE datestr

Purpose

Returns a date in a string.

Format

str = datestr(d);

Input

d 41 vector, like the date function returns. If this is 0, the date function

will be called for the current system date.

Output

str 8 character string containing current date in the form: mo/dy/yr

Example

d = { 1998, 6, 15, 0 };

y = datestr(d);

print y;

6/15/98

Source

time.src

Globals

None

See also

date, datestring, datestrymd, time, timestr, ethsec

455

datestring 25. COMMAND REFERENCE

Purpose

Returns a date in a year-2000-compliant string.

Format

str = datestring(d);

Input

d 41 vector, like the date function returns. If this is 0, the date function

will be called for the current system date.

Output

str 10 character string containing current date in the form: mm/dd/yyyy

Example

y = datestring(0);

print y;

6/15/1996

Source

time.src

Globals

None

See also

date, datestr, datestrymd, time, timestr, ethsec

456

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE datestrymd

Purpose

Returns a date in a string.

Format

str = datestrymd(d);

Input

d 41 vector, like the date function returns. If this is 0, the date function

will be called for the current system date.

Output

str 8 character string containing current date in the form: yyyymmdd

Example

d = { 1998, 6, 15, 0 };

y = datestrymd(d);

print y;

19980615

Source

time.src

Globals

None

See also

date, datestr, datestring, time, timestr, ethsec

457

dayinyr 25. COMMAND REFERENCE

Purpose

Returns day number in the year of a given date.

Format

daynum = dayinyr(dt );

Input

dt 31 or 41 vector, date to check. The date should be in the form returned

by date.

Output

daynum scalar, the day number of that date in that year.

Example

x = { 1998, 6, 15, 0 };

y = dayinyr(x);

print y;

166.00000

Source

time.src

Globals

isleap

458

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE debug

Purpose

Runs a program under the source level debugger.

Format

debug lename;

Input

lename The name of the program to debug.

459

declare 25. COMMAND REFERENCE

Purpose

To initialize matrices and strings at compile time.

Format

declare [[type]] symbol [[aop clist]];

Input

type optional literal, specifying the type of the symbol.

matrix

string

if type is not specied, matrix is assumed.

symbol the name of the symbol being declared.

aop the type of assignment to be made.

= if not initialized, initialize.

if already initialized, reinitialize.

!= if not initialized, initialize.

if already initialized, reinitialize.

:= if not initialized, initialize.

if already initialized, redenition error.

?= if not initialized, initialize.

if already initialized, leave as is.

If aop is specied, clist must be also.

clist a list of constants to assign to symbol .

If aop clist is not specied, symbol is initialized as a scalar 0 or a null

string.

Example

declare matrix x,y,z;

x = 0

y = 0

z = 0

declare string x = "This string.";

460

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE declare

x = This string.

declare matrix x;

x = 0

declare matrix x != { 1 2 3, 4 5 6, 7 8 9 };

x =

1 2 3

4 5 6

7 8 9

declare matrix x[3,3] = 1 2 3 4 5 6 7 8 9;

x =

1 2 3

4 5 6

7 8 9

declare matrix x[3,3] = 1;

x =

1 1 1

1 1 1

1 1 1

declare matrix x[3,3];

x =

0 0 0

0 0 0

0 0 0

declare matrix x = 1 2 3 4 5 6 7 8 9;

x =

1

2

3

4

5

6

7

8

9

declare matrix x = dog cat;

x =

DOG

CAT

461

declare 25. COMMAND REFERENCE

declare matrix x = "dog" "cat";

x =

dog

cat

Remarks

The declare syntax is similar to the let statement.

declare generates no executable code. This is strictly for compile time initialization.

The data on the right-hand side of the equal sign must be constants. No expressions or

variables are allowed.

declare statements are intended for initialization of global matrices and strings that are

used by procedures in a library system.

It is best to place declare statements in a separate le from procedure denitions. This

will prevent redenition errors when rerunning the same program without clearing your

workspace.

Complex numbers can be entered by joining the real and imaginary parts with a sign

(+ or -); there can be no spaces between the numbers and the sign. Numbers with no

real part can be entered by appending an i to the number.

There should be only one declaration for any symbol in a program. Multiple

declarations of the same symbol should be considered a programming error. When

GAUSS is looking through the library to reconcile a reference to a matrix or a string, it

will quit looking as soon as a symbol with the correct name is found. If another symbol

with the same name existed in another le, it would never be found. Only the rst one

in the search path would be available to programs.

Here are some of the possible uses of the three forms of declaration:

!=, = Interactive programming or any situation where a global by the same name

will probably be sitting in the symbol table when the le containing the

declare statement is compiled. The symbol will be reset.

This allows mixing declare statements with the procedure denitions that

reference the global matrices and strings or placing them in your main le.

:= Redenition is treated as an error because you have probably just

outsmarted yourself. This will keep you out of trouble because it wont

allow you to zap one symbol with another value that you didnt know was

getting mixed up in your program. You probably need to rename one of

them.

You need to place declare statements in a separate le from the rest of

your program and procedure denitions.

462

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE declare

?= Interactive programming where some global defaults were set when you

started and you dont want them reset for each successive run even if the

le containing the declares gets recompiled. This can get you into trouble

if you are not careful.

Ctrl-W controls the declare statement warning level. If declare warnings are on, you

will be warned whenever a declare statement encounters a symbol that is already

initialized. Heres what happens when you declare a symbol that is already initialized

when declare warnings are turned on:

declare != Reinitialize and warn.

declare := Crash with fatal error.

declare ?= Leave as is and warn.

If declare warnings are o, no warnings are given for the != and ?= cases.

See also

let, external

463

delete 25. COMMAND REFERENCE

Purpose

Deletes global symbols from the symbol table.

Format

delete -ags symbol1,symbol2,symbol3;

Remarks

This completely and irrevocably deletes a symbol from GAUSSs memory and

workspace. It will no longer show up when the show command is used.

The following ags are dened:

p procedures

k keywords

f fn functions

m matrices

s strings

g only procedures with global references

l only procedures with all local references

n no pause for conrmation

Flags must be preceded by a slash (e.g. -pfk) and are dened in the same way as the

show command. If symbol names are ended with an asterisk, any names matching

those rst letters will be deleted. If the n (no pause) ag is used, you will not be asked

for conrmation for each symbol.

This command is supported only from COMMAND level. Since the interpreter

executes a compiled pseudo-code, this command would invalidate a previously compiled

code image and therefore would destroy any program it was a part of. If any symbols

are deleted, all procedures, keywords and functions with global references will be

deleted as well.

Example

print x;

96.000000

6.0000000

14.000000

3502965.9

delete -m x;

At the Delete? [Yes No Previous Quit] prompt, enter y.

464

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE delif

Purpose

Deletes rows from a matrix. The rows deleted are those for which there is a 1 in the

corresponding row of e.

Format

y = delif(x,e);

Input

x NK data matrix.

e N1 logical vector (vector of 0s and 1s).

Output

y MK data matrix consisting of the rows of y for which there is a 0 in the

corresponding row of e. If no rows remain, delif will return a scalar

missing.

Remarks

The input e will usually be generated by a logical expression using dot operators. For

instance:

y = delif(x, x[.,2] .> 100);

will delete all rows of x whose second element is greater than 100. The remaining rows

of x will be assigned to y.

Example

x = { 0 10 20,

30 40 50,

60 70 80 };

/* logical vector */

e = (x[.,1] .gt 0) .and (x[.,3] .lt 100);

y = delif(x,e);

Here is the resulting matrix y:

0 10 20

All rows for which the elements in column 1 are greater than 0 and the elements in

column 3 are less than 100 are deleted.

Source

datatran.src

Globals

None

See also

selif

465

denseSubmat 25. COMMAND REFERENCE

Purpose

Returns dense submatrix of sparse matrix.

Format

c = denseSubmat(x,r,c);

Input

x MN sparse matrix.

r K1 vector, row indices.

c L1 vector, column indices.

Output

e KL dense matrix.

Remarks

If r or c are scalar zeros, all rows or columns will be returned.

Source

sparse.src

See also

sparseFd, sparseFp

466

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE design

Purpose

Creates a design matrix of 0s and 1s from a column vector of numbers specifying the

columns in which the 1s should be placed.

Format

y = design(x);

Input

x N1 vector.

Output

y NK matrix, where K = maxc(x); each row of y will contain a single 1,

and the rest 0s. The one in the i

th

row will be in the round(x[i,1])

column.

Remarks

Note that x does not have to contain integers: it will be rounded to nearest if necessary.

Example

x = { 1, 1.2, 2, 3, 4.4 };

y = design(x);

y =

1 0 0 0

1 0 0 0

0 1 0 0

0 0 1 0

0 0 0 1

Source

design.src

Globals

None

See also

cumprodc, cumsumc, recserrc

467

det 25. COMMAND REFERENCE

Purpose

Returns the determinant of a square matrix.

Format

y = det(x);

Input

x NN square matrix.

Output

y determinant of x.

Remarks

x may be any valid expression that returns a square matrix (number of rows equals

number of columns).

det computes a LU decomposition.

detl can be much faster in many applications.

Example

x = { 3 2 1,

0 1 -2,

1 3 4 };

y = det(x);

x =

3 2 1

0 1 2

1 3 4

y = 25

See also

detl

468

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE detl

Purpose

Returns the determinant of the last matrix that was passed to one of the intrinsic

matrix decomposition routines.

Format

y = detl;

Remarks

Whenever one of the following functions is executed, the determinant of the matrix is

also computed and stored in a system variable. This function will return the value of

that determinant and, because the value has been computed in a previous instruction,

this will require no computation.

The following functions will set the system variable used by detl:

chol(x)

crout(x)

croutp(x)

det(x)

inv(x)

invpd(x)

solpd(y,x) determinant of x

y/x determinant of x when neither argument is a scalar

or

determinant of x

x if x is not square

Example

If both the inverse and the determinant of the matrix are needed, the following two

commands will return both with the minimum amount of computation:

xi = inv(x);

xd = detl;

The function det(x) returns the determinant of a matrix using the Crout

decomposition. If you only want the determinant of a positive denite matrix, the

following code will be the fastest for matrices larger than 1010:

call chol(x);

xd = detl;

The Cholesky decomposition is computed and the result from that is discarded. The

determinant saved during that instruction is retrieved using detl. This can execute up

to 2.5 times faster than det(x) for large positive denite matrices.

See also

det

469

dt 25. COMMAND REFERENCE

Purpose

Computes a discrete Fourier transform.

Format

y = dt(x);

Input

x N1 vector.

Output

y N1 vector.

Remarks

The transform is divided by N.

This uses a second-order Goertzel algorithm. It is considerably slower than t, but it

may have some advantages in some circumstances. For one thing, N does not have to

be an even power of 2.

Source

dfft.src

Globals

None

See also

dti, t, ti

470

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dti

Purpose

Computes inverse discrete Fourier transform.

Format

y = dti(x);

Input

x N1 vector.

Output

y N1 vector.

Remarks

The transform is divided by N.

This uses a second-order Goertzel algorithm. It is considerably slower than ti, but it

may have some advantages in some circumstances. For one thing, N does not have to

be an even power of 2.

Source

dffti.src

Globals

None

See also

t, dti, ti

471

dfree 25. COMMAND REFERENCE

Purpose

Returns the amount of room left on a diskette or hard disk.

Format

y = dfree(drive);

Input

drive scalar, valid disk drive number.

Output

y number of bytes free.

Portability

Unix

The dfree function is not supported in Unix.

Remarks

Valid disk drive numbers are 0 = default, 1 = A, 2 = B, etc. If an error is encountered,

dfree will return -1.

See also

coreleft

472

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE diag

Purpose

Creates a column vector from the diagonal of a matrix.

Format

y = diag(x);

Input

x NK matrix.

Output

y min(N,K)x1 vector.

Remarks

The matrix need not be square.

diagrv reverses the procedure and puts a vector into the diagonal of a matrix.

Example

x = rndu(3,3);

y = diag(x);

x =

0.660818 0.367424 0.302208

0.204800 0.077357 0.145755

0.712284 0.353760 0.642567

y =

0.660818

0.077357

0.642567

See also

diagrv

473

diagrv 25. COMMAND REFERENCE

Purpose

Inserts a vector into the diagonal of a matrix.

Format

y = diagrv(x,v);

Input

x NK matrix.

v min(N,K) vector.

Output

y NK matrix equal to x with its principal diagonal elements equal to those

of v.

Remarks

diag reverses the procedure and pulls the diagonal out of a matrix.

Example

x = rndu(3,3);

v = ones(3,1);

y = diagrv(x,v);

x =

0.660818 0.367424 0.302208

0.204800 0.077357 0.145755

0.712284 0.353760 0.642567

v =

1.000000

1.000000

1.000000

y =

1.000000 0.367424 0.302208

0.204800 1.000000 0.145755

0.712284 0.353760 1.000000

See also

diag

474

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE disable

Purpose

Disables the invalid operation interrupt of the numeric processor. This aects the way

missing values are handled in most calculations.

Format

disable;

Portability

Unix, OS/2, Windows

This function is not used by these platforms. The invalid operation is always disabled

Remarks

When disable is in eect, missing values will be allowed in most calculations. A missing

value is a special oating point encoding which the numeric processor considers a NaN

(Not A Number). disable allows missing values to pass through most calculations

unchanged, i.e., a number plus a missing value is a missing value.

The default when GAUSS is started is to have the program crash when missing values

are encountered or when any operation sets the numeric processors invalid operation

exception. See the Debugger or Error Handling and Debugging chapter in your

supplement.

If disable is on, these operations will return a NaN, and the program will continue.

This can complicate debugging for programs that do not need to handle missing values,

because the program may proceed far beyond the point that NaNs are created before it

actually crashes.

The opposite of disable is enable, which is the default. If enable is on, the program

will terminate with an Invalid oating point operation error message.

The following operators are specially designed to handle missing values and are not

aected by the disable/enable commands: b/a (matrix division when a is not square

and neither a nor b is scalar), counts, ismiss, maxc, maxindc, minc, minindc, miss,

missex, missrv, moment, packr, scalmiss, sortc.

ndpcntrl can be used to get and reset the numeric processor control word, so it is more

exible than enable/disable.

See also

enable, miss, missrv, ndpchk, ndpcntrl

475

do while, do until 25. COMMAND REFERENCE

Purpose

Executes a series of statements in a loop as long as a given expression is true (or false).

Format

do while expression;

or

do until expression;

.

.

.

statements in loop

.

.

.

endo;

Remarks

expression is any expression that returns a scalar. It is TRUE if it is nonzero and

FALSE if it is zero.

In a do while loop, execution of the loop will continue as long as the expression is

TRUE.

In a do until loop, execution of the loop will continue as long as the expression is

FALSE.

The condition is checked at the top of the loop. If execution can continue, the

statements of the loop are executed until the endo is encountered. Then GAUSS

returns to the top of the loop and checks the condition again.

The do loop does not automatically increment a counter. See the rst example below.

do loops may be nested.

It is often possible to avoid using loops in GAUSS by using the appropriate matrix

operator or function. It is almost always preferable to avoid loops when possible, since

the corresponding matrix operations can be much faster.

Example

476

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE do while, do until

format /rdn 1,0;

space = " ";

comma = ",";

i = 1;

do while i <= 4;

j = 1;

do while j <= 3;

print space i comma j;;

j = j+1;

endo;

i = i+1;

print;

endo;

1, 1 1, 2 1, 3

2, 1 2, 2 2, 3

3, 1 3, 2 3, 3

4, 1 4, 2 4, 3

In the example above, two nested loops are executed and the loop counter values are

printed out. Note that the inner loop counter must be reset inside of the outer loop

before entering the inner loop. An empty print statement is used to print a carriage

return/line feed sequence after the inner loop nishes.

The following are examples of simple loops that execute a predetermined number of

times. These loops will both have the result shown.

format /rd 1,0;

i = 1;

do while i <= 10;

print i;;

i = i+1;

endo;

i = 1;

do until i > 10;

print i;;

i = i+1;

endo;

1 2 3 4 5 6 7 8 9 10

See also

continue, break

477

dos 25. COMMAND REFERENCE

Purpose

Provides access to the operating system from within GAUSS.

Format

dos [[s]];

Portability

Unix

Control and output go to the controlling terminal, if there is one.

This function may be used in terminal mode.

OS/2, Windows

The dos function opens a new terminal.

Running programs in the background is allowed in all three of the aforementioned

platforms.

Input

s literal or ^string, the OS command to be executed.

Remarks

This allows all operating system commands to be used from within GAUSS. It allows

other programs to be run even though GAUSS is still resident in memory.

If no operating system command (for instance, dir or copy) or program name is

specied, then a shell of the operating system will be entered which can be used just

like the base level OS. The exit command must be given from the shell to get back into

GAUSS. If a command or program name is included, the return to GAUSS is

automatic after the DOS command has been executed.

All matrices are retained in memory when the OS is accessed in this way. This

command allows the use of word processing, communications, and other programs from

within GAUSS.

Do not execute programs that terminate and remain resident. This is because they will

be left resident inside of GAUSSs workspace. Some examples are programs that create

ramdisks or print spoolers.

If the command is to be taken from a string variable, the ^ (caret) must precede the

string.

The shorthand > can be used in place of the word DOS.

Example

478

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dos

comstr = "basic myprog";

dos ^comstr;

This will cause the BASIC program myprog to be run. When that program is nished,

control will automatically return to GAUSS.

>dir *.prg;

This will use the DOS dir command to print a directory listing of all les with a .prg

extension. When the listing is nished, control will be returned to GAUSS.

dos;

This will cause a second level OS shell to be entered. The OS prompt will appear and

OS commands or other programs can be executed. To return to GAUSS, type exit.

See also

exit, exec

479

dotfeqdotfne 25. COMMAND REFERENCE

Purpose

Fuzzy comparison functions. These functions use fcmptol to fuzz the comparison

operations to allow for roundo error.

Format

y = dotfeq(a,b);

y = dotfge(a,b);

y = dotfgt(a,b);

y = dote(a,b);

y = dott(a,b);

y = dotfne(a,b);

Input

a NK matrix, rst matrix.

b LM matrix, second matrix, EE compatible with a.

fcmptol global scalar, comparison tolerance. The default value is 1.0e 15.

Output

y max(N,L) by max(K,M) matrix of 1s and 0s.

Remarks

The return value is 1 if true and 0 if false.

The statement:

y = dotfeq(a,b);

is equivalent to:

y = a .eq b;

The calling program can reset fcmptol before calling these procedures.

_fcmptol = 1e-12;

480

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dotfeqdotfne

Example

x = rndu(2,2);

y = rndu(2,2);

t = dotfge(x,y);

x =

0.85115559 0.98914218

0.12703276 0.43365175

y =

0.41907226 0.49648058

0.58039125 0.98200340

t =

1.0000000 1.0000000

0.0000000 0.0000000

Source

fcompare.src

Globals

fcmptol

See also

feq

481

dstat 25. COMMAND REFERENCE

Purpose

Compute descriptive statistics.

Format

{ vnam,mean,var,std,min,max,valid,mis } = dstat(dataset ,vars);

Input

dataset string, name of data set.

If dataset is null or 0, vars will be assumed to be a matrix containing the

data.

vars the variables.

If dataset contains the name of a GAUSS data set, vars will be interpreted

as:

K1 character vector names of variables.

K1 numeric vector indices of columns.

These can be any size subset of the variables in the data set and can be in

any order. If a scalar 0 is passed, all columns of the data set will be used.

If dataset is null or 0, vars will be interpreted as:

NK matrix the data on which to compute the descriptive

statistics.

Defaults are provided for the following global input variables, so they can be ignored

unless you need control over the other options provided by this procedure.

altnam global matrix, default 0.

This can be a K1 character vector of alternate variable names for the

output.

miss global scalar, default 0.

0 there are no missing values (fastest).

1 listwise deletion, drop a row if any missings occur in it.

2 pairwise deletion.

row global scalar, the number of rows to read per iteration of the read loop.

if 0, (default) the number of rows will be calculated internally.

output global scalar, controls output, default 1.

482

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dstat

1 print output table.

0 do not print output.

Output

vnam K1 character vector, the names of the variables used in the statistics.

mean K1 vector, means.

var K1 vector, variance.

std K1 vector, standard deviation.

min K1 vector, minima.

max K1 vector, maxima.

valid K1 vector, the number of valid cases.

mis K1 vector, the number of missing cases.

Remarks

If pairwise deletion is used, the minima and maxima will be the true values for the

valid data. The means and standard deviations will be computed using the correct

number of valid observations for each variable.

Source

dstat.src

Globals

output, dstatd, dstatx

483

dtvnormal 25. COMMAND REFERENCE

Purpose

Normalizes a date and time vector.

Format

d = dtvnormal(t );

Input

t 18 date and time vector that has one or more elements outside the

normal range.

Output

d Normalized 18 date and time vector.

Remarks

The date and time vector is a 18 vector whose elements consist of:

Year: Year, four digit integer.

Month: 1-12, Month in year.

Day: 1-31, Day of month.

Hour: 0-23, Hours since midnight.

Min: 0-59, Minutes.

Sec: 0-59, Seconds.

DoW: 0-6, Day of week, 0 = Sunday.

DiY: 0-365, Days since Jan 1 of year.

The last two elements are ignored on input.

Example

format /rd 10,2;

x = { 1996 14 21 6 21 37 0 0 };

d = dtvnormal(x);

d = 1997.00 2.00 21.00 6.00 21.00 37.00 2.00 51.00

Globals

None.

See also

date, ethsec, etstr, time, timestr, timeutc, utctodtv

484

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dummy

Purpose

Creates a set of dummy (0/1) variables by breaking up a variable into specied

categories. The highest (rightmost) category is unbounded on the right.

Format

y = dummy(x,v);

Input

x N1 vector of data that is to be broken up into dummy variables.

v (K1)1 vector specifying the K1 breakpoints (these must be in

ascending order) that determine the K categories to be used. These

categories should not overlap.

Output

y NK matrix containing the K dummy variables.

Remarks

Missings are deleted before the dummy variables are created.

All categories are open on the left (i.e., do not contain their left boundaries) and all but

the highest are closed on the right (i.e., do contain their right boundaries). The highest

(rightmost) category is unbounded on the right. Thus, only K1 breakpoints are

required to specify K dummy variables.

The function dummybr is similar to dummy, but in that function the highest category

is bounded on the right. The function dummydn is also similar to dummy, but in that

function a specied column of dummies is dropped.

Example

x = { 0, 2, 4, 6 };

v = { 1, 5, 7 };

y = dummy(x,v);

The result y looks like this:

1 0 0 0

0 1 0 0

0 1 0 0

0 0 1 0

485

dummy 25. COMMAND REFERENCE

The vector v will produce 4 dummies satisfying the following conditions:

x 1

1 < x 5

5 < x 7

7 < x

Source

datatran.src

Globals

None

See also

dummybr, dummydn

486

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dummybr

Purpose

Creates a set of dummy (0/1) variables. The highest (rightmost) category is bounded

on the right.

Format

y = dummybr(x,v);

Input

x N1 vector of data that is to be broken up into dummy variables.

v K1 vector specifying the K breakpoints (these must be in ascending

order) that determine the K categories to be used. These categories should

not overlap.

Output

y NK matrix containing the K dummy variables. Each row will have a

maximum of one 1.

Remarks

Missings are deleted before the dummy variables are created.

All categories are open on the left (i.e., do not contain their left boundaries) and are

closed on the right (i.e., do contain their right boundaries). Thus, K breakpoints are

required to specify K dummy variables.

The function dummy is similar to dummybr, but in that function the highest category

is unbounded on the right.

Example

x = { 0,

2,

4,

6 };

v = { 1,

5,

7 };

y = dummybr(x,v);

487

dummybr 25. COMMAND REFERENCE

The resulting matrix y looks like this:

1 0 0

0 1 0

0 1 0

0 0 1

The vector v = 1 5 7 will produce 3 dummies satisfying the following conditions:

x 1

1 < x 5

5 < x 7

Source

datatran.src

Globals

None

See also

dummydn, dummy

488

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

D

25. COMMAND REFERENCE dummydn

Purpose

Creates a set of dummy (0/1) variables by breaking up a variable into specied

categories. The highest (rightmost) category is unbounded on the right, and a specied

column of dummies is dropped.

Format

y = dummydn(x,v,p);

Input

x N1 vector of data to be broken up into dummy variables.

v K1 vector specifying the K1 breakpoints (these must be in ascending

order) that determine the K categories to be used. These categories should

not overlap.

p positive integer in the range [1,K], specifying which column should be

dropped in the matrix of dummy variables.

Output

y N(K1) matrix containing the K1 dummy variables.

Remarks

This is just like the function dummy, except that the p

th

column of the matrix of

dummies is dropped. This ensures that the columns of the matrix of dummies do not

sum to 1, and so these variables will not be collinear with a vector of ones.

Missings are deleted before the dummy variables are created.

All categories are open on the left (i.e., do not contain their left boundaries) and all but

the highest are closed on the right (i.e., do contain their right boundaries). The highest

(rightmost) category is unbounded on the right. Thus, only K1 breakpoints are

required to specify K dummy variables.

Example

x = { 0, 2, 4, 6 };

v = { 1, 5, 7 };

p = 2;

y = dummydn(x,v,p);

489

dummydn 25. COMMAND REFERENCE

The resulting matrix y looks like this:

1 0 0

0 0 0

0 0 0

0 1 0

The vector v = 1 5 7 will produce 4 dummies satisfying the following conditions:

x 1

1 < x 5

5 < x 7

7 < x

Since p = 2, the second dummy is dropped.

Source

datatran.src

Globals

None

See also

dummy, dummybr

490

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE ed

Purpose

To access an alternate editor.

Format

ed lename;

Input

lename The name of the le to be edited.

Remarks

The default name of the editor is b.exe. To change the name of the editor used type:

ed = editor name ags;

or

ed = editor name ags;

The ags are any command line ags you may want between the name of the editor

and the lename when your editor is invoked. The quoted version will prevent the ags,

if any, from being forced to uppercase.

This command can be placed in the startup le so it will be set for you automatically

when you start GAUSS.

491

edit 25. COMMAND REFERENCE

Purpose

To edit a disk le.

Format

edit lename;

Remarks

Example

edit b:test1;

See also

run, medit, editm

492

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE editm

Purpose

To edit a matrix. See medit for a full-screen matrix editor.

Format

y = editm(x);

Portability

Unix

editm is not supported.

DOS

and e can be entered with Alt-P and Alt-E.

Input

x any legal expression that returns a matrix.

Output

y edited matrix.

Remarks

A matrix editor is invoked when the editm function is called. This editor allows you to

move around the matrix you are editing and make changes. (This editor is also used by

the con function.)

When editm appears in a program, the following will appear on the screen:

[1,1] = 1.2361434675434E+002 ?

The number after the equal sign is the [1,1] element of the matrix being edited.

There are two general ways to move around the matrix. First, you can simply type

numbers separated by commas, spaces or carriage returns. The editor will

automatically move you left to right and down through the matrix. That is, you will

rst go across the rst row left to right, then across the second row, and so on. When

you reach the last element in the matrix, you will automatically cycle back to the rst

element. When this occurs, the editors prompt will again be displayed on the screen.

To get out of the editor, type a semicolon. If a semicolon is typed after you have

entered a number, that number will be saved.

493

editm 25. COMMAND REFERENCE

The second general way to move around the matrix is to use the cursor keys. The left

and right cursor keys move you back and forth along rows. The up and down cursor

keys move you up and down in a column. When you come to the end of a row or

column, movement is left and up, or right and down. If, for instance, you are moving

left to right along a row using the right cursor key, you will move down to the

beginning of the next row when you come to the end of the row you are in. GAUSS will

beep at you if you try to move outside the matrix.

The question mark you see on the screen is the matrix editors prompt. If you want to

change the number that is in the [1,1] position of the matrix, just type in the number

you want. If you do not want to change anything, you can move to a dierent element

by hitting the appropriate cursor key. If you start to type a number and then hit a

cursor key, the number will not be saved. The BACKSPACE key will delete characters

to the left of the cursor.

If you type in a space, comma or carriage return before you type a number, nothing

will happen. GAUSS will wait until you type a number or use a cursor key to move to

a new element.

Numbers can be entered in scientic notation. The syntax is: dE+n or dE-n, where d is

a number and n is an integer power of 10. Thus, 1E+10, 1.1e-4, 1100E+1 are all legal.

Complex numbers can be entered by joining the real and imaginary parts with a sign

(+ or -); there can be no spaces between the numbers and the sign. Numbers with no

real part can be entered by appending an i to the number. For example, 1.2+23, 8.56i,

3-2.1i, -4.2e+6i and 1.2e-4-4.5e+3i are all legal.

An editm function can appear anywhere in an expression that any other function can

appear. Thus, for instance, the following statements are legal:

y = x*editm(z);

y = sqrt(editm(x));

Example

y = editm(ones(2,2));

[1,1] = 1.000000000000E+000 ? 2 3 4 5[space]

[1,1] = 2.000000000000E+000 ? 6 7 8 9[;]

y =

6.000000 7.000000

8.000000 9.000000

In this example, a 22 matrix of 1s is edited. Spaces are used to separate the numbers

as they are entered. Note that after 4 numbers have been entered, the editor has cycled

494

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE editm

back to the [1,1] position in the matrix again. When this occurs, the prompt appears

on the screen again. This time, after 4 more numbers have been entered, a semicolon is

entered (as indicated in the brackets). This causes the editor to stop and the edited

matrix to be returned.

See also

con, medit

495

eig 25. COMMAND REFERENCE

Purpose

Computes the eigenvalues of a general matrix.

Format

va = eig(x);

Input

x NN matrix.

Output

va N1 vector, the eigenvalues of x.

Remarks

If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]

to the scalerr function will return the index of the eigenvalue that failed. The

eigenvalues for indices scalerr(va[1])+1 to N should be correct.

Error handling is controlled with the low bit of the trap ag.

trap 0 set va[1] and terminate with message

trap 1 set va[1] and continue execution

The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will

appear consecutively with the eigenvalue having the positive imaginary part rst.

Example

x = { 4 8 1,

9 4 2,

5 5 7 };

va = eig(x);

va =

4.4979246

14.475702

5.0222223

See also

eigh, eighv, eigv

496

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eigcg

Purpose

Computes the eigenvalues of a complex, general matrix. (Included for backwards

compatibilityplease use eig instead.)

Format

{ var,vai } = eigcg(xr,xi );

Input

xr NN matrix, real part.

xi NN matrix, imaginary part.

Output

var N1 vector, real part of eigenvalues.

vai N1 vector, imaginary part of eigenvalues.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices eigerr+1 to N should be correct.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will

appear consecutively with the eigenvalue having the positive imaginary part rst.

Source

eigcg.src

Globals

eigerr

See also

eigcg2, eigch, eigrg, eigrs

497

eigcg2 25. COMMAND REFERENCE

Purpose

Computes eigenvalues and eigenvectors of a complex, general matrix. (Included for

backwards compatibilityplease use eigv instead.)

Format

{ var,vai ,ver,vei } = eigcg2(xr,xi );

Input

xr NN matrix, real part.

xi NN matrix, imaginary part.

Output

var N1 vector, real part of eigenvalues.

vai N1 vector, imaginary part of eigenvalues.

ver NN matrix, real part of eigenvectors.

vei NN matrix, imaginary part of eigenvectors.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices eigerr+1 to N should be correct. The eigenvectors

are not computed.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will

appear consecutively with the eigenvalue having the positive imaginary part rst. The

columns of ver and vei contain the real and imaginary eigenvectors of x in the same

order as the eigenvalues. The eigenvectors are not normalized.

Source

eigcg.src

Globals

eigerr

See also

eigcg, eigch, eigrg, eigrs

498

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eigch

Purpose

Computes the eigenvalues of a complex, hermitian matrix. (Included for backwards

compatibilityplease use eigh instead.)

Format

va = eigch(xr,xi );

Input

xr NN matrix, real part.

xi NN matrix, imaginary part.

Output

va N1 vector, real part of eigenvalues.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices 1 to eigerr1 should be correct.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are in ascending order. The eigenvalues for a complex hermitian

matrix are always real so this procedure returns only one vector.

Source

eigch.src

Globals

eigerr

See also

eigch2, eigcg, eigrg, eigrs

499

eigch2 25. COMMAND REFERENCE

Purpose

Computes eigenvalues and eigenvectors of a complex, hermitian matrix. (Included for

backwards compatibilityplease use eighv instead.)

Format

{ var,vai ,ver,vei } = eigch2(xr,xi );

Input

xr NN matrix, real part.

xi NN matrix, imaginary part.

Output

var N1 vector, real part of eigenvalues.

vai N1 vector, imaginary part of eigenvalues.

ver NN matrix, real part of eigenvectors.

vei NN matrix, imaginary part of eigenvectors.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices 1 to eigerr1 should be correct. The eigenvectors

are not computed.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are in ascending order. The eigenvalues of a complex hermitian matrix

are always real. This procedure returns a vector of zeros for the imaginary part of the

eigenvalues so the syntax is consistent with other eigxx procedure calls. The columns of

ver and vei contain the real and imaginary eigenvectors of x in the same order as the

eigenvalues. The eigenvectors are orthonormal.

Source

eigch.src

Globals

eigerr

See also

eigch, eigcg, eigrg, eigrs

500

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eigh

Purpose

Computes the eigenvalues of a complex hermitian or real symmetric matrix.

Format

va = eigh(x);

Input

x NN matrix.

Output

va N1 vector, the eigenvalues of x.

Remarks

If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]

to the scalerr function will return the index of the eigenvalue that failed. The

eigenvalues for indices 1 to scalerr(va[1])-1 should be correct.

Error handling is controlled with the low bit of the trap ag.

trap 0 set va[1] and terminate with message

trap 1 set va[1] and continue execution

The eigenvalues are in ascending order.

The eigenvalues of a complex hermitian or real symmetric matrix are always real.

See also

eig, eighv, eigv

501

eighv 25. COMMAND REFERENCE

Purpose

Computes eigenvalues and eigenvectors of a complex hermitian or a real symmetric

matrix.

Format

{ va,ve } = eighv(x);

Input

x NN matrix.

Output

va N1 vector, the eigenvalues of x.

ve NN matrix, the eigenvectors of x.

Remarks

If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]

to the scalerr function will return the index of the eigenvalue that failed. The

eigenvalues for indices 1 to scalerr(va[1])-1 should be correct. The eigenvectors are not

computed.

Error handling is controlled with the low bit of the trap ag.

trap 0 set va[1] and terminate with message

trap 1 set va[1] and continue execution

The eigenvalues are in ascending order. The columns of ve contain the eigenvectors of x

in the same order as the eigenvalues. The eigenvectors are orthonormal.

The eigenvalues of a complex hermitian or real symmetric matrix are always real.

See also

eig, eigh, eigv

502

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eigrg

Purpose

Computes the eigenvalues of a real, general matrix. (Included for backwards

compatibilityplease use eig instead.)

Format

{ var,vai } = eigrg(x);

Input

x NN matrix.

Output

var N1 vector, real part of eigenvalues.

vai N1 vector, imaginary part of eigenvalues.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices eigerr+1 to N should be correct.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will

appear consecutively with the eigenvalue having the positive imaginary part rst.

Example

x = { 1 2i 3,

4i 5+3i 6,

7 8 9i };

{y,n} = eigrg(x);

y =

6.3836054

2.0816489

10.301956

n =

7.2292503

1.4598755

6.2306252

503

eigrg 25. COMMAND REFERENCE

Source

eigrg.src

Globals

eigerr

See also

eigrg2, eigcg, eigch, eigrs

504

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eigrg2

Purpose

Computes eigenvalues and eigenvectors of a real, general matrix. (Included for

backwards compatibilityplease use eigv instead.)

Format

{ var,vai ,ver,vei } = eigrg2(x);

Input

x NN matrix.

Output

var N1 vector, real part of eigenvalues.

vai N1 vector, imaginary part of eigenvalues.

ver NN matrix, real part of eigenvectors.

vei NN matrix, imaginary part of eigenvectors.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices eigerr+1 to N should be correct. The eigenvectors

are not computed.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will

appear consecutively with the eigenvalue having the positive imaginary part rst. The

columns of ver and vei contain the real and imaginary eigenvectors of x in the same

order as the eigenvalues. The eigenvectors are not normalized.

Source

eigrg.src

Globals

eigerr

See also

eigrg, eigcg, eigch, eigrs

505

eigrs 25. COMMAND REFERENCE

Purpose

Computes the eigenvalues of a real, symmetric matrix. (Included for backwards

compatibilityplease use eigh instead.)

Format

va = eigrs(x);

Input

x NN matrix.

Output

va N1 vector, eigenvalues of x.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues for indices 1 to eigerr1 should be correct.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are in ascending order. The eigenvalues for a real symmetric matrix are

always real so this procedure returns only one vector.

Source

eigrs.src

Globals

eigerr

See also

eigrs2, eigcg, eigch, eigrg

506

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eigrs2

Purpose

Computes eigenvalues and eigenvectors of a real, symmetric matrix. (Included for

backwards compatibilityplease use eighv instead.)

Format

{ va,ve } = eigrs2(x);

Input

x NN matrix.

Output

va N1 vector, eigenvalues of x.

ve NN matrix, eigenvectors of x.

eigerr global scalar, if all the eigenvalues can be determined eigerr = 0,

otherwise eigerr is set to the index of the eigenvalue that failed. The

eigenvalues and eigenvectors for indices 1 to eigerr1 should be correct.

Remarks

Error handling is controlled with the low bit of the trap ag.

trap 0 set eigerr and terminate with message

trap 1 set eigerr and continue execution

The eigenvalues are in ascending order. The columns of ve contain the eigenvectors of x

in the same order as the eigenvalues. The eigenvectors are orthonormal.

The eigenvalues and eigenvectors for a real symmetric matrix are always real so this

procedure returns only the real parts.

Source

eigrs.src

Globals

eigerr

See also

eigrs, eigcg, eigch, eigrg

507

eigv 25. COMMAND REFERENCE

Purpose

Computes the eigenvalues and eigenvectors of a general matrix.

Format

{ va,ve } = eigv(x);

Input

x NN matrix.

Output

va N1 vector, the eigenvalues of x.

ve NN matrix, the eigenvectors of x.

Remarks

If the eigenvalues cannot all be determined, va[1] is set to an error code. Passing va[1]

to the scalerr function will return the index of the eigenvalue that failed. The

eigenvalues for indices scalerr(va[1])+1 to N should be correct. The eigenvectors are

not computed.

Error handling is controlled with the low bit of the trap ag.

trap 0 set va[1] and terminate with message

trap 1 set va[1] and continue execution

The eigenvalues are unordered except that complex conjugate pairs of eigenvalues will

appear consecutively with the eigenvalue having the positive imaginary part rst. The

columns of ve contain the eigenvectors of x in the same order as the eigenvalues. The

eigenvectors are not normalized.

Example

x = { 4 8 1,

9 4 2,

5 5 7 };

{y,n} = eigv(x);

y =

4.4979246

14.475702

5.0222223

n =

0.66930459 0.64076622 0.40145623

0.71335708 0.72488533 0.26047487

0.019156716 0.91339349 1.6734214

See also

eig, eigh, eighv

508

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE enable

Purpose

Enables the invalid operation interrupt of the numeric processor. This aects the way

missing values are handled in most calculations.

Format

enable;

Portability

Unix, OS/2, Windows

Invalid operation is always disabled. enable is not supported by these platforms.

Remarks

When enable is in eect, missing values will not be allowed in most calculations. A

missing value is a special oating point encoding which the numeric processor considers

a NaN (Not A Number).

The default, when GAUSS is started, is to have the program crash when missing values

are encountered or when any operation sets the numeric processors invalid operation

exception. See the Debugger or Error Handling and Debugging chapter in your

supplement.

If enable is on, these operations will cause the program to terminate with an Invalid

oating point operation error message.

The opposite of enable is disable. If disable is on these operations will return a NaN,

and the program will continue. This can complicate debugging for programs that do

not need to handle missing values, because the program may proceed far beyond the

point that NaNs are created before it actually crashes.

The following operators are specially designed to handle missing values and are not

aected by the disable/enable commands: b/a (matrix division when a is not square),

counts, ismiss, maxc, maxindc, minc, minindc, miss, missex, missrv, moment, packr,

scalmiss, sortc.

ndpcntrl can be used to get and reset the numeric processor control word, and is more

exible than enable/disable.

See also

ndpcntrl, disable, miss, missrv, ndpchk

509

end 25. COMMAND REFERENCE

Purpose

Terminate a program.

Format

end;

Portability

Unix

end closes all windows except window 1. If you want to leave a programs windows

open, use stop.

OS/2, Windows

end closes all user-created windows.

DOS

COMMAND mode requires the screen to be in text mode, so it will be reset if it is in

graphics mode. The screen will revert to text mode whenever it drops to COMMAND

mode.

Remarks

end causes GAUSS to revert to COMMAND mode, and closes all open les. end also

closes the auxiliary output le and turns the screen on. It is not necessary to put an

end statement at the end of a program.

An end command can be placed above a label which begins a subroutine to make sure

that a program does not enter a subroutine without a gosub.

stop also terminates a program but closes no les and leaves the screen setting as it is.

Example

output on;

screen off;

print x;

end;

In this example a matrix x is printed to the auxiliary output. The screen is turned o

to speed up the printing. The end statement is used to terminate the program so the

output le will be closed and the screen will be turned back on.

See also

new, stop, system

510

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE endp

Purpose

Close a procedure or keyword denition.

Format

endp;

Remarks

endp marks the end of a procedure denition that began with a proc or keyword

statement. See Chapter 9 for details on writing and using procedures.

Example

proc regress(y,x);

retp(inv(xx)*xy);

endp;

x = { 1 3 2, 7 4 9, 1 1 6, 3 3 2 };

y = { 3, 5, 2, 7 };

b = regress(y,x);

x =

1.00000000 3.00000000 2.00000000

7.00000000 4.00000000 9.00000000

1.00000000 1.00000000 6.00000000

3.00000000 3.00000000 2.00000000

y =

3.00000000

5.00000000

2.00000000

7.00000000

b =

0.15456890

1.50276345

0.12840825

See also

proc, keyword, retp

511

envget 25. COMMAND REFERENCE

Purpose

Searches the environment for a dened name.

Format

y = envget(s);

Input

s string, the name to be searched for.

Output

y string, the string that corresponds to that name in the environment or a

null string if it is not found.

Example

proc dopen(file);

local fname,fp;

fname = envget("DPATH");

if fname $== "";

fname = file;

else;

if strsect(fname,strlen(fname),1) $== "\\";

fname = fname $+ file;

else;

fname = fname $+ "\\" $+ file;

endif;

endif;

open fp = ^fname;

retp(fp);

endp;

This is an example of a procedure which will open a data le using a path stored in an

environment string called DPATH. The procedure returns the le handle and is called

as follows:

fp = dopen(myle);

See also

cdir

512

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eof

Purpose

Tests if the end of a le has been reached.

Format

y = eof(fh);

Input

fh scalar, le handle.

Output

y scalar, 1 if end of le has been reached, else 0.

Remarks

This function is used with the readr and fgetsxxx commands to test for the end of a le.

The seekr function can be used to set the pointer to a specic row position in a data

set; the fseek function can be used to set the pointer to a specic byte oset in a le

opened with fopen.

Example

open f1 = dat1;

xx = 0;

do until eof(f1);

xx = xx+moment(readr(f1,100),0);

endo;

In this example, the data le dat1.dat is opened and given the handle f1. Then the

data are read from this data set and are used to create the moment (x

x) matrix of the

data. On each iteration of the loop, 100 additional rows of data are read in and the

moment matrix for this set of rows is computed, and added to the matrix xx. When all

the data have been read, xx will contain the entire moment matrix for the data set.

GAUSS will keep reading until eof(f1) returns the value 1, which it will when the end

of the data set has been reached. On the last iteration of the loop, all remaining

observations are read in if there are 100 or fewer left.

See also

open, readr, seekr

513

eqSolve 25. COMMAND REFERENCE

Purpose

Solves a system of nonlinear equations

Format

{ x, retcode } = eqSolve(&F,start );

Input

start K1 vector, starting values

&F scalar, a pointer to a procedure which computes the value at x of the

equations to be solved.

Output

x K1 vector, solution

retcode scalar, the return code:

1 Norm of the scaled function value is less than Tol. x given is an

approximate root of F(x) (unless Tol is too large).

2 The scaled distance between the last two steps is less than the

step-tolerance ( eqs StepTol). x may be an approximate root of

F(x), but it is also possible that the algorithm is making very slow

progress and is not near a root, or the step-tolerance is too large.

3 The last global step failed to decrease norm2(F(x)) suciently;

either x is close to a root of F(x) and no more accuracy is possible,

or an incorrectly coded analytic Jacobian is being used, or the

secant approximation to the Jacobian is inaccurate, or the

step-tolerance is too large.

4 Iteration limit exceeded.

5 Five consecutive steps of maximum step length have been taken;

either norm2(F(x)) asymptotes from above to a nite value in

some direction or the maximum step length is too small.

6 x seems to be an approximate local minimizer of norm2(F(x)) that

is not a root of F(x). To nd a root of F(x), restart eqSolve from a

dierent region.

Globals

eqs JacobianProc pointer to a procedure which computes the analytical Jacobian.

By default, eqSolve will compute the Jacobian numerically.

514

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eqSolve

eqs MaxIters scalar, the maximum number of iterations. Default = 100.

eqs StepTol scalar, the step tolerance. Default = macheps^(2/3).

eqs TypicalF K1 vector of the typical F(x) values at a point not near a root, used

for scaling. This becomes important when the magnitudes of the

components of F(x) are expected to be very dierent. By default, function

values are not scaled.

eqs TypicalX K1 vector of the typical magnitude of x, used for scaling. This

becomes important when the magnitudes of the components of x are

expected to be very dierent. By default, variable values are not scaled.

eqs IterInfo scalar, if nonzero, iteration information is printed. Default = 0;

Tol scalar, the tolerance of the scalar function f = 0.5 [[F(x)[[

2

required to

terminate the algorithm. Default = 1e-5

altnam K1 character vector of alternate names to be used by the printed output.

By default, the names X1, X2, X3... or X01, X02, X03 (depending on how

vpad is set) will be used.

output scalar. If non-zero, nal results are printed.

title string, a custom title to be printed at the top of the iterations report. By

default, only a generic title will be printed.

Remarks

The equation procedure should return a column vector containing the result for each

equation. For example:

Equation 1: x1^2 + x2^2 - 2 = 0

Equation 2: exp(x1-1) + x2^3 - 2 = 0

proc f(var);

local x1,x2,eqns;

x1 = var[1];

x2 = var[2];

eqns[1] = x1^2 + x2^2 - 2; /* Equation 1 */

eqns[2] = exp(x1-1) + x2^3 - 2; /* Equation 2 */

retp( eqns );

endp;

Example

515

eqSolve 25. COMMAND REFERENCE

eqsolveset;

proc f(x);

local f1,f2,f3;

f1 = 3*x[1]^3 + 2*x[2]^2 + 5*x[3] - 10;

f2 = -x[1]^3 - 3*x[2]^2 + x[3] + 5;

f3 = 3*x[1]^3 + 2*x[2]^2 - 4*x[3];

retp(f1|f2|f3);

endp;

proc fjc(x);

local fjc1,fjc2, fjc3;

fjc1 = 9*x[1]^2 ~ 4*x[2] ~ 5;

fjc2 = -3*x[1]^2 ~ -6*x[2] ~ 1;

fjc3 = 9*x[1]^2 ~ 4*x[2] ~ -4;

retp(fjc1|fjc2|fjc3);

endp;

start = { -1, 12, -1 };

_eqs_JacobianProc = &fjc;

{ x,tcode } = eqSolve(&f,start);

==========================================================================

EqSolve Version 3.2.22 2/24/97 9:54 am

==========================================================================

||F(X)|| at final solution: 0.93699762

--------------------------------------------------------------------------

Termination Code = 1:

Norm of the scaled function value is less than __Tol;

--------------------------------------------------------------------------

--------------------------------------------------------------------------

VARIABLE START ROOTS F(ROOTS)

--------------------------------------------------------------------------

X1 -1.00000 0.54144351 4.4175402e-06

X2 12.00000 1.4085912 -6.6263102e-06

X3 -1.00000 1.1111111 4.4175402e-06

--------------------------------------------------------------------------

516

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eqSolve

Source

eqsolve.src

517

erf, erfc 25. COMMAND REFERENCE

Purpose

Computes the Gaussian error function (erf) and its complement (erfc).

Format

y = erf(x);

y = erfc(x);

Input

x NK matrix.

Output

y NK matrix.

Remarks

The allowable range for x is:

x 0

The erf and erfc functions are closely related to the Normal distribution:

cdfn(x) =

1

2

(1 + erf(

x

2

)) x 0

1

2

erfc(

x

2

) x < 0

Example

x = { .5 .4 .3,

.6 .8 .3 };

y = erf(x);

y =

0.52049988 0.42839236 0.32862676

0.60385609 0.74210096 0.32862676

x = { .5 .4 .3,

.6 .8 .3 };

y = erfc(x);

y =

0.47950012 0.57160764 0.67137324

0.39614391 0.25789904 0.67137324

See also

cdfn, cdfnc

Technical Notes

erf and erfc are computed by summing the appropriate series and continued fractions.

They are accurate to about 10 digits.

518

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE error

Purpose

Allows the user to generate a user-dened error code which can be tested quickly with

the scalerr function.

Format

y = error(x);

Input

x scalar, in the range 065535.

Output

y scalar error code which can be interpreted as an integer with the scalerr

function.

Remarks

The user may assign any number in the range 065535 to denote particular error

conditions. This number may be tested for as an error code by scalerr.

The scalerr function will return the value of the error code and so is the reverse of

error. These user-generated error codes work in the same way as the intrinsic GAUSS

error codes which are generated automatically when trap 1 is on and certain GAUSS

functions detect a numerical error such as a singular matrix.

error(0) is equal to the missing value code.

Example

proc syminv(x);

local oldtrap,y;

if not x == x;

retp(error(99));

endif;

oldtrap = trapchk(0xffff);

trap 1;

y = invpd(x);

if scalerr(y);

y = inv(x);

endif;

trap oldtrap,0xffff;

retp(y);

endp;

The procedure syminv returns error code 99 if the matrix is not symmetric. If invpd

fails, it returns error code 20. If inv fails, it returns error code 50. The original trap

state is restored before the procedure returns.

See also

scalerr, trap, trapchk

519

errorlog 25. COMMAND REFERENCE

Purpose

Prints an error message to the screen and error log le.

Format

errorlog str;

Input

str string, the error message to print.

Portability

Unix

errorlog prints to window 1 and the error log le.

OS/2, Windows

errorlog prints to the main GAUSS window and the error log le.

520

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE etdays

Purpose

Computes the dierence between two times, as generated by the date command, in

days.

Format

days = etdays(tstart,tend);

Input

tstart 31 or 41 vector, starting date, in the order: yr, mo, day. (Only the rst

3 elements are used.)

tend 31 or 41 vector, ending date, in the order: yr, mo, day. (Only the rst

3 elements are used.) MUST be later than tstart.

Output

days scalar, elapsed time measured in days.

Remarks

This will work correctly across leap years and centuries. The assumptions are a

Gregorian calendar with leap years on the years evenly divisible by 4 and not evenly

divisible by 400.

Example

let date1 = 1986 1 2;

let date2 = 1987 10 25;

d = etdays(date1,date2);

d = 661

Source

time.src

Globals

daypryr, dayinyr

521

ethsec 25. COMMAND REFERENCE

Purpose

Computes the dierence between two times, as generated by the date command, in

hundredths of a second.

Format

hs = ethsec(tstart,tend);

Input

tstart 41 vector, starting date, in the order: yr, mo, day, hundredths of a

second.

tend 41 vector, ending date, in the order: yr, mo, day, hundredths of a second.

MUST be later date than tstart.

Output

hs scalar, elapsed time measured in hundredths of a second.

Remarks

This will work correctly across leap years and centuries. The assumptions are a

Gregorian calendar with leap years on the years evenly divisible by 4 and not evenly

divisible by 400.

Example

let date1 = 1986 1 2 0;

let date2 = 1987 10 25 0;

t = ethsec(date1,date2);

t = 5711040000

Source

time.src

Globals

daypryr, dayinyr

522

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE etstr

Purpose

Formats an elapsed time measured in hundredths of a second to a string.

Format

str = etstr(tothsecs);

Input

tothsecs scalar, an elapsed time measured in hundredths of a second, as given, for

instance, by the ethsec function.

Output

str string containing the elapsed time in the form:

# days # hours # minutes #.## seconds

Example

d1 = { 86, 1, 2, 0 };

d2 = { 86, 2, 5, 815642 };

t = ethsec(d1,d2);

str = etstr(t);

t = 2.9457564e +08

str = 34 days 2 hours 15 minutes 56.42 seconds

Source

time.src

Globals

None

523

exctsmpl 25. COMMAND REFERENCE

Purpose

Computes a random subsample of a data set.

Format

n = exctsmpl(inle,outle,percent );

Input

inle string, the name of the original data set.

outle string, the name of the data set to be created.

percent scalar, the percentage random sample to take. This must be in the range

0100.

Output

n scalar, number of rows in output data set.

Error returns are controlled by the low bit of the trap ag:

trap 0 terminate with error message

trap 1 return scalar negative integer

1 cant open input le

2 cant open output le

3 disk full

Remarks

Random sampling is done with replacement. Thus, an observation may be in the

resulting sample more than once. If percent is 100, the resulting sample will not be

identical to the original sample, though it will be the same size.

Example

n = exctsmpl("freq.dat","rout",30);

n = 30

freq.dat is an example data set provided with GAUSS. Switching to the GAUSS

examples directory will make it possible to do the above example as shown. Otherwise

substitute data set names will need to be used.

Source

exctsmpl.src

Globals

None

524

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE exec

Purpose

Executes an executable program and returns the exit code to GAUSS.

Format

y = exec(program,comline);

Portability

Unix

All I/O goes to GAUSSs controlling terminal.

Windows

The le can be given an extension or a . meaning no extension. Otherwise the le

will be searched for with the following extensions in their given order: .com, .exe,

.bat, .cmd.

OS/2

exec works the same as in Windows, except that the only default extension is .exe.

DOS

You must use the full name of the executable, including the extension.

This uses MS-DOS functions 4B and 4D. The child process can return an exit code

when it returns if it terminates with the MS-DOS function 4C. See the DOS Technical

Reference manual for detailed information on these functions.

Input

program string, the name of the program to be executed.

comline string, the arguments to be placed on the command line of the program

being executed.

Output

y the exit code returned by program.

If exec cant execute program, the error returns will be negative.

1 le not found

2 the le is not an executable le

525

exec 25. COMMAND REFERENCE

3 not enough memory

4 command line too long

Remarks

On some platforms the exit code is truncated to a 2-byte signed integer and only the

lower 8 bits will be returned. Therefore a 1 will be returned as 255. The operating

system may also set the lower 2 bits of the high byte of the returned word.

Example

y = exec("atog","comd1.cmd");

if y;

errorlog "atog failed";

end;

endif;

In this example the atog ASCII conversion utility is executed under the exec function.

The name of the command le to be used, comd1.cmd, is passed to atog on its

command line. The exit code y returned by exec is tested to see if atog was successful;

if not, the program will be terminated after printing an error message.

526

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE exp

Purpose

Calculates the exponential function.

Format

y = exp(x);

Input

x NK matrix.

Output

y NK matrix containing e, the base of natural logs, raised to the powers

given by the elements of x.

Example

x = eye(3);

y = exp(x);

x =

1.000000 0.000000 0.000000

0.000000 1.000000 0.000000

0.000000 0.000000 1.000000

y =

2.718282 1.000000 1.000000

1.000000 2.718282 1.000000

1.000000 1.000000 2.718282

This example creates a 33 identity matrix and computes the exponential function for

each one of its elements. Note that exp(1) returns e, the base of natural logs.

See also

ln

527

external 25. COMMAND REFERENCE

Purpose

To let the compiler know about symbols that are referenced above or in a separate le

from their denitions.

Format

external proc dog,cat ;

external keyword dog;

external fn dog;

external matrix x,y,z;

external string mstr,cstr;

Remarks

See Chapter 9.

You may have several procedures in dierent les that reference the same global

variable. By placing an external statement at the top of each le, you can let the

compiler know if the symbol is a matrix, string or procedure. If the symbol is listed and

strongly typed in an active library, no external statement is needed.

If a matrix or string appears in an external statement it needs to appear once in a

declare statement. If no declaration is found, an Undened symbol error will result.

Example

The real general eigenvalue procedure, eigrg, sets a global variable eigerr if it cannot

compute all of the eigenvalues.

external matrix _eigerr;

x = rndn(4,4);

xi = inv(x);

xev = eigrg(x);

if _eigerr;

print "Eigenvalues not computed";

end;

endif;

Without the external statement, the compiler would assume that eigerr was a

procedure and incorrectly compile this program. The le containing the eigrg

procedure also contains an external statement that denes eigerr as a matrix, but

this would not be encountered until the if statement containing the reference to eigerr

in the main program le had already been incorrectly compiled.

See also

declare

528

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

E

25. COMMAND REFERENCE eye

Purpose

Creates an identity matrix.

Format

y = eye(n);

Input

n scalar, size of identity matrix to be created.

Output

y NN identity matrix.

Remarks

If n is not an integer, it will be truncated to an integer.

The matrix created will contain 1s down the diagonal and 0s everywhere else.

Example

x = eye(3);

x =

1.000000 0.000000 0.000000

0.000000 1.000000 0.000000

0.000000 0.000000 1.000000

See also

zeros, ones

529

fcheckerr 25. COMMAND REFERENCE

Purpose

Gets the error status of a le.

Format

err = fcheckerr(f );

Input

f scalar, le handle of a le opened with fopen.

Output

err scalar, error status.

Remarks

If there has been a read or write error on a le, fcheckerr returns 1, otherwise 0.

If you pass fcheckerr the handle of a le opened with open (i.e., a data set or matrix

le), your program will terminate with a fatal error.

530

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fclearerr

Purpose

Gets the error status of a le, then clears it.

Format

err = fclearerr(f );

Input

f scalar, le handle of a le opened with fopen.

Output

err scalar, error status.

Remarks

Each le has an error ag that gets set when there is an I/O error on the le.

Typically, once this ag is set, you can no longer do I/O on the le, even if the error is

a recoverable one. fclearerr clears the les error ag, so you can attempt to continue

using it.

If there has been a read or write error on a le, fclearerr returns 1, otherwise 0.

If you pass fclearerr the handle of a le opened with open (i.e., a data set or matrix

le), your program will terminate with a fatal error.

The ag accessed by fclearerr is not the same as that accessed by fstrerror.

531

feqfne 25. COMMAND REFERENCE

Purpose

Fuzzy comparison functions. These functions use fcmptol to fuzz the comparison

operations to allow for roundo error.

Format

y = feq(a,b);

y = fge(a,b);

y = fgt(a,b);

y = e(a,b);

y = t(a,b);

y = fne(a,b);

Input

a NK matrix, rst matrix.

b LM matrix, second matrix, EE compatible with a.

fcmptol global scalar, comparison tolerance. The default value is 1.0e 15.

Output

y scalar, 1 (true) or 0 (false).

Remarks

The return value is true if every comparison is true.

The statement:

y = feq(a,b);

is equivalent to:

y = a eq b;

The calling program can reset fcmptol before calling these procedures.

_fcmptol = 1e-12;

532

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE feqfne

Example

x = rndu(2,2);

y = rndu(2,2);

t = fge(x,y);

x =

0.038289504 0.072535275

0.014713947 0.96863611

y =

0.25622293 0.70636474

0.0036191244 0.35913385

t = 0.0000000

Source

fcompare.src

Globals

fcmptol

See also

dotfeq

533

ush 25. COMMAND REFERENCE

Purpose

Flushes a les output buer.

Format

ret = ush(f );

Input

f scalar, le handle of a le opened with fopen.

Output

ret scalar, 0 if successful, -1 if not.

Remarks

If ush fails, you can call fstrerror to nd out why.

If you pass ush the handle of a le opened with open (i.e., a data set or matrix le),

your program will terminate with a fatal error.

534

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE t

Purpose

Computes a 1- or 2-D Fast Fourier transform.

Format

y = t(x);

Input

x NK matrix.

Output

y LM matrix, where L and M are the smallest powers of 2 greater than or

equal to N and K, respectively.

Remarks

This computes the FFT of x, scaled by 1/N.

This uses a Temperton Fast Fourier algorithm.

If N or K is not a power of 2, x will be padded out with zeros before computing the

transform.

Example

x = { 22 24,

23 25 };

y = fft(x);

y =

23.500000 1.0000000

0.5000000 0.00000000

See also

ti, rt, rti

535

ti 25. COMMAND REFERENCE

Purpose

Computes an inverse 1- or 2-D Fast Fourier transform.

Format

y = ti(x);

Input

x NK matrix.

Output

y LM matrix, where L and M are the smallest prime factor products

greater than or equal to N and K, respectively.

Remarks

Computes the inverse FFT of x, scaled by 1/N.

This uses a Temperton prime factor Fast Fourier algorithm.

Example

x = { 22 24,

23 25 };

y = fft(x);

y =

23.500000 1.0000000

0.5000000 0.00000000

fi = ffti(y);

fi =

22.000000 24.000000

23.000000 25.000000

See also

t, rt, rti

536

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE tm

Purpose

Computes a multi-dimensional FFT.

Format

y = tm(x,dim);

Input

x M1 vector, data.

dim K1 vector, size of each dimension.

Output

y L1 vector, FFT of x.

Remarks

The multi-dimensional data are laid out in a recursive or heirarchical fashion in the

vector x. That is to say, the elements of any given dimension are stored in sequence left

to right within the vector, with each element containing a sequence of elements of the

next smaller dimension. In abstract terms, a 4-dimensional 2x2x2x2 hypercubic x

would consist of two cubes in sequence, each cube containing two matrices in sequence,

each matrix containing two rows in sequence, and each row containing two columns in

sequence. Visually, x would look something like this:

X

hyper

= X

cube1

[ X

cube2

X

cube1

= X

mat1

[ X

mat2

X

mat1

= X

row1

[ X

row2

X

row1

= X

col1

[ X

col2

Or, in an extended GAUSS notation, x would be:

Xhyper = x[1,.,.,.] | x[2,.,.,.];

Xcube1 = x[1,1,.,.] | x[1,2,.,.];

Xmat1 = x[1,1,1,.] | x[1,1,2,.];

Xrow1 = x[1,1,1,1] | x[1,1,1,2];

To be explicit, x would be laid out like this:

x[1,1,1,1] x[1,1,1,2] x[1,1,2,1] x[1,1,2,2]

x[1,2,1,1] x[1,2,1,2] x[1,2,2,1] x[1,2,2,2]

x[2,1,1,1] x[2,1,1,2] x[2,1,2,1] x[2,1,2,2]

x[2,2,1,1] x[2,2,1,2] x[2,2,2,1] x[2,2,2,2]

537

tm 25. COMMAND REFERENCE

Constructing multi-dimensional matrices in vector format is actually quite simple. If

you look at the last diagram for the layout of x youll notice that each line actually

constitutes the elements of an ordinary matrix in normal row-major order. This is easy

to achieve with vecr. Further, each pair of lines or matrices constitutes one of the

desired cubes, again with all the elements in the correct order. And nally, the two

cubes combine to form the hypercube. So, the process of construction is simply a

sequence of concatenations of column vectors, with a vecr step if necessary to get

started.

Heres an example, this time working with a 2x3x2x3 hypercube.

let dim = 2 3 2 3;

let x1[2,3] = 1 2 3 4 5 6;

let x2[2,3] = 6 5 4 3 2 1;

let x3[2,3] = 1 2 3 5 7 11;

xc1 = vecr(x1)|vecr(x2)|vecr(x3); /* cube 1 */

let x1 = 1 1 2 3 5 8;

let x2 = 1 2 6 24 120 720;

let x3 = 13 17 19 23 29 31;

xc2 = x1|x2|x3; /* cube 2 */

xh = xc1|xc2; /* hypercube */

xhfft = fftm(xh,dim);

let dimi = 2 4 2 4;

xhffti = fftmi(xhfft,dimi);

I left out the vecr step for the 2

nd

cube. Its not really necessary when youre

constructing the matrices with let statements.

dim contains the dimensions of x, beginning with the highest dimension. The last

element of dim is the number of columns, the next to the last element of dim is the

number of rows, and so on. Thus

dim = { 2, 3, 3 };

indicates that the data in x is a 2x3x3 three-dimensional array, i.e., two 3x3 matrices of

data. Suppose that x1 is the rst 3x3 matrix and x2 the second 3x3 matrix, then x =

vecr(x1) | vecr(x2).

The size of dim tells you how many dimensions x has.

The arrays have to be padded in each dimension to the nearest power of two. Thus the

output array can be larger than the input array. In the 2x3x2x3 hypercube example, x

would be padded from 2x3x2x3 out to 2x4x2x4. The input vector would contain 36

elements, while the output vector would contain 64 elements. You may have noticed

that we used a dimi with padded values at the end of the example to check our answer.

538

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE tmi

Purpose

Computes a multi-dimensional inverse FFT.

Format

y = tmi(x,dim);

Input

x M1 vector, data.

dim K1 vector, size of each dimension.

Output

y L1 vector, inverse FFT of x.

Remarks

The multi-dimensional data are laid out in a recursive or heirarchical fashion in the

vector x. That is to say, the elements of any given dimension are stored in sequence left

to right within the vector, with each element containing a sequence of elements of the

next smaller dimension. In abstract terms, a 4-dimensional 2x2x2x2 hypercubic x

would consist of two cubes in sequence, each cube containing two matrices in sequence,

each matrix containing two rows in sequence, and each row containing two columns in

sequence. Visually, x would look something like this:

X

hyper

= X

cube1

[ X

cube2

X

cube1

= X

mat1

[ X

mat2

X

mat1

= X

row1

[ X

row2

X

row1

= X

col1

[ X

col2

Or, in an extended GAUSS notation, x would be:

Xhyper = x[1,.,.,.] | x[2,.,.,.];

Xcube1 = x[1,1,.,.] | x[1,2,.,.];

Xmat1 = x[1,1,1,.] | x[1,1,2,.];

Xrow1 = x[1,1,1,1] | x[1,1,1,2];

To be explicit, x would be laid out like this:

x[1,1,1,1] x[1,1,1,2] x[1,1,2,1] x[1,1,2,2]

x[1,2,1,1] x[1,2,1,2] x[1,2,2,1] x[1,2,2,2]

x[2,1,1,1] x[2,1,1,2] x[2,1,2,1] x[2,1,2,2]

x[2,2,1,1] x[2,2,1,2] x[2,2,2,1] x[2,2,2,2]

539

tmi 25. COMMAND REFERENCE

Constructing multi-dimensional matrices in vector format is actually quite simple. If

you look at the last diagram for the layout of x youll notice that each line actually

constitutes the elements of an ordinary matrix in normal row-major order. This is easy

to achieve with vecr. Further, each pair of lines or matrices constitutes one of the

desired cubes, again with all the elements in the correct order. And nally, the two

cubes combine to form the hypercube. So, the process of construction is simply a

sequence of concatenations of column vectors, with a vecr step if necessary to get

started.

Heres an example, this time working with a 2x3x2x3 hypercube.

let dim = 2 3 2 3;

let x1[2,3] = 1 2 3 4 5 6;

let x2[2,3] = 6 5 4 3 2 1;

let x3[2,3] = 1 2 3 5 7 11;

xc1 = vecr(x1)|vecr(x2)|vecr(x3); /* cube 1 */

let x1 = 1 1 2 3 5 8;

let x2 = 1 2 6 24 120 720;

let x3 = 13 17 19 23 29 31;

xc2 = x1|x2|x3; /* cube 2 */

xh = xc1|xc2; /* hypercube */

xhffti = fftmi(xh,dim);

I left out the vecr step for the 2

nd

cube. Its not really necessary when youre

constructing the matrices with let statements.

dim contains the dimensions of x, beginning with the highest dimension. The last

element of dim is the number of columns, the next to the last element of dim is the

number of rows, and so on. Thus

dim = { 2, 3, 3 };

indicates that the data in x is a 2x3x3 three-dimensional array, i.e., two 3x3 matrices of

data. Suppose that x1 is the rst 3x3 matrix and x2 the second 3x3 matrix, then x =

vecr(x1) | vecr(x2).

The size of dim tells you how many dimensions x has.

The arrays have to be padded in each dimension to the nearest power of two. Thus the

output array can be larger than the input array. In the 2x3x2x3 hypercube example, x

would be padded from 2x3x2x3 out to 2x4x2x4. The input vector would contain 36

elements, while the output vector would contain 64 elements.

540

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE tn

Purpose

Computes a complex 1- or 2-D FFT.

Format

y = tn(x);

Input

x NK matrix.

Output

y LM matrix, where L and M are the smallest prime factor products

greater than or equal to N and K, respectively.

Remarks

tn uses the Temperton prime factor FFT algorithm. This algorithm can compute the

FFT of any vector or matrix whose dimensions can be expressed as the product of

selected prime number factors. GAUSS implements the Temperton algorithm for any

power of 2, 3, and 5, and one factor of 7. Thus, tn can handle any matrix whose

dimensions can be expressed as

2

p

3

q

5

r

7

s

, p, q, r nonnegative integers

s = 0 or 1

If a dimension of x does not meet this requirement, it will be padded with zeros to the

next allowable size before the FFT is computed.

tn pads matrices to the next allowable dimensions; however, it generally runs faster

for matrices whose dimensions are highly composite numbers, i.e., products of several

factors (to various powers), rather than powers of a single factor. For example, even

though it is bigger, a 33600x1 vector can compute as much as 20% faster than a

32768x1 vector, because 33600 is a highly composite number, 2

6

3 5

2

7, whereas

32768 is a simple power of 2, 2

15

. For this reason, you may want to hand-pad matrices

to optimum dimensions before passing them to tn. The Run-Time Library includes a

routine, optn, for determining optimum dimensions.

The Run-Time Library also includes the nextn routine, for determining allowable

dimensions for a matrix. (You can use this to see the dimensions to which tn would

pad a matrix.)

tn scales the computed FFT by 1/(L*M).

See also

t, ti, tm, tmi, rt, rti, rtip, rtn, rtnp, rtp

541

fgets 25. COMMAND REFERENCE

Purpose

Reads a line of text from a le.

Format

str = fgets(f ,maxsize);

Input

f scalar, le handle of a le opened with fopen.

maxsize scalar, maximum size of string to read in, including the terminating null

byte.

Output

str string.

Remarks

fgets reads text from a le into a string. It reads up to a newline, the end of the le, or

maxsize-1 characters. The result is placed in str, which is then terminated with a null

byte. The newline, if present, is retained.

If the le is already at end-of-le when you call fgets, your program will terminate with

an error. Use eof in conjunction with fgets to avoid this.

If the le was opened for update (see fopen) and you are switching from writing to

reading, dont forget to call fseek or ush rst, to ush the les buer.

If you pass fgets the handle of a le opened with open (i.e., a data set or matrix le),

your program will terminate with a fatal error.

542

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fgetsa

Purpose

Reads lines of text from a le into a string array.

Format

sa = fgetsa(f ,numl );

Input

f scalar, le handle of a le opened with fopen.

numl scalar, number of lines to read.

Output

sa N1 string array, N <= numl .

Remarks

fgetsa reads up to numl lines of text. If fgetsa reaches the end of the le before reading

numl lines, sa will be shortened. Lines are read in the same manner as fgets, except

that no limit is placed on the size of a line. Thus, fgetsa always returns complete lines

of text. Newlines are retained. If numl is 1, fgetsa returns a string. (This is one way to

read a line from a le without placing a limit on the length of the line.)

If the le is already at end-of-le when you call fgetsa, your program will terminate

with an error. Use eof in conjunction with fgetsa to avoid this. If the le was opened

for update (see fopen) and you are switching from writing to reading, dont forget to

call fseek or ush rst, to ush the les buer.

If you pass fgetsa the handle of a le opened with open (i.e., a data set or matrix le),

your program will terminate with a fatal error.

543

fgetsat 25. COMMAND REFERENCE

Purpose

Reads lines of text from a le into a string array.

Format

sa = fgetsat(f ,numl );

Input

f scalar, le handle of a le opened with fopen.

numl scalar, number of lines to read.

Output

sa N1 string array, N <= numl .

Remarks

fgetsat operates identically to fgetsa, except that newlines are not retained as text is

read into sa.

In general, you dont want to use fgetsat on les opened in binary mode (see fopen).

fgetsat drops the newlines, but it does NOT drop the carriage returns that precede

them on some platforms. Printing out such a string array can produce unexpected

results.

544

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fgetst

Purpose

Reads a line of text from a le.

Format

str = fgetst(f ,maxsize);

Input

f scalar, le handle of a le opened with fopen.

maxsize scalar, maximum size of string to read in, including the null terminating

byte.

Output

str string.

Remarks

fgetst operates identically to fgets, except that the newline is not retained in the string.

In general, you dont want to use fgetst on les opened in binary mode (see fopen).

fgetst drops the newline, but it does NOT drop the preceding carriage return used on

some platforms. Printing out such a string can produce unexpected results.

545

leinfo 25. COMMAND REFERENCE

Purpose

Returns names and information for les that match a specication.

Format

{ fnames,nfo } = leinfo(fspec);

Input

fspec string, le specication. Can include path. Wildcards are allowed in the

lename.

Output

fnames N1 string array of all lenames that match, null string if none are found.

nfo N13 matrix, information about matching les.

Unix

[N, 1] lesystem ID

[N, 2] inode number

[N, 3] mode bit mask

[N, 4] number of links

[N, 5] user ID

[N, 6] group ID

[N, 7] device ID (char/block special les only)

[N, 8] size in bytes

[N, 9] last access time

[N,10] last data modication time

[N,11] last le status change time

[N,12] preferred I/O block size

[N,13] number of 512-byte blocks allocated

546

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE leinfo

OS/2, Windows

[N, 1] drive number (A = 0, B = 1, etc.)

[N, 2] n/a, 0

[N, 3] mode bit mask

[N, 4] number of links, always 1

[N, 5] n/a, 0

[N, 6] n/a, 0

[N, 7] n/a, 0

[N, 8] size in bytes

[N, 9] last access time

[N,10] last data modication time

[N,11] creation time

[N,12] n/a, 0

[N,13] n/a, 0

DOS

[N, 1] drive number (A = 0, B = 1, etc.)

[N, 2] n/a, 0

[N, 3] mode bit mask

[N, 4] number of links, always 1

[N, 5] n/a, 0

[N, 6] n/a, 0

[N, 7] n/a, 0

[N, 8] size in bytes

[N, 9] n/a, 0

[N,10] last data modication time

[N,11] n/a, 0

[N,12] n/a, 0

[N,13] n/a, 0

nfo will be a scalar zero if no matches are found.

Remarks

fnames will contain le names only; any path information that was passed is dropped.

The time stamp elds (finfo[N, 9][N, 11]) are expressed as the number of seconds

since midnight, Jan. 1, 1970, Coordinated Universal Time (UTC).

See also

les, lesa

547

les 25. COMMAND REFERENCE

Purpose

Returns a matrix of matching le names.

Format

y = les(n,a);

Input

n string containing any combination of drive, path, and lename to search

for. Wildcards are allowed in the lename.

a scalar, the attribute to use in the search.

Output

y N2 matrix of all lenames that match, or scalar 0 if none are found.

Portability

Unix, OS/2, Windows

les was written to work under DOS, with its 8x3 lenames; use leinfo or lesa

instead.

Remarks

The le names will be in the rst column of the returned matrix. The drive and path

that was passed is dropped, and the extensions, including the period ., will be in the

second column. For les with no extension the second column entry will be null.

Volume labels look like lenames and have a period before the 9

th

character.

The attribute corresponds to the le attribute for each entry in the disk directory. For

normal les an attribute of 0 is used. This will return the names of all matching

normal les. The bits in the attribute byte have the following meaning:

2 Hidden les

4 System les

8 Volume Label (DOS only)

16 Subdirectory

The values above are added together to specify dierent types of les to be searched

for. Therefore 6 would specify hidden+system.

If the attribute is set for hidden, system, or subdirectory entries then it will be an

inclusive search. All normal entries plus all entries matching the specied attributes

will be returned.

If the attribute is set for the volume label, it will be an exclusive search and only the

volume label will be returned.

Example

548

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE les

y = files("ch*.*",0);

In this example all normal les listed in the current directory that begin with ch will

be returned.

y = files("ch*.",0);

In this example all normal les listed in the current directory that begin with ch but

do not have an extension will be returned.

y = files("ch*.*",2+4+16);

In this example all normal, hidden, and system les and all subdirectories listed in the

current directory that begin with ch will be returned.

proc exist(filename);

retp(not files(filename,0) $== 0);

endp;

This procedure will return 1 if the le exists or 0 if not.

See also

dos, leinfo, lesa

549

lesa 25. COMMAND REFERENCE

Purpose

Returns a string array of le names.

Format

y = lesa(n);

Input

n string, le specication to search for. Can include path. Wildcards are

allowed in the lename.

Output

y N1 string array of all lenames that match, or null string if none are

found.

Remarks

y will contain le names only; any path information that was passed is dropped.

Example

y = filesa("ch*");

In this example all les listed in the current directory that begin with ch will be

returned.

proc exist(filename);

retp(not filesa(filename) $== "");

endp;

This procedure will return 1 if the le exists or 0 if not.

See also

dos, leinfo, les

550

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE oor

Purpose

Round down toward .

Format

y = oor(x);

Input

x NK matrix.

Output

y NK matrix containing the elements of x rounded down.

Remarks

This rounds every element in the matrix x down to the nearest integer.

Example

x = 100*rndn(2,2);

x =

77.68 14.10

4.73 158.88

f = floor(x);

f =

77.00 15.00

4.00 159.00

See also

ceil, round, trunc

551

fmod 25. COMMAND REFERENCE

Purpose

Computes the oating-point remainder of x/y.

Format

r = fmod(x,y);

Input

x NK matrix.

y LM matrix, EE conformable with x.

Output

r max(N,L) by max(K,M) matrix.

Remarks

Returns the oating-point remainder r of x/y such that x = iy +r, where i is an

integer, r has the same sign as x and [r[ < [y[.

Compare this with %, the modulo division operator, in Chapter 8.

Example

x = seqa(1.7,2.3,5);

y = 2;

r = fmod(x,y);

x = 1.7 4 6.3 8.6 10.9

r = 1.7 0 0.3 0.6 0.9

552

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fn

Purpose

Allows user to create one-line functions.

Format

fn fn name(args) = code for function;

Example

fn area(r) = pi*r*r;

a = area(4);

Remarks

Functions can be called in the same way as other procedures.

553

fopen 25. COMMAND REFERENCE

Purpose

Opens a le.

Format

f = fopen(lename,omode);

Input

lename string, name of le to open.

omode string, le I/O mode.

Output

f scalar, le handle.

Portability

Unix

Carriage return-linefeed conversion for les opened in text mode is unnecessary,

because in Unix a newline is simply a linefeed.

Remarks

lename can contain a path specication.

omode is a sequence of characters that specify the mode in which to open the le. The

rst character must be one of:

r Open an existing le for reading. If the le does not exist, fopen fails.

w Open or create a le for writing. If the le already exists, its current

contents will be destroyed.

a Open or create a le for appending. All output is appended to the end of

the le.

To this can be appended a + and/or a b. The + indicates the le is to opened for

reading and writing, or update, as follows:

r+ Open an existing le for update. You can read from or write to any

location in the le. If the le does not exist, fopen fails.

554

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fopen

w+ Open or create a le for update. You can read from or write to any location

in the le. If the le already exists, its current contents will be destroyed.

a+ Open or create a le for update. You can read from any location in the

le, but all output will be appended to the end of the le.

Finally, the b indicates whether the le is to be opened in text or binary mode. If the

le is opened in binary mode, the contents of the le are read verbatim; likewise,

anything output to the le is written verbatim. In text mode (the default), carriage

return-linefeed sequences are converted on input to linefeeds, or newlines. Likewise on

output, newlines are converted to carriage return-linefeeds. Also in text mode, if a

Ctrl-Z (char 26) is encountered during a read, it is interpreted as an end-of-le

character, and reading ceases. In binary mode, Ctrl-Z is read in uninterpreted.

The order of + and b is not signicant; rb+ and r+b mean the same thing.

You can both read from and write to a le opened for update. However, before

switching from one to the other, you must make an fseek or ush call, to ush the

les buer.

If fopen fails, it returns a 0.

Use close and closeall to close les opened with fopen.

555

for 25. COMMAND REFERENCE

Purpose

Begins a for loop.

Format

for i (start , stop, step);

.

.

.

endfor;

Input

i literal, the name of the counter variable.

start scalar expression, the initial value of the counter.

stop scalar expression, the nal value of the counter.

step scalar expression, the increment value.

Remarks

The counter is strictly local to the loop. It is created with an implicit #dene. The

expressions, start , stop and step are evaluated only once when the loop initializes.

They are converted to integers and stored local to the loop.

The for loop is optimized for speed and much faster than a do loop.

The commands break and continue are supported. The continue command steps the

counter and jumps to the top of the loop. The break command terminates the current

loop.

When the loop terminates, the value of the counter is stop if the loop terminated

naturally. If break is used to terminate the loop and you want the nal value of the

counter you need to assign it to a variable before the break statement. See the third

example below.

Example

x = zeros(10, 5);

for i (1, rows(x), 1);

for j (1, cols(x), 1);

x[i,j] = i*j;

endfor;

556

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE for

endfor;

x = rndn(3,3);

y = rndn(3,3);

for i (1, rows(x), 1);

for j (1, cols(x), 1);

if x[i,j] >= y[i,j];

continue;

endif;

temp = x[i,j];

x[i,j] = y[i,j];

y[i,j] = temp;

endfor;

endfor;

li = 0;

x = rndn(100,1);

y = rndn(100,1);

for i (1, rows(x), 1);

if x[i] /= y[i];

li = i;

break;

endif;

endfor;

if li;

print "Compare failed on row " li;

endif;

557

format 25. COMMAND REFERENCE

Purpose

Controls the format of matrices and numbers printed out with print or lprint

statements.

Format

format [[/typ]] [[/fmted]] [[/mf ]] [[/jnt]] [[f,p]]; ;

Input

/typ literal, symbol type ag(s). Indicate which symbol types you are setting

the output format for.

/mat, /sa, /str Formatting parameters are maintained separately for

matrices (/mat), string arrays (/sa), and strings (/str). You can

specify more than one /typ ag; the format will be set for all types

indicated. If no /typ ag is listed, format assumes /mat.

/fmted literal, enable formatting ag.

/on, /o Enable/disable formatting. When formatting is disabled, the

contents of a variable are dumped to the screen in a raw format.

/o is currently supported only for strings. Raw format for

strings means that the entire string is printed, starting at the

current cursor position. When formatting is enabled for strings,

they are handled the same as string arrays. This shouldnt be too

surprising, since a string is actually a 1x1 string array.

/mf literal, matrix row format ag.

/m0 no delimiters before or after rows when printing out matrices.

/m1 or /mb1 print 1 carriage return/line feed pair before each row of a

matrix with more than 1 row.

/m2 or /mb2 print 2 carriage return/line feed pairs before each row of a

matrix with more than 1 row.

/m3 or /mb3 print Row 1, Row 2... before each row of a matrix

with more than one row.

/ma1 print 1 carriage return/line feed pair after each row of a matrix

with more than 1 row.

/ma2 print 2 carriage return/line feed pairs after each row of a matrix

with more than 1 row.

/a1 print 1 carriage return/line feed pair after each row of a matrix.

/a2 print 2 carriage return/line feed pairs after each row of a matrix.

558

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE format

/b1 print 1 carriage return/line feed pair before each row of a matrix.

/b2 print 2 carriage return/line feed pairs before each row of a matrix.

/b3 print Row 1, Row 2... before each row of a matrix.

/jnt literal, matrix element format ag controls justication, notation and

trailing character.

Right-Justied

/rd Signed decimal number in the form [[-]]####.####, where #### is

one or more decimal digits. The number of digits before the

decimal point depends on the magnitude of the number, and the

number of digits after the decimal point depends on the precision.

If the precision is 0, no decimal point will be printed.

/re Signed number in the form [[-]]#.##E###, where # is one decimal

digit, ## is one or more decimal digits depending on the precision,

and ### is three decimal digits. If precision is 0, the form will be

[[-]]#E### with no decimal point printed.

/ro This will give a format like /rd or /re depending on which is most

compact for the number being printed. A format like /re will be

used only if the exponent value is less than -4 or greater than the

precision. If a /re format is used, a decimal point will always

appear. The precision signies the number of signicant digits

displayed.

/rz This will give a format like /rd or /re depending on which is most

compact for the number being printed. A format like /re will be

used only if the exponent value is less than -4 or greater than the

precision. If a /re format is used, trailing zeros will be supressed

and a decimal point will appear only if one or more digits follow it.

The precision signies the number of signicant digits displayed.

Left-Justied

/ld Signed decimal number in the form [[-]]####.####, where #### is

one or more decimal digits. The number of digits before the

decimal point depends on the magnitude of the number, and the

number of digits after the decimal point depends on the precision.

If the precision is 0, no decimal point will be printed. If the number

is positive, a space character will replace the leading minus sign.

/le Signed number in the form [[-]]#.##E###, where # is one decimal

digit, ## is one or more decimal digits depending on the precision,

and ### is three decimal digits. If precision is 0, the form will be

[[-]]#E### with no decimal point printed. If the number is

positive, a space character will replace the leading minus sign.

/lo This will give a format like /ld or /le depending on which is most

compact for the number being printed. A format like /le will be

559

format 25. COMMAND REFERENCE

used only if the exponent value is less than -4 or greater than the

precision. If a /le format is used, a decimal point will always

appear. If the number is positive, a space character will replace the

leading minus sign. The precision species the number of

signicant digits displayed.

/lz This will give a format like /ld or /le depending on which is most

compact for the number being printed. A format like /le will be

used only if the exponent value is less than -4 or greater than the

precision. If a /le format is used, trailing zeros will be supressed

and a decimal point will appear only if one or more digits follow it.

If the number is positive, a space character will replace the leading

minus sign. The precision species the number of signicant digits

displayed.

Trailing Character

The following characters can be added to the /jnt parameters

above to control the trailing character if any:

format /rdn 1,3;

s The number will be followed immediately by a space character.

This is the default.

c The number will be followed immediately with a comma.

t The number will be followed immediately with a tab character.

n No trailing character.

f scalar expression, controls the eld width.

p scalar expression, controls the precision.

Portability

Unix, OS/2, Windows

format sets the print statement format for the active window. Each window

remembers its own format, even when it is no longer the active window.

Remarks

For numeric values in matrices, p sets the number of signicant digits to be printed.

For string arrays, strings, and character elements in matrices, p sets the number of

characters to be printed. If a string is shorter than the specied precision, the entire

string is printed. For string arrays and strings, p = -1 means print the entire string,

regardless of its length. p = -1 is illegal for matrices; setting p >= 8 means the same

thing for character elements.

The /xxx slash parameters are optional. Field and precision are optional also but if one

is included, then both have to be included.

560

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE format

Slash parameters, if present, must precede the eld and precision parameters.

A format statement stays in eect until it is overridden by a new format statement.

The slash parameters may be used in a print statement to override the current default.

f and p may be any legal expressions that return scalars. Nonintegers will be truncated

to integers.

The total width of eld will be overridden if the number is too big to t into the space

allotted. For instance, format /rds 1,0 can be used to print integers with a single space

between them, regardless of the magnitudes of the integers.

Complex numbers are printed with the sign of the imaginary half separating them and

an i appended to the imaginary half. Also, the eld parameter refers to the width of

eld for each half of the number, so a complex number printed with a eld of 8 will

actually take (at least) 20 spaces to print. The character printed after the imaginary

part can be changed (for example, to a j) with the sysstate function, case 9.

The default when GAUSS is rst started is:

format /mb1 /ros 16,8;

Example

x = rndn(3,3);

format /m1 /rd 16,8;

print x;

-1.63533465 1.61350700 -1.06295179

0.26171282 0.27972294 -1.38937242

0.58891114 0.46812202 1.08805960

format /m1 /rzs 1,10;

print x;

-1.635334648 1.613507002 -1.062951787

0.2617128159 0.2797229414 -1.389372421

0.5889111366 0.4681220206 1.088059602

format /m3 /rdn 16,4;

print x;

Row 1

-1.6353 1.6135 -1.0630

Row 2

561

format 25. COMMAND REFERENCE

0.2617 0.2797 -1.3894

Row 3

0.5889 0.4681 1.0881

format /m1 /ldn 16,4;

print x;

-1.6353 1.6135 -1.0630

0.2617 0.2797 -1.3894

0.5889 0.4681 1.0881

format /m1 /res 12,4;

print x;

-1.6353E+000 1.6135E+000 -1.0630E+000

2.6171E-001 2.7972E-001 -1.3894E+000

5.8891E-001 4.6812E-001 1.0881E+000

See also

formatcv, formatnv, print, lprint, output

562

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE formatcv

Purpose

Sets the character data format used by printfmt.

Format

oldfmt = formatcv(newfmt );

Input

newfmt 13 vector, the new format specication.

Output

oldfmt 13 vector, the old format specication.

Remarks

See printfm for details on the format vector.

Example

x = { A 1, B 2, C 3 };

oldfmt = formatcv("*.*s" ~ 3 ~ 3);

call printfmt(x,0~1);

call formatcv(oldfmt);

Source

gauss.src

Globals

fmtcv

See also

formatnv, printfm, printfmt

563

formatnv 25. COMMAND REFERENCE

Purpose

Sets the numeric data format used by printfmt.

Format

oldfmt = formatnv(newfmt );

Input

newfmt 13 vector, the new format specication.

Output

oldfmt 13 vector, the old format specication.

Remarks

See printfm for details on the format vector.

Example

x = { A 1, B 2, C 3 };

oldfmt = formatnv("*.*lf" ~ 8 ~ 4);

call printfmt(x,0~1);

call formatnv(oldfmt);

Source

gauss.src

Globals

fmtnv

See also

formatcv, printfm, printfmt

564

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fputs

Purpose

Writes strings to a le.

Format

numl = fputs(f ,sa);

Input

f scalar, le handle of a le opened with fopen.

sa string or string array.

Output

numl scalar, the number of lines written to the le.

Portability

Unix

Carriage return-linefeed conversion for les opened in text mode is unnecessary,

because in Unix a newline is simply a linefeed.

Remarks

fputs writes the contents of each string in sa, minus the null terminating byte, to the

le specied. If the le was opened in text mode (see fopen), any newlines present in

the strings are converted to carriage return-linefeed sequences on output. If numl is not

equal to the number of elements in sa, there may have been an I/O error while writing

the le. You can use fcheckerr or fclearerr to check this. If there was an error, you can

call fstrerror to nd out what it was. If the le was opened for update (see fopen) and

you are switching from reading to writing, dont forget to call fseek or ush rst, to

ush the les buer. If you pass fputs the handle of a le opened with open (i.e., a

data set or matrix le), your program will terminate with a fatal error.

565

fputst 25. COMMAND REFERENCE

Purpose

Writes strings to a le.

Format

numl = fputst (f ,sa);

Input

f scalar, le handle of a le opened with fopen.

sa string or string array.

Output

numl scalar, the number of lines written to the le.

Portability

Unix

Carriage return-linefeed conversion for les opened in text mode is unnecessary,

because in Unix a newline is simply a linefeed.

Remarks

fputst works identically to fputs, except that a newline is appended to each string that

is written to the le. If the le was opened in text mode (see fopen), these newlines are

also converted to carriage return-linefeed sequences on output.

566

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fseek

Purpose

Positions the le pointer in a le.

Format

ret = fseek(f ,os,base);

Input

f scalar, le handle of a le opened with fopen.

os scalar, oset (in bytes).

base scalar, base position.

0 beginning of le.

1 current position of le pointer.

2 end of le.

Output

ret scalar, 0 is successful, 1 if not.

Portability

Unix

Carriage return-linefeed conversion for les opened in text mode is unnecessary,

because in Unix a newline is simply a linefeed.

Remarks

fseek moves the le pointer os bytes from the specied base position. os can be

positive or negative. The call may fail if the le buer needs to be ushed (see ush).

If fseek fails, you can call fstrerror to nd out why.

For les opened for update (see fopen), the next operation can be a read or a write.

fseek is not reliable when used on les opened in text mode (see fopen). This has to do

with the conversion of carriage return-linefeed sequences to newlines. In particular, an

fseek that follows one of the fgetxxx or fputxxx commands may not produce the

expected result. For example:

567

fseek 25. COMMAND REFERENCE

p = ftell(f);

s = fgetsa(f,7);

call fseek(f,p,0);

is not reliable. We have found that the best results are obtained by fseeking to the

beginning of the le and then fseeking to the desired location, as in:

p = ftell(f);

s = fgetsa(f,7);

call fseek(f,0,0);

call fseek(f,p,0);

If you pass fseek the handle of a le opened with open (i.e., a data set or matrix le),

your program will terminate with a fatal error.

568

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE fstrerror

Purpose

Returns an error message explaining the cause of the most recent le I/O error.

Format

s = fstrerror;

Output

s string, error message.

Remarks

Any time an I/O error occurs on a le opened with fopen, an internal error ag is

updated. (This ag, unlike those accessed by fcheckerr and fclearerr, is not specic to

a given le; rather, it is system-wide.) fstrerror returns an error message based on the

value of this ag, clearing it in the process. If no error has occurred, a null string is

returned.

Since fstrerror clears the error ag, if you call it twice in a row, it will always return a

null string the second time.

569

ftell 25. COMMAND REFERENCE

Purpose

Gets the position of the le pointer in a le.

Format

pos = ftell(f );

Input

f scalar, le handle of a le opened with fopen.

Output

pos scalar, current position of the le pointer in a le.

Remarks

ftell returns the position of the le pointer in terms of bytes from the beginning of the

le. The call may fail if the le buer needs to be ushed (see ush).

If an error occurs, ftell returns -1. You can call fstrerror to nd out what the error was.

If you pass ftell the handle of a le opened with open (i.e., a data set or matrix le),

your program will terminate with a fatal error.

570

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE ftocv

Purpose

Converts a matrix containing oating point numbers into a matrix containing the

decimal character representation of each element.

Format

y = ftocv(x,eld,prec);

Input

x NK matrix containing numeric data to be converted.

eld scalar, minimum eld width.

prec scalar, the numbers created will have prec places after the decimal point.

Output

y NK matrix containing the decimal character equivalent of the

corresponding elements in x in the format dened by eld and prec.

Remarks

If a number is narrower than eld, it will be padded on the left with zeros.

If prec = 0, the decimal point will be suppressed.

Example

y = seqa(6,1,5);

x = 0 $+ "cat" $+ ftocv(y,2,0);

x =

cat06

cat07

cat08

cat09

cat10

Notice that the ( 0 $+ ) above was necessary to force the type of the result to

MATRIX because the string constant cat would be of type STRING. The left

operand in an expression containing a $+ operator controls the type of the result.

See also

ftos

571

ftos 25. COMMAND REFERENCE

Purpose

Converts a scalar into a string containing the decimal character representation of that

number.

Format

y = ftos(x,fmat,eld,prec);

Input

x scalar, the number to be converted.

fmat string, the format string to control the conversion.

eld scalar or 21 vector, the minimum eld width. If eld is 21, it species

separate eld widths for the real and imaginary parts of x.

prec scalar or 21 vector, the number of places following the decimal point. If

prec is 21, it species separate precisions for the real and imaginary parts

of x.

Output

y string containing the decimal character equivalent of x in the format

specied.

Remarks

The format string corresponds to the format /jnt (justication, notation, trailing

character) slash parameter as follows:

/rdn %*.*lf

/ren %*.*lE

/ron %#*.*lG

/rzn %*.*lG

/ldn %- *.*lf

/len %- *.*lE

/lon %-# *.*lG

/lzn %- *.*lG

If x is complex, you can specify separate formats for the real and imaginary parts by

putting two format specications in the format string. You can also specify separate

elds and precisions. You can position the sign of the imaginary part by placing a +

between the two format specications. If you use two formats, no i is appended to

the imaginary part. This is so you can use an alternate format if you prefer, for

example, prefacing the imaginary part with a j.

The format string can be a maximum of 80 characters.

If you want special characters to be printed after x, include them as the last characters

of the format string. For example:

572

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

F

25. COMMAND REFERENCE ftos

%*.*lf, right-justied decimal followed by a comma.

%-*.*s left-justied string followed by a space.

%*.*lf right-justied decimal followed by nothing.

You can embed the format specication in the middle of other text.

Time: %*.*lf seconds.

If you want the beginning of the eld padded with zeros, then put a 0 before the rst

* in the format string:

%0*.*lf right-justied decimal.

If prec = 0, the decimal point will be suppressed.

Example

You can create custom formats for complex numbers with ftos. For example,

let c = 24.56124+6.3224e-2i;

field = 1;

prec = 3|5;

fmat = "%lf + j%le is a complex number.";

cc = ftos(c,fmat,field,prec);

results in

cc = "24.561 + j6.32240e-02 is a complex number."

Some other things you can do with ftos:

let x = 929.857435324123;

let y = 5.46;

let z = 5;

field = 1;

prec = 0;

fmat = "%*.*lf";

zz = ftos(z,fmat,field,prec);

field = 1;

prec = 10;

fmat = "%*.*lE";

573

ftos 25. COMMAND REFERENCE

xx = ftos(x,fmat,field,prec);

field = 7;

prec = 2;

fmat = "%*.*lf seconds";

s1 = ftos(x,fmat,field,prec);

s2 = ftos(y,fmat,field,prec);

field = 1;

prec = 2;

fmat = "The maximum resistance is %*.*lf ohms.";

om = ftos(x,fmat,field,prec);

The results:

zz = "5"

xx = "9.2985743532E+02"

s1 = " 929.86 seconds"

s2 = " 5.46 seconds"

om = "The maximum resistance is 929.86 ohms."

See also

ftocv, stof, format

574

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE gamma

Purpose

Returns the value of the gamma function.

Format

y = gamma(x);

Input

x NK matrix.

Output

y NK matrix.

Remarks

For each element of x this function returns the integral

0

t

(x1)

e

t

dt

All elements of x must be positive and less than or equal to 169. Values of x greater

than 169 will cause an overow.

The natural log of gamma is often what is required and it can be computed without

the overow problems of gamma. lnfact can be used to compute log gamma.

Example

y = gamma(2.5);

y = 1.32934

See also

cdfchic, cdfbeta, cdc, cdfn, cdfnc, cdftc, erf, erfc

575

gammaii 25. COMMAND REFERENCE

Purpose

Compute the inverse incomplete gamma function.

Format

x = gammaii(a,p);

Input

a MN matrix, exponents.

p KL matrix, EE conformable with a, incomplete gamma values.

Output

x max(M,K) by max(N,L) matrix, abscissae.

Source

cdfchii.src

Globals

ginvinc, macheps

576

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE gausset

Purpose

Resets the global control variables declared in gauss.dec.

Format

gausset;

Source

gauss.src

Globals

altnam, con, , fmtcv, fmtnv, header, miss, output,

row, rowfac, sort, title, tol, vpad, vtype, weight

577

getf 25. COMMAND REFERENCE

Purpose

Loads an ASCII or binary le into a string.

Format

y = getf(lename,mode);

Input

lename string, any valid le name.

mode scalar 1 or 0 which determines if the le is to be loaded in ASCII mode (0)

or binary mode (1).

Output

y string containing the le, up to 65519 bytes long.

Remarks

If the le is loaded in ASCII mode, it will be tested to see if it contains any end of le

characters. These are Z (ASCII 26). The le will be truncated before the rst Z and

there will be no Zs in the string. This is the correct way to load most text les

because the Zs can cause problems when trying to print the string to a printer.

If the le is loaded in binary mode, it will be loaded just like it is with no changes.

Example

Create a le examp.e containing the following program.

library pgraph;

graphset;

x = seqa(0,0.1,100);

y = sin(x);

xy(x,y);

Then execute the following.

y = getf("examp.e",0);

print y;

library pgraph;

graphset;

x = seqa(0,0.1,100);

y = sin(x);

xy(x,y);

See also

load, save, let, con

578

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE getname

Purpose

Returns a column vector containing the names of the variables in a GAUSS data set.

Format

y = getname(dset );

Input

dset string specifying the name of the data set from which the function will

obtain the variable names.

Output

y N1 vector containing the names of all of the variables in the specied

data set.

Remarks

The output, y, will have as many rows as there are variables in the data set.

Example

y = getname("olsdat");

format 8,8;

print $y;

TIME

DIST

TEMP

FRICT

The above example assumes the data set olsdat contained the variables: TIME, DIST,

TEMP, FRICT.

NOTE that the extension is not included in the lename passed to the getname

function.

See also

getnamef, indcv

579

getnamef 25. COMMAND REFERENCE

Purpose

Returns a string array containing the names of the variables in a GAUSS data set.

Format

y = getnamef(f );

Input

f scalar, le handle of an open data set

Output

y N1 string array containing the names of all of the variables in the

specied data set.

Remarks

The output, y, will have as many rows as there are variables in the data set.

Example

open f = olsdat for read;

y = getnamef(f);

t = vartypef(f);

print y;

time

dist

temp

frict

The above example assumes the data set olsdat contained the variables: time, dist,

temp, frict. Note the use of vartypef to determine the types of these variables.

See also

getname, indcv, vartypef

580

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE getnr

Purpose

Compute number of rows to read per iteration for a program that reads data from a

disk le in a loop.

Format

nr = getnr(nsets,ncols);

Input

nsets scalar, estimate of the maximum number of duplicate copies of the data

matrix read by readr to be kept in memory during each iteration of the

loop.

ncols scalar, columns in the data le.

Output

nr scalar, number of rows readr should read per iteration of the read loop.

Remarks

If row is greater than 0, nr will be set to row.

If an insucient memory error is encountered, change rowfac to a number less than

1.0 (e.g., 0.75). The number of rows read will be reduced in size by this factor.

Source

gauss.src

Globals

row, rowfac, maxvec

581

getpath 25. COMMAND REFERENCE

Purpose

Returns an expanded lename including the drive and path.

Format

fname = getpath(pfname);

Input

pfname string, partial lename with only partial or missing path information.

Output

fname string, lename with full drive and path.

Remarks

This function handles relative path references.

Example

y = getpath("temp.e");

print y;

/gauss/temp.e

Source

getpath.src

Globals

None

582

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE gosub

Purpose

Causes a branch to a subroutine.

Format

gosub label ;

.

.

.

label:

.

.

.

return;

Remarks

See Chapter 9 for multi-line recursive user-dened functions.

When a gosub statement is encountered the program will branch to the label and begin

executing from there. When a return statement is encountered, the program will

resume executing at the statement following the gosub statement. Labels are 1-32

characters long and are followed by a colon. The characters can be A-Z or 0-9 and they

must begin with an alphabetic character. Uppercase or lowercase is allowed.

It is possible to pass parameters to subroutines and receive parameters from them when

they return. See the second example below.

The only legal way to enter a subroutine is with a gosub statement.

If your subroutines are at the end of your program, you should have an end statement

before the rst one to prevent the program from running into a subroutine without

using a gosub. This will result in a return without gosub error message.

The variables used in subroutines are not local to the subroutine and can be accessed

from other places in your program. See Chapter 9.

Example

In the program below the name mysub is a label. When the gosub statement is

executed, the program will jump to the label mysub and continue executing from there.

When the return statement is executed, the program will resume executing at the

statement following the gosub.

x = rndn(3,3); z = 0;

583

gosub 25. COMMAND REFERENCE

gosub mysub;

print z;

end;

/* ------ Subroutines Follow ------ */

mysub:

z = inv(x);

return;

Parameters can be passed to subroutines in the following way (line numbers are added

for clarity):

1. gosub mysub(x,y);

2. pop j; /* b will be in j */

3. pop k; /* a will be in k */

4. t = j*k;

5. print t;

6. end;

7.

8. /* ---- Subroutines Follow ----- */

9.

10. mysub:

11. pop b; /* y will be in b */

12. pop a; /* x will be in a */

13.

14. a = inv(b)*b+a;

15. b = ab;

16. return(a,b);

In the above example, when the gosub statement is executed, the following sequence of

events results:

1. x and y are pushed on the stack and the program branches to the label

mysub in line 10.

11. the second argument that was pushed, y, is popped into b.

12. the rst argument that was pushed, x, is popped into a.

14. inv(b)*b+a is assigned to a.

15. a

b is assigned to b.

16. a and b are pushed on the stack and the program branches to the

statement following the gosub, which is line 2.

584

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE gosub

2. the second argument that was pushed, b, is popped into j.

3. the rst argument that was pushed, a, is popped into k.

4. j*k is assigned to t.

5. t is printed.

6. the program is terminated with the end statement.

Matrices are pushed on a last-in/rst-out stack in the gosub() and return() statements.

They must be popped o in the reverse order. No intervening statements are allowed

between the label and the pop or the gosub and the pop. Only one matrix may be

popped per pop statement.

See also

goto, proc, pop, return

585

goto 25. COMMAND REFERENCE

Purpose

Causes a branch to a label.

Format

goto label ;

.

.

.

label:

Remarks

Label names can be any legal GAUSS names up to 32 alphanumeric characters,

beginning with an alphabetic character or an underscore, not a reserved word.

Labels are always followed immediately by a colon.

Labels do not have to be declared before they are used. GAUSS knows they are labels

by the fact that they are followed immediately by a colon.

When GAUSS encounters a goto statement, it jumps to the specied label and

continues execution of the program from there.

Parameters can be passed in a goto statement the same way as they can with a gosub.

Example

x = seqa(.1,.1,5);

n = { 1 2 3 };

goto fip;

print x;

end;

fip:

print n;

1.0000000 2.0000000 3.0000000

See also

gosub, if

586

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE gradp

Purpose

Computes the gradient vector or matrix (Jacobian) of a vector-valued function that has

been dened in a procedure. Single-sided (forward dierence) gradients are computed.

Format

g = gradp(&f ,x0);

Input

&f a pointer to a vector-valued function (f :K1 > N1) dened as a

procedure. It is acceptable for f(x) to have been dened in terms of global

arguments in addition to x, and thus f can return an N1 vector:

proc f(x);

retp( exp(x.*b) );

endp;

x0 K1 vector of points at which to compute gradient.

Output

g NK matrix containing the gradients of f with respect to the variable x at

x0.

Remarks

gradp will return a row for every row that is returned by f . For instance, if f returns a

scalar result, then gradp will return a 1K row vector. This allows the same function

to be used regardless of N, where N is the number of rows in the result returned by f .

Thus, for instance, gradp can be used to compute the Jacobian matrix of a set of

equations.

Example

proc myfunc(x);

retp( x.*2 .* exp( x.*x./3 ) );

endp;

x0 = 2.5|3.0|3.5;

y = gradp(&myfunc,x0);

587

gradp 25. COMMAND REFERENCE

y =

82.98901842 0.00000000 0.00000000

0.00000000 281.19752975 0.00000000

0.00000000 0.00000000 1087.95414117

It is a 33 matrix because we are passing it 3 arguments and myfunc returns 3 results

when we do that; the o-diagonals are zeros because the cross-derivatives of 3

arguments are 0.

Source

gradp.src

Globals

None

See also

hessp

588

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

G

25. COMMAND REFERENCE graph

Purpose

Graphs a set of points, taking the horizontal coordinates of the points from one matrix

and the vertical coordinates from the other.

Format

graph x,y;

Input

x NK matrix of horizontal coordinates.

y LM matrix, vertical coordinates, EE conformable with x.

Remarks

This command matches up the x and y values in the standard element-by-element

fashion and sets the appropriate pixels.

The origin 0,0 is at the lower lefthand corner of the screen.

Note that the screen must be in graphics mode for this command to operate. See

setvmode.

Example

x = seqa(0,1,640);

y = 50~100~150;

call setvmode(17);

graph x,y;

wait;

The program above will draw three horizontal lines across the screen, one at y = 50,

one at y = 100, and one at y = 150.

When GAUSS returns to COMMAND level, the screen will be reset automatically to

text mode because the editor requires the screen in text mode. Your program should

contain a pause to allow viewing the graph or printing with the DOS graphics screen

dump.

See also

setvmode, color, plot

589

hasimag 25. COMMAND REFERENCE

Purpose

Tests whether the imaginary part of a complex matrix is negligible.

Format

y = hasimag(x);

Input

x NK matrix.

Output

y scalar, 1 if the imaginary part of x has any nonzero elements, 0 if it

consists entirely of 0s.

The function iscplx tests whether x is a complex matrix or not, but it does not test the

contents of the imaginary part of x. hasimag tests the contents of the imaginary part

of x to see if it is zero.

hasimag actually tests the imaginary part of x against a tolerance to determine if it is

negligible. The tolerance used is the imaginary tolerance set with the sysstate

command, case 21.

Some functions are not dened for complex matrices. iscplx can be used to determine

whether a matrix has no imaginary part and so can pass through those functions.

hasimag can be used to determine whether a complex matrix has a negligible imaginary

part and could thus be converted to a real matrix to pass through those functions.

iscplx is useful as a preliminary check because for large matrices it is much faster than

hasimag.

Example

x = { 1 2 3i,

4-i 5 6i,

7 8i 9 };

y = hasimag(x);

y = 1.0000000

See also

iscplx

590

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

H

25. COMMAND REFERENCE header

Purpose

Print a header for a report.

Format

header(prcnm,dataset ,ver);

Input

prcnm string, name of procedure that calls header.

dataset string, name of data set.

ver 21 numeric vector, the rst element is the major version number of the

program, the second element is the revision number. Normally this

argument will be the version/revision global ( ?? ver) associated with the

module within which header is called. This argument will be ignored if set

to 0.

Global Input

header string, containing the letters:

t title is to be printed

l lines are to bracket the title

d a date and time is to be printed

v version number of program is printed

f le name being analyzed is printed

title string, title for header.

Source

gauss.src

Globals

header, title

591

hess 25. COMMAND REFERENCE

Purpose

Computes the Hessenberg form of a square matrix.

Format

{ h,z } = hess(x);

Input

x KK matrix.

Output

h KK matrix, Hessenberg form.

z KK matrix, transformation matrix.

Remarks

hess computes the Hessenberg form of a square matrix. The Hessenberg form is an

intermediate step in computing eigenvalues. It also is useful for solving certain matrix

equations that occur in control theory (see Charles F. Van Loan, Using the

Hessenberg Decomposition in Control Theory, in Algorithms and Theory in Filtering

and Control, D.C. Sorenson and R.J. Wets (eds), Mathematical Programming Study

No. 18, North Holland, Amsterdam, pp. 102-111, 1982).

z is an orthogonal matrix that transforms x into h and vice versa. Thus:

h = z

xz

and since z is orthogonal,

x = zhz

This preserves the Frobenious norm of the matrix and the condition numbers of the

eigenvalues.

hess uses the ORTRAN and ORTHES functions from EISPACK.

592

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

H

25. COMMAND REFERENCE hess

Example

let x[3,3] = 1 2 3

4 5 6

7 8 9;

{ h,z } = hess(x);

h =

1.00000000 3.59700730 0.24806947

8.06225775 14.04615385 2.83076923

0.00000000 0.83076923 0.04615385

z =

1.00000000 0.00000000 0.00000000

0.00000000 0.49613894 0.86824314

0.00000000 0.86824314 0.49613894

See also

schur

593

hessp 25. COMMAND REFERENCE

Purpose

Computes the matrix of second partial derivatives (Hessian matrix) of a function

dened as a procedure.

Format

h = hessp(&f ,x0);

Input

&f pointer to a single-valued function f(x), dened as a procedure, taking a

single K1 vector argument (f :K1 > 11); f(x) may be dened in

terms of global arguments in addition to x.

x0 K1 vector specifying the point at which the Hessian of f(x) is to be

computed.

Output

h KK matrix of second derivatives of f with respect to x at x0; this matrix

will be symmetric.

Remarks

This procedure requires K*(K+1)/2 function evaluations. Thus if K is large, it may

take a long time to compute the Hessian matrix.

No more than 3-4 digit accuracy should be expected from this function, though it is

possible for greater accuracy to be achieved with some functions.

It is important that the function be properly scaled, in order to obtain greatest possible

accuracy. Specically, scale it so that the rst derivatives are approximately the same

size. If these derivatives dier by more than a factor of 100 or so, the results can be

meaningless.

Example

x = { 1, 2, 3 };

proc g(b);

retp( exp(xb) );

endp;

b0 = { 3, 2, 1 };

h = hessp(&g,b0);

594

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

H

25. COMMAND REFERENCE hessp

The resulting matrix of second partial derivatives of g(b) evaluated at b=b0 is:

22027.12898372 44054.87238165 66083.36762901

44054.87238165 88111.11102645 132168.66742899

66083.36762901 132168.66742899 198256.04087836

Source

hessp.src

Globals

None

See also

gradp

595

hsec 25. COMMAND REFERENCE

Purpose

Returns the number of hundredths of a second since midnight.

Format

y = hsec;

Remarks

The number of hundredths of a second since midnight can also be accessed as the [4,1]

element of the vector returned by the date function.

Example

x = rndu(100,100);

ts = hsec;

y = x*x;

et = hsec-ts;

In this example, hsec is used to time a 100100 multiplication in GAUSS. A 100100

matrix, x, is created, and the current time, in hundredths of a second since midnight, is

stored in the variable ts. Then the multiplication is carried out. Finally, ts is

subtracted from hsec to give the time dierence which is assigned to et.

See also

date, time, timestr, ethsec, etstr

596

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE if

Purpose

Controls program ow with conditional branching.

Format

if scalar expression;

list of statements;

elseif scalar expression;

list of statements;

elseif scalar expression;

list of statements;

else;

list of statements;

endif;

Remarks

scalar expression is any expression that returns a scalar. It is TRUE if it is not zero,

and FALSE if it is zero.

A list of statements is any set of GAUSS statements.

GAUSS will test the expression after the if statement. If it is TRUE (nonzero), then

the rst list of statements is executed. If it is FALSE (zero), then GAUSS will move to

the expression after the rst elseif statement if there is one and test it. It will keep

testing expressions and will execute the rst list of statements that corresponds to a

TRUE expression. If no expression is TRUE, then the list of statements following the

else statement is executed. After the appropriate list of statements is executed, the

program will go to the statement following the endif and continue on.

if statements can be nested.

One endif is required per if statement. If an else statement is used, there may be only

one per if statement. There may be as many elseifs as are required. There need not be

any elseifs or any else statement within an if statement.

Note the semicolon after the else statement.

597

if 25. COMMAND REFERENCE

Example

if x < 0;

y = -1;

elseif x > 0;

y = 1;

else;

y = 0;

endif;

See also

do

598

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE imag

Purpose

Returns the imaginary part of a matrix.

Format

zi = imag(x);

Input

x NK matrix.

Output

zi NK matrix, the imaginary part of x.

Remarks

If x is real, zi will be an NK matrix of zeros.

Example

x = { 4i 9 3,

2 5-6i 7i };

y = imag(x);

y =

4.0000000 0.0000000 0.0000000

0.0000000 6.0000000 7.0000000

See also

complex, real

599

#include 25. COMMAND REFERENCE

Purpose

Inserts code from another le into a GAUSS program.

Format

#include lename;

#include lename;

Remarks

lename can be any legitimate le name.

This command makes it possible to write a section of general-purpose code, and insert

it into other programs.

The code from the #included le is inserted literally as if it were merged into that

place in the program with a text editor.

If a complete drive and pathname is specied for the le, then no additional searching

will be attempted if the le is not found.

If a complete drive and pathname is not specied and a src path conguration variable

is dened in the GAUSS conguration le, then each path listed in src path will be

searched for the specied lename. Any drive or path on the user-specied lename will

be stripped o prior to being combined with the paths found in src path.

#include /gauss/myprog.prc; No additional search will be made if the le is not

found.

#include myprog.prc; The paths listed in src path will be searched for myprog.prc

if the le is not found.

The src path conguration variable can be dened in the GAUSS conguration le by

editing the le with any text editor.

Compile time errors will return the line number and the name of the le in which they

occur. For execution time errors, if a program is compiled with #lineson, the line

number and name of the le where the error occurred will be printed. For les that

have been #included this reects the actual line number within the #included le.

See #lineson for a more complete discussion of the use of and the validity of line

numbers when debugging.

Example

#include "/gauss/inc/cond.inc";

The command will cause the code in the program cond.inc to be merged into the

current program at the point at which this statement appears.

See also

run, #lineson

600

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE indcv

Purpose

Checks one character vector against another and returns the indices of the elements of

the rst vector in the second vector.

Format

z = indcv(what ,where);

Input

what N1 character vector which contains the elements to be found in vector

where.

where M1 character vector to be searched for matches to the elements of what .

Output

z N1 vector of integers containing the indices of the corresponding element

of what in where.

Remarks

If no matches are found for any of the elements in what , then the corresponding

elements in the returned vector are set to the GAUSS missing value code.

Both arguments will be forced to uppercase before the comparison.

If there are duplicate elements in where, the index of the rst match will be returned.

Example

let what = AGE PAY SEX;

let where = AGE SEX JOB date PAY;

z = indcv(what,where);

what =

AGE

PAY

SEX

where =

AGE

SEX

JOB

date

PAY

z =

1

5

2

601

indexcat 25. COMMAND REFERENCE

Purpose

Returns the indices of the elements of a vector which fall into a specied category

Format

y = indexcat(x,v);

Input

x N1 vector.

v scalar or 21 vector.

If scalar, the function returns the indices of all elements of x equal to v.

If 21, then the function returns the indices of all elements of x that fall

into the range:

v[1] < x v[2].

If v is scalar, it can contain a single missing to specify the missing value as

the category.

Output

y L1 vector, containing the indices of the elements of x which fall into the

category dened by v. It will contain error code 13 if there are no elements

in this category.

Remarks

Use a loop to pull out indices of multiple categories.

Example

let x = 1.0 4.0 3.3 4.2 6.0 5.7 8.1 5.5;

let v = 4 6;

y = indexcat(x,v);

x =

1.0

4.0

3.3

4.2

6.0

5.7

8.1

5.5

v =

4

6

y =

4

5

6

8

602

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE indices

Purpose

Processes a set of variable names or indices and returns a vector of variable names and

a vector of indices.

Format

{ name,indx } = indices(dataset ,vars);

Input

dataset string, the name of the data set.

vars N1 vector, a character vector of names or a numeric vector of column

indices.

If scalar 0, all variables in the data set will be selected.

Output

name N1 character vector, the names associated with vars.

indx N1 numeric vector, the column indices associated with vars.

Remarks

If an error occurs, indices will either return a scalar error code or terminate the

program with an error message, depending on the trap state. If the low order bit of the

trap ag is 0, indices will terminate with an error message. If the low order bit of the

trap ag is 1, indices will return an error code. The value of the trap ag can be tested

with trapchk; the return from indices can be tested with scalerr. You only need to

check one argument; they will both be the same. The following error codes are possible:

1 Cant open dataset.

2 Index of variable out of range, or

undened data set variables.

Source

indices.src

Globals

None

603

indices2 25. COMMAND REFERENCE

Purpose

Processes two sets of variable names or indices from a single le. The rst is a single

variable and the second is a set of variables. The rst must not occur in the second set

and all must be in the le.

Format

{ name1,indx1,name2,indx2 } = indices2(dataset ,var1,var2);

Input

dataset string, the name of the data set.

var1 string or scalar, variable name or index.

This can be either the name of the variable, or the column index of the

variable.

If null or 0, the last variable in the data set will be used.

var2 N1 vector, a character vector of names or a numeric vector of column

indices.

If scalar 0, all variables in the data set except the one associated with var1

will be selected.

Output

name1 scalar character matrix containing the name of the variable associated with

var1.

indx1 scalar, the column index of var1.

name2 N1 character vector, the names associated with var2.

indx2 N1 numeric vector, the column indices of var2.

Remarks

If an error occurs, indices2 will either return a scalar error code or terminate the

program with an error message, depending on the trap state. If the low order bit of the

trap ag is 0, indices2 will terminate with an error message. If the low order bit of the

trap ag is 1, indices2 will return an error code. The value of the trap ag can be

tested with trapchk; the return from indices2 can be tested with scalerr. You only need

to check one argument; they will all be the same. The following error codes are possible:

604

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE indices2

1 Cant open dataset.

2 Index of variable out of range, or

undened data set variables.

3 First variable must be a single name or index.

4 First variable contained in second set.

Source

indices2.src

Globals

None

605

indnv 25. COMMAND REFERENCE

Purpose

Checks one numeric vector against another and returns the indices of the elements of

the rst vector in the second vector.

Format

z = indnv(what ,where);

Input

what N1 numeric vector which contains the values to be found in vector where.

where M1 numeric vector to be searched for matches to the values in what .

Output

z N1 vector of integers, the indices of the corresponding elements of what

in where.

Remarks

If no matches are found for any of the elements in what , then those elements in the

returned vector are set to the GAUSS missing value code.

If there are duplicate elements in where, the index of the rst match will be returned.

Example

let what = 8 7 3;

let where = 2 7 8 4 3;

z = indnv(what,where);

what =

8

7

3

where =

2

7

8

4

3

z =

3

2

5

606

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intgrat2

Purpose

Integrates the following double integral, using user-dened functions f, g

1

and g

2

and

scalars a and b:

b

a

g1(x)

g2(x)

f(x, y)dydx

Format

y = intgrat2(&f ,xl ,gl );

Input

&f scalar, pointer to the procedure containing the function to be integrated.

xl 21 or 2N matrix, the limits of x. These must be scalar limits.

gl 21 or 2N matrix of function pointers, the limits of y.

For xl and gl , the rst row is the upper limit and the second row is the

lower limit. N integrations are computed.

intord scalar, the order of the integration. The larger intord, the more precise

the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16, 20, 24,

32, 40.

Default = 12.

intrec scalar. This variable is used to keep track of the level of recursion of

intgrat2 and may start out with a dierent value if your program

terminated inside of the integration function on a previous run. Always set

intrec explicitly to 0 before any call to intgrat2.

Output

y N1 vector of the estimated integral(s) of f(x, y) evaluated between the

limits given by xl and gl .

Remarks

The user-dened functions specied by f and gl must either

1. Return a scalar constant, OR

2. Return a vector of function values. intgrat2 will pass

to user-dened functions a vector or matrix for x and

y and expect a vector or matrix to be returned. Use .*

and ./ instead of * and /.

607

intgrat2 25. COMMAND REFERENCE

Example

proc f(x,y);

retp(cos(x) + 1).*(sin(y) + 1));

endp;

proc g1(x);

retp(sqrt(1-x^2));

endp;

proc g2(x);

retp(0);

endp;

xl = 1|-1;

gl = &g1|&g2;

_intord = 40;

_intrec = 0;

y = intgrat2(&f,xl,gl);

This will integrate the function f(x, y) = (cos(x) +1)(sin(y) +1) over the upper half of

the unit circle. Note the use of the .* operator instead of just * in the denition of

f(x, y). This allows f to return a vector or matrix of function values.

Source

intgrat.src

Globals

intgrat2, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,

intq4, intq40, intq6, intq8, intrec

See also

intgrat3, intquad1, intquad2, intquad3, intsimp

608

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intgrat3

Purpose

Integrates the following triple integral, using user-dened functions and scalars for

bounds:

b

a

g1(x)

g2(x)

h1(x,y)

h2(x,y)

f(x, y, z)dzdydx

Format

y = intgrat3(&f ,xl ,gl ,hl );

Input

&f scalar, pointer to the procedure containing the function to be integrated.

F is a function of (x, y, z).

xl 21 or 2N matrix, the limits of x. These must be scalar limits.

gl 21 or 2N matrix of function pointers. These procedures are functions of

x.

hl 21 or 2N matrix of function pointers. These procedures are functions of

x and y.

For xl , gl , and hl , the rst row is the upper limit and the second row is the lower limit.

N integrations are computed.

intord scalar, the order of the integration. The larger intord, the more precise

the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16, 20, 24,

32, 40.

Default = 12.

intrec scalar. This variable is used to keep track of the level of recursion of

intgrat3 and may start out with a dierent value if your program

terminated inside of the integration function on a previous run. Always set

intrec explicitly to 0 before any call to intgrat3.

Output

y N1 vector of the estimated integral(s) of f(x, y, z) evaluated between the

limits given by xl , gl and hl .

Remarks

User-dened functions f, and those used in gl and hl must either:

609

intgrat3 25. COMMAND REFERENCE

1. Return a scalar constant, OR

2. Return a vector of function values. intgrat3 will pass

to user-dened functions a vector or matrix for x and

y and expect a vector or matrix to be returned. Use .*

and ./ operators instead of just * or /.

Example

proc f(x,y,z);

retp(2);

endp;

proc g1(x);

retp(sqrt(25-x^2));

endp;

proc g2(x);

retp(-g1(x));

endp;

proc h1(x,y);

retp(sqrt(25 - x^2 - y^2));

endp;

proc h2(x,y);

retp(-h1(x,y));

endp;

xl = 5|-5;

gl = &g1|&g2;

hl = &h1|&h2;

_intrec = 0;

_intord = 40;

y = intgrat3(&f,xl,gl,hl);

This will integrate the function f(x, y, z) = 2 over the sphere of radius 5. The result

will be approximately twice the volume of a sphere of radius 5.

Source

intgrat.src

Globals

intgrat3, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,

intq4, intq40, intq6, intq8, intrec

See also

intgrat2, intquad1, intquad2, intquad3, intsimp

610

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intquad1

Purpose

Integrates a specied function using Gauss-Legendre quadrature. A suite of upper and

lower bounds may be calculated in one procedure call.

Format

y = intquad1(&f ,xl );

Input

&f scalar, pointer to the procedure containing the function to be integrated.

This must be a function of x.

xl 2N matrix, the limits of x.

The rst row is the upper limit and the second row is the lower limit. N

integrations are computed.

intord scalar, the order of the integration. The larger intord, the more precise

the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16, 20, 24,

32, 40.

Default = 12.

Output

y N1 vector of the estimated integral(s) of f(x) evaluated between the

limits given by xl .

Remarks

The user-dened function f must return a vector of function values. intquad1 will pass

to the user-dened function a vector or matrix for x and expect a vector or matrix to

be returned. Use the .* and ./ instead of * and /.

Example

proc f(x);

retp(x.*sin(x));

endp;

xl = 1|0;

y = intquad1(&f,xl);

611

intquad1 25. COMMAND REFERENCE

This will integrate the function f(x) = xsin(x) between 0 and 1. Note the use of the .*

instead of *.

Source

integral.src

Globals

intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32, intq4,

intq40, intq6, intq8

See also

intsimp, intquad2, intquad3, intgrat2, intgrat3

612

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intquad2

Purpose

Integrates a specied function using Gauss-Legendre quadrature. A suite of upper and

lower bounds may be calculated in one procedure call.

Format

y = intquad2(&f ,xl ,yl );

Input

&f scalar, pointer to the procedure containing the function to be integrated.

xl 21 or 2N matrix, the limits of x.

yl 21 or 2N matrix, the limits of y.

For xl and yl , the rst row is the upper limit and the second row is the

lower limit. N integrations are computed.

intord global scalar, the order of the integration. The larger intord, the more

precise the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16,

20, 24, 32, 40.

Default = 12.

intrec global scalar. This variable is used to keep track of the level of recursion of

intquad2 and may start out with a dierent value if your program

terminated inside of the integration function on a previous run. Always set

intrec explicitly to 0 before any calls to intquad2.

Output

y N1 vector of the estimated integral(s) of f(x,y) evaluated between the

limits given by xl and yl .

Remarks

The user-dened function f must return a vector of function values. intquad2 will pass

to user-dened functions a vector or matrix for x and y and expect a vector or matrix

to be returned. Use .* and ./ instead of * and /.

intquad2 will expand scalars to the appropriate size. This means that functions can be

dened to return a scalar constant. If users write their functions incorrectly (using *

instead of .*, for example), intquad2 may not compute the expected integral, but the

integral of a constant function.

To integrate over a region which is bounded by functions, rather than just scalars, use

intgrat2 or intgrat3.

Example

613

intquad2 25. COMMAND REFERENCE

proc f(x,y);

retp(x.*sin(x+y));

endp;

xl = 1|0;

yl = 1|0;

_intrec = 0;

y = intquad2(&f,xl,yl);

This will integrate the function x. sin(x +y) between x = 0 and 1, and between y = 0

and 1.

Source

integral.src

Globals

intquad2, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,

intq4, intq40, intq6, intq8, intrec

See also

intquad1, intquad3, intsimp, intgrat2, intgrat3

614

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intquad3

Purpose

Integrates a specied function using Gauss-Legendre quadrature. A suite of upper and

lower bounds may be calculated in one procedure call.

Format

y = intquad3(&f ,xl ,yl ,zl );

Input

&f scalar, pointer to the procedure containing the function to be integrated. f

is a function of (x, y, z).

xl 21 or 2N matrix, the limits of x.

yl 21 or 2N matrix, the limits of y.

zl 21 or 2N matrix, the limits of z.

For xl , yl , and zl , the rst row is the upper limit and the second row is the

lower limit. N integrations are computed.

intord global scalar, the order of the integration. The larger intord, the more

precise the nal result will be. intord may be set to 2, 3, 4, 6, 8, 12, 16,

20, 24, 32, 40.

Default = 12.

intrec global scalar. This variable is used to keep track of the level of recursion of

intquad3 and may start out with a dierent value if your program

terminated inside of the integration function on a previous run. Always set

intrec explicitly to 0 before any calls to intquad3.

Output

y N1 vector of the estimated integral(s) of f(x,y,z) evaluated between the

limits given by xl , yl and zl .

Remarks

The user-dened function f must return a vector of function values. intquad3 will pass

to the user-dened function a vector or matrix for x, y and z and expect a vector or

matrix to be returned. Use .* and ./ instead of * and /.

intquad3 will expand scalars to the appropriate size. This means that functions can be

dened to return a scalar constant. If users write their functions incorrectly (using *

615

intquad3 25. COMMAND REFERENCE

instead of .*, for example), intquad3 may not compute the expected integral, but the

integral of a constant function.

To integrate over a region which is bounded by functions, rather than just scalars, use

intgrat2 or intgrat3.

Example

proc f(x,y,z);

retp(x.*y.*z);

endp;

xl = 1|0;

yl = 1|0;

zl = { 1 2 3, 0 0 0 };

_intrec = 0;

y = intquad3(&f,xl,yl,zl);

This will integrate the function f(x) = x y z over 3 sets of limits, since zl is dened

to be a 23 matrix.

Source

integral.src

Globals

intquad3, intord, intq12, intq16, intq2, intq20, intq24, intq3, intq32,

intq4, intq40, intq6, intq8, intrec

See also

intquad1, intquad2, intsimp, intgrat2, intgrat3

616

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intrleav

Purpose

Interleaves the rows of two les that have been sorted on a common variable, to give a

single le sorted on that variable.

Format

intrleav(inle1,inle2,outle,keyvar,keytyp);

Input

inle1 string, name of input le 1.

inle2 string, name of input le 2.

outle string, name of output le.

keyvar string, name of key variable, this is the column the les are sorted on.

keytyp scalar, data type of key variable.

1 numeric key, ascending order

2 character key, ascending order

1 numeric key, descending order

2 character key, descending order

Remarks

The two les MUST have exactly the same variables, i.e., the same number of columns

AND the same variable names. They must both already be sorted on the key column.

This procedure will combine them into one large le, sorted by the key variable.

If the inputs are null or 0, the procedure will ask for them.

Example

intrleav("freq.dat","freqdata.dat","intfile","AGE",1);

Source

sortd.src

Globals

None

617

intrsect 25. COMMAND REFERENCE

Purpose

Returns the intersection of two vectors, with duplicates removed.

Format

y = intrsect(v1,v2,ag);

Input

v1 N1 vector.

v2 M1 vector.

ag scalar, if 1, v1 and v2 are numeric, if 0, character.

Output

y L1 vector containing all unique values that are in both v1 and v2, sorted

in ascending order.

Remarks

Place smaller vector rst for fastest operation.

If there are a lot of duplicates within a vector, it is faster to remove them with unique

before calling intrsect.

Source

intrsect.src

Globals

None

Example

let v1 = mary jane linda dawn;

let v2 = mary sally lisa ruth linda;

y = intrsect(v1,v2,0);

618

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE intsimp

Purpose

Integrates a specied function using Simpsons method with end correction. A single

integral is computed in one function call.

Format

y = intsimp(&f ,xl ,tol );

Input

&f pointer to the procedure containing the function to be integrated.

xl 21 vector, the limits of x.

The rst element is the upper limit and the second element is the lower

limit.

tol The tolerance to be used in testing for convergence.

Output

y The estimated integral of f(x) between xl[1] and xl[2] .

Remarks

Example

proc f(x);

retp(sin(x));

endp;

let xl = { 1,

0 };

y = intsimp(&f,xl,1E-8);

This will integrate the function between 0 and 1.

Source

intsimp.src

Globals

None

See also

intquad1, intquad2, intquad3, intgrat2, intgrat3

619

inv, invpd 25. COMMAND REFERENCE

Purpose

inv returns the inverse of an invertible matrix.

invpd returns the inverse of a symmetric, positive denite matrix.

Format

y = inv(x);

y = invpd(x);

Input

x NN matrix.

Output

y NN matrix containing the inverse of x.

Remarks

x can be any legitimate matrix expression that returns a matrix that is legal for the

function.

For inv, x must be square and invertible.

For invpd, x must be symmetric and positive denite.

If the input matrix is not invertible by these functions, they will either terminate the

program with an error message or return an error code which can be tested for with the

scalerr function. This depends on the trap state as follows:

trap 1, return error code

inv invpd

50 20

trap 0, terminate with error message

inv invpd

Matrix singular Matrix not positive denite

If the input to invpd is not symmetric, it is possible that the function will (erroneously)

appear to operate successfully.

Positive denite matrices can be inverted by inv. However, for symmetric, positive

denite matrices (such as moment matrices), invpd is about twice as fast as inv.

Example

620

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE inv, invpd

n = 4000;

x1 = rndn(n,1);

x = ones(n,1)~x1;

btrue = { 1, 0.5 };

y = x*btrue + rndn(n,1);

bols = invpd(xx)*xy;

bols = 1.017201 0.484244

This example simulates some data and computes the ols coecient estimator using the

invpd function. First, the number of observations is specied. Second, a vector x1 of

standard Normal random variables is generated and is concatenated with a vector of 1s

(to create a constant term). The true coecients are specied, and the dependent

variable y is created. Then the ols coecient estimates are computed.

Technical Notes

For complex matrices, inv uses the ZGECO, ZGEDI path in the LINPACK routines.

For real matrices, it uses the croutp function.

The inv function uses the Crout decomposition. The advantage of this routine is that

on some platforms it allows most of the intermediate results to be computed in

extended precision.

The invpd function uses the Cholesky decomposition and is based upon the LINPACK

routines for positive denite matrices. On OS/2 and DOS, if prcsn 80 is in eect, all

intermediate calculations and intermediate results will be in the 80-bit extended

precision of the 80x87 temporary real format. The nal results will be rounded to

64-bit double precision.

The tolerance used to determine singularity is 1.0e14. This can be changed. See

Appendix E.

See also

scalerr, trap, prcsn

621

invswp 25. COMMAND REFERENCE

Purpose

Computes a generalized sweep inverse.

Format

y = invswp(x);

Input

x NN matrix.

Output

y NN matrix, the generalized inverse of x.

Remarks

This will invert any general matrix. That is, even matrices which will not invert using

inv because they are singular will invert using invswp.

x and y will satisfy the four Moore-Penrose conditions:

1. xyx = x

2. yxy = y

3. xy is symmetric

4. yx is symmetric

The tolerance used to determine if a pivot element is zero is taken from the crout

singularity tolerance. The corresponding row and column are zeroed out. See Appendix

E.

Example

let x[3,3] = 1 2 3 4 5 6 7 8 9;

y = invswp(x);

y =

1.6666667 0.66666667 0.0000000

1.3333333 0.33333333 0.0000000

0.0000000 0.0000000 0.0000000

622

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE iscplx

Purpose

Returns whether a matrix is complex or real.

Format

y = iscplx(x);

Input

x NK matrix.

Output

y scalar, 1 if x is complex, 0 if it is real.

Example

x = { 1, 2i, 3 };

y = iscplx(x);

y = 1.0000000

See also

hasimag, iscplxf

623

iscplxf 25. COMMAND REFERENCE

Purpose

Returns whether a data set is complex or real.

Format

y = iscplxf(fh);

Input

fh scalar, le handle of an open le.

Output

y scalar, 1 if the data set is complex, 0 if it is real.

See also

hasimag, iscplx

624

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

I

25. COMMAND REFERENCE ismiss

Purpose

Returns a 1 if its matrix argument contains any missing values, otherwise returns a 0.

Format

y = ismiss(x);

Input

x NK matrix.

Output

y scalar, 1 or 0.

Remarks

y will be a scalar 1 if the matrix x contains any missing values, otherwise it will be a 0.

An element of x is considered to be a missing if and only if it contains a missing value

in the real part. Thus, for x = 1 + .i, ismiss(x) will return a 0.

Example

x = { 1 6 3 4 };

y = ismiss(x);

y = 0.0000000

See also

scalmiss, miss, missrv

625

isSparse 25. COMMAND REFERENCE

Purpose

Tests whether a matrix is a sparse matrix.

Format

r = isSparse(x);

Input

x MN sparse or dense matrix.

Output

r scalar, 1 if x is sparse, 0 otherwise.

Source

sparse.src

626

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

K

25. COMMAND REFERENCE key

Purpose

Returns the ASCII value of the next key available in the keyboard buer.

Format

y = key;

Portability

Unix, OS/2, Windows

key gets input from the active window. If you are working in terminal mode, key

doesnt see any keystrokes until Enter is pressed.

Remarks

The value returned will be zero if no key is available in the buer or it will equal the

ASCII value of the key if one is available. The key is taken from the buer at this time

and the next call to key will return the next key.

Here are the values returned on a PC if the key pressed is not a standard ASCII

character in the range of 1-255.

1015 Shift Tab

1016-1025 Alt Q, W, E, R, T, Y, U, I, O, P

1030-1038 Alt A, S, D, F, G, H, J, K, L

1044-1050 Alt Z, X, C, V, B, N, M

1059-1068 F1-F10

1071 Home

1072 Cursor Up

1073 Pg Up

1075 Cursor Left

1077 Cursor Right

1079 End

1080 Cursor Down

1081 Pg Dn

1082 Ins

1083 Del

1084-1093 Shift F1-F10

1094-1103 Ctrl F1-F10

1104-1113 Alt F1-F10

1114 Ctrl-PrtSc

1115 Ctrl-Cursor Left

1116 Ctrl-Cursor Right

1117 Ctrl-End

1118 Ctrl-PgDn

1119 Ctrl-Home

1120-1131 Alt 1,2,3,4,5,6,7,8,9,0,-,=

1132 Ctrl-PgUp

627

key 25. COMMAND REFERENCE

Example

format /rds 1,0;

kk = 0;

do until kk == 27;

kk = key;

if kk == 0;

continue;

elseif kk == vals(" ");

print "space \\" kk;

elseif kk == vals("\r");

print "carriage return \\" kk;

elseif kk >= vals("0") and kk <= vals("9");

print "digit \\" kk chrs(kk);

elseif vals(upper(chrs(kk))) >= vals("A") and

vals(upper(chrs(kk))) <= vals("Z");

print "alpha \\" kk chrs(kk);

else;

print "\\" kk;

endif;

endo;

This is an example of a loop that processes keyboard input. This loop will continue

until the escape key (ASCII 27) is pressed.

See also

vals, chrs, upper, lower, con, cons

628

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

K

25. COMMAND REFERENCE keyw

Purpose

Waits for and gets a key.

Format

k = keyw;

Output

k scalar, ASCII value of the key pressed.

Portability

Unix, OS/2, Windows

keyw gets the next key from the input buer of the active window.

If you are working in terminal mode, GAUSS will not see any input until you press the

Enter key.

Remarks

keyw gets the next key from the keyboard buer. If the keyboard buer is empty, keyw

waits for a keystroke. For normal keys, keyw returns the ASCII value of the key. See

key for a table of return values for extended and function keys.

See also

key

629

keyword 25. COMMAND REFERENCE

Purpose

Begins the denition of a keyword procedure. Keywords are user-dened functions

with local or global variables.

Format

keyword name(str);

Input

name literal, name of the keyword. This name will be a global symbol.

str string, a name to be used inside the keyword to refer to the argument that

is passed to the keyword when the keyword is called. This will always be

local to the keyword, and cannot be accessed from outside the keyword or

from other keywords or procedures.

Remarks

A keyword denition begins with the keyword statement and ends with the endp

statement. See Chapter 9.

Keywords always have 1 string argument and 0 returns. GAUSS will take everything

past name, excluding leading spaces, and pass it as a string argument to the keyword.

Inside the keyword, the argument is a local string. The user is responsible to

manipulate or parse the string.

An example of a keyword denition is:

keyword add(str);

local tok,sum;

sum = 0;

do until str $== "";

{ tok, str } = token(str);

sum = sum + stof(tok);

endo;

print "Sum is: " sum;

endp;

To use this keyword, type:

add 1 2 3 4 5;

This keyword will respond by printing:

Sum is: 15

See also

proc, local, endp

630

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

L

25. COMMAND REFERENCE lag1

Purpose

Lags a matrix by one time period for time series analysis.

Format

y = lag1(x);

Input

x NK matrix.

Output

y NK matrix, x lagged 1 period.

Remarks

lag1 lags x by one time period, so the rst observations of y are missing.

Source

lag.src

Globals

None

See also

lagn

631

lagn 25. COMMAND REFERENCE

Purpose

Lags a matrix a specied number of time periods for time series analysis.

Format

y = lagn(x,t );

Input

x NK matrix.

t scalar, number of time periods.

Output

y NK matrix, x lagged t periods.

Remarks

If t is positive, lagn lags x back t time periods, so the rst t observations of y are

missing. If t is negative, lagn lags x forward t time periods, so the last t observations

of y are missing.

Source

lag.src

Globals

None

See also

lag1

632

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

L

25. COMMAND REFERENCE let

Purpose

Creates a matrix from a list of numeric or character values. The result is always of type

MATRIX.

Format

let x = constant list;

Example

let x;

x = 0

let x = { 1 2 3, 4 5 6, 7 8 9 };

x =

1 2 3

4 5 6

7 8 9

let x[3,3] = 1 2 3 4 5 6 7 8 9;

x =

1 2 3

4 5 6

7 8 9

let x[3,3] = 1;

x =

1 1 1

1 1 1

1 1 1

let x[3,3];

x =

0 0 0

0 0 0

0 0 0

let x = 1 2 3 4 5 6 7 8 9;

x =

1

2

3

4

5

6

7

8

9

633

let 25. COMMAND REFERENCE

let x = dog cat;

x =

DOG

CAT

let x = "dog" "cat";

x =

dog

cat

Remarks

Expressions and matrix names are not allowed in the let command, expressions such as

this:

let x[2,1] = 3*a b

are illegal. To dene matrices by combining matrices and expressions, use an expression

containing the concatenation operators: and | .

Numbers can be entered in scientic notation. The syntax is dEn, where d is a

number and n is an integer (denoting the power of 10).

let x = 1e+10 1.1e-4 4.019e+2;

Complex numbers can be entered by joining the real and imaginary parts with a sign

(+ or -); there can be no spaces between the numbers and the sign. Numbers with no

real part can be entered by appending an i to the number.

let x = 1.2+23 8.56i 3-2.1i -4.2e+6i 1.2e-4-4.5e+3i;

If curly braces are used, the let is optional. You will need the let for statements that

you want to protect from the beautier using the -l ag on the beautier command line.

let x = { 1 2 3, 4 5 6, 7 8 9 };

x = { 1 2 3, 4 5 6, 7 8 9 };

If indices are given, a matrix of that size will be created:

let x[2,2] = 1 2 3 4;

x =

1 2

3 4

If indices are not given, a column vector will be created:

634

C

o

m

m

a

n

d

R

e

f

e

r

e

n

c

e

L

25. COMMAND REFERENCE let

let x = 1 2 3 4;

x =

1

2

3

4

You can create matrices with no elements, i.e., empty matrices . Just use a set of

empty curly braces.

x = {};

Empty matrices are chiey used as the starting poin