fsc2: 5.5 Auxiliary functions

5.5 Auxiliary functions

List of all auxiliary functions:

`end()'
`abort()'
`date()'
`time()'
`delta_time()'
`wait()'
`T_to_G()'
`G_to_T()'
`C_to_K()'
`K_to_C()'
`D_to_R()'
`R_to_D()'
`WL_to_WN()'
`WN_to_WL()'
`F_to_WN()'
`WN_to_F()'
`slice()'
`int_slice()'
`float_slice()'
`dim()'
`size()'
`sort()'
`reverse()'
`sprint()'
`mouse_position()'
`lin_space()'
`find_peak()'
`spike_remove()'

Descriptions of auxiliary functions:

`end()'

The function simulates the user clicking onto the Stop button in the display window. If there is an ON_STOP label flow of control will be transferred to the code following the ON_STOP label, otherwise the program will be stopped immediately. This function can be used in the EXPERIMENT section only and not after the ON_STOP label.

`abort()'

The function will abort the currently running script immediately without even running the code following the ON_STOP label, so it is a kind of an emergency exit when nothing better will do. When called it displays a message box on the screen to inform the user.

If called after the ON_STOP label it simply ends the experiment without any notification of the user, so it then can be used to get out of the ON_STOP handling.

The function can only be used in the EXPERIMENT section.

`date()'

When called without an argument the function returns a string with the current date in a form like "Sun Jun 17, 2000". Alternatively, it may be called with a single argument, a string representing a format string acceptable to the strftime(3) function .Please read the manual page for this function (type "man 3 strftime" at the command prompt to read it) to find out how such a format string must look like. Allowed conversion specifiers are ""aAbBcCdDeFGghHIjklmMnPrRsStTuUVWxXyYzZ+%", where "cCxXyY" may be preceded by 'E' and "deHImMSuUVwWy" by 'O' to request use of an alternative format.

`time()'

If called without an argument the function returns a string with the current time in the form hh:mm:ss. If it's called with a string containing of one or two characters the colons (':') in the returned string are replaced by the characters from the argument. The new separator characters must be printable, i.e. they can't be control characters.

`delta_time()'

This function (that can only be used in the EXPERIMENT section of the script) returns the time (in seconds) since the last call of the functions as a floating point value. When called for the very first time it returns the time since the start of the experiment (i.e. the time the start of the EXPERIMENT section was processed). The time returned by the function has micro-second resolution. During the test run of the EDL script the function returns a very rough guess of the time that will be required in the real run of the experiment.

`wait()'

Waits for the specified time. Times are always to be given in seconds or alternatively with a unit, e.g. 100 ms. Unfortunately, the time resolution of wait() is in the 10 ms range and may even be less precise. If the argument is negative the function will print an error message and return immediately. The maximum time the function accepts is more than 2.1 billion seconds (or about 68 years).

This function can only be used in the EXPERIMENT section of an EDL script.

`T_to_G()'

Converts a number or all elements of an 1- or more-dimensional array, assumed to have a unit of Tesla, to Gauss (by multiplying with 1.0e4).

`G_to_T()'

Converts a number or all elements of an 1- or more-dimensional array, assumed to have a unit of Gauss, to Tesla (by multiplying with 1.0e-4).

`C_to_K()'

Converts a number or all elements of an 1- or more-dimensional array, assumed to have a unit of degree Celsius, to Kelvin (by adding 273.16).

`K_to_C()'

Converts a number or all elements of an 1- or more-dimensional array, assumed to have a unit of Kelvin, to degree Celsius (by subtracting 273.16).

`D_to_R()'

Converts a number or all elements of an 1- or more-dimensional array, assumed to represent angles in degrees, to radians.

`R_to_D()'

Converts a number or all elements of an 1- or more-dimensional array, assumed to represent angles in radians, to degrees.

`WL_to_WN()'

Converts a wave length (in m) or all elements of an 1- or more-dimensional array of wave lengths to wavenumbers (in cm^-1).

`WN_to_WL()'

Converts a wavenumber (in cm^-1) or all elements of an 1- or more-dimensional array of wavenumbers to wave lengths (in m).

`F_to_WN()'

Converts a frequency (in Hz) or all elements of an 1- or more-dimensional array of frequencies to wavenumbers (in cm^-1).

`WN_to_F()'

Converts a wavenumber (in cm^-1) or all elements of an 1- or more-dimensional array of wavenumbers to frequencies (in Hz).

