From c978cccd9a9ef5c023be35d6343d285e8c57ed3e Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Sun, 24 Oct 2021 18:28:30 -0700 Subject: [PATCH] work on examples --- doc/matrices.texi | 158 ++++++++++++++++++++++++++++++++- doc/utilities.texi | 1 + tests/language/stats/matrix.at | 25 +++--- 3 files changed, 170 insertions(+), 14 deletions(-) diff --git a/doc/matrices.texi b/doc/matrices.texi index 1f650c773c..a95e8e29f0 100644 --- a/doc/matrices.texi +++ b/doc/matrices.texi @@ -1172,28 +1172,49 @@ Computes the inverse sine or tangent, respectively, of each element in @math{+\pi/2}, inclusive. The value of @math{\pi} can be computed as @code{4*ARTAN(1)}. + +@t{ARSIN(@{-1, 0, 1@}) @result{} @{-1.57, 0, 1.57@}} (approximately) + +@t{ARTAN(@{-5, -1, 1, 5@}) @result{} @{-1.37, -.79, .79, 1.37@}} (approximately) @end deffn @deffn {Matrix Function} COS (@var{M}) @deffnx {Matrix Function} SIN (@var{M}) Computes the cosine or sine, respectively, of each element in @var{M}, which must be in radians. + +@t{COS(@{0.785, 1.57; 3.14, 1.57 + 3.14@}) @result{} @{.71, 0; -1, 0@}} (approximately) @end deffn @deffn {Matrix Function} EXP (@var{M}) Computes @math{e^x} for each element @var{x} in @var{M}. + +@t{EXP(@{2, 3; 4, 5@}) @result{} @{7.39, 20.09; 54.6, 148.4@}} (approximately) @end deffn @deffn {Matrix Function} LG10 (@var{M}) @deffnx {Matrix Function} LN (@var{M}) Takes the logarithm with base 10 or base @math{e}, respectively, of each element in @var{M}. + +@t{LG10(@{1, 10, 100, 1000@}) @result{} @{0, 1, 2, 3@}} @* +@t{LG10(0) @result{}} (error) + +@t{LN(@{EXP(1), 1, 2, 3, 4@}) @result{} @{1, 0, .69, 1.1, 1.39@}} (approximately) @* +@t{LN(0) @result{}} (error) @end deffn @deffn {Matrix Function} MOD (@var{M}, @var{s}) Takes each element in @var{M} modulo nonzero scalar value @var{s}, that is, the remainder of division by @var{s}. The sign of the result is the same as the sign of the dividend. + +@t{MOD(@{5, 4, 3, 2, 1, 0@}, 3) @result{} @{2, 1, 0, 2, 1, 0@}} @* +@t{MOD(@{5, 4, 3, 2, 1, 0@}, -3) @result{} @{2, 1, 0, 2, 1, 0@}} @* +@t{MOD(@{-5, -4, -3, -2, -1, 0@}, 3) @result{} @{-2, -1, 0, -2, -1, 0@}} @* +@t{MOD(@{-5, -4, -3, -2, -1, 0@}, -3) @result{} @{-2, -1, 0, -2, -1, 0@}} @* +@t{MOD(@{5, 4, 3, 2, 1, 0@}, 1.5) @result{} @{.5, 1.0, .0, .5, 1.0, .0@}} @* +@t{MOD(@{5, 4, 3, 2, 1, 0@}, 0) @result{}} (error) @end deffn @deffn {Matrix Function} RND (@var{M}) @@ -1201,11 +1222,24 @@ is the same as the sign of the dividend. Rounds each element of @var{M} to an integer. @code{RND} rounds to the nearest integer, with halves rounded to even integers, and @code{TRUNC} rounds toward zero. + +@t{RND(@{-1.6, -1.5, -1.4@}) @result{} @{-2, -2, -1@}} @* +@t{RND(@{-.6, -.5, -.4@}) @result{} @{-1, 0, 0@}} @* +@t{RND(@{.4, .5, .6@} @result{} @{0, 0, 1@}} @* +@t{RND(@{1.4, 1.5, 1.6@}) @result{} @{1, 2, 2@}} + +@t{TRUNC(@{-1.6, -1.5, -1.4@}) @result{} @{-1, -1, -1@}} @* +@t{TRUNC(@{-.6, -.5, -.4@}) @result{} @{0, 0, 0@}} @* +@t{TRUNC(@{.4, .5, .6@} @result{} @{0, 0, 0@}} @* +@t{TRUNC(@{1.4, 1.5, 1.6@}) @result{} @{1, 1, 1@}} @end deffn @deffn {Matrix Function} SQRT (@var{M}) Takes the square root of each element of @var{M}, which must not be negative. + +@t{SQRT(@{0, 1, 2, 4, 9, 81@}) @result{} @{0, 1, 1.41, 2, 3, 9@}} (approximately) @* +@t{SQRT(-1) @result{}} (error) @end deffn @node Matrix Logical Functions @@ -1214,11 +1248,21 @@ negative. @deffn {Matrix Function} ALL (@var{M}) Returns a scalar with value 1 if all of the elements in @var{M} are nonzero, or 0 if at least one element is zero. + +@t{ALL(@{1, 2, 3@} < @{2, 3, 4@}) @result{} 1} @* +@t{ALL(@{2, 2, 3@} < @{2, 3, 4@}) @result{} 0} @* +@t{ALL(@{2, 3, 3@} < @{2, 3, 4@}) @result{} 0} @* +@t{ALL(@{2, 3, 4@} < @{2, 3, 4@}) @result{} 0} @end deffn @deffn {Matrix Function} ANY (@var{M}) Returns a scalar with value 1 if any of the elements in @var{M} is nonzero, or 0 if all of them are zero. + +@t{ANY(@{1, 2, 3@} < @{2, 3, 4@}) @result{} 1} @* +@t{ANY(@{2, 2, 3@} < @{2, 3, 4@}) @result{} 1} @* +@t{ANY(@{2, 3, 3@} < @{2, 3, 4@}) @result{} 1} @* +@t{ANY(@{2, 3, 4@} < @{2, 3, 4@}) @result{} 0} @end deffn @node Matrix Construction Functions @@ -1229,6 +1273,17 @@ Returns a block diagonal matrix with as many rows as the sum of its arguments' row counts and as many columns as the sum of their columns. Each argument matrix is placed along the main diagonal of the result, and all other elements are zero. + +@format +@t{BLOCK(@{1, 2; 3, 4@}, 5, @{7; 8; 9@}, @{10, 11@}) @result{} + 1 2 0 0 0 0 + 3 4 0 0 0 0 + 0 0 5 0 0 0 + 0 0 0 7 0 0 + 0 0 0 8 0 0 + 0 0 0 9 0 0 + 0 0 0 0 10 11} +@end format @end deffn @deffn {Matrix Function} IDENT (@var{n}) @@ -1236,6 +1291,23 @@ and all other elements are zero. Returns an identity matrix, whose main diagonal elements are one and whose other elements are zero. The returned matrix has @var{n} rows and columns or @var{nr} rows and @var{nc} columns, respectively. + +@format +@t{IDENT(1) @result{} 1 +IDENT(2) @result{} + 1 0 + 0 1 +IDENT(3, 5) @result{} + 1 0 0 0 0 + 0 1 0 0 0 + 0 0 1 0 0 +IDENT(5, 3) @result{} + 1 0 0 + 0 1 0 + 0 0 1 + 0 0 0 + 0 0 0} +@end format @end deffn @deffn {Matrix Function} MAGIC (@var{n}) @@ -1244,11 +1316,18 @@ the integers @math{1@dots{}@var{n}} once, in which each column, each row, and each diagonal sums to @math{n(n^2+1)/2}. There are many magic squares with given dimensions, but this function always returns the same one for a given value of @var{n}. + +@t{MAGIC(3) @result{} @{8, 1, 6; 3, 5, 7; 4, 9, 2@}} @* +@t{MAGIC(4) @result{} @{1, 5, 12, 16; 15, 11, 6, 2; 14, 8, 9, 3; 4, 10, 7, 13@}} @end deffn @deffn {Matrix Function} MAKE (@var{nr}, @var{nc}, @var{s}) Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements are all @var{s}. + +@t{MAKE(1, 2, 3) @result{} @{3, 3@}} @* +@t{MAKE(2, 1, 4) @result{} @{4; 4@}} @* +@t{MAKE(2, 3, 5) @result{} @{5, 5, 5; 5, 5, 5@}} @end deffn @deffn {Matrix Function} MDIAG (@var{V}) @@ -1258,23 +1337,63 @@ from @var{V}. The other elements in the returned vector are zero. Use @code{CALL SETDIAG} (@pxref{CALL SETDIAG}) to replace the main diagonal of a matrix in-place. + +@format +@t{MDIAG(@{1, 2, 3, 4@}) @result{} + 1 0 0 0 + 0 2 0 0 + 0 0 3 0 + 0 0 0 4} +@end format @end deffn @deffn {Matrix Function} RESHAPE (@var{M}, @var{nr}, @var{nc}) Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements come from @var{M}, which must have the same number of elements as the new matrix, copying elements from @var{M} to the new matrix row by row. + +@format +@t{RESHAPE(1:12, 1, 12) @result{} + 1 2 3 4 5 6 7 8 9 10 11 12 +RESHAPE(1:12, 2, 6) @result{} + 1 2 3 4 5 6 + 7 8 9 10 11 12 +RESHAPE(1:12, 3, 4) @result{} + 1 2 3 4 + 5 6 7 8 + 9 10 11 12 +RESHAPE(1:12, 4, 3) @result{} + 1 2 3 + 4 5 6 + 7 8 9 + 10 11 12} +@end format @end deffn @deffn {Matrix Function} T (@var{M}) @deffnx {Matrix Function} TRANSPOS (@var{M}) Returns @var{M} with rows exchanged for columns. + +@t{T(@{1, 2, 3@}) @result{} @{1; 2; 3@}} @* +@t{T(@{1; 2; 3@}) @result{} @{1, 2, 3@}} @end deffn @deffn {Matrix Function} UNIFORM (@var{nr}, @var{nc}) Returns a @math{@var{nr}@times{}@var{nc}} matrix in which each element is randomly chosen from a uniform distribution of real numbers between -0 and 1. +0 and 1. Random number generation honors the current seed setting +(@pxref{SET SEED}). + +The following example shows one possible output, but of course every +result will be different (given different seeds): + +@format +@t{UNIFORM(4, 5)*10 @result{} + 7.71 2.99 .21 4.95 6.34 + 4.43 7.49 8.32 4.99 5.83 + 2.25 .25 1.98 7.09 7.61 + 2.66 1.69 2.64 .88 1.50} +@end format @end deffn @node Matrix Minimum and Maximum and Sum Functions @@ -1287,6 +1406,11 @@ is randomly chosen from a uniform distribution of real numbers between Returns a row vector with the same number of columns as @var{M}, in which each element is the minimum, maximum, sum, or sum of squares, respectively, of the elements in the same column of @var{M}. + +@t{CMIN(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{1, 2, 3@}} @* +@t{CMAX(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{7, 8, 9@}} @* +@t{CSUM(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{12, 15, 18@}} @* +@t{CSSQ(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{66, 93, 126@}} @end deffn @deffn {Matrix Function} MMIN (@var{M}) @@ -1295,6 +1419,11 @@ respectively, of the elements in the same column of @var{M}. @deffnx {Matrix Function} MSSQ (@var{M}) Returns the minimum, maximum, sum, or sum of squares, respectively, of the elements of @var{M}. + +@t{MMIN(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 1} @* +@t{MMAX(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 9} @* +@t{MSUM(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 45} @* +@t{MSSQ(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 285} @end deffn @deffn {Matrix Function} RMIN (@var{M}) @@ -1304,17 +1433,25 @@ the elements of @var{M}. Returns a column vector with the same number of rows as @var{M}, in which each element is the minimum, maximum, sum, or sum of squares, respectively, of the elements in the same row of @var{M}. + +@t{RMIN(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{1; 4; 7@}} @* +@t{RMAX(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{3; 6; 9@}} @* +@t{RSUM(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{6; 15; 24@}} @* +@t{RSSQ(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{14; 77; 194@}} @end deffn @deffn {Matrix Function} SSCP (@var{M}) Returns @math{@var{M}^T @times{} @var{M}}. + +@t{SSCP(@{1, 2, 3; 4, 5, 6@}) @result{} @{17, 22, 27; 22, 29, 36; 27, 36, 45@}} @end deffn @deffn {Matrix Function} TRACE (@var{M}) Returns the sum of the elements along @var{M}'s main diagonal, equivalent to @code{MSUM(DIAG(@var{M}))}. -@end deffn +@t{TRACE(MDIAG(1:5)) @result{} 15} +@end deffn @node Matrix Property Functions @subsubsection Matrix Property Functions @@ -1322,12 +1459,22 @@ equivalent to @code{MSUM(DIAG(@var{M}))}. @deffn {Matrix Function} NROW (@var{M}) @deffnx {Matrix Function} NCOL (@var{M}) Returns the number of row or columns, respectively, in @var{M}. + +@format +@t{NROW(@{1, 0; -2, -3; 3, 3@}) @result{} 3 +NROW(1:5) @result{} 1 + +NCOL(@{1, 0; -2, -3; 3, 3@}) @result{} 2 +NCOL(1:5) @result{} 5} +@end format @end deffn @deffn {Matrix Function} DIAG (@var{M}) Returns a column vector containing a copy of @var{M}'s main diagonal. The vector's length is the lesser of @code{NCOL(@var{M})} and @code{NROW(@var{M})}. + +@t{DIAG(@{1, 0; -2, -3; 3, 3@}) @result{} @{1; -3@}} @end deffn @node Matrix Rank Ordering Functions @@ -1373,6 +1520,13 @@ COMPUTE v(GRADE(-v))=v. /* Sort v in descending order. Matrix @var{M} must be an @math{@var{n}@times{}@var{n}} symmetric positive-definite matrix. Returns an @math{@var{n}@times{}@var{n}} matrix @var{B} such that @math{@var{B}^T@times{}@var{B}=@var{M}}. + +@format +@t{CHOL(@{4, 12, -16; 12, 37, -43; -16, -43, 98@}) @result{} + 2 6 -8 + 0 1 5 + 0 0 3} +@end format @end deffn @deffn {Matrix Function} DESIGN (@var{M}) diff --git a/doc/utilities.texi b/doc/utilities.texi index f5ec9d5e86..18a45095e9 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -698,6 +698,7 @@ The maximum number of iterations for an uncontrolled loop LOOP and BREAK Commands}). The default @var{max_loops} is 40. @item SEED +@anchor{SET SEED} The initial pseudo-random number seed. Set it to a real number or to RANDOM, to obtain an initial seed from the current time of day. diff --git a/tests/language/stats/matrix.at b/tests/language/stats/matrix.at index 00e4dfdbe0..cc111c4952 100644 --- a/tests/language/stats/matrix.at +++ b/tests/language/stats/matrix.at @@ -1422,6 +1422,7 @@ PRINT KRONEKER({1, 2; 3, 4}, {0, 5; 6, 7}). PRINT LG10({1, 10, 100, 1000}). PRINT LN({1, 2; 3, 4})/FORMAT F5.2. +PRINT LN(0). END MATRIX. ]) AT_CHECK([pspp matrix.sps], [0], [dnl @@ -1691,12 +1692,12 @@ AT_CLEANUP AT_SETUP([MATRIX - RESHAPE RMAX RMIN RND RNKORDER]) AT_DATA([matrix.sps], [dnl MATRIX. -PRINT RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 1, 12). -PRINT RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 2, 6). -PRINT RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 3, 4). -PRINT RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 4, 3). -PRINT RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 6, 2). -PRINT RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 12, 1). +PRINT RESHAPE(1:12, 1, 12). +PRINT RESHAPE(1:12, 2, 6). +PRINT RESHAPE(1:12, 3, 4). +PRINT RESHAPE(1:12, 4, 3). +PRINT RESHAPE(1:12, 6, 2). +PRINT RESHAPE(1:12, 12, 1). PRINT RMAX({1, 0, 1; -2, -3, 1; 3, 3, 0}). @@ -1711,25 +1712,25 @@ PRINT RNKORDER({1, 0, 3; 3, 1, 2; 3, 0, 5}) /FORMAT F5.1. END MATRIX. ]) AT_CHECK([pspp matrix.sps], [0], [dnl -RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 1, 12) +RESHAPE(1:12, 1, 12) 1 2 3 4 5 6 7 8 9 10 11 12 -RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 2, 6) +RESHAPE(1:12, 2, 6) 1 2 3 4 5 6 7 8 9 10 11 12 -RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 3, 4) +RESHAPE(1:12, 3, 4) 1 2 3 4 5 6 7 8 9 10 11 12 -RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 4, 3) +RESHAPE(1:12, 4, 3) 1 2 3 4 5 6 7 8 9 10 11 12 -RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 6, 2) +RESHAPE(1:12, 6, 2) 1 2 3 4 5 6 @@ -1737,7 +1738,7 @@ RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 6, 2) 9 10 11 12 -RESHAPE({1, 2, 3; 4, 5, 6; 7, 8, 9; 10, 11, 12}, 12, 1) +RESHAPE(1:12, 12, 1) 1 2 3 -- 2.30.2