Array and Workspace Handling Functions

This section describes the basic utility functions for creating and using Open GENIE workspaces and arrays. For detailed information on the data analysis based use of workspaces see the section on Workspace Operations. Most arithmetic functions on arrays are described in the section on Mathematical Functions and are simply generalisations of the scalar functions.

The functions documented in this section are listed below.

Array functions Description
Bracket Finds the index position of a given value in an array.
Centre_bins Centre the bins of a real array.
Cut Takes a one-D cut out of a two-D array
Dimensionality Return an integer giving the dimensionality of the array
Dimensions Create and size an Open GENIE array
Fill Fill an array with values
Fix Fix any undefined values in an array
Max Find the maximum value in an array
Min Find the minimum value in an array
Redim Redimensions an array whilst keeping the size and contents identical
Sum Sums all the elements in an array
Unfix Replace sentinel values with "undefined"
Workspace functions
Fields Create a workspace

See also the generic Length() command (documented in String Operations) for getting the number of fields in a workspace or the total length of an array.

Command Reference

Array Functions

Bracket()

Finds the index position of a given value in an array.

BRACKET xarray=Realarray xval=Real Allows bracketing of X values.

example:

	# Rebin data to a smaller range manually
	>> lower = bracket(w.x, 1000.0)
	>> upper = bracket(w.x, 4000.0)
	>> w.x = w.x[(lower):(uppper)]
	>> w.y = w.y[(lower):(uppper-1)]
	>> w.e = w.e[(lower):(uppper-1)]

Note: Normally this would be done with the Rebin() command.

Bracket

This command is effectively used to "find" the location or neareset location to a number in a real array where the assumption (for all i x[i] <= x[i+1]) holds true for an array "x" (the X values of a histogram).

This command is used when it is necessary to bracket out a section of a histogram based on the actual X values.

Parameters:

Xarray (Realarray)

An array which fulfils the assumption above.

Xval (Real)

The value being searched for.

RESULT = (Integer)

This is either the index of the first element with the value "xval" or the index of the element such that "xval" would be included within the open interval (x[i], x[i+1]) where i is the returned index.

If the range where the value would be found is not present in the array then a value of -1 is returned.

Centre_bins()

Centre the bins of a real array (i.e. convert from histogram to point mode).

CENTRE_BINS array=Array Centre the bins of a real array (i.e. convert from histogram to point mode).

example:

	# Do a rough conversion from a histogram workspace to
	# to a new point mode workspace
	point_mode = my_work
	point_mode.x = centre_bins(my_work.x)
	
	# convert an array to point mode
	centre_bins my_array

Centre

The Centre() command is useful for converting histogram data to point mode data. Used on the X-array of a workspace, it will reduce the total number of X points by one and the X values left will be those of the centre of each bin.

Parameters:

Array (Array)

Any valid Open GENIE array type

RESULT = (Array)

Returns the centered array

Cut()

Takes a one-D cut out of a two-D array

CUT array=Realarray dimension=Integer index=Real Takes a slice out of an array.

example:

	# Take a cuts at 1 and 1.5 along the 2nd dimension
	printn y
	>> y = Dimensions(2,3)
	>> fill y 1.0 1.0
	>> printn cut(y, 1, 1.0)
	[1.0 2.0 3.0 ] Array(3 )
	>> printn cut(y, 1, 1.5)
	[2.5 3.5 4.5 ] Array(3 )

Note: Returns a one-D array of one element if a one-D array is supplied.

Cut

The Cut() command takes a one dimensional slice out of a two dimensional array (useful in two dimensional graphics applications where a one dimensional plot is required along one axis). Depending on which dimension is chosen from the source array, the length of the resulting array is the length of the orthogonal dimension. The cut is taken at an index value along the dimension selected and the values of the resulting slice are linearly interpolated for this position of the index value.

Parameters:

Array (Realarray)

The array to be cut

Dimension (Integer)

Specifies the dimension along which the index position of the slice is specified.

RESULT = (Realarray)

The values along the orthogonal dimension, interpreted if necessary for a non-integer index value.