`slice()'

The function returns a part (slice) of an one-dimensional array. It expects at least two arguments, the array the values are to be taken from and the number of the start element of the slice to be returned. Usually, you also will pass it a third argument, the length of the slice to be returned. If this argument is missing an array made up from all elements from the start element to the end of the array is returned.

For an array defined as

X[ 8 ] = { 1, 2, 3, 4, 5, 6, 7, 8 }

the call of slice()

slice( X, 3, 4 );

will return an array with 4 elements containing the data

3, 4, 5, 6

Please note: This function is not very useful anymore because the same effect can be achieved by using ranges when indexing the array (see Array ranges).

`int_slice()'

Creates an integer array of the size of the first and only argument with every element set to 0 which then can be assigned to an integer array of variable length. The size argument can also be 0 to allow the removal f all elements of the array the result is assigned to.

`float_slice()'

Creates an float array of the size of the first and only argument with every element set to 0.0 which then can be assigned to a float array of variable length. The size argument can also be 0 to allow the removal f all elements of the array the result is assigned to.

`dim()'

The function returns the dimension of the array passed to it as argument. I.e. if applied to the array defined as

X[ 4, 2, 5 ]

it will return 3.

`size()'

The function normally takes one arguments, an array, and returns its length. I.e. for an array defined as

X[ 4, 2, 5 ]

size(X) will return 4 (the size of the first dimension), size(X[4]) returns 2 and size(X[4,2]) returns 5.

For variable sized arrays for which the length is still unknown the function returns 0.

If the argument is a simple numerical variable 1 is returned and a warning is printed. If the argument is a string the length of the string is returned.

`sort()'

The function takes at least one argument, a one-dimensional array. If no further argument is given it returns an array with the sorted (in ascending order) values of the argument array. If there's a second argument and this is 1 or "DOWN" or "DOWNWARDS" then the array is sorted in descending order. (You may also specify 0 or "UP" or "UPWARDS" as the second argument to explicitly request sorting in ascending order.)

`reverse()'

The function takes a single argument, normally a one- or more-dimensional array. For a one-dimensional array it returns another array with the order of the elements of the input array reversed. For a multi-dimensional array it returns a multi-dimensional array of the same rank as the input array and the order of all the elements of all one-dimensional arrays making up the multi-dimensional array being reversed.

If the argument is a simple integer or floating point number the same number gets returned. If the argument is a string the reversed string is returned.

`sprint()'

The function can be used to create strings with a text that only gets determined while the experiment is running, e.g. to create label strings on demand etc. The function expects at least one argument, a format string, having exactly the same form as the format string passed to the print() function, i.e. with embedded # characters as placeholders for the values of other variables to be inserted into the string. For each unescaped # in the string there must be an additional argument, a number, a variable or a string. The function returns a variable that can be used in all places where otherwise a string would be required. Here's a simple-minded example on how to create a set of 10 buttons, where the label contains the button number (note that the first # character is escaped by a backslash, so it goes directly into the string to be created without any conversions):

FOR I = 1 : 10 {
    B[ I ] = button_create( "NORMAL_BUTTON",
                            sprint( "Button \##", I ) );
}

