TReplace
TReplace-func
Description
The Threshold Replace function is used to compare each value in a dataset vd with a value val1, with respect to (optional) condition cnd. When the comparison is true, the value in vd is replaced with val2 or -val2, depending on the condition cnd. When the comparison is false, the value is retained or replaced with a missing value, depending on the condition cnd.
Syntax
dataset tReplace(dataset vd, double val1, double val2[, string cnd])
Parameters
vd
- is the dataset you want to compare.
val1
- is the value you will compare dataset vd values against.
val2
- is the value that may replace values in dataset vd.
cnd
- is the condition that determines how comparisons between vd and val1 are made.
The condition argument cnd is optional. Calculate the value of condition by adding the Value number for all those conditions which should apply. Note that the first four bits (0, 1, 2, 3) determine how the comparison is made, while the last two bits (4, 5) determine what happens as a result of the comparison. Note that the Action is applied to values in dataset vd, when comparing to val1. For instance, if Value is 1 ("Use Less Than in the comparison"), the comparison becomes "If the value in dataset vd is less than val1..."
| Bit |
Value |
Action |
| 0 |
1 |
1(on) = Use Less Than in the comparison;
0(off) = Do not consider Less Than.
|
| 1 |
2 |
2(on) = Use Equal in the comparison;
0(off) = Do not consider Equal.
|
| 2 |
4 |
4(on) = Use Greater Than in the comparison;
0(off) = Do not consider Greater Than.
|
| 3 |
8 |
8(on) = Use the absolute value of dataset in the comparison;
0(off) = Use value of dataset.
|
| 4 |
16 |
16(on) = Keep original sign when replacing;
0(off) = Use value2 regardless of original sign.
|
| 5 |
32 |
32(on) = When comparison fails, replace dataset with a missing value;
0(off) = Leave dataset alone.
|
Return
If val1 is a missing value, then testing will only look at the bit Value = 2 (Use Equal in the comparison) and ignore bit Values 1, 4, and 8. In this case, each value in dataset is tested to see if it is a missing value. When missing values are found in dataset, they are replaced with val2.
If Bit 1 is set to 0 (Do not consider Equal), then each value in dataset is tested to see if it is not a missing value. This time, all non-missing values in dataset are replaced with val2.
When the condition is not specified, the function takes Value to equal 12 -- the sum of 4 and 8: Replace dataset value with val2 if the absolute value of dataset value is greater than val1.
When the first three bits (0, 1, 2) are all off (Do not consider Less Than, Do not consider Equal, Do not consider Greater Than), all comparisons between dataset and val1 are false. This occurs when Value is one of the following: 0, 8, 16, 24, 32, 40, 48 and 56.
When the first three bits (0, 1, 2) are on (Use Less Than in the comparison, User Equal in the comparison, Use Greater Than in the comparison), the Less Than condition is ignored. This occurs when Value is one of the following 7, 15, 23, 31, 39, 47, 55 and 63.
When Less Than and Greater Than are both on and Equal is off (Use Less Than in the comparison, Use Greater Than in the comparison, Do not consider Equal), the comparison is equivalent to Not Equal. This occurs when Value is one of the following: 5, 13, 21, 29, 37, 45, 53 and 61.
Example
Data1_result = treplace(Data1_A, 1.5, 999, condition);
Values of Data1_Result for various conditions:
| Data1_A |
1 |
2 |
3 |
5 |
13 |
14 |
| 2 |
2 |
2 |
2 |
999 |
999 |
999 |
| 1.5 |
1.5 |
999 |
999 |
1.5 |
1.5 |
999 |
| 1 |
999 |
1 |
999 |
999 |
999 |
1 |
| 0 |
999 |
0 |
999 |
999 |
999 |
0 |
| -1 |
999 |
-1 |
999 |
999 |
999 |
-1 |
| -1.5 |
999 |
-1.5 |
999 |
999 |
-1.5 |
999 |
| -2 |
999 |
-2 |
999 |
999 |
999 |
999 |
| Data1_A |
22 |
25 |
32 |
36 |
49 |
63 |
| 2 |
999 |
2 |
-- |
999 |
-- |
999 |
| 1.5 |
999 |
1.5 |
-- |
-- |
-- |
999 |
| 1 |
1 |
999 |
-- |
-- |
999 |
-- |
| 0 |
0 |
999 |
-- |
-- |
999 |
-- |
| -1 |
-1 |
-999 |
-- |
-- |
-999 |
-- |
| -1.5 |
-1.5 |
-1.5 |
-- |
-- |
-999 |
-999 |
| -2 |
-2 |
-2 |
-- |
-- |
-999 |
-999 |
If you assign the results to the same dataset as the first argument, the original data may be changed.
See Also
The treplace() function should be faster than the similar ternary operator.
|