G-Octave Manual: Functions

G-Octave currently includes a number of functions not distributed with Octave (although some of them probably will be in the future). All of them should reside in a directory /usr/share/goctave/m/ after you "make install". Please note that although some of these are specifically related to G-Octave and its user interface, most of them are simple functions that I wrote for my own personal library and have included here because it is the easiest way to distribute them.

Builtin Function : control_string = cls ()

Clears the screen. More likely to do it successfully than clc().

Outputs:

control_string: An escape sequence tailored to your terminal which clears the screen.

Builtin Function : control_string = color ( c )

Sets the text color. The number of colors available and their mapping varies from terminal to terminal. On the standard Linux console (or on G-Octave) they are assigned as follows:

       NUMBER    COLOR
         0       BLACK
         1       RED
	 2	 GREEN
	 3	 BROWN
	 4	 BLUE
	 5	 VIOLET
	 6	 TEAL
	 7	 GRAY

Inputs:

c: An integer color value.

Outputs:

control_string: An escape sequence tailored to your terminal which sets the new foreground color. If the terminal dose not support color, returns NULL.

Function File : ret_val = eval_eq ( expression, var_0, value_0, ..., var_n, value_n )

Evaluates an expression for given variable values. This function is an improvement over the eval() because you can give it variables and values to use for them. Note that you can also include calls to other functions inside your expression.

Inputs:

expression: A standard Octave expression.
var_0, ..., var_n: Variables, given as strings.
value_0, ..., value_n: The values to set each variable to.

Outputs:

ret_val: The value that the expression evaluates to.

Example:

octave:35> eval_eq("floor(x) - 3*y", "x", 3.4, "y", 2)
ans = -3

Function File : ret_set = expsmooth ( data_set, k )

Smooths a data set, using an exponential smoothing algorithm. This technique is generally used to smooth time-series information so it is easier to spot long-term trends.

The smoothing constant, k, is a number between 0 and 1 exclusive. The lower this constant, the more smoothing is done.

It should be possible to use this function to smooth out colors in a bitmap image, for instance by smoothing first rows, then columns of pixels in a "plaid" pattern. I have never tried this, however.

Inputs:

data_set: A row or column vector of data.
k: A smoothing constant, between 0 and 1.

Outputs:

ret_set: A smoothed data set.

Function File : fract = fraction ( float )

Attempts to take a floating point number and convert it to a fraction. The fraction is returned at a column vector. The first number is the numerator, the second the denominator.

Inputs:

float: A floating point value.

Outputs:

fraction: A vector containing the numerator and denominator of an equivalent fraction.

Function File : m = makecsv ( m, filename )

Takes a matrix and outputs it as a file in Comma Separated Value format. It can then be imported with ease into any of the many spreadsheets and other applications that can read .csv, such as Gnumeric.

Inputs:

m: A matrix of real numbers.
filename: The file name to write to. Should have an extension .csv.

Outputs:

m: The matrix that was written.

Function File : m = makedif ( m, filename )

Takes a matrix and outputs it as a file in Data Interchange Format. It can then be imported with ease into any of the many spreadsheets and other applications that can read .dif, such as Gnumeric.

Inputs:

m: A matrix of real numbers.
filename: The file name to write to. Should have an extension .dif.

Outputs:

m: The matrix that was written.

Function File : maxima ( [expression])

Calls Maxima and has it evaluate expression. Multiple commands can be passed, and separated with semi-colons. If invoked without arguments, opens a Maxima session (type quit(); to return to Goctave).

Obviously, this function is not going to do anything if you do not have Maxima installed on your machine.

Inputs:

expression: Any Maxima expression.

Known Problems:

Maxima displays its output character-cell style, while Octave uses strings and matrices. This means that, while we can run Maxima commands and display the output, we do not get a return value to use in further Octave computations.

Example:

octave:2> maxima ("integrate(x*sin(x), x);")
(D1) 			       SIN(x) - x COS(x)

octave:3> maxima("3/4 + 1/2;")
				       5
(D1) 				       -
				       4

Function File : m = rref ( m )

Return the (reduced) row-echelon form of a matrix. Exactly similar to the Matlab(tm) function of the same name. This is (conceptually) a fairly slow function. Use it for compatibility with Matlab(tm) or when you expect to get a parametric solution to a system (i.e. when the matrix is singular). For general equation solving, Octave's "\" operator is nearly always superior.

Inputs:

m: A matrix

Outputs:

m: The row-reduced matrix.

Function File : plot_string = stemleaf ( data_set, [stem_unit] )

Generates a stem-leaf plot of a vector of data values, which is returned in string form.

Inputs:

data_set: A vector of data values.
stem_unit: The digit to use as the first digit of the "stem", such as 100, 1, .1, etc. The default is 1 (ones place).

Outputs:

plot_string: A string containing the stem-leaf plot.

Example

octave:1> m = rand(10,1)
m =

  0.445231
  0.084164
  0.283295
  0.191321
  0.573918
  0.261156
  0.695213
  0.571522
  0.955541
  0.696154

octave:2> stemleaf(m, .1)
ans = 
0 | 8 
1 | 9 
2 | 6 8 
4 | 4 
5 | 7 7 
6 | 9 9 
9 | 5 

n = 10, stem unit = 0.1

Function File : m = sortrows ( m )

Sorts a matrix, keeping each row together, as opposed to sorting each column separately as sort does.

Inputs:

m: A matrix

Outputs:

m: The row-sorted matrix.

Example

octave:12> m
m =

  4  7  7  6  5
  9  9  0  3  2
  6  8  2  5  3
  4  4  9  5  3

octave:13> sortrows(m)
ans =

  9  9  0  3  2
  6  8  2  5  3
  4  7  7  6  5
  4  4  9  5  3

Function File : [mean, stddev] = threepest ( worst_case, most_likely, best_case )

Estimates the mean and standard deviation of a distribution of outcomes, given good guesses for the worst case, most probable, and best case outcomes. Careful, while a useful tool, this is only an estimate. Furthermore, it only really works if the distribution in question is pretty close to a standard distribution.

Inputs:

worst_case: Worst possible outcome.
most_likely: Most probable outcome (ie the mode).
best_case: Best possible outcome.

Outputs:

mean: Mean (center) of the distribution.
stddev: Standard deviation of the distribution.