Home Manual Packages Global Index Keywords Quick Reference |
### 2.3.9 Rank reducing (statistical) range functions The beauty of Yorick's matrix multiplication syntax is that you "point" to the dimension which is to be contracted by placing the `+` marker in the corresponding subscript. In this section and the following section, I introduce Yorick's range functions, which share the "this dimension right here" syntax with matrix multiplication. The topic in this section is the statistical range functions. These functions reduce the rank of an array, as if they were a simple scalar index, but instead of selecting a particular element along the dimension, a statistical range function selects a value based on an examination of all of the elements along the selected dimension. The statistical function is repeated separately for each value of any spectator dimensions. The available functions are: `min` `max` returns the minimum (or maximum) value. These are also available as ordinary functions. `sum` returns the sum of all the values. This is also available as an ordinary function. `avg` returns the arithmetic mean of all the values. The result will be a real number, even if the input is an integer array. This is also available as an ordinary function. `ptp` returns the peak-to-peak difference (difference between the maximum and the minimum) among all the values. The result will be positive if the maximum occurs at a larger index than the minimum, otherwise the result will be negative. `rms` returns the root mean square deviation from the arithmetic mean of the values. The result will be a real number, even if the input is an integer array. `mnx` `mxx` returns the index of the element with the smallest (or largest) value. The result is always an integer index value, independent of the data type of the array being subscripted. If more than one element reaches the extreme value, the result will be the smallest index. The `min`, `max`, `sum`, and `avg` functions may also be applied using ordinary function syntax, which is preferred if you want the function to be applied across all the dimensions of an array to yield a single scalar result. Given the `brightness` array representing the spectrum incident on a detector or set of detectors, the `mxx` function can be used to find the photon energy at which the incident light is brightest. Assume that the final dimension of `brightness` is always the spectral dimension, and that the 1-D array `gav` of photon energies (with the same length as the final dimension of `brightness`) is also given:
    max_index_list = brightness(.., mxx);
    gav_at_max = gav(max_index_list);
Note that `gav_at_max` would be a scalar if `brightness` were a 1-D spectrum for a single detector, a 2-D array if `brightness` were a 3-D array of spectra for each point of an image, and so on. An arbitrary index range (`start:stop` or `start:stop:step`) may be specified for any range function, by separating the function name from the range by another colon. For example, to select only a relative maximum of `brightness` for photon energies above 1.0, ignoring possible larger values at smaller energies, you could use:
    i = min(where(gav > 1.0));
    max_index_list = brightness(.., mxx:i:0);
    gav_at_max = gav(max_index_list);
Note the use of `min` invoked as an ordinary function in the first line of this example. (Recall that `where` returns a list of indices where some conditional expression is true.) In the second line, `mxx:i:0` is equivalent to `mxx:i:`. Because of the details of Yorick's current implementation, the former executes slightly faster. More than one range function may appear in a single subscript list. If so, they are computed from left to right. In order to execute them in another order, you must explicitly subscript the expression resulting from the first application:
    x = [[1, 3, 2], [8, 0, 9]];
    max_min = x(max, min);
    min_max = x(, min)(max);
The value of `max_min` is 3; the value of `min_max` is 2.