`mouse_position()'

The function can be used to determine the mouse position in the display windows currently having the focus. It expects either none or a single argument, a integer value indicating which mouse buttons must be pressed in order to return a set of values - -1 (or any negative value) means that values are to be returned independent of the state of the mouse buttons, 0 means no mouse button may be pressed, 1 means the left mouse button, 2 the middle button and 4 the right button. Combinations can be specified by adding the values for the respective mouse buttons. If no argument has been given the function for historic reasons returns valid values when both the left and right mouse button are pressed, i.e. it works as if the function was called with a value of 3. The function returns an array of 10 floating point values.

The first element of the returned array can have the following values, indicating the meaning of the following elements:

`0': The mouse pointer is not within the main display area of one of the display windows, the requested mouse buttons aren't pressed, or no curve is shown at the moment in the currently active window (possibly because there's no scaling set for the curve). The remaining elements (except the last) of the array have no meaning.
`1': The mouse pointer is in the display area of the 1D display window and the requested mouse buttons are pressed. The second and third element are the x- and y-coordinates of the position of the mouse according to the current scaling for the first curve. If there is more than one curve the following array elements are the coordinates of the mouse position according to the scaling of each of the other curves as far as they exist.
`2': The mouse pointer is in the display area of the 2D display window and the requested mouse buttons are pressed. The second and third element of the array are x- and y-coordinates of the mouse position according to scaling of the currently displayed curve. The fourth element is the z-value of the curve at this position. All of the array elements (except the last one) are meaningless.
`-2': The mouse pointer is in the display area of the 2D display window and the requested mouse buttons are pressed. The second and third element of the array are x- and y-coordinates of the mouse position according to scaling of the correctly displayed curve. At the current mouse position is no displayed point, a z-value thus cannot be given. All other array elements (except the last one) are meaningless.
`3': The mouse pointer is in the display area of the display window showing a cross section through a 2-dimensional data set and the requested mouse buttons are pressed. The second and third element of the array are x- and y-coordinates of the mouse position according to scaling of the correctly displayed cross section curve. The fourth element is the coordinate of the cut through the 2-dimensional curve. All other array elements (except the last one) are meaningless.

The tenth and last element of the array can be used to figure out if one of the modifier keys on the keyboard is currently pressed. Modifier keys are the Shift keys, the Shift-Lock key, the Control keys and other keys like the Alternate key. The value returned consists of values for:

`0': No modifier key is pressed
`1': Shift modifier key (typically one of the Shift keys) is pressed.
`2': Shift-lock modifier (typically the Shift-lock key) is pressed.
`4': Control modifier (typically one of the Control keys) is pressed.
`8': Modifier-1 (typically the Alternate key) is pressed.
`16': Modifier-2 key is pressed.
`32': Modifier-3 key is pressed.
`64': Modifier-4 key is pressed.
`128': Modifier-5 key is pressed.

The value returned in last the array element is the sum of the above values for the keys currently pressed. I.e. when someone holds down both the Shift modifier key and the Control modifier key the returned value will be 5. To find out if e.g. the Control modifier key is pressed you could use:

pos_arr = mouse_position( );
IF ( int( pos_arry[ 10 ] ) / 4 ) % 2 {
    print( "The Control modifier key is pressed.\n" );
}

Please note: since under X it is easy to remap keys the returned value does not represent how a keys is labeled on the keyboard but the function the user has assigned to it. If, for example, the user has mapped the function "Shift" to the key labeled "Ctrl", pressing this key will be reported as a press of the Shift modifier key. The Modifier-2 to Modifier-5 functions often are not mapped to a key.

`lin_space()'

The function returns an array of equally spaced (floating point) numbers. It expects three arguments, the start value, then end value and the number of points. It then returns an array with as many points as specified by the third argument, starting with the value of the first argument and ending with the value of the second and with the difference between adjacent points being identical.

`find_peak()'

This function can be used for trying to find a peak in a certain region of a 1-dimensional array, the only function argument. The function returns useful results only when the spectrum has a rather good signal-to-noise ratio (at least about 250) and a more or less straight baseline (i.e. does only changes linearly). It makes no assumptions about the form of the peak and returns the index in the array where the area under the peak is halve that of its total area, so it should work reasonable well with asymmetric peaks.

`spike_remove()'

The function tries to remove spikes from 1-dimensional arrays. Before going on describing the arguments here's an explanation how it works. That's necessary because a fit-it-all function for detecting and removing spikes is impossible and when this function is used it must be done with all restrictions in mind.

The function calculates numerically the first derivative of the 1-dimensional arrays by computing the differences between neighboring points of the array. It then goes on calculating the mean and the standard deviation of the derivatives and picks the points where the derivative deviates by more than a certain factor (to be specified as one of the arguments to the function) of the standard deviation from the mean value. These "outliers" are further investigated.

In the next step all points are discarded where no other "outlier" with the opposite derivative is within its vicinity (another argument to be passed to the function). Only the remaining points are taken to be spikes.

To summarize: a structure in the spectrum to be recognized as a spike must satisfy two conditions. First, there must be an usually large derivative and, at the same time, another unusually large derivative, but with opposite sign, must exist in the near vicinity (and there's some special treatment for spikes at the very fringes of the spectrum in case it starts or ends with a spike). The algorithm fails often rather miserably when e.g. a "positive" spike is directly followed by a "negative" spike.

When a spike has been identified the points of the spike are replaced by the a straight line starting from the point on the left to the point to the right of the spike.

The arguments the function takes are the 1-dimensional-array and, optionally, the factor by which the standard deviation is multiplied to determine what should be taken to be "outliers" (which defaults to 5.0) and the maximum width a spike can have (in number of points, defaulting to 3). What to pick as the second and third argument depends a lot on the circumstances. When the spikes don't have a large amplitude (compared to the signal) or there are lots of spikes a factor lower than the default value should be taken, otherwise most of the spikes will make it through the filter. The maximum spike width can only be determined from experience and must always be lower than the width of any significant feature in the spectrum.

Please note: Never, ever use this function on data you intend to store as results of an experiment. It is only meant for situations where one wants to display data during the experiment to get a first impression of what's happening (e.g. to get rid of the spikes one sometimes gets in spectra from a CCD camera when cosmic radiation hits the detector). It is no replacement at all for a careful analysis of a spectrum where one can use a priori knowledge to determine what are spikes and what not (and even the eye is often a much better guide than a stupid program)!

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.