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.

Most GAUSS users keep their code and data from different projects in separate directories. This is a good practice since it helps keep your work organized.

However, since it is your code and your computer, it can seem like the path of least resistance is to add full path references to any data that you read or write. Below is a toy example that illustrates the issue.

// Load data
y = loadd("C:\\Users\\YourUserName\\Projects\\GAUSS\\data\\mydata.csv");
oil_vars = xlsReadM("C:\\Users\\YourUserName\\Projects\\GAUSS\\data\\oil.xlsx", "A2:A220");

// Estimate least squares parameters
parameters = invpd(oil_vars'oil_vars)*(oil_vars'y);

// Write estimated parameters to output file
call xlsWriteM(parameters, "C:\\Users\\YourUserName\\Projects\\GAUSS\\data\\oil_parms.xlsx", "A2");

Assuming the paths are correct, this will work fine for you–at least when you first write it. However, if you want to share the code with others, run it on multiple computers or upgrade your computer, the paths will have to be changed.

For a simple program like the one above, you can probably get the change made in under a minute. But most programs are longer and more complicated than this and it is common to have path references throughout the code.

Step 1: Make variables to hold your paths

The first thing we can do to simplify this code is to make one variable at the top of the program which contains the path.

// Create variable to hold the path
path = "C:\\Users\\YourUserName\\Projects\\GAUSS\\data\\";

// Load data
y = loadd(path $+ "mydata.csv");
oil_vars = xlsReadM(path $+ "oil.xlsx", "A2:A220");

// Estimate least squares parameters
parameters = invpd(oil_vars'oil_vars)*(oil_vars'y);

// Write estimated parameters to output file
call xlsWriteM(parameters, path $+ "oil_parms.xlsx", "A2");

This is a great step because we now only have to change the path in one place. No more digging through hundreds or thousands of lines of code!

Step 2: Use __FILE_DIR to find the path for you

While only having to modify your paths in one location does not sound too bad, do you really want to have to make that change, or would you rather have it just work?

Furthermore, it can be a significant problem if multiple people are working with the code, or if you are using version control. Wouldn't it be nice if we could just ask GAUSS to figure out the path for us? Fortunately, __FILE_DIR (first available in version 18) does exactly this.

What does __FILE_DIR tell GAUSS to do?

Whenever GAUSS sees __FILE_DIR in a program, it replaces it with the full path to the location of the file which contains the __FILE_DIR statement. So if we add the following command to the top of the file C:\gauss22\examples\ols.e:

// Print the full path to the location of this file
print __FILE_DIR;

when we run it, in addition to the OLS estimates that the example prints out, we will see:

C:\gauss22\examples\

If you placed that same statement in the file /Users/david/programs/myprogram.gss, then it would print out:

/Users/david/programs/

Replace the first path with __FILE_DIR

Now that we have a tool to return the path of our program file, we need to decide how we want the project set up. If we just want to keep everything for the project in one folder, we can do this:

// Create variable to hold the path
path = __FILE_DIR;

// Load data
y = loadd(path $+ "mydata.csv");
oil_vars = xlsReadM(path $+ "oil.xlsx", "A2:A220");

// Estimate least squares parameters
parameters = invpd(oil_vars'oil_vars)*(oil_vars'y);

// Write estimated parameters to output file
call xlsWriteM(parameters, path $+ "oil_parms.xlsx", "A2");

For a very simple project this is probably fine and as long as the code and the data are in the same folder, the code will just run on any computer without modification. But we may wish to separate the code and the data into separate folders. For example, let's say we want our project to be laid out like this:

• ols_oil - base path for project.
• ols_oil/data - folder to hold input data files.
• ols_oil/main - folder to hold our main program.
• ols_oil/results - folder to hold the output written by the main program.

Since the data folder and the results folder are at the same level (or depth) as the 'main' folder which contains our main program, we will have to use .. to go back to ols_oil from ols_oil/main.

// Get full path to ols_oil/main
main_path = __FILE_DIR;

// Get full path to ols_oil/data
data_path = main_path $+ "..\\data\\";

