emath [ parameter=value ... ] [ inputfile outputfile ] emath [ parameter=value ... ] [ inputfile ... directory ] emath2 [ parameter=value ... ] [ inputfile1 inputfile2 outputfile ] emathc [ parameter=value ... ] [ inputfile ... outputfile ] emathp [ parameter=value ... ] [ inputfile ... outputfile ]
Parameters for emath are: expr_vars, expression, use_degrees, var_name, var_units, var_type, offset, scale_factor.
Parameters for emath2 are: file1_vars, file2_vars, expression, use_degrees, var_name, var_units, var_type, offset, scale_factor.
Parameters for emathc are: function_file, num_input, num_exprs, expr_vars, filen_vars, yn_expr, use_degrees, one_bad_all, save_exprs, var_names, var_units, var_types, scale_offsets, scale_factors.
Parameters for emathp are: num_exprs, expr_vars, filen_vars, yn_expr, use_degrees, poly_size, box_sides, min_good, save_exprs, var_names, var_units, var_types, scale_offsets, scale_factors.
These functions perform element-by-element math on TeraScan datasets. Complex expressions can combine several variables from one or more files to create a variable in a new output dataset. All input variables must have the same dimensions, but not necessarily the same datatype. All arithmetic is done as 64-bit floating point calculations. Output data can be stored as any non-string datatype, including 8-bit or 16-bit scaled integers.
Functions emathc and emathp allow multiple output variables. emath and emath2 allow only one output variable.
In expressions, input variables are specified symbolically as xn. The correspondence between the symbolic names xn and the actual input variable names is taken care of by the parameters expr_vars and filen_vars. The parameter expr_vars is used when there is exactly one input file per output file. The parameters filen_vars are used when there is more than one input file per output file. The following examples show how the correspondence between symbolic name xn and actual name is made.
If expr_vars = a b c then x1 = variable a x2 = variable b x3 = variable c
If file1_vars = a b c, and file2_vars = a d then x1 = variable a from the 1st input file x2 = variable b from the 1st input file x3 = variable c from the 1st input file x4 = variable a from the 2nd input file x5 = variable d from the 2nd input file
All of these functions support temporary variables, which have symbolic names yn. Each temporary variable can depend on previously defined temporary variables. In emathc and emathp, temporary variables are explicitly defined by parameter name, e.g., y1_expr. In emath and emath2, there is only one expression parameter, which can be broken into one or more sub-expressions using semicolons. The first sub-expression is the temporary variable y1, the second sub-expression is y2, etc. The last sub-expression is the output expression. The following examples are equivalent:
expr_vars = a b expression = (x1 - x2)/(x1 + x2)
expr_vars = a b expression = x1 - x2; x1 + x2; y1/y2
expr_vars = a b num_exprs = 3 y1_expr = x1 - x2 y2_expr = x1 + x2 y3_expr = y1/y2
emath, emath2, and emathp evaluate expressions in an interpretive fashion. These functions parse the mathematical expressions, generating pseudo code which is executed internally. Pseudo code operations are really vector operations, e.g., the pseudo code evaluator executes a simple addition operation as follows:
if the operation is addition, then
for each output (or temporary) variable element
if either of the two operands is bad, then
output the bad (missing) value
else
output the sum of the two operands
Thus, the expression 3*x1 + x2 is evaluated by following the order of operations, or doing multiplication first, followed by addition. Note that if for any case, if any operand is bad (missing), the operation is not allowed. This also applies to illegal operations, such as division by zero.
Function emathc, although very similar to emathp, generates an executable module for the given set of expressions. This increases the computation speed for large datasets and/or for complex expressions. The source file for generating this executable has name emathexpr.c. It is stored in the TeraScan library directory and should not be changed by the user. The basic evaluation loop used by emathexpr.c is
for each output variable element
if any corresponding input variable element is bad, then
output the bad (missing) value
else
evaluate the entire expression (e.g.,
each temporary expression, in order)
User expressions are directly embedded in this evaluation loop with little modification. Thus, user expressions must protect themselves against illegal operations, especially if the initial per-element bad value check is suppressed using the one_bad_all=no parameter option.
The following basic expression primitives are supported:
xj the j-th variable, starting with j=1 yj the j-th temporary variable, starting with j=1 ij the index of the j-th dimension, starting with j=1 nj the size of the j-th dimension, starting with j=1 number real number badval output bad value pi 3.14159265358979323846 halfpi 1.57079632679489661923 twopi 6.28318530717958647692
Variables are numbered independent of file number to simplify typing and to avoid name conflicts across files.
The precedence and order of expression evaluation is the same as the C programming language (e.g. Kernighan and Richie, The C Programming Language). Users unfamiliar with these rules should use parentheses to control the order of evaluation.
The following arithmetic operators are supported:
x + y addition x - y subtraction x * y multiplication x / y division
If one or more of the input values are bad or if division by zero is attempted, emath produces badval for the output element. badval is the symbolic name for the output variable's bad value.
The following functions are supported:
abs(x) absolute value sqrt(x) square-root of, x >= 0 exp(x) e ** x log(x) log base e, x > 0 log10(x) log base 10, x > 0 sin(x) sine cos(x) cosine tan(x) tangent asin(x) inverse sine, -1 <= x <= 1 acos(x) inverse cosine, -1 <= x <= 1 atan(x) inverse tangent bad(x) 1 if bad (missing), otherwise 0 sign(x) 1 if x > 0, -1 if x < 0, otherwise 0 sinh(x) hyperbolic sine cosh(x) hyperbolic cosine tanh(x) hyperbolic tangent asinh(x) inverse hyperbolic sine acosh(x) inverse hyperbolic cosine, x >= 1 atanh(x) inverse hyperbolic tangent, -1 <= x <= 1 int(x) nearest integer y to x, |y| <= x nint(x) nearest integer y to x pow(x,y) x to the power y atan2(x,y) inverse tangent of y/x mod(x,y) x modulo y, output retains sign of x remain(x,y) x modulo y, output has magnitude <= |x|/2 hypot(x,y) sqrt(x*x + y*y) bmin(x,y) best minimum of x and y bmax(x,y) best maximum of x and y bave(x,y) best average of x and y bfirst(x,y) output x if it is not bad, otherwise output y
There is no exponentiation operator like the FORTRAN ** operator. To achieve exponentiation, use the pow() function. Trigonometric functions are based on degrees rather than radians, unless overridden by the parameter option use_degrees=no.
The best functions output bad (missing) values only if both input values are bad (missing).
The following relational operators are supported:
x > y greater than x >= y greater than or equal to x < y less than x <= y less than or equal to x == y equal to x != y not equal to
All relational operators return 1 if the comparison is true and 0 if the comparison is false.
The following logical connectives are supported:
expr1 && expr2 logical and expr1 || expr2 logical or ! expr1 logical not
All logical connectives return 1 if the comparison is true and 0 if the comparison is false.
Conditional processing of complex expressions is supported, based on the following syntax:
expr1 ? expr2 : expr3.
In emathc, expr2 is evaluated only if expr1 is true, while expr3 is evaluated only if expr1 is false. However, in emath, emath2, and emathp, because operations are vectorized, expr2 and expr3 are evaluated first. Then if expr1 is true, expr2 is used, otherwise expr3 is used.
In general, if an operand's value is missing or bad, or if an operation is illegal (e.g., dividing by zero, or taking the log of 0), the result of the expression also will be missing or bad. This rule can be circumvented using conditional processing and the bad() function. The bad() function is used to identify bad operands and to avoid using them in expressions.
An example of a simple expression without conditional processing is:
x1 + 2*x2 + (x2-x1)/(x2+x1) - cos(x1) - 1.5
An example of a complex expression with conditional processing is:
x1 == 0 || x2 > 1 ? x2 : x2/x1
which means if x1 is equal to 0 or x2 is greater than 1, then the result is x2; otherwise the result is x2/x1.
An example of using conditional processing in conjunction with the bad() function is:
bad(x1) && bad(x2) ? badval : bad(x1) ? x2 : bad(x2) ? x1 : (x1 + x2)/2
which means if both x1 and x2 are bad, output badval; otherwise if x1 is bad, output x2; otherwise if x2 is bad, output x1; otherwise output the average.
emathp has a number of additional features. First, the output dataset can be one of the input datasets, in which case, the computed variables are added to the output dataset. Output variables cannot overwrite input variables.
The following angles and angle cosines can be used in expressions when input variables are 2-D and have the appropriate earth location. These angles are defined and computed in the same manner as angles.
cossatzen cosine satellite zenith angle sunzen solar zenith angle cosscatter cosine scattering phase angle scatter scattering phase angle cosreflect cosine solar reflection angle reflect solar reflection angle cosrelazm cosine relative azimuth angle relazm relative azimuth angle latitude geodetic latitude longitude geodetic longitude
The following time values can be used in expressions when input variables are 2-D and have been derived from satellite data.
gmt GMT time of day in seconds;
does not wrap around to zero at day's end
julian fractional day of the year;
midnight, January 1, corresponds to zero;
wraps around to zero at year's end
The following land boolean function is supported, based on the landmask.wdb2 database:
land if land (1) else (0)
The following single-argument aggregate functions are supported. Fixed box size is specified via the box_sides parameter.
min(x) minimum of the values in the box max(x) maximum of the values in the box ngood(x) number of good values in the box ave(x) average of the values in the box sum(x) sum of the values in the box. stdev(x) standard deviation of the values in the box var(x) variance of the values in the box median(x) median of the values in the box.
The following three-argument functions are supported, but only when input variables are 2-D. Maximum box size is specified via the box_sides parameter.
zmin(x,i,j) minimum in i by j box zmax(x,i,j) maximum in i by j box zngood(x,i,j) number of good values in i by j box zave(x,i,j) average in i by j box zsum(x,i,j) sum in i by j box zstdev(x,i,j) standard deviation in i by j box zvar(x,i,j) variance in i by j box zmedian(x,i,j) median in i by j box zelem(x,i,j) value at offset (i,j)
The offsets for the zelem function can be positive or negative. (0,0) is the center. Clockwise, starting with the element left of center we have (0,-1), (-1,-1), (-1,0), (-1,1), (0,1), (1,1), (1,0), (1,-1).
List of variables to use in the expression. Wildcards * and ? are allowed, provided that each wildcard term matches exactly one variable. This restriction forces the user to unambiguously specify variables in order. There is no default.
Optional, for emathc only. The name of the executable, generated in advance from emathexpr.c for the specific expression. If it's not supplied, user will have to to specify the expression. The temporary generated executable will then be deleted. There is no default.
For emathc only. The number of parameters in the expression. Used only if function_file was specified. There is no default.
For emathp and emathc only. The number of expressions. Each expression can be saved to the output dataset as a separate variable. The default is 1.
Arithmetic/logical expression. There is no default.
For emathc only. If yes, indicates that if any input variable element is bad (missing), then the corresponding output variable element is bad (missing). If no, the user assumes responsibility for all bad value checking. The default is yes.
If yes, output from trig functions is in degrees, and input to inverse trig functions is assumed to be in degrees. If no, output from trig functions is in radians, and input to inverse trig functions is assumed to be in radians. The default is yes.
Note, use_degrees is optional for emath and emath2. It must be set on the command line to have any effect, e.g., use_degrees=no.
Used only by emathp if expressions involve named satellite/solar angles. emathp speeds up the computation process by using piecewise polynomial interpolation. The input image is divided up into nearly square regions, each of which is covered by its biquadratic polynomial. A region's polynomials are determined by computing angles exactly from satellite ephemeris at 9 points in the region.
polysize is the width of these regions in kilometers. Valid range is [>= 1]. The default is 100.
Defines the box size for emathp when expressions involve fixed box single-argument aggregates. Also defines the maximum box size when emathp expressions involve three-argument aggregates. The number of box sides must agree with the dimensionality of the input variables. The valid range for each box side is [1, 50]. There is no default.
The minimum number of good values required by emathp to compute an aggregate statistic. The same value of min_good applies to all one argument and three-argument aggregates. The default is 1.
For emathp and emathc only. The list of expressions to save, by number. The default is to save all expressions.
The name(s) of the output variable(s) in the output TeraScan dataset. There is no default.
The units of the output variable(s). The default is no units for each output variable.
The datatype of the output variable(s). Valid responses are [byte, short, long, float, and double]. The default is float for emath and emath2. There is no default for emathc and emathp; in this case, datatype must be specified for each output variable.
offset
scale_factor
scale_offsets
scale_factors
If the var_type is byte or short for any output variable, the output data are scaled using the following linear transform:
stored output value = nearest int[(original value - offset)*scale_factor]
What scale does is decrease the value of the dataset proportionally by whatever number you enter here. For example, a scale of 10 is actually 1/10. So, if you have values ranging from 0 - 255, and you enter a scale factor of 10, then your output will equal 0 - 25.5.
The scale_factor can be any non-zero number. The default is 1.
The offset can be any number. The default is 0.
Example 1. Simple vegetation index combining AVHRR channels 1 and 2. Note that the order of the variables is unambiguous.
[8] % emath in/out files : char(255) ? big big.out expr_vars : char(255) ? [] *ch1 *ch2 expression : char(255) ?(x2-x1)/(x1+x2) var_name : char( 31) ? veg_index var_units : char( 31) ? [] var_type : char( 15) ? [float]
Example 2. Same as example 1, except pretending there are two input files.
[9] % emath2 in/out files : char(255) ? big big big.out file1_vars : char(255) ? [] *ch1 file2_vars : char(255) ? [] *ch2 expression : char(255) ?(x2-x1)/(x1+x2) var_name : char( 31) ? veg_index var_units : char( 31) ? [] var_type : char( 15) ? [float]
Example 3. Similar to the previous examples, except that a second output variable is produced, the simple ratio avhrr_ch1/avhrr_ch2.
[10] % emathp in/out files : char(255) ? big big.out expr_vars : char(255) ? *ch1 *ch2 num_exprs : int ? [1] 2 y1_expr : char(255) ? (x2 - x1)/(x2 + x1) y2_expr : char(255) ? x1/x2 save_exprs : int ( 2) ? [1 2] var_names : char( 63) ? veg_index ch1/ch2 var_units : char( 63) ? [- -] var_types : char( 31) ? float float
See fakedata for an example expression using dimension indices and sizes.
The emath family of functions copy the earth transform from the first input dataset to the output dataset, if that transform exists.
Last Update: $Date: 1998/07/08 23:21:30 $