Today's blog will:

1. Explain the cause of the index out-of-range error in GAUSS.
2. Explain why performing index assignments past the end of your data can lead to bad outcomes.
3. Show how to use some functions and operators that can assist with diagnosing and resolving this error.
4. Work through an example to resolve an indexing problem.

What Causes the Index-out-of-Range Error?

The index out-of-range error occurs any time that you try to select an element of a dataframe, matrix, or string array that does not exist. Let's look at a basic example:

Index out-of-range on read

// Create a 2x1 vector
a = { 5, 9 };

// Attempt to access the third element and assign it to 'b'
b = a[3];

In the above example, the error is clear. Since a does not have a third element, trying to access it is clearly an error.

Index out-of-range on write

// Create a 2x1 vector
a = { 5, 9 };

// Attempt to assign to the third element of 'a'
a[3] = 12;

Since this code is attempting to write past the end of the vector a, it will also cause an index out-of-range error. This behavior is standard among most programming environments. However, it can sometimes confuse new GAUSS users who are coming from statistical software that has historically been designed more for prototyping.

At first, it might seem convenient for the extra elements to be automatically added past the end of your data. However, there are two reasons why it is not such a good idea:

1. It allows errors to go undetected. Writing past the end of data is very easy to do by accident and one of the most common errors to make when programming--even for trained professional programmers. Letting the error go undetected at the source can cause a much harder-to-detect error to happen later on in the program. In other cases, it can even lead to wrong answers.
2. It will slow down your code. Starting out with a vector, matrix, or dataframe of the correct size and filling it in can be 10 or more times faster than adding new elements an observation at a time.

Functions and Operators to Investigate and Resolve an Index out-of-range Error

Here are a few functions and operators that should be helpful when diagnosing and resolving an index out-of-range error.

Basic Usage Examples

a = { 7 2,
      4 1 };

b = { 5 8,
      3 9 };

c = { 6 6 };

print "rows(a) = " rows(a);
print "cols(a) = " cols(a);
print "----";
print "getorders(a) = " getorders(a);

will return:

rows(a) =        2.0000000
cols(a) =        2.0000000
----
getorders(a) =
       2.0000000
       2.0000000 

Continuing with the previous code:

// Use horizontal concatenation to add columns
d = a ~ b;

// User vertical concatenation to add rows
e = c | b;

After the above code:

d = 7 2 5 8
    4 1 3 9

e = 6 6
    5 8
    3 9

Solve an Example Index Error

Let's work through a simplified real-world example of an out-of-range error. Our code takes some bootstrap samples from a dataset and then computes and stores the means and standard deviations of these samples. Here is the initial code:

burn_in = 5;
ndraws = 10;

// Data to sample from
data = rndn(10, 1);

// Pre-allocate vector to hold results
stats = zeros(ndraws, 1);

for i(1, ndraws + burn_in, 1);
    // Take a bootstrap sample
    s = sampleData(data, rows(data), 1);

    // Assign the mean of the sample
    // to the 1st column of the i'th row of stats
    stats[i,1] = meanc(s);

    // Assign the standard deviation of the sample
    // to the 2nd column of the i'th row of stats
    stats[i,2] = stdsc(s);

endfor;

After running the above code, GAUSS reports the index out-of-range error from the line stats[i,2] = stdsc(s);.

Let's start diagnosing this problem by printing out the size of stats before the loop and the value of i on each iteration, like this:

burn_in = 5;
ndraws = 10;

// Data to sample from
data = rndn(10, 1);

// Pre-allocate vector to hold results
stats = zeros(ndraws, 1);

print "rows(stats) = " rows(stats);
print "cols(stats) = " cols(stats);

for i(1, ndraws + burn_in, 1);

    print "i = " i;

    // Take a bootstrap sample
    s = sampleData(data, rows(data), 1);

    // Assign the mean of the sample
    // to the 1st column of the i'th row of stats
    stats[i,1] = meanc(s);

    // Assign the standard deviation of the sample
    // to the 2nd column of the i'th row of stats
    stats[i,2] = stdsc(s);

