work on examples

diff --git a/doc/matrices.texi b/doc/matrices.texi
index 1f650c773c83f55b08865d4cb9eb2c0df3cf3083..a95e8e29f03c6b6e92039c7c43794113ad052655 100644 (file)
--- 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 f5ec9d5e8660b6419a7251018bbcec3402facc27..18a45095e986af89d3c1f26a93169fbddc90f2da 100644 (file)
--- 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 00e4dfdbe02979a20c530a58ef6d6064d64f8552..cc111c4952fd71a76fddfbbde18542eac8eabd90 100644 (file)
--- 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