GAUSS 22 brings many substantial new features that will save you hours of time and frustration with everyday tasks like:

• Data exploration
• Data cleaning and management
• Graphics

See some of the ways that GAUSS 22 will help you make the most of your limited research time below!

Intelligent Graph Attributes

• Specify variables to plot by name with convenient formula strings.
• Automatic, intelligent use of variable names and category labels.
• Split data using the new 'by' keyword.
• Never overwrites your settings.

Highlight Important Parts of Your Data

• Specify locations with simple date strings, category labels, numbers, or popular datasets.

• Add spanning bars and lines with one line of code.

Simple Data Filtering with Strings and Dates

• Reference dates, category labels, and variable names.
• Use greater than and less than comparisons with ordinal data.

Easily Generate New Variables

• Create categorical variables from string arrays.
• Automatically convert simple date strings to real date variables.
• Simple new functions and interactive controls to rename and change types.
• Function for combining, splitting, and manipulating strings now support string, categorical and date variables.

Clean Messy Data

• Fix typos and misentries.
• Consolidate categories.
• Identify and remove outliers.
• Identify and remove duplicate observations.

Aggregate by String, Category or Date

• Options for how to handle missing values.

Simple Data Merge

• Load and combine data from CSV, Excel, SAS, Stata, SPSS.

Conclusion

GAUSS 22 has more new features and bug fixes than any previous version. For a complete list of what's new, see the changelog.

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

The new dataframes and interactive data management in GAUSS 21 will make your work more enjoyable and save you hours of time.

New GAUSS dataframes make data easy to read...

...and make code and results clearer

>> // Load data
>> lending = loadd("lending.csv");
>>
>> // Estimate in one line
>> call olsmt(lending, "int_rate ~ .");

                                            Std.           
Variable                     Estimate      Error   t-value 
-----------------------------------------------------------

CONSTANT                       11.988     1.298      9.235 
term: 60_months                 3.987    0.6446      6.184 
annual_inc                 -0.0092475  0.005473     -1.689 
purpose: credit_card         -0.12827     1.320   -0.09714 
         renewable_energy     -1.9637     4.229    -0.4643 
         small_business        3.9262     1.799      2.182 
         vacation             -0.7038     1.809    -0.3890

Customize your date display

Reference your data by name

// Index by variable name
auto = auto[., "mpg" "rep78"];

// Select if position is center
nba = selif(nba, nba[., "Pos"] .$== "C");

// Set base category
yarn = setBaseCat(yarn, "low","yarn_length");

See your data your way with GAUSS dataframes

>> print lending[1:5,.];

        int_rate             date          purpose
       12.620000       2014-12-14      credit_card
       9.4400000       2014-05-18             auto
       10.420000       2014-02-01          medical
       15.050000       2014-04-05      credit_card
       9.9300000       2014-05-17      credit_card 

Easy and fast interactive data management

Interactive data import

View, rename, and reorder categorical variables

Intuitive interactive controls to:

• Set the base case.
• Rename labels.
• Set category order.

Import dates in any format

Non-standard date formats are no problem.

• Auto-detects 30 formats.
• Specify any custom format.
• Any characters.
• Any order.

Interactive data filter

Placing graphs next to each other can be a great way to present information. Today we will learn how to create tiled graphs in GAUSS using plotLayout.

We will work through two simple examples where you will learn:

• How to created tiled layouts which are uniform and layouts with graphs of different sizes.
• Which graph types can be used with plotLayout.
• How to clear your tiled graph layouts.

How to use plotLayout

In GAUSS, plotLayout allows you to arrange multiple graphs in a tiled layout. It takes the following inputs:

g_rows

The number of rows in the graph grid.

g_cols

The number of columns in the graph grid.

idx

The cell in which to place the next graph, walking along the rows.

---

Therefore, the call:

plotLayout(2, 3, idx);

will:

1. Split the graph canvas into a 2x3 grid.
2. Place the next graph in the cell corresponding to the value of idx as shown below.

Which Graph Types Can be Used with plotLayout?

Below is a partial list of the GAUSS graph functions which can be used with plotLayout. Each cell is independent and may contain a different graph type.

Example 1: Uniform Grid Layout

Now that we have seen the basics of plotLayout, let's put together a simple example placing 4 graphs in a 2x2 grid.

new;

// Create the vector 0.1, 0.2, 0.3...3.0
x = seqa(0.1, 0.1, 30);