// Get full path to ols_oil/results
rslt_path = main_path $+ "..\\results\\";

// Load data
y = loadd(data_path $+ "mydata.csv");
oil_vars = xlsReadM(data_path $+ "oil.xlsx", "A2:A220");

// Estimate least squares parameters
parameters = invpd(oil_vars'oil_vars)*(oil_vars'y);

// Write estimated parameters to output file
call xlsWriteM(parameters, rslt_path $+ "oil_parms.xlsx", "A2");

Now as long as the data, results and main sub-folders are all in the same location, this code will run on any computer, regardless of where they place the ols_oil folder or what their GAUSS working directory is set to.

Conclusion

You have just learned how to:

• Create variables to hold paths.
• Use __FILE_DIR for the base path.

can make your code more portable and easier to share with others.

Further Reading

1. The Current Working Directory: What you need to know
2. GAUSS Basics 2: Running a program
3. Understanding Errors | G0025 : Undefined symbol
4. Understanding Errors: G0064 Operand Missing
5. Understanding Errors: G0058 Index out-of-Range

The key to getting the most performance from a matrix language is to vectorize your code as much as possible. Vectorized code performs operations on large sections of matrices and vectors in a single operation, rather than looping over the elements one-by-one.

For example, we could scale a vector by looping over each element:

// Create a random normal vector
// with 10 elements
x = rndn(10,1);

// NOT Vectorized
// Loop through each element
// in 'x' and multiply by 3
for i(1, rows(x), 1);
    x[i] = x[i] * 3;
endfor;

or we could perform all of the multiplications in a single call:

// Vectorized
// Scale each element of 'x'
// with a single operation
x = x * 3;

Not only is the second version much shorter, but it is also approximately 10 times faster.

Challenges to vectorizing time series code

Our initial example cut the lines of code by one third and ran 10 times more quickly. Clearly, this technique is valuable, but not all cases are as simple. Let's start by looking at the standard AR(1) model for time series data:

$$y_t = C + \rho y_{t-1} + \epsilon_t$$

Let's start by writing a non-vectorized version of this equation:

// Number of observations to simulate
nobs = 5;

// Constant initial value
C = 1;

// AR parameter
rho = 0.3;

// Set random seed for repeatable random numbers
rndseed 5423;

// Pre-allocate vector for the output 'y'
y = C | zeros(nobs, 1);

// Create error term
epsilon = rndn(rows(y), 1);

// Simulate the AR(1) process
for t(2, nobs + 1, 1);
    y[t] = y[t-1] * rho + epsilon[t];
endfor;

Loop-carried dependencies

The problem which prevents us from vectorizing the AR(1) simulation (or parallelizing it) is that each iteration of the loop depends upon the result from the previous iteration. This is the definition of a loop-carried dependence.

Vectorizing an AR process with recserar

Fortunately, GAUSS has a built-in function for exactly this type of problem, recserar. In terms of an AR(1) model, recserar has the following inputs:

epsilon

A Tx1 matrix, the error term.

C

A scalar, the initial value of the time series.

rho

A scalar, the AR parameter.

Using recserar the code would look like this:

// Number of observations to simulate
nobs = 5;

// Constant initial value
C = 1;

// AR parameter
rho = 0.3;

// Set random seed for repeatable random numbers
rndseed 5423;

// Create error term
epsilon = rndn(nobs+1, 1);

// Simulate the AR(1) process
y_vec = recserar(epsilon, C, rho);

Results

The speed-up that you see from this change is mainly a function of the length of the number of elements in the vector. In the testing for this post, the recserar version ran up to around 20 times faster as shown in the graph above.

Conclusion

In this post we saw how the GAUSS recserar function can be used to vectorize code with loop-carried dependencies like the simulation of an AR(1) model, giving speed-ups of up to 20 times.

This pattern comes up often in other time series models such as GARCH. However, it is not exclusive to time series, so keep it in mind whenever you find a loop that is difficult to vectorize.

Code and data from this blog can be found here.