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.
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.
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.
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 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
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.
Array (Array)
Any valid Open GENIE array type
RESULT = (Array)
Returns the centered array
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.
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.
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.
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
Returns the dimensionality of an array.
Array (Array)
The array to test the dimensionality of.
RESULT = (Integer)
Number of 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).
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.
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 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.
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.
/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 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.
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.
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.
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
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.
Array (Array)
Array to be tested.
RESULT = (Array element type)
The maximum value found in the array.
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
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.
Array (Array)
Array to be tested.
RESULT = (Array element type)
The minimum value found in the array.
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
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.
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
Sums all the elements in an array
| SUM() | array=Array | Sum all the elements |
example:
# Integrate some data >> printn sum(w.y) 12456890.789
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.
Array (Array)
Array to be summed.
RESULT = (Array element type)
The sum of all the data in an array.
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.
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.
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.
Create a workspace
| FIELDS() | Create a new empty workspace. |
example:
# Example in preformatted font >> w = fields() >> w.new = 5 >> printn w Workspace [] ( new = 5 )
Creates an empty workspace to which fields may be added.
RESULT = (Workspace)
Returns an empty workspace.