endfor;

After running this version, we see the following printed output:

rows(stats) =        10.000000
cols(stats) =        1.0000000
i =        1.0000000 

This tells us that the error happened on the first iteration of the loop, since i is never greater than one. We also see that stats only has one column. The line causing our error is trying to write to the second column of stats. So we need to add a second column to stats when we pre-initialize it.

After we fix that problem, our code looks like this:

burn_in = 5;
ndraws = 10;

// Data to sample from
data = rndn(10, 1);

// Pre-allocate vector to hold results
stats = zeros(ndraws, 2);

print "rows(stats) = " rows(stats);
print "cols(stats) = " cols(stats);

for i(1, ndraws + burn_in, 1);

    print "i = " i;

    // Take a bootstrap sample
    s = sampleData(data, rows(data), 1);

    // Assign the mean of the sample
    // to the 1st column of the i'th row of stats
    stats[i,1] = meanc(s);

    // Assign the standard deviation of the sample
    // to the 2nd column of the i'th row of stats
    stats[i,2] = stdsc(s);

endfor;

Unfortunately, GAUSS is still reporting an index out-of-range error. This time it is on an earlier line, stats[i,1] = meanc(s);. However, when we look at our printed output:

rows(stats) =        10.000000
cols(stats) =        2.0000000
i =        1.0000000
i =        2.0000000
i =        3.0000000
i =        4.0000000
i =        5.0000000
i =        6.0000000
i =        7.0000000
i =        8.0000000
i =        9.0000000
i =        10.000000
i =        11.000000 

we see that the code has gotten through several iterations. We can also see that the error occurs when the code tries to write to the 11th row of stats, but stats only has 10 rows. We need to find out why the number of iterations in the loop and the number of rows in stats don't agree.

Looking back over the code, we can see that stats has ndraws rows, but the loop has ndraws + burn_in iterations. There are many ways we could resolve this, but since our main focus is on identifying the cause of the problem, we will just change the size of stats to have enough rows to hold all iterations.

Below is our final code:

burn_in = 5;
ndraws = 10;

// Data to sample from
data = rndn(10, 1);

// Pre-allocate vector to hold results
stats = zeros(ndraws + burn_in, 2);

print "rows(stats) = " rows(stats);
print "cols(stats) = " cols(stats);

for i(1, ndraws + burn_in, 1);

    print "i = " i;

    // Take a bootstrap sample
    s = sampleData(data, rows(data), 1);

    // Assign the mean of the sample
    // to the 1st column of the i'th row of stats
    stats[i,1] = meanc(s);

    // Assign the standard deviation of the sample
    // to the 2nd column of the i'th row of stats
    stats[i,2] = stdsc(s);

endfor;

Fortunately, this time the code runs without error and the printout shows us that all iterations have been performed--problem solved! We can now remove the print statements and keep going.

Conclusion

Congratulations! You have learned:

1. The cause of the index out-of-range error in GAUSS.
2. Why performing index assignments past the end of your data can lead to bad outcomes.
3. How to use some functions and operators that can assist with finding the size of your data and adding rows and columns.

and worked through a simple, but realistic example.

Further Reading

1. Understanding Errors | G0025 : Undefined symbol
2. Understanding Errors: G0064 Operand Missing

Today we will help you to understand and resolve Error G0064: Operand Missing. We will answer the questions:

• What is an operand?
• How do common mathematical and non-mathematical operators interact with operands?
• What are common causes of operand missing errors?

What is an operand?

An operand is a symbol that an operator operates on. For example, in the line below:

X = 4 + 5;

The plus sign is the operator and both 4 and 5 are operands.

Mathematical and Logical Operators

When you think of operators, the mathematical and logical operators tend to come to mind first. For example, operators like those shown in the table below.

Operand Missing Errors with Mathematical and Logical Operators