Dimensionality()

Return an integer giving the dimensionality of the array

DIMENSIONALITY [array=Array] Returns the number of dimensions

example:

	# create an array and print its dimensionality
	>> a = dimensions(2,3,4)
	>> printn dimensionality(a)
	3

Dimensionality

Returns the dimensionality of an array.

Parameters:

Array (Array)

The array to test the dimensionality of.

RESULT = (Integer)

Number of dimensions

Dimensions()

Create and size an Open GENIE array

DIMENSIONS() dim1=Integer [dim2=Integer] ... [dim10=Integer] Create an empty array

example:

	# Dimension a 1 x 2 x 3 array
	>> a = dimensions(1, 2, 3)
	>> printn is_a(a, "Realarray")
	$FALSE
	>> a[1,2,1] = 4.0
	>> printn is_a(a, "Realarray")
	$TRUE
	>> printn a
	[_ _ _ 4.0 _ ...] Array(1 2 3 )

Note: Arrays print as if they are one dimensional (in row major order).

Dimensions

The dimensions command is used for creating arrays of a specified length and dimensionality. The number of "dim" parameters specified gives the dimensionality and the values give the length of each dimension. In Open GENIE arrays always start at 1.

Until a value has been assigned to one element of the array, the array has no fixed type and it will take on the type of the first value assigned to one of its elements. After this, trying to assign a different type will create an error as arrays may only contain variables of one type. Elements in an array that are undefined are shown as an "_" character. Undefined values in arrays can be changed to fixed values using the Fix() command.

Parameters:

Dim1, ..., Dim10 (Integer)

Sizes of each array dimension.

RESULT = (Array)

An array of the correct size and dimensionality but with an as yet undecided type.

Fill()

Fill an array with values

FILL value=Any [step=Number] Fill and array with values
[/GEOMETRIC]   Fill array geometrically

example:

	# Create some geometric data
	>> a = dimensions(200)
	>> Fill/Geometric a 1.0 0.9
	>> printn a
	[1.0 0.9 0.81 0.729 0.6561 ...] Array(200 )

Note: step values only work with integer and real arrays.

Fill

The Fill() command provides a quick way of filling up an array with data. For non-numeric data, it is just a way of filling the array with identical values. For numeric data, it is also a quick way of putting some useful data in an array, for example, an arithmetic fill is ideal for generating an axis to plot an array of data against. In the same mode, a geometric fill creates automatic log data to plot against.

Parameters:

/Geometric

Increase the values placed into the array geometrically based on the starting value and the step

Value (Any)

The value to fill the array with, or, if "step" is used, this is the starting value of the series and appears in the first element of the array.

Step (Number)

Sets a step size (or rate if /Geometric) is specified.

RESULT = (Array)

The filled array can also be returned as a result. In this case, the original array remains unmodified.

Fix()

Fix any undefined values in an array

FIX array=Array value=Any except Array Replaces any instances of "undefined" in an array.

example:

	# Fix undefined results to 999
	>> fill a -4.0 1.0
	>> printn 10/a
	[-2.5 -3.33333333333333 -5.0 -10.0  _  ...] Array(6 )
	>> fix a 999.0
	>> printn a
	[-2.5 -3.33333333333333 -5.0 -10.0 999.0 ...] Array(6 )

Note: See Unfix() for replacing sentinel values with "_" on data import.

Fix

Open GENIE caters for situations where an element of an array has an undefined value. This value is correctly propagated through all internal operations but can cause problems, especially when exporting data. To get round this problem, the Fix() command is used to replace any instances of an undefined value in an array with a specific sentinel value.

To go the other way, for example with imported data which, say, has undefined values represented by a specific number, the Unfix() command can be used.

Parameters:

Array (Array)

The array containing one or more undefined values to be fixed.

Value (Any except an array)

A value of the same type as the array with which to replace any undefined values.

RESULT = (Array)

An array of the same type as the original but with all undefined values replaced with a sentinal value of the correct type.

Max()

Find the maximum value in an array

