### SUBSTITUTE

Replaces all occurrences of a given value in an NDF array with another value

#### Description:

This application changes all pixels that have a defined value in an NDF  with an alternate value. The number of replacements is reported. Two modes are available.
• A single pair of old and new values can be supplied (see Parameters OLDVAL and NEWVAL). All occurrences of OLDVAL are replaced with NEWVAL. Other values are unchanged.

• A look-up table containing corresponding old and new values can be supplied. By default, each input pixel that equals an old value is replaced by the corresponding new value. Alternatively, all input pixels can be changed to a new value by interpolation between the input values (see Parameters LUT and INTERP).

#### Usage:

substitute in out oldval newval [comp]

#### Parameters:

The components whose values are to be substituted. It may be "Data", "Error", "Variance", or "All". The last of the options forces substitution in both the data and variance arrays. This parameter is ignored if the data array is the only array component within the NDF. ["Data"]
Input NDF structure containing the data and/or variance array to have some of its elements substituted.
Determines how the values in the file specified by Parameter LUT are used, from the following options.
• "None" – Pixel values that equal an input value are replaced by the corresponding output value. Other values are left unchanged.

• "Nearest" – Every pixel value is replaced by the output value corresponding to the nearest input value.

• "Linear" – Every pixel value is replaced by an output value determined using linear interpolation between the input values.

If "Nearest" or "Linear" is used, pixel values that are outside the range of input value covered by the look-up table are set bad in the output. Additionally, an error is reported if the old data values are not montonic increasing. ["None"]

The name of a text file containing a look-up table of old and new data values. If null (!) is supplied for this parameter the old and new data values will instead be obtained using Parameters OLDVAL and NEWVAL. Lines starting with a hash (#) or exclamation mark (!) are ignored, as are blank lines. Other lines should contain an old data value followed by the corresponding new data value. The way in which the values in this table are used is determined by Parameter INTERP. [!]
The value to replace occurrences of OLDVAL. It must lie within the minimum and maximum values of the data type of the array with higher precision. The new value is converted to data type of the array being converted before the search begins. The suggested default is the current value. This parameter is only accessed if a null value is supplied for Parameter LUT.
The element value to be replaced. The same value is substituted in both the data and variance arrays when COMP="All". It must lie within the minimum and maximum values of the data type of the array with higher precision. The replacement value is converted to data type of the array being converted before the search begins. The suggested default is the current value. This parameter is only accessed if a null value is supplied for Parameter LUT.
##### OUT = NDF (Write)
Output NDF structure containing the data and/or variance array that is a copy of the input array, but with replacement values substituted.
Title for the output NDF structure. A null value (!) propagates the title from the input NDF to the output NDF. [!]
The numeric type for the output NDF. The value given should be one of the following: _DOUBLE, _REAL, _INTEGER, _INT64, _WORD, _UWORD, _BYTE or _UBYTE (note the leading underscore). If a null (!) value is supplied, the output data type equals the input data type. [!]

#### Examples:

substitute aa bb 1 0
This copies the NDF called aa to the NDF bb, except that any pixels with value 1 in aa are altered to have value 0 in bb.
substitute aa bb oldval=1 newval=0 comp=v
As above except the substitution occurs to the variance values.
substitute in=saturn out=saturn5 oldval=2.5 newval=5 comp=All
This copies the NDF called saturn to the NDF saturn5, except that any elements in the data and variance arrays that have value 2.5 are altered to have value 5 in saturn5.

#### Notes:

• The comparison for floating-point values tests that the difference between the replacement value and the element value is less than their mean times the precision of the data type.

#### Related Applications

KAPPA: CHPIX, FILLBAD, GLITCH, NOMAGIC, SEGMENT, SETMAGIC, ZAPLIN;
FIGARO: GOODVAR.