Missing operand errors that occur with mathematical operators tend to be simple to understand and fix, so we will only show one example.

Example 1

// Multiply 6 by 5 
// and print  
// the result
6.*5;

// The left-hand 
// operand is 
// missing
.*5;

Non-mathematical Operators

Unlike the logical and mathematical operators, many of the “other” operators are not commonly noticed or considered.

Comma Operator Examples

Comma Operator Example One

// Create a 4x2 matrix with 
// random normally 
// distributed numbers
X = rndn(4,2);

// No operands on either 
// side of the comma 
// operator
X = rndn(,);

Comma Operator Example Two

// Assign the element from  
// the 6th row and first 
// column to Z
Z = X[6,1];

// The operand to the right 
// of the comma operator 
// is missing
Z = X[6, ];

Colon Operator Example

Operand missing statements with the colon operator will look like the previous comma operator errors.

// Assign the 3rd to 5th 
// elements from the vector
// y to u
u = y[3:5];

// The operand to the
// right of the colon 
// operator is missing
u = y[3: ];

Print Statements and the Space Operator

The usage of space operator is probably the most likely “operand missing” error to trip up new GAUSS users.

The print statement takes a space-separated list of items to print. For example:

print 4 5 6;

will return:

4.0000    5.0000    6.0000

Similarly, we can print the same data with variables like this:

A = 4;
B = 5;

print A B 6;

And GAUSS will again return:

4.0000    5.0000    6.0000

So far this is quite simple and something you may have done without a thought. However, adding an operator can cause a problem. For example, because the print statement uses the space operator to separate the items to print, the statement:

print A + B;

is interpreted by GAUSS as the following instructions:

Print the value of A.
Print the value of +.
Print the value of B.

Therefore, when GAUSS gets to the + sign, it does not see enough operands, because it has already been told to print A.

You can resolve this by removing the space operator between A, + and B, or by adding parentheses around the statement.

A = 4;
B = 5;

// Option 1: Add parentheses 
// around the sum of A and B
print (A + B);

// Option 2: Remove space operator 
// to print the sum of A and B
print A+B;

The parentheses (or dropped spaces) only need to be around the operator. The table below shows a few variations and the resulting printed output.

print (4 + 5) 6;

print (4 + 5)*6;

print  ((4 + 5) / 6);

print 4 5*6;

Conclusion

Congratulations! In today's blog, you have learned:

• What mathematical, logical, and non-mathematical operands are in GAUSS.
• Common causes of the G0064: Operand Missing error.

Further reading

1. Understanding Errors | G0025 : Undefined symbol
2. Understanding Errors: G0058 Index out-of-Range
3. GAUSS Basics 6: Logical and relational operators

Today we will help you to understand and resolve Error G0025: Undefined symbol. We will answer the questions:

• What is a GAUSS symbol?
• What are the most common types of GAUSS symbols?
• How do I define a GAUSS symbol?
• How do I resolve the error G0025: Undefined symbol?

What is a symbol?

In GAUSS a symbol is a label used to represent some data, a procedure or function. For example, in the code below:

a = 3;
b = 4;

a and b are symbols representing the scalar values 3 and 4 respectively.

c = a + b;

d = 3 + 4;

The above code creates two new symbols, c and d.

• c is created by applying the addition operator to the previously created symbols, a and b.
• d is created by adding two literal values.

Numbers, such as the integers 3 and 4 are called literals, rather than symbols.

How to define a symbol

Numeric and string symbols are defined in GAUSS using the equals sign as we saw previously. Here are some more examples:

// Define the symbol 'e' to be a 3x1 vector
e = { 2.1, 0.9, 3.8 };

// Define the symbol 'f' to be the
// largest element of the vector 'e'
f = maxc(e);

// Define the symbol 'g' to be a 10x2 random normal matrix
g = rndn(10,2);

// Define the symbol 'h' to be a string
h = "String symbols contain text";

Procedure (proc) and function (fn) names are also symbols. Below are some simple examples of procedure definitions:

/*
** The procedure and function definitions below define the symbols
** 'doubleIt' and 'squareIt'.
*/

proc (1) = doubleIt(X);
    retp(X .* 2);
endp;

fn squareIt(X) = X .^ 2;

Basic undefined symbol examples

Any time a symbol is referenced on the right side of an equation before it has been defined can cause Error G00025: Undefined symbol. Here are a few simple examples:

// Clear out all symbols in the GAUSS workspace
new;

// Since 'a' has not been defined,
// this line will cause an error
b = a;

// Clear out all symbols in the GAUSS workspace
new;

b = 3;

// Since 'a' has not been defined,
// this line will cause an error
c = a + b;

// Clear out all symbols in the GAUSS workspace
new;

a = { 2, 4, 6 };

// Since the procedure 'foo' has not been defined,
// this line will cause an error
X = foo(a);

Solve a simple undefined symbols error

If we run a file named estimate.gss with the following contents:

// Clear all symbols from the GAUSS workspace
new;

/*
** Simulate random normal variables
*/
X = rndn(nobs, nvars);

/*
** Simulate a random normal response variable
*/
y = rndn(nobs, 1);

/*
** Estimate a linear model
*/
call glm(y, X, "normal");

we will get the following error messages:

G0025 : Undefined symbol: 'nobs'  [estimate.gss, line 6]
G0025 : Undefined symbol: 'nvars' [estimate.gss, line 6]

These error messages tell us that line 6 of our code is using two symbols that have not yet been defined, nobs and nvars. To resolve these errors, we need to set those symbols to appropriate values.

The inputs to the rndn function need to be scalar values that represent the number of rows and columns of the output matrix. We set them to 100 and 4 respectively in the code below to resolve the errors.

// Clear all symbols from the GAUSS workspace
new;

// Specify the number of observations to simulate
nobs = 100;

// Specify the number of columns to simulate
nvars = 4;

/*
** Simulate random normal variables
*/
X = rndn(nobs, nvars);

/*
** Simulate a random normal response variable
*/
y = rndn(nobs, 1);

/*
** Estimate a linear model
*/
call glm(y, X, "normal");

After these changes the code will run successfully.

What causes undefined proc or function symbols?

Now let's move to a less obvious example. Let's suppose we have a file arimafit-example.gss with these contents:

// Clear all symbols from GAUSS workspace
new;

// Create file name with full path
fname = getGAUSSHome() $+ "pkgs/tsmt/examples/enders_sim2.dat";

p = 3;
d = 1;
q = 1;

// Run arima estimation
call arimaFit(fname, "ar2", p, d, q);

When we run this file, we get the error:

G0025 : Undefined symbol: 'arimaFit' [arimafit-example.gss, line 12]

In this example, we can tell that arimaFit is a GAUSS procedure or function. There are four main reasons why a procedure or function might be undefined in your GAUSS code:

1. It was added in a newer version of GAUSS than you have.

You can search the GAUSS Change Log for the procedure or function to see if it has been added in a newer version.

2. It is in a library that you do not have loaded.

arimaFit from our above code snippet is from the GAUSS Time Series MT add-on package. If this is the case, you will need to make sure that the package is installed and loaded correctly.

Undefined references to the procedures maxset, optset, maxlik and optmum are sometimes found undefined in publicly available third-party code.

3. It is in a code file that GAUSS has not been told about.

Our Basics of GAUSS Procedures blog explains the four ways to tell GAUSS about your user-defined procedure.

4. Running the code line-by-line

When you run a file all at once, GAUSS allows you to place procedures wherever you like, such as the end of the file.

new;

a = 3;

b = doubleIt(a);

proc (1) = doubleIt(x);
    retp(2 * x);
endp;

However, if you run a program file like the one above, line-by-line, you will get an undefined symbol error. If you run the entire file at once, GAUSS will search the file for any procedures that it does not know about. However, when you run the code line-by-line, GAUSS only runs the code you tell it to run.