MAX() array=Array Find the value of the highest element

example:

	# Find the index of the highest data value
	>> print Bracket(w.y, Max(w.y))
	12456

Max

The Max() function returns the value of the largest element of the array it is applied to. The size of an element is determined by comparing elements with each other using the "<" and "< "operators. As a result string arrays may also have a maximum value.

In arrays where there are undefined elements, the maximum value returned is the value of the largest defined element. For correctness, the array should have all undefined elements "fixed" explicitly to a defined value first. This can be done using the Fix() command.

Parameters:

Array (Array)

Array to be tested.

RESULT = (Array element type)

The maximum value found in the array.

Min()

Find the minimum value in an array

MIN() array=Array Find the value of the lowest element

example:

	# Find the index of the lowest data value
	>> print Bracket(w.y, Min(w.y))
	245

Min

The Min() function returns the value of the smallest element of the array it is applied to. The size of an element is determined by comparing elements with each other using the "<" and "< "operators. As a result string arrays may also have a minimum value.

In arrays where there are undefined elements, the minimum value returned is the value of the smallest defined element. For correctness, the array should have all undefined elements "fixed" explicitly to a defined value first. This can be done using the Fix() command.

Parameters:

Array (Array)

Array to be tested.

RESULT = (Array element type)

The minimum value found in the array.

Redim()

Redimensions an array whilst keeping the size and contents identical

REDIM [array=Array] i=Integer [j=Integer] [k=Integer][l=Integer] Re-dimensions an array whilst keeping the contents identical

example:

	>> printn a
	[1.0 2.0 3.0 4.0 5.0 ...] Array[400 ] Array(1 )
	>> printn redim(a,20,10,2)
	[1.0 2.0 3.0 4.0 5.0 ...] Array[20 10 2 ] Array(3 )
	>> printn a[1,2,1]
	3.0

Note: Redim will return an error if an attempt is made to change the total size of the array

Redim

The Redim() command is used to re-dimension an array whilst keeping the contents and overall size of the array the same. Arrays in GCL are stored in row major order so that the fastest varying index is on the Right hand side.

Parameters:

Array (Array)

Any valid Open GENIE array type

i, j, k, l (Integer)

Up to four integer indicies for re-dimensioning the array

RESULT = (Array)

Returns the re-dimensioned array

Sum()

Sums all the elements in an array

SUM() array=Array Sum all the elements

example:

	# Integrate some data
	>> printn sum(w.y)
	12456890.789

Sum

The Sum() function returns the sum of all the elements in an array. As a matter of convenience, undefined elements are ignored. To be correct however, all undefined elements should be "fixed" to a chosen value using the Fix() command.

Parameters:

Array (Array)

Array to be summed.

RESULT = (Array element type)

The sum of all the data in an array.

Unfix()

Replace sentinel values with "undefined"

UNFIX array=Array value=Any except Array Replace a specific value with undefined

example:

	# Fix undefined results to 999
	>> scan = get_dat("Old_data_file")
	>> Unfix scan 999.0    # 999.0 represents unknown values

Note: See Fix() for replacing undefined values with a sentinel value.

Unfix

Open GENIE caters for situations where an element of an array has an undefined value. This value is correctly propagated through all internal operations but when importing data it may be necessary to convert external sentinel values into proper Open GENIE undefined values before operating on the data.

To go the other way, for example when exporting data the Fix() command can be used.

Parameters:

Array (Array)

The array containing one or more sentinel values to be fixed.

Value (Any except an array)

The sentinel value to replace with proper undefined values in Open GENIE.

RESULT = (Array)

An array of the same type as the original but with all sentinel values replaced with undefined.

Workspace Functions

Fields()

Create a workspace

FIELDS()   Create a new empty workspace.

example:

	# Example in preformatted font
	>> w = fields()
	>> w.new = 5
	>> printn w
	  Workspace []
	  (
	    new = 5
	  )

Fields

Creates an empty workspace to which fields may be added.

Parameters:

RESULT = (Workspace)

Returns an empty workspace.