/*
** First subplot
*/

// Divide the graph canvas into a 2x2 grid
// and place the next graph in the 1st cell
plotLayout(2, 2, 1);

// Create 'y1' and draw graph
y1 = exp(x);
plotXY(x, y1);

/*
** Second subplot
*/
plotLayout(2, 2, 2);

y2 = sin(x);
plotXY(x, y2);

/*
** Third subplot
*/
plotLayout(2, 2, 3);

y3 = cos(x);
plotXY(x, y3);

/*
** Fourth subplot
*/
plotLayout(2, 2, 4);

y4 = ln(x);
plotXY(x, y4);

After running the above code, you should see a graph that looks like this:

Clearing the Plot Layout

What do you think would happen if we created another plot right after running the code from the previous section? Let's try it with the code below.

// Create new 'y' by adding uniform random
// numbers to the 'x' created above
y = x + rndu(30,1);

// Draw graph
plotScatter(x, y);

This time your graph should look like this:

As we can see, GAUSS remembers the grid we created with our last call to plotLayout as well as the chosen cell index. This state will persist until one of the following statements has been executed:

// Subsequent graphs will fill the entire graph canvas.
plotClearLayout();

// 1. Clear all data from the GAUSS workspace.
// 2. Clear the current plot layout state, so that new graphs will fill the entire graph canvas.
new;

Example 2: Mixed Size Grid Layout

Sometimes your graphs will look better with tiles of different sizes. Fortunately, as we saw earlier, plotLayout only computes and stores coordinates.

Therefore, each call to plotLayout is independent of any previous calls. As long as your graph tiles do not overlap, each call to plotLayout may use a different grid size. This allows you to mix graphs of different sizes in the same graph canvas.

Let's modify our previous example, so that the third graph takes up the entire second row.

new;

// Create the vector 0.1, 0.2, 0.3...3.0
x = seqa(0.1, 0.1, 30);

/*
** First subplot
*/

// Divide the graph canvas into a 2x2 grid
// and place the next graph in the 1st cell
plotLayout(2, 2, 1);

// Create 'y1' and draw graph
y1 = exp(x);
plotXY(x, y1);

/*
** Second subplot
*/
plotLayout(2, 2, 2);

y2 = sin(x);
plotXY(x, y2);

/*
** Third subplot
**
**     Change to interpret the graph canvas
**     as a 2x1 grid and place the next graph
**     in the second cell.
*/
plotLayout(2, 1, 2);

y3 = cos(x);
plotXY(x, y3);

In this code example, we changed the inputs to plotLayout instructing it to:

• Split the graph canvas into a grid with 2 rows and 1 column.
• Place the next graph in the second cell.

This results in the graph below with the third plot taking up the entire second row of the graph canvas.

Conclusion

Congratulations, you now have another tool in your graph creating toolbox! You have learned how to:

1. Create tiled graphics in GAUSS.
2. Create uniform and mixed size layouts.
3. Clear the plot layout grid.

Next Steps

• How to Mix, Match and Style Different Graph Types.
• Five Hacks For Creating Custom GAUSS Graphics.
• How to Interactively Create Reusable Graphics Profiles.

Our goal for this post is to learn the fundamentals of creating and using procedures in GAUSS. When you are finished, you should be able to create GAUSS procedures and use those written by others.

What is a GAUSS Procedure?

GAUSS procedures are user-defined functions. They allow you to combine a sequence of commands to perform a desired task.

Why Create GAUSS Procedures?

There are many advantages to creating GAUSS procedures. Even if you don’t consider yourself a programmer, creating GAUSS procedures will make your work easier and more productive.

Save time. Every time you use a previously written GAUSS procedure you,

• Avoid rewriting the same code.
• Avoid debugging new or old mistakes.
• Keep your main code simpler and more readable.

How to Create a GAUSS Procedure Definition

Let’s start with a simple example. We’ll create a simple procedure named power which takes two inputs and returns one output.

proc (1) = power(X, p); // 1. Procedure declaration
    local X_out;        // 2. Local variable list

    X_out = X ^ p;      // 3. Procedure body

    retp(X_out);        // 4. Procedure return
endp;                   // 5. Procedure end

Each line in the above procedure is one of the main parts of a GAUSS procedure. Now let's discuss the details of each of these elements.

1. The Procedure Declaration

a.         c.
↓          ↓
proc (1) = power(X, p);
      ↑          ↑
      b.         d.

