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 Re-dimensions 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):(upper)] >> w.y = w.y[(lower):(upper-1)] >> w.e = w.e[(lower):(upper-1)]
Note: Normally this would be done with the Rebin() command.
This command is effectively used to "find" the location or nearest 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 sentinel 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.
Re-dimensions 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 indices 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.