You can resolve this problem, by either:

1. Running the code under the debugger.
2. Adding the procedures to a GAUSS library or a .g file.
3. Highlighting all lines of the needed procedures and running them first.

Conclusion

Congratulations! In today's blog, you have learned that:

• GAUSS symbols are labels, or names, that represent data, procedures and functions.
• Use of a symbol on the right side of an equation before it is defined, or assigned a value, can cause an undefined symbol error.
• Symbols are commonly defined by using the equals operator as well as loading libraries.

Further Reading

1. Understanding Errors: G0064 Operand Missing
2. Understanding Errors: G0058 Index out-of-Range
3. Make your code portable: Data paths
4. The Current Working Directory: What you need to know

If you have run much publicly available GAUSS code, you have probably come across the #include command. Since it is used so much, it will be helpful to answer these questions:

1. What does #include do?
2. What is the most common error when using #include?
3. How can I resolve the most common error?

What does #include do?

The #include command is almost exactly like an instruction telling GAUSS to copy-and-paste the contents of one file into another. It is often used so that a file containing procedures and/or control variables can be kept separate from the main code file.

Example without #include

For example, let's imagine we have a file named hypotenuse.gss with the following contents:

a = 3;
b = 4;

c = hypotenuse(a, b);

proc (1) = hypotenuse(a,b);
    retp(sqrt(a.^2 + b.^2));
endp;

We can run this file and it will assign c to be equal to 5 as we expect.

Example with #include

If we will only ever want to use the hypotenuse procedure in this one file, then it is probably fine to leave it as it is. However, if this procedure will be reused a lot, it might be better to just have one copy of the procedure, instead of copy-and-pasting the procedure every time we need to use it.

To do this, we would break our hypotenuse.gss file up into two files, main.gss and hypotenuse.src. The contents of main.gss will be:

a = 3;
b = 4;

c = hypotenuse(a,b);

// Make hypotenuse procedure available
#include hypotenuse.src

and the contents of hypotenuse.src will be:

proc (1) = hypotenuse(a,b);
    retp(sqrt(a.^2 + b.^2));
endp;

As long as GAUSS can find the hypotenuse.src file, these versions will behave identically.

The most common #include error

By far the most common error occurs when GAUSS cannot find the #include'd file. If GAUSS could not find our hypotenuse.src file, we would get an error like this:

G0014 : File not found 'C:\gauss\examples\hypotenuse.src'

Where does GAUSS look for the #include file?

When shown an error message stating that the file cannot be found in a directory such as C:\gauss\examples\, people often wonder why GAUSS looked for the file in their GAUSS examples directory. GAUSS did search in the directory found in the error message. However, that is the last place that GAUSS looked.

The GAUSS #include command will search the following locations, in this order:

1. Your current working directory.
2. The files in your SRC_PATH.

How can I resolve the problem?

If GAUSS cannot find a #include'd file you can fix the problem by either:

1. Changing your GAUSS working directory to the folder in which the file is located.
2. Moving the file to one of the GAUSS SRC_PATH locations.
3. Adding a full path to the #include statement.

The second most common #include error

The second most common error with #include occurs when either:

1. Entering the #include command in the Program Input/Output window.
2. Running a #include statement by right-clicking and selecting Run Selected Text, or Run Current Line.

Either of these will return an error like this:

G0008: Syntax error '#include hypotenuse.src'

This is because #include statements must be run as part of a program file.

How can I resolve the problem?

If you would like to execute the command #include <filename> in the GAUSS Program Input/Output window, simply replace #include with run.

// Use the 'run' statement at the GAUSS command line
run hypotenuse.src

The run command will execute the code in the file exactly as if the #include statement was run as part of a program file.

Conclusions

Today we have learned:

1. What the #include command does in GAUSS.
2. Why it is used.
3. The two most common errors associated with its usage.
4. Methods to resolve common errors.

Code and data from this blog can be found here.