The procedure declaration is the first line of all GAUSS procedures. It contains four main sections:

Don't forget the ending semi-colon.

2. The Local Variable List

    local X_out;  

The local variable list is a comma-separated list of variables that will be used inside the procedure. These local variables only exist when the procedure is running.

3. The Procedure Body

    X_out = X ^ p;

The procedure body is where the procedure's computations are performed. In this case, we have just one simple line. However, there is no limit to the size of your procedure.

You can use procedures created by you or others as well as any built-in GAUSS function or operator inside the body of your procedure.

4. The Procedure Return

    retp(X_out);

You can return any of the local variables from the procedure, or none at all. When returning more than one variable, use commas to separate the variable names.

5. The Procedure End

endp;

The endp keyword signals the end of the procedure.

How to Use a GAUSS Procedure

There are two steps required to use a GAUSS procedure:

1. Define the procedure.
2. Call the procedure.

How to Define a GAUSS Procedure

When GAUSS first starts up, it is only aware of its own built-in functions and procedures. Defining a procedure is the process of making GAUSS aware of your procedure. If you try to use a procedure before it is defined, like this:

// Clear all data and procedures from the GAUSS workspace
new;

// Call procedure that has not been defined
power(3, 2);

you will get the error G0025 : Undefined symbol: 'power'.

Here are four ways to define your GAUSS procedure:

1. Add the procedure to your main code file.
2. Run the GAUSS procedure.
3. Place the procedure in a .g file.
4. Add your procedure to a GAUSS library.

1. Add the procedure to your main code file. The simplest method to define a procedure is to simply add it to your code and run the main file. This allows for a natural process of learning-by-doing.

As we can see from the above image, the procedure can be included anywhere in your program file. It is often convenient to place procedures after the main code.

GAUSS can allow this because it does not just run your code line-by-line. It is smarter than that. When GAUSS runs your program, its first step is to compile your code. This allows GAUSS to find many mistakes immediately and also speed-up your code in addition to locating your procedures.

2. Run the GAUSS procedure. Since GAUSS does not run your code line-by-line, as we saw in the previous section, GAUSS needs to have the entire procedure definition at once. Therefore, you cannot run a procedure one line at a time. If you try to run the first line alone:

proc (1) = power(X, p);

you will get the error G0278 : PROC without ENDP 'power'.

After you run the entire procedure:

the procedure is defined so that you can use it in GAUSS. Now running:

x = power(3, 2);
print x;

will be successful, returning:

9

3. Place your procedure in a .g file. It is not always convenient to keep all procedures in your main code file.

A simple alternative is to:

    i. Create a file with the same name as your procedure plus a .g file extension. Such as power.g.
    ii. Place your procedure in this file.
    iii. Save this file in a location where GAUSS can find it.

4. Add your procedure to a GAUSS library. Adding your related procedures to a GAUSS library is considered a best practice. GAUSS libraries make it easier to use and share code without worrying about paths.

Full GAUSS library management is beyond the scope of this article. However, the above image shows the Create Library and Add Files controls.

How to Call a GAUSS Procedure

Now that we've learned how to create and define GAUSS procedures, it's time to use them. Here are a few example procedures to fill in anything you might be unsure about.

We'll start with a procedure with two returns.

// Create 4x1 vector
y = { 1, 3, 2, 1 };

// Call procedure
{ a, b } = range(y);

// Print results
print "The smallest value is: " a;
print "The largest value is : " b;

// Procedure that returns two items
proc (2) = range(X);
    local min, max;

    min = minc(X);
    max = maxc(X);

    retp(min, max);
endp;

Running the above code will return:

The smallest value is:        1
The largest value is :        3

Next, we'll consider a case with two inputs.

// Create 5x1 vector
z = { 1, 2, 3, 4, 9 };

m1 = average(z, "median");
print m1;

m2 = average(z, "mean");
print m2;

proc (1) = average(y, type_);
    local avg;

    if type_ $== "mean";
        avg = meanc(y);
    elseif type_ $== "median";
        avg = median(y);
    else;
        print "Second input, type_, not recognized";
        end;
    endif;

    retp(avg);
endp;

which will return:

3.0
3.8

Conclusion

Great job! You've made it through the fundamentals of GAUSS procedures. You've learned:

1. The parts that make up a GAUSS procedure.
2. How to define GAUSS procedures.
3. How to call GAUSS procedures.