.. index:: ! gmtmath .. include:: module_core_purpose.rst_ ******* gmtmath ******* |gmtmath_purpose| Synopsis -------- .. include:: common_SYN_OPTs.rst_ **gmt math** [ |-A|\ *t_f(t)*\ [**+e**]\ [**+r**]\ [**+s**\|\ **w**] ] [ |-C|\ *cols* ] [ |-E|\ *eigen* ] [ |-I| ] [ |-N|\ *n\_col*\ [/*t_col*] ] [ |-Q|\ [**c**\|\ **i**\|\ **p**\|\ **n**] ] [ |-S|\ [**f**\|\ **l**] ] [ |-T|\ [*min*/*max*/*inc*\ [**+b**\|\ **i**\|\ **l**\|\ **n**]\|\ *file*\|\ *list*] ] [ |SYN_OPT-V| ] [ |SYN_OPT-b| ] [ |SYN_OPT-d| ] [ |SYN_OPT-e| ] [ |SYN_OPT-f| ] [ |SYN_OPT-g| ] [ |SYN_OPT-h| ] [ |SYN_OPT-i| ] [ |SYN_OPT-o| ] [ |SYN_OPT-q| ] [ |SYN_OPT-s| ] [ |SYN_OPT-w| ] [ |SYN_OPT--| ] *operand* [ *operand* ] **OPERATOR** [ *operand* ] **OPERATOR** ... **=** [ *outfile* ] |No-spaces| Description ----------- **math** will perform operations like add, subtract, multiply, and numerous other operands on one or more table data files or constants using `Reverse Polish Notation (RPN) `_ syntax. Arbitrarily complicated expressions may therefore be evaluated; the final result is written to an output file [or standard output]. Data operations are element-by-element, not matrix manipulations (except where noted). Some operators only require one operand (see below). If no data tables are used in the expression then options |-T|, |-N| can be set (and optionally **-bo** to indicate the data type for binary tables). If STDIN is given, the standard input will be read and placed on the stack as if a file with that content had been given on the command line. By default, all columns except the "time" column are operated on, but this can be changed (see |-C|). Complicated or frequently occurring expressions may be coded as a macro for future use or stored and recalled via named memory locations. .. include:: RPN_info.rst_ Required Arguments ------------------ *operand* If *operand* can be opened as a file it will be read as an ASCII (or binary, see **-bi**) table data file. If not a file, it is interpreted as a numerical constant or a special symbol (see below). The special argument STDIN means that standard input will be read and placed on the stack; STDIN can appear more than once if necessary. *outfile* The name of a table data file that will hold the final result. If not given then the output is sent to standard output. Optional Arguments ------------------ .. _-A: **-A**\ *t_f(t)*\ [**+e**]\ [**+r**]\ [**+s**\|\ **w**] Requires |-N| and will partially initialize a table with values from the given file *t_f(t)* containing *t* and *f(t)* only. The *t* is placed in column *t_col* while *f(t)* goes into column *n_col - 1* (see |-N|) and is called **b**. The stack table is then the :math:`m \times (n+1)` augmented matrix [ **A** \| **b** ] and you want to solve for the least squares solution **x** to the matrix equation **Ax** = **b**. Usually, you will need to fill in the remaining columns in **A** using the various functions that defines the linear model you are trying to fit. If used with operators **LSQFIT** and **SVDFIT** you can optionally append some modifiers: - **+e** - Evaluate the solution and write a data set with four columns: *t*, *f(t)*, the model solution and residuals at *t*, respectively [Default writes one column with model coefficients **x**]. - **+r** - Only place f(t) (i.e., **b**) and leave the **A** part of the augmented matrix equation alone. - **+s** - Your *t_f(t)* has a third column with 1-sigma uncertainties, or - **+w** - Your *t_f(t* table has a third column with weights. **Note**: If either **+s** or **+w** are used we find the weighted solution. The weights (or sigmas) will be output as the last column if **+e** is in effect. .. _-C: **-C**\ *cols* Select the columns that will be operated on until next occurrence of |-C|. List columns separated by commas; ranges like 1,3-5,7 are allowed, plus **-Cx** can be used for **-C**\ 0 and **-Cy** can be used for **-C**\ 1. |-C| (no arguments) resets the default action of using all columns except time column (see |-N|). **-Ca** selects all columns, including time column, while **-Cr** reverses (toggles) the current choices. When |-C| is in effect it also controls which columns from a file will be placed on the stack. .. _-E: **-E**\ *eigen* Sets the minimum eigenvalue used by operators **LSQFIT** and **SVDFIT** [1e-7]. Smaller eigenvalues are set to zero and will not be considered in the solution. .. _-I: **-I** Reverses the output row sequence from ascending time to descending [ascending]. .. _-N: **-N**\ *n_col*\ [/*t_col*] Select the number of columns and optionally the column number that contains the "time" variable [0]. Columns are numbered starting at 0 [2/0]. If input files are specified then |-N| will add any missing columns. .. _-Q: **-Q**\ [**c**\|\ **i**\|\ **p**\|\ **n**] Quick mode for scalar calculation. Internally sets the equivalent of **-Ca** **-N**\ 1/0 **-T**\ 1. In this mode, constants may have dimensional units (i.e., **c**, **i**, or **p**), and will be converted to internal *inches* before computing. If one or more constants with units are encountered then the final answer will be reported in the unit set by :term:`PROJ_LENGTH_UNIT`, unless overridden by appending another unit. Alternatively, append **n** for a non-dimensional result, meaning no unit conversion during output. To avoid any unit conversion on input, just do not use units. .. _-S: **-S**\ [**f**\|\ **l**] Only report the first or last row of the results [Default outputs all rows]. This is useful if you have computed a statistic (say the **MODE**) and only want to report a single number instead of numerous records with identical values. Append **l** to get the last row and **f** to get the first row only [Default]. .. _-T: **-T**\ [*min*/*max*/*inc*\ [**+b**\|\ **i**\|\ **l**\|\ **n**]\|\ *file*\|\ *list*] Required when no input files are given. Builds an array for the "time" column (see |-N|). If there is no time column (i.e., your input has only data columns), give |-T| with no arguments; this also implies **-Ca**. For details on array creation, see `Generate 1-D Array`_. .. |Add_-V| replace:: |Add_-V_links| .. include:: explain_-V.rst_ :start-after: **Syntax** :end-before: **Description** .. |Add_-bi| unicode:: 0x20 .. just an invisible code .. include:: explain_-bi.rst_ .. |Add_-bo| replace:: [Default is same as input, but see **-o**] .. include:: explain_-bo.rst_ .. |Add_-d| unicode:: 0x20 .. just an invisible code .. include:: explain_-d.rst_ .. |Add_-e| unicode:: 0x20 .. just an invisible code .. include:: explain_-e.rst_ .. |Add_-f| unicode:: 0x20 .. just an invisible code .. include:: explain_-f.rst_ .. |Add_-g| unicode:: 0x20 .. just an invisible code .. include:: explain_-g.rst_ .. |Add_-h| unicode:: 0x20 .. just an invisible code .. include:: explain_-h.rst_ .. include:: explain_-icols.rst_ .. include:: explain_-ocols.rst_ .. include:: explain_-q.rst_ .. include:: explain_-s.rst_ .. include:: explain_-w.rst_ .. include:: explain_help.rst_ .. include:: explain_array.rst_ Operators --------- Choose among the following operators. Here, "args" are the number of input and output arguments. =============== ======= ============================================================================================= ===================== Operator args Returns Type of Function =============== ======= ============================================================================================= ===================== **ABS** 1 1 Absolute value of A Arithmetic **ACOS** 1 1 Inverse cosine (result in radians) Calculus **ACOSD** 1 1 Inverse cosine (result in degrees) Calculus **ACOSH** 1 1 Inverse hyperbolic cosine Calculus **ACOT** 1 1 Inverse of cotangent (result in radians) Calculus **ACOTD** 1 1 Inverse of cotangent (result in degrees) Calculus **ACSC** 1 1 Inverse of cosecant (result in radians) Calculus **ACSCD** 1 1 Inverse of cosecant (result in degrees) Calculus **ADD** 2 1 A + B (addition) Arithmetic **AND** 2 1 B if A equals NaN, else A Logic **ASEC** 1 1 Inverse of secant (result in radians) Calculus **ASECD** 1 1 Inverse of secant (result in degrees) Calculus **ASIN** 1 1 Inverse of sine (result in radians) Calculus **ASIND** 1 1 Inverse of sine (result in degrees) Calculus **ASINH** 1 1 Inverse of hyperbolic sine Calculus **ATAN** 1 1 Inverse of tangent (result in radians) Calculus **ATAN2** 2 1 Inverse of tangent of A/B (result in radians) Calculus **ATAN2D** 2 1 Inverse of tangent of A/B (result in degrees) Calculus **ATAND** 1 1 Inverse of tangent (result in degrees) Calculus **ATANH** 1 1 Inverse of hyperbolic tangent Calculus **BCDF** 3 1 Binomial cumulative distribution function for p = A, n = B, and x = C Probability **BEI** 1 1 Kelvin function bei (A) Special Functions **BER** 1 1 Kelvin function ber (A) Special Functions **BITAND** 2 1 A & B (bitwise AND operator) Logic **BITLEFT** 2 1 A << B (bitwise left-shift operator) Arithmetic **BITNOT** 1 1 ~A (bitwise NOT operator, i.e., return two’s complement) Logic **BITOR** 2 1 A | B (bitwise OR operator) Logic **BITRIGHT** 2 1 A >> B (bitwise right-shift operator) Arithmetic **BITTEST** 2 1 1 if bit B of A is set, else 0 (bitwise TEST operator) n Logic **BITXOR** 2 1 A ^ B (bitwise XOR operator) Logic **BPDF** 3 1 Binomial probability density function for p = A, n = B, and x = C Probability **CEIL** 1 1 ceil (A) (smallest integer >= A) Logic **CHICDF** 2 1 Chi-squared cumulative distribution function for chi2 = A and nu = B Probability **CHICRIT** 2 1 Chi-squared distribution critical value for alpha = A and nu = B Probability **CHIPDF** 2 1 Chi-squared probability density function for chi2 = A and nu = B Probability **COL** 1 1 Places column A on the stack Special Operators **COMB** 2 1 Combinations n_C_r, with n = A and r = B Probability **CORRCOEFF** 2 1 Correlation coefficient r(A, B) Probability **COS** 1 1 Cosine of A (A in radians) Calculus **COSD** 1 1 Cosine of A (A in degrees) Calculus **COSH** 1 1 Hyperbolic cosine of A Calculus **COT** 1 1 Cotangent of A (A in radians) Calculus **COTD** 1 1 Cotangent of A (A in degrees) Calculus **CSC** 1 1 Cosecant of A (A in radians) Calculus **CSCD** 1 1 Cosecant of A (A in degrees) Calculus **D2DT2** 1 1 d\ :sup:`2`\ (A)/dt\ :sup:`2` Central 2nd derivative Calculus **D2R** 1 1 Converts degrees to radians Special Operators **DDT** 1 1 d(A)/dt Central 1st derivative Calculus **DEG2KM** 1 1 Converts spherical degrees to kilometers Special Operators **DENAN** 2 1 Replace NaNs in A with values from B Logic **DIFF** 1 1 Forward difference between adjacent elements of A (A[1]-A[0], A[2]-A[1], …, NaN) Arithmetic **DILOG** 1 1 Dilogarithm (Spence's) function Special Functions **DIV** 2 1 A / B (division) Arithmetic **DUP** 1 2 Places duplicate of A on the stack Special Operators **ECDF** 2 1 Exponential cumulative distribution function for x = A and lambda = B Probability **ECRIT** 2 1 Exponential distribution critical value for alpha = A and lambda = B Probability **EPDF** 2 1 Exponential probability density function for x = A and lambda = B Probability **EQ** 2 1 1 if A equals B, else 0 Logic **ERF** 1 1 Error function erf (A) Probability **ERFC** 1 1 Complementary Error function erfc (A) Probability **ERFINV** 1 1 Inverse error function of A Probability **EXCH** 2 2 Exchanges A and B on the stack Special Operators **EXP** 1 1 E raised to a power. Arithmetic **FACT** 1 1 A! (A factorial) Arithmetic **FCDF** 3 1 F cumulative distribution function for F = A, nu1 = B, and nu2 = C Probability **FCRIT** 3 1 F distribution critical value for alpha = A, nu1 = B, and nu2 = C Probability **FLIPUD** 1 1 Reverse order of each column Special Operators **FLOOR** 1 1 greatest integer less than or equal to A Logic **FMOD** 2 1 A % B (remainder after truncated division) Arithmetic **FPDF** 3 1 F probability density function for F = A, nu1 = B, and nu2 = C Probability **GE** 2 1 1 if A >= (greater or equal than) B, else 0 Logic **GT** 2 1 1 if A > (greater than) B, else 0 Logic **HSV2LAB** 3 3 Convert *h,s,v* triplets to *l,a,b* triplets, with h = A (0-360), s = B and v = C (0-1) Special Operators **HSV2RGB** 3 3 Convert *h,s,v* triplets to *r,g,b* triplets, with h = A (0-360), s = B and v = C (0-1) Special Operators **HSV2XYZ** 3 3 Convert *h,s,v* triplets to *x,t,z* triplets, with h = A (0-360), s = B and v = C (0-1) Special Operators **HYPOT** 2 1 Hypotenuse of a right triangle of sides A and B (= sqrt (A\ :sup:`2` + B\ :sup:`2`)) Calculus **I0** 1 1 Modified Bessel function of A (1st kind, order 0) Special Functions **I1** 1 1 Modified Bessel function of A (1st kind, order 1) Special Functions **IFELSE** 3 1 B if A is not equal to 0, else C Logic **IN** 2 1 Modified Bessel function of A (1st kind, order B) Special Functions **INRANGE** 3 1 1 if B <= A <= C, else 0 Logic **INT** 1 1 Numerically integrate A Calculus **INV** 1 1 Invert (1/A) Arithmetic **ISFINITE** 1 1 1 if A is finite, else 0 Logic **ISNAN** 1 1 1 if A equals NaN, else 0 Logic **J0** 1 1 Bessel function of A (1st kind, order 0) Special Functions **J1** 1 1 Bessel function of A (1st kind, order 1) Special Functions **JN** 2 1 Bessel function of A (1st kind, order B) Special Functions **K0** 1 1 Modified Kelvin function of A (2nd kind, order 0) Special Functions **K1** 1 1 Modified Bessel function of A (2nd kind, order 1) Special Functions **KEI** 1 1 Kelvin function kei (A) Special Functions **KER** 1 1 Kelvin function ker (A) Special Functions **KM2DEG** 1 1 Converts kilometers to spherical degrees Special Operators **KN** 2 1 Modified Bessel function of A (2nd kind, order B) Special Functions **KURT** 1 1 Kurtosis of A Probability **LAB2HSV** 3 3 Convert *l,a,b* triplets to *h,s,v* triplets Special Operators **LAB2RGB** 3 3 Convert *l,a,b* triplets to *r,g,b* triplets Special Operators **LAB2XYZ** 3 3 Convert *l,a,b* triplets to *x,y,z* triplets Special Operators **LCDF** 1 1 Laplace cumulative distribution function for z = A Probability **LCRIT** 1 1 Laplace distribution critical value for alpha = A Probability **LE** 2 1 1 if A <= (equal or smaller than) B, else 0 Logic **LMSSCL** 1 1 LMS (Least Median of Squares) scale estimate (LMS STD) of A Probability **LMSSCLW** 2 1 Weighted LMS scale estimate (LMS STD) of A for weights in B Probability **LOG** 1 1 log (A) (natural logarithm) Arithmetic **LOG10** 1 1 log\ :sub:`10` (A) (logarithm base 10) Arithmetic **LOG1P** 1 1 log (1+A) (natural logarithm, accurate for small A) Arithmetic **LOG2** 1 1 log\ :sub:`2` (A) (logarithm base 2) Arithmetic **LOWER** 1 1 The lowest (minimum) value of A Arithmetic **LPDF** 1 1 Laplace probability density function for z = A Probability **LRAND** 2 1 Laplace random noise with mean A and std. deviation B Probability **LSQFIT** 1 0 Stack is [**A** | **b**]; return least squares solution **x** = **A** \\ **b** Special Operators **LT** 2 1 1 if A < (smaller than) B, else 0 Logic **MAD** 1 1 Median Absolute Deviation (L1 STD) of A Probability **MADW** 2 1 Weighted Median Absolute Deviation (L1 STD) of A for weights in B Probability **MAX** 2 1 Maximum of A and B Probability **MEAN** 1 1 Mean value of A Probability **MEANW** 2 1 Weighted mean value of A for weights in B Probability **MEDIAN** 1 1 Median value of A Probability **MEDIANW** 2 1 Weighted median value of A for weights in B Probability **MIN** 2 1 Minimum of A and B Probability **MOD** 2 1 A mod B (remainder after floored division) Arithmetic **MODE** 1 1 Mode value (Least Median of Squares) of A Probability **MODEW** 2 1 Weighted mode value (Least Median of Squares) of A for weights in B Probability **MUL** 2 1 A x B (multiplication) Arithmetic **NAN** 2 1 NaN if A equals B, else A Logic **NEG** 1 1 Negative (-A) Arithmetic **NEQ** 2 1 1 If A is not equal to B, else 0 Logic **NORM** 1 1 Normalize (A) so min(A) = 0 and max(A) = 1 Probability **NOT** 1 1 NaN ia A is equal NaN, 1 if A is equal to 0, else 0 Logic **NRAND** 2 1 Normal, random values with mean A and std. deviation B Probability **OR** 2 1 NaN if B equals NaN, else A Logic **PCDF** 2 1 Poisson cumulative distribution function for x = A and lambda = B Probability **PERM** 2 1 Permutations n_P_r, with n = A and r = B Probability **PLM** 3 1 Associated Legendre polynomial P(A) degree B order C Special Functions **PLMg** 3 1 Normalized associated Legendre polynomial P(A) degree B order C (geophysical convention) Special Functions **POP** 1 0 Delete top element from the stack Special Operators **POW** 2 1 A to the power of B Arithmetic **PPDF** 2 1 Poisson distribution P(x,lambda), with x = A and lambda = B Probability **PQUANT** 2 1 The B’th quantile (0-100%) of A Probability **PQUANTW** 3 1 The C’th weighted quantile (0-100%) of A for weights in B Probability **PSI** 1 1 Psi (or Digamma) of A Special Functions **PV** 3 1 Legendre function Pv(A) of degree v = real(B) + imag(C) Special Functions **QV** 3 1 Legendre function Qv(A) of degree v = real(B) + imag(C) Special Functions **R2** 2 1 Hypotenuse squared (= A\ :sup:`2` + B\ :sup:`2`) Calculus **R2D** 1 1 Convert radians to degrees Special Operators **RAND** 2 1 Uniform random values between A and B Probability **RCDF** 1 1 Rayleigh cumulative distribution function for z = A Probability **RCRIT** 1 1 Rayleigh distribution critical value for alpha = A Probability **RGB2HSV** 3 3 Convert *r,g,b* triplets to *h,s,v* triplets, with r = A, g = B, and b = C (in 0-255 range) Special Operators **RGB2LAB** 3 3 Convert *r,g,b* triplets to *l,a,b* triplets, with r = A, g = B, and b = C (in 0-255 range) Special Operators **RGB2XYZ** 3 3 Convert *r,g,b* triplets to *x,y,z* triplets, with r = A, g = B, and b = C (in 0-255 range) Special Operators **RINT** 1 1 Rint (A) (round to integral value nearest to A) Arithmetic **RMS** 1 1 Root-mean-square of A Arithmetic **RMSW** 1 1 Weighted root-mean-square of A for weights in B Arithmetic **ROLL** 2 0 Cyclically shifts the top A stack items by an amount B Special Operators **ROOTS** 2 1 Treats col A as f(t) = 0 and returns its roots Special Operators **ROTT** 2 1 Rotate A by the (constant) shift B in the t-direction Arithmetic **RPDF** 1 1 Rayleigh probability density function for z = A Probability **SEC** 1 1 Secant of A (A in radians) Calculus **SECD** 1 1 Secant of A (A in degrees) Calculus **SIGN** 1 1 Sign (+1 or -1) of A Logic **SIN** 1 1 Sine of A (A in radians) Calculus **SINC** 1 1 Normalized sinc function. Special Functions **SIND** 1 1 Sine of A (A in degrees) Calculus **SINH** 1 1 Hiperbolic sine of A Calculus **SKEW** 1 1 Skewness of A Probability **SQR** 1 1 Square (to the power of 2) Arithmetic **SQRT** 1 1 Square root Arithmetic **STD** 1 1 Standard deviation of A Probability **STDW** 2 1 Weighted standard deviation of A for weights in B Probability **STEP** 1 1 Heaviside step function H(A) Special Functions **STEPT** 1 1 Heaviside step function H(t-A) Special Functions **SUB** 2 1 A - B (subtraction) Arithmetic **SUM** 1 1 Cumulative sum of A Arithmetic **SVDFIT** 1 0 Stack is [**A** | **b**]; return **x** = **A** \\ **b** via SVD decomposition (see |-E)| Special Operators **TAN** 1 1 Tangent of A (A in radians) Calculus **TAND** 1 1 Tangent of A (A in degrees) Calculus **TANH** 1 1 Hyperbolic tangent of A Calculus **TAPER** 1 1 Unit weights cosine-tapered to zero within A of end margins Special Operators **TCDF** 2 1 Student’s t cumulative distribution function for t = A, and nu = B Probability **TCRIT** 2 1 Student’s t distribution critical value for alpha = A and nu = B Probability **TN** 2 1 Chebyshev polynomial Tn(-1